@event4u/agent-config 2.26.0 → 3.1.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/frontmatter-contract.md

@@ -0,0 +1,140 @@
+---
+stability: beta
+keep-beta-until: 2026-08-19
+---
+
+# Per-artefact frontmatter contract
+
+> Companion to [`ADR-013`](../decisions/ADR-013-discovery-frontmatter-contract.md)
+> and [`discovery-manifest.schema.json`](discovery-manifest.schema.json). The
+> ADR is the decision; this file is the worked-example reference linters,
+> installer, and contributors cite at runtime.
+
+Every `.md` artefact under `.agent-src.uncompressed/` MUST declare the five
+ADR-013 discovery keys. The release-time manifest builder
+(`scripts/build_discovery_manifest.py`) derives all workspace/pack assignment
+from these alone — **no manual workspace or pack list is ever maintained**.
+
+## Required keys
+
+| Key | Type | Vocabulary | Source |
+|---|---|---|---|
+| `workspaces` | `array<string>`, ≥1 | [`config/discovery/workspaces.yml`](../../config/discovery/workspaces.yml) | role-based axis |
+| `packs` | `array<string>`, ≥1 | [`config/discovery/packs.yml`](../../config/discovery/packs.yml) | functional axis |
+| `lifecycle` | enum | `active` · `experimental` · `deprecated` · `archived` | review cycle |
+| `trust.level` | enum | `core` · `professional` · `experimental` · `advisory` · `restricted` | safety gate |
+| `trust.confidence` | enum | `high` · `medium` · `low` | curator signal |
+| `trust.human_review_required` | bool | — | reviewer routing |
+| `install.default` | bool | — | ships-by-default toggle |
+| `install.removable` | bool | — | core / removable axis |
+
+Vocabularies are **closed**. New entries require an amendment to
+[`ADR-013`](../decisions/ADR-013-discovery-frontmatter-contract.md) in the
+same PR. The linter
+([`scripts/lint_artefact_frontmatter.py`](../../scripts/lint_artefact_frontmatter.py))
+rejects free-text values.
+
+## Worked examples
+
+### Skill — `laravel/SKILL.md`
+
+```yaml
+---
+name: laravel
+description: "Writes Laravel PHP — Eloquent, Artisan, FormRequests, jobs, policies."
+source: package
+domain: engineering
+workspaces:
+  - engineering
+packs:
+  - laravel
+lifecycle: active
+trust:
+  level: professional
+  confidence: high
+  human_review_required: false
+install:
+  default: false
+  removable: true
+---
+```
+
+### Rule — `rules/commit-policy.md`
+
+```yaml
+---
+type: "always"
+tier: "safety-floor"
+description: "Commit policy — never commit unless explicitly authorized this turn."
+alwaysApply: true
+source: package
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
+---
+```
+
+### Command — `commands/cost-report.md`
+
+```yaml
+---
+name: cost-report
+tier: 2
+description: "Capture token cost from the active session and surface the 50/75/90/100% budget ladder."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
+---
+```
+
+## Quarantine
+
+Artefacts that genuinely cannot yet carry frontmatter (early scaffolds,
+generated stubs) MUST be listed in
+[`config/discovery/unassigned-artefacts.yml`](../../config/discovery/unassigned-artefacts.yml)
+with a `reason`. A quarantined entry MUST NOT also carry the five keys —
+the linter rejects that collision.
+
+## Enforcement
+
+| Surface | What runs | When |
+|---|---|---|
+| Local | `task lint-artefact-frontmatter` | manual / pre-commit |
+| Pre-commit | `pre-commit-roadmap-progress` template | when `.agent-src.uncompressed/*.md`, `config/discovery/*.yml`, or the linter itself is staged |
+| CI | `task ci` → `lint-artefact-frontmatter` | every push / PR |
+
+Install the pre-commit hook with:
+
+```bash
+./agent-config hooks:install            # combined hook (roadmap + frontmatter)
+./agent-config hooks:install --print    # dump to stdout for manual chaining
+```
+
+The hook is opt-in per concern — it short-circuits when no relevant files
+are staged.
+
+## Roundtrip invariant
+
+Frontmatter survives the `task sync` compression pipeline. Path-bearing
+keys (`load_context`) may be rewritten relative to the projected location,
+but the five Phase-1 keys above are byte-stable between
+`.agent-src.uncompressed/`, `.agent-src/`, and `.augment/`. Enforced by
+`tests/test_frontmatter_roundtrip.py`.

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/gui-wizard.md

