@event4u/agent-config 7.4.0 → 8.0.0

package/docs/guidelines/design-antipatterns.md

@@ -26,6 +26,7 @@ hierarchy, reduced-motion, focus indicator) is in `lint_design_quality`
 |---|---|---|
 | **Guidance** | Subjective taste — Visual / Typography / Color / Layout / Copy patterns, override judgment, the originality self-test | this catalog |
 | **Enforcement** | Objective floors — Q1–Q6 (WCAG contrast, font-size, line-length, reduced-motion, heading hierarchy, focus indicator) as exit-code-2 CI | `lint_design_quality` |
+| **Detection** | Deterministic *aesthetic-tell* flags (P0–P3, rebuttable via DESIGN.md) — the pattern-detectable subset of the entries below | `lint_design_slop` |
 | **Audit method** | HOW to test WCAG (keyboard nav, ARIA, screen-reader procedures) | `accessibility-auditor` |
 | **Stack manifestation** | Concrete Tailwind class / hex bans, shadcn defaults | `tailwind-engineer`, `react-shadcn-ui` (per `framework-neutrality-in-generic-skills`) |
 | **Register** | Brand mode vs product mode — which patterns apply | `docs/guidelines/design-modes.md` |
@@ -34,6 +35,31 @@ This catalog is the canonical *index*; it states the pattern stack-agnostically.
 The stack-specific bans live in the apply skills and link back here by entry ID.
 The objective floors are cited from the linter, never re-eyeballed by an agent.
 
+**Deterministic detector backing** (`lint_design_slop`, dependency-free, zero
+runtime token cost): a pattern-detectable subset of these entries now has a
+deterministic rule that `design-review` cites instead of re-deriving — `V1`,
+`V3`, `V6`, `C2`, `C5`, `T4`, `T6`, `T7`, `L4`, `L8`, `M2`, `M4`, `CP1`, `CP2`,
+`CP5`, plus the **Consistency Locks & layout caps** `V8`, `C6`, `L9`, `L10`
+(rule ids `slop-<id>-*`, registry in `src/scripts/design_slop_rules.ts`). These
+are **flags / rebuttable presumptions**, never hard blocks — a consumer
+`DESIGN.md` that declares the pattern as intentional suppresses the flag. The
+entries needing structural or aesthetic judgment (e.g. `T3` icon-tile stack,
+`L2` three-identical-card grid, `V2` glassmorphism intent, `C7` theme-inversion)
+stay agent-judgment-only and are deliberately **not** in the detector.
+
+### Consistency Locks & layout caps (taste-dials roadmap)
+
+Within-project invariants + repetition caps. Override = declare the value in
+`DESIGN.md` (`## Consistency Locks` / a brutalist or uniform-grid style note).
+
+| # | Pattern | Why it reads as AI-generated | Override condition |
+|---|---|---|---|
+| V8 | Shape Lock — ≥ 4 distinct corner-radius scales in one surface | A fragmented radius system reads as no shape decision | Declare the radius scale in `DESIGN.md`; a genuine multi-tier scale documents each tier |
+| C6 | Colour Lock — ≥ 3 distinct saturated accent hue families | No single accent identity; reads as default-palette sprawl | Brand genuinely uses a multi-accent system, declared in `DESIGN.md` / `brand-to-tokens` |
+| C7 | Theme inversion — a light island mid-dark surface (or vice versa) not driven by the theme system | Mid-surface inversion breaks the theme rhythm | Intentional inverted callout with a documented reason — **judgment-only**, design-review calls it (deterministic detection is unreliable) |
+| L9 | Section monotony — ≥ 8 sections, < 4 distinct layout families | Uniform section rhythm collapses scannability | Deliberately uniform grid (e.g. a gallery), declared as such |
+| L10 | Zigzag — > 2 consecutive image-left/text-right two-column sections | The alternating-zigzag landing-page tell | A genuinely sequenced walkthrough where alternation aids comprehension |
+
 ---
 
 ## Visual
@@ -114,6 +140,7 @@ The objective floors are cited from the linter, never re-eyeballed by an agent.
 | CP2 | Marketing buzzwords: streamline, empower, supercharge, world-class, enterprise-grade, seamlessly, robust, leverage | These words carry no information; an AI-slop test: replace each with nothing — the sentence still communicates the same thing | No override; if a word can be deleted without loss, delete it |
 | CP3 | Aphoristic manufactured contrast ("We don't do X. We do Y." / "Not just A, but B.") | A generated sentence rhythm that sounds like brand writing but carries no specificity | Aphoristic copy is legitimate when the contrast reveals a genuine product distinction; test by asking whether the Y side says something concrete |
 | CP4 | "Theater" framing — copy that announces what the product does without saying how or why | "The platform for modern teams." communicates nothing; it is content-shaped noise | Every tagline must pass the "so what" test: can a skeptic follow it with "but how?" and get a concrete answer? |
