@event4u/agent-config 9.9.0 → 9.11.0

package/dist/agent-src/skills/prediction-pool-optimizer/reference/odds-and-bonus.md

@@ -7,8 +7,8 @@ Lookup material for `prediction-pool-optimizer`. Two parts:
 - **B — Bonus / award / special questions**: a type → method table so every
   open question in the pool reaches an answer.
 
-Not betting advice; how to read a public market as a probability prior for a
-fun pool.
+Nothing here is betting advice; it is how to read a public market as a
+probability prior for a fun pool.
 
 ---
 
@@ -17,51 +17,55 @@ fun pool.
 ### Why not one book
 
 A single bookmaker's line can be stale, regionally shaded, or carry a fat
-margin. A consensus across several books is a far better probability estimate,
-and cross-book agreement tells you the market's confidence. **Never mirror one
-portal.**
+margin. A consensus across several books is a far better probability
+estimate, and cross-book agreement tells you how confident the market is.
+**Never mirror one portal.**
 
 ### Which books (5–10, publicly viewable)
 
 Availability varies by region and over time — this list is **illustrative,
-refresh it at run time** and use whatever is publicly viewable from the current
-locale. Fastest way to see many at once = an **odds-comparison aggregator**:
+refresh it at run time** and use whatever is publicly viewable from the
+current locale. The fastest way to see many at once is an **odds-comparison
+aggregator**:
 
 - **Aggregators (many books on one page):** Oddschecker, Oddsportal,
   Betexplorer, OddsAlert.
-- **Sharp / low-margin reference books (weight higher):** Pinnacle, Betfair
-  Exchange (an exchange = closest thing to a true market price).
+- **Sharp / low-margin reference books (weight higher):** Pinnacle,
+  Betfair Exchange (an exchange = the closest thing to a true market price).
 - **Large recreational books (weight lower):** bet365, Bwin, William Hill,
   Unibet, Betano, Tipico, Interwetten, bet-at-home, 888sport, Winamax.
 
-Aim for **5–10** spanning both groups. If only recreational books are viewable,
-say so in the run note — the consensus is then softer.
+Aim for **5–10** spanning both groups. If only recreational books are
+viewable, say so in the run note — the consensus is then softer.
 
 ### The recipe
 
-1. **Per market, per book**: collect decimal odds (1X2, exact-score, each
-   outright, each special/award market a bonus question needs).
-2. **De-vig each book independently.** For 1X2 decimal odds `o_H, o_D, o_A`,
-   raw implied probs `1/o` sum to `>1` (overround); normalise:
-   `p_i = (1/o_i) / Σ(1/o)`. Per book — never aggregate raw odds.
-3. **Sharpness-weight and combine.** Sharp books > recreational; **weighted
-   mean** — or **trimmed median** when books disagree a lot (robust to one
-   outlier). A defensible weighting:
+1. **Per market, per book**: collect the decimal odds (1X2, exact-score,
+   each outright, each special/award market a bonus question needs).
+2. **De-vig each book independently.** For a 1X2 market with decimal odds
+   `o_H, o_D, o_A`, the raw implied probs are `1/o`; they sum to `>1` (the
+   overround). Normalise: `p_i = (1/o_i) / Σ(1/o)`. Do this **per book** —
+   never aggregate raw odds.
+3. **Sharpness-weight and combine.** Give sharp books more weight than
+   recreational ones, then take a **weighted mean** — or a **trimmed median**
+   when books disagree a lot (robust to one outlier). A simple, defensible
+   weighting:
 
    - Pinnacle / Betfair Exchange → weight 3
    - large recreational books → weight 1
-   - aggregator "average" column → weight 1 (already blends many)
-
-   `p_consensus = Σ(wᵢ · pᵢ) / Σwᵢ` per outcome, then re-normalise the outcome
-   set to sum to 1.
-4. **Outlier handling.** One book far off the others = **flag, not truth**:
-   check for a reason (priced-in injury, stale line) before moving the
-   consensus. Cross-book agreement = signal; one disagreeing book = investigate.
+   - aggregator "average" column → weight 1 (it already blends many)
+
+   `p_consensus = Σ(wᵢ · pᵢ) / Σwᵢ`, computed per outcome, then re-normalise
+   the outcome set to sum to 1.
+4. **Outlier handling.** If one book is far off the others, that is a **flag,
+   not a truth**: check for a reason (priced-in injury, stale line) before
+   moving the consensus. Cross-book agreement = signal; one disagreeing book
+   = investigate.
 5. **Healthy weighting overall.** The consensus is a **prior**. Blend it with
