@event4u/agent-config 2.25.0 → 3.0.0

package/docs/contracts/provider-lifecycle.md

@@ -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
@@ -119,4 +119,4 @@ 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/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/settings-api.md

@@ -0,0 +1,160 @@
+---
+stability: beta
+keep-beta-until: 2026-08-18
+---
+
+# Settings GUI — REST API Contract (v1)
+
+> Local-only HTTP API exposed by `agent-config ui:serve` and reused by
+> `agent-config settings` / `agent-config setup`. Listens on `127.0.0.1`
+> only; no auth, no cross-origin. The browser SPA is the sole client —
+> the legacy `/onboard` chat skill has been retired.
+>
+> Server-side validators live in `src/server/schemas/`; the JSON-Schema
+> emitted at `GET /api/v1/schema` is derived from those Zod modules via
+> `zod-to-json-schema` so client and server cannot drift.
+
+## Conventions
+
+- Base path: `/api/v1`. Any breaking change bumps the version segment.
+- Content type: `application/json; charset=utf-8` on every request and
+  response unless noted.
+- Errors: HTTP status carries the verdict; bodies are
+  `{ error: { code, message, fields?: Array<{ path, message }> } }`.
+- Time format: ISO-8601 UTC (`2026-05-20T14:23:11.842Z`).
+- File mtime: integer milliseconds since epoch (`fs.statSync(...).mtimeMs`
+  truncated to integer) — wire-stable across JSON parsers.
+- Optimistic locking: every endpoint that mutates an on-disk file
+  echoes `lastModified` on read and requires `If-Unmodified-Since` on
+  write. Drift returns **409 Conflict** with the current file body so
+  the client can render a 3-way merge.
+
+## Endpoints
+
+### `GET /api/v1/schema`
+
+Returns the JSON-Schema rendition of `settingsSchema` and `userMdSchema`
+so the SPA can build forms without bundling Zod.
+
+Response (200):
+
+```json
+{
+    "settings": { "$schema": "...", "type": "object", "properties": { ... } },
+    "userMd":   { "$schema": "...", "type": "object", "properties": { ... } },
+    "generatedAt": "2026-05-20T14:23:11.842Z"
+}
+```
+
+### `GET /api/v1/settings`
+
+Reads `<projectRoot>/.agent-settings.yml` and returns the parsed values
+plus the freshness token for optimistic locking.
+
+Response (200):
+
+```json
+{
+    "values":       { "cost_profile": "balanced", "...": "..." },
+    "lastModified": 1747749791842,
+    "path":         ".agent-settings.yml"
+}
+```
+
+Errors: **404** when the file is missing (the SPA should redirect to
+`/#/wizard/Welcome`); **500** with `code=YAML_PARSE` when YAML parsing
+fails (body includes the line/column).
+
+### `POST /api/v1/settings/diff`
+
+Computes the merged delta without writing. Used by the **Preview
+changes** modal. Request:
+
+```json
+{
+    "values":             { "...": "..." },
+    "ifUnmodifiedSince":  1747749791842
+}
+```
+
+Response (200): `{ "changes": [{ "path": "cost_profile", "from": "minimal", "to": "balanced" }, ...] }`.
+
+Errors: **409** on mtime drift; **422** on validation failure (`fields`
+populated).
+
+### `PUT /api/v1/settings`
+
+Validates, merges with disk, writes atomically.
+
+Request: same shape as `/diff`. Required header:
+`If-Unmodified-Since: <ms-epoch>`.
+
+Response (200): `{ "lastModified": <new-ms-epoch>, "writtenPaths": [".agent-settings.yml"] }`.
+
+Errors: **412 Precondition Required** when the header is absent;
+**409 Conflict** when the on-disk mtime is newer than the header value;
+**422 Unprocessable Entity** with per-field errors on validation
+failure; **500** with `code=ATOMIC_WRITE` if the temp-rename loop fails.
+
+### `GET /api/v1/user-md`
+
+Reads `<projectRoot>/.agent-user.md`. Returns `{ body: '', exists: false, lastModified: null }`
+when the file is missing (wizard pre-fill case).
+
+### `GET /api/v1/user-md/template`
+
+Returns the package-shipped template (`templates/agent-user.md`) when
+present, else 204 No Content. Wizard uses this to pre-fill the textarea
+on first run.
+
+### `PUT /api/v1/user-md`
+
+Validates the body through `userMdSchema` (`gray-matter` parse must
+succeed; ≤ 8 000 chars). Atomic-writes with mode 0600.
+
+Required header: `If-Unmodified-Since: <ms-epoch>` (omitted only when
+`exists=false` on the prior GET — server treats absence as "create new").
+
+### `GET /api/v1/wizard/state`
+
+Returns the persisted partial wizard state, or
+`{ step: 0, totalSteps: <N>, partial: {}, startedAt: null }` when no
+state file exists.
+
+### `POST /api/v1/wizard/state`
+
+Persists partial state between step transitions. Body:
+`{ step: number, partial: Record<string, unknown> }`.
+
+### `POST /api/v1/wizard/finish`
+
+Two-Phase-Commit (council HIGH 2026-05-18): assigns a `txnId`, writes
+`settings.yml.tmp-{txnId}` + `user-md.tmp-{txnId}` + an empty
+`wizard.commit-intent-{txnId}` marker, renames both target files, then
+deletes the marker. Server boot replays orphaned markers idempotently.
+
+Response (200): `{ writtenPaths: string[], txnId: string }`.
+
+Errors: **500** with `code=TXN_PARTIAL` when the marker survives a crash
+(client should redirect the user to a "your last save is being
+recovered" screen and refetch state).
+
+## Status codes summary
+
+| Code | Meaning                                              |
+| ---- | ---------------------------------------------------- |
+| 200  | Success                                              |
+| 204  | No content (template-not-shipped case)               |
+| 404  | Target file missing                                  |
+| 409  | `If-Unmodified-Since` drift                          |
+| 412  | `If-Unmodified-Since` header missing on write        |
+| 422  | Validation failure (`error.fields` populated)        |
+| 500  | YAML parse / atomic-write / 2PC partial recovery     |
+
+## Test fixtures
+
+Round-trip fixtures live in `tests/server/fixtures/`. Every endpoint
+above has a happy-path test in `tests/server/<endpoint>.test.ts` and at
+least one error-path test (409 or 422). The schema↔template parity
+test (`tests/server/schemas/parity.test.ts`) is the gate that keeps
+`settingsSchema` and `config/agent-settings.template.yml` in lockstep.

package/docs/contracts/settings-gui-agent-mode.schema.json

@@ -0,0 +1,128 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://event4u.app/contracts/settings-gui-agent-mode.schema.json",
+    "title": "settings-gui-agent-mode",
+    "description": "Machine-readable mode of `agent-config settings`. When invoked with `--agent`, the CLI emits a single JSON envelope to stdout instead of opening a browser; the caller (chat agent, CI script, IDE extension) drives the wizard or settings editor via the same `/api/v1/*` routes through this envelope. Lives at `docs/contracts/settings-gui-agent-mode.schema.json` per the frontend-engineer council finding (roadmap line 333).",
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["version", "kind", "endpoint", "auth"],
+    "properties": {
+        "version": {
+            "type": "string",
+            "const": "1",
+            "description": "Envelope schema version. Bumped on breaking changes."
+        },
+        "kind": {
+            "type": "string",
+            "enum": ["wizard", "settings"],
+            "description": "Which mode the server booted in. `wizard` = first-run flow; `settings` = settings editor."
+        },
+        "endpoint": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["base", "discoveryFile"],
+            "properties": {
+                "base": {
+                    "type": "string",
+                    "format": "uri",
+                    "pattern": "^http://127\\.0\\.0\\.1:[0-9]+/?$",
+                    "description": "Fastify server URL. Always 127.0.0.1; the port is picked from the foundation roadmap's port-picker."
+                },
+                "discoveryFile": {
+                    "type": "string",
+                    "description": "Absolute path to `.agent-config/skill-bridge.port` / `.token` / `.pid` discovery file the caller should read for handshake."
+                }
+            }
+        },
+        "auth": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["scheme", "token"],
+            "properties": {
+                "scheme": {
+                    "type": "string",
+                    "const": "Bearer"
+                },
+                "token": {
+                    "type": "string",
+                    "description": "Random per-boot token; the caller MUST send `Authorization: Bearer <token>` on every API request. Token rotates on every `agent-config settings` boot."
+                }
+            }
+        },
+        "routes": {
+            "type": "object",
+            "description": "Stable list of routes the caller may use. Schema-bound to roadmap step 0.4; new routes added here MUST land in `docs/contracts/settings-api.md` simultaneously.",
+            "additionalProperties": false,
+            "properties": {
+                "settings": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "get": {"type": "string", "const": "/api/v1/settings"},
+                        "diff": {"type": "string", "const": "/api/v1/settings/diff"},
+                        "put": {"type": "string", "const": "/api/v1/settings"}
+                    }
+                },
+                "userMd": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "get": {"type": "string", "const": "/api/v1/user-md"},
+                        "put": {"type": "string", "const": "/api/v1/user-md"},
+                        "template": {"type": "string", "const": "/api/v1/user-md/template"}
+                    }
+                },
+                "wizard": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "state": {"type": "string", "const": "/api/v1/wizard/state"},
+                        "finish": {"type": "string", "const": "/api/v1/wizard/finish"}
+                    }
+                }
+            }
+        },
+        "shutdown": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["signal", "timeoutSeconds"],
+            "properties": {
+                "signal": {
+                    "type": "string",
+                    "enum": ["SIGTERM", "SIGINT"],
+                    "description": "Signal the caller sends to gracefully stop the server."
+                },
+                "timeoutSeconds": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 60,
+                    "description": "Caller's grace window before SIGKILL. Server drains in-flight requests within this window."
+                }
+            }
+        },
+        "capabilities": {
+            "type": "array",
+            "description": "Optional feature flags the server advertises. Callers MAY ignore unknown values for forward compatibility.",
+            "items": {
+                "type": "string",
+                "enum": ["wizard.resumeState", "settings.diff", "settings.optimisticLock", "userMd.template", "wizard.crashRecovery"]
+            },
+            "uniqueItems": true
+        }
+    },
+    "examples": [
+        {
+            "version": "1",
+            "kind": "settings",
+            "endpoint": {
+                "base": "http://127.0.0.1:41999/",
+                "discoveryFile": "/Users/dev/proj/.agent-config/skill-bridge.port"
+            },
+            "auth": {
+                "scheme": "Bearer",
+                "token": "9f3a7b2c1d4e8f6a"
+            },
+            "capabilities": ["settings.diff", "settings.optimisticLock"]
+        }
+    ]
+}