@@ -0,0 +1,223 @@
+---
+stability: beta
+keep-beta-until: 2026-08-19
+---
+
+# GUI wizard — local browser installer
+
+> Companion to the agent-mode protocol
+> ([`installer-agent-mode.md`](installer-agent-mode.md)) and the
+> trust-and-safety layer ([`trust-and-safety.md`](trust-and-safety.md)).
+> The wizard is a thin HTTP wrapper around the same install plan, the
+> same lockfile, and the same atomic-write semantics as the CLI/TUI
+> paths. It is **optional by design** — the CLI is the canonical entry
+> point; the wizard exists for non-technical users who want a visual
+> picker.
+
+## Source of truth
+
+- Server: [`packages/core/installer/src/gui/server.ts`](../../packages/core/installer/src/gui/server.ts)
+- Handlers: [`packages/core/installer/src/gui/handlers.ts`](../../packages/core/installer/src/gui/handlers.ts)
+- Security primitives: [`packages/core/installer/src/gui/security.ts`](../../packages/core/installer/src/gui/security.ts)
+- Inlined SPA: [`packages/core/installer/src/gui/static-assets.ts`](../../packages/core/installer/src/gui/static-assets.ts)
+- Transaction log: [`packages/core/installer/src/gui/transaction-log.ts`](../../packages/core/installer/src/gui/transaction-log.ts)
+- Tests: [`packages/core/installer/tests/gui-*.test.ts`](../../packages/core/installer/tests/)
+
+## Local-only invariant
+
+The server **must** bind to `127.0.0.1` and reject any request whose
+`Host` header is not in `{ "127.0.0.1:<port>", "localhost:<port>" }`.
+`Origin` is additionally checked on every POST. No CDN, no analytics,
+no cross-origin asset, no remote endpoint — CSP
+`default-src 'self'` is set on every response.
+
+## Boot sequence
+
+```
+npx @event4u/agent-config init --gui [--gui-port=<n>] [--no-open] [--gui-idle=<s>]
+  │
+  ├─► inspect agents/runtime/gui/server.pid → abort if live
+  ├─► load dist/discovery/discovery-manifest.json (walks up from CWD)
+  ├─► generate per-server CSRF token (64-hex)
+  ├─► http.createServer + listen({ host: '127.0.0.1', port: 0 })
+  ├─► write agents/runtime/gui/server.pid (POSIX pid, single line)
+  ├─► default-spawn the OS browser opener (skipped with --no-open)
+  └─► return GuiServerHandle { url, port, csrfToken, pidFile, close }
+```
+
+Idle timeout (default 600 s, configurable via `--gui-idle`) is keyed on
+the **last HTTP request timestamp**, not on SSE event activity.
+
+## Endpoints
+
+| Method | Path             | Purpose                                              |
+|--------|------------------|------------------------------------------------------|
+| GET    | `/`              | SPA shell with CSRF token injected via `<meta>`      |
+| GET    | `/app.css`       | Static stylesheet                                    |
+| GET    | `/app.js`        | Inlined SPA logic                                    |
+| GET    | `/api/manifest`  | `{ manifest, sha256 }` — bytes-identical to disk     |
+| GET    | `/api/auto-detect` | `{ signals: { composer, package, pyproject } }`    |
+| POST   | `/api/preview`   | `{ plan, lockfileSha256 }` for current selection     |
+| POST   | `/api/apply`     | SSE: `plan-file`, `progress`, `done`, `error`        |
+| POST   | `/api/cancel`    | Flush in-flight transaction log, close SSE stream    |
+
+All POSTs require:
+
+1. `Origin` header matching `http://127.0.0.1:<port>` or
+   `http://localhost:<port>`.
+2. Body field `csrf` matching the per-server token (timing-safe
+   compare in `security.ts`).
+
+A bad CSRF returns `403` with no body. A bad Origin or Host returns
+`403` with a short plaintext reason.
+
+## Transaction log + rollback
+
+Every `POST /api/apply` writes append-only JSONL entries to
+`<projectRoot>/agents/runtime/gui/install-<ts>.log`. Shapes are
+declared in
+[`types.ts § TransactionLogEntry`](../../packages/core/installer/src/gui/types.ts):
+
+- `start` — workspaces + packs selected
+- `plan` — one entry per planned write (`path`, `pack`)
+- `commit` — `filesWritten`, `lockfileSha256`
+- `cancel` — explicit `POST /api/cancel`
+- `error` — terminating failure with `message`
+
+The next `--gui` boot inspects the most recent log and offers to roll
+back if it ended on `start`/`plan`/`error` without a matching
+`commit`/`cancel`. The CLI path consumes the same log, so a mid-install
+crash can be undone from either entry point.
+
+## SSE event framing
+
+Every `POST /api/apply` event is `data: <json>\n\n`. The terminal event
+is one of:
+
+```jsonc
+{ "type": "done", "filesWritten": 12, "lockfileSha256": "<64-hex>" }
+{ "type": "error", "message": "<reason>" }
+```
+
+The browser closes the EventSource on either; the server flushes the
+transaction log and unblocks the idle timer.
+
+## Tarball budget
+
+GUI assets under `packages/core/installer/src/gui/` (inlined HTML +
+CSS + JS in `static-assets.ts`) must stay **≤ 200 KB compiled**. The
+constraint is enforced by reviewer judgment for now; a CI check is
+tracked under the Phase 6 follow-ups.
+
+## Security failure modes covered
+
+- **Remote exploitation** — loopback bind, Host allowlist, Origin
+  allowlist, CSRF token, CSP `default-src 'self'`.
+- **DNS rebinding** — Host header check covers POSTs that omit
+  `Origin` (form posts).
+- **Zombie servers** — ephemeral port + PID file + last-request idle
+  timer. Stale PIDs (process gone) are silently overwritten on next
+  boot; live PIDs block boot with a helpful message.
+- **Mid-install crash** — transaction log + boot-time rollback prompt.
+- **Hidden state** — closing the tab triggers idle timeout; no
+  cross-tab session.
+
+## Non-goals (documented contract)
+
+- Not a hosted SaaS — no auth, no account model, no telemetry.
+- Not a settings editor — read-only on the lockfile; writes go
+  through the same install plan as the CLI.
+- Not a CI surface — every operation is reachable via `--gui-port=0
+  --no-open` is supported for headless smoke tests, but the canonical
+  CI path is the flag-driven non-interactive CLI.
+
+## Apply payload — versioning handshake (road-to-global-only-install Phase 0.4 · D12)
+
+`/api/apply` accepts a discriminated-union body keyed on
+`schema_version`. The full JSON Schema lives at
+[`schemas/wizard-apply-payload.schema.json`](../../schemas/wizard-apply-payload.schema.json).
+
+| `schema_version` | Variant | Shape |
+|---|---|---|
+| `"installer-v1"` | `InstallerPayloadV1` | `{ ai_tools[], configs{}, dry_run? }` — legacy Installer-GUI, AI tools only. |
+| `"wizard-v2"` | `WizardPayloadV2` | `{ tools[], packs[], settings{}, scope_to_project_only?, dry_run? }` — unified 9-step wizard. |
+
+**D12 (locked).** Single `/api/apply` endpoint with a `schema_version`
+discriminator — **not** two endpoints with a shared Python backend.
+Reasoning: one bind, one CSRF token, one transaction log; the
+Python `scripts/install.py` payload-router branches on
+`schema_version` before any disk write. The dual-endpoint variant was
+considered and rejected for doubling the CSRF + idle-timer surface
+with no observability gain.
+
+`schema_version` is **required**. Servers MUST reject any body that
+lacks it (HTTP 400, single-line error pointing at the schema). This
+locks the contract before Phase 1 implementation so no implicit fork
+can sneak in at Phase 1.5.
+
+## Unified 9-step flow (road-to-global-only-install § Phase 1.6)
+
+The maintainer-facing wizard at `src/server/routes/wizard.ts` switches
+between two step layouts based on the server-side `extendedSteps`
+flag (default `false` for v2.x users; flipped to `true` by the
+`agent-config setup` CLI when the npm-version kill-switch is in
+effect):
+
+| `extendedSteps` | Steps | Layout |
+|---|---|---|
+| `false` | 7 | `editor → personality → cost → roadmap-quality → memory → user-md → review` |
+| `true`  | 9 | `ai-tools → packs → editor → personality → cost → roadmap-quality → memory → user-md → review` |
+
+The step shapes themselves are declared in
+[`src/ui/wizard/steps.ts`](../../src/ui/wizard/steps.ts) — the two
+prepended lead steps (`ai-tools`, `packs`) carry no `paths` and use
+dedicated renderers in `WizardPage.tsx`. `getWizardSteps({ extended })`
+is the single resolver; the UI consumes the active list via
+`getActiveSteps()` / `activeTotalSteps()` so a server toggle takes
+effect on the next reload without a code change.
+
+### `GET /api/v1/wizard/state` payload
+
+```jsonc
+{
+  "step": 0,
+  "totalSteps": 9,
+  "partial": {},
+  "startedAt": null,
+  "extendedSteps": true
+}
+```
+
+`extendedSteps` is **advisory** — older server bundles MAY omit it,
+and the UI treats `undefined` as `false`. `totalSteps` reflects the
+flow that was active when the partial was written, which the UI uses
+for resume continuity; the active step set is otherwise derived from
+the current `extendedSteps` flag.
+
+### State persistence + recovery
+
+Per-session state is written to `<writeRoot>/state/wizard-state.json`
+(under the global config root, typically
+`~/.event4u/agent-config/state/wizard-state.json`). If the file
+becomes malformed — partial JSON write, orphaned session from a
+previous npm version, manual edit gone wrong — the recovery path is:
+
+```
+agent-config doctor --repair wizard-state
+```
+
+The repair unlinks the file (idempotent; absent files are a no-op
+success). The next `agent-config setup` boots from step 1 with a
+fresh `startedAt`. A matching `wizard-state` health check is part of
+the standard `agent-config doctor` run and surfaces malformed JSON or
+schema-shape drift before the next setup attempt.
+
+### Extended-mode endpoints
+
+`extendedSteps: true` activates two additional read-only endpoints:
+
+| Method | Path                          | Purpose |
+|--------|-------------------------------|---------|
+| GET    | `/api/v1/wizard/auto-detect`  | Project-signal evidence (composer / package / pyproject / artisan / next.config) for the `ai-tools` step. 404 when extended-mode is off. |
+| GET    | `/api/v1/wizard/manifest`     | Locked discovery-manifest (ADR-015) so the `packs` step can render supported AI IDs + every pack the manifest exposes. 404 when extended-mode is off. |
+

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/installer-agent-mode.md

