@event4u/agent-config 9.8.0 → 9.10.0

package/docs/maintainers/branch-protection.md

@@ -1,105 +0,0 @@
-# Branch protection for `main` — prepared config (user-applied)
-
-> The one reviewer point open since PR #223, repeated in every 8.11 review:
-> "no code needed." Correct — and that is exactly why an agent never applies
-> it: changing repository protection is a repo-admin, outward-facing action
-> that affects every future merge. This page prepares the exact
-> configuration; a human runs it. Blocker `branch-protection-apply` (owner:
-> user) in `road-to-feedback-8.11-2` tracks the application.
-
-## Design decisions (council 2026-07-12)
-
-- **PR required, no direct pushes to `main`** — including the maintainer;
-  the agent-side rules already treat `main` as a Hard-Floor trunk, this
-  makes GitHub enforce the same.
-- **No force-pushes, no branch deletion.**
-- **Required checks = a MINIMAL STABLE CORE, not all ~59 checks.**
-  Requiring everything turns every workflow/job rename into a lockout.
-  Core = the suites that gate correctness on every PR:
-  - `Static Checks (ESLint · typecheck · prepack)`
-  - `Node Tests (ubuntu-latest, shard 1/4)` … `shard 4/4`
-  - `Golden Tests (ubuntu-latest)`
-  - `Install Aux Tests (ubuntu-latest)`
-  (macOS twins stay unrequired — same code, second OS; they still run and
-  still show red, they just don't lock the merge on a runner outage.)
-- **Enforce for admins: yes** (otherwise the protection is decorative).
-- **Required reviews: 0 for now** — the trailing-90-day distinct-reviewer
-  count is 1 (bus-factor reality); requiring a second reviewer would block
-  every merge. Revisit when a second maintainer exists
-  (`road-to-maintainer-bus-factor`).
-
-## Verify the current check names first (renames happen)
-
-```bash
-gh api repos/event4u-app/agent-config/commits/main/check-runs \
-  --jq '.check_runs[].name' | sort -u
-```
-
-Adjust the `contexts` list below to the names that actually exist — this
-doc is a preparation, the live names win.
-
-## The ready-to-run command
-
-```bash
-gh api -X PUT repos/event4u-app/agent-config/branches/main/protection \
-  --input - <<'JSON'
-{
-  "required_status_checks": {
-    "strict": false,
-    "contexts": [
-      "Static Checks (ESLint · typecheck · prepack)",
-      "Node Tests (ubuntu-latest, shard 1/4)",
-      "Node Tests (ubuntu-latest, shard 2/4)",
-      "Node Tests (ubuntu-latest, shard 3/4)",
-      "Node Tests (ubuntu-latest, shard 4/4)",
-      "Golden Tests (ubuntu-latest)",
-      "Install Aux Tests (ubuntu-latest)"
-    ]
-  },
-  "enforce_admins": true,
-  "required_pull_request_reviews": null,
-  "restrictions": null,
-  "allow_force_pushes": false,
-  "allow_deletions": false
-}
-JSON
-```
-
-Notes: `strict: false` deliberately — with a single maintainer,
-require-branches-up-to-date adds a rebase round-trip per merge with no
-second-writer race to protect against; flip to `true` when there are
-concurrent mergers. `required_pull_request_reviews: null` per the
-bus-factor reality above.
-
-## Operating conditions under `strict: false`
-
-`strict: false` drops the branches-up-to-date requirement, so three
-conditions become merge-time habits the config cannot enforce:
-
-- **The checked commit must not change after green CI.** No post-CI
-  amend or force-push on the PR branch — the config already blocks
-  force-pushes to `main`; the same discipline applies to the head that
-  CI checked: what went green is what merges.
-- **Critical checks must have run on the final head before merge.** A
-  human glance at the checks tab on the PR's latest commit — with
-  `strict: false` GitHub does not re-run required checks when the base
-  moves, so the green you see is only as fresh as the head it ran on.
-- **Auto-merge must not be enabled in a way that merges with pending or
-  failed required checks.** Enable auto-merge only once the required
-  list is complete and green on the final head — never as a
-  fire-and-forget while checks are still queued.
-
-## Rollback
-
-```bash
-gh api -X DELETE repos/event4u-app/agent-config/branches/main/protection
-```
-
-## After applying
-
-- Verify: `gh api repos/event4u-app/agent-config/branches/main/protection --jq '{checks: .required_status_checks.contexts, admins: .enforce_admins.enabled}'`
-- Update the blocker in `road-to-feedback-8.11-2` (resolved-when: this
-  command ran, or the user records why not).
-- Any future check rename: update the contexts list in the SAME PR that
-  renames the job — a required check that no longer reports blocks every
-  merge until an admin edits the list.

package/docs/maintainers/dev-mode.md

@@ -1,106 +0,0 @@
-# Maintainer Dev Mode (`AGENT_CONFIG_DEV_MODE=1`)
-
-**Audience.** Maintainers of `@event4u/agent-config` working **inside**
-the package repo. Consumers never see this flag; consumer installs
-land in `~/.event4u/agent-config/` per [ADR-020](../decisions/ADR-020-global-only-consumer-scope.md).
-
-**Status.** Forward-looking — the gate ships in Phase 3 of the
-`road-to-global-only-install` roadmap. This document is the
-canonical reference once Phase 3 lands.
-
-## Why the flag exists
-
-Phase 3 of `road-to-global-only-install` flips `SCOPE_SUPPORT` so that
-**every** consumer scope on `scripts/install.py` is global. The
-package repo itself is structurally identical to a consumer repo
-(same `.augment/`, `.claude/`, `.cursor/` projection layout) which
-means maintainer dev-installs would otherwise be blocked by the same
-gate.
-
-`AGENT_CONFIG_DEV_MODE=1` is the explicit, audit-visible opt-out.
-With the flag set, the installer:
-
-1. Allows project-scope writes back into the repo tree (so a
-   maintainer can run `task dev:install-global` and iterate on the
-   working copy).
-2. **Skips** consumer-surface writes into the package repo. (The
-   `agents/.event4u-bridge.yml` marker is retired — ADR-020 amendment
-   2026-07-13 — and no longer written at all.) The repo is the
-   source, not a consumer of itself.
-3. Treats `~/.event4u/agent-config/` as a peer install — touches are
-   limited to the working-copy projection.
-
-Without the flag, `scripts/install.py` refuses to write anywhere
-under the repo tree and points at this document.
-
-## When to set it
-
-Set the flag for these workflows, and **only** these:
-
-- `task dev:install-global` — refresh the user-scope projection from the working tree.
-- `task dev:install:gui` — iterate the unified Setup-Wizard / Installer-GUI before merge.
-- `task dev:setup` / `task dev:setup:dry-run` — exercise the onboarding wizard.
-- `task release` rehearsal — verify the published shape matches the dev shape.
-
-Do **not** set it for:
-
-- Consumer project work (the flag is undefined behaviour outside this repo).
-- CI runs on the package itself (CI uses the flag transparently via the dev tasks above; bare runs MUST NOT export it).
-- Production maintainer machines that also consume the package as a user (set per-shell, not in `~/.zshrc`).
-
-## How to set it
-
-Per-command (preferred):
-
-```bash
-AGENT_CONFIG_DEV_MODE=1 task dev:install-global
-```
-
-Per-shell session:
-
-```bash
-export AGENT_CONFIG_DEV_MODE=1
-task dev:install:gui
-unset AGENT_CONFIG_DEV_MODE
-```
-
-The `unset` discipline matters: a stale `=1` in your shell environment
-is the most common way a project-scope write sneaks into a consumer
-repo. Future work (`agent-config doctor`, Phase 5.4) will warn when
-the flag is set outside the package repo.
-
-## Safety properties
-
-- **Audit-visible.** Every install run logs whether the flag was set
-  at the top of the transaction log.
-- **No silent fallback.** If `scripts/install.py` detects the
-  package repo signature (presence of `.agent-src.uncondensed/` plus
-  `dist/router.json`) and the flag is **not** set, the install
-  refuses with a one-line error pointing here.
-- **Not for consumers.** Setting the flag in a consumer project is
-  defined as undefined behaviour. The installer will not actively
-  refuse (because it cannot distinguish a misconfigured shell from a
-  legitimate vendored maintainer install), but it will print a single
-  warning line on every run.
-
-## Interaction with the bridge marker
-
-Per [`consumer-bridge`](../contracts/consumer-bridge.md), the bridge
-marker is the in-repo pointer to the global root. Under
-`AGENT_CONFIG_DEV_MODE=1`:
-
-- The marker is **not** written into the package repo — the repo's
-  `agents/` directory is the project surface, not a consumer surface.
-- A pre-existing marker in the package repo is treated as stale and
-  removed on the next dev install (with an audit log line).
-- Consumer adapters reading the marker from inside the package repo
-  during local development should expand `global_root` against the
-  current user's `$HOME` per the reader contract — same as in a
-  consumer repo.
-
-## References
-
-- [ADR-020](../decisions/ADR-020-global-only-consumer-scope.md) — the global-only decision.
-- [`consumer-bridge`](../contracts/consumer-bridge.md) — bridge marker schema.
-- [`road-to-global-only-install`](../../agents/roadmaps/road-to-global-only-install.md) — Phase 3 SCOPE_SUPPORT flip + Phase 5 migration order.
-- [`taskfiles/dev.yml`](../../taskfiles/dev.yml) — `dev:install-global`, `dev:install:gui`, `dev:setup` task entries.

package/docs/maintainers/optional-media-deps.md

@@ -1,50 +0,0 @@
-# Optional media tooling (B8 recorded demos)
-
-The package ships **no bundled binaries** and never installs system tools
-silently (`missing-tool-handling`). A small set of tools is *optional* — needed
-only for the B8 recorded proof-page demos, not for day-to-day maintenance.
-Install them **on demand**, when the check tells you to.
-
-## The tools
-
-| Tool | What it does |
-|---|---|
-| `asciinema` | Records a terminal session to a compact `.cast` file (timestamped JSON of what was typed + printed). Replayable / embeddable — no backend, fits the no-runtime floor. |
-| `agg` | Converts a `.cast` → animated GIF (asciinema's gif generator), for embedding a short run on the proof page. |
-
-## When you need them
-
-- Only for **B8** — recording a real wedge / skill run for the proof page.
-- Once B8 lands, its falsifiability lock regenerates each recording **in CI from
-  a real run**, so the CI job (and any maintainer refreshing a demo) needs them.
-- Nothing else in the suite uses terminal recording — this is not a daily tool.
-
-## Check before recording (never a silent install)
-
-```bash
-task check-media-deps
-```
-
-It detects `asciinema` + `agg`, and if either is missing prints the exact
-platform install command and exits non-zero — the same detect-and-instruct
-shape as the docker check in `taskfiles/mcp.yml`. It never installs anything
-for you.
-
-## Install (only when the check asks)
-
-| Platform | Command |
-|---|---|
-| macOS | `brew install asciinema agg` |
-| Linux | `pipx install asciinema` · `cargo install --locked agg` (or a release binary) |
-| Other | see each tool's own install docs |
-
-## Why not auto-install with the maintainer package
-
-Three reasons the base setup does **not** pull these in:
-
-1. **The suite's own floor** (`missing-tool-handling`) forbids silent system-binary installs — detect + prompt only.
-2. **Cross-platform fragility + surface** — `asciinema` (brew / pipx) and `agg` (brew / cargo / release binary) install differently per OS; a config package that brings in system binaries on setup is invasive.
-3. **YAGNI** — a single, gated feature does not justify a base-setup dependency.
-
-The `check-media-deps` gate gives every maintainer the same on-demand path
-without any of the above — which is exactly what "install on demand" means here.

package/docs/maintainers/system-map.md

@@ -1,85 +0,0 @@
-# System map — how the whole thing fits together
-
-> One page, by design. This is a MAP, not a contract — where this page and a
-> linked contract disagree, the contract wins. It exists so a new maintainer
-> (or the same maintainer in six months) can orient without reading 121 ADRs.
-> Requested by both 8.11 external reviews ("a 'how the whole system fits
-> together' document that does not presuppose reading every contract").
-
-## The one chain that explains everything
-
-```
-src/                    ← the ONLY thing you edit
-  → condensation        (condense.sh; hashes in internal/.condensation-hashes.json)
-  → dist/agent-src/     (shipped projection — generated, read-only)
-  → host projection     (task generate-tools → .claude/ .cursor/ .clinerules/ …)
-  → installer           (npx @event4u/agent-config init → consumer's .augment/ etc.)
-  → consumer runtime    (host agent runs; hooks fire via the dispatcher)
-```
-
-Everything below either feeds this chain or checks it.
-
-## Subsystems, one paragraph each
-
-- **Rules + router** — `src/rules/*.md`, compiled into `dist/router.json`.
-  9 kernel rules load always; the rest route on trigger-sets. Heavy rule
-  bodies migrate to skills/guidelines (P4 pattern); inbound routes are
-  derivable per target (`internal/reports/rule-backlinks.md`). Contracts:
-  `docs/contracts/kernel-membership.md`, `docs/contracts/rule-router.md`.
-
-- **Skills / commands / personas** — the capability library
-  (`src/skills`, command domains under `src/domains`, personas). Counts are
-  generated and drift-gated (`CAPABILITIES.yaml`, count-messaging gate).
-  Catalog: `docs/catalog.md`.
-
-- **Knowledge + memory** — file-first, no DB. Per-card origin tier AND
-  sensitivity class (`prohibited/project/shareable`, ADR-121) gate what may
-  reach the global store (`~/.event4u/agent-config/knowledge/`); promotion
-  needs a human reason; deletion leaves tombstones. Design:
-  `agents/settings/contexts/knowledge-sensitivity.md`.
-
-- **Council** — external multi-model deliberation (no repo access),
-  debate/stance/chairman machinery complete and default-off; further
-  expansion is gated on the pre-registered council-vs-solo baseline
-  (`docs/design/council-vs-solo-baseline.md`). Config contract:
-  `docs/contracts/ai-council-config.md`.
-
-- **Subagents / orchestration** — in-session delegation with a form gate
-  before mode selection; implementer/judge separation; telemetry on the
-  audit JSONL. Team mode (cross-model builder/reviewer WITH repo access) is
-  the depth complement — `agents/roadmaps/road-to-team-mode.md`.
-
-- **Telemetry + measurement** — engagement records (id-only,
-  PII-excluded-by-construction, default-off; ON in this repo since
-  2026-07-12 with pre-registered decision criteria at
-  `docs/design/utilization-window-criteria.md`); orchestration audit lines;
-  bench harnesses with spend gates.
-
-- **Claims + proof** — every public claim binds to resolvable evidence:
-  `docs/CLAIMS.md` (source) → `docs/proof.md` (generated). Honest nulls are
-  published; pre-registration before data is the norm. Gate:
-  `check_claims`, `build_proof --check`.
-
-- **Introspection lenses (all report-only, all with kill criteria)** —
-  `complexity_report` (system-complexity soft ratchet vs checked-in
-  baseline), `explain_run` (why rules/skills/dispatches happened),
-  `rule_backlinks`. None fails a build; each dies if it informs no decision.
-
-- **CI gates** — `task ci` locally mirrors remote CI; remote CI is the
-  authoritative gate (`quality.local_auto_run: false` BY DESIGN — narrow
-  diff-scoped probes still run locally; new gates run once locally). The
-  consumer matrix installs the real package and fires real hook lifecycle
-  events. Branch protection: `docs/maintainers/branch-protection.md`.
-
-## Where to change what (the 10-second router)
-
-| You want to… | Edit… | Never touch… |
-|---|---|---|
-| Change agent behavior | `src/rules` / `src/skills` / `src/domains` | `dist/`, `.claude/`, `.cursor/` (generated) |
-| Change what ships | `src/config/packs.yml`, profiles | consumer trees |
-| Change counts/claims/proof | `docs/CLAIMS.md` + regenerate | `docs/proof.md` directly |
-| Change install/hooks | `src/install`, `src/scripts/_lib/claude_settings_hooks.ts` | consumer settings by hand |
-| Record a decision | `docs/decisions/ADR-*` via adr-create | roadmaps as decision storage |
-
-Deeper operating material (release runbook, succession, incident playbooks)
-is owned by `road-to-maintainer-bus-factor` — this page stays the map.

package/docs/mcp-registries.md

@@ -1,94 +0,0 @@
-# MCP registries & cross-tool install landscape
-
-> Reference material. Where to *discover* MCP servers, what each registry gives
-> you, and how to install one into each agent today — without our own tooling.
->
-> Background: we evaluated building a read-only cross-agent MCP discovery helper
-> (`ADR-086`) and decided **not to** — existing tooling already covers it. This
-> doc captures the surviving value: the registry comparison and the per-agent
-> manual install path. See [`docs/mcp.md`](mcp.md) for generating *your own*
-> `mcp.json` across tools.
-
-## The three registries (verified 2026-06-11)
-
-| Dimension | Official registry | Glama | Smithery |
-|---|---|---|---|
-| Role | Vendor-neutral **catalog** (discovery spec) | Catalog **superset** + quality/safety scoring | Catalog **+ installer** |
-| Canonical shape | `server.json` | Own schema (maps to `server.json` fields) | Own schema |
-| Approx. scale | Hundreds+ (paginated, growing) | ~32k servers | Own index |
-| Writes client config? | **No** (discovery only) | **No** (discovery only) | **Yes** — `smithery install X --client <c>` |
-| API auth | **None** — public read | **None** — public read | n/a (CLI) |
-| Query endpoint | `GET registry.modelcontextprotocol.io/v0/servers?search=&limit=&cursor=` | `GET glama.ai/api/mcp/v1/servers?first=&after=` | `smithery` CLI / site |
-
-Both catalog APIs were live-checked: each returns `200` with **no API key**. The
-official registry returns `{servers:[{server:<server.json>,_meta:…}],metadata:{nextCursor,count}}`;
-Glama returns `{pageInfo:{endCursor,hasNextPage},servers:[{id,name,namespace,slug,
-description,environmentVariablesJsonSchema,repository,spdxLicense,tools,url}]}`.
-
-> Glama's quality/safety **score is a popularity/heuristic signal, not a verified
-> security property** — treat it as a hint, never a guarantee.
-
-## Installing a discovered server per agent
-
-For most agents, **Smithery already writes the config for you** (the read-write
-path — harder than discovery). Its CLI (`smithery-ai/cli`, `src/config/clients.ts`
-`VALID_CLIENTS`, verified 2026-06-11) configures 23 clients, including:
-
-`smithery install <server> --client <client>` where `<client>` ∈ **claude** (Desktop),
-**claude-code**, **cursor**, **windsurf**, **cline**, **vscode** / **vscode-insiders**
-(Copilot), plus codex, gemini-cli, zed, goose, kiro, trae, and others.
-
-That covers Claude Code, Cursor, Windsurf, Cline, and VS Code/Copilot. **Augment is
-the gap** — it is not in Smithery's client list, so install it manually (below).
-
-## Augment — manual MCP install (no tooling needed)
-
-Augment supports the **standard `mcpServers` object map** via its built-in
-**Import from JSON** (Augment Settings Panel → gear icon → Import from JSON).
-Paste, for a stdio server:
-
-```json
-{
-  "mcpServers": {
-    "<server-name>": {
-      "command": "npx",
-      "args": ["-y", "<package>"]
-    }
-  }
-}
-```
-
-…or for a remote server:
-
-```json
-{
-  "mcpServers": {
-    "<server-name>": {
-      "url": "https://example.com/mcp",
-      "type": "sse"
-    }
-  }
-}
-```
-
-Secret env vars get their own section in the Settings Panel — paste placeholders,
-fill in the real value there; never commit a real secret. Augment also offers
-**Easy MCP** (one-click) for common servers, and the JetBrains plugin manages MCP
-through its own settings UI.
-
-> Why no automated Augment writer? Augment's only file-writable surface is VS Code
-> `settings.json` under the nested key `augment.advanced.mcpServers` (an array of
-> `{name, command, args}`), which the official docs do not commit to as a stable
-> contract. Smithery's writer targets flat, dedicated config files, so it cannot
-> safely write Augment's nested/shared surface. Manual Import-from-JSON is the
-> supported path today.
-
-## Reopen criteria — automated Augment install
-
-Reconsidered (e.g. native Smithery support or our own writer) only if **all** hold:
-
-1. ≥ 3 users independently request automated Smithery → Augment install.
-2. Augment documents the `settings.json` MCP schema as a **stable** contract.
-3. The Smithery maintainers pre-approve the integration approach.
-
-Until then this stays manual by design (`ADR-086`, AI-council convergence 2026-06-11).

package/docs/mcp-server.md

@@ -1,175 +0,0 @@
-# MCP Server
-
-> Status: **experimental** — read-only prompts + resources plus a growing `tools/*` surface (stub-by-default: every catalogued tool name resolves, unimplemented ones return a structured `not_implemented` envelope). Tool coverage and the write/exec unlock path are governed by [`agents/settings/contexts/mcp-coverage-strategy.md`](../agents/settings/contexts/mcp-coverage-strategy.md). Promotion to **beta** is gated on the six criteria in [`docs/contracts/mcp-beta-criteria.md`](contracts/mcp-beta-criteria.md); current gate status: `./agent-config doctor --check mcp-beta-readiness`.
-
-`agent-config` ships a built-in [Model Context Protocol](https://modelcontextprotocol.io)
-server that exposes the package's read-only governance surface to MCP-aware
-clients (Claude Desktop, Cursor, Zed, Continue, Codex via MCP). Three channels
-coexist:
-
-- **File projection** — `task generate-tools` writes `.claude/`, `.cursor/`,
-  `.clinerules/`, `.windsurfrules`. Used by Aider, Cline, Windsurf, Gemini CLI.
-- **Local stdio MCP server** — `scripts/mcp_server/` exposes the same content
-  over JSON-RPC. Used by clients that speak MCP natively. Default for personal
-  installs.
-- **Remote MCP** *(experimental, opt-in)* — a Cloudflare-hosted TypeScript
-  Worker (`internal/workers/mcp/`) serves the same wire surface over HTTP/SSE for
-  hosted-agent platforms. URL shapes pinned in
-  [`docs/setup/mcp-cloud-endpoints.md`](setup/mcp-cloud-endpoints.md);
-  safety contract in
-  [`docs/contracts/mcp-cloud-scope.md`](contracts/mcp-cloud-scope.md).
-  Wire-parity-checked against the local stdio kernel on every release.
-
-Every implemented tool is either read-only or writes only inside the
-consumer's project tree via a path-guard (`_validateInTreePath`) —
-[`docs/contracts/mcp-phase-1-scope.md`](contracts/mcp-phase-1-scope.md)
-is the scope contract; exec-tier tools (shell-spawning) and network-tier
-tools (billable) are gated behind
-[`agents/settings/contexts/mcp-coverage-strategy.md`](../agents/settings/contexts/mcp-coverage-strategy.md).
-
-## What the server exposes
-
-| Primitive | URIs | Source |
-|---|---|---|
-| `prompts/list` + `prompts/get` | `skill.<name>`, `command.<name>` | `dist/agent-src/skills/`, `dist/agent-src/commands/` |
-| `resources/list` + `resources/read` | `rule://<stem>` | `dist/agent-src/rules/` |
-| ↳ | `guideline://<relpath>` | `docs/guidelines/` |
-| ↳ | `context://<relpath>` | `dist/agent-src/contexts/` |
-| `tools/list` + `tools/call` | see [`agents/settings/contexts/mcp-tool-tier-map.md`](../agents/settings/contexts/mcp-tool-tier-map.md) for the full candidate surface | `src/scripts/mcp_server/consumer_tool_catalog.json` |
-
-All resources are served with `mimeType: text/markdown`. Pagination is
-cursor-based (default page size: 100). Hot-reload triggers automatically on
-file mtime changes — edit a rule, reissue `resources/list`, see the update.
-Exact prompt/resource/tool counts drift with every content change — the smoke
-test below reports the live numbers rather than a number pinned in prose.
-_Last verified boot (`task mcp:glama-test`, 2026-07-07): 430 prompts / 232
-resources / 27 tools (18 implemented, 9 stubs — post write/exec cut)._
-
-## Setup — one-line install
-
-```bash
-task mcp:setup            # maintainer / dev repo
-./agent-config mcp:setup  # consumer projects (uses the package CLI wrapper)
-```
-
-Either form verifies that `tsx` + the server module are present and
-prints the client config snippet. Run once per checkout.
-
-If you do not have `task` or the CLI wrapper available:
-
-```bash
-bash scripts/mcp_setup.sh
-```
-
-## Running the server
-
-```bash
-task mcp:run            # maintainer / dev repo
-./agent-config mcp:run  # consumer projects
-```
-
-Both forms launch the TypeScript MCP server over stdio via `tsx`. Use these
-for a manual smoke test — MCP clients (Claude Desktop, Cursor, Zed, Continue)
-launch the server themselves via the config snippets below.
-
-## Client configuration
-
-### Claude Desktop
-
-Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
-or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
-
-```json
-{
-  "mcpServers": {
-    "agent-config": {
-      "command": "/absolute/path/to/agent-config/node_modules/.bin/tsx",
-      "args": ["/absolute/path/to/agent-config/src/scripts/mcp_server/__main__.ts"],
-      "cwd": "/absolute/path/to/agent-config"
-    }
-  }
-}
-```
-
-Restart Claude Desktop. The skills, commands, rules, guidelines, and contexts
-appear under the connector dropdown.
-
-### Cursor
-
-`~/.cursor/mcp.json` (or `<repo>/.cursor/mcp.json`):
-
-```json
-{
-  "mcpServers": {
-    "agent-config": {
-      "command": "/absolute/path/to/agent-config/node_modules/.bin/tsx",
-      "args": ["/absolute/path/to/agent-config/src/scripts/mcp_server/__main__.ts"],
-      "cwd": "/absolute/path/to/agent-config"
-    }
-  }
-}
-```
-
-### Zed
-
-`~/.config/zed/settings.json`:
-
-```json
-{
-  "context_servers": {
-    "agent-config": {
-      "command": {
-        "path": "/absolute/path/to/agent-config/node_modules/.bin/tsx",
-        "args": ["/absolute/path/to/agent-config/src/scripts/mcp_server/__main__.ts"]
-      },
-      "settings": {}
-    }
-  }
-}
-```
-
-### Continue (`continue.dev`)
-
-`~/.continue/config.yaml`:
-
-```yaml
-mcpServers:
-  - name: agent-config
-    command: /absolute/path/to/agent-config/node_modules/.bin/tsx
-    args: [/absolute/path/to/agent-config/src/scripts/mcp_server/__main__.ts]
-    cwd: /absolute/path/to/agent-config
-```
-
-## Smoke test
-
-After configuring a client, run a manual stdio handshake to verify the server
-boots cleanly:
-
-```bash
-./agent-config mcp:run < /dev/null
-# Expect stderr: "mcp-server: loaded N prompts (0 warnings)",
-#                "mcp-server: loaded N resources (0 warnings)", and
-#                "mcp-server: registered N tools (N implemented, N stubs): [...]"
-```
-
-## Troubleshooting
-
-| Symptom | Fix |
-|---|---|
-| Client shows no prompts | Confirm the `cwd` points at the repo root (where `dist/agent-src/` lives), not at `scripts/`. |
-| Stale prompts after editing | Hot-reload triggers on mtime; touch the file or reissue `resources/list`. |
-| Client refuses to start the server | Check the client's log for the full command. Most clients require **absolute** paths in `command` and `cwd`. |
-
-## Scope
-
-- **In scope:** read-only prompts + resources, pagination, hot-reload, stdio
-  transport, free-tier client compatibility, a growing read-only and
-  in-tree-write `tools/*` surface (see
-  [`agents/settings/contexts/mcp-tool-tier-map.md`](../agents/settings/contexts/mcp-tool-tier-map.md)).
-- **Out of scope:** SSE / native HTTP transport for this server (the
-  Cloudflare Worker above is the HTTP bridge instead), shell-exec and
-  network-tier tools until the safety envelope in
-  [`agents/settings/contexts/mcp-coverage-strategy.md`](../agents/settings/contexts/mcp-coverage-strategy.md)
-  ships, signed payloads.
-
-← [Architecture](architecture.md) · [MCP config generation (consumer side)](mcp.md)