package/docs/contracts/smoke-contracts.md

@@ -51,11 +51,11 @@ constant in the script body and the row below.
 ### § 3.1 — Kernel (`scripts/smoke/kernel.sh`)
 
 ```
-9 kernel rules · 8 carry Iron-Law fences · 1 dispatch index · ≤ 2 budget breaches
+10 kernel rules · 9 carry Iron-Law fences · 1 dispatch index · ≤ 2 budget breaches
 ```
 
-- **9 kernel rules** — fixed by [`kernel-membership.md`](kernel-membership.md).
-- **8 carry Iron-Law fences** — measured 2026-05-16. `agent-authority`
+- **10 kernel rules** — fixed by [`kernel-membership.md`](kernel-membership.md).
+- **9 carry Iron-Law fences** — measured 2026-05-16. `agent-authority`
   is the **dispatch index** (priority table pointing at the other four
   authority rules); it is structurally exempt from the Iron-Law-fence
   requirement and listed in the script's `EXEMPT_FROM_FENCE` set.
@@ -70,13 +70,13 @@ constant in the script body and the row below.
 ### § 3.2 — Router (`scripts/smoke/router.sh`)
 
 ```
-75 router ids · 0 broken rule pointers · 35 routes_to refs · 2 missing contracts
+68 router ids · 0 broken rule pointers · 36 routes_to refs · 2 missing contracts
 ```
 
