@reqvire-org/ads 0.3.10 → 0.3.12

package/dist/skills/ads-break-ui/SKILL.md

@@ -49,10 +49,12 @@ For owner drafts, token-sample reconciliation, coupled transactions and local
 constant namespaces, read [guarded-editing.md](references/guarded-editing.md).
 
 
-For parent/child `covers`, public style-helper use in scenarios, or
-`scenario-render` / `showcase-class` findings, read
-[scenario contracts](references/scenarios.md). Traced parents can cover declared
-public children; verified public Linaria helpers do not grant custom scenario CSS.
+For parent/child `covers`, conditional-control review, reference comparisons,
+public style-helper use in scenarios, or `scenario-render` / `showcase-class`
+findings, read [scenario contracts](references/scenarios.md). Its verification
+examples explain API visibility, reference baselines and state-transition checks.
+Traced parents can cover declared public children; verified public Linaria
+helpers do not grant custom scenario CSS.
 
 For atomic base/variant styling, helper/wrapper class composition, extracted
 custom-property arithmetic, or an

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

@@ -6,6 +6,16 @@ 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.
 
+Shared provenance uses the existing `documentation` unit. Read its `filePolicy`
+from `ads_units`: one patch can create `CREDITS.md`, shared `licenses/*.txt` and
+README links together. Conventional root credits/license/notice names support
+UTF-8 `.md`/`.txt` or extensionless notices; `licenses/` may also sit under
+`docs/`, `doc/` or the ADS root. Preserve upstream notice text exactly. Keep
+component/asset-local notices with their owner; reference shared notices instead
+of duplicating them across units. Do not create an asset group or bypass a guard
+to add these documents. Code/configuration and hidden/generated paths remain
+outside documentation ownership.
+
 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

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

@@ -3,6 +3,21 @@
 Use this reference for `scenario-render`, `scenario-coverage` or `showcase-class`
 diagnostics. MCP serves the same guide as `ads://guides/scenarios`.
 
+All preview kinds open at `?scenario=<discovered-id>`. Use the returned showcase
+link instead of inferring a section from an ID's directory: an owner-local token
+scenario may live under `components/` or `patterns/`, with `kind: "tokens"`.
+Legacy `?category=` links remain aliases. The `ads_show_tokens` tool retains its
+`category` argument; both preview tools return canonical `?scenario=` links.
+
+After an edit, check the build's `current`/`stale` fields and `sourceRevision`.
+Source evidence is captured before compilation and checked against current project
+inputs; an unchanged artifact or running watcher cannot establish freshness.
+`ADS_PREVIEW_STALE_SOURCE` means the retained output awaits a current build.
+Guarded writes explicitly invalidate the compiler, and content reconciliation
+recovers missed atomic replacements. Do not touch source to force freshness;
+inspect build diagnostics. Upgrade the project's compiler dependency together
+with MCP when an older reporter lacks source evidence.
+
 ## Owner-local token previews load their own definitions
 
 Keep the registered token sheet imported by its runtime owner for product use.
@@ -53,6 +68,23 @@ just to satisfy a guard. Static evidence does not establish successful mounting,
 visibility, interaction, every state or visual parity. Verify those in the built
 App and registered browser checks.
 
+## Verification pitfalls
+
+Preserve the intended API and the reference baseline when resolving a diagnostic.
+These examples describe verification mistakes, not component-specific rules:
+
+| Situation | Do not | Do instead |
+|-----------|--------|------------|
+| A reference example sets `width: 15rem`, while the native popup uses its default width. | Remove the reference width and claim the original example now matches. | Keep the baseline intact. Reproduce demo sizing through the project's public review/layout pattern or supported style helper. If a different native size is intentional, document it. Label any additional normalized comparison separately. |
+| Static tracing cannot prove that a public clear control renders when a value is selected. | Remove its export, drop its required coverage, or change runtime behavior merely to pass the gate. | Preserve the intended public API. Try a meaningful selected-state fixture or another real scenario. If valid rendering remains untraceable, report the tooling limitation with a small reproduction. |
+| A screenshot shows the clear control in a selected state. | Treat its presence as evidence that clearing works. | Add a browser check: start selected, activate Clear, assert the value and selection are empty, verify the control's resulting visibility and documented focus behavior, then select again. |
+
+A private helper exposed through its parent's public prop can legitimately stay
+private when that is the intended API. Verify the behavior through the parent;
+do not export the helper solely for a test. Public/private ownership is a product
+decision, not a coverage workaround. Browser checks verify transitions but do not
+replace the current static `covers` requirement; `exercises` does not waive it.
+
 ## Scenarios may consume verified public style helpers
 
 A deliberately public helper can expose its owner's Linaria treatment:

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

