@event4u/agent-config 9.8.0 → 9.9.0

package/docs/setup/mcp-cloud-setup.md

@@ -1,183 +0,0 @@
-# Cloudflare MCP — Operator Setup
-
-One-stop landing for onboarding a Cloudflare account to host the
-`agent-config-mcp` Worker. Combines bucket bootstrap, DNS, GitHub
-secrets, and troubleshooting in one place.
-
-Governed by [`docs/contracts/mcp-cloud-scope.md`](../contracts/mcp-cloud-scope.md)
-(A0-cloud). Deploys run **only** in CI
-([`.github/workflows/deploy-mcp-worker.yml`](../../.github/workflows/deploy-mcp-worker.yml))
-— per A0-cloud invariant 7, never `wrangler deploy` from a developer
-machine.
-
-## TL;DR — the happy path
-
-```sh
-task mcp:cloud:login        # one-time, opens browser
-task mcp:cloud:setup        # check → r2-create → r2-verify → whoami
-task mcp:cloud:secret-put   # optional but recommended — sets MCP-Token (Bearer auth)
-# Copy account id from output → GitHub Secrets (see § GitHub Secrets)
-# Create scoped API token (see § API Token) → GitHub Secrets
-# Done. First `release: published` triggers the deploy.
-```
-
-## Prerequisites
-
-| Tool | Version | Install |
-|---|---|---|
-| Node.js | ≥ 20 | <https://nodejs.org/> or `nvm install 20` |
-| `npx`/`wrangler` | wrangler ≥ 4.0 (auto-fetched on first run) | bundled with Node |
-| `gh` CLI | latest | <https://cli.github.com/> (only for manual `deploy-dispatch`) |
-| Cloudflare account | any plan | <https://dash.cloudflare.com/sign-up> |
-
-Run `task mcp:cloud:check` to verify all four in one shot.
-
-## Step 1 — Cloudflare login
-
-```sh
-task mcp:cloud:login
-```
-
-Opens a browser to authorize wrangler against your Cloudflare account.
-One-time per developer machine; the token is stored in
-`~/Library/Preferences/.wrangler/` (macOS) or `~/.wrangler/` (Linux).
-
-## Step 2 — Enable R2
-
-Cloudflare requires a one-time plan activation before R2 buckets can
-be created. **You will hit error `code: 10042` on the first attempt
-if you skip this.**
-
-1. <https://dash.cloudflare.com/?to=/:account/r2/overview>
-2. Click **Purchase R2 Plan**
-3. Select **Free Tier** — 10 GB storage / 1 M Class-A / 10 M Class-B
-   ops per month at **$0** (credit card required, $0 within quota,
-   $0 egress)
-4. Confirm; wait ~30 s for activation
-
-## Step 3 — Create the R2 bucket
-
-```sh
-task mcp:cloud:r2-create     # idempotent — safe to re-run
-task mcp:cloud:r2-verify     # ✅ if present
-```
-
-The bucket is named `agent-config-mcp` and configured per
-[`docs/setup/mcp-r2-bootstrap.md`](mcp-r2-bootstrap.md) (private,
-indefinite retention, Worker reads via binding).
-
-`task mcp:cloud:setup` chains steps 1, 3, and the account-id readout
-in one shot.
-
-## Step 4 — API Token
-
-The CI deploy pipeline needs a **scoped** token — never reuse the
-Global API Key or a production-tenant token.
-
-Dashboard → **My Profile → API Tokens → Create Token → Custom token**:
-
-| Permission | Resource | Access |
-|---|---|---|
-| Account · Workers Scripts | your account | Edit |
-| Account · Workers R2 Storage | your account | Edit |
-| User · User Details | — | Read |
-
-If you uncomment the `routes` block in `internal/workers/mcp/wrangler.toml`
-(custom domain cutover, Phase 5.2), add **Zone · DNS · Edit** on the
-relevant zone.
-
-Copy the generated token immediately — Cloudflare shows it once.
-
-## Step 5 — GitHub Secrets
-
-Repository → **Settings → Secrets and variables → Actions → New
-repository secret**:
-
-| Secret | Value | Source |
-|---|---|---|
-| `CLOUDFLARE_API_TOKEN` | scoped token from Step 4 | dashboard |
-| `CLOUDFLARE_ACCOUNT_ID` | account id | `task mcp:cloud:whoami` |
-
-Set them in **Actions** secrets, not **Codespaces** or **Dependabot**
-scopes.
-
-## Step 6 — Validate
-
-Trigger the deploy workflow manually against an existing tag — no
-release event needed:
-
-```sh
-task mcp:cloud:deploy-dispatch TAG=v1.37.0
-gh run watch
-```
-
-Green smoke step → `latest.txt` repoints → release is live on
-`*.workers.dev`. A red smoke step leaves `latest.txt` on the previous
-release.
-
-## Step 7 — Bearer auth (recommended)
-
-Without auth, anyone who knows your `*.workers.dev` URL can read the
-catalog. The Worker checks for an `MCP-Token` secret and, when set,
-gates every POST behind `Authorization: Bearer <token>`. The `GET /`
-liveness probe stays open so health checks keep working.
-
-Generate a token (any high-entropy random string — `openssl rand -hex 32`
-or your password manager) and set it on the Worker:
-
-```sh
-task mcp:cloud:secret-put
-# wrangler prompts for the value interactively (stdin) — never passed
-# via argv, never written to shell history.
-```
-
-This wraps `npx wrangler secret put MCP-Token --name agent-config-mcp`.
-The secret is encrypted in Cloudflare and injected as `env["MCP-Token"]`
-at request time; the source repo never sees the value.
-
-Once set, every MCP client config needs the header — per-client
-snippets (Claude Desktop, Claude Code, Cursor, Zed, Continue) live in
-[`mcp-client-config.md`](mcp-client-config.md) § Bearer auth.
-
-Rotate by re-running `task mcp:cloud:secret-put` with a fresh value;
-the new secret takes effect on the next request (no redeploy needed).
-To remove auth entirely, run
-`npx wrangler secret delete MCP-Token --name agent-config-mcp`.
-
-## Step 8 — DNS (optional, Phase 5.2)
-
-Custom domain `mcp.<your-domain>` setup lives in
-[`docs/setup/mcp-cloud-endpoints.md`](mcp-cloud-endpoints.md) § DNS
-setup. Until cutover, the Worker serves on the free
-`agent-config-mcp.<account>.workers.dev` URL.
-
-## Troubleshooting
-
-| Symptom | Cause | Fix |
-|---|---|---|
-| `code: 10042` on bucket create | R2 not enabled on account | Step 2 — Enable R2 |
-| `wrangler whoami` shows no Account ID | not logged in | `task mcp:cloud:login` |
-| Workflow fails on `wrangler deploy` with auth error | secret missing/wrong scope | re-check Step 4 token permissions |
-| Smoke step red after deploy | bundle vs. SDK mismatch | check `compatibility_date` in `wrangler.toml` |
-| Bucket create returns `already exists` | bucket present | not an error — `task mcp:cloud:r2-verify` to confirm |
-
-## Available tasks
-
-| Task | Purpose |
-|---|---|
-| `task mcp:cloud:check` | Preflight — tools + login status |
-| `task mcp:cloud:login` | Interactive wrangler login |
-| `task mcp:cloud:whoami` | Print account id for GitHub Secret |
-| `task mcp:cloud:r2-create` | Create R2 bucket (idempotent) |
-| `task mcp:cloud:r2-verify` | Verify R2 bucket exists |
-| `task mcp:cloud:setup` | Full chain — check → r2 → whoami |
-| `task mcp:cloud:secret-put` | Set the `MCP-Token` Bearer-auth secret (interactive) |
-| `task mcp:cloud:dev` | Local `wrangler dev` on :8787 |
-| `task mcp:cloud:deploy-dispatch TAG=v…` | Manual workflow trigger |
-
-## See also
-
-- [`docs/contracts/mcp-cloud-scope.md`](../contracts/mcp-cloud-scope.md) — A0-cloud contract
-- [`docs/setup/mcp-r2-bootstrap.md`](mcp-r2-bootstrap.md) — R2 layout & break-glass
-- [`docs/setup/mcp-cloud-endpoints.md`](mcp-cloud-endpoints.md) — URL shapes & DNS
-- [`internal/workers/mcp/README.md`](../../internal/workers/mcp/README.md) — Worker source overview

