# Tool reference The tool list carries short routing guidance. This guide preserves the detailed contracts and limits for each tool. Full input validation schemas are available through MCP resources at `oods://schemas/.input.json`; relative JSON Schema references are readable under the same prefix. These full schemas remain the server validators; the compact tool-list schemas are discovery summaries. ## tokens_build Build the current brand-registry source with the shipped compiler kit and server dependencies. apply:true compiles in an isolated artifact directory, returns requested-brand/theme CSS variables, CSS and JSON inline, and writes five artifacts with paths, hashes and sizes. Full CSS includes all registered scopes; TypeScript and Tailwind retain A/light defaults. Source and shipped runtime files are never changed. Without apply it lists the artifacts it would create and writes nothing, including no run record. A missing compiler kit returns OODS-N011; a failed compiler returns OODS-S019 with its output. ## structured_data_fetch Read the live components dataset (including registered team objects and traits), archived token/export datasets, or Stage1 artifacts. Dataset reads preserve full output by default. For clients without access to the server filesystem, start with `{ "dataset": "components", "detail": "summary" }`, then call `meta.next` unchanged until absent. Pages carry lossless `{path,value}` entries using JSON Pointers; apply them in order to reconstruct the full object. Each page is below 100,000 characters. `pageSize` defaults to 10 and accepts 1–100, also bounded by serialized size. `meta.full` requests the complete file; `payloadMode:"inline"` requests the complete inline payload explicitly. Projection-specific ETags prevent a summary or previous page from suppressing a different page. `includePayload:false` omits the current payload; next/full calls still request data. `includeInternal` includes internal objects; otherwise `registry.hiddenInternal` counts them. `version` pins a dated export (nearest earlier with a warning if absent), and `listVersions` lists dates. These and paging/detail are dataset-only; kind mode refuses them with OODS-V202. `meta.source` distinguishes live registry and committed export. Stage1 is an optional capture tool, published separately. `kind` plus `runPath` reads its retained artifacts: run_manifest through 1.8.0, a11y_report 2.2.0–2.5.0 and 3.0.0, drift_report 1.0.0–1.4.0 and 2.0.0, report_index 1.0.0/1.1.0, and a11y_evidence 1.1.0–1.4.0, alongside the existing identity/capability/object rollups. The derived_analysis kind admits analysis 1.0.0/1.1.0, fig_local_tokens 1.0.0/1.3.0/1.5.0/1.6.0 and recomputed style_fingerprint 1.3.0/1.4.0. Retained-file hashes, confined paths, lineage and JSON Pointers are checked. Unknown versions and suite roots refuse with accepted versions named. Earlier admitted versions remain readable. Missing accessibility scores stay absent; drift 1.4.0/2.0.0 raw observations do not become invented token identities or regraded severity. ## brand_apply Apply brand token overlays to a brand's canonical source using alias strategy or the supported add/remove/replace subset of RFC 6902. Requires a delta object. apply=true writes source, runs both real token-build stages, and returns before/after SHA256, byte counts and captured build results. The brand as the change would leave it is checked first, as brand_create validate checks a brand: apply:true writes nothing unless it validates (OODS-V216), and a dry run returns the report. The receipt lists each changed slot. Build failure returns OODS-S019 with the last 40 output lines; source writes remain in place. After the build, the review kit's variables.css holds the CSS variables the build emitted differently, under their selectors. Default dry-run writes no files, directories, transcripts or bundle indexes. Only apply writes its run record. The brands are the brand registry's: the brands folder the token build reads (A and B ship; health_check lists them). A brand of yours (in OODS_BRANDS_DIR; from npm ~/.oods-foundry/brands) is written and rebuilt there, from npm too. For the brands OODS Foundry ships, the runtime bundle ships the brand source, so apply:false previews from the bundle; there apply:true emits the review kit (snapshots and specimens) without writing source or rebuilding, and the receipt records both steps as skipped. OODS-N020 is returned only when the brand source directory is missing. ## brand_create Actions: `create`, `draft`, `apply`. Create a brand or stage a local token intake draft. Use it when adding a brand; use brand_read for templates, validation, derivation and draft review, or brand_apply to edit a brand. Returns a staged draft or created brand with build results. apply needs draftId and accept:true. create accepts filled documents or a recipe, validates all themes, refuses replacement and removes a brand whose build fails. Full schema: oods://schemas/brand_create.input.json. ## catalog_list List available OODS components from the live component-contract registry, with current trait usages and registry object/trait names including team definitions: business objects first, OODS Foundry's internal objects only when includeInternal is true, and registry.hiddenInternal counting the ones left out. Historical readiness evidence is retained with its original provenance. Filter by category, trait, or rendering context. Response includes availableCategories array showing all valid category values for filtering. Unfiltered, it answers briefly: each component's name, categories and one readiness label (proven-in-generated-apps when a runtime sweep's generated app used it, the sweep its evidence names; react-and-vue; or incomplete); detail summary adds tags, contexts, regions and traits, and detail full adds the evidence. Filtered calls with no explicit detail now default to full detail in pages of 10. Unfiltered calls keep their bounded brief default. `totalCount`, `returnedCount` and `nextPage` make truncation explicit; pass `nextPage` unchanged for the next response. `pageSize` is at most 100. An explicit `detail` without paging preserves the previous unpaged response. ## code_generate Generate a versioned, content-addressed React or Vue file-set artifact, or a self-contained static HTML document with sample data, from a validated UiSchema tree. Select draft, build, or release validation; build is the default blocking gate of static checks (schema, registry, readiness, prop/slot/event/binding contracts, dependency closure and HTML fallbacks; the static gate does not install or run the generated application), and every response includes a validationReceipt naming applied policy, checks, omissions, and evidence disposition. Receipts produced after artifact construction also name that artifact's content hash. Release receipts retain accepted caller-supplied evidence references without claiming independent execution. The artifact includes exact dependencies and required consumer-supplied domain actions. Legacy code/fileExtension/imports aliases remain for compatibility. Accepts schemaRef from design_compose; save it before the 30-minute reference expires. Release receipts report evidenceVerification:file-verified-not-re-executed. Local JSON evidence files are opened and SHA-256, passed status and artifact binding are verified; evidence is not re-executed. contentHash names the evidence file-byte digest. OODS-V162 reports missing files or envelopes; OODS-V163 reports invalid JSON, byte hash, status or artifact binding. Portable React/Vue generation uses an assembly-time readiness attestation bound to shipped package bytes and emits real artifacts without source or test files. Missing or tampered readiness evidence returns OODS-N015 without an artifact. Host repository generation retains direct readiness checks. Application options.theme accepts light, dark and hc, with options.brand in the brand registry (A and B ship), for both the shell and embedded chart assets. Authored Subscription payment histories render through viz_render; absent payment history produces a named empty state without claiming a rendered series. Both assets remain verbatim in React and Vue. Bound record-array charts support bar, line, area, scatter and heatmap with explicit sampleRows; trait titles, descriptions and units accompany generated static SVG. Invoice bar and Usage line are authored in detail and dashboard layouts. Relationship detail and workflow declare an edge-array force_graph over optional neighborhood rows, explicitly labelled synthetic. Source and target IDs produce sorted distinct nodes and row-ordered directed links; a true bidirectional flag adds the reverse link, with directed-pair deduplication and no invented values or groups. Missing or malformed edge fields fail closed. VizGraphPreview embeds the exact public SVG inside a named wrapper. React/Vue application output is supported. HTML shares its record renderer with schema_render document output: labelled native form controls, local list search/filter/sort/pagination, keyboard tabs, charts and selectable workflow screens and loading/error/empty/success states. Domain actions display an integration notice and never claim a saved, deleted or navigated record. The build profile statically validates HTML contracts and fallback absence; it does not launch a browser, run axe or measure text parity. HTML opens directly from disk with embedded styles and scripts. Broad HTML browser coverage is recorded separately from generation checks. options.payloadMode file writes every artifact file plus artifact.json beside the saved-schema store (/../payloads/code_generate-/) and returns a payload block of file references instead of the artifact, for clients with a result-size cap; a directory that cannot be written is OODS-S020 with no payload. React/Vue substitution uses the mapped package export and translated normalized props for single screens and workflows. Artifact substitutions record mapping identity and exact package versions; install steps name the team dependencies. An explicit mapping version or an installed package manifest is required. Mapped team components receive advisory componentContracts reports from the shared contract scenarios through the generated adapters. With a preview host and an installed Chromium browser (OODS_CONTRACT_BROWSER_EXECUTABLE or OODS_PLAYWRIGHT_WS_ENDPOINT), the host executes real React/Vue checks; it does not download browsers or install team packages. Reports bind package, adapter and contract bytes, enumerate met, unmet and not-checked obligations, and travel in file payloads too. Unavailable checks and the 45-second check budget remain not-checked; unmet obligations add OODS-V218 warnings without refusing generation. Unmeasured obligations remain not checked. options.output application delivers a runnable single-screen React/Vue app with strict TypeScript, package.json, Vite config, index.html and entry, deterministic sample data and a README. For HTML, application output is the same standalone document. The default remains component output for React/Vue; their workflows already emit apps. A generated app installs its @oods packages from npm, at the exact versions the install block names. Domain actions show a visible integration notice until the consumer supplies its handler; no backend change is fabricated. Sample fields use authored examples/defaults/enums or neutral typed values. Missing payment history produces a named empty SVG state, with no chart data or viz_render call. React and Vue shadcn mappings import the project module for component output; React output puts 'use client' first for Next.js App Router. Application output stays Vite, copies the local closure, CSS and font assets, configures aliases and Tailwind, and pins installed dependencies. Binary artifact files have encoding: base64; file payloads decode them. Metadata contains the base, style, project-relative paths and closure hashes. Dark shells set both data-theme and the dark class; component consumers must set both on an ancestor. React and Vue shadcn mappings support components, screen apps and workflow apps, each in its own framework. Static HTML documents keep OODS components and report OODS-V218 for each shadcn mapping they drop, as does output in a framework the mapping does not cover. In a reply to an MCP client, an unset options.payloadMode is inline unless the artifact would exceed 100,000 characters; then it is written as with file, and warning OODS-W004 says so. options.payloadMode inline always returns the artifact in the response. ## design_compose Compose a UiSchema from an object and a context, or from a short intent sentence matched against fixed keyword and phrase tables: a sentence that matches no layout keyword uses the dashboard default without numeric confidence (OODS-V116) with no object, so naming an object and a context is the reliable input. Returns schemaRef for reuse in validate/render/code_generate. schemaRef includes createdAt/expiresAt timestamps (default TTL: 30 minutes) and lives in the server process that issued it: a restarted client starts a new server that does not know earlier refs and returns OODS-N003 for them. To keep a screen beyond the TTL or across sessions, save it with schema_store (action: save) and load it by name (action: load). Every successful composition is recorded as a durable version (compositions//versions/.json beside the saved-schema store) and the result carries compositionId, version, parentVersion, operation and head; pass compositionId to record the result as that composition's next version, or options.transient to record nothing. design_preview opens any version at /preview//. preferences.regionOrder, preferences.fieldOrder and preferences.seed are the override surface edits re-compose through; the seed is recorded on the schema and rotates the deterministic sample data. Selected OODS Foundry nodes snapshot active substitution mappings; meta.substitutions lists affected nodes. A saved snapshot retains its mapping even if the user store changes. Component selection remains based on OODS Foundry traits. Explicit placements omit confidence; keyword rankings report their computed scores and warnings. Selections describe only surviving slots. Validation failures and unloadable objects return errors. ## design_preview Actions: `render`, `compare`, `edit`, `accept`. Render, compare, edit or accept a running React/Vue composition. Use it when reviewing generated behavior; use design_versions to inspect lineage without starting a host, or fidelity_preview for static drawings. Returns preview URLs, editable fields and measured or unmeasured evidence. Supply compositionId/version or object/context. Edits create versions; compare generates missing artifacts. accept records the generated version and a snapshot of its measurements as accepted, preserving prior acceptances. Full schema: oods://schemas/design_preview.input.json. Open a composition version as the generated React or Vue code actually running in a browser (a single screen mounted by the preview host with generated sample records, or a workflow app): an existing compositionId (and optional version) or an object and context composed now as a new composition. Generates one or both frameworks onto the version, seeds the deterministic field model, compiles each artifact once through the preview host and returns one URL per framework with the lineage (compositionId, version, parentVersion, operation, head), the schema hash and the compiled module digests; the page leads with the running app under its brand, theme and width controls, with the lineage and the measurements one toggle below it, and brand and theme re-mount the app in place. Measurements are stored on the version and the result's measured block names them: the code_generate validation receipt per framework, artifact_certify for every placed chart, and axe-core run inside the running page per framework, brand and theme; every measurement not taken is listed under notMeasured, so nothing is claimed that did not run. The HTTP bridge hosts the preview in-process and the stdio adapter starts it on 127.0.0.1 for Claude Desktop, Claude Code and Cursor, so the extracted runtime bundle serves it with no Vite, npm install or browser automation. A client that negotiates the MCP Apps extension (io.modelcontextprotocol/ui) with the stdio adapter also receives the preview app as a ui:// resource: the same running app with its lineage and measurements, the brand, theme, framework and width switches, the four edits, compare side by side, accept and request changes, inside the conversation. The MCP Apps SDK reference host v1.7.5 rendered React and Vue inside the conversation with OODS_MCP_APPS_UI=1, through a local HTTP-to-stdio relay and a one-line change to how the host serves its fixed sandbox file, measured on 0.2.1. Its initialize request advertises no UI capability, so the default is a text result; no Claude Desktop or Cursor run is recorded. action compare (compositionId@version against another version) prepares missing generated artifacts for both versions in the requested frameworks, then returns the structural what-changed (including props on and inside slots and objectSchema fields in the definition category; identical requires equal schema hashes) the compare page shows: regions added, removed or reordered, slot components, nodes outside slots, props, field order, the seed and artifact files whose hash moved, with the side-by-side URL; identical versions report zero differences. action edit applies one operation to compositionId@version by re-composing through the override surface and re-generating, and records the result as a new version with its parent and the operation, then opens it: reorder-region (regionOrder), swap-slot (slot, component from the composer's own candidates), reorder-fields (region, fieldOrder), seed (seed); the parent version is never changed, and an operation that names nothing on the version or changes nothing is refused with OODS-V204. design_versions lists the composition's versions with their lineage and the accepted one, without starting the preview host. action accept records compositionId@version (default its latest) as the composition's accepted version, with the time, its schema hash and a snapshot of its measurements; a later accept supersedes it with lineage, and a version not generated yet or already accepted is refused with OODS-V205. The render result's editable block names the regions, slots with candidates, field order and seed an edit may use; the page offers the same four edits. Typed limits: without a reachable host (a native server run on its own, a host reading another schema store root, or a platform without a bundled esbuild binary) the outcome is OODS-N021, retryable, with the host details in data; an unknown composition or version is OODS-N022. Mapped team packages resolve from an installed folder or an absolute mapping localPath, must match their exact version pin, and are bundled with OODS Foundry globals preserved. Package content hashes bind the stored artifacts; opening latest after a package changes records a new version, while an explicit old version serves frozen ESM and MCP-app modules. Missing or unbuildable packages fail with OODS-V217. Package scripts are never installed or run; imported CSS must inline its assets. Writes only the version's artifacts, model, package identity and compiled module snapshots; never saves or edits a schema. A running preview is an observation, not usability certification. Context beside the design: pass contextItems with the decisions and evidence YOU already fetched about this object — each carrying source, id, title, body or excerpt, the query that produced it and when you fetched it — and OODS Foundry validates them, keys them to the composition object and its OODS Foundry URN (urn:oods:object:@), stores them on the version beside the measurements so they travel with the lineage, and renders them beside the running app on both surfaces. An item naming an object the composition does not show is refused with OODS-V207 and nothing is written; a malformed item is refused with OODS-V206. Pass contextSearched for a source that returned nothing, so an empty panel states what was searched rather than leaving the reader unable to tell nothing-found from nobody-asked. An edit carries the panel onto the new version and marks every item, because it was gathered for the design as it was before. Observation beside the design: pass observationRunPath, a Stage1 run directory on this machine, and OODS Foundry reads its identity_graph and object_rollup through structured_data_fetch, compares them with this version's own schema for the object on screen, and shows the rows beside the running app on both surfaces — observed-only, composed-only, agreeing and disagreeing, each disagreement naming its axis (entity, input, data-bound), every row naming the Stage1 run, target, artifact and capture time beside the OODS Foundry object, context and URN. The rows are evidence a person judges: nothing is proposed, applied or queued, and OODS Foundry opens no other product's store or writes into the run. OODS-V208 refuses a path that is not one Stage1 run, OODS-V209 an artifact outside the accepted schema_version, OODS-V210 a composition whose object the registry does not hold; each writes nothing. An edit carries the rows onto the new version and marks every one. Run view: pass runPath, a Stage1 run directory on this machine, with object Run, Finding or CapturedArtifact, and the version shows that run's REAL records — the run, its findings with their result state and provenance, its attested artifacts — read only through structured_data_fetch's run-view kinds; OODS Foundry never calls Stage1 or writes into the run. OODS-V212 refuses a path that is not one Stage1 run, OODS-V213 an artifact outside the admitted contract, OODS-V214 a composition that is not a capture object or a version already showing a different capture identity or manifest; each writes nothing. Nothing is proposed, applied or queued. Capture inspection in the browser appUrl: use presentation stage1-inspection to omit the accessibility score and show measurement limits. Run/Violations/Needs review/Artifacts navigation is read-only, filters and keyboard row opening work, and evidence links recheck the selected operand against the pinned capture manifest and SHA-256. Pass recordId with a fresh runPath detail/card/inline request to select an exact record; unknown IDs are refused before compose. Existing versions retain their record and presentation; a different capture ID or changed manifest is refused even for the same target. These navigation controls live in the browser appUrl, not the inline conversation renderer. Derived Comparison: pass analysisPath (separate from runPath) with object Comparison or ComparisonSignal. Summary, filtered signal list and exact recordId detail use generated React/Vue. Signal detail requires its analysis-id#/signals/N recordId. Both comparands retain paths, JSON pointers and SHA-256; cached navigation and every evidence open recheck all pinned retained bytes. Source and analysis identities/times stay distinct; copied inputs are not rerun. Synthetic zero is labelled; typeface comparands remain incomplete, with no type conformance ratio or source accessibility score. These read-only controls are in browser appUrl; human acceptance and public distribution are separate. Mapped team component contract reports are stored on the preview version and shown in Measurements. Unmet obligations are warnings; unmeasured obligations remain explicitly not-checked. Stored chart artifacts record the token CSS build that drew them. Reopening through design_preview regenerates stale charts; a browser page opened from the saved version flags a token build change until redrawn. Mapped shadcn source renders with its project Tailwind 4 theme. Latest previews refresh after mapping, import-closure or CSS changes; unrelated files keep the same version. Explicit old versions retain their compiled bytes. ## pipeline_run Execute the full design pipeline (compose -> validate -> render -> codegen) in a single call. It forwards draft, build, or release generation validation without downgrade and always discloses the applied validationReceipt plus target resolution provenance. The code step carries the versioned artifact without flattening, including exact dependencies and required consumer-supplied domain actions. Defaults to compact render mode (token CSS omitted). Supports optional validation/render skipping, an optional static screen and built-scope contrast check (options.checkA11y; unresolved pairs remain unmeasured), and schema persistence via save parameter. Returns schemaRefCreatedAt/schemaRefExpiresAt (default TTL: 30 minutes); use save to persist the schema. Release receipts report evidenceVerification:file-verified-not-re-executed. Local JSON evidence files are opened and SHA-256, passed status and artifact binding are verified; evidence is not re-executed. contentHash names the evidence file-byte digest. OODS-V162 reports missing files or envelopes; OODS-V163 reports invalid JSON, byte hash, status or artifact binding. Portable React/Vue generation uses an assembly-time readiness attestation bound to shipped package bytes and emits real artifacts without source or test files. Missing or tampered readiness evidence returns OODS-N015 without an artifact. Host repository generation retains direct readiness checks. options.payloadMode works the same way in a reply to an MCP client: unset, the rendered page and the generated files go to render/index.html and code/ when they would exceed 100,000 characters, and payload lists them with its reason instead of render.html and code.artifact; file always writes them, inline always returns them. ## health_check Read server readiness, live registry/store counts and retained proof summaries. status ok means health could read its sources; each retained proof names the build it measured, and only the reference-app proof says whether that is this build (thisBuild). tokens lists brands, themes and scopes from the built css-variables-by-scope.json, plus defaultScope {brand, theme, source: env|default}; this is configured default metadata, never an observed consumer scope. Missing built scopes are reported as unavailable. includeChangelog and sinceVersion select the reported DSL changelog; request-level DSL version selection is not supported. productReality.viz reports the generated taxonomy counts: types, patterns, families, classified, coreCells, coreSurfaceComplete, typedGaps and retiredCells. A surface-complete cell has public pixels from an identity assigned to that cell; Retired Core Analytics cells retain explicit reasons in the taxonomy; missing or invalid taxonomy yields null and degraded health. Each proof block also says what it was measured on (measuredOn: the release version its source declared, the source head and the archive, or null), and productReality.viz adds the census's certifiedChartTypes and certifiedScopes with the census's own measuredOn. server.uptime is milliseconds since the native server process started. ## registry_snapshot Return in one call recorded mappings plus the active shipped and registered team traits and objects, with a canonical ETag and generatedAt. Objects are the business objects; OODS Foundry's internal objects are included only when includeInternal is true, each object carries its visibility, and registry.hiddenInternal counts the ones left out. registry states the live source, names and loader issues, including the shadowed shipped Subscription. Draft preferred_terms, disambiguation_decisions and capabilities remain historical mapping storage fields and are not advertised as snapshot capabilities. By default the snapshot is a summary: each trait and object without its schema, parameters, view extensions, semantics, tokens and metadata, with descriptions cut to their first paragraph (about 45,000 characters). detail full returns complete definitions; the whole registry at full detail is about 410,000 characters, so pair it with names, which limits either detail to the traits and objects named and lists the others in notFound. ## viz_render Render a real, data-bound visualization spec from inline rows (or a datasetRef). Four input modes: supply pattern with an exact catalog id (for example pattern:viz:simple-bar) to render its bundled rows, encodings and presentation; supply chartType+encodings for explicit mode; omit chartType for recommender-driven suggest mode; OR supply a structured `intent` {goal, measures[], dimensions[], chartFamily?, measureRef?} (instead of chartType/encodings — the deterministic half of NL→viz) where the named fields drive encoding, the goal+data drive the recommender pick, an optional chartFamily post-filters it, and an optional governed measureRef lights the measure narrative under output.includeA11y. Returns spec for the five tabular Vega-Lite families (additional ECharts output opt-in). The eight ECharts-primary families return echartsSpec with spec omitted and output.echarts:true plus reason:echarts-primary-family, even if the caller passed false with a synthesized a11y description; compact by default with a specRef trio for pipeline reuse. Supports 13 chart types: 5 tabular (bar, line, area, scatter, heatmap) in suggest/explicit/intent mode, plus 8 explicit-only (treemap, sunburst, sankey, force_graph, chord, choropleth, bubble_map, flow_map). On the CARTESIAN color channel you may supply an explicit `encodings.color.range` — an array of 2+ hex colors (e.g. ["#1F6FEB","#D1242F"]) applied in order to the distinct series, overriding the baked OODS categorical palette (e.g. a 2-color presence scale). Cartesian nominal/ordinal color only: a range on a non-color channel is rejected, on an ECharts-primary type (treemap/sankey/etc.) fails loud (OODS-V145), and on a continuous color scale is ignored with a warning. certify grades the supplied range exactly as it grades the palette, so a low-chroma or low-contrast 'absent' color truthfully fails the contrast pillar — prefer chromatic colors above the chroma floor. For the categorical ECharts-primary types (treemap/sunburst/sankey/force_graph/chord), more distinct color groups than the 6-slot OODS palette recycles a color across two groups and is surfaced as a never-cycle warning (OODS-V146). For chord and force_graph link integrity, a link naming a node that does not exist fails loud (OODS-V147), and a duplicate directed (source,target) link — chord/force_graph are directed, so A→B and B→A are distinct — is surfaced as a warning (OODS-V148). SCOPE. theme (light|dark|hc, default light) and brand (a brand in the brand registry, default A) resolve the generated CSS token scopes for chart pixels. Omission equals explicit light/A. Scope changes chart content and SVG hashes. HC emits the scope declarations verbatim, including Canvas/CanvasText; computed paints are verified under forced-colors browser emulation. HC SVG for all 13 chart types and both brands was measured on 0.11.1, and its forced-colors browser proof on 0.2.1. HC heatmaps use nine declared quantized steps with symbol legends; numeric geo color uses declared piecewise steps. The paint guard still returns OODS-V165 if a renderer substitutes an undeclared paint. No server-side system-color hex palette is invented. Series retain the light palette where tokens declare no theme-specific palette. PATTERNS. The 22 offered source identities render public SVG with four conformant light/dark and A/B scopes; linked-brush-scatter is retired and not offered (the viz taxonomy records its reason and the correlation-scatter alternative): the input schema refuses it with OODS-V001, and a caller that skips the schema gets OODS-V174. Scenes preserve layers, bounded facets and secondary axes. Static SVG shows the default selection state (OODS-V175); transforms, datasets, external data and unknown traits remain structural limits (OODS-V167). Combining pattern with explicit data, encodings, intent or identity/presentation overrides returns OODS-V166. Brand, theme, strictFields and output controls remain available; authored source data and presentation are bundled for portable rendering. TEMPORAL RENDERING. Temporal axes render in UTC in both Vega-Lite and ECharts, independent of the host TZ. Adapter-generated parsing of formatted temporal fields also uses UTC; caller-authored expressions retain their own semantics. ScaleTemporal declares no timezone parameter; temporal rendering is UTC. Numeric tooltip formatting uses the en-US locale. ECHARTS SERVER-SIDE LIMIT: SVG rendering accepts only treemap, sunburst, sankey, chord, graph, map, scatter, and lines series; unsupported series return ECHARTS_UNSUPPORTED_OPTION. ECharts Cartesian line/bar/area output remains spec-only and uncertified. JSON output carries declarative `__oodsFormat` descriptors for axis labels and tooltips, including currency, numeric precision, locale and UTC time rules. Before `setOption`, pass the parsed option through `restoreEChartsFormats` from `@oods/foundry/echarts.js`. This standalone browser helper restores formatters without eval; see [ECHARTS-JSON.md](https://github.com/kneelinghorse/OODS-Foundry/blob/v0.11.2/packages/foundry/ECHARTS-JSON.md). Consumers that skip it still receive raw numeric values. The category-bar width cap is preserved in JSON. ## dashboard_render Render a composed metric-overview dashboard (KPI row + trend + breakdown + optional geo map) from a declarative DashboardSpec of shared datasets + panels. Composes each panel through the in-process viz engine with deterministic auto-layout and headless KPI compute, and applies a caller-supplied cross-filter selection at render time (declared links render as a labelled reference list; filtering uses selection and crossFilter). KPI tiles in HTML draw their computed sparklines and labelled breach/anomaly markers. Returns the resolved layout, per-panel compiled specs (Vega-Lite or ECharts, geo registration preserved), KPI values, a dashboard-level a11y block, and one specRef for pipeline reuse. PANEL IDENTITY. Every successful chart panel returns the contentHash produced by its in-process viz_render call; it therefore matches a standalone viz_render call with the identical spec and data. Set the call-level output.includeNormalizedSpec flag to also return each successful chart panel's NormalizedVizSpec. That IR can be passed to artifact_certify as {spec} alone for a cartesian chart, or as {spec,data} with exactly the matching hierarchy, sankey, chord, network, or geo branch for an ECharts-primary chart. These per-panel identity fields are attached after the dashboard's canonical {panels,layout} projection is cached and hashed, so they do not feed the dashboard contentHash. HTML IDENTITY. When output.html=true, outputHtmlHash is SHA-256 over the exact returned HTML bytes. It is evidence of deterministic output for that call and runtime, not part of the ECharts certified-matrix/renderHash epoch. All 11 admitted chart panel types draw server-rendered SVG in light, dark and HC; both HC brand scopes have forced-colors browser proof, measured on 0.2.1. Chord and flow_map stay excluded from dashboards. output.contrastScan is a four-pair brand-token preflight, not whole-document WCAG certification. HC scans return zero numerically graded pairs with a forced-colors explanation. BRAND. Pass brand (a brand in the brand registry) to select the palette used by both the tokens inlined into output.html and the four-pair contrast preflight; omit it for the previous behavior. Per-panel contentHash and dashboard contentHash are brand-invariant because brand applies at HTML/SVG emission time, while outputHtmlHash is brand-variant. SCOPE. theme (light|dark|hc, default light) and brand (a brand in the brand registry, default A) resolve the generated CSS token scopes for chart pixels. Omission equals explicit light/A. Scope changes chart content and SVG hashes. HC emits the scope declarations verbatim, including Canvas/CanvasText; computed paints are verified under forced-colors browser emulation. HC SVG and forced-colors browser proof for all 11 admitted dashboard chart types and both brands were measured on 0.2.1. HC heatmaps use nine declared quantized steps with symbol legends; numeric geo color uses declared piecewise steps. The paint guard still returns OODS-V165 if a renderer substitutes an undeclared paint. No server-side system-color hex palette is invented. Series retain the light palette where tokens declare no theme-specific palette. HTML sets data-theme and data-brand on the document. Governed measureRef resolution defaults to true: KPI refs bind field/aggregate, chart refs decorate narrative only. Unknown refs produce OODS-V130; missing resolved fields produce OODS-V137 through the panel error policy. Explicit resolveMeasures:false opts out of ref resolution; inputs without refs retain their rendered bytes. ## artifact_certify Certify the OODS Foundry NormalizedVizSpec returned by viz_render. Returns coverage, a measured conformant result, findings, and four pillars: a11yEquivalence, determinism, contrast and accuracy. Read-only: it reads the IR and the matching data operand without rebuilding or recommending a chart. DECLARED COVERAGE. The five Cartesian types certify from the IR alone. The eight ECharts-primary types certify under the declared operand profile when the same data branch used by viz_render is supplied. ECharts conformance requires a11yEquivalence:'pass', contrast neither 'fail' nor 'ungradeable', stable determinism, and accuracy:'pass' with rulesEvaluated > 0 and no detected distortion. A certified chart can be conformant:false; inspect the pillars and findings. No Vega-Lite compile is added to the ECharts profile. Spec-only ECharts calls remain coverage:'uncertified' with conformant:null and notes naming the missing operand. Unmodeled marks remain explicitly uncertified. DATA. An ECharts-primary IR carries metadata; nodes, links, rows and geometry live in its original branch. Supply exactly the matching hierarchy, sankey, chord, network or geo branch as data. The tool validates it against the mark trait. Data on a Cartesian IR is OODS-V123 because those charts certify from their IR. HTML or invalid IR is OODS-V126. ACCESSIBILITY. The 16 equivalence rules evaluate the operand-built table and narrative. Error-severity failures fail the ECharts pillar and conformance. Warnings stay visible without failing the pillar. Findings keep their native severity. a11yNotApplicable lists rules whose declared preconditions were absent; absence is not a meaningful pass. This channel is present when the ECharts engine completed, including [] if no rule was inapplicable, and absent for spec-only, Cartesian or incomplete engine evaluations. A completed engine with an individual rule fault retains its findings and not-applicable results while failing the pillar. An evaluator fault cannot produce a passing accessibility pillar. ACCURACY. Cartesian rules read the IR and compiled spec: non-zero bar baseline (V150), dual axis (V151), area scaling (V152), undisclosed aggregation (V153). ECharts rules read data: invalid hierarchy values/non-additive parents (V154/V155); invalid sankey/chord link values (V156); inconsistent sankey node throughput/duplicate links (V157/V158); conflicting choropleth join values (V159); negative or non-finite bubble size (OODS-V168), radius-based bubble scaling (OODS-V169), conflicting rows at the same bubble coordinates (OODS-V170), negative or non-finite flow strength (OODS-V171), duplicate directed geographic flows (OODS-V172), and duplicate directed force-graph links (OODS-V173). Reciprocal graph links and reciprocal geographic flows are distinct. Bubble scaling measures numeric diameters on the built projected ECharts option against area ratios from zero; missing drawn sizes are unresolved, and certification does not repair pixels. accuracyRules lists offered codes, while accuracySummary counts only rules whose preconditions resolved. Pass means no offered rule detected its distortion, not a general promise of accuracy; zero evaluated ECharts rules is unchecked and cannot yield conformant:true. DETERMINISM. Two independent compiler/adapter emissions are compared and rendered independently. contentHash identifies the first canonical compiled spec or projected ECharts option; renderHash identifies its normalized SVG and matches viz_render for the same operand/scope. Stable requires both identities to repeat. A first-render fault keeps contentHash, omits renderHash and fails stability. A bubble_map without inline geometry keeps the option proof, omits renderHash and names the no-server-map limitation. Proof is bounded by packages/viz-render/certified-matrix.json and covers certify's own rendering, not a caller's rendering. CONTRAST. Cartesian charts and ECharts calls with data grade actual rendered paints. Role C checks mark-to-canvas WCAG 3:1; Role A checks categorical CIEDE2000 distinguishability across normal vision and three CVD simulations, retaining recycled-palette duplicates. Missing baked OODS palette bytes cannot produce contrast:'pass'. The three geo families retain the standing contrast exemption with their render evidence; this includes ordinal bubble maps. Spec-only ECharts calls retain the reconstructed palette grade and caveat. Cartesian conformance still fails for fail or ungradeable contrast/accuracy; unchecked and exempt retain their existing semantics. Read every pillar's enum, including ungradeable. contrastResults reports the requested theme/brand and measurement evidence; exemptions do not claim a canvas ratio. SCOPE. Theme light|dark|hc and a brand in the brand registry select the same CSS scope as rendering, default light/A. HC contrast returns exempt, measured:false and reason:forced-colors, with no numeric grade. Accessibility, accuracy and determinism retain their normal evaluation; an actual HC render failure fails determinism and conformance. All 13 chart types render and certify conformantly in the 78 measured light/dark/HC and A/B scopes, measured on 0.11.1; HC has forced-colors browser proof, measured on 0.2.1, and no numeric contrast grade. After a release that changes a schema or verdict, reconnect clients that cache tool descriptions and schemas. ## fidelity_preview Render OODS Foundry objects or compositions at four fidelity levels. boxes-arrows draws declared object relationships as dagre SVG (object/depth or objects set); schema/schemaRef draws explicitly labelled component containment. wireframe draws the composed tree, regions, component names and field bindings with responsive layout and selected brand/theme tokens; review adds recorded node confidence, never invented scores. branded-mockup uses static sample HTML in the chosen built brand and light/dark/hc theme. Object+context composes a screen; schemaRef or inline schema uses an existing UiSchema. Legacy Object Catalog manifest input and nine packaged registry fixtures remain supported. Legacy branded mockups use light tokens; Unknown brands return OODS-BM-002 on that legacy path. Drawings are not live applications or referential-integrity checks. ## component_map Actions: `apply`, `create`, `update`, `delete`, `draft`. Write component substitutions or stage an intake draft. Use it when connecting React/Vue exports, shadcn source or built Storybook files; use component_map_read to list, resolve or review drafts. Returns staged evidence or write outcomes. apply with draftId requires accepted ids and writes adapters and mappings atomically. create takes one entry, mappings or mappingsPath; create and report-based apply preview unless apply:true. update and delete always write. Full schema: oods://schemas/component_map.input.json. Read actions list, resolve and show now belong to component_map_read. Write actions draft, apply, create, update and delete belong to component_map. The following shared mapping contract describes both halves. Manage mappings in your user folder with action draft|show|apply|create|list|resolve|update|delete. draft reads, from an absolute local source.project, a shadcn or shadcn-vue project (source.format shadcn) or a built Storybook (source.format storybook, with source.storybook naming its folder), without running its code, resolving installed dependencies or fetching anything; it returns a draftId (components-), the source content hash, mapping proposals, counts and warnings, and changes no team file or active mapping. show takes that draftId and exposes every component, prop and story as proposed or unmatched with a reason, with the exact adapter files a proposal installs and their limits. apply with that draftId and accept, the proposal ids you reviewed, checks the source hashes again, validates the mappings against the installed project, writes only reviewed new adapter files and registers the accepted mappings in one atomic write; missing dependencies or any invalid mapping roll back the adapter files and leave the mapping store unchanged, and an existing adapter with different contents is reported, never overwritten. An accepted React or Vue implementation joins the mapping that already owns its component; replacing an existing implementation needs update. Drafts are kept under OODS_FOUNDRY_HOME/intake (default ~/.oods-foundry/intake). Optional substitution names a shipped OODS Foundry component, React and/or Vue package exports, and OODS Foundry-to-team prop translations checked against the component contract. The launcher defaults OODS_MAPPINGS_DIR to ~/.oods-foundry/mappings; MCP_MAPPINGS_PATH remains an overriding file path. Legacy Stage1 annotations are preserved; their coercion labels are not executable substitutions. Compose snapshots substitution mappings on OODS Foundry nodes. React/Vue code generation applies team imports and prop translations with exact dependency versions; preview bundles installed or localPath packages and freezes their bytes per version; shared-scenario browser contract reports travel with generation and preview. Unmeasured obligations remain not checked. create also accepts mappings (a list) or mappingsPath (an absolute JSON file containing a mappings list), with one apply flag. Every entry is checked before one all-or-nothing write: ids and shipped components must be distinct from each other and existing mappings, and a localPath package must match its pinned name/version and export. The response names each entry outcome; OODS-V219 refuses a bad list without writing. Resolve path placeholders in a mapping file to absolute local package folders before calling. React and Vue also accept shadcn: { project: an absolute installed project root, module: its TypeScript alias or relative module }, plus export, instead of package/version/localPath; a Vue source (vue.shadcn) names a .vue module with export default. Create and substitution-changing updates statically check components.json, aliases, TSX and Vue single-file component exports, local imports and dependencies resolved from their importing files. Tailwind 4 accepts the Vite or PostCSS integration. React supports the Radix and Base UI bases and Vue supports shadcn-vue on Reka UI; React Aria and unknown styles are refused at create with OODS-V219. Metadata-only updates need no source project. Catalog event props permit name-only translations; event value maps are refused. ## schema_store Actions: `save`, `delete`. Save or delete a named composition schema. Use it when retaining a UiSchema across sessions; use schema_read to list or load saved schemas. Returns the saved metadata or deletion result. save takes schemaRef, overwrites that name and increments its version; only the latest is loadable. Both actions write immediately. Full schema: oods://schemas/schema_store.input.json. Saved schemas have no ETags or conditional requests. ## object_registry Actions: `list`, `show`, `validate`, `reload`. Read object and trait definitions or validate YAML without saving. Use it when exploring shapes or checking a definition; use object_register to save one or object_import to draft from a schema file. Returns definitions, composed traits, validation findings or cache reload status. includeInternal reveals hidden objects; reload clears only process caches. Full schema: oods://schemas/object_registry.input.json. ## object_import Actions: `draft`, `apply`. Draft objects from local OpenAPI, JSON Schema, Postgres SQL, Prisma, dbt, OData or GraphQL files, then apply accepted proposals. Use it when importing a schema; use object_import_read to review a staged object. Returns importId, staged files, proposal counts and re-import differences, or batch registration results. draft takes source.path or source.content; apply requires explicit objects and proposal ids. overwrite replaces team objects; confirmShipped names approved shipped replacements. No network fetch or code execution. Full schema: oods://schemas/object_import.input.json. ## schema_render Actions: `render`, `validate`. Validate a UiSchema or render static HTML and fragments. Use it when checking schema or patch contracts; use design_preview for a running app or schema_store to save. Returns diagnostics or rendered output. action selects validate/render; mode selects full/patch. apply:true enables rendering, without saving a schema. Render includes token CSS unless output.compact; oversized output or output.payloadMode:file writes only reply payloads. brand and scope options affect documents; ignored fragment options are diagnosed. Full schema: oods://schemas/schema_render.input.json. Validate or render a composition schema. Set `action` to validate (check a UiSchema/patch against the DSL+registry) or render (an HTML document using the same record renderer and deterministic sample data as code_generate HTML: bound values, native controls, charts, tabs and honest action notices; apply=true to emit). Fragment mode retains its component-fragment contract; document output binds composed object data. Render defaults to an HTML document with token CSS; output.compact=true explicitly omits it. The inert researchContext field has been removed. BRAND: pass brand (a brand in the brand registry) to render a specific brand's palette; omit it for the previous behaviour, byte-identical. On dashboard_render the brand drives both the tokens inlined into the output.html export and the palette output.contrastScan grades, so what is painted and what is checked are always the same brand. Fragment output diagnoses ignored brand/output.tokenOverlay/output.skinOverlay with OODS-W001. Non-strict fragments expose OODS-W002 when OODS-V006 is reclassified per node. Document output applies scope options. validate.apply is an ignored bridge-parity key. Fragment depth and request-level dslVersion are not supported. output.payloadMode file writes the rendered document as index.html (or fragments.json and css.json) beside the saved-schema store (/../payloads/repl.render-/) and returns a payload block of file references instead of html, fragments and css; a directory that cannot be written is OODS-S020. In a reply to an MCP client, an unset output.payloadMode is inline unless the output would exceed 100,000 characters (a document with its token CSS is about 680,000); then it is written as with file, and warning OODS-W004 says so. ## a11y_scan Grade accessibility against the built tokens. Checks button states per intent and every text and non-text colour pair the shared component stylesheet declares (4.5:1 for text, 3:1 for icons and progress/meter marks) in every built brand and theme, a team's brands included. With a UiSchema, grades only the pairs that apply to that screen's components, renders it through the shared HTML renderer and checks its document language, title, one main landmark, unique IDs, ARIA references, control names, image alternatives, chart SVG names and descriptions, and heading names and order. Pairs that need an inherited surface, dynamic CSS, alpha compositing or operating-system colours are reported as unmeasured. Browser-computed colour and layout, keyboard and focus, and screen-reader behavior are not checked. Preview writes nothing. apply=true writes the report, transcript and bundle index. ## object_register Actions: `register`. Register an object or trait from reviewed YAML. Use it when saving a definition; use object_registry to list, inspect or validate without writing. Returns the saved definition and registry result. overwrite replaces your own definition. Team objects may shadow shipped objects; traits cannot reuse shipped names. Relationships must name valid targets and fields. Full schema: oods://schemas/object_register.input.json. ## schema_read Actions: `list`, `load`. Read saved composition schemas. Use it when listing saved work or loading a named schema; use schema_store to save or delete one. Returns metadata or the schema with a new process-local schemaRef, valid for 30 minutes. Tool input schemas are separate MCP resources. Full schema: oods://schemas/schema_read.input.json. ## component_map_read Actions: `list`, `resolve`, `show`. Read component substitutions and staged intake evidence. Use it when listing mappings, resolving an external component or reviewing a draftId; use component_map to stage or apply changes. Returns entries, matches or draft evidence including proposed adapters and unmatched elements. Reads local stores without generating adapters or changing project files. Full schema: oods://schemas/component_map_read.input.json. ## brand_read Actions: `template`, `validate`, `derive`, `show`. Read brand templates, validate documents, derive recipes or inspect staged drafts. Use it when preparing a brand without saving; use brand_create to stage or create it. Returns complete template slots, validation findings, a recipe with provenance and gaps, or draft evidence. derive takes exactly one of tokens, css or absolute cssPath. Template replies use compact JSON so all themes fit inline. Full schema: oods://schemas/brand_read.input.json. ## object_import_read Actions: `show`. Read one staged object import. Use it when reviewing YAML, graded proposals and unmapped elements before acceptance; use object_import to draft or apply. Returns the named object, proposals and differences from its registered definition. Supply importId and the exact object name. Reading never rewrites the staged report. Full schema: oods://schemas/object_import_read.input.json. ## design_versions Actions: `versions`. Read a composition's versions and accepted version. Use it when inspecting saved lineage; use design_preview to render, edit, compare or accept. Returns version metadata, latest and acceptance summary. Supply compositionId. Starts no preview host and returns no running URL. Full schema: oods://schemas/design_versions.input.json.