@reqvire-org/ads 0.3.5 → 0.3.6

package/dist/skills/ads-break-ui/references/guarded-editing.md

@@ -0,0 +1,44 @@
+# Advanced guarded editing
+
+Use `ads_apply_patch` for independent owner edits. `ads_prepare_patch` can create a
+local draft of one owner and its companions; edit that directory with local file
+tools, request `action:"diff"`, then apply the returned patchFile. Discard the
+draft afterward. Remote clients can keep sending inline Git diffs. Neither draft
+preparation nor diff generation validates or changes live source.
+
+For genuinely coupled changes, `ads_apply_transaction` accepts 2–8 distinct owner
+patches (32 distinct files and 16 MiB combined). Each patch keeps its ownership and
+companion restrictions. Patches apply in order; later shared-entry hunks match the
+earlier candidate. All guards, registered checks and affected behavior checks run
+on the final candidate before live source is written. Dry-run first. Rejection,
+conflict and cancellation publish nothing. Dependency installation remains local;
+the candidate uses installed node_modules. Never bypass a rejected gate directly.
+
+A component/pattern can own constants without expanding the shared vocabulary:
+colocate `tokens.json` with `{ "schemaVersion":1, "namespace":"--<owner>-" }`
+and a definition-only `tokens.css`, imported by its runtime source. Flat owners use
+`<Owner>.tokens.json`/`<Owner>.tokens.css`. Namespaces are unique and cannot overlap
+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
+coverage. Manifests and fixtures stay out of the product bundle.
+
+`ads_prepare_token_samples({id, bindings?})` preserves existing project samples,
+removes undeclared names and returns an owner patchFile. Supply explicit
+`{token,property,probe}` bindings for new samples; unresolved tokens stay reported.
+ADS does not infer visual meaning or fabricate renderers. Apply through the guard,
+then inspect the actual App sample effects.
+
+An empty .gitkeep can be deleted alongside new source beneath it in the selected
+owner. Nonempty markers and other hidden files stay protected. A redundant
+Scenario.tsx can be deleted when real coverage remains elsewhere; removing a
+scenario does not erase ownership of the unit's runtime source.
+
+Keep contextual public parts public when they are intended consumer API. Demonstrate
+them through their actual public composition/customization path and list their real
+render references in covers. Do not count internal production renders as public API
+coverage. Behavioral APIs use exercises and registered guarantees instead.
+Scenario controls still use public UI; native link/button markup belongs in an
+owned public primitive/pattern or an owner-local test, including polymorphic/slot
+adaptation. Do not add demo-only component props or global styles for review glue.

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

@@ -26,6 +26,12 @@ The showcase keeps a notification stream open. Wait for document loading and the
 selected App's ready/error state; `networkidle` is not a readiness condition.
 For tall previews, scroll the App document to its last example and verify it is
 reachable without the host shell scrolling or clipping the preview.
+Compare references under equivalent framing. With `content-visibility`, App
+readiness can precede off-screen layout: bring measured content into view and
+wait for observable geometry to settle. Record initial placeholder behavior
+separately when relevant; a framed/top-level difference alone does not identify
+an ADS defect. Wait for actual focus/positioning readiness for keyboard checks;
+exercise rapid input as a separate case instead of adding arbitrary delays.
 Capture the fixture, viewport/container size, theme, zoom, and actions alongside
 each failure. CSS viewport emulation is useful; it is not evidence of real
 mobile keyboard, browser chrome, or assistive-technology behavior.

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

@@ -68,8 +68,8 @@ and `boundaries.styleWrites` entries together with its source. Unused permission
 fail the core checks; do not pre-register a boundary without its implementation.
 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
+owner. Use `ads_apply_transaction` for genuinely coupled owner patches;
+never bypass 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
@@ -77,6 +77,8 @@ ADS gates. For binary/large assets, generate `git diff --binary --full-index` in
 `.ds/patches/<name>.patch` and send `patchFile` instead of inline `patch`, so bytes
 stay out of model context. Binary changes require Git. When editing is disabled,
 use the client's normal source-editing tools.
+For owner drafts, token-sample reconciliation, coupled transactions and local
+constant namespaces, read [guarded-editing.md](references/guarded-editing.md).
 
 Controllers are UI behavior owners: private helpers stay with their component or
 pattern; reusable controllers use discovered `controllers/<Name>` units. Use the

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

@@ -36,8 +36,14 @@ Projects sharing this ADS use the same token names, meanings, and value types;
 their concrete values and theme overrides can differ. Reuse existing local values
 when importing components/patterns, add missing shared definitions, and import
 source token values only when adopting that theme is requested.
