@event4u/agent-config 2.25.0 → 3.0.0

package/docs/decisions/ADR-014-gui-framework-choice.md

@@ -0,0 +1,136 @@
+---
+adr: 014
+status: accepted
+date: 2026-05-20
+decision: gui-framework-choice
+supersedes: —
+superseded_by: —
+phase: v2.x · unified-setup-and-settings-gui Phase 0
+type: prospective
+---
+
+# ADR-014 — GUI Framework Choice (Preact + Signals)
+
+## Status
+
+**Accepted** · 2026-05-20 · in-session council recommendation folded.
+External AI Council pass on the implementing roadmap
+(`agents/roadmaps/unified-setup-and-settings-gui.md`) did not contest
+the framework choice; it focused on data integrity (atomic writes,
+optimistic locking) which is orthogonal to the rendering layer.
+
+## Context
+
+`unified-setup-and-settings-gui.md` introduces the first browser-facing
+surface of `@event4u/agent-config` — a local UI that doubles as a
+first-run wizard and a settings editor. The package is distributed via
+`npx`, so every byte of UI ships in the npm tarball and re-downloads on
+every fresh install. The wizard has **at most 8 screens**; the settings
+editor renders **one zod-derived form tree**. There is no router-driven
+deep navigation, no SSR, no SEO surface, no offline-first concern.
+
+Picking a heavyweight framework here would inflate the tarball with no
+proportional benefit and would make hand-off audits (a maintainer
+opening `src/ui/` cold) substantially harder. The choice is locked
+**now**, in this ADR, because Phase 2 onwards depends on the form
+primitives being written against a stable rendering API.
+
+## Decision
+
+**Preact 10 + `@preact/signals` for state.** Vite as the build tool
+(already in `package.json`). No router beyond a 1 KB hash-route
+helper. Plain CSS files with design tokens, no CSS-in-JS, no UI kit.
+
+### Decision matrix
+
+| Framework | Hello-world + 5 fields + wizard (gzip) | Forms ecosystem | TS support | Mental model | Verdict |
+|---|---|---|---|---|---|
+| **Preact + signals** | **~6 KB** | Manual primitives, ergonomic | Excellent | React-compatible | **Chosen** |
+| Svelte 5 (runes) | ~10 KB | Built-in form bindings | Good | Single-file components | Rejected: compiler magic harder to audit; smaller community for form libs vs Preact |
+| lit-html / Lit | ~7 KB | None — manual | Good | Web Components, shadow DOM | Rejected: shadow DOM complicates token-driven styling and a11y |
+| Vanilla + uhtml + mfsv | ~3 KB | None — bring your own | Manual | Tagged-template HTML | Rejected: 8 screens + multi-step form is the threshold where "bring your own" costs more than the saved KB |
+| React 18 + RSC-disabled | ~45 KB | Best-in-class | Excellent | Industry default | Rejected: 7× the bundle for the same JSX surface; over-spec for an `npx`-shipped UI |
+
+### Forbidden adds
+
+- **Routers heavier than `wouter-preact` / `preact-router`** (≤ 1 KB
+  gzipped). The UI has ≤ 8 screens; a 40 KB router is over-spec.
+- **CSS frameworks** — Tailwind, MUI, Chakra, Mantine, shadcn-ui.
+  Shipping 50 KB+ of CSS into an `npx`-installed binary is poor
+  stewardship. We ship hand-written CSS using design tokens (see
+  `src/ui/tokens.css`).
+- **State libraries beyond signals** — no Redux, no Zustand, no Jotai.
+  Signals are a built-in reactive primitive; the wizard's partial
+  state lives server-side in `wizard-state.json` anyway.
+- **SSR / streaming frameworks** — Next.js, Remix, SolidStart, Astro.
+  The server is local Fastify; the UI is a static bundle mounted
+  under `/`. No SSR concern exists.
+
+### Reactive state pattern
+
+```ts
+import { signal, computed } from '@preact/signals';
+
+const settings = signal<SettingsValues | null>(null);
+const isDirty = computed(() => /* compare against load-time snapshot */ false);
+```
+
+- **`signal`** holds the editable form values; component subtrees
+  re-render only on the signals they read.
+- **`computed`** derives the dirty flag, the diff preview, and the
+  per-field error map without prop-drilling.
+- No `useState` for cross-component shared state; only for local
+  ephemera (open/closed of a single modal, focus rings).
+
+### Build target
+
+- **ES2022**, native modules, no transpilation to ES5. The UI runs
+  in the developer's browser, which is always evergreen.
+- Vite builds emit `dist/ui/assets/*.js` + `*.css`; the Fastify
+  static handler serves them under `/`.
+- Bundle budget: **≤ 35 KB gzip** total (the wizard + the settings
+  editor combined). Enforced by `tests/ui/bundle-budget.test.ts` in
+  Phase 2. Breach is a CI fail, not a warning.
+
+### Testing stack
+
+- **Vitest 2.x** (already in `package.json`) + **happy-dom** for UI
+  unit tests. No Jest. No React Testing Library (Preact has
+  `@testing-library/preact` but we keep the primitives small enough
+  that direct DOM assertions suffice).
+
+## Consequences
+
+### Positive
+
+- Tarball stays under control: the entire GUI ships in < 50 KB gzip
+  of `dist/ui/` regardless of how many screens accumulate.
+- React-shaped JSX means contributors familiar with React onboard in
+  hours, not weeks.
+- Signals eliminate the prop-drilling overhead Form state would
+  otherwise require.
+- Zero CSS-in-JS keeps Vite's output predictable and lets a maintainer
+  grep `.css` files for token usage at audit time.
+
+### Negative
+
+- Preact's smaller ecosystem means **some** React-only libraries
+  (e.g. `react-hook-form`) cannot be reused without a shim. Mitigation:
+  we hand-write form primitives anyway per the "no UI kit" rule, so
+  the gap is theoretical for this scope.
+- Contributors who only know Vue or Svelte must learn Preact's
+  JSX-flavoured API. Mitigation: documented in `docs/architecture.md`
+  alongside the existing TS-CLI onboarding notes.
+
+### Risks accepted
+
+- **No React migration path is preserved**. If a future roadmap needs
+  RSC, streaming, or React-only libraries, the UI is rewritten end-to-
+  end. Acceptable because the UI is feature-bounded (wizard + settings)
+  and any RSC-shaped future is a different product.
+
+## Cross-references
+
+- [Implementing roadmap](../../agents/roadmaps/unified-setup-and-settings-gui.md).
+- [ADR-012 — TypeScript CLI Shell](ADR-012-typescript-cli-shell.md): the host server that mounts this UI.
+- [ADR-013 — Discovery Frontmatter Contract](ADR-013-discovery-frontmatter-contract.md): the discovery manifest the GUI reads to render workspace / pack pickers in a future phase.

