@reqvire-org/ads 0.3.0 → 0.3.2

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

@@ -57,9 +57,15 @@ relevant ranges with `ads_read_file` and send only a Git unified diff through
 `ads_apply_patch({ unit, patch, dryRun })`. A unit includes its own implementation,
 scenarios and fixtures; imported peers remain separate. `tokens` is the token
 foundation unit. Unit discovery and file ownership are distinct from preview IDs.
-Include only that owner's required re-exports in the public entry. Use
-`dryRun: true` to inspect validation; applying re-runs the gates. Fix rejected
-patches in their owner. Shared styles/helpers use `foundation`, root guides use
+Include only that owner's required re-exports in the public entry; preserve
+unrelated statements. Its real re-export may accompany removal of a redundant
+`export {};` placeholder; do not add empty exports. A `tokens` manifest lists the foundation
+entry in `companionFiles`: when creating/deleting a canonical token file such as
+`fonts.css`, include only its required import change there in the same patch.
+Preserve other imports/comments and the canonical order. Use `dryRun: true` to
+inspect validation; applying re-runs the gates. Fix rejected patches in their
+owner. Report unsupported coupled changes instead of bypassing a rejection with
+direct source writes. Shared styles/helpers use `foundation`, root guides use
 `documentation`, and branding/fonts use their discovered `assets/*` unit.
 Intentional configuration, rule exceptions, registered guard code and compiler
 changes use `configuration`; validate the proposed settings and keep mandatory
@@ -92,8 +98,8 @@ 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, an empty public
-barrel, empty component/pattern directories, and a project preview compiler adapter. The browser shell is supplied by ADS tooling.
+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.
 It contains no components, shell patterns, vendored fonts, or example screens.
 
 Resolve assets relative to this skill's `SKILL.md`, including after installation
@@ -299,15 +305,25 @@ entry independently and verify real behavior at narrow/wide sizes in both themes
 The older `showcase-coverage` policy separately checks application references.
 
 Token previews use that same scenario pipeline. Colocate a token scenario and
-fixture under the configured token directory. Use static metadata
-`{ title: "Typography", covers: ["TokenSamples"], tokens: fixture.tokens }` with
-literal const fixture fields; names/sample text are fixture data, values come
-from the real foundation CSS. Reuse a public project review pattern for styled
-samples. The minimal starter's foundation value scenario can have `covers: []`.
-Every declared token needs reachable scenario coverage; adding/removing a token
-requires fixture updates. Fix `token-scenario-reference`, `token-scenario-render`
-and `token-scenario-coverage` findings. Metadata and unused fixture fields do not
-count. Discover exact token IDs with `ads_scenarios({kind:"tokens"})`; mount them
+fixture under the configured token directory. Declare metadata
+`{ title: fixture.title, covers: ["TokenSamples"], samples: fixture.samples }`.
+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,
+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,
+unused fixtures and value-only lists fail the static gates. `covers: []` is invalid.
+During App rendering, the browser checks sample markers `data-ads-token` and
+`data-ads-property`, validates CSS with its own `CSS.supports`, and temporarily
+probes each token to verify that the declared sample property responds. It restores
+values immediately. Missing, hidden, invalid or hardcoded samples produce a preview
+error instead of a successful review. These browser checks apply to the mounted
+scenario/theme, not every application state or pixel-level design quality.
+Keep styles in the project renderer; do not add inline-style exemptions to scenarios.
+Fix `token-scenario-reference`, `token-scenario-render` and `token-scenario-coverage`
+findings. Metadata and unused fixture fields do not count. Discover exact token IDs with `ads_scenarios({kind:"tokens"})`; mount them
 with `ads_show_scenario({id})` or `ads_show_tokens({category:id})`. With the shared
 resource compiler, omitting category opens the first project token scenario.
 Legacy compilers retain the generic definition inspector. Use `ads_tokens` for
