@event4u/agent-config 1.37.0 → 1.39.0

package/README.md

@@ -90,6 +90,41 @@ 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. Per-client setup snippets
+(Claude Desktop, Claude Code, Cursor, Zed, Continue) —
+[`docs/setup/mcp-client-config.md`](docs/setup/mcp-client-config.md).
+URL shapes (latest vs. pinned `/v<X.Y.Z>`) —
+[`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 lives at `docs/contracts/mcp-cloud-scope.md` (internal reference only per `STABILITY.md`).
+
+> **Scope — Lite, not Full.** The hosted MCP endpoint serves the
+> read-only governance surface (skills · commands · rules · guidelines
+> · contexts) as MCP prompts and resources. It does **not** execute any
+> of the ~112 Python scripts that ship with the package (linters,
+> audits, `task ci`, work-engine hooks, …). Those require the full
+> local install per [Quickstart](#quickstart). See
+> [`docs/contracts/mcp-cloud-scope.md`](docs/contracts/mcp-cloud-scope.md)
+> for the execution-safety boundary.
+
 ### Optional: persistent agent memory
 
 `agent-config` integrates with [`@event4u/agent-memory`](https://www.npmjs.com/package/@event4u/agent-memory)
@@ -109,7 +144,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/customization.md

@@ -42,6 +42,51 @@ The `.agent-settings.yml` file in the consumer project configures agent behavior
 It is written as YAML with section-level grouping; dotted keys below reference
 those sections.
 
+### User-global DX-comfort defaults (cross-project)
+
+Six **DX-comfort** keys can be carried across every project that uses
+`event4u/agent-config` by storing them once in a user-global file at:
+
+```
+~/.config/agent-config/agent-settings.yml
+```
+
+The path is XDG-style and matches the existing
+`~/.config/agent-config/` directory used for `anthropic.key`,
+`openai.key`, and `council-spend.jsonl`.
+
+**Whitelist (locked, exact dotted paths)** — only these six keys are
+mergeable from the user-global file; every other key is silently ignored:
+
+```
+name
+ide
+cost_profile
+personal.bot_icon
+personal.autonomy
+caveman.speak_scope
+```
+
+**Merge order** (lowest → highest precedence):
+
+```
+1. Package defaults                                   (shipped by event4u/agent-config)
+2. ~/.config/agent-config/agent-settings.yml          (user-global · whitelist-filtered)
+3. <project>/.agent-settings.yml                      (project-local · always wins)
+```
+
+Project-local values **always win**. The user-global file is a
+fallback, never a lock. Non-whitelisted keys in the user-global file
+are dropped without error — adding `personal.theme` there has no
+effect.
+
+The file is created **only on explicit opt-in via `/onboard`**. The
+loader at [`scripts/_lib/agent_settings.py`](../scripts/_lib/agent_settings.py)
+is **read-only** — no script can create or mutate it without an
+explicit `/onboard` confirmation. Edit the file by hand for mid-life
+changes; `/sync-agent-settings` stays project-scoped and never touches
+user-global state.
+
 ### Available settings
 
 | Setting | Default | Description |

package/docs/guidelines/agent-infra/layered-settings.md

@@ -1,37 +1,74 @@
 # Layered Settings
 
-Two-file settings model: **team defaults** (committed) and
-**developer overrides** (git-ignored). Lets a project pin decisions
-without forcing every developer to work the same way.
+Three-file settings model: **team defaults** (committed),
+**user-global DX-comfort defaults** (per-developer, cross-project), and
+**developer overrides** (per-project, git-ignored). Lets a project pin
+decisions, a developer carry DX preferences across every project, and
+project-local choices always win.
 
-Referenced by `road-to-project-memory.md` Phase 0. Consumed by the
-settings loader, the `/onboard` command, and any agent that edits
-`.agent-settings.yml` on user request.
+Referenced by `road-to-project-memory.md` Phase 0 and
+`road-to-portable-dev-preferences.md`. Consumed by the centralized
+settings loader at
+[`scripts/_lib/agent_settings.py`](../../../scripts/_lib/agent_settings.py),
+the `/onboard` command, and any agent that edits `.agent-settings.yml`
+on user request.
 
-## The two files
+## The three files
 
 | File | Git | Scope | Owner | Example values |
 |---|---|---|---|---|
 | `.agent-project-settings.yml` | **committed** | team / repo | lead maintainer | `project.stack`, `quality.php.tools`, `memory.dogfood` |
-| `.agent-settings.yml` | **gitignored** | developer workstation | individual | `personal.ide`, `personal.user_name`, `subagents.max_parallel` |
+| `~/.config/agent-config/agent-settings.yml` | **n/a** (outside repo) | individual developer · cross-project | individual | `name`, `ide`, `cost_profile`, `personal.bot_icon`, `personal.autonomy`, `caveman.speak_scope` |
+| `.agent-settings.yml` | **gitignored** | individual developer · this project | individual | `personal.ide`, `personal.user_name`, `subagents.max_parallel`, `onboarding.onboarded` |
 
-Both are YAML. Schema is documented in
-[`agent-settings.md`](../../templates/agent-settings.md) (dev layer)
-and [`agent-project-settings.example.yml`](../../templates/agents/agent-project-settings.example.yml)
-(team layer).
+All three are YAML. Schemas:
+
+- Developer (project-local): [`agent-settings.md`](../../templates/agent-settings.md).
+- Team: [`agent-project-settings.example.yml`](../../templates/agents/agent-project-settings.example.yml).
+- User-global: six exact dotted paths — whitelist in
+  [`scripts/_lib/agent_settings.py`](../../../scripts/_lib/agent_settings.py).
 
 ## Merge order
 
 Lowest priority → highest priority:
 
 ```
-1. Package defaults       (shipped by event4u/agent-config)
-2. .agent-project-settings.yml   (team file, committed)
-3. .agent-settings.yml           (developer file, gitignored)
+1. Package defaults                                   (shipped by event4u/agent-config)
+2. ~/.config/agent-config/agent-settings.yml          (user-global · whitelist-filtered)
+3. .agent-project-settings.yml                        (team file, committed)
+4. .agent-settings.yml                                (developer file, gitignored)
+```
+
+Keys from higher layers win unless a lower layer marks them
+`locked` (team file only). The user-global file does **not** support
+`locked` — its purpose is cross-project comfort, never policy.
+
+## User-global whitelist
+
+Only these exact dotted paths are mergeable from the user-global file;
+every other key is silently dropped by the loader. The whitelist is
+intentionally tiny — adding a key requires an ADR.
+
+```
+name
+ide
+cost_profile
+personal.bot_icon
+personal.autonomy
+caveman.speak_scope
 ```
 
-Keys from higher layers win unless the lower layer marks them
-`locked`. Locked keys cannot be shadowed by a higher layer.
+Loader contract:
+
+- **Read-only.** The loader never creates, modifies, or deletes the
+  user-global file. Writes are the exclusive responsibility of the
+  `/onboard` command on explicit user opt-in.
+- **Tolerant.** Missing file, malformed YAML, empty file — all fall
+  back to the next tier without raising.
+- **Silent on out-of-whitelist keys.** `verbose=True` logs which keys
+  were dropped for debugging; default mode is silent.
+- **Never auto-creates `~/.config/agent-config/`.** That directory
+  pre-exists from key installation; `/onboard` `mkdir -p`s on opt-in.
 
 ## Lock semantics
 

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-client-config.md

@@ -0,0 +1,152 @@
+# MCP Client Config — Remote agent-config
+
+Connect any MCP-capable client to the hosted `agent-config-mcp` Worker
+at `https://agent-config-mcp.event4u.workers.dev`. Read-only,
+identity-stable per release, no auth.
+
+For URL shapes (latest vs. pinned `/v<X.Y.Z>`) see
+[`mcp-cloud-endpoints.md`](mcp-cloud-endpoints.md). For operator
+setup of your own deployment see [`mcp-cloud-setup.md`](mcp-cloud-setup.md).
+
+## Transport note
+
+The Worker speaks JSON-RPC over HTTP POST. Clients that support
+HTTP transport natively (Claude Code, Cursor) talk to it directly.
+Clients that only support stdio (Claude Desktop, Zed) need the
+[`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge from
+npm — invoked via `npx`, no install required.
+
+## Where settings live — `.agent-settings.yml` vs. MCP config
+
+These are **two different files** for two different layers. Don't
+look for MCP server config inside `.agent-settings.yml`.
+
+| File | Where | Who reads it | Purpose |
+|---|---|---|---|
+| MCP client config (this page) | client-specific path per section above | the MCP client at startup | which MCP servers to talk to (name + URL / command) |
+| `.agent-settings.yml` | consumer project root (`<repo>/.agent-settings.yml`) | the agent at runtime (Claude / Cursor / …) | per-developer preferences: `name`, `ide`, `cost_profile`, `personal.autonomy`, `pipelines.skill_improvement`, `caveman.speak_scope`, … |
+
+The hosted MCP is **stateless** and **project-agnostic** — it serves
+the same skill / rule / command catalog to every client. Personalization
+happens agent-side after the MCP delivers its content blob; the Worker
+itself does not read `.agent-settings.yml`.
+
+First-time setup of `.agent-settings.yml` runs through `/onboard`;
+template drift is handled by `/sync-agent-settings`.
+
+## 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": "npx",
+      "args": ["-y", "mcp-remote", "https://agent-config-mcp.event4u.workers.dev"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The connector appears in the dropdown.
+
+Newer builds also support **Settings → Connectors → Add Custom
+Connector** with the URL directly — no `mcp-remote` wrapper needed.
+
+## Claude Code
+
+Native HTTP transport — one command:
+
+```bash
+claude mcp add --transport http agent-config https://agent-config-mcp.event4u.workers.dev
+```
+
+Verify:
+
+```bash
+claude mcp list
+```
+
+## Cursor
+
+`~/.cursor/mcp.json` (global) or `<repo>/.cursor/mcp.json`
+(project-local):
+
+```json
+{
+  "mcpServers": {
+    "agent-config": {
+      "url": "https://agent-config-mcp.event4u.workers.dev"
+    }
+  }
+}
+```
+
+Reload Cursor (`Cmd+Shift+P → Reload Window`).
+
+## Zed
+
+`~/.config/zed/settings.json`:
+
+```json
+{
+  "context_servers": {
+    "agent-config": {
+      "source": "custom",
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://agent-config-mcp.event4u.workers.dev"]
+    }
+  }
+}
+```
+
+Zed has no native remote-MCP transport yet, so the `mcp-remote`
+bridge is required.
+
+## Continue
+
+`~/.continue/config.yaml` (or `<repo>/.continue/config.yaml`):
+
+```yaml
+mcpServers:
+  - name: agent-config
+    command: npx
+    args: ["-y", "mcp-remote", "https://agent-config-mcp.event4u.workers.dev"]
+```
+
+## Verify
+
+After reload, every client should:
+
+1. List `agent-config` under connectors / tools with a release-key
+   matching the live deploy. Probe the endpoint to see the current
+   release:
+
+   ```bash
+   curl https://agent-config-mcp.event4u.workers.dev
+   # → { "ok": true, "release_key": "v…", "signature": "…", … }
+   ```
+
+2. Expose skill + command prompts under URIs like `skill://…` and
+   `command://…`.
+3. Expose rule + guideline + context resources under `rule://…`,
+   `guideline://…`, `context://…`.
+
+If the client shows the connector but no prompts / resources,
+re-probe the URL — a 5xx from the Worker indicates the deploy is
+mid-roll, retry after a minute.
+
+## Local stdio alternative
+
+If you have the repo cloned and prefer running the MCP server
+locally (faster startup, no network), the stdio kernel under
+`scripts/mcp_server/` is the same wire surface. Setup:
+`task mcp:setup`, run details in [`../mcp-server.md`](../mcp-server.md).
+
+## See also
+
+- URL shapes & DNS — [`mcp-cloud-endpoints.md`](mcp-cloud-endpoints.md)
+- Operator setup (your own deploy) — [`mcp-cloud-setup.md`](mcp-cloud-setup.md)
+- A0-cloud contract — [`../contracts/mcp-cloud-scope.md`](../contracts/mcp-cloud-scope.md)