@reqvire-org/ads 0.3.17 → 0.3.20

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

@@ -0,0 +1,123 @@
+# Components, patterns and application adapters
+
+Read this when choosing an owner, moving UI between layers, or resolving
+`component-dependency`, `component-contract`, `component-style`, `no-app-import`
+or `showcase-import`. MCP also serves this guide as `ads://guides/layers`.
+
+## Choose by responsibility
+
+A **component** provides one cohesive UI capability: semantics, input handling,
+focus, accessibility, states and appearance. It may compose other components and
+controllers. A notification using an icon, action button and spinner can still
+be one component.
+
+A **pattern** arranges capabilities and content slots into a reusable structure
+or workflow, such as navigation with search/account controls or a report screen.
+Layout parts may arrange `children` without importing several components.
+Patterns may compose other patterns. A native wrapper or a large implementation
+does not decide the layer.
+
+An **application adapter** supplies domain data, store access, route state and
+navigation/service callbacks. Domain-shaped inputs are valid in project-owned
+patterns; importing a particular application store/router is not.
+
+A **scenario** supplies demonstration inputs, local state and simulated services.
+A component scenario may compose several public components and development review helpers
+to demonstrate its subject. That does not turn its fixture or variant selectors
+into production API. Keep `covers` aligned with the scenario's subject layer.
+
+Do not classify by import count, JSX element count, names or file length. Review
+the capability and its consumer contract. Preserve valid APIs when tracing is
+inconclusive; do not make an export private or add a product prop just to pass.
+
+## Demonstrate the production implementation
+
+Product patterns are reusable application UI, not showcase replicas. A scenario
+imports the same production owner and supplies fixtures through its public API;
+the application supplies live data and callbacks to that API. Keep mock records,
+demo selections and simulated services in development files. Legitimate defaults,
+control labels and the pattern's own interaction logic remain with their owner.
+
+Demo framing must not replace a product pattern's styling or behavior. Browser
+checks should exercise both the demonstrated contract and relevant application
+integration; a successful showcase does not establish production parity. A new
+pattern need not already have an application consumer, and import counts cannot
+detect a duplicated implementation. Existing import guards prevent fixture/test
+dependencies; review and browser checks must assess hardcoded mock data and
+unrepresentative rendering that source ownership alone cannot prove.
+
+Review framing belongs in development-only `review/`, not production patterns.
+Use the separate review entry and [review.md](review.md) for the migration and
+build contract.
+
+## Dependency contracts (blocking)
+
+- Component runtime may depend on components, shared controllers and lower-level
+  helpers. It cannot depend on patterns or composition, including indirectly
+  through aliases, forwarding exports, helpers or literal dynamic imports.
+  Type-only pattern references do not introduce runtime dependencies.
+- Patterns consume component symbols published by the configured public entry,
+  including intentional public types. A relative import of a public symbol is
+  allowed inside the ADS; requiring a self-import through the barrel can create
+  cycles. Private state, class blocks and implementation helpers stay internal.
+  A public component may use its own private implementation dependencies.
+- Runtime code cannot import review implementations/types/styles, scenarios, fixtures or checks, including through
+  forwarding exports. Scenarios also cannot import application source.
+- ADS implementations receive application data/effects through inputs and
+  callbacks. Re-exporting application stores, routers or services from a helper
+  does not make them part of the ADS.
+
+For example, `components/Control → shared/helper → patterns/Navigation` fails
+`component-dependency`. Extract a lower-level capability/controller, or move the
+arrangement to a pattern. `patterns/Navigation → components/Control` is valid
+when `Control` is public. Replacing that import with its private state helper
+fails `component-contract` even through a forwarding module.
+
+## Styling contracts (blocking when ownership is established)
+
+Components own their control states and appearance. Patterns own arrangement,
+spacing and their own presentation. Use typed component props/variants, an
+intentional public class helper/hook, or registered non-state customization
+variables. Registration does not authorize overriding interaction policy.
+
+```tsx
+// Component-owned implementation; the marker is not a consumer styling API.
+function Control() {
+  return <button><span className="control-private-label">Label</span></button>;
+}
+
+// Pattern: rejected because it styles the component's private rendered part.
+const wrong = css`
+  & .control-private-label { color: var(--text-muted); }
+`;
+
+// Pattern: its own arrangement remains valid.
+const layout = css`
+  display: flex;
+  gap: var(--space-4);
+`;
+```
+
+The source guard matches component-emitted class names and unambiguous literal
+data markers to the selector's styled subject, including `:is()`/`:where()`.
+It also rejects reads of known private component variables. It does not treat
+an ancestor predicate or `:has()` query as styling that ancestor/descendant:
+`[data-layout="expanded"] > & { gap: var(--space-4); }` changes the pattern's
+own arrangement. Public hooks and registered non-state variables remain valid.
+Token definitions, namespaces and writes retain their existing guards.
+
+Opaque/computed imports, generated selectors, ambiguous shared markers, forwarded
+consumer classes and arbitrary service abstractions are not a complete static
+proof. Passing source checks does not prove that every visual override is safe.
+Review the real rendered states, computed styles, keyboard interactions and
+responsive layouts; use registered browser checks for promised behavior.
+
+## Refactoring an owner
+
+Move runtime source, its scenarios/fixtures and guides together; update public
+exports, dependent imports and documented scenario IDs. Keep callers on the
+same intentional public API. Navigation stays in an application callback or a
+normal link supplied by the consumer, rather than a hidden router mutation in
+the pattern. Validate the complete migration with project checks, product and
+preview builds, and behavior tests. An existing guard rejection is not permission
+to write around the guarded editing workflow.

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