@@ -80,10 +80,12 @@ 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 parent/child `covers`, public style-helper use in scenarios, or
-`scenario-render` / `showcase-class` findings, read
-[scenario contracts](references/scenarios.md). Traced parents can cover declared
-public children; verified public Linaria helpers do not grant custom scenario CSS.
+For parent/child `covers`, conditional-control review, reference comparisons,
+public style-helper use in scenarios, or `scenario-render` / `showcase-class`
+findings, read [scenario contracts](references/scenarios.md). Its verification
+examples explain API visibility, reference baselines and state-transition checks.
+Traced parents can cover declared public children; verified public Linaria
+helpers do not grant custom scenario CSS.
 
 For atomic base/variant styling, helper/wrapper class composition, extracted
 custom-property arithmetic, or an

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

@@ -6,6 +6,16 @@ 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.
 
+Shared provenance uses the existing `documentation` unit. Read its `filePolicy`
+from `ads_units`: one patch can create `CREDITS.md`, shared `licenses/*.txt` and
+README links together. Conventional root credits/license/notice names support
+UTF-8 `.md`/`.txt` or extensionless notices; `licenses/` may also sit under
+`docs/`, `doc/` or the ADS root. Preserve upstream notice text exactly. Keep
+component/asset-local notices with their owner; reference shared notices instead
+of duplicating them across units. Do not create an asset group or bypass a guard
+to add these documents. Code/configuration and hidden/generated paths remain
+outside documentation ownership.
+
 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

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

@@ -3,6 +3,21 @@
 Use this reference for `scenario-render`, `scenario-coverage` or `showcase-class`
 diagnostics. MCP serves the same guide as `ads://guides/scenarios`.
 
+All preview kinds open at `?scenario=<discovered-id>`. Use the returned showcase
+link instead of inferring a section from an ID's directory: an owner-local token
+scenario may live under `components/` or `patterns/`, with `kind: "tokens"`.
+Legacy `?category=` links remain aliases. The `ads_show_tokens` tool retains its
+`category` argument; both preview tools return canonical `?scenario=` links.
+
+After an edit, check the build's `current`/`stale` fields and `sourceRevision`.
+Source evidence is captured before compilation and checked against current project
+inputs; an unchanged artifact or running watcher cannot establish freshness.
+`ADS_PREVIEW_STALE_SOURCE` means the retained output awaits a current build.
+Guarded writes explicitly invalidate the compiler, and content reconciliation
+recovers missed atomic replacements. Do not touch source to force freshness;
+inspect build diagnostics. Upgrade the project's compiler dependency together
+with MCP when an older reporter lacks source evidence.
+
 ## Owner-local token previews load their own definitions
 
 Keep the registered token sheet imported by its runtime owner for product use.
@@ -53,6 +68,23 @@ just to satisfy a guard. Static evidence does not establish successful mounting,
 visibility, interaction, every state or visual parity. Verify those in the built
 App and registered browser checks.
 
