@hobocode/thought-layer 0.7.0 → 0.8.5

package/core/index.ts

@@ -22,5 +22,9 @@ export * from "./backend.ts";
 export * from "./backend-io.ts";
 export * from "./scaffold.ts";
 export * from "./scaffold-io.ts";
+export * from "./artifacts.ts";
+export * from "./artifacts-io.ts";
+export * from "./notion.ts";
+export * from "./notion-io.ts";
 export * from "./deploy.ts";
 export * from "./deploy-io.ts";

package/core/merge.ts

@@ -28,7 +28,7 @@ export interface MergeOpts {
   theirsTs: number; // their file's writer.ts
 }
 
-const ARTIFACT_KEYS = ["bizModel", "grill", "assets", "research", "swot", "prd", "naming", "brand"] as const;
+const ARTIFACT_KEYS = ["bizModel", "grill", "assets", "research", "swot", "prd", "naming", "brand", "governance"] as const;
 
 const num = (v: unknown): number => (typeof v === "number" && !Number.isNaN(v) ? v : 0);
 const genAt = (v: unknown): number =>
@@ -108,6 +108,7 @@ export function mergeProgressStates(ours: ProgressState, theirs: ProgressState,
     prd: artifact("prd"),
     naming: artifact("naming"),
     brand: artifact("brand"),
+    governance: artifact("governance"),
     kit: mergeKit(ours.kit, theirs.kit, oursNewer),
   };
 

package/core/notion-io.ts