@@ -325,6 +341,25 @@ Use local simulated services in fixtures. Tests may import fixtures; load real
 foundation CSS rather than assigning shared token values in JavaScript. Keep
 full-app integration harnesses and workflow coverage in application test support.
 
+Foundation CSS is checked, not an escape hatch. Value sheets define shared tokens
+on the document root/themes; `fonts.css` holds font-face metadata. `base.css` has
+three closed roles: root/body typography, canvas and theme defaults; limited native
+normalization; and global focus indicators/reduced-motion rules. Every selector
+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.
+Put skin/state/animation in the Linaria owner, and scenario layout variations in
+the public review pattern's typed API. Browser review still verifies the effects.
+
+Invalid metadata and source failures keep the managed compiler alive for repairs.
+Read `ads_status.build` or `ads://project/build`, fix the owner, then wait for current
+successful output. If the builder exited, fix its command and invoke the preview
+again; ADS starts one fresh child without an MCP reconnect. Compiler-code changes
+also reload on the next preview invocation. Reconnect the client when upgrading
+the ADS server package itself. Persistent SSE/notification streams make
+`networkidle` unsuitable: wait for the App's current ready/error state instead.
+
+
 
 
 Register component/project Oxlint plugins and rules in `ds.config.json`. Use

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

@@ -40,6 +40,35 @@ Token names and prefixes are fixed by ADS architecture; foreign brand prefixes
 are rejected. Shared assignments belong in token files. Components own
 `--ds-*`, patterns `--ux-*`, and the showcase `--showcase-*`; token files cannot
 assign those local variables or override component state.
+
+Foundation roles are enforced by `foundation-role`, `foundation-selector` and
+`foundation-import`, alongside the regular token checks. Shared definitions
+belong on the document root or explicit root themes; ordinary declarations belong
+in `base.css`, and font-face descriptors in optional `fonts.css`. The entry imports
+canonical sheets; those sheets cannot import another styling layer. Component
+classes, IDs, data/ARIA hooks, contextual selectors, keyframes and scoped UI rules
+are rejected in the foundation, including nested functional selectors. Raw visual
+values and undefined token references are checked in native defaults too; literal
+font-face metadata keeps its separate asset role.
+
+`base.css` has three closed roles:
+
+- Document defaults: root/body typography, canvas colors and theme behavior,
+  global text selection and document scrollbars.
+- Native resets: permitted normalization properties and values, such as zero
+  spacing, inherited control typography, list resets and responsive replaced media.
+- Global accessibility: universal `:focus-visible` outline rules, and reduced-motion
+  overrides inside `@media (prefers-reduced-motion: reduce)`.
+
+The `foundation-role` check validates every selector branch, property and value.
+Native selectors are not a bypass: token-backed button backgrounds, flex/grid
+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
+still checks the effects and accessibility of permitted defaults.
+
 Own primitive markup, focus, hover, selected, disabled, loading, and motion in
 the primitive. Use typed props for variations. Keep reusable structure and skin
 in colocated Linaria blocks using `css` and `cx` from `@linaria/atomic`.
@@ -114,13 +143,24 @@ design-system/
 Flat owners may use `Button.scenario.tsx` and `Button.fixture.ts` instead.
 `Scenario.tsx` exports a default independently mountable view and literal metadata
 `export const scenario = { title: "Button states", covers: ["Button"] };`.
-Token entries under the configured token directory also declare `tokens`:
-`export const scenario = { title: "Typography", covers: ["TokenSamples"], tokens: fixture.tokens };`.
-Metadata may read literal const fixture fields; it cannot run expressions,
-functions, wildcard lists or token discovery. The same fixture list must be
-consumed by the default entry. `covers: []` is valid for a minimal token value
-inspection entry without public UI; styled samples use a real public review
-pattern. Names and sample text belong to the fixture, values to foundation CSS.
+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.
+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
+samples to a rendered public pattern's `samples` prop. No token-name/property mapping
+or sample values are embedded in the tool. Display values come from foundation CSS;
+probes are isolated verification inputs owned by the fixture.
+
+The renderer marks the actual styled element with `data-ads-token` and
+`data-ads-property`. In a browser, the App validates the declared property/value and
+probe using `CSS.supports`, checks the sample is rendered, then temporarily changes
+that token to its fixture probe. Its computed sample property must respond. Values
+are restored before yielding to painting; hardcoded lookalikes fail. Source gates
+prove the contract structure, not successful rendering. The browser check covers
+the mounted scenario and theme; visual quality and other states still need review.
+
 It imports real public UI through `@ds` and its local fixture. The adapter supplies
 initial state, callbacks and simulated services. The default entry needs no
 mandatory caller inputs or prior page initialization. Related parts may share a

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

