@reqvire-org/ads 0.3.5 → 0.3.7

package/dist/skills/ads-designer/references/atomic-styles.md

@@ -0,0 +1,121 @@
+# Atomic style composition
+
+Use this guide when creating or migrating component/pattern styles, changing
+base/size/state combinations, or reviewing `atomic-composition-review` warnings.
+It is also available as `ads://guides/atomic-styles` through ADS MCP.
+
+## Why valid tokens can still render incorrectly
+
+Atomic Linaria extracts declarations into reusable classes. `cx` from
+`@linaria/atomic` or `@linaria/core` replaces earlier atoms with the same property
+and selector/condition key. It does not expand every CSS shorthand or resolve
+every overlap between physical and logical properties.
+
+For example, these declarations have different atomic keys:
+
+```tsx
+const base = css`
+  padding: 0;
+`;
+const small = css`
+  padding-inline: var(--space-6);
+`;
+
+cx(base, small);
+```
+
+Both classes survive. Both declarations can affect horizontal padding in a
+horizontal writing mode. In the inspected Linaria implementation, `padding` and
+`padding-inline` receive equal specificity. If a reset atom is emitted later,
+it can override the intended size. Shared atom reuse and CSS splitting can make
+this visible in a larger build even when an isolated view appears correct.
+The order of class names in HTML does not decide equal-specificity rule order.
+Valid tokens, successful extraction and a passing source check do not establish
+the intended computed value.
+
+See Linaria's [class merging implementation](https://github.com/callstack/linaria/blob/master/packages/core/src/cx.ts)
+and [property priority implementation](https://github.com/callstack/linaria/blob/master/packages/atomic/src/processors/helpers/propertyPriority.ts).
+Inspect the project's installed version when investigating its output.
+
+## Prefer matching properties across composed blocks
+
+Express the reset and overrides using the same property vocabulary:
+
+```tsx
+const base = css`
+  padding-block: 0;
+  padding-inline: 0;
+`;
+const small = css`
+  padding-inline: var(--space-6);
+`;
+const regular = css`
+  padding-block: var(--space-4);
+  padding-inline: var(--space-8);
+`;
+
+cx(base, compact ? small : regular);
+```
+
+Now each selected size replaces the corresponding base atom through `cx`.
+Review every size, including the default and icon-only variants. Changing only
+one size can leave another size mixing shorthand and logical properties.
+The names and tokens above are illustrative: use the project's real API and
+declared tokens. Preserve its intended dimensions and supported writing modes.
+
+The same reasoning applies to margin, inset, logical borders/corners, dimensions
+and overflow. For example, prefer `margin-inline: 0` plus a size's
+`margin-inline: var(...)` over combining `margin: 0` with that logical override.
+Choose consistent physical properties when the product deliberately positions
+against physical edges; logical properties are not mandatory.
+
+An intentional state override may have a different selector or condition:
+
+```tsx
+const treatment = css`
+  padding-inline: var(--space-6);
+  &:hover { padding-inline: var(--space-8); }
+`;
+```
+
+This is a distinct state, not two competing base atoms. Whether changing padding
+on hover is desirable remains a product decision.
+
+## Respond to a warning
+
+1. Follow the warning's related file/line locations and inspect the actual `cx`
+   composition. Variant lookups may contribute several possible combinations.
+2. In a current built preview, inspect computed properties and the winning CSS
+   rules. Establish whether extraction order, specificity, writing mode or an
+   intentional override explains the result.
+3. For accidental overlap, align property names/granularity across the base and
+   affected variants. Use Linaria's `cx`, preserve tokens and fix the owning
+   component/pattern. Reordering class strings does not remove overlapping keys.
+4. Verify the affected sizes/states and supported directions in the normal app
+   and preview build. Add a registered rendered check when a specific geometry
+   or computed-style guarantee matters.
+
+Increasing specificity, adding `!important`, copying styles into scenarios or
+moving component styling into `base.css` can hide the symptom while retaining
+the conflict. Prefer resolving the composition itself. If an overlap is
+intentional, document why its precedence is stable and verify the resulting
+behavior rather than changing product capabilities to silence a warning.
+
+## What ADS checks
+
+`atomic-composition-review` is a nonblocking warning, returned under `advisories`
+with `severity: "warning"`. CLI checks still exit successfully when there are no
+errors; MCP checks and mutations preserve the warning and its guidance URI.
+
+The source review examines atomic Linaria templates and statically traceable
+`cx` arguments, including aliases, local imports, nested composition, conditional
+expressions and variant-object lookups. It checks known overlaps involving box
+spacing, inset, borders/corners, dimensions, overflow, backgrounds, typography,
+motion and common layout shorthands, plus `all` resets. It compares shared selector/condition contexts; separate alternatives
+within one conditional or lookup are not assumed to apply together.
+
+This is a bounded source review, not a CSS engine or a proof of precedence. It
+does not enumerate every external class, runtime function result, selector
+interaction or overlapping media query. An empty warning list does not establish
+visual correctness. Actual failed registered browser/behavior checks remain
+blocking; potentially intentional source overlaps remain warnings.

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,14 @@ 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).
+
+For atomic base/variant styling or an `atomic-composition-review` warning, read
+[atomic style composition](references/atomic-styles.md). The same guide is served
+as `ads://guides/atomic-styles`. It explains shorthand/logical conflicts and
+matching-property fixes. Review warnings in the real `cx` composition and verify
+computed styles across affected sizes/states; retain intentional product behavior.
 
 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/atomic-styles.md

