@hobocode/thought-layer 0.2.1 → 0.3.0

package/README.md

@@ -20,8 +20,9 @@ This is open source and BYOK by design. The point is to help people build real t
 
 **A Pi package** that adds, on top of the skills:
 
-- **Deterministic tools** the agent can call so the math is exact and never re-derived: `tl_score` (confidence to status and grade), `tl_domains` (availability, BYOK), `tl_project` (the numeric business projection).
-- **Slash commands** (prompt templates): `/tl` runs the whole flow, and `/tl-panel`, `/tl-grill`, `/tl-prd`, `/tl-naming` run each stage.
+- **Deterministic tools** the agent can call so the math is exact and never re-derived: `tl_score` (confidence to status and grade), `tl_domains` (availability, BYOK), `tl_project` (the numeric business projection), `tl_state` (the portable progress file), and `tl_scaffold` (a deterministic, deployable static site from the spec + brand).
+- **Slash commands** (prompt templates): `/tl` runs the whole flow; `/tl-speedrun` is the fast unranked path; `/tl-panel`, `/tl-grill`, `/tl-prd`, `/tl-naming` run each stage; `/tl-build` builds the hardened PRD into a deploy-ready artifact.
+- **A `tl` CLI** for any shell agent (`npx -y @hobocode/thought-layer tl ...`): `read`/`list`/`answer`/`feedback`/`artifact`/`cursor`/`export` for the shared progress file, and `scaffold` for the deployable static-site floor.
 
 ## Install
 
