@reqvire-org/ads 0.3.18 → 0.3.21

package/dist/skills/ads-break-ui/references/review.md

@@ -0,0 +1,96 @@
+# Development-only review UI
+
+Read this when creating or migrating demo frames, preview sizing helpers, token
+renderers or demonstration controls. MCP serves it as `ads://guides/review`.
+
+## Responsibilities and boundaries
+
+Components provide cohesive production capabilities. Patterns provide reusable
+application structures/workflows. Both receive variable application data and
+callbacks through their APIs. Their scenarios import the same implementation
+used by the application and supply fixtures; do not create a second implementation
+that only looks correct in the showcase.
+
+`design-system/review/` owns development-only presentation: example frames,
+arrangement, demonstration controls, token sample renderers and their styles.
+It remains project-owned. The MCP host shell stays generic; review code executes
+inside the preview App with the project's framework, foundation, fonts and styles.
+Nothing depends on particular helper names or an imported component library.
+
+The development entry defaults to `review/index.ts` relative to `dsDir`; configure
+`reviewEntry` for another script inside `review/`. Its import alias is the
+configured `publicAlias` plus `/review`, normally `@ds/review`. Discover the actual
+entry/alias through `ads_status.project.review`. Export helpers there, never from
+the production public barrel. Review implementations, types and styles must not
+enter application, component, pattern or controller dependencies. Tests, fixtures,
+scenarios and preview mounts can consume review code.
+
+Review helpers can own Linaria presentation, local state and demo controls. Normal
+style-token, variable ownership, measured-style-write and application separation
+gates still apply. They consume deliberate public component/pattern/controller
+contracts and may reuse local foundation helpers. They cannot target private
+component styles or replace real product behavior. Keep one-off fixture data in
+the scenario; a helper need not become a product API to frame an example.
+
+## Scenario and token contracts
+
+```tsx
+import { Panel } from "@ds";
+import { ReviewFrame } from "@ds/review";
+import { fixture } from "./Panel.fixture";
+
+export const scenario = { title: "Panel", covers: ["Panel"] };
+export default function Scenario() {
+  return <ReviewFrame><Panel {...fixture} /></ReviewFrame>;
+}
+```
+
+The names above are illustrative. `covers` names the production subjects actually
+demonstrated, not every review wrapper. A review export has no product catalogue
+entry and needs no standalone catalogue scenario. Keep review unit tests/specs
+beside their owner; optional behavior contracts can verify review guarantees
+through an existing real scenario. They establish no production coverage.
+
+A token scenario may name its real review renderer in `covers`, import it from
+the development entry, declare `samples: fixture.samples`, and pass those samples
+into the renderer. Existing real product patterns may also serve as token UI.
+Empty covers, unused samples, fabricated tokens and plain value lists remain
+invalid. The rendered App must still pass token-binding checks. See
+[scenarios.md](scenarios.md) for the full token/render contract.
+
+Review class helpers can supply source-proven Linaria classes to a scenario.
+Arbitrary scenario classes/styles remain forbidden. A review wrapper's own native
+controls do not authorize arbitrary native controls in its consuming scenario;
+slot/selector exceptions still need actual production-owner evidence. Keep
+production and review export names distinct where `covers` would be ambiguous.
+
+## Build and guarded edits
+
+The normal preview plugin registers the exact review alias before broader product
+aliases. Configure the same alias in project TypeScript and any independent
+preview/dev harness. In an ordered bundler alias map, put `@ds/review` before
+`@ds`; the broad `@ds` mapping must not resolve it as `index.ts/review`.
+Production entrypoints never import the development entry. Inspect the product
+bundle for review modules/CSS; passing static checks does not prove bundle parity.
+
+Use `ads_units` for `review/<Owner>` units. Scenarios, local specs and helper files
+follow ordinary flat/directory ownership. A review patch may update only its own
+re-exports in the development entry and its own documented style boundaries.
+Product owners retain the separate production entry companion. Use prepared
+patches/dry runs and coupled transactions as described in
+[guarded-editing.md](guarded-editing.md); do not bypass a rejected mutation.
+
+For an existing project, identify helpers by responsibility and actual consumers,
+not names or the number of imported components. Preserve real application patterns.
+Move only demo helpers, their styles and relevant guides to `review/`; update
+scenario/preview imports, style-boundary paths, TypeScript/bundler aliases and
+links. Remove their production exports and obsolete standalone product scenarios.
+Do not copy old example fixtures or export demonstration controls as product UI.
+
+Upgrade ADS before migrating a consuming project: older versions do not know the
+separate review entry. For staged guarded edits, first add distinctly named review
+exports, migrate consumers in passing owner patches, then remove the old pattern
+exports/owners once unused. Required coupled changes use a transaction. Check
+source gates, typecheck, preview and production builds, real browser rendering,
+registered behaviors and token bindings. A source move alone establishes none
+of those rendered guarantees.