@@ -0,0 +1,292 @@
+// Node IO for the Notion wiki, shared by the `tl wiki` CLI and the tl_wiki Pi
+// tool. The pure plan (state -> pages + blocks) lives in notion.ts; this calls
+// the Notion REST API directly with the global fetch (Node 18+), so the kit
+// stays dependency-free and the bundle never grows. It find-or-creates the wiki
+// pages idempotently (Notion has no upsert), refreshes their content, and builds
+// an Artifacts database.
+//
+// Secrets: the Notion token is read ONLY from the environment (BYOK), never a
+// CLI flag or tool parameter, never persisted. The parent page id is not a
+// secret, so it may be a flag. The page-id map is machine-local and not synced.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { git, isGitRepo, loadConfig, resolveWorkspace } from "./sync-io.ts";
+import { slugify } from "./sync.ts";
+import { repoOwnerName } from "./artifacts-io.ts";
+import { STATE_DIR, loadStateFile } from "./state-file.ts";
+import { buildWikiPlan, chunkChildren, type Block, type WikiPlan, type WikiArtifact } from "./notion.ts";
+import type { ArtifactManifest } from "./artifacts.ts";
+import type { StateOpResult } from "./state-ops.ts";
+
+const NOTION_API = "https://api.notion.com/v1";
+const NOTION_VERSION = "2022-06-28";
+const MIN_INTERVAL_MS = 350; // ~3 requests/second
+const TOKEN_ENVS = ["THOUGHT_LAYER_NOTION_TOKEN", "NOTION_TOKEN"];
+
+export interface WikiRunOptions {
+  path?: string; // explicit source state file
+  name?: string; // session name (the wiki + id-map key)
+  workspace?: string; // sessions workspace label
+  dir?: string; // explicit clone dir
+  parentPage?: string; // Notion page id or URL the integration is shared with
+  replace?: boolean; // recreate the root page from scratch (new ids)
+  dryRun?: boolean; // build the plan, report counts, no network
+}
+
+const ok = (message: string, details: Record<string, unknown> = {}): StateOpResult => ({ ok: true, message, details });
+const fail = (message: string, details: Record<string, unknown> = {}): StateOpResult => ({ ok: false, message, details });
+
+// ---- machine-local page-id map (mirrors sync.json) ---------------------------
+
+interface NotionEntry { rootPageId?: string; areaPageIds?: Record<string, string>; artifactsDbId?: string; updatedAt?: number; }
+interface NotionConfig { schema: number; sessions: Record<string, NotionEntry>; }
+
+function notionConfigPath(): string {
+  return process.env["THOUGHT_LAYER_NOTION_CONFIG"] || join(homedir(), ".thought-layer", "notion.json");
+}
+function loadNotionConfig(): NotionConfig {
+  const p = notionConfigPath();
+  if (!existsSync(p)) return { schema: 1, sessions: {} };
+  try {
+    const raw = JSON.parse(readFileSync(p, "utf8")) as Record<string, unknown>;
+    const sessions = raw["sessions"] && typeof raw["sessions"] === "object" ? raw["sessions"] as Record<string, NotionEntry> : {};
+    return { schema: 1, sessions };
+  } catch { return { schema: 1, sessions: {} }; }
+}
+function saveNotionConfig(cfg: NotionConfig): void {
+  const p = notionConfigPath();
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify(cfg, null, 2) + "\n");
+}
+
+// ---- helpers -----------------------------------------------------------------
+
+// Accept a raw 32-hex id, a dashed UUID, or a Notion URL; return a dashed UUID.
+export function pageIdFromInput(s: string): string | null {
+  const t = String(s || "").trim();
+  const dashed = t.match(/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/);
+  if (dashed) return dashed[0].toLowerCase();
+  const runs = t.match(/[0-9a-fA-F]{32}/g);
+  if (!runs || !runs.length) return null;
+  const id = runs[runs.length - 1]!.toLowerCase();
+  return `${id.slice(0, 8)}-${id.slice(8, 12)}-${id.slice(12, 16)}-${id.slice(16, 20)}-${id.slice(20)}`;
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+// A small serial Notion client: paces requests to ~3/s and backs off on 429.
+class Notion {
+  private last = 0;
+  constructor(private token: string) {}
+
+  async call(method: string, path: string, body?: unknown): Promise<{ status: number; json: Record<string, unknown> }> {
+    for (let attempt = 0; ; attempt++) {
+      const wait = MIN_INTERVAL_MS - (Date.now() - this.last);
+      if (wait > 0) await sleep(wait);
+      this.last = Date.now();
+      const res = await fetch(`${NOTION_API}${path}`, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.token}`,
+          "Notion-Version": NOTION_VERSION,
+          "Content-Type": "application/json",
+        },
+        ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+      });
+      if (res.status === 429 && attempt < 4) {
+        const retry = Number(res.headers.get("Retry-After")) || Math.pow(2, attempt);
+        await sleep(retry * 1000);
+        continue;
+      }
+      let json: Record<string, unknown> = {};
+      try { json = (await res.json()) as Record<string, unknown>; } catch { /* empty body */ }
+      return { status: res.status, json };
+    }
+  }
+
+  async pageExists(id: string): Promise<boolean> {
+    const r = await this.call("GET", `/pages/${id}`);
+    return r.status === 200 && r.json["archived"] !== true;
+  }
+
+  async createPage(parentPageId: string, title: string, emoji?: string): Promise<string> {
+    const r = await this.call("POST", "/pages", {
+      parent: { page_id: parentPageId },
+      ...(emoji ? { icon: { type: "emoji", emoji } } : {}),
+      properties: { title: { title: [{ text: { content: title } }] } },
+    });
+    if (r.status !== 200) throw new Error(notionErr("create page", r));
+    return String(r.json["id"]);
+  }
+
+  // Replace a page's content: delete every existing child, then append the new
+  // blocks in <=100-block batches.
+  async replaceChildren(pageId: string, blocks: Block[]): Promise<void> {
+    let cursor: string | undefined;
+    do {
+      const q = cursor ? `?start_cursor=${cursor}&page_size=100` : "?page_size=100";
+      const r = await this.call("GET", `/blocks/${pageId}/children${q}`);
+      if (r.status !== 200) break;
+      for (const b of (r.json["results"] as Array<{ id: string }>) || []) await this.call("DELETE", `/blocks/${b.id}`);
+      cursor = r.json["has_more"] ? String(r.json["next_cursor"]) : undefined;
+    } while (cursor);
+    for (const batch of chunkChildren(blocks)) {
+      if (!batch.length) continue;
+      const r = await this.call("PATCH", `/blocks/${pageId}/children`, { children: batch });
+      if (r.status !== 200) throw new Error(notionErr("append blocks", r));
+    }
+  }
+
+  async createArtifactsDb(parentPageId: string, artifacts: WikiArtifact[]): Promise<string> {
+    const cats = Array.from(new Set(artifacts.map((a) => a.category)));
+    const r = await this.call("POST", "/databases", {
+      parent: { type: "page_id", page_id: parentPageId },
+      title: [{ text: { content: "Artifacts" } }],
+      icon: { type: "emoji", emoji: "📎" },
+      properties: {
+        Name: { title: {} },
+        Category: { select: { options: cats.map((c) => ({ name: c })) } },
+        Size: { rich_text: {} },
+        Link: { url: {} },
+      },
+    });
+    if (r.status !== 200) throw new Error(notionErr("create database", r));
+    return String(r.json["id"]);
+  }
+
+  async addArtifactRow(dbId: string, a: WikiArtifact): Promise<void> {
+    await this.call("POST", "/pages", {
+      parent: { database_id: dbId },
+      properties: {
+        Name: { title: [{ text: { content: a.name } }] },
+        Category: { select: { name: a.category } },
+        Size: { rich_text: [{ text: { content: humanSize(a.bytes) } }] },
+        ...(a.url ? { Link: { url: a.url } } : {}),
+      },
+    });
+  }
+}
+
+function notionErr(what: string, r: { status: number; json: Record<string, unknown> }): string {
+  const msg = String(r.json["message"] || "").slice(0, 200);
+  return `Notion ${what} failed (${r.status})${msg ? `: ${msg}` : ""}`;
+}
+function humanSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+// ---- the orchestrator --------------------------------------------------------
+
+export async function runWiki(opts: WikiRunOptions): Promise<StateOpResult> {
+  try {
+    const cfg = loadConfig();
+    const { cloneDir, ws } = resolveWorkspace(opts as never, cfg);
+    if (!isGitRepo(cloneDir)) {
+      return fail(`No sessions workspace at ${cloneDir}. Run tl sync init then tl artifacts before building the wiki.`, { cloneDir });
+    }
+    const slug = slugify(opts.name || ws?.activeSession?.replace(/\.json$/, "") || "");
+    if (!slug) return fail("Name the session to publish: tl wiki --name <name>.");
+
+    // Load the session state.
+    const sessionPath = join(cloneDir, STATE_DIR, `${slug}.json`);
+    const useExplicit = !!((opts.path && opts.path.trim()) || (process.env["THOUGHT_LAYER_STATE"] || "").trim());
+    const loaded = loadStateFile(useExplicit ? opts.path : existsSync(sessionPath) ? sessionPath : opts.path);
+    if (!loaded.exists) return fail(`No session "${slug}" found (looked at ${loaded.path}). Save it first with tl sync save --name ${slug}.`, { cloneDir });
+
+    // Read the delivered artifacts manifest + recompute GitHub URLs (if delivered).
+    const artifactsDir = join(cloneDir, "artifacts", slug);
+    let manifest: ArtifactManifest | null = null;
+    const manifestPath = join(artifactsDir, "artifacts.json");
+    if (existsSync(manifestPath)) {
+      try { manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as ArtifactManifest; } catch { manifest = null; }
+    }
+    const branch = git(cloneDir, ["rev-parse", "--abbrev-ref", "HEAD"]).out.trim() || ws?.defaultBranch || "main";
+    const ownerName = repoOwnerName(ws?.repo || "");
+    const urls: Record<string, string> = {};
+    if (ownerName && manifest) {
+      const base = `https://github.com/${ownerName}/blob/${branch}/artifacts/${slug}`;
+      for (const f of manifest.files) urls[f.path] = `${base}/${f.path.split("/").map(encodeURIComponent).join("/")}`;
+    }
+
+    const plan: WikiPlan = buildWikiPlan(loaded.state, { manifest, urls });
+    const blockCount = plan.overview.length + plan.areas.reduce((n, a) => n + a.blocks.length, 0);
+
+    if (opts.dryRun) {
+      const areaList = plan.areas.map((a) => `${a.emoji} ${a.title} (${a.blocks.length} blocks)`).join(", ");
+      return ok(
+        `Dry run for "${plan.title}": ${plan.areas.length} area page(s), ${blockCount} blocks total, ${plan.artifacts.length} artifact(s) in the database.\nAreas: ${areaList || "(none with content yet)"}.${manifest ? "" : "\nNo delivered artifacts found; run tl artifacts first to populate the Artifacts database with GitHub links."}`,
+        { title: plan.title, areas: plan.areas.map((a) => ({ key: a.key, blocks: a.blocks.length })), blockCount, artifacts: plan.artifacts.length, delivered: !!manifest },
+      );
+    }
+
+    // Token (BYOK, env only) and parent page are required for the live run.
+    const token = TOKEN_ENVS.map((e) => process.env[e]).find((v) => v && v.trim())?.trim() || "";
+    if (!token) {
+      return fail(
+        "No Notion token. Create an internal integration at https://www.notion.so/my-integrations, copy its secret, and set THOUGHT_LAYER_NOTION_TOKEN. Then share a Notion page with the integration and pass it as --parent-page.",
+        { needs: "token" },
+      );
+    }
+
+    const ncfg = loadNotionConfig();
+    const entry: NotionEntry = ncfg.sessions[slug] || {};
+    const notion = new Notion(token);
+
+    // Resolve / verify the root page. With --replace, force a fresh root.
+    let rootId = opts.replace ? "" : entry.rootPageId || "";
+    if (rootId && !(await notion.pageExists(rootId))) rootId = "";
+    if (!rootId) {
+      const parentInput = opts.parentPage || process.env["THOUGHT_LAYER_NOTION_PARENT"] || "";
+      const parentId = pageIdFromInput(parentInput);
+      if (!parentId) {
+        return fail(
+          "No Notion parent page. Share a page with your integration in Notion (Share, then add your integration), then pass it as --parent-page <id or url>.",
+          { needs: "parent-page" },
+        );
+      }
+      if (!(await notion.pageExists(parentId))) {
+        return fail(`Notion cannot see the parent page ${parentId}. In Notion, open the page, click Share, and add your integration so it has access.`, { needs: "share" });
+      }
+      rootId = await notion.createPage(parentId, plan.title, plan.icon);
+      entry.areaPageIds = {};
+      entry.artifactsDbId = undefined;
+    }
+    await notion.replaceChildren(rootId, plan.overview);
+
+    // Area child pages: find-or-create, then refresh content.
+    const areaIds: Record<string, string> = entry.areaPageIds || {};
+    for (const area of plan.areas) {
+      let pid = areaIds[area.key] || "";
+      if (pid && !(await notion.pageExists(pid))) pid = "";
+      if (!pid) pid = await notion.createPage(rootId, `${area.emoji} ${area.title}`, area.emoji);
+      areaIds[area.key] = pid;
+      await notion.replaceChildren(pid, area.blocks);
+    }
+
+    // Artifacts database: create once, then add a row per artifact. (Idempotent
+    // re-runs reuse the stored db; rows are appended, so --replace gives a clean
+    // db by recreating the whole wiki.)
+    let dbId = entry.artifactsDbId || "";
+    if (plan.artifacts.length && (!dbId || opts.replace)) {
+      dbId = await notion.createArtifactsDb(rootId, plan.artifacts);
+      for (const a of plan.artifacts) await notion.addArtifactRow(dbId, a);
+    }
+
+    ncfg.sessions[slug] = { rootPageId: rootId, areaPageIds: areaIds, artifactsDbId: dbId || undefined, updatedAt: Date.now() };
+    saveNotionConfig(ncfg);
+
+    const rootUrl = `https://www.notion.so/${rootId.replace(/-/g, "")}`;
+    return ok(
+      `Built the "${plan.title}" wiki in Notion: ${plan.areas.length} area page(s), ${blockCount} blocks, ${plan.artifacts.length} artifact(s) listed.` +
+        `${manifest ? "" : " No delivered artifacts were found, so the Artifacts database links are empty; run tl artifacts first."}` +
+        `\nOpen it: ${rootUrl}`,
+      { title: plan.title, rootPageId: rootId, rootUrl, areas: plan.areas.length, blockCount, artifacts: plan.artifacts.length },
+    );
+  } catch (e) {
+    return fail(`tl_wiki error: ${(e as Error).message}`);
+  }
+}

package/core/notion.ts

@@ -0,0 +1,312 @@
+// Pure mapping from a ProgressState (+ the delivered-artifacts manifest) to a
+// Notion "wiki" plan: a root page, one child page per workflow area, and an
+// Artifacts database. No fetch, no fs - the notion-io layer turns this plan into
+// API calls. Kept pure so the block construction and the API-limit chunking are
+// unit-testable without a token.
+//
+// Notion API limits this encodes: rich_text content max 2000 chars (chunkRichText),
+// at most 100 children per append (chunkChildren), and at most 2 levels of block
+// nesting per create/append (withinDepth guards it; we keep tables/toggles to one
+// nested level). Notion has no upsert, so the io layer find-or-creates by stored id.
+
+import { computeProjection, fmtMoney, type Assumptions } from "./model.ts";
+import {
+  brandGuideMarkdown, requirementsMarkdown, glossaryMarkdown, swotMarkdown,
+  type Brand, type Grill, type Swot, type ArtifactManifest,
+} from "./artifacts.ts";
+import type { ProgressState } from "./progress.ts";
+
+// Notion's free-tier single-file upload ceiling. Larger files link to GitHub.
+export const NOTION_FREE_FILE_LIMIT = 5 * 1024 * 1024;
+const RICH_TEXT_MAX = 2000;
+const CHILDREN_MAX = 100;
+
+export type Annotations = Partial<Record<"bold" | "italic" | "strikethrough" | "underline" | "code", boolean>> & { color?: string };
+export interface RichText { type: "text"; text: { content: string; link?: { url: string } | null }; annotations?: Annotations; }
+export type Block = Record<string, unknown>;
+
+const obj = (v: unknown): Record<string, unknown> => (v && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, unknown>) : {});
+const str = (v: unknown): string => (typeof v === "string" ? v : "");
+
+// ---- rich text (with the 2000-char split) ------------------------------------
+
+const rtSeg = (content: string, ann?: Annotations, link?: string): RichText => ({
+  type: "text",
+  text: { content, ...(link ? { link: { url: link } } : {}) },
+  ...(ann ? { annotations: ann } : {}),
+});
+
+// Split a string into rich_text segments no longer than 2000 chars each.
+export function chunkRichText(text: string, ann?: Annotations, link?: string): RichText[] {
+  const s = String(text ?? "");
+  if (s.length <= RICH_TEXT_MAX) return [rtSeg(s, ann, link)];
+  const out: RichText[] = [];
+  for (let i = 0; i < s.length; i += RICH_TEXT_MAX) out.push(rtSeg(s.slice(i, i + RICH_TEXT_MAX), ann, link));
+  return out;
+}
+
+// Minimal inline markdown: **bold** and `code`. Everything else is plain text.
+// Every segment is itself chunked to the 2000-char limit.
+function inline(text: string): RichText[] {
+  const out: RichText[] = [];
+  const re = /\*\*([^*]+)\*\*|`([^`]+)`/g;
+  let last = 0;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(text))) {
+    if (m.index > last) out.push(...chunkRichText(text.slice(last, m.index)));
+    if (m[1] != null) out.push(...chunkRichText(m[1], { bold: true }));
+    else if (m[2] != null) out.push(...chunkRichText(m[2], { code: true }));
+    last = re.lastIndex;
+  }
+  if (last < text.length) out.push(...chunkRichText(text.slice(last)));
+  return out.length ? out : [rtSeg("")];
+}
+
+// ---- block builders ----------------------------------------------------------
+
+const para = (text: string): Block => ({ object: "block", type: "paragraph", paragraph: { rich_text: inline(text) } });
+const heading = (level: 1 | 2 | 3, text: string): Block => {
+  const t = `heading_${level}`;
+  return { object: "block", type: t, [t]: { rich_text: inline(text) } };
+};
+const bullet = (text: string): Block => ({ object: "block", type: "bulleted_list_item", bulleted_list_item: { rich_text: inline(text) } });
+const numbered = (text: string): Block => ({ object: "block", type: "numbered_list_item", numbered_list_item: { rich_text: inline(text) } });
+const quote = (text: string): Block => ({ object: "block", type: "quote", quote: { rich_text: inline(text) } });
+const callout = (text: string, emoji = "💡"): Block => ({ object: "block", type: "callout", callout: { rich_text: inline(text), icon: { type: "emoji", emoji } } });
+const divider = (): Block => ({ object: "block", type: "divider", divider: {} });
+const codeBlock = (text: string, language = "plain text"): Block => ({ object: "block", type: "code", code: { rich_text: chunkRichText(text), language } });
+export const bookmark = (url: string): Block => ({ object: "block", type: "bookmark", bookmark: { url } });
+export const externalImage = (url: string): Block => ({ object: "block", type: "image", image: { type: "external", external: { url } } });
+
+function table(headers: string[], rows: string[][]): Block {
+  const toRow = (cells: string[]): Block => ({ object: "block", type: "table_row", table_row: { cells: cells.map((c) => chunkRichText(c)) } });
+  return {
+    object: "block",
+    type: "table",
+    table: { table_width: headers.length, has_column_header: true, has_row_header: false, children: [toRow(headers), ...rows.map(toRow)] },
+  };
+}
+
+// ---- markdown -> blocks (the workhorse; all artifacts are markdown) ----------
+
+export function markdownToBlocks(md: string): Block[] {
+  const lines = String(md ?? "").split("\n");
+  const out: Block[] = [];
+  let i = 0;
+  while (i < lines.length) {
+    const raw = lines[i] ?? "";
+    const t = raw.trim();
+    if (t.startsWith("```")) {
+      const buf: string[] = [];
+      i++;
+      while (i < lines.length && !(lines[i] ?? "").trim().startsWith("```")) { buf.push(lines[i] ?? ""); i++; }
+      i++; // skip closing fence
+      out.push(codeBlock(buf.join("\n")));
+      continue;
+    }
+    if (!t) { i++; continue; }
+    if (t === "---" || t === "***" || t === "___") { out.push(divider()); i++; continue; }
+    const mh = t.match(/^(#{1,6})\s+(.*)$/);
+    if (mh) { out.push(heading(Math.min(3, mh[1]!.length) as 1 | 2 | 3, mh[2]!)); i++; continue; }
+    if (t.startsWith("> ")) { out.push(quote(t.slice(2))); i++; continue; }
+    const mb = t.match(/^[-*]\s+(.*)$/);
+    if (mb) { out.push(bullet(mb[1]!)); i++; continue; }
+    const mn = t.match(/^\d+\.\s+(.*)$/);
+    if (mn) { out.push(numbered(mn[1]!)); i++; continue; }
+    out.push(para(t));
+    i++;
+  }
+  return out;
+}
+
+// ---- API-limit helpers (unit-tested) -----------------------------------------
+
+// Split a children array into <=100-block append batches.
+export function chunkChildren(blocks: Block[], size = CHILDREN_MAX): Block[][] {
+  const out: Block[][] = [];
+  for (let i = 0; i < blocks.length; i += size) out.push(blocks.slice(i, i + size));
+  return out.length ? out : [[]];
+}
+
+// True when no block nests deeper than maxDepth levels (Notion allows 2 per
+// create/append). We keep tables/toggles to a single nested level, so this holds.
+export function withinDepth(blocks: Block[], maxDepth = 2): boolean {
+  const depth = (bs: Block[], d: number): number => {
+    let max = d;
+    for (const b of bs) {
+      const t = b["type"] as string;
+      const inner = (obj(b[t])["children"]) as Block[] | undefined;
+      if (Array.isArray(inner) && inner.length) max = Math.max(max, depth(inner, d + 1));
+    }
+    return max;
+  };
+  return depth(blocks, 1) <= maxDepth;
+}
+
+// ---- artifact references (link vs upload decision) ---------------------------
+
+export function artifactCategory(path: string): string {
+  if (path.startsWith("Brand/")) return "Brand";
+  if (path.startsWith("Deploy/")) return "Deploy";
+  if (path.startsWith("LandingPage/")) return "Landing";
+  if (path.endsWith(".svg")) return "Infographic";
+  if (path === "BuildPrompt.md") return "Build prompt";
+  return "Doc";
+}
+
+// Decide how an artifact appears in the wiki: upload to Notion when small enough
+// and an uploadable type, else link to its GitHub copy.
+export function artifactRef(bytes: number, hasGithubUrl: boolean): "upload" | "link" {
+  return bytes <= NOTION_FREE_FILE_LIMIT && !hasGithubUrl ? "upload" : hasGithubUrl ? "link" : "upload";
+}
+
+// ---- the wiki plan -----------------------------------------------------------
+
+export interface WikiArtifact { name: string; path: string; category: string; bytes: number; url?: string; }
+export interface WikiArea { key: string; title: string; emoji: string; blocks: Block[]; }
+export interface WikiPlan { title: string; icon: string; overview: Block[]; areas: WikiArea[]; artifacts: WikiArtifact[]; }
+
+export interface WikiBuildOptions {
+  manifest?: ArtifactManifest | null;
+  urls?: Record<string, string>; // artifact relpath -> GitHub blob URL
+}
+
+// The 8 workflow areas, in order, with their emoji.
+export const WIKI_AREAS: Array<{ key: string; title: string; emoji: string }> = [
+  { key: "big-idea", title: "The Big Idea", emoji: "💡" },
+  { key: "business-model", title: "Business Model", emoji: "💰" },
+  { key: "brand", title: "Brand", emoji: "🎨" },
+  { key: "market-research", title: "Market Research", emoji: "📊" },
+  { key: "strategy", title: "Strategy", emoji: "📈" },
+  { key: "product", title: "Product (PRD)", emoji: "📋" },
+  { key: "compliance", title: "Compliance & Tax", emoji: "⚖️" },
+  { key: "decision-science", title: "Decision Science", emoji: "🧭" },
+  { key: "library", title: "Library", emoji: "📚" },
+];
+
+export function buildWikiPlan(state: ProgressState, opts: WikiBuildOptions = {}): WikiPlan {
+  const answers = obj(state.answers);
+  const brand = (state.brand && typeof state.brand === "object" ? state.brand : null) as Brand | null;
+  const guide = brand?.guide || null;
+  const grill = (state.grill && typeof state.grill === "object" ? state.grill : null) as Grill | null;
+  const swot = (state.swot && typeof state.swot === "object" ? state.swot : null) as Swot | null;
+  const prd = obj(state.prd);
+  const bizModel = obj(state.bizModel);
+  const research = obj(state.research);
+  const assumptions = (bizModel["assumptions"] || null) as Assumptions | null;
+  const brandName = str(guide?.brandName) || "Your Product";
+  const oneLiner = str(answers["what-statement"]) || str(answers["pitch"]) || str(guide?.positioning);
+
+  const overview: Block[] = [];
+  if (oneLiner) overview.push(callout(oneLiner, "💡"));
+  overview.push(para("This private workspace was generated by The Thought Layer. Each section below is a page; the Artifacts database links the files delivered to your repo."));
+
+  const areaBlocks: Record<string, Block[]> = {};
+
+  // Big idea: the one-liner, positioning, and the press release if present.
+  {
+    const b: Block[] = [];
+    if (oneLiner) b.push(heading(2, "What it is"), callout(oneLiner, "🎯"));
+    if (guide?.positioning) b.push(heading(2, "Who it is for"), para(guide.positioning));
+    const press = str(answers["press-release"]);
+    if (press) b.push(heading(2, "The press release"), ...markdownToBlocks(press));
+    areaBlocks["big-idea"] = b;
+  }
+
+  // Business model: a parties table + the projection summary.
+  {
+    const b: Block[] = [];
+    const proj = computeProjection(assumptions);
+    if (proj && assumptions) {
+      const s = proj.summary;
+      const cur = assumptions.currency || "USD";
+      b.push(heading(2, "The numbers"));
+      b.push(callout(
+        `Year 1 revenue ${fmtMoney(s.year1Revenue, cur)}. Monthly break-even ${s.breakEvenMonth ? `month ${s.breakEvenMonth}` : "beyond horizon"}. Max cash drawdown ${fmtMoney(s.maxDrawdown, cur)}. MRR at month ${s.horizon} is ${fmtMoney(s.endingMRR, cur)}.`,
+        "💰",
+      ));
+      const rows = (assumptions.parties || []).slice(0, 12).map((p) => [
+        str(p.name) || p.id, str(p.role), String(p.startingCount ?? ""), String(p.monthlyNewBase ?? ""),
+        `${p.monthlyChurnPct ?? 0}%`, fmtMoney(Number(p.revenuePerUnitPerMonth) || 0, cur), fmtMoney(Number(p.cacPerUnit) || 0, cur),
+      ]);
+      b.push(heading(2, "Parties"), table(["Party", "Role", "Start", "New/mo", "Churn", "Rev/unit/mo", "CAC"], rows));
+      if (assumptions.narrative) b.push(heading(2, "Notes"), para(assumptions.narrative));
+    }
+    areaBlocks["business-model"] = b;
+  }
+
+  // Brand: the style guide rendered natively, plus a palette table.
+  {
+    const b: Block[] = [];
+    if (guide) {
+      b.push(...markdownToBlocks(brandGuideMarkdown(guide)));
+      const pal = (guide.palette || []).filter((p) => p?.hex);
+      if (pal.length) b.push(heading(2, "Palette"), table(["Color", "Hex", "Role"], pal.map((p) => [str(p.name), str(p.hex), str(p.role)])));
+    }
+    areaBlocks["brand"] = b;
+  }
+
+  // Market research.
+  {
+    const b: Block[] = [];
+    const brief = str(research["brief"]);
+    if (brief) {
+      const desc = str(research["description"]);
+      if (desc) b.push(callout(desc, "📊"));
+      b.push(...markdownToBlocks(brief));
+    }
+    areaBlocks["market-research"] = b;
+  }
+
+  // Strategy: the SWOT.
+  {
+    const b: Block[] = [];
+    const hasSwot = !!swot && Object.values(swot).some((v) => Array.isArray(v) && v.some((x) => x && String(x).trim()));
+    if (hasSwot) b.push(...markdownToBlocks(swotMarkdown(swot)));
+    areaBlocks["strategy"] = b;
+  }
+
+  // Product: the PRD, requirements, and glossary.
+  {
+    const b: Block[] = [];
+    const prdMd = str(prd["markdown"]);
+    if (prdMd) b.push(...markdownToBlocks(prdMd));
+    if (grill?.requirements?.length) { b.push(divider()); b.push(...markdownToBlocks(requirementsMarkdown(grill))); }
+    if (grill?.glossary?.length) { b.push(divider()); b.push(...markdownToBlocks(glossaryMarkdown(grill))); }
+    areaBlocks["product"] = b;
+  }
+
+  // Compliance: the researched GRC, licensing, and tax report (from the
+  // thought-layer-compliance skill). The report carries its own disclaimer.
+  {
+    const b: Block[] = [];
+    const report = str(obj(state.governance)["report"]);
+    if (report.trim()) b.push(...markdownToBlocks(report));
+    areaBlocks["compliance"] = b;
+  }
+
+  // Decision science: any dq-* / decision-* answers.
+  {
+    const b: Block[] = [];
+    const dq = Object.keys(answers).filter((k) => /^(dq|decision)/i.test(k) && str(answers[k]).trim());
+    if (dq.length) { b.push(heading(2, "Decision records")); for (const k of dq) b.push(bullet(`**${k}**: ${str(answers[k])}`)); }
+    areaBlocks["decision-science"] = b;
+  }
+
+  // Library: no structured data in state; left empty (the io layer skips empties).
+  areaBlocks["library"] = [];
+
+  const areas: WikiArea[] = WIKI_AREAS
+    .map((a) => ({ ...a, blocks: areaBlocks[a.key] || [] }))
+    .filter((a) => a.blocks.length > 0);
+
+  // Artifacts for the database: skip the landing-page SEO sidecars (keep only
+  // index.html), keep everything else.
+  const urls = opts.urls || {};
+  const files = opts.manifest?.files || [];
+  const artifacts: WikiArtifact[] = files
+    .filter((f) => !(f.path.startsWith("LandingPage/") && f.path !== "LandingPage/index.html"))
+    .map((f) => ({ name: f.path, path: f.path, category: artifactCategory(f.path), bytes: f.bytes, ...(urls[f.path] ? { url: urls[f.path] } : {}) }));
+
+  return { title: `${brandName} workspace`, icon: "🚀", overview, areas, artifacts };
+}