@event4u/agent-config 1.37.0 → 1.38.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Shared agent configuration \u2014 skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI).",
-    "version": "1.37.0"
+    "version": "1.38.0"
   },
   "plugins": [
     {

package/CHANGELOG.md

@@ -318,6 +318,36 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [1.38.0](https://github.com/event4u-app/agent-config/compare/1.37.0...1.38.0) (2026-05-11)
+
+### Features
+
+* **mcp:** add cloud setup tasks + operator README ([c5aebba](https://github.com/event4u-app/agent-config/commit/c5aebba37a608d0a41b1586acacdb055996a961d))
+* **scripts:** MCP content packer + cloud parity smoke ([e0d132a](https://github.com/event4u-app/agent-config/commit/e0d132afb487b720386bd54b68e10f1a342d6b0c))
+
+### Documentation
+
+* **readme:** surface hosted Remote MCP as zero-install option ([de6161e](https://github.com/event4u-app/agent-config/commit/de6161e3660b81a460f057bc46c1b75e6fe8693c))
+* **mcp:** add A0-cloud invariant 8 — ingress protection via edge cache + platform rate-limit ([c4b9371](https://github.com/event4u-app/agent-config/commit/c4b9371da2db55958bca29a7d10291626d13782f))
+* **mcp:** drop archived-roadmap refs from stable contracts ([15418de](https://github.com/event4u-app/agent-config/commit/15418de5a65c3cd5968bbeecc20ed5ad5c4a4958))
+* **mcp:** surface experimental hosted-MCP channel ([cecae08](https://github.com/event4u-app/agent-config/commit/cecae08ad647c7e28931e7328047fdef5ca3d3a3))
+* **setup:** MCP cloud endpoints, R2 bootstrap, registry listing ([7cb3341](https://github.com/event4u-app/agent-config/commit/7cb334110ff940d3703ada013ef5163c899d96b2))
+* **mcp:** add A0-cloud contract + cross-links (Phase 1 of cloudflare-mcp-hosting) ([2fc5084](https://github.com/event4u-app/agent-config/commit/2fc50845c3b194e861b54f82c852ba4bb9fc406a))
+* **roadmap:** add Cloudflare-hosted MCP roadmap, archive distribution ([fd1c437](https://github.com/event4u-app/agent-config/commit/fd1c437ea8a918eebc8604ee7958d8c842c7aac8))
+
+### CI
+
+* **deploy-mcp-worker:** release-tag triggered Worker deploy ([4297514](https://github.com/event4u-app/agent-config/commit/4297514b80457852511ad90674f4d633a75a92bf))
+
+### Chores
+
+* **linter:** raise README overloaded threshold to 750 lines ([1e3fbb7](https://github.com/event4u-app/agent-config/commit/1e3fbb7c649398ba56bc32677c7b588131f7e949))
+* **mcp:** mark dev content.json stub with explanatory _comment ([8f6c7ff](https://github.com/event4u-app/agent-config/commit/8f6c7ffe493b72ccb2d0ec66121a9d32d0b2fe8c))
+* **roadmap:** archive road-to-cloudflare-mcp-hosting (100% complete) ([99e07f9](https://github.com/event4u-app/agent-config/commit/99e07f92293e62841ff87f315e41c5ceabd7b277))
+* **workers/mcp:** scaffold TypeScript Cloudflare Worker ([447e071](https://github.com/event4u-app/agent-config/commit/447e071984f86fc084058d05f22d0e0a7c936a5e))
+
+Tests: 2679 (+0 since 1.37.0)
+
 ## [1.37.0](https://github.com/event4u-app/agent-config/compare/1.36.1...1.37.0) (2026-05-10)
 
 ### Features

package/README.md

@@ -90,6 +90,30 @@ Install directly in your agent for global, cross-project use:
 → [Full getting started guide](docs/getting-started.md) ·
 [More examples & expected behavior](docs/showcase.md)
 
+### Remote MCP — zero install
+
+Skills, commands, rules, and guidelines are also served as a hosted MCP
+endpoint. No clone, no `task mcp:setup`, no Python venv — point any
+MCP-capable client (Claude Desktop, Cursor, Zed, Continue, hosted agents)
+at:
+
+```
+https://agent-config-mcp.event4u.workers.dev
+```
+
+Verify it's live:
+
+```bash
+curl https://agent-config-mcp.event4u.workers.dev
+# → { "ok": true, "name": "agent-config-mcp", "release_key": "v…", … }
+```
+
+Read-only, identity-stable per release. Client config snippets and URL
+shapes (latest vs. pinned `/v<X.Y.Z>`) live in
+[`docs/setup/mcp-cloud-endpoints.md`](docs/setup/mcp-cloud-endpoints.md).
+Operator setup (account, R2, secrets) — [`docs/setup/mcp-cloud-setup.md`](docs/setup/mcp-cloud-setup.md).
+Experimental — A0-cloud contract in [`docs/contracts/mcp-cloud-scope.md`](docs/contracts/mcp-cloud-scope.md).
+
 ### Optional: persistent agent memory
 
 `agent-config` integrates with [`@event4u/agent-memory`](https://www.npmjs.com/package/@event4u/agent-memory)
@@ -109,7 +133,7 @@ Install in the same project (dev-only):
 npm install --save-dev @event4u/agent-memory
 ```
 
-→ [Memory contract & retrieval API](docs/contracts/agent-memory-contract.md) (beta) · [Built-in MCP server](docs/mcp-server.md) (experimental — read-only access from Claude Desktop / Cursor / Zed / Continue, install with `task mcp:setup`)
+→ [Memory contract & retrieval API](docs/contracts/agent-memory-contract.md) (beta) · [Built-in MCP server](docs/mcp-server.md) (experimental — local stdio access from Claude Desktop / Cursor / Zed / Continue, install with `task mcp:setup`)
 
 ---
 

package/docs/contracts/mcp-cloud-scope.md

@@ -0,0 +1,182 @@
+---
+stability: experimental
+---
+
+# MCP Server — Cloud Scope (A0-cloud Hard Contract)
+
+> **Status:** Active · covers `workers/mcp/` (TypeScript Cloudflare
+> Worker bridge), MVP-1 surface. Extends — does **not** supersede —
+> [`mcp-phase-1-scope.md`](mcp-phase-1-scope.md), which retains
+> exclusive ownership of `scripts/mcp_server/` (local stdio).
+> **Stability:** experimental — not linked from README, AGENTS.md, or
+> `docs/architecture.md`. Internal index reference only per `STABILITY.md`.
+
+## Purpose
+
+Locks the **execution-safety boundary** for the hosted MCP Worker. Any
+code under `workers/mcp/` must satisfy this contract verbatim. The
+local stdio kernel and the hosted Worker are two distinct surfaces; a
+deviation in one is **not** authorized by a precedent in the other.
+
+The Worker IS the bridge described in
+[`mcp-request-signing § Appendix`](../guidelines/agent-infra/mcp-request-signing.md#appendix--http-bridge-stdio-kernel-pattern-reference)
+— but with two material differences from the appendix pattern: (1) no
+spawned stdio child (content is read from a release-pinned R2 blob,
+not a sub-process), and (2) no HMAC for MVP-1 (content is OSS and
+read-only; the appendix pattern's `verifyRequest` is deferred to MVP-2
+alongside auth).
+
+## In-scope (MVP-1)
+
+- **Transport:** HTTP + SSE (Cloudflare Worker `fetch` handler). The
+  local stdio kernel is out-of-scope for this contract and stays
+  governed by `mcp-phase-1-scope.md`.
+- **MCP primitives:** `prompts/list` + `prompts/get` + `resources/list`
+  + `resources/read` — read-only, parity with the local stdio surface.
+- **Source data:** release-pinned content blob in R2 under the key
+  shape `releases/v<X.Y.Z>-<sha>/` (immutable per release). The blob
+  bundles `.agent-src/skills/<name>/SKILL.md`,
+  `.agent-src/commands/**/*.md`, and `docs/guidelines/` (the same
+  projection the local kernel reads). Never reads `.agent-src.uncompressed/`.
+- **Identity surface:** `serverInfo.version` reads from a Worker-
+  bundled constant, `_meta.packageVersion` reads from a
+  `wrangler.toml` env var, `_meta.skillSetSignature` reads from a
+  **prebaked manifest JSON** shipped with the content blob. The
+  Worker never computes the signature at runtime.
+- **URL shape:** two pinned shapes only —
+  `mcp.<host>/v<X.Y.Z>/sse` (immutable, cache TTL 1 h) and
+  `mcp.<host>/latest/sse` (pointer, cache TTL 5 min). The `latest`
+  pointer is repointed atomically by the release pipeline after a
+  green smoke run; pre-smoke failures leave it on the previous
+  release.
+- **Pagination + hot-reload parity:** `prompts/list` paginates with
+  `nextCursor` the same way the stdio kernel does; the Worker has no
+  hot-reload because the content blob is immutable per release —
+  the **release** is the cache-bust event.
+- **Deprecated tool stubs:** `tools/list` returns exactly two entries,
+  `lint_skills` and `chat_history_append`, both with
+  `deprecated: true` and a description pointing to the local stdio
+  server. `tools/call` against either returns `isError=true` with a
+  message naming the local-stdio successor. No other tool name is
+  reachable.
+
+## Out-of-scope (MVP-1)
+
+- **Tool execution.** `lint_skills` and `chat_history_append` are
+  exposed as deprecated stubs only — no TS port, no FS access, no
+  shell, no Python runtime in the Worker. Restoration is the
+  Phase-7-DEFERRED block of the roadmap, gated on a real consumer ask
+  plus a multi-tenant security review.
+- **`.agent-settings.yml` exposure.** Consumer-machine config, never
+  surfaced as a resource. The Worker has no access to consumer FS at
+  any layer.
+- **Agent memory** — separate MCP server, different roadmap.
+- **Chat history persistence** — the local kernel writes to
+  `agents/.agent-chat-history`; the Worker has no equivalent. Listed
+  as a deprecated stub per above.
+- **Authentication / multi-tenancy.** MVP-1 is open (OSS content,
+  read-only). Bearer / CF Access / HMAC moves to MVP-2 alongside
+  tool restoration.
+- **Network egress from the Worker** beyond an **explicit subrequest
+  allowlist** — see invariants below.
+
+## A0-cloud invariants
+
+The Worker code must satisfy all of:
+
+1. **Origin allowlist** — `fetch()` calls from the Worker are limited
+   to R2 (content read) and an explicit observability sink (optional).
+   No calls to consumer infrastructure, no calls to upstream LLM
+   APIs, no calls to `api.github.com`, no DNS-based egress. Enforced
+   in `wrangler.toml` via Worker-level network policies.
+2. **R2 write boundary** — the Worker never writes to R2. The release
+   pipeline writes under `releases/v<X.Y.Z>-<sha>/` and atomically
+   repoints `releases/latest.txt`; the Worker only reads.
+3. **Per-versioned-URL immutability** — for any
+   `mcp.<host>/v<X.Y.Z>/sse`, the response body is deterministic for
+   the lifetime of the deployment. Patch fixes ship a new version key;
+   the existing key is never rewritten. R2 eventual consistency is
+   handled by the unique-key-per-release shape.
+4. **Cache-TTL policy** — pinned URLs cache at the edge for 1 h
+   (safe because immutable); `latest` caches for 5 min (bounded
+   staleness window after a repoint). No client may rely on `latest`
+   for reproducibility — that is what the pinned URL is for.
+5. **Prebaked signature** — `skillSetSignature` is computed once by
+   the release pipeline against the worktree at the tag and stored in
+   `releases/v<X.Y.Z>-<sha>/manifest.json`. The Worker reads, never
+   computes. Any signature drift at runtime is a contract violation.
+6. **No consumer code execution.** No `eval`, no dynamic import of
+   content, no shelling out, no spawning a runtime. The Worker is a
+   read-and-route function.
+7. **Single deployment per release.** One `wrangler deploy` per tag.
+   Concurrent deployments are not supported; the release pipeline
+   serializes through `release: published` + `workflow_dispatch`
+   hotfix paths.
+8. **Ingress protection = edge cache + platform rate limit.** MVP-1
+   is auth-less by design; the public surface is shielded by two
+   layers Cloudflare provides without code: (a) edge caching per
+   invariant 4 (1 h on pinned URLs, 5 min on `latest`) absorbs
+   read-loop traffic before it reaches the Worker, and (b)
+   Cloudflare's account-level anti-abuse + DDoS shielding caps
+   per-IP burst on `*.workers.dev`. These two together **are** the
+   MVP-1 auth surrogate. **Promotion triggers** — any of these
+   flips HMAC (currently MVP-2 §Out-of-scope) from deferred to
+   active before the wake-up triggers below would otherwise fire:
+   sustained 429 spikes from origin (cache miss storm), Workers
+   request-cost line item exceeding the free-tier budget for two
+   consecutive billing periods, or a CVE-class abuse report
+   against the endpoint. A per-Worker `[[unsafe.bindings]]`
+   rate-limiter in `wrangler.toml` is **not** configured in MVP-1
+   — adding one is a contract amendment, not a free hand.
+
+## Deprecated tool stub contract
+
+`tools/list` returns:
+
+```json
+[
+  {
+    "name": "lint_skills",
+    "description": "Deprecated on hosted MCP — use the local stdio server (scripts/mcp_server/) which retains this tool. See road-to-cloudflare-mcp-hosting Phase 7 for restoration triggers.",
+    "deprecated": true
+  },
+  {
+    "name": "chat_history_append",
+    "description": "Deprecated on hosted MCP — filesystem-bound, local-only. Use the local stdio server.",
+    "deprecated": true
+  }
+]
+```
+
+`tools/call` against either name returns `isError=true` with the same
+deprecation message. No other tool name is reachable.
+
+## MVP-2 wake-up triggers
+
+The Phase-7 deferred items in the roadmap (tool restoration, history
+persistence, auth) wake up only when **all** of these fire:
+
+- A named consumer (internal or external) requests hosted lint or
+  history.
+- A security review has approved the validation layer for
+  `lint_skills` (URI regex allowlist, size limits, timeout,
+  concurrency cap).
+- An auth model has been selected (bearer vs. CF Access vs. HMAC).
+- The server stability label has been promoted from *experimental*
+  to *beta*.
+
+## Revision policy
+
+This contract is **experimental** — breaking changes are allowed in
+any release with a CHANGELOG note. Promotion to `beta` requires at
+least one shipped client connecting to the hosted endpoint end-to-end
+without a contract amendment.
+
+## See also
+
+- [`mcp-phase-1-scope.md`](mcp-phase-1-scope.md) — local-stdio kernel
+  contract (sibling, not parent).
+- [`STABILITY.md`](../../STABILITY.md) — stability policy for
+  `docs/contracts/`.
+- [`mcp-request-signing § Appendix`](../guidelines/agent-infra/mcp-request-signing.md#appendix--http-bridge-stdio-kernel-pattern-reference)
+  — bridge pattern reference (the Worker is a flavor of this).

package/docs/contracts/mcp-phase-1-scope.md

@@ -6,9 +6,10 @@ stability: experimental
 
 > **Status:** Active · covers Phase 1 (A1–A7) + Phase 2 (B1–B5) +
 > Phase 3 (C1–C4) + Phase 4 (D1–D4) + Phase 6 F1/F3 of
-> `road-to-mcp-server.md`. Phase 6 F2 (SSE transport) is deferred to
-> [`road-to-mcp-distribution.md`](../../agents/roadmaps/road-to-mcp-distribution.md)
-> and remains out of scope here.
+> `road-to-mcp-server.md`. Phase 6 F2 (SSE transport) is owned by
+> [`mcp-cloud-scope.md`](mcp-cloud-scope.md) — the hosted Cloudflare
+> Worker bridge — and remains out of scope here. This contract retains
+> exclusive ownership of `scripts/mcp_server/` (local stdio).
 > **Stability:** experimental — not linked from README, AGENTS.md, or
 > `docs/architecture.md`. Internal index reference only per `STABILITY.md`.
 
@@ -187,4 +188,8 @@ prompts end-to-end without a contract amendment.
 
 ## See also
 
+- [`mcp-cloud-scope.md`](mcp-cloud-scope.md) — hosted Worker contract
+  (sibling, not child). Extends the bridge pattern from
+  [`mcp-request-signing § Appendix`](../guidelines/agent-infra/mcp-request-signing.md#appendix--http-bridge-stdio-kernel-pattern-reference)
+  for multi-tenant SSE.
 - [`STABILITY.md`](STABILITY.md) — stability policy for `docs/contracts/`.

package/docs/guidelines/agent-infra/mcp-request-signing.md

@@ -194,3 +194,7 @@ out-of-scope until a consumer surfaces a tenancy requirement.
   starts here; the upstream link is the authoritative source.
 - `road-to-ruflo-adoption.md` **P2.1** — landed this appendix; full
   bridge fork stays out-of-scope unless the dual trigger fires.
+- [`mcp-cloud-scope.md`](../../contracts/mcp-cloud-scope.md) —
+  operationalizes this pattern as a TypeScript Cloudflare Worker (no
+  spawned stdio child; R2 blob replaces the child process). HMAC
+  `verifyRequest` is deferred to MVP-2 alongside auth.

package/docs/mcp-server.md

@@ -4,13 +4,21 @@
 
 `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). Two channels
+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.
-- **MCP server** — `scripts/mcp_server/` exposes the same content over
-  JSON-RPC. Used by clients that speak MCP natively.
+- **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

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/package.json

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

package/scripts/mcp_parity_smoke.py

@@ -0,0 +1,146 @@
+"""Live-replay parity smoke — local stdio kernel vs deployed Worker URL.
+
+Replays a fixed set of JSON-RPC calls against:
+
+1. The local Python loaders (`prompts.py` / `resources.py`) — the
+   source-of-truth wire surface.
+2. An HTTP target (typically `wrangler dev` locally, or the deployed
+   Cloudflare Worker URL in CI / post-deploy).
+
+Diffs the two on a normalised view (signature + release_key + content
+hashes stripped). Exit 0 = parity, 1 = drift.
+
+Usage:
+    python scripts/mcp_parity_smoke.py --target http://127.0.0.1:8787
+    python scripts/mcp_parity_smoke.py --target https://mcp.example.com
+
+Phase 5.1 of `road-to-cloudflare-mcp-hosting.md`. Governed by
+`docs/contracts/mcp-cloud-scope.md` §A0-cloud.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+_SCRIPTS = Path(__file__).resolve().parent
+sys.path.insert(0, str(_SCRIPTS))
+
+from mcp_server.prompts import load_all_prompts, to_mcp_prompt_meta  # noqa: E402
+from mcp_server.resources import load_all_resources, to_mcp_resource_meta  # noqa: E402
+
+PAGE_SIZE = 50
+
+
+def _local_prompts_list() -> dict[str, Any]:
+    prompts, _ = load_all_prompts()
+    metas = [to_mcp_prompt_meta(p) for p in prompts]
+    page = metas[:PAGE_SIZE]
+    out: dict[str, Any] = {"prompts": page}
+    if len(metas) > PAGE_SIZE:
+        out["nextCursor"] = page[-1]["name"]
+    return out
+
+
+def _local_resources_list() -> dict[str, Any]:
+    resources, _ = load_all_resources()
+    metas = [to_mcp_resource_meta(r) for r in resources]
+    page = metas[:PAGE_SIZE]
+    out: dict[str, Any] = {"resources": page}
+    if len(metas) > PAGE_SIZE:
+        out["nextCursor"] = page[-1]["uri"]
+    return out
+
+
+def _rpc(target: str, method: str, params: dict[str, Any] | None = None) -> Any:
+    body = json.dumps(
+        {"jsonrpc": "2.0", "id": 1, "method": method, "params": params or {}}
+    ).encode("utf-8")
+    req = urllib.request.Request(
+        target,
+        data=body,
+        headers={"content-type": "application/json"},
+        method="POST",
+    )
+    with urllib.request.urlopen(req, timeout=10) as r:  # noqa: S310
+        resp = json.loads(r.read().decode("utf-8"))
+    if "error" in resp:
+        raise RuntimeError(f"{method}: {resp['error']}")
+    return resp["result"]
+
+
+def _normalize_prompts(payload: dict[str, Any]) -> list[dict[str, Any]]:
+    out = []
+    for p in payload.get("prompts", []):
+        out.append({
+            "name": p["name"],
+            "description": p["description"],
+            "kind": p.get("_meta", {}).get("kind"),
+        })
+    return sorted(out, key=lambda x: x["name"])
+
+
+def _normalize_resources(payload: dict[str, Any]) -> list[dict[str, Any]]:
+    out = []
+    for r in payload.get("resources", []):
+        out.append({
+            "uri": r["uri"],
+            "name": r["name"],
+            "description": r["description"],
+            "mimeType": r["mimeType"],
+            "kind": r.get("_meta", {}).get("kind"),
+        })
+    return sorted(out, key=lambda x: x["uri"])
+
+
+def _diff(label: str, local: list[Any], remote: list[Any]) -> int:
+    if local == remote:
+        print(f"✅  {label}: {len(local)} entries match")
+        return 0
+    print(f"❌  {label}: drift ({len(local)} local vs {len(remote)} remote)")
+    local_set = {json.dumps(x, sort_keys=True) for x in local}
+    remote_set = {json.dumps(x, sort_keys=True) for x in remote}
+    only_local = local_set - remote_set
+    only_remote = remote_set - local_set
+    for s in sorted(only_local)[:5]:
+        print(f"    local-only: {s}")
+    for s in sorted(only_remote)[:5]:
+        print(f"    remote-only: {s}")
+    if len(only_local) > 5 or len(only_remote) > 5:
+        print(f"    (+{len(only_local) - 5} local, +{len(only_remote) - 5} remote more)")
+    return 1
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--target", required=True, help="HTTP URL of the Worker.")
+    args = ap.parse_args()
+
+    failed = 0
+    local_p = _normalize_prompts(_local_prompts_list())
+    remote_p = _normalize_prompts(_rpc(args.target, "prompts/list"))
+    failed += _diff("prompts/list", local_p, remote_p)
+
+    local_r = _normalize_resources(_local_resources_list())
+    remote_r = _normalize_resources(_rpc(args.target, "resources/list"))
+    failed += _diff("resources/list", local_r, remote_r)
+
+    try:
+        _ = _rpc(args.target, "tools/list")
+        print("✅  tools/list: round-trips (stub list — content not parity-checked)")
+    except Exception as e:
+        print(f"❌  tools/list: {e}")
+        failed += 1
+
+    if failed:
+        print(f"\n{failed} surface(s) drifted between local stdio and {args.target}")
+        return 1
+    print(f"\nparity OK against {args.target}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/pack_mcp_content.py

@@ -0,0 +1,274 @@
+"""Pack agent-config content into a Worker-bundle JSON blob.
+
+Walks `.agent-src/skills/`, `.agent-src/commands/`, `.agent-src/rules/`,
+`docs/guidelines/`, `.agent-src/contexts/` via the same Python loaders
+that drive the local stdio kernel, emits one JSON blob and a sidecar
+manifest for `workers/mcp/`.
+
+Outputs (relative to repo root):
+- `workers/mcp/content.json`      — uncompressed, bundled by `wrangler deploy`.
+- `workers/mcp/content.json.gz`   — gzipped archival copy for R2.
+- `workers/mcp/manifest.json`     — manifest only (RCA / R2 sidecar).
+
+Hard-fail thresholds (Phase 2-5 council verdict D2):
+- Uncompressed JSON > 2 MB         → SystemExit(1).
+- Empty content (zero URIs)        → SystemExit(2). Catches a broken
+                                     `.agent-src/` tree before deploy.
+
+Cloud signature divergence vs local kernel (`metadata.compute_skill_set_signature`):
+- Local kernel:  SHA-256 over `(uri, mtime)` pairs — reproducible only
+                 within one filesystem.
+- This packer:   SHA-256 over `(uri, body)` pairs — reproducible across
+                 CI runs, machines, and re-clones. Same 12-char prefix.
+
+Governed by `docs/contracts/mcp-cloud-scope.md` §A0-cloud invariant 5.
+"""
+from __future__ import annotations
+
+import argparse
+import gzip
+import hashlib
+import json
+import os
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+# Re-use the local kernel's loaders so the live-replay baseline stays
+# trivially comparable.
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+sys.path.insert(0, str(_SCRIPTS_DIR))
+
+from mcp_server.prompts import scan_commands, scan_skills  # noqa: E402
+from mcp_server.resources import scan_contexts, scan_guidelines, scan_rules  # noqa: E402
+
+SCHEMA_VERSION = 1
+PACKER_VERSION = "1.0.0"
+# Worker bundle is the compact JSON; gzipped copy lives in R2. Cloudflare's
+# compressed-bundle limit is 3 MB (free) / 10 MB (paid); 778 KB gz today
+# (438 entries) leaves ample headroom. Hard-fail at 5 MB uncompressed so
+# the build dies before the Worker upload does.
+MAX_UNCOMPRESSED_BYTES = 5 * 1024 * 1024
+
+
+def _repo_root() -> Path:
+    return Path(__file__).resolve().parent.parent
+
+
+def _git_sha(root: Path) -> str:
+    """Resolve HEAD SHA. Falls back to env var, then to all-zeros."""
+    for env_var in ("GITHUB_SHA", "CI_COMMIT_SHA", "GIT_COMMIT"):
+        sha = os.environ.get(env_var)
+        if sha and len(sha) >= 7:
+            return sha
+    try:
+        out = subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            cwd=root,
+            capture_output=True,
+            text=True,
+            check=True,
+            timeout=5,
+        )
+        return out.stdout.strip()
+    except (subprocess.SubprocessError, FileNotFoundError):
+        return "0" * 40
+
+
+def _package_version(root: Path) -> str:
+    data = json.loads((root / "package.json").read_text(encoding="utf-8"))
+    return str(data.get("version", "0.0.0"))
+
+
+def _collect_entries(root: Path) -> tuple[dict[str, dict[str, Any]], list[str]]:
+    """Run all 5 scanners and project entries into the wire shape."""
+    uris: dict[str, dict[str, Any]] = {}
+    errors: list[str] = []
+
+    skills, e = scan_skills(root)
+    errors.extend(e)
+    for s in skills:
+        key = f"skill://{s.name}"
+        uris[key] = {
+            "uri": key,
+            "name": s.name,
+            "description": s.description,
+            "body": s.body,
+            "source": s.source,
+            "kind": "skill",
+        }
+
+    commands, e = scan_commands(root)
+    errors.extend(e)
+    for c in commands:
+        key = f"command://{c.name.replace(':', '.')}"
+        uris[key] = {
+            "uri": key,
+            "name": c.name,
+            "description": c.description,
+            "body": c.body,
+            "source": c.source,
+            "kind": "command",
+        }
+
+    for scan in (scan_rules, scan_guidelines, scan_contexts):
+        items, e = scan(root)
+        errors.extend(e)
+        for r in items:
+            uris[r.uri] = {
+                "uri": r.uri,
+                "name": r.name,
+                "description": r.description,
+                "body": r.body,
+                "source": r.source,
+                "kind": r.kind,
+                "mime_type": r.mime_type,
+            }
+
+    return uris, errors
+
+
+def _content_signature(uris: dict[str, dict[str, Any]]) -> tuple[str, str]:
+    """SHA-256 over sorted (uri, body) pairs.
+
+    Returns (full_hex, 12-char prefix). The prefix is the wire-surface
+    `skillSetSignature`; the full hex is the diagnostic `content_hash_sha256`.
+    """
+    hasher = hashlib.sha256()
+    for uri in sorted(uris):
+        hasher.update(uri.encode("utf-8"))
+        hasher.update(b"\x00")
+        hasher.update(uris[uri]["body"].encode("utf-8"))
+        hasher.update(b"\x1e")
+    digest = hasher.hexdigest()
+    return digest, digest[:12]
+
+
+def _count_kinds(uris: dict[str, dict[str, Any]]) -> dict[str, int]:
+    counts = {"skill": 0, "command": 0, "rule": 0, "guideline": 0, "context": 0}
+    for entry in uris.values():
+        kind = entry["kind"]
+        if kind in counts:
+            counts[kind] += 1
+    return counts
+
+
+
+def _build_manifest(
+    *,
+    signature: str,
+    content_hash: str,
+    package_version: str,
+    git_sha: str,
+    built_at: str,
+    counts: dict[str, int],
+) -> dict[str, Any]:
+    short = git_sha[:7] if git_sha and git_sha != "0" * 40 else "unknown"
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "signature": signature,
+        "content_hash_sha256": content_hash,
+        "package_version": package_version,
+        "release_key": f"v{package_version}-{short}",
+        "git_sha": git_sha,
+        "built_at": built_at,
+        "packer_version": PACKER_VERSION,
+        "content_uri_count": counts,
+    }
+
+
+def pack(root: Path, out_dir: Path) -> dict[str, Any]:
+    """Run the full pack. Returns the manifest dict."""
+    uris, errors = _collect_entries(root)
+    if not uris:
+        sys.stderr.write("pack: empty content (zero URIs)\n")
+        for line in errors:
+            sys.stderr.write(f"  - {line}\n")
+        raise SystemExit(2)
+
+    content_hash, signature = _content_signature(uris)
+    counts = _count_kinds(uris)
+    built_at = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    manifest = _build_manifest(
+        signature=signature,
+        content_hash=content_hash,
+        package_version=_package_version(root),
+        git_sha=_git_sha(root),
+        built_at=built_at,
+        counts=counts,
+    )
+
+    blob = {
+        "schema_version": SCHEMA_VERSION,
+        "uris": uris,
+        "manifest": manifest,
+    }
+    # Compact JSON for the bundle (saves ~20 KB vs indent=2). The R2
+    # archival copy is gzipped, so legibility there is moot.
+    payload = json.dumps(blob, ensure_ascii=False, sort_keys=True)
+    payload_bytes = payload.encode("utf-8")
+
+    if len(payload_bytes) > MAX_UNCOMPRESSED_BYTES:
+        sys.stderr.write(
+            f"pack: uncompressed content {len(payload_bytes)} bytes "
+            f"exceeds limit {MAX_UNCOMPRESSED_BYTES}\n"
+        )
+        raise SystemExit(1)
+
+    out_dir.mkdir(parents=True, exist_ok=True)
+    (out_dir / "content.json").write_bytes(payload_bytes)
+    # mtime=0 keeps the gzip header byte-stable across CI runs so the
+    # R2 archival copy hashes deterministically.
+    with open(out_dir / "content.json.gz", "wb") as raw:
+        with gzip.GzipFile(
+            fileobj=raw, mode="wb", compresslevel=9, mtime=0
+        ) as gz:
+            gz.write(payload_bytes)
+    (out_dir / "manifest.json").write_text(
+        json.dumps(manifest, ensure_ascii=False, sort_keys=True, indent=2) + "\n",
+        encoding="utf-8",
+    )
+
+    if errors:
+        sys.stderr.write("pack: non-fatal frontmatter errors:\n")
+        for line in errors:
+            sys.stderr.write(f"  - {line}\n")
+
+    return manifest
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--root", type=Path, default=_repo_root(), help="Repository root."
+    )
+    parser.add_argument(
+        "--out",
+        type=Path,
+        default=None,
+        help="Output directory (defaults to <root>/workers/mcp).",
+    )
+    parser.add_argument(
+        "--quiet", action="store_true", help="Suppress success summary."
+    )
+    args = parser.parse_args(argv)
+
+    out_dir = args.out or (args.root / "workers" / "mcp")
+    manifest = pack(args.root, out_dir)
+
+    if not args.quiet:
+        c = manifest["content_uri_count"]
+        sys.stderr.write(
+            f"pack: ok signature={manifest['signature']} "
+            f"release={manifest['release_key']} "
+            f"skills={c['skill']} commands={c['command']} "
+            f"rules={c['rule']} guidelines={c['guideline']} "
+            f"contexts={c['context']}\n"
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/readme_linter.py

@@ -88,7 +88,7 @@ GENERIC_BOILERPLATE = [
     r"(?i)\blightweight yet powerful\b",
 ]
 
-OVERLOADED_LINE_THRESHOLD = 500
+OVERLOADED_LINE_THRESHOLD = 750
 WEAK_QUICKSTART_LINE_GAP = 80