@event4u/agent-config 16.4.0 → 17.0.0

package/dist/agent-src/skills/corpus-grounding/scripts/schema_validator.ts

@@ -267,7 +267,13 @@ export function resolve_data_path(manifest: Manifest, relative: string): string
         throw new ManifestError(`data_dir must be manifest-relative: ${pyRepr(data_dir)}`);
     }
     // Python: (base / dd / rel).resolve() — resolve() follows symlinks.
-    return pyResolve(path.join(base, data_dir, relative));
+    const resolved = pyResolve(path.join(base, data_dir, relative));
+    // The string checks above cannot see a symlink inside the pack that points out of it.
+    const root = pyResolve(base);
+    if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+        throw new ManifestError(`corpus path resolves outside the manifest directory: ${pyRepr(relative)}`);
+    }
+    return resolved;
 }
 
 /** Mirror pathlib Path(p).parts for the relative-path containment check. */

package/dist/agent-src/skills/dashboard-design/SKILL.md

@@ -27,7 +27,7 @@ Do NOT use when:
 2. **Pick the surface** — Use the decision tables below to choose Grafana, app dashboard, or embed; document audience and refresh cadence.
 3. **Draft the layout** — Sketch panels, choose visualization per signal (RED / USE / Golden Signals), define filters and thresholds.
    **Ground the chart-type choice** in the adopted data-viz corpus instead
-   of memory: `./scripts-run <skills-root>/corpus-grounding/scripts/ground
+   of memory: `node <skills-root>/corpus-grounding/scripts/ground.mjs
    search --manifest
    <skills-root>/design-intelligence/data/manifest.json --domain chart
    "<data shape>"` returns the best chart type, when-NOT-to-use, data-volume

package/dist/agent-src/skills/data-flow-mapper/SKILL.md

@@ -156,8 +156,11 @@ Runtime confirmation (e.g. *"actually POST a request and log the payload"*,
 
 ## References
 
-- **OWASP ASVS v4.0.3 V5** — Validation, Sanitization and Encoding — baseline
-  for naming validation / normalization hops.
+- **OWASP ASVS v5.0.0** — V1 Encoding and Sanitization + V2 Validation and
+  Business Logic — baseline for naming validation / normalization hops. The
+  two chapters were one in the previous revision; `threat-modeling`'s
+  References records that split and the migration guide it comes from, and the
+  old numbering is deliberately not repeated here.
   [owasp.org/www-project-application-security-verification-standard/](https://owasp.org/www-project-application-security-verification-standard/)
 - [`threat-modeling`](../threat-modeling/SKILL.md),
   [`authz-review`](../authz-review/SKILL.md),

package/dist/agent-src/skills/database/SKILL.md

@@ -15,13 +15,14 @@ packs:
 
 
 > **Grounded corpus (Tier-1 consultation):** symptom → index/strategy
-> decisions come grounded — `./scripts-run
-> <skills-root>/corpus-grounding/scripts/ground search --manifest
+> decisions come grounded — `node
+> <skills-root>/corpus-grounding/scripts/ground.mjs search --manifest
 > <skills-root>/database/data/manifest.json "<symptom>"` returns root
 > cause, strategy, good-code sketch, anti-pattern, and the verification
 > probe (EXPLAIN expectation). Corpus:
-> [`data/query-tuning.csv`](data/query-tuning.csv) (PostgreSQL 16 /
-> MySQL 8-derived).
+> [`data/query-tuning.csv`](data/query-tuning.csv); its engine versions and
+> their date live in [`data/manifest.json`](data/manifest.json) `upstream`.
+> Repeating them here is how this line fell two majors behind.
 
 ## When to use
 

package/dist/agent-src/skills/decision-record/references/weighted-matrix.md

@@ -1,5 +1,17 @@
 # Weighted-matrix mode — full procedure
 