package/docs/decisions/ADR-rule-kernel-and-router.md

@@ -39,7 +39,7 @@ size budgets.
   tier-1 (default) · `full` = kernel + tier-1 + tier-2.
 - **Budget gates:** `task lint-rule-budget` enforces kernel ≤ 26k chars
   and per-rule ≤ 2.5k (Iron-Law overrides up to 4.0k via ADR-002).
-  Daily snapshots in `agents/.rule-budget-history.jsonl`.
+  Daily snapshots in `agents/runtime/.rule-budget-history.jsonl`.
 - **Compression discipline:** P4.3 brought the auto-bucket from
   ~75k → 59 220 chars (under the 60k target) without behaviour drift.
 
@@ -105,7 +105,7 @@ point.
 
 Kernel-bucket-check: PASS. Per-rule cap: 16 rules over 2.5k target,
 all within 4.0k Iron-Law override per ADR-002. Trend snapshot
-appended to `agents/.rule-budget-history.jsonl`.
+appended to `agents/runtime/.rule-budget-history.jsonl`.
 
 ## Consequences
 

package/docs/decisions/INDEX.md

@@ -15,6 +15,9 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-009](ADR-009-event4u-namespace.md) | Event4U Namespace And Claude Desktop Zip Bundles | accepted | 2026-05-13 | — |
 | [ADR-010](ADR-010-profile-pack-preset-boundary.md) | Profile Pack Preset Boundary | proposed | 2026-05-16 | — |
 | [ADR-011](ADR-011-domain-pack-readiness.md) | Domain Pack Readiness | accepted | 2026-05-17 | — |
+| [ADR-012](ADR-012-typescript-cli-shell.md) | Typescript Cli Shell | accepted | 2026-05-19 | — |
+| [ADR-013](ADR-013-discovery-frontmatter-contract.md) | Discovery Frontmatter Contract | accepted | 2026-05-19 | — |
+| [ADR-014](ADR-014-gui-framework-choice.md) | Gui Framework Choice | accepted | 2026-05-20 | — |
 
 ## Unnumbered (legacy)
 