-- **75 ids** — 9 kernel + 24 tier_1 + 42 tier_2; every id resolves to
+- **68 ids** — 10 kernel + 23 tier_1 + 35 tier_2; every id resolves to
   `.agent-src/rules/<id>.md`.
 - **0 broken rule pointers** — hard assertion; smoke fails on any miss.
-- **35 routes_to refs** across tier_1 + tier_2; resolver honours the
+- **36 routes_to refs** across tier_1 + tier_2; resolver honours the
   four prefixes (`skill:`, `command:`, `guideline:`, `contract:`).
 - **2 missing contracts** — measured 2026-05-16:
   `contract:artifact-engagement-flow`,
@@ -130,7 +130,7 @@ the final baseline line) for CI summary parsing.
 
 | Symptom | Likely cause | Fix |
 |---|---|---|
-| `kernel.sh` reports > 8 missing fences | Kernel rule lost its Iron Law block during edit | Restore the fence; update `EXEMPT_FROM_FENCE` only for new dispatch indexes |
+| `kernel.sh` reports > 9 missing fences | Kernel rule lost its Iron Law block during edit | Restore the fence; update `EXEMPT_FROM_FENCE` only for new dispatch indexes |
 | `router.sh` reports > 0 broken pointers | `router.json` references an id without a rule file | Add the rule or remove the route — never edit the smoke baseline up |
 | `schema.sh` reports FAILs | A skill / rule lost a required field | Restore via [`scripts/schemas/skill.schema.json`](../../scripts/schemas/skill.schema.json) |
 | `skills.sh` 5/5 random sample fails | Hand-edit broke frontmatter or renamed directory without updating `name:` | Restore filename ↔ slug coupling |