package/dist/skills/ads-break-ui/references/scenarios.md

@@ -34,10 +34,31 @@ do not add scenario `preventDefault` handlers merely to hide it. Explicit App
 bases retain their declared behavior and CSP requirements; external hosts own
 their document-loading policy. Verify link activation as well as rendering.
 
+## Forms inside Apps
+
+Use real form semantics and the runtime owner's intended submit handler. ADS's
+showcase and diagnostic explorer permit `allow-forms` at every iframe layer,
+including legacy widgets. Browser constraint validation, Submit clicks, Enter and
+`requestSubmit()` can reach the normal submit path. Client-side forms call
+`preventDefault()` in their submit handlers; the host does not synthesize clicks
+or submit events. Native action requests are blocked by CSP `form-action 'none'`.
+Submit effects that use tools or resources still follow the MCP bridge.
+
+If a click fires but the `submit` handler never runs, inspect the browser's sandbox
+diagnostic and every ancestor iframe's permissions. Distinguish that host problem
+from native constraint validation legitimately preventing submission. Do not add
+scenario click interception to disguise a missing sandbox permission. External
+MCP hosts control their own sandbox/CSP policy.
+
+Verify an invalid submit, a valid submit, implicit Enter submission and the promised
+state effects. A working Next button is not evidence that form submission works.
+Keep native action navigation separate from client-side submission behavior;
+`allow-forms` does not grant host DOM access or top-level navigation.
+
 ## Owner-local token previews load their own definitions
 
 Keep the registered token sheet imported by its runtime owner for product use.
-A colocated `kind: "tokens"` scenario may render only the public review pattern
+A colocated `kind: "tokens"` scenario may render only the development-only review renderer
 with its fixture samples. Discovery adds the registered owner sheet to the
 generated record's `stylesheets`; `previewEntriesPlugin` imports those paths
 into the token preview independently of the runtime component. Custom builders
@@ -91,7 +112,7 @@ These examples describe verification mistakes, not component-specific rules:
 
 | Situation | Do not | Do instead |
 |-----------|--------|------------|
-| A reference example sets `width: 15rem`, while the native popup uses its default width. | Remove the reference width and claim the original example now matches. | Keep the baseline intact. Reproduce demo sizing through the project's public review/layout pattern or supported style helper. If a different native size is intentional, document it. Label any additional normalized comparison separately. |
+| A reference example sets `width: 15rem`, while the native popup uses its default width. | Remove the reference width and claim the original example now matches. | Keep the baseline intact. Reproduce demo sizing through the project's development-only review helper or supported style helper. If a different native size is intentional, document it. Label any additional normalized comparison separately. |
 | Static tracing cannot prove that a public clear control renders when a value is selected. | Remove its export, drop its required coverage, or change runtime behavior merely to pass the gate. | Preserve the intended public API. Try a meaningful selected-state fixture or another real scenario. If valid rendering remains untraceable, report the tooling limitation with a small reproduction. |
 | A screenshot shows the clear control in a selected state. | Treat its presence as evidence that clearing works. | Add a browser check: start selected, activate Clear, assert the value and selection are empty, verify the control's resulting visibility and documented focus behavior, then select again. |
 
