@hobocode/thought-layer 0.2.0 → 0.2.2

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") {
@@ -365,9 +398,10 @@ function applyStateOp(p, ctx) {
 }
 
 // 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 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 +410,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 +451,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":
@@ -432,6 +471,7 @@ function buildOp(args, flags) {
 }
 function main() {
   const { args, flags } = parseArgs(process.argv.slice(2));
+  if (args[0] === "tl" || args[0] === "thought-layer") args.shift();
   if (flags["help"] || args.length === 0) {
     console.log(HELP);
     process.exit(0);

package/extensions/thought-layer.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." })),

package/package.json

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

package/prompts/tl-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-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>"`).

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

@@ -0,0 +1,60 @@
+---
+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.
+
+## 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.