@reqvire-org/ads 0.3.11 → 0.3.12

package/dist/mcp/catalog.mjs

@@ -4,7 +4,7 @@ import ts from "typescript";
 import { isInside, sourceFiles } from "../config.mjs";
 import { projectCompilerOptions } from "../boundaries.mjs";
 import { publicApi } from "../public-api.mjs";
-import { projectGuideFiles } from "../project-documents.mjs";
+import { projectDocumentFiles } from "../project-documents.mjs";
 
 export const PROJECT_URI = "ads://project";
 export const sourceUri = (file) => `${PROJECT_URI}/files/${file.split("/").map(encodeURIComponent).join("/")}`;
@@ -21,10 +21,10 @@ export function projectDocuments(options) {
   }
   for (const directory of new Set(files.map((file) => path.dirname(file)))) docs(directory);
   docs(dsRoot);
-  for (const name of projectGuideFiles(root)) files.push(path.join(root, name));
+  for (const directory of new Set([root,dsRoot])) for (const name of projectDocumentFiles(directory)) files.push(path.join(directory, name));
   return [...new Set(files)].filter((file) => isInside(root, realpathSync(file))).sort().map((file) => {
     const relative = path.relative(root, file).replaceAll("\\", "/");
-    return { uri: sourceUri(relative), name: relative, mimeType: file.endsWith(".md") ? "text/markdown" : file.endsWith(".json") ? "application/json" : "text/plain", file };
+    return { uri: sourceUri(relative), name: relative, mimeType: /\.md$/i.test(file) ? "text/markdown" : file.endsWith(".json") ? "application/json" : "text/plain", file };
   });
 }
 

package/dist/mcp/mutations.mjs

