codecartographer-pi 0.8.0 → 0.9.0

package/.codecarto/GUIDE.md

@@ -232,6 +232,8 @@ Before starting `reimplementation-spec` (or any synthesis phase), confirm with t
 
 This conversation produces inputs the synthesis phase actually needs (locked target stack, locked project name, locked scope cuts) and selects the right template. If the answer is "opinionated," use `templates/reimplementation-spec-opinionated.md` instead of the default. Skipping the hook produces a generic spec when the user wanted a specific one — the most informative friction the framework has produced to date. A two-question pre-flight is cheap.
 
+**Behavior under `/codecarto-next --auto`:** the auto runner suppresses this hook to keep the loop moving. The spec defaults to **language-agnostic** and is tagged `selection: auto-default` in its front-matter; any choice the hook would otherwise have prompted for (target stack, project name, scope cuts) is captured as an `open_questions` entry on the phase rather than blocking the run. Users who want an opinionated spec should run `reimplementation-spec` interactively (via `/codecarto-phase reimplementation-spec` or by stopping `--auto` before the synthesis phase).
+
 ## Guardrails
 
 These rules cannot be enforced by the template — they rely on the LLM following instructions. A future code-backed implementation should enforce them programmatically.

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="assets/logo.svg" alt="CodeCartographer logo" width="96" height="96">
+</p>
+
 # CodeCartographer
 
 [![CI](https://github.com/HuginnIndustries/CodeCartographer/actions/workflows/ci.yml/badge.svg)](https://github.com/HuginnIndustries/CodeCartographer/actions/workflows/ci.yml)
@@ -23,26 +27,32 @@
 |---|---|
 | **Layered analysis pipeline** — architecture → defect scan → behavioral contracts → protocols → porting → reimplementation spec | `.codecarto/` template |
 | **Validation gates between phases** — no advancing past a `FAIL` output | `core/` state machine |
-| **Three delivery surfaces** — Pi extension, MCP server, or pure template | All three share `core/` |
+| **Three surfaces, one framework** — Pi extension (recommended), MCP server (for other coding agents), or drop-in template (one-off / evaluation) | All three share `core/` |
 | **Live progress widget** while phase sub-agents work | Pi extension |
 | **HTML dashboard** — single-file aggregate of progress, links, usage, narrative | `.codecarto/dashboard.html` |
 | **Per-phase token tracking** | `/codecarto-usage` |
 | **Opt-in LLM steering** of the next phase's seed prompt | `/codecarto-next --llm-steer` |
 
+> **Forward-flow synthesis is underway.** v0.9.0 adds the experimental library foundation and MCP publish/list/reindex tools for accumulating `reimplementation-spec.md` artifacts in a git-trackable library. The Pi publish UX and synthesis pipeline that turns selected library entries plus a vision into `project-plan.md` are still in progress. See [`docs/synthesis-roadmap.md`](docs/synthesis-roadmap.md) for the implementation tracker.
+
 ---
 
 ## Install
 
-Pick the surface that matches your tooling. All three share the same `core/` and produce byte-identical phase prompts.
+Three surfaces, in recommended order. All three share the same `core/` and produce byte-identical phase prompts — but the user experience differs by surface, and new features (live widget, dashboard, auto-runner, the upcoming library + synthesis workflows) land on Pi first, MCP second, drop-in last.
+
+1. **Pi extension** — recommended for interactive use. First-class UX.
+2. **MCP server** — for Claude Code, Codex, opencode, Cursor, Claude Desktop, and any other MCP-capable agent.
+3. **Drop-in template** — pure `.codecarto/` markdown + YAML for one-off evaluation or any LLM that can read and write files. Library and synthesis workflows are **not** available in pure drop-in mode; the analysis side works fully.
 
-### Pi extension (recommended for interactive use)
+### Pi extension (recommended)
 
 [Pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) is a TUI coding agent. The CodeCartographer extension adds slash commands, a live agents widget, and the dashboard.
 
 ```bash
 pi install npm:codecartographer-pi          # from the npm registry
 pi install /absolute/path/to/CodeCartographer  # from a local checkout
-pi install git:github.com/your-user/CodeCartographer  # from a git URL
+pi install git:github.com/HuginnIndustries/CodeCartographer  # from a git URL
 ```
 
 > **Don't** run `npm install codecartographer-pi` for the Pi use case. Plain `npm install` puts the package on disk but doesn't register it with Pi. Use `pi install npm:...` so Pi writes the package into its own `~/.pi/agent/settings.json`.
@@ -53,7 +63,9 @@ For extension development, point Pi directly at the entrypoint:
 pi -e /absolute/path/to/CodeCartographer/extensions/codecarto/index.ts
 ```
 
-### MCP server (for Claude Code, Claude Desktop, any MCP host)
+### MCP server (for other coding agents)
+
+Use this when your coding agent isn't Pi — Claude Code, Codex, opencode, Cursor, Claude Desktop, or anything else that speaks MCP. The host drives the conversation and runs the LLM; CodeCartographer provides phase prompts, validation, and experimental library publish/list/reindex operations.
 
 ```bash
 npm install --global codecartographer-pi
@@ -71,7 +83,9 @@ Add to your host config (`~/.config/claude-code/config.json`, `claude_desktop_co
 }
 ```
 
-### Pure template (no runtime, any LLM that reads/writes files)
+### Drop-in template (one-off / evaluation)
+
+Use this to try CodeCartographer in any repo without installing anything, or in environments where neither Pi nor an MCP-capable agent is available. Works with any LLM that can read and write files.
 
 ```bash
 cp -r /path/to/CodeCartographer/.codecarto /path/to/your-repo/
@@ -79,6 +93,8 @@ cp -r /path/to/CodeCartographer/.codecarto /path/to/your-repo/
 
 Then in the LLM session: `Read .codecarto/GUIDE.md and begin the analysis.`
 
+> **Limitation.** Drop-in mode runs the analysis pipeline fully, but library + synthesis workflows require executable code. Publishing and reading library entries are currently available through the MCP server; Pi publish UX and project-plan synthesis are still in progress. See [`docs/synthesis-roadmap.md`](docs/synthesis-roadmap.md) for the planned scope.
+
 ---
 
 ## How it works
@@ -207,13 +223,13 @@ Beyond the slash commands, the Pi extension layers on:
 
 ### Version history (Pi orchestration)
 
-The current parallel-sub-agent design landed in 0.2.0 and has been incrementally enriched: file-backed sessions (0.3.0), summary injection (0.4.0), opt-in LLM steering (0.5.0), usage tracking (0.6.0), HTML dashboard (0.7.0), and end-to-end auto mode (0.8.0). 0.1.x workspaces don't need migration — existing `.codecarto/` directories work unchanged. See `CHANGELOG.md` for details.
+The current parallel-sub-agent design landed in 0.2.0 and has been incrementally enriched: file-backed sessions (0.3.0), summary injection (0.4.0), opt-in LLM steering (0.5.0), usage tracking (0.6.0), HTML dashboard (0.7.0), end-to-end auto mode (0.8.0), and experimental library foundations plus MCP library tools (0.9.0). 0.1.x workspaces don't need migration — existing `.codecarto/` directories work unchanged. See `CHANGELOG.md` for details.
 
 ---
 
 ## MCP server
 
-The same framework is packaged as a [Model Context Protocol](https://modelcontextprotocol.io) server. The MCP path returns prompt text for the host to dispatch and never runs sub-agents itself, so the Pi-only orchestration features (sub-agents, live widget, dashboard, usage tracking) don't apply — but phase prompts and validation are byte-identical with the Pi path because both import the same `core/`.
+The same framework is packaged as a [Model Context Protocol](https://modelcontextprotocol.io) server. The MCP path returns prompt text for the host to dispatch and never runs sub-agents itself, so the Pi-only orchestration features (sub-agents, live widget, dashboard, usage tracking) don't apply — but phase prompts and validation are byte-identical with the Pi path because both import the same `core/`. v0.9.0 also exposes experimental library tools so MCP-capable hosts can publish, list, and reindex reusable `reimplementation-spec.md` artifacts.
 
 Implements MCP spec revision [`2025-11-25`](https://modelcontextprotocol.io/specification/2025-11-25) via `@modelcontextprotocol/sdk` ≥ 1.29.0. The negotiated `protocolVersion` reflects whatever the connecting client requests; the server accepts every revision the SDK supports (currently `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`, `2024-10-07`).
 
@@ -226,21 +242,25 @@ Implements MCP spec revision [`2025-11-25`](https://modelcontextprotocol.io/spec
 | `codecarto_validate` | `/codecarto-validate` |
 | `codecarto_complete` | `/codecarto-complete` |
 | `codecarto_skill` | `/codecarto-skill` |
+| `codecarto_publish` | MCP-only library publish |
+| `codecarto_library_list` | MCP-only library listing |
+| `codecarto_library_reindex` | MCP-only library reindex |
 
-Each tool accepts an absolute `cwd` for the target repository. `codecarto_init` requires `force: true` to overwrite an existing `.codecarto/` (instead of Pi's interactive confirmation).
+Each workflow tool accepts an absolute `cwd` for the target repository. `codecarto_init` requires `force: true` to overwrite an existing `.codecarto/` (instead of Pi's interactive confirmation). The library tools accept an explicit absolute `library_path` or resolve `library.path` from `.codecarto/workflow/config.yaml` / `~/.codecarto/config.yaml`. The library schema is experimental and may break before v2.
 
 ---
 
 ## Compatible environments
 
-| Environment | Notes |
+| Environment | Recommended surface |
 |---|---|
-| **Pi** | Native — install the extension, get slash commands + widget + dashboard. |
-| **Claude Code** | MCP server, or point it at `.codecarto/GUIDE.md` directly. |
+| **Pi** | Native Pi extension — slash commands + widget + dashboard. |
+| **Claude Code / Codex / opencode** | MCP server. All three speak MCP cleanly. |
+| **Cursor / Windsurf / IDE copilots** | MCP server where supported; otherwise drop-in template (`.codecarto/GUIDE.md`). |
 | **Claude Desktop** | MCP server. |
-| **OpenCode / Aider / Cursor / Windsurf / IDE copilots** | Open the repo, point the LLM at `.codecarto/GUIDE.md`. |
-| **Claude.ai / ChatGPT (web chat)** | Paste file contents manually. Tedious for multi-phase runs. |
-| **API-based agents** | Load files programmatically, pass to the model, write outputs back. |
+| **Aider** | Drop-in template — point at `.codecarto/GUIDE.md`. |
+| **Claude.ai / ChatGPT (web chat)** | Drop-in, paste file contents manually. Tedious for multi-phase runs. |
+| **API-based agents** | Load files programmatically, pass to the model, write outputs back. Drop-in semantics. |
 
 ---
 
@@ -381,7 +401,7 @@ core/                        # Pipeline state machine, validators, prompt assemb
                              # dashboard renderer, usage log, orchestrator config.
 extensions/codecarto/        # Pi extension surface (slash commands, widget,
                              # tool gating, dashboard writer + narrator).
-mcp-server/                  # MCP server surface (seven tools mirroring Pi commands).
+mcp-server/                  # MCP server surface (workflow tools + experimental library tools).
 tests/                       # Invariant tests catching cross-wrapper drift.
 docs/                        # Roadmap, design notes.
 ```

package/assets/logo.svg

@@ -0,0 +1,42 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-labelledby="title desc">
+  <title id="title">CodeCartographer logo</title>
+  <desc id="desc">A folded map with a highlighted route over subtle matrix-style code marks.</desc>
+  <defs>
+    <linearGradient id="bg" x1="8" y1="6" x2="56" y2="58" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#303431"/>
+      <stop offset="1" stop-color="#111312"/>
+    </linearGradient>
+    <linearGradient id="route" x1="18" y1="45" x2="48" y2="18" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#b8432f"/>
+      <stop offset="1" stop-color="#f1a84f"/>
+    </linearGradient>
+  </defs>
+
+  <rect x="4" y="4" width="56" height="56" rx="14" fill="url(#bg)"/>
+  <rect x="5" y="5" width="54" height="54" rx="13" fill="none" stroke="#f5efd8" stroke-opacity="0.22" stroke-width="2"/>
+
+  <!-- Matrix/code rain: intentionally sparse so it survives favicon/header size. -->
+  <g stroke="#63e6a4" stroke-width="2.2" stroke-linecap="round" opacity="0.42">
+    <path d="M15 14v5M15 25v4M49 13v7M49 28v4"/>
+    <path d="M25 11v4M39 49v4" opacity="0.65"/>
+  </g>
+
+  <!-- Simplified folded map silhouette. -->
+  <path d="M15 22 27 16l12 6 10-5v25l-10 6-12-6-12 6Z" fill="#f5efd8"/>
+  <path d="M27 16v26M39 22v26" fill="none" stroke="#141413" stroke-opacity="0.25" stroke-width="2"/>
+  <path d="M15 22 27 16l12 6 10-5v25l-10 6-12-6-12 6Z" fill="none" stroke="#141413" stroke-opacity="0.38" stroke-width="2" stroke-linejoin="round"/>
+
+  <!-- Cartography contour lines. -->
+  <g fill="none" stroke="#2c5862" stroke-width="2.2" stroke-linecap="round" opacity="0.9">
+    <path d="M19 29c3-2 5-2 8 0"/>
+    <path d="M31 29c2.5 1.3 4.5 1.1 6.5-.2"/>
+    <path d="M43 29c2-1.5 3.4-1.5 5 .1"/>
+  </g>
+
+  <!-- Dominant route/compass mark. -->
+  <path d="M18 43c7-10 12-11 17-12 6-1 8-7 13-13" fill="none" stroke="#141413" stroke-opacity="0.28" stroke-width="7" stroke-linecap="round"/>
+  <path d="M18 43c7-10 12-11 17-12 6-1 8-7 13-13" fill="none" stroke="url(#route)" stroke-width="4.5" stroke-linecap="round"/>
+  <circle cx="18" cy="43" r="4" fill="#141413" stroke="#f5efd8" stroke-width="2"/>
+  <circle cx="35" cy="31" r="3.3" fill="#141413" stroke="#f5efd8" stroke-width="2"/>
+  <path d="M48 11.5 52 19l-4 7.5-4-7.5Z" fill="#b8432f" stroke="#f5efd8" stroke-width="2" stroke-linejoin="round"/>
+</svg>

package/dist/core/dashboard.d.ts

@@ -2,10 +2,16 @@ import type { NormalizedStatus, PipelineFile } from "./types.ts";
 import type { UsageFile } from "./usage.ts";
 export declare const DASHBOARD_RELATIVE_PATH = "dashboard.html";
 export declare const NARRATION_CACHE_RELATIVE_PATH = ".dashboard-narration.local.md";
+export interface DashboardArtifactLink {
+    path: string;
+    exists: boolean;
+    kind: "primary" | "secondary";
+}
 export interface DashboardCloseoutEntry {
     date: string;
     phaseOrModule: string;
     fileName: string;
+    summary?: string;
 }
 export interface OutputAvailability {
     primary?: {