-   the per-sport model (Poisson / Gaussian) and override only with *current*
-   info the market has not absorbed (confirmed lineup, late injury,
-   suspension, manager change). The pool answer is EV under the rules on top of
-   this blended probability — the market informs, it does not dictate.
+   the per-sport model (Poisson / Gaussian) and only override with *current*
+   info the market has not yet absorbed (confirmed lineup, late injury,
+   suspension, manager change). The pool answer is EV under the rules on top
+   of this blended probability — the market informs, it does not dictate.
 
 ### Worked mini-example (1X2)
 
@@ -81,27 +85,27 @@ the per-match EV grid — not either book's raw number.
 ## B. Bonus / award / special questions — type → method
 
 Every entry on the step-1 checklist gets an answer. Match the question to a
-row; real market where one exists, a **labelled** model estimate where none
-does. Optimize each on expected points under its point weight.
+row; use a real market where one exists, a **labelled** model estimate where
+none does. Optimize each on expected points under its point weight.
 
 | Question type | Example | Method |
 |---|---|---|
 | **Outright winner** | "Who wins the tournament?" | Outright "to win" market, consensus per A; or `poisson_sim.ts` `title_pct`. EV-max under the question's points. |
 | **Group / stage** | "Who wins group X?", "Who advances?" | "To win group" / "to qualify" markets; or `advance_pct` from the simulator. |
 | **Finalists / matchup** | "Who reaches the final?" | "To reach final" market per team; simulator pairing is approximate — prefer the market. |