@@ -61,8 +62,8 @@ The hosted version of the rigor lives at [weareallproductmanagersnow.com](https:
 
 ## Roadmap
 
-- **Done:** the rigor as portable skills, and a Pi package with deterministic tools + slash commands.
-- **Phase 3:** a `build` step that turns the PRD into a deploy-ready artifact, built by your own agent.
+- **Done:** the rigor as portable skills; a Pi package with deterministic tools + slash commands; the portable progress file (`tl_state` / the `tl` CLI) shared with the web app; and the speedrun.
+- **Phase 3 (done):** a `build` step that turns the hardened PRD into a deploy-ready artifact, built by your own agent (`/tl-build`), with a deterministic `tl_scaffold` tool that writes an instantly-deployable branded static site as the floor.
 - **Phase 4:** a `deploy` step that publishes it to a live URL you own (Netlify deploy-and-claim by default), closing the loop.
 
 ## Notes for contributors

package/core/index.ts

@@ -15,3 +15,5 @@ export * from "./stages.ts";
 export * from "./stage-map.ts";
 export * from "./state-file.ts";
 export * from "./state-ops.ts";
+export * from "./scaffold.ts";
+export * from "./scaffold-io.ts";

package/core/scaffold-io.ts

@@ -0,0 +1,56 @@
+// Node IO for the deterministic scaffold, shared by both frontends (the
+// tl_scaffold Pi tool and the `tl scaffold` CLI). The pure generation lives in
+// scaffold.ts; this loads the state file, writes the site to a publish dir, and
+// writes the build.json manifest co-located with the selected state file.
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { loadStateFile } from "./state-file.ts";
+import { extractScaffoldSpec, buildStarterSite, scaffoldManifest, type ScaffoldOptions } from "./scaffold.ts";
+import type { StateOpResult } from "./state-ops.ts";
+
+export interface ScaffoldRunOptions extends ScaffoldOptions {
+  path?: string;
+  outDir?: string;
+}
+
+export function runScaffold(opts: ScaffoldRunOptions, ctx: { builtAt: string }): StateOpResult {
+  try {
+    const loaded = loadStateFile(opts.path);
+    const spec = extractScaffoldSpec(loaded.state);
+    const { files } = buildStarterSite(spec, { domain: opts.domain, founderName: opts.founderName, socialImage: opts.socialImage });
+
+    const outDir = opts.outDir || "dist";
+    const outAbs = isAbsolute(outDir) ? outDir : resolve(process.cwd(), outDir);
+    mkdirSync(outAbs, { recursive: true });
+    for (const [name, content] of Object.entries(files)) {
+      writeFileSync(join(outAbs, name), content);
+    }
+
+    const prd = loaded.state.prd && typeof loaded.state.prd === "object" ? (loaded.state.prd as Record<string, unknown>) : null;
+    const grill = loaded.state.grill && typeof loaded.state.grill === "object" ? (loaded.state.grill as Record<string, unknown>) : null;
+    const manifest = scaffoldManifest(outDir, ctx.builtAt, {
+      stateFile: loaded.path,
+      prdTs: prd && typeof prd["ts"] === "number" ? (prd["ts"] as number) : null,
+      grillDone: !!(grill && grill["done"] === true),
+      fromSpeedrun: loaded.state.kit?.cursor?.phase === "speedrun",
+    });
+
+    // build.json sits in the selected state file's .thought-layer/ dir.
+    const manifestPath = join(dirname(loaded.path), "build.json");
+    mkdirSync(dirname(manifestPath), { recursive: true });
+    writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+
+    const names = Object.keys(files);
+    return {
+      ok: true,
+      message:
+        `Scaffolded a deployable static site for "${spec.brandName}" -> ${outAbs} ` +
+        `(${names.length} files: ${names.join(", ")}). Manifest: ${manifestPath}. ` +
+        `Deploy the publish dir, or build the full product with /tl-build.`,
+      details: { publishDir: outDir, outAbs, files: names, manifestPath, brandName: spec.brandName, hadBrand: loaded.state.brand != null },
+    };
+  } catch (e) {
+    return { ok: false, message: `tl_scaffold error: ${(e as Error).message}`, details: {} };
+  }
+}

package/core/scaffold.ts

@@ -0,0 +1,276 @@
+// Deterministic, no-LLM starter-site generator: structured spec + brand -> a
+// self-contained, branded, SEO-complete static site. This is the guaranteed
+// "instantly-deployable floor" so even a thin or failed model-build still
+// yields a real, ownable site. The build skill drives the agent to build the
+// PRODUCT; this tool guarantees a deployable landing page from the same spec.
+//
+// Technique ported from the web app's brandLookbookHtml/brandTokens
+// (src/lib/exports.js): esc() HTML escaping, the color-role regex with
+// fallbacks, the fam() Google-Fonts URL builder, inline CSS via :root brand
+// vars. CDATA is needed only inside SVG <style>; HTML <style> does not need it,
+// so this emits plain HTML. Pure: no fs, no Date - the caller supplies builtAt.
+
+import type { ProgressState } from "./progress.ts";
+
+export interface StarterSiteSpec {
+  brandName: string;
+  tagline: string;
+  pitch: string;
+  positioning: string;
+  personality: string[];
+  palette: { primary: string; accent: string; ink: string; surface: string; muted: string };
+  displayFont: string;
+  bodyFont: string;
+  voiceTone: string;
+  logoSvg?: string;
+  pricing?: string;
+}
+
+export interface ScaffoldOptions {
+  domain?: string;
+  founderName?: string;
+  socialImage?: string;
+}
+
+// The shared build manifest the deploy step consumes. Both producers (this
+// scaffold tool and the build skill's agent) write the same shape.
+export interface BuildManifest {
+  app: "thought-layer";
+  kind: "build";
+  version: 1;
+  builtAt: string;
+  producer: "agent" | "scaffold";
+  publishDir: string;
+  entry: string;
+  stack: string;
+  hasBackend: boolean;
+  backendNote: string | null;
+  buildCommand: string | null;
+  installCommand: string | null;
+  nodeVersion: string;
+  provenance: { stateFile: string; prdTs: number | null; grillDone: boolean; fromSpeedrun: boolean };
+  requirements: { total: number; built: number; deferred: number; deferredIds: string[] };
+  seo: Record<string, boolean>;
+  artifacts: { traceability: string | null; decisions: string | null; seo: string | null };
+  verified: { buildRan: boolean; publishDirExists: boolean; entryLoads: boolean; notes: string };
+}
+
+const esc = (s: unknown): string =>
+  String(s ?? "")
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+
+const fam = (f: string): string => f.trim().replace(/\s+/g, "+");
+
+// ---- extract a spec from the portable state file -----------------------------
+
+export function extractScaffoldSpec(state: ProgressState): StarterSiteSpec {
+  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 : "");
+
+  const brand = obj(state.brand);
+  const guide = obj(brand["guide"]);
+  const answers = state.answers || {};
+
+  const palette = Array.isArray(guide["palette"])
+    ? (guide["palette"] as Array<{ name?: string; hex?: string }>)
+    : [];
+  const role = (re: string, fb: string): string => {
+    const m = palette.find((p) => p?.name && new RegExp(re, "i").test(p.name));
+    return m?.hex || fb;
+  };
+  const typography = obj(guide["typography"]);
+  const fontOf = (slot: unknown, fb: string): string => str(obj(slot)["family"]) || fb;
+  const voice = obj(guide["voice"]);
+  const logos = Array.isArray(brand["logos"]) ? (brand["logos"] as Array<{ id?: string; svg?: string }>) : [];
+  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"]),
+    personality: Array.isArray(guide["personality"])
+      ? (guide["personality"] as unknown[]).filter((x): x is string => typeof x === "string")
+      : [],
+    palette: {
+      primary: role("primary", palette[0]?.hex || "#1f3a5f"),
+      accent: role("accent|secondary", palette[1]?.hex || "#e8743b"),
+      ink: role("ink|text|dark|black", "#16202b"),
+      surface: role("surface|background|light|paper|off.?white|cream", "#f7f8fa"),
+      muted: role("muted|gray|grey|neutral|border", "#8a9099"),
+    },
+    displayFont: fontOf(typography["display"], "Inter"),
+    bodyFont: fontOf(typography["body"], "Inter"),
+    voiceTone: str(voice["tone"]),
+    logoSvg: chosen?.svg || undefined,
+    pricing: str(answers["pricing-model"]) || undefined,
+  };
+}
+
+// ---- the site -----------------------------------------------------------------
+
+function indexHtml(spec: StarterSiteSpec, opts: ScaffoldOptions): string {
+  const domain = (opts.domain || "https://example.com").replace(/\/+$/, "");
+  const founder = opts.founderName || "";
+  const social = opts.socialImage || `${domain}/og-image.png`;
+  const name = esc(spec.brandName);
+  const headline = esc(spec.tagline || spec.brandName);
+  const lead = esc(spec.pitch || spec.positioning);
+  const desc = esc(spec.pitch || spec.positioning || spec.brandName);
+  const fonts = `https://fonts.googleapis.com/css2?family=${fam(spec.displayFont)}:wght@400;600;700;800&family=${fam(spec.bodyFont)}:wght@400;500;600&display=swap`;
+
+  const graph: Array<Record<string, unknown>> = [
+    { "@type": "Organization", "@id": `${domain}/#org`, name: spec.brandName, url: `${domain}/`, ...(founder ? { founder: { "@id": `${domain}/#founder` } } : {}) },
+    ...(founder ? [{ "@type": "Person", "@id": `${domain}/#founder`, name: founder, worksFor: { "@id": `${domain}/#org` } }] : []),
+    { "@type": "WebSite", "@id": `${domain}/#website`, url: `${domain}/`, name: spec.brandName, publisher: { "@id": `${domain}/#org` } },
+    { "@type": "WebPage", "@id": `${domain}/#webpage`, url: `${domain}/`, name: `${spec.brandName}${spec.tagline ? " - " + spec.tagline : ""}`, isPartOf: { "@id": `${domain}/#website` }, about: { "@id": `${domain}/#org` }, description: spec.pitch || spec.positioning || spec.brandName },
+  ];
+  // JSON.stringify does NOT escape < or >, so a value containing "</script>"
+  // would break out of the ld+json <script> block. Unicode-escape both.
+  const jsonLd = JSON.stringify({ "@context": "https://schema.org", "@graph": graph })
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e");
+
+  const lockup = spec.logoSvg ? spec.logoSvg : `<span class="wordmark">${name}</span>`;
+  const pills = spec.personality.map((t) => `<li class="pill">${esc(t)}</li>`).join("");
+  const positioningSection = spec.positioning
+    ? `<section class="value" aria-labelledby="value-h"><div class="wrap"><h2 id="value-h">Who it is for</h2><p>${esc(spec.positioning)}</p>${pills ? `<ul class="pills" aria-label="What it stands for">${pills}</ul>` : ""}</div></section>`
+    : "";
+  const pricingSection = spec.pricing
+    ? `<section class="pricing" aria-labelledby="pricing-h"><div class="wrap"><h2 id="pricing-h">Pricing</h2><p class="price">${esc(spec.pricing)}</p></div></section>`
+    : "";
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${name}${spec.tagline ? " - " + headline : ""}</title>
+<meta name="description" content="${desc}">
+<link rel="canonical" href="${domain}/">
+<meta property="og:type" content="website">
+<meta property="og:title" content="${name}">
+<meta property="og:description" content="${desc}">
+<meta property="og:url" content="${domain}/">
+<meta property="og:image" content="${esc(social)}">
+<meta name="twitter:card" content="summary_large_image">
+<meta name="twitter:title" content="${name}">
+<meta name="twitter:description" content="${desc}">
+<meta name="twitter:image" content="${esc(social)}">
+<link href="${esc(fonts)}" rel="stylesheet">
+<script type="application/ld+json">${jsonLd}</script>
+<style>
+:root{--p:${spec.palette.primary};--a:${spec.palette.accent};--ink:${spec.palette.ink};--su:${spec.palette.surface};--mu:${spec.palette.muted};--disp:'${spec.displayFont}',system-ui,sans-serif;--body:'${spec.bodyFont}',system-ui,sans-serif}
+*{margin:0;padding:0;box-sizing:border-box}
+html{scroll-behavior:smooth}
+body{background:var(--su);color:var(--ink);font-family:var(--body);line-height:1.6;-webkit-font-smoothing:antialiased}
+.wrap{max-width:960px;margin:0 auto;padding:0 24px}
+a{color:var(--a)}
+:focus-visible{outline:3px solid var(--a);outline-offset:2px}
+.sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);border:0}
+header{padding:24px 0}
+header .wrap{display:flex;align-items:center;justify-content:space-between;gap:16px}
+.wordmark{font-family:var(--disp);font-weight:800;font-size:22px;color:var(--p)}
+.logo svg,.logo img{height:36px;width:auto}
+.cta{display:inline-block;background:var(--p);color:#fff;text-decoration:none;font-weight:600;padding:12px 22px;border-radius:10px;border:0;cursor:pointer;font-size:15px}
+.cta.alt{background:var(--a)}
+.hero{padding:72px 0 56px}
+.hero h1{font-family:var(--disp);font-weight:800;font-size:clamp(34px,6vw,60px);line-height:1.05;color:var(--ink);letter-spacing:-0.02em;max-width:14ch}
+.hero p.lead{font-size:clamp(17px,2.4vw,22px);opacity:.82;margin:20px 0 28px;max-width:42ch}
+.signup{display:flex;gap:10px;flex-wrap:wrap;max-width:460px}
+.signup input[type=email]{flex:1 1 220px;padding:12px 14px;border:1px solid var(--mu);border-radius:10px;font:inherit;background:#fff;color:var(--ink)}
+.value,.pricing{padding:48px 0;border-top:1px solid color-mix(in srgb,var(--mu) 40%,transparent)}
+.value h2,.pricing h2{font-family:var(--disp);font-weight:700;font-size:28px;margin-bottom:12px}
+.value p{max-width:54ch;opacity:.85}
+ul.pills{list-style:none;display:flex;flex-wrap:wrap;gap:10px;margin-top:22px}
+.pill{font-size:13px;font-weight:600;color:var(--p);background:color-mix(in srgb,var(--p) 12%,transparent);padding:6px 14px;border-radius:999px}
+.pricing .price{font-family:var(--disp);font-size:24px;font-weight:700;color:var(--p);margin-top:8px}
+footer{padding:48px 0;border-top:1px solid color-mix(in srgb,var(--mu) 40%,transparent);color:var(--mu);font-size:13px}
+@media (max-width:640px){.hero{padding:48px 0 40px}header .wrap{flex-direction:column;align-items:flex-start}}
+</style>
+</head>
+<body>
+<header><div class="wrap"><div class="logo">${lockup}</div><a class="cta" href="#get-started">Get early access</a></div></header>
+<main>
+<section class="hero" aria-labelledby="hero-h"><div class="wrap">
+<h1 id="hero-h">${headline}</h1>
+<p class="lead">${lead}</p>
+<form name="signups" id="get-started" method="POST" data-netlify="true" class="signup">
+<input type="hidden" name="form-name" value="signups">
+<label class="sr-only" for="email">Email address</label>
+<input id="email" type="email" name="email" placeholder="you@email.com" required>
+<button type="submit" class="cta alt">Get early access</button>
+</form>
+</div></section>
+${positioningSection}
+${pricingSection}
+</main>
+<footer><div class="wrap"><p>${name}${founder ? ` - by ${esc(founder)}` : ""}. Scaffolded by The Thought Layer.</p></div></footer>
+</body>
+</html>
+`;
+}
+
+function companionFiles(spec: StarterSiteSpec, opts: ScaffoldOptions): Record<string, string> {
+  const domain = (opts.domain || "https://example.com").replace(/\/+$/, "");
+  const name = spec.brandName;
+  const summary = spec.pitch || spec.positioning || name;
+
+  const llms = `# ${name}\n\n> ${summary}\n\n## About\n${name}${spec.tagline ? ` - ${spec.tagline}` : ""}. ${spec.positioning || summary}\n\n## Pages\n- [Home](${domain}/) - ${spec.tagline || summary}\n\n## FAQ\n- What is ${name}? ${summary}\n- Who is it for? ${spec.positioning || "See the home page."}\n`;
+
+  const robots = `User-agent: *\nAllow: /\n\nUser-agent: GPTBot\nAllow: /\n\nUser-agent: ClaudeBot\nAllow: /\n\nUser-agent: PerplexityBot\nAllow: /\n\nUser-agent: Google-Extended\nAllow: /\n\nSitemap: ${domain}/sitemap.xml\n`;
+
+  const sitemap = `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n  <url><loc>${domain}/</loc><changefreq>weekly</changefreq><priority>1.0</priority></url>\n</urlset>\n`;
+
+  const redirects = `/*  /index.html  200\n`;
+
+  const netlifyToml = `[build]\n  publish = "."\n\n[[redirects]]\n  from = "/*"\n  to = "/index.html"\n  status = 200\n`;
+
+  const seoDoc = `# SEO and deployment\n\nThis static site was scaffolded deterministically by The Thought Layer. It is ready to deploy (drag the publish folder onto https://app.netlify.com/drop, or use the deploy step). Everything below is already in place; the lines marked TO FILL need your input.\n\n## In place\n- **Structured data**: schema.org JSON-LD (@graph) with Organization, WebSite, and WebPage in index.html.\n- **/llms.txt**: an AI-crawler summary at the site root.\n- **robots.txt**: allows search + AI crawlers and points to the sitemap.\n- **sitemap.xml**: lists the home page.\n- **Canonical + Open Graph + Twitter Card** meta on the page.\n- **_redirects** and **netlify.toml**: SPA fallback (/* -> /index.html).\n- **Email capture**: a Netlify Forms signup ("signups") - submissions appear in your Netlify dashboard after deploy, no backend needed.\n- Semantic, accessible HTML (landmarks, heading order, labelled form, visible focus).\n\n## TO FILL\n- **Domain**: replace ${domain} with your real domain in index.html (canonical/OG), llms.txt, robots.txt, sitemap.xml. Pass --domain to the scaffold tool to set it up front.\n- **Founder + sameAs**: add a Person with real sameAs profile links (LinkedIn, X) to the JSON-LD, and cross-reference the Organization. Pass --founder to seed the name.\n- **Social image**: add a 1200x630 image at /og-image.png (referenced by og:image / twitter:image).\n- **The product**: this is a landing/coming-soon page. Build the actual product with the thought-layer-build skill (/tl-build).\n`;
+
+  return {
+    "llms.txt": llms,
+    "robots.txt": robots,
+    "sitemap.xml": sitemap,
+    "_redirects": redirects,
+    "netlify.toml": netlifyToml,
+    "SEO.md": seoDoc,
+  };
+}
+
+export function buildStarterSite(spec: StarterSiteSpec, opts: ScaffoldOptions = {}): { files: Record<string, string> } {
+  return { files: { "index.html": indexHtml(spec, opts), ...companionFiles(spec, opts) } };
+}
+
+// ---- the manifest (scaffold producer) ----------------------------------------
+
+export function scaffoldManifest(
+  publishDir: string,
+  builtAt: string,
+  provenance: { stateFile: string; prdTs: number | null; grillDone: boolean; fromSpeedrun: boolean },
+): BuildManifest {
+  return {
+    app: "thought-layer",
+    kind: "build",
+    version: 1,
+    builtAt,
+    producer: "scaffold",
+    publishDir,
+    entry: "index.html",
+    stack: "static",
+    hasBackend: false,
+    backendNote: null,
+    buildCommand: null,
+    installCommand: null,
+    nodeVersion: "20",
+    provenance,
+    requirements: { total: 0, built: 0, deferred: 0, deferredIds: [] },
+    seo: { jsonLd: true, llmsTxt: true, sitemap: true, robots: true, canonical: true, openGraph: true, socialImage: false, semanticHtml: true, seoDoc: true, netlifyToml: true },
+    artifacts: { traceability: null, decisions: null, seo: "SEO.md" },
+    verified: { buildRan: true, publishDirExists: true, entryLoads: true, notes: "deterministic static scaffold; landing page + SEO files written" },
+  };
+}

package/core/state-file.ts

@@ -3,7 +3,7 @@
 // tl_state tool and the CLI bin. Kept out of progress.ts so the transforms stay
 // testable without touching disk.
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import {
   parseProgress, buildProgress, serializeProgress, emptyState,
@@ -12,15 +12,35 @@ import {
 
 export const STATE_DIR = ".thought-layer";
 export const STATE_FILE = "state.json";
+// Set THOUGHT_LAYER_STATE to a file path to make it the session default, so the
+// agent or user does not have to pass --path on every op when juggling several
+// ideas. Precedence: an explicit target (--path / the tool's `path`) wins, then
+// the env var, then <cwd>/.thought-layer/state.json.
+export const STATE_ENV = "THOUGHT_LAYER_STATE";
+
+const withEnv = (target?: string): string | undefined => target ?? (process.env[STATE_ENV] || undefined);
 
 // Resolve the canonical state file path. `target` may be a project directory or
-// a direct path to a .json file; defaults to <cwd>/.thought-layer/state.json.
+// a direct path to a .json file; with neither, falls back to the env default or
+// <cwd>/.thought-layer/state.json.
 export function resolveStatePath(target?: string, cwd: string = process.cwd()): string {
-  if (!target) return join(cwd, STATE_DIR, STATE_FILE);
-  const abs = isAbsolute(target) ? target : resolve(cwd, target);
+  const t = withEnv(target);
+  if (!t) return join(cwd, STATE_DIR, STATE_FILE);
+  const abs = isAbsolute(t) ? t : resolve(cwd, t);
   return abs.endsWith(".json") ? abs : join(abs, STATE_DIR, STATE_FILE);
 }
 
+// List the state files under <dir>/.thought-layer/ so several ideas can live
+// side by side and be discovered. `dir` is a project directory (defaults to cwd).
+export function listStateFiles(dir: string = process.cwd()): Array<{ name: string; path: string }> {
+  const d = join(dir, STATE_DIR);
+  if (!existsSync(d)) return [];
+  return readdirSync(d)
+    .filter((f) => f.endsWith(".json"))
+    .sort()
+    .map((name) => ({ name, path: join(d, name) }));
+}
+
 export interface LoadResult {
   path: string;
   exists: boolean;

package/core/state-ops.ts

@@ -5,7 +5,7 @@
 // core/state-file.ts. Pure of any host concern (no Pi types, no argv).
 
 import { gradeFromConfidence } from "./scoring.ts";
-import { loadStateFile, saveStateFile } from "./state-file.ts";
+import { loadStateFile, saveStateFile, listStateFiles, STATE_DIR, STATE_ENV } from "./state-file.ts";
 import {
   setAnswer, setArtifact, setCursor, parkNote, buildFeedbackEntry,
   normalizeArtifactValue, summarizeState,
@@ -40,17 +40,39 @@ export function applyStateOp(p: StateOp, ctx: { ts: number; exportedAt: string }
   const { ts, exportedAt } = ctx;
   const fail = (message: string): StateOpResult => ({ ok: false, message, details: {} });
   try {
+    if (p.op === "list") {
+      const files = listStateFiles(p.path);
+      if (!files.length) {
+        return { ok: true, message: `No state files under ./${STATE_DIR}/. A fresh run creates ${STATE_DIR}/state.json; pass --path <file>.json (or set ${STATE_ENV}) to use another.`, details: { files: [] } };
+      }
+      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: [] as string[], 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: true, message: `${files.length} state file(s) under ./${STATE_DIR}/:\n${lines}\nPick one with --path .thought-layer/<name>.json, or set ${STATE_ENV} for the session.`, details: { files: rows } };
+    }
+
     const loaded = loadStateFile(p.path);
     const save = (next: typeof loaded.state) => saveStateFile(next, { target: p.path, ts, exportedAt }).path;
 
     if (p.op === "read" || p.op === "export") {
       const sum = summarizeState(loaded.state);
-      const message = loaded.exists
-        ? `Loaded ${loaded.path}: ${sum.answered}/${sum.totalAnswerable} answered ` +
+      let message: string;
+      if (loaded.exists) {
+        message = `Loaded ${loaded.path}: ${sum.answered}/${sum.totalAnswerable} answered ` +
           `(${sum.byStatus.green} green, ${sum.byStatus.yellow} yellow, ${sum.byStatus.red} red), ` +
           `artifacts: ${sum.artifacts.join(", ") || "none"}. ` +
-          `Resume at ${sum.cursor ? `stage ${sum.cursor.backboneStage ?? "?"} (${sum.cursor.phase ?? "?"})` : "the beginning"}.`
-        : `No state file yet at ${loaded.path}. Start a fresh run; it will be created on first write.`;
+          `Resume at ${sum.cursor ? `stage ${sum.cursor.backboneStage ?? "?"} (${sum.cursor.phase ?? "?"})` : "the beginning"}.`;
+      } else {
+        const others = listStateFiles().filter((f) => f.path !== loaded.path);
+        const hint = others.length ? ` Other state files here: ${others.map((f) => f.name).join(", ")} (pick one with --path, or 'tl list').` : "";
+        message = `No state file yet at ${loaded.path}.${hint} Start a fresh run; it will be created on first write.`;
+      }
       return { ok: true, message, details: { path: loaded.path, exists: loaded.exists, summary: sum, state: loaded.state } };
     }
 

package/dist/tl.js

@@ -26,7 +26,7 @@ function aggregateConfidence(values) {
 }
 
 // core/state-file.ts
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "fs";
 import { dirname, isAbsolute, join, resolve } from "path";
 
 // core/stage-map.ts
@@ -282,11 +282,19 @@ function parkNote(state, key, note, ts) {
 // core/state-file.ts
 var STATE_DIR = ".thought-layer";
 var STATE_FILE = "state.json";
+var STATE_ENV = "THOUGHT_LAYER_STATE";
+var withEnv = (target) => target ?? (process.env[STATE_ENV] || void 0);
 function resolveStatePath(target, cwd = process.cwd()) {
-  if (!target) return join(cwd, STATE_DIR, STATE_FILE);
-  const abs = isAbsolute(target) ? target : resolve(cwd, target);
+  const t = withEnv(target);
+  if (!t) return join(cwd, STATE_DIR, STATE_FILE);
+  const abs = isAbsolute(t) ? t : resolve(cwd, t);
   return abs.endsWith(".json") ? abs : join(abs, STATE_DIR, STATE_FILE);
 }
+function listStateFiles(dir = process.cwd()) {
+  const d = join(dir, STATE_DIR);
+  if (!existsSync(d)) return [];
+  return readdirSync(d).filter((f) => f.endsWith(".json")).sort().map((name) => ({ name, path: join(d, name) }));
+}
 function loadStateFile(target, cwd) {
   const path = resolveStatePath(target, cwd);
   if (!existsSync(path)) {
@@ -313,11 +321,36 @@ function applyStateOp(p, ctx) {
   const { ts, exportedAt } = ctx;
   const fail = (message) => ({ ok: false, message, details: {} });
   try {
+    if (p.op === "list") {
+      const files = listStateFiles(p.path);
+      if (!files.length) {
+        return { ok: true, message: `No state files under ./${STATE_DIR}/. A fresh run creates ${STATE_DIR}/state.json; pass --path <file>.json (or set ${STATE_ENV}) to use another.`, details: { files: [] } };
+      }
+      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: true, message: `${files.length} state file(s) under ./${STATE_DIR}/:
+${lines}
+Pick one with --path .thought-layer/<name>.json, or set ${STATE_ENV} for the session.`, details: { files: rows } };
+    }
     const loaded = loadStateFile(p.path);
     const save = (next) => saveStateFile(next, { target: p.path, ts, exportedAt }).path;
     if (p.op === "read" || p.op === "export") {
       const sum = summarizeState(loaded.state);
-      const message = loaded.exists ? `Loaded ${loaded.path}: ${sum.answered}/${sum.totalAnswerable} answered (${sum.byStatus.green} green, ${sum.byStatus.yellow} yellow, ${sum.byStatus.red} red), artifacts: ${sum.artifacts.join(", ") || "none"}. Resume at ${sum.cursor ? `stage ${sum.cursor.backboneStage ?? "?"} (${sum.cursor.phase ?? "?"})` : "the beginning"}.` : `No state file yet at ${loaded.path}. Start a fresh run; it will be created on first write.`;
+      let message;
+      if (loaded.exists) {
+        message = `Loaded ${loaded.path}: ${sum.answered}/${sum.totalAnswerable} answered (${sum.byStatus.green} green, ${sum.byStatus.yellow} yellow, ${sum.byStatus.red} red), artifacts: ${sum.artifacts.join(", ") || "none"}. Resume at ${sum.cursor ? `stage ${sum.cursor.backboneStage ?? "?"} (${sum.cursor.phase ?? "?"})` : "the beginning"}.`;
+      } else {
+        const others = listStateFiles().filter((f) => f.path !== loaded.path);
+        const hint = others.length ? ` Other state files here: ${others.map((f) => f.name).join(", ")} (pick one with --path, or 'tl list').` : "";
+        message = `No state file yet at ${loaded.path}.${hint} Start a fresh run; it will be created on first write.`;
+      }
       return { ok: true, message, details: { path: loaded.path, exists: loaded.exists, summary: sum, state: loaded.state } };
     }
     if (p.op === "answer") {
@@ -364,10 +397,284 @@ function applyStateOp(p, ctx) {
   }
 }
 
+// core/scaffold-io.ts
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname2, isAbsolute as isAbsolute2, join as join2, resolve as resolve2 } from "path";
+
+// core/scaffold.ts
+var esc = (s) => String(s ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+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 brand = obj(state.brand);
+  const guide = obj(brand["guide"]);
+  const answers = state.answers || {};
+  const palette = Array.isArray(guide["palette"]) ? guide["palette"] : [];
+  const role = (re, fb) => {
+    const m = palette.find((p) => p?.name && new RegExp(re, "i").test(p.name));
+    return m?.hex || fb;
+  };
+  const typography = obj(guide["typography"]);
+  const fontOf = (slot, fb) => str(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"]),
+    personality: Array.isArray(guide["personality"]) ? guide["personality"].filter((x) => typeof x === "string") : [],
+    palette: {
+      primary: role("primary", palette[0]?.hex || "#1f3a5f"),
+      accent: role("accent|secondary", palette[1]?.hex || "#e8743b"),
+      ink: role("ink|text|dark|black", "#16202b"),
+      surface: role("surface|background|light|paper|off.?white|cream", "#f7f8fa"),
+      muted: role("muted|gray|grey|neutral|border", "#8a9099")
+    },
+    displayFont: fontOf(typography["display"], "Inter"),
+    bodyFont: fontOf(typography["body"], "Inter"),
+    voiceTone: str(voice["tone"]),
+    logoSvg: chosen?.svg || void 0,
+    pricing: str(answers["pricing-model"]) || void 0
+  };
+}
+function indexHtml(spec, opts) {
+  const domain = (opts.domain || "https://example.com").replace(/\/+$/, "");
+  const founder = opts.founderName || "";
+  const social = opts.socialImage || `${domain}/og-image.png`;
+  const name = esc(spec.brandName);
+  const headline = esc(spec.tagline || spec.brandName);
+  const lead = esc(spec.pitch || spec.positioning);
+  const desc = esc(spec.pitch || spec.positioning || spec.brandName);
+  const fonts = `https://fonts.googleapis.com/css2?family=${fam(spec.displayFont)}:wght@400;600;700;800&family=${fam(spec.bodyFont)}:wght@400;500;600&display=swap`;
+  const graph = [
+    { "@type": "Organization", "@id": `${domain}/#org`, name: spec.brandName, url: `${domain}/`, ...founder ? { founder: { "@id": `${domain}/#founder` } } : {} },
+    ...founder ? [{ "@type": "Person", "@id": `${domain}/#founder`, name: founder, worksFor: { "@id": `${domain}/#org` } }] : [],
+    { "@type": "WebSite", "@id": `${domain}/#website`, url: `${domain}/`, name: spec.brandName, publisher: { "@id": `${domain}/#org` } },
+    { "@type": "WebPage", "@id": `${domain}/#webpage`, url: `${domain}/`, name: `${spec.brandName}${spec.tagline ? " - " + spec.tagline : ""}`, isPartOf: { "@id": `${domain}/#website` }, about: { "@id": `${domain}/#org` }, description: spec.pitch || spec.positioning || spec.brandName }
+  ];
+  const jsonLd = JSON.stringify({ "@context": "https://schema.org", "@graph": graph }).replace(/</g, "\\u003c").replace(/>/g, "\\u003e");
+  const lockup = spec.logoSvg ? spec.logoSvg : `<span class="wordmark">${name}</span>`;
+  const pills = spec.personality.map((t) => `<li class="pill">${esc(t)}</li>`).join("");
+  const positioningSection = spec.positioning ? `<section class="value" aria-labelledby="value-h"><div class="wrap"><h2 id="value-h">Who it is for</h2><p>${esc(spec.positioning)}</p>${pills ? `<ul class="pills" aria-label="What it stands for">${pills}</ul>` : ""}</div></section>` : "";
+  const pricingSection = spec.pricing ? `<section class="pricing" aria-labelledby="pricing-h"><div class="wrap"><h2 id="pricing-h">Pricing</h2><p class="price">${esc(spec.pricing)}</p></div></section>` : "";
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${name}${spec.tagline ? " - " + headline : ""}</title>
+<meta name="description" content="${desc}">
+<link rel="canonical" href="${domain}/">
+<meta property="og:type" content="website">
+<meta property="og:title" content="${name}">
+<meta property="og:description" content="${desc}">
+<meta property="og:url" content="${domain}/">
+<meta property="og:image" content="${esc(social)}">
+<meta name="twitter:card" content="summary_large_image">
+<meta name="twitter:title" content="${name}">
+<meta name="twitter:description" content="${desc}">
+<meta name="twitter:image" content="${esc(social)}">
+<link href="${esc(fonts)}" rel="stylesheet">
+<script type="application/ld+json">${jsonLd}</script>
+<style>
+:root{--p:${spec.palette.primary};--a:${spec.palette.accent};--ink:${spec.palette.ink};--su:${spec.palette.surface};--mu:${spec.palette.muted};--disp:'${spec.displayFont}',system-ui,sans-serif;--body:'${spec.bodyFont}',system-ui,sans-serif}
+*{margin:0;padding:0;box-sizing:border-box}
+html{scroll-behavior:smooth}
+body{background:var(--su);color:var(--ink);font-family:var(--body);line-height:1.6;-webkit-font-smoothing:antialiased}
+.wrap{max-width:960px;margin:0 auto;padding:0 24px}
+a{color:var(--a)}
+:focus-visible{outline:3px solid var(--a);outline-offset:2px}
+.sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);border:0}
+header{padding:24px 0}
+header .wrap{display:flex;align-items:center;justify-content:space-between;gap:16px}
+.wordmark{font-family:var(--disp);font-weight:800;font-size:22px;color:var(--p)}
+.logo svg,.logo img{height:36px;width:auto}
+.cta{display:inline-block;background:var(--p);color:#fff;text-decoration:none;font-weight:600;padding:12px 22px;border-radius:10px;border:0;cursor:pointer;font-size:15px}
+.cta.alt{background:var(--a)}
+.hero{padding:72px 0 56px}
+.hero h1{font-family:var(--disp);font-weight:800;font-size:clamp(34px,6vw,60px);line-height:1.05;color:var(--ink);letter-spacing:-0.02em;max-width:14ch}
+.hero p.lead{font-size:clamp(17px,2.4vw,22px);opacity:.82;margin:20px 0 28px;max-width:42ch}
+.signup{display:flex;gap:10px;flex-wrap:wrap;max-width:460px}
+.signup input[type=email]{flex:1 1 220px;padding:12px 14px;border:1px solid var(--mu);border-radius:10px;font:inherit;background:#fff;color:var(--ink)}
+.value,.pricing{padding:48px 0;border-top:1px solid color-mix(in srgb,var(--mu) 40%,transparent)}
+.value h2,.pricing h2{font-family:var(--disp);font-weight:700;font-size:28px;margin-bottom:12px}
+.value p{max-width:54ch;opacity:.85}
+ul.pills{list-style:none;display:flex;flex-wrap:wrap;gap:10px;margin-top:22px}
+.pill{font-size:13px;font-weight:600;color:var(--p);background:color-mix(in srgb,var(--p) 12%,transparent);padding:6px 14px;border-radius:999px}
+.pricing .price{font-family:var(--disp);font-size:24px;font-weight:700;color:var(--p);margin-top:8px}
+footer{padding:48px 0;border-top:1px solid color-mix(in srgb,var(--mu) 40%,transparent);color:var(--mu);font-size:13px}
+@media (max-width:640px){.hero{padding:48px 0 40px}header .wrap{flex-direction:column;align-items:flex-start}}
+</style>
+</head>
+<body>
+<header><div class="wrap"><div class="logo">${lockup}</div><a class="cta" href="#get-started">Get early access</a></div></header>
+<main>
+<section class="hero" aria-labelledby="hero-h"><div class="wrap">
+<h1 id="hero-h">${headline}</h1>
+<p class="lead">${lead}</p>
+<form name="signups" id="get-started" method="POST" data-netlify="true" class="signup">
+<input type="hidden" name="form-name" value="signups">
+<label class="sr-only" for="email">Email address</label>
+<input id="email" type="email" name="email" placeholder="you@email.com" required>
+<button type="submit" class="cta alt">Get early access</button>
+</form>
+</div></section>
+${positioningSection}
+${pricingSection}
+</main>
+<footer><div class="wrap"><p>${name}${founder ? ` - by ${esc(founder)}` : ""}. Scaffolded by The Thought Layer.</p></div></footer>
+</body>
+</html>
+`;
+}
+function companionFiles(spec, opts) {
+  const domain = (opts.domain || "https://example.com").replace(/\/+$/, "");
+  const name = spec.brandName;
+  const summary = spec.pitch || spec.positioning || name;
+  const llms = `# ${name}
+
+> ${summary}
+
+## About
+${name}${spec.tagline ? ` - ${spec.tagline}` : ""}. ${spec.positioning || summary}
+
+## Pages
+- [Home](${domain}/) - ${spec.tagline || summary}
+
+## FAQ
+- What is ${name}? ${summary}
+- Who is it for? ${spec.positioning || "See the home page."}
+`;
+  const robots = `User-agent: *
+Allow: /
+
+User-agent: GPTBot
+Allow: /
+
+User-agent: ClaudeBot
+Allow: /
+
+User-agent: PerplexityBot
+Allow: /
+
+User-agent: Google-Extended
+Allow: /
+
+Sitemap: ${domain}/sitemap.xml
+`;
+  const sitemap = `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <url><loc>${domain}/</loc><changefreq>weekly</changefreq><priority>1.0</priority></url>
+</urlset>
+`;
+  const redirects = `/*  /index.html  200
+`;
+  const netlifyToml = `[build]
+  publish = "."
+
+[[redirects]]
+  from = "/*"
+  to = "/index.html"
+  status = 200
+`;
+  const seoDoc = `# SEO and deployment
+
+This static site was scaffolded deterministically by The Thought Layer. It is ready to deploy (drag the publish folder onto https://app.netlify.com/drop, or use the deploy step). Everything below is already in place; the lines marked TO FILL need your input.
+
+## In place
+- **Structured data**: schema.org JSON-LD (@graph) with Organization, WebSite, and WebPage in index.html.
+- **/llms.txt**: an AI-crawler summary at the site root.
+- **robots.txt**: allows search + AI crawlers and points to the sitemap.
+- **sitemap.xml**: lists the home page.
+- **Canonical + Open Graph + Twitter Card** meta on the page.
+- **_redirects** and **netlify.toml**: SPA fallback (/* -> /index.html).
+- **Email capture**: a Netlify Forms signup ("signups") - submissions appear in your Netlify dashboard after deploy, no backend needed.
+- Semantic, accessible HTML (landmarks, heading order, labelled form, visible focus).
+
+## TO FILL
+- **Domain**: replace ${domain} with your real domain in index.html (canonical/OG), llms.txt, robots.txt, sitemap.xml. Pass --domain to the scaffold tool to set it up front.
+- **Founder + sameAs**: add a Person with real sameAs profile links (LinkedIn, X) to the JSON-LD, and cross-reference the Organization. Pass --founder to seed the name.
+- **Social image**: add a 1200x630 image at /og-image.png (referenced by og:image / twitter:image).
+- **The product**: this is a landing/coming-soon page. Build the actual product with the thought-layer-build skill (/tl-build).
+`;
+  return {
+    "llms.txt": llms,
+    "robots.txt": robots,
+    "sitemap.xml": sitemap,
+    "_redirects": redirects,
+    "netlify.toml": netlifyToml,
+    "SEO.md": seoDoc
+  };
+}
+function buildStarterSite(spec, opts = {}) {
+  return { files: { "index.html": indexHtml(spec, opts), ...companionFiles(spec, opts) } };
+}
+function scaffoldManifest(publishDir, builtAt, provenance) {
+  return {
+    app: "thought-layer",
+    kind: "build",
+    version: 1,
+    builtAt,
+    producer: "scaffold",
+    publishDir,
+    entry: "index.html",
+    stack: "static",
+    hasBackend: false,
+    backendNote: null,
+    buildCommand: null,
+    installCommand: null,
+    nodeVersion: "20",
+    provenance,
+    requirements: { total: 0, built: 0, deferred: 0, deferredIds: [] },
+    seo: { jsonLd: true, llmsTxt: true, sitemap: true, robots: true, canonical: true, openGraph: true, socialImage: false, semanticHtml: true, seoDoc: true, netlifyToml: true },
+    artifacts: { traceability: null, decisions: null, seo: "SEO.md" },
+    verified: { buildRan: true, publishDirExists: true, entryLoads: true, notes: "deterministic static scaffold; landing page + SEO files written" }
+  };
+}
+
+// core/scaffold-io.ts
+function runScaffold(opts, ctx) {
+  try {
+    const loaded = loadStateFile(opts.path);
+    const spec = extractScaffoldSpec(loaded.state);
+    const { files } = buildStarterSite(spec, { domain: opts.domain, founderName: opts.founderName, socialImage: opts.socialImage });
+    const outDir = opts.outDir || "dist";
+    const outAbs = isAbsolute2(outDir) ? outDir : resolve2(process.cwd(), outDir);
+    mkdirSync2(outAbs, { recursive: true });
+    for (const [name, content] of Object.entries(files)) {
+      writeFileSync2(join2(outAbs, name), content);
+    }
+    const prd = loaded.state.prd && typeof loaded.state.prd === "object" ? loaded.state.prd : null;
+    const grill = loaded.state.grill && typeof loaded.state.grill === "object" ? loaded.state.grill : null;
+    const manifest = scaffoldManifest(outDir, ctx.builtAt, {
+      stateFile: loaded.path,
+      prdTs: prd && typeof prd["ts"] === "number" ? prd["ts"] : null,
+      grillDone: !!(grill && grill["done"] === true),
+      fromSpeedrun: loaded.state.kit?.cursor?.phase === "speedrun"
+    });
+    const manifestPath = join2(dirname2(loaded.path), "build.json");
+    mkdirSync2(dirname2(manifestPath), { recursive: true });
+    writeFileSync2(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+    const names = Object.keys(files);
+    return {
+      ok: true,
+      message: `Scaffolded a deployable static site for "${spec.brandName}" -> ${outAbs} (${names.length} files: ${names.join(", ")}). Manifest: ${manifestPath}. Deploy the publish dir, or build the full product with /tl-build.`,
+      details: { publishDir: outDir, outAbs, files: names, manifestPath, brandName: spec.brandName, hadBrand: loaded.state.brand != null }
+    };
+  } catch (e) {
+    return { ok: false, message: `tl_scaffold error: ${e.message}`, details: {} };
+  }
+}
+
 // bin/tl.ts
-var HELP = `tl - read/write the portable Thought Layer state file (.thought-layer/state.json)
+var HELP = `tl - read/write a portable Thought Layer state file (default: .thought-layer/state.json)
 
   tl read [path] [--json]            where the run stands
+  tl list [dir]                      list the state files under .thought-layer/ (juggle several ideas)
+  tl scaffold [--out dist] [--domain x.com] [--founder "Name"]  deterministic deployable static site from the spec + brand
   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})
@@ -376,6 +683,9 @@ var HELP = `tl - read/write the portable Thought Layer state file (.thought-laye
   tl park <key> <note> [path]        stash a panel note
   tl exec --data '<json>'            run a full {op,...} payload
 
+Selecting a file: pass --path <file>.json (or a positional path) to any op, keep several
+ideas as .thought-layer/<name>.json, or set THOUGHT_LAYER_STATE once as the session default.
+
   --path <p>  project dir or .json path   --data <j>  JSON payload ("-" = stdin)
   --json      print details JSON          -h, --help`;
 function parseArgs(argv) {
@@ -414,6 +724,8 @@ function buildOp(args, flags) {
     case "read":
     case "export":
       return { op, path: path ?? args[1] };
+    case "list":
+      return { op, path: path ?? args[1] };
     case "answer":
       return { op, qId: args[1], value: args[2], path: path ?? args[3] };
     case "park":
@@ -437,6 +749,20 @@ function main() {
     console.log(HELP);
     process.exit(0);
   }
+  if (args[0] === "scaffold") {
+    const r2 = runScaffold(
+      {
+        path: typeof flags["path"] === "string" ? flags["path"] : void 0,
+        outDir: typeof flags["out"] === "string" ? flags["out"] : void 0,
+        domain: typeof flags["domain"] === "string" ? flags["domain"] : void 0,
+        founderName: typeof flags["founder"] === "string" ? flags["founder"] : void 0
+      },
+      { builtAt: (/* @__PURE__ */ new Date()).toISOString() }
+    );
+    if (flags["json"]) console.log(JSON.stringify(r2.details, null, 2));
+    else console.log(r2.message);
+    process.exit(r2.ok ? 0 : 1);
+  }
   let payload;
   try {
     payload = buildOp(args, flags);

package/extensions/thought-layer.ts

@@ -9,7 +9,7 @@ import {
   aggregateConfidence, statusFromConfidence, gradeFromConfidence,
   checkDomains, registrarSearchUrl,
   computeProjection, fmtMoney,
-  applyStateOp,
+  applyStateOp, runScaffold,
   type Assumptions, type StateOp,
 } from "../core/index.ts";
 
@@ -148,16 +148,16 @@ export default function (pi: ExtensionAPI) {
     name: "tl_state",
     label: "Thought Layer: state",
     description:
-      "Read, update, and write the portable Thought Layer progress file (.thought-layer/state.json) shared with the web app so work passes losslessly between a founder in the browser and an agent. " +
-      "ops: 'read' (resume: where the run stands), 'answer' (record a question answer), 'feedback' (record a panel verdict - pass it the per-persona prose + confidences and it builds the exact entry), " +
+      "Read, update, and write a portable Thought Layer progress file (default .thought-layer/state.json) shared with the web app so work passes losslessly between a founder in the browser and an agent. " +
+      "ops: 'read' (resume: where the run stands), 'list' (list the state files under .thought-layer/ when juggling several ideas), 'answer' (record a question answer), 'feedback' (record a panel verdict - pass it the per-persona prose + confidences and it builds the exact entry), " +
       "'artifact' (store prd/grill/bizModel/naming/brand/etc., requirements auto-normalized), 'cursor' (save resume position), 'park' (stash a panel note with no web-app question), 'export' (report the current file for handoff). " +
-      "Always use this instead of writing the JSON by hand.",
+      "To juggle several ideas, give each its own file via `path` (e.g. .thought-layer/acme.json) and use the same path for every op in the session. Always use this instead of writing the JSON by hand.",
     parameters: Type.Object({
       op: Type.Union([
-        Type.Literal("read"), Type.Literal("answer"), Type.Literal("feedback"),
+        Type.Literal("read"), Type.Literal("list"), Type.Literal("answer"), Type.Literal("feedback"),
         Type.Literal("artifact"), Type.Literal("cursor"), Type.Literal("park"), Type.Literal("export"),
       ], { description: "The operation to perform." }),
-      path: Type.Optional(Type.String({ description: "Project dir or .json path. Defaults to ./.thought-layer/state.json in the cwd." })),
+      path: Type.Optional(Type.String({ description: "Project dir or .json path; selects WHICH state file to use. Defaults to ./.thought-layer/state.json. Use a named file (e.g. .thought-layer/acme.json) to keep ideas separate; for 'list', a project dir to scan." })),
       qId: Type.Optional(Type.String({ description: "Question id (for 'answer'/'feedback'). Must be a real Thought Layer question id." })),
       value: Type.Optional(Type.Unknown({ description: "For 'answer': the answer string. For 'artifact': the artifact object." })),
       artifact: Type.Optional(Type.String({ description: "For 'artifact': one of bizModel, grill, assets, research, swot, prd, naming, brand." })),
@@ -179,4 +179,28 @@ export default function (pi: ExtensionAPI) {
       return text(r.message, r.details);
     },
   });
+
+  // tl_scaffold: deterministically generate a self-contained, branded,
+  // SEO-complete static site (the instantly-deployable floor) from the spec +
+  // brand in the state file - no model needed. Writes the site to a publish dir
+  // plus a build.json manifest the deploy step consumes.
+  pi.registerTool({
+    name: "tl_scaffold",
+    label: "Thought Layer: scaffold",
+    description:
+      "Deterministically scaffold a self-contained, branded, SEO-complete static landing site (an instantly-deployable floor) from the spec + brand in the state file - no model call. " +
+      "Use it for the fastest path to something live, or as the floor when a model build is thin or fails. Writes the site (index.html + llms.txt/robots.txt/sitemap.xml/_redirects/netlify.toml/SEO.md) to the publish dir and a build.json manifest for the deploy step. " +
+      "The full product is built by the thought-layer-build skill; this is the guaranteed deployable baseline.",
+    parameters: Type.Object({
+      path: Type.Optional(Type.String({ description: "State file (or project dir) to read the spec + brand from. Defaults to ./.thought-layer/state.json; honors a named file." })),
+      outDir: Type.Optional(Type.String({ description: "Publish directory to write the site into. Defaults to ./dist." })),
+      domain: Type.Optional(Type.String({ description: "The site's real domain (e.g. https://acme.com) for canonical/OG/sitemap. Defaults to a placeholder you fill later." })),
+      founder: Type.Optional(Type.String({ description: "Founder name for the schema.org Person + footer. Optional." })),
+    }),
+    async execute(_id, params): Promise<ToolResult> {
+      const p = params as { path?: string; outDir?: string; domain?: string; founder?: string };
+      const r = runScaffold({ path: p.path, outDir: p.outDir, domain: p.domain, founderName: p.founder }, { builtAt: new Date().toISOString() });
+      return text(r.message, r.details);
+    },
+  });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hobocode/thought-layer",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "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>",
@@ -64,6 +64,8 @@
     "core/stage-map.ts",
     "core/state-file.ts",
     "core/state-ops.ts",
+    "core/scaffold.ts",
+    "core/scaffold-io.ts",
     "dist",
     "README.md",
     "LICENSE"

package/prompts/tl-build.md

@@ -0,0 +1,7 @@
+Apply the **thought-layer-build** skill. Build the hardened PRD into a static-first, deploy-ready artifact - a self-contained site or a Vite/static build that yields a predictable `dist/`-style publish directory.
+
+If there is no hardened PRD in the state file (`state.prd.markdown` + requirements), say so and point me to `/tl` (or `/tl-prd` then `/tl-grill`) rather than building from a bare idea - only proceed cold if I tell you to.
+
+Honor the ubiquitous language (the glossary), R-ID traceability, the out-of-scope list, mobile+desktop, the brand if present, and the full SEO/discoverability layer. Default to static; escalate to a backend only when a requirement genuinely needs one, and flag loudly that the default deploy path is static. Verify the build runs, and leave `.thought-layer/build.json` + `DECISIONS.md` + `TRACEABILITY.md`.
+
+Read the spec from the state file (default `.thought-layer/state.json`; honor `--path` / `THOUGHT_LAYER_STATE` if a named file is in use). For the fastest deployable floor, or if a full build is too much, run the **tl_scaffold** tool to write a branded, SEO-complete static landing site and the same `build.json` manifest.

package/prompts/tl-speedrun.md

@@ -0,0 +1,9 @@
+Run the Thought Layer speedrun on the idea below using the **thought-layer-speedrun** skill.
+
+The speedrun is the fast path to a build-ready spec: a condensed five-stage validation spine (what it is, will anyone pay, the market, the price, do the numbers work) with fast unranked feedback - one honest read per stage, no panel, no `tl_score`, no grade, no 0.85 gate, and the user moves on when they are ready. After the five stages, ask whether to run the **thought-layer-brand** skill, then run **thought-layer-prd** and **thought-layer-grill** to reach a hardened, build-ready PRD. Do not skip the PRD and the grill - reaching the spec fast is the whole point, not stopping short of it. The same unranked, user-driven mode applies through the brand pass, the PRD, and the grill: ignore those skills' panel, scoring, gate, and stop-condition machinery (keep only the grill's metric-honesty rule), and let the user's "move on" end each step.
+
+Take it one stage at a time, one stage per turn, and wait for the user between stages. Persist answers and artifacts to the shared state file as you go (the question ids match the web app). The speedrun trades the panel's defensible conviction for speed, so close by pointing the user at the full `/tl` for anything they will actually build.
+
+If an idea is given below, treat it as the answer to stage 1 (the What) and give it a fast read before moving on. If nothing is below, ask the user for their idea in one sentence - do not wait to be handed a brief.
+
+The idea (if any):

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

@@ -0,0 +1,98 @@
+---
+name: thought-layer-build
+description: "Turn the hardened PRD into a static-first, deploy-ready artifact, built directly by this agent. Reads the build brief from the shared state file (PRD, glossary, R-ID requirements, brand, business context, open to-dos), then builds a self-contained site or a Vite/static build that yields a predictable publish directory (dist/), honoring ubiquitous language, R-ID traceability, the out-of-scope list, mobile+desktop, brand, and the full SEO/discoverability layer. Escalates to a backend only when the spec genuinely requires server-side, and flags loudly that the default deploy path is static. Verifies the build runs and writes a .thought-layer/build.json manifest for the deploy step. Run it after the grill has hardened the PRD; it is a standalone build step, not a validation stage."
+---
+
+# Build it: the hardened PRD becomes a deploy-ready artifact
+
+You are not generating a prompt to paste elsewhere. **You are the agent that builds.** The hardened PRD is your brief; build it now, static-first, and verify it actually runs. AI made building cheap, so the value is building the *right* thing, honestly, and shipping something real and ownable. One pass, then verify. This is a build step, not a second framework: no panel, no stages, no per-turn loop.
+
+For the fastest possible deployable thing, or as a floor when a full build is too much, you can run the **tl_scaffold** tool first (or instead) - it deterministically writes a branded, SEO-complete static landing site you can ship immediately, then build the real product on top.
+
+## Precondition: a hardened PRD must exist
+
+Read the state file first (next section). Then:
+- **Required:** `state.prd` with a non-empty `markdown` and a non-empty `requirements` array.
+- **Ideal:** `state.grill.done === true` (the PRD was actually hardened). If `prd` exists but the grill is absent or not done, build anyway and warn in one line: "Building from a drafted-but-not-grilled PRD - gaps the grill would have caught may surface; `/tl-grill` first would tighten it."
+- **Refuse** only when there is no `prd.markdown` / no requirements at all: say so and point to `/tl` (the full framework) or at least `/tl-prd` then `/tl-grill`. Proceed cold only if the user explicitly says to, and record in DECISIONS.md that the spec was incomplete.
+
+## Read the brief from the state file
+
+The spec lives in `.thought-layer/state.json` (or a named file). Honor the same selection as the rest of the kit: an explicit `--path` / tool `path` wins, then `THOUGHT_LAYER_STATE`, then the default. If the `tl_state` tool is available (Pi), `tl_state read`; otherwise `tl read --json` (the CLI). If neither a path nor the env is set, `tl list` (or `tl_state list`) first and **ask which idea to build** when several exist, then stick to that path for the whole session and write `build.json` next to it.
+
+Assemble the brief from the state:
+- `prd.markdown` - the full spec (your primary source of truth).
+- `prd.glossary` `[{term, definition}]` - the ubiquitous language to enforce.
+- `grill.requirements` if `grill.done`, else `prd.requirements` `[{id, category, text}]` - the R-IDs to build and trace.
+- `prd.weakestAssumptions` - flag these as known gaps in DECISIONS.md.
+- `brand` - the identity to apply (skip if absent; see ground rules).
+- `bizModel.assumptions` / key `answers` - a one-line business context.
+- `feedback` to-dos and any "Open validation to-dos" in the PRD - known gaps the founder set aside; build around them, do not treat them as blockers.
+
+## The ground rules (honor these exactly)
+
+- **Ubiquitous language.** Use the glossary's terms verbatim for every entity, field, route, and UI label. Do not introduce synonyms.
+- **Traceability.** Every requirement has an R-ID. Create `TRACEABILITY.md` mapping each R-ID to the file/component that implements it and how it is verified (a test, a manual check, or "deferred").
+- **Out of scope is absolute.** Do not build past the spec's Out-of-Scope list, even if it looks easy.
+- **Mobile and desktop both work.** Responsive by default; check both viewports.
+- **Brand.** If `state.brand` is present, apply its colors, type, voice, and name throughout. If absent, pick a clean, neutral, accessible default and record the choice in DECISIONS.md.
+- **Ask nothing, decide and record.** The spec is the answer; where it is genuinely silent, choose the simplest option consistent with the PRD and record it in `DECISIONS.md` rather than blocking.
+
+## Build static-first
+
+Default to a self-contained static site or a Vite/Astro/static build whose output is one publish directory (`dist/`); set the manifest `hasBackend: false`. Pure HTML/CSS/JS where the interactivity allows; a bundler only when the spec warrants it.
+
+**Escalate to a backend ONLY if a requirement genuinely needs one** - apply this three-question test to the R-IDs:
+1. Does it need a **secret** that cannot ship to the browser (a server-side API key, a payment secret)?
+2. Does it need **shared or persistent state across users** (a real database, server-stored accounts)?
+3. Does it need **trusted server-side enforcement** (something the client must not be allowed to fake)?
+
+If all three are no, build **static, full stop.** localStorage, static data files, BYOK client-side AI calls, and third-party embeddable widgets do **not** count as a backend - many specs that sound like they need a server can ship a compelling static slice first.
+
+**When a backend is genuinely required:** build the static parts anyway, set `hasBackend: true` + `backendNote` in the manifest, and **warn loudly** in chat: the default deploy publishes a static `dist/` to Netlify, so the server part will not deploy that way and needs serverless functions or a separate host. Build the static shell with a clear seam for the backend.
+
+## SEO and discoverability (build all of it, do not skip it)
+
+This is the cheap moat. Either run **tl_scaffold** to lay these down for you, or build them by hand into the publish dir, and set each `build.json.seo.*` flag from the file you actually emitted:
+- schema.org JSON-LD as one `@graph` (Organization + Person(founder) cross-referenced, WebSite, and the page type that matches the content); never a type that does not match visible content.
+- `/llms.txt` (title, one-paragraph summary, links to the key pages, a short FAQ).
+- `sitemap.xml`, `robots.txt` (allow search + AI crawlers, point to the sitemap), a canonical link, Open Graph + Twitter meta, and a 1200x630 social image.
+- Semantic, accessible HTML: landmarks, ordered headings, alt text, labelled controls, a visible focus style.
+- A `netlify.toml` (publish dir + SPA redirect) and a `SEO.md` documenting where each item lives and what to fill later (the sameAs links, the social image, the real domain).
+
+## Verify before you call it done
+
+Do not declare victory - check:
+1. **Run the build.** For a bundler: `npm install` then the build command; confirm it exits clean (capture the command into `build.json.buildCommand`). For pure static: confirm the files exist.
+2. **Confirm the publish dir + entry load.** `dist/index.html` (or your entry) exists and is non-trivial. Where a preview or browser tool is available, load it and confirm it renders; otherwise inspect the built HTML for the expected title/nav/hero and that the mobile viewport meta is set.
+3. **R-ID coverage.** Walk TRACEABILITY.md: each R-ID is implemented (with a pointer) or explicitly deferred (with a reason). Put the counts in `build.json.requirements`.
+4. **SEO check.** Confirm the SEO files are actually in the publish dir; set `build.json.seo.*` from reality, not intent.
+5. **Report** what is built and what is deferred, plainly, in chat.
+
+## Honest about being model-built
+
+If you cannot fully build it (the spec is thin, a requirement you genuinely cannot satisfy, time or tool limits), ship **the best static slice that loads** plus DECISIONS.md noting every gap and TRACEABILITY.md marking the unbuilt R-IDs deferred. A partial, honest, deployable artifact beats a complete-looking broken one. **Never fake a green check** - `verified.buildRan: false` is an acceptable, honest value. If even a slice is too much, run **tl_scaffold** to leave a real deployable landing page as the floor.
+
+## Leave a manifest and your decisions
+
+Write three files with your own file tools (the manifest is NOT a `tl_state` artifact - it is a plain sidecar):
+- `.thought-layer/build.json` - the deploy contract, co-located with the state file you read. Shape (fill what you can, never fake a field):
+
+```jsonc
+{ "app": "thought-layer", "kind": "build", "version": 1, "builtAt": "<ISO>",
+  "producer": "agent", "publishDir": "dist", "entry": "index.html",
+  "stack": "static|vite|astro|next-static|other", "hasBackend": false, "backendNote": null,
+  "buildCommand": null, "installCommand": null, "nodeVersion": "20",
+  "provenance": { "stateFile": "<the file you read>", "prdTs": <state.prd.ts>, "grillDone": <bool>, "fromSpeedrun": <bool> },
+  "requirements": { "total": 0, "built": 0, "deferred": 0, "deferredIds": [] },
+  "seo": { "jsonLd": true, "llmsTxt": true, "sitemap": true, "robots": true, "canonical": true, "openGraph": true, "socialImage": false, "semanticHtml": true, "seoDoc": true, "netlifyToml": true },
+  "artifacts": { "traceability": "TRACEABILITY.md", "decisions": "DECISIONS.md", "seo": "SEO.md" },
+  "verified": { "buildRan": true, "publishDirExists": true, "entryLoads": true, "notes": "..." } }
+```
+  `publishDir` + `entry` are load-bearing - the deploy step reads them. (The `tl_scaffold` tool writes this same manifest with `producer: "scaffold"`.)
+- `DECISIONS.md` - every choice the spec did not pin down, one line each, with the reason.
+- `TRACEABILITY.md` - the R-ID map. (`SEO.md` comes from the SEO step.)
+
+## Persisting
+
+The build output and the three files live on disk; the portable `state.json` stays focused on validation and design. The only optional state touch is a best-effort cursor bump - `tl_state cursor` (or `tl cursor`) with `{ "backboneStage": 15, "phase": "built" }` - pure provenance; if the tool is absent or it fails, the build still succeeded. Tell the user where the artifact is (`<publishDir>`) and that the next step is the deploy (Phase 4, `/tl-deploy`, coming) which reads `build.json`.

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

@@ -24,9 +24,11 @@ Reaching the Grill or the PRD before all of Part 1 (validate the idea) and Part
 
 No one finishes this in one sitting. The work lives in a portable file, `.thought-layer/state.json`, in the project directory. It is your memory across turns and sessions, and it is the SAME interop file the web app reads, so a founder can answer some stages here and hand the file to a co-founder who continues in the web app (weareallproductmanagersnow.com, "Load progress from file"), back and forth, losslessly. Never hand-write this JSON: use the tool below, which builds the exact shapes the web app expects.
 
-**The tool.** If the `tl_state` tool is available (Pi), use it. Otherwise run the CLI from any shell: `npx -y @hobocode/thought-layer tl <op> ...` (or just `tl ...` if the package is installed). Ops: `read`, `answer`, `feedback`, `artifact`, `cursor`, `park`, `export`.
+**The tool.** If the `tl_state` tool is available (Pi), use it. Otherwise run the CLI from any shell: `npx -y @hobocode/thought-layer tl <op> ...` (or just `tl ...` if the package is installed). Ops: `read`, `list`, `answer`, `feedback`, `artifact`, `cursor`, `park`, `export`.
 
-**On start, ALWAYS read first.** `tl_state read` (or `tl read`). If a file exists, summarize where the run stands and **resume from the saved cursor** - do not restart at stage 1. If not, start fresh; the file is created on first write.
+**Choosing the file.** The default is `.thought-layer/state.json`. To keep several ideas side by side, give each its own file and use the SAME path for every op in the session: pass `--path .thought-layer/<name>.json` (or the tool's `path`), or set `THOUGHT_LAYER_STATE` once as the session default. `list` shows the files already there.
+
+**On start, ALWAYS read first.** `tl_state read` (or `tl read`). If a file exists, summarize where the run stands and **resume from the saved cursor** - do not restart at stage 1. If not, start fresh; the file is created on first write. If `list` shows more than one state file, ask which idea to resume (or to start a new one) before reading, and stick to that path for the rest of the session.
 
 **After each stage:**
 1. Record the answer against its question id: `tl_state` op `answer` (or `tl answer <qId> "<value>"`).
@@ -87,6 +89,8 @@ This is where "how will it actually be built" gets answered. Every implementatio
 14. **The PRD (draft).** Run the **thought-layer-prd** skill: compose a complete first-draft PRD — including a first-cut domain glossary and testable requirements — from the validated idea and the business model above.
 15. **The Grill.** Run the **thought-layer-grill** skill: grill that draft PRD. Challenge it against the domain one question at a time, sharpen the glossary, surface contradictions, unstated rules, and edge cases, and update the PRD inline until it is build-ready.
 
+Once the grill has hardened the PRD, the spec is build-ready. Run the **thought-layer-build** skill (`/tl-build`) to turn it into a static-first, deploy-ready artifact (or the `tl_scaffold` tool for an instant deployable landing-page floor). This is the build step, not another validation stage.
+
 ## Supporting passes (run when relevant)
 
 Not strictly sequential; pull them in when they help: market research on the segment, a SWOT once the picture is full, and **thought-layer-naming** plus domain checks when the thing needs a name. These inform the stages above; they do not replace them.

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

@@ -0,0 +1,62 @@
+---
+name: thought-layer-speedrun
+description: "Run the Thought Layer at speed: a condensed five-stage validation spine (what it is, will anyone pay, market, price, do the numbers work) with fast unranked feedback - no panel, no score, no 0.85 gate, you move on when ready - then an optional brand pass and the PRD plus grill, so you still reach a build-ready spec. For the impatient and for demos. It trades the panel's defensible conviction for speed; run the full thought-layer-framework on anything you will actually build."
+---
+
+# The Thought Layer speedrun
+
+The fast path to a build-ready spec. You still reach the same SHAPE of output the full framework produces - a PRD hardened by the grill - but the validation in front of it is compressed to five fast, unranked stages, and there is far less conviction behind it. No panel, no confidence score, no 0.85 gate: one honest read per stage, and you move on whenever you want.
+
+For the impatient, and a good way to see the whole arc - validation to spec - in one sitting (a demo). It trades the panel's defensible conviction for speed: the spec is real and buildable, but the validation behind it is a gut-check, not an adversarial panel. For anything you will actually build, run the full **thought-layer-framework** (`/tl`) - the rigor is the part that was ever scarce. Speedrun is the taste and the on-ramp.
+
+## How the fast feedback works
+
+For each of the five stages, give ONE honest read - not three personas, no `tl_score`, no grade, no gate:
+
+- The single strongest thing about the answer, and the single weakest.
+- At most one sharp question or fix that would most improve it.
+- Then ask: "sharpen it, or move on?" The user decides, every time. Keep offering feedback as they revise; never force a bar, never auto-advance.
+
+Stay honest and stay fast: a few sentences, not an audit. **Fast does not mean kind** - a fatal flaw gets named plainly even if everything else gets one sentence. Park concerns that belong to the design phase in a line ("we'll catch that in the grill") rather than raising them now.
+
+**This no-panel, no-score, no-gate, user-driven rule holds for the ENTIRE speedrun - the brand pass, the PRD, and the grill included.** Every sub-skill you invoke below runs in this unranked, user-driven mode: ignore its panel, `tl_score`, 0.85-gate, disqualifier-loop, and "categories covered" stop machinery, and let the user's "move on" end each step. The one exception is the grill's **metric-honesty rule**, kept below - it is cheap and load-bearing.
+
+## The five-stage spine
+
+One stage per turn, in order, waiting for the user between stages. Record each answer to the shared state file as you go (op `answer`; see "Persisting"). The question ids match the web app exactly, so a speedrun loads straight into it. The spine deliberately skips the framework's domain-knowledge, time, costs, scale, acquisition, relationships, and support stages; those stay blank by design, so a loaded file that reads as partially complete is expected, not an error. If a skipped stage holds something that genuinely blocks the spec, raise it in one line instead of re-opening the stage.
+
+1. **The What** (`what-statement`) - "One sentence: a thing that does what, for whom." Clear and specific, not the pitch.
+2. **Will anyone pay?** (`paid-today`, `evidence`) - "Has anyone paid you to solve this, or what is the strongest signal they will?" Liking is not buying.
+3. **The market** (`target-market`, `incumbent-gap`) - "Who specifically is this for, and why won't an incumbent just copy it?" Start with the smallest market you can dominate.
+4. **The price** (`pricing-model`) - "What is the number, and can you defend it in one sentence without apologizing?"
+5. **Do the numbers move?** (`bm-who-buys`, `bm-who-supplies`) - "Name the price, a plausible customer count, and the main monthly costs as real numbers: does revenue clear cost, and roughly when?" The honest read is whether those are real estimates or hopeful blanks. Use the `tl_project` tool for a quick projection and store it as the `bizModel` artifact if useful. (`bm-parties` is intentionally left for the full mode, so the `/tl` upgrade stays lossless.)
+
+After stage 5, before the design phase, branch on brand.
+
+## Before the PRD: ask about brand
+
+Ask the user once: **"Want to name it and sketch a quick brand before we spec it?"**
+
+- If yes, run the **thought-layer-brand** skill (which wraps **thought-layer-naming** + the `tl_domains` tool) - for its stages and questions only: suppress its panel, `tl_score`, 0.85 gate, and disqualifier loop; one fast unranked read per brand step, and the user moves on when they like a direction. A speedrun brand is a directional sketch off an unvalidated idea - re-test it under `/tl` before you print it on anything. Its output feeds the PRD's identity and UX notes and persists as the `naming` and `brand` artifacts.
+- If no, go straight to the PRD.
+
+## The end - do NOT skip this, it is the whole point
+
+The speedrun gets you all the way to a real spec, fast. The two design steps are not optional.
+
+6. **The PRD.** Run the **thought-layer-prd** skill to compose the draft from the five answers (and the brand, if you ran it). Store it as the `prd` artifact.
+7. **The grill.** Run the **thought-layer-grill** skill to harden it, speedrun-style. **In speedrun mode the user's "good enough, ship it" ends the grill, not category coverage - this overrides the grill skill's own stop rule.** Hit only the highest-risk gaps and contradictions; do not pursue completeness. Keep the grill's **metric-honesty rule** (the cheap backstop against vanity metrics); relax only the exhaustive-coverage stop and the gate. Update the PRD inline and re-store the `prd` artifact when done.
+
+What you get is a fast first draft built on a gut-check, not a validated spec. Re-running the grill under `/tl`, with the panels behind it, is what turns it into something to bet on.
+
+With the PRD hardened you have a build-ready spec - run the **thought-layer-build** skill (`/tl-build`) to build it, or the `tl_scaffold` tool for an instant deployable landing page. (A speedrun spec is a gut-check; re-grill under `/tl` before you bet on it.)
+
+## Persisting
+
+Write to the state file as you go, like the full framework (see the **thought-layer-framework** skill's "Saving and resuming"): answers via op `answer`, the bizModel / naming / brand / prd / grill via op `artifact`, and a cursor via op `cursor` after each stage so the file resumes and upgrades cleanly (use the backbone stage numbers - the spine maps to stages 1, 3, 4, 9, 10, then the PRD is 14 and the grill 15; set `phase` to `speedrun`). The default file is `.thought-layer/state.json`; to keep several ideas apart, pass `--path .thought-layer/<name>.json` (or the tool's `path`) on every op, or set `THOUGHT_LAYER_STATE`, and use `list` to see what is already there. **Do not write graded feedback** - the speedrun does not rank, so there are no panel verdicts to store and the answers persist ungraded.
+
+This keeps a speedrun loadable in the web app and upgradable. If you resume a file that already has panel feedback or a `/tl` cursor, do not discard it: tell the user which stages are already graded and only speedrun the still-open ones. If the user stops mid-spine, the answers so far are already saved - tell them the file location and that they can resume here or upgrade to `/tl` anytime.
+
+## Demo mode
+
+If the user just wants to see how this works, offer to run the whole thing on a sample idea (suggest one, for example a scheduling tool for mobile dog groomers) so they can watch the arc - five fast reads, an optional brand, a PRD, a quick grill - in a couple of minutes. It is still one stage per turn, pausing for the user: demo mode is fast, not unattended. The sample writes a real `state.json`, so clear it (or run it in a throwaway directory) before the user starts on their own idea.