@reqvire-org/ads 0.3.16 → 0.3.18

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

@@ -101,7 +101,12 @@ failed/cancelled capture does not replace existing image slots or apply source.
 If a scenario/target is newly introduced, `current` is null with an explicit
 `currentAbsent` explanation; only the real candidate image exists.
 
-Review the returned images and diagnostics, fix the draft if necessary, then apply
+The edit reply is a summary. Read `ads_results({resultId,section:"captures"})` for
+the requested image resource URIs and `section:"diagnostics"` for relevant
+messages; follow `nextCursor` when needed. Read image resources explicitly.
+Standalone `ads_capture` continues returning its selected capture directly.
+
+Review those images and diagnostics, fix the draft if necessary, then apply
 with `dryRun:false`. Apply reruns all gates. An image is promoted only when the
 accepted source revision matches the captured candidate; other proposals remain
 stale. Images do not approve a patch or certify interaction/accessibility/parity.

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

@@ -0,0 +1,120 @@
+# Investigate the failing boundary
+
+Use this reference after a rejected patch, failed check or preview loading error.
+MCP serves it as `ads://guides/evidence`. Inspect the compact result first; fetch
+only the failing check's bundle or relevant artifact, rather than repeating a suite.
+
+## Read the result correctly
+
+`failure.category` identifies a boundary, not an inferred root cause:
+
+| Category | Established observation | Next inspection |
+|----------|-------------------------|-----------------|
+| `architecture` | A source/ownership/configuration gate rejected the candidate. | Exact rule, source location and `certainty`. An inconclusive ownership proof does not establish that a valid API is wrong. |
+| `build` | A registered project pipeline step or compiled-resource integrity check failed. | Named command/phase, exit code, bounded output and build revision. A custom project script may contain several kinds of checks. |
+| `transport` | An MCP/browser resource delivery boundary failed. | Resource URI, relevant failed startup requests and observed browser errors. Do not infer a network-interface or component cause without evidence. |
+| `runner` | The harness, process, readiness or reporting boundary failed, or a test threw without assertion evidence. | Active/pending checks, timeout, failing step and artifacts. `certainty: "unclassified"` means ADS cannot establish the cause. |
+| `assertion` | A reported assertion step or token binding check failed. | Expected behavior, source location, state and trace. This can still be a test defect; compare the intended contract before editing the component. |
+
+A complete failed run can contain independent passing cases. Suite interruption,
+missing/skipped cases, stale inputs and an unexplained process exit cannot certify
+a pass. Keep the reported case outcome separate from whole-run acceptance.
+
+## Retrieve only the evidence needed
+
+`ads_verify`, `ads_apply_patch` and `ads_apply_transaction` reply with counts,
+bounded acceptance, at most three failure previews and `resultId`, within 4096
+UTF-8 JSON bytes. Full validation still decides acceptance. Do not repeat a suite
+merely to recover its output, or restate the complete report in conversation.
+
+Read a relevant saved section:
+
+```js
+ads_results({resultId: "<returned ID>", section: "outcomes", status: "not_passed"})
+// Continue only when needed, with the same section and status:
+ads_results({resultId: "<returned ID>", section: "outcomes", status: "not_passed", cursor: "<nextCursor>"})
+```
+
+Pages default to 10 rows, allow at most 20 and stay within 8192 JSON bytes. The
+byte cap can return fewer rows; `nextCursor` is the continuation. Other sections
+are `checks` (pipeline steps), `diagnostics`, `advisories`, `warnings`, `changes`,
+`captures`, `acceptance`, `investigation` (mutation boundary) and `selection`.
+A row marked `detailTruncated` is a preview. To read that exact record, pass its
+`recordIndex`, the same result/section, and `offset`/`chars` (maximum 2000 UTF-16
+characters); follow `nextOffset`. Do not combine ranges with a cursor/status filter.
+Read only the relevant log range. Reading pages or ranges never executes checks.
+
+`ads://project/results` lists the latest IDs. `ads://results/<resultId>` reads a
+summary; matching query parameters read pages/ranges. Only the latest verification
+and latest mutation snapshots are retained, independently, up to 8 MiB each.
+A superseded ID fails explicitly. An oversized report retains only its summary
+with a warning; disk failure retains details in server memory until shutdown.
+Neither changes actual acceptance or applied state. These are logical JSON byte
+budgets, not token estimates; compatibility text can duplicate structured JSON.
+Saved outcomes describe completion-time evidence, not current source freshness;
+compare their revisions with `ads_behaviors` before claiming a current pass.
+
+`ads_behaviors` pages owner summaries, then an exact unit's `checks`, `guarantees`,
+`subjects`, `demonstrations` or `profiles`. Use `nextCursor` and identical filters;
+changes invalidate a discovery cursor. Read a truncated contract via its
+`sourceFile` and bounded `ads_read_file`, rather than requesting everything.
+
+## Get a compact investigation
+
+Take an outcome's exact owner/check/run IDs from `ads_results`, then:
+
+```json
+{ "unit": "components/Example", "check": "keyboard-navigation", "runId": "<outcome runId>" }
+```
+
+Send this to `ads_investigate`. It reads a summary within 4096 JSON bytes, without
+running code. The run ID rejects evidence superseded by another execution.
+`section: "details"`, `"requests"`, `"browserErrors"` or `"artifacts"` reads separate pages
+(default 10/max 20 rows, at most 8192 JSON bytes); artifacts themselves require
+explicit resource reads. Truncated investigation records also support
+`recordIndex`/`offset`/`chars`; keep the exact `runId` to avoid mixing evidence.
+Without a check, the tool pages available investigations.
+`ads://project/investigations` lists available entries; the returned `resourceUri`
+reads the same bundle. It records:
+
+- Project versus isolated candidate, configured framework/profile and scenario.
+- Exact input revision and the preview revision actually observed by the helper.
+- `details.failingStep`, `details.source`, startup viewport and failure boundary.
+- Counts for separately paged relevant requests, browser errors and artifacts.
+- Available registered trace, screenshot or context artifact resource URIs.
+- Explicit `acceptance.established` and `acceptance.unverified` scope.
+
+Absent observations are `null` or empty; ADS does not invent a viewport, trace or
+source line. Viewport evidence is labeled `preview-startup`; a test that resizes
+later must collect its own failure-state evidence. Failed-request collection
+covers managed startup, not a complete network trace. Bodies and headers are not
+collected. Project-configured Playwright trace/screenshot policy controls which
+artifacts exist; ADS does not turn on expensive recording or rerun a failed case.
+Protocol runners may provide structured failure/step/location/artifact fields;
+older reports remain valid and their unclassified errors stay explicit.
+
+Only the latest bundle per registered check is exposed, including dry runs.
+Another verification replaces it and removes old artifacts from resource access;
+old runner output directories follow project cleanup policy. Artifact resources
+are restricted to registered ordinary files under that run's output directory,
+bounded to 20 MiB each and checked against their recorded digest on read.
+Metadata is bounded to 2 MiB. Removed registrations are pruned on verification.
+
+Candidate evidence never becomes passing live-source evidence. Compare the
+recorded input revision with current `ads_behaviors` evidence; a bundle describes
+its run, and does not claim current source merely because it remains available.
+For a build/architecture rejection before behavior runs, inspect the mutation
+saved `investigation` section via `ads_results`. Status retains the compact
+execution summary and result ID, rather than embedding complete reports.
+
+## Preserve the design while repairing the failure
+
+Fix the owner of the demonstrated defect. Do not privatize a valid API, introduce
+demo-only props, substitute a styled link, change the reference baseline or weaken
+verification policy to pass a tooling limitation. Preserve the draft and report
+the smallest source/browser reproduction when ownership remains unprovable.
+
+`acceptance` states what that result established. Core checks establish source
+guard acceptance; registered tests establish only their actual cases/profiles.
+Neither establishes untested states, visual parity, an accessibility audit or
+another MCP host's compatibility. Captures show an appearance, not a transition.

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