@@ -207,6 +228,6 @@ An `exercises` entry records behavioral use; it never grants styling permission.
 Keep helper signatures compatible with the product API. Fix ownership/provenance
 in the runtime owner when genuinely wrong; retain intentional public APIs when
 reporting an unsupported trace. Demo-only sizing, framing and arrangement still
-belong in public review/layout patterns. A style helper is not permission to
+belong in development-only review helpers. A style helper is not permission to
 author a second design in the scenario. For cascade risks and extraction issues,
 read [atomic-styles.md](atomic-styles.md).

package/dist/skills/ads-designer/SKILL.md

@@ -90,6 +90,19 @@ then page needed `ads_results` sections using the returned result ID. Inspect
 one `ads_investigate({unit,check,runId})` summary before changing APIs or policy;
 load request/error/artifact details only when relevant.
 
+Review/demo layout belongs in development-only `review/`, exported through the
+separate `${publicAlias}/review` entry (normally `@ds/review`), never the production
+barrel. Product patterns are application UI. For ownership, migration, token
+renderers, build aliases or `review-import` / `review-contract` diagnostics, read
+[development review UI](references/review.md), also served as `ads://guides/review`.
+
+A component provides one cohesive UI capability; a pattern arranges capabilities
+into reusable structures or workflows. Components may compose components/controllers;
+layout patterns may arrange slots. Do not classify by component count. For owner
+selection or `component-dependency`, `component-contract` or `component-style`, read
+[layer responsibilities and contracts](references/layers.md), also served as
+`ads://guides/layers`. Preserve public APIs and documented non-state styling hooks.
+
 For parent/child `covers`, conditional-control review, reference comparisons,
 public style-helper use, native slot/selector composition, fragment navigation,
 or `scenario-render` / `showcase-control` / `showcase-class` findings, read [scenario contracts](references/scenarios.md). Its verification
@@ -148,7 +161,7 @@ checks; do not fetch the unpublished package.
 Read [assets/bootstrap-ds/README.md](assets/bootstrap-ds/README.md) and its
 [contract](assets/bootstrap-ds/ADS.md). The scaffold contains semantic token
 defaults, React/TypeScript/Linaria configuration, general lint, a public
-barrel, empty product component directories, a project-owned token review pattern, and a project preview compiler adapter. The browser shell is supplied by ADS tooling.
+barrel, empty product component directories, a project-owned token review renderer, and a project preview compiler adapter. The browser shell is supplied by ADS tooling.
 It contains no components, shell patterns, vendored fonts, or example screens.
 
 Resolve assets relative to this skill's `SKILL.md`, including after installation
@@ -361,7 +374,7 @@ fixture under the configured token directory. Declare metadata
 The renderer name is project-owned; use its real public API. Each literal fixture
 sample declares `{ token, property, probe }`: a real token, the CSS property its
 sample demonstrates, and a valid test value different from that token's current
-value. Pass `samples` into the rendered public review pattern. Names, sample text,
+value. Pass `samples` into the rendered development-only review renderer. Names, sample text,
 bindings and probes are fixture data; displayed values come from foundation CSS.
 There is no property catalogue, token-name mapping or probe palette in ADS.
 Every token needs sample coverage; fabricated tokens, missing bindings/probes,
@@ -382,10 +395,12 @@ source definitions and values; inspecting definitions does not prove UI parity.
 The tool keeps the shared naming contract; sample templates and their token
 lists belong to the project.
 
-A public review pattern may be covered by real token or composition scenarios;
-it needs no redundant standalone entry. Remove an optional scenario only while
-retaining reachable render coverage. Keep directory ownership anchored by its
-runtime entry (`index` or a file matching the directory name) or colocated fixture.
+Development review helpers need no product catalogue scenario. A token scenario
+may name its review renderer in `covers`; ordinary component/pattern scenarios
+cover their production subjects. Keep review exports in the separate review entry.
+Remove redundant helper catalogue scenarios during migration. Product UI retains
+its real render-coverage requirement. Keep directory ownership anchored by its
+implementation entry (`index` or a file matching the directory name) or colocated fixture.
 Import colocated image/font fixtures so MCP serves them through asset resources.
 For a broken-image case, use a local failing fixture, rather than an external
 network failure or a domain-specific CSP exception. Production asset APIs remain
