@nanobpm/nano-workforce 0.160.0 → 0.162.0

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:
@@ -2353,6 +2460,71 @@ components:
           description: >-
             A NAVIGATIONAL cockpit deep-link to the staged proposal (helps the agent hand the human a
             link). It is a pointer only — NOT a dispatch handle; nothing in this response can start a run.
+    SequenceIssuesIntent:
+      description: >-
+        The `sequenceIssues` INTENT (epic nano-workforce#605, S4) — a high-level shape that GENERATES
+        the canonical "implement issue → converge → merge" delivery graph (operator-guide §9.4) instead
+        of making an agent hand-author its node/edge JSON. It names an ordered list of `issues` to
+        sequence (each issue's implementation starts once the PRIOR issue has merged) and an OPTIONAL
+        leading `behind` gate (wait for that issue/epic/feature to be fully merged first, §9.5). The
+        door GENERATES, then STAGES the graph through the same compile+stage flow as
+        `compileDeliveryGraph` — it never dispatches (dispatch is an operator-only cockpit action, ADR
+        0005 Decision 7). For each issue it emits `agent` (`senior:feature`, emits a `pr` fact) →
+        `connector` (`converge-merge`, late-binding that `pr`) → `wait[pr, merged]` (a realistic
+        `poll.timeoutMs`), threading the `pr` fact per §9.4. Invalid input (empty `issues`, an
+        unparseable ref) is a 400 carrying `issues: [{ path, message }]`; nothing is staged.
+      type: object
+      additionalProperties: false
+      example:
+        behind: nanobpm/nano-ide#488
+        issues:
+          - nanobpm/nano-workforce#567
+          - nanobpm/nano-workforce#568
+      required:
+        - issues
+      properties:
+        behind:
+          type: string
+          minLength: 1
+          maxLength: 255
+          description: >-
+            OPTIONAL gate — an `owner/repo#NN` issue/epic/feature reference. When present, a leading
+            `wait[epic]` node gates the whole sequence on that reference reaching "fully merged" (every
+            opened slice/PR landed, §9.5) before the first issue's implementation starts.
+        issues:
+          type: array
+          minItems: 1
+          maxItems: 64
+          items:
+            type: string
+            minLength: 1
+            maxLength: 255
+            description: An `owner/repo#N` issue reference to implement + converge + merge, in sequence.
+          description: >-
+            The ordered issues to sequence — each is implemented by a `senior:feature` agent that opens
+            a PR, driven to convergence + merge, and the NEXT issue's implementation starts only once
+            the prior issue has merged. At least one; at most 64 (keeps the generated graph within the
+            compiler's node ceiling).
+    SequenceIssuesRejected:
+      description: >-
+        A rejected `sequenceIssues` intent — the input failed validation (empty/oversized `issues`, an
+        unparseable `owner/repo#N` reference, or an unknown target/probe per the delivery-graph
+        vocabulary). Every failure is path-qualified so the caller can fix the exact offending input.
+        Nothing was generated or staged.
+      type: object
+      additionalProperties: false
+      required:
+        - error
+        - issues
+      properties:
+        error:
+          type: string
+          description: A human-readable summary of why the intent was rejected.
+        issues:
+          type: array
+          items:
+            $ref: "#/components/schemas/DeliveryCompileError"
+          description: The path-qualified validation failures (at least one).
     FeatureStart:
       description: The start-feature request body — a SINGLE-issue feature run. Names the target issue
         by EXACTLY ONE of `issue` (an `owner/repo#123` reference) or `url` (a bare issue URL), plus a
@@ -3080,6 +3252,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
@@ -3338,6 +3557,83 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /actions/start/sequence-issues:
+    post:
+      operationId: sequenceIssues
+      summary: Generate + STAGE the canonical "implement issue → converge → merge" delivery graph from a high-level intent (never dispatches). (epic #605 / S4)
+      description: >-
+        An INTENT-SHAPED door (epic nano-workforce#605, S4). ADR 0005's delivery graph is a closed
+        vocabulary and operator-guide §9.4 already names the canonical shape for "implement issue →
+        converge → merge", but an agent still had to hand-author the full node/edge JSON — sequencing
+        four issues behind a gate meant constructing 13 nodes and 12 edges by hand. This door takes the
+        high-level intent `{ behind?, issues[] }` and GENERATES that canonical graph, then STAGES it
+        through the SAME compile+stage flow the raw `compileDeliveryGraph` door uses (one compiler, one
+        staging path — idempotency + digest inherited, not re-implemented). It returns a preview and a
+        navigational `reviewUrl` and NOTHING that can trigger a run: dispatch is an OPERATOR action in
+        the cockpit (ADR 0005 Decision 7 / issue #460).
+
+
+        For each issue it emits the canonical chain — `agent` (`senior:feature`, emits a typed `pr`
+        fact) → `connector` (`converge-merge`, late-binding that `pr`) → `wait[pr, merged]` (a realistic
+        `poll.timeoutMs`) — and threads the `pr` fact along fact-qualified edges (§9.4). The issues run
+        in SEQUENCE: each issue's implementation starts once the PRIOR issue has merged. When `behind`
+        is given, a leading `wait[epic]` gate (§9.5) makes the whole sequence wait for that reference to
+        be fully merged first.
+
+
+        INPUT — the intent OBJECT `{ "issues": ["owner/repo#A", …] }` with an OPTIONAL
+        `"behind": "owner/repo#NN"` gate (this is the object-body door). SIDE EFFECTS — impure: a valid intent is STAGED as a proposal.
+        IDEMPOTENCY — content-addressed by the compiled `digest` (an identical intent re-stages the same
+        digest). VALIDATION — invalid input (empty `issues`, an unparseable `owner/repo#N` reference, an
+        unknown target/probe per the S3 vocabulary) is a `400` with `issues: [{ path, message }]`;
+        nothing is staged. NEXT — surface the returned `reviewUrl` to the operator; poll
+        `listStagedProposals` to see the staged digest.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              # BEGIN generated:mcp-body source=#/components/schemas/SequenceIssuesIntent (scripts/inline-mcp-bodies.ts — do not hand-edit)
+              description: 'The `sequenceIssues` INTENT (epic nano-workforce#605, S4) — a high-level shape that GENERATES the canonical "implement issue → converge → merge" delivery graph (operator-guide §9.4) instead of making an agent hand-author its node/edge JSON. It names an ordered list of `issues` to sequence (each issue''s implementation starts once the PRIOR issue has merged) and an OPTIONAL leading `behind` gate (wait for that issue/epic/feature to be fully merged first, §9.5). The door GENERATES, then STAGES the graph through the same compile+stage flow as `compileDeliveryGraph` — it never dispatches (dispatch is an operator-only cockpit action, ADR 0005 Decision 7). For each issue it emits `agent` (`senior:feature`, emits a `pr` fact) → `connector` (`converge-merge`, late-binding that `pr`) → `wait[pr, merged]` (a realistic `poll.timeoutMs`), threading the `pr` fact per §9.4. Invalid input (empty `issues`, an unparseable ref) is a 400 carrying `issues: [{ path, message }]`; nothing is staged.'
+              type: object
+              additionalProperties: false
+              example:
+                behind: nanobpm/nano-ide#488
+                issues:
+                  - nanobpm/nano-workforce#567
+                  - nanobpm/nano-workforce#568
+              required:
+                - issues
+              properties:
+                behind:
+                  type: string
+                  minLength: 1
+                  maxLength: 255
+                  description: OPTIONAL gate — an `owner/repo#NN` issue/epic/feature reference. When present, a leading `wait[epic]` node gates the whole sequence on that reference reaching "fully merged" (every opened slice/PR landed, §9.5) before the first issue's implementation starts.
+                issues:
+                  type: array
+                  minItems: 1
+                  maxItems: 64
+                  items:
+                    type: string
+                    minLength: 1
+                    maxLength: 255
+                    description: An `owner/repo#N` issue reference to implement + converge + merge, in sequence.
+                  description: The ordered issues to sequence — each is implemented by a `senior:feature` agent that opens a PR, driven to convergence + merge, and the NEXT issue's implementation starts only once the prior issue has merged. At least one; at most 64 (keeps the generated graph within the compiler's node ceiling).
+              # END generated:mcp-body
+      responses:
+        "200":
+          description: The intent generated a valid delivery graph — it compiled and is STAGED for operator review; the response carries a preview and a navigational reviewUrl (no dispatch handle).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CompileDeliveryGraphStaged"
+        "400":
+          description: The intent was invalid (empty/oversized issues, an unparseable reference, or an unknown target/probe) — path-qualified issues, nothing generated or staged.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SequenceIssuesRejected"
   /actions/compile-delivery-graph:
     post:
       operationId: compileDeliveryGraph

package/operations/compileDeliveryGraph.ts

@@ -12,74 +12,36 @@
 // cockpit; the response tells the agent its role ends here, turning the boundary into a self-documenting
 // protocol. A malformed graph is a 400 carrying path-qualified errors; nothing is staged.
 
-import { compileDeliveryGraph } from "../app/deliveryGraphCompiler.ts";
-import {
-  buildProposalPreview,
-  buildProposalRow,
-  proposalLogicalKey,
-  proposalReviewUrl,
-  stageProposal,
-} from "../app/deliveryGraphProposals.ts";
-import { deliveryGraphDigest } from "../app/deliveryRunner.ts";
+import { compileAndStageDeliveryGraph } from "../app/deliveryGraphStage.ts";
 import { resolvePublicOrigin } from "../app/resolveApiBase.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
-const STAGED_MESSAGE =
-  "The graph compiled and is staged for operator review. Ask the operator to preview and approve — or request modifications — in the cockpit. Dispatch is an operator action; there is no start endpoint.";
-
 export default defineOperation("compileDeliveryGraph", async ({ body, req }, app) => {
-  // The runtime validates the body's SHAPE against `DeliveryGraph` before we run; the compiler adds
-  // the SEMANTIC checks (acyclicity, edge integrity, fact resolution). A directly-invoked delegate
-  // could still pass `undefined` — the compiler reads its input as `unknown` and maps that to a clean
-  // `ok:false`, never a 500.
-  const result = await compileDeliveryGraph(body);
-  if (!result.ok) {
-    app.log.warn("compile-delivery-graph rejected", { errors: result.errors.length });
-    return { status: 400, body: result };
-  }
-
-  // Persist the compiled graph as a `staged` proposal — the agent's surface ends here. Superseded by
-  // logical key + TTL inside `stageProposal`.
-  const digest = deliveryGraphDigest(result.bpmn);
-  const name =
-    typeof result.resolved.name === "string" && result.resolved.name.trim() !== ""
-      ? result.resolved.name.trim()
-      : null;
-  const preview = buildProposalPreview(result);
-  await stageProposal(
+  // The runtime validates the body's SHAPE against `DeliveryGraph` before we run; the shared
+  // compile+stage flow adds the SEMANTIC checks (acyclicity, edge integrity, fact resolution) and,
+  // when valid, persists the compiled graph as a `staged` proposal. A directly-invoked delegate could
+  // still pass `undefined` — the compiler reads its input as `unknown` and maps that to a clean
+  // `ok:false`, never a 500. The navigational `reviewUrl` is keyed to the ORIGIN this request arrived
+  // on (tunnel, proxy prefix, …), not the static deployment-wide NANO_WORKFORCE_BASE_URL, so the
+  // operator driving this instance can actually open it (#577).
+  const staged = await compileAndStageDeliveryGraph(
     app.data,
-    buildProposalRow({
-      digest,
-      logicalKey: proposalLogicalKey(name, digest),
-      title: name,
-      graphJson: JSON.stringify(body),
-      preview,
-      nodeCount: result.resolved.nodes.length,
-      humanNodeCount: result.humanNodes.length,
-      sideEffectCount: result.sideEffects.length,
-      sideEffecting: result.sideEffects.length > 0,
-    }),
+    body,
+    JSON.stringify(body),
+    resolvePublicOrigin(req),
   );
+  if (!staged.ok) {
+    app.log.warn("compile-delivery-graph rejected", { errors: staged.body.errors.length });
+    return { status: 400, body: staged.body };
+  }
 
   app.log.info("compile-delivery-graph staged", {
-    digest,
-    nodes: result.resolved.nodes.length,
-    humanNodes: result.humanNodes.length,
-    sideEffects: result.sideEffects.length,
+    digest: staged.digest,
+    nodes: staged.nodeCount,
+    humanNodes: staged.humanNodeCount,
+    sideEffects: staged.sideEffectCount,
   });
 
   // The response carries a preview + a navigational pointer and NO dispatch handle (issue #460).
-  return {
-    status: 200,
-    body: {
-      status: "ready",
-      message: STAGED_MESSAGE,
-      digest,
-      preview,
-      // Navigational, human-facing link → keyed to the ORIGIN this request arrived on (tunnel,
-      // proxy prefix, …), not the static deployment-wide NANO_WORKFORCE_BASE_URL, so the operator
-      // driving this instance can actually open it (#577).
-      reviewUrl: proposalReviewUrl(digest, resolvePublicOrigin(req)),
-    },
-  };
+  return { status: staged.status, body: staged.body };
 });

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,
+      },
+    },
+  };
+});