@reqvire-org/ads 0.3.3 → 0.3.6

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,25 @@ 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
+project's configured framework and declared dependencies, or plain TypeScript,
+browser APIs and local helpers. MCP hosts supply no ad hoc runtime APIs. The
+framework setting selects compilation/mounting; controller checks also validate
+imports. For controller/behavior work, read `ads://guides/behaviors` (offline:
+the installed ADS package's `docs/BEHAVIORS.md`). Discover registered guarantees
+with `ads_behaviors`; use `ads_verify` for selected real checks. Optional
+`exercises` links public behavioral APIs to scenarios; keep `covers` for rendered
+UI. Registration and demonstration are not passing evidence. `behavior.json`,
+scenarios, fixtures and checks stay out of production exports/imports. Verify
+current results, including lifecycle setup/cleanup/setup and the actual browser
+profile when promised. React StrictMode needs a development harness; wrapping a
+production widget cannot replay development effects. Keep dynamic behavior and
+capabilities intact rather than rewriting them only for static coverage.
+
 
 Check `ads_status.previewWatch` before launching another preview builder. With a
 managed watcher, edit owned sources, wait for the rebuild and invoke the preview
@@ -153,7 +172,7 @@ Do not assume it has a particular component, hook, font, or token helper.
 Record the source revision and required dependencies.
 
 Use the ADS import workflow to bring selected existing ADS items into the target,
-or assimilation to create a native component from an upstream library. Follow
+or migration to create a native component from an upstream library. Follow
 those workflows directly if the corresponding skills are unavailable: copy
 selected source and its dependency closure, or study/reproduce the upstream
 contract; integrate local ownership, exports, styles, assets, credits, applicable
@@ -364,6 +383,11 @@ Do not copy an unchecked upstream preflight or turn a component repair into a re
 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
 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
+angle units remain available for orientation, skew and spin. Put tunable visual
+angles in project tokens; static checks cannot infer that intent. Percentages,
+grid fractions and viewport/container relationships retain structural use.
 Browser review still verifies the effects.
 
 Invalid metadata and source failures keep the managed compiler alive for repairs.

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
@@ -241,3 +247,10 @@ Run `npm run build` after adding or changing components. Add meaningful tests
 for stateful behavior, accessibility, gestures, or async lifecycle where needed.
 Run `npm run dev` to inspect the real showcase. A screenshot alone does not
 verify interaction or animation. Generated output and dependencies are not source.
+
+Shared behavior may live in `controllers/<Name>/`; private controllers stay with
+their component/pattern. Use the configured framework and declared dependencies.
+Behavior contracts/checks are development-only, and scenario `exercises` links
+public hooks to demonstrations separately from rendered `covers`. Read the
+installed ADS package's `docs/BEHAVIORS.md` or MCP `ads://guides/behaviors` before
+registering guarantees, profiles and verification.

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/cli.md

@@ -102,7 +102,7 @@ script but does not install the project preview compiler. Integrate its graph
 compiler/mount adapter and configure `mcp.previewManifest` plus `mcp.previewWatch`;
 then use the same foundation and Linaria extraction as the application. Source discovery,
 selected component/pattern/style/brand imports, explicit theme-value imports, and
-assimilation are agent workflows. There is no CLI `import` command. Core checks
+migration are agent workflows. There is no CLI `import` command. Core checks
 do not copy source, import values, or establish behavior/motion parity; continue
 project type checking, meaningful tests, and browser comparisons.
 

package/dist/skills/ads-designer/references/design-craft.md

@@ -56,7 +56,7 @@ changing them to a generic default.
 
 Keep typed props, examples, state behavior, token hooks, and important tradeoffs
 in the item README. Record concrete upstream influences, authors, revision, and
-applicable notices when importing or assimilating source. Do not describe an
+applicable notices when importing or migrating source. Do not describe an
 adapted implementation as independent solely because it uses native primitives.
 
 Run the actual project's checks after changes and inspect the real consumer

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,25 @@ 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
+project's configured framework and declared dependencies, or plain TypeScript,
+browser APIs and local helpers. MCP hosts supply no ad hoc runtime APIs. The
+framework setting selects compilation/mounting; controller checks also validate
+imports. For controller/behavior work, read `ads://guides/behaviors` (offline:
+the installed ADS package's `docs/BEHAVIORS.md`). Discover registered guarantees
+with `ads_behaviors`; use `ads_verify` for selected real checks. Optional
+`exercises` links public behavioral APIs to scenarios; keep `covers` for rendered
+UI. Registration and demonstration are not passing evidence. `behavior.json`,
+scenarios, fixtures and checks stay out of production exports/imports. Verify
+current results, including lifecycle setup/cleanup/setup and the actual browser
+profile when promised. React StrictMode needs a development harness; wrapping a
+production widget cannot replay development effects. Keep dynamic behavior and
+capabilities intact rather than rewriting them only for static coverage.
+
 
 Before trusting a preview after edits, check `ads_status.build` or
 `ads://project/build`. Fix build diagnostics in owned source; an older view or
@@ -331,6 +350,11 @@ Do not copy an unchecked upstream preflight or turn a component repair into a re
 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
 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
+angle units remain available for orientation, skew and spin. Put tunable visual
+angles in project tokens; static checks cannot infer that intent. Percentages,
+grid fractions and viewport/container relationships retain structural use.
 Browser review still verifies the effects.
 
 Invalid metadata and source failures keep the managed compiler alive for repairs.

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

@@ -102,7 +102,7 @@ script but does not install the project preview compiler. Integrate its graph
 compiler/mount adapter and configure `mcp.previewManifest` plus `mcp.previewWatch`;
 then use the same foundation and Linaria extraction as the application. Source discovery,
 selected component/pattern/style/brand imports, explicit theme-value imports, and
-assimilation are agent workflows. There is no CLI `import` command. Core checks
+migration are agent workflows. There is no CLI `import` command. Core checks
 do not copy source, import values, or establish behavior/motion parity; continue
 project type checking, meaningful tests, and browser comparisons.
 

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-assimilate → ads-migrate}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: ads-assimilate
-description: "Implement or refine a native design-system component from a component-library URL, studying the original implementation and verifying behavior, visuals, and motion against the real reference. Use for component assimilation, including local documentation and justified usage lint rules; not for simply installing or wrapping a dependency."
+name: ads-migrate
+description: "Implement or refine a native design-system component from a component-library URL, studying the original implementation and verifying behavior, visuals, and motion against the real reference. Use for component migration, including local documentation and justified usage lint rules; not for simply installing or wrapping a dependency."
 ---
 
-# ADS Assimilate
+# ADS Migrate
 
 When ADS MCP is connected, discover public UI and addressable scenarios with
 `ads_status`/`ads_catalog`; use `ads_tokens` for definitions and values, and
@@ -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,25 @@ 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
+project's configured framework and declared dependencies, or plain TypeScript,
+browser APIs and local helpers. MCP hosts supply no ad hoc runtime APIs. The
+framework setting selects compilation/mounting; controller checks also validate
+imports. For controller/behavior work, read `ads://guides/behaviors` (offline:
+the installed ADS package's `docs/BEHAVIORS.md`). Discover registered guarantees
+with `ads_behaviors`; use `ads_verify` for selected real checks. Optional
+`exercises` links public behavioral APIs to scenarios; keep `covers` for rendered
+UI. Registration and demonstration are not passing evidence. `behavior.json`,
+scenarios, fixtures and checks stay out of production exports/imports. Verify
+current results, including lifecycle setup/cleanup/setup and the actual browser
+profile when promised. React StrictMode needs a development harness; wrapping a
+production widget cannot replay development effects. Keep dynamic behavior and
+capabilities intact rather than rewriting them only for static coverage.
 
 Before trusting a preview after edits, check `ads_status.build` or
 `ads://project/build`. Fix build diagnostics in owned source; an older view or
@@ -75,8 +94,8 @@ workflows. Do not look for a built-in or optional UI catalogue in the tool.
 Invocation accepts a library/repository/documentation URL as its first argument:
 
 ```text
-$ads-assimilate <library-url> [component-name] [requirements]
-$ads-assimilate https://github.com/emilkowalski/sonner toast
+$ads-migrate <library-url> [component-name] [requirements]
+$ads-migrate https://github.com/emilkowalski/sonner toast
 ```
 
 The URL is the required reference, not a request to install the library into the
@@ -147,7 +166,7 @@ the scenario; larger entries belong under `composition/`. Browsing pages only
 select these entries. The scenario labels, controls and review layouts are public ADS entities with defined
 APIs. The outer shell belongs to the tool client. Showcase/scenario files define no CSS, custom classes, or widget markup.
 Change the owning ADS pattern when a frame layout is missing; do not recreate
-the assimilated UI there or override its internals.
+the migrated UI there or override its internals.
 
 The showcase is a minimal shell plus an MCP client and Apps host, supplied by ADS
 tooling. It discovers Tokens/Components/Patterns/Composition entries through MCP
@@ -274,6 +293,11 @@ Do not copy an unchecked upstream preflight or turn a component repair into a re
 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
 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
+angle units remain available for orientation, skew and spin. Put tunable visual
+angles in project tokens; static checks cannot infer that intent. Percentages,
+grid fractions and viewport/container relationships retain structural use.
 Browser review still verifies the effects.
 
 Invalid metadata and source failures keep the managed compiler alive for repairs.

package/dist/skills/ads-migrate/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ADS Migrate"
+  short_description: "Adapt reference components into a native design system"
+  default_prompt: "Use $ads-migrate with a component-library URL to implement and verify a native design-system component."

package/dist/skills/{ads-assimilate → ads-migrate}/references/cli.md

@@ -102,7 +102,7 @@ script but does not install the project preview compiler. Integrate its graph
 compiler/mount adapter and configure `mcp.previewManifest` plus `mcp.previewWatch`;
 then use the same foundation and Linaria extraction as the application. Source discovery,
 selected component/pattern/style/brand imports, explicit theme-value imports, and
-assimilation are agent workflows. There is no CLI `import` command. Core checks
+migration are agent workflows. There is no CLI `import` command. Core checks
 do not copy source, import values, or establish behavior/motion parity; continue
 project type checking, meaningful tests, and browser comparisons.
 

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-assimilate → ads-migrate}/references/native-implementation.md

@@ -112,3 +112,14 @@ README and in a References and credits section in the component-local README.
 Link the library and the actual source/docs/articles studied, identify the
 version or commit, name the authors, and explain the concrete influences.
 Document material adaptations and agreed deviations beside the public contract.
+
+## Behavioral evidence
+
+Keep private controllers in their owner; extract a shared controller only for a
+real reuse need. Register optional behavior guarantees and real colocated checks;
+see `ads://guides/behaviors` or the installed package's `docs/BEHAVIORS.md`. Link
+public hooks with scenario `exercises`, while `covers` still requires rendered UI.
+Move reviewed scratchpad investigations into maintained owner checks. Disabling
+StrictMode can isolate an upstream lifecycle defect; keep a development StrictMode
+check and verify the native port's setup/cleanup/setup independently. Use first-
+render browser cases for lazy intrinsic sizing, retaining offscreen rendering.

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,25 @@ 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
+project's configured framework and declared dependencies, or plain TypeScript,
+browser APIs and local helpers. MCP hosts supply no ad hoc runtime APIs. The
+framework setting selects compilation/mounting; controller checks also validate
+imports. For controller/behavior work, read `ads://guides/behaviors` (offline:
+the installed ADS package's `docs/BEHAVIORS.md`). Discover registered guarantees
+with `ads_behaviors`; use `ads_verify` for selected real checks. Optional
+`exercises` links public behavioral APIs to scenarios; keep `covers` for rendered
+UI. Registration and demonstration are not passing evidence. `behavior.json`,
+scenarios, fixtures and checks stay out of production exports/imports. Verify
+current results, including lifecycle setup/cleanup/setup and the actual browser
+profile when promised. React StrictMode needs a development harness; wrapping a
+production widget cannot replay development effects. Keep dynamic behavior and
+capabilities intact rather than rewriting them only for static coverage.
 
 Before trusting a preview after edits, check `ads_status.build` or
 `ads://project/build`. Fix build diagnostics in owned source; an older view or
@@ -221,6 +240,11 @@ Do not copy an unchecked upstream preflight or turn a component repair into a re
 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
 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
+angle units remain available for orientation, skew and spin. Put tunable visual
+angles in project tokens; static checks cannot infer that intent. Percentages,
+grid fractions and viewport/container relationships retain structural use.
 Browser review still verifies the effects.
 
 Invalid metadata and source failures keep the managed compiler alive for repairs.

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."};
+}