@@ -409,7 +424,7 @@ branch, property and value must fit its role. Token-backed control skins, layout
 interactive state rules and owner hooks are rejected even through `:where()`.
 Do not copy an unchecked upstream preflight or turn a component repair into a reset.
 Keep behavior and skin in their runtime owner. Put demo-only sizing and framing
-in a public review/layout pattern; add component props for a deliberate runtime
+in a development-only review helper; add component props for a deliberate runtime
 API need. Preserve required capabilities while following ownership rules.
 Use tokens for absolute/font-relative lengths, including `ch`, `ex`, `cap`, `ic`
 and `lh`; calculations and fallback values follow the same rule. Structural
@@ -507,3 +522,7 @@ For visual work, inspect the real project showcase, including keyboard/focus,
 relevant pointer/touch behavior, dark theme, and reduced motion as needed.
 A screenshot alone does not prove behavior or animation. Validate public imports,
 CSS/asset resolution, required setup, and local documentation links.
+
+For static owner contracts, `.ads.` development roles, typed paint/binding APIs,
+declarative evidence, token privacy and guarded migration, read
+[contracts.md](references/contracts.md) when the task touches those contracts.

package/dist/skills/ads-designer/assets/bootstrap-ds/ADS.md

@@ -72,7 +72,7 @@ layout, component-specific focus rules and hover/disabled skins are rejected.
 Shared token definitions belong in value sheets, not `base.css`. No project token
 names are embedded in this policy. A zero-specificity `:where()` wrapper does not
 change ownership. Put component design and animation in Linaria owners, and
-scenario layout variations in typed public review-pattern props. Browser review
+scenario layout variations in typed review-helper props. Browser review
 still checks the effects and accessibility of permitted defaults.
 
 Own primitive markup, focus, hover, selected, disabled, loading, and motion in
@@ -151,7 +151,7 @@ Flat owners may use `Button.scenario.tsx` and `Button.fixture.ts` instead.
 `export const scenario = { title: "Button states", covers: ["Button"] };`.
 Token entries under the configured token directory declare
 `export const scenario = { title: fixture.title, covers: ["TokenSamples"], samples: fixture.samples };`.
-`TokenSamples` is any project-owned public review pattern, not a required name.
+`TokenSamples` is any project-owned development-only review renderer, not a required name.
 Its colocated fixture declares literal `samples: [{ token, property, probe }]`.
 Each token must exist and have sample coverage; duplicate bindings, missing probes,
 empty covers and value-only inspectors fail. The default entry passes the declared

package/dist/skills/ads-designer/assets/bootstrap-ds/README.md

@@ -1,7 +1,7 @@
 # Empty native design system
 
 This private React/TypeScript workspace contains semantic CSS tokens, a project-owned
-token review pattern, a public barrel, Linaria extraction and a preview compiler
+token review renderer, a public barrel, Linaria extraction and a preview compiler
 adapter. It has no product components, icons, fonts or example screens. The minimal showcase
 shell and MCP client come from ADS tooling.
 
@@ -56,7 +56,7 @@ Its MCP client discovers entries, invokes preview tools and follows notification
 There are no required TokensPage/ComponentsPage/PatternsPage/CompositionPage
 files, and no separate project browser app to implement or rebuild.
 
-The existing `tokens/Foundation.scenario.tsx` and colocated fixture visually demonstrate all
+The existing `tokens/Foundation.ads.scenario.tsx` and colocated fixture visually demonstrate all
 starter token values. The fixture owns `{ token, property, probe }` bindings;
 the public `TokenPreview` pattern owns their presentation and applies the real CSS
 variables. Add/remove samples alongside token definitions. `ads check` rejects

package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/index.ts

@@ -2,4 +2,3 @@
 import "./styles.css";
 
 // Add public component and pattern exports here as they are implemented.
-export { TokenPreview } from "./patterns/token-preview/TokenPreview";