+| CP5 | Emoji-decoration in UI markup — 🚀/✅/🎉 prepending headings, buttons, list items, or CTAs (`🚀 Get Started`) | Performative-enthusiasm coating; the default-startup-template tell. No emoji is better than decorative emoji | Brand/`DESIGN.md` declares a systematic emoji strategy, or the emoji is functional (status indicator, category marker tied to real meaning) |
 
 ---
 
@@ -137,6 +164,14 @@ these. The rest are agent self-checks.
 | Q10 | Body background: avoid OKLCH L 0.84–0.97, C < 0.06 (cream/sand) unless brand-defined | Color space calculation | Agent self-check |
 | Q11 | Padding floors: ≥ 8px (inline elements), ≥ 16px (card/panel bodies) | Computed padding | Agent self-check |
 | Q12 | Justified text only with CSS hyphenation (`hyphens: auto`) | Presence of `text-align: justify` without `hyphens` | Agent self-check |
+| Q13 | Outward-artifact hygiene: no system internals — absolute workspace paths, skill/tool names, generator traces, config keys — in comments, metadata, or EXIF of deliverables that leave the workspace (HTML decks, prototypes, exports), unless the user asks for build provenance | Comment/metadata scan of the emitted artifact | Agent self-check |
+
+Q13 is **output hygiene only** — it never restricts chat-side transparency to
+the operator (what skills/tools ran stays fully answerable in conversation).
+Converged via council (claude-sonnet-4-5 + gpt-4o, 2026-07-06): shared floor
+here, referenced by artifact-producing skills, deliberately not a PII-rule
+extension. Deterministic detection in `lint_design_slop` (path/trace grep) is
+possible but deferred until a real incident.
 
 ---
 

package/docs/guidelines/design-canon.md

@@ -0,0 +1,62 @@
+# Design Canon — named-systems grounding index
+
+> Lazy-loaded reference. Pull this when a brief names (or a project's
+> `components.json`/deps signal) a published design system, type, or colour
+> reference — so the design is **grounded in named canon**, not improvised.
+> Used by `design-intelligence`; cross-linked from `typography-system`,
+> `iconography`, `design-tokens`, `brand-to-tokens`, `icon-consistency`.
+
+This is a thin **index** — names, one-line summaries, and a "pull this when"
+trigger. It deliberately does **not** bundle the multi-megabyte specs; fetch
+the live spec only when the trigger fires (the canonical URLs below are the
+fetch targets). Precedence (per `brand-source-of-truth`): **consumer brand
+tokens > confirmed session decisions > named canon (this index) > generated
+corpus.** Canon is a gap-filler, never an override of a registered brand value.
+
+## Design systems
+
+| System | Signature traits (one-line) | Pull this when |
+|---|---|---|
+| **Material 3** (Google) | Dynamic colour from a seed (HCT), tonal palettes, elevation by tint not shadow, expressive motion (emphasized easing). | brief says "Material" / "Android"; deps `@mui/material`, `@angular/material`, `react-native-paper`. Spec: m3.material.io |
+| **Apple HIG** | Platform-native clarity/deference/depth, SF type + Dynamic Type, system materials/vibrancy, restrained motion, large touch targets. | brief targets iOS/iPadOS/macOS/visionOS, "native Apple feel". Spec: developer.apple.com/design |
+| **Fluent 2** (Microsoft) | Neutral-forward, acrylic/reveal materials, Segoe/Fluent type ramp, depth via subtle shadow, enterprise density. | brief says "Fluent"/"Windows"/"Office"; deps `@fluentui/*`. Spec: fluent2.microsoft.design |
+| **Carbon** (IBM) | 2px grid, IBM Plex type, strong data-viz system, productive vs expressive themes, accessibility-first. | brief says "Carbon"/"IBM"/data-heavy enterprise; deps `@carbon/*`. Spec: carbondesignsystem.com |
+| **Ant Design** | Dense enterprise/admin, comprehensive component set, token-based theming (v5), wireframe-driven. | brief says "Ant"/admin console/CRUD-heavy; deps `antd`. Spec: ant.design |
+| **Atlassian** | Product-suite consistency, ADS tokens, calm neutral + bold primary, strong empty/loading patterns. | brief says "Atlassian"/Jira-like; deps `@atlaskit/*`. Spec: atlassian.design |
+
+Grounding rule: surface the matching one-liner, then **offer to pull the live
+spec** before committing to the system's conventions. Never reproduce a brand
+book's marks; ground against the *system's* documented principles.
+
+## Typography craft (foundry + theory)
+
+A one-line index — point `typography-system` here; do not inline the content.
+
+- **Theory:** Butterick's *Practical Typography* (practicaltypography.com — line-length, measure, hierarchy rules), *Thinking with Type*.
+- **Calibration / "in use":** Typewolf, Fonts In Use (real pairings, not defaults).
+- **Quality foundries** (beyond the AI-default fonts the anti-slop catalog T7 flags): Klim, Lineto, Colophon, Commercial Type, Grilli Type; libre: League of Movable Type, Google Fonts (chosen deliberately, not reflexively).
+- Pull when: a brief calls for a distinctive type voice, or to escape the Inter/Roboto/Geist default.
+
+## Colour references
+
+Names + when-to-use — not the palettes themselves.
+
+- **Accessibility / contrast:** WCAG contrast checkers (e.g. APCA, WebAIM) — verify text/non-text contrast (ties to `lint_design_quality` Q1 + anti-slop C4). Pull on any colour decision that must clear AA.
+- **Culturally-specific palettes:** Nippon Colors (traditional Japanese), Chinese Colors — pull when the brand/audience is culturally situated and a Western default palette would read as generic.
+- **Systematic palette tools:** the design systems above ship their own token palettes — prefer the system's palette over an ad-hoc picker when a system is in play.
+
+## Icon systems
+
+Each design system ships a matching icon set — prefer it when that system is in
+play (consistency over novelty, per `icon-consistency`): **Material Symbols**
+(Material 3, variable weight/fill/grade), **SF Symbols** (Apple HIG, weight-
+matched to SF text), **Fluent UI System Icons** (Fluent), **Carbon icons**
+(Carbon). Outside a named system, the `iconography` skill resolves a single
+Iconify set (Lucide / Phosphor / Heroicons / Tabler) — pick one and stay in it.
+Pull when: choosing or auditing an icon library.
+
+## See also
+
+- `docs/guidelines/design-antipatterns.md` — the anti-slop catalog (T7 default-font tell, C1/C5 palette tells) this canon helps you escape.
+- `brand-source-of-truth` / `brand-consistency` — the precedence this index obeys.
+- `design-intelligence` — the consumer that surfaces these on a brief signal.

