@event4u/agent-config 6.1.0 → 7.0.0

package/docs/contracts/benchmark-ab-contract.md

@@ -32,7 +32,7 @@ This contract covers the **variant axis** (`with` vs. `without` agent-config) th
 
 1. `task bench:ab` runs (the full pipeline ends with `bench:ab:diff` which calls the renderer).
 2. `task bench:ab:diff` runs alone (no fresh bench, just re-render).
-3. The renderer is invoked directly: `python3 scripts/render_benchmark_md.py`.
+3. The renderer is invoked directly: `./scripts-run src/scripts/render_benchmark_md`.
 
 The renderer is deterministic: same reports → same output. It never runs a bench. If no reports exist, it writes a placeholder document — never errors out.
 
@@ -86,10 +86,10 @@ The integrity check `bench_ab_tracka_run.py::integrity_check` fails the run if `
 
 A bench run counts as a real measurement (rather than a plumbing health check) when:
 
-- `python3 scripts/bench_ab_integrity.py` exits 0 (the variant axis is clean).
+- `./scripts-run src/scripts/bench_ab_integrity` exits 0 (the variant axis is clean).
 - Track A runs in BOTH variants and produces `integrity_ok: true` (with scoring close to 100%, without scoring 0%).
 - Track B runs in BOTH variants in `--mode live` (not dry-run).
-- `python3 scripts/lint_bench_ab.py` passes.
+- `./scripts-run src/scripts/lint_bench_ab` passes.
 - The rendered `docs/benchmark.md` carries the Headline + Track A + Track B + Methodology + History sections.
 
 ## Out of scope for this contract

package/docs/contracts/branch-protection-policy.md

@@ -91,6 +91,33 @@ under "Required status checks" honours this when "Require branches to be
 up to date before merging" is enabled and the check's most recent run
 on the head SHA is green.
 
+## Addendum — `python2ts` integration branch (py2ts migration)
+
+> Added 2026-06-11 for the Python → TypeScript migration (roadmap
+> `road-to-typescript-only-scripts.md`, Phase 1). Lives until the
+> migration completes; applied by the maintainer in the same Rules UI.
+
+The `python2ts` branch is the working trunk of the migration and carries
+its own protection rules:
+
+- **PRs only, no force-push, no deletion** — direct commits are blocked;
+  the scheduled `py2ts-main-sync.yml` workflow is the single sanctioned
+  direct-push writer (clean `main → python2ts` merges only; conflicts go
+  through the `sync/main-into-python2ts` PR instead).
+- **Required checks** — the full feature-PR floor (matrix above) plus
+  `py2ts Base Guard / py2ts-base-guard`.
+- **Migration PRs never target `main`** — a head branch matching
+  `^(feat|fix|chore)/py2ts-` or `^py2ts` must base on `python2ts`; the
+  base guard fails the PR otherwise. The inverse direction (non-py2ts
+  head targeting `python2ts`) only warns — sync PRs and hotfixes are
+  legitimate.
+- **Drift surfacing** — `py2ts-drift.yml` comments nightly on open
+  migration PRs whose touched `.py` files changed on `python2ts` since
+  the merge-base; such PRs rebase before merge.
+- **Final `python2ts → main` merge is user-owned** — Hard Floor
+  (production-trunk merge, explicit per-turn confirmation); never a
+  workflow, bot, or roadmap step.
+
 ## See also
 
 - [`release-pr-gating.md`](release-pr-gating.md) — shape predicates, cut

package/docs/contracts/brand-token-consumption.md

@@ -0,0 +1,69 @@
+# Brand-Token Consumption Contract (greenfield interface stub)
+
+> **Status:** interface stub. This contract is the **only** greenfield surface
+> shipped by `road-to-image-brand-typography` (Phase B.3, decision 2). The
+> Lovable-style `scaffold` work-engine directive that *consumes* it ships in the
+> sibling `road-to-greenfield-scaffold.md` — **no `scaffold.py` lives here.**
+> This doc exists so brand→token output is not dead output: it publishes the
+> shape a scaffold step reads, and the `mixed`-set routing hook, against a frozen
+> interface a later roadmap can build to.
+
+## 1 — What a scaffold step reads
+
+A greenfield scaffold step consumes a brand profile through two artifacts that
+pack-brand already produces — it does **not** call any pack-brand skill at
+build time:
+
+| Artifact | Producer | Shape |
+|---|---|---|
+| `.tokens.json` | [`brand-to-tokens`](../../src/skills/brand-to-tokens/SKILL.md) | DTCG (`$value` / `$type`) token tree — colour, type, spacing, radius. The same file `design-tokens/scripts/tokens.py` emits CSS vars + Tailwind from. |
+| voice profile | [`brand-strategy`](../../src/skills/brand-strategy/SKILL.md) / [`brand-identity`](../../src/skills/brand-identity/SKILL.md) | the confirmed voice traits + do/don't (3-5 traits) used to seed microcopy register. |
+
+**Read contract (frozen v1):**
+
+- The scaffold step reads `.tokens.json` as a DTCG document — never a
+  pack-brand-internal format. Style Dictionary / Tokens Studio round-trip is the
+  sanctioned external transform.
+- It reads the voice profile as a list of `{trait, do, don't}` records.
+- Absence of either artifact is **not an error** — it means greenfield with no
+  brand layer. The scaffold step then proceeds on the brief and SHOULD invoke
+  `brand-strategy` / `brand-identity` to define the tokens first (graceful, like
+  the brand-asset generation fallback). The scaffold never invents tokens
+  silently.
+
+## 2 — The `mixed`-set routing hook
+
+A greenfield request can arrive as one of three set-shapes; the routing hook
+names which path the scaffold takes:
+
+| Set | Meaning | Brand-token behaviour |
+|---|---|---|
+| `branded` | a brand profile (`.tokens.json` + voice) exists | consume tokens; `brand-consistency` gates emitted artifacts. |
+| `bare` | no brand layer, none requested | scaffold on neutral defaults; no brand gate. |
+| `mixed` | partial brand (some tokens, no voice; or voice, no tokens) | consume what exists; **route the gaps** to `brand-identity` to define the missing slice before emitting, then re-read `.tokens.json`. |
+
+The `mixed` path is the load-bearing one: it prevents a scaffold from either
+ignoring a partial brand or hard-failing on an incomplete one. The sibling
+scaffold roadmap implements the directive; this contract fixes the hook's
+inputs/outputs so that implementation has a stable target.
+
+## 3 — Direction of dependency (do not invert)
+
+```
+pack-brand  EXPORTS  .tokens.json + voice profile
+                 │
+                 ▼  (read-only, build time)
+greenfield scaffold step  (sibling roadmap)  and  pack-ai-image generation
+```
+
+The scaffold and pack-ai-image generation **consume** brand tokens; they never
+write back into pack-brand. Generation does not live in pack-brand (that would
+be a God-object — decision 1). This contract is read-only from the consumer
+side.
+
+## See also
+
+- [`brand-to-tokens`](../../src/skills/brand-to-tokens/SKILL.md) — emits the `.tokens.json` source of truth.
+- [`brand-consistency`](../../src/rules/brand-consistency.md) — the gate that runs on the `branded` / `mixed` paths.
+- [`design-tokens`](../../src/skills/design-tokens/SKILL.md) — DTCG token authoring + CSS/Tailwind emission.
+- `road-to-greenfield-scaffold.md` (sibling roadmap) — the scaffold directive that consumes this contract.

package/docs/contracts/command-clusters.md

@@ -49,11 +49,12 @@ column 1 of this table.
 | `sync-gitignore` | — | `fix` | new sub-command 2026-05-11 — cluster head retains the existing append-only sync as its default flow; `:fix` adds `--cleanup-legacy` semantics, scrubbing pre-`/agents/` runtime patterns wherever they appear in the consumer's `.gitignore` (inside or outside the managed block) and re-syncing the canonical entries. |
 | `ghostwriter` | — | `fetch` · `write` · `list` · `show` · `delete` | new cluster 2026-05-15 — third voice primitive for AI-assisted writing in the public voice of a public figure. Hybrid storage: real-person profiles live consumer-side under `agents/reference/ghostwriter/<slug>.md` (gitignored by default); package source ships only `fictional: true` fixtures. Zero network code in the package — `:fetch` delegates web-fetch / web-search to the host agent. Mandatory disclosure footer on every `:write` output (no opt-out). Schema: [`ghostwriter-schema`](ghostwriter-schema.md). |
 | `post-as` | — | `me` · `ghostwriter` | new cluster 2026-05-15 — consumer-facing write entry points. `:me` reads `.agent-user.md.voice_sample` and drafts in the maintainer's own voice (no disclosure footer — the user is the author); `:ghostwriter` is a thin alias for `/ghostwriter:write` with the mandatory disclosure footer. Both share the procedural [`write-engine`](write-engine.md) contract — style source and footer are the only axes of variation. |
-| `video` | — | `from-script` · `from-song` · `scene` · `storyboard` · `stitch` | new cluster 2026-05-17 — AI video generation pipeline. Cluster head orchestrates the full flow; `:scene` runs a single scene end-to-end (script → blueprint → still → motion → clip); `:storyboard` expands a script into per-scene blueprints + reference stills with character-lock JSON; `:from-script` walks a multi-scene script through storyboard + per-scene generation; `:from-song` builds a music-video from a song + reference images — derived/briefed timed script (via the `song-to-script` skill + `probe-audio.sh` hybrid segmentation), optional character-lock, then stitch with the song muxed as the master track and a mandatory AI-generation disclosure; `:stitch` concatenates scene clips with `ffmpeg` against a scene manifest. Provider-agnostic via the adapter contract under `scripts/ai-video/lib/adapter-contract.md`; cost-gated with mandatory `AIV_DRYRUN=true` default and explicit confirmation before live provider calls. |
+| `video` | — | `from-script` · `from-song` · `scene` · `storyboard` · `stitch` | new cluster 2026-05-17 — AI video generation pipeline. Cluster head orchestrates the full flow; `:scene` runs a single scene end-to-end (script → blueprint → still → motion → clip); `:storyboard` expands a script into per-scene blueprints + reference stills with character-lock JSON; `:from-script` walks a multi-scene script through storyboard + per-scene generation; `:from-song` builds a music-video from a song + reference images — derived/briefed timed script (via the `song-to-script` skill + `probe-audio.sh` hybrid segmentation), optional character-lock, then stitch with the song muxed as the master track and a mandatory AI-generation disclosure; `:stitch` concatenates scene clips with `ffmpeg` against a scene manifest. Provider-agnostic via the adapter contract under `scripts/media/lib/adapter-contract.md`; cost-gated with mandatory `AIV_DRYRUN=true` default and explicit confirmation before live provider calls. |
 | `knowledge` | — | `ingest` · `list` · `forget` · `cross-repo` | local-knowledge namespace (employee-product Phase 7); `:cross-repo` added 2026-05-30 (`road-to-leaner-core-and-discovery` Phase 4) — read-only targeted retrieval over opted-in `linked_projects` siblings (ADR-032 Option A), per [`cross-repo-retrieval`](cross-repo-retrieval.md). The pre-existing `ingest`/`list`/`forget` sub-commands are recorded in the registry here for the first time. |
 | `skills` | — | `discover` | new cluster 2026-05-30 (`road-to-leaner-core-and-discovery` Phase 3) — local, explained skill-recommendation surface over the catalog + role shortlists + optional local analytics, per [`skill-discovery`](skill-discovery.md). Every result carries a non-empty `why`; no network, honours the analytics opt-out. |
 | `skill` | — | `preview` | new cluster 2026-05-30 (`road-to-leaner-core-and-discovery` Phase 5) — non-destructive skill/command preview: surfaces the declared steps + files/commands a skill would touch before it runs, per [`skill-dry-run`](skill-dry-run.md). Singular `skill` (one target) vs plural `skills` (the catalog) by design. |
 | `image` | — | `analyse` · `create` · `verify` | new cluster 2026-05-31 (`road-to-character-image-fidelity` Phase 4) — character-image fidelity surface mirroring `/video:*`. `:analyse` extracts a per-feature spec from an image and diffs it against a Canon Spec down to the smallest mole (OCR for lettered tattoos, per-section severity scores, canon-breaking hard gate); `:create` assembles a max-fidelity anchors-first generation prompt from the Canon Spec, governance- + provider-gated, `AIV_DRYRUN=true` default; `:verify` runs the analyser in loop mode against a candidate and reports the gate verdict + remaining diff with plateau/oscillation/budget stop conditions. Skills: [`image-analyser`](../../skills/image-analyser/SKILL.md) + [`image-creator`](../../skills/image-creator/SKILL.md); schema/rubric/loop in [`canon-spec.md`](../../skills/image-analyser/canon-spec.md). |
+| `brand` | — | `strategy` · `identity` · `tokens` · `review` · `voice` | new cluster 2026-06-17 (`road-to-image-brand-followups` Phase 3) — brand-as-first-class-UX surface for `pack-brand`, consulted before `design-intelligence` so brand bounds style. `:strategy` (positioning/archetype/voice/messaging over the brand corpus), `:identity` (logo/colour/type/imagery direction — defines the tokens downstream generation consumes), `:tokens` (derive a DTCG `.tokens.json` source of truth → CSS/Tailwind, no Node), `:review` (audit emitted UI/copy/assets against active brand tokens + voice per the `brand-consistency` gate), `:voice` (voice-and-tone profile). Skills: [`brand-strategy`](../../skills/brand-strategy/SKILL.md) · [`brand-identity`](../../skills/brand-identity/SKILL.md) · [`brand-to-tokens`](../../skills/brand-to-tokens/SKILL.md) · [`brand-audit`](../../skills/brand-audit/SKILL.md) · [`voice-and-tone-design`](../../skills/voice-and-tone-design/SKILL.md). The companion `/imagegen:*` generation cluster (pack-ai-image) is deferred until its adapters' live submit/poll/fetch is wired. |
 
 | `profile` | — | `activate` · `deactivate` · `show` | new cluster 2026-06-02 (`road-to-session-profile-activation`) — session-profile activation: an ephemeral `runtime.active_packs` overlay that biases the surfaced command/skill set to the active pack closure, with no persistence and no execution-gating (recommendation-bias MVP). `:activate <name…>` resolves an alias (`src/config/discovery/session-profiles.yml`) or a raw pack id, fails fast on a not-installed pack, expands the `requires_hint` closure, and writes the overlay atomically to `agents/settings/.agent-settings.local.yml`; `:deactivate [name…]` clears it (or drops named packs, keeping deps a still-active pack needs); `:show` is the observability surface (active packs + surfaced/hidden counts). Overlay = runtime modulation of the existing `pack` axis, not a fifth axis (ADR-010 addendum). Library: `scripts/config/session_profiles.py`; schema in [`session-profile-overlay`](session-profile-overlay.md). |
 

package/docs/contracts/command-surface-tiers.md

@@ -156,6 +156,19 @@ the help text groups commands under `## Tier 0`, `## Tier 1`,
 
 Hooked into `task lint-skills` so it runs in CI.
 
+## `tier` deprecation signal (discovery manifest v2)
+
+Since ADR-090 the named `visibility:` field is the command classifier source
+of truth and the integer `tier:` (`0/1/2`) is a back-compat alias. The
+published discovery manifest (`dist/discovery/discovery-manifest.json`) is now
+**v2** and carries a machine-readable top-level `deprecations` block
+announcing the `tier` key (replacement: `visibility`). `tier` is **still
+emitted** on command artefacts (non-breaking) — the block only signals the
+deprecation so external manifest consumers can migrate during a soak window.
+Removal of `tier` (frontmatter + schema + manifest emit) is tracked in
+`road-to-tier-removal` (ADR-092, Phase 4) and is **not** done yet; restoring
+`tier` after removal would be a sub-1h manifest-schema patch.
+
 ## See also
 
 - The distribution-maturity roadmap — Phase 4 (under `agents/roadmaps/`).

package/docs/contracts/discovery-manifest.schema.json

@@ -8,8 +8,13 @@
   "additionalProperties": false,
   "properties": {
     "version": {
-      "const": 1,
-      "description": "Manifest schema version. Bump on breaking change."
+      "const": 2,
+      "description": "Manifest schema version. Bump on breaking change. v2 (road-to-tier-removal Phase 1 / ADR-092) adds the top-level `deprecations` block; the integer command `tier` field stays emitted (non-breaking)."
+    },
+    "deprecations": {
+      "type": "array",
+      "description": "road-to-tier-removal Phase 1 / ADR-092 — machine-readable deprecation signals for keys still emitted (non-breaking) but scheduled for removal. Lets external manifest consumers migrate during the soak window before any field is dropped.",
+      "items": { "$ref": "#/$defs/deprecation" }
     },
     "generated_at": {
       "type": "string",
@@ -53,6 +58,20 @@
     "stats": { "$ref": "#/$defs/stats" }
   },
   "$defs": {
+    "deprecation": {
+      "type": "object",
+      "required": ["key", "replacement", "since"],
+      "additionalProperties": false,
+      "description": "A single deprecated manifest key still emitted during its soak window.",
+      "properties": {
+        "key": { "type": "string", "minLength": 1, "description": "The deprecated key (e.g. `tier`)." },
+        "scope": { "type": "string", "minLength": 1, "description": "Where the key appears (e.g. `command` artefact entries)." },
+        "replacement": { "type": "string", "minLength": 1, "description": "The canonical key consumers should read instead (e.g. `visibility`)." },
+        "since": { "type": "string", "minLength": 1, "description": "The decision that deprecated it (e.g. an ADR id)." },
+        "sunset": { "type": ["string", "null"], "description": "Maintainer-owned removal date/marker; null until the soak window clears (scope-control: agents do not pin dates)." },
+        "note": { "type": "string", "description": "Human-readable migration guidance." }
+      }
+    },
     "workspace_id": {
       "type": "string",
       "enum": ["engineering", "product", "finance", "founder", "gtm", "ops", "small-business", "construction", "agent-config-maintainer"]
@@ -64,8 +83,8 @@
         "product-basic", "product-discovery",
         "finance-basic", "finance-advanced",
         "gtm-sales", "gtm-marketing",
-        "ops-people", "founder-strategy", "small-business", "construction", "ai-video", "fun", "meta", "git", "frontend-design",
-        "memory", "analytics", "product-reasoning"
+        "ops-people", "founder-strategy", "small-business", "construction", "ai-video", "ai-image", "fun", "meta", "git", "frontend-design", "brand",
+        "memory", "analytics", "product-reasoning", "analysis-workbench"
       ]
     },
     "lifecycle": {
@@ -135,7 +154,7 @@
         "category": { "type": "string", "enum": ["skill", "rule", "command", "template"] },
         "name": { "type": "string" },
         "pack": { "$ref": "#/$defs/pack_id", "description": "capability-packs.md — canonical OWNER pack (ownership/budget unit). Orthogonal to `packs` (discovery tags); the owner need not appear in `packs`." },
-        "tier": { "type": "integer", "enum": [0, 1, 2], "description": "6.0.0-C — command-surface tier surfaced on `category: command` artefacts so the CLI discovery surface reads the manifest, not a parallel catalog. Back-compat alias of `visibility` since ADR-090; dual-emitted during the deprecation window." },
+        "tier": { "type": "integer", "enum": [0, 1, 2], "description": "6.0.0-C — command-surface tier surfaced on `category: command` artefacts so the CLI discovery surface reads the manifest, not a parallel catalog. DEPRECATED back-compat alias of `visibility` since ADR-090; still dual-emitted (non-breaking) but announced for removal in the top-level `deprecations` block (road-to-tier-removal Phase 1 / ADR-092). Read `visibility`." },
         "visibility": { "type": "string", "enum": ["visible", "advanced", "internal"], "description": "ADR-090 — named command-surface visibility (visible↔tier 0, advanced↔tier 1, internal↔tier 2); the classifier source of truth. Dual-emitted alongside `tier` on `category: command` artefacts during the deprecation window." },
         "intent": { "type": "string", "description": "6.0.0-C — command routing metadata (one-line existence justification). Present on visible command artefacts." },
         "routes_to": { "type": "array", "items": { "type": "string" }, "description": "6.0.0-C — command routing metadata (skill/cluster-sub/command slugs the intent routes to)." },

package/docs/contracts/implement-ticket-flow.md

@@ -170,7 +170,7 @@ therefore requires:
 2. Re-run the per-dimension fixtures
    (`tests/work_engine/test_scoring_confidence.py`).
 3. Re-capture GT-P1..GT-P4 if a fixture's band assignment shifts
-   (`python3 -m tests.golden.capture`); review the diff before
+   (`node node_modules/.bin/tsx tests/golden/capture.ts`); review the diff before
    locking. If GT-P3 (low) or GT-P4 (UI rejection) flip bands the
    threshold change is rejected — those fixtures are pinned to
    their bands by design.
@@ -428,7 +428,7 @@ manual for producing and re-producing those packs.
 
 Each cycle is a fresh `./agent-config implement-ticket` subprocess
 seeded from the persisted state file. The runner
-(`tests/golden/sandbox/runner.py`) chains them:
+(`tests/golden/sandbox/runner.ts`) chains them:
 
 ```bash
 ./agent-config implement-ticket \
@@ -443,8 +443,8 @@ seeded from the persisted state file. The runner
 The runner is invoked via the capture driver:
 
 ```bash
-python3 -m tests.golden.capture                 # all five GTs
-python3 -m tests.golden.capture --scenarios GT-3
+node node_modules/.bin/tsx tests/golden/capture.ts                 # all five GTs
+node node_modules/.bin/tsx tests/golden/capture.ts --scenarios GT-3
 ```
 
 ### Kill points & resume
@@ -492,7 +492,7 @@ recipe and relock policy: [`tests/golden/CAPTURING.md`](../../tests/golden/CAPTU
 Only when the engine's observable behaviour intentionally changes:
 
 ```bash
-python3 -m tests.golden.capture
+node node_modules/.bin/tsx tests/golden/capture.ts
 git diff tests/golden/baseline tests/golden/CHECKSUMS.txt
 ```
 
@@ -566,7 +566,7 @@ Only when an engine change is **intentionally** behaviour-altering.
 The PR description must justify each new checksum. Procedure:
 
 ```bash
-python3 -m tests.golden.capture                  # regenerate Capture Packs + manifest
+node node_modules/.bin/tsx tests/golden/capture.ts                  # regenerate Capture Packs + manifest
 git diff tests/golden/baseline tests/golden/CHECKSUMS.txt
 ```
 
@@ -587,13 +587,13 @@ are blocked by `freeze-guard.yml::manifest-integrity` at PR time.
 
 - Loosening the harness comparator to "fix" a failing replay. The
   harness is the contract; the engine is the variable.
-- Re-running `python3 -m tests.golden.capture` to "make the diff go
+- Re-running `node node_modules/.bin/tsx tests/golden/capture.ts` to "make the diff go
   away" without justification. The diff *is* the question.
 - Treating the harness and freeze-guard as duplicate checks. They
   catch different drift classes — both must stay green.
 - Adding a sixth Capture Pack without adding a corresponding entry
-  to `RECIPE_MODULES` in `harness.py` and a parametrize row in
-  `test_replay.py`.
+  to `RECIPES` in `sandbox/recipes/index.ts` and a parametrize row in
+  `golden_replay.test.ts`.
 
 ## Non-goals
 

package/docs/contracts/install-layout.md

@@ -0,0 +1,249 @@
+---
+stability: beta
+keep-beta-until: 2026-09-15
+---
+
+# Install Layout — the on-disk ABI
+
+The **install layout** is the on-disk shape `agent-config` writes into a host:
+the file paths it creates, the JSON-pointer keys it claims in shared/foreign
+config files, the surgical-uninstall pointer schema, and the lockfile shapes.
+For a tool whose promise is "install into your shared host config," this layout
+is part of the public contract — a consumer's working tree, their other tools'
+configs, and any automation that reads the lockfile all depend on it staying
+stable.
+
+This document is the **frozen source** the install-ABI conformance test
+(`tests/test_install_layout_contract.py`) guards against. Any change to the
+shape below must (a) bump `install_layout_version` and (b) carry a
+`### Breaking` / deprecation note per the install-ABI deprecation-window rule in
+[`BREAKING_CHANGES.md`](../../BREAKING_CHANGES.md).
+
+- **Authoritative writer:** [`src/scripts/install.py`](../../src/scripts/install.py)
+  (the wizard plans via `src/install/`, then `install.py --apply-payload`
+  performs the real writes).
+- **Lockfile writers:** [`src/scripts/_lib/installed_tools.py`](../../src/scripts/_lib/installed_tools.py)
+  (project manifest), [`src/scripts/_lib/installed_lock.py`](../../src/scripts/_lib/installed_lock.py)
+  (global lockfile).
+- **Companion contracts:** [`install-scopes.md`](install-scopes.md) (user-global
+  vs project-local), [`installed-tools-lockfile.md`](installed-tools-lockfile.md)
+  (project manifest wire format).
+
+## `install_layout_version`
+
+The on-disk layout carries a single integer version, defined in
+[`src/scripts/_lib/install_layout.py`](../../src/scripts/_lib/install_layout.py)
+as `INSTALL_LAYOUT_VERSION`. The installer stamps it into the global lockfile
+(`~/.event4u/agent-config/installed.lock`) so an installed tree self-declares
+which ABI it was written under.
+
+| Value | Meaning |
+|---|---|
+| absent | **v0 / pre-freeze** — an installed tree written before this contract existed. Treated as the current shape; the installer migrates it in place on the next run. |
+| `1` | **frozen baseline** — the shape documented below. |
+
+A bump to `INSTALL_LAYOUT_VERSION` is a declared layout change: it ships under
+the deprecation-window rule (old + new shape side-by-side for one minor cycle),
+and the installer migrates an older installed tree in place before the old shape
+is dropped.
+
+## Supported tools
+
+The canonical install targets are `_VALID_TOOLS` in
+[`install.py`](../../src/scripts/install.py):
+
+```
+claude-code  claude-desktop  cursor  windsurf  cline  gemini-cli  copilot
+augment  aider  codex  roocode  continue  kilocode  zed  jetbrains  kiro
+qoder  opencode  trae  antigravity  codebuddy  droid  warp
+```
+
+`all` is an expansion sentinel accepted by `--tools`, not a tool.
+
+## Written paths
+
+Two install scopes (see [`install-scopes.md`](install-scopes.md)): **project-local**
+(`<root>/…`) and **user-global** (`~/…`). The layout below is the union; a given
+run writes only the subset for the selected scope + tools.
+
+### Always-written project files (both scopes)
+
+| Path | Kind | Notes |
+|---|---|---|
+| `<root>/agents/settings/.agent-settings.yml` | deployed | canonical YAML settings (ADR-038) |
+| `<root>/.agent-settings.yml` | deployed | legacy fallback; migrated then removed on first run |
+| `<root>/agents/.event4u-bridge.yml` | bridge | project → `~/.event4u/agent-config/` pointer; schema `event4u-bridge/v1` |
+| `<root>/agents/.agent-state/install-mode.txt` | marker | `minimal\n` or `full\n` |
+
+Minimal-install scaffold (override layer): `agents/overrides/{rules,skills,commands}/.gitkeep`,
+`agents/overrides/README.md`.
+
+VSCode substrate bridge: `<root>/.vscode/settings.json` key
+`/chat/pluginLocations/<plugin_path>` is written unconditionally and is
+**intentionally not tracked** in the manifest (see § Untracked surfaces).
+
+### Per-tool project-scope bridge markers
+
+`PROJECT_BRIDGE_MARKERS` in [`install.py`](../../src/scripts/install.py). The
+manifest records the marker path as the tool's `bridge_marker`.
+
+| Tool | Path (project-relative) | Kind |
+|---|---|---|
+| claude-code | `.claude/settings.json` | bridge (JSON merge) |
+| claude-desktop | `.claude-desktop/agent-config.md` | marker |
+| cursor | `.cursor/hooks.json` | bridge (JSON merge) |
+| windsurf | `.windsurf/hooks.json` | bridge (JSON merge) |
+| cline | `.clinerules/hooks/<HookName>` (6 hook scripts) | bridge (executable) |
+| gemini-cli | `.gemini/settings.json` | bridge (JSON merge) |
+| copilot | `.github/plugin/marketplace.json` | bridge (whole-file write) |
+| augment | `.augment/settings.json` | bridge (JSON merge) |
+| aider | `.aider/agent-config.md` | marker |
+| codex | `.codex/agent-config.md` | marker |
+| roocode | `.roo/rules/agent-config.md` | marker |
+| continue | `.continue/rules/agent-config.md` | marker |
+| kilocode | `.kilocode/rules/agent-config.md` | marker |
+| zed | `.zed/agent-config.md` | marker |
+| jetbrains | `.jetbrains/agent-config.md` | marker |
+| kiro | `.kiro/steering/agent-config.md` | marker |
+
+Anchor-pointer bridges (subset, project scope): `.windsurf/agent-config.bridge.yml`,
+`.clinerules/agent-config.bridge.yml`, `.gemini/agent-config.bridge.yml`.
+
+> **Known gap (frozen as-is):** `qoder`, `opencode`, `trae`, `antigravity`,
+> `codebuddy`, `droid`, `warp` are valid tools with global deploy sources but no
+> project-scope bridge marker — a project-scope install of these writes no marker
+> and records no `bridge_marker`. The contract freezes the current behaviour; a
+> future addition of markers for these tools is an additive (non-breaking) change.
+
+### User-global content deployment (`--global` / `--scope=global`)
+
+User-scope anchor roots are `USER_SCOPE_PATHS`; deployed subtrees are
+`GLOBAL_DEPLOY_SOURCES` (both in [`install.py`](../../src/scripts/install.py)).
+
+| Tool | User-scope anchor | Deployed subtrees |
+|---|---|---|
+| claude-code | `~/.claude/` | `rules/`, `skills/`, `commands/`, `personas/` |
+| augment | `~/.augment/` | `rules/`, `skills/`, `commands/`, `contexts/`, `personas/`, `templates/` |
+| cursor | `~/.cursor/` | `rules/`, `commands/`, `personas/` |
+| windsurf | `~/.codeium/windsurf/` | `rules/` |
+| cline | `~/Documents/Cline/Rules/` | flat `rules/` (no sub-prefix) |
+| gemini-cli | `~/.gemini/` | `rules/`, `skills/`, `commands/`, `personas/` |
+| codex | `~/.codex/` | `rules/`, `skills/`, `commands/`, `personas/` |
+| continue / roocode / kilocode / qoder / opencode / trae / codebuddy | `~/.continue/`, `~/.roo/`, `~/.kilocode/`, `~/.qoder/`, `~/.opencode/`, `~/.trae/`, `~/.codebuddy/` | claude-code bundle |
+| antigravity | `~/.agents/` | claude-code bundle |
+| droid | `~/.factory/` | claude-code bundle |
+| warp | `~/.warp/` | claude-code bundle |
+| kiro | `~/.kiro/` | `rules/`, `steering/`, `personas/` |
+| claude-desktop | `~/Library/Application Support/Claude/agent-config.md` (marker) | `~/.event4u/agent-config/claude-desktop/bundles/*.zip` |
+
+Tools `copilot`, `aider`, `zed`, `jetbrains` write no global content (hint
+printed only).
+
+### Global runtime root (`~/.event4u/agent-config/`)
+
+| Path | Writer | Notes |
+|---|---|---|
+| `installed.lock` | `installed_lock.py` | global lockfile (carries `install_layout_version`) |
+| `.agent-settings.yml` | `install.py` | global layer of the three-layer settings merge |
+| `.agent-user.yml` | `install.py` | user personal settings |
+| `install-log.jsonl` | `src/install/` (TS) | transaction log (TS engine only) |
+
+### User-scope hook trampolines (explicit-flag only)
+
+Written only with `--{augment,cursor,cline,windsurf,gemini}-user-hooks`:
+a per-tool `*-dispatcher.sh` under the tool's hook dir, plus a JSON merge into
+that tool's user-scope settings/hooks file (cline also writes 6 hook wrappers).
+
+## Claimed JSON-pointer keys
+
+All JSON merges use `deep_merge()` — recurse into nested dicts, replace at
+leaves; sibling keys owned by other tools survive. The exceptions are noted.
+
+| File | Pointer(s) | Merge / overwrite |
+|---|---|---|
+| `.augment/settings.json` | `/enabledPlugins/agent-config@event4u` | deep_merge |
+| `~/.augment/settings.json` | `/hooks/{SessionStart,SessionEnd,Stop,PreToolUse,PostToolUse}/0` | deep_merge (array-replace) |
+| `.claude/settings.json` | `/enabledPlugins/agent-config@event4u-agent-config` | deep_merge |
+| `.cursor/hooks.json`, `~/.cursor/hooks.json` | `/hooks/{sessionStart,sessionEnd,stop,beforeSubmitPrompt,postToolUse}` | deep_merge |
+| `.windsurf/hooks.json`, `~/.codeium/windsurf/hooks.json` | `/hooks/{post_setup_worktree,pre_user_prompt,post_cascade_response}` | deep_merge |
+| `.gemini/settings.json`, `~/.gemini/settings.json` | `/hooks/{SessionStart,SessionEnd,AfterAgent,BeforeAgent,AfterTool}` | deep_merge |
+| `.github/plugin/marketplace.json` | `/marketplace/name`, `/marketplace/plugins/0` | **whole-file write** |
+| `.vscode/settings.json` | `/chat/pluginLocations/<path>` | deep_merge (**untracked**) |
+
+Per the manifest contract, RFC-6901 pointers target object keys, never array
+indices — except the documented hook-array replacements above, which the
+installer owns wholesale.
+
+## Surgical-uninstall pointer schema
+
+An uninstall/prune flow removes exactly what the installer wrote, leaving
+foreign keys and files intact. The pointers it follows:
+
+1. **`bridge_marker`** (per tool) — single canonical path proving the tool is
+   installed. Existence-tracked; removal signals complete uninstall for that tool.
+2. **`files[]`** (per tool) — objects with `path`, `kind` ∈ `{deployed, bridge, marker}`,
+   and `sha256` (or `null` for markers). `deployed` = owned content (delete);
+   `bridge` = shared config (remove only our keys); `marker` = sentinel (delete).
+3. **`merged_keys[]`** (per tool) — objects with `file` + `json_pointer` (+ optional
+   `value_hash`). Uninstall removes only these keys.
+4. **`status`** — `installed` (default) or `uninstalling`; the two-phase uninstall
+   resume target (`agent-config prune --resume-uninstall` sweeps only `uninstalling`
+   entries' `files[]`).
+
+Full wire format: [`installed-tools-lockfile.md`](installed-tools-lockfile.md).
+
+## Lockfile shapes
+
+### Project manifest — `agents/installed-tools.lock`
+
+`schema_version: 2`, reader tolerates v1 + v2. Wire format is the canonical
+contract in [`installed-tools-lockfile.md`](installed-tools-lockfile.md); this
+layout contract freezes that the file exists at that path and carries that shape.
+
+### Global lockfile — `~/.event4u/agent-config/installed.lock`
+
+Written by `installed_lock.py`. Frozen shape:
+
+```yaml
+schema_version: 1
+install_layout_version: 1
+agent_config_version: "<semver>"
+installed_at: "<ISO-8601 UTC>"
+tools:
+  - claude-code
+  - cursor
+```
+
+`install_layout_version` is the field this contract adds (§ `install_layout_version`).
+Absent on a pre-freeze tree → treated as v0, migrated in place. The legacy
+`~/.config/agent-config/installed.lock` is read as a fallback, never written.
+
+## Untracked surfaces (frozen as known gaps)
+
+These are written but **not** recorded in any lockfile; uninstall cannot
+currently undo them. They are frozen as documented behaviour, not contract
+promises — fixing them is an additive change (recording a previously-untracked
+write), never a breaking one.
+
+- `.vscode/settings.json` `chat.pluginLocations` (substrate bridge, written
+  unconditionally).
+- User-scope `merged_keys` (the global install path passes `files_by_tool` but
+  not `merged_keys_by_tool`, so JSON merges into `~/.augment/settings.json`,
+  `~/.cursor/hooks.json`, etc. are unrecorded).
+- Best-effort legacy-trampoline removal (`OSError` swallowed; failed removals
+  leave stale files with no manifest entry).
+
+## `--apply-payload` entry point
+
+The real-apply path consumes a JSON payload (`wizard-v2` or legacy `installer-v1`
+schema) and writes the layout above, emitting NDJSON progress frames
+(`{"type":"file",…}`, `{"type":"done"}`, `{"type":"error",…}`). `dry_run: true`
+previews without writing. The payload schema is a separate wire contract from the
+on-disk layout this document freezes.
+
+## See also
+
+- [`STABILITY.md`](STABILITY.md) — beta/stable contract policy.
+- [`BREAKING_CHANGES.md`](../../BREAKING_CHANGES.md) — install-ABI deprecation-window rule.
+- [`install-scopes.md`](install-scopes.md) · [`installed-tools-lockfile.md`](installed-tools-lockfile.md).
+- [`tests/test_install_layout_contract.py`](../../tests/test_install_layout_contract.py) — the conformance test that locks this shape.

package/docs/contracts/kernel-membership.md

@@ -259,7 +259,7 @@ with the trigger-relaxed parameter, lock new value, re-attempt.
 
 | check | command | acceptance |
 |---|---|---|
-| Pilot reproducibility | `python3 scripts/_pilot_measure.py` | r-values, sum, SHAs identical across runs |
+| Pilot reproducibility | `./scripts-run src/scripts/_pilot_measure` | r-values, sum, SHAs identical across runs |
 | Iron-Law preservation | SHA-256 of fence-block content (whitespace-norm, case-fold) | all 3 pilots match originals |
 | Bucket projection | `r_median × sum(always)` | ≤ 25 000 chars |
 | Per-rule cap (P2.1) | `measure_rule_budget.py --kernel-budget-check` (P2 deliverable) | each ≤ 2 500 chars OR ADR |

package/docs/contracts/linear-ai-rules-inclusion.md

@@ -11,7 +11,7 @@ keep-beta-until: 2026-08-12
 > agent (Codegen, Charlie, Cursor's Linear app, …) reads it verbatim —
 > no skill triggering, no script execution, no `.augment/` access.
 >
-> Source of tier data: `python3 scripts/audit_cloud_compatibility.py
+> Source of tier data: `./scripts-run src/scripts/audit_cloud_compatibility
 > --details` (47 rules: T1=20, T2=19, T3-S=8).
 >
 > Last refreshed: 2026-04-29.
@@ -135,7 +135,7 @@ persistence on cloud platforms; the rule is a no-op.
 ## Source of tier data
 
 ```
-python3 scripts/audit_cloud_compatibility.py --details --format json
+./scripts-run src/scripts/audit_cloud_compatibility --details --format json
 ```
 
 47 rules: T1=20, T2=19, T3-S=8. Counts in this document derive from the

package/docs/contracts/linter-structural-model.md

@@ -66,7 +66,7 @@ imperatives (`NEVER COMMIT.`).
 Sweep covered all 310 lintable artifacts via
 [`scripts/measure_density.py`](../../src/scripts/measure_density.py); raw
 data lives at `agents/runtime/density/snapshot.jsonl` (local-only — re-run
-`python3 scripts/measure_density.py --root dist/agent-src --jsonl
+`./scripts-run src/scripts/measure_density --root dist/agent-src --jsonl
 agents/runtime/density/snapshot.jsonl` to regenerate).
 
 | Type | Count | Avg density | Median | Bucket [0.4-0.6] | Bucket [0.6-1.0] |

package/docs/contracts/mcp-discovery-phase-notice.md

@@ -35,7 +35,7 @@ raw identifiers (J4 in the roadmap). Three outcomes are logged:
 On any host running the stdio server:
 
 ```bash
-python3 scripts/mcp_telemetry_health.py
+./scripts-run src/scripts/mcp_telemetry_health
 ```
 
 Healthy → exit 0 with the 24 h count. Silent → exit 1; treat as an alert.

package/docs/contracts/multi-tool-projection-fidelity.md

@@ -105,7 +105,7 @@ native `model:`. See ADR-035 and `road-to-model-capability-tiers.md`.
 | `skill:laravel` | skill | Augment + Claude only; rationale for absence on others |
 | `command:commit` | command | per-tool command surface divergence |
 
-Run: `python3 scripts/probe_projection_fidelity.py` — exits non-zero on any divergence. Report at `agents/runtime/reports/projection-fidelity.json`.
+Run: `./scripts-run src/scripts/probe_projection_fidelity` — exits non-zero on any divergence. Report at `agents/runtime/reports/projection-fidelity.json`.
 
 ## Known divergences (do not file as bugs)
 

package/docs/contracts/namespace.md

@@ -91,9 +91,9 @@ Diagnostic format: one issue per line — `<path>: <rule> — <detail>`.
 Pick the name; verify locally:
 
 ```bash
-python3 scripts/lint_namespace.py --name <candidate>
+./scripts-run src/scripts/lint_namespace --name <candidate>
 # or full run:
-python3 scripts/lint_namespace.py
+./scripts-run src/scripts/lint_namespace
 ```
 
 If the candidate fails, the linter prints the rule it violated.