package/docs/setup/mcp-r2-bootstrap.md

@@ -1,82 +0,0 @@
-# R2 Bootstrap — agent-config MCP
-
-One-time setup for the R2 bucket that holds the Worker's release archive.
-Owned by `mcp-cloud-scope.md` §3.3 and consumed by the deploy pipeline
-(`.github/workflows/deploy-mcp-worker.yml`).
-
-## Bucket
-
-| Field | Value |
-|---|---|
-| Bucket name | `agent-config-mcp` |
-| Location hint | `auto` (Cloudflare-chosen) |
-| Public access | **off** — Worker reads via binding, never via signed URL |
-| Object retention | indefinite — every release stays for forensics |
-
-## Layout
-
-```
-agent-config-mcp/
-├─ releases/
-│  ├─ v<X.Y.Z>-<sha>/
-│  │  ├─ content.json.gz    # gzipped content blob (R2 archival copy)
-│  │  └─ manifest.json      # uncondensed manifest sidecar
-│  └─ latest.txt            # one-line: v<X.Y.Z>-<sha>
-└─ (no other prefixes)
-```
-
-`latest.txt` is the only mutable object. Every `releases/v*/` directory
-is **immutable** once written; the pipeline refuses to overwrite an
-existing release prefix.
-
-## Bootstrap — one-time
-
-Requires `wrangler` ≥ 4.0 and a Cloudflare API token with R2 admin scope.
-
-```sh
-# 1. Authenticate (interactive, opens browser).
-npx wrangler login
-
-# 2. Create the bucket.
-npx wrangler r2 bucket create agent-config-mcp
-
-# 3. Verify.
-npx wrangler r2 bucket list | grep agent-config-mcp
-```
-
-The Worker binding is declared in `internal/workers/mcp/wrangler.toml` under
-`[[r2_buckets]]`. The pipeline reads/writes via the wrangler CLI in CI,
-not via the Worker — A0-cloud invariant 2 forbids the Worker from
-issuing R2 writes.
-
-## Secrets in CI
-
-The deploy pipeline needs two GitHub secrets:
-
-| Secret | Scope |
-|---|---|
-| `CLOUDFLARE_API_TOKEN` | `Workers Scripts:Edit` + `Workers R2 Storage:Edit` |
-| `CLOUDFLARE_ACCOUNT_ID` | account id (not a token) |
-
-The token must be scoped to **this account only**; do not reuse a
-production-tenant token.
-
-## Manual fixes — break-glass
-
-If `latest.txt` ends up pointing to a broken release, the recovery is to
-repoint it manually:
-
-```sh
-# Repoint latest to a known-good release.
-echo -n "v1.36.0-abc1234" | \
-  npx wrangler r2 object put agent-config-mcp/releases/latest.txt --pipe
-```
-
-Past `releases/v*/` directories are not deleted in recovery — leave the
-forensics intact.
-
-## Terraform note
-
-The repo does not yet manage CF resources via Terraform. When TF lands,
-this bucket should move into a `cloudflare_r2_bucket` resource and this
-doc shrinks to a pointer.

