@nanobpm/nano-workforce 0.170.0 → 0.170.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.170.1](https://github.com/nanobpm/nano-workforce/compare/v0.170.0...v0.170.1) (2026-08-31)
+
+### Documentation
+
+* **agent-guide:** make the operator guide tool-aware + tool↔curl crosswalk (N1) ([#669](https://github.com/nanobpm/nano-workforce/issues/669)) ([44c5937](https://github.com/nanobpm/nano-workforce/commit/44c5937fb3a1cdaa5a106d67ed16225c35d614f6)), closes [#664](https://github.com/nanobpm/nano-workforce/issues/664) [#666](https://github.com/nanobpm/nano-workforce/issues/666) [#667](https://github.com/nanobpm/nano-workforce/issues/667) [#665](https://github.com/nanobpm/nano-workforce/issues/665) [666/#667](https://github.com/666/nano-workforce/issues/667) [#666](https://github.com/nanobpm/nano-workforce/issues/666) [#667](https://github.com/nanobpm/nano-workforce/issues/667) [#665](https://github.com/nanobpm/nano-workforce/issues/665)
+
 ## [0.170.0](https://github.com/nanobpm/nano-workforce/compare/v0.169.0...v0.170.0) (2026-08-31)
 
 ### Features

package/app/agentGuide.ts

@@ -106,6 +106,7 @@ export const GUIDE_SECTIONS: readonly GuideSectionMeta[] = [
   { id: "unstick", summary: "Unstick a wedged process — publish a correlating message, cancel, or otherwise recover a stalled instance." },
   { id: "raise-issue", summary: "Raise an issue or open a PR against the nano-workforce repository itself." },
   { id: "delivery-graphs", summary: "Author, preview, compile/stage and run an agent-authored delivery graph (ADR 0005): node/wait/connector vocabulary." },
+  { id: "tool-crosswalk", summary: "Tool↔curl crosswalk: map every guide action to its projected MCP tool (status, version, urban_debug_* engine reads, escalation answer, cancel) with the curl no-MCP fallback." },
 ] as const;
 
 /** A parsed section: its stable id + summary (from the registry), the derived heading `title` (the

package/docs/agent-guide.md

@@ -25,18 +25,28 @@ in full so you can tell which are under the control-API base and which are not.
 
 ## 0. Orient yourself first
 
-Before acting, confirm what is running and what is in flight:
+Before acting, confirm what is running and what is in flight. **Prefer the projected
+tools** (`getVersion`, `listActivePrs`); curl is the no-MCP fallback only. Every step in
+this guide that has a tool is mapped in the **tool↔curl crosswalk (§10)** — reach for the
+tool first and drop to curl only when you are not driving this instance over MCP.
 
-```bash
+```text
 # Which code is live (app version, urban version, git sha/branch, uptime):
-curl -sS __BASE__/version | jq
+tool: getVersion            # GET /version
 
 # Every PR currently in flight (not converged/abandoned), with its engine
 # process key, status, round, and any open escalation:
+tool: listActivePrs         # GET /status
+```
+
+```bash
+# No-MCP fallback (agent without the projected tools):
+curl -sS __BASE__/version | jq
 curl -sS __BASE__/status | jq
 ```
 
-`/status` is your primary situational-awareness endpoint. Each entry carries:
+`listActivePrs` (the `/status` endpoint) is your primary situational-awareness surface.
+Each entry carries:
 `prKey` (`owner/repo#123`), `status`, `round`, `processKey` (the **engine process
 instance key** — the bridge to the engine REST API, §5), `openEscalation`,
 `activeWorker`/`leaseUntil` (is an agent actually working the round, or is the job
@@ -152,24 +162,36 @@ A loop escalates only when an agent returns `needs_input`/`blocked`, or a safety
 fires (round cap, a review that never arrives, a merge conflict, an unfixable CI
 failure). The parked process waits for a human answer.
 
-Find the open escalations, then answer them:
+Find the open escalations, then answer them. **Prefer the `listEscalations` tool**
+(the projected read tool that lists every open escalation with the `userTaskKey` and form —
+tracked by sibling #666; on a deployment that predates it, use the `/status` / task-inbox
+curl fallback below —
+you need to answer it); curl is the no-MCP fallback.
+
+```text
+# Every open escalation waiting for a human, across all four kinds — each with its
+# userTaskKey, prKey, kind (elementId), question/findings/task, and formVariables:
+tool: listEscalations
+```
 
 ```bash
-# Which in-flight PRs have an open escalation waiting for a human?
+# No-MCP fallback: read the open escalations off /status …
 curl -sS __BASE__/status | jq '.prs[] | select(.openEscalation != null)
   | { prKey, status, round, openEscalation }'
 ```
 
 The four decision-required escalation kinds — **PR review-loop**, **implementation
 (feature) task**, **plan-review**, and **trial-merge** — are now native BPMN
-`userTask`s bearing a linked `.form`, all answered the same way through the **task
-inbox** surface. There is no bespoke per-kind webhook or answer page any more.
+`userTask`s bearing a linked `.form`, all answered the same way through the
+`completeUserTask` tool (a human uses the same **task inbox** surface underneath).
+There is no bespoke per-kind webhook or answer page any more.
 
-**List the open escalation tasks.** Each task carries its context (e.g. `prKey` /
-`question` / `findings` / `task`) in its `variables`, and its kind in `elementId`:
+**List the open escalation tasks.** `listEscalations` returns each open task with its
+context (`prKey` / `question` / `findings` / `task`) and its kind in `elementId` /
+`kind`, so you do **not** need to reach for the raw Tasks inbox. No-MCP fallback only:
 
 ```bash
-# Every parked escalation, across all kinds:
+# No-MCP fallback — the un-projected engine task inbox (prefer `listEscalations`):
 curl -sS __BASE__/../../tasks/api/tasks | jq '.[] | { userTaskKey, elementId, variables }'
 
 # Filter to one kind (e.g. plan-review decisions) by elementId:
@@ -187,34 +209,52 @@ answer (assignee/candidate-group and age surface on each task once assignment la
 > node then runs against the unmet dependency. See §9.2 before clearing one.
 
 **Answer a task** by completing it with the typed variables its form expects — the
-completion resumes the parked process:
+completion resumes the parked process. **Prefer the `completeUserTask` tool** (or
+`agentCompleteEscalation` when you answer as an agent assignee, ADR 0046); the
+`curl … /actions/complete-user-task` app-owned door is the no-MCP fallback.
 
-```bash
+```text
 # PR review-loop (elementId `wait-answer`, pr-escalation form):
-curl -sS -X POST __BASE__/../../tasks/api/complete -H 'content-type: application/json' \
-  -d '{ "userTaskKey": "<key>", "variables": { "answer": "Cap retries at 5 and proceed." } }'
+tool: completeUserTask { "userTaskKey": "<key>",
+                         "variables": { "answer": "Cap retries at 5 and proceed." } }
 
 # Implementation (feature) task (elementId `feature-escalation`):
 #   { "resolution": "answer", "answer": "…" }  to resume, or  { "resolution": "abandon" }
-curl -sS -X POST __BASE__/../../tasks/api/complete -H 'content-type: application/json' \
-  -d '{ "userTaskKey": "<key>", "variables": { "resolution": "answer", "answer": "Use v2." } }'
+tool: completeUserTask { "userTaskKey": "<key>",
+                         "variables": { "resolution": "answer", "answer": "Use v2." } }
 
 # Plan-review (elementId `plan-review-decision`):
 #   { "directive": "revise", "notes": "…" }  (fresh review budget)  or  { "directive": "proceed" }
-curl -sS -X POST __BASE__/../../tasks/api/complete -H 'content-type: application/json' \
-  -d '{ "userTaskKey": "<key>", "variables": { "directive": "revise", "notes": "Make issue-7 the seam." } }'
+tool: completeUserTask { "userTaskKey": "<key>",
+                         "variables": { "directive": "revise", "notes": "Make issue-7 the seam." } }
 
 # Trial-merge (elementId `trial-merge-decision`):
 #   { "action": "proceed" | "rebase" | "abandon", "notes"?: "…" }
-curl -sS -X POST __BASE__/../../tasks/api/complete -H 'content-type: application/json' \
-  -d '{ "userTaskKey": "<key>", "variables": { "action": "rebase", "notes": "Re-run after the fix." } }'
+tool: completeUserTask { "userTaskKey": "<key>",
+                         "variables": { "action": "rebase", "notes": "Re-run after the fix." } }
+```
+
+```bash
+# No-MCP fallback — the app-owned complete-user-task door (prefer the tool).
+# `variables` must carry the shape THIS task's escalation kind expects (see the per-kind
+# tool forms above): `{ answer }` here is the PR review-loop form — a feature task wants
+# `{ resolution, answer }`, plan-review `{ directive, notes }`, trial-merge `{ action, notes? }`.
+curl -sS -X POST __BASE__/actions/complete-user-task -H 'content-type: application/json' \
+  -d '{ "userTaskKey": "<key>", "variables": { "answer": "Cap retries at 5 and proceed." } }'
 ```
 
 **Answer a PR escalation** (both the review-loop `wait-answer` and the merge-loop
 `wait-merge-answer` — both are now native user tasks answered the same way, #256).
-Use the PR key's parked user task and submit the `pr-escalation` form's `{ answer }`:
+Use the PR key's parked user task and submit the `pr-escalation` form's `{ answer }`
+through the `completeUserTask` tool; curl is the no-MCP fallback:
+
+```text
+tool: completeUserTask { "userTaskKey": "<key>",
+                         "variables": { "answer": "Yes — cap the retries at 5 and proceed." } }
+```
 
 ```bash
+# No-MCP fallback:
 curl -sS -X POST __BASE__/actions/complete-user-task \
   -H 'content-type: application/json' \
   -d '{
@@ -223,9 +263,11 @@ curl -sS -X POST __BASE__/actions/complete-user-task \
       }'
 ```
 
-The `userTaskKey` comes from `GET /status` or the Tasks inbox. This is the ONE
-canonical answer door for every escalation kind; the merge loop no longer uses a
-durable `escalation-answered` message catch.
+The `userTaskKey` comes from `listEscalations` (or `GET /status`/the Tasks inbox). This
+is the ONE canonical answer door (`completeUserTask`) for every escalation kind — with
+`agentCompleteEscalation` the agent-assignee variant that records identity for
+attribution (ADR 0046); the merge loop no longer uses a durable `escalation-answered`
+message catch.
 
 If `NANO_PR_WEBHOOK_SECRET` is set on the deployment, add `-H "x-hook-secret: <secret>"`.
 
@@ -266,10 +308,35 @@ The app stores each PR/plan's engine **process instance key** in its `process_ke
 column and surfaces it as `processKey` in `/status`. That key is the join between the
 app's business view and the engine's execution view.
 
-**Find the instance for a PR:** take `processKey` from `/status`, then query the
-engine's Camunda-8 v2 REST API:
+**Find the instance for a PR:** take `processKey` from `listActivePrs` (`/status`), then
+query engine truth. **Prefer the framework `urban_debug_*` engine-debug tools** (owned by
+the nano-ide urban runtime — see the crosswalk in §10); the `curl __ENGINE__/…` engine
+REST calls are the no-MCP fallback:
+
+```text
+PK = <processKey from listActivePrs>
+
+# The instance itself (state, the BPMN process it is running, start time):
+tool: urban_debug_search_process_instances   { "filter": { "processInstanceKey": PK } }
+
+# Where is it parked? — active jobs on the instance (a CREATED senior:pr-review job
+# with a `worker` set means an agent has leased the round; none means it is queued).
+# `urban_debug_search_jobs`/`_search_variables` are projected only where the framework
+# offers them (sibling nano-ide epic); else drop to the curl door (see §10 crosswalk):
+tool: urban_debug_search_jobs                 { "filter": { "processInstanceKey": PK, "state": "CREATED" } }   # where projected
+
+# Its variables (the aggregate/job payload the engine holds):
+tool: urban_debug_search_variables           { "filter": { "processInstanceKey": PK } }   # where projected
+
+# Is it dead-in-the-water on a technical fault? — active incidents:
+tool: urban_debug_search_incidents           { "filter": { "processInstanceKey": PK, "state": "ACTIVE" } }
+
+# Which BPMN element/wait-state is it sitting on?
+tool: urban_debug_search_element_instance_wait_states { "filter": { "processInstanceKey": PK } }
+```
 
 ```bash
+# No-MCP fallback — the raw engine Camunda-8 v2 REST API:
 PK=<processKey-from-status>
 
 # The instance itself (state, the BPMN process it is running, start time):
@@ -277,8 +344,7 @@ curl -sS -X POST __ENGINE__/process-instances/search \
   -H 'content-type: application/json' \
   -d "{ \"filter\": { \"processInstanceKey\": \"$PK\" } }" | jq
 
-# Where is it parked? — active jobs on the instance (a CREATED senior:pr-review job
-# with a `worker` set means an agent has leased the round; none means it is queued):
+# Where is it parked? — active jobs on the instance:
 curl -sS -X POST __ENGINE__/jobs/search \
   -H 'content-type: application/json' \
   -d "{ \"filter\": { \"processInstanceKey\": \"$PK\", \"state\": \"CREATED\" } }" | jq
@@ -294,15 +360,23 @@ curl -sS -X POST __ENGINE__/element-instances/search \
   -d "{ \"filter\": { \"processInstanceKey\": \"$PK\" } }" | jq
 ```
 
+> The `urban_debug_search_jobs`, `urban_debug_search_variables` and
+> `urban_debug_get_process_definition_xml` reads are owned by the sibling nano-ide urban
+> epic; where a deployment's framework has not yet projected them, use the curl fallback
+> for that row. The three always-present engine reads are
+> `urban_debug_search_process_instances`, `urban_debug_search_element_instance_wait_states`
+> and `urban_debug_search_incidents`.
+
 The app already mirrors an ACTIVE incident onto the PR row (`incident`/incident
 message), so a PR that shows an incident in the UI is parked on an engine fault —
-inspect it with `incidents/search` above. If the engine is not at the default, the
-deployment's engine base is `__ENGINE__` (set via `NANOBPMN_BASE_URL` or
-`CAMUNDA_REST_ADDRESS`).
+inspect it with `urban_debug_search_incidents` (or `incidents/search`) above. If the
+engine is not at the default, the deployment's engine base is `__ENGINE__` (set via
+`NANOBPMN_BASE_URL` or `CAMUNDA_REST_ADDRESS`).
 
 **Relate an instance back to a PR:** if you have a `processKey` but not the PR, match
-it against `/status` (`.prs[] | select(.processKey == "<PK>")`). A terminal PR is no
-longer in `/status`; its instance has already completed or been cancelled.
+it against `listActivePrs`/`/status` (`.prs[] | select(.processKey == "<PK>")`). A
+terminal PR is no longer in `/status`; its instance has already completed or been
+cancelled.
 
 ---
 
@@ -311,9 +385,15 @@ longer in `/status`; its instance has already completed or been cancelled.
 The behaviour is defined by durable BPMN processes and model-authored agent prompts —
 both live in the source repo, not in the job payload.
 
-- **Processes:** `resources/processes/*.bpmn` — `convergence-loop.bpmn` (review),
-  `merge-loop.bpmn` (merge/CI-fix/rebase), `plan-fanout.bpmn` (planning),
-  `retro.bpmn`. These are the source of truth for routing. To understand *why* an
+- **Processes:** to inspect the model an instance is **actually running**, prefer the
+  framework tool **`urban_debug_get_process_definition_xml`** (owned by the sibling
+  nano-ide urban epic — see §10), which returns the deployed BPMN XML for a process
+  definition; that is engine truth and cannot drift from what is live. The repo copies
+  `resources/processes/*.bpmn` — `convergence-loop.bpmn` (review), `merge-loop.bpmn`
+  (merge/CI-fix/rebase), `plan-fanout.bpmn` (planning), `retro.bpmn` — are the
+  **source of truth in git** for routing, read them from the checkout when you want the
+  authored form (or have no MCP). They can lag a running deployment, so confirm against
+  the deployed XML when *why did this instance route here* matters. To understand *why* an
   instance went where it did, read the gateway conditions (FEEL expressions on the
   sequence flows) for the element it is parked on (§5).
 - **Prompts (agent base instructions):** `resources/prompts/*.md` — `review-round.md`,
@@ -369,11 +449,24 @@ Work through this order:
    `NANO_PR_REVIEW_WAIT_TIMEOUT` (default `PT20M`); the poller also re-nudges the
    reviewer periodically. If the reviewer bot is not provisioned on the repo, no
    review will ever land — that is a repo-config problem, not an app bug.
-5. **Cancel + resubmit** as a last resort. Cancel the instance via the app (the UI's
-   per-row Cancel, `POST /app/actions/cancel { "processInstanceKey": "<PK>" }`), which
-   marks the PR `abandoned`, then re-submit the PR (§1) to start a fresh loop. Do not
-   cancel a raw engine instance out from under the app — go through the app so its
-   record state stays consistent.
+5. **Cancel + resubmit** as a last resort. Cancel through the **app-owned** door —
+   **prefer the `cancelInstance` tool** (projected by sibling #667; the same
+   record-consistent path as the UI's per-row Cancel, `POST /app/actions/cancel
+   { "processInstanceKey": "<PK>" }`), which cancels
+   the engine instance **and** marks the PR `abandoned` so it drops out of
+   `listActivePrs`. Then re-submit the PR (§1) to start a fresh loop. **Do not** cancel a
+   raw engine instance out from under the app with the engine-level
+   `urban_debug_cancel_instance` tool (or a direct engine REST cancel) — that cancels the
+   token but leaves the PR row inconsistent. Always go through `cancelInstance` /
+   `POST /app/actions/cancel` so the app's record state stays consistent. Note the door
+   sits at `/app/actions/cancel`, **outside** the `__BASE__` control-API base (ADR 0059) —
+   until #667 projects `cancelInstance`, that curl door is the only cancel path. No-MCP
+   fallback:
+
+   ```bash
+   curl -sS -X POST __BASE__/../actions/cancel -H 'content-type: application/json' \
+     -d '{ "processInstanceKey": "<PK>" }'
+   ```
 
 ---
 
@@ -767,3 +860,66 @@ Semantics:
   `stage:"merged"` once its PR merges. So `wait[epic]` targeting a feature/epic **root issue**
   observes that thread's aggregate frontier and releases on `stage:"merged" && active:false` either
   way — see `getDeliveryGraphVocabulary` (the `epic` probe entry) for the structured contract.
+
+---
+
+## 10. Tool ↔ curl crosswalk (MCP-first, curl is the no-MCP fallback)
+
+When you drive this instance over MCP, **call the projected tool** — every recipe above
+leads with it. `curl __BASE__/…`/`curl __ENGINE__/…` is only the **no-MCP fallback** for an
+agent that has no tools (see the runbook, `docs/mcp-runbook.md` §2/§3, and [§5
+Fallback](mcp-runbook.md#5-fallback)). This table maps every guide action to its projected
+tool name and its no-MCP fallback underneath (usually a curl door; a few rows fall back to reading a repo file instead).
+
+App-owned operations (projected from this app's `openapi.yaml`; the `__BASE__` control API).
+Rows tagged *(projected by sibling #NNN)* name a tool that lands with that sibling task —
+until it does, only the curl door in the third column exists on the deployment:
+
+| Guide action | Projected tool | No-MCP fallback |
+|---|---|---|
+| Which code is live (§0) | `getVersion` | `curl __BASE__/version` |
+| Every PR in flight (§0/§5) | `listActivePrs` | `curl __BASE__/status` |
+| List open escalations (§3) | `listEscalations` *(projected by sibling #666; curl door until then)* | `curl __BASE__/../../tasks/api/tasks` (the answerable list — carries each `userTaskKey`); `/status` filtered with the jq recipe just below this table is only a quick *indicator* (it surfaces `openEscalation` as a question string, **no `userTaskKey`**, so you can't answer from it) |
+| Answer an escalation (§3) | `completeUserTask` (agent-assignee: `agentCompleteEscalation`) | `curl -X POST __BASE__/actions/complete-user-task` |
+| Cancel an instance (record-consistent) (§7) | `cancelInstance` *(projected by sibling #667; curl door until then)* | `curl -X POST __BASE__/../actions/cancel` *(the `/app/actions/cancel` door, outside `__BASE__`)* |
+| Publish a BPMN message (§7) | `postMessage` | `curl -X POST __BASE__/actions/message` |
+| The operator guide itself | `getAgentInstructions` (full) / `getAgentGuide(section?)` (addressable) | `curl __BASE__/agent` / `curl __BASE__/agent/guide` |
+
+The `listEscalations` no-MCP fallback that filters `/status` with `jq` lives here, not inside the
+table cell above: a literal `|` can't be written in a GFM table cell without escaping it as `\|`,
+and this guide is served **raw** (byte-for-byte, `__BASE__`/`__ENGINE__` aside) to no-MCP agents, so
+the escaped form would be copied verbatim and the shell would treat `\|` as a literal argument
+rather than a pipe. It's only a **quick indicator** — `/status` surfaces `openEscalation` as a
+question string with **no `userTaskKey`**, so to actually *answer* one you still need the tasks
+inbox (`curl __BASE__/../../tasks/api/tasks`) or the `listEscalations` tool for its `userTaskKey`
+(§3). It selects the same `{ prKey, status, round, openEscalation }` fields as the §3 fallback for
+consistency. Copy it from here:
+
+```sh
+curl __BASE__/status | jq '.prs[] | select(.openEscalation != null)
+  | { prKey, status, round, openEscalation }'
+```
+
+
+Framework engine-debug tools (owned by the nano-ide urban runtime, not this app; they front
+the engine's Camunda-8 v2 REST API at `__ENGINE__`). The first three are always projected;
+`urban_debug_search_jobs` / `urban_debug_search_variables` /
+`urban_debug_get_process_definition_xml` are owned by the sibling nano-ide urban epic — use
+them by name where the framework projects them, else drop to the curl door:
+
+| Guide action | Projected tool | No-MCP fallback |
+|---|---|---|
+| Search process instances (§5) | `urban_debug_search_process_instances` | `curl -X POST __ENGINE__/process-instances/search` |
+| Inspect element/wait states (§5) | `urban_debug_search_element_instance_wait_states` | `curl -X POST __ENGINE__/element-instances/search` |
+| Active incidents (§5) | `urban_debug_search_incidents` | `curl -X POST __ENGINE__/incidents/search` |
+| Jobs on an instance (§5) | `urban_debug_search_jobs` | `curl -X POST __ENGINE__/jobs/search` |
+| Instance variables (§5) | `urban_debug_search_variables` | `curl -X POST __ENGINE__/variables/search` |
+| Deployed BPMN model XML (§6) | `urban_debug_get_process_definition_xml` | read the source copy `resources/processes/*.bpmn` from the checkout |
+| Engine-level cancel — **avoid** (§7) | `urban_debug_cancel_instance` | *(use the app-owned `cancelInstance` instead — engine cancel leaves the PR row inconsistent)* |
+
+**Rule of thumb (agent-guide §5 fallback discipline):** if a row has a projected tool, use
+it; reach for its curl door only when you are genuinely not on MCP (or the tool's sibling
+task has not yet landed — see the *(projected by sibling #NNN)* tags above). The app-owned
+cancel door (`cancelInstance`, #667) is always preferred over the engine-level
+`urban_debug_cancel_instance`,
+because only the app door transitions the PR/plan record to `abandoned`.

package/docs/mcp-runbook.md

@@ -91,7 +91,14 @@ family). Ask:
 
 > *"Using workforce-local, show what's in flight and any open escalations."*
 
-The agent should call the status operation tool, not curl.
+The agent should call the status operation tool (`listActivePrs`), not curl. The operator
+guide's **tool↔curl crosswalk** (agent-guide §10, via `getAgentGuide(section="tool-crosswalk")`)
+maps every guide action to its projected tool name and the curl door underneath — so a
+tool-aware agent leads with the tool (`listActivePrs`, `getVersion`, `completeUserTask`,
+the `urban_debug_*` engine reads — plus `listEscalations` and `cancelInstance` *where the
+deployment projects them*; those two are sibling tasks #666/#667 and are not on a
+deployment that predates them, so fall back to the curl door there) and treats curl as
+the no-MCP fallback only.
 
 ## 3. Debug a wedged instance
 
@@ -99,10 +106,19 @@ The agent should call the status operation tool, not curl.
 > 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 agent has: instance search, wait states, incidents (engine truth) — plus
+`variables` where the framework projects the `urban_debug_search_variables` read
+(otherwise via the engine curl fallback) — plus
 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.
+shape. A wedge is frequently exactly a disagreement between the two planes. The guide's
+**tool↔curl crosswalk** (agent-guide §10) names each engine-truth tool
+(`urban_debug_search_process_instances` / `urban_debug_search_element_instance_wait_states`
+/ `urban_debug_search_incidents`, and where projected `urban_debug_search_jobs` /
+`urban_debug_search_variables` / `urban_debug_get_process_definition_xml`) so the agent
+reaches for the tool, not the raw `__ENGINE__` curl — and steers cancels to the app-owned
+`cancelInstance` (projected by sibling #667; until it lands, the `/app/actions/cancel`
+door the UI's Cancel uses), never the record-desyncing engine-level `urban_debug_cancel_instance`.
 
 ## 4. Guard posture
 
@@ -166,7 +182,8 @@ limit. Over MCP, prefer the **addressable** companion tool `getAgentGuide(sectio
 
 - **No argument** → a compact **table of contents**: every stable section id
   (`orient`, `submit-pr`, `submit-epic`, `escalations`, `lifecycle`, `debug`,
-  `debug-models`, `unstick`, `raise-issue`, `delivery-graphs`) with a one-line summary.
+  `debug-models`, `unstick`, `raise-issue`, `delivery-graphs`, `tool-crosswalk`) with a
+  one-line summary.
 - **`section=<id>`** → **only** that section's markdown, small enough to fit a typical
   limit. An unknown id is rejected with `issues[{path,message}]` listing the valid ids.
 

package/openapi.yaml

@@ -3628,7 +3628,7 @@ paths:
             example: delivery-graphs
           description: OPTIONAL stable section id (from the table of contents `getAgentGuide` returns
             with no argument), e.g. `orient`, `submit-pr`, `submit-epic`, `escalations`, `lifecycle`,
-            `debug`, `debug-models`, `unstick`, `raise-issue`, `delivery-graphs`. Omit it to get the
+            `debug`, `debug-models`, `unstick`, `raise-issue`, `delivery-graphs`, `tool-crosswalk`. Omit it to get the
             table of contents. An unknown id yields a 400 listing the valid ids.
       responses:
         "200":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.170.0",
+  "version": "0.170.1",
   "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",

package/pages/overview.page.json

@@ -82,9 +82,9 @@
         "variant": "ghost",
         "modal": {
           "title": "Point your agent at Nano Workforce",
-          "description": "Copy this prompt and paste it into your coding agent (Copilot, Claude, etc.). It connects the agent to this instance's MCP server \u2014 the workforce's operations become native tools (including the live operator guide as `getAgentInstructions`), so it can drive and debug your workforce; agents with no MCP client fall back to fetching the operator skill. Note: `/app/mcp` is served on the same HTTP surface as the rest of the app \u2014 reachable on loopback by default, and from a remote instance (merlin, an ngrok tunnel) only when the app is bound wide (`network.bind`) or fronted by a reverse proxy, per the MCP runbook.",
+          "description": "Copy this prompt and paste it into your coding agent (Copilot, Claude, etc.). It connects the agent to this instance's MCP server \u2014 the workforce's operations become native tools (including the live operator guide as `getAgentInstructions`, or its addressable companion `getAgentGuide(section?)` \u2014 preferred over the ~43KB blob to avoid tool-result overrun), so it can drive and debug your workforce; agents with no MCP client fall back to fetching the operator skill. Note: `/app/mcp` is served on the same HTTP surface as the rest of the app \u2014 reachable on loopback by default, and from a remote instance (merlin, an ngrok tunnel) only when the app is bound wide (`network.bind`) or fronted by a reverse proxy, per the MCP runbook.",
           "copyLabel": "Copy prompt",
-          "copyText": "Add this running Nano Workforce instance as an MCP server, then help me drive and debug my workforce \u2014 a durable orchestration app that drives pull requests to review convergence against an automated reviewer, merges them, and can take a whole issue and plan \u2192 implement \u2192 converge it across a fleet of coding agents.\n\nRegister ONE MCP server entry per instance (streamable-HTTP transport, URL {{appBase}}app/mcp). Naming the instance makes targeting the wrong one structurally impossible \u2014 its tools are namespaced under that name:\n\n    copilot mcp add --transport http workforce-local {{appBase}}app/mcp\n\nGive each instance its own entry (e.g. `workforce-merlin` for a LAN/remote node). In config form (~/.copilot/mcp-config.json or repo-scoped .mcp.json):\n\n    {\n      \"mcpServers\": {\n        \"workforce-local\": {\n          \"type\": \"http\",\n          \"url\": \"{{appBase}}app/mcp\",\n          \"tools\": [\"*\"]\n        }\n      }\n    }\n\nIf this instance is secured with a shared secret (NANO_PR_WEBHOOK_SECRET), pass it on the MCP connection \u2014 reads AND mutations both require it:\n\n    copilot mcp add --transport http workforce-local {{appBase}}app/mcp \\\n      --header \"x-hook-secret: $NANO_PR_WEBHOOK_SECRET\"\n\nIn config form, add a `headers` entry alongside `url` on that server (per the MCP runbook) \u2014 the config path has no header flag, so omitting this yields 401s:\n\n    \"headers\": { \"x-hook-secret\": \"$NANO_PR_WEBHOOK_SECRET\" }\n\nA Basic-Auth-fronted instance (behind a reverse proxy) additionally needs `Authorization: Basic \u2026` on the connection.\n\nMCP servers register at host startup \u2014 add the entry, THEN start a new session so its tools load. The `workforce-*` tools then appear (the full set of operations projected from this instance's OpenAPI contract, including the live operator guide itself as the `getAgentInstructions` read tool, plus the `urban_debug_*` family for inspecting a wedged instance's process instances, wait states, variables, and incidents).\n\nThe instance's operations are now native tools. Ask, naming the instance: \"Using workforce-local, show what's in flight and any open escalations.\" It should call the status tool, not curl. Operator-only doors (the delivery-graph stage/dispatch/dismiss lifecycle \u2014 the human click IS the approval) are deliberately not tools.\n\nNo MCP client? The curl path is unchanged \u2014 fetch and follow the live guide (the response is JSON with a `skill` markdown field), adding `-H \"x-hook-secret: <secret>\"` if this instance is secured:\n\n    curl -sS {{appBase}}app/api/agent/skill\n\nThat skill bootstraps you to this instance's live operator guide at {{appBase}}app/api/agent (the same guide MCP exposes as `getAgentInstructions`). If you find a bug or a stuck process, the guide explains how to raise an issue or a PR against nanobpm/nano-workforce."
+          "copyText": "Add this running Nano Workforce instance as an MCP server, then help me drive and debug my workforce \u2014 a durable orchestration app that drives pull requests to review convergence against an automated reviewer, merges them, and can take a whole issue and plan \u2192 implement \u2192 converge it across a fleet of coding agents.\n\nRegister ONE MCP server entry per instance (streamable-HTTP transport, URL {{appBase}}app/mcp). Naming the instance makes targeting the wrong one structurally impossible \u2014 its tools are namespaced under that name:\n\n    copilot mcp add --transport http workforce-local {{appBase}}app/mcp\n\nGive each instance its own entry (e.g. `workforce-merlin` for a LAN/remote node). In config form (~/.copilot/mcp-config.json or repo-scoped .mcp.json):\n\n    {\n      \"mcpServers\": {\n        \"workforce-local\": {\n          \"type\": \"http\",\n          \"url\": \"{{appBase}}app/mcp\",\n          \"tools\": [\"*\"]\n        }\n      }\n    }\n\nIf this instance is secured with a shared secret (NANO_PR_WEBHOOK_SECRET), pass it on the MCP connection \u2014 reads AND mutations both require it:\n\n    copilot mcp add --transport http workforce-local {{appBase}}app/mcp \\\n      --header \"x-hook-secret: $NANO_PR_WEBHOOK_SECRET\"\n\nIn config form, add a `headers` entry alongside `url` on that server (per the MCP runbook) \u2014 the config path has no header flag, so omitting this yields 401s:\n\n    \"headers\": { \"x-hook-secret\": \"$NANO_PR_WEBHOOK_SECRET\" }\n\nA Basic-Auth-fronted instance (behind a reverse proxy) additionally needs `Authorization: Basic \u2026` on the connection.\n\nMCP servers register at host startup \u2014 add the entry, THEN start a new session so its tools load. The `workforce-*` tools then appear (the full set of operations projected from this instance's OpenAPI contract, including the live operator guide itself as the `getAgentInstructions` read tool \u2014 or its addressable companion `getAgentGuide(section?)`, which the MCP runbook recommends over the ~43KB blob to avoid tool-result overrun \u2014 plus the `urban_debug_*` family for inspecting a wedged instance's process instances, wait states, and incidents).\n\nThe instance's operations are now native tools. Ask, naming the instance: \"Using workforce-local, show what's in flight and any open escalations.\" It should call the status tool, not curl. Operator-only doors (the delivery-graph stage/dispatch/dismiss lifecycle \u2014 the human click IS the approval) are deliberately not tools.\n\nNo MCP client? The curl path is unchanged \u2014 fetch and follow the live guide (the response is JSON with a `skill` markdown field), adding `-H \"x-hook-secret: <secret>\"` if this instance is secured:\n\n    curl -sS {{appBase}}app/api/agent/skill\n\nThat skill bootstraps you to this instance's live operator guide at {{appBase}}app/api/agent (the same guide MCP exposes as `getAgentInstructions`, or section-addressably as `getAgentGuide`). If you find a bug or a stuck process, the guide explains how to raise an issue or a PR against nanobpm/nano-workforce."
         }
       }
     },