@@ -86,17 +86,32 @@ For on-demand current/candidate screenshots and visual dry-run review, read
 [captures.md](references/captures.md).
 For a rejected patch, failed check or loading error, read
 [evidence and diagnosis](references/evidence.md); inspect the failing boundary
-and `ads_investigate` bundle before changing APIs or verification policy.
+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, fragment-link navigation, or `scenario-render` /
-`showcase-class` findings, read [scenario contracts](references/scenarios.md). Its verification
+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
 examples explain API visibility, reference baselines and state-transition checks.
 Traced parents can cover declared public children; verified public Linaria
 helpers do not grant custom scenario CSS.
 
 For atomic base/variant styling, helper/wrapper class composition, extracted
-custom-property arithmetic, or an
+custom-property arithmetic, typed `@property` registrations, or an
 `atomic-composition-review` / `atomic-composition-limit` advisory, read
 [atomic style composition](references/atomic-styles.md). The same guide is served
 as `ads://guides/atomic-styles`. It explains shorthand/logical conflicts and
@@ -146,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
@@ -359,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,
@@ -380,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
@@ -407,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

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.
 

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

@@ -1,4 +1,4 @@
-import { TokenPreview } from "@ds";
+import { TokenPreview } from "@ds/review";
 import { fixture } from "./Foundation.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.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/atomic-styles.md

@@ -81,6 +81,54 @@ const treatment = css`
 This is a distinct state, not two competing base atoms. Whether changing padding
 on hover is desirable remains a product decision.
 
+## Register typed custom properties without atomizing their descriptors
+
+Use a literal `@property` in its component/pattern's Linaria template when the
+browser needs a typed, interpolated runtime variable:
+
+```tsx
+const treatment = css`
+  @property --ds-example-progress {
+    syntax: "<number>";
+    inherits: false;
+    initial-value: 0;
+  }
+  opacity: var(--ds-example-progress);
+`;
+```
+
+The identifier is illustrative; use a unique name owned by the real unit.
+Registrations are document-global, even when authored beside one component.
+Put them at template level or inside conditional at-rules, never element selectors.
+Use the same ADS tag resolver described below in both product and preview builds;
+it preserves each complete registration and its conditional context instead of
+splitting syntax/inherits/initial-value into invalid atomic rules. This works for
+atomic `css` and `styled`; the browser receives CSS without a registration runtime.
+MCP delivers it inside the App document, not the outer showcase host.
+
+`property-registration` validates descriptor shape, CSS syntax/initial-value and
+ownership, and rejects conflicting schemas or registrations shared by unrelated
+owners. Identical registrations from the same owner are permitted. Runtime
+`--ds-*` / `--ux-*` variables stay with their runtime owner. A shared token's
+registration belongs beside its actual definition in a foundation value sheet;
+a namespaced owner token's registration belongs in its registered `tokens.css`.
+Neither `base.css` nor `fonts.css` becomes a registration escape hatch. Registration
+alone does not define a token or satisfy its sample/fixture coverage.
+
+Typed initial values must match their syntax and be computationally independent:
+`0px` is valid metadata; `var(--space-4)`, `1rem` and `currentColor` are not.
+The literal exemption applies only to registration descriptors. Keep design
+assignments outside them token-backed; a technical fallback is not a place to
+hide a component skin. Use literal static descriptors so guards can inspect them.
+See the [W3C registration contract](https://www.w3.org/TR/css-properties-values-api-1/#at-property-rule).
+
+Verify extracted CSS and actual interpolation, including after minification and
+inside the MCP App. A declaration can parse while a browser ignores an invalid
+registration. Keep required browser fallbacks and reduced-motion behavior; do not
+replace a valid CSS implementation with script merely to evade extraction or a
+guard limitation. These checks cover declarative registrations; arbitrary dynamic
+`CSS.registerProperty()` calls are not an ownership proof.
+
 ## Preserve custom-property arithmetic during extraction
 
 Custom properties can hold an unevaluated token stream that becomes arithmetic

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

@@ -101,7 +101,12 @@ failed/cancelled capture does not replace existing image slots or apply source.
 If a scenario/target is newly introduced, `current` is null with an explicit
 `currentAbsent` explanation; only the real candidate image exists.
 
-Review the returned images and diagnostics, fix the draft if necessary, then apply
+The edit reply is a summary. Read `ads_results({resultId,section:"captures"})` for
+the requested image resource URIs and `section:"diagnostics"` for relevant
+messages; follow `nextCursor` when needed. Read image resources explicitly.
+Standalone `ads_capture` continues returning its selected capture directly.
+
+Review those images and diagnostics, fix the draft if necessary, then apply
 with `dryRun:false`. Apply reruns all gates. An image is promoted only when the
 accepted source revision matches the captured candidate; other proposals remain
 stale. Images do not approve a patch or certify interaction/accessibility/parity.

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

@@ -20,21 +20,67 @@ A complete failed run can contain independent passing cases. Suite interruption,
 missing/skipped cases, stale inputs and an unexplained process exit cannot certify
 a pass. Keep the reported case outcome separate from whole-run acceptance.
 
+## Retrieve only the evidence needed
+
+`ads_verify`, `ads_apply_patch` and `ads_apply_transaction` reply with counts,
+bounded acceptance, at most three failure previews and `resultId`, within 4096
+UTF-8 JSON bytes. Full validation still decides acceptance. Do not repeat a suite
+merely to recover its output, or restate the complete report in conversation.
+
+Read a relevant saved section:
+
+```js
+ads_results({resultId: "<returned ID>", section: "outcomes", status: "not_passed"})
+// Continue only when needed, with the same section and status:
+ads_results({resultId: "<returned ID>", section: "outcomes", status: "not_passed", cursor: "<nextCursor>"})
+```
+
+Pages default to 10 rows, allow at most 20 and stay within 8192 JSON bytes. The
+byte cap can return fewer rows; `nextCursor` is the continuation. Other sections
+are `checks` (pipeline steps), `diagnostics`, `advisories`, `warnings`, `changes`,
+`captures`, `acceptance`, `investigation` (mutation boundary) and `selection`.
+A row marked `detailTruncated` is a preview. To read that exact record, pass its
+`recordIndex`, the same result/section, and `offset`/`chars` (maximum 2000 UTF-16
+characters); follow `nextOffset`. Do not combine ranges with a cursor/status filter.
+Read only the relevant log range. Reading pages or ranges never executes checks.
+
+`ads://project/results` lists the latest IDs. `ads://results/<resultId>` reads a
+summary; matching query parameters read pages/ranges. Only the latest verification
+and latest mutation snapshots are retained, independently, up to 8 MiB each.
+A superseded ID fails explicitly. An oversized report retains only its summary
+with a warning; disk failure retains details in server memory until shutdown.
+Neither changes actual acceptance or applied state. These are logical JSON byte
+budgets, not token estimates; compatibility text can duplicate structured JSON.
+Saved outcomes describe completion-time evidence, not current source freshness;
+compare their revisions with `ads_behaviors` before claiming a current pass.
+
+`ads_behaviors` pages owner summaries, then an exact unit's `checks`, `guarantees`,
+`subjects`, `demonstrations` or `profiles`. Use `nextCursor` and identical filters;
+changes invalidate a discovery cursor. Read a truncated contract via its
+`sourceFile` and bounded `ads_read_file`, rather than requesting everything.
+
 ## Get a compact investigation
 