package/docs/distribution/mcp-submission-checklist.md

@@ -0,0 +1,95 @@
+# MCP registry submission checklist
+
+> One-shot procedure for opening a submission PR to an external MCP
+> registry. The manifest under `dist/mcp/` is the source of truth;
+> this file is what the maintainer runs through at submission time.
+
+## Before submitting
+
+1. Confirm the npm package is published with **2FA-required** for new
+   releases. A downstream user clicking the registry link must not
+   land on a hijacked release.
+2. Re-run the builder so payloads reflect the current package:
+   ```bash
+   python3 scripts/build_discovery_manifest.py --write --strict
+   python3 scripts/build_mcp_registry_manifest.py --write --strict
+   python3 scripts/lint_mcp_registry_manifest.py
+   ```
+3. Confirm `dist/mcp/registry-manifest.json` `package.version`
+   matches the latest published npm version (or the version about to
+   be released in the same change set).
+
+## Per-registry steps
+
+### `awesome-mcp-servers`
+
+- Upstream: <https://github.com/punkpeye/awesome-mcp-servers>
+- Target file: `README.md`, section **"Server Frameworks / Agents"**.
+  *Verify the section heading before each submission — upstream
+  reorganises occasionally.*
+- Payload to paste: the row in `dist/mcp/awesome-mcp-servers.row.md`.
+  ```bash
+  cat dist/mcp/awesome-mcp-servers.row.md
+  ```
+- Open the upstream PR. Title: `Add @event4u/agent-config`.
+- After opening, update `dist/mcp/registry-manifest.json`:
+  ```jsonc
+  {
+    "id": "awesome-mcp-servers",
+    "status": "pending",     // → "listed" once merged, "rejected" if closed
+    "submitted_at": "YYYY-MM-DD",
+    "pr_url": "https://github.com/punkpeye/awesome-mcp-servers/pull/NNN",
+    "last_verified": null
+  }
+  ```
+  Then commit the manifest change as a follow-up.
+
+### `mcp-cloudflare-catalogue`
+
+- Upstream: <https://github.com/cloudflare/mcp-server-cloudflare>
+- Target file: the catalogue JSON file the repository documents
+  (verify path against the upstream README before each submission).
+- Payload to paste: the JSON object in
+  `dist/mcp/mcp-cloudflare-catalogue.json`.
+  ```bash
+  cat dist/mcp/mcp-cloudflare-catalogue.json
+  ```
+- Same lifecycle update as above once the PR is open.
+
+## After the upstream PR closes
+
+The submission PR can end in three states. Each maps to a `status`
+value in the manifest. Do **not** silently drop entries.
+
+- **merged** → `status: "listed"`, set `last_verified` to today, open
+  the live listing once and confirm the link still resolves to this
+  package. Refresh `last_verified` every release.
+- **closed without merge** → `status: "rejected"`. Leave
+  `submitted_at` and `pr_url` populated so the rejection is
+  auditable. Do **not** auto-resubmit; the next attempt is a
+  judgment call by the maintainer.
+- **listing removed later** → `status: "unlisted"`. Refresh
+  `last_verified` to the date of removal so the audit trail is
+  intact.
+
+`scripts/lint_mcp_registry_manifest.py` exits non-zero if any
+registry entry uses a value outside the four-state enum.
+
+## Submitting to a new registry
+
+The schema's `id` vocabulary is closed (`awesome-mcp-servers`,
+`mcp-cloudflare-catalogue`). Adding a third registry is a
+**schema-version bump**:
+
+1. Update `docs/contracts/mcp-registry-manifest.schema.json`:
+   add the new `id` value, bump the top-level `version` const if
+   the field shape changes.
+2. Update `scripts/build_mcp_registry_manifest.py`'s
+   `REGISTRIES_SEED` with the new entry (id, label,
+   listing_format, submission_url, rendered_payload).
+3. Add a new renderer for the rendered payload (Markdown row,
+   JSON entry, or whatever the new registry expects).
+4. Add a new payload-shape check to
+   `scripts/lint_mcp_registry_manifest.py`.
+5. Land it as its own PR so the schema change is reviewed
+   independently of the submission itself.

package/docs/distribution/topics-equivalents-decay-policy.md