-| **Top scorer (player)** | "Tournament top scorer?" | "Top goalscorer" outright market, consensus per A; EV-max player (favourite unless rarity scoring rewards a longer shot). |
-| **Team of the top scorer** | "Which team supplies the top scorer?" | Aggregate per-player top-scorer probabilities **by team** (sum each squad); pick the highest-summed team. |
-| **Most assists / cards / etc.** | "Most yellow cards?" | Matching special market if offered; else a labelled model estimate (discipline/aggression proxy). |
-| **Binary special** | "Will there be a red card in match X?" | De-vig the yes/no line to a probability; EV-max side under the points. No market → labelled base-rate estimate. |
-| **Over / under total** | "Over/under total goals / cards?" | De-vig the totals line at the offered threshold; higher-EV side. |
-| **Exact stat** | "How many goals in the final?" | Market totals distribution if available; else per-match Poisson on consensus xG. State the model. |
+| **Top scorer (player)** | "Tournament top scorer?" | "Top goalscorer" outright market, consensus per A; pick the EV-max player (favourite unless rarity scoring rewards a longer shot). |
+| **Team of the top scorer** | "Which team supplies the top scorer?" | Aggregate per-player top-scorer probabilities **by team** (sum each squad's players); pick the team with the highest summed probability. |
+| **Most assists / cards / etc.** | "Most yellow cards?" | The matching special market if offered; else a labelled model estimate (e.g. discipline/aggression proxy). |
+| **Binary special** | "Will there be a red card in match X?" | De-vig the yes/no line to a probability; pick the EV-max side under the points. No market → labelled base-rate estimate. |
+| **Over / under total** | "Over/under total goals / cards?" | De-vig the totals line at the offered threshold; pick the side with higher EV. |
+| **Exact stat** | "How many goals in the final?" | Market totals distribution if available; else the per-match Poisson on consensus xG. State the model. |
 
 ### Rules for bonus answers
 
 - **Answer all of them.** The output's bonus table must have the same number
-  of rows as the step-1 checklist. A missing row = a dropped question.
-- **Market first, labelled model second.** Prefer a real special market; none
-  exists → derive from a stated model and mark `Source: model`.
+  of rows as the step-1 checklist. A missing row is a dropped question.
+- **Market first, labelled model second.** Prefer a real special market;
+  when none exists, derive from a stated model and mark `Source: model`.
 - **Rarity rules apply here too.** Under quote/rarity scoring, a
   plausible-but-rarer answer can out-score the favourite when
   `payout × probability` is higher — same EV logic as the scores.

package/dist/agent-src/skills/project-analysis-core/SKILL.md

@@ -131,11 +131,11 @@ Check:
 
 ## Knowledge capture (`convention_detected` events)
 
-An architecture-map or stack finding that recurs (naming convention,
-module boundary, layering rule) is worth persisting for the team.
+An architecture map or stack finding that recurs (a naming convention,
+a module boundary, a layering rule) is worth persisting for the team.
 Append to the knowledge intake instead of leaving it in the one-off
-analysis output — applies to every `project-analysis-*` specialist
-this skill hands off to:
+analysis output (applies to every `project-analysis-*` specialist this
+skill hands off to, not just this one):
 
 ```bash
 npx tsx node_modules/@event4u/agent-config/src/scripts/emit_knowledge_event.ts --type convention_detected \

package/dist/agent-src/skills/project-analysis-hypothesis-driven/SKILL.md

@@ -17,7 +17,7 @@ packs:
 Use this skill when:
 
 * There is a concrete issue to explain
-* Multiple root → are plausible
+* Multiple root causes are plausible
 * The system spans several layers
 * A shallow single-explanation answer would be risky
 * `universal-project-analysis` or `bug-analyzer` routes here
@@ -33,7 +33,7 @@ Do NOT use when:
 * Never stop at the first plausible explanation
 * Code, docs, and evidence beat intuition
 * Rejected hypotheses matter
-* Multiple interacting → are common
+* Multiple interacting causes are common
 * Uncertainty must be marked explicitly
 
 ## Procedure
@@ -95,7 +95,7 @@ Ask:
 
 * does this fully explain the behavior?
 * what remains unexplained?
-* could multiple → interact?
+* could multiple causes interact?
 * does contradictory evidence exist?
 
 If anything major remains unexplained: continue analysis, do not present a final conclusion yet.

package/dist/agent-src/skills/project-analysis-react/SKILL.md

@@ -117,7 +117,7 @@ Check:
 ## Gotcha
 
 * React bugs often come from stale state, not broken logic.
-* Missing deps in hooks are one of the most common root causes.
+* Missing dependencies in hooks are one of the most common root causes.
 * Overusing memoization can make code harder to reason about without solving real problems.
 
 ## Do NOT

package/dist/agent-src/skills/project-analysis-symfony/SKILL.md

@@ -44,7 +44,7 @@ Do NOT use when:
 ### 1. Confirm Symfony version and app shape
 
 Check: `composer.lock`, `composer.json`, Symfony packages/components, PHP version, environment config structure.
-Validate: Symfony version is explicit, major bundles/components are identified, env-specific config layout is known.
+Validate: Symfony version is explicit, major bundles/components are identified, environment-specific config layout is known.
 
 ### 2. Analyze kernel and container boot
 

package/dist/agent-src/skills/project-analysis-zend-laminas/SKILL.md

@@ -54,7 +54,7 @@ Check:
 
 * merge order surprises
 * missing overrides
-* env config mismatches
+* environment config mismatches
 * heavy bootstrap logic
 
 ### 3. Analyze ServiceManager behavior
@@ -106,7 +106,7 @@ Check:
 ## Gotcha
 
 * Many Zend/Laminas issues are caused by config order and service resolution, not controller code.
-* Shared services and legacy migration remnants can create cross-request or env-specific bugs.
+* Shared services and legacy migration remnants can create cross-request or environment-specific bugs.
 * Old project behavior may depend on historical bootstrap side effects that are easy to miss.
 
 ## Do NOT

package/dist/agent-src/skills/prompt-engineering-patterns/SKILL.md

@@ -144,7 +144,7 @@ Production prompts handle their own failure cases:
 
 ## Provenance
 
-- Adopted from: an external reference (MIT, © 2025 an external reference) — restructured into a decision-framework shape; vendor `prompt_optimizer` Python snippets dropped (project-specific to an external reference).
+- Adopted from: an external reference (internal provenance, redacted) — restructured into a decision-framework shape; source-specific vendor Python snippets dropped.
 - Cross-linked: [`prompt-optimizer`](../prompt-optimizer/SKILL.md), [`refine-prompt`](../refine-prompt/SKILL.md), [`mcp-builder`](../mcp-builder/SKILL.md), [`async-python-patterns`](../async-python-patterns/SKILL.md).
 - Provenance registry: `agents/settings/contexts/skills-provenance.yml` (entry: `prompt-engineering-patterns`).
 - Iron-Law floor: `verify-before-complete`, `skill-quality`, `non-destructive-by-default`.

package/dist/agent-src/skills/prompt-validator/SKILL.md

@@ -20,14 +20,14 @@ install:
 # prompt-validator
 
 > Deterministic pre-spend gate: collect **every** prompt a video run is
-> about to send (all scenes, all blocks), cross-check against each other
-> and against the run's locked facts (character lock, vocal map, model
-> capabilities), **block with a specific error** on contradiction.
-> Skills are deterministic — a multi-scene batch fails by
-> *contradiction*, not drift: two prompts that cannot both be true of
-> the same video (AI-council convergence, 2026-06-06). One blocked
-> batch costs a re-edit; one rendered contradiction costs the whole
-> spend.
+> about to send (all scenes, all blocks), cross-check them against each
+> other and against the run's locked facts (character lock, vocal map,
+> model capabilities), and **block with a specific error** on
+> contradiction. Skills are deterministic — the failure mode of a
+> multi-scene batch is not drift, it is *contradiction*: two prompts
+> that cannot both be true of the same video (AI-council convergence,
+> 2026-06-06). One blocked batch costs a re-edit; one rendered
+> contradiction costs the whole spend.
 
 ## When to use
 
@@ -41,16 +41,16 @@ install:
 
 Do NOT use when:
 
-- Only a single scene exists (nothing to contradict) — per-scene checks
-  in `video-director` cover internal consistency.
-- Pure preview with no approval intent — validate when the batch is
-  about to be gated, not on every draft keystroke.
+- Only a single scene exists (nothing to contradict) — the per-scene
+  checks in `video-director` already cover internal consistency.
+- The run is pure preview with no approval intent — validate when the
+  batch is about to be gated, not on every draft keystroke.
 
 ## Inputs
 
 - `<project>/script.md` — every `## Scene N` (duration, mood, action,
   camera, dialogue).
