@nanobpm/nano-workforce 0.160.0 → 0.161.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.161.0](https://github.com/nanobpm/nano-workforce/compare/v0.160.0...v0.161.0) (2026-08-29)
+
+### Features
+
+* addressable operator guide via getAgentGuide(section?) over MCP ([#615](https://github.com/nanobpm/nano-workforce/issues/615)) ([8d59f54](https://github.com/nanobpm/nano-workforce/commit/8d59f541e25478ff7a076debc053d988f1d79b29)), closes [#611](https://github.com/nanobpm/nano-workforce/issues/611)
+
 ## [0.160.0](https://github.com/nanobpm/nano-workforce/compare/v0.159.1...v0.160.0) (2026-08-29)
 
 ### Features

package/app/agentGuide.test.ts

@@ -0,0 +1,115 @@
+// Tests for the addressable operator guide (epic #605 slice S5, issue #611): the stable section
+// registry, the fence-aware markdown splitter, the table of contents, and per-section rendering.
+// The drift guard here is the load-bearing test — it fails the build if the authored guide
+// (`docs/agent-guide.md`) grows/loses a `## ` section without a matching `GUIDE_SECTIONS` entry, so
+// the addressable surface can never silently diverge from the prose.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import {
+  GUIDE_SECTIONS,
+  guideToc,
+  renderAgentGuide,
+  renderGuideSection,
+  splitGuideSections,
+} from "./agentGuide.ts";
+
+const REPO_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const RAW_GUIDE = readFileSync(join(REPO_ROOT, "docs", "agent-guide.md"), "utf8");
+
+test("DRIFT GUARD: every `## ` section in docs/agent-guide.md has exactly one registry entry", () => {
+  const { sections } = splitGuideSections(RAW_GUIDE);
+  assertEquals(
+    sections.length,
+    GUIDE_SECTIONS.length,
+    `docs/agent-guide.md has ${sections.length} top-level sections but GUIDE_SECTIONS lists ` +
+      `${GUIDE_SECTIONS.length}. Add/remove a { id, summary } entry so the addressable surface ` +
+      "matches the prose.",
+  );
+});
+
+test("section ids are unique and non-empty; summaries are non-empty", () => {
+  const ids = new Set<string>();
+  for (const s of GUIDE_SECTIONS) {
+    assert(s.id.length > 0, "section id must be non-empty");
+    assert(!ids.has(s.id), `duplicate section id "${s.id}"`);
+    ids.add(s.id);
+    assert(s.summary.trim().length > 0, `section "${s.id}" needs a one-line summary`);
+  }
+});
+
+test("the fence-aware splitter ignores `## ` inside fenced code blocks", () => {
+  const raw = [
+    "# Title",
+    "",
+    "## 0. Real heading",
+    "body",
+    "```",
+    "## not a heading (inside a fence)",
+    "```",
+    "more body",
+    "## 1. Second heading",
+    "tail",
+  ].join("\n");
+  const { sections } = splitGuideSections(raw);
+  assertEquals(sections.length, 2);
+  assertEquals(sections[0].title, "0. Real heading");
+  assert(sections[0].body.includes("## not a heading"), "fenced content stays in its section body");
+  assertEquals(sections[1].title, "1. Second heading");
+});
+
+test("guideToc lists every registry id with a derived title and its summary", () => {
+  const toc = guideToc();
+  assertEquals(toc.length, GUIDE_SECTIONS.length);
+  for (let i = 0; i < toc.length; i++) {
+    assertEquals(toc[i].id, GUIDE_SECTIONS[i].id);
+    assertEquals(toc[i].summary, GUIDE_SECTIONS[i].summary);
+    assert(toc[i].title.length > 0, `toc[${i}] must carry the derived heading title`);
+  }
+  // The TOC is compact by construction — comfortably under any tool-result limit.
+  assert(JSON.stringify(toc).length < 4000, "the table of contents must stay small");
+});
+
+test("delivery-graphs is addressable, smaller than the full guide, and base-keyed", () => {
+  const base = "https://example.test/app/api";
+  const section = renderGuideSection("delivery-graphs", base);
+  assert(section !== undefined, "delivery-graphs must resolve");
+  const full = renderAgentGuide(base);
+  assert(section!.length > 0);
+  assert(section!.length < full.length, "a single section must be smaller than the whole guide");
+  assert(section!.length < 30000, "the delivery-graphs section must fit a typical tool-result budget");
+  assert(!section!.includes("__BASE__"), "placeholders must be substituted in a section render");
+  assert(!section!.includes("__ENGINE__"), "engine placeholder must be substituted too");
+});
+
+test("a compact section is a small fraction of the whole guide", () => {
+  const base = "https://example.test/app/api";
+  const orient = renderGuideSection("orient", base)!;
+  const full = renderAgentGuide(base);
+  assert(orient.length < full.length / 10, "the orient section must be a small fraction of the guide");
+});
+
+test("every registry id resolves to a non-empty section whose heading matches its title", () => {
+  const base = "https://example.test/app/api";
+  const toc = guideToc();
+  for (const { id, title } of toc) {
+    const md = renderGuideSection(id, base);
+    assert(md !== undefined, `section "${id}" must resolve`);
+    assert(md!.startsWith(`## ${title}`), `section "${id}" body must open with its heading`);
+  }
+});
+
+test("an unknown section id resolves to undefined (the op turns that into a 400)", () => {
+  assertEquals(renderGuideSection("does-not-exist", "https://x/app/api"), undefined);
+});
+
+test("no content regression: each section body is a verbatim slice of the raw guide", () => {
+  // Rendering keys examples to an instance; the UN-substituted section bodies must be exact
+  // substrings of the authored doc, so the addressable surface never rewrites guide content.
+  const { sections } = splitGuideSections(RAW_GUIDE);
+  for (const s of sections) {
+    assert(RAW_GUIDE.includes(s.body), `section "${s.title}" must be a verbatim slice of the guide`);
+  }
+});

package/app/agentGuide.ts

@@ -59,8 +59,117 @@ export function resolveEngineBase(): string {
 /**
  * Render the guide for a given app control-API base (e.g. "https://host/app/api"). The engine base
  * is resolved from the environment. Substitutes every `__BASE__`/`__ENGINE__` occurrence.
+ *
+ * This is the FULL guide, byte-for-byte the same content the non-MCP fallback doors serve
+ * (`GET /app/api/agent`, and — via the skill — `GET /app/api/agent/skill`). The addressable helpers
+ * below (`guideToc` / `renderGuideSection`) never touch this path, so those doors stay unchanged.
  */
 export function renderAgentGuide(apiBase: string): string {
   const base = apiBase.replace(/\/+$/, "");
   return RAW_GUIDE.replaceAll("__BASE__", base).replaceAll("__ENGINE__", resolveEngineBase());
 }
+
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// Addressable guide (epic nano-workforce#605, slice S5, issue #611).
+//
+// The full guide is ~43KB — a single `getAgentInstructions` call can exceed an agent's tool-result
+// limit, forcing it to persist the blob and carve out the section it wanted out-of-band. The guide
+// is already well-structured as top-level `## N. Title` sections, so we make each one individually
+// addressable: a compact table of contents (id + one-line summary), and per-section retrieval.
+//
+// STABLE IDS ARE THE CONTRACT. `GUIDE_SECTIONS` below is the single source of truth for the stable
+// section ids and their summaries, in document order. The section *bodies* are derived by parsing
+// the authored markdown (`docs/agent-guide.md`) at module load — never duplicated here — so prose
+// edits never drift from the addressable surface. The parity is guarded by a drift test
+// (`app/agentGuide.test.ts`): add or remove a `## ` section in the doc without updating this
+// registry and the build fails.
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+
+/** One addressable top-level guide section: a stable id and a one-line summary, in document order.
+ *  The `id` is the durable handle agents pass to `getAgentGuide(section)`; keep it stable across
+ *  prose edits (rename the heading freely, never the id). */
+export interface GuideSectionMeta {
+  readonly id: string;
+  readonly summary: string;
+}
+
+/** The stable section registry — ONE per `## N.` heading in `docs/agent-guide.md`, in order. Adding
+ *  a section to the doc requires adding an entry here (enforced by the drift test). */
+export const GUIDE_SECTIONS: readonly GuideSectionMeta[] = [
+  { id: "orient", summary: "Orient first: confirm which instance you're driving; see the live version and every PR in flight." },
+  { id: "submit-pr", summary: "Submit a PR to the review-convergence loop — review-only vs. converge-and-merge, dependency barriers, round caps." },
+  { id: "submit-epic", summary: "Hand a whole issue to the fleet: plan → implement → converge across coding agents, against a required base branch." },
+  { id: "escalations", summary: "Find and answer parked human-in-the-loop escalations (PR-review, feature, plan-review, trial-merge) by user-task key." },
+  { id: "lifecycle", summary: "The PR/epic lifecycle and status vocabulary, so you can reason about where a run currently sits." },
+  { id: "debug", summary: "Debug: find the engine process instance behind a PR and inspect its jobs, incidents, and element-instances." },
+  { id: "debug-models", summary: "Debug the deployed BPMN models and the agent prompts a running instance is actually using." },
+  { 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." },
+] as const;
+
+/** A parsed section: its stable id + summary (from the registry), the derived heading `title` (the
+ *  markdown text after `## `, e.g. "9. Author and run a delivery graph (ADR 0005)"), and the raw
+ *  section markdown `body` INCLUDING the heading line, with `__BASE__`/`__ENGINE__` un-substituted. */
+export interface ParsedGuideSection extends GuideSectionMeta {
+  readonly title: string;
+  readonly body: string;
+}
+
+/** Split raw guide markdown into its top-level `## ` sections, fence-aware (a `## ` inside a fenced
+ *  code block is content, not a heading). Everything before the first heading is the preamble.
+ *  Pure/​testable — takes the raw text so the drift test can feed it the on-disk doc directly. */
+export function splitGuideSections(raw: string): { preamble: string; sections: { title: string; body: string }[] } {
+  const lines = raw.split("\n");
+  const sections: { title: string; lines: string[] }[] = [];
+  const preambleLines: string[] = [];
+  let inFence = false;
+  let current: { title: string; lines: string[] } | null = null;
+  for (const line of lines) {
+    if (/^(```|~~~)/.test(line.trim())) inFence = !inFence;
+    const heading = !inFence ? /^## (.+)$/.exec(line) : null;
+    if (heading) {
+      current = { title: heading[1].trim(), lines: [line] };
+      sections.push(current);
+    } else if (current) {
+      current.lines.push(line);
+    } else {
+      preambleLines.push(line);
+    }
+  }
+  return {
+    preamble: preambleLines.join("\n"),
+    sections: sections.map((s) => ({ title: s.title, body: s.lines.join("\n").replace(/\s+$/, "") })),
+  };
+}
+
+/** The parsed sections of THIS deployment's guide, zipped against the stable registry, computed once
+ *  at module load. When the doc is unreadable (fallback guide, no `## ` headings) this is empty — the
+ *  addressable surface degrades to "no sections", never throws. Length/registry parity is asserted by
+ *  the drift test, not at runtime, so a mismatched deploy still serves what it can. */
+const PARSED_SECTIONS: readonly ParsedGuideSection[] = (() => {
+  const { sections } = splitGuideSections(RAW_GUIDE);
+  const n = Math.min(sections.length, GUIDE_SECTIONS.length);
+  const out: ParsedGuideSection[] = [];
+  for (let i = 0; i < n; i++) {
+    out.push({ ...GUIDE_SECTIONS[i], title: sections[i].title, body: sections[i].body });
+  }
+  return out;
+})();
+
+/** The compact table of contents: every addressable section's id, derived heading title, and stable
+ *  one-line summary, in document order. Small by construction — safe to return whole under any
+ *  tool-result limit. Titles reflect THIS deployment's doc; summaries come from the registry. */
+export function guideToc(): { id: string; title: string; summary: string }[] {
+  return PARSED_SECTIONS.map((s) => ({ id: s.id, title: s.title, summary: s.summary }));
+}
+
+/** Render a SINGLE section's markdown for a given app control-API base, `__BASE__`/`__ENGINE__`
+ *  substituted exactly as {@link renderAgentGuide} does for the whole guide. Returns `undefined` for
+ *  an unknown id (the caller turns that into a 400 listing the valid ids). */
+export function renderGuideSection(id: string, apiBase: string): string | undefined {
+  const section = PARSED_SECTIONS.find((s) => s.id === id);
+  if (!section) return undefined;
+  const base = apiBase.replace(/\/+$/, "");
+  return section.body.replaceAll("__BASE__", base).replaceAll("__ENGINE__", resolveEngineBase());
+}

package/docs/mcp-runbook.md

@@ -150,6 +150,22 @@ Agents without MCP are unchanged — resolve the instance, then
 live guide. `GET /app/api/agent` and `GET /app/api/agent/skill` keep working exactly as
 before.
 
+### Addressable guide (MCP) — `getAgentGuide`
+
+The full guide is ~43KB — a single `getAgentInstructions` call can overrun a tool-result
+limit. Over MCP, prefer the **addressable** companion tool `getAgentGuide(section?)`
+(`GET /app/api/agent/guide`):
+
+- **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.
+- **`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.
+
+The section ids are the single source of truth in `app/agentGuide.ts` (`GUIDE_SECTIONS`),
+derived-and-checked against the authored `docs/agent-guide.md`. The `getAgentInstructions`
+/ `GET /agent` full-guide door is unchanged — the addressable tool is additive.
+
 ## 6. Regression harness — pin the MCP surface from nwf's side
 
 The MCP projection layer (schema shape, argument encoding, session handshake) is

package/e2e/addressable-guide.e2e.ts

@@ -0,0 +1,89 @@
+// Addressable operator-guide regression net (epic #605 slice S5, issue #611).
+//
+// Drives the app's REAL runtime-served MCP endpoint (`/app/mcp`, ADR 0067) via the reusable
+// `e2e/support/mcp-harness.ts` module (slice S1, #607) — it does NOT re-implement the handshake.
+// It PINS the addressable-guide contract from a client's point of view:
+//
+//   • `getAgentGuide` is projected with a `$ref`-free, explicitly-typed input schema (S0 invariant);
+//   • no argument → a compact table of contents listing every stable section id + summary, small
+//     enough to fit a typical tool-result limit;
+//   • `section=<id>` → ONLY that section, far smaller than the whole guide (the defect this fixes:
+//     `getAgentInstructions` returns ~43KB that overran the limit);
+//   • an unknown id → a uniform `issues[{path,message}]` validation error;
+//   • the full-guide fallback door (`getAgentInstructions`) is UNCHANGED — still the whole guide.
+//
+// Run with `npm run e2e`.
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+import { assertSchemaSelfContained, bootMcpHarness, type McpHarness } from "./support/mcp-harness.ts";
+
+describe("S5 — the addressable operator guide over MCP (#611)", () => {
+  let h: McpHarness;
+  before(async () => {
+    h = await bootMcpHarness();
+  });
+  after(async () => {
+    await h.stop();
+  });
+
+  test("getAgentGuide is projected with a self-contained, explicitly-typed input schema", async () => {
+    const tools = await h.listTools();
+    const tool = tools.find((t) => t.name === "getAgentGuide");
+    assert(tool, "getAgentGuide must be projected onto the MCP surface");
+    assertSchemaSelfContained(tool!.inputSchema, "getAgentGuide");
+    const props = (tool!.inputSchema as { properties?: Record<string, unknown> }).properties ?? {};
+    const section = props.section as { type?: string } | undefined;
+    assert(section, "getAgentGuide must expose a `section` argument");
+    assert.equal(section!.type, "string", "`section` must be an explicitly-typed string");
+  });
+
+  test("no argument returns a compact table of contents with every section id", async () => {
+    const res = await h.callTool("getAgentGuide", {});
+    assert(!res.isError, `getAgentGuide (TOC) must not error: ${res.text}`);
+    const body = res.json as { kind?: string; sections?: { id: string; title: string; summary: string }[] };
+    assert.equal(body.kind, "toc");
+    assert(Array.isArray(body.sections) && body.sections.length > 0, "the TOC must list sections");
+    const ids = body.sections!.map((s) => s.id);
+    for (const id of ["orient", "submit-pr", "submit-epic", "escalations", "delivery-graphs"]) {
+      assert(ids.includes(id), `the TOC must list "${id}"`);
+    }
+    for (const s of body.sections!) {
+      assert(s.title.length > 0 && s.summary.length > 0, `TOC entry "${s.id}" needs a title + summary`);
+    }
+    // The whole point: the TOC is tiny relative to the ~43KB monolith.
+    assert(res.text.length < 4000, "the TOC must fit comfortably under a tool-result limit");
+  });
+
+  test("section=delivery-graphs returns ONLY that section, under a typical result budget", async () => {
+    const res = await h.callTool("getAgentGuide", { section: "delivery-graphs" });
+    assert(!res.isError, `getAgentGuide(delivery-graphs) must not error: ${res.text}`);
+    const body = res.json as { kind?: string; section?: { id: string; instructions: string } };
+    assert.equal(body.kind, "section");
+    assert.equal(body.section?.id, "delivery-graphs");
+    assert(body.section!.instructions.length > 200, "the section must carry real content");
+    assert(!body.section!.instructions.includes("__BASE__"), "placeholders must be substituted");
+
+    // It must be smaller than the full guide the fallback door still serves — a proper subset.
+    const full = await h.callTool("getAgentInstructions", {});
+    assert(res.text.length < full.text.length, "one section must be smaller than the whole guide");
+    assert(res.text.length < 30000, "one section must fit a typical tool-result budget in a single call");
+  });
+
+  test("an unknown section id is rejected with issues[{path,message}]", async () => {
+    const res = await h.callTool("getAgentGuide", { section: "no-such-section" });
+    assert(res.isError, "an unknown section id must surface as a tool-level error");
+    const body = res.json as { issues?: { path: string; message: string }[] };
+    assert(Array.isArray(body.issues) && body.issues.length >= 1, "must answer with issues[]");
+    assert.equal(body.issues![0].path, "section");
+  });
+
+  test("the full-guide fallback door is unchanged — still the whole guide", async () => {
+    const res = await h.callTool("getAgentInstructions", {});
+    assert(!res.isError, `getAgentInstructions must still answer: ${res.text}`);
+    const body = res.json as { instructions?: string };
+    assert(typeof body.instructions === "string", "getAgentInstructions still returns the full guide");
+    // The monolith still contains a section the addressable tool now carves out — no content regression.
+    assert(body.instructions!.includes("delivery graph"), "the full guide still contains every section");
+    assert(body.instructions!.length > 10000, "the full guide door is unshrunk");
+  });
+});

package/openapi.yaml

@@ -35,6 +35,37 @@ components:
       properties:
         error:
           type: string
+    ValidationError:
+      description: >-
+        The uniform validation-error contract: a human-readable `error` plus a path-qualified
+        `issues[]` naming each offending input. Returned by endpoints that reject a bad query/body
+        param (e.g. `GET /agent/guide` with an unknown `section` id).
+      type: object
+      additionalProperties: false
+      required:
+        - error
+        - issues
+      properties:
+        error:
+          type: string
+          description: A human-readable summary of the rejection.
+        issues:
+          type: array
+          minItems: 1
+          items:
+            type: object
+            additionalProperties: false
+            required:
+              - path
+              - message
+            properties:
+              path:
+                type: string
+                description: JSON-path pointer at the offending input (e.g. `section`).
+              message:
+                type: string
+                description: Human-actionable description of the failure.
+          description: The path-qualified `{ path, message }` failures (at least one).
     ActivePr:
       type: object
       description: A tracked PR that is not in a terminal (converged/abandoned) state.
@@ -881,6 +912,82 @@ components:
         skill:
           type: string
           description: The full operator skill (SKILL.md) as markdown, including its YAML frontmatter.
+    AgentGuideResponse:
+      type: object
+      description: The addressable operator-guide response served by `getAgentGuide`. Two shapes,
+        discriminated by `kind`. `kind:"toc"` (no `section` argument) carries `sections` — the compact
+        table of contents, one entry per stable section id. `kind:"section"` (a `section` id given)
+        carries `section` — that one section's markdown, with its examples keyed to this instance.
+      additionalProperties: false
+      required:
+        - kind
+        - appVersion
+        - generatedAt
+        - baseUrl
+      properties:
+        kind:
+          type: string
+          description: '"toc" when listing sections (no `section` argument); "section" when returning one.'
+          enum:
+            - toc
+            - section
+        appVersion:
+          type: string
+          nullable: true
+          description: The running app version this guide matches (null when unreadable).
+        generatedAt:
+          type: string
+          description: When this response was rendered (ISO-8601).
+        baseUrl:
+          type: string
+          description: The app control-API base the examples target (e.g. https://host/app/api).
+        engineBase:
+          type: string
+          description: The engine's Camunda-8 v2 REST base this app talks to (present on a section response).
+        sections:
+          type: array
+          description: The table of contents — present when `kind` is "toc". One entry per addressable section.
+          items:
+            type: object
+            additionalProperties: false
+            required:
+              - id
+              - title
+              - summary
+            properties:
+              id:
+                type: string
+                description: The stable section id to pass back as `getAgentGuide(section)`.
+              title:
+                type: string
+                description: The section's heading text (e.g. "9. Author and run a delivery graph (ADR 0005)").
+              summary:
+                type: string
+                description: A one-line summary of what the section covers.
+        section:
+          type: object
+          description: The requested section — present when `kind` is "section".
+          additionalProperties: false
+          required:
+            - id
+            - title
+            - format
+            - instructions
+          properties:
+            id:
+              type: string
+              description: The stable section id that was requested.
+            title:
+              type: string
+              description: The section's heading text.
+            format:
+              type: string
+              description: The `instructions` media format. Always "markdown".
+              enum:
+                - markdown
+            instructions:
+              type: string
+              description: The section's markdown, with example commands keyed to this instance.
     SubmitResult:
       type: object
       required:
@@ -3080,6 +3187,53 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /agent/guide:
+    get:
+      operationId: getAgentGuide
+      summary: The operator guide, ADDRESSABLE — fetch one section instead of the whole ~43KB blob.
+        Read-only, pure, idempotent. Call with NO `section` to get a compact table of contents (every
+        stable section id + a one-line summary); call with `section` set to a TOC id (e.g.
+        `delivery-graphs`) to get ONLY that section's markdown, small enough to fit a typical
+        tool-result limit. This is the MCP-friendly companion to `getAgentInstructions`, which still
+        returns the full guide unchanged for non-MCP callers. Typical flow — first call
+        `getAgentGuide` (no arg) to see the ids, then `getAgentGuide(section=<id>)` for the one you
+        need. An unknown id is rejected with `issues[{path,message}]` that lists the valid ids.
+      security:
+        - hookSecret: []
+        - {}
+      parameters:
+        # Self-contained tool input (epic #605 S0 convention): a single inline `type: string` query
+        # param — no `$ref`, an explicit type and example — so the projected MCP tool schema is
+        # client-usable as-is (no request body; the inline-mcp-bodies generator does not apply here).
+        - name: section
+          in: query
+          required: false
+          schema:
+            type: string
+            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
+            table of contents. An unknown id yields a 400 listing the valid ids.
+      responses:
+        "200":
+          description: Either the table of contents (no `section`) or a single section's markdown.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AgentGuideResponse"
+        "400":
+          description: The `section` id is not a known section; `issues` lists the valid ids.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ValidationError"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /actions/start/convergence-loop:
     post:
       operationId: startConvergenceLoop

package/operations/getAgentGuide.test.ts

@@ -0,0 +1,100 @@
+// Tests for GET /app/api/agent/guide → operation `getAgentGuide` (epic #605 slice S5, issue #611):
+// the addressable operator guide. No `section` → a compact table of contents; `section=<id>` → just
+// that section; an unknown id → 400 with `issues[{path,message}]`. Mirrors the getAgentInstructions
+// test's request shape and shared-secret guard pattern.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
+import { GUIDE_SECTIONS } from "../app/agentGuide.ts";
+import handler from "./getAgentGuide.ts";
+
+const app = { log: noopLog() } as any as AppApi;
+
+function input(query: Record<string, string> = {}, headers: Record<string, string> = {}) {
+  return {
+    req: {
+      method: "GET",
+      path: "/app/api/agent/guide",
+      query: new URLSearchParams(query),
+      headers: new Headers(headers),
+      text: async () => "",
+    } as any,
+    params: {},
+    query,
+    body: undefined,
+  };
+}
+
+test("no section → the table of contents, one entry per registry section", async () => {
+  const r = (await handler(input(), app)) as any;
+  assertEquals(r.status, 200);
+  assertEquals(r.body.kind, "toc");
+  assert(typeof r.body.baseUrl === "string" && r.body.baseUrl.length > 0);
+  assert(Array.isArray(r.body.sections));
+  assertEquals(r.body.sections.length, GUIDE_SECTIONS.length);
+  const ids = r.body.sections.map((s: any) => s.id);
+  for (const s of GUIDE_SECTIONS) assert(ids.includes(s.id), `TOC must list "${s.id}"`);
+  for (const s of r.body.sections) {
+    assert(typeof s.title === "string" && s.title.length > 0);
+    assert(typeof s.summary === "string" && s.summary.length > 0);
+  }
+});
+
+test("the TOC is far smaller than the full guide (fits a tool-result limit)", async () => {
+  const r = (await handler(input(), app)) as any;
+  assert(JSON.stringify(r.body).length < 4000, "the TOC response must stay compact");
+});
+
+test("section=delivery-graphs → just that section's markdown, base-keyed", async () => {
+  const r = (await handler(input({ section: "delivery-graphs" }), app)) as any;
+  assertEquals(r.status, 200);
+  assertEquals(r.body.kind, "section");
+  assertEquals(r.body.section.id, "delivery-graphs");
+  assertEquals(r.body.section.format, "markdown");
+  assert(r.body.section.instructions.length > 200);
+  assert(!r.body.section.instructions.includes("__BASE__"), "placeholders must be substituted");
+  assert(typeof r.body.engineBase === "string" && r.body.engineBase.length > 0);
+});
+
+test("a section is much smaller than the whole guide", async () => {
+  const toc = (await handler(input(), app)) as any;
+  const section = (await handler(input({ section: "orient" }), app)) as any;
+  assert(
+    JSON.stringify(section.body).length < 30000,
+    "a single section must comfortably fit a typical tool-result limit",
+  );
+  assertEquals(toc.body.kind, "toc");
+});
+
+test("an unknown section id → 400 with issues[{path,message}] listing valid ids", async () => {
+  const r = (await handler(input({ section: "nope" }), app)) as any;
+  assertEquals(r.status, 400);
+  assert(typeof r.body.error === "string");
+  assert(Array.isArray(r.body.issues) && r.body.issues.length === 1);
+  assertEquals(r.body.issues[0].path, "section");
+  assert(r.body.issues[0].message.includes("delivery-graphs"), "the 400 must name the valid ids");
+});
+
+test("blank/whitespace section is treated as no section (TOC)", async () => {
+  const r = (await handler(input({ section: "  " }), app)) as any;
+  assertEquals(r.status, 200);
+  assertEquals(r.body.kind, "toc");
+});
+
+test("shared-secret guard: rejects when the secret is set and header is wrong", async () => {
+  const prev = process.env.NANO_PR_WEBHOOK_SECRET;
+  process.env.NANO_PR_WEBHOOK_SECRET = "s3cr3t";
+  try {
+    // Re-import with the secret set so the module-level SECRET picks it up.
+    const mod = await import(`./getAgentGuide.ts?secret=${Date.now()}`);
+    const guarded = mod.default;
+    const rejected = (await guarded(input({}, {}), app)) as any;
+    assertEquals(rejected.status, 401);
+    const ok = (await guarded(input({}, { "x-hook-secret": "s3cr3t" }), app)) as any;
+    assertEquals(ok.status, 200);
+  } finally {
+    if (prev === undefined) delete process.env.NANO_PR_WEBHOOK_SECRET;
+    else process.env.NANO_PR_WEBHOOK_SECRET = prev;
+  }
+});

package/operations/getAgentGuide.ts

@@ -0,0 +1,92 @@
+// GET /app/api/agent/guide → operationId `getAgentGuide` (epic nano-workforce#605, slice S5,
+// issue #611). The ADDRESSABLE operator guide: fetch one section instead of the whole ~43KB blob
+// that `getAgentInstructions` returns (which can exceed an agent's tool-result limit, forcing it to
+// persist the blob and carve out a section out-of-band).
+//
+//   • No `section` query param → a compact table of contents: every stable section id + a one-line
+//     summary (`kind: "toc"`). Small by construction — safe under any tool-result limit.
+//   • `section=<id>` → ONLY that section's markdown (`kind: "section"`), examples keyed to THIS
+//     instance's control-API base + engine base, exactly as the full guide keys them.
+//   • An unknown id → 400 with `issues: [{ path: "section", message }]` listing the valid ids
+//     (the uniform validation-error contract).
+//
+// This is the MCP-friendly companion to `getAgentInstructions`; the full-guide doors
+// (`GET /agent`, `GET /agent/skill`) are untouched and byte-identical. Read-only, pure, idempotent.
+//
+// The optional shared-secret guard mirrors /agent and /version: enforced HERE only when
+// NANO_PR_WEBHOOK_SECRET is set (the runtime does not enforce OpenAPI `security`).
+import { guideToc, renderGuideSection, resolveEngineBase } from "../app/agentGuide.ts";
+import { resolveApiBase } from "../app/resolveApiBase.ts";
+import { buildVersionInfo, envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+export default defineOperation("getAgentGuide", ({ query, req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("getAgentGuide rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+
+  const baseUrl = resolveApiBase(req, "agent/guide");
+  const rawSection = query.section;
+  const section = typeof rawSection === "string" ? rawSection.trim() : "";
+
+  // No section → the table of contents.
+  if (!section) {
+    return {
+      status: 200,
+      body: {
+        kind: "toc",
+        appVersion: buildVersionInfo().version,
+        generatedAt: new Date().toISOString(),
+        baseUrl,
+        sections: guideToc(),
+      },
+    };
+  }
+
+  // A section id → just that section, or a 400 that names the valid ids.
+  const instructions = renderGuideSection(section, baseUrl);
+  if (instructions === undefined) {
+    // Derive the valid ids from the PARSED table of contents — the sections this deployment can
+    // actually serve — not the static registry. When the guide doc is unreadable (RAW_GUIDE
+    // fallback, no `##` headings) the TOC is empty and NO id is retrievable, so say so explicitly
+    // rather than list registry ids that would themselves 400.
+    const validIds = guideToc().map((s) => s.id);
+    const detail =
+      validIds.length > 0
+        ? `valid ids: ${validIds.join(", ")}`
+        : "no sections are available in this deployment";
+    return {
+      status: 400,
+      body: {
+        error: `unknown guide section "${section}"`,
+        issues: [
+          {
+            path: "section",
+            message: `unknown section id "${section}"; ${detail}`,
+          },
+        ],
+      },
+    };
+  }
+
+  const title = guideToc().find((s) => s.id === section)?.title ?? section;
+  return {
+    status: 200,
+    body: {
+      kind: "section",
+      appVersion: buildVersionInfo().version,
+      generatedAt: new Date().toISOString(),
+      baseUrl,
+      engineBase: resolveEngineBase(),
+      section: {
+        id: section,
+        title,
+        format: "markdown",
+        instructions,
+      },
+    },
+  };
+});

package/package.json

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