@event4u/agent-config 2.26.0 → 3.1.0

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.
 
@@ -175,7 +205,7 @@ if the key file's permissions drift.
 `cost_profile` is the master switch for rule-tier loading. The kernel
 (always-loaded Iron-Law floor, ≤ 26k chars across 9 rules) ships in every
 profile. Tier-1 and tier-2 rules are gated by profile and resolved at
-session start from `router.json` (compiled by `scripts/compile_router.py`).
+session start from `dist/router.json` (compiled by `scripts/compile_router.py`).
 
 | Profile | Rule tiers loaded | Token footprint | Best for |
 |---|---|---|---|
@@ -188,7 +218,7 @@ The kernel-and-router architecture is documented in
 [`docs/contracts/rule-router.md`](contracts/rule-router.md) and
 [`docs/contracts/kernel-membership.md`](contracts/kernel-membership.md).
 Tier flags live in each rule's frontmatter (`tier: kernel | tier-1 | tier-2`);
-the router compiles them into `router.json` deterministically.
+the router compiles them into `dist/router.json` deterministically.
 
 All profiles except `custom` ship with `pipelines.skill_improvement: true`,
 so the agent captures learnings after meaningful tasks by default. Set it
@@ -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
 

package/docs/decisions/ADR-004-rule-governance-pruning.md

@@ -35,7 +35,7 @@ analytic passes ran:
 
 **5.4** AI Council R3 (claude-sonnet-4-5 + gpt-4o, 2 rounds, prompt
 mode) walked the candidate list. Council convergence and host
-verdicts are recorded in `agents/reports/auto-rules-audit.md`
+verdicts are recorded in `agents/runtime/reports/auto-rules-audit.md`
 § Phase 5.4. The dominant council insight:
 
 > *"Rarity ≠ redundancy. Low corpus hits often indicate a