package/docs/guidelines/design-modes.md

@@ -89,6 +89,12 @@ not minimal white, not brutalist → everyone picks terminal dark").
 
 **Both modes:** `design-antipatterns` (always pull), `design-review` (with anti-slop check)
 
+**Exploration front-ends (either mode, before committing):**
+`wireframe` (lo-fi structure exploration, disposable greyscale) →
+`design-variations` (3+ substantive hi-fi options, basic→bold, single file
+with tweak controls). Decks are their own medium → `html-deck`
+(fixed-canvas slides), not the responsive-UI routing above.
+
 ## See also
 
 - `docs/guidelines/design-antipatterns.md` — the slop-tell catalog; brand mode especially needs this

package/docs/guidelines/php/general.md

@@ -77,7 +77,15 @@ $data = ['id' => 1, 'name' => 'John'];
 createUser(...$data);
 ```
 
-## DocBlocks
+## Comments and DocBlocks
+
+A code comment earns its place only by stating a constraint the code
+cannot show — a non-obvious invariant, a workaround for a known bug, a
+hidden dependency. Never write comments that narrate ("added for X",
+"this calls Y"), repeat the next line, or justify the change to the
+reviewer. Full clause: [`code-clarity.md § Comment discipline`](../code-clarity.md#comment-discipline--state-a-constraint-not-a-narration).
+
+DocBlocks:
 
 - **Only** use DocBlocks to explain complex logic or when type hints are insufficient
 - **Must** add DocBlock for iterable types: `@param array<int, MyObject> $items`

package/docs/guidelines/php/php-coding-patterns.md

@@ -55,6 +55,13 @@ Default: `getters_setters`. See the `eloquent` skill for the full reference tabl
 - Always write tests in **Pest**, not PHPUnit class syntax — unless the user explicitly asks for PHPUnit.
 - Pest tests in `tests/Unit/` automatically use `UnitTestCase` as the base class (configured in `tests/Pest.php`).
 
+## Code comments
+
+A code comment earns its place only by stating a constraint the code
+cannot show. Never write comments that narrate, repeat the next line,
+or justify the change to the reviewer. Full clause:
+[`code-clarity.md § Comment discipline`](../code-clarity.md#comment-discipline--state-a-constraint-not-a-narration).
+
 ## PHPDoc
 
 - Only add PHPDoc when type hints are insufficient (e.g. generic arrays: `@param array<int, MyObject> $items`).

package/docs/guides/cross-repo-retrieval.md

@@ -27,7 +27,7 @@ siblings you have not decided on yet. A sibling only becomes reachable once you
 Under the hood:
 
 ```bash
