@event4u/agent-config 1.36.1 → 1.38.0

package/docs/mcp-server.md

@@ -0,0 +1,164 @@
+# MCP Server
+
+> Status: **experimental** — Phase 1 + 2 + 3 shipped. No `tools/*` primitive yet (Phase 4, deferred behind a design call).
+
+`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 (`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.
+
+The MCP server **never executes engine code, never writes files, never spawns
+shells**. It is a read-only instructional surface — see
+[`docs/contracts/mcp-phase-1-scope.md`](contracts/mcp-phase-1-scope.md).
+
+## What the server exposes
+
+| Primitive | URIs | Source | Count (this package) |
+|---|---|---|---|
+| `prompts/list` + `prompts/get` | `skill.<name>`, `command.<name>` | `.agent-src/skills/`, `.agent-src/commands/` | 174 skills + 104 commands |
+| `resources/list` + `resources/read` | `rule://<stem>` | `.agent-src/rules/` | 60 rules |
+| ↳ | `guideline://<relpath>` | `docs/guidelines/` | 69 guidelines |
+| ↳ | `context://<relpath>` | `.agent-src/contexts/` | 31 contexts |
+
+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.
+
+## Setup — one-line install
+
+```bash
+task mcp:setup            # maintainer / dev repo
+./agent-config mcp:setup  # consumer projects (uses the package CLI wrapper)
+```
+
+Either form creates `.venv-mcp/` (Python 3.11+), installs the `mcp` SDK, 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 `python -m scripts.mcp_server` over stdio against the
+local `.venv-mcp/`. Use these for ad-hoc smoke tests; long-running 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/.venv-mcp/bin/python",
+      "args": ["-m", "scripts.mcp_server"],
+      "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/.venv-mcp/bin/python",
+      "args": ["-m", "scripts.mcp_server"],
+      "cwd": "/absolute/path/to/agent-config"
+    }
+  }
+}
+```
+
+### Zed
+
+`~/.config/zed/settings.json`:
+
+```json
+{
+  "context_servers": {
+    "agent-config": {
+      "command": {
+        "path": "/absolute/path/to/agent-config/.venv-mcp/bin/python",
+        "args": ["-m", "scripts.mcp_server"]
+      },
+      "settings": {}
+    }
+  }
+}
+```
+
+### Continue (`continue.dev`)
+
+`~/.continue/config.yaml`:
+
+```yaml
+mcpServers:
+  - name: agent-config
+    command: /absolute/path/to/agent-config/.venv-mcp/bin/python
+    args: ["-m", "scripts.mcp_server"]
+    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)" and
+#                "mcp-server: loaded 160 resources (0 warnings)"
+```
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Client shows no prompts | Confirm the `cwd` points at the repo root (where `.agent-src/` lives), not at `scripts/`. |
+| `ModuleNotFoundError: mcp` | Re-run `task mcp:setup`. The MCP runtime is isolated in `.venv-mcp/` — the project's base Python 3.9 deliberately does not see it. |
+| 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.
+- **Out of scope (Phase 4+):** `tools/*` primitive, SSE / HTTP transport,
+  cloud distribution, signed payloads. Tracked in
+  [`agents/roadmaps/road-to-mcp-server.md`](../agents/roadmaps/road-to-mcp-server.md).
+
+← [Architecture](architecture.md) · [MCP config generation (consumer side)](mcp.md)

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

@@ -0,0 +1,93 @@
+# MCP Cloud Endpoints — URL shapes & DNS
+
+Public URL shapes for the hosted `agent-config-mcp` Worker. Governed
+by `docs/contracts/mcp-cloud-scope.md` (A0-cloud) and Phase 5.2 of
+`agents/roadmaps/road-to-cloudflare-mcp-hosting.md`.
+
+## Stability
+
+**Experimental.** Inherits the label from `mcp-phase-1-scope.md`. URL
+shapes below are pinned for the lifetime of the *experimental* window;
+breaking changes require a stability-label bump.
+
+## URL shapes (pinned)
+
+Two surfaces, both serve identical wire contracts (JSON-RPC over POST,
+SSE on GET — A0-cloud invariant 1):
+
+| Shape | Resolves to | Use case |
+|---|---|---|
+| `https://mcp.<domain>/latest/sse` | the release currently pointed at by `releases/latest.txt` in R2 | client wants the rolling cutting-edge build |
+| `https://mcp.<domain>/v<X.Y.Z>/sse` | the immutable release `<X.Y.Z>` from the R2 archive | client wants a pinned, reproducible build |
+
+The `<domain>` placeholder is operator-configured; the package itself
+does not own DNS. Pin the chosen domain in your fork's
+`mcp-cloud-scope.md` § Bucket / DNS.
+
+For JSON-RPC, drop the `/sse` suffix:
+
+| JSON-RPC | SSE |
+|---|---|
+| `POST https://mcp.<domain>/latest` | `GET  https://mcp.<domain>/latest/sse` |
+| `POST https://mcp.<domain>/v1.37.0` | `GET  https://mcp.<domain>/v1.37.0/sse` |
+
+The Worker reads its bundled blob at module init (per A0-cloud
+invariant 2); the path prefix in MVP-1 is a routing artefact, not a
+content selector. Multi-version routing lands in MVP-2.
+
+## DNS setup (operator-side)
+
+One-time, requires Cloudflare account + zone access:
+
+```sh
+# 1. Add the Worker custom domain in Cloudflare dashboard:
+#    Workers & Pages → agent-config-mcp → Settings → Domains & Routes
+#    → Add Custom Domain → "mcp.<your-domain>"
+#
+# 2. Cloudflare creates the AAAA + A records automatically. No manual
+#    CNAME — Custom Domains is the supported path (not "Routes").
+#
+# 3. Verify:
+curl -s -X POST https://mcp.<your-domain>/ \
+  -H "content-type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"ping","params":{}}'
+```
+
+After DNS is live, uncomment the `routes` block in
+`workers/mcp/wrangler.toml` and redeploy via `wrangler deploy` (or let
+the GitHub Action pick it up on the next release).
+
+The fallback `*.workers.dev` URL stays live for free; the custom
+domain is only the public stability promise.
+
+## Health probe
+
+Every URL accepts `GET /` with no body and returns release identity:
+
+```json
+{
+  "ok": true,
+  "name": "agent-config-mcp",
+  "release_key": "v1.37.0-2fc5084",
+  "package_version": "1.37.0",
+  "signature": "35bc3c5e8b83",
+  "schema_version": 1
+}
+```
+
+The `signature` field is the wire-surface `skillSetSignature` — same
+hash that MCP clients see under `_meta.skillSetSignature` on the
+identity surface.
+
+## Parity smoke
+
+Post-deploy CI runs `scripts/mcp_parity_smoke.py` against the new
+deployment with `--target https://mcp.<domain>`. A non-zero exit
+aborts the `latest.txt` repoint, so the previous release keeps
+serving on `/latest/`.
+
+## See also
+
+- A0-cloud contract: `docs/contracts/mcp-cloud-scope.md`
+- R2 bootstrap: `docs/setup/mcp-r2-bootstrap.md`
+- Local stdio fallback: `scripts/mcp_server/` (unchanged)

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

@@ -0,0 +1,99 @@
+# 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

@@ -0,0 +1,152 @@
+# 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
+# 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 `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 — 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: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
+- [`workers/mcp/README.md`](../../workers/mcp/README.md) — Worker source overview

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

@@ -0,0 +1,82 @@
+# 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      # uncompressed 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 `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

@@ -0,0 +1,97 @@
+# MCP server — Docker (stdio bundle)
+
+Phase-6 F3 ships `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 `docker/mcp-server/` — the
+`COPY` lines reference paths relative to the project root.
+
+```bash
+docker build -f 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 278 prompts (0 warnings)
+mcp-server: loaded 160 resources (0 warnings)
+mcp-server: registered 2 tools: ['chat_history_append', 'lint_skills']
+mcp-server: identity serverVersion=0.1.0 packageVersion=1.36.1 skillSetSignature=<12-hex>
+```
+
+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/.agent-chat-history` **inside the container**. For writes to
+survive container lifecycle, mount the host directory:
+
+```bash
+docker run --rm -i \
+  -v "$(pwd)/agents/.agent-chat-history:/app/agents/.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 `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
+`.agent-src/` content. Expect ~150-200 MB; the builder stage is
+discarded.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "1.36.1",
+    "version": "1.38.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,