@event4u/agent-config 2.25.0 → 3.0.0

package/docs/contracts/file-ownership-matrix.md

@@ -18,7 +18,7 @@ keep-beta-until: 2026-08-12
 This contract defines the **schema** of the file-ownership matrix: the
 machine-readable JSON at `docs/contracts/file-ownership-matrix.json` and
 the human-readable mirror at
-`agents/contexts/structural/file-ownership-matrix.md`. Both are
+`agents/settings/contexts/structural/file-ownership-matrix.md`. Both are
 regenerated from `.agent-src.uncompressed/` by the generator and locked
 by CI.
 

package/docs/contracts/ghostwriter-schema.md

@@ -21,7 +21,7 @@ explicit `accept` step on `/ghostwriter:fetch` re-runs.
 
 ## Storage model (dual)
 
-- **Consumer projects** — `agents/ghostwriter/<slug>.md`. Real-person
+- **Consumer projects** — `agents/reference/ghostwriter/<slug>.md`. Real-person
   profiles live here. **Gitignored by default** via the package-managed
   `.gitignore` block. A `--shared` opt-in to commit profiles is
   deferred to v2; only the doc note lands in v1.
@@ -298,7 +298,7 @@ The lint runs in `task ci` and fails on:
 2. Any allowlisted file missing `fictional: true` in frontmatter.
 3. Any package-source file (`fictional: true`) carrying an `aliases:`
    field (aliases are a consumer-only feature; see [§ Aliases](#aliases)).
-4. Any consumer-side file under `agents/ghostwriter/` with `fictional: true`
+4. Any consumer-side file under `agents/reference/ghostwriter/` with `fictional: true`
    (fictional profiles belong in the package source, not consumer trees).
 5. Any consumer-side `aliases:` entry that violates the storage rules:
    shorter than 2 characters, non-Latin scripts (homoglyph protection),
@@ -325,7 +325,7 @@ cluster registration.
 
 ## Gitignore
 
-`agents/ghostwriter/*.md` (except `README.md`) is added to the
+`agents/reference/ghostwriter/*.md` (except `README.md`) is added to the
 package-managed `.gitignore` block ([`config/gitignore-block.txt`](../../config/gitignore-block.txt))
 and ignored by default. A `--shared` opt-in to commit profiles is
 deferred to v2.

package/docs/contracts/hook-architecture-v1.md

@@ -11,9 +11,9 @@ written, tested, and refactored against a stable surface.
 
 **Scope.** Defines the dispatcher's stdin/stdout shape, exit-code
 semantics, the `hook_manifest.yaml` schema, the concurrency contract
-for `agents/state/` writes, and the Copilot fallback pattern. Does
+for `agents/runtime/state/` writes, and the Copilot fallback pattern. Does
 **not** specify per-platform install paths — those live in
-[`chat-history-platform-hooks.md`](../../agents/contexts/chat-history-platform-hooks.md).
+[`chat-history-platform-hooks.md`](../../agents/settings/contexts/chat-history-platform-hooks.md).
 
 Last refreshed: 2026-05-04.
 
@@ -74,7 +74,7 @@ inferred from exit code only).
   "decision": "allow" | "block" | "warn",
   "reason": "human-readable, ≤ 200 chars",
   "additional_context": "optional — surfaces back to the model on platforms that support it",
-  "state_writes": ["agents/state/chat-history.json", "…"]
+  "state_writes": ["agents/runtime/state/chat-history.json", "…"]
 }
 ```
 
@@ -103,7 +103,7 @@ runs them **sequentially** in manifest order and reduces:
 in manifest order. Concerns are never run in parallel — concurrency
 guarantees rely on serial state writes.
 
-## Feedback channel — `agents/state/.dispatcher/<session_id>/`
+## Feedback channel — `agents/runtime/state/.dispatcher/<session_id>/`
 
 Exit-code reduction collapses the severity ladder to a single
 platform-native code, which can hide a `warn` behind a `block` or
@@ -112,7 +112,7 @@ without re-routing control flow, the dispatcher writes a feedback
 directory per invocation:
 
 ```