@@ -192,11 +192,11 @@ documentation rewrite for marginal additional savings.
   governance pass; the stub-cost / body-cost ratio changes
   drastically.
 - Auto-rule count grows by ≥ 5 (history check via
-  `agents/.augment-budget-history.jsonl`) → repeat the audit
+  `agents/runtime/.augment-budget-history.jsonl`) → repeat the audit
   with the same three-pass methodology.
 - A retained rule (`upstream-proposal`, `slash-command-routing-policy`,
   `analysis-skill-routing`'s sibling skill) shows a 30-day window
-  with zero documented activation in `agents/council-sessions/` →
+  with zero documented activation in `agents/runtime/council/sessions/` →
   open a follow-up ADR demoting it.
 
 ## Alternatives considered
@@ -224,13 +224,13 @@ documentation rewrite for marginal additional savings.
 ## References
 
 - `agents/roadmaps/archive/road-to-augment-limit-fit.md` § Phase 5
-- `agents/reports/auto-rules-audit.md` (full audit findings,
+- `agents/runtime/reports/auto-rules-audit.md` (full audit findings,
   council walk, host verdicts)
-- `agents/reports/auto-rules-overlap.json` (Phase 5.2 data)
-- `agents/reports/auto-rules-likelihood.json` (Phase 5.3 data)
-- `agents/council-questions/augment-limit-fit-rule-governance.md` <!-- council-ref-allowed: ADR decision trace -->
+- `agents/runtime/reports/auto-rules-overlap.json` (Phase 5.2 data)
+- `agents/runtime/reports/auto-rules-likelihood.json` (Phase 5.3 data)
+- `agents/runtime/council/questions/augment-limit-fit-rule-governance.md` <!-- council-ref-allowed: ADR decision trace -->
   (Phase 5.4 prompt)
-- `agents/council-responses/augment-limit-fit-rule-governance.json` <!-- council-ref-allowed: ADR decision trace -->
+- `agents/runtime/council/responses/augment-limit-fit-rule-governance.json` <!-- council-ref-allowed: ADR decision trace -->
   (Phase 5.4 R3 raw debate)
 - `docs/decisions/ADR-rule-kernel-and-router.md` (kernel-membership
   contract — Phase 5 changes leave kernel untouched per Lever C lock)

package/docs/decisions/ADR-006-skill-tools-python-pilot.md

@@ -29,7 +29,7 @@ Python tools for skill / persona corpus maintenance:
 
 The pilot was gated by **iter-1 AI-Council verdict** (members:
 claude-sonnet-4-5 + gpt-4o · 2 rounds · 2026-05-01) <!-- council-ref-allowed: ADR decision trace -->
-([`block-d-python-tools-pilot-verdict`](../../agents/council-responses/block-d-python-tools-pilot-verdict.md)) <!-- council-ref-allowed: ADR decision trace -->
+([`block-d-python-tools-pilot-verdict`](../../agents/runtime/council/responses/block-d-python-tools-pilot-verdict.md)) <!-- council-ref-allowed: ADR decision trace -->
 under strict invariants: stdlib-only (internal package imports
 allowed), ≤ 200 LOC per tool, machine-readable output (`--json`),
 embedded `_SAMPLE`, blind-labelled eval corpora, and a kill-switch if
@@ -37,9 +37,9 @@ embedded `_SAMPLE`, blind-labelled eval corpora, and a kill-switch if
 
 ## Eval Outcome (D5)
 
-Corpora at `agents/eval-corpora/block-d/`. Runner:
+Corpora at `agents/evidence/eval-corpora/block-d/`. Runner:
 `scripts/skill_tools/run_block_d_eval.py`. Report:
-[`agents/eval-corpora/block-d/report.json`](../../agents/eval-corpora/block-d/report.json).
+[`agents/evidence/eval-corpora/block-d/report.json`](../../agents/evidence/eval-corpora/block-d/report.json).
 
 | Tool | Target | Result | Verdict |
 |---|---|---|---|
@@ -106,9 +106,9 @@ dir, and the `lint-skill-tools` task entry. Mark this ADR
 ## References
 
 - Roadmap: [`road-to-better-skills-and-profiles`](../../agents/roadmaps/archive/road-to-better-skills-and-profiles.md) Block D.
-- Council: [`block-d-python-tools-pilot-verdict`](../../agents/council-responses/block-d-python-tools-pilot-verdict.md). <!-- council-ref-allowed: ADR decision trace -->
+- Council: [`block-d-python-tools-pilot-verdict`](../../agents/runtime/council/responses/block-d-python-tools-pilot-verdict.md). <!-- council-ref-allowed: ADR decision trace -->
 
 - Tools: [`scripts/skill_tools/`](../../scripts/skill_tools/).
 - Linter: [`scripts/lint_skill_tools.py`](../../scripts/lint_skill_tools.py).
-- Corpora + report: [`agents/eval-corpora/block-d/`](../../agents/eval-corpora/block-d/).
+- Corpora + report: [`agents/evidence/eval-corpora/block-d/`](../../agents/evidence/eval-corpora/block-d/).
 - Tests: `tests/test_lint_skill_tools.py`, `tests/test_score_skill_relevance.py`, `tests/test_audit_persona_coverage.py`, `tests/test_suggest_skill_for_task.py`.

package/docs/decisions/ADR-007-agent-discovery-scopes.md

@@ -31,7 +31,7 @@ phase: post-v2.1.0 · simplicity-and-everywhere
 Originates from user ask: "Es macht keinen Sinn, das paket nicht
 global zu installieren." Validated through AI Council (2 + 1 rounds,
 2026-05-12 · members claude-sonnet-4-5 + gpt-4o). Council session:
-[`agents/council-sessions/2026-05-12-global-first-strategy/`](../../agents/council-sessions/2026-05-12-global-first-strategy/). <!-- council-ref-allowed: ADR decision trace -->
+[`agents/runtime/council/sessions/2026-05-12-global-first-strategy/`](../../agents/runtime/council/sessions/2026-05-12-global-first-strategy/). <!-- council-ref-allowed: ADR decision trace -->
 
 ## Context
 
@@ -110,8 +110,8 @@ differ.
 | 3 (targeted resolution) | same | $0.0252 | **3/4 convergence** |
 
 Full responses:
-[`responses.json`](../../agents/council-sessions/2026-05-12-global-first-strategy/responses.json), <!-- council-ref-allowed: ADR decision trace -->
-[`responses-round3.json`](../../agents/council-sessions/2026-05-12-global-first-strategy/responses-round3.json). <!-- council-ref-allowed: ADR decision trace -->
+[`responses.json`](../../agents/runtime/council/sessions/2026-05-12-global-first-strategy/responses.json), <!-- council-ref-allowed: ADR decision trace -->
+[`responses-round3.json`](../../agents/runtime/council/sessions/2026-05-12-global-first-strategy/responses-round3.json). <!-- council-ref-allowed: ADR decision trace -->
 
 ## Decision
 
@@ -262,6 +262,18 @@ maintainer manifest).
   road-to-simplicity-and-everywhere" is **never built**. Roadmap
   entry should be updated to point at `export` instead.
 