@@ -15,8 +15,10 @@ ads_apply_patch({"unit":"components/Example","patchFile":"<returned patchFile>",
 
 The dry run validates the full candidate, including affected registered behavior
 checks in an isolated project copy. Configured browser checks use that candidate's
-managed preview, not the live showcase. Inspect the returned `behavior` failures
-or the registered behavior-check results in `checks`, fix the draft and diff again.
+managed preview, not the live showcase. Read the summary, then page failing
+`outcomes`, `diagnostics` or pipeline `checks` through `ads_results` with its
+`resultId`. Inspect one exact outcome with `ads_investigate({unit,check,runId})`;
+fix the draft and diff again. See [evidence.md](evidence.md) for page/range limits.
 Keep behavior.json/specs with their owner and use registered checks; a scratchpad
 run against live source cannot verify unapplied changes. After validation, apply
 with `dryRun:false`; ADS revalidates before writing. Dry-run evidence is not saved
@@ -120,9 +122,10 @@ them through their actual public composition/customization path and list their r
 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. A native link/button can supply semantics
-as the single direct child of a public runtime slot when source tracing proves
-that owner clones the child with its props. An `asChild` flag alone is insufficient;
-standalone native controls and custom scenario styling remain rejected. See
+through a public runtime slot that demonstrably clones its child with owned
+props, or through matching runtime-owned selectors attached to the actual rendered
+DOM. Source ownership must be proven; an `asChild` flag or a lookalike marker is
+insufficient. Standalone controls and custom scenario styling remain rejected. See
 [scenarios.md](scenarios.md) for evidence and limits. Preserve the intended
 composition instead of substituting an unrelated styled control or adding a
 demo-only component prop. Review framing belongs in public layout patterns.

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

@@ -101,6 +101,38 @@ do not export the helper solely for a test. Public/private ownership is a produc
 decision, not a coverage workaround. Browser checks verify transitions but do not
 replace the current static `covers` requirement; `exercises` does not waive it.
 
+## Native semantics through runtime-owned selectors
+
+An anchor or other native semantic element can also occupy a position styled by
+public runtime UI, without cloning or an `asChild` API:
+
+```tsx
+// Runtime owner: the class is attached to Line's actual rendered span.
+const line = css`:is(a, button) > & { color: var(--text-body); }`;
+export function Line(props) { return <span className={line} {...props} />; }
+
+// Scenario: semantics belong to the consumer, appearance to the runtime owner.
+<a href={fixture.destination}><Line>{fixture.label}</Line></a>
+```
+
+ADS traces the actual returned DOM, the attached Linaria template and matching
+selector relationships. A public parent's `& > a` is evidence too. A tag-agnostic
+parent selector such as `& > :has(> [data-part="line"])` must match a marker
+declared by the actual runtime-owned child; a scenario-authored lookalike does not
+qualify. No component names or marker spellings are reserved.
+
+Unused styles, unrelated CSS, broad `& > *` selectors, negative selectors alone,
+fabricated markers, unknown render alternatives and opaque class replacement
+cannot grant permission. A selector cannot establish a scenario-built custom
+widget's keyboard behavior. Inline styles and arbitrary classes remain rejected;
+existing source-verified public class helpers keep their own contract.
+
+Do not add a public link part or change the DOM to satisfy a cloning-only model.
+Preserve semantic attributes and the intended public API. Unsupported source
+grammar produces an inconclusive ownership diagnostic, not proof of a bad API.
+Browser verification must establish the real focus treatment, hover/state
+precedence, navigation and other promised behavior in the compiled App iframe.
+
 ## Native semantics through a public runtime slot
 
 A native element can be the direct child of a public runtime component that

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

@@ -48,16 +48,21 @@ For owner drafts, token-sample reconciliation, coupled transactions and local
 constant namespaces, read [guarded-editing.md](references/guarded-editing.md).
 For on-demand current/candidate screenshots and visual dry-run review, read
 [captures.md](references/captures.md).
+For a rejected patch, failed check or loading error, read
+[evidence and diagnosis](references/evidence.md); inspect the failing boundary
+then page needed `ads_results` sections using the returned result ID. Inspect
+one `ads_investigate({unit,check,runId})` summary before changing APIs or policy;
+load request/error/artifact details only when relevant.
 
 For parent/child `covers`, conditional-control review, reference comparisons,
-public style-helper use, fragment-link navigation, or `scenario-render` /
-`showcase-class` findings, read [scenario contracts](references/scenarios.md). Its verification
+public style-helper use, native slot/selector composition, fragment navigation,
+or `scenario-render` / `showcase-control` / `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
+custom-property arithmetic, typed `@property` registrations, or an
 `atomic-composition-review` / `atomic-composition-limit` advisory, read
 [atomic style composition](references/atomic-styles.md). The same guide is served
 as `ads://guides/atomic-styles`. It explains shorthand/logical conflicts and

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

@@ -81,6 +81,54 @@ const treatment = css`
 This is a distinct state, not two competing base atoms. Whether changing padding
 on hover is desirable remains a product decision.
 
+## Register typed custom properties without atomizing their descriptors
+
+Use a literal `@property` in its component/pattern's Linaria template when the
+browser needs a typed, interpolated runtime variable:
+
+```tsx
+const treatment = css`
+  @property --ds-example-progress {
+    syntax: "<number>";
+    inherits: false;
+    initial-value: 0;
+  }
+  opacity: var(--ds-example-progress);
+`;
+```
+
+The identifier is illustrative; use a unique name owned by the real unit.
+Registrations are document-global, even when authored beside one component.
+Put them at template level or inside conditional at-rules, never element selectors.
+Use the same ADS tag resolver described below in both product and preview builds;
+it preserves each complete registration and its conditional context instead of
+splitting syntax/inherits/initial-value into invalid atomic rules. This works for
+atomic `css` and `styled`; the browser receives CSS without a registration runtime.
+MCP delivers it inside the App document, not the outer showcase host.
+
+`property-registration` validates descriptor shape, CSS syntax/initial-value and
+ownership, and rejects conflicting schemas or registrations shared by unrelated
+owners. Identical registrations from the same owner are permitted. Runtime
+`--ds-*` / `--ux-*` variables stay with their runtime owner. A shared token's
+registration belongs beside its actual definition in a foundation value sheet;
+a namespaced owner token's registration belongs in its registered `tokens.css`.
+Neither `base.css` nor `fonts.css` becomes a registration escape hatch. Registration
+alone does not define a token or satisfy its sample/fixture coverage.
+
+Typed initial values must match their syntax and be computationally independent:
+`0px` is valid metadata; `var(--space-4)`, `1rem` and `currentColor` are not.
+The literal exemption applies only to registration descriptors. Keep design
+assignments outside them token-backed; a technical fallback is not a place to
+hide a component skin. Use literal static descriptors so guards can inspect them.
+See the [W3C registration contract](https://www.w3.org/TR/css-properties-values-api-1/#at-property-rule).
+
+Verify extracted CSS and actual interpolation, including after minification and
+inside the MCP App. A declaration can parse while a browser ignores an invalid
+registration. Keep required browser fallbacks and reduced-motion behavior; do not
+replace a valid CSS implementation with script merely to evade extraction or a
+guard limitation. These checks cover declarative registrations; arbitrary dynamic
+`CSS.registerProperty()` calls are not an ownership proof.
+
 ## Preserve custom-property arithmetic during extraction
 
 Custom properties can hold an unevaluated token stream that becomes arithmetic

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

@@ -101,7 +101,12 @@ failed/cancelled capture does not replace existing image slots or apply source.
 If a scenario/target is newly introduced, `current` is null with an explicit
 `currentAbsent` explanation; only the real candidate image exists.
 
-Review the returned images and diagnostics, fix the draft if necessary, then apply
+The edit reply is a summary. Read `ads_results({resultId,section:"captures"})` for
+the requested image resource URIs and `section:"diagnostics"` for relevant
+messages; follow `nextCursor` when needed. Read image resources explicitly.
+Standalone `ads_capture` continues returning its selected capture directly.
+
+Review those images and diagnostics, fix the draft if necessary, then apply
 with `dryRun:false`. Apply reruns all gates. An image is promoted only when the
 accepted source revision matches the captured candidate; other proposals remain
 stale. Images do not approve a patch or certify interaction/accessibility/parity.

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

@@ -0,0 +1,120 @@
+# Investigate the failing boundary
+
+Use this reference after a rejected patch, failed check or preview loading error.
+MCP serves it as `ads://guides/evidence`. Inspect the compact result first; fetch
+only the failing check's bundle or relevant artifact, rather than repeating a suite.
+
+## Read the result correctly
+
+`failure.category` identifies a boundary, not an inferred root cause:
+
+| Category | Established observation | Next inspection |
+|----------|-------------------------|-----------------|
+| `architecture` | A source/ownership/configuration gate rejected the candidate. | Exact rule, source location and `certainty`. An inconclusive ownership proof does not establish that a valid API is wrong. |
+| `build` | A registered project pipeline step or compiled-resource integrity check failed. | Named command/phase, exit code, bounded output and build revision. A custom project script may contain several kinds of checks. |
+| `transport` | An MCP/browser resource delivery boundary failed. | Resource URI, relevant failed startup requests and observed browser errors. Do not infer a network-interface or component cause without evidence. |
+| `runner` | The harness, process, readiness or reporting boundary failed, or a test threw without assertion evidence. | Active/pending checks, timeout, failing step and artifacts. `certainty: "unclassified"` means ADS cannot establish the cause. |
+| `assertion` | A reported assertion step or token binding check failed. | Expected behavior, source location, state and trace. This can still be a test defect; compare the intended contract before editing the component. |
+
+A complete failed run can contain independent passing cases. Suite interruption,
+missing/skipped cases, stale inputs and an unexplained process exit cannot certify
+a pass. Keep the reported case outcome separate from whole-run acceptance.
+
+## Retrieve only the evidence needed
+
+`ads_verify`, `ads_apply_patch` and `ads_apply_transaction` reply with counts,
+bounded acceptance, at most three failure previews and `resultId`, within 4096
+UTF-8 JSON bytes. Full validation still decides acceptance. Do not repeat a suite
+merely to recover its output, or restate the complete report in conversation.
+
+Read a relevant saved section:
+
+```js
+ads_results({resultId: "<returned ID>", section: "outcomes", status: "not_passed"})
+// Continue only when needed, with the same section and status:
+ads_results({resultId: "<returned ID>", section: "outcomes", status: "not_passed", cursor: "<nextCursor>"})
+```
+
+Pages default to 10 rows, allow at most 20 and stay within 8192 JSON bytes. The
+byte cap can return fewer rows; `nextCursor` is the continuation. Other sections
+are `checks` (pipeline steps), `diagnostics`, `advisories`, `warnings`, `changes`,
+`captures`, `acceptance`, `investigation` (mutation boundary) and `selection`.
+A row marked `detailTruncated` is a preview. To read that exact record, pass its
+`recordIndex`, the same result/section, and `offset`/`chars` (maximum 2000 UTF-16
+characters); follow `nextOffset`. Do not combine ranges with a cursor/status filter.
+Read only the relevant log range. Reading pages or ranges never executes checks.
+
+`ads://project/results` lists the latest IDs. `ads://results/<resultId>` reads a
+summary; matching query parameters read pages/ranges. Only the latest verification
+and latest mutation snapshots are retained, independently, up to 8 MiB each.
+A superseded ID fails explicitly. An oversized report retains only its summary
+with a warning; disk failure retains details in server memory until shutdown.
+Neither changes actual acceptance or applied state. These are logical JSON byte
+budgets, not token estimates; compatibility text can duplicate structured JSON.
+Saved outcomes describe completion-time evidence, not current source freshness;
+compare their revisions with `ads_behaviors` before claiming a current pass.
+
+`ads_behaviors` pages owner summaries, then an exact unit's `checks`, `guarantees`,
+`subjects`, `demonstrations` or `profiles`. Use `nextCursor` and identical filters;
+changes invalidate a discovery cursor. Read a truncated contract via its
+`sourceFile` and bounded `ads_read_file`, rather than requesting everything.
+
+## Get a compact investigation
+
+Take an outcome's exact owner/check/run IDs from `ads_results`, then:
+
+```json
+{ "unit": "components/Example", "check": "keyboard-navigation", "runId": "<outcome runId>" }
+```
+
+Send this to `ads_investigate`. It reads a summary within 4096 JSON bytes, without
+running code. The run ID rejects evidence superseded by another execution.
+`section: "details"`, `"requests"`, `"browserErrors"` or `"artifacts"` reads separate pages
+(default 10/max 20 rows, at most 8192 JSON bytes); artifacts themselves require
+explicit resource reads. Truncated investigation records also support
+`recordIndex`/`offset`/`chars`; keep the exact `runId` to avoid mixing evidence.
+Without a check, the tool pages available investigations.
+`ads://project/investigations` lists available entries; the returned `resourceUri`
+reads the same bundle. It records:
+
+- Project versus isolated candidate, configured framework/profile and scenario.
+- Exact input revision and the preview revision actually observed by the helper.
+- `details.failingStep`, `details.source`, startup viewport and failure boundary.
+- Counts for separately paged relevant requests, browser errors and artifacts.
+- Available registered trace, screenshot or context artifact resource URIs.
+- Explicit `acceptance.established` and `acceptance.unverified` scope.
+
+Absent observations are `null` or empty; ADS does not invent a viewport, trace or
+source line. Viewport evidence is labeled `preview-startup`; a test that resizes
+later must collect its own failure-state evidence. Failed-request collection
+covers managed startup, not a complete network trace. Bodies and headers are not
+collected. Project-configured Playwright trace/screenshot policy controls which
+artifacts exist; ADS does not turn on expensive recording or rerun a failed case.
+Protocol runners may provide structured failure/step/location/artifact fields;
+older reports remain valid and their unclassified errors stay explicit.
+
+Only the latest bundle per registered check is exposed, including dry runs.
+Another verification replaces it and removes old artifacts from resource access;
+old runner output directories follow project cleanup policy. Artifact resources
+are restricted to registered ordinary files under that run's output directory,
+bounded to 20 MiB each and checked against their recorded digest on read.
+Metadata is bounded to 2 MiB. Removed registrations are pruned on verification.
+
+Candidate evidence never becomes passing live-source evidence. Compare the
+recorded input revision with current `ads_behaviors` evidence; a bundle describes
+its run, and does not claim current source merely because it remains available.
+For a build/architecture rejection before behavior runs, inspect the mutation
+saved `investigation` section via `ads_results`. Status retains the compact
+execution summary and result ID, rather than embedding complete reports.
+
+## Preserve the design while repairing the failure
+
+Fix the owner of the demonstrated defect. Do not privatize a valid API, introduce
+demo-only props, substitute a styled link, change the reference baseline or weaken
+verification policy to pass a tooling limitation. Preserve the draft and report
+the smallest source/browser reproduction when ownership remains unprovable.
+
+`acceptance` states what that result established. Core checks establish source
+guard acceptance; registered tests establish only their actual cases/profiles.
+Neither establishes untested states, visual parity, an accessibility audit or
+another MCP host's compatibility. Captures show an appearance, not a transition.

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

@@ -15,8 +15,10 @@ ads_apply_patch({"unit":"components/Example","patchFile":"<returned patchFile>",
 
 The dry run validates the full candidate, including affected registered behavior
 checks in an isolated project copy. Configured browser checks use that candidate's
-managed preview, not the live showcase. Inspect the returned `behavior` failures
-or the registered behavior-check results in `checks`, fix the draft and diff again.
+managed preview, not the live showcase. Read the summary, then page failing
+`outcomes`, `diagnostics` or pipeline `checks` through `ads_results` with its
+`resultId`. Inspect one exact outcome with `ads_investigate({unit,check,runId})`;
+fix the draft and diff again. See [evidence.md](evidence.md) for page/range limits.
 Keep behavior.json/specs with their owner and use registered checks; a scratchpad
 run against live source cannot verify unapplied changes. After validation, apply
 with `dryRun:false`; ADS revalidates before writing. Dry-run evidence is not saved
@@ -120,9 +122,10 @@ them through their actual public composition/customization path and list their r
 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. A native link/button can supply semantics
-as the single direct child of a public runtime slot when source tracing proves
-that owner clones the child with its props. An `asChild` flag alone is insufficient;
-standalone native controls and custom scenario styling remain rejected. See
+through a public runtime slot that demonstrably clones its child with owned
+props, or through matching runtime-owned selectors attached to the actual rendered
+DOM. Source ownership must be proven; an `asChild` flag or a lookalike marker is
+insufficient. Standalone controls and custom scenario styling remain rejected. See
 [scenarios.md](scenarios.md) for evidence and limits. Preserve the intended
 composition instead of substituting an unrelated styled control or adding a
 demo-only component prop. Review framing belongs in public layout patterns.

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

@@ -101,6 +101,38 @@ do not export the helper solely for a test. Public/private ownership is a produc
 decision, not a coverage workaround. Browser checks verify transitions but do not
 replace the current static `covers` requirement; `exercises` does not waive it.
 
+## Native semantics through runtime-owned selectors
+
+An anchor or other native semantic element can also occupy a position styled by
+public runtime UI, without cloning or an `asChild` API:
+
+```tsx
+// Runtime owner: the class is attached to Line's actual rendered span.
+const line = css`:is(a, button) > & { color: var(--text-body); }`;
+export function Line(props) { return <span className={line} {...props} />; }
+
+// Scenario: semantics belong to the consumer, appearance to the runtime owner.
+<a href={fixture.destination}><Line>{fixture.label}</Line></a>
+```
+
+ADS traces the actual returned DOM, the attached Linaria template and matching
+selector relationships. A public parent's `& > a` is evidence too. A tag-agnostic
+parent selector such as `& > :has(> [data-part="line"])` must match a marker
+declared by the actual runtime-owned child; a scenario-authored lookalike does not
+qualify. No component names or marker spellings are reserved.
+
+Unused styles, unrelated CSS, broad `& > *` selectors, negative selectors alone,
+fabricated markers, unknown render alternatives and opaque class replacement
+cannot grant permission. A selector cannot establish a scenario-built custom
+widget's keyboard behavior. Inline styles and arbitrary classes remain rejected;
+existing source-verified public class helpers keep their own contract.
+
+Do not add a public link part or change the DOM to satisfy a cloning-only model.
+Preserve semantic attributes and the intended public API. Unsupported source
+grammar produces an inconclusive ownership diagnostic, not proof of a bad API.
+Browser verification must establish the real focus treatment, hover/state
+precedence, navigation and other promised behavior in the compiled App iframe.
+
 ## Native semantics through a public runtime slot
 
 A native element can be the direct child of a public runtime component that

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

@@ -49,17 +49,22 @@ For owner drafts, token-sample reconciliation, coupled transactions and local
 constant namespaces, read [guarded-editing.md](references/guarded-editing.md).
 For on-demand current/candidate screenshots and visual dry-run review, read
 [captures.md](references/captures.md).
+For a rejected patch, failed check or loading error, read
+[evidence and diagnosis](references/evidence.md); inspect the failing boundary
+then page needed `ads_results` sections using the returned result ID. Inspect
+one `ads_investigate({unit,check,runId})` summary before changing APIs or policy;
+load request/error/artifact details only when relevant.
 
 
 For parent/child `covers`, conditional-control review, reference comparisons,
-public style-helper use, fragment-link navigation, or `scenario-render` /
-`showcase-class` findings, read [scenario contracts](references/scenarios.md). Its verification
+public style-helper use, native slot/selector composition, fragment navigation,
+or `scenario-render` / `showcase-control` / `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
+custom-property arithmetic, typed `@property` registrations, or an
 `atomic-composition-review` / `atomic-composition-limit` advisory, read
 [atomic style composition](references/atomic-styles.md). The same guide is served
 as `ads://guides/atomic-styles`. It explains shorthand/logical conflicts and

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

@@ -81,6 +81,54 @@ const treatment = css`
 This is a distinct state, not two competing base atoms. Whether changing padding
 on hover is desirable remains a product decision.
 
+## Register typed custom properties without atomizing their descriptors
+
+Use a literal `@property` in its component/pattern's Linaria template when the
+browser needs a typed, interpolated runtime variable:
+
+```tsx
+const treatment = css`
+  @property --ds-example-progress {
+    syntax: "<number>";
+    inherits: false;
+    initial-value: 0;
+  }
+  opacity: var(--ds-example-progress);
+`;
+```
+
+The identifier is illustrative; use a unique name owned by the real unit.
+Registrations are document-global, even when authored beside one component.
+Put them at template level or inside conditional at-rules, never element selectors.
+Use the same ADS tag resolver described below in both product and preview builds;
+it preserves each complete registration and its conditional context instead of
+splitting syntax/inherits/initial-value into invalid atomic rules. This works for
+atomic `css` and `styled`; the browser receives CSS without a registration runtime.
+MCP delivers it inside the App document, not the outer showcase host.
+
+`property-registration` validates descriptor shape, CSS syntax/initial-value and
+ownership, and rejects conflicting schemas or registrations shared by unrelated
+owners. Identical registrations from the same owner are permitted. Runtime
+`--ds-*` / `--ux-*` variables stay with their runtime owner. A shared token's
+registration belongs beside its actual definition in a foundation value sheet;
+a namespaced owner token's registration belongs in its registered `tokens.css`.
+Neither `base.css` nor `fonts.css` becomes a registration escape hatch. Registration
+alone does not define a token or satisfy its sample/fixture coverage.
+
+Typed initial values must match their syntax and be computationally independent:
+`0px` is valid metadata; `var(--space-4)`, `1rem` and `currentColor` are not.
+The literal exemption applies only to registration descriptors. Keep design
+assignments outside them token-backed; a technical fallback is not a place to
+hide a component skin. Use literal static descriptors so guards can inspect them.
+See the [W3C registration contract](https://www.w3.org/TR/css-properties-values-api-1/#at-property-rule).
+
+Verify extracted CSS and actual interpolation, including after minification and
+inside the MCP App. A declaration can parse while a browser ignores an invalid
+registration. Keep required browser fallbacks and reduced-motion behavior; do not
+replace a valid CSS implementation with script merely to evade extraction or a
+guard limitation. These checks cover declarative registrations; arbitrary dynamic
+`CSS.registerProperty()` calls are not an ownership proof.
+
 ## Preserve custom-property arithmetic during extraction
 
 Custom properties can hold an unevaluated token stream that becomes arithmetic

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

@@ -101,7 +101,12 @@ failed/cancelled capture does not replace existing image slots or apply source.
 If a scenario/target is newly introduced, `current` is null with an explicit
 `currentAbsent` explanation; only the real candidate image exists.
 
-Review the returned images and diagnostics, fix the draft if necessary, then apply
+The edit reply is a summary. Read `ads_results({resultId,section:"captures"})` for
+the requested image resource URIs and `section:"diagnostics"` for relevant
+messages; follow `nextCursor` when needed. Read image resources explicitly.
+Standalone `ads_capture` continues returning its selected capture directly.
+
+Review those images and diagnostics, fix the draft if necessary, then apply
 with `dryRun:false`. Apply reruns all gates. An image is promoted only when the
 accepted source revision matches the captured candidate; other proposals remain
 stale. Images do not approve a patch or certify interaction/accessibility/parity.