+## Verification pitfalls
+
+Preserve the intended API and the reference baseline when resolving a diagnostic.
+These examples describe verification mistakes, not component-specific rules:
+
+| Situation | Do not | Do instead |
+|-----------|--------|------------|
+| A reference example sets `width: 15rem`, while the native popup uses its default width. | Remove the reference width and claim the original example now matches. | Keep the baseline intact. Reproduce demo sizing through the project's public review/layout pattern or supported style helper. If a different native size is intentional, document it. Label any additional normalized comparison separately. |
+| Static tracing cannot prove that a public clear control renders when a value is selected. | Remove its export, drop its required coverage, or change runtime behavior merely to pass the gate. | Preserve the intended public API. Try a meaningful selected-state fixture or another real scenario. If valid rendering remains untraceable, report the tooling limitation with a small reproduction. |
+| A screenshot shows the clear control in a selected state. | Treat its presence as evidence that clearing works. | Add a browser check: start selected, activate Clear, assert the value and selection are empty, verify the control's resulting visibility and documented focus behavior, then select again. |
+
+A private helper exposed through its parent's public prop can legitimately stay
+private when that is the intended API. Verify the behavior through the parent;
+do not export the helper solely for a test. Public/private ownership is a product
+decision, not a coverage workaround. Browser checks verify transitions but do not
+replace the current static `covers` requirement; `exercises` does not waive it.
+
 ## Scenarios may consume verified public style helpers
 
 A deliberately public helper can expose its owner's Linaria treatment:

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

@@ -44,10 +44,12 @@ 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 parent/child `covers`, public style-helper use in scenarios, or
-`scenario-render` / `showcase-class` findings, read
-[scenario contracts](references/scenarios.md). Traced parents can cover declared
-public children; verified public Linaria helpers do not grant custom scenario CSS.
+For parent/child `covers`, conditional-control review, reference comparisons,
+public style-helper use in scenarios, or `scenario-render` / `showcase-class`
+findings, read [scenario contracts](references/scenarios.md). Its verification
+examples explain API visibility, reference baselines and state-transition checks.
+Traced parents can cover declared public children; verified public Linaria
+helpers do not grant custom scenario CSS.
 
 For atomic base/variant styling, helper/wrapper class composition, extracted
 custom-property arithmetic, or an

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

@@ -6,6 +6,16 @@ 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.
 
+Shared provenance uses the existing `documentation` unit. Read its `filePolicy`
+from `ads_units`: one patch can create `CREDITS.md`, shared `licenses/*.txt` and
+README links together. Conventional root credits/license/notice names support
+UTF-8 `.md`/`.txt` or extensionless notices; `licenses/` may also sit under
+`docs/`, `doc/` or the ADS root. Preserve upstream notice text exactly. Keep
+component/asset-local notices with their owner; reference shared notices instead
+of duplicating them across units. Do not create an asset group or bypass a guard
+to add these documents. Code/configuration and hidden/generated paths remain
+outside documentation ownership.
+
 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

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

@@ -92,7 +92,9 @@ imports, setup/providers, and scope/mounting across routes where relevant.
 
 Compare the imported component or pattern with the actual source implementation
 at the recorded revision. Align content, configuration, themes, viewport, and
