codecartographer-pi 0.22.2 → 0.23.0

package/.codecarto/broadside/SKILL.md

@@ -86,6 +86,21 @@ Submits pre-flight the chosen model: pricing comes from the live catalog
 model that does not advertise structured-output support is refused outright,
 because every lens depends on `json_schema` response_format.
 
+Each lens reads a scope of the repository. Architecture reads the manifest,
+entry point, README, and file tree; defect, conventions, and porting read
+every source file; the **security** and **API** lenses target where the
+trust boundary usually lives — `server/**`, `**/auth*`, `**/middleware/**`,
+`SECURITY.md` (security) and `server/**`, `api/**`, `src/server/**`,
+`src/api/**`, `**/*routes*`, `**/*router*`, `**/*handler*`, `**/*endpoint*`
+(API). A repository whose server is `src/server.js` matches none of those, so
+when the targeted patterns find nothing those two lenses **fall back to every
+source file** — priced as such, chunked at the lens's slice size rather than
+truncated, and said so on the lens line of the estimate, the submit report,
+`status`, and the prompt the model receives. A lens whose targeted patterns
+and fallback both find nothing (only test files, say) is skipped with a line
+naming both. `max_cost` is the guard against a fallback scan on a large
+repository being more than you meant to spend.
+
 Collect runs two cross-lens post-passes by default: **synthesis** (the
 executive report) and **triage** (the prioritized work order). Pass
 `include_synthesis: false` or `include_triage: false` on collect to skip one.

package/.codecarto/workflow/scaffold-version.yaml

@@ -3,4 +3,4 @@
 # workspace's framework-owned files (GUIDE.md, templates/, workflow/ pipelines
 # and VALIDATE.md) predate the running release. Written at release time and
 # copied verbatim by init — never edit by hand.
-scaffold_version: 0.22.2
+scaffold_version: 0.23.0

package/README.md