@@ -0,0 +1,51 @@
+# Topics-equivalents decay policy
+
+The `equivalents:` map in [`.github/topics.yml`](../../.github/topics.yml)
+is a manually-curated paraphrase dictionary. Without a review cadence
+it rots: the README's prose evolves, the equivalents stay frozen, the
+positioning lint quietly accepts dead phrases, and a topic that *used*
+to be discoverable in the README becomes a ghost mapping.
+
+This policy locks down the review cadence so the map stays load-bearing.
+
+## Review cadence
+
+- **Every release cycle that touches the README tagline, H1, or any
+  section heading enumerated in `.github/topics.yml`** — the PR
+  author must re-run `task lint-positioning` *after* the README edit
+  and visually re-confirm that every entry under `equivalents:` still
+  matches a phrase in the current README. The lint only checks that
+  *at least one* needle hits — it cannot detect a stale entry.
+- **Six-monthly** — a dedicated `chore(visibility): refresh topics
+  equivalents` PR walks every key in `equivalents:` and either:
+  removes it (the equivalent now appears literally in the README),
+  rewrites it (the README phrase changed), or removes the parent
+  topic (no longer positioned).
+
+## Removal heuristics
+
+Drop an `equivalents:` entry when **any** of these holds:
+
+- The topic key appears verbatim (case-insensitive) in the current
+  README — the equivalents row is redundant.
+- The README phrase the equivalent was mapped to no longer exists —
+  the row is a stale alias and the lint is silently passing on a
+  ghost.
+- The topic itself is no longer in `topics:` — orphan entry.
+
+## Why not a runtime lint?
+
+The original AI-Council suggestion was to "replace the map with a
+runtime lint that warns when a tagline word appears in a topic
+equivalent but the parent README phrase has changed." That requires
+storing a hash of the matched README phrase per equivalent and
+re-validating on every lint run — extra moving parts for a low-yield
+gate. The cheaper contract is the six-monthly human review documented
+above. If the map grows past ~15 keys or rots faster than two release
+cycles, revisit and promote to a runtime check.
+
+## Tracking
+
+Maintainers log each refresh in
+[`agents/evidence/notes/visibility-sync-audit.md`](../../agents/evidence/notes/visibility-sync-audit.md)
+with a one-line entry: date, PR, keys touched.

package/docs/examples/agent-user.example.md

@@ -4,7 +4,9 @@ identity:
   name: "Mathias"
   nickname: "Matze"
 language: "de"
-role: "founder/engineer"
+role:
+  - founder
+  - engineer
 style:
   formality: "informal"
   pace: "pragmatic"

package/docs/getting-started.md

@@ -106,7 +106,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 84 rules. No configuration needed.
+This is enforced automatically by 72 rules. No configuration needed.
 
 ---
 
@@ -146,15 +146,16 @@ Your agent now understands slash commands:
 | `/quality-fix` | Run and fix all quality checks |
 | `/chat-history` | Inspect the persistent chat-history log (read-only `show`) |
 
-→ [Browse all 129 active commands](../.agent-src/commands/)
+→ [Browse all 128 active commands](../.agent-src/commands/)
 
 ---
 
-## Crash recovery — `agents/.agent-chat-history`
+## Crash recovery — `agents/runtime/.agent-chat-history`
 
 When `chat_history.enabled: true` in `.agent-settings.yml` (on by default
 for every profile), the agent keeps a JSONL log of your conversation in
-`agents/.agent-chat-history`. The file is git-ignored and rotates at the
+`agents/runtime/.agent-chat-history`. The file is git-ignored (covered
+by the `/agents/runtime/` catch-all) and rotates at the
 size configured in the profile (`128 KB` on `minimal`, `256 KB` on
 `balanced`, `512 KB` on `full`).
 
@@ -169,7 +170,7 @@ the log size, last entries, and current fingerprint. For the rare case
 where auto-adopt misfires (corrupted file, hook misconfiguration), run
 `./agent-config chat-history:adopt` as the manual recovery lever.
 
-See [`agents/contexts/chat-history-platform-hooks.md`](../agents/contexts/chat-history-platform-hooks.md)
+See [`agents/settings/contexts/chat-history-platform-hooks.md`](../agents/settings/contexts/chat-history-platform-hooks.md)
 and [`scripts/chat_history.py`](../scripts/chat_history.py) for the mechanics.
 
 ---

package/docs/guidelines/agent-infra/ask-when-uncertain-demos.md

@@ -106,7 +106,7 @@ Agent: Bevor ich die Roadmap übergebe:
 - Welcher Branch?
 - Soll ich PRs erwähnen?
 - Welches Modell für die Fortsetzung?
