@hobocode/thought-layer 0.8.5 → 0.8.6

package/README.md

@@ -73,7 +73,7 @@ The hosted version of the rigor lives at [weareallproductmanagersnow.com](https:
 - **Phase 4 (done):** a `deploy` step (`/tl-deploy`, the `deploy` tool, or `tl deploy`) that takes the build live to a URL you own, closing the loop. With a Netlify token it deploys into your own account via the file-digest API (owned immediately, no claim step); with no token it delegates to your Netlify CLI - logged in it creates a site in your account, logged out it deploys anonymously with a one-hour claim link. BYOK, no central account, no lock-in. `--dry-run` shows the plan first.
 - **Backend-capable build (done):** when the three-question backend test shows a product genuinely needs a server, `/tl-build` emits a real backend alongside the static front end (serverless functions per backend requirement, a `schema.sql`, a names-only `.env.example`, an updated `netlify.toml`, and a `BACKEND.md` guide), with Neon Postgres as the documented default and overridable to any Postgres. Static stays the default, gated by the same backend test.
 - **Backend deploy (done):** when `build.json` declares a backend, `/tl-deploy` (the `deploy` tool, or `tl deploy`) ships it automatically alongside the front end: the functions go up via your Netlify CLI and the declared env var names are set on the site (values read only from your environment, BYOK). `DATABASE_URL` is bring-your-own by default; `--provision-db` (your own Neon key) and `--apply-schema` (psql) are opt in, and `--static-only` ships just the front end. Owned, no lock-in.
-- **Artifacts and wiki (done):** `tl artifacts` (the `tl_artifacts` tool) delivers the full asset bundle for a session, the PRD, brand guide + look book + logo, SWOT and business-model infographics, market research, a landing page, and any build/deploy provenance, to your own private sessions repo under `artifacts/<session>/`. `tl wiki` (the `tl_wiki` tool) then builds a **private Notion wiki**, an internal intranet that organizes all of it into a page per workflow area plus an Artifacts database that links each file. Notion pages are private to your own workspace (auth, not public); the integration token is BYOK from the environment. Free for one user, upgradeable for a team.
+- **Artifacts and wiki (done):** `tl artifacts` (the `tl_artifacts` tool) delivers the full asset bundle for a session, the PRD, brand guide + look book + logo, SWOT and business-model infographics, market research, a landing page, and any build/deploy provenance, to your own private sessions repo under `artifacts/<session>/`. `tl wiki` (the `tl_wiki` tool) then builds a **private Notion wiki**, an internal intranet that organizes all of it into a page per workflow area plus an Artifacts database that links each file. Notion pages are private to your own workspace (auth, not public); the integration token is BYOK from the environment. If your agent already has a **Notion MCP / connector**, `tl wiki --emit-plan` (or `tl_wiki { emitPlan: true }`) returns the wiki as per-area markdown so the agent builds it through that MCP with no token at all; the BYOK token stays the floor for hosts without one. Free for one user, upgradeable for a team.
 - **Sessions and collaboration (done):** `tl sync` (and the `tl_sync` tool) stores your session files in your OWN private GitHub repo. Save any number of named sessions (one private repo for your own projects, a separate repo per founder you collaborate with), list and open them, and sync. Git carries history and multi-user; the kit reconciles concurrent edits itself (newest wins per field, conflicts reported), so it never hand-merges JSON. Collaboration is granted on GitHub (you add collaborators, the kit never changes permissions). BYOK, no central account.
 
 ## Notes for contributors

package/core/notion-io.ts

@@ -16,7 +16,7 @@ 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 { buildWikiPlan, wikiPlanToMarkdown, chunkChildren, type Block, type WikiPlan, type WikiArtifact } from "./notion.ts";
 import type { ArtifactManifest } from "./artifacts.ts";
 import type { StateOpResult } from "./state-ops.ts";
 
@@ -33,6 +33,7 @@ export interface WikiRunOptions {
   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
+  emitPlan?: boolean; // emit the plan as agent-replayable markdown (MCP path), no token, no network
 }
 
 const ok = (message: string, details: Record<string, unknown> = {}): StateOpResult => ({ ok: true, message, details });
@@ -223,6 +224,21 @@ export async function runWiki(opts: WikiRunOptions): Promise<StateOpResult> {
       );
     }
 
