@thehammer/danx-dashboard-mcp 0.1.162 → 0.1.164

package/dist/index.js

@@ -11,49 +11,23 @@
  * Tool surface (all exposed as `mcp__danx-dashboard__<name>` once wired
  * through the workspace `mcp.template.json`):
  *
- *   - issue_list             GET    /api/issues
- *   - issue_get              GET    /api/issues/:id | /api/issues/batch (DX-2727 ids[] batch;
- *                            DX-3426 `fields` is a recursive field TREE, not a flat group list —
- *                            see `resource_fields` below and `./field-tree.ts`)
+ *   - danxbot_api            the generic surface for every non-agent-specific dashboard
+ *                            operation (DX-3465 / PLN-11 R-25) — list/get/create/update/delete
+ *                            against the uniform resource routes that used to each have their
+ *                            own per-operation tool (issue_*, plan_* (except plan_connect),
+ *                            brief_*, repo_knowledge_*, failure_category_*,
+ *                            dispatch_transcript_search, quality_gate_instruction — all deleted
+ *                            here). See `SERVER_INSTRUCTIONS` below for the calling convention.
+ *   - danxbot_api_list       lists the routes your credential may call, one line each (DX-3465
+ *                            A5, backed by DX-3528's permission-aware discovery). Call this
+ *                            first to find the route for something you need to do.
+ *   - danxbot_api_spec       discovers the exact request/response shape of any route
+ *                            `danxbot_api` can call, before calling it.
  *   - resource_fields        GET    /api/resources/:resource/fields (DX-3426 — what `fields` may
  *                            name for a resource; install-global, no `board`)
- *   - issue_create           POST   /api/issues
- *   - issue_edit             PATCH  /api/issues/:id/edit
- *   - issue_transition       POST   /api/issues/:id/transition
- *   - issue_triage           POST   /api/issues/:id/triage
- *   - issue_comment          POST/PATCH/DELETE /api/issues/:id/comments[/:cid]
- *   - issue_checklist        POST/PATCH/DELETE /api/issues/:id/checklists[/:cid[/items[/:iid]]]
- *   - issue_problem          GET/POST/PATCH/DELETE /api/issues/:id/problems[/:pid] (DX-2735)
- *   - issue_solution         POST/PATCH/DELETE /api/issues/:id/problems/:pid/solutions[/:sid][/steps[/:stepId]] (DX-2735, steps DX-3310)
- *   - issue_dependency       POST/DELETE /api/issues/:id/dependencies[/:did]
- *   - issue_retire_branch    POST   /api/issues/:id/card-branch-retire (DX-2845)
- *   - issue_quality_gate     POST   /api/issues/:id/quality-gates/:gate
- *   - issue_quality_gate_verdict
- *                            PATCH  /api/issues/:id/quality-gates/:gate
- *   - issue_retro            PUT    /api/issues/:id/retro
- *   - issue_attach           POST   /api/issues/:id/attachments (reads a local file)
- *   - quality_gate_instruction
- *                            GET    /api/quality-gates/:gate/instruction (DX-3341, not card-scoped)
- *   - plan_list              GET    /api/plans (DX-2683)
- *   - plan_get               GET    /api/plans/:id/full | /api/plans/mine (DX-2727: bare = scalars only, fields= opts in)
- *   - plan_create            POST   /api/plans
- *   - plan_connect           POST   /api/plan-sessions/me/plan
- *   - plan_add_record        POST   /api/plans/mine/records
- *   - plan_get_record        GET    /api/plans/mine/records/:rid (DX-2681 follow-up)
- *   - plan_update_record     PATCH  /api/plans/mine/records/:rid (DX-2681 follow-up)
- *   - plan_delete_record     DELETE /api/plans/mine/records/:rid (DX-2681 follow-up)
- *   - plan_add_card          POST   /api/plans/mine/cards
- *   - plan_remove_card       DELETE /api/plans/:plan_id/cards/:card_id (DX-2740)
- *   - plan_rename            PATCH  /api/plans/:plan_id (DX-2740)
- *   - plan_get_architecture_section     GET    /api/plans/mine/architecture/sections/:sid (DX-2726)
- *   - plan_add_architecture_section     POST   /api/plans/mine/architecture/sections (DX-2726)
- *   - plan_update_architecture_section  PATCH  /api/plans/mine/architecture/sections/:sid (DX-2726)
- *   - plan_delete_architecture_section  DELETE /api/plans/mine/architecture/sections/:sid (DX-2726)
- *   - plan_reorder_architecture_section PUT    /api/plans/mine/architecture/sections/reorder (DX-2726)
- *   - failure_category_list     GET    /api/failure-categories (DX-2791/DX-2792, board-less)
- *   - failure_category_create   POST   /api/failure-categories (DX-2791/DX-2792, board-less)
- *   - failure_category_update   PATCH  /api/failure-categories/:id (DX-2791/DX-2792, board-less)
- *   - dispatch_transcript_search  GET  /api/dispatches/:id/logs (DX-3221 — search/tail, no new route)
+ *   - plan_connect           POST   /api/plan-sessions/me/plan — SESSION-BOUND (kept as a
+ *                            dedicated tool; every other plan_* operation goes through
+ *                            danxbot_api now)
  *
  * DX-2683 — THE PLAN TOOLS ARE SESSION-BOUND, and asymmetrically so. Reads
  * may name any plan; WRITES take no plan id at all and act on the plan this
@@ -98,16 +72,15 @@ import { isEntrypointModule } from "./entrypoint.js";
 import { BRIDGE_SUBCOMMAND, runBridgeCommand } from "./bridge.js";
 import { PLAN_STATE_SUBCOMMAND, runPlanStateCommand } from "./plan-state.js";
 import { BACKGROUND_WORK_SUBCOMMAND, runBackgroundWorkCommand } from "./background-work.js";
-import { MANTRA_SUBCOMMAND, runMantraCommand } from "./mantra.js";
+import { EVENT_TEXT_SUBCOMMAND, runEventTextCommand } from "./event-text.js";
 import { resolveDeclaredCredential } from "./credential.js";
 import { recordSessionConnectionAfterConnect } from "./session-connection.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { DashboardHttpClient } from "./http-client.js";
-import { issueAttach, issueChecklist, issueComment, issueCreate, issueDependency, issueEdit, issueGet, issueList, issueProblem, issueQualityGate, issueQualityGateVerdict, issueRetireBranch, issueRetro, issueSolution, issueTransition, issueTriage, failureCategoryCreate, failureCategoryList, failureCategoryUpdate, dispatchTranscriptSearch, planAddArchitectureSection, planAddCard, planAddNote, planAddRecord, planConnect, planCreate, planDeleteArchitectureSection, planDeleteNote, planDeleteRecord, planGet, PLAN_STATUSES, ISSUE_BATCH_GET_MAX, LIST_PAGE_MAX_LIMIT, planGetArchitectureSection, planGetRecord, planList, planRemoveCard, planRename, planReorderArchitectureSection, planUpdateArchitectureSection, planUpdateNote, planUpdateRecord, qualityGateInstruction, resourceFields, } from "./handlers.js";
-import { PRIORITY_TIER_WORDS } from "./priority.js";
-import { fieldTreeSchema } from "./field-tree.js";
+import { planConnect, resourceFields, danxbotApi, danxbotApiList, danxbotApiSpec, attachFile, DANXBOT_API_METHODS, } from "./handlers.js";
+import { registerLifecycleTools, applyLifecycleVisibility, readLifecycleUrlsFromEnv, } from "./lifecycle.js";
 function readEnvOrDie(name) {
     const v = process.env[name];
     if (typeof v !== "string" || v === "") {
@@ -168,6 +141,14 @@ function boot() {
         fingerprint: credential.fingerprint,
     };
     client = new DashboardHttpClient(config);
+    // DX-3465 (PLN-11 R-25) — the lifecycle tool set's per-tool visibility is
+    // per-dispatch, not static: a tool whose callback URL wasn't injected for
+    // THIS dispatch must not even be advertised (mirrors the old standalone
+    // server's `buildActiveTools`). Applied here (inside `boot()`, before
+    // `server.connect()`) so the DX-1606 tool-defs generator — which imports
+    // this module WITHOUT calling `boot()` — still sees every lifecycle tool
+    // registered and enabled for token-cost accounting.
+    applyLifecycleVisibility(lifecycleTools, readLifecycleUrlsFromEnv());
 }
 /**
  * DX-2862 — the credential, through the ONE resolver the `bridge` subcommand
@@ -219,10 +200,66 @@ function readSessionConfig() {
         return undefined;
     return { id };
 }
+/**
+ * DX-3465 (PLN-11 R-25) — the ONE home for prose that used to be repeated
+ * (or would otherwise need repeating) on every per-operation tool this
+ * server exposes, now that `danxbot_api` is the generic surface for
+ * everything that is not agent-specific (R-25). Read this before your first
+ * `danxbot_api` call.
+ *
+ * Per-tool descriptions stay minimal — this block is where the shared rules
+ * live, once.
+ */
+const SERVER_INSTRUCTIONS = `\
+danx-dashboard-mcp — reach the dashboard API through danxbot_api; find a route with danxbot_api_list; discover
+its shape through danxbot_api_spec.
+
+UNIFORM RESOURCE SHAPE. Most dashboard resources (cards, plans, records, comments, problems, ...) follow the
+same four verbs:
+  - list   GET  <collection>            — filter/sort/limit/offset; the default row is minimal scalars,
+                                           opt into more with \`fields\`.
+  - get    GET  <collection>/:id        — one resource; \`fields\` opts into relations/heavy data the same way.
+  - create POST <collection>            — the resource's own required fields; a 400 names any missing/invalid one.
+  - update PATCH/PUT <collection>/:id   — send only the fields you are changing; most resources require the
+                                           concurrency token below when the edit touches contested text fields.
+  - delete DELETE <collection>/:id      — usually a soft-delete; the resource's own docs say so.
+Don't know the route for what you need to do? Call \`danxbot_api_list()\` — it lists exactly the routes your
+credential may call, one line each. Then call \`danxbot_api_spec({endpoints: ["METHOD /path/template"]})\` for the
+EXACT current shape of the one(s) you picked, before calling them through \`danxbot_api\` — request/response
+schema, required permission, and every documented error envelope. Never guess a field name or a route path.
+
+ALWAYS PASS \`fields\`. The default response for a list/get route is minimal — scalars only, no relations, no
+heavy text. Every resource that supports it takes a \`fields\` query param (a field tree, or a flat group list on
+an older route) that opts into exactly what you need. Passing nothing and then being surprised a field is
+missing is a caller bug, not a server one — check the spec for the resource's own field vocabulary.
+
+THE STALE-HASH RULE. A write that touches contested text (a card's title/description/checklists, a plan
+record, a problem, ...) is optimistic-concurrency guarded by a \`content_hash\` / \`base_hash\` you must have read
+FIRST (from the same resource's own \`get\`/\`list\` response) and send back unchanged. A stale hash 409s with the
+CURRENT hash and CURRENT content in the body — re-read, merge, retry with the fresh hash. Never retry blindly
+with the same stale value, and never omit the hash hoping the write "just works" — omission is refused exactly
+like a stale value on any route that requires one.
+
+A 4XX BODY NAMES THE FIX. Every refusal is structured, never a bare string: \`{error, ...extra}\`, where the
+extra fields tell you exactly what to do next — \`offending_keys\` (an unknown/invalid field, by name),
+\`failed_gate\` (which lifecycle/dispatch gate blocked a transition), \`currentHash\`/\`currentContent\` (a stale-
+hash 409, ready to merge from), \`unresolved_items\` (which checklist items still block completion). Read the
+body before retrying — the shape is the same one \`danxbot_api_spec\` documents per route, so a persistent 4xx
+you don't understand means re-checking the spec, not repeating the same call.
+
+WRITING STANDARD — for any tool that writes prose onto a card, plan record, or problem (title, summary,
+description, context, a problem's statement, a solution's body, ...). The reader is new to the subject and has
+not read, and will not read, the code or docs: what you write IS their documentation. Define any term a
+newcomer would not know where it first appears. Open with plain background — what the thing is, why it exists,
+what is wrong or what the choice changes — before evidence or technical detail. Cite ids/SHAs/paths precisely
+rather than describing them vaguely ("the migration file" → the actual filename). Be brief: the goal is less to
+read, not more, not a transcript of your reasoning. A summary/title alone must let the reader decide without
+opening the description.
+`;
 export const server = new McpServer({
     name: "danx-dashboard-mcp",
     version: "0.1.0",
-});
+}, { instructions: SERVER_INSTRUCTIONS });
 function jsonResult(value) {
     return {
         content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
@@ -234,8 +271,8 @@ function jsonResult(value) {
  * shape, cb)` builds its input schema as a bare `z.object(shape)` internally
  * (via the SDK's own `objectFromShape`), and zod's default behaviour for an
  * object schema is to STRIP any key not in `shape` — so a caller's typo (or a
- * field the route accepts but this tool never declared, e.g. `issue_create`'s
- * `priority` before this card) vanished before the HTTP request was even
+ * field the route accepts but this tool never declared, e.g. the issue-create
+ * route's `priority` before this card) vanished before the HTTP request was even
  * built, and the server's own fail-loud checks (e.g. `parseFilterObject`'s
  * "Unknown filter key" 400) never got a chance to run.
  *
@@ -252,55 +289,13 @@ function jsonResult(value) {
 function strictTool(name, description, shape, cb) {
     return server.registerTool(name, { description, inputSchema: z.object(shape).strict() }, cb);
 }
-// Effort + verdict + action tuples kept in lockstep with the v2 write
-// handlers. Drift surfaces at runtime as a server 400 — not silently
-// wrong data — but pinning them here gets the failure caught at the
-// MCP boundary before the round-trip.
-const EFFORT_VALUES = [
-    "min",
-    "very_low",
-    "low",
-    "medium",
-    "high",
-    "very_high",
-    "max",
-];
-// DX-2479 — `Task` is a planning record: a leaf card the dispatcher can never
-// pick up. Convert it to a Story/Bug/Chore via `issue_edit({type:"Story"})`
-// (DX-2484 wired `type` onto that tool's schema — see the issue_edit
-// registration below). Accepted everywhere a type is, so a planning card can
-// still be CREATED through this MCP.
-const ISSUE_TYPES = ["Epic", "Bug", "Feature", "Story", "Chore", "Task"];
-const NON_EPIC_TYPES = ["Bug", "Feature", "Story", "Chore", "Task"];
-const SORT_ORDERS = ["asc", "desc"];
-const sortField = z
-    .array(z.object({
-    column: z.string().min(1),
-    order: z.enum(SORT_ORDERS),
-}).strict())
-    .optional()
-    .describe("Multi-column sort — ordered list of {column, order}. Absent → the server's default order (priority desc (higher priority=most urgent first), repo_name asc, with a numeric-id tiebreaker always appended).");
-// DX-1290 — the uniform checklist-item status, extended DX-2653 with
-// `deferred` (a named real-world/post-deploy check still outstanding).
-// Terminal = passing|cancelled|deferred.
-const CHECKLIST_ITEM_STATUSES = [
-    "incomplete",
-    "failing",
-    "passing",
-    "cancelled",
-    "deferred",
-];
-const TRANSITION_ACTIONS = [
-    "ready",
-    "pickup",
-    "rollback_pickup",
-    "complete",
-    "cancel",
-    "block",
-    "unblock",
-    "archive",
-    "reopen",
-];
+// ---------------- lifecycle tool set (DX-3465 / PLN-11 R-25) ----------------
+// Merged from `src/mcp/danxbot-server.ts` — see `lifecycle.ts` for the full
+// per-tool doc comments and the DX-3394 problem 1682 cleanup this merge
+// folded in. `danxbot_complete` registers unconditionally-visible; the rest
+// register here and are `.enable()`/`.disable()`d per-dispatch inside
+// `boot()` above, based on which callback URL env vars are present.
+const lifecycleTools = registerLifecycleTools(strictTool);
 // Optional per-call board override shared by every tool. Omitted → the
 // dispatch's env-derived board (`<repo>:<slug>`) is used; provided → that
 // board is targeted instead (the dashboard owns board→repo and 404s an
@@ -316,599 +311,92 @@ const boardField = {
         .optional()
         .describe("Board id `<repo>:<slug>`; omit for this dispatch's board. Unknown → 404."),
 };
-// The three prose fields of a card, each with ONE job. Shared by issue_create
-// (root + phase children) and issue_edit so the guidance an agent reads is
-// identical wherever it writes the field.
-const TITLE_DESCRIBE = 'Short, specific label naming the domain (e.g. "Guest checkout rejects gift-card carts"). Never generic ("Fix bug", "Follow-up").';
-const SUMMARY_DESCRIBE = "1–3 plain-language sentences, no markdown/jargon: what the card is and why it matters. Always shown, never collapsed — not a second title, not a teaser.";
-const DESCRIPTION_DESCRIBE = 'The full body ("Context"): evidence, examples, technical detail; markdown, collapsed by default. Operator questions go in issue_problem. Style: see issue_comment\'s `text` param.';
-// DX-3335 — condensed from the now-deleted danxbot:comment-style skill (PLN-11
-// R-16: fold a skill's rule into the tool description it governs rather than
-// require a separate load). Shared by every prose-writing field below so an
-// agent sees the same rules wherever it writes card markdown.
-// DX-2623 — this constant (and every `.describe()` reference to it) must stay
-// reachable: an earlier dedup pass (05af82086) deleted it outright and left
-// the "never escape markdown" / "GFM not ASCII tables" rules unreachable from
-// any tool in this surface until it was restored. The text below (from
-// DX-3335) already carries both clauses — do not dedup them away again.
-const MARKDOWN_STYLE_DESCRIBE = "Renders as markdown here. Use `##`/`###` headers, fenced code blocks with a language tag, inline code for paths/symbols/flags, `-`/`1.` lists, and GFM tables (`|---|`) for 2D data — never ASCII tables. Never escape markdown characters (`\\*`, `\\_`) to \"play it safe\"; they render wrong. Don't repeat the same content as both prose and a list. Structure the content itself per `base:convey` (concept-first headline, diff, caveats, verify) — this rule only governs the markdown syntax.";
-// ---------------- issue_list ----------------
-strictTool("issue_list", 
-// DX-2735: trimmed to pay for the problem tools inside the work-profile
-// injected-surface budget — same facts, no repeated prose.
-"List cards. Board-scoped; see `board`. `filter`: type, parent_id, dispatchable_derived, status_derived[], self_dispatchable_derived, assigned_agent, include_closed, include_deleted, q (free text over id+title+description). THE DEFAULT ROW IS MINIMAL — scalars only (id, type, title, status, parent_id, priority, created_at, updated_at, assigned_agent, content_hash), no joins; `fields` opts into more — the SAME recursive field-tree JSON `issue_get` takes, against the SAME issue resource (list-row fields like `ac_total`/`comments_count`/`waiting_on`/`quality_gates`/`next_pre_gate` sit alongside every detail field `issue_get` can name). Call `resource_fields({resource:\"issue\"})` for the full, current list of what `fields` may name — never guess a name; unknown → 400 `unknown_field`. `sort`: [{column, order}] over id|priority|repo_name|title|type|status_derived|triage_ice_total|created_at|updated_at (default order: see `sort`'s own field description). `limit`/`offset` page (uncapped by default). `include_closed` defaults to FALSE: a bare call silently excludes every Done/Cancelled card (leaf AND container alike). The response always carries `total` (the full count matching every filter except limit/offset — compare against `issues.length` to tell an exhausted list from a truncated one) and, whenever `include_closed` was not explicitly `true`, `closed_excluded` (how many additional terminal cards the default withheld — re-call with `include_closed: true` to see them). issue_get reads one card in full.", {
-    filter: z
-        .object({
-        q: z.string().optional(),
-        type: z.enum(ISSUE_TYPES).optional(),
-        parent_id: z.string().nullable().optional(),
-        dispatchable_derived: z.boolean().optional(),
-        status_derived: z.array(z.string()).optional(),
-        self_dispatchable_derived: z.boolean().optional(),
-        assigned_agent: z.string().optional(),
-        include_closed: z.boolean().optional(),
-        include_deleted: z.boolean().optional(),
-    })
-        // DX-3238 — the card's own repro: a mistyped key here (`dispatchable`
-        // for `dispatchable_derived`) was silently stripped by this NESTED
-        // object's own bare `z.object`, so the query ran unfiltered — the
-        // outer `strictTool` wrapper (below) only guards the TOP-LEVEL shape,
-        // never a nested one, so every nested z.object() in this file needs
-        // its own `.strict()`.
-        .strict()
-        .optional(),
-    // DX-3427 — a field TREE, exactly like `issue_get`'s `fields` below
-    // (against the same shared issue resource) — replaces the retired
-    // CSV field-GROUP list.
-    fields: fieldTreeSchema
-        .optional()
-        .describe("A field tree (see tool description); absent/empty = minimal scalars. `resource_fields({resource:\"issue\"})` names every valid key."),
-    sort: sortField,
-    limit: z.number().int().positive().max(LIST_PAGE_MAX_LIMIT).optional(),
-    offset: z.number().int().nonnegative().optional(),
-    ...boardField,
-}, async (args) => jsonResult(await issueList(client, args)));
-// ---------------- issue_get ----------------
-strictTool("issue_get", 
-// DX-3426: field GROUPS replaced by a recursive field TREE (see
-// `./field-tree.ts`) — comment paging now lives INSIDE the tree (a
-// cursor-paged relation, today only `comments`, takes `limit`/`before` in
-// its own nested object) instead of top-level `comments_limit`/
-// `comments_offset`, which is also why the old "ids + comments_* refused"
-// rule is gone: paging is per-relation now, so it works on the batch form
-// too. Kept compact — call `resource_fields({resource:"issue"})` for the
-// full, current list of what `fields` may name, rather than enumerating it
-// here (it would drift the moment a field/relation is added or removed).
-"Fetch one card (`id`) or many (`ids`, at most " + ISSUE_BATCH_GET_MAX + " — split larger sets); pass exactly one. Ids are globally unique, so both resolve from any board; the batch form is global and throws with `board`. THE DEFAULT ROW IS THE ALWAYS-ON FIELDS ONLY — identity, lifecycle stamps, derived status/list/blocked, assigned_agent, and content_hash (the concurrency token issue_edit needs for title/description/checklists); every child hash is likewise always returned. `fields` opts into more, per card in a batch too: a JSON object tree — each key names a field or relation, each value is `true` (that field, or a relation's child with its default fields), a nested object (a relation's child with named fields), or on the cursor-paged `comments` relation the nested object may also carry `limit`/`before` (comment id) to page — e.g. `{\"description\": true, \"problems\": {\"solutions\": {\"steps\": true}}, \"comments\": {\"limit\": 10}}`; a paged response also carries `comments_page: {limit, total, next_cursor}` (`next_cursor` → pass back as `before` for the next older page, null = none). Call `resource_fields({resource:\"issue\"})` for exactly what may be requested (every field/relation name, each relation's own child resource, and its paging shape if any) — never guess a name. Unknown field/relation → 400 `unknown_field`; bad shape → 400 `invalid_fields`; bad `limit`/`before` → 400 `invalid_field_argument`; a field you lack permission for → 403 `forbidden_field`. Single form: unknown id → 404. Batch form: `{issues: [...], not_found: [...ids]}` — an unknown or deleted id never fails the call.", {
-    id: z.string().min(1).optional(),
-    ids: z.array(z.string().min(1)).min(1).max(ISSUE_BATCH_GET_MAX).optional(),
-    fields: fieldTreeSchema
-        .optional()
-        .describe("A field tree (see tool description); absent/empty = minimal scalars. `resource_fields({resource:\"issue\"})` names every valid key."),
-    ...boardField,
-}, async (args) => jsonResult(await issueGet(client, args)));
 // ---------------- resource_fields ----------------
-strictTool("resource_fields", "DX-3426: what a field TREE (`issue_get`'s `fields`, and any later tool that takes one) may name for one resource — `{resource, description, always: string[], hashes: string[], fields: [{name, description}], relations: [{name, description, resource, paging?: {default_limit, max_limit, page_field}}]}`. `always`/`hashes` ride every response regardless of `fields` (never request them). A relation's `resource` names what to call this same tool with next, to go one level deeper. Install-global, not board-scoped. `resource: \"issue\"` is the root; unknown resource → 404 `unknown_resource`.", {
+strictTool("resource_fields", "DX-3426: what a field TREE (the `fields` arg on `GET /api/issues/:id` via `danxbot_api`, and any later tool that takes one) may name for one resource — `{resource, description, always: string[], hashes: string[], fields: [{name, description}], relations: [{name, description, resource, paging?: {default_limit, max_limit, page_field}}]}`. `always`/`hashes` ride every response regardless of `fields` (never request them). A relation's `resource` names what to call this same tool with next, to go one level deeper. Install-global, not board-scoped. `resource: \"issue\"` is the root; unknown resource → 404 `unknown_resource`.", {
     resource: z.string().min(1).describe('Resource name, e.g. "issue", or a relation\'s own `resource` from a prior call.'),
 }, async (args) => jsonResult(await resourceFields(client, args)));
-// ---------------- issue_create ----------------
-strictTool("issue_create", '`plan` is REQUIRED on every create — no default, no inference; see its own field description for the two values and the refusal. This replaces the plan_add_card follow-up at creation time; plan_add_card remains for putting an EXISTING card on a plan. ' +
-    'Create a card. Board-scoped; see `board`. type=Epic REQUIRES non-empty phase_children[] (epic and phases inserted in one transaction; children get the epic as parent); other types refuse phase_children[] (400). Status starts at Review. `list_id` places the card straight into a column — a board_lists id or the list\'s display NAME (case-insensitive, emoji-tolerant): a `ready`-type queue lands it in ToDo, a `completed` list in Done, with no follow-up transition. Not valid on Epic; unknown name/id → 400. `quality_gates` adds gates beyond the board\'s type defaults (see its own field description); add one later with `issue_quality_gate`. ALWAYS pass `triage_enabled` explicitly on the root card and every phase child (see its own field description).', {
-    type: z.enum(ISSUE_TYPES),
-    title: z.string().min(1).describe(TITLE_DESCRIBE),
-    summary: z.string().min(1).optional().describe(SUMMARY_DESCRIBE),
-    description: z.string().describe(DESCRIPTION_DESCRIBE),
-    // DX-3006 — REQUIRED and nullable, deliberately. `.nullable()` WITHOUT
-    // `.optional()` is the whole point: the caller must supply the key, and
-    // `null` is a legitimate answer it has to give on purpose. Adding
-    // `.optional()` here silently restores the hole this field closes.
-    plan: z
-        .literal("mine")
-        .nullable()
-        .describe('"mine" = attach to the plan THIS session is connected to; null = deliberately no plan. REQUIRED — decide per card, never omit. "mine" while unconnected is refused 409 session_not_connected (creates NO card). A plan id is not accepted: a card is only ever created onto your own connected plan.'),
-    parent_id: z.string().nullable().optional(),
-    ac: z.array(z.object({ title: z.string().min(1) }).strict()).optional(),
-    effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
-    list_id: z.string().min(1).nullable().optional(),
-    quality_gates: z
-        .array(z.object({
-        gate: z.string().min(1),
-        note: z.string().optional(),
-        effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
-    }).strict())
-        .optional()
-        .describe("The gates this card carries BEYOND the board's default set for its type — one {gate, note?} each, `note` = why it applies here. Every gate on a card is required; a gate you do not name is not on the card at all (not displayed, not counted, never run), and omitting this field entirely is normal. Optional `effort_level` overrides a `plan-*` gate's reviewer rung."),
-    phase_children: z
-        .array(z.object({
-        type: z.enum(NON_EPIC_TYPES),
-        title: z.string().min(1).describe(TITLE_DESCRIBE),
-        summary: z
-            .string()
-            .min(1)
-            .optional()
-            .describe(`${SUMMARY_DESCRIBE} This child's OWN summary — never inherited from the root card.`),
-        description: z.string().describe(DESCRIPTION_DESCRIBE),
-        ac: z.array(z.object({ title: z.string().min(1) }).strict()).optional(),
-        effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
-        quality_gates: z
-            .array(z.object({
-            gate: z.string().min(1),
-            note: z.string().optional(),
-            effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
-        }).strict())
-            .optional()
-            .describe("Same as the root quality_gates, resolved against THIS child's type."),
-        triage_enabled: z
-            .boolean()
-            .optional()
-            .describe("ALWAYS pass per child; absent → false (never auto-triaged). Not inherited from the root."),
-    }).strict())
-        .optional(),
-    triage_enabled: z
-        .boolean()
-        .optional()
-        .describe("ALWAYS pass explicitly. true = enters automatic triage/dispatch without further human review; absent → false. Ignored by issue_triage and by an operator-initiated triage write."),
-    // DX-3238 — was absent from this schema entirely (not merely optional),
-    // so a caller's value was silently stripped before the request was built
-    // even though the route already honoured it (ALLOWED_CREATE_KEYS,
-    // create.ts:39-56; parsePriority, create.ts:545). Same shape as
-    // issue_edit's `priority` above.
-    priority: z
-        .union([z.enum(PRIORITY_TIER_WORDS), z.number()])
-        .optional()
-        .describe('Tier word ("lowest"…"critical", prefer this) or number in [0,6); higher = more urgent. Omit for the route\'s own default.'),
-    // DX-3238 — `assigned_agent` is DELIBERATELY left undeclared here, unlike
-    // `priority` above. The route accepts it (`ALLOWED_CREATE_KEYS`,
-    // create.ts:39-56) but it only matters for the create→`list_id`-lands-
-    // in-progress placement path (create.ts:918-955), a dispatched-worker
-    // internal-bookkeeping concern this MCP tool never exposes (no MCP
-    // caller can pick an in-progress-mapped `list_id`) — so there is no
-    // legitimate agent-facing use for it. Before this card that gap was
-    // silent (the key vanished with no signal); now, with every schema
-    // here strict, a caller that tries it gets a clear "Invalid arguments"
-    // refusal naming `assigned_agent` instead — that refusal IS the fix for
-    // this field, not a schema addition. Revisit only if a future card
-    // wires the in-progress-placement path up to this tool on purpose.
-    ...boardField,
-}, async (args) => jsonResult(await issueCreate(client, args, config.board)));
-// ---------------- issue_edit ----------------
-strictTool("issue_edit", 'Patch a card. ALLOWED keys: title, summary, description, ac, checklists, effort_level, parent_id, priority, list_id, triage_enabled, type, content_hash. Any other key (lifecycle, triage, dependencies, retro, blocked) is refused 400 with offending_keys[] naming the right tool: issue_transition / issue_triage / issue_comment / issue_dependency / issue_problem / issue_retro. `type` (see its own field description) is how a planning item becomes work. `priority` (see its own field description) is the ONLY way to set priority; a "Priority:" line in the description does nothing. CHECKLISTS: each item has one status `incomplete|failing|passing|cancelled|deferred`; `deferred` (work done, a real-world/post-deploy check outstanding) REQUIRES `detail`, and a `📡`-prefixed item can never be `passing`. `ac` edits the default "Acceptance Criteria" checklist (items matched by check_item_id, else exact title); `checklists` REPLACES every named checklist with full status control (`{name, items:[{label, detail?, status}]}`). Send `ac` OR `checklists`, not both (400). `list_id` pins the card to a list by id or display NAME; its type must match the card\'s current derived status (400 otherwise — e.g. ready the card first before pinning it to a `ready`-type list); null clears the pin. `content_hash` (see its own field description) is the card\'s optimistic-concurrency token.', {
-    id: z.string().min(1),
-    title: z.string().min(1).optional().describe(TITLE_DESCRIBE),
-    summary: z
-        .string()
-        .min(1)
-        .nullable()
-        .optional()
-        .describe(`${SUMMARY_DESCRIBE} Pass null to clear it.`),
-    description: z.string().optional().describe(DESCRIPTION_DESCRIBE),
-    type: z
-        .enum(ISSUE_TYPES)
-        .optional()
-        .describe("Story/Bug/Chore = dispatchable; Task/Epic/Feature = never dispatched, in any status."),
-    ac: z
-        .array(z.object({
-        title: z.string(),
-        checked: z.boolean().optional(),
-        status: z
-            .enum(CHECKLIST_ITEM_STATUSES)
-            .optional()
-            .describe("Optional full status; omitted → from `checked`. See tool description for the deferred/📡 rules."),
-        detail: z
-            .string()
-            .optional()
-            .describe("paired with `status`; required (non-empty) when `status` is `deferred`."),
-        check_item_id: z
-            .union([z.string(), z.number()])
-            .optional()
-            .describe("Optional id from issue_get's ac[].check_item_id. Only needed to tell apart two items with identical titles; otherwise items match by title."),
-    }).strict())
-        .optional()
-        .describe("The default Acceptance Criteria checklist: checked true → passing, false → incomplete, or pass `status`. Diffed against live items — unchanged items keep their id, new titles are inserted, missing ones removed."),
-    checklists: z
-        .array(z.object({
-        name: z.string().min(1),
-        items: z.array(z.object({
-            label: z.string().min(1),
-            detail: z.string().optional(),
-            status: z.enum(CHECKLIST_ITEM_STATUSES),
-        }).strict()),
-    }).strict())
-        .optional(),
-    effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
-    parent_id: z.string().nullable().optional(),
-    priority: z
-        .union([z.enum(PRIORITY_TIER_WORDS), z.number()])
-        .optional()
-        .describe('Tier word ("lowest"…"critical", prefer this) or number in [0,6); higher = more urgent — see tool description for why this is the only way to set it.'),
-    list_id: z.string().min(1).nullable().optional(),
-    triage_enabled: z
-        .boolean()
-        .optional()
-        .describe("Per-card opt-in to the automatic triage dispatcher (default false = never auto-selected). Ignored by issue_triage and by an operator-initiated triage write."),
-    content_hash: z
+// ---------------- danxbot_api (DX-3465, PLN-11 R-25) ----------------
+strictTool("danxbot_api", "Call any dashboard API route your credential may reach. `method` + `path` (a FULL path, e.g. " +
+    '"/api/issues/DX-1/transition" — substitute real ids yourself, never a route template with `:id` in it) + ' +
+    "optional `query`/`body`. The response is the route's JSON body verbatim, `reminders[]` included when the " +
+    "route attaches one. `board` overrides this dispatch's configured board for a board-scoped route only " +
+    "(ignored by a route that isn't board-scoped). See this server's own instructions (shown once, at connect) " +
+    "for the shared resource shape, the stale-hash rule, and how to read a refusal — don't know the route? call " +
+    "`danxbot_api_list` first; unsure of its exact shape? call `danxbot_api_spec` first.", {
+    method: z.enum(DANXBOT_API_METHODS),
+    path: z
         .string()
         .min(1)
-        .optional()
-        .describe("The card's content_hash last read via issue_get/issue_list's content_hash scalar (present even minimal). REQUIRED whenever this edit touches title/description/checklists (NOT ac, which keeps its own check_item_id/title diffing): missing → 400, stale → 409 stale_issue_content carrying currentHash + currentTitle + currentDescription — re-issue_get and retry with the fresh hash, never blindly."),
+        .startsWith("/api/")
+        .describe('Full path starting with "/api/" — never a route template.'),
+    query: z.record(z.union([z.string(), z.number(), z.boolean(), z.null()])).optional(),
+    body: z.unknown().optional(),
     ...boardField,
-}, async (args) => jsonResult(await issueEdit(client, args)));
-// ---------------- issue_transition ----------------
-strictTool("issue_transition", 
-// DX-2735: trimmed with the problem tools to stay inside the work-profile budget.
-"Move a card's lifecycle — the ONLY way; `danxbot_complete` never moves a card, so call this first. Actions: ready (Review→ToDo); pickup (ToDo→In Progress; checks every dispatch gate — ready, blocked, open_problem_count (a card needs a human exactly when this is > 0), depends_on terminal, conflict_on idle — and refuses 409 with failed_gate naming the cause; `manual:true` is a self-pickup for work in YOUR session: it bypasses card-flow gates EXCEPT open_problem_count, which never lets a card start, and is never auto-rolled-back — see `assigned_agent`'s own field description for the dispatched-agent requirement); rollback_pickup (see `keep_assignment`'s own field description); complete (your explicit decision; 409 on an Epic with non-terminal children (non_terminal_phases[]) or while a required POST quality gate is not pass (failed_gate 'quality_gate_post' + failed_post_gates[])); cancel (terminal); block (non-empty reason; only holds dispatch, never asks a human — for that use issue_problem add; env faults use `danxbot_complete({status:'failed'})`); unblock; archive (to Backlog, clears ready_at); reopen (terminal→active). Terminal cards refuse all but reopen; forward stamps never clear earlier ones. A pickup that loses a race is refused 409 `failed_gate: \"dispatch_id\"` — re-read assigned_agent/dispatch_id, never retry blindly.", {
-    id: z.string().min(1),
-    action: z.enum(TRANSITION_ACTIONS),
-    reason: z.string().optional(),
-    summary: z.string().optional(),
-    dispatch_id: z.string().min(1).optional(),
-    manual: z.boolean().optional(),
-    assigned_agent: z
-        .string()
-        .min(1)
-        .optional()
-        .describe("Required for a dispatched agent's manual:true pickup: your agent/profile name, never the shared dispatch-token identity. Optional for a human session; ignored by other actions."),
-    keep_assignment: z
-        .boolean()
-        .optional()
-        .describe("rollback_pickup-only. true preserves assigned_agent + assignment_mode across the release (the card lands ready still manually held, off the automated dispatcher) instead of the default clear-and-hand-back-to-automation."),
-    ...boardField,
-}, async (args) => jsonResult(await issueTransition(client, args)));
-// ---------------- issue_triage ----------------
-strictTool("issue_triage", "Record a triage confidence score. Caller sends a single `confidence` integer 0-5 plus a required non-empty `reason` — the server computes the verdict by comparing `confidence` against the board's configured thresholds (all band edges inclusive on the low side): confidence <= cancelThreshold -> cancel (stamps cancelled_at, terminal); cancelThreshold < confidence <= archiveThreshold -> defer (stamps archived_at AND ready_at:null); archiveThreshold < confidence <= reviewThreshold -> keep (no column stamp); confidence > reviewThreshold -> approve (stamps ready_at). REFUSES 409 on terminal cards. a keep/defer verdict does NOT block the card: it opens a problem asking the reason with three real choices (approve and ready / defer / cancel, one recommended) — opening it IS what puts the card in front of a human, the same escalation shape every other machine writer uses (the dashboard's Needs You tab reads only open_problem_count). Answering that problem applies the chosen outcome through the normal issue_transition actions automatically. It is not a cross-card ordering gate; use issue_dependency (kind: depends_on) to sequence one card after another.", {
-    id: z.string().min(1),
-    confidence: z.number().int().min(0).max(5),
-    reason: z.string().min(1),
-    ...boardField,
-}, async (args) => jsonResult(await issueTriage(client, args)));
-// ---------------- issue_comment ----------------
-strictTool("issue_comment", "Comment CRUD. action=add → {text, metadata?, problem_id?} (server stamps author from bearer + auto-incrementing ordinal); action=edit → PATCH /:cid {text}; action=delete → DELETE /:cid (soft-delete, audit trail preserved — comments are NEVER hard-deleted). Client-supplied author is IGNORED (server-stamped to prevent impersonation). `metadata` (action=add only) is an OPTIONAL opaque JSON object a calling app attaches to the comment — e.g. a generated `{sql, explanation}` packet its own UI renders specially. danxbot stores + returns it verbatim and enforces NO shape on its contents; omit for a plain markdown-only comment (unaffected either way). `problem_id` (action=add only) OPTIONALLY threads the comment as a follow-up question under one of this SAME card's problems (from `issue_problem` list/add) WITHOUT answering it — commenting never changes open_problem_count, blocked, or records a decision; use issue_problem's answer route for that. An unknown id, another card's id, or a removed problem's id all 404 naming the problem id — an ANSWERED (but not removed) problem still accepts a follow-up comment, since the thread continues after a decision.", {
-    id: z.string().min(1),
-    action: z.enum(["add", "edit", "delete"]),
-    comment_id: z.number().int().positive().optional(),
-    text: z.string().min(1).optional().describe(MARKDOWN_STYLE_DESCRIBE),
-    metadata: z.record(z.unknown()).optional(),
-    problem_id: z.number().int().positive().optional().describe("action=add only — thread this comment as a follow-up under a LIVE problem of this same card, without answering it"),
-    ...boardField,
-}, async (args) => jsonResult(await issueComment(client, args)));
-// ---------------- issue_checklist ----------------
-const CHECKLIST_ITEM_INPUT = z
-    .object({
-    label: z.string().min(1),
-    detail: z.string().optional(),
-    status: z.enum(CHECKLIST_ITEM_STATUSES).optional(),
-})
-    .strict();
-strictTool("issue_checklist", "Targeted checklist CUD — mutates ONE checklist/item without `issue_edit({checklists})`'s wholesale replace, which drops any checklist you omit and churns every item id (orphaning its Trello mirror). Actions: add_list (name, items?) creates a checklist; update_list renames it; remove_list soft-deletes it; add_item appends an item (status defaults incomplete); update_item changes only the fields passed (≥1 required, keeps id + Trello link); remove_item soft-deletes one item. Status: incomplete|failing|passing|cancelled|deferred (terminal = passing|cancelled|deferred; deferred means the work is done but a real-world/post-deploy check remains — requires a non-empty `detail`). checklist_id required for every action except add_list; item_id for update_item/remove_item. Unknown card/checklist/item → 404, invalid status → 400. Additive — `issue_edit({checklists})` still works for bulk authoring.", {
-    id: z.string().min(1),
-    action: z.enum([
-        "add_list",
-        "update_list",
-        "remove_list",
-        "add_item",
-        "update_item",
-        "remove_item",
-    ]),
-    checklist_id: z.number().int().positive().optional(),
-    item_id: z.number().int().positive().optional(),
-    name: z.string().min(1).optional(),
-    items: z.array(CHECKLIST_ITEM_INPUT).optional(),
-    label: z.string().min(1).optional(),
-    detail: z.string().optional(),
-    status: z.enum(CHECKLIST_ITEM_STATUSES).optional(),
-    ...boardField,
-}, async (args) => jsonResult(await issueChecklist(client, args)));
-// ---------------- issue_problem ----------------
-// DX-2735: the option fields, shared by `issue_problem` add's inline solutions[]
-// and `issue_solution`. Their meaning is stated ONCE, in issue_solution's
-// description — per-field describes repeated it on every call's context.
-const SOLUTION_FIELDS = {
-    body: z.string().optional(),
-    pro: z.string().optional(),
-    con: z.string().optional(),
-    recommended: z.boolean().optional(),
-};
-const STEP_INPUT = z.lazy(() => z
-    .object({
-    id: z
-        .number()
-        .int()
-        .positive()
-        .optional()
-        .describe("present -> matches an existing step by this id (400 if not a live child of this exact parent scope, " +
-        "never claimed by the fallback below); absent -> matches the first unclaimed same-titled sibling " +
-        "under the same parent, else creates new (title-based, never positional — keeps later id-less " +
-        "siblings' ids intact on a middle insert). Send ids anyway when identity matters (checked progress, " +
-        "a later edit) or siblings share a title."),
-    title: z
-        .string()
-        .min(1)
-        .describe("one imperative line — labels (\"1.\", \"2a\") are DERIVED on read, never put one in the title."),
-    description: z.string().nullable().optional().describe("markdown detail, or null/omitted for none"),
-    steps: z.array(STEP_INPUT).optional().describe("this step's own children, nested — refused past 3 levels total"),
-})
-    .strict());
-strictTool("issue_problem", "A card's PROBLEMS: one statement the operator must resolve (a question, or a flaw in the plan) OR an action only a person can carry out, each with its own solutions/answers — one problem per question. OPEN = not yet answered; the card needs a human exactly while open_problem_count > 0 — adding a problem IS putting the card in front of a human, there is no separate flag. list → live problems in order, each {id, statement, context, type, summary, content_hash, open, solutions[], decisions[]} (each decision carries `relayed_by_session`, DX-3471 — the working session that recorded it, or null for one entered directly in the dashboard); add {statement, context?, type?, summary?, solutions?} → problem_id + solution_ids in one transaction (zero solutions is valid: the operator answers free-form) plus a `reminders: [{key, text}]` array (DX-3365 — every MCP-response reminder rides this ONE field now, DB-registry-driven and operator-overridable from the dashboard) naming each still-open problem's solution count; edit :pid {base_hash, statement, context?, summary?}; remove :pid {base_hash} — always allowed, even as the card's last open problem (removing it just means the card no longer needs a human). A stale base_hash → 409 `stale_problem` with currentHash + currentProblem: merge, then retry. " +
-    "DX-3471 — answer :pid {solution_id, note?} | {freeform} records the operator's decision on a LIVE problem (exactly one of solution_id/freeform; note only qualifies a chosen solution); change_answer :pid {base_hash, solution_id, note?} | {base_hash, freeform} retracts the current decision and records a new one in ONE server transaction; unanswer :pid {base_hash} retracts with no new answer, reopening the problem. `base_hash` on these two names the live DECISION (from that problem's `decisions[].content_hash` in `list`), NOT the problem's own hash — a stale one → 409 `stale_decision` with currentHash + currentDecision: merge, then retry. " +
-    "**These three are OPERATOR-SESSION ONLY** — the server refuses a dispatched agent's machine credential 403 (DX-2830: an agent that could answer its own question could release the very human gate it set to stop and wait for); call them only when relaying a decision the OPERATOR actually made in this chat, never a decision you are making yourself. Session attribution is automatic (the same `x-danx-session-id` every call already carries, DX-2683) — no session parameter to pass here. " +
-    "`statement` is capped at 200 characters (400 names the actual length otherwise): one plain sentence, with any investigation detail in `context` (markdown, no cap) instead. Read `type`'s and `summary`'s own descriptions below before your first `add` — together they teach which type this is and the three-field split (`statement`/`summary`/`context`) an action needs.", {
-    id: z.string().min(1),
-    action: z.enum(["list", "add", "edit", "remove", "answer", "change_answer", "unanswer"]),
-    problem_id: z.number().int().positive().optional().describe("edit/remove/answer/change_answer/unanswer"),
-    base_hash: z
-        .string()
-        .min(1)
-        .optional()
-        .describe("edit/remove: content_hash last read for the PROBLEM. change_answer/unanswer: content_hash last read for " +
-        "the live DECISION instead (that problem's `decisions[].content_hash` from `list`) — the two are never " +
-        "interchangeable."),
-    solution_id: z
-        .number()
-        .int()
-        .positive()
-        .optional()
-        .describe("answer/change_answer only. The chosen option's id, from this problem's own solutions[]. Exactly one of " +
-        "solution_id / freeform — never both, never neither (refused before any request)."),
-    note: z
-        .string()
-        .min(1)
-        .optional()
-        .describe("answer/change_answer only, solution_id answers only: an optional qualification (\"this, but…\"). Refused " +
-        "alongside freeform, which is already the operator's own words."),
-    freeform: z
-        .string()
-        .min(1)
-        .optional()
-        .describe("answer/change_answer only. The operator's own words, when no listed solution fits. Exactly one of " +
-        "solution_id / freeform — never both, never neither."),
-    statement: z
-        .string()
-        .min(1)
-        .optional()
-        .describe("add/edit; ONE plain sentence, at most 200 characters — see `type` below for question vs action phrasing."),
-    context: z
-        .string()
-        .nullable()
-        .optional()
-        .describe("add/edit; markdown detail behind statement — file:line refs, code excerpts, root-cause writeups, or (for " +
-        "an action) whatever detail the person carrying it out needs. NOT where an action's why-can't-the-agent " +
-        "sentence goes — that is `summary`. add: sent only when given (null/omit means none). edit: omit to keep " +
-        "the stored context, null to clear it."),
-    type: z
-        .enum(["question", "action"])
-        .optional()
-        .describe("add only. Test: could you do this yourself if you tried harder, and is the only thing missing a decision? " +
-        "Yes → \"question\": statement is the question (one plain sentence); summary optional (why it matters); " +
-        "context is the evidence; solutions[] are candidate ANSWERS with their own pro/con, done once one is " +
-        "picked. No — the blocker is access, credentials, hardware, a human's authority, or a system you " +
-        "genuinely cannot reach — \"action\": statement is WHAT IS TO BE DONE, never phrased as a question " +
-        "(\"Rotate the staging DB credential\", not \"Should we rotate it?\"); summary is REQUIRED, stating why " +
-        "it's needed and why you can't do it yourself (an add with no summary refuses 400); context is detail " +
-        "for whoever carries it out; solutions[] are the possible ROUTES (e.g. \"rotate by hand\" vs \"run the " +
-        "provisioning script\"), each MUST carry ≥1 step (400 otherwise — no procedure means not yet actionable). " +
-        "Omitted defaults to \"question\" — decide deliberately every time."),
-    summary: z
-        .string()
-        .nullable()
-        .optional()
-        .describe("add/edit. Plain text, 1-3 sentences — never markdown (that's `context`'s job). Required+non-empty for an " +
-        "action problem (why needed + why you can't do it yourself — see `type`; refused 400 if missing on add or " +
-        "cleared on a live action edit); optional for a question. add: sent only when given (omit/null on a " +
-        "question means none). edit: omit keeps the stored summary, null clears it."),
-    solutions: z
-        .array(z.object({ title: z.string().min(1), ...SOLUTION_FIELDS, steps: z.array(STEP_INPUT).optional() }).strict())
-        .optional()
-        .describe("add only; fields as issue_solution add, INCLUDING steps — an ACTION problem's inline " +
-        "solutions must each carry at least one step (refused 400 otherwise); a QUESTION's may carry any number, " +
-        "including none."),
-    ...boardField,
-}, async (args) => jsonResult(await issueProblem(client, args)));
-// ---------------- issue_solution ----------------
-strictTool("issue_solution", "One problem's options, AND one solution's individual " +
-    "procedure steps; `problem_id` is REQUIRED (from issue_problem list/add; " +
-    "another problem's solution id → 404). add {title, body?, pro?, con?, recommended?, steps?}: title names the " +
-    "option, body/pro/con its markdown detail and case for/against; `steps` authors the WHOLE procedure in one " +
-    "call — {title, description?, steps?}[], nestable to 3 levels (4th refused 400, naming the step + limit). " +
-    "ACTION problem: `steps` must be non-empty (400 otherwise); QUESTION: may be omitted/empty. Labels " +
-    "(\"1\", \"2a\", \"2a.i\") are DERIVED on read from position — never put one in a title. edit :sid {base_hash, " +
-    "...changed fields, steps?, steps_base_hash?}: `steps` omitted leaves the procedure untouched; an explicit " +
-    "array (incl. [], refused if it leaves an action's solution with zero steps) DIFFS against it — send an " +
-    "existing step's `id` to keep it (even while retitling/reordering), omit `id` for a new step; any existing " +
-    "step left out is removed. An id-less node matches the first unclaimed same-titled sibling under the same " +
-    "parent (never positional), so an id-less MIDDLE insert keeps later id-less siblings' ids — send ids anyway " +
-    "when identity matters. `steps_base_hash` REQUIRED whenever `steps` is sent — the solution's current " +
-    "`steps_hash`; stale → 409 `stale_steps` with the current tree. Never resend the whole tree to fix one word " +
-    "— use add_step/edit_step/remove_step below. remove :sid {base_hash}: stale → 409 `stale_solution` with " +
-    "currentHash + currentSolution, merge and retry. At most ONE live recommended per problem — a second → 409 " +
-    "naming `recommended_solution_id`. A CHOSEN option's words and WHOLE PROCEDURE are frozen (409 — add a new " +
-    "one instead); every steps route below refuses once a decision has chosen this solution.\n\n" +
-    "Granular single-step actions, no tree resend: add_step {solution_id, title, description?, parent_step_id?, " +
-    "position?} — title is one imperative line (labels derived, never typed); parent_step_id omitted/null = " +
-    "top-level; position 1-indexed among current live children, omitted = append, beyond sibling count → 400 " +
-    "(never clamped); nesting past depth 3 → 400. edit_step {solution_id, step_id, base_hash, title?, " +
-    "description?} — never moves a step. remove_step {solution_id, step_id, base_hash} — soft-deletes it and " +
-    "its live children; refused 409 if this solution belongs to an ACTION problem and removing it leaves zero " +
-    "live steps. Stale base_hash on a step → 409 `stale_step` with currentHash + currentStep (real derived " +
-    "`label`).", {
-    id: z.string().min(1),
-    action: z.enum(["add", "edit", "remove", "add_step", "edit_step", "remove_step"]),
-    problem_id: z.number().int().positive(),
-    solution_id: z.number().int().positive().optional().describe("edit/remove/add_step/edit_step/remove_step"),
-    base_hash: z.string().min(1).optional().describe("content_hash last read; edit/remove/edit_step/remove_step"),
-    title: z.string().min(1).optional().describe("add; also add_step/edit_step"),
-    ...SOLUTION_FIELDS,
-    steps: z.array(STEP_INPUT).optional().describe("add/edit only — see this tool's own description"),
-    steps_base_hash: z
-        .string()
-        .min(1)
-        .optional()
-        .describe("edit only, REQUIRED whenever steps is sent — the solution's current steps_hash; a stale value is refused 409 stale_steps"),
-    description: z.string().nullable().optional().describe("add_step/edit_step; markdown detail, or null/omitted for none"),
-    step_id: z.number().int().positive().optional().describe("edit_step/remove_step"),
-    parent_step_id: z
-        .number()
-        .int()
-        .positive()
-        .nullable()
-        .optional()
-        .describe("add_step only; omitted/null = top-level step"),
-    position: z
-        .number()
-        .int()
-        .positive()
-        .optional()
-        .describe("add_step only; 1-indexed among the parent's current live children, omitted = append"),
-    ...boardField,
-}, async (args) => jsonResult(await issueSolution(client, args)));
-// ---------------- issue_dependency ----------------
-strictTool("issue_dependency", 'Dependency CRUD. add: {kind, target_id, reason}, kind ∈ {depends_on, conflict_on}. depends_on is cycle-checked (409 on a loop back to source); self-loops refuse 409; re-adding a live triple returns the existing id. remove: {dependency_id} — reason is fixed server-side to "recorded_in_error" (removal means NOT related, never satisfied), so never pass it. The ONLY mechanism the dispatch picker uses to sequence one card after another — a held status (e.g. an issue_triage "keep") is not a substitute and gives no cross-card ordering.', {
-    id: z.string().min(1),
-    action: z.enum(["add", "remove"]),
-    kind: z.enum(["depends_on", "conflict_on"]).optional(),
-    target_id: z.string().min(1).optional(),
-    reason: z.string().optional(),
-    dependency_id: z.number().int().positive().optional(),
-    ...boardField,
-}, async (args) => jsonResult(await issueDependency(client, args)));
-// ---------------- issue_retire_branch ----------------
-strictTool("issue_retire_branch", "Mark a card's own `card/<id>` branch RETIRED (unsafe to merge); pass `reason`. No status gate — settable at any lifecycle stage, unlike the Done/Cancelled-only branch cleanup this is distinct from. `by` is server-stamped, never client-supplied. The next dispatch bootstrap forces `origin/main` as its checkout start point instead of re-attaching to the retired content; the origin ref itself is backed up then deleted separately as lazy hygiene. Idempotent — re-retiring just re-stamps reason/actor/timestamp.", {
-    id: z.string().min(1),
-    reason: z.string().min(1),
-    ...boardField,
-}, async (args) => jsonResult(await issueRetireBranch(client, args)));
-// ---------------- issue_quality_gate ----------------
-strictTool("issue_quality_gate", "Put one quality gate ON a card, or take it OFF (`action`) — the only way after create (issue_create names gates in quality_gates; issue_edit refuses gate keys). A gate on the card is required; add means it now runs, remove means it's gone entirely. PRE `plan-*` gates run before the work dispatch; POST `code-*` gates block complete. Unknown gate, or a never-gated type (Epic/Feature/Task), → 400. `note`/`effort_level` are add-only (400 with remove). Re-adding an existing gate updates note/effort and keeps its verdict; remove discards the row and its verdict. Board-scoped; see `board`.", {
-    id: z.string().min(1),
-    gate: z.enum([
-        "plan-dependency",
-        "plan-architecture",
-        "plan-tdd",
-        "code-test-quality",
-        "code-architecture",
-        "code-quality",
-    ]),
-    action: z
-        .enum(["add", "remove"])
-        .describe("add = put this gate on the card; remove = take it off."),
-    note: z
-        .string()
-        .optional()
-        .describe("Why this gate applies to this card. `add` only."),
-    effort_level: z.enum(EFFORT_VALUES).nullable().optional(),
-    ...boardField,
-}, async (args) => jsonResult(await issueQualityGate(client, args)));
-// ---------------- issue_quality_gate_verdict ----------------
-strictTool("issue_quality_gate_verdict", "Stamp an operator MANUAL quality-gate VERDICT (`status`, `message`) — the dashboard Gates-tab Pass/Fail/Revert write. Sibling of `issue_quality_gate` (that toggles whether a gate applies; this records whether it passed) — neither substitutes for the other. Needed to close a card claimed via `issue_transition pickup {manual:true}`: `complete` refuses 409 (`failed_gate: \"quality_gate_post\"`, `failed_post_gates[]`) while any required POST gate (`code-quality`/`code-test-quality`/`code-architecture`) isn't `pass`. `status`: pass|fail|pending (pending reverts a prior verdict, clearing the message). `message` required at >=20 characters for pass/fail (else 400), ignored for pending — record the real reviewer finding, not a rubber stamp. Pure row write: no side effects — a manual fail never blocks the card, a manual pass never releases a dispatch. Unknown gate/status → 400; unknown card → 404. Board-scoped; see `board`.", {
-    id: z.string().min(1),
-    gate: z.enum([
-        "plan-dependency",
-        "plan-architecture",
-        "plan-tdd",
-        "code-test-quality",
-        "code-architecture",
-        "code-quality",
-    ]),
-    status: z.enum(["pass", "fail", "pending"]),
-    message: z.string().optional(),
-    ...boardField,
-}, async (args) => jsonResult(await issueQualityGateVerdict(client, args)));
-// ---------------- quality_gate_instruction ----------------
-strictTool("quality_gate_instruction", "Fetch a named quality gate's current instruction — the same DB-catalog skill prose a dispatched gate reviewer's clean-room materializes, not card-scoped. Use from an operator session to run a gate manually: fetch the instruction, dispatch a tier-selected `danxbot:worker-*` with it, review, then record the verdict via `issue_quality_gate_verdict` — never a hand-written brief. `gate` is the same enum `issue_quality_gate` accepts. Unknown gate → 400; an unresolvable catalog artifact for this repo → 500. Board-scoped; see `board`.", {
-    gate: z.enum([
-        "plan-dependency",
-        "plan-architecture",
-        "plan-tdd",
-        "code-test-quality",
-        "code-architecture",
-        "code-quality",
-    ]),
-    ...boardField,
-}, async (args) => jsonResult(await qualityGateInstruction(client, args)));
-// ---------------- issue_retro ----------------
-strictTool("issue_retro", "Replace the retro block: {good, bad, correctable_danxbot_problem, correctable_danxbot_problem_description, action_item_ids[], commits[], tests[]}. Refuses 409 unless the card is terminal (completed_at or cancelled_at). good/bad upsert; the three list fields REPLACE (soft-delete prior live rows, fresh ordinals). action_item_ids[] entries match <PREFIX>-N. commits[] entries: {sha, subject?}. tests[] is required (empty array = ran none): one row per test GROUP that ran (name the group, not individual unit tests) or per e2e test (kind:'e2e', listed explicitly since few/expensive); each row {name, kind:'group'|'e2e', num_tests, num_passing_tests, duration_ms} required, num_assertions/num_passing_assertions nullable (omit when the runner has no assertion totals).", {
-    id: z.string().min(1),
-    good: z.string().describe("Free-form markdown (prose or list, they render identically). Style: see issue_comment's `text` param."),
-    bad: z.string().describe("Free-form markdown (prose or list, they render identically). Style: see issue_comment's `text` param."),
-    correctable_danxbot_problem: z
-        .boolean()
-        .describe("Required. Did this dispatch hit a problem in danxbot's OWN code/configuration (not \"this card was hard\") that danxbot could change so it stops happening? A true+described answer starts exactly one automated repair (fix or a ready card) — the only reliable channel for a danxbot defect found mid-dispatch. Answer explicitly every time, never a default."),
-    correctable_danxbot_problem_description: z
-        .string()
-        .describe("Required. Non-empty (naming the concrete problem) when correctable_danxbot_problem is true; must be empty when it is false."),
-    action_item_ids: z.array(z.string()),
-    commits: z.array(z.object({
-        sha: z.string().min(1),
-        subject: z.string().optional(),
-    }).strict()),
-    tests: z.array(z.object({
-        name: z.string().min(1),
-        kind: z.enum(["group", "e2e"]),
-        num_tests: z.number().int().nonnegative(),
-        num_assertions: z.number().int().nonnegative().nullable().optional(),
-        num_passing_tests: z.number().int().nonnegative(),
-        num_passing_assertions: z
-            .number()
-            .int()
-            .nonnegative()
-            .nullable()
-            .optional(),
-        duration_ms: z.number().int().nonnegative(),
-    }).strict()),
-    ...boardField,
-}, async (args) => jsonResult(await issueRetro(client, args)));
-// ---------------- issue_attach ----------------
-// The "25 MB" ceiling quoted in the description below tracks the backend
-// route's MAX_DECODED_BYTES (src/issues/write/attachments.ts). This package is
-// a separate published artifact and cannot import that constant, so the number
-// is restated here as prose — keep the two in sync if the backend ceiling moves.
-strictTool("issue_attach", "Attach a LOCAL file to an issue card: `id` (the card) + `file_path` (an ABSOLUTE path on the dispatch's shared filesystem). Reads the bytes, infers MIME from the extension, uploads via the dashboard: stores in S3, inserts one attachment row, auto-mirrors to the card's linked Trello card and Slack thread. Board-scoped; see `board`. Fail-loud: a relative/empty path is rejected at the boundary; a missing/unreadable file throws before any upload (no partial S3 object or row). 25 MB decoded ceiling (413). Returns `{issue, attachment_id, s3_key}` — find the attachment in `issue.attachments` by `attachment_id` to read its permanent, non-expiring `url`. That url can be embedded in ANY markdown field (a problem's statement/context, a comment, a plan record, a solution body) as `![description](url)` — the dashboard renders it inline as a thumbnail. Use whenever a screenshot judges something faster than prose.", {
-    id: z.string().min(1),
-    file_path: z
+}, async (args) => jsonResult(await danxbotApi(client, args)));
+// ---------------- danxbot_api_list (DX-3465 A5, PLN-11 R-25) ----------------
+strictTool("danxbot_api_list", "Lists the dashboard API routes your credential may call right now — `[{method, path, summary, permission}]`, " +
+    "one line each, in the route TEMPLATE form `danxbot_api_spec` also expects (e.g. " +
+    '`"POST /api/issues/:id/transition"`). This is how you find the route for something you need to do: a ' +
+    "route listed here is always callable by you; one that isn't never appears (DX-3528 filters through the " +
+    "SAME permission check the dashboard enforces on every request, so this list can never drift from what " +
+    "you can actually call). No arguments. Call this when you don't already know the route, then " +
+    "`danxbot_api_spec({endpoints})` for the exact contract of the one(s) you picked, then `danxbot_api` to " +
+    "call it.", {}, async () => jsonResult(await danxbotApiList(client)));
+// ---------------- danxbot_api_spec (DX-3465, PLN-11 R-25) ----------------
+strictTool("danxbot_api_spec", "The exact OpenAPI 3.1 contract (DX-3527) for one or more routes — request/response shape, required " +
+    "permission, and every documented error envelope. `endpoints` (REQUIRED, non-empty): an array of " +
+    '`"METHOD /path/template"` strings (e.g. `"POST /api/issues/:id/transition"`, the route TEMPLATE form, ' +
+    "unlike `danxbot_api`'s own `path` which is a real path with real ids — the same form `danxbot_api_list` " +
+    "reports). A requested endpoint this dashboard does not serve, or that your credential may not call, is " +
+    "refused loud (never silently dropped or silently included) — see the response for which. Don't know which " +
+    "endpoints to name? call `danxbot_api_list` first.", {
+    endpoints: z.array(z.string().min(1)).min(1),
+}, async (args) => jsonResult(await danxbotApiSpec(client, args)));
+// ---------------- attach_file (DX-3465 A4, checklist item 36140) ----------------
+//
+// The "25 MB" ceiling quoted below tracks the backend route's
+// MAX_DECODED_BYTES (`src/issues/write/attachments.ts`). This package is a
+// separate published artifact and cannot import that constant, so the
+// number is restated here as prose — keep the two in sync if the backend
+// ceiling moves. Opt-in (R-25's "operations about the agent itself" carve-
+// out plus a role-by-role grant, see `tool-defs.ts`'s `MCP_SERVER_OPT_IN_TOOLS`
+// — a role needs local-file-upload only when it deals with files an agent
+// might hold locally, e.g. the Slack recovery agent's CSV path).
+strictTool("attach_file", "Attach a LOCAL file to a card: `card_id` + `path` (an ABSOLUTE path on the dispatch's shared filesystem). " +
+    "Reads the bytes INSIDE this MCP server process and uploads them — the file's bytes never pass through " +
+    "your own context/transcript. Infers MIME from the extension unless you pass `content_type`; defaults " +
+    "`filename` to the path's basename unless you pass one. Stores in S3, inserts one attachment row, auto-" +
+    "mirrors to the card's linked Trello card and Slack thread. Board-scoped; see `board`. Fail-loud: a " +
+    "relative/empty path is rejected before any upload; a missing/unreadable file throws before any upload " +
+    "(no partial S3 object or row). 25 MB decoded ceiling (413). Returns `{issue, attachment_id, s3_key}` — " +
+    "find the attachment in `issue.attachments` by `attachment_id` to read its permanent, non-expiring `url`. " +
+    "That url can be embedded in ANY markdown field (a problem's statement/context, a comment, a plan record, " +
+    "a solution body) as `![description](url)` — the dashboard renders it inline as a thumbnail. Use whenever " +
+    "a screenshot or a local file judges something faster than prose, or replaces pasting a large CSV/log " +
+    "straight into a card field.", {
+    card_id: z.string().min(1).describe("The card id to attach the file to."),
+    path: z
         .string()
         .min(1)
         .describe("Absolute path to a local file on the dispatch's shared filesystem (must start with `/`)."),
+    filename: z.string().min(1).optional().describe("Override for the stored filename; default: path's basename."),
+    content_type: z.string().min(1).optional().describe("Override for the stored MIME type; default: an extension guess."),
     ...boardField,
-}, async (args) => jsonResult(await issueAttach(client, args)));
+}, async (args) => jsonResult(await attachFile(client, args)));
 // ---------------- plans (DX-2683) ----------------
-// THE BINDING ASYMMETRY IS IN THE SCHEMAS, NOT IN PROSE. `plan_get` takes an
-// optional `plan_id`; `plan_add_record`, `plan_get_record`,
-// `plan_update_record`, `plan_delete_record`, `plan_add_card` and the five
-// `plan_*_architecture_section` tools take NO plan id in any form, so a
-// connected session cannot even express "write to that other plan". `plan_connect` takes one
-// because binding a session to a plan is the one operation that is ABOUT a
-// plan id — and it can only ever bind the caller's own session. `plan_create`
-// also takes no plan id, but for a different reason: it MAKES a plan rather
-// than acting on one, so there is no existing plan for an id to name yet.
-strictTool("plan_list", "List every plan, and learn which plan THIS session is connected to. Plans are GLOBAL, not board-scoped — a plan is a named, dated set of cards an operator assembled by hand, from any repo. Returns `{plans: [{id, ref, name, createdAt, cardCount, boards, status, signedOffAt, signedOffBy, autoSignOff}], session, sessionListenerAttached}` — `ref` is the plan's short reference (`PLAN-<id>`), cite it rather than the bare id. `status` is computed fresh on every read, never stored — except the sign-off pair itself: `awaiting-session` (no live session — a session row isn't released just because a session ended), `planning` (no cards, or only Review/Backlog/terminal ones with ≥1 not Done/Cancelled), `building` (a live session AND ≥1 card ToDo/In Progress or stuck-but-active — Blocked/Needs Help), `awaiting-sign-off` (≥1 card, all Done/Cancelled, but nobody has signed the plan off yet — DX-3519), `complete` (≥1 card, all Done/Cancelled, AND signed off — wins even with no session). `signedOffAt`/`signedOffBy` are `null` until a human (`signedOffBy` = their identity) or the `autoSignOff` toggle (`signedOffBy: 'auto'`) signs the plan off; sign-off itself is a human-only write, not exposed through this MCP surface — direct the operator to the dashboard's plan page. Pass `status` to filter. `session` is your own registration (`{sessionId, title, planId, planName, firstSeenAt, lastActiveAt}`) or null outside a Claude Code session; `planId: null` means connected to no plan — `plan_get` to browse, `plan_connect` to bind. `sessionListenerAttached` says whether your event stream is attached (the plugin's plan bridge); false for a few seconds right after connect is normal, false after that means events aren't reaching you — tell the operator.", {
-    status: z
-        .enum(PLAN_STATUSES)
-        .optional()
-        .describe("Filter to one computed status: awaiting-session, planning, building, awaiting-sign-off, complete. Omit for every plan."),
-}, async (args) => jsonResult(await planList(client, args)));
-strictTool("plan_get", 
-// DX-3428 — the retired flat field-GROUP list (`cards`, `records:<kind>`,
-// `cards_offset`/`cards_limit`, `events_*`) is replaced by a JSON field
-// TREE against the plan resource — the SAME `fieldTreeSchema` `issue_get`/
-// `issue_list` already take (`./field-tree.ts`). Every former query param
-// now lives INSIDE the tree as a relation argument.
-"Read a plan. Pass `plan_id` to read ANY plan; OMIT to read the plan this session is connected to — omitting while connected to none fails loud `{error: \"session_not_connected\"}`, connect first. A BARE call (no `fields`) returns ONLY the plan's cheap scalars: `{id, ref, name, created_at, signed_off_at, signed_off_by, auto_sign_off, boards, card_count, bucket_counts, status, session, sessionListenerAttached}` — no cards, records, or architecture body. `ref` is the plan's short reference (`PLAN-<id>`) — cite that, not the bare id. `status` is computed fresh on every read, never stored — see `plan_list` for the four values and what each means. Pass a `fields` tree to opt into: `cards` (member cards — the ISSUE resource itself, so any of `issue_get`'s own fields/relations may be nested under it, e.g. `{\"cards\": {\"title\": true, \"status\": true}}`; cursor-paged via `{\"limit\": N, \"before\": \"<cursor>\"}`, response carries a sibling `cards_page: {limit, total, next_cursor}`), `records` (every goal+rule+caveat) or `{\"records\": {\"kind\": \"goal\"}}` / `{\"kind\": [\"goal\",\"rule\"]}` (narrow to one or more kinds, cheaper), `architecture_sections` (`[{id, plan_id, content_hash, title, content, sort_order, created_at, updated_at}]`), `sessions` (every session connected to the plan), `notes` (the latest milestone-timeline page), `events` (the plan's durable event ledger — every human action and bridge message; cursor-paged via `{\"limit\": N, \"before\": \"<cursor>\"}` plus the filter args `{\"kinds\": [...], \"origin\": \"...\", \"writer\": \"...\"}`; response carries `events` rows plus a sibling `events_page: {limit, total, next_cursor}`; `next_cursor` null on the last page; an event on a card whose board you cannot read is left out, plan-level events are always visible). Call `resource_fields({resource:\"plan\"})` for the full, current list of what a tree may name — never guess a name; unknown → 400 `unknown_field`. `session`/`sessionListenerAttached` ride every response regardless (not part of the tree — they describe YOUR session, not the plan). `sessionListenerAttached` is `false` for a few seconds right after `plan_connect` while the plugin's event bridge starts; still `false` after that while connected means the plan's card events are not reaching you — tell the operator. ALWAYS `plan_get`/`plan_get_architecture_section` immediately before `plan_update_architecture_section`/`plan_delete_architecture_section` and pass the returned `content_hash`/`contentHash` back as `base_hash`.", {
-    plan_id: z
-        .number()
-        .int()
-        .positive()
-        .optional()
-        .describe("A plan id from `plan_list`. Omit to read the plan this session is connected to."),
-    fields: fieldTreeSchema
-        .optional()
-        .describe("A field tree (see tool description); absent/empty = cheap scalars only. `resource_fields({resource:\"plan\"})` names every valid key."),
-}, async (args) => jsonResult(await planGet(client, args)));
-strictTool("plan_create", "Create a new, empty plan. Global — not board-scoped. Adds no cards, records, or architecture sections, and does not connect any session (call `plan_connect` separately). Returns `{plan: {id, ref, name, createdAt}}` — `ref` is the short reference (`PLAN-<id>`). Use `plan.id` with `plan_connect` to start working on it, or `plan_get({plan_id})` to browse.", {
-    name: z.string().min(1).describe("The plan's name — shown in the Plans list."),
-}, async (args) => jsonResult(await planCreate(client, args)));
+// THE BINDING ASYMMETRY IS IN THE SCHEMAS, NOT IN PROSE. `GET /api/plans/:planId`
+// takes a plan id in its path; the plan records, plan cards and
+// architecture-section routes under `/api/plans/mine/...` take NO plan id in
+// any form, so a connected session cannot even express "write to that other
+// plan". `plan_connect` takes a plan id because binding a session to a plan
+// is the one operation that is ABOUT a plan id — and it can only ever bind
+// the caller's own session. `POST /api/plans` also takes no plan id, but for
+// a different reason: it MAKES a plan rather than acting on one, so there is
+// no existing plan for an id to name yet.
 strictTool("plan_connect", 
 // DX-2735: trimmed with the problem tools to stay inside the work-profile budget.
-"Connect THIS session to a plan. ONE CALL IS ENOUGH TO START: the reply carries `{session, movedFrom, browserInstruction, briefing, listenerHealth}` — `browserInstruction` is a server-built action to take NOW: it names the plan's URL and tells you to open it (in-app browser if you have one, else default), keep that tab open for the whole session without navigating it away, and use a different tab for your own browsing — the operator's tab for following and talking to you. Returned on every connect, including a re-connect, so it doubles as the post-context-loss reminder. `briefing` is every goal/rule/caveat (ref+body), every architecture section (id+title), the plan's own ref/name/status, a first page of open cards (id/type/status/title/openProblemCount/assignedAgent) with a `morePagesHint` when more exist, and the closed-card count — usually replacing the `plan_get({fields: {...}})` + card batch-read a fresh session used to need. A session is on AT MOST ONE plan: connecting elsewhere MOVES it, and `movedFrom: {id, name} | null` says which plan it left (null = no plan, or already this one). Binds only your OWN session, resolved from the session id this server forwards; afterwards every plan WRITE tool acts on this plan and takes no plan id. `listenerHealth` reports the event bridge's state — `null` (no session), or `{attached, state: \"unattached\"|\"credential_mismatch\"|\"healthy\", nextStep}` naming a concrete fix per unhealthy state (same shape `plan_list`/`plan_get` report). Once healthy, every comment, answer, problem added and block/unblock on this plan's cards reaches the session unpolled, relayed by the plugin's event bridge as a line like `[DX-8 \"Title\" repo:board] newms87 answered \"<statement>\": chose \"Pause E2E\"`. Pass `title` (call `get_session({session_id:\"self\"})` first and forward its `title` verbatim) so the dashboard shows the same name Claude does — this server cannot read it itself.", {
-    plan_id: z.number().int().positive().describe("The plan id, from `plan_list`."),
+"Connect THIS session to a plan. ONE CALL IS ENOUGH TO START: the reply carries `{session, movedFrom, browserInstruction, briefing, listenerHealth}` — `browserInstruction` is a server-built action to take NOW: it names the plan's URL and tells you to open it (in-app browser if you have one, else default), keep that tab open for the whole session without navigating it away, and use a different tab for your own browsing — the operator's tab for following and talking to you. Returned on every connect, including a re-connect, so it doubles as the post-context-loss reminder. `briefing` is every goal/rule/caveat (ref+body), every architecture section (id+title), the plan's own ref/name/status, a first page of open cards (id/type/status/title/openProblemCount/assignedAgent) with a `morePagesHint` when more exist, and the closed-card count — usually replacing the plan read + card batch-read a fresh session used to need. A session is on AT MOST ONE plan: connecting elsewhere MOVES it, and `movedFrom: {id, name} | null` says which plan it left (null = no plan, or already this one). Binds only your OWN session, resolved from the session id this server forwards; afterwards every plan WRITE tool acts on this plan and takes no plan id. `listenerHealth` reports the event bridge's state — `null` (no session), or `{attached, state: \"unattached\"|\"credential_mismatch\"|\"healthy\", nextStep}` naming a concrete fix per unhealthy state (same shape the plan list/get routes report). Once healthy, every comment, answer, problem added and block/unblock on this plan's cards reaches the session unpolled, relayed by the plugin's event bridge as a line like `[DX-8 \"Title\" repo:board] newms87 answered \"<statement>\": chose \"Pause E2E\"`. Pass `title` (call `get_session({session_id:\"self\"})` first and forward its `title` verbatim) so the dashboard shows the same name Claude does — this server cannot read it itself. The response's `reminders[]` (when present) carries the mantra — read and follow it.", {
+    plan_id: z.number().int().positive().describe("The plan id, from the plans list (`danxbot_api` `GET /api/plans`)."),
     title: z
         .string()
         .min(1)
@@ -931,139 +419,6 @@ async (args) => {
         }),
     });
 });
-strictTool("plan_add_record", "Add a goal, rule or caveat to your connected plan (see `kind`'s own values below for what each means — never progress/status/session notes, those are card comments). `body` is one plain statement, at most 250 characters (400 if longer); detail goes in markdown `context`. Allocates a permanent reference (`G-1`, `R-4`, `CAV-12`). Takes no plan id; not connected → `plan_connect` first. Returns the created record plus `records_count` (that kind's live count, not the whole list) — read the list with `plan_get({fields: {records: {kind: \"<kind>\"}}})`.", {
-    kind: z.enum(["goal", "rule", "caveat"]).describe("goal = outcome, rule = constraint, caveat = architecture trade-off."),
-    body: z.string().min(1).describe("One plain statement, at most 250 characters. Details go in `context`."),
-    context: z.string().optional().describe("Markdown detail behind the statement: evidence, history, examples."),
-}, async (args) => jsonResult(await planAddRecord(client, args)));
-strictTool("plan_get_record", "Read one goal/rule/caveat without pulling the whole plan. Takes no plan id; an unknown or foreign record id → 404. Returns `{record: {id, planId, kind, refNum, ref, body, context, contentHash, createdAt, updatedAt}}` — `context` is markdown detail, or null.", {
-    record_id: z.number().int().positive().describe("A record id, from `plan_add_record`, `plan_get` or `plan_get_record` itself."),
-}, async (args) => jsonResult(await planGetRecord(client, args)));
-strictTool("plan_update_record", 'Edit a goal/rule/caveat. The reference never moves. `body` stays one plain statement, at most 250 characters (400 otherwise); detail belongs in markdown `context`. `content_hash` must be the record\'s last-read `contentHash` (covers body AND context); on mismatch nothing is written and you get `{error: "stale_plan_record", currentHash, currentBody, currentContext}` — merge and retry with `content_hash: currentHash`, never blindly. Takes no plan id. Returns the edited record plus `records_count` (see `plan_add_record`).', {
-    record_id: z.number().int().positive().describe("The record id to edit."),
-    content_hash: z.string().describe("The record's `contentHash` from your last read. Required."),
-    body: z.string().min(1).describe("The new statement, at most 250 characters. Plain text."),
-    context: z
-        .string()
-        .nullable()
-        .optional()
-        .describe("New markdown detail. Omit to keep the stored context; null clears it."),
-}, async (args) => jsonResult(await planUpdateRecord(client, args)));
-strictTool("plan_delete_record", 'Soft-delete a goal/rule/caveat; its reference is retired permanently, never reused. `content_hash` must be the record\'s last-read `contentHash` — stale deletes nothing, returns `{error: "stale_plan_record", currentHash, currentBody, currentContext}`. Takes no plan id. Unknown or already-deleted id → 404. Returns `{records_count}` (see `plan_add_record`).', {
-    record_id: z.number().int().positive().describe("The record id to delete."),
-    content_hash: z.string().describe("The record's `contentHash` from your last read. Required."),
-}, async (args) => jsonResult(await planDeleteRecord(client, args)));
-strictTool("plan_add_note", "Write a milestone note to a plan's timeline — a MILESTONE, not a log: use for a card (or group) finishing, an important decision, or a meaningful goal/rule/caveat/architecture change; routine progress stays a card comment. Terse: `title` at most 60 characters, `body` at most 250 (400 if too long, naming the limit). Links resolve on read into their target (a card's title, a record's ref+body, a section's title); an unknown card, unparseable/foreign record ref, or unknown/foreign section id is refused 400 naming which one. A card link needn't be a plan member; a record/section link must belong to THIS plan. `author` is stamped server-side. Takes an explicit `plan_id` (like `plan_remove_card`/`plan_rename`) so a dispatched worker with no plan connection can still write. Unknown plan → 404. Returns the new note plus `notes_count` (the plan's total live count, not the latest page) — read the timeline with `plan_get({fields: {notes: true}})`.", {
-    plan_id: z.number().int().positive().describe("The plan id, from `plan_list`."),
-    title: z.string().min(1).describe("At most 60 characters."),
-    body: z.string().min(1).describe("The wrap-up, at most 250 characters."),
-    card_ids: z.array(z.string().min(1)).optional().describe("Card ids this note concerns, e.g. `[\"DX-2894\"]`."),
-    record_refs: z
-        .array(z.string().min(1))
-        .optional()
-        .describe("Goal/rule/caveat references this note announces, e.g. `[\"G-1\", \"R-3\", \"CAV-2\"]`."),
-    section_ids: z.array(z.number().int().positive()).optional().describe("Architecture section ids this note announces."),
-}, async (args) => jsonResult(await planAddNote(client, args)));
-strictTool("plan_update_note", 'Edit a plan note. `content_hash` must be the note\'s last-read `contentHash` (covers title, body AND the link set); a mismatch writes nothing and returns `{error: "stale_plan_note", currentHash, currentTitle, currentBody, currentLinks}` — merge and retry, never blindly. `title`/`body` optional, keep stored value when omitted. The link fields (`card_ids`/`record_refs`/`section_ids`) are all-or-nothing as a group: omit all three to leave links untouched, send ANY one to REPLACE THE WHOLE SET — no per-link add/remove. Takes an explicit `plan_id` (see `plan_add_note`). Unknown plan or note id → 404. Returns the edited note plus `notes_count`.', {
-    plan_id: z.number().int().positive().describe("The plan id, from `plan_list`."),
-    note_id: z.number().int().positive().describe("The note id to edit."),
-    content_hash: z.string().describe("The note's `contentHash` from your last read. Required."),
-    title: z.string().min(1).optional().describe("New title, at most 60 characters. Omit to keep the stored title."),
-    body: z.string().min(1).optional().describe("New wrap-up, at most 250 characters. Omit to keep the stored body."),
-    card_ids: z.array(z.string().min(1)).optional().describe("Part of the link-set group — see tool description."),
-    record_refs: z.array(z.string().min(1)).optional().describe("Part of the link-set group — see tool description."),
-    section_ids: z.array(z.number().int().positive()).optional().describe("Part of the link-set group — see tool description."),
-}, async (args) => jsonResult(await planUpdateNote(client, args)));
-strictTool("plan_delete_note", 'Soft-delete a plan note. `content_hash` must be the note\'s last-read `contentHash` — stale deletes nothing, returns `{error: "stale_plan_note", currentHash, currentTitle, currentBody, currentLinks}` (same shape as `plan_update_note`). Takes an explicit `plan_id` (see `plan_add_note`). Unknown plan, note, or already-deleted note → 404. Returns `{notes_count}`.', {
-    plan_id: z.number().int().positive().describe("The plan id, from `plan_list`."),
-    note_id: z.number().int().positive().describe("The note id to delete."),
-    content_hash: z.string().describe("The note's `contentHash` from your last read. Required."),
-}, async (args) => jsonResult(await planDeleteNote(client, args)));
-strictTool("plan_add_card", "Add an existing card, from ANY board, to the plan this session is connected to. Idempotent (re-adding is a no-op; a card may sit in several plans). Adds MEMBERSHIP only, never edits the card. Takes no plan id — resolved from your connected session. Not connected → `{error: \"session_not_connected\"}`. Unknown card → 404. Returns `{card_id, member: true, cards_count}` (the plan's total member-card count, not the full list — a plan can hold hundreds; read it with `plan_get({fields: {cards: true}})`, cursor-paged).", {
-    card_id: z.string().min(1).describe("An existing card id, e.g. `DX-2683`."),
-}, async (args) => jsonResult(await planAddCard(client, args)));
-strictTool("plan_remove_card", "Remove a card from a plan — sibling of `plan_add_card`, any board. Idempotent (removing a non-member is a no-op). Removes MEMBERSHIP only — never touches the card itself or its membership in other plans. Unlike `plan_add_card`, takes an EXPLICIT `plan_id` — you may remove from any plan you can name. Unknown plan → 404. Returns `{card_id, member: false, cards_count}` (see `plan_add_card`).", {
-    plan_id: z.number().int().positive().describe("The plan id, from `plan_list`."),
-    card_id: z.string().min(1).describe("An existing card id, e.g. `DX-2683`."),
-}, async (args) => jsonResult(await planRemoveCard(client, args)));
-strictTool("plan_rename", "Rename a plan — the only way to change `name`. Takes an EXPLICIT `plan_id`, so you may rename any plan you can name. `name` non-empty (400 otherwise). Unknown plan → 404. Returns the renamed plan `{id, ref, name, createdAt}`.", {
-    plan_id: z.number().int().positive().describe("The plan id, from `plan_list`."),
-    name: z.string().min(1).describe("The plan's new name."),
-}, async (args) => jsonResult(await planRename(client, args)));
-strictTool("plan_get_architecture_section", "Read one section of the plan this session is connected to. Takes no plan id — resolved from your connected session. Not connected → `{error: \"session_not_connected\"}`. Unknown or foreign section id → 404. Returns `{section: {id, planId, contentHash, title, content, sortOrder, createdAt, updatedAt}}`.", {
-    section_id: z.number().int().positive().describe("A section id, from `plan_get` or `plan_add_architecture_section`."),
-}, async (args) => jsonResult(await planGetArchitectureSection(client, args)));
-strictTool("plan_add_architecture_section", "Append a section to your connected plan's architecture. Architecture is SECTIONS, not one document — each independently editable and hash-guarded, so editing one never stales a concurrent edit to another. Sorts after every existing live section; use `plan_reorder_architecture_section` to move it. Takes no plan id; not connected → `plan_connect` first. Returns the new section plus the plan's full live section list.", {
-    title: z.string().min(1).describe("The section's heading, shown in the navigation index."),
-    content: z.string().describe("The section's markdown. May be empty — a section awaiting its first draft is a real state."),
-}, async (args) => jsonResult(await planAddArchitectureSection(client, args)));
-strictTool("plan_update_architecture_section", 'Edit a section\'s title and/or content — both optional, send only what changed. `base_hash` must be the section\'s last-read `contentHash`; on mismatch fails loud with `{error: "stale_plan_architecture_section", currentHash, currentTitle, currentContent}` rather than overwriting a concurrent write — merge and retry, never blindly. Takes no plan id. Returns the edited section plus the plan\'s full live section list.', {
-    section_id: z.number().int().positive().describe("The section id to edit."),
-    base_hash: z.string().describe("The section's `contentHash` from your last read. Required."),
-    title: z.string().min(1).optional().describe("New heading. Omit to keep the stored title."),
-    content: z.string().optional().describe("New markdown. Omit to keep the stored content."),
-}, async (args) => jsonResult(await planUpdateArchitectureSection(client, args)));
-strictTool("plan_delete_architecture_section", 'Soft-delete a section of your connected plan\'s architecture. `base_hash` must be the section\'s last-read `contentHash` — stale deletes nothing, returns `{error: "stale_plan_architecture_section", currentHash, currentTitle, currentContent}`; re-fetch and confirm before retrying, never blindly. Takes no plan id. Unknown or already-deleted section id → 404. Returns the plan\'s remaining live section list.', {
-    section_id: z.number().int().positive().describe("The section id to delete."),
-    base_hash: z.string().describe("The section's `contentHash` from your last read. Required."),
-}, async (args) => jsonResult(await planDeleteArchitectureSection(client, args)));
-strictTool("plan_reorder_architecture_section", "Reassign your connected plan's section display order. Unguarded by content hash by design — moving a section never changes any `contentHash`. `order` must name EXACTLY the plan's current live section ids, each once — a partial or foreign list refuses 400 rather than silently reordering a subset. Takes no plan id. Returns the plan's full live section list in its new order.", {
-    order: z
-        .array(z.number().int().positive())
-        .min(1)
-        .describe("Every live section id of the connected plan, in the desired order — exactly once each."),
-}, async (args) => jsonResult(await planReorderArchitectureSection(client, args)));
-// ---------------- failure_category_list / _create / _update (DX-2792) ----------------
-const matcherField = z
-    .object({
-    sourceKind: z
-        .enum(["tool-error", "hook-refusal", "api-error", "usage-limit", "session-result"])
-        .optional()
-        .describe("Absent matches any source kind."),
-    tool: z.string().min(1).optional().describe("Exact tool name (e.g. \"Bash\"); absent matches any tool, including null."),
-    regexPattern: z
-        .string()
-        .min(1)
-        .optional()
-        .describe("Regex source tested against the normalized excerpt (paths/UUIDs/timestamps/ports already stripped)."),
-})
-    .strict()
-    .describe("At least one of sourceKind/tool/regexPattern must be set — an empty matcher is refused.");
-const expectedRateField = z
-    .object({
-    count: z.number().int().min(0).describe("N — how many failures are expected."),
-    overDispatches: z.number().int().positive().describe("X — over how many dispatches."),
-})
-    .strict()
-    .nullable()
-    .optional()
-    .describe("Both fields together, or omit/null entirely — never a half-specified rate.");
-strictTool("failure_category_list", "List every failure category. Board-less — applies across the whole install. Returns `{categories: [{id, name, description, matchers, ignore, ignoreReason, expectedRate, matchedCount, lastSeenMs, createdAtMs, createdBy, updatedAtMs, updatedBy}]}`, id ascending (`[]` on a fresh install). Read this immediately before `failure_category_create`/`_update` so your overlap decision is against the current set, not a stale snapshot.", {}, async () => jsonResult(await failureCategoryList(client)));
-strictTool("failure_category_create", 'Create a new failure category. Board-less. `matchers` (≥1) is OR-across-matchers — matches an occurrence when ANY ONE matcher\'s fields all hold. `ignore: true` requires non-empty `ignoreReason` (400 otherwise) — use for an expected, non-actionable failure. A matcher set overlapping an EXISTING category refuses 400 naming the conflict — list first and EXPAND that category (`failure_category_update`) instead of a near-duplicate. On success, re-matches every uncategorized occurrence against the new category.', {
-    name: z.string().min(1).describe("The category's name."),
-    description: z.string().optional().describe("Optional free-text description. Defaults to empty."),
-    matchers: z.array(matcherField).min(1).describe("At least one matcher; a category matches an occurrence when ANY ONE matches (OR across matchers)."),
-    ignore: z.boolean().optional().describe("Mark this category as expected/non-actionable noise. Requires ignoreReason. Defaults to false."),
-    ignoreReason: z.string().nullable().optional().describe("Required (non-empty) when ignore is true."),
-    expectedRate: expectedRateField,
-}, async (args) => jsonResult(await failureCategoryCreate(client, args)));
-strictTool("failure_category_update", "Patch an existing failure category. Board-less. Covers both: expanding matchers (send the FULL replacement `matchers` array — it REPLACES, not appends, so include every matcher you want to keep) and marking ignored (`ignore: true` + non-empty `ignoreReason`). At least one field besides `id` required (400 otherwise). Same overlap refusal as create, excluding this category's own prior matchers. On success, re-matches every uncategorized occurrence against the updated set.", {
-    id: z.number().int().positive().describe("The category id to patch — from failure_category_list."),
-    name: z.string().min(1).optional(),
-    description: z.string().optional(),
-    matchers: z.array(matcherField).min(1).optional().describe("REPLACES the full matcher set when sent — never a partial append."),
-    ignore: z.boolean().optional(),
-    ignoreReason: z.string().nullable().optional(),
-    expectedRate: expectedRateField,
-}, async (args) => jsonResult(await failureCategoryUpdate(client, args)));
-// ---------------- dispatch_transcript_search (DX-3221) ----------------
-strictTool("dispatch_transcript_search", "Search or tail another dispatch's stored JSONL transcript. Needs no filesystem access (an authenticated HTTP call, not a local read) and fixes what Read cannot: a single JSONL entry can exceed Read's token cap with no way to sub-page inside it, so this tool searches itself and returns only a bounded excerpt around a match. With `pattern`: up to `maxMatches` matching lines (case-insensitive regex), each windowed to `contextChars` around the first match. Without `pattern`: the most recent `tail` lines instead, each capped at `contextChars` (`truncated: true` marks a capped excerpt either way, never a thrown error). `dispatchId` is a real `dispatches.id` — e.g. from a failure-repair card's own body.", {
-    dispatchId: z.string().min(1).describe("The dispatch id whose transcript to search — from a failure-repair card's own body, or any other dispatch id you already have."),
-    pattern: z.string().min(1).optional().describe("Case-insensitive regex tested against each raw JSONL line. Omit to get a tail read of the most recent lines instead."),
-    tail: z.number().int().positive().optional().describe("Only used when `pattern` is omitted. How many of the most recent lines to return. Defaults to 20, capped at 200."),
-    contextChars: z.number().int().positive().optional().describe("Characters of context per returned line/match. Defaults to 1000, capped at 4000 — this cap is what keeps even a single oversized line searchable instead of erroring the way Read does."),
-    maxMatches: z.number().int().positive().optional().describe("Only used with `pattern`. Stop after this many matching lines. Defaults to 10, capped at 50."),
-}, async (args) => jsonResult(await dispatchTranscriptSearch(client, args)));
 // ---------------- main ----------------
 async function main() {
     boot();
@@ -1119,20 +474,21 @@ if (isEntrypointModule(import.meta.url, process.argv[1])) {
             process.exit(0);
         });
     }
-    else if (subcommand === MANTRA_SUBCOMMAND) {
-        // DX-3366 — unlike plan-state/background-work, a rejection here is a
-        // genuine fatal (never expected: runMantraCommand itself already
-        // classifies every network/shape failure into its own {ok:false} exit
-        // 1), so it exits 1 too rather than the "always 0, stay silent" contract
-        // those two hook-only subcommands use.
-        runMantraCommand(rest).then((code) => process.exit(code), (err) => {
-            console.error(`[danx-dashboard-mcp] mantra fatal: ${err.message}`);
+    else if (subcommand === EVENT_TEXT_SUBCOMMAND) {
+        // DX-3421 (was DX-3366's `mantra` subcommand) — unlike plan-state/
+        // background-work, a rejection here is a genuine fatal (never expected:
+        // runEventTextCommand itself already classifies every network/shape
+        // failure into its own {ok:false} exit 1), so it exits 1 too rather than
+        // the "always 0, stay silent" contract those two hook-only subcommands
+        // use.
+        runEventTextCommand(rest).then((code) => process.exit(code), (err) => {
+            console.error(`[danx-dashboard-mcp] event-text fatal: ${err.message}`);
             process.exit(1);
         });
     }
     else if (subcommand !== undefined) {
         console.error(`[danx-dashboard-mcp] unknown subcommand "${subcommand}" (the only ones are ` +
-            `"${BRIDGE_SUBCOMMAND}", "${PLAN_STATE_SUBCOMMAND}", "${BACKGROUND_WORK_SUBCOMMAND}", and "${MANTRA_SUBCOMMAND}")`);
+            `"${BRIDGE_SUBCOMMAND}", "${PLAN_STATE_SUBCOMMAND}", "${BACKGROUND_WORK_SUBCOMMAND}", and "${EVENT_TEXT_SUBCOMMAND}")`);
         process.exit(2);
     }
     else {