@@ -139,6 +139,6 @@ the final baseline line) for CI summary parsing.
 
 - [`measurement-baseline.md`](measurement-baseline.md) — measurement substrate.
 - [`cost-enforcement.md`](cost-enforcement.md) — cost ladder, sibling smoke surface.
-- [`kernel-membership.md`](kernel-membership.md) — the 9-rule kernel set.
+- [`kernel-membership.md`](kernel-membership.md) — the 10-rule kernel set.
 - [`rule-router.md`](rule-router.md) — router contract.
 - `road-to-kernel-and-router.md` — kernel budget reduction path.

package/docs/contracts/tier-3-contrib-plugin.md

@@ -34,7 +34,7 @@ Tier-3 is the explicit overflow bucket.
 
 The following surfaces are Tier-3 candidates as of 2026-05-12. They
 were surfaced during the
-[`2026-05-12-installer-expansion`](../../agents/council-sessions/2026-05-12-installer-expansion/synthesis.md)
+[`2026-05-12-installer-expansion`](../../agents/runtime/council/sessions/2026-05-12-installer-expansion/synthesis.md)
 council round and have **no entries** in `_VALID_TOOLS`,
 `USER_SCOPE_PATHS`, `SCOPE_SUPPORT`, or the bash `VALID_TOOLS` set.
 

package/docs/contracts/universal-skills.md

@@ -76,7 +76,7 @@ Adding a skill to this allowlist:
 1. Open a PR that edits this file + the relevant skill's `recommended_for_user_types:` (omitted = universal).
 2. Cite ≥ 4 user-type prompts from `tests/eval/corpus-non-dev.yaml` that select the skill.
 3. Require approval from one Tier-1 reviewer (architecture-review-lens or skill-writing).
-4. Document the inclusion in `agents/eval-findings/` with the supporting eval prompts.
+4. Document the inclusion in `agents/evidence/eval-findings/` with the supporting eval prompts.
 
 Removing a skill is breaking. It must be announced in `STABILITY.md` with a deprecation window ≥ one minor release.
 

package/docs/contracts/write-engine.md

@@ -24,7 +24,7 @@ consumer command; the **only** axis of variation is:
 
 | Consumer command | Style source | Footer |
 |---|---|---|
-| `/ghostwriter:write` | `agents/ghostwriter/<slug>.md` (selected) | **Mandatory** |
+| `/ghostwriter:write` | `agents/reference/ghostwriter/<slug>.md` (selected) | **Mandatory** |
 | `/post-as:ghostwriter` | Same as above (thin alias) | **Mandatory** |
 | `/post-as:me` | `.agent-user.md` (project root) | **Omitted** — user is the author |
 

package/docs/customization.md

@@ -98,12 +98,12 @@ config. Use a subdirectory `.agent-settings.yml` to scope a single
 field (e.g. a `cost_profile` override for `services/heavy-ml/`) without
 duplicating the root file.
 