-- Every rendered scene prompt (eight-block image/video prompts from
+- Every rendered scene prompt (the eight-block image/video prompts from
   `video-director` / blueprint JSON), in scene order.
 - `<project>/character.json` — when present, the locked identity
   (subject, palette, wardrobe, prop, seed).
@@ -64,20 +64,20 @@ Do NOT use when:
 
 Read every scene's prompt blocks into one table:
 `scene → {style, subject, environment, action, camera, lens, lighting,
-mood, duration, aspect, dialogue/singer}`. Prompt missing or
-unparseable → **block**: `scene N: prompt missing/unreadable` — an
-incomplete batch already contradicts the script.
+mood, duration, aspect, dialogue/singer}`. A scene whose prompt is
+missing or unparseable → **block**: `scene N: prompt missing/unreadable`
+— an incomplete batch is already a contradiction with the script.
 
 ### 2. Style consistency
 
-`style` block must agree across all scenes — one look per video unless
-the script *names* an intentional break (e.g. "dream sequence").
+The `style` block must agree across all scenes — one look per video
+unless the script *names* an intentional break (e.g. "dream sequence").
 
 - Conflicting render families (`photorealistic` vs `cel-shaded` /
   `claymation` / `watercolor`) with no scripted break →
   `style mismatch: scene 3 'photorealistic' vs scene 7 'cel-shaded'`.
 - Conflicting era/grade tokens (`1970s film grain` vs `clean digital
-  HDR`) → same error shape, name both scenes + both tokens.
+  HDR`) → same error shape, name both scenes and both tokens.
 
 ### 3. Character consistency (character mode)
 
@@ -88,7 +88,7 @@ match the lock:
   `blue jacket`) → `character mismatch: scene 5 'blue jacket' vs lock
   'red coat'`.
 - A scene inventing a second recurring subject the script never cast →
-  flag — uncast identities break continuity AND the likeness gate.
+  flag it — uncast identities break continuity AND the likeness gate.
 - **Lip-sync ownership:** a scene with a `dialogue:` line must name the
   vocal map's singer for that line — wrong mouth on wrong words is the
   render-money-burning failure (`media-sync-ground-truth`). A `"?"`
@@ -100,21 +100,21 @@ match the lock:
   with no scripted transition → `continuity: scene 4 'noon sun' →
   scene 5 'starry night' within the same chorus`.
 - Impossible camera/action pairs (`locked-off tripod` + `whip pan`),
-  (`underwater` + `desert dust`) → name scene + both tokens.
-- Duration / aspect vs. model envelope: any scene outside
-  `[min_duration, max_duration]` or with an unlisted aspect → block
-  with the violated bound (defense-in-depth after `song-to-script`
-  Step 1 — hand-edited prompts re-open this hole).
+  (`underwater` + `desert dust`) → name scene + the two tokens.
+- Duration / aspect vs. the model envelope: any scene outside
+  `[min_duration, max_duration]` or with an aspect the model does not
+  list → block with the violated bound (defense-in-depth after
+  `song-to-script` Step 1 — hand-edited prompts re-open this hole).
 
 ### 5. Verdict
 
 - **Zero findings** → emit `prompt-validator: N scenes, no
-  contradictions`, hand the batch to the preview gate.
+  contradictions` and hand the batch to the preview gate.
 - **Any finding** → **block the gate**. Report every finding (not just
   the first), each as `class: scene(s) + conflicting values + fix
