@hobocode/thought-layer 0.2.2 → 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/dist/tl.js

@@ -397,11 +397,284 @@ Pick one with --path .thought-layer/<name>.json, or set ${STATE_ENV} for the ses
   }
 }
 
+// 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 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})
@@ -476,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";
 
@@ -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.2",
+  "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/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

@@ -89,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

@@ -49,6 +49,8 @@ The speedrun gets you all the way to a real spec, fast. The two design steps are
 
 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.