+    // Emit the plan as agent-replayable markdown (no token, no network). This is
+    // the MCP path: when the agent already holds a Notion MCP, it creates the
+    // pages itself from this plan instead of the kit calling Notion with a token.
+    if (opts.emitPlan) {
+      const pm = wikiPlanToMarkdown(plan);
+      const areaList = pm.areas.map((a) => `${a.emoji} ${a.title}`).join(", ");
+      return ok(
+        `Wiki plan for "${plan.title}" ready (no Notion call, no token needed): a root page, ${pm.areas.length} child page(s), ${blockCount} blocks, ${pm.artifacts.length} artifact(s). ` +
+          `Create them with your connected Notion MCP: a root page "${plan.title}", one child page per area (each area's markdown is in the plan), and an Artifacts database with the listed files.` +
+          `${manifest ? "" : " No delivered artifacts were found, so the Artifacts list is empty; run tl artifacts first to add GitHub links."}` +
+          `\nAreas: ${areaList || "(none with content yet)"}.`,
+        { plan: pm, 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) {

package/core/notion.ts

@@ -119,6 +119,106 @@ export function markdownToBlocks(md: string): Block[] {
   return out;
 }
 
+// ---- blocks -> markdown (the inverse; the agent-replayable wiki plan) ---------
+
+// Reverse rich_text segments to inline markdown. Adjacent segments that share
+// formatting are merged first (undoing the 2000-char split), so a long bold run
+// renders as one **...** rather than several.
+function richTextToMarkdown(rt: RichText[]): string {
+  if (!rt || !rt.length) return "";
+  const sig = (s: RichText): string => {
+    const a = s.annotations || {};
+    return `${a.bold ? 1 : 0}${a.italic ? 1 : 0}${a.code ? 1 : 0}|${s.text.link?.url || ""}`;
+  };
+  const merged: RichText[] = [];
+  for (const s of rt) {
+    const prev = merged[merged.length - 1];
+    if (prev && sig(prev) === sig(s)) prev.text.content += s.text.content;
+    else merged.push({ type: "text", text: { content: s.text.content, ...(s.text.link ? { link: s.text.link } : {}) }, ...(s.annotations ? { annotations: { ...s.annotations } } : {}) });
+  }
+  return merged
+    .map((seg) => {
+      const a = seg.annotations || {};
+      let t = seg.text.content;
+      if (a.code) t = "`" + t + "`";
+      else {
+        if (a.bold) t = `**${t}**`;
+        if (a.italic) t = `*${t}*`;
+      }
+      const link = seg.text.link?.url;
+      return link ? `[${t}](${link})` : t;
+    })
+    .join("");
+}
+
+// The plain (unformatted) concatenation of a rich_text run, for code blocks and
+// table cells where inline markdown would be wrong.
+function richTextToPlain(rt: RichText[]): string {
+  return (rt || []).map((s) => s.text.content).join("");
+}
+
+function tableToMarkdown(tbl: Record<string, unknown>): string {
+  const rows = ((tbl["children"] as Block[]) || []).map((r) =>
+    (((obj(r["table_row"])["cells"]) as RichText[][]) || []).map((c) =>
+      richTextToPlain(c).replace(/\|/g, "\\|").replace(/\n+/g, " ").trim(),
+    ),
+  );
+  if (!rows.length) return "";
+  const width = Math.max(...rows.map((r) => r.length));
+  const pad = (r: string[]): string[] => { const c = r.slice(); while (c.length < width) c.push(""); return c; };
+  const line = (cells: string[]): string => `| ${cells.join(" | ")} |`;
+  const [header, ...body] = rows;
+  const out = [line(pad(header!)), line(pad(header!).map(() => "---"))];
+  for (const r of body) out.push(line(pad(r)));
+  return out.join("\n");
+}
+
+// Render a flat block array back to GitHub-flavored markdown: the inverse of
+// markdownToBlocks plus the synthesized blocks buildWikiPlan adds (callouts,
+// tables). Consecutive list items stay tight; other blocks get a blank line.
+export function blocksToMarkdown(blocks: Block[]): string {
+  const isList = (t: string): boolean => t === "bulleted_list_item" || t === "numbered_list_item";
+  const parts: string[] = [];
+  let prevType = "";
+  let numbered = 0;
+  for (const b of blocks || []) {
+    const type = str(b["type"]);
+    const data = obj(b[type]);
+    const rt = (data["rich_text"] as RichText[]) || [];
+    if (type !== "numbered_list_item") numbered = 0;
+    let rendered: string;
+    switch (type) {
+      case "heading_1": rendered = `# ${richTextToMarkdown(rt)}`; break;
+      case "heading_2": rendered = `## ${richTextToMarkdown(rt)}`; break;
+      case "heading_3": rendered = `### ${richTextToMarkdown(rt)}`; break;
+      case "bulleted_list_item": rendered = `- ${richTextToMarkdown(rt)}`; break;
+      case "numbered_list_item": rendered = `${++numbered}. ${richTextToMarkdown(rt)}`; break;
+      case "quote": rendered = `> ${richTextToMarkdown(rt)}`; break;
+      case "callout": {
+        const emoji = str(obj(data["icon"])["emoji"]);
+        rendered = `> ${emoji ? `${emoji} ` : ""}${richTextToMarkdown(rt)}`;
+        break;
+      }
+      case "divider": rendered = "---"; break;
+      case "code": {
+        const lang = str(data["language"]);
+        rendered = "```" + (lang && lang !== "plain text" ? lang : "") + "\n" + richTextToPlain(rt) + "\n```";
+        break;
+      }
+      case "table": rendered = tableToMarkdown(data); break;
+      case "bookmark": rendered = str(data["url"]); break;
+      case "image": { const u = str(obj(data["external"])["url"]); rendered = u ? `![](${u})` : ""; break; }
+      case "paragraph": rendered = richTextToMarkdown(rt); break;
+      default: rendered = richTextToMarkdown(rt);
+    }
+    if (!rendered && type !== "divider") continue;
+    const sep = parts.length === 0 ? "" : isList(type) && isList(prevType) ? "\n" : "\n\n";
+    parts.push(sep + rendered);
+    prevType = type;
+  }
+  return parts.join("");
+}
+
 // ---- API-limit helpers (unit-tested) -----------------------------------------
 
 // Split a children array into <=100-block append batches.
@@ -310,3 +410,29 @@ export function buildWikiPlan(state: ProgressState, opts: WikiBuildOptions = {})
 
   return { title: `${brandName} workspace`, icon: "🚀", overview, areas, artifacts };
 }
+
+// ---- the agent-replayable plan (markdown per area; no token, no network) ------
+
+export interface WikiPlanArea { key: string; title: string; emoji: string; markdown: string; }
+export interface WikiPlanMarkdown {
+  title: string;
+  icon: string;
+  overview: string;
+  areas: WikiPlanArea[];
+  artifacts: WikiArtifact[];
+}
+
+// Render a WikiPlan to per-area markdown so an agent that already holds a Notion
+// MCP can replay it (create a root page, one child page per area, an Artifacts
+// database) without the kit ever touching Notion or needing a token. The token
+// path (notion-io) renders the same plan as native blocks; this is the same
+// content, one canonical plan with two executors.
+export function wikiPlanToMarkdown(plan: WikiPlan): WikiPlanMarkdown {
+  return {
+    title: plan.title,
+    icon: plan.icon,
+    overview: blocksToMarkdown(plan.overview),
+    areas: plan.areas.map((a) => ({ key: a.key, title: a.title, emoji: a.emoji, markdown: blocksToMarkdown(a.blocks) })),
+    artifacts: plan.artifacts,
+  };
+}

package/dist/tl.js

@@ -2841,6 +2841,119 @@ function markdownToBlocks(md) {
   }
   return out;
 }
+function richTextToMarkdown(rt) {
+  if (!rt || !rt.length) return "";
+  const sig = (s) => {
+    const a = s.annotations || {};
+    return `${a.bold ? 1 : 0}${a.italic ? 1 : 0}${a.code ? 1 : 0}|${s.text.link?.url || ""}`;
+  };
+  const merged = [];
+  for (const s of rt) {
+    const prev = merged[merged.length - 1];
+    if (prev && sig(prev) === sig(s)) prev.text.content += s.text.content;
+    else merged.push({ type: "text", text: { content: s.text.content, ...s.text.link ? { link: s.text.link } : {} }, ...s.annotations ? { annotations: { ...s.annotations } } : {} });
+  }
+  return merged.map((seg) => {
+    const a = seg.annotations || {};
+    let t = seg.text.content;
+    if (a.code) t = "`" + t + "`";
+    else {
+      if (a.bold) t = `**${t}**`;
+      if (a.italic) t = `*${t}*`;
+    }
+    const link = seg.text.link?.url;
+    return link ? `[${t}](${link})` : t;
+  }).join("");
+}
+function richTextToPlain(rt) {
+  return (rt || []).map((s) => s.text.content).join("");
+}
+function tableToMarkdown(tbl) {
+  const rows = (tbl["children"] || []).map(
+    (r) => (obj2(r["table_row"])["cells"] || []).map(
+      (c) => richTextToPlain(c).replace(/\|/g, "\\|").replace(/\n+/g, " ").trim()
+    )
+  );
+  if (!rows.length) return "";
+  const width = Math.max(...rows.map((r) => r.length));
+  const pad = (r) => {
+    const c = r.slice();
+    while (c.length < width) c.push("");
+    return c;
+  };
+  const line = (cells) => `| ${cells.join(" | ")} |`;
+  const [header, ...body] = rows;
+  const out = [line(pad(header)), line(pad(header).map(() => "---"))];
+  for (const r of body) out.push(line(pad(r)));
+  return out.join("\n");
+}
+function blocksToMarkdown(blocks) {
+  const isList = (t) => t === "bulleted_list_item" || t === "numbered_list_item";
+  const parts = [];
+  let prevType = "";
+  let numbered2 = 0;
+  for (const b of blocks || []) {
+    const type = str3(b["type"]);
+    const data = obj2(b[type]);
+    const rt = data["rich_text"] || [];
+    if (type !== "numbered_list_item") numbered2 = 0;
+    let rendered;
+    switch (type) {
+      case "heading_1":
+        rendered = `# ${richTextToMarkdown(rt)}`;
+        break;
+      case "heading_2":
+        rendered = `## ${richTextToMarkdown(rt)}`;
+        break;
+      case "heading_3":
+        rendered = `### ${richTextToMarkdown(rt)}`;
+        break;
+      case "bulleted_list_item":
+        rendered = `- ${richTextToMarkdown(rt)}`;
+        break;
+      case "numbered_list_item":
+        rendered = `${++numbered2}. ${richTextToMarkdown(rt)}`;
+        break;
+      case "quote":
+        rendered = `> ${richTextToMarkdown(rt)}`;
+        break;
+      case "callout": {
+        const emoji = str3(obj2(data["icon"])["emoji"]);
+        rendered = `> ${emoji ? `${emoji} ` : ""}${richTextToMarkdown(rt)}`;
+        break;
+      }
+      case "divider":
+        rendered = "---";
+        break;
+      case "code": {
+        const lang = str3(data["language"]);
+        rendered = "```" + (lang && lang !== "plain text" ? lang : "") + "\n" + richTextToPlain(rt) + "\n```";
+        break;
+      }
+      case "table":
+        rendered = tableToMarkdown(data);
+        break;
+      case "bookmark":
+        rendered = str3(data["url"]);
+        break;
+      case "image": {
+        const u = str3(obj2(data["external"])["url"]);
+        rendered = u ? `![](${u})` : "";
+        break;
+      }
+      case "paragraph":
+        rendered = richTextToMarkdown(rt);
+        break;
+      default:
+        rendered = richTextToMarkdown(rt);
+    }
+    if (!rendered && type !== "divider") continue;
+    const sep = parts.length === 0 ? "" : isList(type) && isList(prevType) ? "\n" : "\n\n";
+    parts.push(sep + rendered);
+    prevType = type;
+  }
+  return parts.join("");
+}
 function chunkChildren(blocks, size = CHILDREN_MAX) {
   const out = [];
   for (let i = 0; i < blocks.length; i += size) out.push(blocks.slice(i, i + size));
@@ -2975,6 +3088,15 @@ function buildWikiPlan(state, opts = {}) {
   const artifacts = 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: "\u{1F680}", overview, areas, artifacts };
 }
+function wikiPlanToMarkdown(plan) {
+  return {
+    title: plan.title,
+    icon: plan.icon,
+    overview: blocksToMarkdown(plan.overview),
+    areas: plan.areas.map((a) => ({ key: a.key, title: a.title, emoji: a.emoji, markdown: blocksToMarkdown(a.blocks) })),
+    artifacts: plan.artifacts
+  };
+}
 
 // core/notion-io.ts
 var NOTION_API = "https://api.notion.com/v1";
@@ -3152,6 +3274,15 @@ Areas: ${areaList || "(none with content yet)"}.${manifest ? "" : "\nNo delivere
         { title: plan.title, areas: plan.areas.map((a) => ({ key: a.key, blocks: a.blocks.length })), blockCount, artifacts: plan.artifacts.length, delivered: !!manifest }
       );
     }