package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/review/index.ts

@@ -0,0 +1 @@
+export { TokenPreview } from "./token-preview/TokenPreview";

package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/tokens/{Foundation.scenario.tsx → Foundation.ads.scenario.tsx}

@@ -1,4 +1,4 @@
-import { TokenPreview } from "@ds";
-import { fixture } from "./Foundation.fixture";
+import { TokenPreview } from "@ds/review";
+import { fixture } from "./Foundation.ads.fixture";
 export const scenario = { title: fixture.title, covers: ["TokenPreview"], samples: fixture.samples };
 export default function Scenario() { return <TokenPreview {...fixture} />; }

package/dist/skills/ads-designer/assets/bootstrap-ds/ds.config.json

@@ -13,7 +13,7 @@
   "boundaries": {
     "styleWrites": [
       {
-        "file": "design-system/patterns/token-preview/TokenPreview.tsx",
+        "file": "design-system/review/token-preview/TokenPreview.tsx",
         "properties": [
           "--ux-token-preview-value"
         ]

package/dist/skills/ads-designer/assets/bootstrap-ds/tsconfig.build.json

@@ -7,6 +7,13 @@
     "rootDir": "design-system",
     "outDir": "dist"
   },
-  "include": ["design-system/**/*.ts", "design-system/**/*.tsx"],
-  "exclude": ["design-system/showcase"]
+  "include": [
+    "design-system/index.ts"
+  ],
+  "exclude": [
+    "design-system/showcase",
+    "design-system/review",
+    "design-system/composition",
+    "**/*.ads.*"
+  ]
 }

package/dist/skills/ads-designer/assets/bootstrap-ds/tsconfig.json

@@ -1,7 +1,11 @@
 {
   "compilerOptions": {
     "target": "ES2022",
-    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "lib": [
+      "ES2022",
+      "DOM",
+      "DOM.Iterable"
+    ],
     "module": "ESNext",
     "moduleResolution": "bundler",
     "skipLibCheck": true,
@@ -14,7 +18,18 @@
     "noUnusedParameters": true,
     "noFallthroughCasesInSwitch": true,
     "baseUrl": ".",
-    "paths": { "@ds": ["design-system/index.ts"] }
+    "paths": {
+      "@ds/review": [
+        "design-system/review/index.ts"
+      ],
+      "@ds": [
+        "design-system/index.ts"
+      ]
+    }
   },
-  "include": ["src", "design-system", "vite.config.ts"]
+  "include": [
+    "src",
+    "design-system",
+    "vite.config.ts"
+  ]
 }

package/dist/skills/ads-designer/assets/bootstrap-ds/vite.config.ts

@@ -7,7 +7,7 @@ import { linariaTagResolver } from "@reqvire-org/ads/linaria";
 export default defineConfig({
   plugins: [wyw({ tagResolver: linariaTagResolver }), react()],
   resolve: {
-    alias: { "@ds": path.resolve(import.meta.dirname, "design-system/index.ts") },
+    alias: { "@ds/review": path.resolve(import.meta.dirname, "design-system/review/index.ts"), "@ds": path.resolve(import.meta.dirname, "design-system/index.ts") },
   },
   build: {
     outDir: "dist",

package/dist/skills/ads-designer/references/contracts.md

@@ -0,0 +1,250 @@
+# Static owner contracts and development files
+
+Use one optional `<Owner>.ads.contract.ts` for owner-local tokens, constrained
+paint inputs, scoped runtime bindings, declarative parts and behavioral checks.
+The import `import type { UnitContract } from "@reqvire-org/ads/contracts"` supplies
+development typing. ADS reads its AST and resolves real symbols without importing
+or executing project modules. It adds no production runtime.
+
+## Files and ownership
+
+```text
+components/Plot/
+  Plot.tsx                     production API/root
+  Series.tsx                   production declarative API
+  renderer.tsx                 production consumer
+  paints.ts                    production binding producer
+  types.ts                     production prop types
+  tokens.css                   optional production token definitions
+  Plot.ads.contract.ts         static tool declaration
+  Plot.ads.scenario.tsx         demonstration
+  Plot.ads.fixture.ts           demonstration data
+  Tokens.ads.scenario.tsx       real owner-token samples
+  Tokens.ads.fixture.ts         sample bindings/probes
+  Plot.ads.behavior.spec.ts     registered browser checks
+  Plot.ads.test.tsx             optional unit tests
+  Plot.ads.helpers.ts           development-only adapters
+  README.md                    API/provenance
+```
+
+This is an example, not a required inventory. Use the same roles for patterns,
+controllers and relevant development owners. `review/` remains a separate
+shared development layer; its implementation filenames need no extra marker.
+Runtime components, types and styles cannot import `.ads.` files, tests, fixtures
+or review code through aliases, barrels or helpers. Unknown `.ads.` roles are
+still development-only and are diagnosed. Fixtures/helpers cannot define styles;
+put demo framing in review. Ordinary README/license files retain their names.
+
+Scenarios/fixtures/review enter only the selected preview closure. Contracts are
+never executable preview modules; derived audit descriptors are data. Specs run
+only in the configured test runner. Production declaration emission must also
+start from the public runtime entry, rather than include every file under the
+design-system folder. The starter’s `tsconfig.build.json` does this; its normal
+no-emit typecheck still checks development sources. Core import guards protect
+the runtime dependency closure. Review custom emitter configurations through
+the configuration owner before migrating a consuming project. Guards remain tooling. Production prop types
+belong in runtime files, never inferred from a development contract.
+
+## A contract uses actual implementation references
+
+```ts
+import type { UnitContract } from "@reqvire-org/ads/contracts";
+import { Plot } from "./Plot";
+import { Series } from "./Series";
+import { Renderer } from "./renderer";
+import { paints } from "./paints";
+
+export default {
+  schemaVersion: 1,
+  tokens: { namespace: "--plot-", stylesheet: "./tokens.css" },
+  paintInputs: [
+    { api: Plot, property: "config.*.paint", kind: "paint-reference" },
+    { api: Series, property: "fill", kind: "paint-reference", bindings: ["items"] },
+  ],
+  bindings: {
+    items: {
+      input: { api: Plot, property: "config" },
+      producer: paints,
+      valueFrom: "paint",
+      variable: "--plot-runtime-${key}",
+      scope: { api: Plot, selector: '[data-plot-root=""]' },
+      checks: ["isolation"],
+    },
+  },
+  declarativeParts: [
+    { api: Series, parent: Plot, consumer: Renderer, checks: ["isolation"] },
+  ],
+  behavior: {
+    subjects: { plot: { api: Plot }, renderer: { implementation: Renderer } },
+    guarantees: [{
+      id: "scoped-output",
+      description: "Changing either instance updates only its own output.",
+      subjects: ["plot", "renderer"], checks: ["isolation"],
+    }],
+    checks: {
+      isolation: {
+        file: "./Plot.ads.behavior.spec.ts", case: "isolation",
+        scenario: "components/Plot", profile: "widget",
+      },
+    },
+  },
+} satisfies UnitContract;
+```
+
+Keep contracts small; most owners need none or one section. Supported data are
+literal objects/arrays, static constants/spreads, `as const` and `satisfies`.
+Symbol references resolve through normal imports, aliases and re-exports.
+Calls, getters, methods, computed metadata and environment-dependent expressions
+are rejected. Function references are opaque identities, never executed.
+Private implementation subjects may be internal module exports without becoming
+public barrel exports. Producers/consumers must belong to the same owner. Required
+checks must exist, back named guarantees and use a browser profile with the
+corresponding scenario. A relationship is registration, not a passing guarantee.
+
+## Typed paints and runtime bindings
+
+Production-facing types can use:
+
+```ts
+export type Paint = `var(--${string})` | `url(#${string})` | "none" | "currentColor";
+export interface SeriesProps { fill?: Paint }
+export type Config = Readonly<Record<string, { paint: Paint }>>;
+```
+
+ADS follows the actual property path/type, including nested maps. A name such as
+`Paint`, an arbitrary `string`, `any` or a forged metadata role grants no waiver.
+Supported references are a single accessible token/binding `var(--name)`, a local
+SVG paint `url(#id)`, `none` or `currentColor`. Fallbacks, raw colours, external
+URLs and arbitrary CSS are outside this role. Raw domain colours need a separately
+reviewed validated input boundary; they are not implicitly supported here.
+
+A runtime family is instance data, not an infinite design-token inventory. Its
+source proof requires the declared config map, exact key/value mapping and actual
+root attachment. Supported producers use `Object.entries(config)` with a loop,
+or `Object.fromEntries(...map(...))`; same-owner helper returns are traceable.
+Guard each key before the write/return using
+`if (!/^[A-Za-z0-9_-]+$/.test(key)) throw new Error("Invalid key")` (a loop may
+`continue`). Return only the computed map. For example:
+
+```ts
+export function paints(config: Config) {
+  const result: Record<string, string> = {};
+  for (const [key, entry] of Object.entries(config)) {
+    if (!/^[A-Za-z0-9_-]+$/.test(key)) throw new Error("Invalid key");
+    result[`--plot-runtime-${key}`] = entry.paint;
+  }
+  return result;
+}
+```
+
+The runtime root attaches that returned map using `style={paints(config)}` or a
+traceable local/useMemo result and the declared class/exact data attribute.
+Place spreading props before the explicit scope/style so an unknown spread
+cannot replace them. This grants permission to that binding attachment only;
+it does not authorize arbitrary inline styling, CSSProperties APIs or bulk writes.
+Unsupported dynamic producers/attachment paths fail with an analysis diagnostic.
+Keep the implementation project-owned; there is no required ADS binding helper.
+
+Families cannot overlap shared tokens, owner-token namespaces, private runtime
+prefixes or other bindings. A broad family such as `--color-${key}` grants no
+shared-token exception. Use a distinct private family where collision freedom
+cannot be established. Registered paint consumers list their allowed binding IDs;
+borrowing a peer's family or private token remains invalid. Bindings are scoped
+to their actual root; portals outside it need deliberate project integration.
+
+The App audit checks current mounted instances, accessible values, local SVG
+resources and computed paint-property responses. Visibility and complete rendered
+output still need assertions in the registered browser checks. It rejects missing/duplicate IDs and reports unobserved written values separately. It is bounded to 100 families, 20 instances per family, 100 keys
+and 1000 elements per instance. Exceeding a budget reports limits and complete: false; it does not invalidate a
+working component. An unobserved paint effect also remains unverified until its
+relevant consumer/state is checked. It does
+not prove every future input, visibility state or interaction. In registered
+Playwright checks, use `auditBehaviorPaints(frame)` from
+`@reqvire-org/ads/verification` after updates. Assert `result.ok` and, when claiming complete current-map
+evidence, `result.complete` and the expected `verified` entries.
+Exercise two instances with identical keys/different paints, key updates/removal,
+themes, local SVG IDs and invalid/inaccessible references. Keep normal runner
+profiles; React StrictMode still needs a project development harness.
+
+## Rendered and declarative evidence
+
+`covers` names rendered public UI. A null-returning declarative part belongs in
+`exercises`, alongside behavioral APIs:
+
+```tsx
+export const scenario = {
+  title: "Plot", covers: ["Plot"], exercises: ["Series"],
+};
+```
+
+The real part must reach its registered consumer through a rendered parent.
+ADS resolves source identity comparisons (`child.type === Series`, including a
+traceable comparison helper) and reads of that same child’s props traced from the consumer’s children input.
+A comparison against a decoy object gives no evidence. An import, unrelated parent, unused
+child or metadata claim gives no consumption credit. Unknown render branches are
+conservative. Browser checks must verify that adding/removing/changing the part
+changes output. Source relationships and current browser evidence are separate.
+Do not add fake DOM, hide public parts or rewrite a valid API to appease tracing.
+
+Scenario metadata is validated by field/entry with positions and reasons.
+A bad entry still blocks acceptance while valid independent render evidence is
+retained. Unreadable prerequisites report coverage as not established. Inspect
+the exact source diagnostic and bounded results; do not assume every subsequent
+missing preview means its runtime API is invalid.
+
+## Local tokens and project consistency
+
+`tokens.css` remains optional production design data for component/pattern owners,
+imported by the runtime owner. Controllers stay headless; review uses the shared
+vocabulary and its own development presentation state. Only root/theme definitions belong there. Tokens require real sample
+coverage, including independently built owner token scenarios. One namespace
+cannot be shared by peer components. Private references remain private through
+TS constants, re-exports, helper returns, SVG/paint props and property reads/writes.
+Normal composition of a public component using its own tokens remains valid.
+Source analysis covers supported value flows; arbitrary dynamic code is not
+proof of ownership. CSS variables remain browser-visible; namespacing is an
+architecture boundary, not browser encapsulation.
+
+Ownership does not establish a project's visual scale:
+
+- A component redefining shared `--space-4` fails.
+- Its private `--plot-gap: 7px` can be valid component geometry.
+- `--plot-gap: var(--space-4)` preserves a shared scale with local meaning.
+
+Choose project policy explicitly. A registered project check can use tooling-only
+`inspectTokens(root)` and `inspectTokenOrigins(inventory, name, { stopAt: names })`
+from `@reqvire-org/ads`. `aliasOnly` verifies every theme definition follows only
+aliases to the explicitly selected origins; `literals` and `diagnostics` explain
+violations/limits. Select the exact targets and permitted shared origins. Keep
+intentional geometry exceptions exact with documented reasons. ADS neither
+infers spacing meaning from names nor prescribes a global spacing palette.
+
+## Migration and MCP editing
+
+Legacy `tokens.json`/`<Owner>.tokens.json` and `behavior.json` remain readable.
+Use either authoring form per section; competing declarations fail. New contracts
+normalize into the same discovery, ownership, source revisions, affected-check
+selection and candidate gates. `ads_units` exposes `contractFile`; `ads_catalog`
+reports constrained paint paths and declarative parent/consumer/check references.
+Use bounded file reads and paged detailed results, not repeated whole-project dumps.
+
+Install supporting ADS tooling before migrating a consuming project and reconnect
+MCP before replacing a package used by a running server. Then:
+
+1. Discover one owner with `ads_units`.
+2. `ads_prepare_patch({ unit, action: "migrate" })` creates a normal local draft.
+3. Review the converted contract, renamed files/imports and migration notes.
+4. `ads_prepare_patch({ unit, action: "diff", draft })` emits its Git patchFile.
+5. Dry-run/apply with `ads_apply_patch`, or a genuinely coupled transaction.
+
+Migration never edits live source or bypasses gates. It retains stable scenario
+IDs and check case IDs. An optional static `scenario.id` preserves a legacy
+identity when a renamed filename would otherwise be ambiguous; it must stay
+inside the owning unit and be unique. Whole-file or unimportable private behavior subjects stay
+in legacy registration with a note until deliberately resolved. Unknown runner
+globs, custom adapters and documentation references require review. Ambiguous
+flat-to-directory renames stay in the legacy form with a migration note so file
+ownership cannot silently change. Preserve
+licenses, pending drafts and unrelated work; keep transactions within their limits.
+There is no alternate JSON contract editor. Do not loosen a guard or make a valid
+API private merely to complete a migration.

package/dist/skills/ads-designer/references/guarded-editing.md

@@ -103,7 +103,7 @@ and a definition-only `tokens.css`, imported by its runtime source. Flat owners
 shared or --ds-/--ux-/--showcase- variables. Only that owner consumes/defines its
 local tokens; aliases can use shared or own tokens. UI styles stay in Linaria.
 Add a colocated token scenario with `kind:"tokens"`, real fixture `samples` and a
-public review pattern. These inputs belong to the same owner and need real sample
+development-only review renderer. These inputs belong to the same owner and need real sample
 coverage. Manifests and fixtures stay out of the product bundle.
 
 `ads_prepare_token_samples({id, bindings?})` preserves existing project samples,