-input modality. For implementation comparisons, use matching token values when
+input modality. Preserve the original comparison baseline; see the
+[verification pitfalls](scenarios.md#verification-pitfalls) before changing
+reference sizing or API visibility to make checks pass. For implementation comparisons, use matching token values when
 possible; also verify the item under its actual destination theme. For
 stateful/motion-heavy items, check lifecycle, focus, keyboard,
 pointer and touch, natural dimensions, transitions, interruption, reduced motion,

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

@@ -3,6 +3,21 @@
 Use this reference for `scenario-render`, `scenario-coverage` or `showcase-class`
 diagnostics. MCP serves the same guide as `ads://guides/scenarios`.
 
+All preview kinds open at `?scenario=<discovered-id>`. Use the returned showcase
+link instead of inferring a section from an ID's directory: an owner-local token
+scenario may live under `components/` or `patterns/`, with `kind: "tokens"`.
+Legacy `?category=` links remain aliases. The `ads_show_tokens` tool retains its
+`category` argument; both preview tools return canonical `?scenario=` links.
+
+After an edit, check the build's `current`/`stale` fields and `sourceRevision`.
+Source evidence is captured before compilation and checked against current project
+inputs; an unchanged artifact or running watcher cannot establish freshness.
+`ADS_PREVIEW_STALE_SOURCE` means the retained output awaits a current build.
+Guarded writes explicitly invalidate the compiler, and content reconciliation
+recovers missed atomic replacements. Do not touch source to force freshness;
+inspect build diagnostics. Upgrade the project's compiler dependency together
+with MCP when an older reporter lacks source evidence.
+
 ## Owner-local token previews load their own definitions
 
 Keep the registered token sheet imported by its runtime owner for product use.
@@ -53,6 +68,23 @@ just to satisfy a guard. Static evidence does not establish successful mounting,
 visibility, interaction, every state or visual parity. Verify those in the built
 App and registered browser checks.
 
+## Verification pitfalls
+
+Preserve the intended API and the reference baseline when resolving a diagnostic.
+These examples describe verification mistakes, not component-specific rules:
+
+| Situation | Do not | Do instead |
+|-----------|--------|------------|
+| A reference example sets `width: 15rem`, while the native popup uses its default width. | Remove the reference width and claim the original example now matches. | Keep the baseline intact. Reproduce demo sizing through the project's public review/layout pattern or supported style helper. If a different native size is intentional, document it. Label any additional normalized comparison separately. |
+| Static tracing cannot prove that a public clear control renders when a value is selected. | Remove its export, drop its required coverage, or change runtime behavior merely to pass the gate. | Preserve the intended public API. Try a meaningful selected-state fixture or another real scenario. If valid rendering remains untraceable, report the tooling limitation with a small reproduction. |
+| A screenshot shows the clear control in a selected state. | Treat its presence as evidence that clearing works. | Add a browser check: start selected, activate Clear, assert the value and selection are empty, verify the control's resulting visibility and documented focus behavior, then select again. |
+
+A private helper exposed through its parent's public prop can legitimately stay
+private when that is the intended API. Verify the behavior through the parent;
+do not export the helper solely for a test. Public/private ownership is a product
+decision, not a coverage workaround. Browser checks verify transitions but do not
+replace the current static `covers` requirement; `exercises` does not waive it.
+
 ## Scenarios may consume verified public style helpers
 
 A deliberately public helper can expose its owner's Linaria treatment:

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

@@ -46,10 +46,12 @@ For owner drafts, token-sample reconciliation, coupled transactions and local
 constant namespaces, read [guarded-editing.md](references/guarded-editing.md).
 
 
-For parent/child `covers`, public style-helper use in scenarios, or
-`scenario-render` / `showcase-class` findings, read
-[scenario contracts](references/scenarios.md). Traced parents can cover declared
-public children; verified public Linaria helpers do not grant custom scenario CSS.
+For parent/child `covers`, conditional-control review, reference comparisons,
+public style-helper use in scenarios, or `scenario-render` / `showcase-class`
+findings, read [scenario contracts](references/scenarios.md). Its verification
+examples explain API visibility, reference baselines and state-transition checks.
+Traced parents can cover declared public children; verified public Linaria
+helpers do not grant custom scenario CSS.
 
 For atomic base/variant styling, helper/wrapper class composition, extracted
 custom-property arithmetic, or an

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

@@ -6,6 +6,16 @@ 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.
 
+Shared provenance uses the existing `documentation` unit. Read its `filePolicy`
+from `ads_units`: one patch can create `CREDITS.md`, shared `licenses/*.txt` and
+README links together. Conventional root credits/license/notice names support
+UTF-8 `.md`/`.txt` or extensionless notices; `licenses/` may also sit under
+`docs/`, `doc/` or the ADS root. Preserve upstream notice text exactly. Keep
+component/asset-local notices with their owner; reference shared notices instead
+of duplicating them across units. Do not create an asset group or bypass a guard
+to add these documents. Code/configuration and hidden/generated paths remain
+outside documentation ownership.
+
 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

package/dist/skills/ads-migrate/references/scenarios.md

@@ -3,6 +3,21 @@
 Use this reference for `scenario-render`, `scenario-coverage` or `showcase-class`
 diagnostics. MCP serves the same guide as `ads://guides/scenarios`.
 
+All preview kinds open at `?scenario=<discovered-id>`. Use the returned showcase
+link instead of inferring a section from an ID's directory: an owner-local token
+scenario may live under `components/` or `patterns/`, with `kind: "tokens"`.
+Legacy `?category=` links remain aliases. The `ads_show_tokens` tool retains its
+`category` argument; both preview tools return canonical `?scenario=` links.
+
+After an edit, check the build's `current`/`stale` fields and `sourceRevision`.
+Source evidence is captured before compilation and checked against current project
+inputs; an unchanged artifact or running watcher cannot establish freshness.
+`ADS_PREVIEW_STALE_SOURCE` means the retained output awaits a current build.
+Guarded writes explicitly invalidate the compiler, and content reconciliation
+recovers missed atomic replacements. Do not touch source to force freshness;
+inspect build diagnostics. Upgrade the project's compiler dependency together
+with MCP when an older reporter lacks source evidence.
+
 ## Owner-local token previews load their own definitions
 
 Keep the registered token sheet imported by its runtime owner for product use.
@@ -53,6 +68,23 @@ just to satisfy a guard. Static evidence does not establish successful mounting,
 visibility, interaction, every state or visual parity. Verify those in the built
 App and registered browser checks.
 
+## Verification pitfalls
+
+Preserve the intended API and the reference baseline when resolving a diagnostic.
+These examples describe verification mistakes, not component-specific rules:
+
+| Situation | Do not | Do instead |
+|-----------|--------|------------|
+| A reference example sets `width: 15rem`, while the native popup uses its default width. | Remove the reference width and claim the original example now matches. | Keep the baseline intact. Reproduce demo sizing through the project's public review/layout pattern or supported style helper. If a different native size is intentional, document it. Label any additional normalized comparison separately. |
+| Static tracing cannot prove that a public clear control renders when a value is selected. | Remove its export, drop its required coverage, or change runtime behavior merely to pass the gate. | Preserve the intended public API. Try a meaningful selected-state fixture or another real scenario. If valid rendering remains untraceable, report the tooling limitation with a small reproduction. |
+| A screenshot shows the clear control in a selected state. | Treat its presence as evidence that clearing works. | Add a browser check: start selected, activate Clear, assert the value and selection are empty, verify the control's resulting visibility and documented focus behavior, then select again. |
+
+A private helper exposed through its parent's public prop can legitimately stay
+private when that is the intended API. Verify the behavior through the parent;
+do not export the helper solely for a test. Public/private ownership is a product
+decision, not a coverage workaround. Browser checks verify transitions but do not
+replace the current static `covers` requirement; `exercises` does not waive it.
+
 ## Scenarios may consume verified public style helpers
 
 A deliberately public helper can expose its owner's Linaria treatment:

package/dist/skills/ads-migrate/references/testing.md

@@ -8,6 +8,11 @@ the baseline. The page frame may use native controls, but those controls must
 trigger the original component and store. Two pages importing the native component
 cannot establish upstream parity.
 
+Keep example-level sizing and configuration intact too. Changing a reference to
+match the native result weakens the comparison even when its component CSS is
+untouched. Use the [verification pitfalls](scenarios.md#verification-pitfalls)
+for concrete baseline, API-visibility and conditional-control examples.
+
 Use identical messages, options, counts, async delays/outcomes, action payloads,
 and viewport/input settings. Align configuration explicitly rather than relying
 on two different defaults. Compare brand/token differences separately from UX

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

@@ -66,10 +66,12 @@ For owner drafts, token-sample reconciliation, coupled transactions and local
 constant namespaces, read [guarded-editing.md](references/guarded-editing.md).
 
 
-For parent/child `covers`, public style-helper use in scenarios, or
-`scenario-render` / `showcase-class` findings, read
-[scenario contracts](references/scenarios.md). Traced parents can cover declared
-public children; verified public Linaria helpers do not grant custom scenario CSS.
+For parent/child `covers`, conditional-control review, reference comparisons,
+public style-helper use in scenarios, or `scenario-render` / `showcase-class`
+findings, read [scenario contracts](references/scenarios.md). Its verification
+examples explain API visibility, reference baselines and state-transition checks.
+Traced parents can cover declared public children; verified public Linaria
+helpers do not grant custom scenario CSS.
 
 For atomic base/variant styling, helper/wrapper class composition, extracted
 custom-property arithmetic, or an

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

@@ -6,6 +6,16 @@ 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.
 
+Shared provenance uses the existing `documentation` unit. Read its `filePolicy`
+from `ads_units`: one patch can create `CREDITS.md`, shared `licenses/*.txt` and
+README links together. Conventional root credits/license/notice names support
+UTF-8 `.md`/`.txt` or extensionless notices; `licenses/` may also sit under
+`docs/`, `doc/` or the ADS root. Preserve upstream notice text exactly. Keep
+component/asset-local notices with their owner; reference shared notices instead
+of duplicating them across units. Do not create an asset group or bypass a guard
+to add these documents. Code/configuration and hidden/generated paths remain
+outside documentation ownership.
+
 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

package/dist/skills/ads-motion/references/scenarios.md

@@ -3,6 +3,21 @@
 Use this reference for `scenario-render`, `scenario-coverage` or `showcase-class`
 diagnostics. MCP serves the same guide as `ads://guides/scenarios`.
 
+All preview kinds open at `?scenario=<discovered-id>`. Use the returned showcase
+link instead of inferring a section from an ID's directory: an owner-local token
+scenario may live under `components/` or `patterns/`, with `kind: "tokens"`.
+Legacy `?category=` links remain aliases. The `ads_show_tokens` tool retains its
+`category` argument; both preview tools return canonical `?scenario=` links.
+
+After an edit, check the build's `current`/`stale` fields and `sourceRevision`.
+Source evidence is captured before compilation and checked against current project
+inputs; an unchanged artifact or running watcher cannot establish freshness.
+`ADS_PREVIEW_STALE_SOURCE` means the retained output awaits a current build.
+Guarded writes explicitly invalidate the compiler, and content reconciliation
+recovers missed atomic replacements. Do not touch source to force freshness;
+inspect build diagnostics. Upgrade the project's compiler dependency together
+with MCP when an older reporter lacks source evidence.
+
 ## Owner-local token previews load their own definitions
 
 Keep the registered token sheet imported by its runtime owner for product use.
@@ -53,6 +68,23 @@ just to satisfy a guard. Static evidence does not establish successful mounting,
 visibility, interaction, every state or visual parity. Verify those in the built
 App and registered browser checks.
 
+## Verification pitfalls
+
+Preserve the intended API and the reference baseline when resolving a diagnostic.
+These examples describe verification mistakes, not component-specific rules:
+
+| Situation | Do not | Do instead |
+|-----------|--------|------------|
+| A reference example sets `width: 15rem`, while the native popup uses its default width. | Remove the reference width and claim the original example now matches. | Keep the baseline intact. Reproduce demo sizing through the project's public review/layout pattern or supported style helper. If a different native size is intentional, document it. Label any additional normalized comparison separately. |
+| Static tracing cannot prove that a public clear control renders when a value is selected. | Remove its export, drop its required coverage, or change runtime behavior merely to pass the gate. | Preserve the intended public API. Try a meaningful selected-state fixture or another real scenario. If valid rendering remains untraceable, report the tooling limitation with a small reproduction. |
+| A screenshot shows the clear control in a selected state. | Treat its presence as evidence that clearing works. | Add a browser check: start selected, activate Clear, assert the value and selection are empty, verify the control's resulting visibility and documented focus behavior, then select again. |
+
+A private helper exposed through its parent's public prop can legitimately stay
+private when that is the intended API. Verify the behavior through the parent;
+do not export the helper solely for a test. Public/private ownership is a product
+decision, not a coverage workaround. Browser checks verify transitions but do not
+replace the current static `covers` requirement; `exercises` does not waive it.
+
 ## Scenarios may consume verified public style helpers
 
 A deliberately public helper can expose its owner's Linaria treatment:

package/dist/units.mjs

@@ -4,7 +4,7 @@ import ts from "typescript";
 import postcss from "postcss";
 import { isDevelopmentFile, isInside } from "./config.mjs";
 import { importResolver } from "./boundaries.mjs";
-import { isProjectDocument, projectGuideFiles } from "./project-documents.mjs";
+import { documentationFilePolicy, isProjectDocument, projectDocumentFiles } from "./project-documents.mjs";
 import { foundationFiles, foundationImportTarget } from "./token-policy.mjs";
 
 const source = /\.[cm]?[jt]sx?$/;
@@ -119,13 +119,13 @@ export function inspectUnits(options) {
   function owner(relative) {
     const projectFile = slash(path.relative(root, path.resolve(dsRoot, relative)));
     if (setup.has(projectFile)) return "configuration";
-    if (isProjectDocument(projectFile)) return "documentation";
-    if (!isInside(dsRoot, path.resolve(dsRoot, relative))) return null;
+    if (!isInside(dsRoot, path.resolve(dsRoot, relative))) return isProjectDocument(projectFile) ? "documentation" : null;
     if (relative === publicEntry) return null; // Controlled re-export bookkeeping.
     if (relative.startsWith(tokenDir + "/")) return "tokens";
     if (relative.startsWith("assets/")) return relative.split("/").length > 2 ? relative.split("/").slice(0, 2).join("/") : "assets";
+    if (isProjectDocument(relative)) return "documentation";
     if (!relative.includes("/")) return /(?:\.(?:md|txt)$|^LICENSE$)/i.test(relative) ? "documentation" : "foundation";
-    if (!/^(?:components|patterns|controllers|composition)\//.test(relative)) return relative.split("/")[0];
+    if (!/^(?:components|patterns|controllers|composition)\//.test(relative)) return relative.split("/")[0] === "documentation" ? null : relative.split("/")[0];
     for (const directory of directoryUnits) if (relative.startsWith(directory + "/")) return directory;
     for (const unit of flatUnits) if (relative.startsWith(unit + "/") || relative.startsWith(unit + ".")) return unit;
     const base = path.basename(relative).split(".")[0];
@@ -136,7 +136,8 @@ export function inspectUnits(options) {
   for (const id of ["foundation", "documentation", "tokens", "assets/brand", "assets/fonts"]) units.set(id, { id, kind: id.split("/")[0], files: [] });
   units.get("tokens").companionFiles = [{ path: slash(path.relative(root, path.join(dsRoot, stylesEntry))),
     allowedChanges: "Only add/remove canonical foundation imports required by token foundation files created/deleted in this patch; preserve other imports and comments." }];
-  units.get("documentation").files = projectGuideFiles(root);
+  units.get("documentation").files = projectDocumentFiles(root).filter(file => owner(slash(path.relative(dsRoot,path.resolve(root,file)))) === "documentation");
+  units.get("documentation").filePolicy = documentationFilePolicy;
   for (const relative of files) {
     const id = owner(relative);
     if (!id) continue;
@@ -182,7 +183,7 @@ export function checkUnitFiles(options, unit, changes, inventory = inspectUnits(
     if (unit === "tokens" && relative === inventory.stylesEntry) continue; // Controlled foundation import bookkeeping.
     if (allowNew && change.originalContent === null && (relative.startsWith(unit + "/") || relative.startsWith(unit + "."))) continue;
     const owner = inventory.owner(relative);
-    if (owner !== unit) throw fail(`This patch targets ${unit}; ${change.path} belongs to ${owner ?? "a different ADS layer"}. Submit a separate unit patch.`, change.path);
+    if (owner !== unit) throw fail(`This patch targets ${unit}; ${change.path} belongs to ${owner ?? "a different ADS layer"}. Submit a separate unit patch.${unit === "documentation" ? ` ${documentationFilePolicy}` : ""}`, change.path);
   }
   return inventory;
 }

package/dist/verification.mjs

@@ -171,8 +171,8 @@ export function createVerificationController(root) {
             const { startAdsMcp } = await import("./mcp/server.mjs");
             host ??= await startAdsMcp(root, { stdio: false, showcase: true });
             for (const check of group.filter(check => check.scenario)) {
-              const url = new URL(host.url), scenario = context.scenarios.find(entry => entry.id === check.scenario);
-              url.searchParams.set(scenario?.kind === "tokens" ? "category" : "scenario", check.scenario);
+              const url = new URL(host.url);
+              url.searchParams.set("scenario", check.scenario);
               scenarios[check.scenario] = url.href;
             }
           }

package/docs/ADS.md

@@ -333,6 +333,10 @@ in each item's local README. Record source repository/file links, revision,
 authors, concrete influences, and integration differences. Preserve applicable
 license notices for copied/adapted source and assets. The project guide records
 local implementation choices and links to the local item guides.
+Shared `CREDITS.md`, conventional root notices and text files in `licenses/` use
+the `documentation` mutation unit; its `filePolicy` describes supported new paths.
+They can be added with README links in one guarded patch, without duplicating a
+shared license into every component. Colocated notices retain their owning unit.
 
 ## Build contract
 

package/docs/ARCHITECTURE.md

@@ -288,7 +288,10 @@ Reassembling a second screen from shared primitives still allows design drift.
 The server discovers one path-derived scenario registry. The showcase's four
 sections—Tokens, Components, Patterns and Composition—browse that same registry
 through MCP results. They do not initialize the entry or define
-its UI. The host supplies theme and available space; the public implementation
+its UI. Every preview uses `?scenario=<id>`; discovered `kind` selects its section,
+including token scenarios colocated with component/pattern owners. Existing
+`?category=` links remain compatibility aliases. The host supplies theme and
+available space; the public implementation
 supplies presentation. Several related public parts may share a scenario with
 their required parent. Every declared token and every public renderable component
 and pattern needs addressable coverage. Token references must exist in the real
@@ -304,8 +307,12 @@ The skill-local [scenario guide](../skills/ads-designer/references/scenarios.md)
 explains evidence, limits and diagnostics.
 
 After source changes, validation and compilation must both succeed before a new
-graph becomes current. MCP announces build/resource updates. The built-in client
-refreshes discovery and sends the current selection to the existing App, whose
+graph becomes current. MCP announces build/resource updates.
+Build success records the project input digest captured before compilation;
+status reads independently verify that digest and the output bytes. Guarded
+publication invalidates the compiler explicitly. Content reconciliation recovers
+missed atomic file replacements, so OS watch delivery cannot establish freshness.
+The built-in client refreshes discovery and sends the current selection to the existing App, whose
 loader mounts the new module graph. Failed builds retain the previous view with
 visible stale diagnostics. Invalid scenario metadata at startup and later source
 failures stay in the watcher's recoverable diagnostic path. Fixing source triggers validation again.
@@ -366,7 +373,11 @@ the isolated candidate project. Passing checks describe
 their registered assertions, not every natural-language claim. This keeps edits
 focused without requiring entire file bodies in model context. Peer units and
 unrelated owners remain outside the selected unit's edit boundary. Shared foundation,
-branding and guides have their own units. Project configuration, registered guards
+branding and guides have their own units. Shared credits and text license notices
+belong to the documentation unit, including conventional root notices and shared
+`licenses/` collections. Colocated notices remain with their component or asset
+owner. Documentation paths and UTF-8 validation do not grant code/configuration
+ownership. Project configuration, registered guards
 and compiler integration form an explicit configuration unit; their proposed
 settings pass the same mandatory validation. Binary assets can travel as Git patch
 artifacts without entering model context, and compiler configuration changes

package/docs/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.3.12
+
+- Let the documentation unit create shared credits, conventional root license
+  notices and text `licenses/` collections in one guarded owner patch. Expose its
+  new-file policy, discover readable provenance resources without enlarging
+  workflow guide context, preserve verbatim UTF-8 notices and keep code/peer/path
+  boundaries. Verify drafts, dry runs, publication, reads and rejection atomically.
+- Add generic skill examples for preserving reference baselines and intended
+  public APIs while resolving coverage diagnostics; verify conditional controls
+  through browser state transitions instead of screenshots alone.
+
+## 0.3.11
+
+- Bind preview success to project input content as well as artifact bytes. Source
+  edits immediately mark older output stale, including edits missed by OS watches
+  and changes made during a build; reject reports without source evidence.
+- Recover missed atomic replacements with one-second input reconciliation and
+  explicitly invalidate the live compiler after accepted single/coupled edits.
+  Retain the same process and verify repeated replacements with generic fixtures.
+- Use canonical `?scenario=<id>` links for every preview kind and select the
+  showcase section from discovered metadata. Preserve legacy `?category=` links
+  as aliases, unify MCP preview and browser-check links, and cover all kinds,
+  owner-local tokens, navigation and reloads in a real sandboxed-App regression.
+
 ## 0.3.10
 
 - Attach registered owner-local token sheets to independently compiled token