codecartographer-pi 0.12.3 → 0.12.9

package/.codecarto/findings/vision-capture/INTERVIEW.md

@@ -0,0 +1,80 @@
+---
+name: guided-vision-interview
+description: Conduct a structured product discovery interview to extract a rich vision brief from the user before the synthesis pipeline's vision-capture phase.
+---
+
+# Guided Vision Interview
+
+Your job is to conduct a conversational product discovery interview that draws out the user's product idea and writes it into `inputs/vision.md` as a rich brief. The synthesis pipeline's vision-capture phase will then structure this brief into a testable vision document.
+
+## Interview structure
+
+Ask questions in this order. Do not dump all questions at once — ask one or two at a time, wait for the answer, then probe deeper based on what the user said. Skip questions the user has already answered unprompted.
+
+### 1. Audience and problem (2-3 questions)
+- Who specifically is this for? (Not "everyone" — get them to name a concrete persona or team)
+- What problem does this solve for them? What are they doing today, and why is it painful?
+- Why are existing solutions insufficient? What's the gap?
+
+### 2. Desired outcomes (2-3 questions)
+- What should the user be able to do that they can't today?
+- What does success look like? How would they know it worked?
+- What's the most important outcome — the one thing that must work?
+
+### 3. Scope and non-goals (2-3 questions)
+- What's explicitly in scope for this version?
+- What are you deliberately NOT building? What's a non-goal?
+- Is there anything you're tempted to include but know you should defer?
+
+### 4. Constraints (2-3 questions)
+- Any hard technical constraints? (language, platform, integration, performance)
+- Any operational constraints? (self-hosted, cloud, offline, privacy, latency)
+- Any timeline or team-size constraints?
+
+### 5. Success measures and acceptance (1-2 questions)
+- How would you measure success? What metric or observation would tell you it's working?
+- Can you describe one specific scenario where someone uses this and has a good experience?
+
+## Writing the brief
+
+After the interview, synthesize the user's answers into `inputs/vision.md`. Use this structure:
+
+```markdown
+# Vision brief
+
+## Audience
+- Who: [specific persona]
+- Current approach: [what they do today]
+- Pain: [why it's painful]
+
+## Problem
+[2-3 sentences describing the core problem]
+
+## Desired outcomes
+- [outcome 1]
+- [outcome 2]
+- [outcome 3, if any]
+
+## Scope
+- In scope: [list]
+- Non-goals: [list]
+
+## Constraints
+- [constraint 1]
+- [constraint 2, if any]
+
+## Success measures
+- [measure 1]
+- [acceptance scenario, if provided]
+
+## Assumptions and open decisions
+- [anything the user was unsure about — mark as assumption or needs-decision]
+```
+
+## Rules
+
+- Do not invent product decisions the user didn't make. If something is unclear, ask. If they're unsure, record it as an assumption.
+- Keep the interview conversational — not a form. Follow up on vague answers with a specific probe.
+- If the user gives a very detailed answer up front, skip the questions they already covered and go deeper on the gaps.
+- Do not select library entries or discuss implementation in this interview. That comes later in the synthesis pipeline.
+- After writing the brief, tell the user they can now run `/codecarto-init synthesis` followed by `/codecarto-next` to start the synthesis pipeline.

package/README.md

@@ -222,7 +222,7 @@ The default is a 7-phase run that splits the defect scan into a mechanical early
 | **Architecture only** | 1 | Quick structural overview |
 | **Synthesis** | 4 | Turn a product vision and confirmed library specifications into a provenance-backed implementation plan |
 
-Set the active pipeline by editing `workflow/status.yaml`'s `pipeline:` field, or pass it as the argument to `/codecarto-init`.
+Switch the active pipeline with `/codecarto-switch-pipeline <variant>` (Pi) or `codecarto_switch_pipeline` (MCP). This rewrites `status.yaml` in-place without deleting findings, handoffs, usage data, or closeouts. Phases that exist in both the old and new pipelines preserve their completion status.
 
 **On disk:**
 
@@ -287,6 +287,8 @@ Beyond the slash commands, the Pi extension layers on:
 |---|---|
 | `/codecarto-init [variant]` | Copy `.codecarto/` into the current repository, select pipeline variant |
 | `/codecarto-open` | Activate an existing `.codecarto/` workspace in a new Pi session without resetting durable state |
+| `/codecarto-vision` | Run a guided product discovery interview to produce `inputs/vision.md` for the synthesis pipeline |
+| `/codecarto-switch-pipeline <variant>` | Switch the active pipeline in-place without losing findings or progress |
 | `/codecarto-status` | Current phase, progress, open questions |
 | `/codecarto-next [--auto [--strict]] [--llm-steer \| --no-llm-steer]` | Spawn the next eligible phase as a sub-agent. After the sub-agent finishes, auto-validates and auto-completes the phase so `status.yaml` advances without manual steps. `--auto` walks the full pipeline end-to-end (same validate + complete + advance loop, repeated); `--strict` flips the `PASS WITH GAPS` rule from "advance" to "pause". |
 | `/codecarto-phase <id>` | Force a specific phase, even out of pipeline order |
@@ -294,6 +296,8 @@ Beyond the slash commands, the Pi extension layers on:
 | `/codecarto-complete [phase]` | Validate and atomically apply the phase handoff, canonical status, closeout, and log entry |
 | `/codecarto-skill <name>` | Run a post-pipeline skill once all phases are complete |
 | `/codecarto-publish` | Publish the reimplementation spec to the configured library after reviewing an explicit confirmation preview |
+| `/codecarto-library-init <path> [--namespace <name>]` | Create a library directory with marker and write the config — fixes the first-publish dead end |
+| `/codecarto-config` | Show the effective merged configuration (global + workspace) and library marker status |
 | `/codecarto-usage` | Cumulative + per-phase token usage |
 | `/codecarto-dashboard [--narrate]` | Regenerate `.codecarto/dashboard.html`; `--narrate` for the LLM executive summary |
 

package/dist/core/library.d.ts

