@event4u/agent-config 2.26.0 → 3.1.0

package/README.md

@@ -2,19 +2,21 @@
 
 # Agent Config — Universal AI Agent OS
 
-[![Skills](https://img.shields.io/badge/Skills-218-1f6feb?style=flat-square)](.augment/skills/) [![Rules](https://img.shields.io/badge/Rules-72-d73a49?style=flat-square)](.augment/rules/) [![Commands](https://img.shields.io/badge/Commands-129-2da44e?style=flat-square)](.augment/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-73-8957e5?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-24-bf8700?style=flat-square)](docs/personas.md) [![Advisors](https://img.shields.io/badge/Advisors-5-fb8500?style=flat-square)](docs/profiles.md) [![AI Tools](https://img.shields.io/badge/AI%20Tools-8-1abc9c?style=flat-square)](docs/architecture.md) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
+[![Smoke](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml) [![Public install smoke (3 OS × 2 Node)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml) [![npm](https://img.shields.io/npm/v/@event4u/agent-config?style=flat-square&label=npm&color=orange)](https://www.npmjs.com/package/@event4u/agent-config)
 
-> **A deterministic orchestration contract for AI agents — audited skills, governance rules, replayable state — usable by developers, founders, and creators alike.**
+[![Skills](https://img.shields.io/badge/Skills-218-orange?style=flat-square)](.agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-75-orange?style=flat-square)](.agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-129-orange?style=flat-square)](.agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-73-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-24-orange?style=flat-square)](.agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](.agent-src/personas/advisors/)
 
-Give your AI agents an audit-disciplined execution layer: multiple **skills**, **governance rules**, **commands**, and a replayable state machine that turns any host agent (Claude Code, Augment, Cursor, Copilot, Windsurf) into a reliable team member.
+> **The Universal AI Agent OS for Founders, Content Creators, Consultants, Sales, Finance, and Engineering teams. Bring your own AI provider.**
+
+Six role-shaped entry paths, one shared **skills + rules + commands** layer that turns any host agent (Claude Code, Augment, Cursor, Copilot, Windsurf) into a reliable team member — without locking you to a single model or vendor.
 
 > **Cinematic AI video** — script → character-locked image → motion+audio prompt → provider render → stitched clip, with `AIV_DRYRUN=true` as the cost-safety default. See [`/video:from-script`](.augment/commands/video/from-script.md).
 
 ### Pick your profile — six entry paths
 
-`/onboard` writes `profile.id` to `.agent-settings.yml`; each anchor
-below is the first-screen the wizard sends you to. One README, six
-entries, no role-detection guesswork.
+`agent-config setup` writes `profile.id` to `.agent-settings.yml`; each
+anchor below is the first-screen the wizard sends you to. One README,
+six entries, no role-detection guesswork.
 
 | Profile (`profile.id`) | Audience | First commands | First skills |
 |---|---|---|---|
@@ -25,13 +27,13 @@ entries, no role-detection guesswork.
 | 💼 [`finance`](docs/profiles.md#profile-finance) | CFO / fractional finance / FP&A | `/work` · `/council` · `/challenge-me` | `dcf-modeling` · `forecasting` · `scenario-modeling` · `unit-economics-modeling` · `runway-cognition` |
 | 🛡 [`ops`](docs/profiles.md#profile-ops) | RevOps, support, SRE-adjacent | `/work` · `/threat-model` · `/review-changes` · `/fix` | `incident-commander` · `dashboard-design` · `logging-monitoring` · `threat-modeling` · `launch-readiness` |
 
-**Not sure which one?** Run `npx @event4u/agent-config init` and open
-your AI agent — `/onboard` asks a single 8-option role question and
-maps to the closest profile. Source-of-truth:
-[`.agent-src.uncompressed/profiles/`](.agent-src.uncompressed/profiles/) ·
+**Not sure which one?** Run `npx @event4u/agent-config init` then
+`agent-config setup` — the browser wizard asks a single 8-option role
+question and maps to the closest profile. Source-of-truth:
+[`packages/core/.agent-src.uncompressed/profiles/`](packages/core/.agent-src.uncompressed/profiles/) ·
 schema: [`docs/contracts/profile-system.md`](docs/contracts/profile-system.md).
-Beyond software: [`user-types/`](.agent-src.uncompressed/user-types/)
-(galabau · metalworking · truck — see [Who this is for](#who-this-is-for)).
+Beyond software: [`user-types/`](packages/core/.agent-src.uncompressed/user-types/)
+(galabau · metalworking · truck — see [Beyond software](#beyond-software).
 
 <p align="center">
   <a href="CHANGELOG.md">CHANGELOG</a> ·
@@ -45,20 +47,18 @@ Beyond software: [`user-types/`](.agent-src.uncompressed/user-types/)
 
 Run from a consumer repo — bootstrap via `npx`, the agent picks up
 your stack, and you ship work end-to-end. New install? Start with the
-[Quickstart](#quickstart). Already installed? [Supported Tools](#supported-tools)
+[Quickstart](#quickstart). Already installed? [Supported tools](#supported-tools)
 shows the wired AIs; [`docs/featured-commands.md`](docs/featured-commands.md)
 lists the end-to-end workflows (`/implement-ticket`, `/work`,
-`/commit`, `/create-pr`). Deeper tour: [2-minute demo](#2-minute-demo-implement-ticket).
+`/commit`, `/create-pr`). Deeper tour: [2-minute demo](#2-minute-demo--implement-ticket).
 
 ## Prove it
 
 Audit-disciplined by construction — every memory consult, decision
-key, and hook concern lands in `agents/state/` so you can replay it.
-[Core Principles](#core-principles) names the four invariants;
-[What this package is — and what it isn't](#what-this-package-is--and-what-it-isnt)
-draws the scope boundary. Beta contracts:
-[`memory-visibility-v1`](docs/contracts/memory-visibility-v1.md) ·
-[`decision-trace-v1`](docs/contracts/decision-trace-v1.md).
+key, and hook concern lands in `agents/runtime/state/` so you can replay it.
+[Core principles](#core-principles) names the four invariants;
+[What `agent-config` is — and what it isn't](#what-agent-config-is--and-what-it-isnt)
+draws the scope boundary.
 
 ## Contribute
 
@@ -66,277 +66,68 @@ Working on the package itself? [Development](#development) covers the
 `task ci` pipeline, [Requirements](#requirements) the toolchain,
 [Maintainer telemetry](#maintainer-telemetry-opt-in-default-off) the
 opt-in measurement loop. Source-of-truth tree is
-`.agent-src.uncompressed/`; never hand-edit `.augment/` or `.agent-src/`.
+`packages/core/.agent-src.uncompressed/`; never hand-edit `.augment/` or `.agent-src/`.
+
+---
 
 ## Quickstart
 
-**Three steps. Five minutes. Decision-traced first task.**
+**Three steps. Five minutes. Browser wizard, no YAML by hand.**
 
 ```bash
-# 1. Install (writes .agent-settings.yml, .augment/, .claude/, …)
-npx @event4u/agent-config init
+# 1. Install — wizard auto-launches on first run.
+npx -y @event4u/agent-config init
 
-# 2. First-run setup (sets your name, IDE, cost profile)
-#    Open your AI agent (Claude Code, Cursor, …) and type:
-/onboard
+# 2. Pick your profile + tools in the wizard, click Finish.
+#    (Writes ~/.event4u/agent-config/, ~/.claude/, ~/.cursor/, …)
 
-# 3. First real task — agent refines, plans, logs a decision_result
+# 3. First real task — agent refines, plans, verifies.
 /work "your first real task"
 ```
 
-A `decision_result` entry lands in `agents/state/` confirming the
-work-engine phases ran end-to-end. Stack-aware skills auto-load.
-
-> Pick specific AIs, switch to global scope, deploy MCP on Cloudflare,
-> or wire optional memory — see [**Detailed installation**](#detailed-installation)
-> below. Contributors rebuilding the package — jump to
-> [**Development**](#development).
->
-> **Non-developer? No terminal?** Skip `npx` entirely — host
-> agent-config as a [Cloudflare MCP endpoint](#self-hosted-mcp-on-cloudflare--zero-local-install)
-> and connect from Claude Desktop. The [role-based getting started](docs/getting-started-by-role.md)
-> guide names the three skills each role reaches for first (Creator,
-> Founder, Consultant, GTM, Finance/Ops, Developer).
-
-### Detailed installation
-
-Two minutes from `npx` to a better-behaved agent — no install, no
-vendored package, no postinstall hook.
-
-**v2.1+ — global-first by default.** Running `init` outside a project
-defaults to a user-scope install (`~/.claude/`, `~/.cursor/`, …) and
-records itself in `~/.config/agent-config/installed.lock`. Running it
-inside a project (a `package.json` / `composer.json` / `pyproject.toml`
-manifest is present) defaults to a project-scope install. Override with
-`--scope=global` or `--scope=project`. See
-[`docs/installation.md`](docs/installation.md) for the full matrix.
-
-### For teams (recommended)
-
-Run once in the project root — `npx` resolves the runtime against the
-npm registry on every invocation, and the version pin in
-`.agent-settings.yml` keeps it reproducible:
-
-```bash
-# Bootstrap (writes .agent-settings.yml, .augment/, .claude/, …):
-npx @event4u/agent-config init
-
-# Any subsequent command:
-npx @event4u/agent-config <command>
-```
-
-The init writes:
-
-- `.agent-settings.yml` (including the `agent_config_version` pin)
-- `.vscode/settings.json`, `.augment/settings.json`
-- per-tool glue: `.claude/`, `.cursor/`, `.clinerules/`,
-  `.windsurfrules`, `GEMINI.md`, `.github/copilot-instructions.md`
-
-Want to keep the runtime global and commit only the per-project
-shell (`.agent-settings.yml`, `agents/`, `./agent-config` wrapper —
-no `.augment/` / `.claude/` / `.cursor/` in the repo)?
-
-```bash
-npm install -g @event4u/agent-config && agent-config init --minimal
-```
-
-See [`docs/installation.md § Global CLI + per-project settings`](docs/installation.md#global-cli--per-project-settings-minimal-flow)
-for the decision table and migration notes.
-
-→ Migrating from a pre-vX.0 install? See
-[`docs/migration/v1-to-v2.md`](docs/migration/v1-to-v2.md). The one-shot
-`npx @event4u/agent-config migrate` removes the legacy
-`composer.json` entry / `node_modules/@event4u/agent-config`,
-deletes the retired `~/.claude/{rules,skills}/event4u/` namespace if
-present, and writes the new `.agent-settings.yml` shape.
-
-**To run:** Node ≥ 18 and Python 3 (stdlib only — default on macOS
-12.3+ / major Linux distros). Python missing → orchestrator warns and
-continues payload-only. Task is needed only for *contributors*
-rebuilding compressed content — see [CONTRIBUTING.md](CONTRIBUTING.md).
-
-**Verify hook coverage** after installing — every supported platform
-(Augment, Claude Code, Cowork, Cursor, Cline, Windsurf, Gemini CLI,
-Copilot fallback) is wired through one universal dispatcher per
-[`hook-architecture-v1`](docs/contracts/hook-architecture-v1.md) (beta). Run
-`./agent-config hooks:status` for the matrix (`--strict` for CI,
-`--format json` for tooling). The installer also dry-fires the
-dispatcher per bridge as a post-install smoke test (skip: `--no-smoke`).
-
-### Pick specific AIs
-
-Default `init` wires every supported AI. To install just one, pass
-`--tools=<name>`:
-
-```bash
-npx @event4u/agent-config init --tools=claude-code      # Claude Code
-npx @event4u/agent-config init --tools=cursor           # Cursor
-npx @event4u/agent-config init --tools=windsurf         # Windsurf
-npx @event4u/agent-config init --tools=cline            # Cline
-npx @event4u/agent-config init --tools=gemini-cli       # Gemini CLI
-npx @event4u/agent-config init --tools=copilot          # GitHub Copilot
-npx @event4u/agent-config init --tools=augment --global # Augment Code (global-only)
-npx @event4u/agent-config init --tools=roocode          # Roo Code
-npx @event4u/agent-config init --tools=aider            # Aider
-npx @event4u/agent-config init --tools=codex            # Codex CLI
-npx @event4u/agent-config init --tools=claude-desktop   # Claude Desktop
-npx @event4u/agent-config init --tools=continue         # Continue
-```
-
-Multiple AIs in one shot: `--tools=claude-code,cursor,augment`.
-
-#### Global install (user-scope, available across projects)
-
-Add `--global` to write to the user-scope paths from
-[`ADR-007`](docs/decisions/ADR-007-agent-discovery-scopes.md) (`~/.claude/`,
-`~/.cursor/`, …) instead of the current project:
-
-```bash
-npx @event4u/agent-config init --global                       # all tools, user-scope
-npx @event4u/agent-config init --tools=claude-code --global   # → ~/.claude/
-npx @event4u/agent-config init --tools=cursor --global        # → ~/.cursor/
-```
-
-Per-AI scope support varies — Claude Desktop and Augment Code, for
-example, are global-only (Claude Desktop has no project-local
-discovery on macOS; Augment ships from a single user-scope tree
-(`~/.augment/`) — see [`ADR-007 § Amendment 2026-05-13 — global-only`](docs/decisions/ADR-007-agent-discovery-scopes.md#amendment-2026-05-13--augment-global-only)),
-while Roo Code and Continue.dev are project-local. The Supported
-Tools table below documents per-AI scope. Incompatible combinations
-(e.g. `--tools=roocode --global`, `--tools=claude-desktop` without
-`--global`, or `--tools=augment` without `--global`) are rejected
-with a directive error; `--tools=all` silently filters to the scope's
-compatible subset.
-
-### For individual use (optional)
-
-Skills-only, global across projects — installs into the agent itself,
-no per-repo `init`:
-
-```bash
-<auggie|claude|copilot> plugin install agent-config@event4u-agent-config
-```
-
-→ [All install options & project bridge setup](docs/installation.md)
-
-**Open your agent and try these 3 prompts:**
-
-1. `"Refactor this function"` → watch: agent analyzes first
-2. `"Add caching to this"` → watch: agent asks instead of guessing
-3. `"Implement this feature"` → watch: agent respects your codebase
-
-→ [Full getting started guide](docs/getting-started.md) ·
-[More examples & expected behavior](docs/showcase.md)
-
-### Self-hosted MCP on Cloudflare — zero local install
-
-Skills, commands, rules, and guidelines can be served as an MCP endpoint
-from your own Cloudflare Worker — no clone, no `task mcp:setup`, no
-Python venv on the consumer machine, just an HTTP URL any MCP client
-(Claude Desktop, Claude Code, Cursor, Zed, Continue, hosted agents)
-talks to.
-
-The Worker source lives in `workers/mcp/`; deploying it to your own
-Cloudflare account takes ~5 minutes:
-
-```bash
-task mcp:cloud:login         # one-time, opens browser
-task mcp:cloud:setup         # check → r2-create → r2-verify → whoami
-task mcp:cloud:secret-put    # opt in to bearer-auth mode (recommended for private deploys)
-# Then deploy via CI — see operator guide below.
-```
-
-The Worker ships **two MVP-1 auth modes** the operator picks at deploy
-time (per `docs/contracts/mcp-cloud-scope.md` § `Auth surface`):
+**Headless / CI:** add `--no-ui` and pass flags (`--profile=developer --tools=claude-code,cursor`); add `--dry-run` to preview writes. Reference: [`docs/wizard.md`](docs/wizard.md).
 
-- **`public`** — default. No per-request auth. Edge cache plus
-  Cloudflare account-level DDoS shielding are the ingress controls.
-  Use only for OSS, read-only deploys where the URL is shared widely.
-- **`bearer-auth`** — operator opt-in. Set the `MCP-Token` Wrangler
-  secret with `task mcp:cloud:secret-put`. Every `POST /` then
-  requires `Authorization: Bearer <MCP-Token>`. `GET /` liveness
-  stays open. Use this for private deploys.
+**Pick specific AIs:** `--tools=claude-code,cursor,augment,windsurf,cline,gemini-cli,copilot,roocode,aider,codex,claude-desktop,continue` (any subset). Visual picker: add `--gui` (loopback-bound, CSRF-gated; contract [`gui-wizard`](docs/contracts/gui-wizard.md)).
 
-HMAC and Cloudflare Access modes are declared but **deferred** in the
-contract (`hmac-deferred`, `cf-access-deferred`) — wake-up triggers
-listed there. The README intentionally names no mode the contract
-has not declared (bidirectional drift test enforces this).
+**Verify hook coverage:** `npx @event4u/agent-config hooks:status` prints the per-platform matrix (`--strict` for CI, `--format json` for tooling).
 
-After deploy your Worker lives at
-`https://agent-config-mcp.<your-account>.workers.dev` (or a custom
-domain you wire in Step 7 of the operator guide). Verify:
+> **Scope (v2.5+):** `init` writes **global** only — `~/.event4u/agent-config/`, `~/.claude/`, `~/.cursor/`, …. The project tree gets `agents/overrides/` + `agents/.event4u-bridge.yml`. `--project` is maintainer-only behind `AGENT_CONFIG_DEV_MODE=1` ([ADR-020](docs/decisions/ADR-020-global-only-consumer-scope.md), [dev-mode](docs/maintainers/dev-mode.md)).
 
-```bash
-curl https://agent-config-mcp.<your-account>.workers.dev
-# → { "ok": true, "name": "agent-config-mcp", "release_key": "v…", … }
-```
-
-Per-client setup snippets (Claude Desktop, Claude Code, Cursor, Zed,
-Continue) — [`docs/setup/mcp-client-config.md`](docs/setup/mcp-client-config.md).
-URL shapes (latest vs. pinned `/v<X.Y.Z>`) — [`docs/setup/mcp-cloud-endpoints.md`](docs/setup/mcp-cloud-endpoints.md).
-Full operator walkthrough (account, R2, GitHub secrets, deploy) —
-[`docs/setup/mcp-cloud-setup.md`](docs/setup/mcp-cloud-setup.md).
-Experimental — A0-cloud contract lives at `docs/contracts/mcp-cloud-scope.md` (internal reference only per `STABILITY.md`).
-
-#### Lock your Worker behind a Bearer token (`bearer-auth` mode)
-
-In `bearer-auth` mode the Worker requires `Authorization: Bearer
-<MCP-Token>` on every `POST /` and returns HTTP 401 + RFC 6750
-`WWW-Authenticate` on mismatch. The `GET /` liveness probe stays open
-so health checks keep working without the token. Switch modes by
-setting (or clearing) the `MCP-Token` secret:
+Migrating from a v1.x install? `npx @event4u/agent-config migrate` — full notes in [`docs/migration/v1-to-v2.md`](docs/migration/v1-to-v2.md).
 
-```bash
-task mcp:cloud:secret-put          # wraps `npx wrangler secret put MCP-Token --name agent-config-mcp`
-# wrangler prompts for the value interactively — never passed via argv.
-```
-
-Once the secret is set, every client config block needs the token in
-its headers — see [`docs/setup/mcp-client-config.md`](docs/setup/mcp-client-config.md) § Bearer auth for the
-per-client snippets (Claude Desktop, Claude Code, Cursor, Zed,
-Continue). Mode contract is normative: `docs/contracts/mcp-cloud-scope.md`
-§ `Auth surface` § `bearer-auth`.
-
-> **Scope — Lite, not Full.** The Worker serves the **MCP Lite
-> scope** (`mcp_scope: lite` per `docs/contracts/mcp-cloud-scope.md`):
-> the read-only governance surface (skills · commands · rules ·
-> guidelines · contexts) as MCP prompts and resources, plus a small
-> set of read-only tools (`memory_lookup`, `chat_history_read`,
-> `list_*`, `read_resource_body`). It does **not** execute any of the
-> ~112 Python scripts that ship with the package (linters, audits,
-> `task ci`, work-engine hooks, …) — those require the **MCP Full
-> scope** (`mcp_scope: full` — local install per [Quickstart](#quickstart)).
-> The Lite vs Full boundary is normative in
-> `docs/contracts/mcp-cloud-scope.md` (internal reference only per
-> `STABILITY.md`).
+---
 
-### Optional: persistent agent memory
+## What `agent-config` is — and what it isn't
 
-`agent-config` integrates with [`@event4u/agent-memory`](https://www.npmjs.com/package/@event4u/agent-memory)
-— an MCP-based memory backend that gives agents persistent learnings
-across sessions. It is **strictly optional**:
+A **content layer** — skills, rules, commands, guidelines, personas — distributed via npm and projected into every supported AI tool's native config format. It follows the [Agent Skills open standard](https://agentskills.io).
 
-- Not a required dependency (declared as `suggest` in Composer and as an
-  optional peer in npm). `agent-config` itself never imports it.
-- Without it, agent skills fall back to **file-based memory** under
-  `agents/memory/` and continue to work normally.
-- Recommended for teams that want learnings to survive across machines,
-  branches, and chat sessions.
+It is **not** an agent runtime. The agent loop, the LLM dispatcher, and tool orchestration stay with the host tool (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI, Copilot). Think of it as a playbook and style guide for those tools — not a replacement.
 
-Install in the same project (dev-only):
+| In scope | Out of scope |
+|---|---|
+| Skills, rules, commands, guidelines, personas | Agent loop / LLM dispatcher |
+| Multi-tool projection + compression pipeline | Execution engine inside the package |
+| Memory helpers (`memory-add`, `memory-promote`) | Cross-tool observability dashboard |
+| Linters, CI, frontmatter validation against [JSON-Schema](scripts/schemas/) ([contract](agents/reference/docs/frontmatter-contract.md)) | Runtime GUI / web dashboard |
+| Skill orchestration via citations + deterministic helpers | Opinionated skill-resolver algorithm |
 
-```bash
-npm install --save-dev @event4u/agent-memory
-```
+### What your agent is asked to do
 
-→ [Memory contract & retrieval API](docs/contracts/agent-memory-contract.md) (beta) · [Built-in MCP server](docs/mcp-server.md) (experimental — local stdio access from Claude Desktop / Cursor / Zed / Continue, install with `task mcp:setup`; promotion to beta gated on `docs/contracts/mcp-beta-criteria.md`)
+| Default behavior | With agent-config |
+|---|---|
+| Guess and edit blindly | Analyze code before changing it |
+| Drift from project conventions | Follow detected stack conventions |
+| Skip or invent tests | Write tests in the project's framework |
+| Generic commit messages | Conventional Commits with scope + ticket links |
+| Skip quality checks | Run the project's quality pipeline and fix reported errors |
+| Open PRs without context | Structured PR descriptions from Jira / Linear / GitHub |
+| Claim "done" without proof | Verify with real execution before claiming done |
 
 ---
 
-## 2-minute demo: `/implement-ticket`
+## 2-minute demo — `/implement-ticket`
 
-The flagship command. Drives a ticket end-to-end through a fixed
-linear flow — and **blocks on ambiguity instead of guessing**.
+The flagship command. Drives a ticket end-to-end through a fixed linear flow — and **blocks on ambiguity instead of guessing**.
 
 ```
 /implement-ticket PROJ-123
@@ -351,329 +142,178 @@ refine → memory → analyze → plan → implement → test → verify → rep
 - **Refines** the ticket if acceptance criteria are vague.
 - **Queries memory** for past decisions, invariants, incidents.
 - **Plans** the change; you confirm before any file is touched.
-- **Implements** under `minimal-safe-diff` + `scope-control` — no
-  drive-by edits.
-- **Runs tests** (targeted first, full suite on success).
-- **Reviews** the diff through four judges (bugs, security,
-  tests, code quality).
-- **Reports** a copyable markdown block with changes, verdicts,
-  and follow-ups — then stops. `/commit` and `/create-pr` are
-  suggestions, never run automatically.
+- **Implements** under `minimal-safe-diff` + `scope-control` — no drive-by edits.
+- **Tests** (targeted first, full suite on success).
+- **Reviews** the diff through four judges (bugs, security, tests, code quality).
+- **Reports** changes, verdicts, follow-ups — then stops. `/commit` and `/create-pr` are suggestions, never auto-run.
 
-If any step hits ambiguity, the flow halts with numbered options
-so you decide — never a silent guess. Persona comes from
-`.agent-settings.yml` (`roles.active_role`): `senior-engineer`
-(default), `qa` (widens to the full test suite), or `advisory`
-(plan-only, skips implementation).
+Any ambiguity halts the flow with numbered options — never a silent guess. Persona comes from `.agent-settings.yml` (`roles.active_role`): `senior-engineer` (default), `qa`, or `advisory` (plan-only).
 
-→ [Command reference](.agent-src/commands/implement-ticket.md) ·
-  [Flow contract](docs/contracts/implement-ticket-flow.md) (beta)
+→ [Command reference](.agent-src/commands/implement-ticket.md) · [Flow contract](docs/contracts/implement-ticket-flow.md)
 
-### Sibling entrypoint: `/work` (free-form prompt)
+### Sibling — `/work` (free-form prompt)
 
-Same engine, different envelope. Use `/work` when you have a goal
-but no ticket yet:
+Same engine, no ticket required:
 
 ```
 /work add a CSV export endpoint to the audit-log controller
 ```
 
-The first pass scores the prompt on five dimensions
-(`goal_clarity`, `scope_boundary`, `ac_evidence`, `stack_data`,
-`reversibility`) and routes on the resulting band:
+The first pass scores the prompt on five dimensions and routes on the band:
 
-| Band | Score | Engine action |
+| Band | Score | Action |
 |---|---|---|
-| **high** | `≥ 0.8` | Silent proceed — reconstructed AC + assumptions land in the delivery report |
-| **medium** | `0.5–0.79` | Halts with assumptions report; you confirm or edit before plan |
+| **high** | `≥ 0.8` | Silent proceed — AC + assumptions in the report |
+| **medium** | `0.5–0.79` | Halts with assumptions report; confirm or edit |
 | **low** | `< 0.5` | Halts with **one** clarifying question on the weakest dimension |
 
-After the band gate releases, the rest of the flow is identical
-to `/implement-ticket`. UI-shaped prompts are routed through the
-**product UI track** — see below.
+After the band gate, the flow is identical to `/implement-ticket`. Free-form goal → `/work`; ticket payload → `/implement-ticket`.
 
-→ [Command reference](.agent-src/commands/work.md) ·
-  [`refine-prompt` skill](.agent-src/skills/refine-prompt/SKILL.md) ·
-  [ADR](docs/contracts/adr-prompt-driven-execution.md)
+→ [Command reference](.agent-src/commands/work.md) · [`refine-prompt` skill](.agent-src/skills/refine-prompt/SKILL.md)
 
-**Pick which one:** ticket id or pasted ticket payload → `/implement-ticket`.
-Free-form goal, no ticket → `/work`. The two share `.work-state.json`
-and refuse to switch envelopes mid-flight.
+**After the run:** `agent-config explain last` reconstructs the trace (route · memory · council · halts · provider) — read-only, PII-scrubbed, offline. [Docs](docs/customization.md#explainability--explain-last)
 
 ### Product UI track
 
-UI-shaped work (build a screen, improve a component, fix microcopy)
-switches the engine to one of three directive sets:
+UI-shaped work routes to one of three directive sets — `ui` (full audit→design→apply→review→polish→report), `ui-trivial` (≤ 1 file, ≤ 5 lines: apply→test→report), `mixed` (backend + UI: contract→ui→stitch). Existing-UI audit is a **hard gate** ([`ui-audit-gate`](.agent-src/rules/ui-audit-gate.md)); polish has a 2-round ceiling with a11y precedence. Stack detection → `blade-livewire-flux` / `react-shadcn` / `vue` / `plain`.
 
-| `directive_set` | When | Flow |
-|---|---|---|
-| `ui` | Non-trivial UI surface | `audit → design → apply → review → polish → report` |
-| `ui-trivial` | Bounded edit (≤ 1 file, ≤ 5 changed lines) | `apply → test → report` |
-| `mixed` | Backend + UI | `contract → ui → stitch` |
-
-Four load-bearing properties: (1) **existing-UI audit is a hard gate** —
-no `apply` without audit, enforced at dispatcher AND
-[`ui-audit-gate`](.agent-src/rules/ui-audit-gate.md) rule;
-(2) **design brief is locked microcopy** — placeholders (`<placeholder>`,
-`Lorem`, `TODO:`) rejected at both ends; (3) **polish has a 2-round
-ceiling**, then halts ship-as-is / abort / hand-off; (4) **a11y precedence**
-— unresolved axe-core / pa11y violations must be fixed or explicitly
-accepted before ship, regardless of round counter (one-shot extension
-allowed). The engine never renders UI itself: rendering happens
-out-of-process, the engine consumes a `preview_envelope` (status /
-screenshots / findings) via a defined contract. Stack detection routes
-(`composer.json` + `package.json`) to `blade-livewire-flux` /
-`react-shadcn` / `vue` / `plain`; trivial path reclassifies loudly when
-preconditions fail. Halt budget on the happy path is 2.
-
-→ [Mental model](docs/ui-track-mental-model.md) (1 page — when each set, where it stops, what the agent must never do) ·
-  [Flow contract](docs/contracts/ui-track-flow.md) (beta) ·
-  [ADR](docs/contracts/adr-product-ui-track.md) ·
-  [Stack-extension recipe](docs/contracts/ui-stack-extension.md) (beta)
+→ [Mental model](docs/ui-track-mental-model.md) (1 page) · [Flow contract](docs/contracts/ui-track-flow.md)
 
 ---
 
-## What your agent is asked to do
+## Customize
 
-The package ships rules and skills that guide the agent toward these
-behaviors. The agent still decides in the moment, so the table is a
-description of intent — not a guarantee of output.
+### Profiles — how much governance gets loaded
 
-| Default behavior | With agent-config (the agent is instructed to) |
-|---|---|
-| Guess and edit blindly | Analyze code before changing it — no blind edits |
-| Drift from project conventions | Follow the project's coding standards (detected from the stack) |
-| Skip or invent tests | Write tests in the project's framework (Pest, PHPUnit, Vitest, Jest, …) |
-| Write generic commit messages | Use Conventional Commits with scope and ticket links |
-| Skip quality checks | Run the project's quality pipeline (PHPStan/Rector/ECS, ESLint/Prettier/tsc, …) and fix reported errors |
-| Open PRs without context | Produce structured PR descriptions from Jira / Linear / GitHub tickets |
-| Claim "done" without proof | Verify with real execution before claiming "done" |
+Safety floor (non-destructive defaults · ask-before-guessing · mirror-the-user's-language) ships in **every** profile. What changes is how much extra coaching gets pulled in.
 
----
+| Profile | What you get | When to pick it |
+|---|---|---|
+| **`minimal`** | Non-negotiable safety floor only. Cheapest, fastest. | Quick questions · throw-away scripts · CI · tight token budgets |
+| **`balanced`** (default) | Safety floor + everyday coaching (sensible defaults, review nudges, common pitfalls). | Day-to-day work |
+| **`full`** | Everything, including long-tail rules normally only maintainers need. | Working on `agent-config` itself · audits · max-fidelity demos |
 
-## What this package is — and what it isn't
+Under the hood: kernel-only · kernel + tier-1 · kernel + tier-1 + tier-2. Details: [`rule-router`](docs/contracts/rule-router.md) · [`kernel-membership`](docs/contracts/kernel-membership.md) · [Configure →](docs/customization.md).
 
-`agent-config` is a **content layer** — skills, rules, commands, and
-guidelines — distributed via Composer and npm and projected into every
-supported AI tool's native config format. It follows the
-[Agent Skills open standard](https://agentskills.io).
+> **Stability:** [`STABILITY.md`](docs/contracts/STABILITY.md) for the full matrix. Work Engine (`/work` + `/implement-ticket`): **beta**. Runtime Dispatcher: **stable**. Tool Adapters: **experimental** (`full` profile only).
 
-It is **not** an agent runtime. The agent loop, the LLM dispatcher, and
-tool orchestration stay with the host tool (Claude Code, Augment Code,
-Cursor, Cline, Windsurf, Gemini CLI, GitHub Copilot). Think of this
-package as a playbook and style guide for those tools — not a
-replacement for them.
+### `.agent-user.md` and Ghostwriter — voice primitives
 
-| In scope | Out of scope |
-|---|---|
-| Skills, rules, commands, guidelines | Agent loop / LLM dispatcher |
-| Multi-tool projection + compression pipeline | Execution engine inside the package |
-| Memory helpers (`memory-add`, `memory-promote`, query scripts) | Cross-tool observability dashboard |
-| Linters, CI, frontmatter validation | Runtime GUI / web dashboard |
-| Skill orchestration via markdown citations + deterministic helpers | Opinionated skill-resolver algorithm |
+| Primitive | Voice | Disclosure |
+|---|---|---|
+| [`personas/*.md`](.agent-src/personas/) | Review-lens (internal critique) | n/a |
+| `.agent-user.md` (project root, gitignored) | The maintainer's own voice — `/post-as:me` | None (you are the author) |
+| [`agents/reference/ghostwriter/<slug>.md`](docs/contracts/ghostwriter-schema.md) (gitignored) | Documented public figure — `/post-as:ghostwriter` | **Mandatory, non-removable** footer |
+
+Create the user file interactively: `/agents user init` ([schema](docs/contracts/agent-user-schema.md)). Ghostwriter cluster: `/ghostwriter:fetch <url-or-name>` runs an attestation gate; private individuals rejected; paywalled / leaked / DM content banned at the schema level.
 
-Frameworks like LangChain or CrewAI are **runtimes**; this package
-sits one layer above them — it tells whichever agent you already use
-how to behave, not how to execute.
+### Self-hosted MCP on Cloudflare — zero local install
 
-Example of what *is* in scope: every artefact's frontmatter validates
-against a JSON-Schema under [`scripts/schemas/`](scripts/schemas/)
-([contract](agents/docs/frontmatter-contract.md)), enforced by
-`task validate-schema` in CI. Runtime validation inside a live agent
-session is explicitly not.
+Skills, commands, rules, and guidelines can be served as an MCP endpoint from your own Cloudflare Worker — any MCP client (Claude Desktop, Claude Code, Cursor, Zed, Continue, hosted agents) talks to it over HTTP. Two auth modes: `public` (default, OSS read-only deploys) and `bearer-auth` (operator opt-in, `MCP-Token` Wrangler secret).
 
----
+```bash
+task mcp:cloud:login         # one-time, opens browser
+task mcp:cloud:setup         # check → r2-create → r2-verify → whoami
+task mcp:cloud:secret-put    # opt in to bearer-auth (recommended for private deploys)
+```
 
-## You don't need everything
+→ Operator walkthrough: [`mcp-cloud-setup`](docs/setup/mcp-cloud-setup.md) · Per-client config: [`mcp-client-config`](docs/setup/mcp-client-config.md) · Endpoints: [`mcp-cloud-endpoints`](docs/setup/mcp-cloud-endpoints.md).
 
-Pick how much governance your agent loads up front. The safety floor
-(non-destructive defaults, ask-before-guessing, mirror-the-user's-language)
-ships in **every** profile — what changes is how much extra coaching gets
-pulled in alongside it.
+> **Scope — Lite, not Full.** The Worker serves read-only governance (skills · commands · rules · guidelines · contexts) as MCP prompts and resources, plus small read-only tools (`memory_lookup`, `chat_history_read`, `list_*`). It does **not** execute the ~112 Python scripts (linters, audits, `task ci`, work-engine hooks) — those require local install per [Quickstart](#quickstart).
 
-| Profile | What you get | When to pick it |
-|---|---|---|
-| **`minimal`** | The non-negotiable safety floor and nothing else. Cheapest, fastest. | Quick questions · throw-away scripts · running in CI · tight token budgets |
-| **`balanced`** (default) | Safety floor plus the everyday coaching most teams want — sensible defaults, code-review nudges, common pitfalls flagged. | Day-to-day work · the right answer if you're not sure |
-| **`full`** | Everything, including the long-tail rules normally only the package maintainers need. | Working on `agent-config` itself · audits · maximum fidelity demos |
-
-Under the hood, this is the rule-tier switch: kernel-only · kernel + tier-1
-auto-rules · kernel + tier-1 + tier-2. Architecture details:
-[`docs/contracts/rule-router.md`](docs/contracts/rule-router.md) (beta) ·
-kernel set: [`docs/contracts/kernel-membership.md`](docs/contracts/kernel-membership.md) (beta) ·
-[Configure profiles →](docs/customization.md)
-
-> **Stability tiers** — [`STABILITY.md`](docs/contracts/STABILITY.md) for
-> the full matrix. Runtime Dispatcher: **stable** (`php` / `node` handlers
-> scaffold). Work Engine: **beta (beta)** — orchestrator behind `/work`
-> + `/implement-ticket`. Tool Adapters: **experimental**, read-only,
-> behind `full`. `minimal` profile unaffected.
+### Optional: persistent agent memory
+
+[`@event4u/agent-memory`](https://www.npmjs.com/package/@event4u/agent-memory) — MCP-based backend for cross-session learnings. **Strictly optional**; without it, skills fall back to file-based memory under `agents/memory/`.
+
+```bash
+npm install --save-dev @event4u/agent-memory
+```
+
+→ [Memory contract](docs/contracts/agent-memory-contract.md) · [Built-in MCP server](docs/mcp-server.md) (experimental)
 
 ---
 
-## Who this is for
+## Supported tools
 
-`agent-config` ships a **stack-agnostic governance core** (orchestration contract, role modes, command clusters, quality gates, audit-discipline) plus **parallel stack-specific skill sets** at varying depth:
+### Project-installed (`npx`)
 
-| Stack | Coverage |
-|---|---|
-| Laravel · modern PHP | Skills, rules, project-analysis, quality-tool wiring (Pest · PHPStan · Rector · ECS) |
-| Symfony | Workflow skill (`symfony-workflow`) + project-analysis + shared PHP coder/quality skills |
-| Zend / Laminas | Project-analysis skills + shared PHP coder/quality skills |
-| Next.js · App Router | Workflow skill (`nextjs-patterns`) + project-analysis + UI directive set (`react-shadcn`) |
-| React · Node / Express | Project-analysis skills + UI directive set (`react-shadcn`) |
-| Vue · plain HTML | UI directive set (`vue` / `plain`) — analysis skills as they ship |
-| Cross-stack | API design · testing · security · database · Docker · Git · CI · review · threat modeling · observability |
+| Tool | Rules | Skills | Commands | How it works |
+|---|---|---|---|---|
+| **Claude Code** | ✅ | ✅ | ✅ | Reads `.claude/` |
+| **Cursor** | ✅ | — | ☑️ | Reads `.cursor/rules/` + commands via AGENTS.md |
+| **Cline** | ✅ | — | ☑️ | Reads `.clinerules/` + commands via AGENTS.md |
+| **Windsurf** | ✅ | — | ☑️ | Reads `.windsurfrules` + commands via AGENTS.md |
+| **Gemini CLI** | ✅ | — | ☑️ | Reads `GEMINI.md` |
+| **GitHub Copilot** | ✅ | — | ☑️ | Reads `.github/copilot-instructions.md` |
+| **Roo Code** | ✅ | — | ☑️ | Auto-discovers `.roo/rules/*.md` + AGENTS.md |
+| **Codex CLI** | ✅ | — | ☑️ | Auto-discovers `AGENTS.md` |
+| **Continue.dev** | ✅ | — | ☑️ | Auto-discovers `.continue/rules/*.md` + AGENTS.md |
+| **Aider** | 📌 | — | — | Manual `read:` in `.aider.conf.yml` |
+| **Augment** (VSCode/IntelliJ) | 📌 | — | — | Global-only; project writes marker |
+| **Claude Desktop** | 📌 | — | — | Global-only |
 
-**Deepest reference stack today: Laravel** — Pest, PHPStan, Rector, Eloquent, Livewire/Flux, Horizon, Pulse, Reverb, Pennant. **Workflow-grade second tier: Symfony** (`symfony-workflow` — DI, Doctrine, Messenger, voters, Twig) and **Next.js App Router** (`nextjs-patterns` — RSC boundaries, Server Actions, caching, route handlers). Other stacks ship in the order they are battle-tested, not second-class. Adopting on a thin stack? Open an issue so we can prioritize the right skills for extraction.
+✅ native &nbsp; ☑️ text reference (in AGENTS.md, not invokable as native slash-command) &nbsp; 📌 marker only &nbsp; — not available
 
-### …and beyond software (`user-types/`)
+> **Team reproducibility:** every tool you `init` is recorded in `agents/installed-tools.lock` (committed, machine-managed). New team members run `npx @event4u/agent-config sync` after cloning; CI gates drift with `agent-config validate`. Schema: [`installed-tools-manifest`](docs/guidelines/agent-infra/installed-tools-manifest.md).
 
-The same orchestration core drives non-software trades. Worked-example user types ship as the actual prompt-pack the agent loads: [`galabau-field-crew`](.agent-src.uncompressed/user-types/galabau-field-crew.md) (landscaping) · [`metalworking-shop`](.agent-src.uncompressed/user-types/metalworking-shop.md) · [`truck-driver`](.agent-src.uncompressed/user-types/truck-driver.md). Contributing your own? [5-minute scaffold](.agent-src.uncompressed/user-types/_template/) + [conventions](.agent-src.uncompressed/user-types/README.md). Same governance, command suite, and safety rules apply.
+### Plugin-installed (optional, global)
 
----
+| Tool | Install |
+|---|---|
+| **Augment CLI** · **Claude Code** · **Copilot CLI** | [Install →](docs/installation.md) — rules + skills + commands, marketplace-updated |
 
-## Data governance & domain safety
+### Cloud / Hosted-agent surfaces
+
+For platforms where the package's scripts cannot run, artefacts are built for paste-in or upload:
 
-12 domain-safety rules (`.agent-src.uncompressed/rules/domain-safety-*.md`) act as a per-domain output floor — PII redaction for support / finance / recruiting / marketing, advice disclaimers for legal / financial / medical / consulting drafts, retention guidance for finance / support, and ops floors for logging / export. Full surface → rule(s) → floor matrix: [`docs/safety.md`](docs/safety.md).
+- **Linear AI** (Codegen, Charlie, …) — `dist/linear/{workspace,team,personal}.md`
+- **Claude.ai Web Skills** — `dist/cloud/<skill>.zip`
+
+→ [Install →](docs/installation.md#linear-ai-codegen-charlie-)
 
 ---
 
-## Profile entry paths & featured commands
+## Who this is for
 
-Deep version of the profile table above (audience · first commands ·
-first skills · preset default per profile):
-[`docs/profiles.md`](docs/profiles.md). Curated featured-commands
-subset: [`docs/featured-commands.md`](docs/featured-commands.md).
-[Browse all 129 active commands](.agent-src/commands/) · full catalog:
-[`docs/catalog.md`](docs/catalog.md) ·
-[skills only](docs/skills-catalog.md) · [`llms.txt`](llms.txt).
+Stack-agnostic governance core (orchestration · role modes · command clusters · quality gates · audit-discipline) plus parallel stack-specific skill sets:
 
----
+| Stack | Coverage |
+|---|---|
+| **Laravel · modern PHP** (deepest) | Pest · PHPStan · Rector · ECS · Eloquent · Livewire/Flux · Horizon · Pulse · Reverb · Pennant |
+| **Symfony** | `symfony-workflow` (DI · Doctrine · Messenger · voters · Twig) + project-analysis |
+| **Next.js App Router** | `nextjs-patterns` (RSC · Server Actions · caching · route handlers) + UI `react-shadcn` |
+| **Zend / Laminas** | project-analysis + shared PHP coder/quality skills |
+| **React · Node / Express** | project-analysis + UI `react-shadcn` |
+| **Vue · plain HTML** | UI directive set (`vue` / `plain`) |
+| **Cross-stack** | API design · testing · security · database · Docker · Git · CI · review · threat modeling · observability |
 
-## Supported Tools
+### Beyond software
 
-### Project-installed (`npx`)
+The same orchestration core drives non-software trades via [`user-types/`](packages/core/.agent-src.uncompressed/user-types/): [`galabau-field-crew`](packages/core/.agent-src.uncompressed/user-types/galabau-field-crew.md) · [`metalworking-shop`](packages/core/.agent-src.uncompressed/user-types/metalworking-shop.md) · [`truck-driver`](packages/core/.agent-src.uncompressed/user-types/truck-driver.md). Contribute your own — [5-minute scaffold](packages/core/.agent-src.uncompressed/user-types/_template/).
 
-Every developer gets the same behavior. No per-user setup needed —
-`npx @event4u/agent-config init` writes the per-tool glue listed below.
+---
 
-| Tool | Rules | Skills | Commands | How it works |
-|---|---|---|---|---|
-| **Claude Code** | ✅ | ✅ | ✅ | Reads `.claude/` (skills + commands as skills) |
-| **Cursor** | ✅ | — | ☑️ | Reads `.cursor/rules/` + commands via AGENTS.md |
-| **Cline** | ✅ | — | ☑️ | Reads `.clinerules/` + commands via AGENTS.md |
-| **Windsurf** | ✅ | — | ☑️ | Reads `.windsurfrules` + commands via AGENTS.md |
-| **Gemini CLI** | ✅ | — | ☑️ | Reads `GEMINI.md` (includes commands reference) |
-| **GitHub Copilot** | ✅ | — | ☑️ | Reads `.github/copilot-instructions.md` (includes commands) |
-| **Roo Code** | ✅ | — | ☑️ | Auto-discovers `.roo/rules/*.md` + AGENTS.md |
-| **Codex CLI** | ✅ | — | ☑️ | Auto-discovers `AGENTS.md` at project root |
-| **Continue.dev** | ✅ | — | ☑️ | Auto-discovers `.continue/rules/*.md` + AGENTS.md |
-| **Aider** | 📌 | — | — | Marker + manual `read:` in `.aider.conf.yml` |
-| **Augment VSCode/IntelliJ** | 📌 | — | — | Global-only — install with `--global` (see [ADR-007 Amendment 2026-05-13](docs/decisions/ADR-007-agent-discovery-scopes.md#amendment-2026-05-13--augment-global-only)); project writes `.augment/settings.json` marker only |
-| **Claude Desktop** | 📌 | — | — | Global-only — install with `--global` (see ADR-007) |
-
-✅ = native support &nbsp; — = not available &nbsp; ☑️ = text reference only
-(commands listed in `AGENTS.md`, tool cannot invoke them as native
-slash-commands) &nbsp; 📌 = informational marker only (no auto-discovery
-or manual wiring required)
-
-> **What this means in practice:** Claude Code gets the full project-scoped
-> package (rules + 218 skills + 129 native commands); Augment Code gets the
-> same content but only from a single global install at `~/.augment/`.
-> Cursor, Cline, Windsurf, Gemini CLI, GitHub Copilot, Roo Code, Codex CLI,
-> and Continue.dev only get the **rules** natively; skills and commands are
-> available as documentation the agent can read, not as first-class features.
-> Aider, Augment, and Claude Desktop ship marker-only bridges in projects —
-> Aider needs a one-line `read:` entry in `.aider.conf.yml`; Augment and
-> Claude Desktop are global-scope and pair with `--global`.
-
-> **Team reproducibility (ADR-008):** every tool you `init` is also recorded in
-> `agents/installed-tools.lock` — committed, machine-managed. New team members
-> run `npx @event4u/agent-config sync` after cloning and every bridge in the
-> table above is replayed locally. CI can gate drift with `agent-config validate`.
-> Schema, workflow, and drift catalog:
-> [`docs/guidelines/agent-infra/installed-tools-manifest.md`](docs/guidelines/agent-infra/installed-tools-manifest.md).
-
-### Plugin-installed (optional, for global use)
-
-Works across all your projects. Auto-updates via marketplace.
-
-| Tool | Rules | Skills | Commands | Install |
-|---|---|---|---|---|
-| **Augment CLI** | ✅ | ✅ | ✅ | [Install →](docs/installation.md#augment-cli) |
-| **Claude Code** | ✅ | ✅ | ✅ | [Install →](docs/installation.md#claude-code) |
-| **Copilot CLI** | ✅ | ✅ | ✅ | [Install →](docs/installation.md#copilot-cli) |
+## Data governance & domain safety
 
-Skills use a `SKILL.md` format with YAML frontmatter that is compatible with
-the [Agent Skills](https://agentskills.io) community spec and with Claude
-Code's Agent Skills specification.
+Three domain-safety rules ([`domain-safety-pii`](packages/core/.agent-src.uncompressed/rules/domain-safety-pii.md), [`domain-safety-disclaimer`](packages/core/.agent-src.uncompressed/rules/domain-safety-disclaimer.md), [`domain-safety-retention`](packages/core/.agent-src.uncompressed/rules/domain-safety-retention.md)) act as per-domain output floors across ~12 areas — PII redaction (support / finance / recruiting / marketing), advice disclaimers (legal / financial / medical / consulting), retention guidance (finance / support), ops floors (logging / export). Full surface → rule → floor matrix: [`docs/safety.md`](docs/safety.md). Beta contracts: [`memory-visibility-v1`](docs/contracts/memory-visibility-v1.md) · [`decision-trace-v1`](docs/contracts/decision-trace-v1.md).
 
-### Cloud / Hosted-agent surfaces (paste-in or upload)
+### Maintainer telemetry (opt-in, default-off)
 
-For platforms where the package's scripts cannot run, the package
-builds artefacts you upload or paste into the platform's own surface.
+Local-only artefact-engagement log. Set `telemetry.artifact_engagement.enabled: true` in `.agent-settings.yml`. Records which skills / rules / commands / guidelines the agent consults during `/implement-ticket` / `/work`. JSONL under the project root, nothing uploaded. Reports: `npx @event4u/agent-config telemetry:report`.
 
-| Surface | Output | How to install |
-|---|---|---|
-| **Linear AI** (Codegen, Charlie, …) | `dist/linear/{workspace,team,personal}.md` | [Install →](docs/installation.md#linear-ai-codegen-charlie-) |
-| **Claude.ai Web Skills** | `dist/cloud/<skill>.zip` | [Install →](docs/installation.md#claudeai-web-skills-ui) |
+### Context-aware command suggestion
 
-The Linear digest is split into three layers — workspace (universal
-coding posture), team (framework-specific), personal (empty stub). See
-[`docs/contracts/linear-ai-three-layers.md`](docs/contracts/linear-ai-three-layers.md) (beta)
-for the rationale and
-[`docs/contracts/linear-ai-rules-inclusion.md`](docs/contracts/linear-ai-rules-inclusion.md) (beta)
-for the per-rule routing.
+When a prompt matches a command's purpose ("setze ticket ABC-123 um" → `/implement-ticket`), the agent surfaces matches as numbered options — **nothing auto-executes**. Per-conversation off: `/command-suggestion-off`. Settings: `commands.suggestion.{enabled,blocklist,confidence_floor}` in `.agent-settings.yml`.
 
 ---
 
-## User persona (`.agent-user.md`)
-
-A project-root `.agent-user.md` file captures who the user is — name,
-primary language, role, work style, and a single voice sample — so the
-agent can address them correctly from the first turn. The file is
-gitignored by default, paste-only, and contains zero PII beyond what the
-user explicitly volunteers. Schema is locked v1 in
-[`docs/contracts/agent-user-schema.md`](docs/contracts/agent-user-schema.md).
-
-Create it interactively with `/agents user init`. Inspect with
-`/agents user show`. Updates happen only through the explicit
-`review` / `accept` / `update` flow — never silent auto-writes. The
-legacy `personal.user_name` key in `.agent-settings.yml` stays as a
-fallback when `.agent-user.md` is absent.
-
-## Ghostwriter (`agents/ghostwriter/<slug>.md`)
-
-Third voice primitive — captures **public-facing writing voice of
-documented public figures** (authors, executives, academics,
-journalists, public speakers, deceased historical figures).
-`/ghostwriter:fetch <url-or-name>` runs an attestation gate, delegates
-to the host agent's `web-fetch` / `web-search` (zero network code in
-the package), and writes `agents/ghostwriter/<slug>.md` — **gitignored
-by default**, never shipped in the OSS package. `/ghostwriter:write
---as=<slug>` drafts in that voice and appends the **mandatory
-non-removable disclosure footer** (`*Written in the style of <name>,
-not by them.*`); `/post-as:ghostwriter` is a thin alias. Private
-individuals are rejected; paywalled / leaked / DM content banned at
-the schema level. `:list`, `:show`, `:delete` round out the cluster.
-Schema: [`docs/contracts/ghostwriter-schema.md`](docs/contracts/ghostwriter-schema.md).
-
-| Primitive | Voice | Disclosure footer |
-|---|---|---|
-| `personas/*.md` | review-lens (internal critique) | n/a |
-| `.agent-user.md` | maintainer's own voice (`/post-as:me`) | none — you are the author |
-| `agents/ghostwriter/<slug>.md` | external public-figure (`/post-as:ghostwriter`) | mandatory, non-removable |
-
-## Core Principles
+## Core principles
 
 - **Analyze before implementing** — no guessing, no blind edits
 - **Verify with real execution** — no "should work"
 - **Challenge to improve** — agents are thought partners, not yes-machines
 - **Strict by design** — quality over flexibility
 - **Zero overhead by default** — nothing runs until you ask for it
-- **Terse-by-default chat output** — verbosity flags off, intent narration off,
-  caveman-speak prose-only — flip back via [`docs/customization.md` § Verbosity](docs/customization.md#verbosity)
 
 ---
 
@@ -682,64 +322,39 @@ Schema: [`docs/contracts/ghostwriter-schema.md`](docs/contracts/ghostwriter-sche
 | Document | Content |
 |---|---|
 | [**Getting Started**](docs/getting-started.md) | First run, 3-test experience, profiles, next steps |
-| [**Installation**](docs/installation.md) | Plugin setup, Composer/npm, Git submodule, orchestrator details |
+| [**Installation**](docs/installation.md) | All install paths, Composer/npm, orchestrator details |
 | [**Architecture**](docs/architecture.md) | System layers, content pipeline, tool support matrix |
-| [**Development**](docs/development.md) | Prerequisites, editing workflow, all `task` commands, project structure |
 | [**Customization**](docs/customization.md) | Overrides, AGENTS.md, agent settings, cost profiles |
 | [**Quality & CI**](docs/quality.md) | Linting, CI pipeline, compression system |
-| [**Migration**](docs/MIGRATION.md) | Per-version upgrade steps (e.g. `implement_ticket → work_engine` in 1.15.0) |
-
-Uninstalling: see
-[docs/installation.md#uninstalling](docs/installation.md#uninstalling) —
-there is no dedicated uninstall command; removal is a documented manual
-step (package manager + `rm -rf` of generated dirs).
-
-### Maintainer telemetry (opt-in, default-off)
+| [**Migration**](docs/MIGRATION.md) | Per-version upgrade steps |
+| [**Showcase**](docs/showcase.md) | More examples & expected behavior |
 
-Local-only artefact-engagement log (`telemetry.artifact_engagement.enabled: true` in `.agent-settings.yml`) records which skills / rules / commands / guidelines the agent consults during `/implement-ticket` / `/work`. JSONL under the project root, nothing uploaded, nothing shared. Reports via `./agent-config telemetry:report`. Contract + privacy floor: [`contexts/contracts/artifact-engagement-flow.md`](.agent-src.uncompressed/contexts/contracts/artifact-engagement-flow.md) (beta).
-
-### Context-aware command suggestion
-
-When a user prompt matches a command's purpose ("setze ticket ABC-123 um"
-→ `/implement-ticket`), the agent surfaces matches as a numbered-options
-block with an always-present "run the prompt as-is" escape. **Nothing
-auto-executes** — the user picks every time. Three opt-out paths:
-
-```yaml
-# .agent-settings.yml
-commands:
-  suggestion:
-    enabled: true            # global on/off
-    blocklist: []            # specific commands never suggested
-    confidence_floor: 0.6    # tunable per command in frontmatter
-```
-
-Per-conversation: `/command-suggestion-off` disables the layer until
-re-enabled or the chat ends. Full scoring contract and hardening:
-[`adr-command-suggestion`](docs/contracts/adr-command-suggestion.md),
-[`command-suggestion-flow`](.agent-src.uncompressed/contexts/contracts/command-suggestion-flow.md) (beta).
+Browse content: [all 129 commands](.agent-src/commands/) · [skills catalog](docs/skills-catalog.md) · [full catalog](docs/catalog.md) · [`llms.txt`](llms.txt).
 
 ---
 
 ## Development
 
-Working on the package itself? Edit in `.agent-src.uncompressed/`,
-then regenerate compressed and projected trees:
+Working on the package itself? Edit `packages/core/.agent-src.uncompressed/`, regenerate trees:
 
 ```bash
 task sync             # regenerate .agent-src/ and .augment/
 task generate-tools   # regenerate .claude/, .cursor/, .clinerules/, .windsurfrules
 task ci               # full pipeline — green before PR
 task test             # unit + integration tests
+task dev:setup        # boot the onboarding wizard against the working tree
 ```
 
-→ Full commands and project structure: [**docs/development.md**](docs/development.md)
+**Invoking the CLI from a source checkout:** `./agent-config <command>` (the maintainer shim at the repo root → `scripts/agent-config` → `dist/cli/agent-config.js`). `npx @event4u/agent-config` doesn't resolve in the source repo without a prior `npm link`, since there's no `node_modules/.bin/agent-config` symlink — use `./agent-config` instead. Build the TS binary with `npm run build:cli` if `dist/cli/agent-config.js` is missing.
+
+→ Full project structure and commands: [**docs/development.md**](docs/development.md) · [CONTRIBUTING.md](CONTRIBUTING.md). Stack: **TypeScript** CLI/UI + **Python 3.10+** build/lint scripts. MCP registry payloads render under `dist/mcp/` ([submission checklist](docs/distribution/mcp-submission-checklist.md)).
+
+---
 
 ## Requirements
 
-- **Bash** — `scripts/install` orchestrates payload sync (`install.sh`) and bridges (`install.py`).
-- **Python 3.10+** — bridge stage only; missing → orchestrator skips bridges.
-- **Composer or npm** — to pull the package.
+- **Node ≥ 18** — `npx @event4u/agent-config init` is the canonical install path.
+- **Python 3.10+** — bridge stage only; missing → installer skips bridges.
 - **Platform:** macOS 12.3+, Linux, WSL2. Git Bash needs Developer Mode for symlinks; native PowerShell / cmd unsupported. Contributors rebuilding `.augment/` also need [Task](https://taskfile.dev/).
 
 ## License