@event4u/agent-config 7.5.0 → 8.0.0

package/docs/guidelines/design-antipatterns.md

@@ -39,7 +39,7 @@ The objective floors are cited from the linter, never re-eyeballed by an agent.
 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`,
-plus the **Consistency Locks & layout caps** `V8`, `C6`, `L9`, `L10`
+`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
@@ -140,6 +140,7 @@ Within-project invariants + repetition caps. Override = declare the value in
 | 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) |
 
 ---
 
@@ -163,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-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)
 

package/docs/positioning-evidence.md

@@ -0,0 +1,86 @@
+# Positioning evidence & decision (B0)
+
+> Market-readiness roadmap B0. The evidenced differentiators the positioning
+> rests on, the H1 options that were weighed, and the decision. Every
+> differentiator below is **shipped and machine-checked**, not aspirational —
+> each names the artifact that backs it.
+
+## The problem
+
+External adoption is ≈0. The prior README H1 — *"Governed skills, rules & work
+journeys for AI coding agents"* — was abstract and interchangeable: no single
+uncopyable hook. This document fixes the one sentence that carries the
+differentiator.
+
+## Evidenced differentiators
+
+1. **Machine-checked honest marketing (the Claims-Ledger).** Every public claim
+   that carries a `<!-- claim:ID -->` marker must bind to a resolvable evidence
+   pointer in [`CLAIMS.md`](CLAIMS.md), or CI fails. Unbacked claims are logged
+   as visible debt rather than hidden. Evidence:
+   [`src/scripts/check_claims.ts`](../src/scripts/check_claims.ts),
+   [`CLAIMS.md`](CLAIMS.md).
+2. **A self-verifying proof page.** [`proof.md`](proof.md) is generated from the
+   ledger (claim → evidence table) plus the honest-null benchmark runs
+   (*including the nulls*) plus a "verify it yourself" command block a skeptic
+   runs on a fresh checkout. Drift-gated in CI. Evidence:
+   [`src/scripts/build_proof.ts`](../src/scripts/build_proof.ts),
+   [`proof.md`](proof.md).
+3. **Published honest-nulls.** Measured null results ship rather than hide (e.g.
+   a recursive-verification wrapper measured for null lift; an orchestration
+   auto-flip held at a documented honest-null). Evidence:
+   [`benchmark.md`](benchmark.md).
+4. **No-runtime, host-agnostic governance.** Rules compile into each tool's
+   native format at projection time; the same governance rides on 7+ hosts with
+   no daemon. Surgical uninstall (JSON-pointer + SHA-256, never a neighbour
+   tool's keys). Evidence:
+   [`contracts/no-runtime-boundary.md`](contracts/no-runtime-boundary.md),
+   [`contracts/install-layout.md`](contracts/install-layout.md).
+5. **A 30-second wedge.** `production-validator` — a single self-contained Claude
+   Code subagent (one `curl` into `.claude/agents/`) that runs the last gate
+   before "done": no mock/stub on the shipped path, validated against real
+   systems. Evidence: [`wedge/production-validator/`](wedge/production-validator/).
+
+## Competitive frame
+
+The dominant competitor wins on reach behind a loud, **unbacked** headline
+performance number (present in several files, no reproducible methodology). The
+only defensible, uncopyable inverse is **reproducible honesty**: they cannot
+adopt a Claims-Ledger + proof page without exposing their own unbacked numbers.
+"Honesty" alone can read as merely defensive, so the wedge and the governed
+depth carry the offensive substance.
+
+## H1 options weighed
+
+- **Option 1 — verifiability as frame.** *"Agent Config — every claim
+  machine-checked, including 'zero runtime'."* Subline: 261 skills, 93 rules,
+  7 hosts; run the proof page yourself; no daemon, no lock-in, no unverifiable
+  promises.
+- **Option 2 — architecture first.** *"Governed AI agents with zero runtime —
+  and a proof page you verify in 30 seconds."*
+- **Option 3 — host-agnostic.** *"Write your agent governance once — run it in
+  7 hosts, with a proof page that can't lie."*
+
+## Decision
+
+**Adopted: Option 1** (verifiability as frame).
+
+Council (claude-sonnet-4-5 + gpt-4o, 2026-07-04) split only on headline vs.
+subline placement, and converged on the substance: the stateless / host-agnostic
+/ no-runtime architecture is the technical moat, and the Claims-Ledger + proof
+page is the maximally-uncopyable trust bootstrap. The decisive argument: in a
+low-trust market, "zero runtime" on its own is just another unverifiable
+promise — making **verifiability the frame** and the architectural claims *what
+you verify* is what makes "zero runtime" credible. The maintainer made the final
+call per the B0 "human picks" gate.
+
+**Biggest risk (tracked):** "machine-checked" can read as compliance-boring
+rather than a competitive weapon — mitigated by framing it offensively
+("built to be checked, in a market that runs on unbacked headlines"), not
+defensively.
+
+## Applied to
+
+- README H1 + hero line (this repo).
+- `distribution/launch-story-draft.md` headline placeholder (resolved).
+- `distribution/awesome-list-submission.md` (already Option-1-aligned).