-The user-global file is created **only on explicit opt-in via
-`/onboard`**. The loader at
+The user-global file is created **only on explicit opt-in via the
+setup wizard** (`agent-config setup`). The loader at
 [`scripts/_lib/agent_settings.py`](../scripts/_lib/agent_settings.py)
-is **read-only** — no script can create or mutate it without an
-explicit `/onboard` confirmation. Edit the file by hand for mid-life
-changes; `/sync-agent-settings` stays project-scoped and never touches
+is **read-only** — no script can create or mutate it without explicit
+wizard confirmation. Edit the file by hand for mid-life changes;
+`/sync-agent-settings` stays project-scoped and never touches
 user-global state.
 
 ### Agent config version pin
@@ -134,6 +134,36 @@ Rules:
   triggers a re-exec at the pinned version
   (`npx @event4u/agent-config@<pin> <cmd>`).
 
+### Editing settings
+
+`.agent-settings.yml` has two write surfaces — both share one
+canonical commit path:
+
+#### Via the GUI (recommended)
+
+Run `agent-config setup` for first-run onboarding (cost profile,
+identity, personality, memory, roadmap quality, optional
+`.agent-user.md`) or `agent-config settings` for subsequent edits.
+Both launch the same Fastify server on `127.0.0.1`; the setup
+command lands on `/#/wizard`, the settings command on `/#/settings`.
+Form primitives, JSON schema, and the `commitMulti` 2PC write path
+are shared. See [`docs/wizard.md`](wizard.md) for the step-by-step
+tour.
+
+#### By hand-editing the YAML (advanced)
+
+Open `.agent-settings.yml` in an editor and save. Hand edits skip
+the 2PC marker dance (your editor's atomic save is trusted), but
+you lose the schema validation, optimistic locking, and template
+substitution the GUI surfaces provide. Use this path for quick
+tweaks, comments, or bulk edits across multiple keys.
+
+#### Shared substrate
+
+Both GUI surfaces call `commitMulti` (2PC + intent marker,
+comment-preserving merge via `mergeIntoTemplate`); a crash mid-write
+is recovered on the next server boot.
+
 ### Available settings
 
 | Setting | Default | Description |
@@ -146,11 +176,11 @@ Rules:
 | `personal.open_edited_files` | `false` | Open edited files in IDE |
 | `personal.ide` | *(empty)* | IDE for file opening (`cursor`, `code`, `phpstorm`) |
 | `pipelines.skill_improvement` | `true` | Post-task learning capture. Included in every profile except `custom`. |
-| `chat_history.enabled` | `true` | Persistent JSONL log at `agents/.agent-chat-history` for crash recovery. |
+| `chat_history.enabled` | `true` | Persistent JSONL log at `agents/runtime/.agent-chat-history` for crash recovery. |
 | `chat_history.frequency` | per profile | Logging granularity: `per_turn`, `per_phase`, or `per_tool` (see matrix below). |
 | `chat_history.max_size_kb` | per profile | Max file size before overflow handling (see matrix below). |
 | `chat_history.on_overflow` | per profile | `rotate` drops oldest, `compress` marks for summarization (see matrix below). |
-| `onboarding.onboarded` | `false` | Whether `/onboard` has run. The `onboarding-gate` rule prompts for `/onboard` while this is `false`. |
+| `onboarding.onboarded` | `false` | Whether the setup wizard has run. The `onboarding-gate` rule prompts for `agent-config setup` while this is `false`. |
 | `ai_council.enabled` | `false` | Master switch for the `/council` command. Even when enabled, every consultation asks before spending tokens. |
 | `ai_council.members.<provider>.enabled` | `false` | Per-provider opt-in (`anthropic`, `openai`). Tokens live in `~/.event4u/agent-config/<provider>.key` (mode 0600), never in this file. Legacy `~/.config/agent-config/<provider>.key` is read as a fallback. |
 | `ai_council.members.<provider>.model` | per provider | Which model the provider sends the query to (e.g. `claude-sonnet-4-5`, `gpt-4o`). |
@@ -159,7 +189,7 @@ Rules:
 | `ai_council.cost_budget.max_calls` | `10` | Maximum council members per invocation. |
 | `ai_council.cost_budget.max_total_usd` | `0.0` | Per-invocation USD ceiling. `0` disables (token caps still apply). |
 | `ai_council.cost_budget.daily_limit_usd` | `0.0` | Rolling 24h USD ceiling across all `/council` calls. `0` disables. Ledger lives at `~/.event4u/agent-config/council-spend.jsonl` (mode 0600). |
-| `ai_council.session_retention_days` | `14` | Auto-prune for `agents/council-sessions/` audit folders. Older session directories are removed on the next `save()`. `0` disables (keep forever). |
+| `ai_council.session_retention_days` | `14` | Auto-prune for `agents/runtime/council/sessions/` audit folders. Older session directories are removed on the next `save()`. `0` disables (keep forever). |
 
 > **Experimental.** AI Council is not yet validated by external users. API costs apply per consultation.
 
@@ -314,15 +344,15 @@ shadowed.
 | Subdir | Cascade? | User-global allowed? | Why |
 |---|---|---|---|
 | `agents/overrides/` | ✅ Yes — deepest wins by basename. | ✅ Yes — weakest layer. | Personal developer overrides. |
-| `agents/contexts/` | ✅ Yes — deepest wins by basename. | ❌ No — project-shaped. | Shared knowledge; would leak across projects. |
+| `agents/settings/contexts/` | ✅ Yes — deepest wins by basename. | ❌ No — project-shaped. | Shared knowledge; would leak across projects. |
 | `agents/decisions/` | ✅ Yes — deepest wins by basename. | ❌ No — project-shaped ADRs. | Decisions are repo-bound. |
 | `agents/roadmaps/` | ❌ No — project-rooted only. | ❌ No. | Active delivery plans. |
-| `agents/state/`, `agents/memory/`, `agents/work_engine/`, `agents/.agent-prices.md`, `agents/council-*/` | ❌ No — stateful / session-scoped. | ❌ No. | Per-session state, not shareable. |
+| `agents/runtime/state/`, `agents/memory/`, `agents/work_engine/`, `agents/runtime/.agent-prices.md`, `agents/runtime/council/*/` | ❌ No — stateful / session-scoped. | ❌ No. | Per-session state, not shareable. |
 
 **User-global asymmetry.** `~/.event4u/agent-config/agents/overrides/`
 is the only user-global overlay path consulted by the loader (the
 legacy `~/.config/agent-config/agents/overrides/` tree is read as a
-fallback). Files under `~/.event4u/agent-config/agents/contexts/` or
+fallback). Files under `~/.event4u/agent-config/agents/settings/contexts/` or
 `.../agents/decisions/` are silently skipped — these kinds are
 project-shaped and must not leak across projects.
 