package/docs/setup/mcp-server-docker.md

@@ -1,101 +0,0 @@
-# MCP server — Docker (stdio bundle)
-
-Phase-6 F3 ships `internal/docker/mcp-server/Dockerfile`: a stdio-only image of
-the agent-config MCP server, pinned to the same `mcp` + `PyYAML`
-versions the test suite runs against. No HTTP / SSE transport — that
-lives in [`road-to-mcp-distribution.md`](../../agents/roadmaps/road-to-mcp-distribution.md)
-under its own A0 amendment.
-
-## Build
-
-Build context is the **repo root**, not `internal/docker/mcp-server/` — the
-`COPY` lines reference paths relative to the project root.
-
-```bash
-docker build -f internal/docker/mcp-server/Dockerfile -t agent-config-mcp:local .
-```
-
-Tag conventions:
-
-- `:local` — your machine, current working tree
-- `:vX.Y.Z` — pinned to `package.json::version` at release time
-- `:latest` — most recent release (avoid in MCP client configs; pin)
-
-## Run (stdio)
-
-The image speaks MCP over **stdin / stdout**. `docker run` must be
-invoked with `-i` (interactive stdin) — without it the server has
-nothing to read and exits silently.
-
-```bash
-docker run --rm -i agent-config-mcp:local
-```
-
-You should see, on **stderr**:
-
-```
-mcp-server: loaded 377 prompts (0 warnings)
-mcp-server: loaded 189 resources (0 warnings)
-mcp-server: registered 20 tools (9 implemented, 11 stubs)
-mcp-server: identity serverVersion=0.1.0 packageVersion=<semver> skillSetSignature=<12-hex>
-```
-
-Prompt / resource / tool counts grow as the suite grows — the meaningful
-signal is `0 warnings`, not the exact numbers. The fourth line is the F1
-identity surface — see
-[`mcp-phase-1-scope.md § Phase 6`](../contracts/mcp-phase-1-scope.md)
-for semantics.
-
-## Wire into an MCP client
-
-```jsonc
-// .mcp.json (or your client's equivalent)
-{
-  "mcpServers": {
-    "agent-config": {
-      "command": "docker",
-      "args": ["run", "--rm", "-i", "agent-config-mcp:vX.Y.Z"]
-    }
-  }
-}
-```
-
-## Volume mounts (`chat_history_append`)
-
-The `chat_history_append` tool writes to
-`agents/runtime/.agent-chat-history` **inside the container**
-(`agents/.agent-chat-history` and `.agent-chat-history` are accepted
-for back-compat). For writes to survive container lifecycle, mount
-the host directory:
-
-```bash
-docker run --rm -i \
-  -v "$(pwd)/agents/runtime/.agent-chat-history:/app/agents/runtime/.agent-chat-history" \
-  agent-config-mcp:local
-```
-
-Without the mount the tool still succeeds (path-scope check passes
-inside the container), but the appended JSONL evaporates when the
-container exits. The `lint_skills` tool is read-only and needs no
-mount.
-
-## Security posture
-
-The image inherits the A0 contract verbatim — see
-[`mcp-phase-1-scope.md`](../contracts/mcp-phase-1-scope.md):
-
-- No `subprocess`, `os.system`, `requests`, `httpx`, or `urllib`
-  imports anywhere on the MCP wire surface (enforced by
-  `test_no_unsafe_imports_in_*` tests).
-- Tools allowlist is hardcoded in `src/scripts/mcp_server/tools.py`. The
-  container cannot grow new tools at runtime.
-- Image runs as a non-root user (`mcp:mcp`). Mounted host paths must
-  be writable by uid/gid `999` or you'll see permission errors.
-- No HTTP listener — there is no network attack surface. Stdin/stdout
-  only.
-
-## Size
-
-The runtime stage is `python:3.11-slim` + the pinned deps + the
-`dist/agent-src/` content. Expect ~150-200 MB; the builder stage is
-discarded.