-python3 scripts/cross_repo_retrieve.py "OrderApiContract" [--path-scope 'src/*.ts'] [--max-chunks 8]
+./scripts-run src/scripts/cross_repo_retrieve "OrderApiContract" [--path-scope 'src/*.ts'] [--max-chunks 8]
 ```
 
 You get a bounded table — `source_repo · path · freshness · why` — drawn only from opted-in

package/docs/guides/frontend-design-corpus-refresh.md

@@ -28,9 +28,9 @@ recall/precision must be re-measured.
 2. **Run the live trigger-eval** (token spend — interactive, gated):
 
    ```bash
-   task setup-evals            # once: bootstrap .venv with the pinned anthropic SDK
+   
    task install-anthropic-key  # once: install ~/.event4u/agent-config/anthropic.key
-   .venv/bin/python3 src/scripts/skill_trigger_eval.py \
+   ./scripts-run src/scripts/skill_trigger_eval \
      --skill <skill> --output /tmp/<skill>-eval.json
    ```
 

package/docs/guides/local-analytics.md

@@ -47,14 +47,14 @@ response bodies).
 
 ```bash
 # Render the last 30 days as markdown
-python3 packages/core/installer/python/workspace_analytics.py show
+./agent-config analytics show
 
 # Last 24 h, JSON
-python3 packages/core/installer/python/workspace_analytics.py show \
+./agent-config analytics show \
     --window 24h --format json
 
 # Filter to one role
-python3 packages/core/installer/python/workspace_analytics.py show \
+./agent-config analytics show \
     --role tradesperson --format csv
 ```
 
@@ -108,7 +108,7 @@ rm -rf ~/.event4u/agent-config/workspace/analytics/
 Or prune the rolling window manually:
 
 ```bash
-python3 packages/core/installer/python/workspace_analytics.py prune
+./agent-config analytics prune
 # → pruned 47 event(s)
 ```
 

package/docs/guides/skill-discovery.md

@@ -19,7 +19,7 @@ up `roles.active_role` from `.agent-settings.yml`.
 Under the hood the command runs:
 
 ```bash
-python3 scripts/skill_discovery.py --role sales
+./scripts-run src/scripts/skill_discovery --role sales
 ```
 
 ## 2. Read the `why` column

package/docs/guides/skill-preview.md

@@ -48,7 +48,7 @@ This skill will walk these steps:
 - Write the standard template
 - Regenerate the index
 
-Declared command: `python3 scripts/adr/regenerate_index.py`
+Declared command: `./scripts-run src/scripts/adr/regenerate_index`
 ```
 
 Add `--technical` for the raw frontmatter + numbered step list.

package/docs/hook-payload-capture.md

@@ -26,7 +26,7 @@ cd /path/to/agent-config
 # Confirm the dispatcher is wired in this project (idempotent — safe to rerun).
 # Replace <platform> with cursor / cline / windsurf / gemini as appropriate
 # when you reach that platform's section.
-python3 scripts/install.py --<platform>
+npx @event4u/agent-config install --<platform>
 
 # Confirm the trampoline + project-scope hooks file landed.
 ./agent-config hooks:status | grep -E "^[ ✓✅⚠️❌·] (cursor|cline|windsurf|gemini)"
@@ -71,7 +71,7 @@ archive conversations.
 
 ### Cursor (~5 min)
 
-- **Install:** `python3 scripts/install.py --cursor` (project) or
+- **Install:** `npx @event4u/agent-config install --cursor` (project) or
   `--cursor-user-hooks` (covers every project you open).
 - **Restart:** quit Cursor (Cmd+Q on macOS), then relaunch from the
   shell where you exported `AGENT_HOOK_CAPTURE_DIR` so the env var
@@ -89,7 +89,7 @@ archive conversations.
 
 ### Cline (~5 min)
 
-- **Install:** `python3 scripts/install.py --cline` (project) or
+- **Install:** `npx @event4u/agent-config install --cline` (project) or
   `--cline-user-hooks` (user-scope, covers every workspace).
 - **Restart:** in VS Code or JetBrains, run "Developer: Reload
   Window" (Cmd+Shift+P) from a terminal where the env is exported.
@@ -108,7 +108,7 @@ archive conversations.
 
 ### Windsurf (~5 min)
 
