-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathdocs.html
More file actions
371 lines (346 loc) · 18.2 KB
/
Copy pathdocs.html
File metadata and controls
371 lines (346 loc) · 18.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Docs — CodeCartographer</title>
<meta name="description" content="Installation and configuration: drop-in template, Pi-mono extension, MCP server, pipeline selection, and GitHub Pages deployment.">
<meta name="theme-color" content="#141413">
<link rel="canonical" href="https://codecarto.dev/docs.html">
<link rel="icon" href="logo.svg" type="image/svg+xml">
<link rel="stylesheet" href="site.css">
<script defer src="script.js"></script>
</head>
<body>
<header class="site-nav">
<div class="site-nav-inner">
<a href="index.html" class="brand">
<span class="brand-mark" aria-hidden="true"></span>
<span>CodeCartographer</span>
</a>
<nav>
<a href="index.html">Overview</a>
<a href="features.html">Features</a>
<a href="docs.html" class="active">Docs</a>
<a href="showcase.html">Showcase</a>
</nav>
<a href="https://github.com/HuginnIndustries/CodeCartographer" class="btn btn-secondary">View on GitHub</a>
</div>
</header>
<!-- =================== Page header =============== -->
<section class="hero" style="padding:72px 0 48px">
<div class="container">
<div class="hero-eyebrow"><span class="dot"></span> Installation & configuration</div>
<h1 style="font-size:clamp(36px, 4.5vw, 56px)">Docs</h1>
<p class="hero-sub">
Three ways to install. Drop-in template, Pi-mono extension, or MCP server. Pick the one that
matches your workflow.
</p>
</div>
</section>
<!-- =================== Drop-in template ========== -->
<section class="section">
<div class="container">
<div class="overline">01 · Drop-in template</div>
<h2>Copy one folder into any repository.</h2>
<p class="section-sub">
No CLI, no runtime, no dependencies. The core is structured Markdown and YAML. Works with any
LLM that can read and write files.
</p>
<div class="card-elevated" style="margin-bottom:21px" data-reveal>
<div class="overline">Step 1: Copy the template</div>
<pre class="code-block">cp -r /path/to/CodeCartographer/.codecarto /path/to/your-repo/</pre>
<button class="copy-button" type="button" data-copy="cp -r /path/to/CodeCartographer/.codecarto /path/to/your-repo/" style="margin-top:12px">Copy command</button>
</div>
<div class="card-elevated" style="margin-bottom:21px" data-reveal>
<div class="overline">Step 2: Pick a pipeline (optional)</div>
<p style="margin-bottom:14px;color:var(--color-muted)">Edit <code>.codecarto/workflow/status.yaml</code> and set the pipeline field. Defaults to the 7-phase full analysis with a split defect scan.</p>
<pre class="code-block"><span class="com"># Available pipeline paths:</span>
pipeline: workflow/pipeline-full-with-deep-audit.yaml <span class="com"># 7-phase (default)</span>
pipeline: workflow/pipeline-full-with-audit.yaml <span class="com"># 6-phase</span>
pipeline: workflow/pipeline.yaml <span class="com"># 5-phase</span>
pipeline: workflow/pipeline-defect-scan.yaml <span class="com"># 2-phase</span>
pipeline: workflow/pipeline-lite.yaml <span class="com"># 3-phase</span>
pipeline: workflow/pipeline-architecture-only.yaml <span class="com"># 1-phase</span>
pipeline: workflow/pipeline-synthesis.yaml <span class="com"># 4-phase forward synthesis (Pi/MCP only)</span></pre>
</div>
<div class="card-elevated" data-reveal>
<div class="overline">Step 3: Point an LLM at the guide</div>
<pre class="code-block">Read .codecarto/GUIDE.md and begin the analysis.</pre>
<button class="copy-button" type="button" data-copy="Read .codecarto/GUIDE.md and begin the analysis." style="margin-top:12px">Copy prompt</button>
<p style="margin-top:14px;color:var(--color-muted)">The LLM reads the guide, checks <code>status.yaml</code> for progress, and starts the next phase automatically. Each phase produces a validated output in <code>.codecarto/findings/</code>.</p>
</div>
<div class="compatibility-band" style="margin-top:28px" data-reveal>
<p style="margin:0">Works in Claude Code, OpenCode, Cursor, Windsurf, Aider, and any IDE copilot with file read/write access.</p>
</div>
</div>
</section>
<!-- =================== Pi-mono extension ========= -->
<section class="section-dark">
<div class="container">
<div class="overline">02 · Pi-mono extension</div>
<h2>Slash commands, widgets, and tool gating.</h2>
<p class="section-sub">
Install the package directly into Pi-mono. Phase sub-agents run in parallel widgets with live
token tracking and file-backed session transcripts.
</p>
<div class="card-elevated" style="background:rgba(245,239,216,0.06);border:1px solid rgba(245,239,216,0.14);box-shadow:none;margin-bottom:24px" data-reveal>
<div class="overline">Install</div>
<pre class="code-block">pi install npm:codecartographer-pi
<span class="com"># or, from a local checkout:</span>
pi install /absolute/path/to/CodeCartographer
<span class="com"># or, from a git URL:</span>
pi install git:github.com/HuginnIndustries/CodeCartographer</pre>
<button class="copy-button" type="button" data-copy="pi install npm:codecartographer-pi" style="margin-top:12px">Copy npm install</button>
</div>
<div class="card-elevated" style="background:rgba(245,239,216,0.06);border:1px solid rgba(245,239,216,0.14);box-shadow:none" data-reveal>
<div class="overline">Available commands</div>
<div class="grid-2" style="margin-top:12px">
<div>
<p style="color:var(--color-surface);font-weight:500;margin-bottom:4px"><code>/codecarto-init</code></p>
<p>Copy <code>.codecarto/</code> into the current repository and select a pipeline.</p>
</div>
<div>
<p style="color:var(--color-surface);font-weight:500;margin-bottom:4px"><code>/codecarto-next</code></p>
<p>Spawn the next eligible phase as a sub-agent. Optional <code>--llm-steer</code> flag for customized seed prompts.</p>
</div>
<div>
<p style="color:var(--color-surface);font-weight:500;margin-bottom:4px"><code>/codecarto-status</code></p>
<p>Show current phase progress and pipeline state.</p>
</div>
<div>
<p style="color:var(--color-surface);font-weight:500;margin-bottom:4px"><code>/codecarto-validate</code></p>
<p>Run validation against the current phase output.</p>
</div>
<div>
<p style="color:var(--color-surface);font-weight:500;margin-bottom:4px"><code>/codecarto-complete</code></p>
<p>Atomically mark a phase complete after validation passes.</p>
</div>
<div>
<p style="color:var(--color-surface);font-weight:500;margin-bottom:4px"><code>/codecarto-phase</code></p>
<p>Force a specific phase even out of pipeline order.</p>
</div>
<div>
<p style="color:var(--color-surface);font-weight:500;margin-bottom:4px"><code>/codecarto-skill</code></p>
<p>Run a post-pipeline skill once all phases are complete.</p>
</div>
<div>
<p style="color:var(--color-surface);font-weight:500;margin-bottom:4px"><code>/codecarto-usage</code></p>
<p>Show cumulative and per-phase token usage from local phase runs.</p>
</div>
<div>
<p style="color:var(--color-surface);font-weight:500;margin-bottom:4px"><code>/codecarto-open</code></p>
<p>Activate an existing workspace without resetting state.</p>
</div>
<div>
<p style="color:var(--color-surface);font-weight:500;margin-bottom:4px"><code>/codecarto-vision</code></p>
<p>Run a guided product discovery interview for the synthesis pipeline.</p>
</div>
<div>
<p style="color:var(--color-surface);font-weight:500;margin-bottom:4px"><code>/codecarto-switch-pipeline</code></p>
<p>Switch the active pipeline without losing findings or progress.</p>
</div>
<div>
<p style="color:var(--color-surface);font-weight:500;margin-bottom:4px"><code>/codecarto-publish</code></p>
<p>Publish the reimplementation spec to a configured library.</p>
</div>
<div>
<p style="color:var(--color-surface);font-weight:500;margin-bottom:4px"><code>/codecarto-library-init</code></p>
<p>Initialize a library directory with marker and config.</p>
</div>
<div>
<p style="color:var(--color-surface);font-weight:500;margin-bottom:4px"><code>/codecarto-config</code></p>
<p>Show the effective merged configuration.</p>
</div>
<div>
<p style="color:var(--color-surface);font-weight:500;margin-bottom:4px"><code>/codecarto-dashboard</code></p>
<p>Regenerate the dashboard HTML.</p>
</div>
</div>
</div>
</div>
</section>
<!-- =================== MCP server ================ -->
<section class="section">
<div class="container">
<div class="overline">03 · MCP server</div>
<h2>18 tools for any MCP-compatible host.</h2>
<p class="section-sub">
The same core primitives exposed as a Model Context Protocol server. Wire it into Claude Code,
Claude Desktop, or any MCP host. The host runs the LLM, isolates phase sessions, and controls
compaction; CodeCartographer returns prompts, validates outputs, and manages durable workflow state.
</p>
<div class="card-elevated" style="margin-bottom:24px" data-reveal>
<div class="overline">Install</div>
<pre class="code-block">npm install --global codecartographer-pi
<span class="com"># or, in a project:</span>
npm install codecartographer-pi</pre>
<button class="copy-button" type="button" data-copy="npm install --global codecartographer-pi" style="margin-top:12px">Copy global install</button>
</div>
<div class="card-elevated" data-reveal>
<div class="overline">Host configuration</div>
<p style="margin-bottom:12px;color:var(--color-muted)">Add to your MCP host config. Claude Code uses <code>~/.config/claude-code/config.json</code>; Claude Desktop uses <code>claude_desktop_config.json</code>.</p>
<pre class="code-block">{
"mcpServers": {
"codecartographer": {
"command": "codecarto-mcp"
}
}
}</pre>
<button class="copy-button" type="button" data-copy='{
"mcpServers": {
"codecartographer": {
"command": "codecarto-mcp"
}
}
}' style="margin-top:12px">Copy config</button>
</div>
<p style="margin-top:28px;font-size:15px;color:var(--color-muted)" data-reveal>
The server exposes 18 workflow and library tools: <code>codecarto_init</code>,
<code>codecarto_status</code>, <code>codecarto_switch_pipeline</code>, <code>codecarto_next</code>,
<code>codecarto_phase</code>, <code>codecarto_validate</code>, <code>codecarto_complete</code>,
<code>codecarto_skill</code>, <code>codecarto_publish</code>, <code>codecarto_library_list</code>,
<code>codecarto_library_reindex</code>, <code>codecarto_library_init</code>,
<code>codecarto_config</code>, <code>codecarto_vision</code>, <code>codecarto_open</code>,
<code>codecarto_usage</code>, <code>codecarto_dashboard</code>, and <code>codecarto_list_skills</code>.
Workflow tools accept an absolute <code>cwd</code> for the target repository; library tools
accept a configured or explicit library path.
</p>
</div>
</section>
<!-- =================== Forward synthesis ========= -->
<section class="section-dark">
<div class="container">
<div class="overline">04 · Forward synthesis</div>
<h2>Turn confirmed software maps into a traceable build plan.</h2>
<p class="section-sub">
The synthesis pipeline runs through Pi or MCP. It combines a product vision with reusable,
versioned reimplementation specs, pauses for explicit human selection, preserves conflicts,
and produces work packages with a decision-level provenance ledger.
</p>
<div class="grid-2">
<div class="card-elevated" style="background:rgba(245,239,216,0.06);border:1px solid rgba(245,239,216,0.14);box-shadow:none" data-reveal>
<div class="overline">Start</div>
<pre class="code-block">/codecarto-init synthesis
<span class="com"># Fill .codecarto/inputs/vision.md</span>
/codecarto-next --auto</pre>
<p>The first run creates a ranked proposal, completes that phase, and then intentionally stops at the confirmation preflight.</p>
</div>
<div class="card-elevated" style="background:rgba(245,239,216,0.06);border:1px solid rgba(245,239,216,0.14);box-shadow:none" data-reveal>
<div class="overline">Confirm and resume</div>
<pre class="code-block"><span class="com"># In proposal.md:</span>
| [x] | event-router | v2 | ... |
/codecarto-next --auto</pre>
<p>Merge and finalization read only the checked, version-pinned specs. An unknown entry or version is rejected before any LLM phase starts.</p>
</div>
</div>
<div class="hero-actions" style="margin-top:24px">
<a href="https://github.com/HuginnIndustries/CodeCartographer/blob/main/docs/build-week-2026.md" class="btn btn-primary">Run the one-command demo</a>
</div>
</div>
</section>
<!-- =================== Deploy with GitHub Pages === -->
<section class="section-dark">
<div class="container">
<div class="overline">05 · Deploy with GitHub Pages</div>
<h2>Merge to main and let GitHub Pages publish the site.</h2>
<p class="section-sub">
This site is plain HTML, CSS, and JavaScript. GitHub Pages serves the repository's
<code>main</code> branch from the repository root at <code>codecarto.dev</code>.
</p>
<div class="split">
<div class="deploy-steps" data-reveal>
<ol>
<li>Open a pull request targeting <code>main</code>.</li>
<li>Run <code>npm test</code> against the authoritative CodeCartographer checkout and wait for the pull-request checks to pass.</li>
<li>Merge the pull request. GitHub Pages automatically starts a deployment from <code>main</code> at <code>/(root)</code>.</li>
<li>Confirm the latest build completed in <strong>Settings → Pages</strong>.</li>
<li>Keep <code>CNAME</code> set to <code>codecarto.dev</code>. GitHub Pages manages the approved TLS certificate and enforces HTTPS.</li>
<li>Visit <code>https://codecarto.dev/</code> and hard refresh.</li>
</ol>
</div>
<div class="card-elevated" style="background:rgba(245,239,216,0.06);border:1px solid rgba(245,239,216,0.14);box-shadow:none" data-reveal>
<div class="overline">Published site files</div>
<ul style="list-style:none;padding:0;display:grid;gap:6px;font-family:var(--font-mono);font-size:13px;color:rgba(245,239,216,0.8);margin:0">
<li>index.html</li>
<li>features.html</li>
<li>docs.html</li>
<li>showcase.html</li>
<li>site.css</li>
<li>colors_and_type.css</li>
<li>script.js</li>
<li>CNAME</li>
<li>robots.txt</li>
<li>sitemap.xml</li>
</ul>
</div>
</div>
</div>
</section>
<!-- =================== Token usage =============== -->
<section class="section">
<div class="container">
<div class="overline">06 · Token usage and cost</div>
<h2>What to expect on your first run.</h2>
<p class="section-sub">
CodeCartographer reads your source code multiple times across phases and produces thousands of
words of structured output. The fixed template overhead is about 27,000 tokens across a
6-phase run. Source code reading is the dominant variable cost.
</p>
<div class="grid-2">
<div class="card" data-reveal>
<h3 style="font-size:18px">Medium codebase (~100k tokens)</h3>
<p>A full 5-phase run costs roughly $2 to $4 in API fees. Larger codebases scale linearly. Start with architecture-only to test output quality before committing.</p>
</div>
<div class="card" data-reveal>
<h3 style="font-size:18px">Tips to reduce cost</h3>
<p>Use one session per phase for fresh context windows. The lite pipeline gives 80% of the value for understanding. Skip the defect scan on weaker models.</p>
</div>
</div>
<div class="hero-actions" style="margin-top:24px">
<a href="https://github.com/HuginnIndustries/CodeCartographer/blob/main/README.md#token-usage-and-cost" class="btn btn-primary">Full cost breakdown</a>
</div>
</div>
</section>
<!-- =================== Footer ==================== -->
<footer class="site-footer">
<div class="site-footer-inner">
<div>
<div style="display:flex;align-items:center;gap:10px;font-family:var(--font-serif);font-weight:500;font-size:18px;color:#f5efd8">
<span class="brand-mark" style="width:28px;height:28px;border-radius:8px;flex-shrink:0" aria-hidden="true"></span>
CodeCartographer
</div>
<p class="tagline">A structured reverse-engineering toolkit for unfamiliar codebases.</p>
</div>
<div>
<h4>Site</h4>
<a href="index.html">Overview</a>
<a href="features.html">Features</a>
<a href="docs.html">Docs</a>
<a href="showcase.html">Showcase</a>
</div>
<div>
<h4>Project</h4>
<a href="https://github.com/HuginnIndustries/CodeCartographer">GitHub</a>
<a href="https://github.com/HuginnIndustries/CodeCartographer/blob/main/CHANGELOG.md">Changelog</a>
<a href="https://github.com/HuginnIndustries/CodeCartographer/blob/main/LICENSE">License</a>
<a href="https://github.com/HuginnIndustries/CodeCartographer/archive/refs/heads/main.zip">Download ZIP</a>
</div>
<div>
<h4>Guides</h4>
<a href="https://github.com/HuginnIndustries/CodeCartographer/blob/main/GUIDE.md">Usage guide</a>
<a href="https://github.com/HuginnIndustries/CodeCartographer/blob/main/MANUAL.md">Manual</a>
<a href="https://github.com/HuginnIndustries/CodeCartographer/blob/main/CONTRIBUTING.md">Contributing</a>
</div>
<div>
<h4>Package</h4>
<a href="https://www.npmjs.com/package/codecartographer-pi">npm</a>
</div>
</div>
<div class="site-footer-bottom">
<span>v0.12.11 · MIT License</span>
<span>codecarto.dev</span>
</div>
</footer>
</body>
</html>