package/docs/setup/per-ide/aider.md

@@ -1,48 +0,0 @@
-# Aider Setup
-
-Aider reads `AGENTS.md` (and the legacy `CONVENTIONS.md` if present)
-from the repo root for project conventions.
-
-## Prerequisites
-
-- Aider installed: <https://aider.chat>.
-- Node.js ≥ 18 (for the install entrypoints).
-
-## Install
-
-```bash
-npx @event4u/agent-config init --tools=aider
-```
-
-Populates:
-
-- `AGENTS.md`             — agent self-orientation (Aider auto-loads)
-- `.agent-settings.yml`   — per-project knobs
-
-Aider's chat will read `AGENTS.md` on every session start. Add it to
-the chat explicitly if Aider doesn't pick it up:
-
-```bash
-aider AGENTS.md
-```
-
-## Verification
-
-```bash
-test -f AGENTS.md
-```
-
-In Aider: type `/tokens` — `AGENTS.md` should appear in the loaded
-files list.
-
-## Troubleshooting
-
-| Symptom | Fix |
-|---|---|
-| `AGENTS.md` not auto-loaded | `aider --read AGENTS.md` or `/read AGENTS.md`. |
-| Conventions ignored | Aider reads `CONVENTIONS.md` legacy too — check `--auto-commits` flag. |
-
-## Cross-references
-
-- [`AGENTS.md`](../../../AGENTS.md) — canonical agent self-orientation.
-- [`docs/installation.md`](../../installation.md) — install matrix index.