@@ -0,0 +1,137 @@
+---
+stability: beta
+keep-beta-until: 2026-08-19
+---
+
+# Installer agent-mode protocol — JSON-over-stdio contract
+
+> Companion to [ADR-016](../decisions/ADR-016-installer-architecture.md)
+> § 4 and § 6. The ADR is the decision; this file is the worked-example
+> reference that agents (Claude, Cursor, GPT, …) and the installer
+> CLI share at runtime.
+
+## Source of truth
+
+The agent-mode state machine lives in
+[`packages/core/installer/src/agent-mode/machine.ts`](../../packages/core/installer/src/agent-mode/machine.ts).
+Envelope construction and `--answer` parsing live in
+[`protocol.ts`](../../packages/core/installer/src/agent-mode/protocol.ts).
+Both are unit-tested under
+[`packages/core/installer/tests/agent-mode-*.test.ts`](../../packages/core/installer/tests/).
+
+## Design constraints
+
+- **Stateless across invocations** — the installer keeps no
+  server-side session. Every turn carries the full conversation as
+  repeated `--answer key=value` flags. An agent may re-issue from
+  scratch at any time.
+- **Strict question-id sequencing** — answers must arrive in the
+  order the installer asks them (`q1.workspaces`, then `q2.packs`,
+  then optional `q3.confirm`). Out-of-order or unknown ids return
+  an `error` envelope, exit code 2.
+- **Single-line JSON per turn** — stdout emits exactly one
+  newline-terminated JSON object per invocation; stderr is reserved
+  for diagnostics and is not part of the contract.
+- **`protocol_version: 1`** — every envelope carries it; agents
+  refusing the version negotiate by aborting.
+
+## Envelope shapes
+
+### `question`
+
+The installer is waiting for the next answer.
+
+```json
+{
+  "status": "question",
+  "protocol_version": 1,
+  "id": "q1.workspaces",
+  "prompt": "Which workspaces does this project need? (multi, comma-separated)",
+  "choices": [
+    { "value": "engineering", "label": "Engineering" },
+    { "value": "product", "label": "Product" }
+  ],
+  "multi": true,
+  "next_call": "init --agent --answer q1.workspaces=<value>"
+}
+```
+
+- `id` — the canonical question identifier; the agent echoes it as
+  `--answer <id>=<value>`.
+- `multi: true` — comma-separated values allowed; `multi: false` —
+  exactly one value.
+- `next_call` — the literal command the agent should issue next,
+  with `<value>` (and prior answers) substituted in.
+
+### `done`
+
+Terminal success; no further calls needed.
+
+```json
+{
+  "status": "done",
+  "protocol_version": 1,
+  "summary": { "files_written": 83, "lockfile_sha256": "c45b3035…" }
+}
+```
+
+### `error`
+
+Terminal failure; exit code 2.
+
+```json
+{
+  "status": "error",
+  "protocol_version": 1,
+  "reason": "out_of_order",
+  "expected_question_id": "q1.workspaces",
+  "received": "q2.packs"
+}
+```
+
+Defined `reason` values: `answer_malformed`, `out_of_order`,
+`unknown_workspace`, `unknown_pack`, `aborted_by_agent`.
+
+## Turn-by-turn worked example
+
+```bash
+# Turn 1 — discover workspaces
+$ installer init --agent
+{"status":"question","id":"q1.workspaces", … "next_call":"… --answer q1.workspaces=<value>"}
+
+# Turn 2 — answer workspaces, discover packs
+$ installer init --agent --answer q1.workspaces=engineering
+{"status":"question","id":"q2.packs", … "next_call":"… --answer q1.workspaces=engineering --answer q2.packs=<value>"}
+
+# Turn 3 — answer packs, install completes
+$ installer init --agent --answer q1.workspaces=engineering --answer q2.packs=engineering-base
+{"status":"done","summary":{"files_written":83,"lockfile_sha256":"c45b3035…"}}
+```
+
+When the pack selection pulls in extras via `requires_hint`, the
+installer inserts a `q3.confirm` turn before completing:
+
+```bash
+$ installer init --agent --answer q1.workspaces=engineering --answer q2.packs=symfony
+{"status":"question","id":"q3.confirm", "prompt":"Auto-added packs: php. Continue?", "choices":[{"value":"yes","label":"yes"},{"value":"no","label":"no"}], "multi":false, … }
+```
+
+`q3.confirm=no` returns `reason: "aborted_by_agent"`.
+
+## Flags relevant to agent mode
+
+- `--manifest <path>` — override the manifest location (defaults to
+  walking up for `dist/discovery/discovery-manifest.json`).
+- `--project-root <path>` — destination project root.
+- `--dry-run` — resolve and emit the `done` envelope without
+  touching disk; used by agents that want a plan preview.
+
+## Failure modes guarded against
+
+- **Agent loops** — `protocol_version` mismatch on any side aborts
+  immediately; no implicit version negotiation.
+- **State drift between turns** — the installer never reads
+  workdir state to recover answers; every fact must be carried in
+  `--answer` flags.
+- **Silent partial install** — on any error after `q2.packs`,
+  exit code 2 with no disk writes (atomic via `StagingSession`).

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
@@ -231,7 +231,7 @@ that fires on every action decision. Swap proposal: `agent-authority`
 the 9-rule set through P2.2. Re-evaluation trigger fires at P3.2
 once the router schema and compiler ship; at that point
 `agent-authority`'s routing role becomes redundant (each kernel rule
-carries its own band as frontmatter, compiled into `router.json`),
+carries its own band as frontmatter, compiled into `dist/router.json`),
 clearing the way for the swap under a fresh ADR.
 
 ## § 6 — Abort criteria for P2.2
@@ -285,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`,