+## Amendment 2026-05-23 — Global-only consumer scope (ADR-020)
+
+[`ADR-020`](ADR-020-global-only-consumer-scope.md) finishes the job
+this ADR started: the consumer surface becomes **global-only**
+end-to-end. The project-default in this ADR is therefore historical;
+new installs land at `~/.event4u/agent-config/` only. The project
+tree retains exactly two artefacts — `agents/overrides/` and
+`agents/.event4u-bridge.yml` — both written by
+`scripts/install.py`. Maintainer-only project scope survives behind
+`AGENT_CONFIG_DEV_MODE=1` (see
+[`docs/maintainers/dev-mode.md`](../maintainers/dev-mode.md)).
+
 ## Amendment 2026-05-13 — Augment global-only
 
 **Status:** Accepted · 2026-05-13 · signed off by Matze.
@@ -350,7 +362,7 @@ Out of scope for this ADR. Sequencing target for a separate roadmap:
 ## References
 
 - Council session:
-  [`agents/council-sessions/2026-05-12-global-first-strategy/`](../../agents/council-sessions/2026-05-12-global-first-strategy/) <!-- council-ref-allowed: ADR decision trace -->
+  [`agents/runtime/council/sessions/2026-05-12-global-first-strategy/`](../../agents/runtime/council/sessions/2026-05-12-global-first-strategy/) <!-- council-ref-allowed: ADR decision trace -->
 - User-scope discovery matrix sources: agent vendor official docs
   (Claude, Cursor, Windsurf, Cline, Augment, Copilot, Gemini, Aider,
   Codex) accessed 2026-05-12.

package/docs/decisions/ADR-008-installed-tools-manifest.md

@@ -20,7 +20,7 @@ Projektebene festhalten, welche Agents wir initialisiert haben, damit
 bei jedem Sync das Verzeichnis aktualisiert werden kann?" Validated
 through AI Council Round 1 (claude-sonnet-4-5 + gpt-4o, $0.0298 actual,
 both converged on "yes, separate file"). Council session:
-[`agents/council-sessions/2026-05-12-project-settings-and-v1-v2/`](../../agents/council-sessions/2026-05-12-project-settings-and-v1-v2/). <!-- council-ref-allowed: ADR decision trace -->
+[`agents/runtime/council/sessions/2026-05-12-project-settings-and-v1-v2/`](../../agents/runtime/council/sessions/2026-05-12-project-settings-and-v1-v2/). <!-- council-ref-allowed: ADR decision trace -->
 
 ## Context
 
@@ -156,5 +156,5 @@ for this ADR.
 
 - [`ADR-007`](ADR-007-agent-discovery-scopes.md) — global-first install (this ADR depends on it).
 - [`agents/roadmaps/road-to-global-first-install.md`](../../agents/roadmaps/road-to-global-first-install.md) Phase 3.
-- [`agents/council-sessions/2026-05-12-project-settings-and-v1-v2/`](../../agents/council-sessions/2026-05-12-project-settings-and-v1-v2/) — full council transcripts. <!-- council-ref-allowed: ADR decision trace -->
+- [`agents/runtime/council/sessions/2026-05-12-project-settings-and-v1-v2/`](../../agents/runtime/council/sessions/2026-05-12-project-settings-and-v1-v2/) — full council transcripts. <!-- council-ref-allowed: ADR decision trace -->
 - [`docs/guidelines/agent-infra/layered-settings.md`](../guidelines/agent-infra/layered-settings.md) — the existing 4-layer settings precedence; this ADR adds a parallel file outside that hierarchy.

package/docs/decisions/ADR-010-profile-pack-preset-boundary.md

@@ -14,7 +14,7 @@ phase: v2.x · step-15 Phase 1 prerequisite
 
 **Proposed** · 2026-05-16 · pending Phase 1 of
 [`agents/roadmaps/step-15-product-refinement.md`](../../agents/roadmaps/step-15-product-refinement.md).
-Council v3 action #2 (`agents/council-responses/2026-05-16-step-15-product-refinement-v3.json`): <!-- council-ref-allowed: ADR decision-trace to originating council response -->
+Council v3 action #2 (`agents/runtime/council/responses/2026-05-16-step-15-product-refinement-v3.json`): <!-- council-ref-allowed: ADR decision-trace to originating council response -->
 **"Profile / Pack / Preset boundary is undefined; Phase 2 will duplicate
 Phase 1 abstractions"**. Promoted from Phase 2 to Phase 1 prerequisite —
 the profile loader (Phase 1 item 1) cannot ship without the boundary.
