@devinilabs/reelstack 1.2.0

package/docs/superpowers/plans/2026-05-09-reelstack-init-readiness-gate.md

@@ -0,0 +1,1166 @@
+# ReelStack Init Readiness Gate — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace ReelStack's warn-and-continue init with a 4-tier readiness gate so that after `init` exits 0, every `/reelstack-*` command works.
+
+**Architecture:** Restructure [cli/init.js](../../../cli/init.js) into ordered tiers (Node version hard gate → system binaries → Remotion project bootstrap → smoke test). Add two new modules: `cli/bootstrap.js` (Tier 3) and `cli/smoke.js` (Tier 4). Extend [cli/utils.js](../../../cli/utils.js) with platform-aware installer helpers and a small JSON state store at `~/.reelstack/state.json`. Read the spec at [`docs/superpowers/specs/2026-05-09-reelstack-init-readiness-gate-design.md`](../specs/2026-05-09-reelstack-init-readiness-gate-design.md) for full design rationale.
+
+**Tech Stack:** Node 20+, CommonJS, `node:test` runner, `node:child_process.spawnSync`. No new dependencies.
+
+---
+
+## File map
+
+| File | Responsibility | Action |
+|---|---|---|
+| `cli/utils.js` | Add `getPlatformInstaller()`, `loadState()`, `saveState()`, `STATE_FILE` constant | Modify |
+| `cli/bootstrap.js` | Tier 3: detect cwd state, run `npx create-video@latest`, install `@devinilabs/reelstack` | Create |
+| `cli/smoke.js` | Tier 4: scaffold Demo, validate via `npx remotion compositions`, validate `ffmpeg -version` | Create |
+| `cli/init.js` | Compose tiers, parse flags, write final state | Modify (substantial refactor) |
+| `cli/beats.js` | Read state.json; fail-fast if `whisperCli === "missing-declined"` | Modify (small) |
+| `test/utils-state.test.js` | Tests for `loadState` / `saveState` / `getPlatformInstaller` | Create |
+| `test/bootstrap.test.js` | Tests for cwd-state detection (no-pkg / non-remotion / remotion) | Create |
+| `test/smoke.test.js` | Tests for smoke-test step orchestration with mocked spawnSync | Create |
+| `test/init-flow.test.js` | Integration-ish test for init flag handling (`--skip-smoke`, `--no-bootstrap`) | Create |
+
+---
+
+## Task 1: Add state store + platform installer helper to utils.js
+
+**Files:**
+- Modify: `cli/utils.js`
+- Test: `test/utils-state.test.js`
+
+The state store records what init detected/did so subcommands can fail-fast with helpful messages. The platform helper returns a `{ kind, command, install }` triple per OS so Tier 2 has one place to ask "how do I install $bin on this machine?".
+
+- [ ] **Step 1: Write failing tests**
+
+Create `test/utils-state.test.js`:
+
+```javascript
+"use strict";
+
+const { test, beforeEach } = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+
+const TMP_HOME = path.join(
+  os.tmpdir(),
+  `reelstack-utils-test-${process.pid}-${Date.now()}`,
+);
+process.env.HOME = TMP_HOME;
+process.env.USERPROFILE = TMP_HOME;
+
+const utils = require("../cli/utils");
+
+beforeEach(() => {
+  fs.rmSync(TMP_HOME, { recursive: true, force: true });
+});
+
+test("STATE_FILE resolves under REELSTACK_HOME", () => {
+  assert.equal(
+    utils.STATE_FILE,
+    path.join(TMP_HOME, ".reelstack", "state.json"),
+  );
+});
+
+test("loadState returns {} when state file does not exist", () => {
+  assert.deepEqual(utils.loadState(), {});
+});
+
+test("saveState writes JSON, loadState round-trips", () => {
+  utils.saveState({ ffmpeg: "ok", whisperCli: "missing-declined" });
+  assert.deepEqual(utils.loadState(), {
+    ffmpeg: "ok",
+    whisperCli: "missing-declined",
+  });
+});
+
+test("saveState merges with existing state, doesn't replace", () => {
+  utils.saveState({ ffmpeg: "ok" });
+  utils.saveState({ whisperCli: "ok" });
+  assert.deepEqual(utils.loadState(), {
+    ffmpeg: "ok",
+    whisperCli: "ok",
+  });
+});
+
+test("getPlatformInstaller darwin returns brew when brew exists", () => {
+  const result = utils.getPlatformInstaller("darwin", "ffmpeg", {
+    whichFn: (b) => (b === "brew" ? "/opt/homebrew/bin/brew" : null),
+  });
+  assert.equal(result.kind, "auto");
+  assert.equal(result.command, "brew install ffmpeg");
+  assert.equal(typeof result.install, "function");
+});
+
+test("getPlatformInstaller darwin returns guidance when no brew", () => {
+  const result = utils.getPlatformInstaller("darwin", "ffmpeg", {
+    whichFn: () => null,
+  });
+  assert.equal(result.kind, "guide");
+  assert.match(result.command, /brew\.sh/);
+});
+
+test("getPlatformInstaller linux returns guide with apt+dnf+pacman", () => {
+  const result = utils.getPlatformInstaller("linux", "ffmpeg", {
+    whichFn: () => null,
+  });
+  assert.equal(result.kind, "guide");
+  assert.match(result.command, /apt-get install ffmpeg/);
+  assert.match(result.command, /dnf install ffmpeg/);
+  assert.match(result.command, /pacman -S ffmpeg/);
+});
+
+test("getPlatformInstaller win32 returns guide with choco+scoop", () => {
+  const result = utils.getPlatformInstaller("win32", "ffmpeg", {
+    whichFn: () => null,
+  });
+  assert.equal(result.kind, "guide");
+  assert.match(result.command, /choco install ffmpeg/);
+  assert.match(result.command, /scoop install ffmpeg/);
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+```bash
+cd /Users/abhishekraj/reelstack && node --test test/utils-state.test.js
+```
+
+Expected: FAIL with "STATE_FILE is undefined" / "loadState is not a function" etc.
+
+- [ ] **Step 3: Implement in cli/utils.js**
+
+Add to `cli/utils.js` (after the `which()` function, before `module.exports`):
+
+```javascript
+const STATE_FILE = path.join(REELSTACK_HOME, "state.json");
+
+function loadState() {
+  try {
+    return JSON.parse(fs.readFileSync(STATE_FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function saveState(patch) {
+  const current = loadState();
+  const next = { ...current, ...patch };
+  ensureDir(path.dirname(STATE_FILE));
+  fs.writeFileSync(STATE_FILE, JSON.stringify(next, null, 2), "utf8");
+}
+
+function getPlatformInstaller(platform, bin, opts = {}) {
+  const whichFn = opts.whichFn || which;
+  const { spawnSync } = require("node:child_process");
+
+  if (platform === "darwin") {
+    if (whichFn("brew")) {
+      return {
+        kind: "auto",
+        command: `brew install ${bin}`,
+        install() {
+          return spawnSync("brew", ["install", bin], { stdio: "inherit" });
+        },
+      };
+    }
+    return {
+      kind: "guide",
+      command: `Install Homebrew (https://brew.sh), then: brew install ${bin}`,
+      install: null,
+    };
+  }
+
+  if (platform === "linux") {
+    return {
+      kind: "guide",
+      command: [
+        `apt-get install ${bin}     # Debian/Ubuntu`,
+        `dnf install ${bin}         # Fedora`,
+        `pacman -S ${bin}           # Arch`,
+      ].join("\n  "),
+      install: null,
+    };
+  }
+
+  if (platform === "win32") {
+    return {
+      kind: "guide",
+      command: [
+        `choco install ${bin}       # Chocolatey`,
+        `scoop install ${bin}       # Scoop`,
+      ].join("\n  "),
+      install: null,
+    };
+  }
+
+  return {
+    kind: "guide",
+    command: `Install ${bin} via your platform's package manager`,
+    install: null,
+  };
+}
+```
+
+Update `module.exports` to add `STATE_FILE`, `loadState`, `saveState`, `getPlatformInstaller`.
+
+- [ ] **Step 4: Run tests, verify pass**
+
+```bash
+cd /Users/abhishekraj/reelstack && node --test test/utils-state.test.js
+```
+
+Expected: all 8 tests PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+cd /Users/abhishekraj/reelstack && git add cli/utils.js test/utils-state.test.js
+git commit -m "ReelStack init — add state store + platform installer helper
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+## Task 2: Tier 1 — Node version hard gate
+
+**Files:**
+- Modify: `cli/init.js` (the `checkNode()` function)
+
+The current `checkNode()` returns false on old Node but the caller doesn't act on it. Make it exit-on-fail with a clear remediation message. Keep the function name + signature stable so other callers (if any) aren't surprised.
+
+- [ ] **Step 1: Update `checkNode()` in cli/init.js**
+
+Replace [cli/init.js:40-48](../../../cli/init.js#L40):
+
+```javascript
+function checkNode() {
+  const major = Number(process.versions.node.split(".")[0]);
+  if (major < 20) {
+    fail(`Node ${process.versions.node} detected. ReelStack needs Node 20+.`);
+    console.log("");
+    console.log(c.gray("  Install Node 20+ via:"));
+    console.log(`    ${c.cyan("nvm install 20 && nvm use 20")}     # nvm`);
+    console.log(`    ${c.cyan("fnm install 20 && fnm use 20")}     # fnm`);
+    console.log(`    ${c.cyan("https://nodejs.org/")}              # installer`);
+    console.log("");
+    process.exit(1);
+  }
+  success(`Node ${process.versions.node}`);
+  return true;
+}
+```
+
+No tests required (single-branch logic, tested via integration test in Task 6).
+
+- [ ] **Step 2: Manually verify with current Node**
+
+```bash
+cd /Users/abhishekraj/reelstack && node cli/index.js --help
+```
+
+Expected: command runs without `process.exit(1)` firing (you're on Node 20+).
+
+- [ ] **Step 3: Commit**
+
+```bash
+cd /Users/abhishekraj/reelstack && git add cli/init.js
+git commit -m "ReelStack init — Tier 1: Node hard gate with install guidance
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+## Task 3: Tier 2 — System binaries with platform-aware install
+
+**Files:**
+- Modify: `cli/init.js` (replace `checkFfmpeg()` and `checkWhisper()`)
+
+Replace warn-only checks with the consent-driven install flow from the spec. ffmpeg is **required** (exit on miss + decline). whisper-cli is **soft** (declining records `whisperCli: "missing-declined"` in state.json and continues).
+
+- [ ] **Step 1: Replace `checkFfmpeg()` and `checkWhisper()` in cli/init.js**
+
+Replace [cli/init.js:50-66](../../../cli/init.js#L50):
+
+```javascript
+async function ensureFfmpeg() {
+  if (which("ffmpeg")) {
+    success("ffmpeg found");
+    saveState({ ffmpeg: "ok" });
+    return true;
+  }
+
+  fail("ffmpeg not found.");
+  const installer = getPlatformInstaller(process.platform, "ffmpeg");
+
+  if (installer.kind === "auto") {
+    const yes = await askYesNo(`Run \`${installer.command}\`?`);
+    if (!yes) {
+      console.log("");
+      fail("ffmpeg is required for /reelstack-render and /reelstack-beats.");
+      console.log(c.gray(`  Install later with: ${installer.command}`));
+      console.log(c.gray("  Then re-run: reelstack init"));
+      process.exit(1);
+    }
+    installer.install();
+    if (!which("ffmpeg")) {
+      fail("ffmpeg install did not complete. Check brew output above.");
+      process.exit(1);
+    }
+    success("ffmpeg installed");
+    saveState({ ffmpeg: "ok" });
+    return true;
+  }
+
+  // kind === "guide"
+  console.log("");
+  console.log(c.gray("  Install ffmpeg via:"));
+  console.log(c.gray(`    ${installer.command}`));
+  console.log(c.gray("  Then re-run: reelstack init"));
+  console.log("");
+  process.exit(1);
+}
+
+async function ensureWhisper() {
+  if (which("whisper-cli") || which("whisper-cpp")) {
+    success("whisper-cli found");
+    saveState({ whisperCli: "ok" });
+    return true;
+  }
+
+  warn("whisper-cli not found (only required for /reelstack-beats).");
+  const installer = getPlatformInstaller(process.platform, "whisper-cpp");
+
+  if (installer.kind === "auto") {
+    const yes = await askYesNo(`Run \`${installer.command}\`?`);
+    if (yes) {
+      installer.install();
+      if (which("whisper-cli") || which("whisper-cpp")) {
+        success("whisper-cli installed");
+        saveState({ whisperCli: "ok" });
+        return true;
+      }
+      warn("whisper install did not complete. /reelstack-beats will be unavailable.");
+    } else {
+      warn("Skipped. /reelstack-beats will be unavailable until you install whisper-cpp.");
+    }
+  } else {
+    console.log(c.gray(`  Install later with: ${installer.command}`));
+    console.log(c.gray("  /reelstack-beats will be unavailable until then."));
+  }
+
+  saveState({ whisperCli: "missing-declined" });
+  return false;
+}
+```
+
+Add to the imports at the top of [cli/init.js:19-22](../../../cli/init.js#L19):
+
+```javascript
+const {
+  banner, info, success, fail, warn, c, ask, askYesNo, ensureDir, which,
+  REELSTACK_HOME, CLAUDE_SKILLS_HOME, CLAUDE_COMMANDS_HOME,
+  saveState, getPlatformInstaller,
+} = require("./utils");
+```
+
+- [ ] **Step 2: Update the dep-check block in `run()`**
+
+Replace [cli/init.js:80-85](../../../cli/init.js#L80):
+
+```javascript
+  // 2. Dependencies
+  console.log("");
+  info("Checking dependencies…");
+  checkNode();
+  await ensureFfmpeg();
+  await ensureWhisper();
+```
+
+- [ ] **Step 3: Manually verify**
+
+```bash
+cd /Users/abhishekraj/reelstack && node cli/index.js init
+```
+
+Expected (on a machine with ffmpeg + whisper installed): both checks pass, init proceeds. State.json shows both as `"ok"`.
+
+```bash
+cat ~/.reelstack/state.json
+```
+
+Expected output:
+
+```json
+{
+  "ffmpeg": "ok",
+  "whisperCli": "ok"
+}
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+cd /Users/abhishekraj/reelstack && git add cli/init.js
+git commit -m "ReelStack init — Tier 2: ffmpeg required + whisper soft, with platform-aware install
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+## Task 4: Tier 3 — Remotion project bootstrap (cli/bootstrap.js)
+
+**Files:**
+- Create: `cli/bootstrap.js`
+- Test: `test/bootstrap.test.js`
+
+Encapsulates: detect cwd state (no-pkg / non-remotion / has-remotion), prompt buyer, run `npx create-video@latest --yes --blank <name>`, then `npm install @devinilabs/reelstack` inside the new project. Returns `{ projectDir, isNew }`.
+
+- [ ] **Step 1: Write failing tests**
+
+Create `test/bootstrap.test.js`:
+
+```javascript
+"use strict";
+
+const { test } = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+
+const bootstrap = require("../cli/bootstrap");
+
+function makeTmpDir(label) {
+  const dir = path.join(os.tmpdir(), `reelstack-bootstrap-${label}-${process.pid}-${Date.now()}`);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+test("detectCwdState returns 'no-package-json' for empty dir", () => {
+  const cwd = makeTmpDir("empty");
+  assert.equal(bootstrap.detectCwdState(cwd), "no-package-json");
+});
+
+test("detectCwdState returns 'has-remotion' when remotion in deps", () => {
+  const cwd = makeTmpDir("remotion-dep");
+  fs.writeFileSync(
+    path.join(cwd, "package.json"),
+    JSON.stringify({ dependencies: { remotion: "^4.0.0" } }),
+  );
+  assert.equal(bootstrap.detectCwdState(cwd), "has-remotion");
+});
+
+test("detectCwdState returns 'has-remotion' when remotion in devDependencies", () => {
+  const cwd = makeTmpDir("remotion-devdep");
+  fs.writeFileSync(
+    path.join(cwd, "package.json"),
+    JSON.stringify({ devDependencies: { remotion: "^4.0.0" } }),
+  );
+  assert.equal(bootstrap.detectCwdState(cwd), "has-remotion");
+});
+
+test("detectCwdState returns 'non-remotion-package' when package.json has no remotion", () => {
+  const cwd = makeTmpDir("non-remotion");
+  fs.writeFileSync(
+    path.join(cwd, "package.json"),
+    JSON.stringify({ dependencies: { lodash: "^4.0.0" } }),
+  );
+  assert.equal(bootstrap.detectCwdState(cwd), "non-remotion-package");
+});
+
+test("buildCreateVideoArgs returns --yes --blank <name>", () => {
+  assert.deepEqual(
+    bootstrap.buildCreateVideoArgs("my-reels"),
+    ["create-video@latest", "--yes", "--blank", "my-reels"],
+  );
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+```bash
+cd /Users/abhishekraj/reelstack && node --test test/bootstrap.test.js
+```
+
+Expected: FAIL with "Cannot find module '../cli/bootstrap'".
+
+- [ ] **Step 3: Implement cli/bootstrap.js**
+
+Create `cli/bootstrap.js`:
+
+```javascript
+/**
+ * Tier 3: detect Remotion project state, prompt for bootstrap, run create-video.
+ *
+ * Only the pure helpers (`detectCwdState`, `buildCreateVideoArgs`) are unit-tested.
+ * The full `run()` function shells out and is exercised manually + via init-flow test.
+ */
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+const { info, success, fail, warn, c, askYesNo, ask } = require("./utils");
+
+const PKG_NAME = require("../package.json").name;
+
+function detectCwdState(cwd) {
+  const pkgPath = path.join(cwd, "package.json");
+  if (!fs.existsSync(pkgPath)) return "no-package-json";
+
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+  } catch {
+    return "no-package-json";
+  }
+
+  const hasRemotion =
+    (pkg.dependencies && pkg.dependencies.remotion) ||
+    (pkg.devDependencies && pkg.devDependencies.remotion);
+
+  return hasRemotion ? "has-remotion" : "non-remotion-package";
+}
+
+function buildCreateVideoArgs(projectName) {
+  return ["create-video@latest", "--yes", "--blank", projectName];
+}
+
+function ensureReelstackDep(projectDir) {
+  const pkg = JSON.parse(fs.readFileSync(path.join(projectDir, "package.json"), "utf8"));
+  const already =
+    (pkg.dependencies && pkg.dependencies[PKG_NAME]) ||
+    (pkg.devDependencies && pkg.devDependencies[PKG_NAME]);
+
+  if (already) {
+    success(`${PKG_NAME} already present.`);
+    return true;
+  }
+
+  info(`Installing ${PKG_NAME}…`);
+  const result = spawnSync("npm", ["install", PKG_NAME], {
+    stdio: "inherit",
+    cwd: projectDir,
+  });
+  if (result.status !== 0) {
+    fail(`npm install ${PKG_NAME} failed.`);
+    return false;
+  }
+  success(`${PKG_NAME} installed.`);
+  return true;
+}
+
+/**
+ * Run Tier 3. Returns { projectDir, isNew, skipped } or exits process on
+ * unrecoverable failure. `skipped: true` when buyer declines bootstrap or
+ * --no-bootstrap was passed.
+ */
+async function run({ noBootstrap = false, projectName = "reelstack-project" } = {}) {
+  const cwd = process.cwd();
+  const state = detectCwdState(cwd);
+
+  if (state === "has-remotion") {
+    info("Remotion project detected in current directory.");
+    if (!ensureReelstackDep(cwd)) process.exit(1);
+    return { projectDir: cwd, isNew: false, skipped: false };
+  }
+
+  if (noBootstrap) {
+    warn("No Remotion project here; --no-bootstrap was passed.");
+    console.log(c.gray("  Re-run `reelstack init` from inside a Remotion project to wire up imports."));
+    return { projectDir: null, isNew: false, skipped: true };
+  }
+
+  if (state === "non-remotion-package") {
+    warn("This folder has a non-Remotion package.json.");
+    info("Bootstrapping Remotion in a subdirectory instead so we don't muddy your project.");
+  }
+
+  console.log("");
+  const yes = await askYesNo(`Scaffold a Remotion project at ./${projectName}/?`);
+  if (!yes) {
+    warn("Skipped Remotion bootstrap.");
+    console.log(c.gray("  Re-run `reelstack init` from inside a Remotion project to wire up imports."));
+    return { projectDir: null, isNew: false, skipped: true };
+  }
+
+  const targetDir = path.join(cwd, projectName);
+  if (fs.existsSync(targetDir)) {
+    fail(`./${projectName}/ already exists. Choose a different name with --name=<dir>, or delete it first.`);
+    process.exit(1);
+  }
+
+  info(`Running: npx ${buildCreateVideoArgs(projectName).join(" ")}`);
+  const result = spawnSync("npx", buildCreateVideoArgs(projectName), {
+    stdio: "inherit",
+    cwd,
+  });
+  if (result.status !== 0) {
+    fail("create-video did not exit cleanly.");
+    process.exit(1);
+  }
+  success("Remotion project scaffolded.");
+
+  if (!ensureReelstackDep(targetDir)) process.exit(1);
+
+  return { projectDir: targetDir, isNew: true, skipped: false };
+}
+
+module.exports = { run, detectCwdState, buildCreateVideoArgs, ensureReelstackDep };
+```
+
+- [ ] **Step 4: Run tests, verify pass**
+
+```bash
+cd /Users/abhishekraj/reelstack && node --test test/bootstrap.test.js
+```
+
+Expected: all 5 tests PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+cd /Users/abhishekraj/reelstack && git add cli/bootstrap.js test/bootstrap.test.js
+git commit -m "ReelStack init — Tier 3: Remotion bootstrap module (cli/bootstrap.js)
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+## Task 5: Tier 4 — Smoke test (cli/smoke.js)
+
+**Files:**
+- Create: `cli/smoke.js`
+- Test: `test/smoke.test.js`
+
+Three checks: scaffold a Demo, run `npx remotion compositions` to confirm it loads, run `ffmpeg -version` to confirm the binary executes. Each step gets its own `success`/`fail` line so the buyer can see exactly which check failed.
+
+- [ ] **Step 1: Write failing tests**
+
+Create `test/smoke.test.js`:
+
+```javascript
+"use strict";
+
+const { test } = require("node:test");
+const assert = require("node:assert/strict");
+
+const smoke = require("../cli/smoke");
+
+test("STEPS lists three checks in order", () => {
+  assert.equal(smoke.STEPS.length, 3);
+  assert.equal(smoke.STEPS[0].name, "scaffold-demo");
+  assert.equal(smoke.STEPS[1].name, "remotion-compositions");
+  assert.equal(smoke.STEPS[2].name, "ffmpeg-version");
+});
+
+test("each STEP has a label and a run function", () => {
+  for (const step of smoke.STEPS) {
+    assert.equal(typeof step.label, "string");
+    assert.equal(typeof step.run, "function");
+  }
+});
+
+test("runAll returns { passed: true } when all steps succeed", async () => {
+  const fakeSpawn = () => ({ status: 0, stdout: "", stderr: "" });
+  const result = await smoke.runAll({
+    projectDir: "/tmp/fake",
+    spawnFn: fakeSpawn,
+    scaffoldFn: async () => {},
+  });
+  assert.equal(result.passed, true);
+  assert.equal(result.failedAt, null);
+});
+
+test("runAll returns { passed: false, failedAt } when a step throws", async () => {
+  const fakeSpawn = () => ({ status: 1, stdout: "", stderr: "boom" });
+  const result = await smoke.runAll({
+    projectDir: "/tmp/fake",
+    spawnFn: fakeSpawn,
+    scaffoldFn: async () => {},
+  });
+  assert.equal(result.passed, false);
+  assert.equal(result.failedAt, "remotion-compositions");
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+```bash
+cd /Users/abhishekraj/reelstack && node --test test/smoke.test.js
+```
+
+Expected: FAIL with "Cannot find module '../cli/smoke'".
+
+- [ ] **Step 3: Implement cli/smoke.js**
+
+Create `cli/smoke.js`:
+
+```javascript
+/**
+ * Tier 4: smoke test. Runs after Tiers 1-3 pass and proves the full stack
+ * actually loads. Three fast, non-destructive checks.
+ *
+ * Steps:
+ *   1. scaffold-demo        — reelstack scaffold --family=glass --preset=graphify --name=Demo
+ *   2. remotion-compositions — npx remotion compositions   (proves Demo registers)
+ *   3. ffmpeg-version       — ffmpeg -version              (proves binary executes)
+ */
+const { spawnSync } = require("node:child_process");
+const { info, success, fail, c } = require("./utils");
+const scaffold = require("./scaffold");
+
+const STEPS = [
+  {
+    name: "scaffold-demo",
+    label: "Scaffolding Demo.tsx",
+    async run({ projectDir, scaffoldFn }) {
+      const fn = scaffoldFn || scaffold.run;
+      await fn(["--family=glass", "--preset=graphify", "--name=Demo"], { cwd: projectDir });
+      return { ok: true };
+    },
+  },
+  {
+    name: "remotion-compositions",
+    label: "Loading Remotion compositions",
+    async run({ projectDir, spawnFn }) {
+      const fn = spawnFn || spawnSync;
+      const result = fn("npx", ["remotion", "compositions"], {
+        cwd: projectDir,
+        stdio: "pipe",
+        encoding: "utf8",
+      });
+      return result.status === 0
+        ? { ok: true }
+        : { ok: false, message: (result.stderr || result.stdout || "unknown error").toString().trim() };
+    },
+  },
+  {
+    name: "ffmpeg-version",
+    label: "Validating ffmpeg",
+    async run({ spawnFn }) {
+      const fn = spawnFn || spawnSync;
+      const result = fn("ffmpeg", ["-version"], { stdio: "pipe", encoding: "utf8" });
+      return result.status === 0
+        ? { ok: true }
+        : { ok: false, message: (result.stderr || result.stdout || "ffmpeg failed").toString().trim() };
+    },
+  },
+];
+
+async function runAll(opts) {
+  for (const step of STEPS) {
+    info(step.label + "…");
+    let outcome;
+    try {
+      outcome = await step.run(opts);
+    } catch (err) {
+      outcome = { ok: false, message: err.message };
+    }
+    if (!outcome.ok) {
+      fail(`Smoke test failed at: ${step.name}`);
+      if (outcome.message) console.log(c.gray("  " + outcome.message));
+      return { passed: false, failedAt: step.name };
+    }
+    success(step.label);
+  }
+  return { passed: true, failedAt: null };
+}
+
+module.exports = { STEPS, runAll };
+```
+
+- [ ] **Step 4: Run tests, verify pass**
+
+```bash
+cd /Users/abhishekraj/reelstack && node --test test/smoke.test.js
+```
+
+Expected: all 4 tests PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+cd /Users/abhishekraj/reelstack && git add cli/smoke.js test/smoke.test.js
+git commit -m "ReelStack init — Tier 4: smoke test module (cli/smoke.js)
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+## Task 6: Wire init.js to compose all four tiers + parse flags
+
+**Files:**
+- Modify: `cli/init.js`
+- Test: `test/init-flow.test.js`
+
+Replace the existing `run()` body to compose Tier 1 → runtime/skill/commands install (preserved unchanged) → Tier 2 → Tier 3 → Tier 4. Parse `--name=<dir>`, `--skip-smoke`, `--no-bootstrap` from `argv`.
+
+- [ ] **Step 1: Write failing tests**
+
+Create `test/init-flow.test.js`:
+
+```javascript
+"use strict";
+
+const { test } = require("node:test");
+const assert = require("node:assert/strict");
+
+const init = require("../cli/init");
+
+test("parseFlags defaults", () => {
+  const flags = init.parseFlags([]);
+  assert.equal(flags.skipSmoke, false);
+  assert.equal(flags.noBootstrap, false);
+  assert.equal(flags.projectName, "reelstack-project");
+});
+
+test("parseFlags --skip-smoke", () => {
+  const flags = init.parseFlags(["--skip-smoke"]);
+  assert.equal(flags.skipSmoke, true);
+});
+
+test("parseFlags --no-bootstrap", () => {
+  const flags = init.parseFlags(["--no-bootstrap"]);
+  assert.equal(flags.noBootstrap, true);
+});
+
+test("parseFlags --name=foo", () => {
+  const flags = init.parseFlags(["--name=foo"]);
+  assert.equal(flags.projectName, "foo");
+});
+
+test("parseFlags accepts combined flags", () => {
+  const flags = init.parseFlags(["--name=bar", "--skip-smoke", "--no-bootstrap"]);
+  assert.equal(flags.projectName, "bar");
+  assert.equal(flags.skipSmoke, true);
+  assert.equal(flags.noBootstrap, true);
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+```bash
+cd /Users/abhishekraj/reelstack && node --test test/init-flow.test.js
+```
+
+Expected: FAIL with "init.parseFlags is not a function".
+
+- [ ] **Step 3: Add `parseFlags()` and refactor `run()` in cli/init.js**
+
+Add near the top of `cli/init.js`, after the constants:
+
+```javascript
+function parseFlags(argv) {
+  const flags = {
+    skipSmoke: false,
+    noBootstrap: false,
+    projectName: "reelstack-project",
+  };
+  for (const arg of argv) {
+    if (arg === "--skip-smoke") flags.skipSmoke = true;
+    else if (arg === "--no-bootstrap") flags.noBootstrap = true;
+    else if (arg.startsWith("--name=")) flags.projectName = arg.slice(7);
+  }
+  return flags;
+}
+```
+
+Replace the entire `run()` function. Final version:
+
+```javascript
+async function run(argv) {
+  const flags = parseFlags(argv || []);
+  banner();
+  info("Welcome. Let's get ReelStack set up.");
+  console.log("");
+
+  // 1. License
+  const licensed = await license.verifyOrPrompt();
+  if (!licensed) {
+    fail("License required. Visit https://devini.io/reelstack to purchase.");
+    process.exit(1);
+  }
+
+  // 2. Tier 1 — Node hard gate (exits on fail)
+  console.log("");
+  info("Checking dependencies…");
+  checkNode();
+
+  // 3. Tier 2 — System binaries (exits on ffmpeg miss + decline)
+  await ensureFfmpeg();
+  await ensureWhisper();
+
+  // 4. Install ~/.reelstack runtime (preserved from original init)
+  console.log("");
+  info(`Installing ReelStack runtime at ${REELSTACK_HOME}…`);
+  ensureDir(REELSTACK_HOME);
+  for (const sub of ["families", "templates", "utils", "docs", "cli", "reference"]) {
+    copyTree(path.join(REELSTACK_PKG, sub), path.join(REELSTACK_HOME, sub));
+  }
+  fs.copyFileSync(
+    path.join(REELSTACK_PKG, "package.json"),
+    path.join(REELSTACK_HOME, "package.json"),
+  );
+  success("Runtime installed.");
+
+  // 5. Install Claude skill + slash commands (preserved from original init)
+  info(`Installing Claude Code skill at ${path.join(CLAUDE_SKILLS_HOME, "reelstack")}…`);
+  ensureDir(CLAUDE_SKILLS_HOME);
+  copyTree(path.join(REELSTACK_PKG, "skill"), path.join(CLAUDE_SKILLS_HOME, "reelstack"));
+  success("Skill installed.");
+
+  info(`Installing slash commands at ${CLAUDE_COMMANDS_HOME}…`);
+  ensureDir(CLAUDE_COMMANDS_HOME);
+  const cmdsSrc = path.join(REELSTACK_PKG, "skill", "commands");
+  const cmdFiles = fs.readdirSync(cmdsSrc);
+  for (const file of cmdFiles) {
+    fs.copyFileSync(path.join(cmdsSrc, file), path.join(CLAUDE_COMMANDS_HOME, file));
+  }
+  success(`${cmdFiles.length} slash commands installed.`);
+
+  // 6. Tier 3 — Remotion project bootstrap
+  console.log("");
+  const tier3 = await bootstrap.run({
+    noBootstrap: flags.noBootstrap,
+    projectName: flags.projectName,
+  });
+
+  // 7. Tier 4 — Smoke test (only if we have a project to test against)
+  if (tier3.skipped) {
+    saveState({ smokeTest: "skipped-no-project" });
+  } else if (flags.skipSmoke) {
+    saveState({ smokeTest: "skipped" });
+    warn("Smoke test skipped (--skip-smoke).");
+  } else {
+    console.log("");
+    info("Running smoke test…");
+    const result = await smoke.runAll({ projectDir: tier3.projectDir });
+    if (!result.passed) {
+      saveState({ smokeTest: "failed", smokeFailedAt: result.failedAt });
+      fail(`ReelStack is NOT ready — smoke test failed at ${result.failedAt}.`);
+      process.exit(1);
+    }
+    saveState({ smokeTest: "passed" });
+  }
+
+  saveState({ lastInitAt: new Date().toISOString() });
+
+  // 8. Success banner
+  console.log("");
+  success("ReelStack is ready.");
+  console.log("");
+  console.log(c.gray("  Next:"));
+  if (tier3.isNew) {
+    console.log(`    ${c.cyan("cd " + flags.projectName)}`);
+  }
+  console.log(`    ${c.cyan("npm run dev")}                              ${c.gray("# open Remotion Studio")}`);
+  console.log(`    ${c.cyan("/reelstack-glass")}                         ${c.gray("# scaffold a Glass Iridescent reel")}`);
+  console.log(`    ${c.cyan("/reelstack-paper")}                         ${c.gray("# … or any of the other 4 family commands")}`);
+  console.log("");
+}
+
+module.exports = { run, parseFlags };
+```
+
+Update imports at the top to add the new modules:
+
+```javascript
+const license = require("./license");
+const scaffold = require("./scaffold");
+const bootstrap = require("./bootstrap");
+const smoke = require("./smoke");
+```
+
+Remove the old smoke-scaffold block (the old `// 7. Smoke scaffold` section at [cli/init.js:160-171](../../../cli/init.js#L160)) — Tier 4 replaces it.
+
+- [ ] **Step 4: Run flag tests, verify pass**
+
+```bash
+cd /Users/abhishekraj/reelstack && node --test test/init-flow.test.js
+```
+
+Expected: all 5 flag-parsing tests PASS.
+
+- [ ] **Step 5: Run full test suite to make sure nothing else broke**
+
+```bash
+cd /Users/abhishekraj/reelstack && node --test test/*.test.js
+```
+
+Expected: all tests PASS (existing license / scaffold / lint / etc + the four new files).
+
+- [ ] **Step 6: Commit**
+
+```bash
+cd /Users/abhishekraj/reelstack && git add cli/init.js test/init-flow.test.js
+git commit -m "ReelStack init — wire all four tiers + flag parsing
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+## Task 7: Make /reelstack-beats fail-fast on declined whisper
+
+**Files:**
+- Modify: `cli/beats.js`
+
+If state.json says `whisperCli: "missing-declined"`, beats should refuse to run with a clear "you declined this during init; install it and re-run init" message instead of falling through to the existing "whisper-cli not found" error (which doesn't tell the buyer their decline is the reason).
+
+- [ ] **Step 1: Add state check to top of `run()` in cli/beats.js**
+
+Read the current top of `run()` ([cli/beats.js around line 50-58](../../../cli/beats.js#L50)) and add after the `which()` checks but BEFORE the existing fail messages:
+
+```javascript
+const { loadState } = require("./utils");
+// … existing requires …
+
+async function run(argv) {
+  // … existing argv parsing …
+
+  const state = loadState();
+  if (state.whisperCli === "missing-declined") {
+    fail("whisper-cli was declined during `reelstack init`.");
+    console.log("  Install it now:");
+    console.log("    brew install whisper-cpp     # macOS");
+    console.log("  Then re-run: reelstack init");
+    process.exit(1);
+  }
+
+  if (!which("ffmpeg")) {
+    fail("ffmpeg not found. Install: brew install ffmpeg");
+    process.exit(1);
+  }
+  // … rest unchanged …
+}
+```
+
+The exact insertion point is after argv parsing, before the existing `which("ffmpeg")` check at [cli/beats.js:52](../../../cli/beats.js#L52). Read the current file before editing to find the right line.
+
+- [ ] **Step 2: Manually verify (without trashing your real state.json)**
+
+```bash
+# Backup current state
+cp ~/.reelstack/state.json ~/.reelstack/state.json.bak 2>/dev/null || true
+
+# Force the declined state
+echo '{"whisperCli":"missing-declined"}' > ~/.reelstack/state.json
+
+# Trigger the new fail-fast
+cd /Users/abhishekraj/reelstack && node cli/index.js beats /tmp/fake.wav 2>&1 | head -5
+```
+
+Expected: prints "whisper-cli was declined during `reelstack init`" and exits 1.
+
+Restore real state:
+
+```bash
+mv ~/.reelstack/state.json.bak ~/.reelstack/state.json 2>/dev/null || rm ~/.reelstack/state.json
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+cd /Users/abhishekraj/reelstack && git add cli/beats.js
+git commit -m "ReelStack beats — fail-fast when whisper was declined during init
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+## Task 8: Manual end-to-end verification
+
+**Files:** none (verification only)
+
+The TDD tests cover the units. Tier 3 + Tier 4 shell out to real `npx` and `ffmpeg`, so they need a manual run-through to confirm the buyer experience matches the spec.
+
+- [ ] **Step 1: Test the "no Remotion project" path (the buyer's first run)**
+
+```bash
+mkdir -p /tmp/reelstack-test-run && cd /tmp/reelstack-test-run
+node /Users/abhishekraj/reelstack/cli/index.js init --name=demo-project
+```
+
+Expected:
+- License prompts (or uses cache)
+- All 3 dep checks pass
+- "No Remotion project in this directory. Scaffold one at ./demo-project/?" prompt → answer Y
+- `create-video` runs, scaffolds Remotion project
+- `npm install @devinilabs/reelstack` runs
+- Smoke test runs all 3 steps and passes
+- Final banner: "ReelStack is ready."
+- `cat ~/.reelstack/state.json` shows `smokeTest: "passed"`
+
+- [ ] **Step 2: Test the "already in Remotion project" path (re-run)**
+
+```bash
+cd /tmp/reelstack-test-run/demo-project
+node /Users/abhishekraj/reelstack/cli/index.js init
+```
+
+Expected:
+- "Remotion project detected in current directory."
+- `@devinilabs/reelstack already present.`
+- Smoke test runs and passes
+- "ReelStack is ready."
+
+- [ ] **Step 3: Test `--no-bootstrap` from a non-Remotion folder**
+
+```bash
+mkdir -p /tmp/reelstack-test-nobootstrap && cd /tmp/reelstack-test-nobootstrap
+node /Users/abhishekraj/reelstack/cli/index.js init --no-bootstrap
+```
+
+Expected:
+- Tiers 1 + 2 pass
+- "No Remotion project here; --no-bootstrap was passed."
+- "Re-run `reelstack init` from inside a Remotion project to wire up imports."
+- Exit 0 (success — buyer chose manual path)
+- `cat ~/.reelstack/state.json` shows `smokeTest: "skipped-no-project"`
+
+- [ ] **Step 4: Test `--skip-smoke` with existing Remotion project**
+
+```bash
+cd /tmp/reelstack-test-run/demo-project
+node /Users/abhishekraj/reelstack/cli/index.js init --skip-smoke
+```
+
+Expected:
+- All tiers run except smoke
+- "Smoke test skipped (--skip-smoke)."
+- "ReelStack is ready."
+- `cat ~/.reelstack/state.json` shows `smokeTest: "skipped"`
+
+- [ ] **Step 5: Cleanup**
+
+```bash
+rm -rf /tmp/reelstack-test-run /tmp/reelstack-test-nobootstrap
+```
+
+- [ ] **Step 6: Bump version + commit**
+
+Edit `package.json`: bump version from `1.1.1-rc.1` to `1.2.0-rc.1` (the readiness gate is the marquee feature of v1.2 per the spec).
+
+```bash
+cd /Users/abhishekraj/reelstack && git add package.json
+git commit -m "ReelStack v1.2.0-rc.1 — init readiness gate
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+## Done
+
+After Task 8: every `/reelstack-*` command works the moment `reelstack init` exits 0, or init exits non-zero with a clear remediation. The "I paid, init said ready, but nothing works" failure mode is gone.