-  hint`. Operator (or calling command) fixes prompts, re-runs the
-  validator — never "approve anyway" past a contradiction; an
-  intentional break gets *scripted* (named in `script.md`), which
+  hint`. The operator (or the calling command) fixes the prompts and
+  re-runs the validator — never "approve anyway" past a contradiction;
+  an intentional break gets *scripted* (named in `script.md`), which
   legitimizes it on the next pass.
 
 ## Output format
@@ -135,20 +135,20 @@ verdict: BLOCKED (2 contradictions) — fix and re-run
 
 ## Gotchas
 
-- **An intentional style break is scripted, not waved through.** Only a
-  break `script.md` names is accepted; "operator said it's fine in
-  chat" does not survive to the next run.
-- **Re-validate after every hand-edit.** One edited scene can
+- **An intentional style break is scripted, not waved through.** The
+  validator only accepts a break that `script.md` names; "the operator
+  said it's fine in chat" does not survive to the next run.
+- **Re-validate after every hand-edit.** A single edited scene can
   contradict five untouched ones; the batch is the unit, not the scene.
 - **`verified: false` capability entries still gate.** Blocking on a
   documented-best-effort bound beats rendering past a real one; the
-  report names the unverified flag — override by editing the manifest,
-  never by skipping the check.
+  report names the unverified flag so the operator can override by
+  editing the manifest, never by skipping the check.
 
 ## Do NOT
 
-- Do NOT auto-fix prompts — report and block; the fix is the operator's
-  (or calling skill's) edit, visible in the diff.
+- Do NOT auto-fix prompts — report and block; the fix is the
+  operator's (or calling skill's) edit, visible in the diff.
 - Do NOT validate only changed scenes — always the full batch.
 - Do NOT soften a contradiction into a warning — contradictions block;
   only consistency passes.
@@ -157,8 +157,8 @@ verdict: BLOCKED (2 contradictions) — fix and re-run
 
 ## See also
 
-- [`/video:from-song`](../../commands/video/from-song.md) — invokes this
-  before the unified storyboard/cost preview gate (Step 8).
+- [`/video:from-song`](../../commands/video/from-song.md) —
+  invokes this before the unified storyboard/cost preview gate (Step 8).
 - [`video-director`](../video-director/SKILL.md) — produces the prompts
   this skill cross-checks.
 - [`character-consistency`](../character-consistency/SKILL.md) — the

package/dist/agent-src/skills/quality-tools/SKILL.md