-- **Install:** `python3 scripts/install.py --windsurf` (project) or
+- **Install:** `npx @event4u/agent-config install --windsurf` (project) or
   `--windsurf-user-hooks` (user-scope at `~/.codeium/windsurf/hooks.json`).
 - **Restart:** quit Cascade fully, then relaunch from the shell with
   the env exported. The `pre_user_prompt` event fires on every turn —
@@ -126,7 +126,7 @@ archive conversations.
 
 ### Gemini CLI (~5 min)
 
-- **Install:** `python3 scripts/install.py --gemini` (project) or
+- **Install:** `npx @event4u/agent-config install --gemini` (project) or
   `--gemini-user-hooks` (user-scope at `~/.gemini/settings.json`).
 - **Restart:** Gemini CLI is invoked per command — no daemon to
   restart. Just open a new shell with `AGENT_HOOK_CAPTURE_DIR`
@@ -179,7 +179,7 @@ After pasting and flipping the checkbox:
 ./scripts-run src/scripts/check_portability
 
 # Tests still green.
-python3 -m pytest tests/hooks/ -q
+node node_modules/.bin/vitest run tests/scripts/hooks/ -q
 
 # Optional: regenerate the dashboard if the archived roadmap's
 # checkbox change should bubble up. Iron Law from

package/docs/install-friction-report.md

@@ -0,0 +1,66 @@
+---
+status: template — awaiting sessions (no real data yet)
+study: install-friction (B9)
+recruits_target: 3
+---
+
+# Install-friction report (B9)
+
+> **Template — not yet run.** This file carries the Gate-C read for the wedge
+> install. It holds **no real data** until ≥ 3 external Laravel/TS developers
+> have completed the study per
+> [`agents/recruit-sessions/_install-friction-runbook.md`](../agents/recruit-sessions/_install-friction-runbook.md).
+> Do not cite the placeholder numbers below as findings.
+
+## What this measures
+
+Can an external developer — not on the maintainer team, no prior exposure —
+install the `production-validator` wedge and reach first value (a real verdict
+on their own code) in **< 60 s**, unaided, without abandoning? That is the
+Gate-C signal. Method: observed, timed, wedge-only (see the runbook).
+
+## Per-recruit results
+
+> One row per recruit. `TTFV` = time-to-first-value in seconds ("—" if
+> abandoned). `outcome` ∈ completed · completed-with-rescue · abandoned.
+> Real names never appear (R1/R2/R3); raw notes stay private with the recording.
+
+| recruit | stack | TTFV (s) | outcome | abandonment point | top friction |
+|---|---|---|---|---|---|
+| R1 | _tbd_ | _tbd_ | _tbd_ | _tbd_ | _tbd_ |
+| R2 | _tbd_ | _tbd_ | _tbd_ | _tbd_ | _tbd_ |
+| R3 | _tbd_ | _tbd_ | _tbd_ | _tbd_ | _tbd_ |
+
+## Aggregate
+
+| metric | value | Gate-C threshold |
+|---|---|---|
+| Median TTFV | _tbd_ s | ≤ 60 s |
+| Abandonment rate | _tbd_ % | ≤ 20 % |
+| Clean completions (no rescue) | _tbd_ / _n_ | — |
+
+## Top-3 friction points
+
+> Ranked by how many recruits hit each. Each cites the redacted verbatim moment
+> that named it (timestamp against the private recording).
+
+1. _tbd_ — hit by _N_/_n_ recruits. Quote: _tbd_. Fix: _tbd_.
+2. _tbd_
+3. _tbd_
+
+## Gate-C verdict
+
+```
+PASS  ⇔  median TTFV ≤ 60 s  AND  abandonment rate ≤ 20 %.
+FAIL  →  iterate on the wedge install before finalizing C2. Do not ship a failed wedge.
+```
+
+- **Verdict:** _tbd (PASS / FAIL)_ — filled once the aggregate is real.
+- On **FAIL**, the top-3 friction points above are the exact iteration targets;
+  re-run the study after the fix. A failed gate is a finding, not a stopper.
+
+## Provenance
+
+- Protocol: [`agents/recruit-sessions/_install-friction-runbook.md`](../agents/recruit-sessions/_install-friction-runbook.md).
+- Consent + redaction: [`agents/recruit-sessions/README.md`](../agents/recruit-sessions/README.md) § "Consent + redaction policy".
+- Recordings + raw per-recruit notes: private (not in-repo), per the redaction policy.

package/docs/installation.md

