@bridge_gpt/mcp-server 0.2.0 → 0.2.2

package/build/index.js

@@ -22,6 +22,7 @@ import { PIPELINES as BUNDLED_PIPELINES, INSTRUCTIONS as BUNDLED_INSTRUCTIONS, C
 import { COMMANDS } from "./commands.generated.js";
 import { AGENTS } from "./agents.generated.js";
 import { VERSION } from "./version.generated.js";
+import { README } from "./readme.generated.js";
 import { checkForUpdate } from "./update-check.js";
 import { reconstructAgentMarkdown, translateAgentToCopilot } from "./agent-utils.js";
 import { resolveRecipe, loadCustomPipelines } from "./pipeline-utils.js";
@@ -87,11 +88,18 @@ async function getResolvedApiKey() {
 }
 /** GET auth headers, with the API key resolved once via {@link getResolvedApiKey}. */
 async function getGetHeaders() {
-    return { "X-API-Key": await getResolvedApiKey() };
+    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" };
+    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;
@@ -313,8 +321,8 @@ async function saveLocally(dir, filename, content) {
 // Heavy-read truncate-and-save helpers (BAPI-342)
 // ---------------------------------------------------------------------------
 //
-// Four heavy read tools (get_tickets, get_ticket, get_comments,
-// list_attachments) can return very large JSON payloads. To avoid flooding the
+// 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
@@ -502,6 +510,18 @@ const TICKET_ARTIFACTS = {
             `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`,
@@ -576,6 +596,8 @@ async function getTicketArtifactDocsPath(subdir) {
             return getDocsPath("plans");
         case "architecture":
             return getDocsPath("architecture");
+        case "fsd":
+            return getDocsPath("fsd");
         case "clarifying-questions":
             return getDocsPath("clarifying-questions");
         case "ticket-critiques":
@@ -584,6 +606,14 @@ async function getTicketArtifactDocsPath(subdir) {
             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.
@@ -1306,6 +1336,28 @@ const server = new McpServer({
     version: "1.0.0",
 });
 // ---------------------------------------------------------------------------
+// README resource
+// ---------------------------------------------------------------------------
+//
+// Expose the package README as a readable MCP resource so a connected agent can
+// discover the server's feature set without leaving the session. Without this,
+// `listMcpResources` returns nothing and the README is only visible on npm. The
+// markdown is bundled at build time (scripts/bundle-readme.js → readme.generated)
+// so there is no runtime file read.
+server.registerResource("readme", "bridge-api://readme", {
+    title: "Bridge API MCP — README",
+    description: "Overview and feature reference for the Bridge API MCP server (the same README published with the npm package).",
+    mimeType: "text/markdown",
+}, async (uri) => ({
+    contents: [
+        {
+            uri: uri.href,
+            mimeType: "text/markdown",
+            text: README,
+        },
+    ],
+}));
+// ---------------------------------------------------------------------------
 // Tool registration wrapper (BAPI-275)
 // ---------------------------------------------------------------------------
 //
@@ -1366,15 +1418,6 @@ const registerTool = ((name, config, handler) => {
     }
     return toolHandle;
 });
-// ---------------------------------------------------------------------------
-// Tools
-// ---------------------------------------------------------------------------
-// SECURITY: The `annotations` objects below (readOnlyHint, destructiveHint,
-// idempotentHint, openWorldHint) are UNTRUSTED UX / model-routing hints only.
-// They are advisory metadata forwarded verbatim to the MCP client and MUST
-// NEVER be used for authorization, permission checks, access control, tool
-// enable/disable decisions, or any other security decision. Authorization is
-// enforced server-side via the API key + repo access checks, never here.
 registerTool("ping", {
     annotations: {
         readOnlyHint: true,
@@ -1384,6 +1427,9 @@ registerTool("ping", {
     },
     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.",
@@ -1391,8 +1437,28 @@ registerTool("ping", {
 }, async () => {
     const url = buildGetUrl("/ping", { repo_name: REPO_NAME });
     const resp = await fetch(url, { headers: await getGetHeaders() });
-    const text = await handleResponse(resp);
-    return { content: [{ type: "text", text }] };
+    // 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", {
     annotations: {
@@ -1448,6 +1514,7 @@ registerTool("generate_image", {
         "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
@@ -1470,14 +1537,12 @@ registerTool("generate_image", {
             .optional()
             .default("1024x1024")
             .describe("Image dimensions. Defaults to '1024x1024'."),
-        save_locally: z
-            .boolean()
-            .optional()
-            .default(false)
-            .describe("When true, save the generated image to the local docs/images directory."),
     },
-}, async ({ prompt, provider, quality, size, save_locally }) => {
-    const resp = await fetch(buildApiUrl("/llm/generate-image"), {
+}, async ({ prompt, provider, quality, size }) => {
+    // The backend is async (submit -> poll -> result) so a slow generation no
+    // longer exceeds the server's 30s request timeout. This tool absorbs the
+    // polling so the agent still gets the image back in a single call.
+    const submitResp = await fetch(buildApiUrl("/llm/generate-image"), {
         method: "POST",
         headers: await getPostHeaders(),
         body: JSON.stringify({
@@ -1488,11 +1553,71 @@ registerTool("generate_image", {
             size,
         }),
     });
-    if (!resp.ok) {
-        const text = await handleResponse(resp);
+    if (!submitResp.ok) {
+        const text = await handleResponse(submitResp);
+        return { content: [{ type: "text", text }] };
+    }
+    const submitBody = (await submitResp.json());
+    const requestId = submitBody.request_id;
+    if (typeof requestId !== "number") {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ error: "Image generation submit response is missing request_id", status: 500 }),
+                },
+            ],
+        };
+    }
+    const repoQuery = `repo_name=${encodeURIComponent(REPO_NAME)}`;
+    const statusUrl = buildApiUrl(`/llm/generate-image/${requestId}/status?${repoQuery}`);
+    const resultUrl = buildApiUrl(`/llm/generate-image/${requestId}/result?${repoQuery}`);
+    // Poll /status until terminal. Low quality is ~13s, but high quality can run
+    // 2-4+ min; start snappy at 2s, back off to 5s after 20s, cap at 300s. The
+    // server-side janitor fails truly-stuck rows only after 15 min, so this cap
+    // always returns the recoverable message well before a live row is touched.
+    const startTime = Date.now();
+    const timeoutMs = 300_000;
+    let pollIntervalMs = 2_000;
+    let finalStatus = "";
+    while (true) {
+        await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+        if (Date.now() - startTime >= timeoutMs) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Image generation is still processing after ${Math.round(timeoutMs / 1000)}s (request_id=${requestId}). The result is recoverable from the server via GET /llm/generate-image/${requestId}/result once it finishes.`,
+                    },
+                ],
+            };
+        }
+        if (Date.now() - startTime > 20_000) {
+            pollIntervalMs = 5_000;
+        }
+        const statusResp = await fetch(statusUrl, { headers: await getGetHeaders() });
+        if (!statusResp.ok) {
+            const text = await handleResponse(statusResp);
+            return { content: [{ type: "text", text }] };
+        }
+        const statusBody = (await statusResp.json());
+        finalStatus = typeof statusBody.status === "string" ? statusBody.status : "";
+        if (finalStatus === "completed" || finalStatus === "failed") {
+            break;
+        }
+    }
+    if (finalStatus === "failed") {
+        // /result returns the sanitized 409 failure detail.
+        const failResp = await fetch(resultUrl, { headers: await getGetHeaders() });
+        const text = await handleResponse(failResp);
         return { content: [{ type: "text", text }] };
     }
-    const body = (await resp.json());
+    const resultResp = await fetch(resultUrl, { headers: await getGetHeaders() });
+    if (!resultResp.ok) {
+        const text = await handleResponse(resultResp);
+        return { content: [{ type: "text", text }] };
+    }
+    const body = (await resultResp.json());
     const imageBase64 = body.image_base64;
     if (typeof imageBase64 !== "string" || imageBase64.length === 0) {
         return {
@@ -1510,21 +1635,21 @@ registerTool("generate_image", {
     const content = [
         { type: "image", data: imageBase64, mimeType },
     ];
-    if (save_locally) {
-        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)}`,
-            });
-        }
+    // 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 };
 });
@@ -1538,12 +1663,19 @@ registerTool("get_project_standards", {
     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: await getGetHeaders() });
-    const text = await handleResponse(resp);
+    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", {
@@ -1647,6 +1779,29 @@ registerTool("get_ticket", {
     }
     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,
@@ -2000,7 +2155,7 @@ registerTool("upload_attachment", {
         "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()
@@ -2283,6 +2438,87 @@ registerTool("request_architecture", {
 }, 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", {
     annotations: {
         readOnlyHint: false,
@@ -2705,6 +2941,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",
@@ -2714,7 +2951,16 @@ const VALID_CONFIG_FIELDS = [
     "allow_mutating_smoke_ops",
     "selected_mcp_slugs",
     "base_branch",
-    "tiered_execution",
+    "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: {
@@ -2761,7 +3007,8 @@ registerTool("get_config_field", {
     },
     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}`),
     },
@@ -2781,19 +3028,30 @@ registerTool("update_config_field", {
     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'. " +
-            "The tiered_execution field is a string enum with valid values 'off', 'claude_code_only', and " +
-            "'all_capable'; omitting/clearing the value resolves to the backend default 'claude_code_only'. " +
             "For string fields, omit both value and file_path to set the field to NULL (clearing it). " +
             "Scalar boolean fields are NOT NULL and have no clear/null state: omitting the value writes false " +
             "(matching the API-layer coercion), so pass true/false explicitly."),
@@ -2801,8 +3059,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.
@@ -2825,14 +3092,39 @@ registerTool("update_config_field", {
         const resp = await fetch(buildUrl(`/config-field/${encodeURIComponent(field_name)}`), {
             method: "PUT",
             headers: await getPostHeaders(),
-            body: JSON.stringify({ repo_name: REPO_NAME, value: arrayValue }),
+            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 {
@@ -2874,7 +3166,7 @@ registerTool("update_config_field", {
         const resp = await fetch(buildUrl(`/config-field/${encodeURIComponent(field_name)}`), {
             method: "PUT",
             headers: await getPostHeaders(),
-            body: JSON.stringify({ repo_name: REPO_NAME, value: boolValue }),
+            body: JSON.stringify(withGuard(boolValue)),
         });
         const text = await handleResponse(resp);
         return { content: [{ type: "text", text }] };
@@ -2892,11 +3184,71 @@ registerTool("update_config_field", {
     const resp = await fetch(buildUrl(`/config-field/${encodeURIComponent(field_name)}`), {
         method: "PUT",
         headers: await getPostHeaders(),
-        body: JSON.stringify({ repo_name: REPO_NAME, value: finalValue }),
+        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 "";
@@ -4125,72 +4477,6 @@ registerTool("generate_decision_page", {
     };
 });
 // ---------------------------------------------------------------------------
-// Tiered section-executor telemetry (BAPI-346, Ticket 2)
-// ---------------------------------------------------------------------------
-/**
- * POST one per-section execution-telemetry row through the Bridge API HTTP
- * boundary (`/jira/tiered-section-metrics`). Keeps the MCP layer free of any
- * Python DAL import — the server route owns the dormant BAPI-345 DAL seam.
- */
-async function recordTieredSectionMetric(args) {
-    const payload = {
-        repo_name: REPO_NAME,
-        ticket_number: args.ticket_number,
-        section_id: args.section_id,
-        tier_assigned: args.tier_assigned,
-        mode_run: args.mode_run,
-        metrics: args.metrics ?? {},
-    };
-    const resp = await fetch(buildUrl("/tiered-section-metrics"), {
-        method: "POST",
-        headers: await getPostHeaders(),
-        body: JSON.stringify(payload),
-    });
-    const text = await handleResponse(resp);
-    return { content: [{ type: "text", text }] };
-}
-registerTool("record_tiered_section_metric", {
-    annotations: {
-        readOnlyHint: false,
-        destructiveHint: false,
-        idempotentHint: false,
-        openWorldHint: true,
-    },
-    description: "Record one per-section execution-telemetry row for the Claude Code tiered " +
-        "section executor (BAPI-346). This writes server-side telemetry state only — " +
-        "it does NOT mutate Jira, code, or any ticket. It is intended to be called by " +
-        "the tiered section executor after each section attempt; the executor Warns and " +
-        "continues if recording fails, so telemetry never blocks an implementation. " +
-        "Typed columns are ticket_number, section_id, tier_assigned, and mode_run; put " +
-        "any additional per-section detail in the flexible `metrics` object.",
-    inputSchema: {
-        ticket_number: z
-            .string()
-            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123, BAPI-42)"),
-        section_id: z
-            .string()
-            .describe("The BAPI-345 section graph `id` of the section this metric is for."),
-        tier_assigned: z
-            .enum(["cheap", "basic", "premium"])
-            .describe("The tier resolved for the section (cheap→haiku, basic→sonnet, premium→opus)."),
-        mode_run: z
-            .enum(["sub_agent", "inline_tiered", "inline_default"])
-            .describe("The execution mode the section actually ran in."),
-        metrics: z
-            .record(z.string(), z.unknown())
-            .optional()
-            .describe("Optional flexible JSON detail (e.g. contract_version, mode_intended, " +
-            "model_resolved, tokens, cache, verification, escalation_count, " +
-            "budget_snapshot, files_changed, handoff, degraded_reason)."),
-    },
-}, async ({ ticket_number, section_id, tier_assigned, mode_run, metrics }) => recordTieredSectionMetric({
-    ticket_number,
-    section_id,
-    tier_assigned,
-    mode_run,
-    metrics,
-}));
-// ---------------------------------------------------------------------------
 // Entry point
 // ---------------------------------------------------------------------------
 const transport = new StdioServerTransport();