codecartographer-pi 0.16.0 → 0.17.0

package/dist/extensions/codecarto/index.js

@@ -1,4 +1,4 @@
-import { cp, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import { autoCompletePhase, buildAutoSummary, isPhaseRunning, runAuto, runSinglePhase } from "./auto-runner.js";
@@ -6,12 +6,16 @@ import { disposeAgentsWidget } from "./agent-widget.js";
 import { parseDashboardFlags } from "./dashboard-flags.js";
 import { narrateDashboard } from "./dashboard-narrator.js";
 import { writeDashboard } from "./dashboard-writer.js";
+import { parseBroadsideFlags, KNOWN_BROADSIDE_TOKENS } from "./broadside-flags.js";
 import { parseNextFlags } from "./next-flags.js";
 import { phaseCompactionExtension } from "./phase-compaction.js";
-import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, describeScaffoldStaleness, deriveSlug, discoverLibrary, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPathResolved, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, packagedWorkspaceDir, pathExists, PACKAGE_VERSION, PhasePreflightError, PIPELINE_ALIASES, publishEntry, resolvePhase, resolvePipelineChoice, runPhasePreflight, seedOrchestratorFiles, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, } from "../../core/index.js";
+import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, copyPackagedWorkspace, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, describeScaffoldStaleness, deriveSlug, discoverLibrary, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPathResolved, BROADSIDE_LENS_IDS, BROADSIDE_SKILL_NAME, BroadsideCancelledError, broadsideDirFor, collectResultText, estimateSubmitText, getLens, listBatchModels, listSkillNames, loadBroadsideConfig, modelsText, runBroadsideCollect, runBroadsideStatus, runBroadsideSubmit, statusText, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, packagedWorkspaceDir, pathExists, PACKAGE_VERSION, readBroadsideSkill, PhasePreflightError, PIPELINE_ALIASES, publishEntry, resolvePhase, resolvePipelineChoice, runPhasePreflight, seedOrchestratorFiles, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, } from "../../core/index.js";
 import { initLibrary } from "../../core/library.js";
 import { resolveUserConfigPath } from "../../core/orchestrator-config.js";
 const STATUS_WIDGET_ID = "codecarto-widget";
