sisyphi 1.1.7 → 1.1.9

package/dist/cli.js

@@ -10,6 +10,7 @@ import {
   shellQuote
 } from "./chunk-6G226ZK7.js";
 import {
+  cycleLogPath,
   daemonLogPath,
   daemonPidPath,
   daemonUpdatingPath,
@@ -20,9 +21,9 @@ import {
 
 // src/cli/index.ts
 import { Command } from "commander";
-import { existsSync as existsSync6, mkdirSync as mkdirSync4, readFileSync as readFileSync4 } from "fs";
-import { dirname as dirname2, join as join6 } from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
+import { existsSync as existsSync8, mkdirSync as mkdirSync5, readFileSync as readFileSync5 } from "fs";
+import { dirname as dirname4, join as join8 } from "path";
+import { fileURLToPath as fileURLToPath4 } from "url";
 
 // src/cli/commands/start.ts
 import { execSync as execSync5 } from "child_process";
@@ -91,8 +92,9 @@ while IFS= read -r name; do
   scwd=$(tmux show-option -t "$name" -v @sisyphus_cwd 2>/dev/null)
   if [ "$scwd" = "$cwd" ]; then
     tmux switch-client -t "$name"
-    # Focus the dashboard window if it exists
-    tmux select-window -t "$name:sisyphus-dashboard" 2>/dev/null
+    # Focus the dashboard window by stored ID (not name)
+    dwid=$(tmux show-option -t "$name" -v @sisyphus_dashboard 2>/dev/null)
+    [ -n "$dwid" ] && tmux select-window -t "$dwid" 2>/dev/null
     exit 0
   fi
 done < <(tmux list-sessions -F '#{session_name}')
@@ -112,7 +114,8 @@ if [ "$pane_count" -le 1 ]; then
       scwd=$(tmux show-option -t "$name" -v @sisyphus_cwd 2>/dev/null)
       if [ "$scwd" = "$cwd" ]; then
         tmux switch-client -t "$name"
-        tmux select-window -t "$name:sisyphus-dashboard" 2>/dev/null
+        dwid=$(tmux show-option -t "$name" -v @sisyphus_dashboard 2>/dev/null)
+        [ -n "$dwid" ] && tmux select-window -t "$dwid" 2>/dev/null
         tmux kill-session -t "$session"
         exit 0
       fi
@@ -486,18 +489,22 @@ function getTmuxSession() {
 // src/cli/commands/dashboard.ts
 import { join as join3 } from "path";
 import { execSync as execSync4 } from "child_process";
-function ensureDashboard(tmuxSession, cwd) {
+function openDashboardWindow(tmuxSession, cwd) {
   try {
-    const windows = execSync4(
-      `tmux list-windows -t ${shellQuote(tmuxSession)} -F "#{window_name}"`,
-      { encoding: "utf-8" }
-    );
-    const isOpen = windows.split("\n").some((name) => name.trim() === "sisyphus-dashboard");
-    if (isOpen) {
-      execSync4(
-        `tmux select-window -t ${shellQuote(tmuxSession)}:sisyphus-dashboard`
-      );
-      return false;
+    const storedId = execSync4(
+      `tmux show-option -t ${shellQuote(tmuxSession)} -v @sisyphus_dashboard`,
+      { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }
+    ).trim();
+    if (storedId) {
+      try {
+        execSync4(
+          `tmux display-message -t ${shellQuote(storedId)} -p "#{window_id}"`,
+          { stdio: "pipe" }
+        );
+        execSync4(`tmux select-window -t ${shellQuote(storedId)}`, { stdio: "pipe" });
+        return false;
+      } catch {
+      }
     }
   } catch {
   }
@@ -506,17 +513,23 @@ function ensureDashboard(tmuxSession, cwd) {
     `tmux new-window -n "sisyphus-dashboard" -c ${shellQuote(cwd)} -P -F "#{window_id}"`,
     { encoding: "utf-8" }
   ).trim();
-  const cmd = `node ${shellQuote(tuiPath)} --cwd ${shellQuote(cwd)}`;
+  const cmd = `node ${shellQuote(tuiPath)} --cwd ${shellQuote(cwd)}; exit`;
   execSync4(
     `tmux send-keys -t ${shellQuote(windowId)} ${shellQuote(cmd)} Enter`
   );
+  execSync4(
+    `tmux set-option -t ${shellQuote(tmuxSession)} @sisyphus_dashboard ${shellQuote(windowId)}`,
+    { stdio: "pipe" }
+  );
   return true;
 }
 function registerDashboard(program2) {
   program2.command("dashboard").description("Launch the TUI dashboard for monitoring and managing sessions").action(async () => {
     assertTmux();
-    const tmuxSession = getTmuxSession();
-    ensureDashboard(tmuxSession, process.cwd());
+    const tuiPath = join3(import.meta.dirname, "tui.js");
+    execSync4(`node ${shellQuote(tuiPath)} --cwd ${shellQuote(process.cwd())}`, {
+      stdio: "inherit"
+    });
   });
 }
 
@@ -550,7 +563,7 @@ function registerStart(program2) {
         }
         try {
           const tmuxSession = getTmuxSession();
-          if (ensureDashboard(tmuxSession, cwd)) {
+          if (openDashboardWindow(tmuxSession, cwd)) {
             console.log(`Dashboard opened in tmux window "sisyphus-dashboard"`);
           }
         } catch {
@@ -644,24 +657,6 @@ function registerSpawn(program2) {
 }
 
 // src/cli/commands/submit.ts
-import { execSync as execSync6 } from "child_process";
-function isInWorktree() {
-  try {
-    const gitDir = execSync6("git rev-parse --git-dir", { encoding: "utf-8" }).trim();
-    const commonDir = execSync6("git rev-parse --git-common-dir", { encoding: "utf-8" }).trim();
-    return gitDir !== commonDir;
-  } catch {
-    return false;
-  }
-}
-function getUncommittedChanges() {
-  try {
-    const status = execSync6("git status --porcelain", { encoding: "utf-8" }).trim();
-    return status || null;
-  } catch {
-    return null;
-  }
-}
 function registerSubmit(program2) {
   program2.command("submit").description("Submit work report and exit (agent only)").option("--report <report>", "Work report (or pipe via stdin)").option("--session <sessionId>", "Session ID (defaults to SISYPHUS_SESSION_ID env var)").action(async (opts) => {
     assertTmux();
@@ -671,17 +666,6 @@ function registerSubmit(program2) {
       console.error("Error: provide --session or set SISYPHUS_SESSION_ID (and SISYPHUS_AGENT_ID) environment variables");
       process.exit(1);
     }
-    if (isInWorktree()) {
-      const changes = getUncommittedChanges();
-      if (changes) {
-        console.error("Error: uncommitted changes in worktree. Commit your changes before submitting.");
-        console.error('\nCommit first:\n  git add -A && git commit -m "description of changes"\n');
-        console.error("Or discard:\n  git checkout -- .\n");
-        console.error("Uncommitted changes:");
-        console.error(changes);
-        process.exit(1);
-      }
-    }
     const report = opts.report ?? await readStdin();
     if (!report) {
       console.error("Error: provide --report or pipe content via stdin");
@@ -766,7 +750,8 @@ function registerContinue(program2) {
 }
 
 // src/cli/commands/status.ts
-import { readFileSync as readFileSync3 } from "fs";
+import { execSync as execSync6 } from "child_process";
+import { existsSync as existsSync4, readFileSync as readFileSync3 } from "fs";
 var COLOR_CODES = {
   green: "\x1B[32m",
   yellow: "\x1B[33m",
@@ -802,12 +787,17 @@ function inferOrchestratorPhase(session) {
     return "starting";
   }
 }
-function formatAgent(agent) {
+function formatAgent(agent, verbose) {
   const status = colorize(agent.status, agent.status);
   const name = `${BOLD}${agent.name}${RESET}`;
   const type = `${DIM}(${agent.agentType})${RESET}`;
   const duration = formatDuration(agent.activeMs);
   let line = `    ${agent.id} ${name} ${type} \u2014 ${status} ${DIM}(${duration})${RESET}`;
+  if (verbose && agent.instruction) {
+    const truncated = agent.instruction.length > 200 ? agent.instruction.slice(0, 200) + "..." : agent.instruction;
+    line += `
+      ${DIM}Instruction: ${truncated}${RESET}`;
+  }
   if (agent.reports.length > 0) {
     for (const r of agent.reports) {
       const label = r.type === "final" ? "Final" : "Update";
@@ -857,7 +847,33 @@ function readRoadmapTodos(cwd, sessionId) {
     return [];
   }
 }
-function printSession(session) {
+function readFullRoadmap(cwd, sessionId) {
+  try {
+    return readFileSync3(roadmapPath(cwd, sessionId), "utf8");
+  } catch {
+    return null;
+  }
+}
+function readCycleLog(cwd, sessionId, cycle) {
+  try {
+    const path = cycleLogPath(cwd, sessionId, cycle);
+    if (!existsSync4(path)) return null;
+    return readFileSync3(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+function capturePaneOutput(paneId, lines = 50) {
+  try {
+    return execSync6(
+      `tmux capture-pane -t "${paneId}" -p -S -${lines}`,
+      { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }
+    ).trimEnd();
+  } catch {
+    return null;
+  }
+}
+function printSession(session, verbose) {
   const status = colorize(session.status, session.status);
   const sessionDuration = formatDuration(session.createdAt, session.completedAt);
   console.log(`
@@ -865,7 +881,7 @@ ${BOLD}Session: ${session.id}${RESET}`);
   console.log(`  Status: ${status}`);
   console.log(`  Task: ${session.task}`);
   if (session.context) {
-    const truncated = session.context.length > 120 ? session.context.slice(0, 120) + "..." : session.context;
+    const truncated = !verbose && session.context.length > 120 ? session.context.slice(0, 120) + "..." : session.context;
     console.log(`  Context: ${truncated}`);
   }
   console.log(`  CWD: ${session.cwd}`);
@@ -886,14 +902,27 @@ ${BOLD}Active agents (${runningAgents.length}):${RESET}`);
       const type = `${DIM}(${agent.agentType})${RESET}`;
       const duration = formatDuration(agent.activeMs);
       console.log(`  ${agent.id}  ${name}  ${type}  running ${duration}`);
+      if (verbose && agent.instruction) {
+        const truncated = agent.instruction.length > 200 ? agent.instruction.slice(0, 200) + "..." : agent.instruction;
+        console.log(`    ${DIM}Instruction: ${truncated}${RESET}`);
+      }
     }
   }
-  const todos = readRoadmapTodos(session.cwd, session.id);
-  if (todos.length > 0) {
-    console.log(`
+  if (verbose) {
+    const roadmap = readFullRoadmap(session.cwd, session.id);
+    if (roadmap) {
+      console.log(`
+${BOLD}Roadmap:${RESET}`);
+      console.log(roadmap);
+    }
+  } else {
+    const todos = readRoadmapTodos(session.cwd, session.id);
+    if (todos.length > 0) {
+      console.log(`
 ${BOLD}Remaining (${todos.length} unchecked):${RESET}`);
-    for (const todo of todos) {
-      console.log(`  - ${todo}`);
+      for (const todo of todos) {
+        console.log(`  - ${todo}`);
+      }
     }
   }
   if (session.orchestratorCycles.length > 0) {
@@ -904,25 +933,68 @@ ${BOLD}Remaining (${todos.length} unchecked):${RESET}`);
       const isLast = i === cycles.length - 1;
       const phase = isLast && session.status === "active" ? inferOrchestratorPhase(session) : void 0;
       console.log(formatCycle(cycles[i], phase));
+      if (verbose) {
+        const log = readCycleLog(session.cwd, session.id, cycles[i].cycle);
+        if (log) {
+          const lines = log.split("\n");
+          const preview = lines.slice(0, 20).join("\n");
+          console.log(`      ${DIM}--- cycle log ---${RESET}`);
+          for (const line of preview.split("\n")) {
+            console.log(`      ${DIM}${line}${RESET}`);
+          }
+          if (lines.length > 20) {
+            console.log(`      ${DIM}... (${lines.length - 20} more lines)${RESET}`);
+          }
+        }
+      }
     }
   }
   if (session.agents.length > 0) {
     console.log(`
   ${BOLD}Agents:${RESET}`);
     for (const agent of session.agents) {
-      console.log(formatAgent(agent));
+      console.log(formatAgent(agent, verbose));
     }
   }
+  if (verbose) {
+    const lastCycle = session.orchestratorCycles[session.orchestratorCycles.length - 1];
+    if (lastCycle && !lastCycle.completedAt && lastCycle.paneId) {
+      const output = capturePaneOutput(lastCycle.paneId);
+      if (output) {
+        console.log(`
+<orchestrator-pane-output lines="50">`);
+        console.log(output);
+        console.log(`</orchestrator-pane-output>`);
+      }
+    }
+    for (const agent of runningAgents) {
+      if (agent.paneId) {
+        const output = capturePaneOutput(agent.paneId, 30);
+        if (output) {
+          console.log(`
+<agent-pane-output agent="${agent.id}" name="${agent.name}" lines="30">`);
+          console.log(output);
+          console.log(`</agent-pane-output>`);
+        }
+      }
+    }
+  }
+  if (verbose && session.completionReport) {
+    console.log(`
+${BOLD}Completion Report:${RESET}`);
+    console.log(session.completionReport);
+  }
 }
 function registerStatus(program2) {
-  program2.command("status").description("Show session status").argument("[session-id]", "Session ID (defaults to SISYPHUS_SESSION_ID env)").action(async (sessionIdArg) => {
+  program2.command("status").description("Show session status").argument("[session-id]", "Session ID (defaults to SISYPHUS_SESSION_ID env)").option("-v, --verbose", "Show detailed output (roadmap, pane output, agent instructions)").action(async (sessionIdArg, opts) => {
     const sessionId = sessionIdArg ?? process.env.SISYPHUS_SESSION_ID;
+    const verbose = opts?.verbose ?? false;
     const request = { type: "status", sessionId };
     const response = await sendRequest(request);
     if (response.ok) {
       const session = response.data?.session;
       if (session) {
-        printSession(session);
+        printSession(session, verbose);
       } else {
         console.log("No session found");
       }
@@ -1193,8 +1265,245 @@ function registerSetupKeybind(program2) {
 }
 
 // src/cli/commands/doctor.ts
+import { execSync as execSync8 } from "child_process";
+import { existsSync as existsSync6, statSync } from "fs";
+
+// src/cli/onboard.ts
 import { execSync as execSync7 } from "child_process";
-import { existsSync as existsSync4, statSync } from "fs";
+import { existsSync as existsSync5, mkdirSync as mkdirSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
+import { homedir as homedir3 } from "os";
+import { dirname as dirname2, join as join5 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+function detectTerminal() {
+  const termProgram = process.env["TERM_PROGRAM"] || "";
+  const isIterm = termProgram === "iTerm.app" || !!process.env["ITERM_SESSION_ID"];
+  return { name: termProgram || "unknown", isIterm };
+}
+function isTmuxAvailable() {
+  try {
+    execSync7("which tmux", { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isBrewAvailable() {
+  try {
+    execSync7("which brew", { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function tryAutoInstallTmux() {
+  if (!isBrewAvailable()) return false;
+  try {
+    console.log("  Installing tmux via Homebrew...");
+    execSync7("brew install tmux", { stdio: "inherit" });
+    return isTmuxAvailable();
+  } catch {
+    return false;
+  }
+}
+function checkItermOptionKey() {
+  if (process.platform !== "darwin") {
+    return { checked: false, allCorrect: true, incorrectProfiles: [] };
+  }
+  const plistPath2 = join5(homedir3(), "Library", "Preferences", "com.googlecode.iterm2.plist");
+  if (!existsSync5(plistPath2)) {
+    return { checked: false, allCorrect: false, incorrectProfiles: [] };
+  }
+  try {
+    const json = execSync7(
+      `plutil -extract "New Bookmarks" json -o - "${plistPath2}"`,
+      { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }
+    );
+    const profiles = JSON.parse(json);
+    const currentProfile = process.env["ITERM_PROFILE"];
+    const incorrect = [];
+    for (const profile of profiles) {
+      const name = profile["Name"] || "Unnamed";
+      if (currentProfile && name !== currentProfile) continue;
+      if (profile["Right Option Key Sends"] !== 2) {
+        incorrect.push(name);
+      }
+    }
+    return { checked: true, allCorrect: incorrect.length === 0, incorrectProfiles: incorrect };
+  } catch {
+    return { checked: false, allCorrect: false, incorrectProfiles: [] };
+  }
+}
+function hasExistingTmuxConf() {
+  return existsSync5(join5(homedir3(), ".tmux.conf")) || existsSync5(join5(homedir3(), ".config", "tmux", "tmux.conf"));
+}
+var TMUX_DEFAULTS = `# Sensible tmux defaults (installed by sisyphus)
+# Customize freely \u2014 sisyphus won't overwrite this file.
+
+# Enable mouse (click panes, scroll, resize)
+set -g mouse on
+
+# Scrollback history
+set -g history-limit 50000
+
+# 256 color + true color support
+set -g default-terminal "tmux-256color"
+set -as terminal-overrides ",*:Tc"
+
+# Low escape delay (keeps Option/Meta keybindings responsive)
+set -sg escape-time 10
+
+# Window numbering from 1
+set -g base-index 1
+setw -g pane-base-index 1
+
+# Renumber windows when one closes
+set -g renumber-windows on
+
+# Clipboard integration
+set -g set-clipboard on
+
+# Focus events (for editors)
+set -g focus-events on
+
+# --- Pane navigation (no prefix needed) ---
+bind -n C-h select-pane -L
+bind -n C-j select-pane -D
+bind -n C-k select-pane -U
+bind -n C-l select-pane -R
+
+# --- Window navigation (no prefix needed) ---
+bind -n C-n next-window
+bind -n C-p previous-window
+
+# --- New window / splits preserve cwd ---
+bind c new-window -c "#{pane_current_path}"
+bind '"' split-window -v -c "#{pane_current_path}"
+bind % split-window -h -c "#{pane_current_path}"
+
+# --- Kill pane + rebalance ---
+bind x kill-pane \\; select-layout even-horizontal
+
+# --- Auto-rebalance on pane close ---
+set-hook -g after-kill-pane "select-layout even-horizontal"
+set-hook -g pane-exited "select-layout even-horizontal"
+
+# --- Manual re-tile ---
+bind = select-layout even-horizontal
+
+# --- Scroll (no prefix needed) ---
+bind -n C-u copy-mode \\; send-keys -X halfpage-up
+bind -n C-d copy-mode \\; send-keys -X halfpage-down
+
+# --- Vi copy mode ---
+setw -g mode-keys vi
+bind -T copy-mode-vi v send-keys -X begin-selection
+bind -T copy-mode-vi y send-keys -X copy-selection-and-cancel
+`;
+function writeTmuxDefaults() {
+  const confPath = join5(homedir3(), ".tmux.conf");
+  writeFileSync3(confPath, TMUX_DEFAULTS, "utf8");
+}
+function isNvimAvailable() {
+  try {
+    execSync7("which nvim", { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function getNvimVersion() {
+  try {
+    return execSync7("nvim --version", { encoding: "utf-8", stdio: "pipe" }).split("\n")[0]?.replace("NVIM ", "") || "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+function hasLazyVimConfig() {
+  return existsSync5(join5(homedir3(), ".config", "nvim", "lazy-lock.json"));
+}
+function tryAutoInstallNvim() {
+  if (isNvimAvailable()) {
+    return { installed: true, autoInstalled: false, version: getNvimVersion(), lazyVimInstalled: hasLazyVimConfig() };
+  }
+  if (!isBrewAvailable()) {
+    return { installed: false, autoInstalled: false, version: "", lazyVimInstalled: false };
+  }
+  try {
+    console.log("  Installing neovim via Homebrew...");
+    execSync7("brew install neovim", { stdio: "inherit" });
+  } catch {
+    return { installed: false, autoInstalled: false, version: "", lazyVimInstalled: false };
+  }
+  if (!isNvimAvailable()) {
+    return { installed: false, autoInstalled: false, version: "", lazyVimInstalled: false };
+  }
+  const nvimConfigDir = join5(homedir3(), ".config", "nvim");
+  let lazyVimInstalled = false;
+  if (!existsSync5(nvimConfigDir)) {
+    try {
+      console.log("  Cloning LazyVim starter config...");
+      execSync7(`git clone https://github.com/LazyVim/starter ${nvimConfigDir}`, { stdio: "inherit" });
+      const gitDir = join5(nvimConfigDir, ".git");
+      if (existsSync5(gitDir)) {
+        execSync7(`rm -rf "${gitDir}"`, { stdio: "pipe" });
+      }
+      lazyVimInstalled = true;
+    } catch {
+    }
+  }
+  return { installed: true, autoInstalled: true, version: getNvimVersion(), lazyVimInstalled };
+}
+function beginCommandPath() {
+  return join5(homedir3(), ".claude", "commands", "sisyphus", "begin.md");
+}
+function bundledBeginCommandPath() {
+  const distDir = dirname2(fileURLToPath2(import.meta.url));
+  return join5(distDir, "templates", "begin.md");
+}
+function isBeginCommandInstalled() {
+  return existsSync5(beginCommandPath());
+}
+function installBeginCommand() {
+  const dest = beginCommandPath();
+  if (existsSync5(dest)) {
+    return { installed: true, autoInstalled: false, path: dest };
+  }
+  const src = bundledBeginCommandPath();
+  if (!existsSync5(src)) {
+    return { installed: false, autoInstalled: false, path: dest };
+  }
+  try {
+    mkdirSync3(dirname2(dest), { recursive: true });
+    writeFileSync3(dest, readFileSync4(src, "utf-8"), "utf8");
+    return { installed: true, autoInstalled: true, path: dest };
+  } catch {
+    return { installed: false, autoInstalled: false, path: dest };
+  }
+}
+function runOnboarding() {
+  const terminal = detectTerminal();
+  const tmuxAlreadyInstalled = isTmuxAvailable();
+  let tmuxInstalled = tmuxAlreadyInstalled;
+  let tmuxAutoInstalled = false;
+  let tmuxDefaultsWritten = false;
+  if (!tmuxAlreadyInstalled && process.platform === "darwin") {
+    tmuxAutoInstalled = tryAutoInstallTmux();
+    tmuxInstalled = tmuxAutoInstalled;
+    if (tmuxAutoInstalled && !hasExistingTmuxConf()) {
+      writeTmuxDefaults();
+      tmuxDefaultsWritten = true;
+    }
+  }
+  let itermOptionKey = { checked: false, allCorrect: true, incorrectProfiles: [] };
+  if (terminal.isIterm) {
+    itermOptionKey = checkItermOptionKey();
+  }
+  const nvim = tryAutoInstallNvim();
+  const command = installBeginCommand();
+  return { tmuxInstalled, tmuxAutoInstalled, terminal, itermOptionKey, tmuxDefaultsWritten, nvim, command };
+}
+
+// src/cli/commands/doctor.ts
 function checkNodeVersion() {
   const major = parseInt(process.versions.node.split(".")[0], 10);
   if (major < 22) {
@@ -1204,7 +1513,7 @@ function checkNodeVersion() {
 }
 function checkClaudeCli() {
   try {
-    execSync7("which claude", { stdio: "pipe" });
+    execSync8("which claude", { stdio: "pipe" });
     return { name: "Claude CLI", status: "ok", detail: "Found on PATH" };
   } catch {
     return {
@@ -1217,7 +1526,7 @@ function checkClaudeCli() {
 }
 function checkGit() {
   try {
-    const version = execSync7("git --version", { encoding: "utf-8", stdio: "pipe" }).trim();
+    const version = execSync8("git --version", { encoding: "utf-8", stdio: "pipe" }).trim();
     return { name: "git", status: "ok", detail: version };
   } catch {
     return { name: "git", status: "fail", detail: "Not found on PATH", fix: "Install git: https://git-scm.com/downloads" };
@@ -1225,7 +1534,7 @@ function checkGit() {
 }
 function checkTmuxVersion() {
   try {
-    const version = execSync7("tmux -V", { encoding: "utf-8", stdio: "pipe" }).trim();
+    const version = execSync8("tmux -V", { encoding: "utf-8", stdio: "pipe" }).trim();
     const match = version.match(/(\d+\.\d+)/);
     if (!match) return { name: "tmux version", status: "warn", detail: `Could not parse version: ${version}` };
     const ver = parseFloat(match[1]);
@@ -1251,7 +1560,7 @@ function checkDaemonInstalled() {
     };
   }
   const pid = daemonPidPath();
-  if (existsSync4(pid)) {
+  if (existsSync6(pid)) {
     return { name: "Daemon setup", status: "ok", detail: `PID file found at ${pid}` };
   }
   return {
@@ -1263,7 +1572,7 @@ function checkDaemonInstalled() {
 }
 function checkDaemonRunning() {
   const pid = daemonPidPath();
-  if (!existsSync4(pid)) {
+  if (!existsSync6(pid)) {
     const fix = process.platform === "darwin" ? "launchctl load -w ~/Library/LaunchAgents/com.sisyphus.daemon.plist" : "sisyphusd & \u2014 or check if the process is running";
     return {
       name: "Daemon process",
@@ -1274,7 +1583,7 @@ function checkDaemonRunning() {
   }
   try {
     const sock = socketPath();
-    execSync7(`test -S "${sock}"`, { stdio: "pipe" });
+    execSync8(`test -S "${sock}"`, { stdio: "pipe" });
     return { name: "Daemon process", status: "ok", detail: `Socket at ${sock}` };
   } catch {
     return {
@@ -1287,13 +1596,13 @@ function checkDaemonRunning() {
 }
 function checkTmux() {
   try {
-    execSync7("which tmux", { stdio: "pipe" });
+    execSync8("which tmux", { stdio: "pipe" });
   } catch {
     const installHint = process.platform === "darwin" ? "brew install tmux" : "apt install tmux (Debian/Ubuntu) or your package manager";
     return { name: "tmux", status: "fail", detail: "Not found on PATH", fix: installHint };
   }
   try {
-    execSync7("tmux list-sessions", { stdio: "pipe" });
+    execSync8("tmux list-sessions", { stdio: "pipe" });
     return { name: "tmux", status: "ok", detail: "Running" };
   } catch {
     return { name: "tmux", status: "warn", detail: "Installed but no server running" };
@@ -1301,7 +1610,7 @@ function checkTmux() {
 }
 function checkCycleScript() {
   const path = cycleScriptPath();
-  if (!existsSync4(path)) {
+  if (!existsSync6(path)) {
     return {
       name: "Cycle script",
       status: "fail",
@@ -1326,7 +1635,7 @@ function checkCycleScript() {
 function checkTmuxKeybind() {
   const existing = getExistingBinding(DEFAULT_KEY);
   if (existing === null) {
-    if (existsSync4(sisyphusTmuxConfPath())) {
+    if (existsSync6(sisyphusTmuxConfPath())) {
       return {
         name: `Tmux keybind (${DEFAULT_KEY})`,
         status: "warn",
@@ -1352,25 +1661,85 @@ function checkTmuxKeybind() {
 }
 function checkGlobalDir() {
   const dir = globalDir();
-  if (existsSync4(dir)) {
+  if (existsSync6(dir)) {
     return { name: "Data directory", status: "ok", detail: dir };
   }
   return { name: "Data directory", status: "warn", detail: `${dir} does not exist (created on first use)` };
 }
+function checkTerminal() {
+  if (process.platform !== "darwin") {
+    return { name: "Terminal", status: "ok", detail: "Non-macOS (skipped)" };
+  }
+  const terminal = detectTerminal();
+  if (terminal.isIterm) {
+    return { name: "Terminal", status: "ok", detail: terminal.name };
+  }
+  return {
+    name: "Terminal",
+    status: "warn",
+    detail: terminal.name ? terminal.name : "unknown",
+    fix: "iTerm2 recommended for best experience: https://iterm2.com"
+  };
+}
+function checkItermRightOptionKey() {
+  if (process.platform !== "darwin") return null;
+  const terminal = detectTerminal();
+  if (!terminal.isIterm) return null;
+  const result = checkItermOptionKey();
+  if (!result.checked) return null;
+  if (result.allCorrect) {
+    return { name: "Right Option Key", status: "ok", detail: "Esc+" };
+  }
+  const profiles = result.incorrectProfiles.map((p) => `"${p}"`).join(", ");
+  return {
+    name: "Right Option Key",
+    status: "warn",
+    detail: `Not Esc+ for ${profiles}`,
+    fix: "iTerm2 \u2192 Settings \u2192 Profiles \u2192 Keys \u2192 Right Option Key \u2192 Esc+"
+  };
+}
+function checkBeginCommand() {
+  if (isBeginCommandInstalled()) {
+    return { name: "/begin command", status: "ok", detail: "Installed" };
+  }
+  return {
+    name: "/begin command",
+    status: "warn",
+    detail: "Not installed",
+    fix: "sisyphus setup"
+  };
+}
+function checkNvim() {
+  if (!isNvimAvailable()) {
+    const fix = process.platform === "darwin" ? "brew install neovim" : "Install neovim from https://neovim.io";
+    return { name: "nvim", status: "warn", detail: "Not installed", fix };
+  }
+  try {
+    const version = execSync8("nvim --version", { encoding: "utf-8", stdio: "pipe" }).split("\n")[0]?.replace("NVIM ", "");
+    return { name: "nvim", status: "ok", detail: version ?? "installed" };
+  } catch {
+    return { name: "nvim", status: "ok", detail: "installed" };
+  }
+}
 var SYMBOLS = { ok: "\u2713", warn: "!", fail: "\u2717" };
 function registerDoctor(program2) {
   program2.command("doctor").description("Check sisyphus installation health").action(async () => {
+    const itermCheck = checkItermRightOptionKey();
     const checks = [
       checkNodeVersion(),
       checkClaudeCli(),
       checkGit(),
       checkTmux(),
       checkTmuxVersion(),
+      checkTerminal(),
+      ...itermCheck ? [itermCheck] : [],
       checkGlobalDir(),
       checkDaemonInstalled(),
       checkDaemonRunning(),
       checkCycleScript(),
-      checkTmuxKeybind()
+      checkTmuxKeybind(),
+      checkBeginCommand(),
+      checkNvim()
     ];
     let hasIssues = false;
     for (const c of checks) {
@@ -1400,135 +1769,959 @@ function registerCompanionContext(program2) {
 }
 
 // src/cli/commands/getting-started.ts
-function registerGettingStarted(program2) {
-  program2.command("getting-started").description("Show a complete guide to using sisyphus effectively").action(() => {
-    const hasTmux = isTmuxInstalled();
-    const inTmux = !!process.env["TMUX"];
-    const lines = [
-      "",
-      "  \u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557",
-      "  \u2551        Getting Started with Sisyphus     \u2551",
-      "  \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D",
-      "",
-      "  Sisyphus is a multi-agent orchestration daemon for Claude Code.",
-      "  It breaks large tasks into subtasks, spawns parallel Claude agents,",
-      "  and coordinates their work across multiple cycles \u2014 autonomously.",
-      "",
-      "  \u2500\u2500\u2500 Tmux \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500",
-      ""
-    ];
-    if (!hasTmux) {
-      lines.push(
-        "  \u26A0  tmux is not installed. Sisyphus requires tmux.",
-        "     Install it:  brew install tmux  (macOS)",
-        "                  apt install tmux   (Linux)",
-        ""
-      );
-    } else if (!inTmux) {
-      lines.push(
-        "  \u26A0  You are not inside a tmux session.",
-        "     Sisyphus spawns agent panes inside tmux, so you should",
-        "     start a tmux session before running sisyphus:",
-        "",
-        "       tmux new-session",
-        ""
-      );
+import { execSync as execSync9 } from "child_process";
+import { dirname as dirname3, join as join6 } from "path";
+import { fileURLToPath as fileURLToPath3 } from "url";
+function templatePath(name) {
+  return join6(dirname3(fileURLToPath3(import.meta.url)), "templates", name);
+}
+function isClaudeCode() {
+  return !!process.env["CLAUDECODE"];
+}
+function printNonClaudeMessage() {
+  console.log(`
+  \u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557
+  \u2551   sisyphus getting-started \u2014 Interactive Tutorial \u2551
+  \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D
+
+  This command provides an interactive tutorial best experienced
+  inside Claude Code. Claude will walk you through setup step by step.
+
+  To start:
+    1. Open Claude Code:  claude
+    2. Run:               sisyphus getting-started
+
+  If you just want the quick reference, run:
+    sisyphus --help
+    sisyphus doctor
+`);
+}
+function printStep0() {
+  const tmuxInstalled = isTmuxInstalled();
+  const inTmux = !!process.env["TMUX"];
+  let tmuxSession = null;
+  if (process.env["TMUX"]) {
+    const segments = process.env["TMUX"].split(",");
+    const pathPart = segments[0];
+    if (pathPart) {
+      const parts = pathPart.split("/");
+      tmuxSession = parts[parts.length - 1] || null;
+    }
+  }
+  console.log(`
+<claude-instructions>
+# Sisyphus Getting Started \u2014 Step 0: Entry & Tmux Gate
+
+## Environment Data
+- tmuxInstalled: ${tmuxInstalled}
+- inTmux: ${inTmux}
+- tmuxSession: ${tmuxSession ?? "none"}
+
+## Tutorial Overview
+
+This tutorial has 6 steps. Share this overview so the user knows what's coming and can skip ahead:
+
+| Step | Topic | Command |
+|------|-------|---------|
+| 0 | Entry & tmux gate (you are here) | \`sisyphus getting-started\` |
+| 1 | Tmux basics \u2014 sessions, panes, navigation | \`--tutorial 1\` |
+| 2 | Nvim basics \u2014 open, save, quit (optional) | \`--tutorial 2\` |
+| 3 | Sisyphus concepts \u2014 session model & keybinds | \`--tutorial 3\` |
+| 4 | Live demo \u2014 launch and observe a real session | \`--tutorial 4\` |
+| 5 | What's next \u2014 real usage guidance & suggestions | \`--tutorial 5\` |
+
+Tell the user they can skip to any step with \`sisyphus getting-started --tutorial <N>\`.
+
+## Instructions for Claude
+
+You are guiding a user through the Sisyphus interactive tutorial.
+
+### First: Ask if they want the tutorial
+
+Ask the user if they'd like the interactive walkthrough. If they decline, give this quick summary and stop:
+
+> Sisyphus is a multi-agent orchestrator for Claude Code. Start a session with \`sisyphus start "task"\`,
+> monitor with \`sisyphus dashboard\`, and check health with \`sisyphus doctor\`.
+
+### If they want the tutorial:
+
+**Case 1: tmux is NOT installed (tmuxInstalled: false)**
+- Explain what tmux is in 2-3 sentences: "tmux is a terminal multiplexer \u2014 it lets you split your terminal into multiple panes and keep sessions running in the background. Sisyphus uses it to give each agent its own workspace."
+- Show this ASCII diagram:
+
+\`\`\`
+  Regular terminal:          With tmux:
+  \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510          \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+  \u2502              \u2502          \u2502 Agent\u2502 Agent\u2502
+  \u2502   one view   \u2502          \u2502  001 \u2502  002 \u2502
+  \u2502              \u2502          \u251C\u2500\u2500\u2500\u2500\u2500\u2500\u253C\u2500\u2500\u2500\u2500\u2500\u2500\u2524
+  \u2502              \u2502          \u2502 Agent\u2502 Orch \u2502
+  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518          \u2502  003 \u2502      \u2502
+                            \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+\`\`\`
+
+- Tell them to install tmux:
+  - macOS: \`brew install tmux\`
+  - Linux: \`apt install tmux\` or their package manager
+- After install, re-run: \`sisyphus getting-started --tutorial 0\` to verify
+
+**Case 2: tmux installed but NOT in a tmux session (inTmux: false)**
+- Tell the user they need to be inside a tmux session for the tutorial
+- Have them run: \`tmux new-session\`
+- Then resume the conversation with Claude in the new tmux session: \`claude\`
+- Then re-run: \`sisyphus getting-started --tutorial 0\` to verify
+
+**Case 3: In tmux (inTmux: true)**
+- Tell the user they're all set \u2014 tmux is running
+- Proceed by running: \`sisyphus getting-started --tutorial 1\`
+</claude-instructions>
+`);
+}
+function printStep1() {
+  console.log(`
+<claude-instructions>
+# Sisyphus Getting Started \u2014 Step 1: Tmux Basics
+
+## Instructions for Claude
+
+Teach the user tmux fundamentals. Be conversational and encouraging.
+
+### 1. Explain the concepts with diagrams
+
+**Sessions, Windows, and Panes:**
+
+\`\`\`
+tmux session "work"
+\u251C\u2500\u2500 window 1: "code"
+\u2502   \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+\u2502   \u2502  pane 1  \u2502  pane 2  \u2502
+\u2502   \u2502  (editor)\u2502  (tests) \u2502
+\u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+\u2514\u2500\u2500 window 2: "servers"
+    \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+    \u2502       pane 1         \u2502
+    \u2502    (dev server)      \u2502
+    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+\`\`\`
+
+- **Session**: A collection of windows. Persists even if you close the terminal.
+- **Window**: Like a tab. Each window fills the screen.
+- **Pane**: A split within a window. Sisyphus puts each agent in its own pane.
+
+### 2. Hands-on: Create a test split
+
+Run this command for the user:
+\`\`\`
+tmux split-window -h
+\`\`\`
+
+Tell them: "I just split your terminal. You should see two panes side by side."
+
+Explain navigation:
+- \`Ctrl+l\`: move to the right pane
+- \`Ctrl+h\`: move to the left pane
+- \`Ctrl+j\`: move to the pane below
+- \`Ctrl+k\`: move to the pane above
+- No prefix key needed \u2014 just hold Ctrl and press the direction letter
+- For windows: \`Ctrl+n\` next window, \`Ctrl+p\` previous window
+
+Ask them to try navigating between panes.
+
+### 3. Clean up the test pane
+
+Once they confirm they can navigate, close the extra pane:
+\`\`\`
+tmux kill-pane -t {the other pane}
+\`\`\`
+
+Or tell them they can type \`exit\` in the extra pane to close it.
+
+### 4. Teach essential commands
+
+- **Detach**: \`Ctrl-b d\` \u2014 leaves tmux running in background, returns to normal terminal
+- **Reattach**: \`tmux attach\` (or \`tmux a\`) \u2014 reconnects to the running session
+- **Scroll up/down**: \`Ctrl+u\` / \`Ctrl+d\` \u2014 scroll half-page up/down (no prefix needed). Press \`q\` to exit scroll mode.
+- **New window**: \`Ctrl-b n\` \u2014 opens a new window in the current directory
+- **Kill pane**: \`Ctrl-b x\` \u2014 closes the current pane and rebalances layout
+- **Re-tile**: \`Ctrl-b =\` \u2014 rebalance all panes to equal widths
+
+### 5. Verification
+
+Ask the user to confirm: "Can you navigate between panes with Ctrl+h and Ctrl+l?"
+
+Once confirmed, proceed:
+\`\`\`
+sisyphus getting-started --tutorial 2
+\`\`\`
+</claude-instructions>
+`);
+}
+function printStep2() {
+  const nvimInstalled = isNvimAvailable();
+  console.log(`
+<claude-instructions>
+# Sisyphus Getting Started \u2014 Step 2: Nvim Basics
+
+## Environment Data
+- nvimInstalled: ${nvimInstalled}
+
+## Instructions for Claude
+
+This step is OPTIONAL. Nvim is useful for reviewing and editing files when you jump into agent panes, but not required.
+
+Note: The sisyphus dashboard has keys that auto-open files in nvim \u2014 users don't need to know how to open files from the command line. Focus on what they'll need once they're INSIDE nvim.
+
+### If nvim is NOT installed (nvimInstalled: false)
+
+Ask the user: "Neovim is handy for reviewing and editing files in tmux panes. Want me to install it, or skip this step?"
+
+- **Install**: Run \`brew install neovim\` (macOS) or suggest their package manager
+- **Skip**: That's fine \u2014 they can use \`cat\`, \`less\`, or any editor they prefer. Proceed to step 3.
+
+### If nvim IS installed (nvimInstalled: true)
+
+Briefly explain the key concept \u2014 nvim has two modes:
+
+- **Normal mode** (default): Keys are commands, not text. This is where you navigate.
+- **Insert mode**: Press \`i\` to enter. Now you type normally. \`Esc\` goes back to normal.
+
+Then tell the user: "I'm going to open an interactive tutorial file in a pane to your right. It walks you through everything \u2014 navigation, editing, saving. Follow the instructions inside the file."
+
+Open the bundled tutorial file in a split pane:
+\`\`\`
+cp ${templatePath("nvim-tutorial.txt")} /tmp/sisyphus-nvim-tutorial.txt
+tmux split-window -h "nvim /tmp/sisyphus-nvim-tutorial.txt"
+\`\`\`
+
+Tell them to click on the right pane (or \`Ctrl+l\`) and follow the instructions in the file. When they \`:wq\` or \`ZZ\`, the pane closes and they're back in Claude.
+
+Tell them: "When you jump into an agent's pane and the dashboard opens a file, you'll land in normal mode. Now you know how to look around, make edits, and get out."
+
+### Verification
+
+Ask if they were able to edit and save the file (or if they skipped).
+
+Proceed:
+\`\`\`
+sisyphus getting-started --tutorial 3
+\`\`\`
+</claude-instructions>
+`);
+}
+function printStep3() {
+  let rightOptionKeyStatus = "unknown";
+  const terminal = detectTerminal();
+  if (!terminal.isIterm) {
+    rightOptionKeyStatus = "not-iterm";
+  } else {
+    const result = checkItermOptionKey();
+    if (!result.checked) {
+      rightOptionKeyStatus = "could-not-check";
+    } else if (result.allCorrect) {
+      rightOptionKeyStatus = "ok";
     } else {
-      lines.push(
-        "  \u2713  You are inside tmux. Good to go.",
-        ""
-      );
+      rightOptionKeyStatus = `incorrect:${result.incorrectProfiles.join(",")}`;
     }
-    lines.push(
-      "  \u2500\u2500\u2500 What Makes a Good Sisyphus Task \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500",
-      "",
-      "  Sisyphus is built for BIG tasks \u2014 the kind that would take",
-      "  multiple cycles of orchestration and parallel agent work.",
-      "  If you could do it with a single Claude Code session in plan",
-      "  mode, it's too small for sisyphus.",
-      "",
-      "  Good tasks:",
-      '    \u2022 "Implement this feature" @path/to/requirements.md',
-      '    \u2022 "Do a deep dive on all SEO/AEO optimizations and',
-      '       systematically apply them across the site"',
-      "    \u2022 Large-scale refactors spanning dozens of files",
-      "    \u2022 Full feature builds from written requirements",
-      "",
-      "  Too small for sisyphus:",
-      '    \u2022 "Add these 3 UI components to the page"',
-      '    \u2022 "Fix this bug in auth.ts"',
-      "    \u2022 Anything a single Claude session handles comfortably",
-      "",
-      "  Tasks don't need to be hyper-specific \u2014 broad but meaningful",
-      "  tasks work great because the orchestrator will plan the approach.",
-      "  What matters is SCALE, not specificity.",
-      "",
-      "  For best results, write requirements and reference them directly:",
-      "",
-      '    sisyphus start "Implement this @path/to/requirements.md"',
-      "",
-      "  \u2500\u2500\u2500 How It Works \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500",
-      "",
-      '  1. You run:  sisyphus start "task description"',
-      "  2. An orchestrator Claude reviews the task and creates a roadmap",
-      "  3. It spawns agent Claude instances in parallel tmux panes",
-      "  4. Agents work independently, then submit reports when done",
-      "  5. The orchestrator respawns with fresh context, reviews progress,",
-      "     and kicks off the next cycle of work",
-      "  6. This repeats until the orchestrator marks the task complete",
-      "",
-      "  The orchestrator is stateless \u2014 it gets killed after each cycle",
-      "  and respawned fresh with the full session state. This means it",
-      "  never runs out of context, no matter how many cycles a task takes.",
-      "",
-      "  \u2500\u2500\u2500 Monitoring (Important!) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500",
-      "",
-      "  Sisyphus sessions should be actively monitored. Agents can get",
-      "  stuck waiting for input, fail to submit reports, or take the",
-      "  roadmap in a direction you don't want. The dashboard is your",
-      "  primary tool for staying on top of things:",
-      "",
-      "    sisyphus dashboard",
-      "",
-      "  Key dashboard actions:",
-      "    m  \u2014 Message the orchestrator to steer direction",
-      "    w  \u2014 Jump directly into the sisyphus tmux session",
-      "         to see exactly what agents are doing",
-      "",
-      "  Use `m` to course-correct from the dashboard, and `w` when you",
-      "  need the most granular view of agent activity.",
-      "",
-      "  \u2500\u2500\u2500 Commands \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500",
-      "",
-      "  Start & monitor:",
-      '    sisyphus start "task"               Start a session',
-      '    sisyphus start "task @requirements.md" Start referencing requirements',
-      "    sisyphus status [id]                Show session status",
-      "    sisyphus list                       List all sessions",
-      "    sisyphus dashboard                  Open TUI dashboard",
-      "",
-      "  Control:",
-      '    sisyphus resume <id> "instructions" Resume with new direction',
-      "    sisyphus kill <id>                  Stop a session",
-      "",
-      "  Health:",
-      "    sisyphus doctor                     Check installation health",
-      "    tail -f ~/.sisyphus/daemon.log      Watch daemon logs",
-      "",
-      "  \u2500\u2500\u2500 Next Steps \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500",
-      "",
-      "  1. Run `sisyphus doctor` to check your setup",
-      "  2. Start a tmux session: `tmux new-session`",
-      '  3. Try it: `sisyphus start "your task description"`',
-      ""
-    );
-    console.log(lines.join("\n"));
+  }
+  console.log(`
+<claude-instructions>
+# Sisyphus Getting Started \u2014 Step 3: Sisyphus Concepts & Keybinds
+
+## Environment Data
+- rightOptionKeyStatus: ${rightOptionKeyStatus}
+
+## Instructions for Claude
+
+### 1. CRITICAL FIRST: Right Option Key Setup
+
+**This must be done before anything else.** Sisyphus keybinds use the Option key as "Meta". By default, macOS terminals send special characters when you press Option (e.g., Option+s types \`\xDF\`). We need the RIGHT Option key to send escape sequences instead.
+
+**Check the environment data above:**
+
+- **rightOptionKeyStatus: ok** \u2014 They're all set, briefly confirm and move on.
+
+- **rightOptionKeyStatus: incorrect:ProfileName** \u2014 Walk them through the fix:
+
+  > Your Right Option key isn't configured correctly yet. Here's how to fix it:
+  >
+  > 1. Open **iTerm2 Settings** (Cmd+,)
+  > 2. Go to **Profiles** \u2192 select your profile (shown above)
+  > 3. Click the **Keys** tab
+  > 4. At the bottom, find **Right Option Key**
+  > 5. Change it from **Normal** to **Esc+**
+  >
+  > \`\`\`
+  >   \u250C\u2500 iTerm2 Settings \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+  >   \u2502  Profiles > Keys                            \u2502
+  >   \u2502                                             \u2502
+  >   \u2502  Right Option Key:                          \u2502
+  >   \u2502    \u25CB Normal  (sends special chars like \xDF)   \u2502
+  >   \u2502    \u25CF Esc+    (sends escape sequences) \u2190 \u2713   \u2502
+  >   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+  >  \`\`\`
+  >
+  > **Why right and not left?** You'll still want the left Option key for
+  > typing special characters (accents, symbols). The right Option key
+  > becomes your "Meta" key for tmux/sisyphus keybinds.
+
+  After they change it, have them verify by re-running \`sisyphus doctor\` \u2014 look for "Right Option Key: Esc+".
+
+- **rightOptionKeyStatus: not-iterm** \u2014 They're not using iTerm2. Explain:
+  > Sisyphus keybinds use Option as Meta. In iTerm2 this is configured via
+  > "Right Option Key \u2192 Esc+". For your terminal, look for a similar setting
+  > like "Option sends Meta" or "Option sends Esc+". Without this, pressing
+  > Option+s will type a special character instead of triggering the keybind.
+
+- **rightOptionKeyStatus: could-not-check** or **unknown** \u2014 Ask them to manually check:
+  > Press Option+s in your terminal. If you see \`\xDF\` (or another special character),
+  > your Option key needs to be reconfigured. In iTerm2: Settings \u2192 Profiles \u2192 Keys \u2192
+  > Right Option Key \u2192 Esc+.
+
+### 2. Explain the session model
+
+This is the KEY concept. Use the diagram and be clear:
+
+\`\`\`
+  YOUR tmux session ("work")        Sisyphus tmux session ("sisyphus-abc123")
+  \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510          \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+  \u2502                     \u2502          \u2502  Orch    \u2502  Agent   \u2502  Agent   \u2502
+  \u2502  Your normal work   \u2502   \u2190\u2500\u2500\u2192   \u2502  (yellow)\u2502  (blue)  \u2502  (green) \u2502
+  \u2502  + dashboard        \u2502          \u2502          \u2502          \u2502          \u2502
+  \u2502                     \u2502          \u2502  Plans & \u2502  Writes  \u2502  Writes  \u2502
+  \u2502                     \u2502          \u2502  assigns \u2502  code    \u2502  tests   \u2502
+  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518          \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+\`\`\`
+
+Key points:
+- Sisyphus creates its OWN tmux session \u2014 it doesn't clutter yours
+- The **orchestrator** (yellow pane) plans work and spawns agents
+- **Agents** (colored panes) work in parallel on subtasks
+- Your session stays clean \u2014 you get a **dashboard** for monitoring
+- You can jump between your session and the sisyphus session to observe
+
+### 3. Teach keybinds
+
+Two keybinds to remember (both use the RIGHT Option key):
+
+| Keybind | Action |
+|---------|--------|
+| Right Option + s | Cycle through sisyphus sessions |
+| Right Option + Shift + s | Jump back to dashboard |
+
+### 4. Verify keybinds are installed
+
+Run \`sisyphus doctor\` and check the output. Look for:
+- "Cycle script" \u2014 should be \u2713
+- "Tmux keybind" \u2014 should be \u2713
+- "Right Option Key" \u2014 should be "Esc+"
+
+If cycle script or keybind is missing, run: \`sisyphus setup-keybind\`
+
+### 5. Test the keybind
+
+Have the user try pressing Right Option + s. Nothing should happen yet (no sisyphus session running) \u2014 and that's fine. The important thing is no special character appears.
+
+If they see \`\xDF\` or similar, circle back to the Right Option Key setup above.
+
+### 6. Verification
+
+Confirm:
+- They understand the two-session model (their session vs sisyphus session)
+- \`sisyphus doctor\` shows keybinds installed AND Right Option Key: Esc+
+- Right Option + s doesn't produce a special character
+
+Proceed:
+\`\`\`
+sisyphus getting-started --tutorial 4
+\`\`\`
+</claude-instructions>
+`);
+}
+function printStep4() {
+  console.log(`
+<claude-instructions>
+# Sisyphus Getting Started \u2014 Step 4: Demo Session
+
+## Instructions for Claude
+
+This is the grand finale \u2014 a live demo session.
+
+### 1. Health check
+
+Run \`sisyphus doctor\` first. If any checks are failing, help the user fix them before proceeding.
+All core checks (tmux, daemon, keybinds) should be \u2713.
+
+### 2. BEFORE launching: Teach navigation
+
+**This is critical.** When \`sisyphus start\` runs, it auto-opens the dashboard in a new tmux window. The user will suddenly be looking at the dashboard and may feel "stuck". Teach them how to navigate BEFORE launching:
+
+Explain clearly:
+
+> Before we launch, you need to know how to move between tmux windows. Right now you're in a window with Claude. When sisyphus starts, it'll open a dashboard in a new window. Think of windows like tabs:
+>
+> \`\`\`
+>   Window 1 (you are here)    Window 2 (dashboard)
+>   \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510      \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+>   \u2502  Claude Code     \u2502      \u2502  Sisyphus        \u2502
+>   \u2502  (this session)  \u2502  \u2192   \u2502  Dashboard       \u2502
+>   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518      \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+>       Ctrl+n \u2192                  \u2190 Ctrl+p
+> \`\`\`
+>
+> - **\`Ctrl+n\`** \u2014 next window (go to dashboard)
+> - **\`Ctrl+p\`** \u2014 previous window (come back here)
+>
+> And remember from step 3:
+> - **Right Option + s** \u2014 jump to the sisyphus agent session (where you can watch agents work live)
+> - **Right Option + Shift + s** \u2014 jump back to dashboard
+
+Have the user confirm they understand these keybinds before proceeding.
+
+### 3. Set expectations, copy demo app, and launch
+
+First, copy the demo todo app to a temp directory and init a git repo (sisyphus needs git):
+\`\`\`
+rm -rf /tmp/sisyphus-tutorial-demo
+cp -r ${templatePath("tutorial-demo")} /tmp/sisyphus-tutorial-demo
+git -C /tmp/sisyphus-tutorial-demo init
+git -C /tmp/sisyphus-tutorial-demo add -A
+git -C /tmp/sisyphus-tutorial-demo commit -m "Initial todo app"
+\`\`\`
+
+Tell the user:
+
+> I've set up a small todo app in /tmp/sisyphus-tutorial-demo \u2014 a Node.js API
+> with a few files. I'm going to launch sisyphus on it. Here's what will happen:
+> 1. The dashboard opens automatically (you'll be switched to it)
+> 2. Press **Ctrl+p** to come back here to Claude \u2014 I'll guide you through what to watch
+> 3. The session takes a few minutes. You can watch agents work live!
+
+Then launch from the demo directory:
+\`\`\`
+cd /tmp/sisyphus-tutorial-demo && sisyphus start "Add three improvements to this todo app: (1) add a priority field (high/medium/low) to todos, (2) add a GET /todos/stats endpoint that returns counts of total/done/pending todos, (3) add tests for the new features. Explain your thinking at each step." -c "TUTORIAL DEMO: A user is watching this session to learn how sisyphus works. Be EXTRA VERBOSE \u2014 explain your reasoning, narrate what you're doing, and make your planning visible. When spawning agents, give each agent context that this is a tutorial demo and they should explain their work clearly. Keep scope small: 2-3 agents, 1-2 cycles."
+\`\`\`
+
+After launching, tell them:
+
+> The dashboard just opened. Press **Ctrl+p** to come back here \u2014 I'll provide live commentary as the session runs so you know what's happening.
+
+Wait for them to confirm they're back, then start live commentary.
+
+### 4. Live commentary loop
+
+**This is the most important part of the demo.** Don't just launch and wait \u2014 actively narrate.
+
+Once the user is back, start a polling loop. Every ~45 seconds, run \`sisyphus status --verbose <session-id>\` and provide SHORT, contextual commentary about what's happening. The \`--verbose\` flag shows agent instructions, full roadmap, cycle logs, and live pane output from the orchestrator and running agents \u2014 use this rich data to narrate what's actually happening, not just phase names.
+
+**How to narrate each phase:**
+
+- **Cycle 1, no agents yet**: "The orchestrator is reading the codebase and planning. It's figuring out how to split the work. Check the dashboard (\`Ctrl+n\`) \u2014 you'll see the roadmap updating."
+
+- **Agents spawning**: "Agents just spawned! You should see new panes appearing. Try \`Right Option + s\` to jump to the sisyphus session and watch them work. Each colored pane is an independent Claude instance."
+
+- **Agents working**: "Agent-001 is working on [X], Agent-002 is on [Y]. They're working in parallel \u2014 this is the key advantage of sisyphus. Jump over and watch if you like (\`Right Option + s\`)."
+
+- **Agents submitting**: "Agent-001 just submitted its report! [N] more to go. When all agents finish, the orchestrator will respawn to review."
+
+- **Between cycles**: "All agents done. The orchestrator is respawning with fresh context to review the reports and decide what's next. This is the cycle boundary \u2014 the orchestrator never runs out of context because it starts fresh each time."
+
+- **Completion**: "The session is complete! Let me show you the results."
+
+**Important:**
+- Keep commentary to 1-3 sentences per check \u2014 don't wall-of-text
+- Remind them of navigation keys when relevant ("jump over with Right Option + s to see this live")
+- If agents are still working with no change, say so briefly ("Still working... Agent-001 is the furthest along")
+- Reference specific agent names and tasks from the status output
+- Stop polling when status shows "completed"
+
+Between polls, encourage the user to explore:
+> "While we wait, try jumping around: \`Ctrl+n\` for dashboard, \`Right Option + s\` for the agent session, \`Right Option + Shift + s\` to jump back. I'll keep narrating here."
+
+### 5. After completion
+
+Once the session shows "completed":
+
+- Show them what the agents built: \`cd /tmp/sisyphus-tutorial-demo && git log --oneline\`
+- Run the tests to prove the work: \`cd /tmp/sisyphus-tutorial-demo && node --test test.js\`
+- Show the session artifacts: find the session dir in \`.sisyphus/sessions/\` and show \`roadmap.md\`
+- Explain: "Every session creates a roadmap, agent reports, and logs \u2014 all stored in .sisyphus/sessions/"
+
+### 6. Proceed to wrap-up
+
+Tell the user the demo is done. Then run:
+\`\`\`
+sisyphus getting-started --tutorial 5
+\`\`\`
+</claude-instructions>
+`);
+}
+function printStep5() {
+  let recentCommits = "";
+  let topLevelFiles = "";
+  try {
+    recentCommits = execSync9("git log --oneline -15 2>/dev/null", { encoding: "utf-8" }).trim();
+  } catch {
+  }
+  try {
+    topLevelFiles = execSync9("ls -1 2>/dev/null", { encoding: "utf-8" }).trim();
+  } catch {
+  }
+  console.log(`
+<claude-instructions>
+# Sisyphus Getting Started \u2014 Step 5: What's Next
+
+## Codebase Context
+<recent-commits>
+${recentCommits || "(no git repo detected)"}
+</recent-commits>
+
+<top-level-files>
+${topLevelFiles || "(could not list)"}
+</top-level-files>
+
+## Instructions for Claude
+
+### 1. Congratulate them
+
+Tell them they've completed the tutorial and recap what they learned:
+- tmux basics (sessions, panes, navigation)
+- nvim basics for reviewing files
+- The sisyphus session model (separate tmux session for orchestrator + agents)
+- Monitoring with dashboard and keybinds
+- A live session lifecycle
+
+### 2. Navigation cheat sheet
+
+| Key | Action |
+|-----|--------|
+| \`Ctrl+n\` / \`Ctrl+p\` | Next/previous tmux window |
+| \`Ctrl+h/j/k/l\` | Navigate between panes |
+| \`Right Option + s\` | Jump to sisyphus agent session |
+| \`Right Option + Shift + s\` | Jump to dashboard |
+
+### 3. How to use sisyphus for REAL work
+
+This is the most important part. Explain clearly:
+
+> **Sisyphus is for big, end-to-end features \u2014 the kind that need exploration,
+> planning, and parallel implementation across multiple systems.**
+>
+> You don't need to define the task precisely. Broad is fine \u2014 the orchestrator
+> will explore the codebase, write specs, plan phases, and break it down itself.
+
+**Real sisyphus sessions (from production use):**
+- "Design and implement a human-in-the-loop agent inbox system" \u2014 exploration, spec writing, DB schema, API endpoints, UI components, webhook integration, e2e validation
+- "Build multi-user organization features \u2014 invites, privilege gating, org switcher, workspace sharing, credit tracking" \u2014 touched auth, DB, API, UI, billing, permissions
+- "Rework all 5 worker onboarding templates to match production pipeline patterns" \u2014 mapped existing patterns, designed new architecture, implemented across templates, validated with e2e tests
+- "Autonomous failure detection system across 8 sequential phases" \u2014 monitoring, alerting, recovery, dashboard, with each phase building on the last
+- "Comprehensive code quality audit \u2014 find and fix dead code, null handling, useless fallbacks" \u2014 systematic codebase-wide analysis and cleanup
+- "Implement @requirements.md" \u2014 point it at a spec and let it go
+
+**NOT good for sisyphus:**
+- Five unrelated small tasks bundled together ("fix the login bug, update the README, add a loading spinner") \u2014 these aren't one feature, they're a todo list
+- Something Claude Code in plan mode would handle \u2014 plan mode already handles substantial single-engineer work. If it fits in one Claude session, just do it directly.
+- Quick fixes, bug fixes, small refactors \u2014 use regular Claude Code
+
+**How to start:**
+The easiest way is the \`/sisyphus:begin\` slash command inside Claude Code. Just tell Claude
+what you want to build and it'll hand it off to sisyphus with the right context.
+
+Or directly: \`sisyphus start "your task" -c "any background context"\`
+
+### 4. Suggest real tasks for THEIR codebase
+
+Look at the recent commits and top-level files above. Based on what you can see of their project, suggest 2-3 concrete sisyphus-scale tasks they could try. Be specific to their codebase \u2014 reference actual directories, patterns, or areas you can see.
+
+If there are no commits or files (e.g., they ran this from /tmp), skip this section.
+
+Format as:
+> Based on your codebase, here are some tasks sisyphus would be great for:
+> - "..."
+> - "..."
+
+### 5. There's more to learn
+
+Tell them:
+
+> There's actually a lot of depth to how sisyphus works \u2014 the design is intentional
+> and there's real reasoning behind why it does things the way it does. If you want
+> to understand the philosophy, or you want a deeper rundown on the dashboard,
+> monitoring, configuration, or how to steer sessions \u2014 just ask and I'll explain.
+
+If the user says yes or asks to learn more, run \`sisyphus getting-started --explain\`
+and use its output to explain the system to them conversationally. Don't dump the whole
+thing \u2014 answer what they're curious about, using the reference as your source material.
+</claude-instructions>
+`);
+}
+function printExplain() {
+  console.log(`
+<claude-instructions>
+# Sisyphus \u2014 Comprehensive Reference
+
+This is a detailed reference for how sisyphus works. The user asked to understand
+sisyphus more deeply. Use this to answer their questions conversationally \u2014 don't dump
+the whole thing. Read through it, then respond to what they're curious about.
+
+## Design Philosophy
+
+Sisyphus is built on specific insights about how to get the best work out of LLM agents.
+These aren't arbitrary \u2014 each design decision solves a real failure mode.
+
+### 1. The Orchestrator as "Human-in-the-Loop"
+
+When you use Claude Code effectively, YOU are the orchestrator \u2014 you review work,
+steer direction, break problems down, and assign the next piece. Sisyphus automates
+that human role. The orchestrator does what a skilled developer does when prompting
+Claude: explore the codebase, understand the problem, write specs, plan phases,
+assign focused work, review results, and iterate.
+
+The strategy layer mirrors how developers actually work on end-to-end features:
+explore, understand, spec, plan, implement, review, validate. The orchestrator
+follows this same workflow, but runs it with parallel agents.
+
+### 2. Fresh Context Kills Shortcuts
+
+The orchestrator is KILLED after every cycle and respawned fresh. This is the most
+important design decision.
+
+When an LLM accumulates context over a long session, it starts taking shortcuts.
+It "knows" what it did earlier, so it skips re-reading, assumes things still hold,
+and builds on stale understanding. A fresh start forces honest reassessment every
+cycle \u2014 the orchestrator reads the actual state, not its memory of it.
+
+This is inspired by adversarial training (think GANs) \u2014 better results come from
+adversarial pressure. Each fresh orchestrator effectively audits the previous cycle's
+work because it has no stake in defending prior decisions. It sees the roadmap, the
+reports, the code \u2014 and judges them with fresh eyes.
+
+### 3. Single-Focus Agents
+
+Each agent gets ONE task with a fully self-contained instruction. No context switching,
+no juggling multiple concerns, no "also while you're there could you..."
+
+LLMs perform dramatically better when focused. An agent implementing a priority field
+doesn't think about the stats endpoint. It reads the relevant context, does its one
+thing well, and reports back. The orchestrator handles decomposition \u2014 agents handle
+execution.
+
+### 4. Shared Context Directory (Saved Research)
+
+Every session has a context/ directory where agents save research, specs, plans, and
+design docs. These files persist across ALL cycles and are visible to the orchestrator
+and subsequent agents.
+
+This means research is never repeated. Cycle 1 agents explore and write findings to
+context/explore-auth-system.md. Cycle 3 agents read those findings and build on them.
+Knowledge accumulates even though the orchestrator itself is stateless.
+
+### 5. Two-Layer Planning (Strategy + Roadmap)
+
+The system maintains two documents at different abstraction levels:
+
+**strategy.md** \u2014 The high-level problem-solving map. What phases exist, what gates
+between them, what backtrack paths exist. Updated every few cycles when the shape of
+work changes. Helps the orchestrator see the forest.
+
+**roadmap.md** \u2014 Working memory. Updated every cycle. Current Stage, Exit Criteria,
+Active Context, Next Steps. The orchestrator reads this first each cycle to understand
+where things stand. Helps the orchestrator see the trees.
+
+This prevents the failure mode where a single document becomes either too abstract
+to act on or too detailed to show the big picture.
+
+### 6. Adversarial Review Is Built In
+
+The orchestrator doesn't just implement \u2014 it runs mandatory critique cycles. After
+implementation, review agents attack different dimensions: code reuse, quality,
+efficiency, correctness. Fix agents address the findings. Re-review until only nits
+remain. Multiple agents auditing each other produces better results than any single
+agent reviewing its own work.
+
+The rule: never let 2+ stages complete without critique. Small issues compound into
+architectural problems if unchecked.
+
+### 7. Evidence Over Assumptions
+
+Validation requires PROOF \u2014 command output, test results, HTTP responses. "The code
+looks correct" is not evidence. "All 14 tests pass" is. This catches the gap between
+code that looks right and code that works.
+
+## Architecture Overview
+
+\`\`\`
+\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+\u2502                        USER'S TMUX SESSION                          \u2502
+\u2502                                                                     \u2502
+\u2502  \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  \u2502
+\u2502  \u2502 Window 1: Claude Code   \u2502  \u2502 Window 2: Dashboard (TUI)        \u2502  \u2502
+\u2502  \u2502                         \u2502  \u2502                                  \u2502  \u2502
+\u2502  \u2502  User's normal work     \u2502  \u2502  Real-time session monitor       \u2502  \u2502
+\u2502  \u2502  + this conversation    \u2502  \u2502  Roadmap, agents, reports        \u2502  \u2502
+\u2502  \u2502                         \u2502  \u2502  Interactive controls            \u2502  \u2502
+\u2502  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518  \u2502
+\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+                                   \u2502 Right Option+s / Right Option+Shift+s
+                                   \u25BC
+\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+\u2502                     SISYPHUS TMUX SESSION                           \u2502
+\u2502                    (created per sisyphus session)                   \u2502
+\u2502                                                                     \u2502
+\u2502  \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510                      \u2502
+\u2502  \u2502 Orch     \u2502 Agent    \u2502 Agent    \u2502 Agent    \u2502  \u2190 panes             \u2502
+\u2502  \u2502 (yellow) \u2502 (blue)   \u2502 (green)  \u2502 (magenta)\u2502                      \u2502
+\u2502  \u2502          \u2502          \u2502          \u2502          \u2502                      \u2502
+\u2502  \u2502 Plans,   \u2502 Impl     \u2502 Tests    \u2502 Docs     \u2502  \u2190 each is a         \u2502
+\u2502  \u2502 assigns, \u2502 feature  \u2502          \u2502          \u2502    Claude Code       \u2502
+\u2502  \u2502 reviews  \u2502          \u2502          \u2502          \u2502    instance          \u2502
+\u2502  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518                      \u2502
+\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+                                   \u2502
+                                   \u25BC
+\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+\u2502                          DAEMON (sisyphusd)                         \u2502
+\u2502                     Background process via launchd                  \u2502
+\u2502                                                                     \u2502
+\u2502  Listens on ~/.sisyphus/daemon.sock                                 \u2502
+\u2502  Manages session lifecycle, pane monitoring, state persistence      \u2502
+\u2502  Polls panes to detect when agents/orchestrator finish              \u2502
+\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+\`\`\`
+
+## The Session Lifecycle (in detail)
+
+\`\`\`
+  \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+  \u2502                    SESSION LIFECYCLE                             \u2502
+  \u2502                                                                  \u2502
+  \u2502  sisyphus start "task"                                           \u2502
+  \u2502       \u2502                                                          \u2502
+  \u2502       \u25BC                                                          \u2502
+  \u2502  \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510     spawn agents     \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510               \u2502
+  \u2502  \u2502  Orch   \u2502 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2192  \u2502  Agents work \u2502               \u2502
+  \u2502  \u2502 plans   \u2502     then yields      \u2502  in parallel \u2502               \u2502
+  \u2502  \u2514\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2518                      \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518               \u2502
+  \u2502       \u2502                                  \u2502 each calls            \u2502
+  \u2502       \u2502 orchestrator                     \u2502 sisyphus submit       \u2502
+  \u2502       \u2502 is KILLED                        \u2502 when done             \u2502
+  \u2502       \u2502                                  \u25BC                       \u2502
+  \u2502       \u2502                           \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510               \u2502
+  \u2502       \u2502                           \u2502 All agents   \u2502               \u2502
+  \u2502       \u2502                           \u2502 finished?    \u2502               \u2502
+  \u2502       \u2502                           \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518               \u2502
+  \u2502       \u2502                                  \u2502 yes                   \u2502
+  \u2502       \u2502           \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518                       \u2502
+  \u2502       \u2502           \u25BC                                              \u2502
+  \u2502       \u2502     \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510                                          \u2502
+  \u2502       \u2514\u2500\u2500\u2500\u2500 \u2502 Respawn \u2502  Fresh orchestrator with full state      \u2502
+  \u2502  next cycle \u2502  Orch   \u2502  Reviews reports, plans next cycle       \u2502
+  \u2502             \u2514\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2518                                          \u2502
+  \u2502                  \u2502                                               \u2502
+  \u2502                  \u25BC                                               \u2502
+  \u2502          \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510         \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510                 \u2502
+  \u2502          \u2502 More work     \u2502\u2500\u2500yes\u2500\u2500\u2192 \u2502 Spawn     \u2502 \u2192 (loop)        \u2502
+  \u2502          \u2502 needed?       \u2502         \u2502 agents    \u2502                 \u2502
+  \u2502          \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518         \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518                 \u2502
+  \u2502                  \u2502 no                                            \u2502
+  \u2502                  \u25BC                                               \u2502
+  \u2502          \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510                                       \u2502
+  \u2502          \u2502 sisyphus      \u2502                                       \u2502
+  \u2502          \u2502 complete      \u2502                                       \u2502
+  \u2502          \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518                                       \u2502
+  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+\`\`\`
+
+**Key insight**: The orchestrator is STATELESS. It gets killed after each yield and
+respawned fresh with the complete session state (roadmap, agent reports, cycle history).
+This means it never runs out of context, no matter how many cycles a session takes.
+
+## The Dashboard
+
+The dashboard is a real-time TUI that shows session state. Launch with \`sisyphus dashboard\`
+or it auto-opens when a session starts.
+
+**Dashboard sections:**
+- **Header**: Session ID, status, task description
+- **Roadmap**: Current strategic plan with checked/unchecked items
+- **Agents**: List of all agents with status, duration, and report summaries
+- **Cycles**: Orchestrator cycle history
+- **Messages**: Recent session messages
+
+**Dashboard keys:**
+| Key | Action |
+|-----|--------|
+| \`m\` | Message the orchestrator (steer direction mid-session) |
+| \`w\` | Jump to the sisyphus tmux session (watch agents work) |
+| \`k\` | Kill the session |
+| \`r\` | Resume a paused/completed session |
+| \`q\` | Quit the dashboard |
+| \`\u2191/\u2193\` | Scroll through content |
+| \`Tab\` | Cycle through sections |
+
+**The \`m\` key is the most powerful feature.** You can message the orchestrator at any time
+to course-correct: "Focus on the API layer first", "Skip the tests for now",
+"The approach for auth is wrong, use JWT instead". The orchestrator reads these
+messages when it respawns each cycle.
+
+## Monitoring Strategy
+
+Sisyphus sessions should be actively monitored. Here's what to watch for:
+
+**Things that go wrong:**
+- Agents stuck waiting for user input (they're autonomous \u2014 they shouldn't need input)
+- Agents going down rabbit holes or working on the wrong thing
+- Merge conflicts between agents touching the same files
+- Orchestrator spawning too many agents or too few
+- Agents crashing or getting killed unexpectedly
+
+**When to intervene:**
+- Use \`m\` in the dashboard to message the orchestrator with corrections
+- Use \`sisyphus kill <id>\` to stop a runaway session
+- Use \`sisyphus resume <id> "new instructions"\` to restart with different direction
+
+**Useful monitoring commands:**
+\`\`\`
+sisyphus status <id>              # Quick status check
+sisyphus status --verbose <id>    # Full detail: roadmap, pane output, agent instructions
+sisyphus dashboard                # Interactive TUI
+tail -f ~/.sisyphus/daemon.log    # Daemon activity log
+\`\`\`
+
+## The .sisyphus/ Directory
+
+Everything sisyphus does lives in a \`.sisyphus/\` directory at the root of your project.
+This is project-local \u2014 each project gets its own. It contains:
+
+\`\`\`
+.sisyphus/
+\u251C\u2500\u2500 config.json              # Project-specific config (model, poll interval, etc.)
+\u251C\u2500\u2500 orchestrator.md          # Optional custom orchestrator prompt override
+\u2514\u2500\u2500 sessions/
+    \u251C\u2500\u2500 <session-id-1>/      # Each session gets its own directory
+    \u251C\u2500\u2500 <session-id-2>/
+    \u2514\u2500\u2500 ...
+\`\`\`
+
+There's also a global directory at \`~/.sisyphus/\` for the daemon socket, PID file,
+logs, keybind scripts, and global config. But the session state \u2014 the roadmaps,
+reports, context files, cycle logs \u2014 all lives in your project's \`.sisyphus/sessions/\`.
+
+## Session Files
+
+Every session creates a directory at \`.sisyphus/sessions/<id>/\` with:
+
+\`\`\`
+.sisyphus/sessions/<id>/
+\u251C\u2500\u2500 state.json          # Session state (agents, cycles, status)
+\u251C\u2500\u2500 roadmap.md          # Strategic plan (updated by orchestrator each cycle)
+\u251C\u2500\u2500 goal.md             # Original task description
+\u251C\u2500\u2500 strategy.md         # High-level strategy notes
+\u251C\u2500\u2500 logs/
+\u2502   \u251C\u2500\u2500 cycle-000.md    # What the orchestrator did in cycle 0
+\u2502   \u251C\u2500\u2500 cycle-001.md    # What it did in cycle 1, etc.
+\u2502   \u2514\u2500\u2500 ...
+\u251C\u2500\u2500 reports/
+\u2502   \u251C\u2500\u2500 agent-001-final.md    # Agent's final report
+\u2502   \u251C\u2500\u2500 agent-002-update.md   # Agent's progress update
+\u2502   \u2514\u2500\u2500 ...
+\u251C\u2500\u2500 prompts/            # System/user prompts sent to orchestrator and agents
+\u2514\u2500\u2500 context/            # Shared context files for agents
+\`\`\`
+
+## Configuration
+
+**Global config**: \`~/.sisyphus/config.json\`
+**Project config**: \`.sisyphus/config.json\` (overrides global)
+
+Options:
+- \`model\` \u2014 Claude model for orchestrator and agents
+- \`orchestratorPrompt\` \u2014 Path to custom orchestrator prompt
+- \`pollIntervalMs\` \u2014 How often daemon checks pane status (default: 2000)
+
+## Starting Sessions \u2014 Best Practices
+
+**The /sisyphus:begin slash command** is the recommended way to start. Inside Claude Code:
+\`\`\`
+/sisyphus:begin
+\`\`\`
+Then describe your task. Claude will hand it off with the right context.
+
+**Direct CLI:**
+\`\`\`
+sisyphus start "task description" -c "background context"
+sisyphus start "Implement @requirements.md" -n my-feature
+\`\`\`
+
+**Reference files with @**: \`sisyphus start "Build @docs/spec.md"\` \u2014 the orchestrator
+will read the referenced file as part of its planning.
+
+**The -c flag** adds background context the orchestrator sees but doesn't act on directly.
+Use it for constraints: \`-c "Don't modify the auth module, use the existing API"\`
+
+**The -n flag** gives the session a human-readable name for easier tracking.
+
+## CLI Command Reference
+
+| Command | Purpose |
+|---------|---------|
+| \`sisyphus start "task"\` | Start a new session |
+| \`sisyphus status [id]\` | Check session status |
+| \`sisyphus status -v [id]\` | Detailed status with pane output |
+| \`sisyphus list\` | List all sessions |
+| \`sisyphus dashboard\` | Open the TUI dashboard |
+| \`sisyphus resume <id> "msg"\` | Resume with new instructions |
+| \`sisyphus kill <id>\` | Stop a session |
+| \`sisyphus doctor\` | Check installation health |
+| \`sisyphus setup\` | Run setup/onboarding |
+| \`sisyphus setup-keybind\` | Install tmux keybinds |
+
+## Troubleshooting
+
+**Daemon not running:**
+\`\`\`
+sisyphusd restart
+\`\`\`
+
+**Keybinds not working (special characters appear):**
+iTerm2 \u2192 Settings \u2192 Profiles \u2192 Keys \u2192 Right Option Key \u2192 Esc+
+
+**Agents stuck:** Check \`sisyphus status --verbose <id>\` to see pane output. If an
+agent is waiting for input, kill the session and restart with clearer instructions.
+
+**Dashboard not opening:** Run \`sisyphus dashboard\` manually. Must be inside tmux.
+
+**Session seems hung:** Check \`tail -20 ~/.sisyphus/daemon.log\` for errors.
+The daemon polls panes every 2s \u2014 if a pane dies unexpectedly, it'll be detected.
+</claude-instructions>
+`);
+}
+var STEPS = [printStep0, printStep1, printStep2, printStep3, printStep4, printStep5];
+function registerGettingStarted(program2) {
+  program2.command("getting-started").description("Interactive tutorial (best with Claude Code)").option("--tutorial <step>", "Tutorial step (0-5)", parseInt).option("--explain", "Comprehensive reference for how sisyphus works").action((opts) => {
+    if (opts.explain) {
+      printExplain();
+      return;
+    }
+    if (opts.tutorial !== void 0) {
+      const step = opts.tutorial;
+      if (step < 0 || step > 5 || Number.isNaN(step)) {
+        console.error(`Invalid tutorial step: ${opts.tutorial}. Must be 0-5.`);
+        process.exit(1);
+      }
+      STEPS[step]();
+      return;
+    }
+    if (!isClaudeCode()) {
+      printNonClaudeMessage();
+      return;
+    }
+    printStep0();
   });
 }
 
 // src/cli/commands/init.ts
-import { existsSync as existsSync5, mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "fs";
-import { join as join5 } from "path";
+import { existsSync as existsSync7, mkdirSync as mkdirSync4, writeFileSync as writeFileSync4 } from "fs";
+import { join as join7 } from "path";
 var DEFAULT_CONFIG = {};
 var ORCHESTRATOR_TEMPLATE = `# Custom Orchestrator Prompt
 
@@ -1539,19 +2732,19 @@ var ORCHESTRATOR_TEMPLATE = `# Custom Orchestrator Prompt
 function registerInit(program2) {
   program2.command("init").description("Initialize sisyphus configuration for this project").option("--orchestrator", "Also create a custom orchestrator prompt template").action((opts) => {
     const cwd = process.cwd();
-    const sisDir = join5(cwd, ".sisyphus");
-    const configPath = join5(sisDir, "config.json");
-    if (existsSync5(configPath)) {
+    const sisDir = join7(cwd, ".sisyphus");
+    const configPath = join7(sisDir, "config.json");
+    if (existsSync7(configPath)) {
       console.log(`Already initialized: ${configPath}`);
       return;
     }
-    mkdirSync3(sisDir, { recursive: true });
-    writeFileSync3(configPath, JSON.stringify(DEFAULT_CONFIG, null, 2) + "\n", "utf-8");
+    mkdirSync4(sisDir, { recursive: true });
+    writeFileSync4(configPath, JSON.stringify(DEFAULT_CONFIG, null, 2) + "\n", "utf-8");
     console.log(`Created ${configPath}`);
     if (opts.orchestrator) {
-      const orchPath = join5(sisDir, "orchestrator.md");
-      if (!existsSync5(orchPath)) {
-        writeFileSync3(orchPath, ORCHESTRATOR_TEMPLATE, "utf-8");
+      const orchPath = join7(sisDir, "orchestrator.md");
+      if (!existsSync7(orchPath)) {
+        writeFileSync4(orchPath, ORCHESTRATOR_TEMPLATE, "utf-8");
         console.log(`Created ${orchPath}`);
       }
     }
@@ -1564,6 +2757,94 @@ function registerInit(program2) {
   });
 }
 
+// src/cli/commands/setup.ts
+import { execSync as execSync10 } from "child_process";
+function getTmuxVersion() {
+  try {
+    return execSync10("tmux -V", { encoding: "utf-8", stdio: "pipe" }).trim();
+  } catch {
+    return "installed";
+  }
+}
+function printResults(result, daemonOk, keybindMsg) {
+  console.log("");
+  console.log("Setting up Sisyphus...");
+  console.log("");
+  if (result.tmuxInstalled) {
+    const detail = getTmuxVersion();
+    console.log(`  \u2713 tmux: ${detail}${result.tmuxAutoInstalled ? " (just installed)" : ""}`);
+  } else {
+    const hint = process.platform === "darwin" ? "Install Homebrew (https://brew.sh) then: brew install tmux" : "apt install tmux (Debian/Ubuntu) or your package manager";
+    console.log(`  \u2717 tmux: Not installed \u2014 ${hint}`);
+  }
+  if (result.tmuxDefaultsWritten) {
+    console.log("  \u2713 tmux config: Sensible defaults written to ~/.tmux.conf");
+  }
+  if (process.platform === "darwin") {
+    if (result.terminal.isIterm) {
+      console.log(`  \u2713 Terminal: ${result.terminal.name}`);
+    } else {
+      const name = result.terminal.name ? result.terminal.name : "unknown";
+      console.log(`  \u26A0 Terminal: ${name} \u2014 iTerm2 recommended (https://iterm2.com)`);
+    }
+  }
+  if (result.itermOptionKey.checked) {
+    if (result.itermOptionKey.allCorrect) {
+      console.log("  \u2713 Right Option Key: Esc+");
+    } else {
+      const profiles = result.itermOptionKey.incorrectProfiles.map((p) => `"${p}"`).join(", ");
+      console.log(`  \u26A0 Right Option Key: Not set to Esc+ for ${profiles}`);
+      console.log("    Fix: iTerm2 \u2192 Settings \u2192 Profiles \u2192 Keys \u2192 Right Option Key \u2192 Esc+");
+    }
+  }
+  if (daemonOk) {
+    console.log("  \u2713 Daemon: Running");
+  } else {
+    console.log("  \u2717 Daemon: Failed to start");
+  }
+  console.log(`  \u2713 Keybindings: ${keybindMsg}`);
+  if (result.command.installed) {
+    console.log(`  \u2713 /begin command: ${result.command.path}${result.command.autoInstalled ? " (just installed)" : ""}`);
+  } else {
+    console.log("  \u2717 /begin command: Failed to install");
+  }
+  if (result.nvim.installed) {
+    const extra = result.nvim.autoInstalled ? " (just installed)" : "";
+    console.log(`  \u2713 Editor: nvim ${result.nvim.version}${extra}`);
+    if (result.nvim.lazyVimInstalled) {
+      console.log("  \u2713 LazyVim: Starter config installed to ~/.config/nvim/");
+    }
+  } else {
+    console.log("  \u26A0 Editor: nvim not installed");
+    if (process.platform === "darwin") {
+      console.log("    Install: brew install neovim");
+    }
+  }
+  console.log("");
+  console.log("Run 'sisyphus getting-started' for a usage guide.");
+  console.log("");
+}
+function registerSetup(program2) {
+  program2.command("setup").description("One-time setup: install dependencies, daemon, keybindings, and commands").action(async () => {
+    const result = runOnboarding();
+    let daemonOk = false;
+    try {
+      await ensureDaemonInstalled();
+      daemonOk = true;
+    } catch {
+      daemonOk = isInstalled();
+    }
+    const keybindResult = setupTmuxKeybind();
+    let keybindMsg;
+    if (keybindResult.status === "installed" || keybindResult.status === "already-installed") {
+      keybindMsg = `${DEFAULT_KEY} (cycle), ${DEFAULT_HOME_KEY} (dashboard)`;
+    } else {
+      keybindMsg = keybindResult.message;
+    }
+    printResults(result, daemonOk, keybindMsg);
+  });
+}
+
 // src/cli/index.ts
 var nodeVersion = parseInt(process.versions.node.split(".")[0], 10);
 if (nodeVersion < 22) {
@@ -1573,7 +2854,7 @@ if (nodeVersion < 22) {
 var program = new Command();
 program.name("sisyphus").description("tmux-integrated orchestration daemon for Claude Code").version(
   JSON.parse(
-    readFileSync4(join6(dirname2(fileURLToPath2(import.meta.url)), "..", "package.json"), "utf-8")
+    readFileSync5(join8(dirname4(fileURLToPath4(import.meta.url)), "..", "package.json"), "utf-8")
   ).version
 );
 program.configureHelp({
@@ -1602,6 +2883,7 @@ registerDoctor(program);
 registerCompanionContext(program);
 registerGettingStarted(program);
 registerInit(program);
+registerSetup(program);
 program.addHelpText("after", `
 Examples:
   $ sisyphus start "Implement auth system"     Start a new session
@@ -1614,15 +2896,11 @@ Run 'sisyphus getting-started' for a complete usage guide.
 `);
 var args = process.argv.slice(2);
 var firstArg = args[0];
-var skipWelcome = ["doctor", "getting-started", "help", "--help", "-h", "init", "uninstall", "--version", "-V"];
-if (!existsSync6(globalDir()) && firstArg && !skipWelcome.includes(firstArg)) {
-  mkdirSync4(globalDir(), { recursive: true });
-  console.log("");
-  console.log("  Welcome to Sisyphus \u2014 multi-agent orchestration for Claude Code.");
+var skipWelcome = ["doctor", "getting-started", "help", "--help", "-h", "init", "setup", "uninstall", "--version", "-V"];
+if (!existsSync8(globalDir()) && firstArg && !skipWelcome.includes(firstArg)) {
+  mkdirSync5(globalDir(), { recursive: true });
   console.log("");
-  console.log("  First time? Run these commands:");
-  console.log("    sisyphus doctor           Check your setup");
-  console.log("    sisyphus getting-started   Learn the basics");
+  console.log("  Welcome to Sisyphus. Run 'sisyphus setup' to get started.");
   console.log("");
 }
 program.parseAsync(process.argv).catch((err) => {