docs: launch forward synthesis experience

docs.html

@@ -66,7 +66,8 @@ <h2>Copy one folder into any repository.</h2>
 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></pre>
+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>
@@ -98,7 +99,7 @@ <h2>Slash commands, widgets, and tool gating.</h2>
 <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/your-user/CodeCartographer</pre>
+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>
 
@@ -192,10 +193,45 @@ <h2>10 tools for any MCP-compatible host.</h2>
   </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 to cPanel ========== -->
 <section class="section-dark">
   <div class="container">
-    <div class="overline">04 · Deploy to Namecheap cPanel</div>
+    <div class="overline">05 · Deploy to Namecheap cPanel</div>
     <h2>Upload the static bundle and point the domain at it.</h2>
     <p class="section-sub">
       This site is plain HTML, CSS, and JavaScript. Drop it into <code>public_html</code> on your
@@ -236,7 +272,7 @@ <h2>Upload the static bundle and point the domain at it.</h2>
 <!-- =================== Token usage =============== -->
 <section class="section">
   <div class="container">
-    <div class="overline">05 · Token usage and cost</div>
+    <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

features.html

@@ -45,10 +45,10 @@ <h1 style="font-size:clamp(36px, 4.5vw, 56px)">Features</h1>
 <section class="section">
   <div class="container">
     <div class="overline">01 · Pipeline variants</div>
-    <h2>Six pipelines. Pick the depth that matches the job.</h2>
+    <h2>Seven pipelines. Map existing systems or plan a new one.</h2>
     <p class="section-sub">
-      Every pipeline starts with architecture. From there, you choose how far to go. The default is
-      a 7-phase full analysis with a split defect scan. Scale back when you only need orientation.
+      Six analysis variants scale from quick orientation to a deep audit. The forward synthesis
+      pipeline combines a vision with confirmed reusable specs to create a traceable project plan.
     </p>
 
     <div class="pipeline-panel" data-reveal>
@@ -59,6 +59,7 @@ <h2>Six pipelines. Pick the depth that matches the job.</h2>
         <button class="pipeline-tab" type="button" role="tab" data-pipeline="defect-scan">Defect scan</button>
         <button class="pipeline-tab" type="button" role="tab" data-pipeline="lite">Lite</button>
         <button class="pipeline-tab" type="button" role="tab" data-pipeline="architecture-only">Architecture only</button>
+        <button class="pipeline-tab" type="button" role="tab" data-pipeline="synthesis">Synthesis</button>
       </div>
 
       <div class="pipeline-detail" aria-live="polite">
@@ -86,7 +87,7 @@ <h3 id="pipeline-title">Full with deep audit</h3>
     </div>
 
     <div class="compatibility-band" style="margin-top:32px" data-reveal>
-      <p style="margin:0">Phases form a DAG. Contracts and protocols can run in parallel after architecture. Porting waits for both. Reimplementation spec is last.</p>
+      <p style="margin:0"><strong>Two directions:</strong> analysis distills source code into reusable specifications; synthesis combines human-confirmed specifications with a product vision and preserves decision-level provenance in the resulting plan.</p>
     </div>
   </div>
 </section>

index.html

@@ -3,11 +3,11 @@
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<title>CodeCartographer | Structured reverse-engineering for unfamiliar codebases</title>
-<meta name="description" content="CodeCartographer guides LLMs through a phased analysis of source code: architecture map, defect scan, behavioral contracts, protocol documentation, porting synthesis, and reimplementation spec.">
+<title>CodeCartographer | Map existing software. Plan what comes next.</title>
+<meta name="description" content="CodeCartographer turns unfamiliar code into evidence-backed specifications, then combines confirmed specs with a product vision to produce a provenance-backed project plan.">
 <meta name="theme-color" content="#141413">
 <meta property="og:title" content="CodeCartographer">
-<meta property="og:description" content="A structured reverse-engineering toolkit for understanding unfamiliar codebases with phased, evidence-tagged LLM analysis.">
+<meta property="og:description" content="Map unfamiliar code into evidence-backed specifications, then synthesize confirmed designs into a traceable project plan.">
 <meta property="og:type" content="website">
 <meta property="og:url" content="https://codecarto.dev/">
 <meta name="twitter:card" content="summary_large_image">
@@ -41,24 +41,26 @@
     <div class="hero-copy">
       <div class="hero-eyebrow">
         <span class="dot"></span>
-        Reverse-engineering toolkit · v0.11.0
+        Evidence-backed software cartography · v0.11.0
       </div>
-      <h1>Understand unfamiliar codebases <em>with a process instead of a lucky prompt.</em></h1>
+      <h1>Understand existing software. <em>Plan what comes next.</em></h1>
       <p class="hero-sub">
