@event4u/agent-config 2.26.0 → 3.1.0

package/docs/contracts/load-context-schema.md

@@ -27,7 +27,7 @@ type: "always"
 description: "..."
 load_context:                # lazy — on-demand reference list
   - contexts/<area>/<file>.md         # logical name (canonical)
-  - agents/contexts/<file>.md         # project-local
+  - agents/settings/contexts/<file>.md         # project-local
 load_context_eager:          # opt-in eager — auto-loaded on rule fire
   - contexts/<area>/<file>.md
 ---
@@ -58,7 +58,7 @@ opt-in and budget-gated.
 - Allowed roots:
   - `contexts/<area>/<file>.md` — canonical logical name (resolves
     against `.agent-src.uncompressed/`).
-  - `agents/contexts/<file>.md` — project-local material (consumer
+  - `agents/settings/contexts/<file>.md` — project-local material (consumer
     repo only).
   - `.agent-src/contexts/<file>.md` — compressed mirror; tolerated
     defensively, not authored.
@@ -66,7 +66,7 @@ opt-in and budget-gated.
   regex and by `lint_load_context.py` with a remediation hint pointing
   at the canonical logical name.
 - A rule MAY reference contexts under either tree, but a package-shipped
-  rule SHOULD NOT eager-load an `agents/contexts/` file (project-local
+  rule SHOULD NOT eager-load an `agents/settings/contexts/` file (project-local
   leak into shared package). Linter warns on this combination.
 - A context file may itself declare `load_context:` (chain reasoning).
   The linter rejects cycles.
@@ -148,7 +148,7 @@ A rule shipped to consumers (`.agent-src.uncompressed/rules/`) may
 declare `load_context:` entries pointing at:
 
 - `.agent-src.uncompressed/contexts/` — public, OK.
-- `agents/contexts/` — package-internal, **lint warning** (the entry
+- `agents/settings/contexts/` — package-internal, **lint warning** (the entry
   will not exist in consumer projects).
 
 Project-local rules may reference either. The linter classifies by
@@ -194,7 +194,7 @@ Pattern proven by this consumer:
 - **Cite, don't duplicate** — the slim rule contains zero
   algorithm/mechanics/example prose; everything moved was physically
   removed (verified by Phase 2.5 obligation diff:
-  [`agents/reports/pr-34-phase-2-5-autonomous-execution-obligation-check.md`](../../agents/reports/pr-34-phase-2-5-autonomous-execution-obligation-check.md)).
+  [`agents/runtime/reports/pr-34-phase-2-5-autonomous-execution-obligation-check.md`](../../agents/runtime/reports/pr-34-phase-2-5-autonomous-execution-obligation-check.md)).
 - **Lazy by default** — no eager-load is declared; the budget guard
   is therefore a no-op for this rule.
 

package/docs/contracts/local-server-api.md

@@ -0,0 +1,134 @@
+---
+stability: beta
+keep-beta-until: 2026-08-17
+---
+
+# Local server API — `agent-config ui:serve`
+
+> **Status:** active · **Stability:** beta · **Owner:** ADR-012 (TypeScript CLI shell)
+> · **Surface:** `src/server/**` · **Tests:** `tests/server/**`
+
+Locks the wire shape, security stance, and lifecycle of the embedded
+HTTP server that `agent-config ui:serve` boots. Phase 5 of
+`typescript-cli-and-local-gui-foundation` ships this contract behind
+the flipped TS binary; downstream Roadmap-2 (in-browser wizard) builds
+against it.
+
+## § 1 — Bind and port
+
+- **Bind address.** `127.0.0.1` only. The server **never** binds to
+  `0.0.0.0` or a routable interface. Enforced in
+  `src/cli/commands/uiServe.ts`.
+- **Port range.** First free TCP port in `[41000, 41999]`, scanned
+  ascending. Picker: `src/server/port.ts#pickFreePort`. If the entire
+  range is occupied, the command exits non-zero with a guidance line
+  pointing at the range.
+- **No remote access.** No published TLS, no reverse-proxy story.
+  Operators who need remote access tunnel via `ssh -L` or equivalent;
+  the package does not ship that path.
+
+## § 2 — Authentication — per-process bearer token
+
+- Minted at boot by `src/server/token.ts#mintToken` (URL-safe,
+  256 bits of entropy from `crypto.randomBytes`).
+- Required on **every** `/api/*` route via either:
+  - `Authorization: Bearer <token>`, **or**
+  - `?token=<token>` query parameter (the UI uses this so the
+    browser can bootstrap from the URL).
+- Token comparison runs through `tokensMatch` — constant-time over
+  equal-length inputs.
+- The token is printed to **stderr** by `ui:serve` once, prefixed
+  with `agent-config: token=` so log scrapers can redact it. Never
+  written to disk by the package.
+- Static UI files under `/` are **not** gated — the browser must be
+  able to fetch the HTML before it can present the token.
+
+## § 3 — Defence-in-depth headers
+
+- **Host-header guard.** `Host` MUST be `127.0.0.1:<port>` or
+  `localhost:<port>`. Other values → `421 Misdirected Request`.
+  Blocks DNS-rebinding from a malicious page that resolves an
+  attacker-controlled hostname to `127.0.0.1`.
+- **Origin allow-list.** When `Origin` is present, it MUST equal
+  `http://127.0.0.1:<port>` or `http://localhost:<port>`. Other
+  values → `403 Forbidden`. Absent header is allowed (server-to-server
+  callers, `curl` without `-H`).
+- **CORS.** No `Access-Control-Allow-Origin` header. The server is
+  same-origin to the bundled UI by construction; browsers from any
+  other origin are blocked by the same-origin policy before
+  `Origin` is even checked.
+
+## § 4 — Routes
+
+### `GET /api/v1/ping`
+
+Liveness probe. Used by:
+- The bundled UI to confirm it reached the right process.
+- `agent-config doctor-shell` (future — Phase 6).
+- CI smoke tests (`tests/cli/cli-e2e.test.ts`).
+
+**Request:** no body. Token via header or query.
+
+**Response — `200 OK`:**
+
+```json
+{
+  "ok": true,
+  "version": "2.26.0",
+  "projectRoot": "/abs/path/to/project"
+}
+```
+
+- `ok` — literal `true`.
+- `version` — value of `package.json#version` at boot time.
+- `projectRoot` — absolute path the CLI resolved (see
+  `src/cli/paths.ts`).
+
+Schema source of truth: `src/server/routes/ping.ts#PingResponseSchema`
+(zod). Test gate: `tests/server/app.test.ts`.
+
+### Future routes (Phase 6+)
+
+Reserved namespace under `/api/v1/`. Adding a new route requires:
+- A zod schema export co-located with the handler.
+- A `tests/server/` integration test that exercises the auth gate
+  alongside the happy path.
+- A CHANGELOG entry under the active Unreleased block.
+
+## § 5 — Failure modes
+
+| Condition | HTTP | Body shape |
+|---|---|---|
+| Missing/invalid token on `/api/*` | `401` | `{ "error": "Unauthorized: …" }` |
+| Disallowed `Host` | `421` | `{ "error": "Misdirected Request: …" }` |
+| Disallowed `Origin` | `403` | `{ "error": "Forbidden: …" }` |
+| Port range exhausted | (no HTTP — CLI exit non-zero) | — |
+
+## § 6 — Lifecycle
+
+- **Boot.** `ui:serve` picks a free port, mints the token, builds
+  the Fastify app via `createApp`, and prints the URL + token to
+  stderr. By default it also opens the OS browser at `/` with the
+  token in the query string; `--no-open` suppresses that step.
+- **Headless detection.** When `process.stdout.isTTY === false` AND
+  `--open` was not explicitly passed, the server boots but does not
+  attempt to spawn a browser. Useful for CI and SSH sessions.
+- **Shutdown.** SIGINT / SIGTERM stops the server cleanly; the
+  per-process token is dropped from memory.
+
+## § 7 — Stability commitments
+
+- Wire shape (route paths, response keys, status codes) — covered
+  by the contract above. Breaking change requires SemVer-major.
+- Security stance (§ 1–3) — strengthening is non-breaking;
+  weakening (e.g. removing the Host guard) is a breaking change.
+- Port range — narrowing is breaking, widening is non-breaking.
+- The token is **never** exfiltrated to logs, telemetry, or
+  observability backends by the package itself.
+
+## Related contracts
+
+- `docs/decisions/ADR-012-typescript-cli-shell.md` — the parent
+  decision (shell choice, source layout, dependency surface).
+- `docs/contracts/STABILITY.md` — what `stability: beta` means and
+  the promotion path.

package/docs/contracts/low-impact-corpus-format.md

@@ -5,7 +5,7 @@ keep-beta-until: 2026-08-13
 
 # `low-impact-decisions.md` — corpus format contract (step-9 P4)
 
-Parser-visible invariants for `agents/low-impact-decisions.md` and any
+Parser-visible invariants for `agents/decisions/low-impact-decisions.md` and any
 upstream seed at the same path. The hardened parser lives in
 [`scripts/ai_council/low_impact_corpus.py`](../../scripts/ai_council/low_impact_corpus.py)
 and ships in two modes:

package/docs/contracts/mcp-cloud-scope.md

@@ -155,8 +155,8 @@ prose-only.
   any layer.
 - **Agent memory** — separate MCP server, different roadmap.
 - **Chat history persistence** — the local kernel writes to
-  `agents/.agent-chat-history`; the Worker has no equivalent. Listed
-  as a deprecated stub per above.
+  `agents/runtime/.agent-chat-history`; the Worker has no equivalent.
+  Listed as a deprecated stub per above.
 - **HMAC request signing.** Deferred to MVP-2 alongside tool
   restoration — see `## Auth surface` § `hmac-deferred`.
 - **Cloudflare Access integration.** Deferred to MVP-2 — see

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

@@ -7,7 +7,7 @@ stability: experimental
 **Audience:** MCP consumers integrating with `event4u/agent-config` — host
 applications, CLIs, agents calling our stdio server or the Cloudflare Worker.
 **Status:** active under the Discovery-First MCP coverage strategy
-([`mcp-coverage-strategy.md`](../../agents/contexts/mcp-coverage-strategy.md)).
+([`mcp-coverage-strategy.md`](../../agents/settings/contexts/mcp-coverage-strategy.md)).
 
 ## What you will see
 

package/docs/contracts/mcp-phase-1-scope.md

@@ -50,9 +50,10 @@ phase with its own design-call gate.
 - **`resources/*` beyond rules / guidelines / contexts** — no model
   outputs, no roadmaps, no chat history surfaced as resources.
 - **Filesystem writes outside the Phase 4 write allowlist** — the only
-  writable targets are `agents/.agent-chat-history` and
-  `.agent-chat-history` under `<consumer_root>`. No log files, no
-  telemetry writes, no `.work-state.json` mutation.
+  writable targets are `agents/runtime/.agent-chat-history` (current
+  default), `agents/.agent-chat-history`, and `.agent-chat-history`
+  under `<consumer_root>`. No log files, no telemetry writes, no
+  `.work-state.json` mutation.
 - **Direct shell execution from `mcp_server/*`** — modules under
   `scripts/mcp_server/` do not `import subprocess`, `os.system`, or
   `os.popen` directly. Project helpers that internally spawn shells
@@ -96,7 +97,7 @@ returns `isError=True`.
 | Tool name | Mode | Side effects |
 |---|---|---|
 | `lint_skills` | read-only | Wraps `scripts.skill_linter.lint_file`. Never spawns `git` (no `--changed`). Returns the same JSON shape as `scripts/skill_linter.py --format json`. |
-| `chat_history_append` | path-scoped write | Wraps `scripts.chat_history.append`. Writes are allowed only when the resolved target is `agents/.agent-chat-history` or `.agent-chat-history` under `<consumer_root>`. `dry_run=True` validates the payload without touching the filesystem. |
+| `chat_history_append` | path-scoped write | Wraps `scripts.chat_history.append`. Writes are allowed only when the resolved target is `agents/runtime/.agent-chat-history` (current default), `agents/.agent-chat-history`, or `.agent-chat-history` under `<consumer_root>`. `dry_run=True` validates the payload without touching the filesystem. |
 
 **Path-scoping invariant** — any tool that writes must resolve its
 target through `_validate_in_tree_path` before the underlying writer

package/docs/contracts/mcp-registry-manifest.schema.json

@@ -0,0 +1,129 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://event4u.app/schemas/mcp-registry-manifest.json",
+    "title": "MCP Registry Manifest",
+    "description": "Source of truth for every external MCP-registry submission. R5 Phase 2.1. Lifecycle status per entry — handles 'they said no' without rewriting history.",
+    "type": "object",
+    "additionalProperties": false,
+    "required": [
+        "version",
+        "generated_at",
+        "package",
+        "server",
+        "registries"
+    ],
+    "properties": {
+        "version": {
+            "const": 1
+        },
+        "generated_at": {
+            "type": "string",
+            "description": "UTC date (YYYY-MM-DD). Day-precision keeps the manifest stable across same-day reruns."
+        },
+        "package": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name", "version", "description", "homepage", "repository"],
+            "properties": {
+                "name": { "type": "string", "minLength": 1 },
+                "version": { "type": "string", "minLength": 1 },
+                "description": { "type": "string", "minLength": 1 },
+                "homepage": { "type": "string", "format": "uri" },
+                "repository": { "type": "string", "format": "uri" }
+            }
+        },
+        "server": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+                "name",
+                "transports",
+                "tools_count",
+                "install_hint_stdio"
+            ],
+            "properties": {
+                "name": { "type": "string", "minLength": 1 },
+                "transports": {
+                    "type": "array",
+                    "minItems": 1,
+                    "uniqueItems": true,
+                    "items": { "enum": ["stdio", "worker"] }
+                },
+                "tools_count": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "description": "Sourced from workers/mcp/content.json#/tool_catalog/tools. Hard-sourced — no fallback. R3 (discovery roadmap) is a hard prerequisite per the AI-Council external review."
+                },
+                "install_hint_stdio": { "type": "string", "minLength": 1 }
+            }
+        },
+        "topics": {
+            "type": "array",
+            "uniqueItems": true,
+            "items": { "type": "string", "minLength": 1 },
+            "description": "Mirror of `.github/topics.yml#/topics`. Lets registries that accept topic tags pick from one source."
+        },
+        "discovery": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["artefact_count", "scanner_version"],
+            "properties": {
+                "artefact_count": { "type": "integer", "minimum": 0 },
+                "scanner_version": { "type": "string", "minLength": 1 }
+            }
+        },
+        "registries": {
+            "type": "array",
+            "minItems": 2,
+            "maxItems": 2,
+            "items": { "$ref": "#/$defs/registry" }
+        }
+    },
+    "$defs": {
+        "registry": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+                "id",
+                "label",
+                "listing_format",
+                "submission_url",
+                "status",
+                "submitted_at",
+                "pr_url",
+                "last_verified",
+                "rendered_payload"
+            ],
+            "properties": {
+                "id": {
+                    "enum": ["awesome-mcp-servers", "mcp-cloudflare-catalogue"],
+                    "description": "Closed vocabulary. Adding a third registry requires a schema-version bump."
+                },
+                "label": { "type": "string", "minLength": 1 },
+                "listing_format": { "enum": ["markdown-row", "json-entry"] },
+                "submission_url": { "type": "string", "format": "uri" },
+                "status": {
+                    "enum": ["pending", "listed", "rejected", "unlisted"],
+                    "description": "Lifecycle. `pending` = not yet submitted. `listed` = upstream PR merged. `rejected` = upstream said no (don't auto-resubmit). `unlisted` = was listed, then removed."
+                },
+                "submitted_at": {
+                    "type": ["string", "null"],
+                    "description": "ISO date (YYYY-MM-DD) when the submission PR was opened. Null while status=pending."
+                },
+                "pr_url": {
+                    "type": ["string", "null"],
+                    "description": "URL of the submission PR. Null while status=pending."
+                },
+                "last_verified": {
+                    "type": ["string", "null"],
+                    "description": "ISO date (YYYY-MM-DD) the maintainer last opened the live listing and confirmed it still points at this package. Null while status=pending. SHOULD be refreshed every release."
+                },
+                "rendered_payload": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Repo-relative path to the rendered payload (e.g. `dist/mcp/awesome-mcp-servers.row.md`)."
+                }
+            }
+        }
+    }
+}

