@bridge_gpt/mcp-server 0.1.17 → 0.2.1

package/build/index.js

@@ -14,6 +14,8 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { writeFile, mkdir, readFile, stat } from "fs/promises";
 import path from "path";
+import os from "os";
+import { fileURLToPath } from "url";
 import { execSync } from "child_process";
 import { createRequire } from "module";
 import { PIPELINES as BUNDLED_PIPELINES, INSTRUCTIONS as BUNDLED_INSTRUCTIONS, CHAIN_RECIPES } from "./pipelines.generated.js";
@@ -26,8 +28,14 @@ import { resolveRecipe, loadCustomPipelines } from "./pipeline-utils.js";
 import { runStartTicketsCli } from "./start-tickets.js";
 import { runDoctorCli } from "./doctor.js";
 import { runScheduleRunCli } from "./schedule-run.js";
+import { runMcpInvokeCli } from "./mcp-invoke.js";
+import { runAgentCapabilitiesCli } from "./agent-capabilities/cli.js";
+import { validateRepoName } from "./bridge-config.js";
+import { ensureGitignored as ensureGitignoredShared } from "./git-ignore-utils.js";
+import { resolveBapiCredentials } from "./credential-store.js";
 import { generateDecisionPageHtml } from "./decision-page-template.js";
 import { DecisionPageInputShape } from "./decision-page-schema.js";
+import { slugify, saveBrainstormResultsToDir, } from "./brainstorm-files.js";
 import { runPipeline, resumePipeline, listPipelineRuns, deletePipelineRun, deriveIdeaHash, } from "./pipeline-orchestrator.js";
 import { runFullAutomation, resumeFullAutomation, } from "./chain-orchestrator.js";
 // Mutable pipeline/instruction state — starts with bundled, merged with user at startup
@@ -39,15 +47,137 @@ let userPipelineKeys = new Set();
 // ---------------------------------------------------------------------------
 const BASE_URL = process.env.BAPI_BASE_URL ?? "https://bridgegpt-api.com";
 const REPO_NAME = process.env.BAPI_REPO_NAME ?? "";