@@ -31,20 +31,20 @@ false OR MISSING (THE DEFAULT). DO NOT ASK WHETHER TO RUN THEM.
 THE USER RUNS THEM MANUALLY. REMOTE CI IS THE AUTHORITATIVE GATE.
 ```
 
-Toolchains differ per language and project, often unknown to the agent —
-discovery + execution burns time and tokens. Under the default, exactly
-three triggers justify running a quality tool:
-
-1. **Explicit ask this turn** — user says so or invokes `/fix quality`.
-2. **Concrete CI failure** — remote pipeline reports a failing check;
-   run exactly that failing check to reproduce and fix (`/fix:ci` is
-   the canonical flow).
-3. **New-gate carve-out** — change itself introduces a NEW CI gate,
-   smoke test, or test file; must run once locally to be proven.
-
-`quality.local_auto_run: true` restores legacy autonomous behaviour
-(run pipeline when work is ready for verification). When runs are
-suppressed, completion message says *"quality gates delegated to
+Toolchains differ per language and project and are often unknown to the
+agent — discovering and running them burns time and tokens. Under the
+default, exactly three triggers justify running a quality tool:
+
+1. **Explicit ask this turn** — the user says so or invokes `/fix quality`.
+2. **Concrete CI failure** — the remote pipeline reports a failing
+   check; run exactly that failing check to reproduce and fix it
+   (`/fix:ci` is the canonical flow).
+3. **New-gate carve-out** — the change itself introduces a NEW CI gate,
+   smoke test, or test file; it must run once locally to be proven.
+
+`quality.local_auto_run: true` restores the legacy autonomous behaviour
+(run the pipeline when work is ready for verification). When runs are
+suppressed, the completion message says *"quality gates delegated to
 remote CI"* — never that the tools passed.
 
 ## Language detection
@@ -61,7 +61,7 @@ If both PHP and JS/TS files changed → run **both** pipelines.
 
 ## Related rules and guidelines
 
-- `verify-before-complete` rule — no pass claims without fresh output; suppressed runs surfaced as "delegated to remote CI", never claimed
+- `verify-before-complete` rule — no pass claims without fresh output; suppressed runs are surfaced as "delegated to remote CI", never claimed
 - `php-coding` rule → PHPStan section — inline ignores, PHPDoc rules
 - `contexts/execution/verification-mechanics.md` — Gate zero (`local_auto_run`) + timing when `true` (quality tools ONCE at the end, not after each edit)
 - [`testing-anti-patterns`](../testing-anti-patterns/SKILL.md) and

package/dist/agent-src/skills/react-shadcn-ui/SKILL.md

@@ -128,17 +128,41 @@ declared version:
 
 ## Registry & MCP awareness (opt-in)
 
-Default path = bundled `scripts/shadcn_add.ts` + `components.json`; works on most projects, stays default. Modern registry model is OPT-IN — no round-trips on every op. JSON-schema + namespace detail lazy-loaded from [`reference/registry.md`](reference/registry.md); read only on this path.
-
-**`shadcn info --json` handshake** — run as grounding step WHEN `components.json` declares custom/namespaced `registries`, OR theme-alignment in scope. Returns framework / aliases / installed components / icon lib / base settings. NOT a forced first action on every `add` (over-gating, low ROI vanilla).
-
-- **Precedence:** prefer live `shadcn info --json`; fall back to `state.ui_audit.shadcn_inventory` (existing-ui-audit) when CLI/MCP unreachable. Live read wins.
-
-**Namespaced installs** — `@ns/item` resolves via the `registries` map to a `registry-item.json` URL (see reference). `view @ns/item` before `add`. Honour `registryDependencies` (install the graph, incl. version-pinned GitHub refs `acme/ui/button#v1.2.0`); keep propose-never-silent-run + `--dry-run`.
-
-**Token-aware scaffolding** — `registry-item.json` `cssVars` (OKLCH light/dark/theme) → align to project tokens (`info --json` / `components.json` / `state.ui_audit.design_tokens`); never inject the default shadcn neutral theme (flagged anti-slop tell: default theme + Inter + neutral grays).
-
-**MCP path (opt-in)** — shadcn MCP server: browse / search-across-registries / install-with-NL over MCP; wire per [`mcp`](../mcp/SKILL.md). Alternative to CLI, never a hard dep. Decision: CLI = default + universal; MCP = opt-in when configured; registry-JSON literacy underpins both.
+The default path is the bundled `scripts/shadcn_add.ts` CLI wrapper + reading
+`components.json` — it works on most shadcn projects and stays the default.
+The modern registry model is an **opt-in enhancement**; do not add round-trips
+to every component op. Full JSON-schema + namespace detail is lazy-loaded from
+[`reference/registry.md`](reference/registry.md) — read it only on this path,
+not on the vanilla `add`.
+
+**`shadcn info --json` handshake** — run it as the grounding step **when** the
+project declares custom/namespaced `registries` in `components.json`, OR when
+theme-alignment is in scope. It returns framework, aliases, installed
+components, icon lib, and base settings. Do NOT make it a forced first action
+on every `add` (over-gating; low ROI on vanilla projects).
+
+- **Precedence vs our own audit:** prefer a live `shadcn info --json` when
+  available; fall back to `state.ui_audit.shadcn_inventory` (from
+  `existing-ui-audit`) when the CLI/MCP is not reachable. They answer the same
+  question (project context) — the live read wins.
+
+**Namespaced installs** — `@ns/item` resolves via the `registries` map to a
+`registry-item.json` URL (see the reference). Run `view @ns/item` to inspect
+the JSON before `add`. Honour `registryDependencies` (install the graph,
+including version-pinned GitHub refs like `acme/ui/button#v1.2.0`); keep
+propose-never-silent-run + `--dry-run`.
+
+**Token-aware scaffolding** — when a `registry-item.json` carries `cssVars`
+(OKLCH, light/dark/theme), align additions to the project's existing tokens
+(from `info --json` / `components.json` / `state.ui_audit.design_tokens`) —
+**never inject the default shadcn neutral theme** (it is a flagged anti-slop
+tell: default theme + Inter fallback + neutral grays).
+
+**MCP path (opt-in)** — the shadcn MCP server exposes browse / search-across-
+registries / install-with-natural-language over MCP; configure per the
+[`mcp`](../mcp/SKILL.md) skill. It is an alternative to the CLI, never a hard
+dependency. Decision note: **CLI path = default + universal; MCP path = opt-in
+when the user has it configured; registry-JSON literacy underpins both.**
 
 ## Procedure: render a shadcn/ui component for the design brief
 