+    if (opts.emitPlan) {
+      const pm = wikiPlanToMarkdown(plan);
+      const areaList = pm.areas.map((a) => `${a.emoji} ${a.title}`).join(", ");
+      return ok3(
+        `Wiki plan for "${plan.title}" ready (no Notion call, no token needed): a root page, ${pm.areas.length} child page(s), ${blockCount} blocks, ${pm.artifacts.length} artifact(s). Create them with your connected Notion MCP: a root page "${plan.title}", one child page per area (each area's markdown is in the plan), and an Artifacts database with the listed files.${manifest ? "" : " No delivered artifacts were found, so the Artifacts list is empty; run tl artifacts first to add GitHub links."}
+Areas: ${areaList || "(none with content yet)"}.`,
+        { plan: pm, delivered: !!manifest }
+      );
+    }
     const token = TOKEN_ENVS.map((e) => process.env[e]).find((v) => v && v.trim())?.trim() || "";
     if (!token) {
       return fail3(
@@ -3220,7 +3351,8 @@ var HELP = `tl - read/write a portable Thought Layer state file (default: .thoug
   tl artifacts [--name x] [--workspace w]                    deliver the full asset bundle (PRD, brand, infographics, landing, deploy rules) to your sessions repo
             [--no-push] [--no-deliver] [--domain x.com] [--founder "Name"]
   tl wiki [--parent-page id|url] [--name x]                  build/refresh a private Notion wiki from the session + delivered artifacts
-            [--workspace w] [--replace] [--dry-run]            (set THOUGHT_LAYER_NOTION_TOKEN; share a Notion page with your integration)
+            [--workspace w] [--replace] [--dry-run]            token path: set THOUGHT_LAYER_NOTION_TOKEN and share a Notion page with your integration
+            [--emit-plan]                                      or emit the wiki as per-area markdown to build via a connected Notion MCP (no token)
   tl export [path]                   handoff check
   tl answer <qId> <value> [path]     record an answer
   tl feedback --data '<json>'        record a panel verdict ({qId,mode,personas,endState,round})
@@ -3376,7 +3508,8 @@ function main() {
       dir: typeof flags["dir"] === "string" ? flags["dir"] : void 0,
       parentPage: typeof flags["parent-page"] === "string" ? flags["parent-page"] : void 0,
       replace: flags["replace"] === true,
-      dryRun: flags["dry-run"] === true
+      dryRun: flags["dry-run"] === true,
+      emitPlan: flags["emit-plan"] === true
     }).then((r2) => {
       if (flags["json"]) console.log(JSON.stringify(r2.details, null, 2));
       else console.log(r2.message);

package/extensions/thought-layer.ts

@@ -312,7 +312,8 @@ export default function (pi: ExtensionAPI) {
     description:
       "Build or refresh a PRIVATE Notion wiki (an internal intranet) for a session: a root page, one child page per workflow area (Big Idea, Business Model, Brand, Market Research, Strategy, PRD, Decision Science), rendered natively in Notion, plus an Artifacts database that links the files delivered by tl_artifacts. " +
       "Notion pages are private to the user's workspace, so this satisfies an auth requirement with no public exposure. BYOK: the integration token is read ONLY from THOUGHT_LAYER_NOTION_TOKEN (or NOTION_TOKEN) in the environment, never a parameter. Setup once: create an internal integration at notion.so/my-integrations, set the token, share a page with the integration, and pass that page as parentPage. " +
-      "Idempotent: it stores the page ids locally and refreshes content on re-run; replace recreates the wiki from scratch; dryRun reports the plan with no network call. Run tl_artifacts first so the Artifacts database has GitHub links.",
+      "Idempotent: it stores the page ids locally and refreshes content on re-run; replace recreates the wiki from scratch; dryRun reports the plan with no network call. Run tl_artifacts first so the Artifacts database has GitHub links. " +
+      "If you already have a Notion MCP connected, prefer emitPlan:true: it returns the wiki as per-area markdown (no token, no network) for you to create the pages and Artifacts database through that MCP; the token path stays the fallback.",
     parameters: Type.Object({
       name: Type.Optional(Type.String({ description: "Session name to publish (defaults to the workspace's active session)." })),
       parentPage: Type.Optional(Type.String({ description: "Notion page id or URL the integration is shared with (where the wiki root is created). Or set THOUGHT_LAYER_NOTION_PARENT." })),
@@ -321,10 +322,11 @@ export default function (pi: ExtensionAPI) {
       dir: Type.Optional(Type.String({ description: "Explicit clone dir for the workspace." })),
       replace: Type.Optional(Type.Boolean({ description: "Recreate the wiki from scratch (new pages) instead of refreshing the existing one." })),
       dryRun: Type.Optional(Type.Boolean({ description: "Build the plan and report area/block/artifact counts with no network call." })),
+      emitPlan: Type.Optional(Type.Boolean({ description: "Return the wiki as per-area markdown (the agent-replayable plan) with no token and no network call, so you can create the pages through a connected Notion MCP. The plan is in the result details under `plan`." })),
     }),
     async execute(_id, params): Promise<ToolResult> {
-      const p = params as { name?: string; parentPage?: string; workspace?: string; path?: string; dir?: string; replace?: boolean; dryRun?: boolean };
-      const r = await runWiki({ name: p.name, parentPage: p.parentPage, workspace: p.workspace, path: p.path, dir: p.dir, replace: p.replace, dryRun: p.dryRun });
+      const p = params as { name?: string; parentPage?: string; workspace?: string; path?: string; dir?: string; replace?: boolean; dryRun?: boolean; emitPlan?: boolean };
+      const r = await runWiki({ name: p.name, parentPage: p.parentPage, workspace: p.workspace, path: p.path, dir: p.dir, replace: p.replace, dryRun: p.dryRun, emitPlan: p.emitPlan });
       return text(r.message, r.details);
     },
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hobocode/thought-layer",
-  "version": "0.8.5",
+  "version": "0.8.6",
   "description": "The Thought Layer: rigor for building. Validate an idea, grill it into a buildable spec, then build and deploy it, inside the agent you already use. BYOK, no telemetry.",
   "license": "MIT",
   "author": "Hobocode LLC <jerm@hobocode.net>",

package/prompts/tl-wiki.md

@@ -2,8 +2,10 @@ Apply the **thought-layer-wiki** skill. Build me a private Notion wiki, an inter
 
 First make sure I have delivered the artifacts (`tl artifacts --name <session>`), so the wiki can link to the files in my repo; if I have not, build from the session state and tell me the Artifacts database will be empty until I deliver them. The wiki reads my session from my private sessions repo, so honor `--name` / `--workspace` / `--dir`.
 
-Read my Notion token only from the environment (`THOUGHT_LAYER_NOTION_TOKEN` or `NOTION_TOKEN`), never ask me to paste it. I create an internal integration at notion.so/my-integrations, set the token, and share a Notion page with the integration; pass that page as `--parent-page <id or url>`. If the token or the parent page is missing, tell me exactly what to do rather than pretending it worked.
+**Check what you have first.** If you already have a Notion MCP connected, prefer it and skip the token entirely: run `tl wiki --name <session> --emit-plan` (no token, no network call) to get the wiki as per-area markdown, then create the root "<Product> workspace" page, one child page per area, and the Artifacts database through that MCP. Search Notion for an existing "<Product> workspace" page first so a re-run updates it instead of creating a duplicate, and ask me which Notion page should hold the wiki if you do not already know.
 
-Dry-run first (`tl wiki --name <session> --dry-run`) so I can see the area pages, block counts, and artifact count. Then build it: a root "<Product> workspace" page, a child page per workflow area that has content (Big Idea, Business Model, Brand, Market Research, Strategy, PRD, Decision Science), rendered natively in Notion, plus an Artifacts database that links each delivered file to its GitHub copy. Upload small files only where no link exists; Notion's free tier caps uploads at 5 MiB, so larger files link out.
+Otherwise (no Notion MCP), use the token path. Read my Notion token only from the environment (`THOUGHT_LAYER_NOTION_TOKEN` or `NOTION_TOKEN`), never ask me to paste it. I create an internal integration at notion.so/my-integrations, set the token, and share a Notion page with the integration; pass that page as `--parent-page <id or url>`. Dry-run first (`tl wiki --name <session> --dry-run`) so I can see the area pages, block counts, and artifact count. If the token or the parent page is missing, tell me exactly what to do rather than pretending it worked.
 
-It is idempotent: re-running refreshes the existing pages (the page ids are stored locally, never synced); `--replace` rebuilds from scratch. After it is built, give me the root page URL.
+Either way, build: a root "<Product> workspace" page, a child page per workflow area that has content (Big Idea, Business Model, Brand, Market Research, Strategy, PRD, Compliance & Tax, Decision Science), rendered natively in Notion, plus an Artifacts database that links each delivered file to its GitHub copy. Upload small files only where no link exists; Notion's free tier caps uploads at 5 MiB, so larger files link out.
+
+The token path is idempotent: re-running refreshes the existing pages (the page ids are stored locally, never synced); `--replace` rebuilds from scratch. The MCP path has no local id-map, so search for the existing wiki page first to avoid duplicates. After it is built, give me the root page URL.

package/skills/thought-layer-wiki/SKILL.md

@@ -11,9 +11,25 @@ The wiki is the founder's keepable home for everything the workflow produced: th
 
 1. **A sessions workspace.** The wiki reads the session from the user's private sessions repo (set up by the `tl_sync` tool / `tl sync init`). Honor the usual selection: `--name <session>` (or the workspace's active session), `--workspace <label>`, or an explicit `--dir`.
 2. **Delivered artifacts (recommended).** Run the `tl_artifacts` tool / **`tl artifacts`** first so `artifacts/<session>/artifacts.json` exists. The wiki reads it to fill the Artifacts database with GitHub links. Without it, the wiki still builds from the session state, but the Artifacts database is empty; the tool says so. Tell the user to deliver artifacts first for the full result.
-3. **A Notion integration (one-time, BYOK).** The user creates an internal integration at https://www.notion.so/my-integrations, copies the secret, and sets it as `THOUGHT_LAYER_NOTION_TOKEN` (or `NOTION_TOKEN`) in the environment. Then, in Notion, they open the page that should hold the wiki, click **Share**, and add the integration so it has access. That page's id or URL is the `parent-page`. The token is read **only from the environment**; never ask the user to paste it into the chat or put it in a parameter or file.
+3. **Notion access (one of two ways).** Either (a) a **Notion MCP / connector** already authorized to the user's workspace, in which case you need no token at all (see "Two ways to build it" below); or (b) a one-time **BYOK integration**: the user creates an internal integration at https://www.notion.so/my-integrations, copies the secret, sets it as `THOUGHT_LAYER_NOTION_TOKEN` (or `NOTION_TOKEN`) in the environment, then in Notion opens the page that should hold the wiki, clicks **Share**, and adds the integration so it has access. That page's id or URL is the `parent-page`. The token is read **only from the environment**; never ask the user to paste it into the chat or put it in a parameter or file.
 
-## How to run it
+## Two ways to build it
+
+**First check what you have.** If you (the agent) already have a **Notion MCP / connector** authorized to the user's workspace, prefer it — the user skips the entire integration-token setup. Otherwise use the BYOK token path, which stays the universal floor (the browser SPA and a plain CLI/CI host have no MCP). Both paths render the **same plan**; pick one.
+
+### A. Notion MCP connected (preferred, no token)
+
+Build the wiki through the MCP and never ask for a token:
+
+1. **Get the plan:** `tl wiki --name <session> --emit-plan --json` (or the `tl_wiki` tool with `emitPlan: true`). With **no token and no network call** it returns `{ title, icon, overview, areas: [{ key, title, emoji, markdown }], artifacts: [{ name, category, bytes, url? }] }`. Each area's `markdown` is the ready-to-post page body.
+2. **Pick the parent.** Ask the user which Notion page should hold the wiki, unless they already said.
+3. **Avoid duplicates first.** The local id-map (`~/.thought-layer/notion.json`) is written only by the token path, so on the MCP path it does not exist. Before creating, **search Notion for an existing page titled `<title>`**; if it exists, update it in place; otherwise create it. If you cannot search, ask the user whether to create fresh or point you at the existing page.
+4. **Create the root page** titled `plan.title` under the parent (icon `plan.icon`), with `overview` as its body.
+5. **Create one child page per area** in `areas[]`, titled `"<emoji> <title>"`, with that area's `markdown` as the body.
+6. **Create the Artifacts database** under the root with columns Name, Category, Size, Link, and one row per `artifacts[]` entry (use its `url` for Link when present).
+7. **Report the root page URL.**
+
+### B. No MCP: the BYOK token path (the floor)
 
 Use the tool, never a hand-written Notion `curl`:
 - **Pi:** the `tl_wiki` tool. Start with `tl_wiki { name, dryRun: true }` to show the plan (area pages, block counts, artifact count), then `tl_wiki { name, parentPage }` to build it.
@@ -21,6 +37,8 @@ Use the tool, never a hand-written Notion `curl`:
 
 Always **dry-run first** and show the user the area + artifact plan, then build.
 
+> GitHub needs no equivalent path: `tl artifacts` and `tl sync` already authenticate via the `gh`/git keyring (no token paste), so a GitHub MCP is not required for delivery.
+
 ## What it builds
 
 - A root page **"<Product> workspace"** under the shared parent page.