-- Soll ich agents/.agent-chat-history zitieren?
+- Soll ich agents/runtime/.agent-chat-history zitieren?
 
 Antworte als 1, 2, 3, 4.
 ```

package/docs/guidelines/agent-infra/roadmap-progress-mechanics.md

@@ -112,7 +112,7 @@ When the agent autonomously creates a roadmap, it owns the placement
 in the **same response**:
 
 - **Phase plan** (checkboxes, multi-turn execution) → `agents/roadmaps/<name>.md`, `status: ready` (default), regen dashboard.
-- **Decision matrix / ADR / pattern / lookup** (no `Phase N`, durable rationale) → `agents/contexts/<name>.md`.
+- **Decision matrix / ADR / pattern / lookup** (no `Phase N`, durable rationale) → `agents/settings/contexts/<name>.md`.
 - **Completed work snapshot** → `agents/roadmaps/archive/<name>.md`.
 
 A non-trackable file in `agents/roadmaps/` is a rule violation — the
@@ -146,6 +146,15 @@ dashboard, commit if commit policy allows.
 **Required:** each turn — implement step, flip `[x]`, regen, commit (if policy allows).
 A reply that lands a verified step without flipping its checkbox is a rule violation.
 
+**Deterministic flip-guard.** The autonomous loop carries a per-step
+guard at [`roadmap-process-loop § 5b`](../../.agent-src.uncompressed/contexts/execution/roadmap-process-loop.md#5b-flip-guard--deterministic):
+after the atomic flip, the loop runs
+`git diff --name-only -- agents/roadmaps/<file>.md` and halts loudly
+when the diff is empty. The `command:` triggers on
+`roadmap-progress-sync` keep the rule loaded for the entire
+`/roadmap:process-*` run; the guard is the deterministic backstop
+that catches a forgotten flip per step rather than at run end.
+
 **In-progress marker:** when a step takes more than one reply,
 mark it `[~]` the moment work starts on it and regenerate. The
 user sees one row move from `[ ]` to `[~]` to `[x]` instead of

package/docs/guidelines/agent-infra/rule-type-governance.md

@@ -48,7 +48,7 @@ The `description` field IS the trigger. It must describe **when** the rule appli
 
 Every new rule, and every edited rule whose body changes the trigger
 or the obligation, MUST classify itself against the hardening tiers
-documented in [`rule-trigger-matrix.md`](../../agents/contexts/rule-trigger-matrix.md):
+documented in [`rule-trigger-matrix.md`](../../agents/settings/contexts/rule-trigger-matrix.md):
 
 | Tier | Meaning |
 |---|---|
@@ -64,7 +64,7 @@ Classification surface: the optional `tier:` frontmatter field
 rules; bulk-retrofit of existing rules is tracked separately.
 
 Tier 3 dispositions are recorded centrally in
-[`agents/contexts/tier-3-dispositions.md`](../../agents/contexts/tier-3-dispositions.md)
+[`agents/settings/contexts/tier-3-dispositions.md`](../../agents/settings/contexts/tier-3-dispositions.md)
 with a 6-month re-audit clock. New Tier 3 rules append to that list
 on landing.
 

package/docs/guidelines/agent-infra/tool-integration.md

@@ -54,7 +54,7 @@ tool_permissions:
 New tools require:
 1. An adapter implementation in `scripts/tools/`
 2. Registration in the tool registry
-3. Documentation in `agents/docs/tools/`
+3. Documentation in `agents/reference/docs/tools/`
 
 ## Validation rules (linter)
 

package/docs/guidelines/php/api-design.md

@@ -2,7 +2,7 @@
 
 > API conventions — response format, status codes, pagination, error handling, rate limiting, route naming.
 
-**Related Skills:** `api-design`, `api-endpoint`, `api-testing`
+**Related Skills:** `api-design`, `laravel-api-endpoint`, `api-testing`
 **Related Guidelines:** [controllers.md](controllers.md), [resources.md](resources.md)
 
 ## Response Format
@@ -43,7 +43,7 @@ $projects = Project::query()
 
 ## Filtering and Sorting
 
-- Use the project's **filter pipeline** pattern (see `agents/docs/query-filter.md`).
+- Use the project's **filter pipeline** pattern (see `agents/reference/docs/query-filter.md`).
 - Filter classes are dedicated, testable units — not inline query logic.
 - Sorting via `sort` query parameter.
 

package/docs/guidelines/php/controllers.md

@@ -2,7 +2,7 @@
 
 > Project-specific controller conventions. Thin controllers, single-action pattern, OpenAPI annotations.
 
-**Related Skills:** `api-endpoint`, `laravel`, `openapi`
+**Related Skills:** `laravel-api-endpoint`, `laravel`, `openapi`
 **Related Guidelines:** [validations.md](validations.md), [resources.md](resources.md)
 
 ## Core Rules

package/docs/guidelines/php/resources.md

@@ -2,7 +2,7 @@
 
 > Project-specific API Resource conventions. Base class, versioning (v1/v2), OpenAPI schemas.
 
-**Related Skills:** `api-endpoint`, `api-design`, `openapi`
+**Related Skills:** `laravel-api-endpoint`, `api-design`, `openapi`
 **Related Guidelines:** [controllers.md](controllers.md)
 
 ## Core Rule

package/docs/guidelines/php/validations.md

@@ -2,7 +2,7 @@
 
 > Project-specific FormRequest conventions. Array syntax, route params, property mapping.
 
-**Related Skills:** `laravel-validation`, `api-endpoint`
+**Related Skills:** `laravel-validation`, `laravel-api-endpoint`
 **Related Guidelines:** [controllers.md](controllers.md)
 
 ## Core Rules

package/docs/guidelines/prompt-templates.md

@@ -153,7 +153,7 @@ This package **rejects** that whitelist. CO-STAR, RISEN, CRISPE,
 ReAct, and the image-AI templates above are first-class. The
 "5 safe" framing came from a single benchmark on a single LLM
 generation — it does not generalise. See AI Council session
-`agents/council-responses/prompt-master-mini.json` (2026-05-17) for the analysis behind this rejection. <!-- council-ref-allowed: ADR decision trace -->
+`agents/runtime/council/responses/prompt-master-mini.json` (2026-05-17) for the analysis behind this rejection. <!-- council-ref-allowed: ADR decision trace -->
 
 The right gate is request-type fit, not technique-whitelist
 membership.
@@ -163,4 +163,4 @@ membership.
 - [`prompt-optimizer`](../../.agent-src.uncompressed/skills/prompt-optimizer/SKILL.md) — engine-outbound; cites this catalogue in its Develop step
 - [`refine-prompt`](../../.agent-src.uncompressed/skills/refine-prompt/SKILL.md) — engine-inbound; uses templates in `mini` mode for stack-aware shaping
 - [`prompt-engineering-patterns`](../../.agent-src.uncompressed/skills/prompt-engineering-patterns/SKILL.md) — production-LLM prompt patterns (sibling skill, not a catalogue)
-- AI Council session: `agents/council-responses/prompt-master-mini.json` (2026-05-17) <!-- council-ref-allowed: ADR decision trace -->
+- AI Council session: `agents/runtime/council/responses/prompt-master-mini.json` (2026-05-17) <!-- council-ref-allowed: ADR decision trace -->

package/docs/hook-payload-capture.md

@@ -2,7 +2,7 @@
 
 **Purpose:** walk through the live-session payload capture for one platform
 in roughly 5 minutes, so the corresponding entry in
-[`agents/contexts/chat-history-platform-hooks.md`](../agents/contexts/chat-history-platform-hooks.md)
+[`agents/settings/contexts/chat-history-platform-hooks.md`](../agents/settings/contexts/chat-history-platform-hooks.md)
 can move from `docs-verified` to `payload-verified`.
 
 **Scope:** Cursor · Cline · Windsurf · Gemini CLI. Augment Code and Claude
@@ -158,7 +158,7 @@ then flip the `[ ] Optional upgrade — payload-verified` checkbox to
 `[x]`.
 
 Then update the matching row in
-[`agents/contexts/chat-history-platform-hooks.md`](../agents/contexts/chat-history-platform-hooks.md):
+[`agents/settings/contexts/chat-history-platform-hooks.md`](../agents/settings/contexts/chat-history-platform-hooks.md):
 the `Verification` column moves from `docs-verified` to
 `payload-verified`.
 
@@ -216,6 +216,6 @@ before paste because the redacted output goes into a tracked file
 - Capture engine: [`scripts/hooks/dispatch_hook.py`](../scripts/hooks/dispatch_hook.py) — `_maybe_capture_payload`
 - Redactor: [`scripts/redact_hook_capture.py`](../scripts/redact_hook_capture.py)
 - Per-platform install logic: [`scripts/install.py`](../scripts/install.py) — search `ensure_<platform>_bridge` / `ensure_<platform>_user_hooks`
-- Platform matrix + payload schemas: [`agents/contexts/chat-history-platform-hooks.md`](../agents/contexts/chat-history-platform-hooks.md)
+- Platform matrix + payload schemas: [`agents/settings/contexts/chat-history-platform-hooks.md`](../agents/settings/contexts/chat-history-platform-hooks.md)
 - Hook architecture: [`docs/contracts/hook-architecture-v1.md`](contracts/hook-architecture-v1.md)
 - Archived roadmap with per-phase paste sections: [`agents/roadmaps/archive/road-to-verified-chat-history-platforms.md`](../agents/roadmaps/archive/road-to-verified-chat-history-platforms.md)

package/docs/installation.md

@@ -127,6 +127,14 @@ the per-IDE index above.
 >
 > Python 3.10+ is required for bridges. If it is missing, the orchestrator
 > prints a warning and continues with the payload sync only.
+>
+> **Node.js 20.11+** is required for the `agent-config` binary itself.
+> Starting with the TypeScript CLI shell (ADR-012, road
+> `typescript-cli-and-local-gui-foundation`), the published `bin/`
+> entry is the compiled `dist/cli/agent-config.js`; `npx` resolves it
+> through the registry, so consumers do not need to install Node
+> dependencies into their own project. The package's `engines.node`
+> pin is the source of truth.
 
 | Mode | Best for | Scope |
 |---|---|---|
@@ -706,7 +714,7 @@ writes two local-only files outside the repo contract:
   `mode: cli` members. Daily UTC reset. Inspect with
   `agent-config council quota`; clear today's counter for one provider
   with `agent-config council quota --reset <provider> --confirm`.
-- `agents/council-events.log` — JSONL audit trail. One line per
+- `agents/runtime/council/events.log` — JSONL audit trail. One line per
   necessity-gate decision and per quota block. Gitignored by the
   installer (managed `.gitignore` block); never committed.
   `original_ask` is hashed `sha256[:12]` before write — the raw prompt
@@ -722,7 +730,7 @@ Per-feature environment overrides for ephemeral worktrees, CI runners,
 or sandbox testing:
 
 - `AGENT_CONFIG_NO_EVENTS_LOG=1` — disables every write to
-  `agents/council-events.log` in-process. Quota counter and council
+  `agents/runtime/council/events.log` in-process. Quota counter and council
   output stay untouched.
 - `AGENT_CONFIG_LEGACY_ANCHOR=1` — reverts project-root discovery to
   the pre-step-7 `.git`-only walk. See [Migration — Step 7 anchor
@@ -750,13 +758,13 @@ anchor** wins:
 
 1. `.git` (file or directory).
 2. `agents/` directory containing **any** of `roadmaps/`,
-   `.ai-council.yml`, or `roadmaps-progress.md` — bare `agents/`
+   `settings/.ai-council.yml`, or `roadmaps-progress.md` — bare `agents/`
    does **not** anchor (D1).
 
 If no boundary anchor exists in any ancestor, the **outermost**
 (closest-to-fs-root) `.agent-settings.yml` becomes the root. This
 preserves the layered-settings cascade — see
-[`agents/council-sessions/step-7-d3-cascade-conflict-decision.md`](../agents/council-sessions/step-7-d3-cascade-conflict-decision.md)
+[`agents/runtime/council/sessions/step-7-d3-cascade-conflict-decision.md`](../agents/runtime/council/sessions/step-7-d3-cascade-conflict-decision.md)
 for the rationale.
 
 When a single ancestor carries multiple anchors, the **diagnostic

package/docs/migrations/commands-1.15.0.md

@@ -58,7 +58,7 @@ rg -n '/(fix|optimize|feature)-[a-z-]+' \
 Common spots:
 
 - `agents/roadmaps/*.md` — roadmap steps that name commands
-- `agents/contexts/*.md` — context docs cross-linking commands
+- `agents/settings/contexts/*.md` — context docs cross-linking commands
 - Custom skills/rules under `.augment/` overrides
 - Internal team docs / runbooks / onboarding pages
 
@@ -88,12 +88,12 @@ the deprecation cycle for Phase 1 closes. Tracked in
 ## Related rule split — `chat-history` (post-1.15.0, superseded)
 
 > **Superseded · 2026-05-04** by
-> [`agents/contexts/chat-history-platform-hooks.md`](../../agents/contexts/chat-history-platform-hooks.md).
+> [`agents/settings/contexts/chat-history-platform-hooks.md`](../../agents/settings/contexts/chat-history-platform-hooks.md).
 > The three sibling rules (`chat-history-ownership`,
 > `chat-history-cadence`, `chat-history-visibility`) and the heartbeat
 > marker no longer exist. Persistence is now a pure platform-hook
 > contract — `session_start` auto-adopts foreign sessions silently;
-> the agent never reads or writes `agents/.agent-chat-history` cooperatively.
+> the agent never reads or writes `agents/runtime/.agent-chat-history` cooperatively.
 > Manual recovery lever: `./agent-config chat-history:adopt`.
 
 For historical context: the monolithic `rules/chat-history.md` was

package/docs/parity/bench-ruflo.json

@@ -5,7 +5,7 @@
   "parity_doc": "docs/parity/ruflo.md",
   "parent_bench": "docs/parity/bench.json",
   "claim_under_test": {
-    "source": "agents/audit-2026-05-14-north-star/external-findings.md § 2",
+    "source": "agents/evidence/audits/2026-05-14-north-star/external-findings.md § 2",
     "headline": "Average dollar cost per 25-prompt corpus run, separated by model tier (Haiku / Sonnet / Opus) and by token class (input / output / cache-read / cache-write).",
     "comparison_target": "ruflo cost-tracker README (claimed upstream, not yet pulled into this repo)",
     "type": "claimed_upstream_not_verified_in_repo"

package/docs/parity/ruflo.md

@@ -2,7 +2,7 @@
 
 > Per-row verdict against the eight Ruflo measurement-governance patterns
 > catalogued in
-> [`external-findings.md § 2`](../../agents/council-sessions/audit-2026-05-14-north-star/external-findings.md).
+> [`external-findings.md § 2`](../../agents/evidence/audits/2026-05-14-north-star/external-findings.md).
 > Owner roadmap: [`step-11-ruflo-parity.md`](../../agents/roadmaps/step-11-ruflo-parity.md)
 > (Phase 6 Step 1). Cross-index lives at
 > [`step-99-north-star-restructure.md`](../../agents/roadmaps/step-99-north-star-restructure.md)
@@ -10,7 +10,7 @@
 >
 > **Verdict legend:** `[x] covered by <file:line>` · `[~] superseded by <approach>` · `[!] gap`.
 > **Acceptance:** zero `[!]` rows. Closure flips the corresponding cell in the
-> [composite scorecard](../../agents/council-sessions/audit-2026-05-14-north-star/external-findings.md#5-composite-scorecard--agent-config-vs-the-field)
+> [composite scorecard](../../agents/evidence/audits/2026-05-14-north-star/external-findings.md#5-composite-scorecard--agent-config-vs-the-field)
 > `vs Ruflo` column from `–` to `=` or `+`.
 
 **Measured-vs-claimed disclaimer:** Each row cites the **mechanism** that
@@ -41,6 +41,6 @@ mechanisms remain claimed until [`bench.json`](bench.json) soak completes
 
 ## Cross-references
 
-- Composite scorecard refresh: owned by [`step-99-north-star-restructure.md`](../../agents/roadmaps/step-99-north-star-restructure.md) Phase 5 Step 4 (replaces [`external-findings.md § 5`](../../agents/council-sessions/audit-2026-05-14-north-star/external-findings.md)).
+- Composite scorecard refresh: owned by [`step-99-north-star-restructure.md`](../../agents/roadmaps/step-99-north-star-restructure.md) Phase 5 Step 4 (replaces [`external-findings.md § 5`](../../agents/evidence/audits/2026-05-14-north-star/external-findings.md)).
 - Bench-ruflo redundancy verdict: [`bench-ruflo.json`](bench-ruflo.json) (step-11 Phase 6 Step 2).
 - G5 redundancy gate cite: step-99 Acceptance Criteria row "G5 — external redundancy (Domination Mandate)".

package/docs/profiles.md

@@ -1,7 +1,7 @@
 # Six entry paths — by `profile.id`
 
 Each block below is the first-screen for one shipped profile. The
-`profile.id` written by `/onboard` selects the anchor; the block names
+`profile.id` written by `agent-config setup` selects the anchor; the block names
 the audience, the first three things the agent does for that role,
 and the exact commands and skills wired into the profile YAML at
 [`.agent-src.uncompressed/profiles/<id>.yml`](../.agent-src.uncompressed/profiles/).