@@ -1,8 +1,8 @@
 # Empty native design system
 
-This private React/TypeScript workspace contains semantic CSS tokens, an empty
-public barrel, Linaria extraction and a project preview compiler adapter. It has
-no components, patterns, icons, fonts or example screens. The minimal showcase
+This private React/TypeScript workspace contains semantic CSS tokens, a project-owned
+token review pattern, 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.
 
 Read the local [contract](ADS.md) and the
@@ -13,7 +13,7 @@ Read the local [contract](ADS.md) and the
 Copy the contents of `bootstrap-ds/`, including dotfiles, into a new project.
 The installed `ads-designer` skill contains the same files in
 `assets/bootstrap-ds/`. Set the project name in `package.json`. Use Node 22.12 or
-newer and ADS 0.3 or later for the shared-resource preview compiler.
+newer and ADS 0.3.1 or later for the shared-resource preview compiler.
 
 ```sh
 npx @reqvire-org/ads init --framework react
@@ -25,7 +25,7 @@ npm run dev:showcase
 For unreleased tooling, run init using the real local package:
 
 ```sh
-ads_tool_package="/absolute/path/to/reqvire-org-ads-0.3.0.tgz"
+ads_tool_package="/absolute/path/to/reqvire-org-ads-0.3.1.tgz"
 npx --yes --package "$ads_tool_package" ads init --framework react --tool-package "$ads_tool_package"
 npm install
 npm run build