+// Broad-Side gets its own widget id: a scout run is legal on a repository with
+// no workspace, where the phase widget has nothing to render.
+const BROADSIDE_WIDGET_ID = "codecarto-broadside";
 const STATUS_LINE_ID = "codecarto-status";
 const SAFE_TOOL_NAMES = ["read", "grep", "find", "ls", "edit", "write"];
 function derivePublishHeadline(spec, cwd) {
@@ -92,6 +96,47 @@ function setUiState(ctx, state, extraLines = []) {
     ctx.ui.setStatus(STATUS_LINE_ID, `${theme.fg("accent", "CC")} ${theme.fg("dim", currentPhase)}`);
     ctx.ui.setWidget(STATUS_WIDGET_ID, buildStatusLines(state, extraLines));
 }
+/**
+ * Resolve the OpenRouter key for a Broad-Side run. Deliberately no slash-command
+ * parameter: a key typed as a command argument lands in the session transcript.
+ */
+function resolveBroadsideKey(configuredKey) {
+    const fromEnv = process.env.OPENROUTER_API_KEY?.trim();
+    if (fromEnv)
+        return fromEnv;
+    return configuredKey.trim() || null;
+}
+/** The spend decision, rendered for a human about to approve it. */
+function describeBroadsideEstimate(estimate) {
+    const lines = [
+        `Model: ${estimate.model}${estimate.mixedModels ? " (some lenses overridden — see below)" : ""} (pricing: ${estimate.pricing.source})`,
+        `Rates: $${estimate.pricing.inputPerM.toFixed(4)}/M in · $${estimate.pricing.outputPerM.toFixed(4)}/M out`,
+        "",
+        "Per lens:",
+        ...estimate.lenses.map(({ name, slices, cost, model }) => {
+            // Naming the model only when it differs keeps the common case quiet
+            // and makes a mixed-model run impossible to approve without noticing.
+            const override = estimate.mixedModels && model !== estimate.model ? ` on ${model}` : "";
+            return `  ${name}: ${slices} slice${slices === 1 ? "" : "s"} — ~$${cost.toFixed(4)}${override}`;
+        }),
+        "",
+        `Estimated total: ~$${estimate.totalCost.toFixed(4)} ` +
+            `(~${Math.round(estimate.inputTokens / 1000)}k in, ~${Math.round(estimate.outputTokens / 1000)}k out)`,
+    ];
+    if (estimate.maxCost > 0) {
+        lines.push(estimate.exceedsLimit
+            ? `This EXCEEDS the configured max_cost of $${estimate.maxCost.toFixed(2)}. Approving here overrides it for this run.`
+            : `Within the configured max_cost of $${estimate.maxCost.toFixed(2)}.`);
+    }
+    if (estimate.baseHead) {
+        lines.push(`Incremental: only modules changed since ${estimate.baseHead.slice(0, 8)} are included.`);
+    }
+    else if (estimate.sourceDirty) {
+        lines.push("Incremental was requested but the tree is dirty — this is a full scan.");
+    }
+    lines.push("", "The estimate is a pre-flight prediction from file sizes; OpenRouter bills actual usage.");
+    return lines.join("\n");
+}
 export default function codeCartographerExtension(pi) {
     phaseCompactionExtension(pi);
     let lastFeedbackLines = [];
@@ -268,7 +313,7 @@ export default function codeCartographerExtension(pi) {
             }
             if (!(await pathExists(targetWorkspaceDir))) {
                 await mkdir(ctx.cwd, { recursive: true });
-                await cp(sourceWorkspaceDir, targetWorkspaceDir, { recursive: true });
+                await copyPackagedWorkspace(targetWorkspaceDir);
             }
             const rawStatusPath = join(targetWorkspaceDir, "workflow", "status.yaml");
             const rawStatus = (await loadYamlFile(rawStatusPath)) ?? {};
@@ -597,6 +642,30 @@ export default function codeCartographerExtension(pi) {
                 ctx.ui.notify(`Usage: /codecarto-skill <name>${hint}`, "warning");
                 return;
             }
+            // Broad-Side is a reading guide for batch reconnaissance output, not a
+            // post-pipeline skill: it is read before or during the pipeline and works
+            // on a repository with scout state and no workspace. Same exemption the
+            // MCP surface makes in handleSkill.
+            if (skillName === BROADSIDE_SKILL_NAME) {
+                const skill = await readBroadsideSkill(ctx.cwd).catch(() => null);
+                if (!skill) {
+                    ctx.ui.notify("Broad-Side reading guide not found. Reinstall codecartographer-pi.", "error");
+                    return;
+                }
+                const message = [
+                    "Read the Broad-Side reading guide below and apply it to the batch reconnaissance results in .codecarto/broadside/.",
+                    "",
+                    skill.content,
+                ].join("\n");
+                if (ctx.isIdle()) {
+                    pi.sendUserMessage(message);
+                }
+                else {
+                    pi.sendUserMessage(message, { deliverAs: "followUp" });
+                }
+                ctx.ui.notify("Queued the Broad-Side reading guide", "info");
+                return;
+            }
             const state = await ensureWorkspaceState(ctx);
             if (!state)
                 return;
@@ -609,7 +678,7 @@ export default function codeCartographerExtension(pi) {
             if (!(await pathExists(skillFile))) {
                 const available = await listSkillNames(state.workspaceDir);
                 const hint = available.length > 0 ? ` (available: ${available.join(", ")})` : " (no skills installed)";
-                ctx.ui.notify(`Unknown skill: ${skillName}${hint}`, "error");
+                ctx.ui.notify(`Unknown skill: ${skillName}${hint}. The Broad-Side reading guide is served as \`${BROADSIDE_SKILL_NAME}\` and is not pipeline-gated.`, "error");
                 return;
             }
             const prompt = await buildSkillPrompt(state, skillName);
@@ -624,6 +693,165 @@ export default function codeCartographerExtension(pi) {
             ctx.ui.notify(`Queued CodeCartographer skill: ${skillName}`, "info");
         },
     });
+    pi.registerCommand("codecarto-broadside", {
+        description: "Batch reconnaissance (Broad-Side): /codecarto-broadside [submit|collect|status|models] [lenses…] [flags]",
+        getArgumentCompletions: (prefix) => {
+            const items = KNOWN_BROADSIDE_TOKENS
+                .filter((value) => value.startsWith(prefix))
+                .map((value) => ({ value, label: value }));
+            return items.length > 0 ? items : null;
+        },
+        handler: async (args, ctx) => {
+            const flags = parseBroadsideFlags(args);
+            if (flags.unknown.length > 0) {
+                ctx.ui.notify(`Unknown /codecarto-broadside argument: ${flags.unknown.join(" ")}. ` +
+                    `Actions: submit, collect, status, models. Lenses: ${BROADSIDE_LENS_IDS.join(", ")}.`, "error");
+                return;
+            }
+            if (flags.error) {
+                ctx.ui.notify(flags.error, "error");
+                return;
+            }
+            // Broad-Side runs on any git repository, with or without a workspace —
+            // so this command never goes through ensureWorkspaceState.
+            const broadsideDir = broadsideDirFor(ctx.cwd);
+            const config = await loadBroadsideConfig(broadsideDir);
+            const finish = (lines, notice, level = "info") => {
+                lastFeedbackLines = lines;
+                if (codecartoModeActive) {
+                    // A workspace session already has a widget; fold the result into it.
+                    if (ctx.hasUI)
+                        ctx.ui.setWidget(BROADSIDE_WIDGET_ID, undefined);
+                    void refreshWorkspaceUi(ctx, lines);
+                }
+                else if (ctx.hasUI) {
+                    // Scout-only repository: the Broad-Side widget is the only place
+                    // the result can live, so it holds it instead of being cleared.
+                    ctx.ui.setWidget(BROADSIDE_WIDGET_ID, ["Broad-Side", ...lines]);
+                }
+                ctx.ui.notify(notice, level);
+            };
+            if (flags.action === "status") {
+                const { state } = await runBroadsideStatus(ctx.cwd);
+                const runs = state.runs.length;
+                finish(statusText(state).split("\n"), runs > 0 ? `Broad-Side: ${runs} recorded run${runs === 1 ? "" : "s"}` : "Broad-Side: no runs recorded yet");
+                return;
+            }
+            const apiKey = resolveBroadsideKey(config.apiKey);
+            if (!apiKey) {
+                ctx.ui.notify("No OpenRouter API key. Set OPENROUTER_API_KEY in the environment, or add api_key to " +
+                    ".codecarto/broadside/config.yaml. (A slash command takes no key: it would land in the transcript.)", "error");
+                return;
+            }
+            if (flags.action === "models") {
+                ctx.ui.notify("Fetching the OpenRouter batch-model catalog…", "info");
+                try {
+                    const { entries, benchmarks } = await listBatchModels(broadsideDir, config, apiKey, {
+                        includeBenchmarks: flags.benchmarks,
+                    });
+                    finish(modelsText(entries, { benchmarks, defaultModel: config.model }).split("\n"), `Broad-Side: ${entries.length} batch model${entries.length === 1 ? "" : "s"} listed`);
+                }
+                catch (error) {
+                    ctx.ui.notify(`Model catalog lookup failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+                }
+                return;
+            }
+            // Live per-lens progress. Poll callbacks fire often, so they render
+            // into a widget rather than a notification stream.
+            const progress = new Map();
+            const renderProgress = (heading) => {
+                if (!ctx.hasUI)
+                    return;
+                ctx.ui.setWidget(BROADSIDE_WIDGET_ID, [
+                    "Broad-Side",
+                    heading,
+                    ...[...progress.entries()].map(([lensId, line]) => `  ${lensId}: ${line}`),
+                ]);
+            };
+            const onStatus = (lensId, status, counts) => {
+                progress.set(lensId, `${status} (${counts.completed ?? 0}/${counts.total ?? "?"})`);
+                renderProgress("Polling batches…");
+            };
+            const waitSeconds = flags.waitSeconds ?? config.waitSeconds;
+            const waitMs = waitSeconds > 0 ? waitSeconds * 1000 : undefined;
+            const includeSynthesis = flags.includeSynthesis ?? config.includeSynthesis;
+            const includeTriage = flags.includeTriage ?? config.includeTriage;
+            const retryTruncated = flags.retryTruncated ?? config.retryTruncated;
+            if (flags.action === "submit") {
+                const lenses = flags.lenses.length > 0 ? flags.lenses : config.defaultLenses;
+                renderProgress("Slicing the repository and pricing the run…");
+                let submit;
+                try {
+                    submit = await runBroadsideSubmit(ctx.cwd, apiKey, {
+                        lenses,
+                        model: config.model,
+                        maxCost: flags.maxCost ?? config.maxCost,
+                        incremental: flags.incremental || config.incremental,
+                        // Pi can ask, so it asks instead of refusing over max_cost the
+                        // way MCP has to. An approval here IS the force flag.
+                        confirm: (estimate) => ctx.ui.confirm(`Broad-Side will spend about $${estimate.totalCost.toFixed(4)}`, describeBroadsideEstimate(estimate)),
+                    });
+                }
+                catch (error) {
+                    if (ctx.hasUI)
+                        ctx.ui.setWidget(BROADSIDE_WIDGET_ID, undefined);
+                    if (error instanceof BroadsideCancelledError) {
+                        ctx.ui.notify("Broad-Side cancelled. Nothing was submitted.", "info");
+                        return;
+                    }
+                    ctx.ui.notify(`Broad-Side submit failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+                    return;
+                }
+                const lines = estimateSubmitText(submit, lenses.map(getLens)).split("\n");
+                if (!waitMs) {
+                    lines.push("", "Batches are in flight. Run /codecarto-broadside collect when they finish.");
+                    finish(lines, `Broad-Side submitted: run ${submit.runId} (~$${submit.estimatedTotalCost.toFixed(4)})`);
+                    return;
+                }
+                ctx.ui.notify(`Broad-Side submitted run ${submit.runId}; polling for up to ${waitSeconds}s…`, "info");
+                try {
+                    const collect = await runBroadsideCollect(ctx.cwd, apiKey, {
+                        waitMs,
+                        includeSynthesis,
+                        includeTriage,
+                        retryTruncated,
+                        onStatus,
+                    });
+                    finish([...lines, "", ...collectResultText(collect).split("\n")], `Broad-Side ${collect.status}: run ${collect.runId}`);
+                }
+                catch (error) {
+                    if (ctx.hasUI)
+                        ctx.ui.setWidget(BROADSIDE_WIDGET_ID, undefined);
+                    // The batches are submitted and paid for either way — say so, so
+                    // nobody re-submits a run that is already in flight.
+                    ctx.ui.notify(`Broad-Side submitted run ${submit.runId}, but collect failed: ` +
+                        `${error instanceof Error ? error.message : String(error)}. Retry with /codecarto-broadside collect.`, "error");
+                }
+                return;
+            }
+            // action === "collect"
+            renderProgress("Polling batches…");
+            try {
+                const collect = await runBroadsideCollect(ctx.cwd, apiKey, {
+                    waitMs,
+                    includeSynthesis,
+                    includeTriage,
+                    retryTruncated,
+                    onStatus,
+                });
+                const lines = collectResultText(collect).split("\n");
+                const done = collect.status === "completed";
+                if (!done)
+                    lines.push("", "Still in flight. Run /codecarto-broadside collect again to resume.");
+                finish(lines, `Broad-Side ${collect.status}: ${collect.resultCount} result${collect.resultCount === 1 ? "" : "s"} saved`, done ? "info" : "warning");
+            }
+            catch (error) {
+                if (ctx.hasUI)
+                    ctx.ui.setWidget(BROADSIDE_WIDGET_ID, undefined);
+                ctx.ui.notify(`Broad-Side collect failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+            }
+        },
+    });
     pi.registerCommand("codecarto-publish", {
         description: "Publish the completed reimplementation spec to the configured CodeCartographer library",
         handler: async (_args, ctx) => {

package/dist/mcp-server/server.d.ts

@@ -230,6 +230,28 @@ export declare function handleAmend(args: {
         text: string;
     };
 }>;
+export declare function handleBroadside(args: {
+    cwd: string;
+    action: "submit" | "collect" | "status" | "models";
+    lenses?: string[];
+    api_key?: string;
+    wait_seconds?: number;
+    include_synthesis?: boolean;
+    include_triage?: boolean;
+    retry_truncated?: boolean;
+    max_cost?: number;
+    force?: boolean;
+    include_benchmarks?: boolean;
+    incremental?: boolean;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        text: string;
+    };
+}>;
 export declare function handleGuide(args: {
     topic?: string;
 }): Promise<{

package/dist/mcp-server/server.js

@@ -1,5 +1,7 @@
-// CodeCartographer MCP server. Exposes the framework as seven JSON-RPC tools
-// equivalent to the seven /codecarto-* commands the Pi extension registers.
+// CodeCartographer MCP server. Exposes the framework's workflow, library, and
+// Broad-Side operations as JSON-RPC tools (the TOOLS array below is the
+// authoritative list; the README's tool table maps each tool to its Pi
+// equivalent or marks it MCP-only).
 // Both wrappers import their primitives from ../core/index.ts so phase prompts,
 // status normalization, validation, and atomic completion are byte-identical
 // across surfaces.
@@ -13,9 +15,9 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
-import { cp, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
 import { basename, isAbsolute, join } from "node:path";
-import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, completeValidatedPhase, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, describeScaffoldStaleness, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isValidSlug, isWithinPathResolved, listEntries, listGuideTopics, readGuide, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, PACKAGE_VERSION, packagedWorkspaceDir, pathExists, PhasePreflightError, publishEntry, reindex as libraryReindex, refreshScaffold, resolvePhase, resolvePipelineChoice, seedOrchestratorFiles, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, } from "../core/index.js";
+import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, BROADSIDE_DIR, broadsideDirFor, BROADSIDE_LENS_IDS, BROADSIDE_SKILL_NAME, canonicalPath, copyPackagedWorkspace, collectResultText, completeValidatedPhase, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, describeScaffoldStaleness, estimateSubmitText, getLens, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isValidSlug, isWithinPathResolved, listBatchModels, listEntries, listGuideTopics, loadBroadsideConfig, modelsText, readGuide, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, PACKAGE_VERSION, packagedWorkspaceDir, pathExists, PhasePreflightError, publishEntry, reindex as libraryReindex, refreshScaffold, resolvePhase, resolvePipelineChoice, readBroadsideSkill, runBroadsideCollect, runBroadsideStatus, runBroadsideSubmit, seedOrchestratorFiles, statusText, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, } from "../core/index.js";
 import { applyAmendment } from "../core/amendment.js";
 import { appendUsageRun } from "../core/usage.js";
 import { initLibrary } from "../core/library.js";
@@ -84,7 +86,16 @@ export async function handleInit(args) {
             normalizeForComparison(await canonicalPath(targetWorkspaceDir)) ===
                 normalizeForComparison(await canonicalPath(packagedWorkspaceDir));
     }
+    // Broad-Side (batch reconnaissance) creates .codecarto/broadside/ on any
+    // repo, workspace or not. A .codecarto/ holding only that directory is not
+    // an existing workspace — init must proceed and merge the template into it
+    // rather than demanding force and a backup of pure scout state.
+    let broadsideOnly = false;
     if (targetExists && !sameWorkspace) {
+        const entries = (await readdir(targetWorkspaceDir)).filter((entry) => entry !== BROADSIDE_DIR);
+        broadsideOnly = entries.length === 0 && (await pathExists(join(targetWorkspaceDir, BROADSIDE_DIR)));
+    }
+    if (targetExists && !sameWorkspace && !broadsideOnly) {
         if (!args.force) {
             throw new McpError(ErrorCode.InvalidRequest, `A .codecarto/ directory already exists at ${targetWorkspaceDir}. Pass force: true to back it up and reinitialize. Warning: this moves all existing findings, handoffs, usage data, closeouts, and phase progress to a .codecarto-backup-TIMESTAMP/ directory.`);
         }
@@ -93,7 +104,12 @@ export async function handleInit(args) {
     }
     if (!(await pathExists(targetWorkspaceDir))) {
         await mkdir(cwd, { recursive: true });
-        await cp(packagedWorkspaceDir, targetWorkspaceDir, { recursive: true });
+        await copyPackagedWorkspace(targetWorkspaceDir);
+    }
+    else if (broadsideOnly) {
+        // Merge the template into the scout-only .codecarto/, preserving the
+        // broadside state and results already on disk.
+        await copyPackagedWorkspace(targetWorkspaceDir);
     }
     const statusPath = join(targetWorkspaceDir, "workflow", "status.yaml");
     const rawStatus = (await loadYamlFile(statusPath)) ?? {};
@@ -301,6 +317,15 @@ export async function handleSkill(args) {
         throw new McpError(ErrorCode.InvalidParams, "name is required");
     }
     const cwd = await validateCwd(args.cwd);
+    // Broad-Side is a reading guide for batch reconnaissance output, not a
+    // post-pipeline skill: it is useful before the pipeline starts and on a
+    // repository with no workspace at all, so it is served ahead of both gates.
+    if (args.name.trim() === BROADSIDE_SKILL_NAME) {
+        const skill = await readBroadsideSkill(cwd).catch((error) => {
+            throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
+        });
+        return textResult(skill.content, { skill: BROADSIDE_SKILL_NAME, path: skill.path, postPipeline: false });
+    }
     const state = await requireWorkspace(cwd);
     const nextPhase = getNextEligiblePhase(state);
     if (nextPhase) {
@@ -310,7 +335,7 @@ export async function handleSkill(args) {
     if (!(await pathExists(skillFile))) {
         const available = await listSkillNames(state.workspaceDir);
         const hint = available.length > 0 ? ` Available: ${available.join(", ")}.` : " No skills installed.";
-        throw new McpError(ErrorCode.InvalidParams, `Unknown skill: ${args.name}.${hint}`);
+        throw new McpError(ErrorCode.InvalidParams, `Unknown skill: ${args.name}.${hint} The Broad-Side reading guide is served as \`${BROADSIDE_SKILL_NAME}\` and is not pipeline-gated.`);
     }
     const prompt = await buildSkillPrompt(state, args.name);
     return textResult(prompt, { skill: args.name });
@@ -508,7 +533,10 @@ export async function handlePublish(args) {
         capabilities,
         confidentiality,
         generation,
-    }, { forceNewVersion: args.force_new_version === true });
+    }, {
+        forceNewVersion: args.force_new_version === true,
+        allowSourceRepoChange: args.allow_source_repo_change === true,
+    });
     const lines = [
         `Published ${result.namespace ? `${result.namespace}/` : ""}${result.slug} v${result.version} to ${libraryPath}`,
         result.isNewVersion ? `New version: v${result.version}` : `Metadata-only update (content hash matched v${result.version}).`,
@@ -709,7 +737,13 @@ export async function handleListSkills(args) {
     const lines = skills.length > 0
         ? [`Available skills (${skills.length}):`, ...skills.map((s) => `  - ${s}`)]
         : ["No skills installed."];
-    return textResult(lines.join("\n"), { skills });
+    // Broad-Side is listed apart from the post-pipeline set because it answers
+    // to codecarto_skill without the completion gate.
+    const broadsideAvailable = await readBroadsideSkill(cwd).then(() => true, () => false);
+    if (broadsideAvailable) {
+        lines.push("", `Also served by codecarto_skill (not pipeline-gated): ${BROADSIDE_SKILL_NAME} — how to read a Broad-Side batch reconnaissance run.`);
+    }
+    return textResult(lines.join("\n"), { skills, broadside: broadsideAvailable });
 }
 export async function handleRefreshScaffold(args) {
     const cwd = await validateCwd(args.cwd);
@@ -761,6 +795,117 @@ export async function handleAmend(args) {
         dashboardPath,
     });
 }
+// ---------- broadside (batch reconnaissance) ----------
+function resolveBroadsideApiKey(explicit, config) {
+    if (explicit && explicit.trim())
+        return explicit.trim();
+    const fromEnv = process.env.OPENROUTER_API_KEY?.trim();
+    if (fromEnv)
+        return fromEnv;
+    if (config.apiKey)
+        return config.apiKey;
+    throw new McpError(ErrorCode.InvalidParams, "No OpenRouter API key found. Pass api_key, set the OPENROUTER_API_KEY environment variable, or add api_key to .codecarto/broadside/config.yaml.");
+}
+export async function handleBroadside(args) {
+    const cwd = await validateCwd(args.cwd);
+    const action = args.action ?? "submit";
+    if (!["submit", "collect", "status", "models"].includes(action)) {
+        throw new McpError(ErrorCode.InvalidParams, `Unknown action: ${action}. Valid actions: submit, collect, status, models.`);
+    }
+    const config = await loadBroadsideConfig(broadsideDirFor(cwd));
+    if (action === "status") {
+        const { state } = await runBroadsideStatus(cwd);
+        return textResult(statusText(state), { state });
+    }
+    const apiKey = resolveBroadsideApiKey(args.api_key, config);
+    // Every run knob resolves the same way: explicit parameter, else the repo's
+    // config.yaml default, else the shipped default baked into loadBroadsideConfig.
+    const waitSeconds = typeof args.wait_seconds === "number" && args.wait_seconds > 0
+        ? args.wait_seconds
+        : config.waitSeconds;
+    const waitMs = waitSeconds > 0 ? waitSeconds * 1000 : undefined;
+    const includeSynthesis = args.include_synthesis ?? config.includeSynthesis;
+    const includeTriage = args.include_triage ?? config.includeTriage;
+    const retryTruncated = args.retry_truncated ?? config.retryTruncated;
+    const incremental = args.incremental ?? config.incremental;
+    if (action === "models") {
+        const { entries, benchmarks } = await listBatchModels(broadsideDirFor(cwd), config, apiKey, {
+            includeBenchmarks: args.include_benchmarks === true,
+        }).catch((error) => {
+            throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
+        });
+        return textResult(modelsText(entries, { benchmarks, defaultModel: config.model }), {
+            models: entries,
+            defaultModel: config.model,
+            benchmarkMeta: benchmarks?.meta ?? null,
+        });
+    }
+    if (action === "submit") {
+        let lenses;
+        if (args.lenses && args.lenses.length > 0) {
+            const unknown = args.lenses.filter((l) => !BROADSIDE_LENS_IDS.includes(l));
+            if (unknown.length > 0) {
+                throw new McpError(ErrorCode.InvalidParams, `Unknown lens(es): ${unknown.join(", ")}. Valid: ${BROADSIDE_LENS_IDS.join(", ")}`);
+            }
+            lenses = args.lenses;
+        }
+        else {
+            lenses = config.defaultLenses;
+        }
+        const maxCost = typeof args.max_cost === "number" && args.max_cost > 0 ? args.max_cost : config.maxCost;
+        const result = await runBroadsideSubmit(cwd, apiKey, {
+            lenses,
+            model: config.model,
+            maxCost,
+            force: args.force === true,
+            incremental,
+        }).catch((error) => {
+            throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
+        });
+        const lines = [estimateSubmitText(result, lenses.map(getLens))];
+        if (waitMs) {
+            lines.push("", "Waiting for batches to complete...");
+            const collect = await runBroadsideCollect(cwd, apiKey, {
+                waitMs,
+                includeSynthesis,
+                includeTriage,
+                retryTruncated,
+                onStatus: (lensId, status, counts) => lines.push(`  ${lensId}: ${status} (${counts.completed ?? 0}/${counts.total ?? "?"})`),
+            });
+            lines.push("", collectResultText(collect));
+        }
+        return textResult(lines.join("\n"), {
+            runId: result.runId,
+            outputDir: result.outputDir,
+            batches: result.batches,
+            estimatedTotalCost: result.estimatedTotalCost,
+            pricing: result.pricing,
+            maxCost: result.maxCost,
+        });
+    }
+    // action === "collect"
+    const collect = await runBroadsideCollect(cwd, apiKey, {
+        waitMs,
+        includeSynthesis,
+        includeTriage,
+        retryTruncated,
+    }).catch((error) => {
+        throw new McpError(ErrorCode.InvalidRequest, error instanceof Error ? error.message : String(error));
+    });
+    return textResult(collectResultText(collect), {
+        runId: collect.runId,
+        status: collect.status,
+        totalCost: collect.totalCost,
+        resultCount: collect.resultCount,
+        truncatedCount: collect.truncatedCount,
+        retriedCount: collect.retriedCount,
+        lensOutcomes: collect.lensOutcomes,
+        synthesis: collect.synthesis,
+        triage: collect.triage,
+        topFindings: collect.topFindings,
+        topTriageItems: collect.topTriageItems,
+    });
+}
 // ---------- tool registry ----------
 const TOOLS = [
     {
@@ -853,12 +998,12 @@ const TOOLS = [
     },
     {
         name: "codecarto_skill",
-        description: "Return the prompt text for a post-pipeline skill (only callable after all phases are complete). Use codecarto_status to confirm completion first.",
+        description: "Return the prompt text for a post-pipeline skill (only callable after all phases are complete). Use codecarto_status to confirm completion first. One name is exempt from the completion gate: \"broadside\" returns the reading guide for a Broad-Side batch reconnaissance run, which is meant to be read before or during the pipeline and works without a workspace.",
         inputSchema: {
             type: "object",
             properties: {
                 cwd: { type: "string", description: "Absolute path to the target repository." },
-                name: { type: "string", description: "Skill name (a directory under .codecarto/skills/)." },
+                name: { type: "string", description: "Skill name (a directory under .codecarto/skills/), or \"broadside\" for the Broad-Side reading guide." },
             },
             required: ["cwd", "name"],
         },
@@ -897,6 +1042,10 @@ const TOOLS = [
                     },
                 },
                 force_new_version: { type: "boolean" },
+                allow_source_repo_change: {
+                    type: "boolean",
+                    description: "Permit publishing when the target entry already records a different source_repo. Off by default, because a mismatch usually means two projects derived the same slug and the spec would land in the wrong version history. Set only when the repository itself moved.",
+                },
             },
             required: ["source_repo", "headline"],
         },
@@ -1004,7 +1153,7 @@ const TOOLS = [
     },
     {
         name: "codecarto_list_skills",
-        description: "List available post-pipeline skills installed in the workspace.",
+        description: "List available post-pipeline skills installed in the workspace, plus the Broad-Side reading guide when it is present (that one is not pipeline-gated).",
         inputSchema: {
             type: "object",
             properties: { cwd: { type: "string", description: "Absolute path to the target repository." } },
@@ -1032,6 +1181,63 @@ const TOOLS = [
             required: ["cwd"],
         },
     },
+    {
+        name: "codecarto_broadside",
+        description: "Broad-Side: fire a cheap batch reconnaissance scan at a repository via the OpenRouter Batch API. Six lenses (architecture, api, security, defect, conventions, porting) run as asynchronous single-turn prompts with structured JSON schemas; results land in .codecarto/broadside/<run>/ as JSON plus markdown, with an optional cross-lens synthesis report. Works on any git repository — no CodeCartographer workspace required. Requires an OpenRouter API key (api_key param, OPENROUTER_API_KEY env var, or .codecarto/broadside/config.yaml). Findings are unverified scouting signals from a batch model, not validated claims — they tell the interactive pipeline where to look. Actions: submit (fire batches, returns batch ids and cost estimate), collect (poll to completion, save results, optionally synthesize), status (show recorded runs), models (list batch-capable models with pricing, context, output caps, structured-output support, and optional coding benchmarks).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                cwd: { type: "string", description: "Absolute path to the target repository." },
+                action: {
+                    type: "string",
+                    enum: ["submit", "collect", "status", "models"],
+                    description: "submit fires all lens batches and returns batch ids; collect polls submitted batches, saves results, and optionally runs the synthesis pass; status shows recorded runs; models lists batch-capable models with pricing and capabilities.",
+                },
+                lenses: {
+                    type: "array",
+                    items: { type: "string", enum: [...BROADSIDE_LENS_IDS] },
+                    description: "Lenses to run (submit only). Defaults to all six.",
+                },
+                api_key: {
+                    type: "string",
+                    description: "OpenRouter API key. Prefer the OPENROUTER_API_KEY environment variable or .codecarto/broadside/config.yaml.",
+                },
+                wait_seconds: {
+                    type: "number",
+                    description: "For submit: after submitting, poll up to this many seconds before returning. For collect: poll up to this many seconds before returning with partial state. Falls back to wait_seconds in .codecarto/broadside/config.yaml.",
+                },
+                include_synthesis: {
+                    type: "boolean",
+                    description: "Run the cross-lens synthesis pass once all lens batches complete. Falls back to include_synthesis in .codecarto/broadside/config.yaml (default true).",
+                },
+                include_triage: {
+                    type: "boolean",
+                    description: "Run the triage pass once all lens batches complete: turns the findings into a prioritized work order (impact × difficulty, P0-P3, effort estimates). Falls back to include_triage in .codecarto/broadside/config.yaml (default true).",
+                },
+                retry_truncated: {
+                    type: "boolean",
+                    description: "Re-submit lens results that came back truncated at the output token limit, once, with a doubled output cap. Falls back to retry_truncated in .codecarto/broadside/config.yaml (default true).",
+                },
+                max_cost: {
+                    type: "number",
+                    description: "Approximate run expense limit in USD. The submit action estimates the run cost from slice sizes and the configured model's per-token pricing (live OpenRouter lookup, cached 24h) and refuses to submit when the estimate exceeds the limit unless force is true. Falls back to max_cost in .codecarto/broadside/config.yaml.",
+                },
+                force: {
+                    type: "boolean",
+                    description: "Submit even when the cost estimate exceeds max_cost (default false).",
+                },
+                incremental: {
+                    type: "boolean",
+                    description: "Diff against the previous run's git HEAD and scan only the modules whose files changed (falls back to a full scan on a dirty tree or when no prior run exists). Falls back to incremental in .codecarto/broadside/config.yaml (default false).",
+                },
+                include_benchmarks: {
+                    type: "boolean",
+                    description: "For action 'models': annotate each model with its Artificial Analysis coding index (extra API call; default false).",
+                },
+            },
+            required: ["cwd", "action"],
+        },
+    },
 ];
 const HANDLERS = {
     codecarto_amend: handleAmend,
@@ -1055,6 +1261,7 @@ const HANDLERS = {
     codecarto_dashboard: handleDashboard,
     codecarto_list_skills: handleListSkills,
     codecarto_guide: handleGuide,
+    codecarto_broadside: handleBroadside,
 };
 export async function handleGuide(args) {
     const topics = await listGuideTopics();