-const API_KEY = process.env.BAPI_API_KEY ?? "";
-const PROJECT_ROOT = process.env.BAPI_PROJECT_ROOT ?? process.cwd();
-const BAPI_DOCS_DIR = path.resolve(PROJECT_ROOT, process.env.BAPI_DOCS_DIR ?? "docs/tmp");
-const BAPI_PIPELINES_DIR = path.resolve(PROJECT_ROOT, process.env.BAPI_PIPELINES_DIR ?? ".bridge/pipelines");
-const GET_HEADERS = { "X-API-Key": API_KEY };
-const POST_HEADERS = {
-    "X-API-Key": API_KEY,
-    "Content-Type": "application/json",
-};
+// ---------------------------------------------------------------------------
+// Resolved-once credential + path accessors (BAPI-338)
+//
+// The API key, auth headers, project root, docs dir, and pipelines dir are NO
+// LONGER eager module-load constants. They are resolved lazily on first use and
+// cached, so:
+//   - the credential store is read only when BAPI_API_KEY is absent from env;
+//   - the project root can be resolved from MCP `roots/list`, which is only
+//     available AFTER the server connection completes (see the connected
+//     marker set at the entry point).
+// Env always wins over the store / roots-list, preserving existing setups.
+// ---------------------------------------------------------------------------
+let resolvedApiKeyPromise;
+/**
+ * Resolve the Bridge API key env-first, then from the home-dir credential store
+ * (`bapi:<repoName>`). Resolved once and cached. Returns an empty string on any
+ * failure (a generic auth-failure path) and never logs secret material.
+ */
+async function getResolvedApiKey() {
+    if (!resolvedApiKeyPromise) {
+        resolvedApiKeyPromise = (async () => {
+            try {
+                const result = await resolveBapiCredentials(REPO_NAME, {
+                    env: process.env,
+                    homedir: os.homedir,
+                    platform: process.platform,
+                    readFile: (p) => readFile(p, "utf-8"),
+                    stat: (p) => stat(p),
+                });
+                return result.ok ? result.credentials.apiKey : "";
+            }
+            catch {
+                return "";
+            }
+        })();
+    }
+    return resolvedApiKeyPromise;
+}
+/** GET auth headers, with the API key resolved once via {@link getResolvedApiKey}. */
+async function getGetHeaders() {
+    return {
+        "X-API-Key": await getResolvedApiKey(),
+        "X-Bridge-MCP-Version": VERSION,
+    };
+}
+/** POST auth headers (API key + JSON content type). */
+async function getPostHeaders() {
+    return {
+        "X-API-Key": await getResolvedApiKey(),
+        "Content-Type": "application/json",
+        "X-Bridge-MCP-Version": VERSION,
+    };
+}
+/** Set true immediately after the server connection (transport) completes. */
+let serverConnected = false;
+/**
+ * Query MCP `roots/list` through the connected server and return the first
+ * usable `file://` root path, or null. Only attempted after the server has
+ * connected; all failures are caught and yield null (the caller falls through).
+ */
+async function resolveProjectRootFromRootsList() {
+    if (!serverConnected)
+        return null;
+    try {
+        const result = await server.server.listRoots();
+        const roots = Array.isArray(result?.roots) ? result.roots : [];
+        for (const root of roots) {
+            const uri = root?.uri;
+            if (typeof uri === "string" && uri.startsWith("file://")) {
+                try {
+                    return fileURLToPath(uri);
+                }
+                catch {
+                    /* not a usable file URI — keep scanning */
+                }
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+let projectRootPromise;
+/**
+ * Resolve the project root once, in the exact order:
+ *   1. `BAPI_PROJECT_ROOT` env (always wins),
+ *   2. connected MCP `roots/list`,
+ *   3. `CLAUDE_PROJECT_DIR` env,
+ *   4. `process.cwd()`.
+ *
+ * INVARIANT: the FIRST call must happen inside a tool handler (i.e. AFTER the
+ * server connects), so the `roots/list` branch is reachable. This holds today —
+ * custom-pipeline loading is deferred and `checkCiConfigAndDisablePoll()` only
+ * resolves headers, not paths. If any future module-load code path calls this
+ * (or `getDocsDir()` / `getPipelinesDir()`) before connect, it would permanently
+ * cache a `cwd` / `CLAUDE_PROJECT_DIR` fallback even when a `file://` root exists.
+ */
+async function getProjectRoot() {
+    if (!projectRootPromise) {
+        projectRootPromise = (async () => {
+            const explicit = (process.env.BAPI_PROJECT_ROOT ?? "").trim();
+            if (explicit.length > 0)
+                return explicit;
+            const fromRoots = await resolveProjectRootFromRootsList();
+            if (fromRoots && fromRoots.length > 0)
+                return fromRoots;
+            const claudeDir = (process.env.CLAUDE_PROJECT_DIR ?? "").trim();
+            if (claudeDir.length > 0)
+                return claudeDir;
+            return process.cwd();
+        })();
+    }
+    return projectRootPromise;
+}
+let docsDirPromise;
+/** Resolve `BAPI_DOCS_DIR` (default `docs/tmp`) against the project root, once. */
+async function getDocsDir() {
+    if (!docsDirPromise) {
+        docsDirPromise = (async () => path.resolve(await getProjectRoot(), process.env.BAPI_DOCS_DIR ?? "docs/tmp"))();
+    }
+    return docsDirPromise;
+}
+let pipelinesDirPromise;
+/** Resolve `BAPI_PIPELINES_DIR` (default `.bridge/pipelines`) against the root, once. */
+async function getPipelinesDir() {
+    if (!pipelinesDirPromise) {
+        pipelinesDirPromise = (async () => path.resolve(await getProjectRoot(), process.env.BAPI_PIPELINES_DIR ?? ".bridge/pipelines"))();
+    }
+    return pipelinesDirPromise;
+}
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -64,18 +194,32 @@ function buildGetUrl(path, params) {
     }
     return url.toString();
 }
-function getDocsPath(subdir) {
-    return path.join(BAPI_DOCS_DIR, subdir);
+async function getDocsPath(subdir) {
+    return path.join(await getDocsDir(), subdir);
 }
-function slugify(text, maxLength = 60) {
-    return text
-        .toLowerCase()
-        .replace(/[^a-z0-9\s-]/g, "")
-        .trim()
-        .replace(/\s+/g, "-")
-        .replace(/-+/g, "-")
-        .slice(0, maxLength)
-        .replace(/-$/, "");
+/**
+ * Merge custom user pipelines (from the resolved pipelines dir) into PIPELINES /
+ * INSTRUCTIONS / userPipelineKeys exactly once. Deferred (not run at module load)
+ * so it can await the project-root resolution that depends on `roots/list`.
+ */
+let customPipelinesPromise;
+async function ensureCustomPipelinesLoaded() {
+    if (!customPipelinesPromise) {
+        customPipelinesPromise = (async () => {
+            const pipelinesDir = await getPipelinesDir();
+            const instructionsDir = path.join(path.dirname(pipelinesDir), "instructions");
+            const customResult = await loadCustomPipelines(pipelinesDir, instructionsDir, BUNDLED_INSTRUCTIONS);
+            for (const [key, pipeline] of Object.entries(customResult.pipelines)) {
+                if (key in BUNDLED_PIPELINES) {
+                    console.error(`Warning: user pipeline "${key}" overrides bundled pipeline.`);
+                }
+                PIPELINES[key] = pipeline;
+            }
+            Object.assign(INSTRUCTIONS, customResult.instructions);
+            userPipelineKeys = customResult.userPipelineKeys;
+        })();
+    }
+    return customPipelinesPromise;
 }
 const ERROR_CODES = {
     400: "BAD_REQUEST",
@@ -104,6 +248,29 @@ async function handleResponse(resp) {
     let message = rawText;
     try {
         const parsed = JSON.parse(rawText);
+        if (parsed.detail !== null &&
+            typeof parsed.detail === "object" &&
+            !Array.isArray(parsed.detail)) {
+            // Structured FastAPI HTTPException(detail={...}): preserve fields like
+            // error_kind and remediation at the top level so agents can read them
+            // natively instead of an opaque stringified blob.
+            const detail = parsed.detail;
+            if (typeof detail.message === "string") {
+                message = detail.message;
+            }
+            else {
+                message = JSON.stringify(detail);
+            }
+            // Spread detail FIRST so the relay's own error code / HTTP status /
+            // message always win — a future detail object that happens to carry an
+            // `error`/`status`/`message` key cannot clobber the relay envelope.
+            return JSON.stringify({
+                ...detail,
+                error: errorCode,
+                status: resp.status,
+                message,
+            });
+        }
         if (parsed.detail) {
             message = typeof parsed.detail === "string" ? parsed.detail : JSON.stringify(parsed.detail);
         }
@@ -133,7 +300,7 @@ async function createTicketRequest(params) {
         payload.parent_key = params.parent_key;
     const resp = await fetch(buildUrl("/create-ticket"), {
         method: "POST",
-        headers: POST_HEADERS,
+        headers: await getPostHeaders(),
         body: JSON.stringify(payload),
     });
     return handleResponse(resp);
@@ -149,6 +316,100 @@ async function saveLocally(dir, filename, content) {
         return `\n\n---\nNote: Failed to save file to ${filePath}: ${writeErr}`;
     }
 }
+// ---------------------------------------------------------------------------
+// Heavy-read truncate-and-save helpers (BAPI-342)
+// ---------------------------------------------------------------------------
+//
+// Five heavy read tools (get_project_standards, get_tickets, get_ticket,
+// get_comments, list_attachments) can return very large payloads. To avoid flooding the
+// agent's context, when a successful payload exceeds MAX_INLINE_TEXT_LENGTH the
+// FULL payload is saved to disk first and only then is a truncated,
+// markdown-fenced inline preview returned. Nothing is lost: if the save fails
+// (or the target escapes the docs directory) we fall back to returning the
+// complete untruncated payload with a warning rather than dropping data.
+// Shared with download_attachment, which uses MAX_INLINE_TEXT_LENGTH directly.
+const MAX_INLINE_TEXT_LENGTH = 50_000;
+// Filesystem-safe ISO timestamp (no ":" or "." which are awkward in filenames).
+function safeTimestampForFilename() {
+    return new Date().toISOString().replace(/[:.]/g, "-");
+}
+// Sanitize an untrusted ticket number into a single safe filename segment.
+// Preserves readable keys like "BAPI-123" while stripping path separators and
+// other unsafe characters; falls back to "ticket" when nothing usable remains.
+function safeTicketFileSegment(ticketNumber) {
+    const base = path.basename(ticketNumber.trim());
+    const cleaned = base
+        .replace(/[^A-Za-z0-9_-]/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return cleaned || "ticket";
+}
+// Mirror the download_attachment containment check: a resolved save target must
+// live strictly inside the resolved directory. Prevents traversal escapes from
+// a crafted filename even though saveLocally does a bare path.join.
+function isContainedSaveTarget(dir, filename) {
+    const resolvedDir = path.resolve(dir);
+    const target = path.resolve(resolvedDir, filename);
+    return target.startsWith(resolvedDir + path.sep);
+}
+// saveLocally returns either a "Saved to <path>" note or a "Failed to save"
+// note (it never throws). A successful save is identified by the "Saved to "
+// marker.
+function saveLocallySucceeded(note) {
+    return note.includes("Saved to ");
+}
+// Save-before-truncate for heavy read payloads. Returns `text` unchanged when
+// it is within the inline limit. Otherwise it saves the full payload first and
+// only truncates after a confirmed, contained save; on any containment or save
+// failure it returns the FULL untruncated text plus a warning so nothing is
+// lost. Returns JSON inside a markdown code fence so a truncated mid-string
+// slice is never mistaken for parseable JSON.
+async function truncateAndSaveIfNeeded(text, dir, filename) {
+    if (text.length <= MAX_INLINE_TEXT_LENGTH) {
+        return text;
+    }
+    if (!isContainedSaveTarget(dir, filename)) {
+        return (text +
+            "\n\n---\nWarning: response was NOT truncated because the save target " +
+            `was rejected as outside the docs directory (dir=${dir}, filename=${filename}).`);
+    }
+    const note = await saveLocally(dir, filename, text);
+    if (!saveLocallySucceeded(note)) {
+        return (text +
+            note +
+            "\n\nWarning: response was NOT truncated because the full payload could not be saved.");
+    }
+    const truncated = text.slice(0, MAX_INLINE_TEXT_LENGTH);
+    return ("[Response truncated. Full response saved locally.]\n\n" +
+        "```json\n" +
+        truncated +
+        "\n```" +
+        note);
+}
+// Build a stable, readable, collision-resistant filename for an oversized
+// get_tickets search payload. Includes the active filters and pagination so
+// distinct search pages do not collide, plus a timestamp; falls back to "all"
+// when no filter produces a slug.
+function buildTicketsSearchFilename(params) {
+    const parts = [];
+    if (params.query)
+        parts.push(params.query);
+    if (params.status)
+        parts.push(params.status);
+    const labels = Array.isArray(params.labels)
+        ? params.labels.join("-")
+        : params.labels;
+    if (labels)
+        parts.push(labels);
+    if (params.updated_since)
+        parts.push(`since-${params.updated_since}`);
+    if (params.limit !== undefined)
+        parts.push(`limit-${params.limit}`);
+    if (params.offset !== undefined)
+        parts.push(`offset-${params.offset}`);
+    const slug = slugify(parts.join("-")) || "all";
+    return `search-${slug}-${safeTimestampForFilename()}.json`;
+}
 async function resolveTextOrFile(textValue, filePath, textLabel) {
     if (!filePath && !textValue) {
         return {
@@ -209,7 +470,7 @@ async function pollForResult(getUrl, timeoutMs, label) {
             };
         }
         console.error(`${label} in progress... (elapsed: ${elapsed}s)`);
-        const resp = await fetch(getUrl, { headers: GET_HEADERS });
+        const resp = await fetch(getUrl, { headers: await getGetHeaders() });
         if (resp.status === 404 || resp.status === 202) {
             await resp.text();
         }
@@ -223,36 +484,333 @@ async function pollForResult(getUrl, timeoutMs, label) {
         }
     }
 }
+const TICKET_ARTIFACTS = {
+    plan: {
+        kind: "single",
+        generateEndpoint: (n) => `/ticket/${encodeURIComponent(n)}/generate-plan`,
+        getEndpoint: (n) => `/ticket/${encodeURIComponent(n)}/plan`,
+        saveSubdir: "plans",
+        filename: (n) => `${n}-plan.md`,
+        requestErrorPrefix: "Failed to request plan generation: ",
+        confirmationText: (n) => `Plan generation requested for ${n}. ` +
+            `Processing typically takes 1-5 minutes. ` +
+            `Use get_plan with ticket_number "${n}" to retrieve the plan once processing completes.`,
+        pollLabel: (n) => `Plan generation for ${n}`,
+    },
+    architecture: {
+        kind: "single",
+        generateEndpoint: (n) => `/ticket/${encodeURIComponent(n)}/generate-architecture`,
+        getEndpoint: (n) => `/ticket/${encodeURIComponent(n)}/architecture-plan`,
+        saveSubdir: "architecture",
+        filename: (n) => `${n}-architecture-plan.md`,
+        requestErrorPrefix: "Failed to request architecture generation: ",
+        confirmationText: (n) => `Architecture generation requested for ${n}. ` +
+            `Processing typically takes 2-4 minutes. ` +
+            `Use get_architecture with ticket_number "${n}" to retrieve the architecture plan once processing completes.`,
+        pollLabel: (n) => `Architecture generation for ${n}`,
+    },
+    fsd: {
+        kind: "single",
+        generateEndpoint: (n) => `/ticket/${encodeURIComponent(n)}/generate-fsd`,
+        getEndpoint: (n) => `/ticket/${encodeURIComponent(n)}/fsd`,
+        saveSubdir: "fsd",
+        filename: (n) => `${n}-fsd-plan.md`,
+        requestErrorPrefix: "Failed to request FSD generation: ",
+        confirmationText: (n) => `FSD generation requested for ${n}. ` +
+            `Processing typically takes 2-4 minutes. ` +
+            `Use get_design_doc with ticket_number "${n}" and doc_type "fsd" to retrieve the functional specification document once processing completes.`,
+        pollLabel: (n) => `FSD generation for ${n}`,
+    },
+    clarifying_questions: {
+        kind: "single",
+        generateEndpoint: (n) => `/ticket/${encodeURIComponent(n)}/generate-clarifying-questions`,
+        getEndpoint: (n) => `/ticket/${encodeURIComponent(n)}/clarifying-questions`,
+        saveSubdir: "clarifying-questions",
+        filename: (n) => `${n}-clarifying-questions.md`,
+        requestErrorPrefix: "Failed to request clarifying questions: ",
+        confirmationText: (n) => `Clarifying questions requested for ${n}. ` +
+            `Processing typically takes 1-5 minutes. ` +
+            `Use get_clarifying_questions with ticket_number "${n}" to retrieve the results once processing completes.`,
+        pollLabel: (n) => `Clarifying questions for ${n}`,
+    },
+    ticket_critique: {
+        kind: "single",
+        generateEndpoint: (n) => `/ticket/${encodeURIComponent(n)}/generate-ticket-critique`,
+        getEndpoint: (n) => `/ticket/${encodeURIComponent(n)}/ticket-critique`,
+        saveSubdir: "ticket-critiques",
+        filename: (n) => `${n}-ticket-quality-critique.md`,
+        requestErrorPrefix: "Failed to request ticket critique: ",
+        confirmationText: (n) => `Ticket critique requested for ${n}. ` +
+            `Processing typically takes 1-5 minutes. ` +
+            `Use get_ticket_critique with ticket_number "${n}" to retrieve the results once processing completes.`,
+        pollLabel: (n) => `Ticket critique for ${n}`,
+    },
+    reimplement_context: {
+        kind: "single",
+        generateEndpoint: (n) => `/ticket/${encodeURIComponent(n)}/request-reimplement-context`,
+        getEndpoint: (n) => `/ticket/${encodeURIComponent(n)}/reimplement-context`,
+        saveSubdir: "reimplementations",
+        filename: (n) => `${n}-context.md`,
+        requestErrorPrefix: "Failed to request reimplement context: ",
+        confirmationText: (n) => `Reimplement context processing requested for ${n}. ` +
+            `Processing typically takes 1-2 minutes. ` +
+            `Use get_reimplement_context with ticket_number "${n}" to retrieve the results once processing completes.`,
+        pollLabel: (n) => `Reimplement context for ${n}`,
+    },
+    ticket_review: {
+        kind: "review",
+        generateEndpoint: (n) => `/ticket/${encodeURIComponent(n)}/generate-ticket-review`,
+        getEndpoint: (n) => `/ticket/${encodeURIComponent(n)}/ticket-review`,
+        requestErrorPrefix: "Failed to request ticket review: ",
+        confirmationText: (n) => `Combined ticket review requested for ${n}. ` +
+            `Processing typically takes 2-6 minutes. ` +
+            `Use get_clarifying_questions and get_ticket_critique with ticket_number "${n}" to retrieve the two documents once processing completes.`,
+        pollLabel: (n) => `Ticket review for ${n}`,
+        clarifySaveSubdir: "clarifying-questions",
+        critiqueSaveSubdir: "ticket-critiques",
+    },
+};
+// Build the shared POST body for an artifact generate request. Preserves the
+// per-tool provider routing exactly: a trimmed `second_opinion` becomes
+// `provider_override` and takes precedence; otherwise a trimmed `provider`
+// becomes `provider`. Blank values are omitted after trimming.
+function buildTicketArtifactRequestBody(args) {
+    const body = { repo_name: REPO_NAME };
+    const trimmedSecondOpinion = args.second_opinion?.trim();
+    if (trimmedSecondOpinion) {
+        body.provider_override = trimmedSecondOpinion;
+    }
+    const trimmedProvider = args.provider?.trim();
+    if (trimmedProvider && !trimmedSecondOpinion) {
+        body.provider = trimmedProvider;
+    }
+    return body;
+}
+// Resolve the docs save directory for an artifact subdir. Implemented as an
+// explicit switch with literal getDocsPath(...) calls so the existing static
+// source-text invariants (literal getDocsPath subdir strings) still hold.
+async function getTicketArtifactDocsPath(subdir) {
+    switch (subdir) {
+        case "plans":
+            return getDocsPath("plans");
+        case "architecture":
+            return getDocsPath("architecture");
+        case "fsd":
+            return getDocsPath("fsd");
+        case "clarifying-questions":
+            return getDocsPath("clarifying-questions");
+        case "ticket-critiques":
+            return getDocsPath("ticket-critiques");
+        case "reimplementations":
+            return getDocsPath("reimplementations");
+    }
+}
+// Map the public unified design-doc `doc_type` to the internal artifact key.
+// `tdd` reuses the existing "architecture" artifact (the TDD/architecture
+// document) WITHOUT renaming it, preserving the back-compatible
+// request_architecture / get_architecture tools. `fsd` routes to the new "fsd"
+// artifact.
+function resolveDesignDocArtifactType(docType) {
+    return docType === "fsd" ? "fsd" : "architecture";
+}
+// Shared request flow for the five single-artifact request_* tools: POST the
+// generate endpoint, return the per-tool error prefix on a non-OK POST, and on
+// wait_for_result poll the get endpoint (900_000 ms) and optionally save.
+async function requestTicketArtifact(type, args) {
+    const config = TICKET_ARTIFACTS[type];
+    const resp = await fetch(buildUrl(config.generateEndpoint(args.ticket_number)), {
+        method: "POST",
+        headers: await getPostHeaders(),
+        body: JSON.stringify(buildTicketArtifactRequestBody(args)),
+    });
+    if (!resp.ok) {
+        const errorText = await handleResponse(resp);
+        return {
+            content: [{ type: "text", text: `${config.requestErrorPrefix}${errorText}` }],
+        };
+    }
+    if (args.wait_for_result) {
+        const getUrl = buildGetUrl(config.getEndpoint(args.ticket_number), { repo_name: REPO_NAME });
+        const result = await pollForResult(getUrl, 900_000, config.pollLabel(args.ticket_number));
+        if (!result.ok) {
+            return { content: [{ type: "text", text: result.text }] };
+        }
+        let text = result.text;
+        if (args.save_locally) {
+            const note = await saveLocally(await getTicketArtifactDocsPath(config.saveSubdir), config.filename(args.ticket_number), text);
+            text += note;
+        }
+        return { content: [{ type: "text", text }] };
+    }
+    return {
+        content: [{ type: "text", text: config.confirmationText(args.ticket_number) }],
+    };
+}
+// Shared GET/save flow for the five single-artifact get_* tools. Normal gets
+// save only on `resp.ok && save_locally`. reimplement_context is asymmetric: it
+// short-circuits a 404 with a custom NOT_FOUND envelope (without leaking the
+// backend body) and otherwise saves on ANY non-404 response when save_locally.
+async function getTicketArtifact(type, args) {
+    const config = TICKET_ARTIFACTS[type];
+    const resp = await fetch(buildGetUrl(config.getEndpoint(args.ticket_number), { repo_name: REPO_NAME }), { headers: await getGetHeaders() });
+    if (type === "reimplement_context") {
+        if (resp.status === 404) {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "NOT_FOUND",
+                            message: `Reimplement context for ${args.ticket_number} is not yet available. ` +
+                                `Processing may still be in progress. Try again in a moment, ` +
+                                `or call request_reimplement_context to trigger processing.`,
+                        }),
+                    }],
+            };
+        }
+        const text = await handleResponse(resp);
+        if (args.save_locally) {
+            const note = await saveLocally(await getTicketArtifactDocsPath(config.saveSubdir), config.filename(args.ticket_number), text);
+            return { content: [{ type: "text", text: text + note }] };
+        }
+        return { content: [{ type: "text", text }] };
+    }
+    const ok = resp.ok;
+    let text = await handleResponse(resp);
+    if (ok && args.save_locally) {
+        const note = await saveLocally(await getTicketArtifactDocsPath(config.saveSubdir), config.filename(args.ticket_number), text);
+        text += note;
+    }
+    return { content: [{ type: "text", text }] };
+}
+// Bespoke combined ticket-review flow. The backend GET returns a JSON envelope
+// ({ clarify, critique }) rather than a single artifact, so this is kept
+// separate from requestTicketArtifact: it fans the envelope out into two
+// markdown parts joined by "\n\n---\n\n" and saves each sub-doc (when present
+// with a doc_type) into its own subdir using a doc_type-derived filename.
+async function requestTicketReview(args) {
+    const config = TICKET_ARTIFACTS.ticket_review;
+    const resp = await fetch(buildUrl(config.generateEndpoint(args.ticket_number)), {
+        method: "POST",
+        headers: await getPostHeaders(),
+        body: JSON.stringify(buildTicketArtifactRequestBody(args)),
+    });
+    if (!resp.ok) {
+        const errorText = await handleResponse(resp);
+        return {
+            content: [{ type: "text", text: `${config.requestErrorPrefix}${errorText}` }],
+        };
+    }
+    if (!args.wait_for_result) {
+        return {
+            content: [{ type: "text", text: config.confirmationText(args.ticket_number) }],
+        };
+    }
+    const getUrl = buildGetUrl(config.getEndpoint(args.ticket_number), { repo_name: REPO_NAME });
+    const result = await pollForResult(getUrl, 900_000, config.pollLabel(args.ticket_number));
+    if (!result.ok) {
+        return { content: [{ type: "text", text: result.text }] };
+    }
+    // The combined GET endpoint returns JSON. Parse and fan out into markdown.
+    let envelope;
+    try {
+        envelope = JSON.parse(result.text);
+    }
+    catch (parseErr) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Failed to parse ticket review response: ${parseErr}\nRaw body: ${result.text}`,
+                }],
+        };
+    }
+    const clarify = envelope.clarify ?? {};
+    const critique = envelope.critique ?? {};
+    const parts = [];
+    let notes = "";
+    if (clarify.status === "success" && typeof clarify.content === "string" && clarify.content) {
+        parts.push(clarify.content);
+        if (args.save_locally && clarify.doc_type) {
+            const filename = `${args.ticket_number}-${clarify.doc_type}`;
+            const note = await saveLocally(await getTicketArtifactDocsPath(config.clarifySaveSubdir), filename, clarify.content);
+            notes += note;
+        }
+    }
+    else {
+        parts.push(`> **Note:** Clarifying questions sub-flow ${clarify.status ?? "unavailable"} (no content returned).`);
+    }
+    if (critique.status === "success" && typeof critique.content === "string" && critique.content) {
+        parts.push(critique.content);
+        if (args.save_locally && critique.doc_type) {
+            const filename = `${args.ticket_number}-${critique.doc_type}`;
+            const note = await saveLocally(await getTicketArtifactDocsPath(config.critiqueSaveSubdir), filename, critique.content);
+            notes += note;
+        }
+    }
+    else {
+        parts.push(`> **Note:** Ticket critique sub-flow ${critique.status ?? "unavailable"} (no content returned).`);
+    }
+    const text = parts.join("\n\n---\n\n") + notes;
+    return { content: [{ type: "text", text }] };
+}
 // ---------------------------------------------------------------------------
 // CLI: --init scaffolds slash commands and MCP configs into the current project
 // ---------------------------------------------------------------------------
 function buildBridgeApiEntry(cwd) {
+    // Secret-free by design: BAPI_API_KEY is NEVER scaffolded into generated MCP
+    // config. The server self-resolves the key from the environment or the
+    // home-dir credential store (~/.config/bridge/credentials.json) at runtime.
     return {
         command: "npx",
         args: ["-y", "@bridge_gpt/mcp-server"],
         env: {
             BAPI_BASE_URL: "https://bridgegpt-api.com",
             BAPI_REPO_NAME: "YOUR_REPO_NAME",
-            BAPI_API_KEY: "YOUR_API_KEY",
             BAPI_DOCS_DIR: "docs/tmp",
             BAPI_PROJECT_ROOT: cwd,
         },
     };
 }
+/**
+ * Choose the `repo_name` written into a scaffolded `.bridge/config`. Uses the
+ * cwd basename when it passes manifest repo-name validation; otherwise falls
+ * back to the `YOUR_REPO_NAME` placeholder for the user to edit.
+ */
+export function chooseScaffoldRepoName(cwd) {
+    const validated = validateRepoName(path.basename(cwd));
+    return validated.ok ? validated.value : "YOUR_REPO_NAME";
+}
+/** Build the secret-free `.bridge/config` TOML scaffolded by `--init`. */
+export function buildBridgeConfigManifest(repoName) {
+    return [
+        "# Bridge API repository MCP manifest (committed, secret-free, machine-agnostic).",
+        "#",
+        "# Inherited by every git worktree; start-tickets worktree provisioning reads it",
+        "# to decide which Bridge API MCP registrations to write. Do not add credentials,",
+        "# connection URLs, or machine-specific paths here — those are resolved at runtime.",
+        "",
+        `repo_name = "${repoName}"`,
+        "",
+        "[[mcp]]",
+        'target = "bapi"',
+        "",
+        "# Optional: declare additional (Tier-2) MCP targets here. Each non-bapi target",
+        "# names the real command/args to launch and the credential-store bundle that",
+        "# supplies its secrets — never the secrets themselves. Uncomment and adapt:",
+        "#",
+        "# [[mcp]]",
+        '# target = "sfcc"',
+        '# command = "npx"',
+        '# args = ["-y", "@salesforce/b2c-dx-mcp"]',
+        '# secret_bundle = "sfcc:YOUR_SANDBOX_ID"',
+        "",
+    ].join("\n");
+}
 async function ensureGitignored(cwd, filePath) {
-    const gitignorePath = path.join(cwd, ".gitignore");
-    const entry = filePath.startsWith("/") ? path.relative(cwd, filePath) : filePath;
-    let content = "";
-    try {
-        content = await readFile(gitignorePath, "utf-8");
-    }
-    catch { /* .gitignore doesn't exist yet */ }
-    // Check if already present (exact line match)
-    const lines = content.split("\n");
-    if (lines.some((line) => line.trim() === entry))
-        return;
-    const separator = content.length > 0 && !content.endsWith("\n") ? "\n" : "";
-    await writeFile(gitignorePath, content + separator + entry + "\n", "utf-8");
+    await ensureGitignoredShared(cwd, filePath, {
+        readFile: (p) => readFile(p, "utf-8"),
+        writeFile: (p, data) => writeFile(p, data, "utf-8"),
+        mkdir: (p, options) => mkdir(p, options),
+    });
 }
 /**
  * Core initialization logic shared by --init and --upgrade.
@@ -609,10 +1167,34 @@ body explicitly says to serialize structured output.
         console.log(`  ${path.relative(cwd, examplePath)} (written)`);
     }
     console.log(`  ${path.relative(cwd, instrDir)}/ (ensured)`);
+    // ---- Phase 6b: Scaffold the committed secret-free `.bridge/config` ----
+    // This manifest is committed and inherited by every worktree; it is the
+    // input to start-tickets worktree MCP provisioning. It is intentionally
+    // NOT gitignored (unlike the .mcp.json configs above). Credentials are
+    // resolved at runtime, never written here.
+    const bridgeConfigPath = path.join(cwd, ".bridge", "config");
+    let bridgeConfigExists = false;
+    try {
+        await stat(bridgeConfigPath);
+        bridgeConfigExists = true;
+    }
+    catch { }
+    if (bridgeConfigExists) {
+        console.log(`\n.bridge/config: skipped — already exists`);
+    }
+    else {
+        await mkdir(path.dirname(bridgeConfigPath), { recursive: true });
+        await writeFile(bridgeConfigPath, buildBridgeConfigManifest(chooseScaffoldRepoName(cwd)), "utf-8");
+        console.log(`\n.bridge/config: written`);
+    }
+    console.log("  Credentials are resolved at runtime from BAPI_API_KEY or " +
+        "~/.config/bridge/credentials.json (no secrets are written to .bridge/config).");
     // ---- Phase 7: Final summary ----
     if (anyCreatedOrAdded) {
-        console.log("\nUpdate BAPI_API_KEY and BAPI_REPO_NAME in your config files — " +
-            "get these values from the Bridge API setup UI at https://bridgegpt-api.com");
+        console.log("\nSet BAPI_REPO_NAME in your config files. Do NOT put BAPI_API_KEY in the " +
+            "generated MCP config — supply it via the BAPI_API_KEY environment variable, " +
+            "or store it under \"bapi:<repo_name>\" in ~/.config/bridge/credentials.json. " +
+            "Get your values from the Bridge API setup UI at https://bridgegpt-api.com");
     }
 }
 // ---------------------------------------------------------------------------
@@ -703,6 +1285,14 @@ async function dispatchCliSubcommand(argv) {
     if (argv[0] === "start-tickets") {
         return runStartTicketsCli(argv.slice(1));
     }
+    // The internal `mcp-invoke` worktree shim (BAPI-337) is a positional
+    // subcommand routed before the flag guards and well before MCP server
+    // construction: it resolves identity/credentials from `--project-root` and
+    // then spawns the real server itself, so it must never fall through to the
+    // normal no-subcommand startup path.
+    if (argv[0] === "mcp-invoke") {
+        return runMcpInvokeCli(argv.slice(1));
+    }
     // The read-only `doctor` subcommand is routed beside start-tickets, before the
     // flag guards and well before MCP server construction (it never starts the server).
     if (argv[0] === "doctor") {
@@ -714,6 +1304,12 @@ async function dispatchCliSubcommand(argv) {
     if (argv[0] === "schedule-run") {
         return runScheduleRunCli(argv.slice(1));
     }
+    // The read-only `agent-capabilities` toolkit is likewise a positional subcommand,
+    // routed before the flag guards and never starts the MCP server. It only spawns
+    // disposable agent probes in temp dirs.
+    if (argv[0] === "agent-capabilities") {
+        return runAgentCapabilitiesCli(argv.slice(1));
+    }
     // --init takes precedence over --upgrade; both are position-independent flags.
     if (argv.includes("--init")) {
         return runInitCli(cwd);
@@ -799,25 +1395,59 @@ const registerTool = ((name, config, handler) => {
     }
     return toolHandle;
 });
-// ---------------------------------------------------------------------------
-// Tools
-// ---------------------------------------------------------------------------
 registerTool("ping", {
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
     description: "Test connectivity to Bridge API. Validates that the API key is accepted and the configured repository is accessible. " +
         "Returns JSON with {status: 'ok', repo_name: '<configured repo>'}. " +
+        "The response also reports MCP version metadata: mcp_version (your installed MCP server version), " +
+        "latest_mcp_version (latest published), upgrade_available, upgrade_advice (a short, optional note when a newer version is available), " +
+        "and release_state_stale. These are informational — an available upgrade is not an error. " +
         "Use this as a quick health check before other operations, or to verify your Bridge API configuration is working. " +
         "A 403 response means the API key is invalid or the repo is not authorized. " +
         "If the server is unreachable, check that BAPI_BASE_URL points to a running Bridge API instance.",
     inputSchema: {},
 }, async () => {
     const url = buildGetUrl("/ping", { repo_name: REPO_NAME });
-    const resp = await fetch(url, { headers: GET_HEADERS });
-    const text = await handleResponse(resp);
-    return { content: [{ type: "text", text }] };
+    const resp = await fetch(url, { headers: await getGetHeaders() });
+    // Preserve existing behavior for non-OK responses (structured error relay).
+    if (!resp.ok) {
+        const text = await handleResponse(resp);
+        return { content: [{ type: "text", text }] };
+    }
+    // OK: keep the first content item independently JSON.parse()-able, and emit
+    // any upgrade advice as a SEPARATE text item so prose never pollutes the JSON.
+    const raw = await resp.text();
+    try {
+        const body = JSON.parse(raw);
+        const content = [
+            { type: "text", text: JSON.stringify(body, null, 2) },
+        ];
+        if (typeof body.upgrade_advice === "string" && body.upgrade_advice.length > 0) {
+            content.push({ type: "text", text: body.upgrade_advice });
+        }
+        return { content };
+    }
+    catch {
+        // Unexpected non-JSON 200 — fall back to the raw text in one content item.
+        return { content: [{ type: "text", text: raw }] };
+    }
 });
 registerTool("second_opinion", {
-    description: "Consult a different LLM model family for a sanity check or technical pushback on a recommendation, plan, or analysis you have already produced. " +
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    description: "Get an IMMEDIATE, ad hoc independent critique or pushback on a plan, recommendation, or analysis you ALREADY HAVE in hand, from a different LLM model family. " +
         "Use this when you want a second, independent opinion before acting on a non-trivial decision — for example, when committing to an implementation approach, a risky refactor, an architectural trade-off, or a recommendation you would otherwise present to a user with no further validation. " +
+        "This tool does NOT create or retrieve any Bridge artifact: it does not generate or fetch plans, ticket critiques, clarifying questions, architecture docs, deep research, brainstorms, or reimplementation context, and it stores nothing. It simply returns the other model's reply to your prompt right now. " +
+        "If instead you want a Bridge ARTIFACT (a plan, critique, clarifying questions, architecture doc, reimplementation context, etc.) generated by a different provider, do NOT use this tool — call the matching `request_*` tool and set that tool's own `second_opinion` or `provider` parameter to route its generation to another provider. " +
         "Pick a provider from a DIFFERENT model family than the one you are running on so the response is genuinely independent (e.g. if you are an OpenAI agent, ask 'anthropic' or 'gemini'). " +
         "Pick a model tier appropriate for the depth of pushback you want: CHEAP_MODEL for a quick sanity check, BASIC_MODEL for a focused review, PREMIUM_MODEL for serious architectural pushback. " +
         "The 'prompt' you supply should be a complete, self-contained brief: the full plan, recommendation, or question you want challenged, along with whatever context is needed to evaluate it. The server adds a system prompt that frames the responder as an independent senior engineer and injects lightweight project context. " +
@@ -839,7 +1469,7 @@ registerTool("second_opinion", {
 }, async ({ prompt, provider, model }) => {
     const resp = await fetch(buildApiUrl("/llm/second-opinion"), {
         method: "POST",
-        headers: POST_HEADERS,
+        headers: await getPostHeaders(),
         body: JSON.stringify({
             repo_name: REPO_NAME,
             prompt,
@@ -850,19 +1480,125 @@ registerTool("second_opinion", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
+registerTool("generate_image", {
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+    description: "Generate an image from a text prompt using a provider image model. " +
+        "This tool spends provider credits on every call — cost scales with quality (low/medium/high). " +
+        "Defaults to low quality to minimize provider spend; increase quality only when fidelity matters. " +
+        "Returns native MCP image content (type: 'image') so the caller receives the image directly. " +
+        "The image is always also saved to the local BAPI_DOCS_DIR/images/ directory. " +
+        "Google Imagen outputs (provider='gemini') include an invisible SynthID watermark applied server-side by Google.",
+    inputSchema: {
+        prompt: z
+            .string()
+            .min(1)
+            .max(8000)
+            .describe("Text prompt sent to the image provider."),
+        provider: z
+            .enum(["openai", "gemini"])
+            .optional()
+            .default("openai")
+            .describe("Image provider. Defaults to 'openai' (gpt-image-2)."),
+        quality: z
+            .enum(["low", "medium", "high"])
+            .optional()
+            .default("low")
+            .describe("Image quality. Defaults to 'low' for cost control."),
+        size: z
+            .enum(["1024x1024", "1024x1536", "1536x1024"])
+            .optional()
+            .default("1024x1024")
+            .describe("Image dimensions. Defaults to '1024x1024'."),
+    },
+}, async ({ prompt, provider, quality, size }) => {
+    const resp = await fetch(buildApiUrl("/llm/generate-image"), {
+        method: "POST",
+        headers: await getPostHeaders(),
+        body: JSON.stringify({
+            repo_name: REPO_NAME,
+            prompt,
+            provider,
+            quality,
+            size,
+        }),
+    });
+    if (!resp.ok) {
+        const text = await handleResponse(resp);
+        return { content: [{ type: "text", text }] };
+    }
+    const body = (await resp.json());
+    const imageBase64 = body.image_base64;
+    if (typeof imageBase64 !== "string" || imageBase64.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ error: "Image generation succeeded but response is missing image_base64", status: 500 }),
+                },
+            ],
+        };
+    }
+    const mimeType = typeof body.mime_type === "string" && body.mime_type.length > 0
+        ? body.mime_type
+        : "image/png";
+    const content = [
+        { type: "image", data: imageBase64, mimeType },
+    ];
+    // Always persist to BAPI_DOCS_DIR/images/. A write failure must not discard
+    // the already-paid-for generation, so warn and still return the inline image.
+    try {
+        const imagesDir = await getDocsPath("images");
+        const filename = `generated-image-${safeTimestampForFilename()}.png`;
+        const filePath = `${imagesDir}/${filename}`;
+        await mkdir(imagesDir, { recursive: true });
+        await writeFile(filePath, Buffer.from(imageBase64, "base64"));
+        content.push({ type: "text", text: `Saved to ${filePath}` });
+    }
+    catch (saveErr) {
+        content.push({
+            type: "text",
+            text: `Warning: image generated successfully but local save failed: ${saveErr instanceof Error ? saveErr.message : String(saveErr)}`,
+        });
+    }
+    return { content };
+});
 registerTool("get_project_standards", {
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
     description: "Retrieve project-specific coding standards, architecture guidelines, testing standards, code review standards, and project context (platform, version, project description) for the configured repository. " +
         "Returns structured markdown with sections for project context, architecture instructions, code review correctness standards, testing stack information, and build analysis. " +
         "Only sections with configured values are included. Returns 404 if no standards are configured. " +
-        "Consult these standards before writing or reviewing code to ensure compliance with project conventions.",
+        "Consult these standards before writing or reviewing code to ensure compliance with project conventions. " +
+        "Successful oversized output is automatically saved under the local docs directory and returned inline as a truncated preview.",
     inputSchema: {},
 }, async () => {
     const url = buildGetUrl("/project-standards", { repo_name: REPO_NAME });
-    const resp = await fetch(url, { headers: GET_HEADERS });
-    const text = await handleResponse(resp);
+    const resp = await fetch(url, { headers: await getGetHeaders() });
+    const ok = resp.ok;
+    let text = await handleResponse(resp);
+    if (ok) {
+        const safeRepo = safeTicketFileSegment(REPO_NAME || "repo");
+        const filename = `${safeRepo}-project-standards.md`;
+        text = await truncateAndSaveIfNeeded(text, await getDocsPath("project-standards"), filename);
+    }
     return { content: [{ type: "text", text }] };
 });
 registerTool("get_tickets", {
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
     description: "Search for and list Jira tickets from the configured project. " +
         "Filters by query text, status name, label, or date. Returns up to 'limit' tickets ordered by most recently updated. " +
         "All data is fetched live from Jira. Use get_ticket to retrieve full details for a specific ticket.",
@@ -913,11 +1649,29 @@ registerTool("get_tickets", {
     if (updated_since)
         params.updated_since = updated_since;
     const url = buildGetUrl("/tickets", params);
-    const resp = await fetch(url, { headers: GET_HEADERS });
-    const text = await handleResponse(resp);
+    const resp = await fetch(url, { headers: await getGetHeaders() });
+    const ok = resp.ok;
+    let text = await handleResponse(resp);
+    if (ok) {
+        const filename = buildTicketsSearchFilename({
+            query,
+            status,
+            labels,
+            updated_since,
+            limit,
+            offset,
+        });
+        text = await truncateAndSaveIfNeeded(text, await getDocsPath("tickets-search"), filename);
+    }
     return { content: [{ type: "text", text }] };
 });
 registerTool("get_ticket", {
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
     description: "Retrieve full details for a single Jira ticket by its key. " +
         "Returns summary, status, type, assignee, reporter, description, and timestamps. " +
         "All data is fetched live from Jira. Use get_tickets to search/list multiple tickets. " +
@@ -929,11 +1683,46 @@ registerTool("get_ticket", {
     },
 }, async ({ ticket_number }) => {
     const url = buildGetUrl(`/tickets/${encodeURIComponent(ticket_number)}`, { repo_name: REPO_NAME });
-    const resp = await fetch(url, { headers: GET_HEADERS });
+    const resp = await fetch(url, { headers: await getGetHeaders() });
+    const ok = resp.ok;
+    let text = await handleResponse(resp);
+    if (ok) {
+        const safeTicket = safeTicketFileSegment(ticket_number);
+        const filename = `${safeTicket}.json`;
+        text = await truncateAndSaveIfNeeded(text, await getDocsPath("tickets"), filename);
+    }
+    return { content: [{ type: "text", text }] };
+});
+registerTool("get_ticket_model_tier", {
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    description: "Resolve the coarse implementation-model TIER for a Jira ticket from its difficulty. " +
+        "Returns { difficulty: int|null, tier: \"cheap\"|\"basic\"|\"premium\"|null, source: \"cached\"|\"computed\"|\"fallback\" }. " +
+        "The backend computes difficulty on demand (and caches it) when missing, and never returns a model id — " +
+        "the tier->model mapping is owned by the start-tickets CLI. A null tier (source=\"fallback\") means the " +
+        "model could not be resolved and callers should use the agent's default model.",
+    inputSchema: {
+        ticket_number: z
+            .string()
+            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
+    },
+}, async ({ ticket_number }) => {
+    const url = buildGetUrl(`/tickets/${encodeURIComponent(ticket_number)}/model-tier`, { repo_name: REPO_NAME });
+    const resp = await fetch(url, { headers: await getGetHeaders() });
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
 registerTool("get_comments", {
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
     description: "Retrieve all comments on a Jira ticket, oldest-first. " +
         "Returns an array of {id, author, body, created, updated}. " +
         "Comment bodies are Markdown (converted from Jira wiki markup). " +
@@ -946,11 +1735,23 @@ registerTool("get_comments", {
     },
 }, async ({ ticket_number }) => {
     const url = buildGetUrl(`/tickets/${encodeURIComponent(ticket_number)}/comments`, { repo_name: REPO_NAME });
-    const resp = await fetch(url, { headers: GET_HEADERS });
-    const text = await handleResponse(resp);
+    const resp = await fetch(url, { headers: await getGetHeaders() });
+    const ok = resp.ok;
+    let text = await handleResponse(resp);
+    if (ok) {
+        const safeTicket = safeTicketFileSegment(ticket_number);
+        const filename = `${safeTicket}-comments.json`;
+        text = await truncateAndSaveIfNeeded(text, await getDocsPath("comments"), filename);
+    }
     return { content: [{ type: "text", text }] };
 });
 registerTool("create_ticket", {
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
     description: "Create a new Jira ticket in the configured project. Requires either description or file_path (or both — file_path takes precedence). " +
         "Returns JSON with {ticket_key: 'PROJ-123', url: 'https://...'}. " +
         "The ticket is created immediately in Jira — confirm details with the user before calling. " +
@@ -999,10 +1800,17 @@ registerTool("create_ticket", {
     return { content: [{ type: "text", text: text + resolved.note }] };
 });
 registerTool("get_plan", {
-    description: "Retrieve the AI-generated implementation plan for a Jira ticket. " +
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    description: "RETRIEVE an already-generated implementation plan for a Jira ticket. This tool only fetches an existing plan — it does NOT start or trigger plan generation. " +
+        "If no plan exists yet (or you need a fresh one), call `request_plan_generation` first; it starts the async generation and this `get_plan` tool retrieves the result. " +
         "Returns the full plan as markdown text — present it verbatim without summarizing. " +
         "The plan includes step-by-step implementation guidance with code file references. " +
-        "Returns 404 if no plan has been generated yet (the ticket may not have been processed by Bridge API). " +
+        "Returns a 404 / not-found response when no plan is ready yet (the ticket may not have been processed by Bridge API) — that means generation has not run, not that this tool failed. " +
         "Tip: call get_clarifying_questions for the same ticket to get the full context for implementation.",
     inputSchema: {
         ticket_number: z
@@ -1015,23 +1823,21 @@ registerTool("get_plan", {
             .describe("Whether to save the plan to a local file in the BAPI_DOCS_DIR/plans/ directory. " +
             "Defaults to true. Set to false to skip saving."),
     },
-}, async ({ ticket_number, save_locally }) => {
-    const url = buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/plan`, { repo_name: REPO_NAME });
-    const resp = await fetch(url, { headers: GET_HEADERS });
-    const ok = resp.ok;
-    let text = await handleResponse(resp);
-    if (ok && save_locally) {
-        const note = await saveLocally(getDocsPath("plans"), `${ticket_number}-plan.md`, text);
-        text += note;
-    }
-    return { content: [{ type: "text", text }] };
+}, async (args) => {
+    return getTicketArtifact("plan", args);
 });
 registerTool("get_architecture", {
-    description: "Retrieve the AI-generated architecture plan for a Jira ticket. " +
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    description: "RETRIEVE an already-generated architecture plan for a Jira ticket. This tool only fetches an existing architecture plan — it does NOT start or trigger generation. " +
+        "If no architecture plan exists yet (or you need a fresh one), call `request_architecture` first; it starts the async generation and this `get_architecture` tool retrieves the result. " +
         "Returns the full architecture plan as markdown text — present it verbatim without summarizing. " +
         "The plan includes high-level architectural decisions, component design, and integration guidance. " +
-        "Returns 404 if no architecture plan has been generated yet. " +
-        "Tip: use request_architecture to trigger architecture plan generation first.",
+        "Returns a 404 / not-found response when no architecture plan is ready yet — that means generation has not run, not that this tool failed.",
     inputSchema: {
         ticket_number: z
             .string()
@@ -1043,21 +1849,20 @@ registerTool("get_architecture", {
             .describe("Whether to save the architecture plan to a local file in the BAPI_DOCS_DIR/architecture/ directory. " +
             "Defaults to true. Set to false to skip saving."),
     },
-}, async ({ ticket_number, save_locally }) => {
-    const url = buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/architecture-plan`, { repo_name: REPO_NAME });
-    const resp = await fetch(url, { headers: GET_HEADERS });
-    const ok = resp.ok;
-    let text = await handleResponse(resp);
-    if (ok && save_locally) {
-        const note = await saveLocally(getDocsPath("architecture"), `${ticket_number}-architecture-plan.md`, text);
-        text += note;
-    }
-    return { content: [{ type: "text", text }] };
+}, async (args) => {
+    return getTicketArtifact("architecture", args);
 });
 registerTool("get_clarifying_questions", {
-    description: "Retrieve AI-generated clarifying questions (for feature/task tickets) or debugging guidance (for bug tickets) for a Jira ticket. " +
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    description: "RETRIEVE already-generated clarifying questions (for feature/task tickets) or debugging guidance (for bug tickets) for a Jira ticket. This tool only fetches existing questions — it does NOT start or trigger generation. " +
+        "If no questions exist yet (or you need fresh ones), call `request_clarifying_questions` first; it starts the async generation and this `get_clarifying_questions` tool retrieves the result. " +
         "Returns markdown text with questions that should be resolved before implementation begins. " +
-        "Returns 404 if no questions have been generated yet. " +
+        "Returns a 404 / not-found response when no questions are ready yet — that means generation has not run, not that this tool failed. " +
         "Tip: call get_plan for the same ticket to get the implementation plan alongside these questions.",
     inputSchema: {
         ticket_number: z
@@ -1070,18 +1875,16 @@ registerTool("get_clarifying_questions", {
             .describe("Whether to save the clarifying questions to a local file in the BAPI_DOCS_DIR/clarifying-questions/ directory. " +
             "Defaults to true. Set to false to skip saving."),
     },
-}, async ({ ticket_number, save_locally }) => {
-    const url = buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/clarifying-questions`, { repo_name: REPO_NAME });
-    const resp = await fetch(url, { headers: GET_HEADERS });
-    const ok = resp.ok;
-    let text = await handleResponse(resp);
-    if (ok && save_locally) {
-        const note = await saveLocally(getDocsPath("clarifying-questions"), `${ticket_number}-clarifying-questions.md`, text);
-        text += note;
-    }
-    return { content: [{ type: "text", text }] };
+}, async (args) => {
+    return getTicketArtifact("clarifying_questions", args);
 });
 registerTool("parse_repository", {
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
     description: "Queue a background job to parse and index the repository for Bridge API's AI agents. " +
         "This should be run after major codebase changes so that plans and questions reflect the latest code. " +
         "Returns 202 with {message: 'Repository parsing queued'} on success, " +
@@ -1101,13 +1904,19 @@ registerTool("parse_repository", {
         payload.directory_path = directory_path;
     const resp = await fetch(buildUrl("/parse-repository"), {
         method: "POST",
-        headers: POST_HEADERS,
+        headers: await getPostHeaders(),
         body: JSON.stringify(payload),
     });
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
 registerTool("regenerate_directory_map", {
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
     description: "Regenerate the repository directory map and return the result. " +
         "Unlike parse_repository (which is async), this tool is synchronous — it blocks until " +
         "the directory map is generated and returns the full map text directly. " +
@@ -1120,7 +1929,7 @@ registerTool("regenerate_directory_map", {
     try {
         const resp = await fetch(buildUrl("/regenerate-directory-map"), {
             method: "POST",
-            headers: POST_HEADERS,
+            headers: await getPostHeaders(),
             body: JSON.stringify({ repo_name: REPO_NAME }),
             signal: controller.signal,
         });
@@ -1132,6 +1941,12 @@ registerTool("regenerate_directory_map", {
     }
 });
 registerTool("get_parse_status", {
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
     description: "Check whether a repository parse job is currently running. " +
         "Returns {status: 'in_progress', started_at: '<ISO timestamp>'} if a parse is active, " +
         "or {status: 'idle'} if no parse is running. " +
@@ -1140,11 +1955,17 @@ registerTool("get_parse_status", {
     inputSchema: {},
 }, async () => {
     const url = buildGetUrl("/parse-status", { repo_name: REPO_NAME });
-    const resp = await fetch(url, { headers: GET_HEADERS });
+    const resp = await fetch(url, { headers: await getGetHeaders() });
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
 registerTool("add_comment", {
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
     description: "Post a comment on a Jira ticket. The comment appears immediately in Jira. " +
         "Supports markdown formatting. " +
         "For long comments (over ~2000 characters), set attach_as_file to true — " +
@@ -1192,13 +2013,19 @@ registerTool("add_comment", {
     }
     const resp = await fetch(buildUrl(`/ticket/${encodeURIComponent(ticket_number)}/comment`), {
         method: "POST",
-        headers: POST_HEADERS,
+        headers: await getPostHeaders(),
         body: JSON.stringify(payload),
     });
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text: text + resolved.note }] };
 });
 registerTool("update_ticket_description", {
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
     description: "Update the description of an existing Jira ticket. This is a direct, synchronous update that overwrites the existing description with the provided text. " +
         "The description should be in markdown format — it will be automatically converted to Jira wiki markup. " +
         "This does NOT create a new ticket. Use create_ticket for that. " +
@@ -1224,19 +2051,25 @@ registerTool("update_ticket_description", {
         return resolved.errorResponse;
     const resp = await fetch(buildUrl(`/ticket/${encodeURIComponent(ticket_number)}/description`), {
         method: "PUT",
-        headers: POST_HEADERS,
+        headers: await getPostHeaders(),
         body: JSON.stringify({ repo_name: REPO_NAME, description: resolved.text }),
     });
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text: text + resolved.note }] };
 });
 registerTool("upload_attachment", {
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
     description: "Upload a local file as an attachment to a Jira ticket. " +
         "Supports text/UTF-8 files only (markdown, plain text, etc.). " +
         "Optionally syncs the content to Bridge API's tickets_links table so retrieval endpoints " +
         "(get_clarifying_questions, get_ticket_critique, get_plan) return the updated content without re-generation. " +
         "Use link_type to specify which retrieval endpoint should serve this content. " +
-        "Known link_type values: clarifying-questions.md, debugging-guidance.md, ticket-quality-critique.md, architecture-plan.md.",
+        "Known link_type values: clarifying-questions.md, debugging-guidance.md, ticket-quality-critique.md, architecture-plan.md, fsd-plan.md.",
     inputSchema: {
         ticket_number: z
             .string()
@@ -1287,13 +2120,19 @@ registerTool("upload_attachment", {
     }
     const resp = await fetch(buildUrl(`/ticket/${encodeURIComponent(ticket_number)}/attachment`), {
         method: "POST",
-        headers: POST_HEADERS,
+        headers: await getPostHeaders(),
         body: JSON.stringify(payload),
     });
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text: text + resolved.note }] };
 });
 registerTool("list_attachments", {
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
     description: "List attachments on a Jira ticket. " +
         "Returns metadata (ID, filename, MIME type, size, created date) for each attachment. " +
         "By default, AI-generated attachments are excluded. " +
@@ -1313,12 +2152,23 @@ registerTool("list_attachments", {
         params.include_ai_generated = "true";
     }
     const url = buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/attachments`, params);
-    const resp = await fetch(url, { headers: GET_HEADERS });
-    const text = await handleResponse(resp);
+    const resp = await fetch(url, { headers: await getGetHeaders() });
+    const ok = resp.ok;
+    let text = await handleResponse(resp);
+    if (ok) {
+        const safeTicket = safeTicketFileSegment(ticket_number);
+        const filename = `${safeTicket}-attachment-list.json`;
+        text = await truncateAndSaveIfNeeded(text, await getDocsPath("attachments"), filename);
+    }
     return { content: [{ type: "text", text }] };
 });
-const MAX_INLINE_TEXT_LENGTH = 50_000;
 registerTool("download_attachment", {
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
     description: "Download an attachment from a Jira ticket and save it to disk. " +
         "Specify either attachment_id or filename (not both). " +
         "For text files, the content is returned inline (truncated at ~50KB) and also saved to disk. " +
@@ -1359,7 +2209,7 @@ registerTool("download_attachment", {
     if (filename)
         params.filename = filename;
     const url = buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/attachments/download`, params);
-    const resp = await fetch(url, { headers: GET_HEADERS });
+    const resp = await fetch(url, { headers: await getGetHeaders() });
     if (!resp.ok) {
         const text = await handleResponse(resp);
         return { content: [{ type: "text", text }] };
@@ -1374,9 +2224,9 @@ registerTool("download_attachment", {
     const safeTicket = path.basename(ticket_number);
     const savePath = file_path
         ? file_path
-        : path.join(BAPI_DOCS_DIR, "attachments", safeTicket, safeFileName);
+        : path.join(await getDocsDir(), "attachments", safeTicket, safeFileName);
     const resolvedSave = path.resolve(savePath);
-    const resolvedRoot = path.resolve(PROJECT_ROOT);
+    const resolvedRoot = path.resolve(await getProjectRoot());
     if (!resolvedSave.startsWith(resolvedRoot + path.sep) && resolvedSave !== resolvedRoot) {
         return {
             content: [{
@@ -1407,10 +2257,16 @@ registerTool("download_attachment", {
     return { content: [{ type: "text", text: resultText }] };
 });
 registerTool("request_plan_generation", {
-    description: "Request AI-generated implementation plan for a Jira ticket. " +
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+    description: "START (or refresh) async generation of an implementation plan for a Jira ticket. " +
         "This triggers an asynchronous background job — results are NOT immediate. " +
         "Processing typically takes 1-5 minutes depending on ticket complexity and number of attachments. " +
-        "After submitting, use get_plan with the same ticket_number to check if results are available. " +
+        "The matching get_plan tool retrieves the generated plan later (call get_plan with the same ticket_number) — unless you set wait_for_result, in which case this call blocks and returns the plan directly. " +
         "Returns 202 if the request was accepted, 404 if the ticket does not exist in Jira, " +
         "or 403 if the API key is unauthorized. " +
         "Set wait_for_result to true to block until the result is ready (typically 1-5 minutes) instead of returning immediately.",
@@ -1431,55 +2287,34 @@ registerTool("request_plan_generation", {
             .default(true)
             .describe("When wait_for_result is true, whether to save the plan to a local file in the " +
             "BAPI_DOCS_DIR/plans/ directory. Defaults to true. Ignored when wait_for_result is false."),
-        second_opinion: z.string().optional(),
+        second_opinion: z
+            .string()
+            .optional()
+            .describe("Provider routing override for THIS artifact-generation request " +
+            "(e.g. 'anthropic', 'openai', 'gemini'). When set, the artifact is " +
+            "generated by the named provider and, where supported, a cross-provider " +
+            "second-opinion pass is applied to this request only. " +
+            "This is NOT the standalone `second_opinion` tool — it does not return " +
+            "an ad hoc critique; it only changes which provider produces this " +
+            "request's artifact. Takes precedence over `provider` when both are set."),
         provider: z.string().optional().describe("Pure provider switch — use a specific LLM provider (openai, anthropic, gemini) without " +
             "triggering second-opinion semantics. If both provider and second_opinion are set, " +
             "second_opinion takes precedence."),
     },
-}, async ({ ticket_number, wait_for_result, save_locally, second_opinion, provider }) => {
-    const body = { repo_name: REPO_NAME };
-    const trimmedSecondOpinion = second_opinion?.trim();
-    if (trimmedSecondOpinion) {
-        body.provider_override = trimmedSecondOpinion;
-    }
-    const trimmedProvider = provider?.trim();
-    if (trimmedProvider && !trimmedSecondOpinion) {
-        body.provider = trimmedProvider;
-    }
-    const resp = await fetch(buildUrl(`/ticket/${encodeURIComponent(ticket_number)}/generate-plan`), {
-        method: "POST",
-        headers: POST_HEADERS,
-        body: JSON.stringify(body),
-    });
-    if (!resp.ok) {
-        const errorText = await handleResponse(resp);
-        return {
-            content: [{ type: "text", text: `Failed to request plan generation: ${errorText}` }],
-        };
-    }
-    if (wait_for_result) {
-        const getUrl = buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/plan`, { repo_name: REPO_NAME });
-        const result = await pollForResult(getUrl, 900_000, `Plan generation for ${ticket_number}`);
-        if (!result.ok) {
-            return { content: [{ type: "text", text: result.text }] };
-        }
-        let text = result.text;
-        if (save_locally) {
-            const note = await saveLocally(getDocsPath("plans"), `${ticket_number}-plan.md`, text);
-            text += note;
-        }
-        return { content: [{ type: "text", text }] };
-    }
-    const confirmationText = `Plan generation requested for ${ticket_number}. ` +
-        `Processing typically takes 1-5 minutes. ` +
-        `Use get_plan with ticket_number "${ticket_number}" to retrieve the plan once processing completes.`;
-    return { content: [{ type: "text", text: confirmationText }] };
+}, async (args) => {
+    return requestTicketArtifact("plan", args);
 });
 registerTool("request_architecture", {
-    description: "Request AI-generated architecture plan for a Jira ticket. " +
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+    description: "START (or refresh) async generation of an architecture plan for a Jira ticket. " +
         "This triggers an asynchronous background job — results are NOT immediate. " +
         "Processing typically takes 2-4 minutes depending on ticket complexity. " +
-        "After submitting, use get_architecture with the same ticket_number to check if results are available. " +
+        "The matching get_architecture tool retrieves the generated architecture plan later (call get_architecture with the same ticket_number) — unless you set wait_for_result, in which case this call blocks and returns it directly. " +
         "Returns 202 if the request was accepted, 404 if the ticket does not exist in Jira, " +
         "or 403 if the API key is unauthorized. " +
         "Set wait_for_result to true to block until the result is ready (typically 2-4 minutes) instead of returning immediately.",
@@ -1500,55 +2335,115 @@ registerTool("request_architecture", {
             .default(true)
             .describe("When wait_for_result is true, whether to save the architecture plan to a local file in the " +
             "BAPI_DOCS_DIR/architecture/ directory. Defaults to true. Only takes effect when wait_for_result is true."),
-        second_opinion: z.string().optional(),
+        second_opinion: z
+            .string()
+            .optional()
+            .describe("Provider routing override for THIS artifact-generation request " +
+            "(e.g. 'anthropic', 'openai', 'gemini'). When set, the artifact is " +
+            "generated by the named provider and, where supported, a cross-provider " +
+            "second-opinion pass is applied to this request only. " +
+            "This is NOT the standalone `second_opinion` tool — it does not return " +
+            "an ad hoc critique; it only changes which provider produces this " +
+            "request's artifact. Takes precedence over `provider` when both are set."),
         provider: z.string().optional().describe("Pure provider switch — use a specific LLM provider (openai, anthropic, gemini) without " +
             "triggering second-opinion semantics. If both provider and second_opinion are set, " +
             "second_opinion takes precedence."),
     },
-}, async ({ ticket_number, wait_for_result, save_locally, second_opinion, provider }) => {
-    const body = { repo_name: REPO_NAME };
-    const trimmedSecondOpinion = second_opinion?.trim();
-    if (trimmedSecondOpinion) {
-        body.provider_override = trimmedSecondOpinion;
-    }
-    const trimmedProvider = provider?.trim();
-    if (trimmedProvider && !trimmedSecondOpinion) {
-        body.provider = trimmedProvider;
-    }
-    const resp = await fetch(buildUrl(`/ticket/${encodeURIComponent(ticket_number)}/generate-architecture`), {
-        method: "POST",
-        headers: POST_HEADERS,
-        body: JSON.stringify(body),
-    });
-    if (!resp.ok) {
-        const errorText = await handleResponse(resp);
-        return {
-            content: [{ type: "text", text: `Failed to request architecture generation: ${errorText}` }],
-        };
-    }
-    if (wait_for_result) {
-        const getUrl = buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/architecture-plan`, { repo_name: REPO_NAME });
-        const result = await pollForResult(getUrl, 900_000, `Architecture generation for ${ticket_number}`);
-        if (!result.ok) {
-            return { content: [{ type: "text", text: result.text }] };
-        }
-        let text = result.text;
-        if (save_locally) {
-            const note = await saveLocally(getDocsPath("architecture"), `${ticket_number}-architecture-plan.md`, text);
-            text += note;
-        }
-        return { content: [{ type: "text", text }] };
-    }
-    const confirmationText = `Architecture generation requested for ${ticket_number}. ` +
-        `Processing typically takes 2-4 minutes. ` +
-        `Use get_architecture with ticket_number "${ticket_number}" to retrieve the architecture plan once processing completes.`;
-    return { content: [{ type: "text", text: confirmationText }] };
+}, async (args) => {
+    return requestTicketArtifact("architecture", args);
+});
+registerTool("request_design_doc", {
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+    description: "START (or refresh) async generation of a design document for a Jira ticket, routed by doc_type. " +
+        "Use doc_type 'tdd' for a Technical Design Document (architecture-focused, for engineers) or 'fsd' for a " +
+        "Functional Specification Document (product/functional-focused, for PMs, designers, and QA). " +
+        "This triggers an asynchronous background job — results are NOT immediate. " +
+        "Processing typically takes 2-4 minutes depending on ticket complexity. " +
+        "The matching get_design_doc tool retrieves the generated document later (call get_design_doc with the same ticket_number and doc_type) — unless you set wait_for_result, in which case this call blocks and returns it directly. " +
+        "Returns 202 if the request was accepted, 404 if the ticket does not exist in Jira, or 403 if the API key is unauthorized.",
+    inputSchema: {
+        ticket_number: z
+            .string()
+            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123) to generate a design document for"),
+        doc_type: z
+            .enum(["tdd", "fsd"])
+            .describe("Which design document to generate: 'tdd' (Technical Design Document, engineer audience) or " +
+            "'fsd' (Functional Specification Document, product/functional audience)."),
+        wait_for_result: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("When true, the tool blocks and polls until the document is ready (typically 2-4 minutes), " +
+            "then returns the full content directly. When false (default), returns immediately " +
+            "with a confirmation message — use get_design_doc later to retrieve results."),
+        save_locally: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("When wait_for_result is true, whether to save the generated document to a local file under " +
+            "BAPI_DOCS_DIR. Defaults to true. Only takes effect when wait_for_result is true."),
+        second_opinion: z
+            .string()
+            .optional()
+            .describe("Provider routing override for THIS artifact-generation request " +
+            "(e.g. 'anthropic', 'openai', 'gemini'). When set, the artifact is " +
+            "generated by the named provider and, where supported, a cross-provider " +
+            "second-opinion pass is applied to this request only. " +
+            "Takes precedence over `provider` when both are set."),
+        provider: z.string().optional().describe("Pure provider switch — use a specific LLM provider (openai, anthropic, gemini) without " +
+            "triggering second-opinion semantics. If both provider and second_opinion are set, " +
+            "second_opinion takes precedence."),
+    },
+}, async (args) => {
+    return requestTicketArtifact(resolveDesignDocArtifactType(args.doc_type), args);
+});
+registerTool("get_design_doc", {
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    description: "RETRIEVE an already-generated design document for a Jira ticket, routed by doc_type. " +
+        "Use doc_type 'tdd' for the Technical Design Document or 'fsd' for the Functional Specification Document. " +
+        "This tool only fetches an existing document — it does NOT start or trigger generation. " +
+        "If no document exists yet (or you need a fresh one), call `request_design_doc` first with the same doc_type. " +
+        "Returns the full document as markdown text — present it verbatim without summarizing. " +
+        "Returns a 404 / not-found response when no document is ready yet — that means generation has not run, not that this tool failed.",
+    inputSchema: {
+        ticket_number: z
+            .string()
+            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123, BAPI-42)"),
+        doc_type: z
+            .enum(["tdd", "fsd"])
+            .describe("Which design document to retrieve: 'tdd' (Technical Design Document) or " +
+            "'fsd' (Functional Specification Document)."),
+        save_locally: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Whether to save the retrieved document to a local file under BAPI_DOCS_DIR. " +
+            "Defaults to true. Set to false to skip saving."),
+    },
+}, async (args) => {
+    return getTicketArtifact(resolveDesignDocArtifactType(args.doc_type), args);
 });
 registerTool("request_clarifying_questions", {
-    description: "Request AI-generated clarifying questions or debugging guidance for a Jira ticket. " +
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+    description: "START (or refresh) async generation of clarifying questions or debugging guidance for a Jira ticket. " +
         "This triggers an asynchronous background job — results are NOT immediate. " +
         "Processing typically takes 1-5 minutes. " +
-        "After submitting, use get_clarifying_questions with the same ticket_number to check if results are available. " +
+        "The matching get_clarifying_questions tool retrieves the generated questions later (call get_clarifying_questions with the same ticket_number) — unless you set wait_for_result, in which case this call blocks and returns them directly. " +
         "For bug tickets, the result may be debugging guidance instead of clarifying questions. " +
         "Returns 202 if the request was accepted, 404 if the ticket does not exist in Jira, " +
         "or 403 if the API key is unauthorized. " +
@@ -1570,59 +2465,38 @@ registerTool("request_clarifying_questions", {
             .default(true)
             .describe("When wait_for_result is true, whether to save the clarifying questions to a local file in the " +
             "BAPI_DOCS_DIR/clarifying-questions/ directory. Defaults to true. Ignored when wait_for_result is false."),
-        second_opinion: z.string().optional(),
+        second_opinion: z
+            .string()
+            .optional()
+            .describe("Provider routing override for THIS artifact-generation request " +
+            "(e.g. 'anthropic', 'openai', 'gemini'). When set, the artifact is " +
+            "generated by the named provider and, where supported, a cross-provider " +
+            "second-opinion pass is applied to this request only. " +
+            "This is NOT the standalone `second_opinion` tool — it does not return " +
+            "an ad hoc critique; it only changes which provider produces this " +
+            "request's artifact. Takes precedence over `provider` when both are set."),
         provider: z.string().optional().describe("Pure provider switch — use a specific LLM provider (openai, anthropic, gemini) without " +
             "triggering second-opinion semantics. If both provider and second_opinion are set, " +
             "second_opinion takes precedence."),
     },
-}, async ({ ticket_number, wait_for_result, save_locally, second_opinion, provider }) => {
-    const body = { repo_name: REPO_NAME };
-    const trimmedSecondOpinion = second_opinion?.trim();
-    if (trimmedSecondOpinion) {
-        body.provider_override = trimmedSecondOpinion;
-    }
-    const trimmedProvider = provider?.trim();
-    if (trimmedProvider && !trimmedSecondOpinion) {
-        body.provider = trimmedProvider;
-    }
-    const resp = await fetch(buildUrl(`/ticket/${encodeURIComponent(ticket_number)}/generate-clarifying-questions`), {
-        method: "POST",
-        headers: POST_HEADERS,
-        body: JSON.stringify(body),
-    });
-    if (!resp.ok) {
-        const errorText = await handleResponse(resp);
-        return {
-            content: [{ type: "text", text: `Failed to request clarifying questions: ${errorText}` }],
-        };
-    }
-    if (wait_for_result) {
-        const getUrl = buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/clarifying-questions`, { repo_name: REPO_NAME });
-        const result = await pollForResult(getUrl, 900_000, `Clarifying questions for ${ticket_number}`);
-        if (!result.ok) {
-            return { content: [{ type: "text", text: result.text }] };
-        }
-        let text = result.text;
-        if (save_locally) {
-            const note = await saveLocally(getDocsPath("clarifying-questions"), `${ticket_number}-clarifying-questions.md`, text);
-            text += note;
-        }
-        return { content: [{ type: "text", text }] };
-    }
-    const confirmationText = `Clarifying questions requested for ${ticket_number}. ` +
-        `Processing typically takes 1-5 minutes. ` +
-        `Use get_clarifying_questions with ticket_number "${ticket_number}" to retrieve the results once processing completes.`;
-    return { content: [{ type: "text", text: confirmationText }] };
+}, async (args) => {
+    return requestTicketArtifact("clarifying_questions", args);
 });
 // ---------------------------------------------------------------------------
 // Ticket Quality Critique
 // ---------------------------------------------------------------------------
 registerTool("get_ticket_critique", {
-    description: "Retrieve AI-generated ticket quality critique for a Jira ticket. " +
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    description: "RETRIEVE an already-generated ticket quality critique for a Jira ticket. This tool only fetches an existing critique — it does NOT start or trigger generation. " +
+        "If no critique exists yet (or you need a fresh one), call `request_ticket_critique` first; it starts the async generation and this `get_ticket_critique` tool retrieves the result. " +
         "Returns markdown text with a structured critique covering Standards Conformance Analysis, " +
         "Standards Deviations, and Suggested Improvements. " +
-        "Returns 404 if no critique has been generated yet. " +
-        "Tip: use request_ticket_critique to trigger critique generation first.",
+        "Returns a 404 / not-found response when no critique is ready yet — that means generation has not run, not that this tool failed.",
     inputSchema: {
         ticket_number: z
             .string()
@@ -1634,22 +2508,20 @@ registerTool("get_ticket_critique", {
             .describe("Whether to save the critique to a local file in the BAPI_DOCS_DIR/ticket-critiques/ directory. " +
             "Defaults to true. Set to false to skip saving."),
     },
-}, async ({ ticket_number, save_locally }) => {
-    const url = buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/ticket-critique`, { repo_name: REPO_NAME });
-    const resp = await fetch(url, { headers: GET_HEADERS });
-    const ok = resp.ok;
-    let text = await handleResponse(resp);
-    if (ok && save_locally) {
-        const note = await saveLocally(getDocsPath("ticket-critiques"), `${ticket_number}-ticket-quality-critique.md`, text);
-        text += note;
-    }
-    return { content: [{ type: "text", text }] };
+}, async (args) => {
+    return getTicketArtifact("ticket_critique", args);
 });
 registerTool("request_ticket_critique", {
-    description: "Request AI-generated ticket critique for a Jira ticket. " +
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+    description: "START (or refresh) async generation of a ticket critique for a Jira ticket. " +
         "This triggers an asynchronous background job — results are NOT immediate. " +
         "Processing typically takes 1-5 minutes. " +
-        "After submitting, use get_ticket_critique with the same ticket_number to check if results are available. " +
+        "The matching get_ticket_critique tool retrieves the generated critique later (call get_ticket_critique with the same ticket_number) — unless you set wait_for_result, in which case this call blocks and returns it directly. " +
         "Returns 202 if the request was accepted, 404 if the ticket does not exist in Jira, " +
         "or 403 if the API key is unauthorized. " +
         "Set wait_for_result to true to block until the result is ready (typically 1-5 minutes) instead of returning immediately.",
@@ -1670,54 +2542,33 @@ registerTool("request_ticket_critique", {
             .default(true)
             .describe("When wait_for_result is true, whether to save the ticket critique to a local file in the " +
             "BAPI_DOCS_DIR/ticket-critiques/ directory. Defaults to true. Ignored when wait_for_result is false."),
-        second_opinion: z.string().optional(),
+        second_opinion: z
+            .string()
+            .optional()
+            .describe("Provider routing override for THIS artifact-generation request " +
+            "(e.g. 'anthropic', 'openai', 'gemini'). When set, the artifact is " +
+            "generated by the named provider and, where supported, a cross-provider " +
+            "second-opinion pass is applied to this request only. " +
+            "This is NOT the standalone `second_opinion` tool — it does not return " +
+            "an ad hoc critique; it only changes which provider produces this " +
+            "request's artifact. Takes precedence over `provider` when both are set."),
         provider: z.string().optional().describe("Pure provider switch — use a specific LLM provider (openai, anthropic, gemini) without " +
             "triggering second-opinion semantics. If both provider and second_opinion are set, " +
             "second_opinion takes precedence."),
     },
-}, async ({ ticket_number, wait_for_result, save_locally, second_opinion, provider }) => {
-    const body = { repo_name: REPO_NAME };
-    const trimmedSecondOpinion = second_opinion?.trim();
-    if (trimmedSecondOpinion) {
-        body.provider_override = trimmedSecondOpinion;
-    }
-    const trimmedProvider = provider?.trim();
-    if (trimmedProvider && !trimmedSecondOpinion) {
-        body.provider = trimmedProvider;
-    }
-    const resp = await fetch(buildUrl(`/ticket/${encodeURIComponent(ticket_number)}/generate-ticket-critique`), {
-        method: "POST",
-        headers: POST_HEADERS,
-        body: JSON.stringify(body),
-    });
-    if (!resp.ok) {
-        const errorText = await handleResponse(resp);
-        return {
-            content: [{ type: "text", text: `Failed to request ticket critique: ${errorText}` }],
-        };
-    }
-    if (wait_for_result) {
-        const getUrl = buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/ticket-critique`, { repo_name: REPO_NAME });
-        const result = await pollForResult(getUrl, 900_000, `Ticket critique for ${ticket_number}`);
-        if (!result.ok) {
-            return { content: [{ type: "text", text: result.text }] };
-        }
-        let text = result.text;
-        if (save_locally) {
-            const note = await saveLocally(getDocsPath("ticket-critiques"), `${ticket_number}-ticket-quality-critique.md`, text);
-            text += note;
-        }
-        return { content: [{ type: "text", text }] };
-    }
-    const confirmationText = `Ticket critique requested for ${ticket_number}. ` +
-        `Processing typically takes 1-5 minutes. ` +
-        `Use get_ticket_critique with ticket_number "${ticket_number}" to retrieve the results once processing completes.`;
-    return { content: [{ type: "text", text: confirmationText }] };
+}, async (args) => {
+    return requestTicketArtifact("ticket_critique", args);
 });
 // ---------------------------------------------------------------------------
 // Combined Ticket Review (clarify + critique)
 // ---------------------------------------------------------------------------
 registerTool("request_ticket_review", {
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
     description: "Request a combined ticket review that generates BOTH clarifying questions (or debugging guidance for bug tickets) " +
         "AND a ticket quality critique in parallel on the server, halving wall-clock latency vs. running the two " +
         "requests sequentially. This triggers an asynchronous background job — results are NOT immediate. " +
@@ -1742,93 +2593,37 @@ registerTool("request_ticket_review", {
             .default(true)
             .describe("When wait_for_result is true, whether to save each generated document to its canonical local path under " +
             "BAPI_DOCS_DIR (clarifying-questions/ or ticket-critiques/). Defaults to true. Ignored when wait_for_result is false."),
-        second_opinion: z.string().optional(),
+        second_opinion: z
+            .string()
+            .optional()
+            .describe("Provider routing override for THIS artifact-generation request " +
+            "(e.g. 'anthropic', 'openai', 'gemini'). When set, the artifact is " +
+            "generated by the named provider and, where supported, a cross-provider " +
+            "second-opinion pass is applied to this request only. " +
+            "This is NOT the standalone `second_opinion` tool — it does not return " +
+            "an ad hoc critique; it only changes which provider produces this " +
+            "request's artifact. Takes precedence over `provider` when both are set."),
         provider: z.string().optional().describe("Pure provider switch — use a specific LLM provider (openai, anthropic, gemini) without " +
             "triggering second-opinion semantics. If both provider and second_opinion are set, " +
             "second_opinion takes precedence."),
     },
-}, async ({ ticket_number, wait_for_result, save_locally, second_opinion, provider }) => {
-    const body = { repo_name: REPO_NAME };
-    const trimmedSecondOpinion = second_opinion?.trim();
-    if (trimmedSecondOpinion) {
-        body.provider_override = trimmedSecondOpinion;
-    }
-    const trimmedProvider = provider?.trim();
-    if (trimmedProvider && !trimmedSecondOpinion) {
-        body.provider = trimmedProvider;
-    }
-    const resp = await fetch(buildUrl(`/ticket/${encodeURIComponent(ticket_number)}/generate-ticket-review`), {
-        method: "POST",
-        headers: POST_HEADERS,
-        body: JSON.stringify(body),
-    });
-    if (!resp.ok) {
-        const errorText = await handleResponse(resp);
-        return {
-            content: [{ type: "text", text: `Failed to request ticket review: ${errorText}` }],
-        };
-    }
-    if (wait_for_result) {
-        const getUrl = buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/ticket-review`, { repo_name: REPO_NAME });
-        const result = await pollForResult(getUrl, 900_000, `Ticket review for ${ticket_number}`);
-        if (!result.ok) {
-            return { content: [{ type: "text", text: result.text }] };
-        }
-        // The combined GET endpoint returns JSON. Parse and fan out into markdown.
-        let envelope;
-        try {
-            envelope = JSON.parse(result.text);
-        }
-        catch (parseErr) {
-            return {
-                content: [{
-                        type: "text",
-                        text: `Failed to parse ticket review response: ${parseErr}\nRaw body: ${result.text}`,
-                    }],
-            };
-        }
-        const clarify = envelope.clarify ?? {};
-        const critique = envelope.critique ?? {};
-        const parts = [];
-        let notes = "";
-        if (clarify.status === "success" && typeof clarify.content === "string" && clarify.content) {
-            parts.push(clarify.content);
-            if (save_locally && clarify.doc_type) {
-                const filename = `${ticket_number}-${clarify.doc_type}`;
-                const note = await saveLocally(getDocsPath("clarifying-questions"), filename, clarify.content);
-                notes += note;
-            }
-        }
-        else {
-            parts.push(`> **Note:** Clarifying questions sub-flow ${clarify.status ?? "unavailable"} (no content returned).`);
-        }
-        if (critique.status === "success" && typeof critique.content === "string" && critique.content) {
-            parts.push(critique.content);
-            if (save_locally && critique.doc_type) {
-                const filename = `${ticket_number}-${critique.doc_type}`;
-                const note = await saveLocally(getDocsPath("ticket-critiques"), filename, critique.content);
-                notes += note;
-            }
-        }
-        else {
-            parts.push(`> **Note:** Ticket critique sub-flow ${critique.status ?? "unavailable"} (no content returned).`);
-        }
-        const text = parts.join("\n\n---\n\n") + notes;
-        return { content: [{ type: "text", text }] };
-    }
-    const confirmationText = `Combined ticket review requested for ${ticket_number}. ` +
-        `Processing typically takes 2-6 minutes. ` +
-        `Use get_clarifying_questions and get_ticket_critique with ticket_number "${ticket_number}" to retrieve the two documents once processing completes.`;
-    return { content: [{ type: "text", text: confirmationText }] };
+}, async (args) => {
+    return requestTicketReview(args);
 });
 // ---------------------------------------------------------------------------
 // Reimplement Context
 // ---------------------------------------------------------------------------
 registerTool("request_reimplement_context", {
-    description: "Request processing of new attachments and context assembly for a previously-implemented Jira ticket. " +
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+    description: "START async processing of new attachments and context assembly for a previously-implemented Jira ticket. " +
         "Use this for follow-up requests on tickets that have already been through the plan+implement cycle. " +
         "This triggers an asynchronous background job to process new attachments/images. " +
-        "After submitting, use get_reimplement_context with the same ticket_number to retrieve the assembled context. " +
+        "The matching get_reimplement_context tool retrieves the assembled context later (call get_reimplement_context with the same ticket_number) — unless you set wait_for_result, in which case this call blocks and returns it directly. " +
         "Set wait_for_result to true to block until the context is ready instead of returning immediately.",
     inputSchema: {
         ticket_number: z
@@ -1846,56 +2641,35 @@ registerTool("request_reimplement_context", {
             .default(true)
             .describe("When wait_for_result is true, save the context markdown to " +
             "BAPI_DOCS_DIR/reimplementations/{ticket_number}-context.md. Defaults to true."),
-        second_opinion: z.string().optional(),
+        second_opinion: z
+            .string()
+            .optional()
+            .describe("Provider routing override for THIS artifact-generation request " +
+            "(e.g. 'anthropic', 'openai', 'gemini'). When set, the artifact is " +
+            "generated by the named provider and, where supported, a cross-provider " +
+            "second-opinion pass is applied to this request only. " +
+            "This is NOT the standalone `second_opinion` tool — it does not return " +
+            "an ad hoc critique; it only changes which provider produces this " +
+            "request's artifact. Takes precedence over `provider` when both are set."),
         provider: z.string().optional().describe("Pure provider switch — use a specific LLM provider (openai, anthropic, gemini) without " +
             "triggering second-opinion semantics. If both provider and second_opinion are set, " +
             "second_opinion takes precedence."),
     },
-}, async ({ ticket_number, wait_for_result, save_locally, second_opinion, provider }) => {
-    const body = { repo_name: REPO_NAME };
-    const trimmedSecondOpinion = second_opinion?.trim();
-    if (trimmedSecondOpinion) {
-        body.provider_override = trimmedSecondOpinion;
-    }
-    const trimmedProvider = provider?.trim();
-    if (trimmedProvider && !trimmedSecondOpinion) {
-        body.provider = trimmedProvider;
-    }
-    const resp = await fetch(buildUrl(`/ticket/${encodeURIComponent(ticket_number)}/request-reimplement-context`), {
-        method: "POST",
-        headers: POST_HEADERS,
-        body: JSON.stringify(body),
-    });
-    if (!resp.ok) {
-        const errorText = await handleResponse(resp);
-        return {
-            content: [{ type: "text", text: `Failed to request reimplement context: ${errorText}` }],
-        };
-    }
-    if (wait_for_result) {
-        const getUrl = buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/reimplement-context`, { repo_name: REPO_NAME });
-        const result = await pollForResult(getUrl, 900_000, `Reimplement context for ${ticket_number}`);
-        if (!result.ok) {
-            return { content: [{ type: "text", text: result.text }] };
-        }
-        let text = result.text;
-        if (save_locally) {
-            const note = await saveLocally(getDocsPath("reimplementations"), `${ticket_number}-context.md`, text);
-            text += note;
-        }
-        return { content: [{ type: "text", text }] };
-    }
-    const confirmationText = `Reimplement context processing requested for ${ticket_number}. ` +
-        `Processing typically takes 1-2 minutes. ` +
-        `Use get_reimplement_context with ticket_number "${ticket_number}" to retrieve the results once processing completes.`;
-    return { content: [{ type: "text", text: confirmationText }] };
+}, async (args) => {
+    return requestTicketArtifact("reimplement_context", args);
 });
 registerTool("get_reimplement_context", {
-    description: "Retrieve the assembled reimplement context for a Jira ticket. " +
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    description: "RETRIEVE an already-assembled reimplement context for a Jira ticket. This tool only fetches an existing result — it does NOT start or trigger processing. " +
+        "If the reimplement context does not exist yet (or you need a fresh one), call `request_reimplement_context` first; it starts the async processing and this `get_reimplement_context` tool retrieves the result. " +
         "Returns a markdown document with new/changed information diffed against stored state, " +
         "the original ticket description, and the existing implementation plan. " +
-        "Returns 404 if processing is not yet complete. " +
-        "Tip: use request_reimplement_context to trigger processing first.",
+        "Returns a 404 / not-found response when processing is not yet complete — that means processing has not finished, not that this tool failed.",
     inputSchema: {
         ticket_number: z
             .string()
@@ -1906,35 +2680,24 @@ registerTool("get_reimplement_context", {
             .default(true)
             .describe("Save the context to BAPI_DOCS_DIR/reimplementations/{ticket_number}-context.md. Defaults to true."),
     },
-}, async ({ ticket_number, save_locally }) => {
-    const resp = await fetch(buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/reimplement-context`, { repo_name: REPO_NAME }), { headers: GET_HEADERS });
-    if (resp.status === 404) {
-        return {
-            content: [{
-                    type: "text",
-                    text: JSON.stringify({
-                        error: "NOT_FOUND",
-                        message: `Reimplement context for ${ticket_number} is not yet available. ` +
-                            `Processing may still be in progress. Try again in a moment, ` +
-                            `or call request_reimplement_context to trigger processing.`,
-                    }),
-                }],
-        };
-    }
-    const text = await handleResponse(resp);
-    if (save_locally) {
-        const note = await saveLocally(getDocsPath("reimplementations"), `${ticket_number}-context.md`, text);
-        return { content: [{ type: "text", text: text + note }] };
-    }
-    return { content: [{ type: "text", text }] };
+}, async (args) => {
+    return getTicketArtifact("reimplement_context", args);
 });
 // ---------------------------------------------------------------------------
 // Ticket Lifecycle Tracking
 // ---------------------------------------------------------------------------
 registerTool("track_ticket", {
-    description: "Insert a ticket into Bridge API's database for lifecycle tracking. This registers the ticket so that workflow state timestamps (critique, clarify, plan, implement) can be tracked. " +
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    description: "Write/update Bridge API's DATABASE lifecycle-tracking record for a ticket ONLY. This registers the ticket in Bridge's own database so workflow state timestamps (critique, clarify, plan, implement) can be tracked. " +
+        "It does NOT edit anything in Jira: it does not change the Jira summary, description, comments, attachments, or status. " +
         "If the ticket is already tracked, this is a safe no-op — it upserts the description and repo_name without error. " +
-        "Call this after creating a ticket with create_ticket to enable state tracking. " +
+        "After create_ticket, this is the correct next step when you want Bridge to track that ticket's workflow timestamps / artifact state. " +
+        "For Jira mutations use a different tool instead: `update_ticket_description` to replace the Jira description, `add_comment` to post a Jira comment, and `update_jira_status` to move the Jira workflow status. " +
         "The repo_name is automatically injected from the configured environment.",
     inputSchema: {
         ticket_number: z.string().describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
@@ -1946,13 +2709,19 @@ registerTool("track_ticket", {
         payload.description = description;
     const resp = await fetch(buildUrl(`/ticket/${encodeURIComponent(ticket_number)}/track`), {
         method: "POST",
-        headers: POST_HEADERS,
+        headers: await getPostHeaders(),
         body: JSON.stringify(payload),
     });
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
 registerTool("update_ticket_state", {
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
     description: "Update workflow state timestamps on a tracked ticket. Each specified field is set to the current UTC timestamp on the server. " +
         "Valid field names: 'critique_called', 'critique_answered', 'clarify_called', 'clarify_answered', 'plan_generated', 'implemented', 'reimplement_called'. " +
         "The ticket must already be tracked (via track_ticket) or a 404 error is returned. " +
@@ -1966,13 +2735,19 @@ registerTool("update_ticket_state", {
     const payload = { repo_name: REPO_NAME, fields };
     const resp = await fetch(buildUrl(`/ticket/${encodeURIComponent(ticket_number)}/state`), {
         method: "PUT",
-        headers: POST_HEADERS,
+        headers: await getPostHeaders(),
         body: JSON.stringify(payload),
     });
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
 registerTool("get_ticket_state", {
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
     description: "Retrieve workflow state timestamps and artifact existence flags for a tracked ticket. " +
         "Returns timestamps for each state field (critique_called, critique_answered, clarify_called, clarify_answered, plan_generated, implemented, reimplement_called) " +
         "and boolean flags indicating whether artifacts exist (has_clarifying_questions, has_critique, has_plan). " +
@@ -1983,7 +2758,7 @@ registerTool("get_ticket_state", {
     },
 }, async ({ ticket_number }) => {
     const url = buildGetUrl(`/ticket/${encodeURIComponent(ticket_number)}/state`, { repo_name: REPO_NAME });
-    const resp = await fetch(url, { headers: GET_HEADERS });
+    const resp = await fetch(url, { headers: await getGetHeaders() });
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
@@ -1991,6 +2766,12 @@ registerTool("get_ticket_state", {
 // Jira Transitions
 // ---------------------------------------------------------------------------
 registerTool("get_jira_transitions", {
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
     description: "List available Jira workflow transitions for a ticket. Returns each transition's id, name, and target status. " +
         "Use this to discover what status changes are possible for a given ticket. " +
         "The repo_name is automatically injected from the configured environment.",
@@ -1999,11 +2780,17 @@ registerTool("get_jira_transitions", {
     },
 }, async ({ ticket_number }) => {
     const url = buildGetUrl(`/tickets/${encodeURIComponent(ticket_number)}/jira-transitions`, { repo_name: REPO_NAME });
-    const resp = await fetch(url, { headers: GET_HEADERS });
+    const resp = await fetch(url, { headers: await getGetHeaders() });
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
 registerTool("update_jira_status", {
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
     description: "Transition a Jira ticket to a specified target status by executing a workflow transition. " +
         "Provide either target_status (matched case-insensitively against available transitions) or transition_id (used directly). " +
         "If transition_id is provided, it takes precedence over target_status. " +
@@ -2024,16 +2811,24 @@ registerTool("update_jira_status", {
         payload.transition_id = transition_id;
     const resp = await fetch(buildUrl(`/tickets/${encodeURIComponent(ticket_number)}/jira-status`), {
         method: "PUT",
-        headers: POST_HEADERS,
+        headers: await getPostHeaders(),
         body: JSON.stringify(payload),
     });
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
 registerTool("resolve_target_status", {
-    description: "Resolve the post-PR target Jira status for the configured repository using an LLM agent. " +
-        "The agent selects the workflow status that best represents 'code committed via PR but not yet tested.' " +
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    description: "Ask an LLM agent to CHOOSE the project's post-PR target Jira status, and cache that choice per project. " +
+        "The agent selects the single workflow status that best represents 'code committed via PR but not yet tested.' " +
         "Results are cached per-project — subsequent calls return the cached value unless force_rerun is true. " +
+        "This does NOT list all available transitions — use `get_jira_transitions` for the full transition list. " +
+        "This also does NOT move the ticket — use `update_jira_status` to actually perform the status transition. " +
         "Requires a ticket_number to fetch available transitions from Jira. " +
         "The repo_name is automatically injected from the configured environment.",
     inputSchema: {
@@ -2049,7 +2844,7 @@ registerTool("resolve_target_status", {
         payload.force_rerun = force_rerun;
     const resp = await fetch(buildUrl("/resolve-target-status"), {
         method: "POST",
-        headers: POST_HEADERS,
+        headers: await getPostHeaders(),
         body: JSON.stringify(payload),
     });
     const text = await handleResponse(resp);
@@ -2060,6 +2855,7 @@ registerTool("resolve_target_status", {
 // ---------------------------------------------------------------------------
 const VALID_CONFIG_FIELDS = [
     "review_instructions", "documentation_instructions", "architecture_instructions",
+    "tdd_document_instructions", "fsd_document_instructions",
     "unit_testing_instructions", "e2e_testing_instructions",
     "unit_testing_stack", "e2e_testing_stack",
     "frontend_correctness_standards", "backend_correctness_standards",
@@ -2069,8 +2865,24 @@ const VALID_CONFIG_FIELDS = [
     "allow_mutating_smoke_ops",
     "selected_mcp_slugs",
     "base_branch",
+    "difficulty_model_routing_enabled",
+    "difficulty_model_tier_overrides",
+    // BAPI-356 easy-install bootstrap fields (also exposed via the registry).
+    "working_in",
+    "version_control_system",
+    "version",
+    "project_description",
+    "custom_directories",
+    "exclude_directories",
+    "exclude_file_extensions",
 ].join(", ");
 registerTool("list_config_fields", {
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
     description: "List all configurable fields available for reading and updating via the Bridge API. " +
         "Returns each field's name and a description of its purpose. No database values are returned — " +
         "use get_config_field to read a specific field's current value. " +
@@ -2078,11 +2890,17 @@ registerTool("list_config_fields", {
     inputSchema: {},
 }, async () => {
     const url = buildGetUrl("/config-fields", { repo_name: REPO_NAME });
-    const resp = await fetch(url, { headers: GET_HEADERS });
+    const resp = await fetch(url, { headers: await getGetHeaders() });
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
 registerTool("get_my_role", {
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
     description: "Check the role and auth source for the current API key. " +
         "Returns JSON with {role: \"admin\" | \"member\" | null, source: \"user_access\" | \"legacy\"}. " +
         "Use this to check if the current key has admin permissions before attempting configuration updates " +
@@ -2090,35 +2908,61 @@ registerTool("get_my_role", {
     inputSchema: {},
 }, async () => {
     const url = buildGetUrl("/my-role", { repo_name: REPO_NAME });
-    const resp = await fetch(url, { headers: GET_HEADERS });
+    const resp = await fetch(url, { headers: await getGetHeaders() });
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
 registerTool("get_config_field", {
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
     description: "Read the current value and metadata for a specific configuration field. " +
         "Returns the field's current database value (or null if not set), along with a description of its purpose and examples of helpful content. " +
-        "Use this before update_config_field to understand the current state and build upon it rather than overwriting blindly.",
+        "Use this before update_config_field to understand the current state and build upon it rather than overwriting blindly. " +
+        "For install bootstrap, prefer get_install_manifest (one read of all bootstrap fields) over many individual get_config_field reads.",
     inputSchema: {
         field_name: z.string().describe(`The configuration field to read. Valid options: ${VALID_CONFIG_FIELDS}`),
     },
 }, async ({ field_name }) => {
     const url = buildGetUrl(`/config-field/${encodeURIComponent(field_name)}`, { repo_name: REPO_NAME });
-    const resp = await fetch(url, { headers: GET_HEADERS });
+    const resp = await fetch(url, { headers: await getGetHeaders() });
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
 registerTool("update_config_field", {
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
     description: "Update a specific configuration field in the Bridge database. " +
         "These fields control LLM behavior during code review, planning, and documentation. " +
         "Always call get_config_field first to read the current value and build upon it. " +
+        "For install bootstrap, prefer apply_install_manifest (one atomic write of all bootstrap fields, " +
+        "with server-owned skip/conflict/confirmation semantics) over many individual update_config_field writes. " +
         "Returns 400 if the field name is invalid, 404 if the repository has no configuration row yet.",
     inputSchema: {
         field_name: z.string().describe(`The configuration field to update. Valid options: ${VALID_CONFIG_FIELDS}`),
-        value: z.union([z.string(), z.boolean(), z.array(z.string())]).optional().describe("The new value for the configuration field. Provide either value or file_path, not both. " +
-            "Most fields take a string; scalar boolean fields (e.g. allow_mutating_smoke_ops) take true/false. " +
+        value: z.union([
+            z.string(),
+            z.boolean(),
+            z.array(z.string()),
+            z.record(z.string(), z.union([z.string(), z.null()])),
+        ]).optional().describe("The new value for the configuration field. Provide either value or file_path, not both. " +
+            "Most fields take a string; scalar boolean fields (e.g. allow_mutating_smoke_ops, " +
+            "difficulty_model_routing_enabled) take true/false. " +
             "The selected_mcp_slugs field takes a JSON array of supported MCP validation manual slug strings " +
             "(e.g. [\"b2c-commerce-developer\", \"playwright-mcp\", \"pwa-kit-mcp\"]) — pass an array of strings, " +
             "not a comma-delimited string; an empty array clears the selection. " +
+            "The difficulty_model_tier_overrides field takes a JSON object mapping tier names " +
+            "(\"cheap\"/\"basic\"/\"premium\") to per-repo model aliases (e.g. {\"premium\": \"opus\"}) — pass " +
+            "an object, not a string; an empty object clears all overrides. " +
+            "The difficulty_model_routing_enabled field enables difficulty-based /start-tickets model routing " +
+            "(default ON); pass true/false. " +
             "The base_branch field is a string/null field controlling the development base branch used by PR " +
             "creation (/create-pr) and start-tickets worktree creation; an empty/null value clears it and " +
             "automations fall back to 'main'. " +
@@ -2129,8 +2973,17 @@ registerTool("update_config_field", {
             "Useful for large configuration values like detailed review instructions. " +
             "The file must be UTF-8 encoded and under 1MB. " +
             "Not supported for scalar boolean fields like allow_mutating_smoke_ops."),
+        only_if_null: z.boolean().optional().describe("Secondary conditional-write guard: when true, the field is updated only if its column is " +
+            "currently NULL (returns status 'skipped'/reason 'already_set' otherwise). Legal only for " +
+            "nullable columns (HTTP 422 otherwise). This is NOT the install bootstrap write path — for " +
+            "easy install, prefer apply_install_manifest, which owns skip/conflict/confirmation semantics."),
     },
-}, async ({ field_name, value, file_path }) => {
+}, async ({ field_name, value, file_path, only_if_null }) => {
+    // Build the PUT body, including only_if_null only when explicitly true so
+    // the default (false) request shape is unchanged for existing callers.
+    const withGuard = (v) => only_if_null === true
+        ? { repo_name: REPO_NAME, value: v, only_if_null: true }
+        : { repo_name: REPO_NAME, value: v };
     // JSONB array config fields (e.g. selected_mcp_slugs): forward the array value
     // as JSON. Never join into a comma-delimited string — the backend expects a
     // real JSON array and validates each slug against the mcp_docs allowlist.
@@ -2152,15 +3005,40 @@ registerTool("update_config_field", {
         const arrayValue = value === undefined ? [] : value;
         const resp = await fetch(buildUrl(`/config-field/${encodeURIComponent(field_name)}`), {
             method: "PUT",
-            headers: POST_HEADERS,
-            body: JSON.stringify({ repo_name: REPO_NAME, value: arrayValue }),
+            headers: await getPostHeaders(),
+            body: JSON.stringify(withGuard(arrayValue)),
+        });
+        const text = await handleResponse(resp);
+        return { content: [{ type: "text", text }] };
+    }
+    // JSONB object config fields (e.g. difficulty_model_tier_overrides): forward the
+    // object value as JSON. Reject file_path; the backend validates/normalizes keys
+    // and alias values. An omitted value clears all overrides (empty object).
+    const JSON_OBJECT_CONFIG_FIELDS = ["difficulty_model_tier_overrides"];
+    if (JSON_OBJECT_CONFIG_FIELDS.includes(field_name)) {
+        if (file_path) {
+            return {
+                isError: true,
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            error: `'${field_name}' is a JSON object field; file_path updates are not supported. Pass value as an object mapping tier names to model aliases.`,
+                        }),
+                    }],
+            };
+        }
+        const objectValue = value === undefined ? {} : value;
+        const resp = await fetch(buildUrl(`/config-field/${encodeURIComponent(field_name)}`), {
+            method: "PUT",
+            headers: await getPostHeaders(),
+            body: JSON.stringify(withGuard(objectValue)),
         });
         const text = await handleResponse(resp);
         return { content: [{ type: "text", text }] };
     }
     // Scalar boolean config fields: reject file-path updates and normalize boolean
     // true/false and string "true"/"false" to a real boolean before persisting.
-    const BOOLEAN_CONFIG_FIELDS = ["allow_mutating_smoke_ops"];
+    const BOOLEAN_CONFIG_FIELDS = ["allow_mutating_smoke_ops", "difficulty_model_routing_enabled"];
     if (BOOLEAN_CONFIG_FIELDS.includes(field_name)) {
         if (file_path) {
             return {
@@ -2201,8 +3079,8 @@ registerTool("update_config_field", {
         }
         const resp = await fetch(buildUrl(`/config-field/${encodeURIComponent(field_name)}`), {
             method: "PUT",
-            headers: POST_HEADERS,
-            body: JSON.stringify({ repo_name: REPO_NAME, value: boolValue }),
+            headers: await getPostHeaders(),
+            body: JSON.stringify(withGuard(boolValue)),
         });
         const text = await handleResponse(resp);
         return { content: [{ type: "text", text }] };
@@ -2219,12 +3097,72 @@ registerTool("update_config_field", {
     }
     const resp = await fetch(buildUrl(`/config-field/${encodeURIComponent(field_name)}`), {
         method: "PUT",
-        headers: POST_HEADERS,
-        body: JSON.stringify({ repo_name: REPO_NAME, value: finalValue }),
+        headers: await getPostHeaders(),
+        body: JSON.stringify(withGuard(finalValue)),
     });
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text: text + note }] };
 });
+// ---------------------------------------------------------------------------
+// Easy Install (BAPI-356): read-the-manifest / apply-the-manifest
+// ---------------------------------------------------------------------------
+registerTool("get_install_manifest", {
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    description: "Read the easy-install configuration manifest for the configured repository in one call. " +
+        "Returns ordered field groups (each bootstrap field with its current value, is_set flag, agent " +
+        "guidance, examples, and validation summary), a list of deferred fields (owned by " +
+        "/learn-repository or set deliberately), a next_step pointer, done_criteria, and a signed " +
+        "snapshot_token. Pass that exact snapshot_token to apply_install_manifest. " +
+        "Prefer this over many individual get_config_field reads during install bootstrap.",
+    inputSchema: {
+        save_locally: z.boolean().optional().default(true).describe("When true (default), also save the full JSON manifest under BAPI_DOCS_DIR/install/."),
+    },
+}, async ({ save_locally }) => {
+    const url = buildGetUrl("/config/install-manifest", { repo_name: REPO_NAME });
+    const resp = await fetch(url, { headers: await getGetHeaders() });
+    const ok = resp.ok;
+    let text = await handleResponse(resp);
+    if (ok && save_locally !== false) {
+        const safeRepo = safeTicketFileSegment(REPO_NAME || "repo");
+        const filename = `${safeRepo}-install-manifest-${safeTimestampForFilename()}.json`;
+        const note = await saveLocally(await getDocsPath("install"), filename, text);
+        text = text + note;
+    }
+    return { content: [{ type: "text", text }] };
+});
+registerTool("apply_install_manifest", {
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+    description: "Apply easy-install configuration in one atomic call. Pass the snapshot_token returned by " +
+        "get_install_manifest plus a fields object. Each field value is either a scalar " +
+        "(e.g. \"base_branch\": \"main\") or an object (e.g. \"project_description\": {\"value\": \"...\", " +
+        "\"confirmed\": true}). project_description MUST be passed as {value, confirmed: true} and only " +
+        "after explicit human approval. The server owns skip-if-set, conflict detection, and " +
+        "confirmation semantics and returns six buckets: applied, skipped, conflict, rejected, " +
+        "deferred, needs_confirmation. Only bootstrap-eligible fields are accepted (others are rejected).",
+    inputSchema: {
+        snapshot_token: z.string().describe("The exact snapshot_token returned by get_install_manifest for this repository."),
+        fields: z.record(z.string(), z.any()).describe("Map of field_name to value. A value is either a scalar or an object {value, confirmed}. " +
+            "Pass project_description only as {value: \"...\", confirmed: true} after human approval."),
+    },
+}, async ({ snapshot_token, fields }) => {
+    const resp = await fetch(buildUrl("/config/apply-install-manifest"), {
+        method: "POST",
+        headers: await getPostHeaders(),
+        body: JSON.stringify({ repo_name: REPO_NAME, snapshot_token, fields }),
+    });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text }] };
+});
 function formatDeepResearchProviderReason(meta) {
     if (!meta)
         return "";
@@ -2282,8 +3220,14 @@ function formatDeepResearchStatus(body, taskId) {
     return `Status: ${body.status}${elapsed}${reason} (task_id: ${taskId}). Try again in a minute.`;
 }
 registerTool("request_deep_research", {
-    description: "Submit a deep research request on a technical topic using AI-powered web search. " +
-        "Returns a task_id for tracking the research progress. " +
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+    description: "START async deep research on a technical topic using AI-powered web search. " +
+        "Returns a task_id for tracking the research progress; the matching get_deep_research tool retrieves the finished report later (unless you set wait_for_result). " +
         "\n\n" +
         "WHEN TO USE: Use this tool when you need to investigate unfamiliar technologies, " +
         "gather implementation guidance across multiple sources, research best practices for a complex topic, " +
@@ -2325,7 +3269,7 @@ registerTool("request_deep_research", {
         submitPayload.ticket_number = ticket_number;
     const submitResp = await fetch(buildUrl("/deep-research"), {
         method: "POST",
-        headers: POST_HEADERS,
+        headers: await getPostHeaders(),
         body: JSON.stringify(submitPayload),
     });
     if (!submitResp.ok) {
@@ -2351,7 +3295,7 @@ registerTool("request_deep_research", {
         const elapsed = Math.round((Date.now() - startTime) / 1000);
         console.error(`Deep research in progress... (elapsed: ${elapsed}s, status: ${lastStatus})`);
         const statusUrl = buildGetUrl(`/deep-research/${taskId}/status`, { repo_name: REPO_NAME });
-        const statusResp = await fetch(statusUrl, { headers: GET_HEADERS });
+        const statusResp = await fetch(statusUrl, { headers: await getGetHeaders() });
         if (!statusResp.ok) {
             const errorText = await handleResponse(statusResp);
             return { content: [{ type: "text", text: JSON.stringify({ error: "INTERNAL_ERROR", status: 500, message: `Error polling deep research status: ${errorText}` }) }] };
@@ -2388,7 +3332,7 @@ registerTool("request_deep_research", {
     }
     // 3. Retrieve the result
     const resultUrl = buildGetUrl(`/deep-research/${taskId}/result`, { repo_name: REPO_NAME });
-    const resultResp = await fetch(resultUrl, { headers: GET_HEADERS });
+    const resultResp = await fetch(resultUrl, { headers: await getGetHeaders() });
     if (!resultResp.ok) {
         const errorText = await handleResponse(resultResp);
         return { content: [{ type: "text", text: JSON.stringify({ error: "INTERNAL_ERROR", status: 500, message: `Error retrieving deep research result: ${errorText}` }) }] };
@@ -2397,15 +3341,22 @@ registerTool("request_deep_research", {
     // 4. Optionally save to file
     if (save_locally) {
         const slug = slugify(query);
-        const note = await saveLocally(getDocsPath("deep-research"), `${slug}-${taskId}.md`, resultText);
+        const note = await saveLocally(await getDocsPath("deep-research"), `${slug}-${taskId}.md`, resultText);
         resultText += note;
     }
     return { content: [{ type: "text", text: resultText }] };
 });
 registerTool("get_deep_research", {
-    description: "Retrieve the result of a previously submitted deep research request. " +
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    description: "RETRIEVE the result of a previously submitted deep research request. This tool only fetches an existing/in-progress result — it does NOT start or trigger new research. " +
+        "If you have not submitted a research request yet (or you need a new one), call `request_deep_research` first; it starts the async research and this `get_deep_research` tool retrieves the result. " +
         "Returns the full markdown research report if the task is completed, " +
-        "or a structured status response if still processing or failed. " +
+        "or a structured status response (still processing / failed / not-found) if the report is not ready yet — that means research has not finished, not that this tool failed. " +
         "Use this after calling request_deep_research with wait_for_result=false.",
     inputSchema: {
         task_id: z.number().describe("The task ID returned by request_deep_research."),
@@ -2416,7 +3367,7 @@ registerTool("get_deep_research", {
 }, async ({ task_id, query_slug, save_locally }) => {
     // 1. Check status
     const statusUrl = buildGetUrl(`/deep-research/${task_id}/status`, { repo_name: REPO_NAME });
-    const statusResp = await fetch(statusUrl, { headers: GET_HEADERS });
+    const statusResp = await fetch(statusUrl, { headers: await getGetHeaders() });
     if (!statusResp.ok) {
         const errorText = await handleResponse(statusResp);
         return { content: [{ type: "text", text: errorText }] };
@@ -2440,7 +3391,7 @@ registerTool("get_deep_research", {
     }
     // 2. Retrieve the result
     const resultUrl = buildGetUrl(`/deep-research/${task_id}/result`, { repo_name: REPO_NAME });
-    const resultResp = await fetch(resultUrl, { headers: GET_HEADERS });
+    const resultResp = await fetch(resultUrl, { headers: await getGetHeaders() });
     if (!resultResp.ok) {
         const errorText = await handleResponse(resultResp);
         return { content: [{ type: "text", text: errorText }] };
@@ -2449,11 +3400,15 @@ registerTool("get_deep_research", {
     // 3. Optionally save to file
     if (save_locally) {
         const slug = query_slug || "research";
-        const note = await saveLocally(getDocsPath("deep-research"), `${slug}-${task_id}.md`, resultText);
+        const note = await saveLocally(await getDocsPath("deep-research"), `${slug}-${task_id}.md`, resultText);
         resultText += note;
     }
     return { content: [{ type: "text", text: resultText }] };
 });
+// ``BrainstormResultRow`` / ``BrainstormResultEnvelope`` types,
+// ``sanitizeProviderForFilename``, and the brainstorm filename/save helpers now
+// live in ``./brainstorm-files.ts`` so they can be unit-tested directly (see the
+// import near the top of this file).
 const BRAINSTORM_TERMINAL_STATUSES = new Set([
     "completed",
     "failed",
@@ -2462,16 +3417,6 @@ const BRAINSTORM_TERMINAL_STATUSES = new Set([
 function isBrainstormTerminalStatus(status) {
     return BRAINSTORM_TERMINAL_STATUSES.has(status);
 }
-function sanitizeProviderForFilename(provider) {
-    // Defensive: allow letters/digits/hyphen/underscore only; collapse runs and
-    // trim trailing punctuation. Falls back to "provider" for an empty result.
-    const cleaned = provider
-        .toLowerCase()
-        .replace(/[^a-z0-9_-]+/g, "-")
-        .replace(/-+/g, "-")
-        .replace(/^-+|-+$/g, "");
-    return cleaned || "provider";
-}
 async function pollBrainstormUntilTerminal(brainstormId, repoName) {
     const startTime = Date.now();
     const MAX_TIMEOUT_MS = 15 * 60 * 1000;
@@ -2480,7 +3425,7 @@ async function pollBrainstormUntilTerminal(brainstormId, repoName) {
     while (Date.now() - startTime < MAX_TIMEOUT_MS) {
         await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
         const statusUrl = buildGetUrl(`/brainstorms/${brainstormId}/status`, { repo_name: repoName });
-        const statusResp = await fetch(statusUrl, { headers: GET_HEADERS });
+        const statusResp = await fetch(statusUrl, { headers: await getGetHeaders() });
         if (!statusResp.ok) {
             return latest;
         }
@@ -2495,27 +3440,13 @@ async function pollBrainstormUntilTerminal(brainstormId, repoName) {
     }
     return latest;
 }
-async function saveBrainstormResultsLocally(envelope) {
-    const dir = getDocsPath("brainstorm");
-    const savedPaths = [];
-    for (const row of envelope.results) {
-        const markdown = row.markdown;
-        if (!markdown) {
-            continue;
-        }
-        const providerSegment = sanitizeProviderForFilename(row.provider);
-        const filename = `${envelope.brainstorm_id}-${providerSegment}.md`;
-        const filePath = path.join(dir, filename);
-        try {
-            await mkdir(dir, { recursive: true });
-            await writeFile(filePath, markdown, "utf-8");
-            savedPaths.push(filePath);
-        }
-        catch {
-            // Skip rows that fail to write — never block the response.
-        }
-    }
-    return savedPaths;
+async function saveBrainstormResultsLocally(envelope, subject) {
+    // Resolve the docs directory here, then delegate the write loop and filename
+    // construction to the pure, unit-tested helper in ``./brainstorm-files.ts``.
+    // When ``subject`` (the original ``task_description``) is provided, files get
+    // semantic names; otherwise they fall back to the UUID-only pattern.
+    const dir = await getDocsPath("brainstorm");
+    return saveBrainstormResultsToDir(envelope, dir, subject);
 }
 function formatBrainstormToolResponse(envelope, savedPaths) {
     const lines = [];
@@ -2544,14 +3475,28 @@ function formatBrainstormToolResponse(envelope, savedPaths) {
     return lines.join("\n");
 }
 registerTool("request_brainstorm", {
-    description: "Submit a brainstorm request that fans out the task to two opinion-provider LLMs " +
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+    description: "START an async brainstorm that fans out the task to two opinion-provider LLMs " +
         "(default: OpenAI + Gemini) and then runs a synthesizer pass over the completed opinions. " +
-        "Returns a brainstorm_id you can use with get_brainstorm. " +
+        "Returns a brainstorm_id; the matching get_brainstorm tool retrieves the finished result later (unless you set wait_for_result). " +
         "\n\n" +
         "BEHAVIOR: By default, returns immediately with a brainstorm_id. Set wait_for_result=true " +
         "to poll for terminal status (up to 15 minutes), then retrieve and optionally save the result. " +
-        "When save_locally=true (default), each provider's markdown is written to " +
-        "BAPI_DOCS_DIR/brainstorm/{brainstorm_id}-{provider}.md, including {brainstorm_id}-synthesizer.md.",
+        "When save_locally=true (default), each provider's markdown is written with a semantic " +
+        "filename derived from task_description: " +
+        "BAPI_DOCS_DIR/brainstorm/{slugified-task-description}-{short_brainstorm_id}-{provider}.md, " +
+        "and the synthesizer row follows the same pattern " +
+        "({slugified-task-description}-{short_brainstorm_id}-synthesizer.md). " +
+        "(If task_description is empty or slugifies to nothing, it falls back to {brainstorm_id}-{provider}.md.) " +
+        "\n\n" +
+        "DESIGN MODE: Set design=true to run the brainstorm as web-page/UI design ideation focused on " +
+        "visual appeal and conversion, rather than the default software-engineering framing. Omit the " +
+        "design field unless you want design mode (absent is treated as false).",
     inputSchema: {
         task_description: z.string().describe("Free-form description of the task to brainstorm about. Sent verbatim — " +
             "this tool does NOT read task_description from a file."),
@@ -2564,12 +3509,14 @@ registerTool("request_brainstorm", {
         wait_for_result: z.boolean().optional().describe("When true, polls until every row reaches a terminal status (max 15 minutes), " +
             "then returns the full result envelope. When false (default), returns immediately."),
         save_locally: z.boolean().optional().describe("When true (default), writes each provider's markdown to BAPI_DOCS_DIR/brainstorm/ " +
-            "after the result is fetched."),
+            "after the result is fetched. Request-time saves use semantic filenames derived from " +
+            "task_description (slugified) plus a short brainstorm-id segment."),
         prior_brainstorm_id: z.string().optional().describe("Optional brainstorm_id from an earlier brainstorm to refine. " +
             "When provided, the new brainstorm receives the prior brainstorm's " +
             "synthesizer markdown, or a completed opinion-provider fallback, as prior context."),
+        design: z.boolean().optional().describe("Set to true for web-page/UI design ideation focused on visual appeal and conversion. Omit this field when not requesting design mode; absent is treated as false."),
     },
-}, async ({ task_description, repo_name, ticket_number, providers, concerns, wait_for_result, save_locally, prior_brainstorm_id, }) => {
+}, async ({ task_description, repo_name, ticket_number, providers, concerns, wait_for_result, save_locally, prior_brainstorm_id, design, }) => {
     const effectiveRepo = repo_name && repo_name.length > 0 ? repo_name : REPO_NAME;
     const effectiveProviders = providers !== undefined ? providers : ["openai", "gemini"];
     const shouldWait = wait_for_result === true;
@@ -2586,9 +3533,11 @@ registerTool("request_brainstorm", {
     if (prior_brainstorm_id) {
         submitPayload.prior_brainstorm_request_id = prior_brainstorm_id;
     }
+    if (design)
+        submitPayload.design = true;
     const submitResp = await fetch(buildUrl("/brainstorms"), {
         method: "POST",
-        headers: POST_HEADERS,
+        headers: await getPostHeaders(),
         body: JSON.stringify(submitPayload),
     });
     if (!submitResp.ok) {
@@ -2614,7 +3563,7 @@ registerTool("request_brainstorm", {
         };
     }
     const resultUrl = buildGetUrl(`/brainstorms/${submitBody.brainstorm_id}/result`, { repo_name: effectiveRepo });
-    const resultResp = await fetch(resultUrl, { headers: GET_HEADERS });
+    const resultResp = await fetch(resultUrl, { headers: await getGetHeaders() });
     if (!resultResp.ok) {
         const errorText = await handleResponse(resultResp);
         return { content: [{ type: "text", text: errorText }] };
@@ -2622,7 +3571,9 @@ registerTool("request_brainstorm", {
     const envelope = (await resultResp.json());
     let savedPaths = [];
     if (shouldSave) {
-        savedPaths = await saveBrainstormResultsLocally(envelope);
+        // Request-time saves use semantic filenames derived from the in-scope
+        // ``task_description``.
+        savedPaths = await saveBrainstormResultsLocally(envelope, task_description);
     }
     return {
         content: [{
@@ -2632,21 +3583,33 @@ registerTool("request_brainstorm", {
     };
 });
 registerTool("get_brainstorm", {
-    description: "Retrieve the result envelope for a previously submitted brainstorm by brainstorm_id. " +
-        "Returns all rows (opinion providers + synthesizer), including error_kind for every row. " +
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    description: "RETRIEVE the result envelope for a previously submitted brainstorm by brainstorm_id. This tool only fetches an existing/in-progress result — it does NOT start or trigger a new brainstorm. " +
+        "If you have not submitted a brainstorm yet (or you need a new one), call `request_brainstorm` first; it starts the async brainstorm and returns the brainstorm_id this `get_brainstorm` tool retrieves by. " +
+        "Returns all rows (opinion providers + synthesizer), including error_kind for every row; a not-found / still-processing response means the brainstorm has not completed, not that this tool failed. " +
         "When save_locally=true (default), writes each provider's markdown to " +
         "BAPI_DOCS_DIR/brainstorm/{brainstorm_id}-{provider}.md (including the synthesizer file). " +
+        "Retrieval uses this UUID-only filename (not the semantic task-description name that " +
+        "request_brainstorm uses) because the original task description is not available in the " +
+        "result envelope on retrieval. " +
         "DB-only retrieval — never falls back to Jira attachments.",
     inputSchema: {
         brainstorm_id: z.string().describe("The brainstorm_id (UUID) returned by request_brainstorm."),
         repo_name: z.string().optional().describe("Repository name. Defaults to BAPI_REPO_NAME from the environment."),
-        save_locally: z.boolean().optional().describe("When true (default), writes each provider's markdown to BAPI_DOCS_DIR/brainstorm/."),
+        save_locally: z.boolean().optional().describe("When true (default), writes each provider's markdown to BAPI_DOCS_DIR/brainstorm/. " +
+            "Retrieval-time saves intentionally use the UUID-only fallback filename " +
+            "({brainstorm_id}-{provider}.md), not a task-description-derived semantic name."),
     },
 }, async ({ brainstorm_id, repo_name, save_locally }) => {
     const effectiveRepo = repo_name && repo_name.length > 0 ? repo_name : REPO_NAME;
     const shouldSave = save_locally !== false;
     const resultUrl = buildGetUrl(`/brainstorms/${brainstorm_id}/result`, { repo_name: effectiveRepo });
-    const resultResp = await fetch(resultUrl, { headers: GET_HEADERS });
+    const resultResp = await fetch(resultUrl, { headers: await getGetHeaders() });
     if (!resultResp.ok) {
         const errorText = await handleResponse(resultResp);
         return { content: [{ type: "text", text: errorText }] };
@@ -2654,6 +3617,9 @@ registerTool("get_brainstorm", {
     const envelope = (await resultResp.json());
     let savedPaths = [];
     if (shouldSave) {
+        // ``get_brainstorm`` intentionally uses the UUID-only fallback: the result
+        // envelope does not echo the original ``task_description``, so no semantic
+        // subject is available here. (Documented asymmetry with ``request_brainstorm``.)
         savedPaths = await saveBrainstormResultsLocally(envelope);
     }
     return {
@@ -2667,6 +3633,12 @@ registerTool("get_brainstorm", {
 // VCS & CI Tools
 // ---------------------------------------------------------------------------
 registerTool("create_pull_request", {
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
     description: "Create a pull request on the configured VCS provider (GitHub or Bitbucket). " +
         "Returns a structured response with {available, reason, action, detail}. " +
         "If a PR already exists for the head branch, returns it with created=false. " +
@@ -2689,13 +3661,19 @@ registerTool("create_pull_request", {
         payload.body = body;
     const resp = await fetch(buildUrl("/vcs/pull-requests"), {
         method: "POST",
-        headers: POST_HEADERS,
+        headers: await getPostHeaders(),
         body: JSON.stringify(payload),
     });
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
 const resolveCiChecksTool = registerTool("resolve_ci_checks", {
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
     description: "Discover and classify CI checks for the configured repository. " +
         "Queries GitHub Check Runs + Commit Statuses APIs (or Bitbucket Build Statuses), " +
         "then uses Branch Protection API or LLM to determine which checks are required for merging. " +
@@ -2715,7 +3693,7 @@ const resolveCiChecksTool = registerTool("resolve_ci_checks", {
         payload.force_rerun = force_rerun;
     const resp = await fetch(buildUrl("/resolve-ci-checks"), {
         method: "POST",
-        headers: POST_HEADERS,
+        headers: await getPostHeaders(),
         body: JSON.stringify(payload),
     });
     const text = await handleResponse(resp);
@@ -2732,6 +3710,12 @@ const resolveCiChecksTool = registerTool("resolve_ci_checks", {
     return { content: [{ type: "text", text }] };
 });
 const pollCiChecksTool = registerTool("poll_ci_checks", {
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
     description: "Poll the current status of CI checks for a specific commit. " +
         "Requires that resolve_ci_checks has been called first to populate the check configuration. " +
         "Returns per-check status, all_complete, all_passed, and unknown_checks fields. " +
@@ -2746,7 +3730,7 @@ const pollCiChecksTool = registerTool("poll_ci_checks", {
         repo_name: REPO_NAME,
         commit_ref,
     });
-    const resp = await fetch(url, { headers: GET_HEADERS });
+    const resp = await fetch(url, { headers: await getGetHeaders() });
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
@@ -2756,7 +3740,7 @@ const pollCiChecksTool = registerTool("poll_ci_checks", {
 async function checkCiConfigAndDisablePoll() {
     try {
         const url = buildGetUrl("/config-field/ci_check_config", { repo_name: REPO_NAME });
-        const resp = await fetch(url, { headers: GET_HEADERS });
+        const resp = await fetch(url, { headers: await getGetHeaders() });
         if (resp.ok) {
             const body = await resp.json();
             const value = body.value;
@@ -2780,42 +3764,45 @@ async function checkCiConfigAndDisablePoll() {
 // Check config before connecting
 await checkCiConfigAndDisablePoll();
 // ---------------------------------------------------------------------------
-// Custom pipeline loading (BAPI-275)
+// Custom pipeline loading (BAPI-275, deferred in BAPI-338)
 // ---------------------------------------------------------------------------
 //
-// Custom user pipelines must be merged into PIPELINES + INSTRUCTIONS BEFORE
-// the run_pipeline tool is registered so its embedded catalog includes both
-// bundled and user entries. The merge result is also used by list_pipelines
-// and get_pipeline_recipe below — every caller must see the same final
-// objects.
-{
-    const instructionsDir = path.join(path.dirname(BAPI_PIPELINES_DIR), "instructions");
-    const customResult = await loadCustomPipelines(BAPI_PIPELINES_DIR, instructionsDir, BUNDLED_INSTRUCTIONS);
-    for (const [key, pipeline] of Object.entries(customResult.pipelines)) {
-        if (key in BUNDLED_PIPELINES) {
-            console.error(`Warning: user pipeline "${key}" overrides bundled pipeline.`);
-        }
-        PIPELINES[key] = pipeline;
-    }
-    Object.assign(INSTRUCTIONS, customResult.instructions);
-    userPipelineKeys = customResult.userPipelineKeys;
-}
+// Custom user pipelines are merged into PIPELINES + INSTRUCTIONS by
+// `ensureCustomPipelinesLoaded()` (defined above). It is NO LONGER run at module
+// load — the pipelines dir resolution depends on the project root, which may
+// come from MCP `roots/list` and is only available after the server connects.
+// Instead, every catalog-dependent handler (`list_pipelines`,
+// `get_pipeline_recipe`) and the orchestrator-deps builders await it first, so
+// they all observe the same final merged objects.
 // ---------------------------------------------------------------------------
 // Pipeline Recipe Tools
 // ---------------------------------------------------------------------------
 registerTool("get_docs_dir", {
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: "Return the locally configured docs directory path (BAPI_DOCS_DIR, default docs/tmp). " +
         "No parameters. Use this instead of reading the BAPI_DOCS_DIR environment variable directly, " +
         "which requires shell access and may be blocked on some AI coding platforms.",
     inputSchema: {},
 }, async () => {
-    return { content: [{ type: "text", text: BAPI_DOCS_DIR }] };
+    return { content: [{ type: "text", text: await getDocsDir() }] };
 });
 registerTool("list_pipelines", {
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: "List all available pipeline recipes with their names, descriptions, and required variables. " +
         "No parameters. Use this to discover available pipelines before calling get_pipeline_recipe.",
     inputSchema: {},
 }, async () => {
+    await ensureCustomPipelinesLoaded();
     const list = Object.entries(PIPELINES).map(([key, pipeline]) => ({
         name: key,
         description: pipeline.description ?? "",
@@ -2827,6 +3814,12 @@ registerTool("list_pipelines", {
     };
 });
 registerTool("get_pipeline_recipe", {
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: "Retrieve a fully resolved pipeline recipe by name. Substitutes variables, resolves instruction " +
         "file references to inline content, and returns an ordered array of executable steps. " +
         "Each step is either an mcp_call (with tool name and params) or an agent_task (with instruction text). " +
@@ -2854,6 +3847,7 @@ registerTool("get_pipeline_recipe", {
             "not via the variables map."),
     },
 }, async ({ pipeline: pipelineName, variables, skip_steps, auto_approve }) => {
+    await ensureCustomPipelinesLoaded();
     const pipelineDef = PIPELINES[pipelineName];
     if (!pipelineDef) {
         const available = Object.keys(PIPELINES).join(", ");
@@ -2882,7 +3876,7 @@ registerTool("get_pipeline_recipe", {
     }
     try {
         const mergedVariables = {
-            docs_dir: BAPI_DOCS_DIR,
+            docs_dir: await getDocsDir(),
             provider: "",
             second_opinion: "",
             auto_approve: auto_approve ? "true" : "",
@@ -2925,21 +3919,13 @@ registerTool("get_pipeline_recipe", {
 // REPO_MISMATCH | TOOL_ERROR). Pipeline state is persisted server-side; the
 // idle TTL defaults to 24 hours and is auto-extended on every state
 // transition.
-function buildPipelineCatalogDescription() {
-    const lines = [];
-    for (const [key, pipeline] of Object.entries(PIPELINES)) {
-        const source = userPipelineKeys.has(key) ? " (user)" : "";
-        const desc = pipeline.description ?? "";
-        lines.push(`- ${key}${source} — ${desc}`);
-    }
-    return lines.join("\n");
-}
-function buildPipelineOrchestratorDeps() {
+async function buildPipelineOrchestratorDeps() {
+    await ensureCustomPipelinesLoaded();
     return {
         baseUrl: BASE_URL,
-        apiKey: API_KEY,
+        apiKey: await getResolvedApiKey(),
         repoName: REPO_NAME,
-        docsDir: BAPI_DOCS_DIR,
+        docsDir: await getDocsDir(),
         pipelines: PIPELINES,
         instructions: INSTRUCTIONS,
         toolHandlers: TOOL_HANDLERS,
@@ -2948,12 +3934,13 @@ function buildPipelineOrchestratorDeps() {
 // BAPI-326: dependency injection for the full-automation chain orchestrator.
 // Same shape as the pipeline deps plus the bundled chain-recipe registry. The
 // chain orchestrator never imports index.ts; everything flows through here.
-function buildChainOrchestratorDeps() {
+async function buildChainOrchestratorDeps() {
+    await ensureCustomPipelinesLoaded();
     return {
         baseUrl: BASE_URL,
-        apiKey: API_KEY,
+        apiKey: await getResolvedApiKey(),
         repoName: REPO_NAME,
-        docsDir: BAPI_DOCS_DIR,
+        docsDir: await getDocsDir(),
         pipelines: PIPELINES,
         chainRecipes: CHAIN_RECIPES,
         instructions: INSTRUCTIONS,
@@ -2961,6 +3948,12 @@ function buildChainOrchestratorDeps() {
     };
 }
 registerTool("run_pipeline", {
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
     description: "Execute a Bridge API pipeline by name. The orchestrator runs steps sequentially, " +
         "dispatching mcp_call steps in-process and pausing on agent_task steps with a " +
         "needs_agent_task envelope. Returns a unified envelope keyed on `status`: " +
@@ -2970,8 +3963,8 @@ registerTool("run_pipeline", {
         "VALIDATION | NOT_FOUND | EXPIRED | REPO_MISMATCH | TOOL_ERROR). " +
         "Paused runs auto-expire after an idle TTL (default 24 hours; override with " +
         "`ttl_seconds`). The TTL is reset on every state transition.\n\n" +
-        "Available pipelines:\n" +
-        buildPipelineCatalogDescription(),
+        "Call list_pipelines for the current resolved catalog of available pipeline " +
+        "names (bundled plus any custom user pipelines).",
     inputSchema: {
         pipeline: z
             .string()
@@ -2996,7 +3989,7 @@ registerTool("run_pipeline", {
             .describe("Override the default 24-hour idle TTL for this run. Must be a positive integer."),
     },
 }, async (input) => {
-    const result = await runPipeline(buildPipelineOrchestratorDeps(), input);
+    const result = await runPipeline(await buildPipelineOrchestratorDeps(), input);
     return {
         content: [
             { type: "text", text: JSON.stringify(result, null, 2) },
@@ -3004,6 +3997,12 @@ registerTool("run_pipeline", {
     };
 });
 registerTool("resume_pipeline", {
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
     description: "Resume a paused pipeline run with the result of the agent_task. Provide the " +
         "`pipeline_run_id` returned by the prior needs_agent_task envelope, and the string " +
         "the instruction's `## Return` section asked you to produce as `agent_result`. " +
@@ -3019,7 +4018,7 @@ registerTool("resume_pipeline", {
             .describe("The string the paused instruction's ## Return section asked you to produce"),
     },
 }, async (input) => {
-    const result = await resumePipeline(buildPipelineOrchestratorDeps(), input);
+    const result = await resumePipeline(await buildPipelineOrchestratorDeps(), input);
     return {
         content: [
             { type: "text", text: JSON.stringify(result, null, 2) },
@@ -3027,6 +4026,12 @@ registerTool("resume_pipeline", {
     };
 });
 registerTool("list_pipeline_runs", {
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
     description: "List recent pipeline runs for the configured repository, newest first. Returns " +
         "metadata only — `resolved_recipe`, resolved params, instruction text, results, " +
         "and agent outputs are intentionally excluded. Use this to recover a " +
@@ -3040,7 +4045,7 @@ registerTool("list_pipeline_runs", {
             .describe("Optional status filter"),
     },
 }, async (input) => {
-    const result = await listPipelineRuns(buildPipelineOrchestratorDeps(), input);
+    const result = await listPipelineRuns(await buildPipelineOrchestratorDeps(), input);
     return {
         content: [
             { type: "text", text: JSON.stringify(result, null, 2) },
@@ -3048,6 +4053,12 @@ registerTool("list_pipeline_runs", {
     };
 });
 registerTool("delete_pipeline_run", {
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
     description: "Delete a pipeline run row (any status). Use this to discard orphaned `running` " +
         "rows from a previous session that can't be resumed (resume_pipeline only accepts " +
         "`paused`), to clean up after a failed run, or to remove a no-longer-needed paused " +
@@ -3061,7 +4072,7 @@ registerTool("delete_pipeline_run", {
             .describe("UUID of the pipeline run to delete."),
     },
 }, async (input) => {
-    const result = await deletePipelineRun(buildPipelineOrchestratorDeps(), input);
+    const result = await deletePipelineRun(await buildPipelineOrchestratorDeps(), input);
     return {
         content: [
             { type: "text", text: JSON.stringify(result, null, 2) },
@@ -3081,6 +4092,12 @@ registerTool("delete_pipeline_run", {
 // TOOL_HANDLERS and the pipeline tools so the orchestrator can dispatch the
 // existing child pipelines in-process.
 registerTool("run_full_automation", {
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
     description: "Run the full-automation chain for an idea: create ticket(s) " +
         "(idea-to-ticket), review each created ticket (review-ticket fan-out), " +
         "then emit the exact `/start-tickets ...` command for you to invoke in " +
@@ -3120,7 +4137,7 @@ registerTool("run_full_automation", {
     if (!resolved.ok) {
         return resolved.errorResponse;
     }
-    const result = await runFullAutomation(buildChainOrchestratorDeps(), {
+    const result = await runFullAutomation(await buildChainOrchestratorDeps(), {
         idea: resolved.text,
         ...rest,
     });
@@ -3131,6 +4148,12 @@ registerTool("run_full_automation", {
     };
 });
 registerTool("resume_full_automation", {
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
     description: "Resume a paused full-automation chain run. Provide the `chain_run_id` " +
         "returned by the prior needs_agent_task envelope and the string the " +
         "instruction asked you to produce as `agent_result`. Returns the same " +
@@ -3140,7 +4163,7 @@ registerTool("resume_full_automation", {
         agent_result: z.string(),
     },
 }, async (input) => {
-    const result = await resumeFullAutomation(buildChainOrchestratorDeps(), input);
+    const result = await resumeFullAutomation(await buildChainOrchestratorDeps(), input);
     return {
         content: [
             { type: "text", text: JSON.stringify(result, null, 2) },
@@ -3150,12 +4173,125 @@ registerTool("resume_full_automation", {
 // ---------------------------------------------------------------------------
 // generate_decision_page
 // ---------------------------------------------------------------------------
+/**
+ * Detect URL-encoded path tokens that could smuggle traversal/separators past
+ * literal-character checks: `%2e` (dot), `%2f` (slash), and `%5c` (backslash),
+ * all case-insensitive. Defense-in-depth alongside the literal-character rules.
+ */
+export function containsUnsafeEncodedPathToken(value) {
+    return /%2e/i.test(value) || /%2f/i.test(value) || /%5c/i.test(value);
+}
+/**
+ * True when `value` is absolute on POSIX OR Windows semantics, regardless of the
+ * host OS. Node's `path.isAbsolute` is platform-specific, so a Windows drive
+ * (`C:\`) or UNC (`\\server\share`) path would not be caught on a POSIX host
+ * without checking `path.win32.isAbsolute` explicitly.
+ */
+export function isPlatformAbsolutePath(value) {
+    return (path.posix.isAbsolute(value) ||
+        path.win32.isAbsolute(value) ||
+        path.isAbsolute(value));
+}
+/**
+ * Validate the docs-relative `output_subdir`. Returns a user-facing error
+ * message string when invalid, or `null` when valid. Never sanitizes/auto-fixes.
+ */
+export function validateDecisionPageOutputSubdir(value) {
+    if (value.trim().length === 0) {
+        return `Invalid output_subdir: must not be empty or whitespace-only.`;
+    }
+    if (value.includes("\0")) {
+        return `Invalid output_subdir: must not contain null bytes.`;
+    }
+    if (containsUnsafeEncodedPathToken(value)) {
+        return `Invalid output_subdir "${value}": must not contain encoded path tokens (%2e, %2f, %5c).`;
+    }
+    if (isPlatformAbsolutePath(value)) {
+        return `Invalid output_subdir "${value}": must be a relative path, not an absolute path.`;
+    }
+    if (value.includes("\\")) {
+        return `Invalid output_subdir "${value}": backslashes are not allowed; use "/" to separate nested directories.`;
+    }
+    // Split on both separators so a "\\"-bearing value (already rejected above) and
+    // "/"-separated nesting are both checked segment-by-segment for "..".
+    const segments = value.split(/[/\\]/);
+    if (segments.some((segment) => segment === "..")) {
+        return `Invalid output_subdir "${value}": must not contain ".." path segments.`;
+    }
+    return null;
+}
+/**
+ * Validate the `output_filename`. Returns a user-facing error message string
+ * when invalid, or `null` when valid. Requires a literal `.html` suffix and
+ * never auto-appends it.
+ */
+export function validateDecisionPageOutputFilename(value) {
+    if (value.trim().length === 0) {
+        return `Invalid output_filename: must not be empty or whitespace-only.`;
+    }
+    if (value.includes("\0")) {
+        return `Invalid output_filename: must not contain null bytes.`;
+    }
+    if (containsUnsafeEncodedPathToken(value)) {
+        return `Invalid output_filename "${value}": must not contain encoded path tokens (%2e, %2f, %5c).`;
+    }
+    if (value.includes("/") || value.includes("\\")) {
+        return `Invalid output_filename "${value}": must not contain path separators.`;
+    }
+    if (value === "." || value === "..") {
+        return `Invalid output_filename "${value}": must be a real filename, not "." or "..".`;
+    }
+    if (!value.endsWith(".html")) {
+        return `Invalid output_filename "${value}": must end with the ".html" suffix.`;
+    }
+    return null;
+}
+/**
+ * Validate and resolve the decision-page output target under the docs base.
+ * Runs string validators first (so an invalid subdir short-circuits before any
+ * docs-dir resolution), then resolves an absolute target and enforces a
+ * containment backstop that the target stays strictly under the docs base.
+ */
+export async function resolveDecisionPageOutputTarget(outputSubdir, outputFilename) {
+    const subdirError = validateDecisionPageOutputSubdir(outputSubdir);
+    if (subdirError)
+        return { ok: false, message: subdirError };
+    const filenameError = validateDecisionPageOutputFilename(outputFilename);
+    if (filenameError)
+        return { ok: false, message: filenameError };
+    // getDocsDir() is async — must be awaited before path.resolve, otherwise the
+    // Promise would be string-coerced into a bogus path.
+    const docsBase = path.resolve(await getDocsDir());
+    const resolvedTarget = path.resolve(docsBase, outputSubdir, outputFilename);
+    // Containment backstop using normalized resolved paths. The strict
+    // `docsBase + path.sep` boundary prevents a sibling-prefix bypass such as
+    // "/tmp/docs-evil" passing a naive startsWith("/tmp/docs") check.
+    if (!resolvedTarget.startsWith(docsBase + path.sep)) {
+        return {
+            ok: false,
+            message: `Invalid output target: the resolved output path must stay under the docs directory.`,
+        };
+    }
+    return {
+        ok: true,
+        docsPath: path.dirname(resolvedTarget),
+        filePath: resolvedTarget,
+    };
+}
 registerTool("generate_decision_page", {
-    description: "Generate a local HTML decision page for capturing user decisions on ticket review findings. " +
-        "Renders recommendation-driven review decisions sourced from the combined review-and-resolution " +
-        "document, with per-option consequence lines, a closed-by-default codebase-evidence disclosure, " +
-        "and confirmed improvements. The user opens the HTML file in a browser, makes selections, and " +
-        "copies the resulting JSON output back to the agent.",
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    description: "Generate a local, reusable, review-shaped HTML decision page for capturing user decisions. " +
+        "Renders recommendation-driven decision cards with per-option consequence lines, optional " +
+        "original-question and closed-by-default codebase-evidence display, and an optional confirmed-" +
+        "improvements list. Presentation labels (title, intro, section/improvements headings) are " +
+        "overridable, and the output location under the docs directory is configurable, so automations " +
+        "beyond ticket review can reuse it. The user opens the HTML file in a browser, makes selections, " +
+        "and copies the resulting JSON output back to the agent.",
     inputSchema: DecisionPageInputShape,
 }, async (input) => {
     // Returned messages travel through JSON.stringify in the MCP envelope below,
@@ -3205,9 +4341,19 @@ registerTool("generate_decision_page", {
         }
         seenCiIds.add(ci.id);
     }
+    // Resolve the (optionally caller-overridden) output location. Defaults
+    // reproduce the legacy review path: {docs_dir}/review/{ticket_key}-decisions.html.
+    // Runs after semantic item validation and before any asset read or file write.
+    const outputSubdir = input.output_subdir ?? "review";
+    const outputFilename = input.output_filename ?? `${input.ticket_key}-decisions.html`;
+    const outputTarget = await resolveDecisionPageOutputTarget(outputSubdir, outputFilename);
+    if (!outputTarget.ok) {
+        return validationError(outputTarget.message);
+    }
     // Read design assets and base64-encode for embedding
-    const assetsDir = path.join(PROJECT_ROOT, "design-assets");
-    const fontsDir = path.join(PROJECT_ROOT, "public", "fonts");
+    const projectRootForAssets = await getProjectRoot();
+    const assetsDir = path.join(projectRootForAssets, "design-assets");
+    const fontsDir = path.join(projectRootForAssets, "public", "fonts");
     let faviconBase64 = "";
     let logoBase64 = "";
     try {
@@ -3220,15 +4366,16 @@ registerTool("generate_decision_page", {
         logoBase64 = logoBuf.toString("base64");
     }
     catch { /* logo optional */ }
-    // Compute relative path from output dir to fonts dir
-    const docsPath = getDocsPath("review");
+    // Use the validated output target. fontsRelPath stays relative to the actual
+    // output directory so font URLs resolve regardless of a custom subdir.
+    const docsPath = outputTarget.docsPath;
+    const filePath = outputTarget.filePath;
     const fontsRelPath = path.relative(docsPath, fontsDir);
     const html = generateDecisionPageHtml(input, {
         faviconBase64,
         logoBase64,
         fontsRelPath,
     });
-    const filePath = path.join(docsPath, `${input.ticket_key}-decisions.html`);
     await mkdir(docsPath, { recursive: true });
     await writeFile(filePath, html, "utf-8");
     return {
@@ -3248,6 +4395,9 @@ registerTool("generate_decision_page", {
 // ---------------------------------------------------------------------------
 const transport = new StdioServerTransport();
 await server.connect(transport);
+// Record that the server has connected so project-root resolution may now query
+// MCP `roots/list` (it falls through to CLAUDE_PROJECT_DIR / cwd before this).
+serverConnected = true;
 console.error("Bridge API MCP server running on stdio");
 // Fire-and-forget update check — delay to let MCP client attach listeners
 (async () => {