@@ -334,6 +364,57 @@ between the code constants (`CASCADE_ELIGIBLE_KINDS`,
 
 ---
 
+## Workspaces & packs (discovery)
+
+Every shipped artefact (skill, rule, command, template) carries five
+discovery keys in its frontmatter — `workspaces:`, `packs:`,
+`lifecycle:`, `trust:`, `install:`. The contract is defined in
+[ADR-013](decisions/ADR-013-discovery-frontmatter-contract.md) and the
+closed vocabularies live in
+[`config/discovery/workspaces.yml`](../config/discovery/workspaces.yml)
+(9 workspaces) and
+[`config/discovery/packs.yml`](../config/discovery/packs.yml) (21
+packs).
+
+At release time, `scripts/build_discovery_manifest.py` walks the source
+trees, validates frontmatter against the vocabularies, and writes
+`dist/discovery/discovery-manifest.json` + the human-readable
+`discovery-manifest.summary.md`. The manifest ships inside the published
+tarball and is the source of truth consumed by:
+
+- `npx @event4u/agent-config workspaces ls` / `packs ls` (CLI)
+- the installer's pack-selection prompts
+- downstream tools that resolve "which skills install for workspace X".
+
+> **Virtual packs and workspaces — a tag, not a directory.** A pack is a
+> label in an artefact's frontmatter, not a folder on disk. A workspace
+> is a label that groups packs, not a git submodule. The discovery
+> scanner emits a JSON catalogue; it does **not** move files, create
+> sub-`package.json` entries, or generate per-pack `node_modules/`.
+> When you read "the Laravel pack", picture a filter over the shared
+> artefact tree — not a separate npm package. The day ADR-011's
+> extraction trigger flips, the same scan output drives the split;
+> until then, every artefact lives under `.agent-src.uncompressed/`.
+
+Alongside the JSON manifest, the scanner writes
+`dist/discovery/discovery-manifest.json.sha256` — a sidecar hash that
+lets downstream consumers detect tampering before trusting the
+manifest's `trust.level` claims.
+
+CI gates: `task lint-discovery-vocab` (vocabulary integrity),
+`task lint-discovery-manifest` (manifest validity),
+`task lint-artefact-frontmatter` (per-file frontmatter sanity), and
+`task check-discovery-determinism` (byte-identical re-runs).
+`task check-release-includes-discovery` is the prepublish guard that
+refuses to ship a tarball without the manifest.
+
+Consumer projects do **not** edit these YAMLs directly — they pick
+packs at install time via `npx @event4u/agent-config install` and the
+resulting `.agent-settings.yml` records which packs the project opted
+into.
+
+---
+
 ## Update check
 
 `npx @event4u/agent-config <cmd>` checks the npm registry once per
@@ -378,4 +459,49 @@ dispatcher integration lives in [`scripts/agent-config`](../scripts/agent-config
 
 ---
 
+## Explainability — `explain last`
+
+`agent-config explain last` reconstructs the execution trace for the
+most recent `/work`, `/implement-ticket`, `/council`, or `/video` run.
+Read-only by construction — never writes back, never opens a network
+socket. Output is the `ExplainTrace` v1 contract
+([`docs/contracts/explain-trace.schema.json`](contracts/explain-trace.schema.json));
+free-form strings pass through the shared PII scrubber before they hit
+your terminal.
+
+```
+agent-config explain last              # Markdown trace
+agent-config explain last --json       # ExplainTrace JSON
+agent-config explain last --quiet      # no trailing tip footer
+```
+
+Sample Markdown output:
+
+```markdown
+# explain last — run PROJ-1234
+
+**Subject:** /implement-ticket · **Started:** 2026-05-19 10:14:22Z
+
+## Why this route?
+- Active rules: architecture, downstream-changes
+- Kernel rules: 9
+- Persona: senior-engineer
+
+## Why this profile / preset?
+| knob | value | source |
+|---|---|---|
+| profile.id | developer | user (.agent-settings.yml) |
+| preset.id  | balanced  | profile.developer |
+
+## Assumptions
+- [x] api-rate-limit-is-100rpm — accepted in step `refine`
+```
+
+Disable for `cost_profile: minimal` CI runs by setting `explain.enable_last: false`
+in `.agent-settings.yml`; the command then exits 0 with a one-line
+notice instead of producing a trace. Exit codes: `0` rendered or
+disabled · `1` no recent run found · `2` invocation error.
+
+---
+
 ← [Back to README](../README.md)

package/docs/decisions/ADR-001-kernel-swap-deferred.md

@@ -103,7 +103,7 @@ migrations) so the migration plan reflects the final kernel set.
 ## References
 
 - `docs/contracts/kernel-membership.md` § 4, § 5.2
-- `agents/council-sessions/20260506T044941Z-phase1-cross-check-r2.json` <!-- council-ref-allowed: ADR decision trace -->
+- `agents/runtime/council/sessions/20260506T044941Z-phase1-cross-check-r2.json` <!-- council-ref-allowed: ADR decision trace -->
 - `agents/roadmaps/road-to-kernel-and-router.md` § Decisions, § Phase 2
 - `.agent-src.uncompressed/rules/agent-authority.md` (subject)
 - `.agent-src.uncompressed/rules/autonomous-execution.md` (proposed promotion)

package/docs/decisions/ADR-002-kernel-bucket-overrides.md

@@ -6,7 +6,7 @@
   `docs/contracts/kernel-membership.md` § 5.1 (median r=0.712, per-rule cap 2.5k,
   kernel-bucket 25k).
 - **Related:** ADR-001 (kernel-swap deferred); Council R2 cross-check session
-  `agents/council-sessions/20260506T044941Z-phase1-cross-check-r2.json`. <!-- council-ref-allowed: ADR decision trace -->
+  `agents/runtime/council/sessions/20260506T044941Z-phase1-cross-check-r2.json`. <!-- council-ref-allowed: ADR decision trace -->
 
 ## Context