-Token names and prefixes are fixed by ADS architecture; foreign brand prefixes
-are rejected. Shared assignments belong in token files. Components own
+Shared token names and prefixes follow the ADS contract. A component/pattern may
+register one unique local namespace in colocated `tokens.json` and define it in
+`tokens.css`, imported by its runtime. Flat owners use `<Owner>.tokens.json` and
+`<Owner>.tokens.css`. These definition-only sheets contain root/theme custom
+properties, not UI selectors or ordinary styles. Other owners consume shared
+tokens; they cannot override or consume a peer's local namespace. A colocated
+`kind:"tokens"` scenario needs real samples for every local token. Shared
+assignments remain in the shared token files. Components own
 `--ds-*`, patterns `--ux-*`, and the showcase `--showcase-*`; token files cannot
 assign those local variables or override component state.
 
@@ -183,7 +189,7 @@ mounting, correct props, every branch/state or visual parity. The older
 
 `token-scenario-reference` rejects undeclared token names in metadata and reachable
 inputs. `token-scenario-render` rejects claimed tokens with no reachable input
-reference; `token-scenario-coverage` requires every discovered foundation token
+reference; `token-scenario-coverage` requires every discovered shared or owner-local token
 to have coverage. A new or removed token therefore needs a scenario/fixture
 update. All three are errors in `ads check`, run by `lint:ds` and the build.
 Coverage is static reachability, not proof that every branch actually renders

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

@@ -62,6 +62,10 @@ the public `TokenPreview` pattern owns their presentation and applies the real C
 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.