@@ -129,4 +129,4 @@ DUPLICATION ACROSS AXES IS A CONTRACT VIOLATION.
 
 - [`docs/contracts/cost-profile-defaults.md`](../contracts/cost-profile-defaults.md) — the existing `cost_profile` contract this ADR explicitly does **not** touch.
 - [`agents/roadmaps/step-15-product-refinement.md`](../../agents/roadmaps/step-15-product-refinement.md) — Phase 1 items 1, 4 and Phase 2 item 7.
-- [`agents/council-responses/2026-05-16-step-15-product-refinement-v3.json`](../../agents/council-responses/2026-05-16-step-15-product-refinement-v3.json) — Council v3 action #2 (origin). <!-- council-ref-allowed: ADR decision-trace to originating council response -->
+- [`agents/runtime/council/responses/2026-05-16-step-15-product-refinement-v3.json`](../../agents/runtime/council/responses/2026-05-16-step-15-product-refinement-v3.json) — Council v3 action #2 (origin). <!-- council-ref-allowed: ADR decision-trace to originating council response -->

package/docs/decisions/ADR-011-domain-pack-readiness.md

@@ -14,7 +14,7 @@ type: prospective
 ## Status
 
 **Accepted** · 2026-05-17 · one-round council pass complete
-(`agents/council-responses/adr-011-domain-pack-readiness.json/debate-round-1.json`, actual spend $0.0300). <!-- council-ref-allowed: ADR decision trace; convergence summary inline in §Council-debate-trace -->
+(`agents/runtime/council/responses/adr-011-domain-pack-readiness.json/debate-round-1.json`, actual spend $0.0300). <!-- council-ref-allowed: ADR decision trace; convergence summary inline in §Council-debate-trace -->
 Split verdict — Anthropic accepted *with* tightened trigger; OpenAI
 accepted as written. The host folded Anthropic's structural critique
 into the trigger and added the escape clause both members' reasoning
@@ -88,7 +88,7 @@ no path changes, no symlink relocation, no namespace prefix:
   recorded in `persona-governance`)
 - `.agent-src.uncompressed/commands/video/{from-script,scene,storyboard,stitch}.md`
 - `scripts/ai-video/` (the 5 adapter scripts + `lib/`)
-- `agents/policies/media/` (Phase 2 output — already structured as
+- `agents/settings/policies/media/` (Phase 2 output — already structured as
   a project-local policy directory, *not* a pack)
 
 ### (ii) The trigger that flips this decision
@@ -148,7 +148,7 @@ for ambiguity:
   `higgsfield`, `sora`) — stay in `scripts/ai-video/`.
 - The two remaining video personas — stay in `.agent-src.uncompressed/personas/`.
 - The `/video:*` command cluster — stays in `.agent-src.uncompressed/commands/video/`.
-- The `media-governance-routing` rule + `agents/policies/media/`
+- The `media-governance-routing` rule + `agents/settings/policies/media/`
   policy files — stay where Phase 2 placed them.
 - The provider-lifecycle contract + the `provider-lifecycle-discipline`
   rule — stay where Phase 3 placed them.
@@ -185,7 +185,7 @@ treats as a smell.
 ## Council-debate trace
 
 One round · 2 members · actual spend $0.0300 · raw responses at
-[`agents/council-responses/adr-011-domain-pack-readiness.json/debate-round-1.json`](../../agents/council-responses/adr-011-domain-pack-readiness.json/debate-round-1.json). <!-- council-ref-allowed: ADR decision-trace to originating council response -->
+[`agents/runtime/council/responses/adr-011-domain-pack-readiness.json/debate-round-1.json`](../../agents/runtime/council/responses/adr-011-domain-pack-readiness.json/debate-round-1.json). <!-- council-ref-allowed: ADR decision-trace to originating council response -->
 
 | Member | Pick | Core argument | Folded back? |
 |---|---|---|---|

package/docs/decisions/ADR-012-typescript-cli-shell.md