package/docs/setup/per-ide/antigravity.md

@@ -1,68 +0,0 @@
-# Antigravity Setup
-
-Antigravity (Google's agentic IDE) reads the Anthropic-shaped
-markdown skill bundle from its user-scope anchor `~/.agents/`. The
-package deploys the universal skill bundle at global scope, the same
-projection its other bundle hosts get (codex, continue, roocode and
-the rest) — global-only by design, not a pending gap.
-
-## Prerequisites
-
-- Antigravity IDE.
-- Node.js ≥ 18 for the install entrypoints.
-
-## Install
-
-Global only (canonical scope):
-
-```bash
-npx @event4u/agent-config init --tools=antigravity --global
-```
-
-Populates:
-
-- `~/.agents/skills/`   — Anthropic-shaped skill bundle
-- `~/.agents/rules/`    — kernel + tier-1/2 rules
-- `~/.agents/personas/` — review-lens personas
-
-(Project-scope `--tools=antigravity` is rejected with exit code 1
-— every bundle host is global-only; the package writes the shared
-bundle to a user-scope anchor, not into the project. Antigravity does
-have a native project `.agents/` convention (`skills/`, `agents.md`,
-`workflows/`), but a project-scope projection is not part of the
-shipped surface.)
-
-## How to use
-
-- Antigravity reads the skill bundle from `~/.agents/skills/` on
-  every session — no manual action required.
-- Slash commands (`/work`, `/implement-ticket`, `/commit`,
-  `/create-pr`, …) ship inside the skill bundle as named skills.
-  Invoke them by name in chat.
-- Antigravity ships an agent-orchestration surface; point it at
-  the project root so the agent can locate `AGENTS.md` and the
-  project's own `agents/` overlay.
-
-## Verification
-
-```bash
-test -d ~/.agents/skills
-test -d ~/.agents/rules
-```
-
-In Antigravity: ask *"What is this repo?"* — the answer should
-cite the AGENTS.md emergency triage block when the workspace is
-open.
-
-## Troubleshooting
-
-| Symptom | Fix |
-|---|---|
-| Skills not listed | Re-run `npx @event4u/agent-config init --tools=antigravity --global --force`. |
-| `--tools=antigravity` rejected | Add `--global` (Antigravity has global-only scope). |
-| `~/.agents/` collides with another tool | The anchor is shared by convention; coexists with other agents that use the same path. |
-
-## Cross-references
-
-- [`AGENTS.md`](../../../AGENTS.md) — canonical agent self-orientation.
-- [`docs/installation.md`](../../installation.md) — install matrix index.

package/docs/setup/per-ide/augment.md

@@ -1,89 +0,0 @@
-# Augment Code Setup
-
-Augment Code is **global-only** in this package — content ships from a
-single user-scope tree at `~/.augment/` and the Augment extension
-(VS Code, JetBrains) reads it on every workspace. Per-project
-`.augment/` content is not installed; project `init` writes only the
-`.augment/settings.json` marker that authorizes the plugin for the
-workspace.
-
-> **Why global-only?** Augment counts the full body of every file in
-> `.augment/rules/` against its 49,512-char workspace-guidelines limit.
-> The package-wide rule set exceeds that limit on every workspace, so
-> a single user-scope install is the canonical surface and the
-> overflow is a known, accepted trade-off. See
-> [`ADR-007 § Amendment 2026-05-13 — global-only`](../../decisions/ADR-007-agent-discovery-scopes.md#amendment-2026-05-13--augment-global-only).
-
-## Prerequisites
-
-- Augment Code extension: <https://www.augmentcode.com/>.
-- Node.js ≥ 18 for the install entrypoints.
-
-## Install
-
-Global scope (the only supported path — deploys the full bundle to
-`~/.augment/`):
-
-```bash
-npx @event4u/agent-config init --tools=augment --global
-```
-
-`--tools=augment` without `--global` is rejected with a directive
-error; `--tools=all` (project scope) silently filters `augment` out.
-
-Populates (`~/.augment/`):
-
-- `~/.augment/rules/`     — kernel (9 Iron-Law rules) + tier-1/2 routed rules
-- `~/.augment/skills/`    — domain skills
-- `~/.augment/commands/`  — slash commands
-- `~/.augment/personas/`  — review-lens personas
-- `~/.augment/contexts/`  — knowledge-layer contexts
-- `~/.augment/templates/` — scaffolds for AGENTS.md, copilot-instructions, etc.
-
-A project-scope `init` (any `--tools=…` selection except `augment`)
-still writes:
-
-- `.augment/settings.json` — plugin activation marker for the workspace
-- `AGENTS.md`              — canonical agent self-orientation
-- `.agent-settings.yml`    — per-project knobs
-
-## How to use
-
-- Augment auto-discovers `.augment/` on every session — no manual
-  action required.
-- The kernel rules (always-on Iron Laws) load first; tier-1/2
-  rules are routed by the rule-router based on intent.
-- Slash commands (`/work`, `/implement-ticket`, `/commit`,
-  `/create-pr`, `/refine-ticket`, …) are registered as Augment
-  Skills and surfaced in the agent's available-skills list.
-- Personas are review-lens voices; invoke them per `/mode` or by
-  name inside `/work` and `/implement-ticket` plans.
-- `.agent-settings.yml` controls per-project knobs (autonomy
-  default, cost profile, role-mode, learning opt-out).
-
-## Verification
-
-```bash
-test -d ~/.augment/rules
-test -d ~/.augment/skills
-test -d ~/.augment/commands
-test -f AGENTS.md
-```
-
-Open the Augment panel and ask *"What is this repo?"* — the answer
-should cite the AGENTS.md emergency triage block.
-
-## Troubleshooting
-
-| Symptom | Fix |
-|---|---|
-| Skills not surfaced | Reload the Augment workspace; skills are indexed on session start. |
-| `~/.augment/rules/` missing | Re-run `npx @event4u/agent-config init --tools=augment --global`. |
-| Workspace-guidelines overflow warning | Expected — the package rule set exceeds Augment's 49,512-char budget. See [`ADR-007 § Amendment 2026-05-13`](../../decisions/ADR-007-agent-discovery-scopes.md#amendment-2026-05-13--augment-global-only). |
-| Iron Laws not firing | Confirm `~/.augment/rules/` contains 9 kernel files. |
-
-## Cross-references
-
-- [`AGENTS.md`](../../../AGENTS.md) — canonical agent self-orientation.
-- [`docs/architecture.md`](../../architecture.md) — kernel + router + projection pipeline.
-- [`docs/installation.md`](../../installation.md) — install matrix index.

package/docs/setup/per-ide/claude-code.md

@@ -1,97 +0,0 @@
-# Claude Code Setup
-
-Claude Code is the canonical agent surface for `event4u/agent-config`. It
-reads from `.claude/skills/`, `.claude/commands/`, `CLAUDE.md`,
-`.claude/hooks/`, and project-level MCP servers. Everything in this repo
-projects to those paths during install.
-
-## Prerequisites
-
-- Claude Code installed (CLI or VS Code extension): <https://claude.com/code>.
-- Node.js ≥ 18 (for the `npx` entrypoints).
-- Git working tree (the package is repository-aware).
-
-## Project install (recommended)
-
-```bash
-# Inside an existing repo:
-npx @event4u/agent-config init --tools=claude-code
-
-# Or with the curl entrypoint:
-curl -sSL https://raw.githubusercontent.com/event4u-app/agent-config/main/setup.sh \
-  | bash -s -- --tools=claude-code
-```
-
-Either form populates:
-
-- `.claude/skills/`         — symlinks into `dist/agent-src/skills/`
-- `.claude/commands/`       — symlinks into `dist/agent-src/commands/`
-- `CLAUDE.md`               — agent root pointer (auto-loaded by Claude Code)
-- `.agent-settings.yml`     — your per-project knobs (kept out of git)
-
-## Plugin marketplace (Claude Code 2026+)
-
-Claude Code 2026 supports plugin marketplaces via
-`.claude-plugin/marketplace.json`. The package ships one, so as an
-**additional, optional** surface you can also install the plugin:
-
-```bash
-claude plugin marketplace add event4u-app/agent-config
-claude plugin install agent-config@event4u-agent-config
-```
-
-The npm/curl entrypoints above are a full install on their own — the
-file projection carries the complete skill/command set; the plugin adds
-the namespaced `agent-config:*` surface on top. When the plugin is
-installed, `agent-config upgrade` refreshes it automatically (Claude
-Code otherwise pins it to the install-time git SHA); `agent-config
-doctor --check claude-plugin` reports a stale snapshot.
-
-## CLAUDE.md
-
-Auto-loaded by Claude Code from the repo root. The package's `CLAUDE.md`
-points to `AGENTS.md` (single source of truth for all agent surfaces);
-edit `AGENTS.md`, never `CLAUDE.md`.
-
-## Hooks
-
-Claude Code reads `.claude/hooks/` for pre/post tool hooks. The package
-ships a memory-extraction hook (Phase 7 of `road-to-mcp-full-coverage`).
-Local overrides go in `agents/overrides/.claude/hooks/`.
-
-## Skills you'll use most
-
-- `/work "<prompt>"` — refine → plan → implement → verify → report loop.
-- `/commit` — Conventional-Commit splitter with confirmation gate.
-- `/create-pr` — opens a structured PR from the current branch.
-- `/review-changes` — five-judge self-review before requesting human review.
-- `/agent-handoff` — produces a fresh-chat continuation summary.
-
-Full list: `ls .claude/skills/`.
-
-## Verification
-
-```bash
-ls -la .claude/skills/        # should symlink into dist/agent-src/skills/
-ls -la CLAUDE.md              # exists, points to AGENTS.md
-test -f .agent-settings.yml   # per-project settings rendered
-```
-
-In Claude Code itself: type `/` — the slash menu should list `work`,
-`commit`, `create-pr`, etc.
-
-## Troubleshooting
-
-| Symptom | Fix |
-|---|---|
-| `/` menu empty | `ls .claude/skills/` — re-run installer if empty. |
-| Skills look stale after `git pull` | `task sync && task generate-tools`. |
-| Hook never fires | `claude --debug` and inspect hook output. |
-| Memory MCP missing | See `road-to-mcp-full-coverage` — Phase 3 ships read-only tools. |
-
-## Cross-references
-
-- [`docs/installation.md`](../../installation.md) — install matrix index.
-- [`docs/setup/per-ide/claude-desktop.md`](claude-desktop.md) — Desktop +
-  Cowork share the same `~/.claude/skills/` path; install once, both surfaces benefit.
-- [`AGENTS.md`](../../../AGENTS.md) — package self-orientation.