@@ -251,17 +275,29 @@ current state on the next polish round.
 
 ## Taste Dials
 
-`DESIGN.md` `## Taste Dials` → honour: Variance → layout-family spread + asymmetry; Motion → animation budget + reduced-motion posture; Density → spacing scale + info-per-viewport. Absent → follow brief's inferred dials.
+When `DESIGN.md` declares `## Taste Dials`, honour them: Variance → layout-family spread + asymmetry tolerance; Motion → animation budget + reduced-motion posture; Density → spacing scale + information-per-viewport. Absent → follow the design brief's inferred dials.
 
 ## Component workshop (Storybook) — when the library is large enough
 
-Generic "isolate + document reusable components" principle → [`fe-design`](../fe-design/SKILL.md) § Component Architecture; this is the React carve-out for the tool-specific part.
-
-- **When it pays off** — real, growing shared-component library (more than a handful of reused primitives, multiple consumers, ongoing UI work): Storybook makes each component discoverable, reviewable in isolation, reused not re-invented. **Skip** for a small surface of one-offs — setup + maintenance not worth it yet.
-- **Story per reusable primitive, not per screen** — a story covers a component + its states (default / loading / empty / error / dark), mirroring the Step 3 state-coverage matrix. Screens composed, not story-fied.
-- **Reuse the token layer** — stories render under the same semantic tokens + `.dark` class; never hardcode a preview theme (Step 2 token discipline).
-- **A11y in-workshop** — run the a11y addon so isolation catches contrast / role / focus before the component reaches a screen.
-- Do NOT let stories drift from the component API — a story props-drilling values the component no longer accepts is stale documentation; keep beside the component, update in the same change.
+The generic "isolate + document reusable components" principle lives in
+[`fe-design`](../fe-design/SKILL.md) § Component Architecture; this is the React
+carve-out for the tool-specific part.
+
+- **When it pays off** — a real, growing shared-component library (roughly: more
+  than a handful of reused primitives, multiple consumers, ongoing UI work).
+  Storybook makes each component discoverable, reviewable in isolation, and
+  reused instead of re-invented. **Skip it** for a small surface of one-off
+  components — the setup + maintenance is not worth it yet.
+- **Story per reusable primitive, not per screen** — a story covers a component
+  and its states (default / loading / empty / error / dark), mirroring the
+  Step 3 state-coverage matrix. Screens are composed, not story-fied.
+- **Reuse the token layer** — stories render under the same semantic tokens +
+  `.dark` class; never hardcode a preview theme (same token discipline as Step 2).
+- **A11y in-workshop** — run the a11y addon so the isolation catches contrast /
+  role / focus issues before the component reaches a screen.
+- Do NOT let stories drift from the component API — a story that props-drills
+  values the component no longer accepts is stale documentation; keep them beside
+  the component and update them in the same change.
 
 ## Do NOT
 

package/dist/agent-src/skills/react-shadcn-ui/reference/registry.md

@@ -1,36 +1,36 @@
 # shadcn registry & namespace reference
 
 > Lazy-loaded by `react-shadcn-ui` ONLY on the registry/MCP path (custom or
-> namespaced registries, or theme-alignment). Not in the always-on skill body —
-> zero token cost on the vanilla `shadcn add` path.
+> namespaced registries, or theme-alignment work). Not part of the always-on
+> skill body — zero token cost on the vanilla `shadcn add` path.
 
 ## `registry-item.json` — the self-describing component unit
 
-Each item is a JSON doc the agent reads before scaffolding — never guesses
-paths, deps, or tokens.
+A registry serves each item as a JSON document the agent reads before
+scaffolding, so it never guesses paths, deps, or tokens.
 
 - `name` — item id.
 - `type` — one of: `registry:ui`, `registry:component`, `registry:block`,
   `registry:hook`, `registry:lib`, `registry:theme`, `registry:style`,
   `registry:page`, `registry:file`, `registry:base`, `registry:item`.