@@ -0,0 +1,162 @@
+---
+adr: 012
+status: accepted
+date: 2026-05-19
+decision: typescript-cli-shell
+supersedes: —
+superseded_by: —
+phase: v2.x · typescript-cli-and-local-gui-foundation
+type: prospective
+---
+
+# ADR-012 — TypeScript CLI Shell & Local Fastify Server
+
+## Status
+
+**Accepted** · 2026-05-19 · in-session council (8 items) +
+external `claude-sonnet-4-5` + `gpt-4o` pass (5 items, cost $0.16) on
+`agents/roadmaps/typescript-cli-and-local-gui-foundation.md`. All 13
+items folded into Phase 0–5a or carved with rationale below.
+
+## Context
+
+`@event4u/agent-config` is distributed as an npm package and consumed
+via `npx`. The current public entry point is `scripts/agent-config` —
+a 955-LOC Bash dispatcher that delegates to `scripts/_cli/cmd_*.py`.
+Two downstream roadmaps (`unified-setup-and-settings-gui`,
+`explainability-v2-explain-last`) need an embedded local HTTP server
+and a static UI bundle. Bash is the wrong substrate for that surface;
+Node is on every consumer's machine already because `npx` itself
+runs on Node.
+
+This ADR locks the dependency surface, the source layout, and the
+npm-package shape **before** any TypeScript is written. The Python
+engine, lint scripts, hooks, and `scripts/work_engine/` stay where
+they are — the TS layer is a thin distribution + UX shell that
+subprocess-invokes Python for heavy work.
+
+Related ADRs:
+
+- [ADR-007 — Agent Discovery Scopes](ADR-007-agent-discovery-scopes.md)
+- [ADR-010 — Profile/Pack/Preset Boundary](ADR-010-profile-pack-preset-boundary.md)
+- [ADR-011 — Domain-Pack Readiness](ADR-011-domain-pack-readiness.md)
+
+## Decision
+
+### Runtime dependencies (frozen)
+
+| Package | Why chosen |
+|---|---|
+| `commander@^12` | Argv parsing; small footprint, zero transitive deps. |
+| `fastify@^5` | HTTP server; fast cold start, schema-first request validation. Bumped from v4 during Phase 1 install: v4 transitive `fast-uri` carries 5 high-sev advisories that block the `npm audit --audit-level=high` security gate. |
+| `@fastify/static@^9` | Static-file plugin for the built UI bundle. v9 fixes the `@fastify/static` path-traversal + route-guard-bypass advisories present in v7/v8. |
+| `open@^10` | Cross-platform "open URL in browser"; single function, near-zero deps. |
+| `zod@^3` | Runtime schema for IPC; reused by R2 GUI for settings validation. |
+| `execa@^9` | Subprocess wrapper around Python; stream pass-through, Windows-safe escaping, predictable exit-code propagation. |
+| `js-yaml@^4` | Read `.agent-settings.yml` from TS before delegating to Python. |
+
+### Dev dependencies (frozen)
+
+`typescript@^5.5`, `tsx@^4`, `vite@^5`, `vitest@^2`, `eslint@^9`,
+`@typescript-eslint/eslint-plugin@^8`, `@typescript-eslint/parser@^8`,
+`@types/node@^20`, `@types/js-yaml@^4`. No `ts-node`, no `nodemon`,
+no `webpack`, no direct `rollup`.
+
+### Forbidden in this roadmap
+
+`inquirer`, `prompts`, `chalk`, `ora`, `boxen`, anything that emits
+colour codes outside a TTY, anything pulling > 5 transitive deps.
+Rationale: keep the binary light enough for `npx` first-run feel.
+
+### Decision matrix
+
+| Concern | Candidates | Chosen | Why rejected (others) |
+|---|---|---|---|
+| Argv parser | commander · yargs · meow · native | **commander** | yargs: 13 transitive deps; meow: ESM-only quirks; native: too verbose. |
+| HTTP server | fastify · express · koa · native | **fastify** | express: legacy middleware shape, slower cold start; koa: smaller community for plugins we need; native: schema validation would be hand-rolled. |
+| Open in browser | open · opn (deprecated) | **open** | opn unmaintained. |
+| Subprocess | execa · node:child_process | **execa** | child_process: Windows escape tax + manual stream wiring; execa cost (~70 KB) is acceptable per roadmap Open Question 3, revisit on measurement. |
+| Schema | zod · joi · ajv-direct | **zod** | joi: heavier; ajv: lower-level; zod is shared with R2 GUI. |
+| Settings parse | js-yaml · yaml | **js-yaml** | yaml: stricter spec but slower for our shape; js-yaml is the de-facto standard. |
+| UI build | vite · esbuild · rollup | **vite** | esbuild lacks HTML entry; rollup needs hand-wired HTML plugin; vite handles `index.html` + `<script type="module">` natively. |
+
+### Source layout
+
+```
+src/
+  cli/
+    agent-config.ts            # bin entry (#!/usr/bin/env node)
+    paths.ts                   # package-root walk-up, src/dist resolver
+    commands/                  # one .ts per Tier-0/1/2 subcommand
+    python/
+      runPython.ts             # execa wrapper, stdio inherit
+      resolvePython.ts         # python3 / py / python detection
+    settings/readSettings.ts   # .agent-settings.yml (read-only)
+    log/logger.ts              # leveled logger, NO chalk
+  server/
+    app.ts                     # Fastify instance + route registration
+    port.ts                    # free-port picker (41000–41999)
+    auth/token.ts              # per-process token in ~/.event4u/agent-config/
+    routes/
+      ping.ts                  # GET /api/v1/ping
+  ui/
+    index.html                 # mount point only
+    main.ts                    # bundle entry (Vite)
+dist/
+  cli/                         # tsc output of src/cli + src/server
+  ui/                          # vite build output of src/ui
+```
+
+No `src/index.ts` god-file. No `src/utils.ts`. Path aliases via
+`baseUrl: "./src"` and `paths: { "@cli/*": ["cli/*"], "@server/*": ["server/*"] }`.
+
+### npm-package shape
+
+- `"bin"` points at `dist/cli/agent-config.js` — but **only** after
+  Phase 5b ships. This ADR lands with `"bin"` still pointing at the
+  Bash file; the TS binary is shipped alongside for shadow mode.
+- `"files"` adds `dist/`; keeps `scripts/agent-config`.
+- `"engines": { "node": ">=20.11.0" }` — Node 20 LTS minimum.
+- npm scripts: `build:cli`, `build:ui`, `build`, `typecheck`,
+  `lint:ts`, `test:ts`, `prepack` (runs `build` + asserts
+  `dist/cli/agent-config.js` exists and is executable). No
+  `postinstall`.
+
+### Local server security floor
+
+Per council `security-engineer` lens, `127.0.0.1` bind is necessary
+but not sufficient. Mandated controls:
+
+1. Bind only to `127.0.0.1` — any non-loopback attempt fails contract test.
+2. Reject `Host` headers other than `127.0.0.1:<port>` or `localhost:<port>` (status `421`).
+3. `Origin` allow-list: same-origin only (`null`, `127.0.0.1:<port>`, `localhost:<port>`).
+4. Per-process token written to `~/.event4u/agent-config/local-server.token` (mode `0600`), required as `Authorization: Bearer <token>` on every `/api/*` route. `/ping` is exempt for liveness probes.
+5. `npm audit --omit=dev --audit-level=high` runs in `task lint-ts` and blocks on regressions.
+
+## Consequences
+
+**Positive**
+
+- TS entry surface gives R2 (GUI) and R4 (explain) a real substrate.
+- Python becomes optional for Tier-0 commands (`versions`, `doctor`-fast-checks). Narrows the "Python required" surface to advanced subcommands.
+- Frozen dep list resists casual scope creep.
+- Token + Origin guard means the local server is safe even on a multi-user host.
+
+**Negative**
+
+- Node 20 LTS becomes a hard requirement for the published binary (Bash shim survives one minor cycle for users on Node < 20).
+- +400 KB tarball budget (compiled JS + Vite output).
+- Shadow-mode rollout (Phase 5a → 5b) costs one release cycle of dual-shipping.
+
+**Accepted as risk**
+
+- Embedding Fastify inside the CLI binary vs. splitting to a separate `@event4u/agent-config-ui` package (external reviewer's pushback). Rationale: ADR-012 + roadmap goal lock the embedded design as infrastructure reuse for R2/R4; revisit if R2 surfaces real integration friction.
+- `execa` install weight (~70 KB) over `node:child_process`. Decide via measurement in Phase 1, not now.
+
+## Council debate trace
+
+In-session (2026-05-18): `backend-architect`, `security-engineer`,
+`frontend-engineer`, `critical-challenger` — 8 items, all folded.
+External pass: `agents/runtime/council/responses/2026-05-18T*-r1-ts-cli-foundation/`
+— 5 items, all folded. Roadmap §"Council TODOs" lists every item
+with its target phase.