@@ -44,7 +44,7 @@ native Preact app without a saved ADS framework, use `ads init --framework preac
 Init records that choice and generates native hook imports without migrating the
 app or rewriting its compiler. Subsequent init runs reuse the saved choice.
 Init adds missing foundation files and connects architectural checks; it does
-not configure Linaria or generate component source. Generated `.ds/` files are
+not configure Linaria or generate product component source. Generated `.ds/` files are
 ignored; original artwork and provenance belong in `assets/brand/`.
 
 ## Inspect and add UI
@@ -56,10 +56,12 @@ 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 inspect all
-starter token values. Add/remove fixture names alongside token definitions;
-`ads check` rejects missing coverage and invented names. Styled token samples
-belong to your public review patterns and mount through the same scenario pipeline.
+The existing `tokens/Foundation.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
+missing coverage and invented names; the App verifies the declared CSS bindings
+in the browser. Extend or replace the project-owned pattern as your tokens evolve.
 
 Create a component under `design-system/components/`, export it through `@ds`,
 and colocate `Scenario.tsx` plus `fixture.ts` (or `<Owner>.scenario.tsx` and

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

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

package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/patterns/token-preview/Scenario.tsx

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

package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/patterns/token-preview/TokenPreview.tsx

@@ -0,0 +1,31 @@
+import { useLayoutEffect, useRef } from "react";
+import { css, cx } from "@linaria/atomic";
+
+export interface TokenSample { token: `--${string}`; property: string; }
+export interface TokenPreviewProps { title: string; samples: readonly TokenSample[]; text: string; }
+const sampleStyle = css`
+  display: inline-block;
+  position: relative;
+  white-space: pre-line;
+  &[data-ads-property="animation-duration"] { animation-duration: var(--ux-token-preview-value); }
+  &[data-ads-property="animation-timing-function"] { animation-timing-function: var(--ux-token-preview-value); }
+  &[data-ads-property="background-color"] { background-color: var(--ux-token-preview-value); }
+  &[data-ads-property="border-radius"] { border-radius: var(--ux-token-preview-value); }
+  &[data-ads-property="box-shadow"] { box-shadow: var(--ux-token-preview-value); }
+  &[data-ads-property="color"] { color: var(--ux-token-preview-value); }
+  &[data-ads-property="font-family"] { font-family: var(--ux-token-preview-value); }
+  &[data-ads-property="font-size"] { font-size: var(--ux-token-preview-value); }
+  &[data-ads-property="font-weight"] { font-weight: var(--ux-token-preview-value); }
+  &[data-ads-property="line-height"] { line-height: var(--ux-token-preview-value); }
+  &[data-ads-property="width"] { width: var(--ux-token-preview-value); }
+  &[data-ads-property="z-index"] { z-index: var(--ux-token-preview-value); }
+`;
+function Sample({ sample, text }: { sample: TokenSample; text: string }) {
+  const ref = useRef<HTMLSpanElement>(null);
+  useLayoutEffect(() => { ref.current?.style.setProperty("--ux-token-preview-value", `var(${sample.token})`); }, [sample.token]);
+  return <span ref={ref} className={cx("ux-token-preview__sample", sampleStyle)} data-ads-token={sample.token} data-ads-property={sample.property}>{text}</span>;
+}
+/** Project-owned review UI. Values always come from the real foundation CSS. */
+export function TokenPreview({ title, samples, text }: TokenPreviewProps) {
+  return <section className="ux-token-preview"><h1>{title}</h1>{samples.map(sample => <div key={`${sample.token}:${sample.property}`} className="ux-token-preview__item"><code className="ux-token-preview__name">{sample.token}</code><Sample sample={sample} text={text}/></div>)}</section>;
+}

package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/patterns/token-preview/fixture.ts

@@ -0,0 +1,8 @@
+export const fixture = {
+  "title": "Token preview",
+  "text": "Aa",
+  samples: [
+    {"token": "--accent", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--space-4", "property": "width", "probe": "13.375px"},
+  ]
+} as const;

package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/tokens/Foundation.fixture.ts

@@ -1,47 +1,48 @@
 export const fixture = {
   "title": "Foundation",
-  "tokens": [
-    "--accent",
-    "--accent-fg",
-    "--accent-hover",
-    "--bg-canvas",
-    "--bg-hover",
-    "--bg-surface",
-    "--border-default",
-    "--border-focus",
-    "--border-w",
-    "--dur-fast",
-    "--dur-normal",
-    "--ease-standard",
-    "--focus-offset",
-    "--focus-w",
-    "--font-mono",
-    "--font-sans",
-    "--leading-normal",
-    "--leading-tight",
-    "--radius-lg",
-    "--radius-md",
-    "--radius-sm",
-    "--shadow-raised",
-    "--shadow-xs",
-    "--space-0",
-    "--space-12",
-    "--space-16",
-    "--space-2",
-    "--space-4",
-    "--space-6",
-    "--space-8",
-    "--text-base",
-    "--text-body",
-    "--text-inverse",
-    "--text-lg",
-    "--text-muted",
-    "--text-sm",
-    "--text-strong",
-    "--text-xl",
-    "--weight-medium",
-    "--weight-normal",
-    "--weight-semibold",
-    "--z-overlay"
+  "text": "Aa",
+  samples: [
+    {"token": "--accent", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--accent-fg", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--accent-hover", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--bg-canvas", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--bg-hover", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--bg-surface", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--border-default", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--border-focus", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--border-w", "property": "width", "probe": "13.375px"},
+    {"token": "--dur-fast", "property": "animation-duration", "probe": "0.375s"},
+    {"token": "--dur-normal", "property": "animation-duration", "probe": "0.375s"},
+    {"token": "--ease-standard", "property": "animation-timing-function", "probe": "cubic-bezier(.13,.27,.61,.83)"},
+    {"token": "--focus-offset", "property": "width", "probe": "13.375px"},
+    {"token": "--focus-w", "property": "width", "probe": "13.375px"},
+    {"token": "--font-mono", "property": "font-family", "probe": "monospace, serif"},
+    {"token": "--font-sans", "property": "font-family", "probe": "monospace, serif"},
+    {"token": "--leading-normal", "property": "line-height", "probe": "2.375"},
+    {"token": "--leading-tight", "property": "line-height", "probe": "2.375"},
+    {"token": "--radius-lg", "property": "border-radius", "probe": "13.375px"},
+    {"token": "--radius-md", "property": "border-radius", "probe": "13.375px"},
+    {"token": "--radius-sm", "property": "border-radius", "probe": "13.375px"},
+    {"token": "--shadow-raised", "property": "box-shadow", "probe": "1px 3px 5px rgb(31, 97, 163)"},
+    {"token": "--shadow-xs", "property": "box-shadow", "probe": "1px 3px 5px rgb(31, 97, 163)"},
+    {"token": "--space-0", "property": "width", "probe": "13.375px"},
+    {"token": "--space-12", "property": "width", "probe": "13.375px"},
+    {"token": "--space-16", "property": "width", "probe": "13.375px"},
+    {"token": "--space-2", "property": "width", "probe": "13.375px"},
+    {"token": "--space-4", "property": "width", "probe": "13.375px"},
+    {"token": "--space-6", "property": "width", "probe": "13.375px"},
+    {"token": "--space-8", "property": "width", "probe": "13.375px"},
+    {"token": "--text-base", "property": "font-size", "probe": "41.375px"},
+    {"token": "--text-body", "property": "color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--text-inverse", "property": "color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--text-lg", "property": "font-size", "probe": "41.375px"},
+    {"token": "--text-muted", "property": "color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--text-sm", "property": "font-size", "probe": "41.375px"},
+    {"token": "--text-strong", "property": "color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--text-xl", "property": "font-size", "probe": "41.375px"},
+    {"token": "--weight-medium", "property": "font-weight", "probe": "327"},
+    {"token": "--weight-normal", "property": "font-weight", "probe": "327"},
+    {"token": "--weight-semibold", "property": "font-weight", "probe": "327"},
+    {"token": "--z-overlay", "property": "z-index", "probe": "367"},
   ]
 } as const;

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

@@ -1,14 +1,4 @@
-import { useEffect, useState } from "react";
+import { TokenPreview } from "@ds";
 import { fixture } from "./Foundation.fixture";
-export const scenario = { title: fixture.title, covers: [], tokens: fixture.tokens };
-export default function Scenario() {
-  const [values, setValues] = useState<Record<string, string>>({});
-  useEffect(() => {
-    const read = () => { const style = getComputedStyle(document.documentElement); setValues(Object.fromEntries(fixture.tokens.map(name => [name, style.getPropertyValue(name).trim()]))); };
-    read();
-    const observer = new MutationObserver(read);
-    observer.observe(document.documentElement, {attributes: true, attributeFilter: ["data-theme"]});
-    return () => observer.disconnect();
-  }, []);
-  return <section><h1>{fixture.title}</h1><dl>{fixture.tokens.map(name => <div key={name}><dt><code>{name}</code></dt><dd>{values[name]}</dd></div>)}</dl></section>;
-}
+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/design-system/tokens/base.css

@@ -1,3 +1,6 @@
+:root { color-scheme: light; }
+:root[data-theme="dark"] { color-scheme: dark; }
+
 *,
 *::before,
 *::after {
@@ -5,7 +8,7 @@
 }
 
 body {
-  margin: var(--space-0);
+  margin: 0;
   background: var(--bg-canvas);
   color: var(--text-body);
   font-family: var(--font-sans);

package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/tokens/colors.css

@@ -1,5 +1,5 @@
 :root {
-  color-scheme: light;
+
   --bg-canvas: #faf9f6;
   --bg-surface: #fff;
   --bg-hover: #f1efea;
@@ -15,7 +15,7 @@
 }
 
 :root[data-theme="dark"] {
-  color-scheme: dark;
+
   --bg-canvas: #17191e;
   --bg-surface: #20232a;
   --bg-hover: #2c3039;

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

@@ -9,5 +9,15 @@
         "--watch"
       ]
     }
+  },
+  "boundaries": {
+    "styleWrites": [
+      {
+        "file": "design-system/patterns/token-preview/TokenPreview.tsx",
+        "properties": [
+          "--ux-token-preview-value"
+        ]
+      }
+    ]
   }
 }

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

@@ -55,7 +55,7 @@ If no published distribution exists, build and pack the tooling checkout with
 From inside an existing test project:
 
 ```sh
-ads_tool_package="/absolute/path/to/reqvire-org-ads-0.3.0.tgz"
+ads_tool_package="/absolute/path/to/reqvire-org-ads-0.3.2.tgz"
 npx --yes --package "$ads_tool_package" ads --help
 npx --yes --package "$ads_tool_package" ads init --framework react --tool-package "$ads_tool_package"
 npm install
@@ -93,7 +93,8 @@ component rules through the project's plugin adapter and `ds.config.json`, then
 run its actual build. Use `lint-config` directly for custom pipeline integration
 or debugging, not as a separate routine setup step.
 
-Use ADS 0.3 or later for the shared-resource preview compiler. `mcp` starts stdio
+Use ADS 0.3.2 or later for the closed foundation contract and recoverable
+shared-resource preview compiler. `mcp` starts stdio
 plus its local website; `showcase` starts the browser-only MCP runtime. Open the existing runtime URL from `ads_status` when
 connected; otherwise use `npm run dev:showcase` or the installed `ads showcase`.
 The tool client discovers entries and renders MCP Apps. Init adds the launch

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

@@ -21,9 +21,15 @@ relevant ranges with `ads_read_file` and send only a Git unified diff through
 `ads_apply_patch({ unit, patch, dryRun })`. A unit includes its own implementation,
 scenarios and fixtures; imported peers remain separate. `tokens` is the token
 foundation unit. Unit discovery and file ownership are distinct from preview IDs.
-Include only that owner's required re-exports in the public entry. Use
-`dryRun: true` to inspect validation; applying re-runs the gates. Fix rejected
-patches in their owner. Shared styles/helpers use `foundation`, root guides use
+Include only that owner's required re-exports in the public entry; preserve
+unrelated statements. Its real re-export may accompany removal of a redundant
+`export {};` placeholder; do not add empty exports. A `tokens` manifest lists the foundation
+entry in `companionFiles`: when creating/deleting a canonical token file such as
+`fonts.css`, include only its required import change there in the same patch.
+Preserve other imports/comments and the canonical order. Use `dryRun: true` to
+inspect validation; applying re-runs the gates. Fix rejected patches in their
+owner. Report unsupported coupled changes instead of bypassing a rejection with
+direct source writes. Shared styles/helpers use `foundation`, root guides use
 `documentation`, and branding/fonts use their discovered `assets/*` unit.
 Intentional configuration, rule exceptions, registered guard code and compiler
 changes use `configuration`; validate the proposed settings and keep mandatory
@@ -266,15 +272,25 @@ entry independently and verify real behavior at narrow/wide sizes in both themes
 The older `showcase-coverage` policy separately checks application references.
 
 Token previews use that same scenario pipeline. Colocate a token scenario and
-fixture under the configured token directory. Use static metadata
-`{ title: "Typography", covers: ["TokenSamples"], tokens: fixture.tokens }` with
-literal const fixture fields; names/sample text are fixture data, values come
-from the real foundation CSS. Reuse a public project review pattern for styled
-samples. The minimal starter's foundation value scenario can have `covers: []`.
-Every declared token needs reachable scenario coverage; adding/removing a token
-requires fixture updates. Fix `token-scenario-reference`, `token-scenario-render`
-and `token-scenario-coverage` findings. Metadata and unused fixture fields do not
-count. Discover exact token IDs with `ads_scenarios({kind:"tokens"})`; mount them
+fixture under the configured token directory. Declare metadata
+`{ title: fixture.title, covers: ["TokenSamples"], samples: fixture.samples }`.
+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,
+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,
+unused fixtures and value-only lists fail the static gates. `covers: []` is invalid.
+During App rendering, the browser checks sample markers `data-ads-token` and
+`data-ads-property`, validates CSS with its own `CSS.supports`, and temporarily
+probes each token to verify that the declared sample property responds. It restores
+values immediately. Missing, hidden, invalid or hardcoded samples produce a preview
+error instead of a successful review. These browser checks apply to the mounted
+scenario/theme, not every application state or pixel-level design quality.
+Keep styles in the project renderer; do not add inline-style exemptions to scenarios.
+Fix `token-scenario-reference`, `token-scenario-render` and `token-scenario-coverage`
+findings. Metadata and unused fixture fields do not count. Discover exact token IDs with `ads_scenarios({kind:"tokens"})`; mount them
 with `ads_show_scenario({id})` or `ads_show_tokens({category:id})`. With the shared
 resource compiler, omitting category opens the first project token scenario.
 Legacy compilers retain the generic definition inspector. Use `ads_tokens` for
@@ -292,6 +308,25 @@ Use local simulated services in fixtures. Tests may import fixtures; load real
 foundation CSS rather than assigning shared token values in JavaScript. Keep
 full-app integration harnesses and workflow coverage in application test support.
 
+Foundation CSS is checked, not an escape hatch. Value sheets define shared tokens
+on the document root/themes; `fonts.css` holds font-face metadata. `base.css` has
+three closed roles: root/body typography, canvas and theme defaults; limited native
+normalization; and global focus indicators/reduced-motion rules. Every selector
+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.
+Put skin/state/animation in the Linaria owner, and scenario layout variations in
+the public review pattern's typed API. Browser review still verifies the effects.
+
+Invalid metadata and source failures keep the managed compiler alive for repairs.
+Read `ads_status.build` or `ads://project/build`, fix the owner, then wait for current
+successful output. If the builder exited, fix its command and invoke the preview
+again; ADS starts one fresh child without an MCP reconnect. Compiler-code changes
+also reload on the next preview invocation. Reconnect the client when upgrading
+the ADS server package itself. Persistent SSE/notification streams make
+`networkidle` unsuitable: wait for the App's current ready/error state instead.
+
+
 
 
 Register component/project Oxlint plugins and rules in `ds.config.json`. Use

package/dist/skills/ads-import/references/cli.md

@@ -55,7 +55,7 @@ If no published distribution exists, build and pack the tooling checkout with
 From inside an existing test project:
 
 ```sh
-ads_tool_package="/absolute/path/to/reqvire-org-ads-0.3.0.tgz"
+ads_tool_package="/absolute/path/to/reqvire-org-ads-0.3.2.tgz"
 npx --yes --package "$ads_tool_package" ads --help
 npx --yes --package "$ads_tool_package" ads init --framework react --tool-package "$ads_tool_package"
 npm install
@@ -93,7 +93,8 @@ component rules through the project's plugin adapter and `ds.config.json`, then
 run its actual build. Use `lint-config` directly for custom pipeline integration
 or debugging, not as a separate routine setup step.
 
-Use ADS 0.3 or later for the shared-resource preview compiler. `mcp` starts stdio
+Use ADS 0.3.2 or later for the closed foundation contract and recoverable
+shared-resource preview compiler. `mcp` starts stdio
 plus its local website; `showcase` starts the browser-only MCP runtime. Open the existing runtime URL from `ads_status` when
 connected; otherwise use `npm run dev:showcase` or the installed `ads showcase`.
 The tool client discovers entries and renders MCP Apps. Init adds the launch