-        CodeCartographer turns "explain this repo" into a staged investigation. Architecture, defect
-        scan, behavioral contracts, protocol notes, porting synthesis, and a reimplementation spec.
-        Each finding is evidence-tagged so confidence stays visible.
+        CodeCartographer turns “explain this repo” into a staged, evidence-backed investigation—then
+        combines explicitly confirmed specifications with a new product vision to create a traceable
+        implementation plan.
       </p>
       <div class="hero-actions">
         <a href="docs.html" class="btn btn-primary">Start with the docs</a>
         <a href="https://www.npmjs.com/package/codecartographer-pi" class="btn btn-secondary">Install from npm</a>
         <a href="features.html" class="btn btn-ghost">Tour the pipeline</a>
+        <a href="https://github.com/HuginnIndustries/CodeCartographer/blob/main/docs/build-week-2026.md" class="btn btn-ghost">Build Week demo</a>
       </div>
       <div class="hero-meta">
         <span><b>Pi</b> extension</span>
         <span><b>MCP</b> server</span>
         <span><b>Drop-in</b> template</span>
         <span><b>MIT</b> licensed</span>
+        <span><b>Human-gated</b> synthesis</span>
       </div>
     </div>
 
@@ -107,6 +109,11 @@ <h3>Confidence stays visible.</h3>
         <h3>Pick up where you left off.</h3>
         <p>The filesystem—not the conversation—is durable memory. A fresh LLM session reads the status and findings, then resumes without depending on compacted chat history.</p>
       </div>
+      <div class="card-elevated">
+        <span class="pill pill-plum" style="margin-bottom:14px;display:inline-block">Synthesis</span>
+        <h3>Specs become a project plan.</h3>
+        <p>Versioned library entries are proposed against a vision, explicitly confirmed by a human, merged with conflicts intact, and transformed into work packages with a decision-level provenance ledger.</p>
+      </div>
     </div>
   </div>
 </section>
@@ -142,6 +149,10 @@ <h3>Porting bundle</h3>
         <h3>Reimplementation spec</h3>
         <p>Language-agnostic build plan with modules, acceptance scenarios, and known unknowns.</p>
       </div>
+      <div class="artifact" data-reveal>
+        <h3>Evidence-backed project plan</h3>
+        <p>Confirmed specifications become architecture, work packages, acceptance gates, conflict dispositions, and a decision-level provenance ledger.</p>
+      </div>
     </div>
   </div>
 </section>

script.js

@@ -64,6 +64,14 @@ const pipelineData = {
     phases: ["Architecture"],
     note: "Ideal as a low-cost first pass when you only need to orient yourself.",
   },
+  synthesis: {
+    kicker: "4 phases · forward flow",
+    title: "Synthesis",
+    description:
+      "Combines a product vision with explicitly confirmed, versioned library specifications to create an implementation-ready plan without losing provenance.",
+    phases: ["Vision capture", "Candidate proposal + human confirmation", "Specification merge", "Project plan"],
+    note: "Pi/MCP only. Runtime preflight refuses to merge or finalize until a human confirms at least one version-pinned input.",
+  },
 };
 
 function initPipelineSwitcher() {

tests/upstream-consistency.test.mjs

@@ -31,7 +31,7 @@ test("every public version label matches the authoritative package version", asy
     assert.match(footer, new RegExp(`v${pkg.version.replaceAll(".", "\\.")}`), `${name} footer must show v${pkg.version}`);
   }
   const index = await read(join(SITE_ROOT, "index.html"));
-  assert.match(index, new RegExp(`Reverse-engineering toolkit · v${pkg.version.replaceAll(".", "\\.")}`));
+  assert.match(index, new RegExp(`Evidence-backed software cartography · v${pkg.version.replaceAll(".", "\\.")}`));
 });
 
 test("MCP documentation names every tool registered by the upstream server", async () => {
@@ -53,6 +53,16 @@ test("pipeline selector mirrors the authoritative pipeline variants", async () =
   assert.equal((features.match(/class="pipeline-tab/g) ?? []).length, pipelineFiles.length);
 });
 
+test("synthesis documentation preserves the human confirmation and provenance contracts", async () => {
+  const docs = await read(join(SITE_ROOT, "docs.html"));
+  const features = await read(join(SITE_ROOT, "features.html"));
+  assert.match(docs, /explicit human selection/i);
+  assert.match(docs, /version-pinned/i);
+  assert.match(docs, /provenance ledger/i);
+  assert.match(features, /human-confirmed/i);
+  assert.match(features, /decision-level provenance/i);
+});
+
 test("continuity copy treats THREAD_LOG as a closeout index, not the durable summary store", async () => {
   const features = await read(join(SITE_ROOT, "features.html"));
   const card = features.match(/<h3[^>]*><code>THREAD_LOG\.md<\/code><\/h3>\s*<p>(.*?)<\/p>/s)?.[1] ?? "";