@@ -65,7 +65,7 @@ function validateContent(change, unit) {
   if (change.content === null) return;
   const bytes = Buffer.from(change.content);
   if (bytes.length > mutationLimits.fileBytes) throw fail("mutation-content", "The patched file exceeds 16 MiB.", change.path);
-  if (textFile(change.path) && (bytes.includes(0) || !Buffer.from(bytes.toString("utf8")).equals(bytes))) throw fail("mutation-content", "Text source must contain valid UTF-8 without NUL bytes.", change.path);
+  if ((unit === "documentation" || textFile(change.path)) && (bytes.includes(0) || !Buffer.from(bytes.toString("utf8")).equals(bytes))) throw fail("mutation-content", "Text source and documentation must contain valid UTF-8 without NUL bytes.", change.path);
   if (/\.jsonc?$/.test(change.path)) {
     const content=bytes.toString("utf8");
     if (unit === "configuration" && !["package.json","ds.config.json"].includes(path.basename(change.path))) {

package/dist/mcp/server.mjs

@@ -260,9 +260,9 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
         await refresh();
         return { ...json(result), ...(!result.ok ? { isError: true } : {}) };
       } },
-      { name: "ads_units", description: "Discover editable ADS units and their files: components/patterns with colocated previews; shared controllers; composition; tokens; foundation shared files; documentation; assets/brand, assets/fonts and asset groups; configuration with ds.config.json, package/build/lint configuration and registered project guard/compiler sources. List summaries with query, or pass an exact unit ID for its manifest. Manifests include companionFiles with permitted shared-entry or owner-only style-boundary bookkeeping; preserve peer permissions and unrelated configuration. Imported peers stay separate. New owners follow the existing colocation convention.", schema: query.extend({ unit: z.string().min(1).max(256).optional() }), call: ({ unit, query: search = "", limit }) => {
+      { name: "ads_units", description: "Discover editable ADS units and their files: components/patterns with colocated previews; shared controllers; composition; tokens; foundation shared files; documentation including shared credits/license notices; assets/brand, assets/fonts and asset groups; configuration with ds.config.json, package/build/lint configuration and registered project guard/compiler sources. List summaries with query, or pass an exact unit ID for its manifest. Manifests include filePolicy for supported new documentation paths and companionFiles with permitted shared-entry or owner-only style-boundary bookkeeping; preserve peer permissions and unrelated configuration. Imported peers stay separate. New owners follow the existing colocation convention.", schema: query.extend({ unit: z.string().min(1).max(256).optional() }), call: ({ unit, query: search = "", limit }) => {
         const matches = edits.units().filter(item => unit ? item.id === unit : item.id.toLowerCase().includes(search.toLowerCase()));
-        return json({ total: matches.length, units: matches.slice(0, limit).map(item => ({ id: item.id, kind: item.kind, fileCount: item.files.length, ...(unit ? { files: item.files.slice(0, 200), filesTruncated: item.files.length > 200, ...(item.companionFiles ? { companionFiles: item.companionFiles } : {}) } : {}) })) });
+        return json({ total: matches.length, units: matches.slice(0, limit).map(item => ({ id: item.id, kind: item.kind, fileCount: item.files.length, ...(unit ? { files: item.files.slice(0, 200), filesTruncated: item.files.length > 200, ...(item.companionFiles ? { companionFiles: item.companionFiles } : {}), ...(item.filePolicy ? { filePolicy: item.filePolicy } : {}) } : {}) })) });
       } },
       { name: "ads_read_file", description: "Read a bounded range of ADS or registered configuration/extension source. Returns unit, full-file digest, startLine and nextOffset; default/max is 12000 UTF-16 characters. Binary assets return byte count/digest and no encoded content. Paths come from ads_units or discovery. Missing new paths return digest null. Read only relevant context before preparing a Git patch.", schema: z.object({ path: z.string().min(1).max(500), offset: z.number().int().min(0).default(0), limit: z.number().int().min(1).max(mutationLimits.readChars).default(mutationLimits.readChars) }).strict(), call: ({ path: file, ...range }) => json(edits.read(file, range)) },
       ...(mutations ? [{ name: "ads_prepare_patch", description: "Prepare a Git patch without a separate project mirror. Create copies only one owner plus its declared companions into a local draft; edit that directory with local file tools. Diff checks baseline/source freshness and owner paths, then writes a patchFile under .ds/patches. Discard removes the draft. Live source is never changed; ads_apply_patch still validates all gates. Remote clients can continue sending inline Git diffs instead.", schema:z.object({unit:z.string().min(1).max(256),action:z.enum(["create","diff","discard"]).default("create"),draft:z.string().max(100).optional()}).strict(), call:args=>json(prepareUnitPatch(options,args)) },

package/dist/project-documents.mjs

@@ -2,15 +2,31 @@ import { existsSync, lstatSync, readdirSync } from "node:fs";
 import path from "node:path";
 
 const rootNames = ["README.md", "ADS.md", "DS.md", "ARCHITECTURE.md", "Architecture.md", "GUIDE.md", "MCP.md", "CHANGELOG.md"];
+const noticeStem = /^(?:CREDITS|LICEN[CS]ES?|NOTICES?|COPYING|COPYRIGHT)(?:[-_][A-Za-z0-9][A-Za-z0-9._-]*)?$/i;
+const textExtension = /\.(?:md|txt)$/i;
+
+export const documentationFilePolicy = "Project guides; root CREDITS, LICENSE/LICENCE, NOTICE, COPYING and COPYRIGHT notices (optional -/_ qualifiers); licenses/ collections, also under docs/ or doc/. Notices use .md, .txt, or conventional extensionless names and valid UTF-8. The same document paths may live at the ADS root. Component-local notices remain with their owner; code, configuration, hidden and generated paths are excluded.";
+
+function noticeName(name) {
+  const extension = path.posix.extname(name);
+  return (!extension || textExtension.test(name)) && noticeStem.test(extension ? name.slice(0,-extension.length) : name);
+}
+
+function isProjectNotice(file) {
+  if (!file.includes("/")) return noticeName(file);
+  return /^(?:(?:docs|doc)\/)?licenses\/.+$/i.test(file) && (textExtension.test(file) || noticeName(path.posix.basename(file)));
+}
 
 /** Recognize documentation ownership even before a new guide exists. */
 export function isProjectDocument(file) {
-  return rootNames.includes(file) || /^(?:docs|doc)\/.+\.md$/i.test(file) && !file.split("/").some(part => part.startsWith("."));
+  if (file.includes("\\") || file.includes("\0") || file.split("/").some(part => !part || part.startsWith("."))) return false;
+  return rootNames.includes(file) || isProjectNotice(file) || /^(?:docs|doc)\/.+\.md$/i.test(file);
 }
 
-/** Shared guide discovery for MCP resources, workflow context and editable units. */
-export function projectGuideFiles(root) {
-  const files = rootNames.filter(file => existsSync(path.join(root, file)) && lstatSync(path.join(root, file)).isFile());
+/** Shared document discovery for MCP resources and editable units. */
+export function projectDocumentFiles(root) {
+  if (!existsSync(root) || !lstatSync(root).isDirectory()) return [];
+  const files = [];
   function walk(relative) {
     const directory = path.join(root, relative);
     if (!existsSync(directory) || !lstatSync(directory).isDirectory()) return;
@@ -21,7 +37,14 @@ export function projectGuideFiles(root) {
       else if (entry.isFile() && isProjectDocument(file)) files.push(file);
     }
   }
-  walk("docs");
-  walk("doc");
+  for (const entry of readdirSync(root,{withFileTypes:true})) {
+    if (entry.isFile() && isProjectDocument(entry.name)) files.push(entry.name);
+    else if (entry.isDirectory() && /^(?:docs|doc|licenses)$/i.test(entry.name)) walk(entry.name);
+  }
   return files.sort();
 }
+
+/** Provenance stays discoverable without loading notice inventories as workflow guides. */
+export function projectGuideFiles(root) {
+  return projectDocumentFiles(root).filter(file => !isProjectNotice(file));
+}

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

@@ -68,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

@@ -68,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

@@ -68,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

@@ -68,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

@@ -68,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/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

@@ -373,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,16 @@
 # 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

package/docs/MCP.md

@@ -294,10 +294,23 @@ The same discovery covers the rest of the project ADS:
 | Unit | Scope |
 |------|-------|
 | `foundation` | Shared ADS entry styles and root helpers |
-| `documentation` | ADS guides/licenses and the project's README, GUIDE, MCP, Architecture and ADS Markdown guides |
+| `documentation` | ADS/project guides, shared credits and license notices, and `licenses/` text collections |
 | `assets/brand`, `assets/fonts`, other `assets/*` groups | Original SVG, image, font and other asset files |
 | `configuration` | `ds.config.json`, package/TypeScript/bundler/lint configuration, registered ADS guard modules, compiler/check entrypoints and their static local dependencies |
 
+The `documentation` manifest includes `filePolicy` for paths that can be created
+before they exist. One documentation patch can add `CREDITS.md`,
+`licenses/example.txt` and the required README links together. Conventional root
+`LICENSE`/`LICENCE`, `NOTICE`, `COPYING`, `COPYRIGHT` and `CREDITS` notices accept
+`.md`, `.txt`, or extensionless names, with optional `-`/`_` qualifiers. Shared
+`licenses/` collections may also live under `docs/`, `doc/`, or the configured ADS
+root. Their entries use `.md`/`.txt` or conventional extensionless notice names.
+Content must be UTF-8 without NUL bytes; Git patches preserve exact text, Unicode,
+line endings and final-newline state. Code/configuration, hidden/generated paths
+and peer-owned files retain their boundaries. A component's colocated notice stays
+in that component unit. Shared notices are listed as readable MCP resources, while
+workflow guide discovery omits provenance inventories. No asset unit is needed.
+
 Configuration ownership follows the project's registrations. It does not absorb
 components merely because a guard or compiler reads them. Guard registration,
 implementation, helpers and the associated check script can change together.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reqvire-org/ads",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "type": "module",
   "description": "A design system your agent can see and shape. Your components. Your look. Your code.",
   "repository": {