-- `dependencies` / `devDependencies` — npm packages.
-- `registryDependencies` — other items to pull first (the dependency graph):
-  built-in (`"button"`), namespaced (`"@acme/input"`), GitHub
+- `dependencies` / `devDependencies` — npm packages to install.
+- `registryDependencies` — other registry items to pull first (the dependency
+  graph). Forms: built-in (`"button"`), namespaced (`"@acme/input"`), GitHub
   (`"acme/ui/button#v1.2.0"`), URL, or local path.
-- `files[]` — each `{ path, type, target }`; `target` uses the project alias
-  placeholders (`~`, `@ui/`, `@lib/`, `@hooks/`) from `components.json`.
-- `cssVars` — tokens scoped by mode: `theme` (font/radius), `light`, `dark`,
-  OKLCH. **Align to the project's tokens; do not inject the default neutral
-  theme** (anti-slop C1/C5/T7).
-- `css` — raw `@layer` / `@utility` / `@keyframes` / `@plugin`.
+- `files[]` — each `{ path, type, target }`; `target` uses the project's alias
+  placeholders (`~`, `@ui/`, `@lib/`, `@hooks/`) resolved from `components.json`.
+- `cssVars` — design tokens scoped by mode: `theme` (font/radius), `light`,
+  `dark`. Values are OKLCH. **Align these to the project's existing tokens, do
+  not inject the default neutral theme** (anti-slop C1/C5/T7).
+- `css` — raw `@layer` / `@utility` / `@keyframes` / `@plugin` directives.
 
-Scaffold order: read item → install npm `dependencies` → resolve
-`registryDependencies` (recurse) → write `files[]` to alias targets → merge
-`cssVars` into the project token layer (reconcile, don't overwrite).
+Scaffold order: read the item → install npm `dependencies` → resolve
+`registryDependencies` (recurse) → write `files[]` to the alias targets →
+merge `cssVars` into the project's token layer (reconcile, do not overwrite).
 
 ## Namespaced registries
 
-`components.json` maps a namespace → URL template under `registries`:
+`components.json` maps a namespace to a URL template under `registries`:
 
 ```json
 {
@@ -44,16 +44,18 @@ Scaffold order: read item → install npm `dependencies` → resolve
 }
 ```
 
-- Resolution: `@ns/name` → look up `@ns` → substitute `{name}` (+ optional
-  `{style}`). Reference regex: `^(@[a-zA-Z0-9](?:[a-zA-Z0-9-_]*[a-zA-Z0-9])?)\/(.+)$`.
-- Auth registries: per-registry `headers` with `${ENV_VAR}` — never inline a
-  token; read from the environment.
-- Namespace space is **decentralized** — no central collision authority; the
-  `components.json` map is the project's source of truth.
+- Resolution: `@ns/name` → look up `@ns` → substitute `{name}` (and optional
+  `{style}`) into the URL template. The reference resolution regex is
+  `^(@[a-zA-Z0-9](?:[a-zA-Z0-9-_]*[a-zA-Z0-9])?)\/(.+)$`.
+- Auth registries: per-registry `headers` with `${ENV_VAR}` interpolation —
+  never inline a token; read it from the environment.
+- The namespace space is **decentralized** — no central authority resolves
+  collisions; the `components.json` map is the project's source of truth.
 
 ## CLI surface (the agent drives these)
 
-`init` · `add [item|@ns/item]` · `search @ns -q <q>` · `view @ns/item` (inspect
-JSON before install) · `docs [item] --json` · `diff` (drift vs updated
-registry) · `info --json` (project context — see the SKILL handshake) · `build`
-(publish). Inspect with `view` before `add` — evidence before action.
+`init` · `add [item|@ns/item]` · `search @ns -q <q>` · `view @ns/item`
+(inspect JSON before install) · `docs [item] --json` · `diff` (drift vs the
+updated registry) · `info --json` (project context — see the SKILL handshake)
+· `build` (publish a registry). Inspect with `view` before `add` — evidence
+before action.

package/dist/agent-src/skills/readme-writing-package/SKILL.md

@@ -262,8 +262,8 @@ npx <package> init --tools=windsurf         # Windsurf
 Pair the catalog with a separate "Global install" subsection (same flags
 plus `--global`) and an "Other commands" subsection. Reference example:
 [`README.md § Pick specific AIs`](../../../README.md#pick-specific-ais) in
-this repository. Inspiration:
-[`an external reference suite § Installation`](https://github.com/an external reference suite#installation).
+this repository — or any well-structured external skill README that
+lists per-target install commands in a flat catalog.
 
 Use the catalog when the package's primary install action varies by
 platform; use a matrix table (Tool / Rules / Skills / Commands) for