-Discover exact owner/check IDs with `ads_behaviors`, then:
+Take an outcome's exact owner/check/run IDs from `ads_results`, then:
 
 ```json
-{ "unit": "components/Example", "check": "keyboard-navigation" }
+{ "unit": "components/Example", "check": "keyboard-navigation", "runId": "<outcome runId>" }
 ```
 
-Send this to `ads_investigate`. It reads the latest bundle without running code.
+Send this to `ads_investigate`. It reads a summary within 4096 JSON bytes, without
+running code. The run ID rejects evidence superseded by another execution.
+`section: "details"`, `"requests"`, `"browserErrors"` or `"artifacts"` reads separate pages
+(default 10/max 20 rows, at most 8192 JSON bytes); artifacts themselves require
+explicit resource reads. Truncated investigation records also support
+`recordIndex`/`offset`/`chars`; keep the exact `runId` to avoid mixing evidence.
+Without a check, the tool pages available investigations.
 `ads://project/investigations` lists available entries; the returned `resourceUri`
 reads the same bundle. It records:
 
 - Project versus isolated candidate, configured framework/profile and scenario.
 - Exact input revision and the preview revision actually observed by the helper.
-- Failing step/source, observed startup viewport and relevant failed requests.
+- `details.failingStep`, `details.source`, startup viewport and failure boundary.
+- Counts for separately paged relevant requests, browser errors and artifacts.
 - Available registered trace, screenshot or context artifact resource URIs.
 - Explicit `acceptance.established` and `acceptance.unverified` scope.
 
@@ -58,7 +104,8 @@ Candidate evidence never becomes passing live-source evidence. Compare the
 recorded input revision with current `ads_behaviors` evidence; a bundle describes
 its run, and does not claim current source merely because it remains available.
 For a build/architecture rejection before behavior runs, inspect the mutation
-result's `investigation` (also retained in `ads_status.mutations.lastResult`).
+saved `investigation` section via `ads_results`. Status retains the compact
+execution summary and result ID, rather than embedding complete reports.
 
 ## Preserve the design while repairing the failure