-agents/state/.dispatcher/<session_id>/
+agents/runtime/state/.dispatcher/<session_id>/
   <concern>.json     — one file per concern that ran
   summary.json       — rollup written after the last concern
 ```
@@ -176,9 +176,9 @@ platform, every event key must be in the agent-config event vocabulary.
 
 ## Concurrency — atomic state writes
 
-Concerns that write under `agents/state/` MUST use the pattern:
+Concerns that write under `agents/runtime/state/` MUST use the pattern:
 
-1. Acquire `fcntl.flock(LOCK_EX)` on `agents/state/.dispatcher.lock`.
+1. Acquire `fcntl.flock(LOCK_EX)` on `agents/runtime/state/.dispatcher.lock`.
 2. Write to a sibling `<dest>.tmp.<pid>` file in the same directory.
 3. `os.replace(tmp, dest)` — POSIX-atomic on the same filesystem.
 4. Release the lock.
@@ -195,7 +195,7 @@ writes (file ends with valid JSON, last-writer-wins).
 ## Copilot fallback pattern
 
 Copilot has no hook surface. Concerns whose source rule cites
-`agents/state/<concern>.json` MUST gain a "Copilot fallback" section
+`agents/runtime/state/<concern>.json` MUST gain a "Copilot fallback" section
 that:
 
 - Names the state file the concern would have written.
@@ -242,12 +242,12 @@ The corpus is platform-shape-representative, not platform-exhaustive
 
 ## Replay mode — `AGENT_CONFIG_REPLAY=1`
 
-Concerns that write under `agents/state/` MUST honor the
+Concerns that write under `agents/runtime/state/` MUST honor the
 `AGENT_CONFIG_REPLAY` env var: when set to `1`, skip all state
 mutations and run as read-only. The dispatcher passes the env var
 through to subprocess concerns unchanged. Concerns that do not honor
 the flag are listed by `./agent-config hooks:doctor` as not
-replay-safe; replay tests assert no `agents/state/` mutation
+replay-safe; replay tests assert no `agents/runtime/state/` mutation
 post-invocation.
 
 ## Stability

package/docs/contracts/kernel-membership.md

@@ -47,7 +47,7 @@ skill / guideline per `rule-classification.md`.
 > the ask-policy floor that the original four-gate test left as an
 > implicit consequence of #1+#4. Both amendments preserve the
 > existing 9-rule kernel set. See
-> `agents/council-sessions/20260506T044941Z-phase1-cross-check-r2.json`. <!-- council-ref-allowed: contract decision trace -->
+> `agents/runtime/council/sessions/20260506T044941Z-phase1-cross-check-r2.json`. <!-- council-ref-allowed: contract decision trace -->
 
 ## § 2 — Empirical compression rate (pilot)
 
@@ -76,7 +76,7 @@ outlier and sits inside the roadmap-stated 0.6–0.75 band. Risk
 asymmetry confirms the choice: under-estimating compressed size
 blows the 25k cap mid-P2.2 (no abort path); over-estimating just
 yields headroom. GPT-4o concurred. Source:
-`agents/council-sessions/20260506T044941Z-phase1-cross-check-r2.json`. <!-- council-ref-allowed: contract decision trace -->
+`agents/runtime/council/sessions/20260506T044941Z-phase1-cross-check-r2.json`. <!-- council-ref-allowed: contract decision trace -->
 
 **Pilot caveat — already-lean floor.** `agent-authority` (1217 chars
 pre-pilot) yielded only `r = 0.838`. Pre-compressed rules give less
@@ -145,6 +145,23 @@ Future edits to any kernel rule must keep the Iron-Law SHA stable
 (or land a deliberate ADR-tracked SHA update). Cap re-raise requires
 a new ADR.
 
+### § 4.2 — Post-P2.2 kernel addition (`user-interrupt-priority`)
+
+After the P2.2 lock, `user-interrupt-priority` was admitted as the
+10th kernel rule. It satisfies criterion (1) (Iron Law: stop → ask
+→ resume on user-interrupt signals) and criterion (3a) (pre-send
+gate — must fire before continuing the current task). The smoke
+baseline is bumped accordingly:
+
+- `scripts/smoke/kernel.sh` — `EXPECTED_KERNEL_COUNT=10`,
+  `EXPECTED_FENCE_CARRIERS=9`.
+- `docs/contracts/smoke-contracts.md` § 3.1 — `10 kernel rules · 9
+  carry Iron-Law fences · 1 dispatch index · ≤ 2 budget breaches`.
+
+The § 4 / § 4.1 tables remain the locked P2.2 baseline (9-rule
+snapshot, 2026-05-06); the 10th rule is tracked separately here
+until the next kernel re-measurement.
+
 † **agent-authority swap candidate (P1.4 ADR).** Sonnet 4.5 argues
 this is a routing index (zero Iron Law fences, dispatches to other
 kernel rules) and should be `compress-and-keep` (auto-tier-3),
@@ -268,7 +285,7 @@ with the trigger-relaxed parameter, lock new value, re-attempt.
 |---|---|---|
 | 2026-05-06 | `scripts/measure_rule_budget.py` | baseline (32 403 chars across 9 always-rules) |
 | 2026-05-06 | `docs/contracts/pilot/*.md` + `scripts/_pilot_measure.py` | empirical r distribution (3 pilots) |
-| 2026-05-06 | `agents/council-sessions/20260506T044821Z-phase1-cross-check.json` | Council R1 (truncated at 1024 tokens) | <!-- council-ref-allowed: contract decision trace -->
-| 2026-05-06 | `agents/council-sessions/20260506T044941Z-phase1-cross-check-r2.json` | Council R2 (3500 tokens) — locks median r, splits criterion #3, adds criterion #5, raises per-rule cap to 2.5k, defines abort criteria | <!-- council-ref-allowed: contract decision trace -->
+| 2026-05-06 | `agents/runtime/council/sessions/20260506T044821Z-phase1-cross-check.json` | Council R1 (truncated at 1024 tokens) | <!-- council-ref-allowed: contract decision trace -->
+| 2026-05-06 | `agents/runtime/council/sessions/20260506T044941Z-phase1-cross-check-r2.json` | Council R2 (3500 tokens) — locks median r, splits criterion #3, adds criterion #5, raises per-rule cap to 2.5k, defines abort criteria | <!-- council-ref-allowed: contract decision trace -->
 | 2026-05-06 | this file | kernel set locked: 9 rules, projected 23 071 chars (median r = 0.712) |
 | 2026-05-06 | P2.2 compression + `scripts/iron_law_sha.py --all-kernel` | empirical: 25 590 chars (r_actual = 0.795 across kernel; longer rules compress less than the pilot median) — see `docs/decisions/ADR-002-kernel-bucket-overrides.md` (KERNEL_HARD raised 25k → 26k, 6 per-rule overrides ≤ 4k ceiling, all Iron-Law SHAs preserved) |

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

@@ -65,9 +65,9 @@ imperatives (`NEVER COMMIT.`).
 
 Sweep covered all 310 lintable artifacts via
 [`scripts/measure_density.py`](../../scripts/measure_density.py); raw
-data lives at `agents/.density-snapshot.jsonl` (local-only — re-run
+data lives at `agents/runtime/density/snapshot.jsonl` (local-only — re-run
 `python3 scripts/measure_density.py --root .agent-src --jsonl
-agents/.density-snapshot.jsonl` to regenerate).
+agents/runtime/density/snapshot.jsonl` to regenerate).
 
 | Type | Count | Avg density | Median | Bucket [0.4-0.6] | Bucket [0.6-1.0] |
 |---|---|---|---|---|---|
@@ -172,7 +172,7 @@ keys** — the structural primitives are the contract.
 ## References
 
 - `scripts/measure_density.py` — Phase 1.1 measurement tool.
-- `agents/.density-snapshot.jsonl` — full per-artifact metrics
+- `agents/runtime/density/snapshot.jsonl` — full per-artifact metrics
   (gitignored, re-run the measurement script to regenerate).
 - `scripts/skill_linter.py` — structural-model implementation
   (`_density_score`, `_count_procedure_sections`,

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-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

@@ -105,7 +105,7 @@ Pay the naming cost once, upfront.
 
 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.
 

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 |
 |---|---|