@@ -0,0 +1,121 @@
+# Atomic style composition
+
+Use this guide when creating or migrating component/pattern styles, changing
+base/size/state combinations, or reviewing `atomic-composition-review` warnings.
+It is also available as `ads://guides/atomic-styles` through ADS MCP.
+
+## Why valid tokens can still render incorrectly
+
+Atomic Linaria extracts declarations into reusable classes. `cx` from
+`@linaria/atomic` or `@linaria/core` replaces earlier atoms with the same property
+and selector/condition key. It does not expand every CSS shorthand or resolve
+every overlap between physical and logical properties.
+
+For example, these declarations have different atomic keys:
+
+```tsx
+const base = css`
+  padding: 0;
+`;
+const small = css`
+  padding-inline: var(--space-6);
+`;
+
+cx(base, small);
+```
+
+Both classes survive. Both declarations can affect horizontal padding in a
+horizontal writing mode. In the inspected Linaria implementation, `padding` and
+`padding-inline` receive equal specificity. If a reset atom is emitted later,
+it can override the intended size. Shared atom reuse and CSS splitting can make
+this visible in a larger build even when an isolated view appears correct.
+The order of class names in HTML does not decide equal-specificity rule order.
+Valid tokens, successful extraction and a passing source check do not establish
+the intended computed value.
+
+See Linaria's [class merging implementation](https://github.com/callstack/linaria/blob/master/packages/core/src/cx.ts)
+and [property priority implementation](https://github.com/callstack/linaria/blob/master/packages/atomic/src/processors/helpers/propertyPriority.ts).
+Inspect the project's installed version when investigating its output.
+
+## Prefer matching properties across composed blocks
+
+Express the reset and overrides using the same property vocabulary:
+
+```tsx
+const base = css`
+  padding-block: 0;
+  padding-inline: 0;
+`;
+const small = css`
+  padding-inline: var(--space-6);
+`;
+const regular = css`
+  padding-block: var(--space-4);
+  padding-inline: var(--space-8);
+`;
+
+cx(base, compact ? small : regular);
+```
+
+Now each selected size replaces the corresponding base atom through `cx`.
+Review every size, including the default and icon-only variants. Changing only
+one size can leave another size mixing shorthand and logical properties.
+The names and tokens above are illustrative: use the project's real API and
+declared tokens. Preserve its intended dimensions and supported writing modes.
+
+The same reasoning applies to margin, inset, logical borders/corners, dimensions
+and overflow. For example, prefer `margin-inline: 0` plus a size's
+`margin-inline: var(...)` over combining `margin: 0` with that logical override.
+Choose consistent physical properties when the product deliberately positions
+against physical edges; logical properties are not mandatory.
+
+An intentional state override may have a different selector or condition:
+
+```tsx
+const treatment = css`
+  padding-inline: var(--space-6);
+  &:hover { padding-inline: var(--space-8); }
+`;
+```
+
+This is a distinct state, not two competing base atoms. Whether changing padding
+on hover is desirable remains a product decision.
+
+## Respond to a warning
+
+1. Follow the warning's related file/line locations and inspect the actual `cx`
+   composition. Variant lookups may contribute several possible combinations.
+2. In a current built preview, inspect computed properties and the winning CSS
+   rules. Establish whether extraction order, specificity, writing mode or an
+   intentional override explains the result.
+3. For accidental overlap, align property names/granularity across the base and
+   affected variants. Use Linaria's `cx`, preserve tokens and fix the owning
+   component/pattern. Reordering class strings does not remove overlapping keys.
+4. Verify the affected sizes/states and supported directions in the normal app
+   and preview build. Add a registered rendered check when a specific geometry
+   or computed-style guarantee matters.
+
+Increasing specificity, adding `!important`, copying styles into scenarios or
+moving component styling into `base.css` can hide the symptom while retaining
+the conflict. Prefer resolving the composition itself. If an overlap is
+intentional, document why its precedence is stable and verify the resulting
+behavior rather than changing product capabilities to silence a warning.
+
+## What ADS checks
+
+`atomic-composition-review` is a nonblocking warning, returned under `advisories`
+with `severity: "warning"`. CLI checks still exit successfully when there are no
+errors; MCP checks and mutations preserve the warning and its guidance URI.
+
+The source review examines atomic Linaria templates and statically traceable
+`cx` arguments, including aliases, local imports, nested composition, conditional
+expressions and variant-object lookups. It checks known overlaps involving box
+spacing, inset, borders/corners, dimensions, overflow, backgrounds, typography,
+motion and common layout shorthands, plus `all` resets. It compares shared selector/condition contexts; separate alternatives
+within one conditional or lookup are not assumed to apply together.
+
+This is a bounded source review, not a CSS engine or a proof of precedence. It
+does not enumerate every external class, runtime function result, selector
+interaction or overlapping media query. An empty warning list does not establish
+visual correctness. Actual failed registered browser/behavior checks remain
+blocking; potentially intentional source overlaps remain warnings.

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,8 +42,16 @@ 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).
 
 
+For atomic base/variant styling or an `atomic-composition-review` warning, read
+[atomic style composition](references/atomic-styles.md). The same guide is served
+as `ads://guides/atomic-styles`. It explains shorthand/logical conflicts and
+matching-property fixes. Review warnings in the real `cx` composition and verify
+computed styles across affected sizes/states; retain intentional product behavior.
+
 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,

