@event4u/agent-config 9.7.0 → 9.9.0

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

@@ -1,99 +0,0 @@
-# MCP Registry Listing — submission package
-
-Single source of truth for every MCP-registry submission of the hosted
-`agent-config-mcp` Worker. Copy-paste sections from this file into the
-target registry's template; do not maintain per-registry forks.
-
-Phase 6.1 of `agents/roadmaps/road-to-cloudflare-mcp-hosting.md`.
-
-## One-liner
-
-> Read-only governance surface for AI coding agents — 174 skills, 104
-> commands, 60 rules, 100 guidelines + contexts. Hosted MCP bridge
-> over the `event4u/agent-config` package.
-
-## Endpoints
-
-| Shape | URL | Use |
-|---|---|---|
-| Rolling latest | `https://mcp.<operator-domain>/latest/sse` | clients tracking the live build |
-| Pinned release | `https://mcp.<operator-domain>/v<X.Y.Z>/sse` | clients pinning a reproducible version |
-| Liveness | `GET https://mcp.<operator-domain>/` | release identity + signature |
-
-The `<operator-domain>` placeholder reflects the package's design —
-every operator hosts their own Worker. The package upstream does not
-run a public reference deployment; consumers point their Worker at
-their own R2 bucket per `docs/setup/mcp-r2-bootstrap.md`.
-
-## Wire surface (MVP-1)
-
-| Method | Status |
-|---|---|
-| `initialize` | implemented |
-| `ping` | implemented |
-| `prompts/list`, `prompts/get` | implemented |
-| `resources/list`, `resources/read` | implemented |
-| `tools/list` | implemented (returns deprecated stubs only) |
-| `tools/call` | **not implemented** — returns `-32601 Method not found` |
-| `notifications/*` | not implemented |
-
-No mutation, no auth, no subrequests at runtime. Full contract:
-`docs/contracts/mcp-cloud-scope.md` § A0-cloud.
-
-## Stability
-
-**Experimental.** Wire surface, URL shapes, and the `_meta.signature`
-field are pinned for the lifetime of the *experimental* window.
-Breaking changes require a stability-label bump (see
-`docs/contracts/mcp-phase-1-scope.md`).
-
-## Identity & reproducibility
-
-Every response carries `_meta.skillSetSignature` — a 12-char SHA-256
-prefix over the sorted `(uri, body)` pairs of the bundled content.
-Identical content → identical signature, across machines and builds.
-R2 archives every release indefinitely under
-`releases/v<X.Y.Z>-<sha>/`.
-
-## Categories (for registry tagging)
-
-- `governance`
-- `meta-prompting`
-- `skills`
-- `agent-infrastructure`
-- `code-review`
-- `experimental`
-
-## License & contact
-
-| Field | Value |
-|---|---|
-| License | MIT |
-| Source | `https://github.com/event4u-app/agent-config` |
-| Maintainer | event4u-app (org) |
-| Contact | GitHub issues |
-
-## Links to upstream contracts
-
-- A0-cloud safety contract: `docs/contracts/mcp-cloud-scope.md`
-- Phase-1 scope (inherited): `docs/contracts/mcp-phase-1-scope.md`
-- URL shapes & DNS: `docs/setup/mcp-cloud-endpoints.md`
-- Local stdio kernel (predecessor): `scripts/mcp_server/`
-
-## Submission targets
-
-| Target | Status | Notes |
-|---|---|---|
-| [`awesome-mcp-servers`](https://github.com/punkpeye/awesome-mcp-servers) | ready for PR | low-friction listing, accepts experimental |
-| [`modelcontextprotocol.io` catalog](https://modelcontextprotocol.io/servers) | ready for PR after `awesome-mcp-servers` merges | needs evidence of community uptake |
-
-Both submissions reuse the **One-liner**, **Endpoints**, **Wire
-surface**, **Stability**, and **License & contact** sections verbatim
-from this file.
-
-## Out of scope for this roadmap
-
-npm-launcher listing (`npx @event4u/agent-config-mcp`) targets the
-**local stdio** server, not the hosted Worker. Different transport,
-different installation pattern, different audience — captured in
-`agents/roadmaps/road-to-mcp-server.md` if revived.

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.