@nanobpm/nano-workforce 0.149.0 → 0.150.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.150.0](https://github.com/nanobpm/nano-workforce/compare/v0.149.0...v0.150.0) (2026-08-28)
+
+### Features
+
+* adopt Urban MCP surface — x-mcp exclusions, runbook, MCP-first skill ([#575](https://github.com/nanobpm/nano-workforce/issues/575)) ([44e89e4](https://github.com/nanobpm/nano-workforce/commit/44e89e40b6cbff0e4c7de32dad76d35f6d534cc6)), closes [nano-ide#488](https://github.com/nanobpm/nano-ide/issues/488) [nano-ide#488](https://github.com/nanobpm/nano-ide/issues/488) [#567](https://github.com/nanobpm/nano-workforce/issues/567) [#567](https://github.com/nanobpm/nano-workforce/issues/567) [nano-ide#488](https://github.com/nanobpm/nano-ide/issues/488)
+
 ## [0.149.0](https://github.com/nanobpm/nano-workforce/compare/v0.148.2...v0.149.0) (2026-08-27)
 
 ### Features

package/README.md

@@ -282,7 +282,7 @@ agent at that URL to author, compile, and submit a graph unaided. See
 | `NANO_PR_GITHUB_TRANSPORT` | `auto` | how the poller reads GitHub: `gh` (host CLI), `token` (`GITHUB_TOKEN` over HTTP), or `auto` |
 | `NANO_PR_POLL_MS` | `60000` | review-ready poll interval |
 | `NANO_PR_MAX_ROUNDS` | `20` | default cap: escalate after N rounds (per-submit override via the form / the `maxRounds` field on `start/convergence-loop`; clamped 1–100) |
-| `NANO_PR_WEBHOOK_SECRET` | — | optional shared secret (`X-Hook-Secret`) for guarded operations (e.g. `POST /app/api/agent`, `/app/api/version`, `/app/api/status`); unset = open |
+| `NANO_PR_WEBHOOK_SECRET` | — | optional shared secret (`x-hook-secret`) for guarded operations (e.g. `GET /app/api/agent`, `/app/api/version`, `/app/api/status`); unset = open |
 | `NANO_PR_AUTO_MERGE` | `1` | after convergence, run the merge stage; `0` = stop at `converged` (review-only). Per-submit override via the `convergeOnly` field on `start/convergence-loop` (`true` forces review-only for that PR) |
 | `NANO_PR_MERGE_METHOD` | `squash` | merge method: `squash`, `merge`, or `rebase` |
 | `NANO_PR_MERGE_ADMIN` | `0` | pass `--admin` to override failing non-required checks (use with care) |
@@ -452,9 +452,42 @@ curl -sS http://localhost:3000/app/api/agent | jq -r .instructions
 ```
 
 Like `/version` and `/status`, this endpoint honours the optional
-`NANO_PR_WEBHOOK_SECRET` guard (`X-Hook-Secret` header): when that secret is set it
+`NANO_PR_WEBHOOK_SECRET` guard (`x-hook-secret` header): when that secret is set it
 returns `401` without the matching header; unset = open. The source lives in
-`resources/agent-guide.md`.
+`docs/agent-guide.md`.
+
+### Configure an agent over MCP
+
+Where your agent supports **MCP**, prefer it over the curl path above. The Urban
+runtime serves a Streamable-HTTP MCP endpoint at **`/app/mcp`** for every instance and
+projects this app's `openapi.yaml` into tools with **zero MCP code in nwf** — the app
+operations (including the operator guide, projected from `GET /app/api/agent` as the
+`getAgentInstructions` read tool), a framework-owned engine-debug tool family (process
+instances, wait states, variables, incidents), the `urban_*` projection reads, and the
+runtime's derived **system brief** as an MCP resource plus an orientation prompt
+(ADR 0067, nano-ide#488). Register one server entry per instance and name
+it when you drive — tool calls are namespaced per entry, so the wrong-instance mistake
+becomes impossible:
+
+```bash
+copilot mcp add --transport http workforce-local http://localhost:3000/app/mcp
+# guarded instance: add the app secret as a header (never in chat)
+copilot mcp add --transport http workforce-merlin http://merlin.local:3000/app/mcp \
+  --header "x-hook-secret: $NANO_PR_WEBHOOK_SECRET"
+```
+
+When `NANO_PR_WEBHOOK_SECRET` is unset, reads and mutations both work from loopback with
+no credential; when it is set, that secret is required as an `x-hook-secret` header on
+**both** — read endpoints like `GET /app/api/agent` and `GET /app/api/version` also
+return `401` without it. **Operator-only doors stay operator-only** —
+delivery-graph **dispatch** (and the stage/dismiss lifecycle) is `x-mcp`-excluded, so the
+human clicking Dispatch in the cockpit remains the approval (ADR 0005). MCP is a **third
+door**: `GET /app/api/agent` and `GET /app/api/agent/skill` are unchanged for agents
+without it.
+
+The full recipe — multiple instances, Basic-Auth-fronted instances, LAN exposure,
+verification and wedged-instance debugging prompts — is the **agent-configuration
+runbook**: [`docs/mcp-runbook.md`](docs/mcp-runbook.md).
 
 ---
 

package/SPEC.md

@@ -492,7 +492,7 @@ queries skip (`merging`), so a slow pass can't double-signal.
 | `GITHUB_TOKEN` | — | GitHub API (poller + agent) |
 | `NANO_PR_POLL_MS` | 60000 | poll interval |
 | `NANO_PR_MAX_ROUNDS` | 20 | default round cap (per-submit `maxRounds` override, clamped 1–100) |
-| `NANO_PR_WEBHOOK_SECRET` | — | optional shared secret (`X-Hook-Secret`) for guarded operations (e.g. `/app/api/agent`, `/app/api/version`, `/app/api/status`) |
+| `NANO_PR_WEBHOOK_SECRET` | — | optional shared secret (`x-hook-secret`) for guarded operations (e.g. `/app/api/agent`, `/app/api/version`, `/app/api/status`) |
 | `NANO_PR_AUTO_MERGE` | 1 | run the merge stage after convergence (`0` = review-only; per-submit `convergeOnly: true` override) |
 | `NANO_PR_MERGE_METHOD` | squash | `squash` \| `merge` \| `rebase` |
 | `NANO_PR_MERGE_ADMIN` | 0 | pass `--admin` on merge |

package/app/mcpExclusions.test.ts

@@ -0,0 +1,83 @@
+// Authoring guard for the `x-mcp` MCP tool-exclusion switch (ADR 0067 §2, nano-ide#488 slice 3;
+// adopted here as slice 4, issue #567).
+//
+// The runtime-served MCP surface (`/app/mcp`) projects every non-excluded `openapi.yaml` operation
+// into an MCP tool. An operation opts OUT with the `x-mcp` extension — `x-mcp: false` or
+// `x-mcp: { exclude: true }`; any other value (or its absence) leaves it exposed. That switch is
+// security-relevant: it is the one authoring control that keeps an operator-only door off the
+// agent-facing tool surface, so this test pins the intended exclusion set at the spec level.
+//
+// Derivation over duplication (AGENTS.md): we do NOT re-implement the exclusion rule or the
+// path×method walk. We read the projection from the SAME `@nanobpm/urban` walker the runtime MCP
+// module builds its live tool list from — `parseSpec` + `collectOperations`, whose `mcpExcluded`
+// flag IS `isMcpExcluded` applied at parse time (openapi/spec.ts). This app-side test is therefore
+// the authoring assertion that OUR operator doors carry the switch and that no agent-facing
+// operation was excluded by accident, checked against the exact rule the runtime honours — no
+// second source of truth to drift from it.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+import { collectOperations, parseSpec } from "@nanobpm/urban/toolkit";
+import { assert, assertEquals } from "#test-assert";
+
+const REPO_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const SPEC_PATH = join(REPO_ROOT, "openapi.yaml");
+
+// Every operation the runtime projection enumerates, with its `x-mcp` exclusion flag — read from
+// the framework walker so this test and the live tool surface can never diverge.
+function projectedOperations() {
+  return collectOperations(parseSpec(readFileSync(SPEC_PATH, "utf8")));
+}
+
+// The operator-only cockpit doors: the staged delivery-graph lifecycle (stage -> dispatch ->
+// dismiss) whose approval is a human click in the cockpit (ADR 0005 Decision 7). These — and ONLY
+// these — must be excluded from the projected MCP tool surface.
+const EXPECTED_EXCLUDED = ["stageDeliveryGraph", "dispatchDeliveryGraph", "dismissProposal"];
+
+// A representative set of agent-facing operations that MUST stay exposed as tools — the drive doors
+// (submit PR / epic / delivery-graph set), the pure compile/preview doors, and the read/orientation
+// surface an agent debugging a wedged instance relies on.
+const EXPECTED_EXPOSED = [
+  "startConvergenceLoop",
+  "startPlanFanout",
+  "startEpicSet",
+  "compileDeliveryGraph",
+  "previewDeliveryGraph",
+  "listStagedProposals",
+  "listActivePrs",
+  "getAgentInstructions",
+  "getVersion",
+];
+
+test("x-mcp excludes exactly the operator-only delivery-graph lifecycle doors", () => {
+  const excluded = projectedOperations()
+    .filter((op) => op.mcpExcluded)
+    .map((op) => op.operationId)
+    .sort();
+  assertEquals(excluded, [...EXPECTED_EXCLUDED].sort());
+});
+
+test("x-mcp leaves the agent-facing drive/preview/read operations exposed", () => {
+  const byId = new Map(projectedOperations().map((op) => [op.operationId, op]));
+  for (const id of EXPECTED_EXPOSED) {
+    const op = byId.get(id);
+    assert(op, `expected operation ${id} to exist in openapi.yaml`);
+    assertEquals(op.mcpExcluded, false, `operation ${id} must NOT be x-mcp excluded`);
+  }
+});
+
+// The operator guide (workflow knowledge) is discoverable over MCP as the projected
+// `getAgentInstructions` READ tool — a safe GET, so the runtime projects it as a read tool
+// (not `x-mcp`-excluded) on loopback, instance-keyed by the same `resolveApiBase` rewriting
+// as its HTTP route. ("Read tool" describes the projected verb, not an auth posture: the
+// route still honours the app's optional `x-hook-secret` guard when `NANO_PR_WEBHOOK_SECRET`
+// is set.) This is how the guide's prose reaches an MCP agent; the framework separately
+// serves its derived system brief as a resource. Pin the projection facts so an accidental
+// exclusion (or a verb change that would flip it into a mutation) fails CI.
+test("the operator guide is projected as a read tool (GET, not x-mcp excluded) over MCP", () => {
+  const op = projectedOperations().find((o) => o.operationId === "getAgentInstructions");
+  assert(op, "getAgentInstructions must exist in openapi.yaml");
+  assertEquals(op.mcpExcluded, false, "the operator guide must stay exposed over MCP");
+  assertEquals(op.method, "get", "the operator guide must be a safe GET so it projects as a read tool");
+});

package/docs/mcp-runbook.md

@@ -0,0 +1,133 @@
+# Configure an agent to drive/debug this workforce over MCP
+
+> Adoption of the Urban runtime-served MCP surface ([ADR 0067](https://github.com/nanobpm/nano-ide/blob/main/docs/adr/0067-runtime-served-mcp-surface.md),
+> nano-ide#488) — first consumer, nano-workforce#567. Written against the
+> [Copilot CLI](https://github.com/github/copilot-cli) (the harness nwf's fleet
+> uses). Claude/Cursor equivalents use the same server entries.
+
+The Urban runtime serves a Streamable-HTTP MCP endpoint at **`/app/mcp`** for every
+hosted app and projects this app's `openapi.yaml` into tools — **zero MCP server code
+in nwf**. An MCP-capable agent gets nwf's operations (submit work, answer escalations,
+read status, and the operator **guide** itself — `GET /app/api/agent`, projected as the
+`getAgentInstructions` read tool), the framework-owned engine-debug tool family (process
+instances, wait states, variables, incidents), the `urban_*` projection reads, and the
+runtime's derived **system brief** as an MCP resource plus an orientation prompt — all
+namespaced per server entry.
+
+This replaces the SKILL.md instance-probing dance for MCP clients: naming the
+instance (`"drive workforce-merlin"`) makes the wrong-instance mistake structurally
+impossible. The named-instance registry (`NANO_WORKFORCE_INSTANCES` /
+`~/.config/nano-workforce/instances.json`) remains the source for the fallback path
+and a handy list of the entries to register here.
+
+MCP is a **third door**, not a replacement: `GET /app/api/agent` (the live guide) and
+`GET /app/api/agent/skill` are unchanged for agents without MCP — see
+[§5 Fallback](#5-fallback).
+
+## 1. One MCP server entry per instance
+
+In `~/.copilot/mcp-config.json` (user-wide) or `.mcp.json` (repo-scoped):
+
+```json
+{
+  "mcpServers": {
+    "workforce-local": {
+      "type": "http",
+      "url": "http://localhost:3000/app/mcp",
+      "tools": ["*"]
+    },
+    "workforce-merlin": {
+      "type": "http",
+      "url": "http://merlin.local:3000/app/mcp",
+      "headers": { "x-hook-secret": "$NANO_PR_WEBHOOK_SECRET" },
+      "tools": ["*"]
+    },
+    "workforce-remote": {
+      "type": "http",
+      "url": "https://<subdomain>.ngrok.app/app/mcp",
+      "headers": { "x-hook-secret": "$NANO_PR_WEBHOOK_SECRET" },
+      "tools": ["*"]
+    }
+  }
+}
+```
+
+Or from the terminal:
+
+```bash
+copilot mcp add --transport http workforce-local http://localhost:3000/app/mcp
+# add --header for a guarded instance:
+copilot mcp add --transport http workforce-merlin http://merlin.local:3000/app/mcp \
+  --header "x-hook-secret: $NANO_PR_WEBHOOK_SECRET"
+```
+
+Tool calls are namespaced per server entry, so the instance you name is the instance
+you drive.
+
+### Instance behind Basic Auth? You need *both* headers
+
+Two different layers. `x-hook-secret` is the **app's own** guard (checked by nwf in
+the operation handler, only when `NANO_PR_WEBHOOK_SECRET` is set). **Basic Auth** is
+enforced by whatever **fronts** the instance (ngrok edge, console proxy) and 401s
+*before* the request ever reaches nwf:
+
+```json
+"headers": {
+  "Authorization": "Basic <base64(user:pass)>",
+  "x-hook-secret": "..."
+}
+```
+
+Generate the blob with `printf '%s' 'user:pass' | base64` — `echo | base64` appends a
+newline and yields the wrong value. The proxy must forward custom headers for
+`x-hook-secret` to survive (most do by default). Base64 is encoding, not encryption:
+only use Basic Auth over HTTPS. The fallback curl path needs both too:
+`curl -u user:pass -H "x-hook-secret: …"`.
+
+## 2. Verify discovery
+
+New agent session → the `workforce-*` tools appear (app operations + the engine-debug
+family). Ask:
+
+> *"Using workforce-local, show what's in flight and any open escalations."*
+
+The agent should call the status operation tool, not curl.
+
+## 3. Debug a wedged instance
+
+> *"workforce-local: PR nanobpm/nano-workforce#123 looks wedged — find its process
+> instance, compare engine truth against the app's projections, and tell me where
+> it's stuck."*
+
+The agent has: instance search, wait states, variables, incidents (engine truth) +
+the `urban_*` projection reads (app belief) + the operator guide (the
+`getAgentInstructions` tool) for the convergence-loop-specific meaning of each wedge
+shape. A wedge is frequently exactly a disagreement between the two planes.
+
+## 4. Guard posture
+
+When `NANO_PR_WEBHOOK_SECRET` is **unset**, both reads (status, instances, incidents,
+projections, the operator guide) and mutations (cancel/retry/resolve, `start/*`
+operations, answering escalations) work from loopback with no credential. When it **is
+set**, the guard is not mutation-only: that secret is required as an `x-hook-secret`
+header on **both reads and mutations** — read endpoints like `GET /app/api/agent` and
+`GET /app/api/version` also return `401` without it. Put it in the server entry's
+`headers`, never in chat. For a remote fleet,
+`NANO_WORKFORCE_BASE_URL` reachability rules apply unchanged, and LAN exposure of
+`/app/mcp` follows the same `network.bind` manifest setting as the rest of the app's
+HTTP surface.
+
+**Operator-only doors stay operator-only.** The staged delivery-graph lifecycle —
+`stageDeliveryGraph`, `dispatchDeliveryGraph`, `dismissProposal` — is `x-mcp`-excluded
+from the projected tool surface (ADR 0067 §2): the human clicking **Dispatch** in the
+cockpit *is* the approval (ADR 0005 Decision 7), so an agent cannot dispatch a delivery
+graph through MCP. Agents author graphs through the pure `compileDeliveryGraph` /
+`previewDeliveryGraph` doors, which stay exposed.
+
+## 5. Fallback
+
+Agents without MCP are unchanged — resolve the instance, then
+`curl -sS $BASE/agent | jq -r .instructions`, or load the
+[`nano-workforce` skill](../skills/nano-workforce/SKILL.md), which fetches the same
+live guide. `GET /app/api/agent` and `GET /app/api/agent/skill` keep working exactly as
+before.

package/openapi.yaml

@@ -3134,6 +3134,12 @@ paths:
   /actions/delivery-graph/stage:
     post:
       operationId: stageDeliveryGraph
+      # x-mcp exclusion (ADR 0067 §2 / nano-ide#488): operator-only cockpit door, kept OFF the
+      # runtime-projected MCP tool surface. The staged-proposal lifecycle (stage -> dispatch ->
+      # dismiss) is the human approval path (ADR 0005 Decision 7 — the operator's click IS the
+      # approval); agents author graphs through the pure compile/preview doors only, never stage.
+      x-mcp:
+        exclude: true
       summary: UI JSON-paste STAGE — parse a pasted delivery-graph JSON string, compile it and stage it for operator dispatch. (ADR 0005 Decision 7 / #460 / #516)
       description: >-
         The human-facing UI JSON-paste STAGE ingress — the deliberate commit half of the preview/stage
@@ -3167,6 +3173,11 @@ paths:
   /actions/delivery-graph/dispatch:
     post:
       operationId: dispatchDeliveryGraph
+      # x-mcp exclusion (ADR 0067 §2 / nano-ide#488): the canonical operator-only door. Dispatch
+      # approval IS a human clicking Dispatch in the cockpit (ADR 0005 Decision 7) — there is no
+      # replayable token and no agent-facing dispatch handle, so it is never a projected MCP tool.
+      x-mcp:
+        exclude: true
       summary: OPERATOR DISPATCH — launch a staged delivery-graph proposal by its digest (idempotent). (ADR 0005 Decision 7 / #460)
       description: >-
         The OPERATOR-ONLY dispatch door (ADR 0005 Decision 7, issue #460). The cockpit's staged-proposals
@@ -3212,6 +3223,11 @@ paths:
   /actions/delivery-graph/dismiss:
     post:
       operationId: dismissProposal
+      # x-mcp exclusion (ADR 0067 §2 / nano-ide#488): operator-only cockpit door — discarding a
+      # staged proposal as noise is a human decision in the same approval class as dispatch, so it
+      # stays off the projected MCP tool surface.
+      x-mcp:
+        exclude: true
       summary: OPERATOR DISMISS — discard a staged delivery-graph proposal by its digest as noise (idempotent). (#520)
       description: >-
         The OPERATOR-ONLY dismiss door (#520). The cockpit's staged-proposals grid posts the `digest` of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.149.0",
+  "version": "0.150.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",
@@ -59,7 +59,7 @@
   },
   "dependencies": {
     "@nanobpm/agentic": "^0.4.0",
-    "@nanobpm/urban": "^0.83.0",
+    "@nanobpm/urban": "^0.86.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2"
   },
   "devDependencies": {

package/skills/README.md

@@ -7,9 +7,13 @@ loads on demand when its `description` matches the task.
 ## `nano-workforce`
 
 A **thin bootstrap** that teaches any agent to operate a running Nano Workforce
-instance: it resolves the instance base URL and fetches the instance's *live*
-operator guide (`GET /app/api/agent`), then follows it. It deliberately holds no
-endpoint detail of its own — the live, version-matched guide is the source of truth.
+instance. Where the client supports **MCP**, it registers the instance's `/app/mcp`
+server (its tools appear automatically, including the operator guide as the
+`getAgentInstructions` tool — ADR 0067); where
+it does not, it resolves the instance base URL and fetches the instance's *live*
+operator guide (`GET /app/api/agent`), then follows it. Either way it deliberately holds
+no endpoint detail of its own — the live, version-matched surface is the source of truth.
+See [`docs/mcp-runbook.md`](../docs/mcp-runbook.md) for the MCP server-entry recipes.
 
 ### Install
 

package/skills/nano-workforce/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: nano-workforce
-description: Drive and debug a running Nano Workforce instance — submit PRs for review convergence, submit issues/epics for plan→implement→converge, submit agent-authored delivery graphs (ADR 0005), answer escalations, and unstick stuck instances. Use when the user asks to operate, drive, submit work to, or debug their Nano Workforce.
+description: Drive and debug a running Nano Workforce instance — submit PRs for review convergence, submit issues/epics for plan→implement→converge, submit agent-authored delivery graphs (ADR 0005), answer escalations, and unstick stuck instances. Prefer the instance's MCP server (add it → its tools appear); fall back to the live operator guide. Use when the user asks to operate, drive, submit work to, or debug their Nano Workforce.
 ---
 
 # Nano Workforce operator skill
@@ -12,27 +12,88 @@ implements → converges** them across a fleet of coding agents, and runs
 DAGs — ADR 0005).
 
 **This skill is a thin bootstrap by design.** It does not describe the endpoints.
-Every running nwf instance serves its own operator guide, *live*, keyed to that
-instance's URLs and matched to its deployed version. Your job is to fetch that
-guide and follow it — never to work from a cached copy, which drifts across
-versions and instances.
+Every running nwf instance is self-describing — over **MCP** where your client
+supports it, and over its **live operator guide** everywhere else. Your job is to
+reach that live surface and follow it, never to work from a cached copy that drifts
+across versions and instances.
+
+There are two paths. **Prefer MCP (§A).** If your client has no MCP support, use the
+fetch-the-live-guide fallback (§B). Both talk to the same app; MCP is a projection of
+the same OpenAPI contract, not a different system (ADR 0067).
+
+## A. Preferred — drive over MCP
+
+The Urban runtime serves a Streamable-HTTP MCP endpoint at **`/app/mcp`** for every
+instance, with **zero app-side MCP code**: the app's operations are projected into
+tools from its OpenAPI spec, alongside a framework-owned engine-debug tool family
+(process instances, wait states, variables, incidents) and the app's projection
+reads. The operator **guide** (the same guide as §B) is itself one of those projected
+tools — `GET /app/api/agent` becomes the `getAgentInstructions` read tool — so the
+workflow knowledge (orient first, preview before dispatch, escalations are for humans)
+is discoverable over the same channel as the drive tools; the runtime additionally
+serves its derived **system brief** as an MCP resource plus an orientation prompt.
+
+**Register one MCP server entry per instance.** Naming the instance
+(`"drive workforce-merlin"`) makes the wrong-instance mistake structurally
+impossible — tool calls are namespaced per server entry. For the Copilot CLI, in
+`~/.copilot/mcp-config.json` (user-wide) or `.mcp.json` (repo-scoped):
+
+```json
+{
+  "mcpServers": {
+    "workforce-local": {
+      "type": "http",
+      "url": "http://localhost:3000/app/mcp",
+      "tools": ["*"]
+    },
+    "workforce-merlin": {
+      "type": "http",
+      "url": "http://merlin.local:3000/app/mcp",
+      "headers": { "x-hook-secret": "$NANO_PR_WEBHOOK_SECRET" },
+      "tools": ["*"]
+    }
+  }
+}
+```
+
+Or from the terminal:
+`copilot mcp add --transport http workforce-local http://localhost:3000/app/mcp`
+(add `--header` for a guarded instance). Claude/Cursor use the same server entries.
+
+Then: start a session, confirm the `workforce-*` tools appear, and ask the agent to
+use a **named** instance (`"Using workforce-local, show what's in flight and any open
+escalations"`). It should call the status operation tool, not curl.
 
-## 1. Confirm which instance you are driving — always
+**Guard posture.** When `NANO_PR_WEBHOOK_SECRET` is **unset**, both reads (status,
+instances, incidents, projections, the operator guide) and mutations (submit work,
+answer escalations, cancel/retry/resolve) work from loopback with no credential. When it
+**is set**, that secret is required as an `x-hook-secret` header on **both reads and
+mutations** — read endpoints like `getAgentInstructions`/`getVersion` also return `401`
+without it — put it in the server entry's `headers`, never in chat. **Operator-only doors stay operator-only:** the delivery-graph
+dispatch/dismiss lifecycle (the human clicking Dispatch *is* the approval, ADR 0005)
+is `x-mcp`-excluded and is **not** a tool — dispatch stays a human action in the
+cockpit.
 
-A user typically runs **several** Nano Workforce instances — e.g. a local dev copy,
-one on the LAN (`http://merlin.local:3000/app/api`), and a public tunnel
-(an ngrok URL) when off the LAN. Every action here is **side-effecting** —
-submitting work, answering escalations, merging PRs — so targeting the wrong
-instance is a real mistake, not a harmless one. **Never silently default to a
-base URL.**
+The full server-entry recipes (multiple instances, Basic-Auth-fronted instances,
+LAN exposure) live in the **agent-configuration runbook** — see the repo README
+("Configure an agent over MCP") and [`docs/mcp-runbook.md`](../../docs/mcp-runbook.md).
 
-### Sources of candidate instances
+## B. Fallback — no MCP client? Fetch the live guide
 
-Gather candidates from, in order:
+Agents without MCP are unchanged: resolve the instance, then fetch and follow its
+live guide.
 
-1. **A named-instance registry** the user maintains — first of these that exists:
-   `$NANO_WORKFORCE_INSTANCES` (JSON object of `name → base URL`), or
-   `~/.config/nano-workforce/instances.json` (same shape). Example:
+### B.1 Confirm which instance you are driving — always
+
+A user typically runs **several** instances — a local dev copy, one on the LAN
+(`http://merlin.local:3000/app/api`), and a public tunnel (ngrok) when off the LAN.
+Every action is **side-effecting**, so targeting the wrong instance is a real
+mistake. **Never silently default to a base URL.** Gather candidates, in order:
+
+1. A named-instance registry the user maintains — first that exists:
+   `$NANO_WORKFORCE_INSTANCES` (JSON `name → base URL`) or
+   `~/.config/nano-workforce/instances.json` (same shape). This is also the source
+   for the per-instance MCP server names in §A. Example:
 
    ```json
    { "local": "http://localhost:3000/app/api",
@@ -40,33 +101,25 @@ Gather candidates from, in order:
      "remote": "https://<subdomain>.ngrok.app/app/api" }
    ```
 
-2. `$NANO_WORKFORCE_URL`, if set (a single default; accept as-is, append `/app/api`
-   only if it is a bare origin).
+2. `$NANO_WORKFORCE_URL`, if set (a single default; append `/app/api` only if it is
+   a bare origin).
 3. Any URL the user names in the conversation.
 4. Local fallback: `http://localhost:3000/app/api` (port `PR_REVIEW_PORT`, default `3000`).
 
-### Choosing
-
-- If the user **named an instance** (by name from the registry, or by URL), use it.
-- Otherwise, **probe the candidates for reachability** and ask the user which to
-  use, offering the candidates as choices and marking which are live. Reachability
-  disambiguates the common case — off the LAN, `merlin.local` won't resolve, so the
-  tunnel instance is the live one:
+If the user named an instance, use it. Otherwise probe candidates for reachability
+and ask which to use, marking which are live:
 
-  ```bash
-  # For each candidate base, a fast liveness + identity check:
-  curl -sS --max-time 3 \
-    ${NANO_PR_WEBHOOK_SECRET:+-H "x-hook-secret: $NANO_PR_WEBHOOK_SECRET"} \
-    "$BASE/version" | jq '{appVersion, gitSha, uptimeSeconds}'
-  ```
-
-- Only skip the question when exactly **one** candidate exists and is reachable —
-  and even then, **name the instance you're about to drive** before acting.
+```bash
+curl -sS --max-time 3 \
+  ${NANO_PR_WEBHOOK_SECRET:+-H "x-hook-secret: $NANO_PR_WEBHOOK_SECRET"} \
+  "$BASE/version" | jq '{appVersion, gitSha, uptimeSeconds}'
+```
 
-Some instances guard the agent endpoints with a shared secret. If the user has
-`$NANO_PR_WEBHOOK_SECRET` set, send it as `x-hook-secret` on every request below.
+Only skip the question when exactly **one** candidate exists and is reachable — and
+even then, name the instance you're about to drive before acting. If the user has
+`$NANO_PR_WEBHOOK_SECRET` set, send it as `x-hook-secret` on every request.
 
-## 2. Fetch the live guide — this is your real playbook
+### B.2 Fetch the live guide — your real playbook
 
 ```bash
 curl -sS ${NANO_PR_WEBHOOK_SECRET:+-H "x-hook-secret: $NANO_PR_WEBHOOK_SECRET"} \
@@ -74,53 +127,47 @@ curl -sS ${NANO_PR_WEBHOOK_SECRET:+-H "x-hook-secret: $NANO_PR_WEBHOOK_SECRET"}
 ```
 
 `GET /app/api/agent` (`getAgentInstructions`) returns
-`{ format, appVersion, generatedAt, baseUrl, engineBase, instructions }`. The
-`instructions` markdown is the authoritative, version-matched operator guide, with
-every example already keyed to this instance's `baseUrl`/`engineBase`. Read it in
-full and follow it for everything that follows — orientation, submitting work,
-answering escalations, and debugging.
-
-**Always re-fetch the guide at the start of a session.** It is the source of truth;
-this skill only tells you how to find it.
-
-## 3. Orient before acting
+`{ format, appVersion, generatedAt, baseUrl, engineBase, instructions }` — the
+authoritative, version-matched operator guide, every example keyed to this
+instance. Read it in full and follow it for orientation, submitting work, answering
+escalations, and debugging. **Re-fetch it at the start of every session.** (This is
+the same prose the `getAgentInstructions` MCP tool serves in §A.)
 
-The guide's first steps confirm what is live and what is in flight:
+### B.3 Orient before acting
 
 ```bash
 curl -sS "$BASE/version" | jq   # app/urban version, git sha, uptime
 curl -sS "$BASE/status"  | jq   # every PR/instance in flight + open escalations
 ```
 
-`/status` is the primary situational-awareness endpoint — check it before you
-submit or unstick anything.
+`/status` is the primary situational-awareness endpoint — check it before you submit
+or unstick anything.
 
-## 4. What you can drive (all detailed in the live guide)
+### B.4 What you can drive (all detailed in the live guide)
 
 - **Submit a PR** for review convergence — `POST $BASE/actions/start/convergence-loop`.
-- **Submit an issue/epic** for plan → implement → converge across the fleet —
-  `POST $BASE/actions/start/plan-fanout`.
-- **Submit a delivery graph** (ADR 0005) — propose → preview → approve → dispatch.
-  Compile/preview is a pure, side-effect-free tool; only the start door dispatches.
-  The live guide documents the exact operations once the instance exposes them.
-- **Answer an escalation** (a durable user task the workforce parked on) —
-  `POST $BASE/actions/complete-user-task`, or the agent hook
-  `POST $BASE/hooks/agent-complete` (`agentCompleteEscalation`).
-- **Debug**: relate an in-flight PR to its engine process instance via `processKey`
-  from `/status`, then use the engine REST base (`engineBase` from the guide) to
-  inspect and unstick it.
+- **Submit an issue/epic** for plan → implement → converge — `POST $BASE/actions/start/plan-fanout`.
+- **Submit a delivery graph** (ADR 0005) — propose → preview → approve → **dispatch**.
+  Compile/preview is a pure, side-effect-free path; **dispatch is an operator action
+  in the cockpit**, not an agent door.
+- **Answer an escalation** — `POST $BASE/actions/complete-user-task`, or the agent
+  hook `POST $BASE/hooks/agent-complete` (`agentCompleteEscalation`).
+- **Debug** — relate an in-flight PR to its engine process instance via `processKey`
+  from `/status`, then inspect and unstick it against the engine REST base
+  (`engineBase` from the guide).
 
 ## Principles
 
-- **Discover, don't declare.** Prefer the live guide and live `/status` over any
-  assumption baked into this file. If this skill and the guide disagree, the guide
-  wins.
-- **Confirm the target instance.** Never run a side-effecting call against an
-  assumed base URL. Know — and when ambiguous, ask — which instance you're driving.
-- **Preview before dispatch.** For delivery graphs and any bulk action, use the
-  pure preview/validate path first and show the user the plan before the
-  side-effecting start call.
-- **Idempotency.** Submissions carry dedupe keys; re-submitting the same work must
-  not double-dispatch. The guide documents the keys — honour them.
-- **Escalations are for humans.** When the workforce parks on a human node, surface
-  it to the user with options; don't silently auto-answer design/product decisions.
+- **Discover, don't declare.** Prefer the live surface (MCP tools including the
+  operator-guide tool, or the live guide and `/status`) over any assumption baked into
+  this file. If this skill and the live surface disagree, the live surface wins.
+- **Confirm the target instance.** Never run a side-effecting call against an assumed
+  base URL. With MCP, name the server entry; with the fallback, know — and when
+  ambiguous, ask — which instance you're driving.
+- **Preview before dispatch.** For delivery graphs and any bulk action, use the pure
+  preview/validate path first and show the user the plan before the side-effecting
+  start. Dispatch itself is the operator's call.
+- **Idempotency.** Submissions carry dedupe keys; re-submitting the same work must not
+  double-dispatch. Honour the keys the guide documents.
+- **Escalations are for humans.** When the workforce parks on a human node, surface it
+  with options; don't silently auto-answer design/product decisions.