package/dist/skills/ads-migrate/references/atomic-styles.md

@@ -0,0 +1,121 @@
+# Atomic style composition
+
+Use this guide when creating or migrating component/pattern styles, changing
+base/size/state combinations, or reviewing `atomic-composition-review` warnings.
+It is also available as `ads://guides/atomic-styles` through ADS MCP.
+
+## Why valid tokens can still render incorrectly
+
+Atomic Linaria extracts declarations into reusable classes. `cx` from
+`@linaria/atomic` or `@linaria/core` replaces earlier atoms with the same property
+and selector/condition key. It does not expand every CSS shorthand or resolve
+every overlap between physical and logical properties.
+
+For example, these declarations have different atomic keys:
+
+```tsx
+const base = css`
+  padding: 0;
+`;
+const small = css`
+  padding-inline: var(--space-6);
+`;
+
+cx(base, small);
+```
+
+Both classes survive. Both declarations can affect horizontal padding in a
+horizontal writing mode. In the inspected Linaria implementation, `padding` and
+`padding-inline` receive equal specificity. If a reset atom is emitted later,
+it can override the intended size. Shared atom reuse and CSS splitting can make
+this visible in a larger build even when an isolated view appears correct.
+The order of class names in HTML does not decide equal-specificity rule order.
+Valid tokens, successful extraction and a passing source check do not establish
+the intended computed value.
+
+See Linaria's [class merging implementation](https://github.com/callstack/linaria/blob/master/packages/core/src/cx.ts)
+and [property priority implementation](https://github.com/callstack/linaria/blob/master/packages/atomic/src/processors/helpers/propertyPriority.ts).
+Inspect the project's installed version when investigating its output.
+
+## Prefer matching properties across composed blocks
+
+Express the reset and overrides using the same property vocabulary:
+
+```tsx
+const base = css`
+  padding-block: 0;
+  padding-inline: 0;
+`;
+const small = css`
+  padding-inline: var(--space-6);
+`;
+const regular = css`
+  padding-block: var(--space-4);
+  padding-inline: var(--space-8);
+`;
+
+cx(base, compact ? small : regular);
+```
+
+Now each selected size replaces the corresponding base atom through `cx`.
+Review every size, including the default and icon-only variants. Changing only
+one size can leave another size mixing shorthand and logical properties.
+The names and tokens above are illustrative: use the project's real API and
+declared tokens. Preserve its intended dimensions and supported writing modes.
+
+The same reasoning applies to margin, inset, logical borders/corners, dimensions
+and overflow. For example, prefer `margin-inline: 0` plus a size's
+`margin-inline: var(...)` over combining `margin: 0` with that logical override.
+Choose consistent physical properties when the product deliberately positions
+against physical edges; logical properties are not mandatory.
+
+An intentional state override may have a different selector or condition:
+
+```tsx
+const treatment = css`
+  padding-inline: var(--space-6);
+  &:hover { padding-inline: var(--space-8); }
+`;
+```
+
+This is a distinct state, not two competing base atoms. Whether changing padding
+on hover is desirable remains a product decision.
+
+## Respond to a warning
+
+1. Follow the warning's related file/line locations and inspect the actual `cx`
+   composition. Variant lookups may contribute several possible combinations.
+2. In a current built preview, inspect computed properties and the winning CSS
+   rules. Establish whether extraction order, specificity, writing mode or an
+   intentional override explains the result.
+3. For accidental overlap, align property names/granularity across the base and
+   affected variants. Use Linaria's `cx`, preserve tokens and fix the owning
+   component/pattern. Reordering class strings does not remove overlapping keys.
+4. Verify the affected sizes/states and supported directions in the normal app
+   and preview build. Add a registered rendered check when a specific geometry
+   or computed-style guarantee matters.
+
+Increasing specificity, adding `!important`, copying styles into scenarios or
+moving component styling into `base.css` can hide the symptom while retaining
+the conflict. Prefer resolving the composition itself. If an overlap is
+intentional, document why its precedence is stable and verify the resulting
+behavior rather than changing product capabilities to silence a warning.
+
+## What ADS checks
+
+`atomic-composition-review` is a nonblocking warning, returned under `advisories`
+with `severity: "warning"`. CLI checks still exit successfully when there are no
+errors; MCP checks and mutations preserve the warning and its guidance URI.
+
+The source review examines atomic Linaria templates and statically traceable
+`cx` arguments, including aliases, local imports, nested composition, conditional
+expressions and variant-object lookups. It checks known overlaps involving box
+spacing, inset, borders/corners, dimensions, overflow, backgrounds, typography,
+motion and common layout shorthands, plus `all` resets. It compares shared selector/condition contexts; separate alternatives
+within one conditional or lookup are not assumed to apply together.
+
+This is a bounded source review, not a CSS engine or a proof of precedence. It
+does not enumerate every external class, runtime function result, selector
+interaction or overlapping media query. An empty warning list does not establish
+visual correctness. Actual failed registered browser/behavior checks remain
+blocking; potentially intentional source overlaps remain warnings.

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,8 +62,16 @@ 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).
 
 
+For atomic base/variant styling or an `atomic-composition-review` warning, read
+[atomic style composition](references/atomic-styles.md). The same guide is served
+as `ads://guides/atomic-styles`. It explains shorthand/logical conflicts and
+matching-property fixes. Review warnings in the real `cx` composition and verify
+computed styles across affected sizes/states; retain intentional product behavior.
+
 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,