@@ -681,7 +681,7 @@ Options:
 ```
 
 The underlying stages keep their own CLI surfaces:
-`bash scripts/install.sh --help` and `python3 scripts/install.py --help`.
+`bash scripts/install.sh --help` and `npx @event4u/agent-config install --help`.
 
 ---
 

package/docs/maintainers/optional-media-deps.md

@@ -0,0 +1,50 @@
+# Optional media tooling (B8 recorded demos)
+
+The package ships **no bundled binaries** and never installs system tools
+silently (`missing-tool-handling`). A small set of tools is *optional* — needed
+only for the B8 recorded proof-page demos, not for day-to-day maintenance.
+Install them **on demand**, when the check tells you to.
+
+## The tools
+
+| Tool | What it does |
+|---|---|
+| `asciinema` | Records a terminal session to a compact `.cast` file (timestamped JSON of what was typed + printed). Replayable / embeddable — no backend, fits the no-runtime floor. |
+| `agg` | Converts a `.cast` → animated GIF (asciinema's gif generator), for embedding a short run on the proof page. |
+
+## When you need them
+
+- Only for **B8** — recording a real wedge / skill run for the proof page.
+- Once B8 lands, its falsifiability lock regenerates each recording **in CI from
+  a real run**, so the CI job (and any maintainer refreshing a demo) needs them.
+- Nothing else in the suite uses terminal recording — this is not a daily tool.
+
+## Check before recording (never a silent install)
+
+```bash
+task check-media-deps
+```
+
+It detects `asciinema` + `agg`, and if either is missing prints the exact
+platform install command and exits non-zero — the same detect-and-instruct
+shape as the docker check in `taskfiles/mcp.yml`. It never installs anything
+for you.
+
+## Install (only when the check asks)
+
+| Platform | Command |
+|---|---|
+| macOS | `brew install asciinema agg` |
+| Linux | `pipx install asciinema` · `cargo install --locked agg` (or a release binary) |
+| Other | see each tool's own install docs |
+
+## Why not auto-install with the maintainer package
+
+Three reasons the base setup does **not** pull these in:
+
+1. **The suite's own floor** (`missing-tool-handling`) forbids silent system-binary installs — detect + prompt only.
+2. **Cross-platform fragility + surface** — `asciinema` (brew / pipx) and `agg` (brew / cargo / release binary) install differently per OS; a config package that brings in system binaries on setup is invasive.
+3. **YAGNI** — a single, gated feature does not justify a base-setup dependency.
+
+The `check-media-deps` gate gives every maintainer the same on-demand path
+without any of the above — which is exactly what "install on demand" means here.

package/docs/mcp-server.md

@@ -44,7 +44,7 @@ task mcp:setup            # maintainer / dev repo
 ./agent-config mcp:setup  # consumer projects (uses the package CLI wrapper)
 ```
 
-Either form creates `.venv-mcp/` (Python 3.11+), installs the `mcp` SDK, and
+Either form verifies that `tsx` + the server module are present and
 prints the client config snippet. Run once per checkout.
 
 If you do not have `task` or the CLI wrapper available:
@@ -60,8 +60,8 @@ task mcp:run            # maintainer / dev repo
 ./agent-config mcp:run  # consumer projects
 ```
 
-Both forms launch `python -m scripts.mcp_server` over stdio against the
-local `.venv-mcp/`. Use these for ad-hoc smoke tests; long-running clients
+Both forms launch the TypeScript MCP server over stdio via `tsx`. Use these for
+
 (Claude Desktop, Cursor, Zed, Continue) launch the server themselves via
 the config snippets below.
 
@@ -76,8 +76,8 @@ or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
 {
   "mcpServers": {
     "agent-config": {
-      "command": "/absolute/path/to/agent-config/.venv-mcp/bin/python",
-      "args": ["-m", "scripts.mcp_server"],
+      "command": "/absolute/path/to/agent-config/node_modules/.bin/tsx",
+      "args": ["/absolute/path/to/agent-config/src/scripts/mcp_server/__main__.ts"],
       "cwd": "/absolute/path/to/agent-config"
     }
   }
@@ -95,8 +95,8 @@ appear under the connector dropdown.
 {
   "mcpServers": {
     "agent-config": {
-      "command": "/absolute/path/to/agent-config/.venv-mcp/bin/python",
-      "args": ["-m", "scripts.mcp_server"],
+      "command": "/absolute/path/to/agent-config/node_modules/.bin/tsx",
+      "args": ["/absolute/path/to/agent-config/src/scripts/mcp_server/__main__.ts"],
       "cwd": "/absolute/path/to/agent-config"
     }
   }
@@ -112,8 +112,8 @@ appear under the connector dropdown.
   "context_servers": {
     "agent-config": {
       "command": {
-        "path": "/absolute/path/to/agent-config/.venv-mcp/bin/python",
-        "args": ["-m", "scripts.mcp_server"]
+        "path": "/absolute/path/to/agent-config/node_modules/.bin/tsx",
+        "args": ["/absolute/path/to/agent-config/src/scripts/mcp_server/__main__.ts"]
       },
       "settings": {}
     }
@@ -128,8 +128,8 @@ appear under the connector dropdown.
 ```yaml
 mcpServers:
   - name: agent-config
