@hobocode/thought-layer 0.6.0 → 0.7.0

package/dist/tl.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // bin/tl.ts
-import { readFileSync as readFileSync3 } from "fs";
+import { readFileSync as readFileSync4 } from "fs";
 
 // core/scoring.ts
 var CONFIDENCE_GOAL = 0.85;
@@ -72,6 +72,20 @@ var KIT_WRITTEN_QIDS = [
 // core/progress.ts
 var APP = "thought-layer";
 var PROGRESS_FORMAT = 2;
+var KNOWN_STATE_KEYS = [
+  "version",
+  "answers",
+  "feedback",
+  "bizModel",
+  "grill",
+  "assets",
+  "research",
+  "swot",
+  "prd",
+  "naming",
+  "brand",
+  "kit"
+];
 function emptyState() {
   return {
     version: 2,
@@ -319,7 +333,7 @@ var ARTIFACT_KEYS = ["bizModel", "grill", "assets", "research", "swot", "prd", "
 var END_STATES = ["open", "pass", "setAside"];
 function applyStateOp(p, ctx) {
   const { ts, exportedAt } = ctx;
-  const fail = (message) => ({ ok: false, message, details: {} });
+  const fail2 = (message) => ({ ok: false, message, details: {} });
   try {
     if (p.op === "list") {
       const files = listStateFiles(p.path);
@@ -354,12 +368,12 @@ Pick one with --path .thought-layer/<name>.json, or set ${STATE_ENV} for the ses
       return { ok: true, message, details: { path: loaded.path, exists: loaded.exists, summary: sum, state: loaded.state } };
     }
     if (p.op === "answer") {
-      if (!p.qId || typeof p.value !== "string") return fail("answer needs a qId and a string value.");
+      if (!p.qId || typeof p.value !== "string") return fail2("answer needs a qId and a string value.");
       const path = save(setAnswer(loaded.state, p.qId, p.value, ts));
       return { ok: true, message: `Recorded answer for "${p.qId}" and saved ${path}.`, details: { path, qId: p.qId } };
     }
     if (p.op === "feedback") {
-      if (!p.qId || !p.personas?.length) return fail("feedback needs a qId and at least one persona.");
+      if (!p.qId || !p.personas?.length) return fail2("feedback needs a qId and at least one persona.");
       const endState = END_STATES.includes(p.endState || "") ? p.endState : "open";
       const mode = p.mode || (p.personas.length > 1 ? "panel" : p.personas[0].persona);
       const entry = buildFeedbackEntry({ mode, personas: p.personas, endState, round: p.round, ts });
@@ -376,24 +390,24 @@ Pick one with --path .thought-layer/<name>.json, or set ${STATE_ENV} for the ses
     }
     if (p.op === "artifact") {
       const key = p.artifact;
-      if (!ARTIFACT_KEYS.includes(key)) return fail(`artifact needs a key in: ${ARTIFACT_KEYS.join(", ")}.`);
-      if (p.value == null) return fail("artifact needs a value object.");
+      if (!ARTIFACT_KEYS.includes(key)) return fail2(`artifact needs a key in: ${ARTIFACT_KEYS.join(", ")}.`);
+      if (p.value == null) return fail2("artifact needs a value object.");
       const path = save(setArtifact(loaded.state, key, normalizeArtifactValue(key, p.value), ts));
       return { ok: true, message: `Stored ${key} artifact and saved ${path}.`, details: { path, artifact: key } };
     }
     if (p.op === "cursor") {
-      if (!p.cursor) return fail("cursor needs a cursor object.");
+      if (!p.cursor) return fail2("cursor needs a cursor object.");
       const path = save(setCursor(loaded.state, p.cursor, ts));
       return { ok: true, message: `Saved resume cursor (stage ${p.cursor.backboneStage ?? "?"}, ${p.cursor.phase ?? "?"}) to ${path}.`, details: { path } };
     }
     if (p.op === "park") {
-      if (!p.key || !p.note) return fail("park needs a key and a note.");
+      if (!p.key || !p.note) return fail2("park needs a key and a note.");
       const path = save(parkNote(loaded.state, p.key, p.note, ts));
       return { ok: true, message: `Parked a note under "${p.key}" and saved ${path}.`, details: { path, key: p.key } };
     }
-    return fail(`Unknown op "${p.op}". Use read, answer, feedback, artifact, cursor, park, or export.`);
+    return fail2(`Unknown op "${p.op}". Use read, answer, feedback, artifact, cursor, park, or export.`);
   } catch (e) {
-    return fail(`tl_state error: ${e.message}`);
+    return fail2(`tl_state error: ${e.message}`);
   }
 }
 
@@ -406,7 +420,7 @@ var esc = (s) => String(s ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").re
 var fam = (f) => f.trim().replace(/\s+/g, "+");
 function extractScaffoldSpec(state) {
   const obj = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : {};
-  const str = (v) => typeof v === "string" ? v : "";
+  const str2 = (v) => typeof v === "string" ? v : "";
   const brand = obj(state.brand);
   const guide = obj(brand["guide"]);
   const answers = state.answers || {};
@@ -416,15 +430,15 @@ function extractScaffoldSpec(state) {
     return m?.hex || fb;
   };
   const typography = obj(guide["typography"]);
-  const fontOf = (slot, fb) => str(obj(slot)["family"]) || fb;
+  const fontOf = (slot, fb) => str2(obj(slot)["family"]) || fb;
   const voice = obj(guide["voice"]);
   const logos = Array.isArray(brand["logos"]) ? brand["logos"] : [];
   const chosen = logos.find((l) => l?.id === brand["chosenLogoId"]) || logos[0];
   return {
-    brandName: str(guide["brandName"]) || "Your Product",
-    tagline: str(guide["tagline"]),
-    pitch: str(answers["pitch"]) || str(answers["what-statement"]),
-    positioning: str(guide["positioning"]),
+    brandName: str2(guide["brandName"]) || "Your Product",
+    tagline: str2(guide["tagline"]),
+    pitch: str2(answers["pitch"]) || str2(answers["what-statement"]),
+    positioning: str2(guide["positioning"]),
     personality: Array.isArray(guide["personality"]) ? guide["personality"].filter((x) => typeof x === "string") : [],
     palette: {
       primary: role("primary", palette[0]?.hex || "#1f3a5f"),
@@ -435,9 +449,9 @@ function extractScaffoldSpec(state) {
     },
     displayFont: fontOf(typography["display"], "Inter"),
     bodyFont: fontOf(typography["body"], "Inter"),
-    voiceTone: str(voice["tone"]),
+    voiceTone: str2(voice["tone"]),
     logoSvg: chosen?.svg || void 0,
-    pricing: str(answers["pricing-model"]) || void 0
+    pricing: str2(answers["pricing-model"]) || void 0
   };
 }
 function indexHtml(spec, opts) {
@@ -734,11 +748,11 @@ function dedupeSortEnv(envVars) {
 function normalizeDatabase(raw) {
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
   const r = raw;
-  const str = (v, fb) => typeof v === "string" && v.trim() ? v.trim() : fb;
+  const str2 = (v, fb) => typeof v === "string" && v.trim() ? v.trim() : fb;
   return {
-    provider: str(r["provider"], "neon"),
-    schemaFile: str(r["schemaFile"], "schema.sql"),
-    envVar: str(r["envVar"], "DATABASE_URL")
+    provider: str2(r["provider"], "neon"),
+    schemaFile: str2(r["schemaFile"], "schema.sql"),
+    envVar: str2(r["envVar"], "DATABASE_URL")
   };
 }
 function normalizeEnvVars(raw) {
@@ -769,15 +783,15 @@ function normalizeBackendMeta(raw) {
   const database = normalizeDatabase(r["database"]);
   const hasFunctionsDir = typeof r["functionsDir"] === "string" && r["functionsDir"].trim().length > 0;
   if (kind === null && envVars.length === 0 && database === null && !hasFunctionsDir) return null;
-  const str = (v, fb) => typeof v === "string" && v.trim() ? v.trim() : fb;
+  const str2 = (v, fb) => typeof v === "string" && v.trim() ? v.trim() : fb;
   return {
     backendKind: kind ?? "serverless",
-    functionsDir: str(r["functionsDir"], "netlify/functions"),
-    runtime: str(r["runtime"], "nodejs20.x"),
-    nodeVersion: str(r["nodeVersion"], "20"),
+    functionsDir: str2(r["functionsDir"], "netlify/functions"),
+    runtime: str2(r["runtime"], "nodejs20.x"),
+    nodeVersion: str2(r["nodeVersion"], "20"),
     envVars,
     database,
-    guide: str(r["guide"], "BACKEND.md")
+    guide: str2(r["guide"], "BACKEND.md")
   };
 }
 var SECRET_NAME_RE = /(KEY|SECRET|TOKEN|PASSWORD|PASSWD|DATABASE_URL|DB_URL|CONN|DSN|CREDENTIAL|PRIVATE|AUTH)/;
@@ -1172,10 +1186,10 @@ Static deploy: the front end is live. This build also declares a backend that th
     return `${lead} To run the backend, follow ${guide}: provision Neon Postgres, set ${envList} in your host environment, then run netlify deploy with the functions present.`;
   })() : "";
   const token = process.env.NETLIFY_AUTH_TOKEN || process.env.NETLIFY_TOKEN || "";
-  const writeRecord = (rec) => {
+  const writeRecord = (rec2) => {
     const recPath = join4(dirname3(stateFile), "deploy.json");
     mkdirSync3(dirname3(recPath), { recursive: true });
-    writeFileSync4(recPath, JSON.stringify(rec, null, 2) + "\n");
+    writeFileSync4(recPath, JSON.stringify(rec2, null, 2) + "\n");
     return recPath;
   };
   if (opts.dryRun) {
@@ -1447,6 +1461,538 @@ ${notes.join("\n")}` : ""}` + (!url ? `
   };
 }
 
+// core/sync-io.ts
+import { spawnSync as spawnSync3 } from "child_process";
+import { existsSync as existsSync4, mkdirSync as mkdirSync4, readFileSync as readFileSync3, readdirSync as readdirSync3, writeFileSync as writeFileSync5 } from "fs";
+import { homedir } from "os";
+import { dirname as dirname4, isAbsolute as isAbsolute3, join as join5, resolve as resolve4 } from "path";
+
+// core/sync.ts
+function slugify(name) {
+  return String(name || "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40).replace(/-+$/g, "");
+}
+function emptySyncConfig() {
+  return { schema: 1, workspaces: [] };
+}
+var str = (v, fb = "") => typeof v === "string" ? v : fb;
+function parseSyncConfig(text) {
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    return emptySyncConfig();
+  }
+  const list = Array.isArray(raw["workspaces"]) ? raw["workspaces"] : [];
+  const workspaces = [];
+  for (const w of list) {
+    if (!w || typeof w !== "object") continue;
+    const r = w;
+    const cloneDir = str(r["cloneDir"]).trim();
+    if (!cloneDir) continue;
+    const ws = {
+      name: str(r["name"]).trim() || cloneDir,
+      repo: str(r["repo"]).trim(),
+      defaultBranch: str(r["defaultBranch"]).trim() || "main",
+      cloneDir
+    };
+    const active = str(r["activeSession"]).trim();
+    if (active) ws.activeSession = active;
+    workspaces.push(ws);
+  }
+  const cfg = { schema: 1, workspaces };
+  const aw = str(raw["activeWorkspace"]).trim();
+  if (aw) cfg.activeWorkspace = aw;
+  return cfg;
+}
+function serializeSyncConfig(cfg) {
+  return JSON.stringify({ schema: 1, activeWorkspace: cfg.activeWorkspace, workspaces: cfg.workspaces }, null, 2) + "\n";
+}
+function selectWorkspace(cfg, name) {
+  if (name) return cfg.workspaces.find((w) => w.name === name) || null;
+  if (cfg.activeWorkspace) {
+    const w = cfg.workspaces.find((ws) => ws.name === cfg.activeWorkspace);
+    if (w) return w;
+  }
+  return cfg.workspaces.length === 1 ? cfg.workspaces[0] : null;
+}
+function defaultSessionsDir(home) {
+  return `${home}/.thought-layer/sessions`;
+}
+function parseGitStatus(out) {
+  const lines = String(out || "").split("\n").filter((l) => l.length > 0);
+  let branch = null;
+  let ahead = 0;
+  let behind = 0;
+  const files = [];
+  for (const line of lines) {
+    if (line.startsWith("## ")) {
+      const header = line.slice(3);
+      branch = header.split(/\.\.\.| /)[0] || null;
+      const a = header.match(/ahead (\d+)/);
+      const b = header.match(/behind (\d+)/);
+      if (a) ahead = Number(a[1]);
+      if (b) behind = Number(b[1]);
+    } else {
+      files.push(line.slice(3).trim());
+    }
+  }
+  return { branch, ahead, behind, dirty: files.length > 0, files };
+}
+
+// core/merge.ts
+var num = (v) => typeof v === "number" && !Number.isNaN(v) ? v : 0;
+var genAt = (v) => v && typeof v === "object" ? num(v["generatedAt"]) : 0;
+var jsonEq = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+var rec = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : {};
+function mergeProgressStates(ours, theirs, opts) {
+  const coarse = [];
+  const oursNewer = opts.oursTs > opts.theirsTs;
+  const answers = {};
+  const oa = rec(ours.answers);
+  const ta = rec(theirs.answers);
+  for (const k of /* @__PURE__ */ new Set([...Object.keys(oa), ...Object.keys(ta)])) {
+    const inO = k in oa;
+    const inT = k in ta;
+    if (inO && !inT) answers[k] = oa[k];
+    else if (!inO && inT) answers[k] = ta[k];
+    else if (jsonEq(oa[k], ta[k])) answers[k] = oa[k];
+    else {
+      answers[k] = oursNewer ? oa[k] : ta[k];
+      coarse.push(`answers.${k}`);
+    }
+  }
+  const feedback = {};
+  const of = rec(ours.feedback);
+  const tf = rec(theirs.feedback);
+  for (const k of /* @__PURE__ */ new Set([...Object.keys(of), ...Object.keys(tf)])) {
+    const o = of[k];
+    const t = tf[k];
+    if (o != null && t == null) feedback[k] = o;
+    else if (o == null && t != null) feedback[k] = t;
+    else if (jsonEq(o, t)) feedback[k] = o;
+    else {
+      const oR = num(rec(o)["round"]);
+      const tR = num(rec(t)["round"]);
+      const oTs = num(rec(o)["ts"]);
+      const tTs = num(rec(t)["ts"]);
+      const pickOurs = oR !== tR ? oR > tR : oTs !== tTs ? oTs > tTs : oursNewer;
+      feedback[k] = pickOurs ? o : t;
+      coarse.push(`feedback.${k}`);
+    }
+  }
+  const artifact = (key) => {
+    const o = ours[key];
+    const t = theirs[key];
+    if (o == null && t == null) return null;
+    if (o != null && t == null) return o;
+    if (o == null && t != null) return t;
+    if (jsonEq(o, t)) return o;
+    const og = genAt(o);
+    const tg = genAt(t);
+    const pickOurs = og !== tg ? og > tg : oursNewer;
+    coarse.push(key);
+    return pickOurs ? o : t;
+  };
+  const merged = {
+    version: 2,
+    answers,
+    feedback,
+    bizModel: artifact("bizModel"),
+    grill: artifact("grill"),
+    assets: artifact("assets"),
+    research: artifact("research"),
+    swot: artifact("swot"),
+    prd: artifact("prd"),
+    naming: artifact("naming"),
+    brand: artifact("brand"),
+    kit: mergeKit(ours.kit, theirs.kit, oursNewer)
+  };
+  for (const src of oursNewer ? [theirs, ours] : [ours, theirs]) {
+    for (const k of Object.keys(src)) {
+      if (!KNOWN_STATE_KEYS.includes(k)) merged[k] = src[k];
+    }
+  }
+  return { state: merged, coarse: Array.from(new Set(coarse)).sort() };
+}
+function mergeKit(o, t, oursNewer) {
+  if (!o && !t) return null;
+  if (o && !t) return o;
+  if (!o && t) return t;
+  const oo = o;
+  const tt = t;
+  const modulesRun = Array.from(/* @__PURE__ */ new Set([...oo.modulesRun || [], ...tt.modulesRun || []]));
+  const parked = {};
+  for (const src of [oo.parked || {}, tt.parked || {}]) {
+    for (const [k, v] of Object.entries(src)) {
+      parked[k] = Array.from(/* @__PURE__ */ new Set([...parked[k] || [], ...Array.isArray(v) ? v : []]));
+    }
+  }
+  const newer = oursNewer ? oo : tt;
+  const older = oursNewer ? tt : oo;
+  const panelMeta = { ...older.panelMeta || {}, ...newer.panelMeta || {} };
+  const kit = {
+    schema: Math.max(num(oo.schema) || 1, num(tt.schema) || 1),
+    updatedAt: Math.max(num(oo.updatedAt), num(tt.updatedAt))
+  };
+  if (modulesRun.length) kit.modulesRun = modulesRun;
+  if (Object.keys(parked).length) kit.parked = parked;
+  const cursor = newer.cursor ?? older.cursor;
+  if (cursor) kit.cursor = cursor;
+  if (Object.keys(panelMeta).length) kit.panelMeta = panelMeta;
+  return kit;
+}
+
+// core/sync-io.ts
+function hasGit() {
+  try {
+    return spawnSync3("git", ["--version"], { encoding: "utf8", timeout: 15e3 }).status === 0;
+  } catch {
+    return false;
+  }
+}
+function hasGh() {
+  try {
+    return spawnSync3("gh", ["--version"], { encoding: "utf8", timeout: 15e3 }).status === 0;
+  } catch {
+    return false;
+  }
+}
+function ghAuthed() {
+  try {
+    return spawnSync3("gh", ["auth", "status"], { encoding: "utf8", timeout: 2e4 }).status === 0;
+  } catch {
+    return false;
+  }
+}
+function syncConfigPath() {
+  return process.env["THOUGHT_LAYER_SYNC_CONFIG"] || join5(homedir(), ".thought-layer", "sync.json");
+}
+function loadConfig() {
+  const p = syncConfigPath();
+  if (!existsSync4(p)) return emptySyncConfig();
+  try {
+    return parseSyncConfig(readFileSync3(p, "utf8"));
+  } catch {
+    return emptySyncConfig();
+  }
+}
+function saveConfig(cfg) {
+  const p = syncConfigPath();
+  mkdirSync4(dirname4(p), { recursive: true });
+  writeFileSync5(p, serializeSyncConfig(cfg));
+}
+function git(dir, args, timeout = 12e4) {
+  const r = spawnSync3("git", dir ? ["-C", dir, ...args] : args, { encoding: "utf8", timeout });
+  return { status: r.status ?? 1, out: r.stdout || "", err: r.stderr || "" };
+}
+function isGitRepo(dir) {
+  return existsSync4(join5(dir, ".git")) && git(dir, ["rev-parse", "--is-inside-work-tree"]).status === 0;
+}
+function dirNonEmpty(dir) {
+  try {
+    return existsSync4(dir) && readdirSync3(dir).length > 0;
+  } catch {
+    return false;
+  }
+}
+var absDir = (d, cwd = process.cwd()) => isAbsolute3(d) ? d : resolve4(cwd, d);
+var GITATTRIBUTES = `# The kit reconciles session JSON itself; never let git textually merge it
+# (which would corrupt the envelope). -merge keeps our copy in the working tree
+# on a conflict; the kit then rebuilds the merged result from the clean blobs.
+.thought-layer/*.json -merge
+`;
+var GITIGNORE = `# A Thought Layer sessions repo holds session state only. Built product
+# artifacts and secrets never sync here.
+build.json
+deploy.json
+*.local
+.env
+.env.*
+!.env.example
+dist/
+.netlify/
+node_modules/
+`;
+var README = `# Thought Layer sessions
+
+This private repo is the home for Thought Layer session files. Each session is one
+file under \`.thought-layer/<name>.json\` (the portable validation and design state).
+Use the kit to work with them:
+
+    tl sync open --name <session>     pull and resume a session
+    tl sync save --name <session>     snapshot the current state, commit, and push
+    tl sync list                      list the sessions in this repo
+
+Collaboration is handled by GitHub: add a collaborator to this repo in its GitHub
+settings, and they can clone it and run the kit against the same sessions.
+The kit reconciles concurrent edits itself (newest wins per field, conflicts are
+reported), so git never has to merge the JSON by hand.
+`;
+function writeCloneScaffold(cloneDir) {
+  mkdirSync4(join5(cloneDir, STATE_DIR), { recursive: true });
+  const put = (name, body) => {
+    const p = join5(cloneDir, name);
+    if (!existsSync4(p)) writeFileSync5(p, body);
+  };
+  put(".gitattributes", GITATTRIBUTES);
+  put(".gitignore", GITIGNORE);
+  put("README.md", README);
+}
+var ok = (message, details = {}) => ({ ok: true, message, details });
+var fail = (message, details = {}) => ({ ok: false, message, details });
+var collaboratorPointer = (repo) => `To collaborate, add people to ${repo} in its GitHub settings (Settings, Collaborators). They clone it and run the kit; the kit never changes GitHub permissions.`;
+async function runSync(opts, ctx) {
+  if (!hasGit()) {
+    return fail("git is not installed. Install git, then re-run. The sync feature stores your session files in your own private GitHub repo.", { needs: "git" });
+  }
+  try {
+    switch (opts.op) {
+      case "init":
+        return syncInit(opts);
+      case "save":
+        return syncSave(opts, ctx);
+      case "list":
+        return syncList(opts);
+      case "open":
+        return syncOpen(opts, ctx);
+      case "pull":
+        return syncPull(opts, ctx);
+      case "push":
+        return syncPush(opts);
+      case "status":
+        return syncStatus(opts);
+      default:
+        return fail(`Unknown sync op "${opts.op}". Use one of: init, save, list, open, pull, push, status.`);
+    }
+  } catch (e) {
+    return fail(`Sync ${opts.op} failed: ${e.message}`);
+  }
+}
+function resolveWorkspace(opts, cfg) {
+  if (opts.dir && opts.dir.trim()) return { cloneDir: absDir(opts.dir), ws: null };
+  const env = process.env["THOUGHT_LAYER_SESSIONS_DIR"];
+  if (env && env.trim()) return { cloneDir: absDir(env), ws: null };
+  const ws = selectWorkspace(cfg, opts.workspace);
+  if (ws) return { cloneDir: ws.cloneDir, ws };
+  return { cloneDir: defaultSessionsDir(homedir()), ws: null };
+}
+function syncInit(opts) {
+  const repo = (opts.repo || "").trim();
+  if (!repo) return fail("Pass the private repo to use: tl sync init --repo <owner/name or url> [--name <label>] [--dir <path>].");
+  const home = homedir();
+  const label = (opts.name || "").trim();
+  const cloneDir = opts.dir ? absDir(opts.dir) : !label || slugify(label) === "personal" ? defaultSessionsDir(home) : join5(home, ".thought-layer", `sessions-${slugify(label)}`);
+  if (dirNonEmpty(cloneDir)) {
+    if (isGitRepo(cloneDir)) return fail(`${cloneDir} is already a git repo. It looks initialized; use tl sync list or pick another --dir.`, { cloneDir });
+    return fail(`${cloneDir} already exists and is not empty. Pick another --dir or remove it first.`, { cloneDir });
+  }
+  const isOwnerName = /^[\w.-]+\/[\w.-]+$/.test(repo);
+  const useGh = isOwnerName && hasGh() && ghAuthed();
+  mkdirSync4(dirname4(cloneDir), { recursive: true });
+  let cloned = false;
+  if (useGh) {
+    cloned = spawnSync3("gh", ["repo", "clone", repo, cloneDir], { encoding: "utf8", timeout: 18e4 }).status === 0;
+    if (!cloned) {
+      const created = spawnSync3("gh", ["repo", "create", repo, "--private"], { encoding: "utf8", timeout: 18e4 });
+      if (created.status !== 0) {
+        return fail(`Could not clone or create ${repo} with gh. Create the private repo on GitHub yourself, then re-run. gh said: ${(created.stderr || "").slice(0, 300)}`);
+      }
+      cloned = spawnSync3("gh", ["repo", "clone", repo, cloneDir], { encoding: "utf8", timeout: 18e4 }).status === 0;
+    }
+  } else {
+    const url = isOwnerName ? `https://github.com/${repo}.git` : repo;
+    cloned = git(null, ["clone", url, cloneDir], 18e4).status === 0;
+    if (!cloned) {
+      return fail(
+        isOwnerName && !hasGh() ? `Could not clone https://github.com/${repo}.git. Create the private repo on GitHub first (or install gh and run gh auth login so the kit can create it), then re-run.` : `Could not clone ${repo}. Check the repo path or URL and your git access, then re-run.`,
+        { repo, cloneDir }
+      );
+    }
+  }
+  writeCloneScaffold(cloneDir);
+  git(cloneDir, ["add", "-A"]);
+  const committed = git(cloneDir, ["commit", "-m", "Initialize Thought Layer sessions"]).status === 0;
+  let branch = git(cloneDir, ["rev-parse", "--abbrev-ref", "HEAD"]).out.trim() || "main";
+  if (committed && branch === "HEAD") {
+    git(cloneDir, ["branch", "-M", "main"]);
+    branch = "main";
+  }
+  let pushed = false;
+  if (committed) pushed = git(cloneDir, ["push", "-u", "origin", branch]).status === 0;
+  const cfg = loadConfig();
+  const wsName = label || "personal";
+  const ws = { name: wsName, repo, defaultBranch: branch, cloneDir };
+  cfg.workspaces = [...cfg.workspaces.filter((w) => w.cloneDir !== cloneDir && w.name !== wsName), ws];
+  cfg.activeWorkspace = wsName;
+  saveConfig(cfg);
+  return ok(
+    `Initialized the "${wsName}" sessions workspace at ${cloneDir} (repo ${repo}).${committed ? pushed ? " Pushed the initial commit." : " Committed locally; push it once your git access is set." : " The repo already had content; left it as is."}
+${collaboratorPointer(repo)}
+Save your first session with: tl sync save --name <name>${label ? ` --workspace ${wsName}` : ""}.`,
+    { cloneDir, repo, workspace: wsName, branch, committed, pushed }
+  );
+}
+function syncSave(opts, ctx) {
+  const cfg = loadConfig();
+  const { cloneDir, ws } = resolveWorkspace(opts, cfg);
+  if (!isGitRepo(cloneDir)) return fail(`No sessions workspace at ${cloneDir}. Run tl sync init --repo <owner/name> first.`, { cloneDir });
+  const slug = slugify(opts.name || ws?.activeSession?.replace(/\.json$/, "") || "");
+  if (!slug) return fail("Name the session: tl sync save --name <name> (for example photobooth, peptide, blogging).");
+  const targetPath = join5(cloneDir, STATE_DIR, `${slug}.json`);
+  const existed = existsSync4(targetPath);
+  const useExplicit = !!(opts.path && opts.path.trim() || (process.env["THOUGHT_LAYER_STATE"] || "").trim());
+  const loadTarget = useExplicit ? opts.path : existed ? targetPath : opts.path;
+  const source = loadStateFile(loadTarget).state;
+  saveStateFile(source, { target: targetPath, ts: ctx.ts, exportedAt: ctx.exportedAt });
+  git(cloneDir, ["add", "-A"]);
+  const msg = opts.message || `${existed ? "Update" : "Save"} session ${slug}`;
+  const commit = git(cloneDir, ["commit", "-m", msg]);
+  const committed = commit.status === 0;
+  let pushed = false;
+  let pushNote = "";
+  if (committed && !opts.noPush) {
+    const p = git(cloneDir, ["push"]);
+    pushed = p.status === 0;
+    if (!pushed) pushNote = ` Could not push (${(p.err || "").split("\n")[0] || "see git output"}); commit is local, run tl sync push when ready.`;
+  }
+  if (ws) {
+    ws.activeSession = `${slug}.json`;
+    saveConfig(cfg);
+  }
+  return ok(
+    `${existed ? "Updated" : "Saved"} session ${slug} in ${cloneDir}.${committed ? opts.noPush ? " Committed locally (no push)." : pushed ? " Committed and pushed." : pushNote : " Nothing changed since the last save."}`,
+    { cloneDir, session: `${slug}.json`, path: targetPath, committed, pushed }
+  );
+}
+function syncList(opts) {
+  const cfg = loadConfig();
+  const { cloneDir } = resolveWorkspace(opts, cfg);
+  if (!isGitRepo(cloneDir)) return fail(`No sessions workspace at ${cloneDir}. Run tl sync init --repo <owner/name> first.`, { cloneDir });
+  const files = listStateFiles(cloneDir);
+  if (!files.length) return ok(`No sessions yet in ${cloneDir}. Create one with tl sync save --name <name>.`, { cloneDir, sessions: [] });
+  const rows = files.map((f) => {
+    try {
+      const sum = summarizeState(loadStateFile(f.path).state);
+      return { name: f.name, path: f.path, answered: sum.answered, artifacts: sum.artifacts };
+    } catch {
+      return { name: f.name, path: f.path, answered: 0, artifacts: [], unreadable: true };
+    }
+  });
+  const lines = rows.map((r) => `  ${r.name}: ${r.answered} answered${r.artifacts.length ? `, artifacts ${r.artifacts.join(", ")}` : ""}${"unreadable" in r ? " (unreadable)" : ""}`).join("\n");
+  return ok(`${files.length} session(s) in ${cloneDir}:
+${lines}
+Open one with tl sync open --name <name>.`, { cloneDir, sessions: rows });
+}
+function syncOpen(opts, ctx) {
+  const cfg = loadConfig();
+  const { cloneDir, ws } = resolveWorkspace(opts, cfg);
+  if (!isGitRepo(cloneDir)) return fail(`No sessions workspace at ${cloneDir}. Run tl sync init --repo <owner/name> first.`, { cloneDir });
+  const slug = slugify(opts.name || "");
+  if (!slug) return fail("Name the session to open: tl sync open --name <name>. List them with tl sync list.");
+  const pullResult = pullAndReconcile(cloneDir, ctx);
+  const targetPath = join5(cloneDir, STATE_DIR, `${slug}.json`);
+  if (!existsSync4(targetPath)) {
+    return fail(`No session "${slug}" in ${cloneDir} after pulling. List them with tl sync list, or create it with tl sync save --name ${slug}.`, { cloneDir });
+  }
+  if (ws) {
+    ws.activeSession = `${slug}.json`;
+    saveConfig(cfg);
+  }
+  return ok(
+    `Opened session ${slug} (pulled latest${pullResult.merged ? `, reconciled local and remote edits${pullResult.coarse.length ? ` (review: ${pullResult.coarse.join(", ")})` : ""}` : ""}).
+Work on it by pointing the kit at this file:
+  export THOUGHT_LAYER_STATE="${targetPath}"
+or pass --path "${targetPath}" to tl read/answer/artifact. Save with tl sync save --name ${slug}.`,
+    { cloneDir, session: `${slug}.json`, path: targetPath, merged: pullResult.merged, coarse: pullResult.coarse }
+  );
+}
+function pullAndReconcile(cloneDir, ctx) {
+  const branch = git(cloneDir, ["rev-parse", "--abbrev-ref", "HEAD"]).out.trim() || "main";
+  if (git(cloneDir, ["fetch", "origin", branch], 12e4).status !== 0) {
+    return { merged: false, coarse: [], note: "no remote branch to fetch yet" };
+  }
+  const local = git(cloneDir, ["rev-parse", "HEAD"]).out.trim();
+  const remote = git(cloneDir, ["rev-parse", `origin/${branch}`]).out.trim();
+  if (!remote || local === remote) return { merged: false, coarse: [], note: "up to date" };
+  const base = git(cloneDir, ["merge-base", local, remote]).out.trim();
+  if (base === remote) return { merged: false, coarse: [], note: "local is ahead; nothing to pull" };
+  if (base === local) {
+    git(cloneDir, ["merge", "--ff-only", `origin/${branch}`], 12e4);
+    return { merged: false, coarse: [], note: "fast-forward" };
+  }
+  const changed = git(cloneDir, ["diff", "--name-only", local, remote]).out.split("\n").map((s) => s.trim()).filter(Boolean);
+  git(cloneDir, ["merge", "--no-ff", "--no-commit", `origin/${branch}`], 12e4);
+  const coarseAll = [];
+  let reconciled = 0;
+  for (const rel of changed) {
+    if (rel.startsWith(`${STATE_DIR}/`) && rel.endsWith(".json")) {
+      const ours = readShow(cloneDir, local, rel);
+      const theirs = readShow(cloneDir, remote, rel);
+      if (ours && theirs) {
+        try {
+          const op = parseProgress(ours);
+          const tp = parseProgress(theirs);
+          const { state, coarse } = mergeProgressStates(op.state, tp.state, { oursTs: op.writer?.ts ?? 0, theirsTs: tp.writer?.ts ?? 0 });
+          writeFileSync5(join5(cloneDir, rel), serializeProgress(buildProgress(state, { kind: "kit", ts: ctx.ts }, ctx.exportedAt)));
+          coarseAll.push(...coarse);
+          reconciled++;
+        } catch {
+          if (theirs) writeFileSync5(join5(cloneDir, rel), theirs);
+        }
+      } else if (theirs && !ours) {
+        writeFileSync5(join5(cloneDir, rel), theirs);
+        reconciled++;
+      }
+    } else {
+      const theirs = readShow(cloneDir, remote, rel);
+      if (theirs !== null) writeFileSync5(join5(cloneDir, rel), theirs);
+    }
+    git(cloneDir, ["add", "--", rel]);
+  }
+  git(cloneDir, ["add", "-A"]);
+  git(cloneDir, ["commit", "--no-edit", "-m", "Reconcile sessions (kit merge)"]);
+  return { merged: reconciled > 0, coarse: Array.from(new Set(coarseAll)).sort(), note: `reconciled ${reconciled} session file(s)` };
+}
+function readShow(cloneDir, ref, rel) {
+  const r = git(cloneDir, ["show", `${ref}:${rel}`]);
+  return r.status === 0 ? r.out : null;
+}
+function syncPull(opts, ctx) {
+  const cfg = loadConfig();
+  const { cloneDir } = resolveWorkspace(opts, cfg);
+  if (!isGitRepo(cloneDir)) return fail(`No sessions workspace at ${cloneDir}. Run tl sync init first.`, { cloneDir });
+  const r = pullAndReconcile(cloneDir, ctx);
+  const push = git(cloneDir, ["push"]);
+  return ok(
+    `Pulled ${cloneDir}.${r.merged ? ` Reconciled local and remote edits${r.coarse.length ? ` (a coarse tie-break dropped one side for: ${r.coarse.join(", ")})` : ""}.` : " Already up to date or fast-forwarded."}${r.merged && push.status === 0 ? " Pushed the reconciliation." : ""}`,
+    { cloneDir, merged: r.merged, coarse: r.coarse }
+  );
+}
+function syncPush(opts) {
+  const cfg = loadConfig();
+  const { cloneDir } = resolveWorkspace(opts, cfg);
+  if (!isGitRepo(cloneDir)) return fail(`No sessions workspace at ${cloneDir}. Run tl sync init first.`, { cloneDir });
+  git(cloneDir, ["add", "-A"]);
+  const committed = git(cloneDir, ["commit", "-m", opts.message || "Sync sessions"]).status === 0;
+  const p = git(cloneDir, ["push"]);
+  if (p.status !== 0) return fail(`Push failed: ${(p.err || "").split("\n")[0] || "see git output"}. Pull first (tl sync pull), then push.`, { cloneDir });
+  return ok(`Pushed ${cloneDir}.${committed ? " Committed pending changes." : " Nothing new to commit; pushed any local commits."}`, { cloneDir, committed });
+}
+function syncStatus(opts) {
+  const cfg = loadConfig();
+  const { cloneDir, ws } = resolveWorkspace(opts, cfg);
+  if (!isGitRepo(cloneDir)) {
+    const known = cfg.workspaces.length ? ` Known workspaces: ${cfg.workspaces.map((w) => w.name).join(", ")}.` : "";
+    return fail(`No sessions workspace at ${cloneDir}. Run tl sync init --repo <owner/name> first.${known}`, { cloneDir, workspaces: cfg.workspaces });
+  }
+  const st = parseGitStatus(git(cloneDir, ["status", "--porcelain=v1", "--branch"]).out);
+  const sessions = listStateFiles(cloneDir).length;
+  return ok(
+    `Workspace ${ws?.name || "(by dir)"} at ${cloneDir}: ${sessions} session(s), branch ${st.branch || "?"}, ${st.ahead} ahead, ${st.behind} behind, ${st.dirty ? `${st.files.length} uncommitted change(s)` : "clean"}.${ws?.activeSession ? ` Active session: ${ws.activeSession}.` : ""}`,
+    { cloneDir, workspace: ws?.name || null, sessions, ...st }
+  );
+}
+
 // bin/tl.ts
 var HELP = `tl - read/write a portable Thought Layer state file (default: .thought-layer/state.json)
 
@@ -1455,6 +2001,8 @@ var HELP = `tl - read/write a portable Thought Layer state file (default: .thoug
   tl scaffold [--out dist] [--domain x.com] [--founder "Name"]  deterministic deployable static site from the spec + brand
   tl deploy [--dry-run] [--anonymous] [--name x] [--site id]  take build.json's publish dir live to a user-owned Netlify URL
             [--static-only] [--provision-db] [--apply-schema]   when build.json has a backend: ships functions+env by default; flags opt out or add Neon provision/schema
+  tl sync <init|save|list|open|pull|push|status>             store/sync your session files in your own private GitHub repo
+            [--repo owner/name] [--name x] [--dir p] [--workspace w] [--message m] [--no-push]
   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})
@@ -1489,7 +2037,7 @@ function parseArgs(argv) {
 function readData(flags) {
   const d = flags["data"];
   if (d === void 0) return void 0;
-  const raw = d === "-" || d === true ? readFileSync3(0, "utf8") : String(d);
+  const raw = d === "-" || d === true ? readFileSync4(0, "utf8") : String(d);
   try {
     return JSON.parse(raw);
   } catch {
@@ -1563,6 +2111,26 @@ function main() {
     });
     return;
   }
+  if (args[0] === "sync") {
+    runSync(
+      {
+        op: typeof args[1] === "string" ? args[1] : "status",
+        name: typeof flags["name"] === "string" ? flags["name"] : void 0,
+        repo: typeof flags["repo"] === "string" ? flags["repo"] : void 0,
+        dir: typeof flags["dir"] === "string" ? flags["dir"] : void 0,
+        workspace: typeof flags["workspace"] === "string" ? flags["workspace"] : void 0,
+        message: typeof flags["message"] === "string" ? flags["message"] : void 0,
+        noPush: flags["no-push"] === true,
+        path: typeof flags["path"] === "string" ? flags["path"] : void 0
+      },
+      { ts: Date.now(), exportedAt: (/* @__PURE__ */ new Date()).toISOString() }
+    ).then((r2) => {
+      if (flags["json"]) console.log(JSON.stringify(r2.details, null, 2));
+      else console.log(r2.message);
+      process.exit(r2.ok ? 0 : 1);
+    });
+    return;
+  }
   let payload;
   try {
     payload = buildOp(args, flags);