+`ads_prepare_token_samples` can prepare a fixture patch from explicit project
+property/probe bindings. It preserves existing samples and reports unmapped tokens;
+it does not guess how a new value should look. Component/pattern constants can use
+the colocated namespace contract in [ADS.md](ADS.md), with their own token scenario.
 
 Create a component under `design-system/components/`, export it through `@ds`,
 and colocate `Scenario.tsx` plus `fixture.ts` (or `<Owner>.scenario.tsx` and
@@ -79,6 +83,8 @@ stale retained output. Switching or rebuilding a scenario unmounts its previous
 state. `showcase/mcp/main.tsx` exports `mountScenario(Scenario, container)` and
 returns an unmount callback; it is not the shell. Keep the saved `framework`,
 compiler and mount adapter consistent.
+Managed sessions own their graph output; standalone prebuilds cannot replace it.
+Verified generated graph snapshots preserve warm-start reuse across sessions.
 
 The application and previews use the same foundation CSS and Linaria pipeline.
 The source barrel loads the foundation once. The private `build:lib` script uses
@@ -98,3 +104,7 @@ from a user-selected external repository, preserving revisions and licenses.
 inspection builds it automatically, then loads selected entries. Browser review
 still checks layout, accessibility, keyboard/focus, states, themes and motion. A clean
 build or delivered HTML alone does not establish those behaviors.
+Opt-in MCP editing uses owner Git patches. `ads_prepare_patch` creates a temporary
+owner draft/diff; `ads_apply_transaction` validates bounded coupled owner patches
+against one final candidate. Preparation changes no live source. Keep all guards
+and review the rendered result after applying.

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

@@ -0,0 +1,44 @@
+# Advanced guarded editing
+
+Use `ads_apply_patch` for independent owner edits. `ads_prepare_patch` can create a
+local draft of one owner and its companions; edit that directory with local file
+tools, request `action:"diff"`, then apply the returned patchFile. Discard the
+draft afterward. Remote clients can keep sending inline Git diffs. Neither draft
+preparation nor diff generation validates or changes live source.
+
+For genuinely coupled changes, `ads_apply_transaction` accepts 2–8 distinct owner
+patches (32 distinct files and 16 MiB combined). Each patch keeps its ownership and
+companion restrictions. Patches apply in order; later shared-entry hunks match the
+earlier candidate. All guards, registered checks and affected behavior checks run
+on the final candidate before live source is written. Dry-run first. Rejection,
+conflict and cancellation publish nothing. Dependency installation remains local;
+the candidate uses installed node_modules. Never bypass a rejected gate directly.
+
+A component/pattern can own constants without expanding the shared vocabulary:
+colocate `tokens.json` with `{ "schemaVersion":1, "namespace":"--<owner>-" }`
+and a definition-only `tokens.css`, imported by its runtime source. Flat owners use
+`<Owner>.tokens.json`/`<Owner>.tokens.css`. Namespaces are unique and cannot overlap
+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
+coverage. Manifests and fixtures stay out of the product bundle.
+
+`ads_prepare_token_samples({id, bindings?})` preserves existing project samples,
+removes undeclared names and returns an owner patchFile. Supply explicit
+`{token,property,probe}` bindings for new samples; unresolved tokens stay reported.
+ADS does not infer visual meaning or fabricate renderers. Apply through the guard,
+then inspect the actual App sample effects.
+
+An empty .gitkeep can be deleted alongside new source beneath it in the selected
+owner. Nonempty markers and other hidden files stay protected. A redundant
+Scenario.tsx can be deleted when real coverage remains elsewhere; removing a
+scenario does not erase ownership of the unit's runtime source.
+
+Keep contextual public parts public when they are intended consumer API. Demonstrate
+them through their actual public composition/customization path and list their real
+render references in covers. Do not count internal production renders as public API
+coverage. Behavioral APIs use exercises and registered guarantees instead.
+Scenario controls still use public UI; native link/button markup belongs in an
+owned public primitive/pattern or an owner-local test, including polymorphic/slot
+adaptation. Do not add demo-only component props or global styles for review glue.

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

@@ -32,8 +32,8 @@ and `boundaries.styleWrites` entries together with its source. Unused permission
 fail the core checks; do not pre-register a boundary without its implementation.
 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
+owner. Use `ads_apply_transaction` for genuinely coupled owner patches;
+never bypass 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
@@ -41,6 +41,8 @@ ADS gates. For binary/large assets, generate `git diff --binary --full-index` in
 `.ds/patches/<name>.patch` and send `patchFile` instead of inline `patch`, so bytes
 stay out of model context. Binary changes require Git. When editing is disabled,
 use the client's normal source-editing tools.
+For owner drafts, token-sample reconciliation, coupled transactions and local
+constant namespaces, read [guarded-editing.md](references/guarded-editing.md).
 
 Controllers are UI behavior owners: private helpers stay with their component or
 pattern; reusable controllers use discovered `controllers/<Name>` units. Use the

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

@@ -0,0 +1,44 @@
+# Advanced guarded editing
+
+Use `ads_apply_patch` for independent owner edits. `ads_prepare_patch` can create a
+local draft of one owner and its companions; edit that directory with local file
+tools, request `action:"diff"`, then apply the returned patchFile. Discard the
+draft afterward. Remote clients can keep sending inline Git diffs. Neither draft
+preparation nor diff generation validates or changes live source.
+
+For genuinely coupled changes, `ads_apply_transaction` accepts 2–8 distinct owner
+patches (32 distinct files and 16 MiB combined). Each patch keeps its ownership and
+companion restrictions. Patches apply in order; later shared-entry hunks match the
+earlier candidate. All guards, registered checks and affected behavior checks run
+on the final candidate before live source is written. Dry-run first. Rejection,
+conflict and cancellation publish nothing. Dependency installation remains local;
+the candidate uses installed node_modules. Never bypass a rejected gate directly.
+
+A component/pattern can own constants without expanding the shared vocabulary:
+colocate `tokens.json` with `{ "schemaVersion":1, "namespace":"--<owner>-" }`
+and a definition-only `tokens.css`, imported by its runtime source. Flat owners use
+`<Owner>.tokens.json`/`<Owner>.tokens.css`. Namespaces are unique and cannot overlap
+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
+coverage. Manifests and fixtures stay out of the product bundle.
+
+`ads_prepare_token_samples({id, bindings?})` preserves existing project samples,
+removes undeclared names and returns an owner patchFile. Supply explicit
+`{token,property,probe}` bindings for new samples; unresolved tokens stay reported.
+ADS does not infer visual meaning or fabricate renderers. Apply through the guard,
+then inspect the actual App sample effects.
+
+An empty .gitkeep can be deleted alongside new source beneath it in the selected
+owner. Nonempty markers and other hidden files stay protected. A redundant
+Scenario.tsx can be deleted when real coverage remains elsewhere; removing a
+scenario does not erase ownership of the unit's runtime source.
+
+Keep contextual public parts public when they are intended consumer API. Demonstrate
+them through their actual public composition/customization path and list their real
+render references in covers. Do not count internal production renders as public API
+coverage. Behavioral APIs use exercises and registered guarantees instead.
+Scenario controls still use public UI; native link/button markup belongs in an
+owned public primitive/pattern or an owner-local test, including polymorphic/slot
+adaptation. Do not add demo-only component props or global styles for review glue.

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

@@ -47,9 +47,11 @@ overwriting destination theme behavior during an item import.
 
 ## Explicit `tokens` mode imports values
 
-ADS token names and prefixes are fixed. New definitions must follow the existing
+Shared ADS token names and prefixes retain their semantics. Owner-local constants
+may use the registered namespace contract described in [guarded-editing.md](guarded-editing.md);
+they do not create a second shared branding vocabulary. New shared definitions follow the existing
 architecture; components use `--ds-*`, patterns `--ux-*`, and owned scenario review layouts
-`--ux-*` (`--showcase-*` is reserved, not permission for fixture CSS). Never add source-brand aliases or configurable prefix support.
+`--ux-*` (`--showcase-*` is reserved, not permission for fixture CSS). Keep shared names canonical; owner-local namespaces remain separate, explicit contracts.
 Normalize nonconforming source references to canonical ADS names during import,
 preserving destination values unless this mode explicitly requests changes.
 

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

@@ -33,8 +33,8 @@ and `boundaries.styleWrites` entries together with its source. Unused permission
 fail the core checks; do not pre-register a boundary without its implementation.
 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
+owner. Use `ads_apply_transaction` for genuinely coupled owner patches;
+never bypass 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
@@ -42,6 +42,8 @@ ADS gates. For binary/large assets, generate `git diff --binary --full-index` in
 `.ds/patches/<name>.patch` and send `patchFile` instead of inline `patch`, so bytes
 stay out of model context. Binary changes require Git. When editing is disabled,
 use the client's normal source-editing tools.
+For owner drafts, token-sample reconciliation, coupled transactions and local
+constant namespaces, read [guarded-editing.md](references/guarded-editing.md).
 
 
 Controllers are UI behavior owners: private helpers stay with their component or

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

@@ -0,0 +1,44 @@
+# Advanced guarded editing
+
+Use `ads_apply_patch` for independent owner edits. `ads_prepare_patch` can create a
+local draft of one owner and its companions; edit that directory with local file
+tools, request `action:"diff"`, then apply the returned patchFile. Discard the
+draft afterward. Remote clients can keep sending inline Git diffs. Neither draft
+preparation nor diff generation validates or changes live source.
+
+For genuinely coupled changes, `ads_apply_transaction` accepts 2–8 distinct owner
+patches (32 distinct files and 16 MiB combined). Each patch keeps its ownership and
+companion restrictions. Patches apply in order; later shared-entry hunks match the
+earlier candidate. All guards, registered checks and affected behavior checks run
+on the final candidate before live source is written. Dry-run first. Rejection,
+conflict and cancellation publish nothing. Dependency installation remains local;
+the candidate uses installed node_modules. Never bypass a rejected gate directly.
+
+A component/pattern can own constants without expanding the shared vocabulary:
+colocate `tokens.json` with `{ "schemaVersion":1, "namespace":"--<owner>-" }`
+and a definition-only `tokens.css`, imported by its runtime source. Flat owners use
+`<Owner>.tokens.json`/`<Owner>.tokens.css`. Namespaces are unique and cannot overlap
+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
+coverage. Manifests and fixtures stay out of the product bundle.
+
+`ads_prepare_token_samples({id, bindings?})` preserves existing project samples,
+removes undeclared names and returns an owner patchFile. Supply explicit
+`{token,property,probe}` bindings for new samples; unresolved tokens stay reported.
+ADS does not infer visual meaning or fabricate renderers. Apply through the guard,
+then inspect the actual App sample effects.
+
+An empty .gitkeep can be deleted alongside new source beneath it in the selected
+owner. Nonempty markers and other hidden files stay protected. A redundant
+Scenario.tsx can be deleted when real coverage remains elsewhere; removing a
+scenario does not erase ownership of the unit's runtime source.
+
+Keep contextual public parts public when they are intended consumer API. Demonstrate
+them through their actual public composition/customization path and list their real
+render references in covers. Do not count internal production renders as public API
+coverage. Behavioral APIs use exercises and registered guarantees instead.
+Scenario controls still use public UI; native link/button markup belongs in an
+owned public primitive/pattern or an owner-local test, including polymorphic/slot
+adaptation. Do not add demo-only component props or global styles for review glue.

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

@@ -53,8 +53,8 @@ and `boundaries.styleWrites` entries together with its source. Unused permission
 fail the core checks; do not pre-register a boundary without its implementation.
 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
+owner. Use `ads_apply_transaction` for genuinely coupled owner patches;
+never bypass 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
@@ -62,6 +62,8 @@ ADS gates. For binary/large assets, generate `git diff --binary --full-index` in
 `.ds/patches/<name>.patch` and send `patchFile` instead of inline `patch`, so bytes
 stay out of model context. Binary changes require Git. When editing is disabled,
 use the client's normal source-editing tools.
+For owner drafts, token-sample reconciliation, coupled transactions and local
+constant namespaces, read [guarded-editing.md](references/guarded-editing.md).
 
 
 Controllers are UI behavior owners: private helpers stay with their component or

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

@@ -0,0 +1,44 @@
+# Advanced guarded editing
+
+Use `ads_apply_patch` for independent owner edits. `ads_prepare_patch` can create a
+local draft of one owner and its companions; edit that directory with local file
+tools, request `action:"diff"`, then apply the returned patchFile. Discard the
+draft afterward. Remote clients can keep sending inline Git diffs. Neither draft
+preparation nor diff generation validates or changes live source.
+
+For genuinely coupled changes, `ads_apply_transaction` accepts 2–8 distinct owner
+patches (32 distinct files and 16 MiB combined). Each patch keeps its ownership and
+companion restrictions. Patches apply in order; later shared-entry hunks match the
+earlier candidate. All guards, registered checks and affected behavior checks run
+on the final candidate before live source is written. Dry-run first. Rejection,
+conflict and cancellation publish nothing. Dependency installation remains local;
+the candidate uses installed node_modules. Never bypass a rejected gate directly.
+
+A component/pattern can own constants without expanding the shared vocabulary:
+colocate `tokens.json` with `{ "schemaVersion":1, "namespace":"--<owner>-" }`
+and a definition-only `tokens.css`, imported by its runtime source. Flat owners use
+`<Owner>.tokens.json`/`<Owner>.tokens.css`. Namespaces are unique and cannot overlap
+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
+coverage. Manifests and fixtures stay out of the product bundle.
+
+`ads_prepare_token_samples({id, bindings?})` preserves existing project samples,
+removes undeclared names and returns an owner patchFile. Supply explicit
+`{token,property,probe}` bindings for new samples; unresolved tokens stay reported.
+ADS does not infer visual meaning or fabricate renderers. Apply through the guard,
+then inspect the actual App sample effects.
+
+An empty .gitkeep can be deleted alongside new source beneath it in the selected
+owner. Nonempty markers and other hidden files stay protected. A redundant
+Scenario.tsx can be deleted when real coverage remains elsewhere; removing a
+scenario does not erase ownership of the unit's runtime source.
+
+Keep contextual public parts public when they are intended consumer API. Demonstrate
+them through their actual public composition/customization path and list their real
+render references in covers. Do not count internal production renders as public API
+coverage. Behavioral APIs use exercises and registered guarantees instead.
+Scenario controls still use public UI; native link/button markup belongs in an
+owned public primitive/pattern or an owner-local test, including polymorphic/slot
+adaptation. Do not add demo-only component props or global styles for review glue.

package/dist/token-fixtures.mjs

@@ -0,0 +1,30 @@
+import { inspectTokens } from "./tokens.mjs";
+import { inspectScenarios, tokenSampleSource } from "./scenarios.mjs";
+import { inspectUnits } from "./units.mjs";
+import { validTokenSamples } from "./token-samples.mjs";
+import { textDiff } from "./mcp/text-diff.mjs";
+
+/** Preserve project bindings; new meanings always need project-selected inputs. */
+export function reconcileTokenSamples(options, {id, bindings = []}) {
+  if (bindings.length && !validTokenSamples(bindings)) throw new Error("Bindings need distinct {token, property, probe} CSS samples.");
+  const inventory = inspectTokens(options.root), registry = inspectScenarios(options), units = inspectUnits(options);
+  const scenario = registry.scenarios.find(entry => entry.id === id && entry.kind === "tokens");
+  if (!scenario) throw new Error("Select an exact token scenario ID from ads_scenarios.");
+  const owner = units.owner(units.relative(scenario.file));
+  const owned = new Set(inventory.tokens.filter(token => token.owner === owner).map(token => token.name));
+  if (bindings.some(sample => !owned.has(sample.token))) throw new Error("New sample bindings must name real tokens from this scenario's owner.");
+  const removed = scenario.samples.filter(sample => !owned.has(sample.token)).map(sample => sample.token);
+  const samples = new Map(scenario.samples.filter(sample => owned.has(sample.token)).map(sample => [`${sample.token}:${sample.property}`, sample]));
+  for (const sample of bindings) samples.set(`${sample.token}:${sample.property}`, sample);
+  if (!samples.size) throw new Error("A token scenario needs at least one real sample; supply a binding or remove the obsolete scenario with an owner patch.");
+  const represented = new Set(registry.scenarios.filter(entry => entry.kind === "tokens" && entry.id !== id).flatMap(entry => entry.samples.map(sample => sample.token)));
+  for (const sample of samples.values()) represented.add(sample.token);
+  const unresolved = [...owned].filter(name => !represented.has(name));
+  const source = tokenSampleSource(options,scenario);
+  const list = [...samples.values()];
+  const current = scenario.samples;
+  const next = JSON.stringify(current) === JSON.stringify(list) ? source.content : source.content.slice(0,source.start) + JSON.stringify(list,null,2) + source.content.slice(source.end);
+  return {unit:owner,id,file:source.file,sampleCount:list.length,removed,unresolved,
+    patch:textDiff(source.file,source.content,next),
+    guidance:"Bindings and probes belong to the project. No token-name/type heuristic chooses a renderer or probe. Apply the proposed owner patch through ads_apply_patch, then verify its real preview."};
+}

package/dist/tokens.mjs

@@ -6,6 +6,7 @@ import { loadConfig, sourceFiles } from "./config.mjs";
 import { foundationFiles, isSharedToken, tokenContract } from "./token-policy.mjs";
 import { dimensionValue, numericCssUnit } from "./css-values.mjs";
 import { checkComponentVariable } from "./boundaries.mjs";
+import { scopedTokens, scopedTokenOwner } from "./scoped-tokens.mjs";
 
 export { tokenContract };
 
@@ -49,7 +50,10 @@ export function inspectTokens(directory) {
   const { root, dsRoot, config } = options;
   const definitions = new Map();
   const diagnostics = [];
+  const scoped = scopedTokens(options);
+  diagnostics.push(...scoped.diagnostics);
   const files = sourceFiles(path.join(dsRoot, config.tokenDir)).filter((file) => file.endsWith(".css"));
+  files.push(...scoped.definitions.map(entry => path.join(root, entry.file)));
   files.sort((a, b) => foundationFiles.indexOf(path.basename(a)) - foundationFiles.indexOf(path.basename(b)) || a.localeCompare(b));
   for (const file of files) {
     let css;
@@ -68,6 +72,7 @@ export function inspectTokens(directory) {
         column: decl.source.start.column,
         scope: context(decl),
         value: decl.value,
+        ...(scoped.definitions.some(entry => entry.file === path.relative(root, file).replaceAll("\\", "/")) ? { owner:scoped.definitions.find(entry => entry.file === path.relative(root, file).replaceAll("\\", "/")).unit } : {}),
       };
       if (!definitions.has(decl.prop)) definitions.set(decl.prop, []);
       definitions.get(decl.prop).push(definition);
@@ -107,7 +112,8 @@ export function inspectTokens(directory) {
       }
       const resolvedReferences = new Map();
       for (const ref of references(entry.value)) {
-        if (!isSharedToken(ref.name)) report("token-name", name, entry, `${name} references ${ref.name}, which does not follow ADS's fixed token naming contract.`);
+        const local = scopedTokenOwner(options, ref.name);
+        if (local ? entry.owner !== local.unit : !isSharedToken(ref.name)) report("token-name", name, entry, `${name} references ${ref.name} outside its shared/owner token contract.`);
         if (!scope.has(ref.name) && !ref.fallback) report("token-reference", name, entry, `${name} references undefined ${ref.name}.`);
         else if (scope.has(ref.name)) resolvedReferences.set(ref.name, resolveAlias(ref.name, [...chain, name]));
       }
@@ -137,7 +143,7 @@ export function inspectTokens(directory) {
   }
   return {
     contractVersion: tokenContract.version,
-    tokens: [...definitions].sort(([a], [b]) => a.localeCompare(b)).map(([name, entries]) => ({ name, ...tokenContract.tokens[name], definitions: entries })),
+    tokens: [...definitions].sort(([a], [b]) => a.localeCompare(b)).map(([name, entries]) => ({ name, ...tokenContract.tokens[name], ...(scopedTokenOwner(options, name) ? {owner:scopedTokenOwner(options, name).unit, namespace:scopedTokenOwner(options, name).namespace} : {owner:"tokens"}), definitions: entries })),
     diagnostics,
   };
 }

package/dist/units.mjs

@@ -100,6 +100,7 @@ export function inspectUnits(options) {
   const sameName = name => name.replace(/[-_]/g, "").toLowerCase();
   const flatFamilies = new Set(files.filter(file => /\.scenario\.[cm]?[jt]sx?$/.test(file)).map(file => path.posix.dirname(file)));
   const directories = new Set(files.filter(file => /(?:^|\/)Scenario\.[cm]?[jt]sx?$/.test(file)).map(file => slash(path.dirname(file))));
+  for (const file of files.filter(file => /^(?:components|patterns)\/.+\/tokens\.json$/.test(file))) directories.add(path.posix.dirname(file));
   for (const file of files) {
     if (!/^(?:components|patterns|controllers|composition)\//.test(file) || !source.test(file)) continue;
     const directory = slash(path.dirname(file)), name = path.basename(file).replace(source, "");
@@ -145,6 +146,12 @@ export function inspectUnits(options) {
   }
   for (const unit of units.values()) if (boundaryCompanion(unit.id)) {
     (unit.companionFiles ??= []).push({ path: "ds.config.json", allowedChanges: "Only this owner's inlineStyleFiles and boundaries.styleWrites entries, together with its source change; preserve all other configuration and peer permissions." });
+    if (/^(?:components|patterns|controllers|composition)\//.test(unit.id)) {
+      for (let directory = unit.id; directory !== "."; directory = path.posix.dirname(directory)) {
+        const marker = path.join(dsRoot, directory, ".gitkeep");
+        if (existsSync(marker) && readFileSync(marker).length === 0) (unit.companionFiles ??= []).push({ path: slash(path.relative(root, marker)), allowedChanges: "Delete this empty placeholder only while adding real source in the selected owner below it." });
+      }
+    }
   }
   return { units: [...units.values()].sort((a, b) => a.id.localeCompare(b.id)), owner, publicEntry, stylesEntry, tokenDir,
     relative: file => slash(path.relative(dsRoot, path.resolve(root, file))) };
@@ -161,6 +168,14 @@ export function checkUnitFiles(options, unit, changes, inventory = inspectUnits(
   validateUnitId(unit);
   for (const change of changes) {
     const relative = inventory.relative(change.path);
+    if (path.posix.basename(relative) === ".gitkeep") {
+      const directory = path.posix.dirname(relative);
+      if (change.originalContent !== "" || change.content !== null || !/^(?:components|patterns|controllers|composition)\//.test(relative)
+        || !(unit === directory || unit.startsWith(directory + "/"))
+        || !changes.some(item => item.originalContent === null && item.content !== null && source.test(item.path)
+          && (inventory.relative(item.path).startsWith(unit + "/") || inventory.relative(item.path).startsWith(unit + ".")))) throw fail("Only delete an existing empty .gitkeep while adding source in the selected owner beneath it. Other hidden-file changes are not allowed.", change.path);
+      continue;
+    }
     if (allowNew && unit === "configuration") continue; // The candidate must register every setup/extension file.
     if (change.path === "ds.config.json" && boundaryCompanion(unit)) continue; // Validated against only this owner below.
     if (relative === inventory.publicEntry) continue;

package/dist/verification.mjs

@@ -193,7 +193,7 @@ export function createVerificationController(root) {
             if (!current) status = "stale";
             if (signal.aborted) status = "cancelled";
             results.push({ unit: check.unit, check: check.id, file: check.file, case: check.case, profile: profileName, status, current, revision: check.inputRevision, runId, completedAt: new Date().toISOString(),
-              previewRevision: profile.mode === "browser" ? readPreviewManifest(options)?.revision ?? null : null,
+              previewRevision: profile.mode === "browser" ? host?.previewRevision() ?? readPreviewManifest(options)?.revision ?? null : null,
               message: runnerError?.message ?? (!matches.length ? "The selected case did not execute/report. Missing and skipped cases do not pass." : matches.filter(item => item.status !== "passed").map(item => String(item.message ?? item.status).slice(0, 2000)).join("\n")), report: slash(path.relative(root, report)) });
           }
           if (signal.aborted) break;

package/docs/ADS.md

@@ -7,7 +7,8 @@ UX, and Skin pillars. [GUIDE.md](GUIDE.md) gives setup and configuration steps.
 ## Ownership boundary
 
 MCP source editing is opt-in through `ads mcp --mutations`. Its write operation
-accepts a Git unified diff for one ADS unit and validates its source, scenario and
+accepts a Git unified diff for one ADS unit (or bounded owner patches for coupled
+transactions) and validates its source, scenario and
 fixture changes against core checks, registered Oxlint rules and project checks
 before application. This includes
 foundation, documentation, original assets and an explicit configuration unit for
@@ -146,7 +147,7 @@ mounting, correct props, every branch/state or visual parity. The older
 
 `token-scenario-reference` rejects undeclared token names in metadata and reachable
 inputs. `token-scenario-render` rejects claimed tokens with no reachable input
-reference; `token-scenario-coverage` requires every discovered foundation token
+reference; `token-scenario-coverage` requires every discovered shared or owner-local token
 to have coverage. A new or removed token therefore needs a scenario/fixture
 update. All three are errors in `ads check`, run by `lint:ds` and the build.
 Coverage is static reachability, not proof that every branch actually renders
@@ -168,6 +169,48 @@ preview builds; review meaningful states in both themes and sizes.
 
 ## Shared token contract
 
+### Owner-local tokens
+
+Shared semantics remain in the configured token foundation. Constants specific
+to one component or pattern may live beside it:
+
+```text
+components/Notice/
+  Notice.tsx                 # imports ./tokens.css; UI styling stays in Linaria
+  tokens.json              # {"schemaVersion":1,"namespace":"--notice-"}
+  tokens.css               # :root { --notice-width: 356px; }
+  Scenario.tsx
+  fixture.ts
+  Tokens.scenario.tsx      # kind: "tokens", public review pattern + samples
+  Tokens.fixture.ts
+```
+
+Flat owners use `<Owner>.tokens.json` and `<Owner>.tokens.css`. A unit has one
+explicit namespace, unique across owners and separate from shared/runtime-variable
+prefixes. The stylesheet contains only namespaced custom-property definitions
+under root/theme conditions; imports, selectors for UI, ordinary declarations,
+font faces and animations remain outside it. Its runtime owner imports it, so
+product and preview consume the same values. Raw UI styling remains token-backed.
+
+Local token aliases may reference shared tokens or their own namespace, with
+undefined references and cycles rejected. Other owners consume shared tokens;
+they cannot redefine, write or directly consume another owner's local namespace.
+Measured runtime variables retain their existing exact `styleWrites` boundary.
+`ads_tokens` returns each token's owner, definitions and local namespace.
+
+A colocated scenario sets `kind:"tokens"` and declares real fixture `samples`
+consumed by a public review pattern. Its ID still derives from its source path.
+Every local token needs this real sample coverage, just like shared tokens.
+Definitions, metadata, fixture and token scenario belong to the same edit unit.
+Manifests/fixtures are development inputs; production includes the runtime's
+imported CSS definitions, never the preview adapter or tooling manifest.
+
+Use `ads_prepare_token_samples` to propose sample reconciliation from explicit
+project property/probe bindings. The tool preserves project sample meaning and
+reports missing mappings instead of choosing them from token prefixes.
+
+### Shared definitions
+
 Keep compatible token names, meanings, value types, and alias relationships;
 project values and theme overrides may differ. The
 [Data pillar](ARCHITECTURE.md#data-gives-implementations-a-common-language)

package/docs/ARCHITECTURE.md

@@ -205,6 +205,13 @@ scenarios unmounts the previous view while keeping unchanged dependencies cached
 Persistence is a host lifecycle choice; a new external widget loads the same
 resources independently. Resource sharing is scoped to an App instance.
 
+Managed graph builders publish into a private session directory beside the
+configured manifest. Logical scenario IDs and resource URIs stay unchanged;
+standalone builds retain the configured output and cannot overwrite a live
+session's success record. Verified compiled snapshots form a bounded shared
+warm-start cache. Source, compiler, dependency and output hashes still gate reuse.
+Ordinary shutdown removes owned session output while retaining that cache.
+
 ```mermaid
 flowchart LR
   Host[Minimal host: navigation and MCP client] --> Proxy[Separate-origin sandbox proxy]
@@ -342,6 +349,13 @@ replace the managed process while retaining the MCP connection. Normal build gat
 remain in place for source changes made through other editors; preview review remains
 necessary after either editing path.
 
+For genuinely coupled changes, a bounded transaction accepts one Git patch per
+distinct owner and validates a single complete candidate before publication.
+Each patch retains its ownership and companion rules. Local owner drafts remove
+the need for a separate project mirror; token-sample reconciliation preserves
+project bindings and reports unresolved mappings. Neither preparation changes live
+source or substitutes for guarded application and rendered review.
+
 Required shared-entry bookkeeping can accompany its owner: component/pattern
 re-exports, canonical foundation imports for token files created or deleted, and
 only that owner’s style-boundary entries in project configuration in the same
@@ -391,3 +405,10 @@ review pattern. The App then verifies rendered samples in the actual browser by
 probing those bindings and restoring them. The tool supplies no token/property
 classification or visual sample palette. A source build alone is not a rendered
 verification, and the browser check does not judge design quality.
+
+An optional owner-local token namespace keeps component/pattern constants beside
+their consumer. Its definition-only stylesheet contains root/theme custom
+properties and is imported by the runtime owner; UI styling remains in Linaria.
+Namespaces, aliases, ownership and actual colocated sample coverage are checked.
+The shared foundation remains the cross-owner vocabulary. See the
+[owner-token contract](ADS.md#owner-local-tokens).