@@ -383,7 +383,7 @@ Each workflow tool accepts an absolute `cwd` for the target repository. `codecar
 
 ## Broad-Side (batch reconnaissance)
 
-Broad-Side is the cheap sweep you run *before* the expensive interactive run. It fires six analysis lenses — architecture, API surface, security, mechanical defect scan, convention extraction, porting — at a repository as single-turn prompts over the [OpenRouter Batch API](https://openrouter.ai/docs), then cross-references them into one executive report (`synthesis.md`) and a prioritized P0–P3 work order (`triage.md`).
+Broad-Side is the cheap sweep you run *before* the expensive interactive run. It fires six analysis lenses — architecture, API surface, security, mechanical defect scan, convention extraction, porting — at a repository as single-turn prompts over the [OpenRouter Batch API](https://openrouter.ai/docs), then cross-references them into one executive report (`synthesis.md`) and a prioritized P0–P3 work order (`triage.md`). The security and API lenses target the paths where a trust boundary usually lives (`server/`, `auth*`, `middleware/`, routers and handlers) and fall back to every source file when a repository has none of them — priced as such, and said so on the estimate — so a service whose server is `src/server.js` still gets its security review.
 
 **Broad-Side findings are unverified scouting leads, not evidence.** Each lens is one shot: no cross-file traversal, no runtime verification, no builds, no tests. Every finding is a `file:line` pointer that the interactive pipeline — or you — must confirm before it is a fact. That division of labor is the point: a sub-dollar unattended sweep that tells the expensive run where to look. Nothing downstream may cite a Broad-Side report as a source.
 

package/dist/core/broadside.d.ts

@@ -121,6 +121,12 @@ export type FileSlice = {
     redactedValues?: number;
     /** The files in this slice that had at least one value redacted. */
     redactedFiles?: string[];
+    /**
+     * Set when the lens's targeted globs matched nothing and the slice was
+     * built from its fallback globs instead (#319). The estimate, the batch
+     * entry, and the prompt all say so.
+     */
+    fallback?: string;
 };
 /**
  * OpenRouter's unified `reasoning` control, as sent on a lens request.
@@ -203,6 +209,12 @@ export type BroadsideBatchEntry = {
     error?: unknown;
     /** Why a `skipped` lens had nothing to submit: the globs that matched no file. */
     reason?: string;
+    /**
+     * Set when the lens scanned its fallback scope because its targeted globs
+     * matched nothing (#319): "no files matched …; scanned all javascript
+     * sources instead". Absent for a targeted scan.
+     */
+    fallback?: string;
     /** Set when this lens used a model other than the run default. */
     model?: string;
     /** The completion ceiling of this lens's model; bounds the truncation retry. */
@@ -348,6 +360,8 @@ export type BroadsideEstimate = {
         /** The model this lens would use — `model` unless a per-lens override applies. */
         model: string;
         pricing: ModelPricing;
+        /** Set when this lens is priced on its fallback scope (#319); see BroadsideBatchEntry.fallback. */
+        fallback?: string;
     }>;
     /** True when at least one lens uses a model other than the run default. */
     mixedModels: boolean;
@@ -490,6 +504,15 @@ type LensDefinition = {
     reasoning?: BroadsideReasoning;
     skipTestFiles?: boolean;
     globsFor: (info: RepoInfo) => string[];
+    /**
+     * Where to look when `globsFor` matches nothing (#319). The security and
+     * api lenses target server/, auth, and middleware paths because that is
+     * where the trust boundary usually lives; a service whose server is
+     * `src/server.js` matched none of them and got no security review at all.
+     * The fallback is the language's whole source set — priced as such, and
+     * said so in the estimate, the run record, and the prompt.
+     */
+    fallbackGlobsFor?: (info: RepoInfo) => string[];
     systemPrompt: (info: RepoInfo) => string;
     userPrompt: (info: RepoInfo, source: string, moduleName: string) => string;
 };
@@ -500,6 +523,20 @@ export declare const BROADSIDE_LANGUAGES: readonly ["go", "python", "rust", "typ
 export declare function collectRepoInfo(targetDir: string, opts?: {
     redact?: boolean;
 }): Promise<RepoInfo>;
+type CollectedFile = {
+    relPath: string;
+    moduleName: string;
+};
+/**
+ * The files a lens will read: its targeted globs, or — when those match
+ * nothing and the lens declares a fallback — the fallback globs, with a
+ * sentence saying so (#319). The sentence travels to the estimate, the
+ * batch entry, and the prompt, so a fallback scan is never a silent one.
+ */
+export declare function selectLensFiles(allFiles: string[], lens: LensDefinition, info: RepoInfo): {
+    files: CollectedFile[];
+    fallback?: string;
+};
 export declare function gatherSlices(targetDir: string, lens: LensDefinition, info: RepoInfo, opts?: {
     redact?: boolean;
 }): Promise<FileSlice[]>;

package/dist/core/broadside.js

@@ -698,6 +698,7 @@ const LENSES = {
                 "**/*handler*",
                 "**/*endpoint*",
             ],
+        fallbackGlobsFor: (info) => [info.sourceGlob],
         systemPrompt: () => "You are a senior API auditor. Given source files from an HTTP server, " +
             "extract every HTTP endpoint (method, path, handler function, auth requirement) " +
             "and every key request/response data type. Return a JSON object following the " +
@@ -718,6 +719,7 @@ const LENSES = {
         globsFor: (info) => info.language === "go"
             ? ["server/**/*.go", "server/*.go", "**/auth*.go", "**/middleware/**/*.go", "SECURITY.md"]
             : ["server/**", "**/auth*", "**/middleware/**", "SECURITY.md"],
+        fallbackGlobsFor: (info) => [info.sourceGlob],
         systemPrompt: () => "You are a security engineer performing a first-pass review of a codebase. " +
             "Given source files, identify potential security issues — focusing on " +
             "authentication, authorization, input validation, TLS, secrets handling, " +
@@ -1237,8 +1239,7 @@ function resolveSliceMode(lens, files, totalChars) {
         return lens.sliceBy;
     return totalChars > lens.maxChars ? "directory" : "none";
 }
-function collectLensFiles(allFiles, lens, info) {
-    const globs = lens.globsFor(info).filter(Boolean);
+function collectFilesMatching(allFiles, lens, globs) {
     if (globs.length === 0)
         return [];
     const out = [];
@@ -1253,6 +1254,30 @@ function collectLensFiles(allFiles, lens, info) {
     }
     return out;
 }
+/**
+ * The files a lens will read: its targeted globs, or — when those match
+ * nothing and the lens declares a fallback — the fallback globs, with a
+ * sentence saying so (#319). The sentence travels to the estimate, the
+ * batch entry, and the prompt, so a fallback scan is never a silent one.
+ */
+export function selectLensFiles(allFiles, lens, info) {
+    const globs = lens.globsFor(info).filter(Boolean);
+    const targeted = collectFilesMatching(allFiles, lens, globs);
+    if (targeted.length > 0 || globs.length === 0 || !lens.fallbackGlobsFor)
+        return { files: targeted };
+    const fallbackGlobs = lens.fallbackGlobsFor(info).filter(Boolean);
+    const files = collectFilesMatching(allFiles, lens, fallbackGlobs);
+    if (files.length === 0)
+        return { files };
+    return {
+        files,
+        fallback: `no files matched ${globs.join(", ")}${lens.skipTestFiles ? " (test files excluded)" : ""}; ` +
+            `scanned all ${info.language} sources (${fallbackGlobs.join(", ")}) instead`,
+    };
+}
+function collectLensFiles(allFiles, lens, info) {
+    return selectLensFiles(allFiles, lens, info).files;
+}
 async function slurpFileList(targetDir, files, maxChars, redact = true) {
     const slices = [];
     let currentModule = "";
@@ -1329,16 +1354,18 @@ export async function gatherSlices(targetDir, lens, info, opts = {}) {
         return [{ moduleName: "root", content: "", fileCount: 0, chars: 0, files: [] }];
     }
     const { files: allFiles } = await listRepoFiles(targetDir);
-    const files = collectLensFiles(allFiles, lens, info);
+    const { files, fallback } = selectLensFiles(allFiles, lens, info);
     const totalChars = await sumFileSizes(targetDir, files);
     const mode = resolveSliceMode(lens, files, totalChars);
-    if (mode === "none") {
+    const slices = mode === "none"
         // Whole-repo slice: one module named after the repo, so a small
         // repo produces a single request instead of one per directory.
-        const single = files.map((f) => ({ ...f, moduleName: info.name }));
-        return slurpFileList(targetDir, single, lens.maxChars, redact);
-    }
-    return slurpFileList(targetDir, files, lens.maxChars, redact);
+        ? await slurpFileList(targetDir, files.map((f) => ({ ...f, moduleName: info.name })), lens.maxChars, redact)
+        : await slurpFileList(targetDir, files, lens.maxChars, redact);
+    if (fallback)
+        for (const slice of slices)
+            slice.fallback = fallback;
+    return slices;
 }
 async function sumFileSizes(targetDir, files) {
     let total = 0;
@@ -1362,7 +1389,17 @@ export function buildBatchRequest(lens, info, slice, index, sliceCount, model =
             model,
             messages: [
                 { role: "system", content: lens.systemPrompt(info) },
-                { role: "user", content: lens.userPrompt(info, slice.content, slice.moduleName) },
+                {
+                    role: "user",
+                    content: 
+                    // A fallback scan is not "server source files": say what it is,
+                    // so the model judges the trust boundary wherever it appears
+                    // and does not report the missing server/ as a finding (#319).
+                    (slice.fallback
+                        ? `NOTE: this repository has no files under the paths this lens usually reads (${slice.fallback}). ` +
+                            "What follows is every source file it has; locate the trust boundary and the request-handling code wherever they live.\n\n"
+                        : "") + lens.userPrompt(info, slice.content, slice.moduleName),
+                },
             ],
             response_format: { type: "json_schema", json_schema: SCHEMAS[lens.schemaName] },
             max_tokens: maxTokensOverride ?? lens.maxTokens,
@@ -2320,11 +2357,14 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
         slicesByLens.set(lensId, slices);
         if (slices.length === 0) {
             const globs = lens.globsFor(info).filter(Boolean);
+            const fallbackGlobs = lens.fallbackGlobsFor?.(info).filter(Boolean) ?? [];
             skipReasons.set(lensId, globs.length === 0
                 ? "the lens has no file patterns for this language"
                 : matchedBeforeIncremental > 0
                     ? "incremental: none of this lens's files changed since the previous run"
-                    : `no files matched ${globs.join(", ")}${lens.skipTestFiles ? " (test files excluded)" : ""}`);
+                    : `no files matched ${globs.join(", ")}` +
+                        (fallbackGlobs.length > 0 ? ` or the fallback ${fallbackGlobs.join(", ")}` : "") +
+                        (lens.skipTestFiles ? " (test files excluded)" : ""));
         }
         const lensModel = modelForLens(lensId);
         const { pricing: lensPricing, outputCap: lensOutputCap } = resolved.get(lensModel);
@@ -2347,15 +2387,19 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
         const approved = await opts.confirm({
             model,
             pricing,
-            lenses: perLensEstimate.map(({ lens, cost, maxTokens, lensModel, lensPricing }) => ({
-                lensId: lens.id,
-                name: lens.name,
-                slices: (slicesByLens.get(lens.id) ?? []).length,
-                maxTokens,
-                cost,
-                model: lensModel,
-                pricing: lensPricing,
-            })),
+            lenses: perLensEstimate.map(({ lens, cost, maxTokens, lensModel, lensPricing }) => {
+                const fallback = (slicesByLens.get(lens.id) ?? []).find((slice) => slice.fallback)?.fallback;
+                return {
+                    lensId: lens.id,
+                    name: lens.name,
+                    slices: (slicesByLens.get(lens.id) ?? []).length,
+                    maxTokens,
+                    cost,
+                    model: lensModel,
+                    pricing: lensPricing,
+                    ...(fallback && { fallback }),
+                };
+            }),
             mixedModels: perLensEstimate.some(({ lensModel }) => lensModel !== model),
             totalCost: estimatedTotalCost,
             inputTokens: estimatedInputTokens,
@@ -2419,12 +2463,15 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
         const requests = slices.map((sl, i) => buildBatchRequest(lens, info, sl, i, slices.length, lensModel, maxTokens, config.reasoning ?? undefined));
         for (const request of requests)
             requestsByCustomId[request.custom_id] = request;
+        const fallback = slices.find((slice) => slice.fallback)?.fallback;
         const entry = {
             batchId: "",
             requests: requests.length,
             status: "submitting",
             submittedAt: new Date().toISOString(),
             estimatedCost: priced.cost,
+            // A scan of the fallback scope is recorded as such (#319).
+            ...(fallback && { fallback }),
             // Recorded per lens so collect's truncation retry re-submits against
             // the model and ceiling this lens actually used, not the run default.
             ...(lensModel !== model && { model: lensModel }),
@@ -3256,7 +3303,9 @@ export function estimateSubmitText(result, lenses) {
             ? ` — ${explainBatchError(entry.error)}`
             : !entry.batchId && entry.reason
                 ? ` — ${entry.reason}`
-                : "";
+                : entry.fallback
+                    ? ` — ${entry.fallback}`
+                    : "";
         lines.push(`  ${lens.name}: ${status} (${entry.requests} request(s), ~$${entry.estimatedCost.toFixed(4)})${override}${reason}`);
     }
     if (result.repo) {
@@ -3492,7 +3541,7 @@ export function statusText(state) {
             if (!entry)
                 continue;
             lines.push(`  ${lensId}: ${entry.status}${entry.batchId ? ` (${entry.batchId})` : ""}${entry.cost !== undefined ? `, $${entry.cost.toFixed(6)}` : ""}` +
-                (entry.status === "skipped" && entry.reason ? ` — ${entry.reason}` : ""));
+                (entry.status === "skipped" && entry.reason ? ` — ${entry.reason}` : entry.fallback ? ` — ${entry.fallback}` : ""));
         }
         lines.push(`  synthesis: ${run.synthesis.status}`);
         lines.push(`  triage: ${run.triage?.status ?? "pending"}`);

package/dist/extensions/codecarto/completions.d.ts

@@ -0,0 +1,18 @@
+export interface CompletionCandidate {
+    value: string;
+    label?: string;
+    description?: string;
+}
+export interface CompletionItem {
+    value: string;
+    label: string;
+    description?: string;
+}
+/**
+ * Complete the last whitespace-separated token of `prefix` from `candidates`,
+ * returning items whose `value` is the full argument text Pi should put in
+ * the line — every earlier token, then the candidate. A candidate already
+ * typed as an earlier token is not offered again. Returns null when nothing
+ * matches, which is what Pi expects for "no popup".
+ */
+export declare function completeLastToken(prefix: string, candidates: readonly CompletionCandidate[]): CompletionItem[] | null;

package/dist/extensions/codecarto/completions.js

@@ -0,0 +1,36 @@
+// Argument completion for the /codecarto-* slash commands.
+//
+// Pi hands `getArgumentCompletions` everything typed after the command name,
+// and when the user accepts an item it replaces all of that text with the
+// item's `value` (pi 0.85: `argumentText = textBeforeCursor.slice(spaceIndex
+// + 1)` on the way in, `applyCompletion` slicing `cursorCol - prefix.length`
+// on the way out). A completer that matches the *last* token but returns a
+// bare flag therefore erases every flag typed before it: with the popup open,
+// `/codecarto-next --auto --llm-steer` became `/codecarto-next --llm-steer` on
+// Enter, the steered phase ran alone, and the auto run never started. The
+// same shape turned `--auto --strict` into `--strict`, the one combination
+// the parser rejects.
+//
+// So: match the last token, but return the whole line.
+/**
+ * Complete the last whitespace-separated token of `prefix` from `candidates`,
+ * returning items whose `value` is the full argument text Pi should put in
+ * the line — every earlier token, then the candidate. A candidate already
+ * typed as an earlier token is not offered again. Returns null when nothing
+ * matches, which is what Pi expects for "no popup".
+ */
+export function completeLastToken(prefix, candidates) {
+    const tokens = prefix.split(/\s+/);
+    const last = tokens.pop() ?? "";
+    const earlier = tokens.filter((token) => token.length > 0);
+    const head = earlier.join(" ");
+    const typed = new Set(earlier);
+    const items = candidates
+        .filter((candidate) => candidate.value.startsWith(last) && !typed.has(candidate.value))
+        .map((candidate) => ({
+        value: head ? `${head} ${candidate.value}` : candidate.value,
+        label: candidate.label ?? candidate.value,
+        ...(candidate.description && { description: candidate.description }),
+    }));
+    return items.length > 0 ? items : null;
+}

package/dist/extensions/codecarto/index.js

@@ -6,6 +6,7 @@ import { parseDashboardFlags } from "./dashboard-flags.js";
 import { narrateDashboard } from "./dashboard-narrator.js";
 import { parseBroadsideFlags, KNOWN_BROADSIDE_TOKENS } from "./broadside-flags.js";
 import { parseNextFlags } from "./next-flags.js";
+import { completeLastToken } from "./completions.js";
 import { buildPiGuideMessage } from "./guide-framing.js";
 import { isCtxLive, notifyCtx } from "./notify.js";
 import { phaseCompactionExtension } from "./phase-compaction.js";
@@ -129,11 +130,14 @@ function describeBroadsideEstimate(estimate) {
         `Rates: $${estimate.pricing.inputPerM.toFixed(4)}/M in · $${estimate.pricing.outputPerM.toFixed(4)}/M out`,
         "",
         "Per lens:",
-        ...estimate.lenses.map(({ name, slices, cost, model }) => {
+        ...estimate.lenses.map(({ name, slices, cost, model, fallback }) => {
             // 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}`;
+            // A lens priced on its fallback scope says so here, where the
+            // spend is approved — every source file, not a server directory (#319).
+            const scope = fallback ? `\n    ↳ ${fallback}` : "";
+            return `  ${name}: ${slices} slice${slices === 1 ? "" : "s"} — ~$${cost.toFixed(4)}${override}${scope}`;
         }),
         "",
         `Estimated total: ~$${estimate.totalCost.toFixed(4)} ` +
@@ -432,12 +436,7 @@ export default function codeCartographerExtension(pi) {
     });
     pi.registerCommand("codecarto-init", {
         description: "Initialize .codecarto/ in the current repository",
-        getArgumentCompletions: (prefix) => {
-            const items = Object.keys(PIPELINE_ALIASES)
-                .filter((value) => value.startsWith(prefix))
-                .map((value) => ({ value, label: value }));
-            return items.length > 0 ? items : null;
-        },
+        getArgumentCompletions: (prefix) => completeLastToken(prefix, Object.keys(PIPELINE_ALIASES).map((value) => ({ value }))),
         handler: async (args, ctx) => {
             const trimmedArgs = args.trim();
             const pipelineChoice = resolvePipelineChoice(trimmedArgs);
@@ -536,12 +535,7 @@ export default function codeCartographerExtension(pi) {
     });
     pi.registerCommand("codecarto-switch-pipeline", {
         description: "Switch the active pipeline without losing findings or progress: /codecarto-switch-pipeline <variant>",
-        getArgumentCompletions: (prefix) => {
-            const items = Object.keys(PIPELINE_ALIASES)
-                .filter((value) => value.startsWith(prefix))
-                .map((value) => ({ value, label: value }));
-            return items.length > 0 ? items : null;
-        },
+        getArgumentCompletions: (prefix) => completeLastToken(prefix, Object.keys(PIPELINE_ALIASES).map((value) => ({ value }))),
         handler: async (args, ctx) => {
             const trimmedArgs = args.trim();
             if (!trimmedArgs) {
@@ -595,16 +589,17 @@ export default function codeCartographerExtension(pi) {
             // --strict is offered only once --auto is present, because on its own
             // it is rejected — suggesting it standalone invites the one error the
             // parser has.
+            // Each item's value is the whole argument line (see completions.ts):
+            // accepting `--llm-steer` after `--auto ` keeps the `--auto`.
             const autoAlreadyTyped = prefix.includes("--auto");
-            const items = [
-                { value: "--auto", label: "--auto", description: "run every remaining phase back to back (recommended with --llm-steer)" },
-                { value: "--llm-steer", label: "--llm-steer", description: "seed each phase from the previous phase's closeout; no effect on the first phase" },
-                { value: "--no-llm-steer", label: "--no-llm-steer", description: "force steering off when the workspace config turns it on" },
+            return completeLastToken(prefix, [
+                { value: "--auto", description: "run every remaining phase back to back (recommended with --llm-steer)" },
+                { value: "--llm-steer", description: "seed each phase from the previous phase's closeout; no effect on the first phase" },
+                { value: "--no-llm-steer", description: "force steering off when the workspace config turns it on" },
                 ...(autoAlreadyTyped
-                    ? [{ value: "--strict", label: "--strict", description: "with --auto: stop on PASS WITH GAPS instead of advancing" }]
+                    ? [{ value: "--strict", description: "with --auto: stop on PASS WITH GAPS instead of advancing" }]
                     : []),
-            ].filter((item) => item.value.startsWith(prefix.split(/\s+/).pop() ?? prefix));
-            return items.length > 0 ? items : null;
+            ]);
         },
         handler: async (args, ctx) => {
             const flags = parseNextFlags(args);
@@ -967,10 +962,7 @@ export default function codeCartographerExtension(pi) {
         description: "Read the packaged CodeCartographer agent guide into the session: /codecarto-guide [topic]",
         getArgumentCompletions: async (prefix) => {
             const topics = await listGuideTopics().catch(() => ["overview"]);
-            const items = topics
-                .filter((value) => value.startsWith(prefix))
-                .map((value) => ({ value, label: value }));
-            return items.length > 0 ? items : null;
+            return completeLastToken(prefix, topics.map((value) => ({ value })));
         },
         handler: async (args, ctx) => {
             // The guide is packaged with the extension, not copied into a
@@ -1004,12 +996,9 @@ export default function codeCartographerExtension(pi) {
     });
     pi.registerCommand("codecarto-broadside", {
         description: "Batch reconnaissance (Broad-Side): /codecarto-broadside [submit|collect|status|models] [lenses…] [--model=ID] [--lens-model=LENS:ID] [flags]",
-        getArgumentCompletions: (prefix) => {
-            const items = KNOWN_BROADSIDE_TOKENS
-                .filter((value) => value.startsWith(prefix))
-                .map((value) => ({ value, label: value }));
-            return items.length > 0 ? items : null;
-        },
+        // Completes the token under the cursor, so lens names and flags are
+        // offered after the action too, and keeps everything typed before it.
+        getArgumentCompletions: (prefix) => completeLastToken(prefix, KNOWN_BROADSIDE_TOKENS.map((value) => ({ value }))),
         handler: async (args, ctx) => {
             const flags = parseBroadsideFlags(args);
             if (flags.unknown.length > 0) {
@@ -1439,12 +1428,7 @@ export default function codeCartographerExtension(pi) {
     });
     pi.registerCommand("codecarto-dashboard", {
         description: "Regenerate .codecarto/dashboard.html (use --narrate for an LLM executive summary)",
-        getArgumentCompletions: (prefix) => {
-            const items = ["--narrate"]
-                .filter((value) => value.startsWith(prefix))
-                .map((value) => ({ value, label: value }));
-            return items.length > 0 ? items : null;
-        },
+        getArgumentCompletions: (prefix) => completeLastToken(prefix, [{ value: "--narrate" }]),
         handler: async (args, ctx) => {
             const flags = parseDashboardFlags(args);
             if (flags.unknown.length > 0) {
@@ -1515,10 +1499,7 @@ export default function codeCartographerExtension(pi) {
         description: "Apply a post-pipeline amendment from .codecarto/scratch/amendments/, after a preview: /codecarto-amend <name | scratch/amendments/name.yaml>",
         getArgumentCompletions: async (prefix) => {
             const names = await listAmendmentNames(join(sessionCwd ?? process.cwd(), ".codecarto"));
-            const items = names
-                .filter((value) => value.startsWith(prefix))
-                .map((value) => ({ value, label: value }));
-            return items.length > 0 ? items : null;
+            return completeLastToken(prefix, names.map((value) => ({ value })));
         },
         handler: async (args, ctx) => {
             const state = await ensureWorkspaceState(ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.22.2",
+  "version": "0.23.0",
   "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",