package/docs/contracts/mcp-tool-inventory.md

@@ -23,12 +23,12 @@ keep-beta-until: 2026-08-14
 
 | Tool | Side-effect | Transports | Catalog | Handler |
 |---|---|---|---|---|
-| `lint_skills` | `ro` | stdio | [`consumer_tool_catalog.json:7`](../../scripts/mcp_server/consumer_tool_catalog.json#L7) | [`tools.py:510`](../../scripts/mcp_server/tools.py#L510) |
-| `chat_history_append` | `fs-write` | stdio | [`consumer_tool_catalog.json:24`](../../scripts/mcp_server/consumer_tool_catalog.json#L24) | [`tools.py:535`](../../scripts/mcp_server/tools.py#L535) |
-| `chat_history_read` | `ro` | stdio | [`consumer_tool_catalog.json:43`](../../scripts/mcp_server/consumer_tool_catalog.json#L43) | [`tools.py:571`](../../scripts/mcp_server/tools.py#L571) |
-| `memory_lookup` | `ro` | stdio | [`consumer_tool_catalog.json:59`](../../scripts/mcp_server/consumer_tool_catalog.json#L59) | [`tools.py:590`](../../scripts/mcp_server/tools.py#L590) |
+| `lint_skills` | `ro` | stdio | [`consumer_tool_catalog.json:7`](../../scripts/mcp_server/consumer_tool_catalog.json#L7) | [`tools.py:521`](../../scripts/mcp_server/tools.py#L521) |
+| `chat_history_append` | `fs-write` | stdio | [`consumer_tool_catalog.json:24`](../../scripts/mcp_server/consumer_tool_catalog.json#L24) | [`tools.py:546`](../../scripts/mcp_server/tools.py#L546) |
+| `chat_history_read` | `ro` | stdio | [`consumer_tool_catalog.json:43`](../../scripts/mcp_server/consumer_tool_catalog.json#L43) | [`tools.py:586`](../../scripts/mcp_server/tools.py#L586) |
+| `memory_lookup` | `ro` | stdio | [`consumer_tool_catalog.json:59`](../../scripts/mcp_server/consumer_tool_catalog.json#L59) | [`tools.py:606`](../../scripts/mcp_server/tools.py#L606) |
 | `memory_signal` | `fs-write` | _(stub)_ | [`consumer_tool_catalog.json:75`](../../scripts/mcp_server/consumer_tool_catalog.json#L75) | _stub-only_ |
-| `memory_status` | `ro` | stdio | [`consumer_tool_catalog.json:91`](../../scripts/mcp_server/consumer_tool_catalog.json#L91) | [`tools.py:617`](../../scripts/mcp_server/tools.py#L617) |
+| `memory_status` | `ro` | stdio | [`consumer_tool_catalog.json:91`](../../scripts/mcp_server/consumer_tool_catalog.json#L91) | [`tools.py:633`](../../scripts/mcp_server/tools.py#L633) |
 | `skill_trigger_eval` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:98`](../../scripts/mcp_server/consumer_tool_catalog.json#L98) | _stub-only_ |
 | `suggest_command` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:114`](../../scripts/mcp_server/consumer_tool_catalog.json#L114) | _stub-only_ |
 | `suggest_skill_for_task` | `ro` | _(stub)_ | [`consumer_tool_catalog.json:129`](../../scripts/mcp_server/consumer_tool_catalog.json#L129) | _stub-only_ |
@@ -38,11 +38,11 @@ keep-beta-until: 2026-08-14
 | `sync_agent_settings` | `fs-write` | _(stub)_ | [`consumer_tool_catalog.json:186`](../../scripts/mcp_server/consumer_tool_catalog.json#L186) | _stub-only_ |
 | `run_tests` | `shell` | _(stub)_ | [`consumer_tool_catalog.json:200`](../../scripts/mcp_server/consumer_tool_catalog.json#L200) | _stub-only_ |
 | `run_quality_checks` | `shell` | _(stub)_ | [`consumer_tool_catalog.json:214`](../../scripts/mcp_server/consumer_tool_catalog.json#L214) | _stub-only_ |
-| `list_skills` | `ro` | stdio | [`consumer_tool_catalog.json:227`](../../scripts/mcp_server/consumer_tool_catalog.json#L227) | [`tools.py:631`](../../scripts/mcp_server/tools.py#L631) |
-| `list_commands` | `ro` | stdio | [`consumer_tool_catalog.json:234`](../../scripts/mcp_server/consumer_tool_catalog.json#L234) | [`tools.py:644`](../../scripts/mcp_server/tools.py#L644) |
-| `list_rules` | `ro` | stdio | [`consumer_tool_catalog.json:241`](../../scripts/mcp_server/consumer_tool_catalog.json#L241) | [`tools.py:657`](../../scripts/mcp_server/tools.py#L657) |
+| `list_skills` | `ro` | stdio | [`consumer_tool_catalog.json:227`](../../scripts/mcp_server/consumer_tool_catalog.json#L227) | [`tools.py:647`](../../scripts/mcp_server/tools.py#L647) |
+| `list_commands` | `ro` | stdio | [`consumer_tool_catalog.json:234`](../../scripts/mcp_server/consumer_tool_catalog.json#L234) | [`tools.py:660`](../../scripts/mcp_server/tools.py#L660) |
+| `list_rules` | `ro` | stdio | [`consumer_tool_catalog.json:241`](../../scripts/mcp_server/consumer_tool_catalog.json#L241) | [`tools.py:673`](../../scripts/mcp_server/tools.py#L673) |
 | `compile_router` | `shell` | _(stub)_ | [`consumer_tool_catalog.json:248`](../../scripts/mcp_server/consumer_tool_catalog.json#L248) | _stub-only_ |
-| `read_resource_body` | `ro` | stdio | [`consumer_tool_catalog.json:261`](../../scripts/mcp_server/consumer_tool_catalog.json#L261) | [`tools.py:670`](../../scripts/mcp_server/tools.py#L670) |
+| `read_resource_body` | `ro` | stdio | [`consumer_tool_catalog.json:261`](../../scripts/mcp_server/consumer_tool_catalog.json#L261) | [`tools.py:686`](../../scripts/mcp_server/tools.py#L686) |
 
 ## Glossary
 

package/docs/contracts/mcp-tool-stub-envelope.md

@@ -5,7 +5,7 @@ stability: experimental
 # MCP Tool Stub Envelope — Phase 1 Discovery Contract
 
 > **Status:** Active · governs the Discovery-First MCP coverage strategy
-> ([`mcp-coverage-strategy.md`](../../agents/contexts/mcp-coverage-strategy.md)).
+> ([`mcp-coverage-strategy.md`](../../agents/settings/contexts/mcp-coverage-strategy.md)).
 > **Stability:** experimental — internal index reference only per
 > `STABILITY.md`.
 

package/docs/contracts/memory-visibility-v1.md

@@ -64,7 +64,7 @@ The visibility line and the JSON it derives from MUST NOT contain:
 
 - Entry **bodies**, summaries, or quoted snippets.
 - Secrets, tokens, environment values, or paths outside the
-  package's `agents/state/` and `tests/` allowlist.
+  package's `agents/runtime/state/` and `tests/` allowlist.
 - User identifiers beyond what is already public in the working
   directory's `.agent-settings.yml` (e.g. developer name).
 
@@ -130,7 +130,7 @@ adoption work). Concretely:
 
 - The engine emits the line + the underlying counts to the
   decision-trace JSON.
-- A consumer hook reads `agents/state/work/<work-id>/decision-trace-*.json`,
+- A consumer hook reads `agents/runtime/state/work/<work-id>/decision-trace-*.json`,
   rolls counts up to the session level, and feeds the result back
   into the agent-memory store as an audit entry.
 

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

@@ -86,7 +86,7 @@ Cursor, Windsurf, Cline, Gemini, Copilot have **no native skill surface**. Skill
 | `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/reports/projection-fidelity.json`.
+Run: `python3 scripts/probe_projection_fidelity.py` — exits non-zero on any divergence. Report at `agents/runtime/reports/projection-fidelity.json`.
 
 ## Known divergences (do not file as bugs)
 
@@ -102,7 +102,7 @@ These are **architectural facts**, not regressions. They are documented so insta
 
 - [x] Fixture under `tests/fixtures/projection_fidelity/`
 - [x] Probe script under `scripts/probe_projection_fidelity.py`
-- [x] Report under `agents/reports/projection-fidelity.json`
+- [x] Report under `agents/runtime/reports/projection-fidelity.json`
 - [x] Per-tool guarantee table above
 - [x] Known-divergence list above
 
@@ -112,4 +112,4 @@ These are **architectural facts**, not regressions. They are documented so insta
 - [`augment-projection`](../architecture/augment-projection.md) — pipeline B (Augment-specific)
 - [`multi-tool-projection`](../architecture/multi-tool-projection.md) — pipeline C (the per-tool emitters)
 - [`rule-router`](rule-router.md) — the `triggers:` / `routes_to:` grammar this contract pins
-- [`agents/council-sessions/2026-05-14-v2-analysis/feedback/09-cross-tool-projection-fidelity.md`](../../agents/council-sessions/2026-05-14-v2-analysis/feedback/09-cross-tool-projection-fidelity.md) — origin council feedback <!-- council-ref-allowed: contract origin trace -->
+- [`agents/runtime/council/sessions/2026-05-14-v2-analysis/feedback/09-cross-tool-projection-fidelity.md`](../../agents/runtime/council/sessions/2026-05-14-v2-analysis/feedback/09-cross-tool-projection-fidelity.md) — origin council feedback <!-- council-ref-allowed: contract origin trace -->

package/docs/contracts/namespace.md

@@ -5,8 +5,8 @@ stability: stable
 # Namespace contract — skills, rules, commands, personas
 
 > Every artefact name is a **stable identifier**: routed to from
-> `router.json`, cited from skills, surfaced in `/help`, embedded in
-> command paths, and back-referenced in test fixtures. Drift breaks
+> `dist/router.json`, cited from skills, surfaced in `/help`, embedded
+> in command paths, and back-referenced in test fixtures. Drift breaks
 > all five surfaces silently.
 >
 > **Source:** Step-11 Phase 5 Step 1
@@ -43,7 +43,7 @@ permitted when the stem already encodes both (`commit`, `eloquent`,
 | `claude-memories` | Reserved for the `~/.claude/CLAUDE.md` shape — host-agent state, not a package artefact. |
 | `default` | Ambiguous with profile / mode defaults; collides with `.agent-settings.yml` keys. |
 | `index` | Reserved for auto-generated INDEX.md files. |
-| `router` | Reserved for `router.json` and the router contract. |
+| `router` | Reserved for `dist/router.json` and the router contract. |
 
 Reserved names apply at the **top level** of each artefact type. A
 sub-verb under a namespaced group (e.g. `council/default.md` →
@@ -97,21 +97,21 @@ python3 scripts/lint_namespace.py
 ```
 
 If the candidate fails, the linter prints the rule it violated.
-**Renames after release are expensive** — touch router.json, every
-skill citing the old name, the bench corpus, and consumer settings.
+**Renames after release are expensive** — touch `dist/router.json`,
+every skill citing the old name, the bench corpus, and consumer settings.
 Pay the naming cost once, upfront.
 
 ## 6. Relationship to the frontmatter contract
 
 The **shape** lives here. The **frontmatter keys** that carry the
 name (`name:` in skills, `id:` in rules) live in
-[`frontmatter-contract.md`](../../agents/docs/frontmatter-contract.md).
+[`frontmatter-contract.md`](../../agents/reference/docs/frontmatter-contract.md).
 Both contracts share the regex; this file is the source of truth for
 the regex string.
 
 ## 7. Why this exists
 
-`router.json` resolves `<kind>:<id>` strings at session start. Any
+`dist/router.json` resolves `<kind>:<id>` strings at session start. Any
 artefact rename breaks every routing entry pointing at the old name
 without compile-time error. The linter catches the rename at the PR
 boundary, not at runtime in a consumer.

package/docs/contracts/one-off-script-lifecycle.md

@@ -100,7 +100,7 @@ rule.
   archived as a one-off): the council CLI section of the package's
   command catalog.
 - The cleanup-mechanics context for housekeeping passes:
-  `agents/contexts/cleanup-mechanics.md`.
+  `agents/settings/contexts/cleanup-mechanics.md`.
 - Linter implementation: `scripts/lint_one_off_age.py`.
 
 ## Stability

package/docs/contracts/package-self-orientation.md

@@ -25,7 +25,7 @@ runtime. Installed via `scripts/install.sh` (Bash) and
 ## The four wings
 
 Four wings compose via [`cross-wing-handoff.md`](cross-wing-handoff.md)
-(beta). Per-wing plates live under `agents/roadmaps/` and `agents/contexts/`.
+(beta). Per-wing plates live under `agents/roadmaps/` and `agents/settings/contexts/`.
 
 | Wing | Cognition cluster |
 |---|---|

package/docs/contracts/provider-lifecycle.md

@@ -7,7 +7,7 @@ keep-beta-until: 2026-08-15
 
 > **Status:** active · **Stability:** beta · **Owner:** universal-platform-refinement Phase 3
 > · **Linter:** none (declarative contract; enforced agent-in-the-loop via [`provider-lifecycle-discipline`](../../.agent-src/rules/provider-lifecycle-discipline.md))
-> · **Source-of-truth template:** [`agents/.ai-video.xml.example`](../../agents/.ai-video.xml.example)
+> · **Source-of-truth template:** [`agents/templates/.ai-video.xml.example`](../../agents/templates/.ai-video.xml.example)
 
 Locks the lifecycle tagging used on every adapter under
 `scripts/ai-video/adapters/` (and future `scripts/ai-image/`,
@@ -33,7 +33,7 @@ the human noticing.
 1. **Real-API smoke run** — at least one live `submit / poll / fetch`
    cycle (or `run` for sync adapters) against the documented
    `default-model`, captured under
-   `agents/ai-video/smoke-traces/<provider>.md` with timestamp,
+   `agents/reference/ai-video/smoke-traces/<provider>.md` with timestamp,
    model id, and **redacted** response shape.
 2. **Secret-redaction confirmation** — the captured trace, re-read
    through `scripts/ai-video/lib/redact.sh`, shows zero residual
@@ -42,7 +42,7 @@ the human noticing.
    surface (`submit / poll / fetch / dry-run` *or* `run / dry-run`)
    matches `scripts/ai-video/lib/adapter-contract.md` verbatim.
 
-A maintainer flipping the tier in `agents/.ai-video.xml.example`
+A maintainer flipping the tier in `agents/templates/.ai-video.xml.example`
 **and** the adapter header comment is the promotion event. There is
 no separate registry — the example file is the registry.
 
@@ -67,7 +67,7 @@ When the agent picks a provider for a `/video:*` / `/image:*` /
 
 1. **Read** the `provider_lifecycle` tag from the adapter's header
    comment **and** the matching `<provider id="…">` block in
-   `agents/.ai-video.xml.example` (or the operator's
+   `agents/templates/.ai-video.xml.example` (or the operator's
    `agents/.ai-video.xml`).
 2. **Refuse-and-surface** if the operator's resolved default is a
    non-`stable` tier — name the tier and the path to this contract
@@ -103,7 +103,7 @@ so the agent surfaces the tier and asks before proceeding — the
 human is the policy decision point.
 
 The `<default-image-provider>` and `<default-video-provider>`
-entries in `agents/.ai-video.xml.example` remain unchanged
+entries in `agents/templates/.ai-video.xml.example` remain unchanged
 (`openai-images` and `gemini-veo`). The tier tag does not change
 defaults; it changes whether the agent silently honours them.
 
@@ -118,5 +118,5 @@ snapshot — older snapshots live in git history, not in this file.
 
 - [`provider-lifecycle-discipline`](../../.agent-src/rules/provider-lifecycle-discipline.md) — the tier-2 routing rule that surfaces this contract when a provider is touched.
 - [`scripts/ai-video/lib/adapter-contract.md`](../../scripts/ai-video/lib/adapter-contract.md) — the four-method shell contract every adapter implements.
-- [`agents/.ai-video.xml.example`](../../agents/.ai-video.xml.example) — operator-facing provider configuration template (carries the tier tag inline).
-- [`agents/policies/media/README.md`](../../agents/policies/media/README.md) — the agent-in-the-loop enforcement model this contract participates in.
+- [`agents/templates/.ai-video.xml.example`](../../agents/templates/.ai-video.xml.example) — operator-facing provider configuration template (carries the tier tag inline).
+- [`agents/settings/policies/media/README.md`](../../agents/settings/policies/media/README.md) — the agent-in-the-loop enforcement model this contract participates in.

package/docs/contracts/router-blending.md

@@ -24,7 +24,7 @@ loaded_skills(user_type) =
   ∪ context_pool(user_type)        (content / writing / safety, ≈10%)
 ```
 
-Percentages are **soft caps** measured against the post-filter skill count, not hard quotas. Drift > ±10% on any pool triggers a re-tag pass and a finding in `agents/eval-findings/`.
+Percentages are **soft caps** measured against the post-filter skill count, not hard quotas. Drift > ±10% on any pool triggers a re-tag pass and a finding in `agents/evidence/eval-findings/`.
 
 ## Per user-type blends
 

package/docs/contracts/rule-classification.md

@@ -117,7 +117,7 @@ existing skills under `.agent-src.uncompressed/skills/`.
 | model-recommendation | 2909 | `set-cost-profile` | Routing procedure |
 | onboarding-gate | 4881 | `onboard` | Mechanical: meta-rule about /onboard |
 | package-ci-checks | 1342 | `lint-skills` | Repo-specific procedure |
-| reviewer-awareness | 3573 | `review-routing` | Skill exists; consolidates former `review-routing-awareness` (2026-05-08, see `agents/contexts/adr-auto-rule-consolidation.md`) |
+| reviewer-awareness | 3573 | `review-routing` | Skill exists; consolidates former `review-routing-awareness` (2026-05-08, see `agents/settings/contexts/adr-auto-rule-consolidation.md`) |
 | skill-improvement-trigger | 1597 | `skill-improvement-pipeline` | Trigger procedure |
 | slash-command-routing-policy | 3218 | `command-routing` | Routing procedure |
 | ui-audit-gate | 3285 | `existing-ui-audit` | Audit procedure |
@@ -153,7 +153,7 @@ Reference / examples / mechanics. Body migrates into
    three resolution variants; this file syncs once the ADR lands.
 2. **`reviewer-awareness` + `review-routing-awareness` merge.** ✅ resolved
    2026-05-08 — merged into `reviewer-awareness` per
-   `agents/contexts/adr-auto-rule-consolidation.md`.
+   `agents/settings/contexts/adr-auto-rule-consolidation.md`.
 3. **`onboarding-gate` migration shape.** The rule fires only on the
    first turn; the migrated form must keep that trigger latch.
    Router state-machine primitives (once / every-turn / on-mode-

package/docs/contracts/rule-router.md

@@ -83,8 +83,8 @@ whose body is fully covered by an existing architectural contract.
 ## Compiled output — `router.json`
 
 `scripts/compile_router.py` reads every rule frontmatter and emits
-`router.json` at the repo root, used by host agents at session start.
-Deterministic key order, sorted lists, stable across runs.
+`dist/router.json` (tracked in git), used by host agents at session
+start. Deterministic key order, sorted lists, stable across runs.
 
 ```json
 {
@@ -110,7 +110,7 @@ Generated alongside `marketplace.json` during `task generate-tools`.
 
 ## Activation semantics
 
-The host agent reads `router.json` once per session. Per turn:
+The host agent reads `dist/router.json` once per session. Per turn:
 
 1. Always evaluate kernel rules.
 2. If `profile = minimal` → stop after kernel.
@@ -151,4 +151,4 @@ start, the router lookup is keyword/phrase/path/intent matching only.
 - This file: schema specification.
 - `kernel-membership.md` § 4: kernel locked count + SHAs.
 - `rule-classification.md`: per-rule tier + disposition pre-Phase-4.
-- `router.json` (generated): runtime artifact, never hand-edited.
+- `dist/router.json` (generated): runtime artifact, never hand-edited.