codecartographer-pi 0.16.0 → 0.17.1

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, detectProvenanceConflicts, 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)) ?? {};
@@ -246,7 +262,7 @@ export async function handleComplete(args) {
     if (validation.overall === "FAIL" || validation.overall === "MISSING") {
         throw new McpError(ErrorCode.InvalidRequest, `Cannot complete ${validation.phaseId}: validation is ${validation.overall}.\n${buildValidationSummary(validation).join("\n")}`);
     }
-    const { updatedState, closeoutNotice, orchestratorCheckpoint } = await completeValidatedPhase(cwd, validation, "codecarto_complete").catch((error) => {
+    const { updatedState, closeoutNotice, orchestratorCheckpoint, warnings } = await completeValidatedPhase(cwd, validation, "codecarto_complete").catch((error) => {
         throw new McpError(ErrorCode.InvalidParams, error instanceof Error ? error.message : String(error));
     });
     // Record the run in the usage log (issue #100). MCP hosts execute phases in
@@ -287,6 +303,10 @@ export async function handleComplete(args) {
         lines.push(orchestratorCheckpoint);
     if (dashboardPath)
         lines.push(`Dashboard refreshed: ${dashboardPath}`);
+    for (const warning of validation.warnings ?? [])
+        lines.push(`NOTE: ${warning} Non-gating.`);
+    for (const warning of warnings)
+        lines.push(`NOTE: ${warning} Non-gating.`);
     return textResult(lines.join("\n"), {
         completedPhase: validation.phaseId,
         validation: validation.overall,
@@ -294,6 +314,7 @@ export async function handleComplete(args) {
         closeoutNotice,
         orchestratorCheckpoint,
         dashboardPath,
+        warnings: [...(validation.warnings ?? []), ...warnings],
     });
 }
 export async function handleSkill(args) {
@@ -301,6 +322,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 +340,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 });
@@ -447,6 +477,33 @@ async function resolveDefaultsFromWorkspace(cwd, overrides) {
     }
     return { pipeline, namespace };
 }
+// ---------- library provenance reporting ----------
+function conflictEntryLabel(conflict) {
+    return conflict.namespace ? `${conflict.namespace}/${conflict.slug}` : conflict.slug;
+}
+/**
+ * The report block appended to the list and reindex text results when an
+ * entry's versions disagree about source_repo (#148). Empty when there is
+ * nothing to report, so a healthy library's output does not change. Repair
+ * is manual by design: the framework does not rename or renumber versions,
+ * because entry paths are ABI.
+ */
+function provenanceConflictLines(conflicts) {
+    if (conflicts.length === 0)
+        return [];
+    const lines = [
+        "",
+        `Provenance conflicts — ${conflicts.length} ${conflicts.length === 1 ? "entry" : "entries"} whose versions disagree about source_repo:`,
+    ];
+    for (const conflict of conflicts) {
+        const others = conflict.disagreeing_versions
+            .map((v) => `v${v.version} records ${v.source_repo}`)
+            .join("; ");
+        lines.push(`  ${conflictEntryLabel(conflict)}: the index advertises ${conflict.source_repo} (v${conflict.latest_version}), but ${others}.`);
+    }
+    lines.push("These entries were merged by a slug collision before publish refused cross-project appends, so each version history spans more than one codebase (a repository that genuinely moved and was re-published with allow_source_repo_change leaves the same shape).", "Repair is manual: split the entry by hand — the framework does not rename or renumber versions, because entry paths are ABI.");
+    return lines;
+}
 // ---------- library handlers ----------
 export async function handlePublish(args) {
     const libraryPath = await resolveLibraryPath(args);
@@ -508,7 +565,11 @@ 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,
+        allowConfidentialityMismatch: args.allow_confidentiality_mismatch === 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}).`,
@@ -539,6 +600,10 @@ export async function handleLibraryList(args) {
     if (typeof args.source_repo === "string" && args.source_repo !== "")
         filter.source_repo = args.source_repo;
     const entries = await listEntries(libraryPath, filter);
+    // Computed over the listed entries only, read-only: one readdir per entry
+    // plus one small metadata read per older version.
+    const conflicts = await detectProvenanceConflicts(libraryPath, entries);
+    const conflicted = new Set(conflicts.map((c) => `${c.namespace ?? ""}/${c.slug}`));
     const summary = entries.length === 0
         ? `No entries match the filter in ${libraryPath}.`
         : [
@@ -546,8 +611,10 @@ export async function handleLibraryList(args) {
             ...entries.map((e) => {
                 const ns = e.namespace ? `${e.namespace}/` : "";
                 const tags = e.tags.length > 0 ? ` [${e.tags.slice(0, 4).join(", ")}${e.tags.length > 4 ? ", ..." : ""}]` : "";
-                return `  ${ns}${e.slug} v${e.latest_version} — ${e.headline}${tags}`;
+                const flag = conflicted.has(`${e.namespace ?? ""}/${e.slug}`) ? " — PROVENANCE CONFLICT (see below)" : "";
+                return `  ${ns}${e.slug} v${e.latest_version} — ${e.headline}${tags}${flag}`;
             }),
+            ...provenanceConflictLines(conflicts),
         ].join("\n");
     return textResult(summary, {
         libraryPath,
@@ -555,6 +622,7 @@ export async function handleLibraryList(args) {
         namespaced: marker.namespaced,
         count: entries.length,
         entries,
+        provenance_conflicts: conflicts,
     });
 }
 export async function handleLibraryReindex(args) {
@@ -565,17 +633,27 @@ export async function handleLibraryReindex(args) {
     }
     const index = await libraryReindex(libraryPath);
     const namespaces = index.namespaces.length > 0 ? index.namespaces.join(", ") : "(none)";
-    return textResult(`Reindexed ${libraryPath}: ${index.entry_count} ${index.entry_count === 1 ? "entry" : "entries"} across namespaces [${namespaces}].`, {
+    return textResult([
+        `Reindexed ${libraryPath}: ${index.entry_count} ${index.entry_count === 1 ? "entry" : "entries"} across namespaces [${namespaces}].`,
+        ...provenanceConflictLines(index.provenance_conflicts),
+    ].join("\n"), {
         libraryPath,
         libraryName: index.library_name,
         entry_count: index.entry_count,
         namespaces: index.namespaces,
+        provenance_conflicts: index.provenance_conflicts,
     });
 }
 export async function handleLibraryInit(args) {
     if (!args.library_path || typeof args.library_path !== "string") {
         throw new McpError(ErrorCode.InvalidParams, "library_path is required.");
     }
+    // Same rule as resolveLibraryPath for the other library tools: a relative
+    // path would resolve against the MCP server process's cwd and then be
+    // persisted verbatim into the user-global config (#134).
+    if (!isAbsolute(args.library_path)) {
+        throw new McpError(ErrorCode.InvalidParams, `library_path must be absolute, got: ${args.library_path}`);
+    }
     const libraryPath = args.library_path;
     const namespaced = !!args.namespace;
     const result = await initLibrary(libraryPath, {
@@ -709,7 +787,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 +845,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 +1048,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"],
         },
@@ -884,7 +1079,11 @@ const TOOLS = [
                 headline: { type: "string" },
                 tags: { type: "array", items: { type: "string" } },
                 capabilities: { type: "array", items: { type: "string" } },
-                confidentiality: { type: "string", enum: ["internal", "shared", "public"] },
+                confidentiality: {
+                    type: "string",
+                    enum: ["internal", "shared", "public"],
+                    description: "Classification of the entry. Defaults to internal. Ordered internal < shared < public; publish refuses an entry more restricted than the library's visibility unless allow_confidentiality_mismatch is set.",
+                },
                 model_metadata: {
                     type: "object",
                     properties: {
@@ -897,13 +1096,21 @@ 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.",
+                },
+                allow_confidentiality_mismatch: {
+                    type: "boolean",
+                    description: "Permit publishing when the entry's confidentiality is more restricted than the library's visibility (internal < shared < public: an internal entry into a shared or public library, a shared entry into a public one). Off by default, because that direction exposes the spec to everyone the library reaches. An omitted confidentiality counts as internal. Set only when the exposure is intended; the recorded confidentiality is not changed.",
+                },
             },
             required: ["source_repo", "headline"],
         },
     },
     {
         name: "codecarto_library_list",
-        description: "List entries in a CodeCartographer library, optionally filtered by namespace, tag, slug, or source_repo. The library is identified by library_path (absolute) or by cwd's config.yaml.",
+        description: "List entries in a CodeCartographer library, optionally filtered by namespace, tag, slug, or source_repo. The library is identified by library_path (absolute) or by cwd's config.yaml. Flags entries whose versions disagree about source_repo (merged by a slug collision before publish refused cross-project appends); repair is manual.",
         inputSchema: {
             type: "object",
             properties: {
@@ -918,7 +1125,7 @@ const TOOLS = [
     },
     {
         name: "codecarto_library_reindex",
-        description: "Regenerate index.yaml and INDEX.md for a CodeCartographer library from filesystem state. Use after manual edits or to resolve a git merge conflict on index.yaml.",
+        description: "Regenerate index.yaml and INDEX.md for a CodeCartographer library from filesystem state. Use after manual edits or to resolve a git merge conflict on index.yaml. Also reports entries whose versions disagree about source_repo (merged by a slug collision before publish refused cross-project appends); the index files are not changed and repair is manual.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1004,7 +1211,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 +1239,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 +1319,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();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "mcpName": "io.github.HuginnIndustries/codecartographer",
   "description": "Turn an unfamiliar codebase into a validated reimplementation spec, then synthesize confirmed specs and a product vision into a traceable plan.",
   "type": "module",
@@ -35,6 +35,14 @@
   },
   "files": [
     ".codecarto/**/*",
+    "!.codecarto/BACKLOG.md",
+    "!.codecarto/THREAD_LOG.md",
+    "!.codecarto/CONVENTIONS.md",
+    "!.codecarto/DECISIONS.md",
+    "!.codecarto/closeouts/**",
+    "!.codecarto/broadside/**",
+    ".codecarto/broadside/SKILL.md",
+    ".codecarto/broadside/config.yaml",
     "agent-skill/**/*",
     "dist/**/*",
     "assets/logo.svg",
@@ -49,13 +57,14 @@
     "prepublishOnly": "npm run build",
     "test": "node --experimental-strip-types --disable-warning=ExperimentalWarning --test tests/*.test.mjs",
     "smoke": "node scripts/smoke-mcp.mjs",
+    "smoke:broadside": "node scripts/smoke-broadside.mjs",
     "demo:synthesis": "npm run build && node scripts/create-synthesis-demo.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.80.10",
+    "@earendil-works/pi-coding-agent": ">=0.84.0",
     "@sinclair/typebox": "*"
   },
   "pi": {