+<!-- reference-toc:start (generated by generate_reference_toc — do not edit) -->
+**Contents**
+
+- [Gate — when the mode fires (all four, else stay qualitative)](#gate--when-the-mode-fires-all-four-else-stay-qualitative)
+- [Elicitation — user first, always](#elicitation--user-first-always)
+- [Scoring — fixed anchors, never relative](#scoring--fixed-anchors-never-relative)
+- [Sensitivity block — the load-bearing gate](#sensitivity-block--the-load-bearing-gate)
+- [Argue against the winner — delegated, scoped](#argue-against-the-winner--delegated-scoped)
+- [Output contract (appended to the standard payload)](#output-contract-appended-to-the-standard-payload)
+- [Worked example (compressed)](#worked-example-compressed)
+<!-- reference-toc:end -->
+
 Quantitative variant of the `decision-record` trade-off matrix. Loaded from
 [`SKILL.md § Weighted-matrix mode`](../SKILL.md) when the gate fires; this
 file carries the elicitation detail, anchor discipline, sensitivity math and

package/dist/agent-src/skills/deep-reading-analyst/SKILL.md

@@ -1,6 +1,6 @@
 ---
 model_tier: high
-context: large
+context_window: large
 name: deep-reading-analyst
 description: "Deep analysis of articles/long-form via thinking frameworks (SCQA, mental models, inversion) — 'analyze article', 'deep dive', 'extract insights', URL/text wanting depth not summary."
 status: active

package/dist/agent-src/skills/dependency-upgrade/SKILL.md

@@ -55,9 +55,6 @@ Ask in this order, and stop at the first that answers:
 3. **The member manifest** — the ordinary case, and only after 1 and 2 are
    silent.
 
-A repository with no catalog and no root pin behaves exactly as before; this
-step adds a lookup, not a change of default.
-
 ### 2. Plan
 
 Categorize changes needed:
@@ -184,11 +181,8 @@ When upgrading multiple packages:
 
 | Pitfall | Prevention |
 |---|---|
-| Upgrading without reading changelog | Always read the changelog first |
-| Upgrading all packages at once | One package at a time (or tightly coupled groups) |
 | Trusting `composer update` blindly | Use `--dry-run` first, review changes |
 | Ignoring deprecation warnings | Fix deprecations before they become errors |
-| Skipping tests after upgrade | Full test suite + project type-checker (PHPStan / tsc / mypy / `go vet` / `cargo check`) after every upgrade |
 | Lock file conflicts | Coordinate upgrades with the team |
 
 ## Version constraint guidelines
@@ -205,7 +199,7 @@ When upgrading multiple packages:
 
 For security patches:
 
-- **Prioritize** — security upgrades should be fast-tracked.
+- **Prioritize** — fast-track security upgrades.
 - **Check `composer audit`** / `npm audit` regularly.
 - **Patch versions** (e.g., 2.1.3 → 2.1.4) are usually safe to apply immediately.
 - **Still run tests** — even security patches can break things.
@@ -217,7 +211,7 @@ Before adding a **new** dependency (not just upgrading), run a security audit:
 ### Composer (PHP)
 
 ```bash
-# Check for known vulnerabilities in current dependencies
+# Known vulnerabilities in installed packages
 composer audit
 
 # After adding a new package, re-check
@@ -257,7 +251,7 @@ When `composer require` or `npm install` fails with conflicts:
 
 ## Post-update malware & behavior audit
 
-CVE scanning (above) catches *known-vulnerable* versions. It does **not** catch a **compromised update**: a trusted package with a legitimate history ships a normal-looking version bump that quietly adds data-exfiltration or other harmful behavior. This is how the biggest supply-chain attacks landed — event-stream (wallet stealer as a new transitive dep), ua-parser-js (`preinstall` miner + credential stealer), @solana/web3.js (key exfil hidden inside expected network calls), chalk/debug + 16 (browser crypto-drainer, 2B weekly downloads), the self-propagating Shai-Hulud worm (added a `.github/workflows` + secret-scanning `postinstall`), xz-utils (backdoor in the released tarball, not the git repo). Routine updates slip through because the version looks normal and install runs scripts across the whole transitive tree silently — this is the exact [`lethal-trifecta-guard`](../../rules/lethal-trifecta-guard.md) egress shape.
+CVE scanning (above) catches *known-vulnerable* versions. It does **not** catch a **compromised update**: a trusted package with a legitimate history ships a normal-looking version bump that quietly adds data-exfiltration or other harmful behavior. This is how the biggest supply-chain attacks landed — event-stream (wallet stealer as a new transitive dep), ua-parser-js (`preinstall` miner + credential stealer), @solana/web3.js (key exfil hidden inside expected network calls), chalk/debug + 16 (browser crypto-drainer), the self-propagating Shai-Hulud worm (added a `.github/workflows` + secret-scanning `postinstall`), xz-utils (backdoor in the released tarball, not the git repo). Routine updates slip through because the version looks normal and install runs scripts across the whole transitive tree silently — this is the exact [`lethal-trifecta-guard`](../../rules/lethal-trifecta-guard.md) egress shape.
 
 **Run this audit during/after any add or upgrade, then surface findings to the user and hold pending confirmation** (per [`active-remediation`](../../rules/active-remediation.md) — a live supply-chain risk is surfaced, never silently accepted):
 
@@ -266,15 +260,71 @@ CVE scanning (above) catches *known-vulnerable* versions. It does **not** catch
 3. **Capability / behavior diff** — did the new version add a capability its job doesn't need: network egress (`fetch`/`net`/`dns`/`http`), `child_process`/shell, env/secret/credential reads, filesystem writes, obfuscated/minified blobs, a `.github/workflows` file? Use `socket` / `guarddog <eco> scan <pkg>@<ver>` if available; else read the delta.
 4. **Purpose-vs-behavior legitimacy check** — a Slack/HTTP client legitimately makes network calls; a date/string/color util does not. For each new capability ask: *does the package's stated purpose require this?* A network/secret capability with no purpose justification — or a **new outbound endpoint** even in a package that already uses the network — is high-risk.
 5. **Provenance + advisory feeds** — `npm audit signatures` (flag a dep that *had* provenance and lost it — a hallmark of a token-theft publish); `osv-scanner --lockfile=…` and the GitHub Advisory / Socket / Snyk malware feeds against the newly-resolved versions.
+6. **Release age and agent-config paths** — a fixing version younger than three days (a default, not a measured threshold) is `fix-fresh`: run steps 1–5 before installing it, not after. Any change to an agent, editor, git-hook or CI config path in a dependency update's diff stops the update — e.g. `.claude/`, `.augment/`, `.cursor/`, `.gemini/`, `.windsurf/`, `.codex/`, `.vscode/`, `.husky/`, `.github/workflows/`, `.mcp.json`, an `AGENTS.md` / `CLAUDE.md` / `.cursorrules`-style instruction file — or to an install script; an unlisted path of that class stops it too. Own analysis: a session-start hook is a persistence point running with the developer's credentials, hence a stop, not a warning.
 
 **Surface to the user** any: new install script · new transitive dep · new network endpoint / secret read · obfuscated blob · lost provenance · advisory/malware hit — with the version delta and the purpose-vs-behavior verdict, and hold the update until they decide. Never auto-accept a bump that introduced an unexplained capability.
 
+## Security fix — one finding carried to a verified PR
+
+Entered from `/audit deps fix <id>` or a finding the user names. The goal is a
+fix the owner can merge, not a plan: smallest change, right place, proven by the
+source that reported it.
+
+1. **Plan and route** — `agent-config audit:deps fix <id>` prints the route
+   (routing table below), the branch and PR title, the smallest fixing change,
+   and for a runtime every pinning file with its edit plus an ops checklist. It
+   claims the finding: a second session sees the open fix and joins it instead
+   of starting another.
+
+   | Situation | Route |
+   |---|---|
+   | the current branch introduced the dependency, or the user says "here" | this branch, its own `fix(security): …` commit |
+   | an open bot PR already moves this dependency | complete that PR |
+   | trunk, clean tree | a new `security/…` branch in this checkout |
+   | a feature branch is in progress | a separate worktree from fresh trunk, its own branch and PR — the fix travels alone; if the feature changes the same lockfile, offer it a rebase after the merge |
+
+   Choosing "separate worktree" in the offer **is** the explicit ask
+   `using-git-worktrees` requires; register it (`agent-config worktree:cleanup
+   register <path> --purpose=security-fix`) so its removal after the merge is
+   not forgotten.
+2. **Build the smallest fix** — inside the current constraint first
+   (`npm update <pkg> --ignore-scripts`, an `overrides` entry for a
+   transitive fix, `composer update vendor/pkg --no-scripts --no-plugins`); a constraint change only
+   when the fixing version is outside it; a new major only with a stated
+   compatibility analysis; never `npm audit fix --force`. A runtime fix changes
+   every file that pins it in one commit. Run the post-update audit above,
+   including step 6.
+3. **Prove it** — `agent-config audit:deps verify <id>`: the source that reported
+   the finding must stop reporting it on this branch. `fix-failed` means the hole
+   is still open — say so; `unverifiable` means the source did not answer — say
+   that too. Then the project's tests and static checks. A fix that leaves the
+   advisory open or breaks a test is reported as exactly that, never as done.
+4. **Open the PR** — `agent-config audit:deps pr-body <id> --tests=passed`
+   prints the body; its After field is what `verify` recorded; a library adds
+   `--release=<current version>` for the patch-release draft. Security fixes are
+   never mixed with unrelated work. Stop before tag and publish. The entry
+   command authorizes only the local fix: before the first push or PR, show
+   branch, title and body and wait for this-turn confirmation
+   (`non-destructive-by-default`). On a public remote the body names the
+   advisory id and fixed version, never an exploit path, until merged.
+5. **Hand over** — watch CI with `agent-config ci:settle <pr>`, fix what the fix
+   broke, report "ready to merge". Merge is the owner's, or `/pr:merge` under the
+   owner's instruction; under `worktrees.cleanup: auto` the merge removes the fix
+   worktree. Afterwards `agent-config audit:deps track` follows it from
+   `fixed-in-trunk` to `fixed-released` to `fixed-deployed`; "merged but not
+   deployed" after 24 h stays in the session notice.
+6. **No fix exists** — offer a mitigation (a configuration change, a disabled
+   feature, a pinned-back version where that is safe) and record it with
+   `agent-config audit:deps mitigate <id> --note="…"`; it stays open and reopens
+   the moment a refresh reports a fix.
+
 ## Output format
 
 1. Updated dependency with version constraint change
 2. Breaking changes addressed with code modifications
 3. Test results confirming compatibility
 4. Post-update audit result: capability delta old→new, purpose-vs-behavior verdict, provenance/advisory status — and any finding surfaced to the user for confirmation
+5. For a security fix: the route taken, the source's own re-check (`fixed-in-branch` / `fix-failed` / `unverifiable`), and the PR or the reason there is none
 
 ## Auto-trigger keywords
 
@@ -288,12 +338,12 @@ CVE scanning (above) catches *known-vulnerable* versions. It does **not** catch
 
 ## Gotcha
 
-- **A trusted package is not a safe version.** Every major supply-chain attack (event-stream, ua-parser-js, chalk/debug, xz) shipped through a *legitimate* package's normal-looking bump — maintainer-authored ≠ safe. Run the post-update behavior audit, not just `audit` for CVEs.
+- **A trusted package is not a safe version.** Every attack listed above shipped as a *legitimate* package's normal-looking bump. Run the post-update behavior audit, not just `audit` for CVEs.
 - **`audit` (CVE) ≠ malware scan.** `npm/composer audit` only knows *published* vulnerabilities; a fresh compromised version has no CVE yet. The capability/behavior diff + purpose-vs-behavior check is what catches zero-hour malware.
 - Don't upgrade multiple major versions at once — one major version per upgrade cycle.
 - The model tends to skip reading the CHANGELOG — breaking changes hide in minor releases too.
 - Always run the full test suite after upgrading, not just the affected tests.
-- Lock file conflicts after upgrade are expected — resolve by re-running the package manager's update (`composer update`, `npm update`, `poetry update`).
+- Lock file conflicts after upgrade are expected — re-run the package manager's update (`composer update`, `npm update`, `poetry update`).
 
 ## Do NOT
 

package/dist/agent-src/skills/description-assist/SKILL.md

@@ -65,7 +65,7 @@ If the target is a skill, check for a trigger-eval report:
 
 * `src/skills/{name}/evals/triggers.json` — the expected-trigger corpus
 * `evals/last-run.json` — the most recent runner output (see
-  [`scripts/skill_trigger_eval.ts`](../../../scripts/skill_trigger_eval.ts))
+  [`scripts/skill_trigger_eval.ts`](../../scripts/skill_trigger_eval.ts))
 
 If `last-run.json` exists and contains failed queries for this skill,
 extract the failure patterns and **use them to inform step 3 variants**.

package/dist/agent-src/skills/design-intelligence/SKILL.md

@@ -94,7 +94,7 @@ corpus. Canon is a gap-filler, never an override of a registered brand value.
    product → style → color → landing → typography with decision rules):
 
    ```bash
-   ./scripts-run <skills-root>/corpus-grounding/scripts/ground ground \
+   node <skills-root>/corpus-grounding/scripts/ground.mjs ground \
      --manifest <skills-root>/design-intelligence/data/manifest.json \
      "<product type + mood + platform>" --json
    ```

package/dist/agent-src/skills/design-intelligence/data/landing.csv

@@ -33,4 +33,4 @@ No,Pattern Name,Keywords,Section Order,Primary CTA Placement,Color Strategy,Reco
 32,Hero-Centric Design,"hero-centric, hero-centric design, hero-first, hero above fold","1. Full-bleed Hero (headline + visual), 2. Single value prop strip, 3. Key benefit or proof, 4. Primary CTA",Hero dominant (center/bottom) + Sticky nav CTA,Hero: High-impact visual. Minimal text. CTA 7:1 contrast.,"Hero parallax or video, CTA pulse on scroll, minimal chrome",One primary CTA. Hero is 60-80% above fold. Mobile: same hierarchy.
 33,Trust & Authority + Conversion,"trust & authority, trust, authority, conversion, credibility, enterprise","1. Hero (mission/credibility), 2. Proof (logos, certs, stats), 3. Solution overview, 4. Clear CTA path",Contact Sales / Get Quote (primary) + Nav,Navy/Grey corporate. Trust blue. Accent for CTA only.,"Logo carousel, stat counters, testimonial strip",Security badges. Case studies. Transparent pricing. Low-friction form.
 34,Real-Time / Operations Landing,"real-time, real-time monitor, operations, dashboard, telemetry, live data","1. Hero (product + live preview or status), 2. Key metrics/indicators, 3. How it works, 4. CTA (Start trial / Contact)",Primary CTA in nav + After metrics,Dark or neutral. Status colors (green/amber/red). Data-dense but scannable.,"Live data ticker, status pulse, minimal decoration",For ops/security/iot products. Demo or sandbox link. Trust signals.
-35,Scroll-Driven Narrative,"scrollytelling, scroll-driven, scroll narrative, story beats, beat ledger, pinned scroll, scrub, narrative landing","1. Hero (static, readable before any scroll), 2. Beat 1 pinned reveal, 3. Beat 2 transform/scrub, 4. Beat 3 payoff, 5. CTA (reachable without scrubbing back)",Hero (static) + Post-payoff,"One palette across all beats — a beat that changes palette reads as a different site. Contrast held at the beat's own background, not the hero's",Pinned section with scrubbed progress; opacity/transform only (never layout-affecting properties); every beat readable at its resting state with motion disabled,"The CTA must be reachable without completing the narrative. Author a story-beat ledger first (wireframe/references/story-beat-ledger.schema.json) — beats are content, so they are decided before layout. prefers-reduced-motion presents each beat at its resting state; it never sets animation: none, which leaves the story untold"
+35,Scroll-Driven Narrative,"scrollytelling, scroll-driven, scroll narrative, story beats, beat ledger, pinned scroll, scrub, narrative landing","1. Hero (static, readable before any scroll), 2. Beat 1 pinned reveal, 3. Beat 2 transform/scrub, 4. Beat 3 payoff, 5. CTA (reachable without scrubbing back)",Hero (static) + Post-payoff,"One palette across all beats — a beat that changes palette reads as a different site. Contrast held at the beat's own background, not the hero's",Pinned section with scrubbed progress; opacity/transform only (never layout-affecting properties); every beat readable at its resting state with motion disabled,"The CTA must be reachable without completing the narrative. Author a story-beat ledger first (design-review/references/story-beat-ledger.schema.json) — beats are content, so they are decided before layout. prefers-reduced-motion presents each beat at its resting state; it never sets animation: none, which leaves the story untold"

package/dist/agent-src/skills/design-intelligence/references/context-and-registers.md

@@ -1,5 +1,13 @@
 # design-intelligence — context and registers
 
+<!-- reference-toc:start (generated by generate_reference_toc — do not edit) -->
+**Contents**
+
+- [Cross-task design memory — read DESIGN.md / PRODUCT.md first](#cross-task-design-memory--read-designmd--productmd-first)
+- [Register — brand vs product](#register--brand-vs-product)
+- [Design Read — articulate intent before generating](#design-read--articulate-intent-before-generating)
+<!-- reference-toc:end -->
+
 > Section-level entry point of the `design-intelligence` skill (progressive
 > disclosure, 2026-08-04). Content moved VERBATIM from SKILL.md —
 > load this file when the section index in SKILL.md routes here.
@@ -20,8 +28,8 @@ the project root for `DESIGN.md` and/or `PRODUCT.md` (written by
    in DESIGN.md (e.g., chose a specific shadow for a new elevated surface),
    flag it for capture: *"Suggest adding to DESIGN.md: elevated surface shadow = …"*
 
-Boundary vs `brand-to-tokens`/`.tokens.json`:
-- `.tokens.json` = primitive definitions (gray-700 = #374151)
+Boundary vs `brand-to-tokens`/`tokens.json`:
+- `tokens.json` = primitive definitions (gray-700 = #374151)
 - `DESIGN.md` = usage decisions (elevated surfaces use the gray-700 shadow, 8px radius)
 Both are consumed; DESIGN.md takes precedence for usage questions.
 

package/dist/agent-src/skills/design-intelligence/references/design-languages.md

@@ -36,7 +36,7 @@
 ## How to use
 
 1. Select the style through the grounding engine first:
-   `./scripts-run <skills-root>/corpus-grounding/scripts/ground search
+   `node <skills-root>/corpus-grounding/scripts/ground.mjs search
    --manifest <skills-root>/design-intelligence/data/manifest.json
    --domain style "<product + mood>"`.
 2. Open the matching spec file and lift its token system (colors,

package/dist/agent-src/skills/design-intelligence/references/design-rules-checklist.md

@@ -24,7 +24,7 @@
 | 3 | Performance | HIGH | `ux` | WebP/AVIF, Lazy loading, Reserve space (CLS < 0.1) | Layout thrashing, Cumulative Layout Shift |
 | 4 | Style Selection | HIGH | `style`, `product` | Match product type, Consistency, SVG icons (no emoji) | Mixing flat & skeuomorphic randomly, Emoji as icons |
 | 5 | Layout & Responsive | HIGH | `ux` | Mobile-first breakpoints, Viewport meta, No horizontal scroll | Horizontal scroll, Fixed px container widths, Disable zoom |
-| 6 | Typography & Color | MEDIUM | `typography`, `color` | Base 16px, Line-height 1.5, Semantic color tokens | Text < 12px body, Gray-on-gray, Raw hex in components |
+| 6 | Typography & Color | MEDIUM | `typography`, `color` | Base 16px, Line-height per `typography-system` (the one authority), Semantic color tokens | Text < 12px body, Gray-on-gray, Raw hex in components |
 | 7 | Animation | MEDIUM | `ux` | Duration within the authority's per-interaction bands, Motion conveys meaning, Spatial continuity | Decorative-only animation, Animating width/height, No reduced-motion |
 | 8 | Forms & Feedback | MEDIUM | `ux` | Visible labels, Error near field, Helper text, Progressive disclosure | Placeholder-only label, Errors only at top, Overwhelm upfront |
 | 9 | Navigation Patterns | HIGH | `ux` | Predictable back, Bottom nav ≤5, Deep linking | Overloaded nav, Broken back behavior, No deep links |
@@ -112,7 +112,8 @@
 - `viewport-meta` - width=device-width initial-scale=1 (never disable zoom)
 - `mobile-first` - Design mobile-first, then scale up to tablet and desktop
 - `breakpoint-consistency` - Use systematic breakpoints (e.g. 375 / 768 / 1024 / 1440)
-- `readable-font-size` - Minimum 16px body text on mobile (avoids iOS auto-zoom)
+- `readable-font-size` - Body text at or above the Q2 floor in `docs/guidelines/design-antipatterns.md`
+- `control-font-size` - Inputs, selects and textareas at 16px or more on touch layouts; a smaller control font is the documented trigger for iOS auto-zoom on focus
 - `line-length-control` - Mobile 35–60 chars per line; desktop 60–75 chars
 - `horizontal-scroll` - No horizontal scroll on mobile; ensure content fits viewport width
 - `spacing-scale` - Use 4pt/8dp incremental spacing system (Material Design)
@@ -128,7 +129,7 @@
 
 ### 6. Typography & Color (MEDIUM)
 
-- `line-height` - Use 1.5-1.75 for body text
+- `line-height` - Body line-height comes from `typography-system` (one authority; Q8 is the floor)
 - `line-length` - Limit to 65-75 characters per line
 - `font-pairing` - Match heading/body font personalities
 - `font-scale` - Consistent type scale (e.g. 12 14 16 18 24 32)

package/dist/agent-src/skills/design-intelligence/references/integration-mapping.md

@@ -24,29 +24,29 @@ The `review`/`polish` steps gate on `state.ui_review.a11y`. Ground two
 finding classes instead of ad-hoc judgment:
 
 - **Chart-type findings** — the grounding CLI (`ground` via
-  ./scripts-run) — `…/ground search --manifest … --domain
+  node) — `…/ground.mjs search --manifest … --domain
   chart "<data shape>"` → `Accessibility Grade`, `A11y Fallback`,
   `Color Guidance` columns justify "wrong chart type / missing colorblind
   fallback" findings with a citable row.
 - **Contrast findings** — `--domain color "<product>"` returns the
   WCAG-adjusted token set; a finding that a hex pair deviates from the
   adopted set cites the row instead of eyeballing ratios. Auditing
-  *method* stays with [`accessibility-auditor`](../accessibility-auditor/SKILL.md).
+  *method* stays with [`accessibility-auditor`](../../accessibility-auditor/SKILL.md).
 
 ## Stack guidance (`--stack` axis)
 
 Per-framework Do/Don't corpora (16 stacks) ride the same manifest:
 
 ```bash
-./scripts-run <skills-root>/corpus-grounding/scripts/ground search \
+node <skills-root>/corpus-grounding/scripts/ground.mjs search \
   --manifest <skills-root>/design-intelligence/data/manifest.json \
   --stack react "list rerender memo" [--filter "Severity=HIGH"]
 ```
 
-Stack executors ([`blade-ui`](../blade-ui/SKILL.md),
-[`livewire`](../livewire/SKILL.md), [`flux`](../flux/SKILL.md),
-[`react-shadcn-ui`](../react-shadcn-ui/SKILL.md),
-[`tailwind-engineer`](../tailwind-engineer/SKILL.md)) pull idiomatic
+Stack executors (`blade-ui`,
+`livewire`, `flux`,
+[`react-shadcn-ui`](../../react-shadcn-ui/SKILL.md),
+[`tailwind-engineer`](../../tailwind-engineer/SKILL.md)) pull idiomatic
 guidance + docs URLs from here instead of memory.
 
 ## Diagram-type routing — route on the verb
@@ -62,16 +62,19 @@ shape; 3–7 → one diagram; 8+ → split or summarize, never one dense picture
 | a **cycle** / loop / lifecycle | — | a **stepper widget**, never a hand-drawn ring |
 | a **DB schema / ERD** / entity relations | — | **mermaid**, never hand-placed SVG |
 
-### Geometric pre-checks (run BEFORE finalizing an SVG/diagram)
+### Drawing the diagram itself
 
-Ranked by failure rate — procedures, not constants:
+The verb routing above and the noun-count triage stay here — they decide WHAT to
+draw. **How** to draw it, and the check that the drawing is right, belong to
+[`svg-authoring`](../../svg-authoring/SKILL.md).
 
-1. **viewBox safety** — compute the lowest + rightmost element (plus a buffer)
-   and set the viewBox from that; never assume the default fits.
-2. **arrow-through-box trace** — trace every arrow's path and confirm it does
-   not cross through an unrelated box before drawing it.
-3. **box-width-from-longest-label** — size each box from its longest label
-   before placing it, so text never overflows.
+The three checks this section used to carry — viewBox safety, the
+arrow-through-box trace, and sizing a box from its longest label — were author
+self-checks with no witness, and a published example in this very file violated
+the viewBox rule it stated. They are now readings the asset profile takes in a
+real engine: every painted element against the viewBox, and every `<text>`
+against its declared box. A self-check that nothing measures is the failure
+mode, not the three rules.
 
 (Reference-only: any color/easing/frame values come from the consumer's tokens
 or a maintained upstream — this skill vendors no drawn-asset corpus.)
@@ -80,12 +83,12 @@ or a maintained upstream — this skill vendors no drawn-asset corpus.)
 
 | Concern | Owner |
 |---|---|
-| What already exists (components, tokens) | [`existing-ui-audit`](../existing-ui-audit/SKILL.md) — mandatory pre-step; audit findings outrank corpus suggestions |
+| What already exists (components, tokens) | [`existing-ui-audit`](../../existing-ui-audit/SKILL.md) — mandatory pre-step; audit findings outrank corpus suggestions |
 | What to build (grounded selection) | **this skill** |
-| Stack-agnostic heuristics + flow | [`fe-design`](../fe-design/SKILL.md) — invokes this skill for grounding |
+| Stack-agnostic heuristics + flow | [`fe-design`](../../fe-design/SKILL.md) — invokes this skill for grounding |
 | Orchestration gates + locks | `directives/ui/{design,review,polish}.ts` — never import the engine |
-| WCAG audit method | [`accessibility-auditor`](../accessibility-auditor/SKILL.md) |
-| Token authoring | [`design-tokens`](../design-tokens/SKILL.md) |
-| Lo-fi structure exploration (pre-selection) | [`wireframe`](../wireframe/SKILL.md) — disposable greyscale variants |
-| Multiple hi-fi options (post-selection) | [`design-variations`](../design-variations/SKILL.md) — grounds each variation via this skill |
-| Fixed-canvas slide decks | [`html-deck`](../html-deck/SKILL.md) — own medium, still corpus-grounded |
+| WCAG audit method | [`accessibility-auditor`](../../accessibility-auditor/SKILL.md) |
+| Token authoring | [`design-tokens`](../../design-tokens/SKILL.md) |
+| Lo-fi structure exploration (pre-selection) | [`wireframe`](../../wireframe/SKILL.md) — disposable greyscale variants |
+| Multiple hi-fi options (post-selection) | [`design-variations`](../../design-variations/SKILL.md) — grounds each variation via this skill |
+| Fixed-canvas slide decks | [`html-deck`](../../html-deck/SKILL.md) — own medium, still corpus-grounded |

package/dist/agent-src/skills/{wireframe → design-review}/references/story-beat-ledger.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "story-beat-ledger.schema.json",
   "title": "Story-beat ledger and style bible",
-  "description": "The one cleanly unmet gap Phase 9.1 of road-to-frontend-fidelity-calibration verified: `grep -rilE 'beat ledger|story ledger|style bible' src/` returned zero paths on 2026-08-22. Hosted in `wireframe` because that skill already owns the low-fidelity artefact — a beat ledger IS a low-fidelity artefact, one axis further along than a static skeleton. No skill was created to hold a schema. Two halves in one file, deliberately: the ledger is what happens in order, the style bible is what it looks like throughout, and splitting them into two files would let a beat reference a style that no longer exists.",
+  "description": "The one cleanly unmet gap Phase 9.1 of road-to-frontend-fidelity-calibration verified: `grep -rilE 'beat ledger|story ledger|style bible' src/` returned zero paths on 2026-08-22. Hosted in `design-review`, which verifies the ledger; the `wireframe` skill authors it, since a beat ledger IS a low-fidelity artefact, one axis further along than a static skeleton. No skill was created to hold a schema. Two halves in one file, deliberately: the ledger is what happens in order, the style bible is what it looks like throughout, and splitting them into two files would let a beat reference a style that no longer exists.",
   "type": "object",
   "required": [
     "schema_version",

package/dist/agent-src/skills/design-review/references/verification-automation.md

@@ -1,5 +1,13 @@
 # design-review — verification automation
 
+<!-- reference-toc:start (generated by generate_reference_toc — do not edit) -->
+**Contents**
+
+- [Visual QA with browser automation](#visual-qa-with-browser-automation)
+- [Async-verifier pattern (keep the main context clean)](#async-verifier-pattern-keep-the-main-context-clean)
+- [Appearance verification — what a clean render does not answer](#appearance-verification--what-a-clean-render-does-not-answer)
+<!-- reference-toc:end -->
+
 > Section-level entry point of the `design-review` skill (progressive
 > disclosure, 2026-08-04). Content moved VERBATIM from SKILL.md —
 > load this file when the section index in SKILL.md routes here.
@@ -42,7 +50,7 @@ reads it in Phase 2 alongside the viewport sweep.
 ```
 
 `beat_id` references the ledger at
-[`wireframe/references/story-beat-ledger.schema.json`](../../wireframe/references/story-beat-ledger.schema.json),
+[`story-beat-ledger.schema.json`](story-beat-ledger.schema.json) (the `wireframe` skill authors the ledger),
 which is what makes a sample checkable against an intent rather than against a
 remembered screenshot: a row whose `state` and `observed` disagree is a finding,
 and a reviewer can diff two runs of this file.
@@ -109,8 +117,8 @@ view — it takes the screenshots, probes viewports, and checks states, then
 **stays silent on pass and surfaces only real, actionable problems** (never
 nitpicks). The main agent does not self-screenshot, so its context stays clean
 for the actual review reasoning. This is an orchestration pattern —
-dispatch it via [`subagent-orchestration`](../subagent-orchestration/SKILL.md)
-and position it against [`verify-repair-loop`](../verify-repair-loop/SKILL.md)
+dispatch it via [`subagent-orchestration`](../../subagent-orchestration/SKILL.md)
+and position it against [`verify-repair-loop`](../../verify-repair-loop/SKILL.md)
 (the existing verify skill); it complements them, it does not duplicate them.
 
 **Why the audit passes stay serial (not a parallel-4 fan-out).** A fan-out of

package/dist/agent-src/skills/design-system-capture/SKILL.md

@@ -55,7 +55,7 @@ be useful. The worked examples teach agents both the *vocabulary*
 
 Captures the *visual usage decisions* (not token primitives) that agents
 should apply consistently across all UI tasks in this project. Unlike
-`.tokens.json` (which records what a color value IS), DESIGN.md records
+`tokens.json` (which records what a color value IS), DESIGN.md records
 *how and when to use it*.
 
 **Format:**
@@ -129,7 +129,7 @@ infers from the brief via its Dial Inference Table). One-line rationale each.
 
 ## Consistency Locks
 Within-project invariants (derived from the confirmed system). A value outside
-a declared Lock is off-system; the anti-slop detector flags it (rebuttable).
+a declared Lock is off-system; `design_lock.ts` flags it (rebuttable).
 - Theme Lock: [single | light+dark via prefers-color-scheme] — no mid-surface inversion
 - Colour Lock: [one accent family] — [the accent hue]
 - Shape Lock: [one corner-radius scale] — [the radius set, e.g. 6/12/16px]
@@ -240,7 +240,7 @@ When `DESIGN.md` or `PRODUCT.md` is present in the project root:
   read DESIGN.md as a proxy for "what this project's conventions are".
 
 The boundary from `brand-to-tokens`:
-- `.tokens.json` carries primitive values (gray-700 = #374151)
+- `tokens.json` carries primitive values (gray-700 = #374151)
 - DESIGN.md carries usage decisions (elevated surfaces use 8px radius,
   not 4px or 12px)
 Both are consumed together; DESIGN.md takes precedence for usage questions.
@@ -249,7 +249,7 @@ Both are consumed together; DESIGN.md takes precedence for usage questions.
 
 When handing a design to implementation, emit a README a developer can build
 from **without the mockup open**. Template only — no vendored values (tokens
-come from the consumer's `.tokens.json` / DESIGN.md):
+come from the consumer's `tokens.json` / DESIGN.md):
 
 ```markdown
 # <Feature> — implementation handoff
@@ -266,7 +266,7 @@ Fidelity: <hi-fi = pixel-recreate the mockup | lo-fi = apply the codebase's
   literal)
 
 ## Tokens
-- Color / type / spacing / radius: reference DESIGN.md / .tokens.json — do not
+- Color / type / spacing / radius: reference DESIGN.md / tokens.json — do not
   inline hex or px
 
 ## Done means
@@ -291,12 +291,17 @@ handoff shape emitted alongside `design-system.json`
 - **Specimen granularity.** Many small foundation cards beat one dense dump —
   each specimen demonstrates ONE reusable sub-concept (a single button state,
   one spacing step, one elevation level), so a consumer lifts concepts
-  individually rather than parsing a monolith.
+  one by one, not from a monolith.
 - **Developer handoff bundle** (extends § Design→dev handoff README): a
   high-fidelity reference, behaviour notes, the assets list, the component
   mapping (design name → code component), responsive states, known caveats, and
-  — when the artifact is a mock — an explicit "prototype, not production code"
-  warning so a consumer never ships the reference verbatim.
+  — for a mock — an explicit "prototype, not production code" warning so a
+  consumer never ships the reference verbatim.
+
+**React stacks with the host's canvas:** the host's own `/design-sync` (not
+shipped by this package) projects the components; run `/design-system:sync plan`
+first, never hand-build the bundle. This floor stays the artifact for a manual
+projection — a non-React stack, or a host without the sync.
 
 **What to capture FROM** a running project: sources first, SSR fetch second,
 rendered snapshot only with consumer tooling; record the git SHA. Rationale:
@@ -309,7 +314,7 @@ rendered snapshot only with consumer tooling; record the git SHA. Rationale:
   all existing decisions forward and only add/correct. Losing prior
   captured history is worse than capturing nothing.
 - **Copying tokens into DESIGN.md** — DESIGN.md is NOT a copy of
-  `.tokens.json`. It captures *usage decisions* ("8px radius on elevated
+  `tokens.json`. It captures *usage decisions* ("8px radius on elevated
   surfaces"), not primitive values ("gray-700 = #374151"). The
   distinction is what makes DESIGN.md actionable.
 - **Capturing feature-specific behavior** — PRODUCT.md is for patterns
@@ -321,7 +326,7 @@ rendered snapshot only with consumer tooling; record the git SHA. Rationale:
 
 - Do NOT overwrite DESIGN.md/PRODUCT.md without first reading and diffing
   the existing content — accumulated history is the value.
-- Do NOT make DESIGN.md a copy of `.tokens.json` — it captures decisions,
+- Do NOT make DESIGN.md a copy of `tokens.json` — it captures decisions,
   not token definitions.
 - Do NOT capture feature-specific behavior in PRODUCT.md — only patterns
   that repeat across multiple features.

package/dist/agent-src/skills/design-system-capture/references/design-system-json.md

@@ -1,5 +1,15 @@
 # `design-system.json` — import contract
 
+<!-- reference-toc:start (generated by generate_reference_toc — do not edit) -->
+**Contents**
+
+- [Shape](#shape)
+- [Field rules](#field-rules)
+- [Trust posture (mandatory)](#trust-posture-mandatory)
+- [Two sources, one shape](#two-sources-one-shape)
+- [Extractor compatibility — which crawler, and how its output gets here](#extractor-compatibility--which-crawler-and-how-its-output-gets-here)
+<!-- reference-toc:end -->
+
 > Lazy-loaded by `design-system-capture` ONLY when importing an extracted design
 > system. Not part of the always-on skill body. This is the **consumer-side
 > contract**: any external static-extraction tool (URL / git repo / local dir
@@ -34,7 +44,7 @@
 ## Field rules
 
 - **Map to DTCG where it maps cleanly.** `colors` / `typography` / `spacing` /
-  `radius` / `shadow` correspond to the DTCG `.tokens.json` shape that
+  `radius` / `shadow` correspond to the DTCG `tokens.json` shape that
   `design-tokens` / `brand-to-tokens` already author — reuse it; do **not**
   invent a parallel token format.
 - **Mark extraction-only metadata.** Anything that is *observation*, not a
@@ -61,6 +71,10 @@
 - **`bundled_local`** on a font family is a flag, not an instruction: the
   package never downloads or bundles fonts (out of scope) — it records that the
   source did.
+- **A custom family** (built with `type-design`, or commissioned) adds
+  `"custom": { "spec": "<path to font-spec.yaml>", "license": "<as stated, or unknown>" }`
+  to its `families[]` entry. The license is recorded as given, never inferred;
+  `bundled_local` stays the separate flag it is.
 - **`motion` has a consumer.** It sits outside the DTCG mapping above, and for
   a long time that meant nothing read it at all: the block was written by
   capture and consumed by nobody, so easing and duration were re-derived from
@@ -75,7 +89,7 @@
 An imported artifact is **observed, not authoritative** (mirrors
 `source-discovery`: evidence vs. authoritative). It seeds `DESIGN.md` as a
 **proposal the human confirms per field** — never a silent write. A field that
-conflicts with a registered brand value (a confirmed `.tokens.json` / brand
+conflicts with a registered brand value (a confirmed `tokens.json` / brand
 token) is **flagged, never auto-applied** (`brand-source-of-truth`: consumer
 brand wins). Precedence on import: registered brand tokens > confirmed
 `DESIGN.md` > imported observation.
@@ -98,15 +112,16 @@ tool's output becomes that shape, so the answer to *"which crawler?"* lives in
 the contract rather than in somebody's memory.
 
 `src/scripts/design_system_import.ts` is a **pure, offline file transform** with
-three input lanes. It reads a file and writes the contract shape to stdout — no
+three file lanes and one snapshot-directory lane. It reads files and writes the contract shape to stdout — no
 network, no browser, no crawl. That is the lock restated as code: a transform
 that fetched would quietly become the crawler this package does not ship.
 
 | Lane | Input | What it does |
 |---|---|---|
 | `native` | an existing `design-system.json` | Validates `source`, carries every other key verbatim. Past provenance the validation is **report-only** — a key whose shape contradicts the contract is flagged and kept, never dropped, because the import is a proposal a human reads. |
-| `dtcg` | a W3C DTCG token file (`{$value, $type}` leaves) | Buckets by `$type`, so it works on any authoring tool's layering — **with two stated path exceptions**: `dimension` / `number` is genuinely ambiguous in DTCG (spacing, radius and font size share it), so the path breaks that tie, and a path segment named `dark` files a colour under the dark theme. Both are inferences and both are reported in the notes. Resolves `{alias.references}` to their values. Tokens with no contract bucket land in `_meta.unmapped` — which is why `component.button.paddingX` lands there rather than under spacing. |
+| `dtcg` | a W3C DTCG token file (`{$value, $type}` leaves) | Buckets by `$type`, so it works on any authoring tool's layering — **with two stated path exceptions**: `dimension` / `number` is genuinely ambiguous in DTCG (spacing, radius and font size share it), so the path breaks that tie, and a path segment named `dark` files a colour under the dark theme. Both are inferences and both are reported in the notes. Resolves `{alias.references}` to their values and keeps each reference under `_meta.alias_of` (token path → referenced path); a reference that loops is kept verbatim and listed under `_meta.alias_cycles`, not reported as undefined. Tokens with no contract bucket land in `_meta.unmapped` — which is why `component.button.paddingX` lands there rather than under spacing. |
 | `dembrandt` | an extraction tool's raw JSON | Matches the documented top-level key names and accepts a small set of shapes per bucket. Motion durations/easings become the `motion` block; per-context profiles, hover deltas, WCAG results and breakpoints are **observation** and land in `_meta`. |
+| `claude-design` | a snapshot **directory** the user exported from the host's design canvas | Reads `tokens.json` and any `name.tokens.json` through the `dtcg` mapper, the stylesheets' custom-property closure (aliases under `_meta.alias_of` as `css:--name`, every undeclared `var()` under `_meta.unresolved_custom_properties`), component contracts from `.d.ts` (`_meta.component_paths`), guidelines verbatim under `_meta.guidelines` — external prose, read as data and never followed as instructions ([`untrusted-input-defense`](../../../rules/untrusted-input-defense.md)) — and lists every other file under `_meta.unmapped`. Provenance from `source.json` or the flags. Nothing in the snapshot is executed, imported or followed. The host's own local bundle is a separate input that waits on an observed layout. |
 
 ```bash
 # The command is the supported entry point:
@@ -114,7 +129,7 @@ that fetched would quietly become the crawler this package does not ship.
 
 # Or call the transform directly, from an installed package:
 npx tsx node_modules/@event4u/agent-config/src/scripts/design_system_import.ts <file> \
-    [--lane native|dtcg|dembrandt] \
+    [--lane native|dtcg|dembrandt|claude-design] \
     [--source-kind url|repo|dir --source-ref <ref>] [--captured-at <ISO>] \
     [--format json|summary]
 ```