-    command: /absolute/path/to/agent-config/.venv-mcp/bin/python
-    args: ["-m", "scripts.mcp_server"]
+    command: /absolute/path/to/agent-config/node_modules/.bin/tsx
+    args: [/absolute/path/to/agent-config/src/scripts/mcp_server/__main__.ts]
     cwd: /absolute/path/to/agent-config
 ```
 
@@ -149,7 +149,6 @@ boots cleanly:
 | Symptom | Fix |
 |---|---|
 | Client shows no prompts | Confirm the `cwd` points at the repo root (where `dist/agent-src/` lives), not at `scripts/`. |
-| `ModuleNotFoundError: mcp` | Re-run `task mcp:setup`. The MCP runtime is isolated in `.venv-mcp/` — the project's base Python 3.9 deliberately does not see it. |
 | Stale prompts after editing | Hot-reload triggers on mtime; touch the file or reissue `resources/list`. |
 | Client refuses to start the server | Check the client's log for the full command. Most clients require **absolute** paths in `command` and `cwd`. |
 

package/docs/media/proof-demo.cast

@@ -0,0 +1,14 @@
+{"version":3,"term":{"cols":80,"rows":24},"timestamp":1783261474,"command":"bash internal/demo/proof-demo-commands.sh","env":{"SHELL":"/bin/zsh"}}
+[0.007, "o", "\r\n\u001b[1;36m$ task check-claims       # every public claim binds to resolvable evidence\u001b[0m\r\n"]
+[0.360, "o", "\u001b[32m   ✓ pass\u001b[0m\r\n\r\n"]
+[0.000, "o", "\u001b[1;36m$ task check-refs         # no broken internal references\u001b[0m\r\n"]
+[0.445, "o", "\u001b[32m   ✓ pass\u001b[0m\r\n"]
+[0.000, "o", "\r\n\u001b[1;36m$ task check-skill-gaps   # every known-limit cites a real witness test\u001b[0m\r\n"]
+[0.399, "o", "\u001b[32m   ✓ pass\u001b[0m\r\n"]
+[0.000, "o", "\r\n\u001b[1;36m$ task check-comparison   # every comparison-table pointer resolves\u001b[0m\r\n"]
+[0.359, "o", "\u001b[32m   ✓ pass\u001b[0m\r\n"]
+[0.001, "o", "\r\n\u001b[1;36m$ task build-proof-check  # the proof page is in sync with its sources\u001b[0m\r\n"]
+[0.399, "o", "\u001b[32m   ✓ pass\u001b[0m\r\n"]
+[0.000, "o", "\r\n"]
+[0.000, "o", "\u001b[1;32m✓ trust surface verified — reproduce any line on a fresh checkout.\u001b[0m\r\n"]
+[0.000, "x", "0"]

package/docs/migration/consumer-template-consumption-model.md

@@ -1,6 +1,6 @@
 # Consumer Template Consumption Model
 
-> Phase 1 Step 11 of `agents/roadmaps/road-to-typescript-only-scripts.md`.
+> Phase 1 Step 11 of `agents/roadmaps/archive/road-to-typescript-only-scripts.md`.
 > Question: how does `dist/agent-src/templates/scripts/` content reach a consumer
 > project — copied, referenced in place, or symlinked — and what does that mean
 > for the Phase 9 TS migration of the consumer-shipped scripts?

package/docs/migration/divergences/bench-stats-float-precision.md

@@ -52,7 +52,7 @@ to Python's exact-Fraction path.
 A full byte-identical fix requires replicating Python's `statistics._ss`
 exact-`Fraction` summation in TS (BigInt-rational arithmetic) across the
 shared bench-stats helpers. That is tracked as a follow-up
-(`agents/roadmaps/road-to-typescript-only-scripts.md`, bench-stats
+(`agents/roadmaps/archive/road-to-typescript-only-scripts.md`, bench-stats
 exact-fraction parity); it is non-trivial and out of scope for the sync that
 surfaced it.
 

package/docs/migration/node-floor.md

@@ -1,6 +1,6 @@
 # Node Floor Audit
 
-> Phase 1 Step 12 of `agents/roadmaps/road-to-typescript-only-scripts.md`.
+> Phase 1 Step 12 of `agents/roadmaps/archive/road-to-typescript-only-scripts.md`.
 > Decision: which Node.js floor the TS-only script suite supports, where it is
 > enforced, and what CI tests.
 

package/docs/migration/yaml-roundtrip-spike.md

@@ -1,6 +1,6 @@
 # YAML Round-Trip Spike — Verdict
 
-> Phase 1 Step 7 of `agents/roadmaps/road-to-typescript-only-scripts.md`.
+> Phase 1 Step 7 of `agents/roadmaps/archive/road-to-typescript-only-scripts.md`.
 > Originally framed as a "ruamel.yaml → npm `yaml`" risk. The survey below
 > shows that framing was wrong: there is **no ruamel usage anywhere** — the
 > comment-preserving round-trip layer is `src/scripts/sync_yaml_rt.py`, a

package/docs/personas.md

@@ -5,14 +5,14 @@ skill — not sub-agents, not execution modes. Each persona shapes
 *what* the agent looks for in a diff, plan, or artifact; the host
 identity, tools, and workflow stay the same.
 
-This page catalogs the **24 active personas** shipped with
-`event4u/agent-config` (6 core + 18 specialists), plus the 5
+This page catalogs the **29 active personas** shipped with
+`event4u/agent-config` (5 core + 24 specialists), plus the 5
 **advisor** personas in `personas/advisors/`. It also explains how
 `personas:` (lens axis) interacts with `/mode` (role-mode axis).
 Removed personas are deleted in-commit (no soak window) — see
 [`persona-governance § Deprecation path`](../dist/agent-src/rules/persona-governance.md).
 
-## Catalog — Core (always-loaded, 6)
+## Catalog — Core (always-loaded, 5)
 
 | ID | Role | Wing | Owner | Lens summary |
 |---|---|---|---|---|
@@ -24,13 +24,16 @@ Removed personas are deleted in-commit (no soak window) — see
 
 Note: `product-owner` was reclassified to **specialist** at v2.0 — see below.
 
-## Catalog — Specialists (opt-in, 20 active)
+## Catalog — Specialists (opt-in, 24 active)
 
 | ID | Role | Wing | Owner | Lens summary |
 |---|---|---|---|---|
 | `qa` | QA | — | package | Test coverage and regression gates. |
 | `backend-architect` | Backend Architect | — | package | Service-layer boundaries, transaction scope, contract changes. |
 | `eloquent-tamer` | Eloquent Tamer | — | package | N+1, query shape, ORM idioms that melt the database. |
+| `performance-engineer` | Performance Engineer (`performance`) | — | package | Latency, allocations, hot-path cost, complexity class at 100× load. |
+| `data-integrity` | Data Integrity Reviewer (`data`) | — | package | Migration reversibility, lock behavior under live traffic, data-loss on backfill. |
+| `production-validator` | Production Validator | — | package | Last gate before done — no mock/stub remains; validated against real systems (ADR-098). |
 | `security-engineer` | Security Engineer | — | package | OWASP-shaped failure modes, secret leakage, trust boundaries. |
 | `frontend-engineer` | Frontend Engineer | — | package | Component lifecycle, reactive state, hydration boundaries. |
 | `product-owner` | Product Owner | — | package | Outcomes named, AC unfalsifiable, scope on record. |
@@ -59,8 +62,16 @@ Note: `product-owner` was reclassified to **specialist** at v2.0 — see below.
 | GTM (Wing 3) | `cmo`, `growth-pm`, `customer-success-lead`, `revops` | ✅ (wing, not domain) |
 | Ops / Money (Wing 4) | `engineering-manager`, `people-strategist`, `finance-partner`, `strategist` | ✅ (wing, not domain) |
 | Backend | `backend-architect`, `eloquent-tamer` | ✅ 2/2 |
+| `performance` | `performance-engineer` | ✅ 1/2 |
+| `data` | `data-integrity` | ✅ 1/2 |
 
-Per-domain count is enforced by `scripts/lint_persona_governance.py` (wired into `task ci`).
+Cross-cutting quality lenses (`qa`, `tech-writer`, `revops-maintainer`,
+`discovery-lead`, `production-validator`) are uncapped — they are not bound to a
+single content domain.
+
+Per-domain count is enforced by `src/scripts/lint_persona_governance.ts`
+(wired into `task ci`), which scans `src/agent-src/personas/` (the source of
+truth) and `src/skills/` + `src/rules/` for `personas:` citations.
 
 ## Advisors (`personas/advisors/`, 5)