@@ -78,6 +78,27 @@ export interface LibraryIndex {
 export declare function discoverLibrary(libraryPath: string): Promise<LibraryMarker | null>;
 export declare function readMarker(libraryRoot: string): Promise<LibraryMarker | null>;
 export declare function writeMarker(libraryRoot: string, marker: LibraryMarker): Promise<void>;
+export interface InitLibraryOptions {
+    /** Library name (defaults to basename of the path). */
+    name?: string;
+    /** Visibility level. Default "internal". */
+    visibility?: LibraryVisibility;
+    /** Whether this is a namespaced (shared) library. Default false. */
+    namespaced?: boolean;
+}
+export interface InitLibraryResult {
+    libraryPath: string;
+    marker: LibraryMarker;
+    /** True if the marker already existed (idempotent re-run). */
+    alreadyExisted: boolean;
+}
+/**
+ * Initialize a CodeCartographer library at the given path: create the
+ * directory if needed, write the `.codecarto-library` marker if missing,
+ * and return the marker. Idempotent — re-running on an existing library
+ * is safe and preserves the existing marker.
+ */
+export declare function initLibrary(libraryPath: string, options?: InitLibraryOptions): Promise<InitLibraryResult>;
 export declare function isValidSlug(slug: string): boolean;
 /**
  * Derive a slug from a source repo URL or path. The last meaningful path

package/dist/core/library.js

@@ -25,7 +25,7 @@
 import { createHash } from "node:crypto";
 import { spawn } from "node:child_process";
 import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { basename, join, resolve } from "node:path";
 import { isPlainObject, pathExists } from "./utils.js";
 import { parseSimpleYaml, stringifySimpleYaml } from "./yaml.js";
 // ─── Constants ──────────────────────────────────────────────────────────────
@@ -86,6 +86,28 @@ function normalizeMarker(raw) {
 function isVisibility(v) {
     return v === "internal" || v === "shared" || v === "public";
 }
+/**
+ * Initialize a CodeCartographer library at the given path: create the
+ * directory if needed, write the `.codecarto-library` marker if missing,
+ * and return the marker. Idempotent — re-running on an existing library
+ * is safe and preserves the existing marker.
+ */
+export async function initLibrary(libraryPath, options = {}) {
+    const existing = await discoverLibrary(libraryPath);
+    if (existing) {
+        return { libraryPath, marker: existing, alreadyExisted: true };
+    }
+    const name = options.name?.trim() || basename(libraryPath);
+    const marker = {
+        schema_version: MARKER_SCHEMA_VERSION,
+        name,
+        namespaced: options.namespaced ?? false,
+        visibility: options.visibility ?? "internal",
+        created_at: new Date().toISOString(),
+    };
+    await writeMarker(libraryPath, marker);
+    return { libraryPath, marker, alreadyExisted: false };
+}
 // ─── Slug helpers ───────────────────────────────────────────────────────────
 export function isValidSlug(slug) {
     if (typeof slug !== "string")

package/dist/core/orchestrator-config.d.ts

@@ -55,4 +55,10 @@ export declare function loadUserConfig(): Promise<CodecartoConfig>;
  * a layer in memory (e.g. "what if library_path were X").
  */
 export declare function mergeConfig(raw: RawConfig | null | undefined): CodecartoConfig;
+/**
+ * Write a `library:` block into a config file (user-global or workspace).
+ * Creates the file and parent directories if needed. Preserves any existing
+ * `orchestrator:` block. Overwrites the `library:` block if present.
+ */
+export declare function writeLibraryConfig(configPath: string, libraryPath: string, namespace?: string | null, publishConfirm?: boolean): Promise<void>;
 export {};

package/dist/core/orchestrator-config.js

@@ -15,8 +15,9 @@
 // don't have to expand themselves.
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { expandTilde, pathExists } from "./utils.js";
-import { loadYamlFile } from "./yaml.js";
+import { loadYamlFile, parseSimpleYaml, stringifySimpleYaml } from "./yaml.js";
 export const CONFIG_RELATIVE_PATH = "workflow/config.yaml";
 export const USER_CONFIG_DIR = join(homedir(), ".codecarto");
 export const USER_CONFIG_PATH = join(USER_CONFIG_DIR, "config.yaml");
@@ -110,3 +111,27 @@ function cloneDefault() {
         library: { ...DEFAULT_CONFIG.library },
     };
 }
+/**
+ * Write a `library:` block into a config file (user-global or workspace).
+ * Creates the file and parent directories if needed. Preserves any existing
+ * `orchestrator:` block. Overwrites the `library:` block if present.
+ */
+export async function writeLibraryConfig(configPath, libraryPath, namespace = null, publishConfirm = true) {
+    let existing = {};
+    if (await pathExists(configPath)) {
+        try {
+            const raw = await readFile(configPath, "utf8");
+            existing = parseSimpleYaml(raw);
+        }
+        catch {
+            // Malformed file — start fresh
+        }
+    }
+    const library = { path: libraryPath, publish_confirm: publishConfirm };
+    if (namespace)
+        library.namespace = namespace;
+    const updated = { ...existing, library };
+    const dir = configPath.includes("/") ? configPath.slice(0, configPath.lastIndexOf("/")) : ".";
+    await mkdir(dir, { recursive: true });
+    await writeFile(configPath, `${stringifySimpleYaml(updated)}\n`, "utf8");
+}

package/dist/core/synthesis.js

@@ -78,25 +78,25 @@ export async function runPhasePreflight(state, phase) {
     if (checks.has("requires-vision-input")) {
         const visionPath = join(state.workspaceDir, SYNTHESIS_VISION_INPUT_PATH);
         if (!(await pathExists(visionPath))) {
-            throw new PhasePreflightError(phase.id, `the vision brief is missing at .codecarto/${SYNTHESIS_VISION_INPUT_PATH}. Create it before starting synthesis.`);
+            throw new PhasePreflightError(phase.id, `the vision brief is missing at .codecarto/${SYNTHESIS_VISION_INPUT_PATH}. Create that file and describe your product intent (audience, problem, desired outcome, constraints, non-goals). See .codecarto/templates/vision.md for the expected structure.`);
         }
         const rawVision = await readFile(visionPath, "utf8");
         if (!hasMeaningfulVisionContent(rawVision)) {
-            throw new PhasePreflightError(phase.id, `the vision brief at .codecarto/${SYNTHESIS_VISION_INPUT_PATH} is still empty. Describe the audience, problem, and desired outcome, then retry.`);
+            throw new PhasePreflightError(phase.id, `the vision brief at .codecarto/${SYNTHESIS_VISION_INPUT_PATH} appears to be empty or only contains comments. Write your product intent into that file — at minimum: who the product is for, what problem it solves, and what outcome you want. See .codecarto/templates/vision.md for the full structure.`);
         }
     }
     if (checks.has("requires-library")) {
         const config = await loadCodecartoConfig(state.workspaceDir);
         if (!config.library.path) {
-            throw new PhasePreflightError(phase.id, "no library.path is configured. Set it in ~/.codecarto/config.yaml or .codecarto/workflow/config.yaml.");
+            throw new PhasePreflightError(phase.id, "no library.path is configured. Create a library directory with a .codecarto-library marker file, then set library.path in ~/.codecarto/config.yaml or .codecarto/workflow/config.yaml. Example config:\n  library:\n    path: ~/codecarto-library\n    publish_confirm: true");
         }
         const marker = await discoverLibrary(config.library.path);
         if (!marker) {
-            throw new PhasePreflightError(phase.id, `no CodeCartographer library was found at ${config.library.path} (missing .codecarto-library).`);
+            throw new PhasePreflightError(phase.id, `no CodeCartographer library was found at ${config.library.path} (missing .codecarto-library). Create a .codecarto-library marker file in that directory with: {"schema_version": 1, "name": "personal-library", "visibility": "internal", "namespaced": false}`);
         }
         const entries = await listEntries(config.library.path);
         if (entries.length === 0) {
-            throw new PhasePreflightError(phase.id, `the configured library at ${config.library.path} has no entries. Publish at least one reimplementation spec first.`);
+            throw new PhasePreflightError(phase.id, `the configured library at ${config.library.path} has no entries. Run a reverse-engineering pipeline (e.g. /codecarto-init full-with-deep-audit) on a source repository, then use /codecarto-publish to publish at least one reimplementation spec into the library before starting synthesis.`);
         }
         result.libraryPath = config.library.path;
         result.libraryName = marker.name;
@@ -110,13 +110,13 @@ export async function runPhasePreflight(state, phase) {
         result.confirmedSelections = parseConfirmedProposalSelections(await readFile(proposalPath, "utf8"));
         result.confirmedEntries = result.confirmedSelections.map((selection) => selection.ref);
         if (result.confirmedSelections.length === 0) {
-            throw new PhasePreflightError(phase.id, `no library entries are confirmed in .codecarto/${SYNTHESIS_PROPOSAL_PATH}. Change at least one [ ] checkbox to [x], then retry.`);
+            throw new PhasePreflightError(phase.id, `no library entries are confirmed in .codecarto/${SYNTHESIS_PROPOSAL_PATH}. Open that file and change at least one [ ] checkbox to [x] for the entry you want to include, then retry.`);
         }
         const available = new Map(result.libraryEntries.map((entry) => [entry.ref, entry]));
         for (const selection of result.confirmedSelections) {
             const entry = available.get(selection.ref);
             if (!entry || !entry.versions.includes(selection.version)) {
-                throw new PhasePreflightError(phase.id, `confirmed selection ${selection.ref}@v${selection.version} is not present in the configured library. Re-run the proposal phase or correct the checked row.`);
+                throw new PhasePreflightError(phase.id, `confirmed selection ${selection.ref}@v${selection.version} is not present in the configured library. Edit .codecarto/${SYNTHESIS_PROPOSAL_PATH} to correct the checked row (change [x] back to [ ] or update the version), or re-run the goal-synthesis-propose phase to regenerate the proposal.`);
             }
             selection.specPath = specPathForVersion(result.libraryPath, selection.ref, selection.version);
         }

package/dist/core/workspace.d.ts

@@ -11,3 +11,17 @@ export declare function updateStatusAtomically(cwd: string, updater: (state: Wor
     handoff?: PhaseHandoff;
     threadLogEntry?: string;
 }): Promise<WorkspaceState>;
+/**
+ * Switch the active pipeline in-place without deleting findings, handoffs,
+ * usage data, closeouts, or checkpoints. Phases that exist in both the old
+ * and new pipelines preserve their completion status, owner notes, open
+ * questions, and carry-forward entries. Phases unique to the new pipeline
+ * start as pending. Phases unique to the old pipeline are dropped from
+ * status.yaml (but their findings remain on disk under findings/).
+ */
+export declare function switchPipeline(cwd: string, newPipelinePath: string): Promise<{
+    state: WorkspaceState;
+    carried: string[];
+    dropped: string[];
+    newPhases: string[];
+}>;

package/dist/core/workspace.js

@@ -4,9 +4,9 @@
 // atomic status-update primitive used by /codecarto-complete.
 import { existsSync, readFileSync } from "node:fs";
 import { appendFile, readFile, rename, writeFile } from "node:fs/promises";
-import { dirname, join, relative } from "node:path";
+import { basename, dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
-import { acquireLock, applyHandoff, normalizeStatus, parseHandoff } from "./status.js";
+import { acquireLock, applyHandoff, createEmptyStatus, normalizeStatus, parseHandoff } from "./status.js";
 import { pathExists } from "./utils.js";
 import { loadYamlFile, stringifySimpleYaml } from "./yaml.js";
 // Walk up from the current file to find the package root. Needed because the
@@ -129,3 +129,58 @@ export async function updateStatusAtomically(cwd, updater) {
         await lock.release();
     }
 }
+/**
+ * Switch the active pipeline in-place without deleting findings, handoffs,
+ * usage data, closeouts, or checkpoints. Phases that exist in both the old
+ * and new pipelines preserve their completion status, owner notes, open
+ * questions, and carry-forward entries. Phases unique to the new pipeline
+ * start as pending. Phases unique to the old pipeline are dropped from
+ * status.yaml (but their findings remain on disk under findings/).
+ */
+export async function switchPipeline(cwd, newPipelinePath) {
+    const workspaceDir = join(cwd, ".codecarto");
+    const statusPath = join(workspaceDir, "workflow", "status.yaml");
+    const lockPath = `${statusPath}.lock`;
+    const lock = await acquireLock(lockPath);
+    try {
+        const currentState = await getWorkspaceState(cwd);
+        if (!currentState) {
+            throw new Error("CodeCartographer workspace not found. Run /codecarto-init first.");
+        }
+        const resolvedPipelinePath = join(workspaceDir, newPipelinePath);
+        if (!(await pathExists(resolvedPipelinePath))) {
+            throw new Error(`Pipeline not found: ${newPipelinePath}`);
+        }
+        const newPipeline = await loadYamlFile(resolvedPipelinePath);
+        const freshStatus = createEmptyStatus(basename(cwd), newPipelinePath, newPipeline);
+        // Preserve phase data for phases that exist in both old and new pipelines.
+        const carried = [];
+        const oldPhases = currentState.status.phases;
+        for (const phaseId of newPipeline.phase_order) {
+            if (oldPhases[phaseId]) {
+                freshStatus.phases[phaseId] = { ...oldPhases[phaseId] };
+                if (oldPhases[phaseId].status === "complete") {
+                    carried.push(phaseId);
+                }
+            }
+        }
+        // Track phases that were in the old pipeline but not the new one.
+        const dropped = currentState.pipeline.phase_order.filter((phaseId) => !newPipeline.phase_order.includes(phaseId));
+        const newPhases = newPipeline.phase_order.filter((phaseId) => !currentState.pipeline.phase_order.includes(phaseId));
+        // Preserve post_pipeline entries from the old status.
+        freshStatus.post_pipeline = currentState.status.post_pipeline;
+        freshStatus.last_updated = new Date().toISOString();
+        assertCanonicalStatus(freshStatus);
+        const serialized = `${stringifySimpleYaml(freshStatus)}\n`;
+        const tempPath = `${statusPath}.${process.pid}.${Date.now()}.tmp`;
+        await writeFile(tempPath, serialized, "utf8");
+        await rename(tempPath, statusPath);
+        const state = await getWorkspaceState(cwd);
+        if (!state)
+            throw new Error("Failed to reload workspace state after pipeline switch.");
+        return { state, carried, dropped, newPhases };
+    }
+    finally {
+        await lock.release();
+    }
+}

package/dist/extensions/codecarto/index.js

@@ -1,4 +1,5 @@
-import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { cp, 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";
 import { disposeAgentsWidget } from "./agent-widget.js";
@@ -7,7 +8,9 @@ import { narrateDashboard } from "./dashboard-narrator.js";
 import { writeDashboard } from "./dashboard-writer.js";
 import { parseNextFlags } from "./next-flags.js";
 import { phaseCompactionExtension } from "./phase-compaction.js";
-import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPath, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, packagedWorkspaceDir, pathExists, PACKAGE_VERSION, PhasePreflightError, PIPELINE_ALIASES, publishEntry, resolvePhase, resolvePipelineChoice, runPhasePreflight, stringifySimpleYaml, validatePhaseOutput, } from "../../core/index.js";
+import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPath, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, packagedWorkspaceDir, pathExists, PACKAGE_VERSION, PhasePreflightError, PIPELINE_ALIASES, publishEntry, resolvePhase, resolvePipelineChoice, runPhasePreflight, 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";
 const STATUS_LINE_ID = "codecarto-status";
 const SAFE_TOOL_NAMES = ["read", "grep", "find", "ls", "edit", "write"];
@@ -195,6 +198,36 @@ export default function codeCartographerExtension(pi) {
             }
         },
     });
+    pi.registerCommand("codecarto-vision", {
+        description: "Run a guided product discovery interview to produce inputs/vision.md for the synthesis pipeline",
+        handler: async (_args, ctx) => {
+            const interviewPath = join(ctx.cwd, ".codecarto", "findings", "vision-capture", "INTERVIEW.md");
+            if (!(await pathExists(interviewPath))) {
+                ctx.ui.notify("Vision interview skill not found. Run /codecarto-init synthesis first.", "warning");
+                return;
+            }
+            const interviewSkill = await readFile(interviewPath, "utf8");
+            const inputsDir = join(ctx.cwd, ".codecarto", "inputs");
+            const visionPath = join(inputsDir, "vision.md");
+            const visionExists = await pathExists(visionPath);
+            const prompt = [
+                "Read the interview skill below and conduct a guided product discovery interview with the user.",
+                "",
+                interviewSkill,
+                "",
+                `The vision brief should be written to .codecarto/inputs/vision.md${visionExists ? " (it already exists — review and improve it based on the interview)" : " (it does not exist yet — create it)"}.`,
+                "After the interview, write the synthesized brief and tell the user to run /codecarto-init synthesis followed by /codecarto-next to start the pipeline.",
+            ].join("\n");
+            if (ctx.isIdle()) {
+                pi.sendUserMessage(prompt);
+            }
+            else {
+                pi.sendUserMessage(prompt, { deliverAs: "followUp" });
+            }
+            lastFeedbackLines = ["Vision interview started — answer the questions in chat."];
+            ctx.ui.notify("Vision interview queued — answer the questions in the chat.", "info");
+        },
+    });
     pi.registerCommand("codecarto-init", {
         description: "Initialize .codecarto/ in the current repository",
         getArgumentCompletions: (prefix) => {
@@ -220,10 +253,13 @@ export default function codeCartographerExtension(pi) {
             if (targetExists) {
                 const sameWorkspace = normalizeForComparison(await canonicalPath(targetWorkspaceDir)) === normalizeForComparison(await canonicalPath(sourceWorkspaceDir));
                 if (!sameWorkspace) {
-                    const overwrite = await ctx.ui.confirm("CodeCartographer already exists", "A .codecarto/ directory already exists in this repository. Overwrite it?");
+                    const overwrite = await ctx.ui.confirm("CodeCartographer already exists — data will be lost", "A .codecarto/ directory already exists in this repository. Re-initializing will back up the existing workspace to .codecarto-backup-TIMESTAMP/ and create a fresh one. All phase findings, handoffs, usage data, closeouts, and progress will be moved to the backup. Consider /codecarto-open to reattach without resetting. Continue?");
                     if (!overwrite)
                         return;
-                    await rm(targetWorkspaceDir, { recursive: true, force: true });
+                    const backupDir = join(ctx.cwd, `.codecarto-backup-${new Date().toISOString().replace(/[:.]/g, "-")}`);
+                    await rename(targetWorkspaceDir, backupDir);
+                    if (ctx.hasUI)
+                        ctx.ui.notify(`Backed up existing workspace to ${basename(backupDir)}/`, "info");
                 }
             }
             if (!(await pathExists(targetWorkspaceDir))) {
@@ -265,6 +301,57 @@ export default function codeCartographerExtension(pi) {
             ctx.ui.notify(`CodeCartographer phase: ${nextPhase}`, "info");
         },
     });
+    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;
+        },
+        handler: async (args, ctx) => {
+            const trimmedArgs = args.trim();
+            if (!trimmedArgs) {
+                ctx.ui.notify("Usage: /codecarto-switch-pipeline <variant> (e.g. lite, full, synthesis)", "warning");
+                return;
+            }
+            const pipelineChoice = resolvePipelineChoice(trimmedArgs);
+            if (!pipelineChoice) {
+                ctx.ui.notify(`Unknown pipeline: ${trimmedArgs}`, "error");
+                return;
+            }
+            const state = await ensureWorkspaceState(ctx);
+            if (!state)
+                return;
+            const currentPipeline = state.status.pipeline;
+            if (currentPipeline === pipelineChoice) {
+                ctx.ui.notify(`Already on pipeline: ${getPipelineLabel(pipelineChoice)}`, "info");
+                return;
+            }
+            try {
+                const result = await switchPipeline(ctx.cwd, pipelineChoice);
+                const lines = [
+                    `Switched pipeline: ${getPipelineLabel(pipelineChoice)}`,
+                ];
+                if (result.carried.length > 0)
+                    lines.push(`Phases preserved (completed): ${result.carried.join(", ")}`);
+                if (result.newPhases.length > 0)
+                    lines.push(`New phases: ${result.newPhases.join(", ")}`);
+                if (result.dropped.length > 0)
+                    lines.push(`Phases not in new pipeline: ${result.dropped.join(", ")} (findings remain on disk)`);
+                lastFeedbackLines = lines;
+                await refreshWorkspaceUi(ctx, lastFeedbackLines);
+                ctx.ui.notify(`Switched to pipeline: ${getPipelineLabel(pipelineChoice)}`, "info");
+                void writeDashboard(ctx.cwd, PACKAGE_VERSION);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                lastFeedbackLines = [message];
+                setUiState(ctx, state, lastFeedbackLines);
+                ctx.ui.notify(message, "error");
+            }
+        },
+    });
     pi.registerCommand("codecarto-next", {
         description: "Run the next eligible CodeCartographer phase as a sub-agent. Flags: --llm-steer / --no-llm-steer / --auto [--strict]",
         getArgumentCompletions: (prefix) => {
@@ -538,12 +625,12 @@ export default function codeCartographerExtension(pi) {
                 return;
             const config = await loadCodecartoConfig(state.workspaceDir);
             if (!config.library.path) {
-                ctx.ui.notify("No library.path is configured. Set it in ~/.codecarto/config.yaml or .codecarto/workflow/config.yaml.", "error");
+                ctx.ui.notify("No library.path is configured. Create a library directory with a .codecarto-library marker, then set library.path in ~/.codecarto/config.yaml or .codecarto/workflow/config.yaml.", "error");
                 return;
             }
             const marker = await discoverLibrary(config.library.path);
             if (!marker) {
-                ctx.ui.notify(`No CodeCartographer library at ${config.library.path} (missing .codecarto-library).`, "error");
+                ctx.ui.notify(`No CodeCartographer library at ${config.library.path} (missing .codecarto-library). Create a .codecarto-library marker file in that directory.`, "error");
                 return;
             }
             const phase = resolvePhase(state, "reimplementation-spec");
@@ -597,6 +684,66 @@ export default function codeCartographerExtension(pi) {
             }
         },
     });
+    pi.registerCommand("codecarto-library-init", {
+        description: "Initialize a CodeCartographer library and configure it: /codecarto-library-init <path> [--namespace <name>]",
+        handler: async (args, ctx) => {
+            const parts = args.trim().split(/\s+/);
+            const pathArg = parts[0];
+            const namespaceIdx = parts.indexOf("--namespace");
+            const namespace = namespaceIdx >= 0 ? parts[namespaceIdx + 1] : null;
+            if (!pathArg) {
+                ctx.ui.notify("Usage: /codecarto-library-init <path> [--namespace <name>]", "warning");
+                return;
+            }
+            const libraryPath = pathArg.startsWith("~") ? join(homedir(), pathArg.slice(1)) : resolve(pathArg);
+            try {
+                const result = await initLibrary(libraryPath, {
+                    namespaced: !!namespace,
+                    ...(namespace ? {} : {}),
+                });
+                // Write the config to the user-global location
+                const configPath = resolveUserConfigPath();
+                await writeLibraryConfig(configPath, libraryPath, namespace);
+                const msg = result.alreadyExisted
+                    ? `Library already exists at ${libraryPath} (marker preserved). Config updated.`
+                    : `Created library at ${libraryPath} with marker "${result.marker.name}".`;
+                lastFeedbackLines = [msg, `Config written to ${configPath}`];
+                if (ctx.hasUI) {
+                    ctx.ui.notify(msg, "info");
+                    ctx.ui.notify(`Config written to ${configPath}`, "info");
+                }
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                ctx.ui.notify(`Library init failed: ${message}`, "error");
+            }
+        },
+    });
+    pi.registerCommand("codecarto-config", {
+        description: "Show the effective merged CodeCartographer configuration (global + workspace)",
+        handler: async (_args, ctx) => {
+            const state = await ensureWorkspaceState(ctx);
+            const config = await loadCodecartoConfig(state ? state.workspaceDir : join(ctx.cwd, ".codecarto"));
+            const lines = [
+                "Effective CodeCartographer configuration:",
+                `  library.path: ${config.library.path ?? "(not set)"}`,
+                `  library.namespace: ${config.library.namespace ?? "(not set)"}`,
+                `  library.publish_confirm: ${config.library.publish_confirm}`,
+                `  orchestrator.llm_steer_next_phase: ${config.orchestrator.llm_steer_next_phase}`,
+                "",
+                `  User-global config: ${resolveUserConfigPath()}`,
+                `  Workspace config: ${state ? join(state.workspaceDir, "workflow/config.yaml") : "(no workspace)"}`,
+            ];
+            if (config.library.path) {
+                const marker = await discoverLibrary(config.library.path);
+                lines.push(`  Library marker: ${marker ? `found ("${marker.name}", namespaced: ${marker.namespaced})` : "MISSING — run /codecarto-library-init"}`);
+            }
+            lastFeedbackLines = lines;
+            if (state)
+                setUiState(ctx, state, lastFeedbackLines);
+            ctx.ui.notify("Configuration shown in status widget.", "info");
+        },
+    });
     pi.registerCommand("codecarto-usage", {
         description: "Show cumulative + per-phase token usage from local phase runs",
         handler: async (_args, ctx) => {

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

@@ -19,6 +19,16 @@ export declare function handleStatus(args: {
     }>;
     structuredContent?: Record<string, unknown>;
 }>;
+export declare function handleSwitchPipeline(args: {
+    cwd: string;
+    pipeline: string;
+}): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+}>;
 export declare function handleNext(args: {
     cwd: string;
 }): Promise<{
@@ -89,6 +99,73 @@ export declare function handleLibraryReindex(args: Record<string, unknown>): Pro
     }>;
     structuredContent?: Record<string, unknown>;
 }>;
+export declare function handleLibraryInit(args: {
+    library_path: string;
+    name?: string;
+    namespace?: string;
+    cwd?: string;
+}): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+}>;
+export declare function handleVision(args: {
+    cwd: string;
+    raw_text: string;
+}): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+}>;
+export declare function handleConfig(args: {
+    cwd?: string;
+}): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+}>;
+export declare function handleOpen(args: {
+    cwd: string;
+}): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+}>;
+export declare function handleUsage(args: {
+    cwd: string;
+}): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+}>;
+export declare function handleDashboard(args: {
+    cwd: string;
+}): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+}>;
+export declare function handleListSkills(args: {
+    cwd: string;
+}): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+}>;
 export declare function buildServer(): Server<{
     method: string;
     params?: {

package/dist/mcp-server/server.js

@@ -13,9 +13,12 @@
 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, rm, writeFile } from "node:fs/promises";
+import { cp, mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { basename, isAbsolute, join } from "node:path";
-import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, completeValidatedPhase, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isValidSlug, listEntries, listSkillNames, loadCodecartoConfig, loadYamlFile, normalizeForComparison, PACKAGE_VERSION, packagedWorkspaceDir, pathExists, PhasePreflightError, publishEntry, reindex as libraryReindex, resolvePhase, resolvePipelineChoice, stringifySimpleYaml, validatePhaseOutput, } from "../core/index.js";
+import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, completeValidatedPhase, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, deriveSlug, discoverLibrary, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isValidSlug, listEntries, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, PACKAGE_VERSION, packagedWorkspaceDir, pathExists, PhasePreflightError, publishEntry, reindex as libraryReindex, resolvePhase, resolvePipelineChoice, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, } from "../core/index.js";
+import { initLibrary } from "../core/library.js";
+import { loadUserConfig, resolveUserConfigPath } from "../core/orchestrator-config.js";
+import { writeDashboard } from "../extensions/codecarto/dashboard-writer.js";
 // ---------- input helpers ----------
 async function validateCwd(cwd) {
     if (typeof cwd !== "string" || !cwd.trim()) {
@@ -77,9 +80,10 @@ export async function handleInit(args) {
     }
     if (targetExists && !sameWorkspace) {
         if (!args.force) {
-            throw new McpError(ErrorCode.InvalidRequest, `A .codecarto/ directory already exists at ${targetWorkspaceDir}. Pass force: true to overwrite it.`);
+            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.`);
         }
-        await rm(targetWorkspaceDir, { recursive: true, force: true });
+        const backupDir = join(cwd, `.codecarto-backup-${new Date().toISOString().replace(/[:.]/g, "-")}`);
+        await rename(targetWorkspaceDir, backupDir);
     }
     if (!(await pathExists(targetWorkspaceDir))) {
         await mkdir(cwd, { recursive: true });
@@ -137,6 +141,31 @@ export async function handleStatus(args) {
         nextActions: state.status.next_actions,
     });
 }
+export async function handleSwitchPipeline(args) {
+    const cwd = await validateCwd(args.cwd);
+    const state = await requireWorkspace(cwd);
+    const pipelineChoice = resolvePipelineChoice(args.pipeline);
+    if (!pipelineChoice) {
+        throw new McpError(ErrorCode.InvalidRequest, `Unknown pipeline: ${args.pipeline}`);
+    }
+    if (state.status.pipeline === pipelineChoice) {
+        return textResult(`Already on pipeline: ${getPipelineLabel(pipelineChoice)}`, { pipeline: getPipelineLabel(pipelineChoice) });
+    }
+    const result = await switchPipeline(cwd, pipelineChoice);
+    const lines = [`Switched pipeline: ${getPipelineLabel(pipelineChoice)}`];
+    if (result.carried.length > 0)
+        lines.push(`Phases preserved (completed): ${result.carried.join(", ")}`);
+    if (result.newPhases.length > 0)
+        lines.push(`New phases: ${result.newPhases.join(", ")}`);
+    if (result.dropped.length > 0)
+        lines.push(`Phases not in new pipeline: ${result.dropped.join(", ")} (findings remain on disk)`);
+    return textResult(lines.join("\n"), {
+        pipeline: getPipelineLabel(pipelineChoice),
+        carried: result.carried,
+        newPhases: result.newPhases,
+        dropped: result.dropped,
+    });
+}
 export async function handleNext(args) {
     const cwd = await validateCwd(args.cwd);
     const state = await requireWorkspace(cwd);
@@ -459,11 +488,144 @@ export async function handleLibraryReindex(args) {
         namespaces: index.namespaces,
     });
 }
+export async function handleLibraryInit(args) {
+    if (!args.library_path || typeof args.library_path !== "string") {
+        throw new McpError(ErrorCode.InvalidParams, "library_path is required.");
+    }
+    const libraryPath = args.library_path;
+    const namespaced = !!args.namespace;
+    const result = await initLibrary(libraryPath, {
+        name: args.name,
+        namespaced,
+    });
+    // Write config to user-global location
+    const configPath = resolveUserConfigPath();
+    await writeLibraryConfig(configPath, libraryPath, args.namespace ?? null);
+    const msg = result.alreadyExisted
+        ? `Library already exists at ${libraryPath} (marker preserved). Config written to ${configPath}.`
+        : `Created library at ${libraryPath} with marker "${result.marker.name}". Config written to ${configPath}.`;
+    return textResult(msg, {
+        libraryPath,
+        markerName: result.marker.name,
+        namespaced: result.marker.namespaced,
+        alreadyExisted: result.alreadyExisted,
+        configPath,
+    });
+}
+export async function handleVision(args) {
+    const cwd = await validateCwd(args.cwd);
+    const workspaceDir = join(cwd, ".codecarto");
+    const interviewPath = join(workspaceDir, "findings", "vision-capture", "INTERVIEW.md");
+    const visionPath = join(workspaceDir, "inputs", "vision.md");
+    if (!(await pathExists(interviewPath))) {
+        throw new McpError(ErrorCode.InvalidRequest, "Vision interview skill not found. Run codecarto_init with the synthesis pipeline first.");
+    }
+    const interviewSkill = await readFile(interviewPath, "utf8");
+    const prompt = [
+        "Read the interview skill below and use it to structure the user's raw product text into a vision brief.",
+        "",
+        interviewSkill,
+        "",
+        "The user's raw product text is:",
+        "",
+        args.raw_text,
+        "",
+        `Write the synthesized brief to ${visionPath}.`,
+    ].join("\n");
+    return textResult(prompt, {
+        cwd,
+        visionPath,
+        interviewPath,
+        note: "Feed this prompt to your agent. The agent will write the structured vision brief to inputs/vision.md.",
+    });
+}
+export async function handleConfig(args) {
+    const config = args.cwd
+        ? await loadCodecartoConfig(join(args.cwd, ".codecarto"))
+        : await loadUserConfig();
+    const userConfigPath = resolveUserConfigPath();
+    const workspaceConfigPath = args.cwd ? join(args.cwd, ".codecarto", "workflow", "config.yaml") : null;
+    let markerStatus = "not configured";
+    if (config.library.path) {
+        const marker = await discoverLibrary(config.library.path);
+        markerStatus = marker ? `found ("${marker.name}", namespaced: ${marker.namespaced})` : "MISSING";
+    }
+    return textResult([
+        "Effective CodeCartographer configuration:",
+        `  library.path: ${config.library.path ?? "(not set)"}`,
+        `  library.namespace: ${config.library.namespace ?? "(not set)"}`,
+        `  library.publish_confirm: ${config.library.publish_confirm}`,
+        `  orchestrator.llm_steer_next_phase: ${config.orchestrator.llm_steer_next_phase}`,
+        `  Library marker: ${markerStatus}`,
+        `  User-global config: ${userConfigPath}`,
+        `  Workspace config: ${workspaceConfigPath ?? "(no cwd provided)"}`,
+    ].join("\n"), {
+        libraryPath: config.library.path,
+        libraryNamespace: config.library.namespace,
+        publishConfirm: config.library.publish_confirm,
+        llmSteerNextPhase: config.orchestrator.llm_steer_next_phase,
+        userConfigPath,
+        workspaceConfigPath,
+    });
+}
+// ---------- MCP parity handlers: open, usage, dashboard, list_skills ----------
+export async function handleOpen(args) {
+    const cwd = await validateCwd(args.cwd);
+    const workspaceDir = join(cwd, ".codecarto");
+    if (!(await pathExists(join(workspaceDir, "workflow", "status.yaml")))) {
+        throw new McpError(ErrorCode.InvalidRequest, "No existing CodeCartographer workspace found. Run codecarto_init first.");
+    }
+    const state = await requireWorkspace(cwd);
+    const nextPhase = getNextEligiblePhase(state)?.id ?? "complete";
+    return textResult(`Opened existing CodeCartographer workspace: ${getPipelineLabel(state.status.pipeline)}. Current phase: ${nextPhase}.`, { pipeline: getPipelineLabel(state.status.pipeline), currentPhase: nextPhase });
+}
+export async function handleUsage(args) {
+    const cwd = await validateCwd(args.cwd);
+    const state = await requireWorkspace(cwd);
+    const usage = await loadUsage(state.workspaceDir);
+    if (usage.runs.length === 0) {
+        return textResult("No phase runs recorded yet.", { runs: 0 });
+    }
+    const totals = computeTotals(usage);
+    const perPhase = computePerPhaseTotals(usage);
+    const lines = [
+        `Total runs: ${totals.runs}`,
+        `Total tokens: ${totals.tokens.input} in / ${totals.tokens.output} out / ${totals.tokens.cache_write} cache-write`,
+        `Total duration: ${totals.duration_ms}ms / ${totals.tool_uses} tool uses`,
+        "",
+        "Per-phase totals:",
+    ];
+    for (const [phaseId, t] of perPhase) {
+        lines.push(`  ${phaseId}: ${t.runs} run(s), ${t.tokens.input + t.tokens.output} tokens, ${t.tool_uses} tool uses, ${t.duration_ms}ms`);
+    }
+    return textResult(lines.join("\n"), {
+        runs: totals.runs,
+        tokens: totals.tokens,
+        toolUses: totals.tool_uses,
+        durationMs: totals.duration_ms,
+        perPhase: Object.fromEntries(perPhase),
+    });
+}
+export async function handleDashboard(args) {
+    const cwd = await validateCwd(args.cwd);
+    await requireWorkspace(cwd);
+    await writeDashboard(cwd, PACKAGE_VERSION);
+    return textResult("Dashboard regenerated: .codecarto/dashboard.html", { path: ".codecarto/dashboard.html" });
+}
+export async function handleListSkills(args) {
+    const cwd = await validateCwd(args.cwd);
+    const state = await requireWorkspace(cwd);
+    const skills = await listSkillNames(state.workspaceDir);
+    const lines = skills.length > 0
+        ? [`Available skills (${skills.length}):`, ...skills.map((s) => `  - ${s}`)]
+        : ["No skills installed."];
+    return textResult(lines.join("\n"), { skills });
+}
 // ---------- tool registry ----------
 const TOOLS = [
     {
         name: "codecarto_init",
-        description: "Initialize a CodeCartographer workspace (.codecarto/) in a target repository. Copies the packaged framework template and writes a fresh status.yaml for the chosen pipeline. Errors if .codecarto/ already exists unless force is true.",
+        description: "Initialize a CodeCartographer workspace (.codecarto/) in a target repository. Copies the packaged framework template and writes a fresh status.yaml for the chosen pipeline. If .codecarto/ already exists, pass force: true to back up the existing workspace to .codecarto-backup-TIMESTAMP/ and create a fresh one. Warning: backing up moves all existing findings, handoffs, usage data, closeouts, and phase progress to the backup directory.",
         inputSchema: {
             type: "object",
             properties: {
@@ -474,12 +636,27 @@ const TOOLS = [
                 },
                 force: {
                     type: "boolean",
-                    description: "Overwrite an existing .codecarto/ directory if present (default false).",
+                    description: "Back up and overwrite an existing .codecarto/ directory if present (default false).",
                 },
             },
             required: ["cwd"],
         },
     },
+    {
+        name: "codecarto_switch_pipeline",
+        description: "Switch the active pipeline in-place without losing findings, handoffs, usage data, or phase progress. Phases that exist in both the old and new pipelines preserve their completion status. Phases unique to the new pipeline start as pending. Pass a pipeline alias (e.g. lite, full, synthesis) or a workflow/*.yaml path.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                cwd: { type: "string", description: "Absolute path to the target repository." },
+                pipeline: {
+                    type: "string",
+                    description: "Pipeline alias (e.g. lite, full, synthesis, architecture-only, defect-scan) or workflow/*.yaml path.",
+                },
+            },
+            required: ["cwd", "pipeline"],
+        },
+    },
     {
         name: "codecarto_status",
         description: "Show the current CodeCartographer phase, active pipeline, and progress for a target repository.",
@@ -610,10 +787,82 @@ const TOOLS = [
             },
         },
     },
+    {
+        name: "codecarto_vision",
+        description: "Generate a structured vision brief from raw product text using the guided interview skill. Returns a prompt the host should feed to its agent to write inputs/vision.md. Requires a synthesis workspace (run codecarto_init with the synthesis pipeline first).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                cwd: { type: "string", description: "Absolute path to the target repository with a .codecarto/ synthesis workspace." },
+                raw_text: { type: "string", description: "The user's raw product text — audience, problem, desired outcomes, constraints, non-goals." },
+            },
+            required: ["cwd", "raw_text"],
+        },
+    },
+    {
+        name: "codecarto_library_init",
+        description: "Initialize a CodeCartographer library at the given path: create the directory, write the .codecarto-library marker, and write the library.path into the user-global config. Idempotent — safe to re-run on an existing library. Pass a namespace to create a namespaced (shared) library.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                library_path: { type: "string", description: "Absolute path for the library directory." },
+                name: { type: "string", description: "Library name (defaults to the directory basename)." },
+                namespace: { type: "string", description: "Default namespace for a namespaced (shared) library." },
+            },
+            required: ["library_path"],
+        },
+    },
+    {
+        name: "codecarto_config",
+        description: "Show the effective merged CodeCartographer configuration (library.path, library.namespace, publish_confirm, llm_steer_next_phase) and whether the library marker was found. Pass cwd to include workspace-level config in the merge.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                cwd: { type: "string", description: "Absolute path to a repository with a .codecarto/ workspace (optional)." },
+            },
+        },
+    },
+    {
+        name: "codecarto_open",
+        description: "Activate an existing CodeCartographer workspace without resetting state. Returns the current pipeline and phase.",
+        inputSchema: {
+            type: "object",
+            properties: { cwd: { type: "string", description: "Absolute path to the target repository." } },
+            required: ["cwd"],
+        },
+    },
+    {
+        name: "codecarto_usage",
+        description: "Show cumulative and per-phase token usage from local phase runs.",
+        inputSchema: {
+            type: "object",
+            properties: { cwd: { type: "string", description: "Absolute path to the target repository." } },
+            required: ["cwd"],
+        },
+    },
+    {
+        name: "codecarto_dashboard",
+        description: "Regenerate .codecarto/dashboard.html from the current workspace state.",
+        inputSchema: {
+            type: "object",
+            properties: { cwd: { type: "string", description: "Absolute path to the target repository." } },
+            required: ["cwd"],
+        },
+    },
+    {
+        name: "codecarto_list_skills",
+        description: "List available post-pipeline skills installed in the workspace.",
+        inputSchema: {
+            type: "object",
+            properties: { cwd: { type: "string", description: "Absolute path to the target repository." } },
+            required: ["cwd"],
+        },
+    },
 ];
 const HANDLERS = {
     codecarto_init: handleInit,
     codecarto_status: handleStatus,
+    codecarto_switch_pipeline: handleSwitchPipeline,
     codecarto_next: handleNext,
     codecarto_phase: handlePhase,
     codecarto_validate: handleValidate,
@@ -622,10 +871,17 @@ const HANDLERS = {
     codecarto_publish: handlePublish,
     codecarto_library_list: handleLibraryList,
     codecarto_library_reindex: handleLibraryReindex,
+    codecarto_library_init: handleLibraryInit,
+    codecarto_config: handleConfig,
+    codecarto_vision: handleVision,
+    codecarto_open: handleOpen,
+    codecarto_usage: handleUsage,
+    codecarto_dashboard: handleDashboard,
+    codecarto_list_skills: handleListSkills,
 };
 // ---------- server bootstrap ----------
 export function buildServer() {
-    const server = new Server({ name: "codecartographer", version: "0.2.0" }, { capabilities: { tools: {} } });
+    const server = new Server({ name: "codecartographer", version: PACKAGE_VERSION }, { capabilities: { tools: {} } });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const handler = HANDLERS[request.params.name];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.12.3",
+  "version": "0.12.9",
   "mcpName": "io.github.HuginnIndustries/codecartographer",
   "description": "Evidence-backed reverse engineering and human-gated software planning for Pi and MCP coding agents.",
   "type": "module",