sisyphi 1.1.8 → 1.1.10

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 existsSync7, mkdirSync as mkdirSync5, readFileSync as readFileSync5 } from "fs";
-import { dirname as dirname3, join as join7 } from "path";
-import { fileURLToPath as fileURLToPath3 } 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 {
@@ -737,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",
@@ -773,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";
@@ -820,15 +839,33 @@ function computeLastActivity(session) {
   if (timestamps.length === 0) return null;
   return new Date(Math.max(...timestamps));
 }
-function readRoadmapTodos(cwd, sessionId) {
+function readRoadmap(cwd, sessionId) {
   try {
-    const content = readFileSync3(roadmapPath(cwd, sessionId), "utf8");
-    return content.split("\n").filter((line) => /^\s*- \[ \]/.test(line)).map((line) => line.replace(/^\s*- \[ \]\s*/, "")).slice(0, 5);
+    return readFileSync3(roadmapPath(cwd, sessionId), "utf8");
   } catch {
-    return [];
+    return null;
   }
 }
-function printSession(session) {
+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(`
@@ -836,7 +873,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}`);
@@ -857,15 +894,17 @@ ${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) {
+  const roadmap = readRoadmap(session.cwd, session.id);
+  if (roadmap) {
     console.log(`
-${BOLD}Remaining (${todos.length} unchecked):${RESET}`);
-    for (const todo of todos) {
-      console.log(`  - ${todo}`);
-    }
+${BOLD}Roadmap:${RESET}`);
+    console.log(roadmap);
   }
   if (session.orchestratorCycles.length > 0) {
     console.log(`
@@ -875,25 +914,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");
       }
@@ -1164,12 +1246,12 @@ function registerSetupKeybind(program2) {
 }
 
 // src/cli/commands/doctor.ts
-import { execSync as execSync7 } from "child_process";
-import { existsSync as existsSync5, statSync } from "fs";
+import { execSync as execSync8 } from "child_process";
+import { existsSync as existsSync6, statSync } from "fs";
 
 // src/cli/onboard.ts
-import { execSync as execSync6 } from "child_process";
-import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
+import { execSync as execSync7 } from "child_process";
+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";
@@ -1180,7 +1262,7 @@ function detectTerminal() {
 }
 function isTmuxAvailable() {
   try {
-    execSync6("which tmux", { stdio: "pipe" });
+    execSync7("which tmux", { stdio: "pipe" });
     return true;
   } catch {
     return false;
@@ -1188,7 +1270,7 @@ function isTmuxAvailable() {
 }
 function isBrewAvailable() {
   try {
-    execSync6("which brew", { stdio: "pipe" });
+    execSync7("which brew", { stdio: "pipe" });
     return true;
   } catch {
     return false;
@@ -1198,7 +1280,7 @@ function tryAutoInstallTmux() {
   if (!isBrewAvailable()) return false;
   try {
     console.log("  Installing tmux via Homebrew...");
-    execSync6("brew install tmux", { stdio: "inherit" });
+    execSync7("brew install tmux", { stdio: "inherit" });
     return isTmuxAvailable();
   } catch {
     return false;
@@ -1209,11 +1291,11 @@ function checkItermOptionKey() {
     return { checked: false, allCorrect: true, incorrectProfiles: [] };
   }
   const plistPath2 = join5(homedir3(), "Library", "Preferences", "com.googlecode.iterm2.plist");
-  if (!existsSync4(plistPath2)) {
+  if (!existsSync5(plistPath2)) {
     return { checked: false, allCorrect: false, incorrectProfiles: [] };
   }
   try {
-    const json = execSync6(
+    const json = execSync7(
       `plutil -extract "New Bookmarks" json -o - "${plistPath2}"`,
       { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }
     );
@@ -1233,7 +1315,7 @@ function checkItermOptionKey() {
   }
 }
 function hasExistingTmuxConf() {
-  return existsSync4(join5(homedir3(), ".tmux.conf")) || existsSync4(join5(homedir3(), ".config", "tmux", "tmux.conf"));
+  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.
@@ -1263,6 +1345,40 @@ 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");
@@ -1270,7 +1386,7 @@ function writeTmuxDefaults() {
 }
 function isNvimAvailable() {
   try {
-    execSync6("which nvim", { stdio: "pipe" });
+    execSync7("which nvim", { stdio: "pipe" });
     return true;
   } catch {
     return false;
@@ -1278,13 +1394,13 @@ function isNvimAvailable() {
 }
 function getNvimVersion() {
   try {
-    return execSync6("nvim --version", { encoding: "utf-8", stdio: "pipe" }).split("\n")[0]?.replace("NVIM ", "") || "unknown";
+    return execSync7("nvim --version", { encoding: "utf-8", stdio: "pipe" }).split("\n")[0]?.replace("NVIM ", "") || "unknown";
   } catch {
     return "unknown";
   }
 }
 function hasLazyVimConfig() {
-  return existsSync4(join5(homedir3(), ".config", "nvim", "lazy-lock.json"));
+  return existsSync5(join5(homedir3(), ".config", "nvim", "lazy-lock.json"));
 }
 function tryAutoInstallNvim() {
   if (isNvimAvailable()) {
@@ -1295,7 +1411,7 @@ function tryAutoInstallNvim() {
   }
   try {
     console.log("  Installing neovim via Homebrew...");
-    execSync6("brew install neovim", { stdio: "inherit" });
+    execSync7("brew install neovim", { stdio: "inherit" });
   } catch {
     return { installed: false, autoInstalled: false, version: "", lazyVimInstalled: false };
   }
@@ -1304,13 +1420,13 @@ function tryAutoInstallNvim() {
   }
   const nvimConfigDir = join5(homedir3(), ".config", "nvim");
   let lazyVimInstalled = false;
-  if (!existsSync4(nvimConfigDir)) {
+  if (!existsSync5(nvimConfigDir)) {
     try {
       console.log("  Cloning LazyVim starter config...");
-      execSync6(`git clone https://github.com/LazyVim/starter ${nvimConfigDir}`, { stdio: "inherit" });
+      execSync7(`git clone https://github.com/LazyVim/starter ${nvimConfigDir}`, { stdio: "inherit" });
       const gitDir = join5(nvimConfigDir, ".git");
-      if (existsSync4(gitDir)) {
-        execSync6(`rm -rf "${gitDir}"`, { stdio: "pipe" });
+      if (existsSync5(gitDir)) {
+        execSync7(`rm -rf "${gitDir}"`, { stdio: "pipe" });
       }
       lazyVimInstalled = true;
     } catch {
@@ -1326,15 +1442,15 @@ function bundledBeginCommandPath() {
   return join5(distDir, "templates", "begin.md");
 }
 function isBeginCommandInstalled() {
-  return existsSync4(beginCommandPath());
+  return existsSync5(beginCommandPath());
 }
 function installBeginCommand() {
   const dest = beginCommandPath();
-  if (existsSync4(dest)) {
+  if (existsSync5(dest)) {
     return { installed: true, autoInstalled: false, path: dest };
   }
   const src = bundledBeginCommandPath();
-  if (!existsSync4(src)) {
+  if (!existsSync5(src)) {
     return { installed: false, autoInstalled: false, path: dest };
   }
   try {
@@ -1378,7 +1494,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 {
@@ -1391,7 +1507,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" };
@@ -1399,7 +1515,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]);
@@ -1425,7 +1541,7 @@ function checkDaemonInstalled() {
     };
   }
   const pid = daemonPidPath();
-  if (existsSync5(pid)) {
+  if (existsSync6(pid)) {
     return { name: "Daemon setup", status: "ok", detail: `PID file found at ${pid}` };
   }
   return {
@@ -1437,7 +1553,7 @@ function checkDaemonInstalled() {
 }
 function checkDaemonRunning() {
   const pid = daemonPidPath();
-  if (!existsSync5(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",
@@ -1448,7 +1564,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 {
@@ -1461,13 +1577,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" };
@@ -1475,7 +1591,7 @@ function checkTmux() {
 }
 function checkCycleScript() {
   const path = cycleScriptPath();
-  if (!existsSync5(path)) {
+  if (!existsSync6(path)) {
     return {
       name: "Cycle script",
       status: "fail",
@@ -1500,7 +1616,7 @@ function checkCycleScript() {
 function checkTmuxKeybind() {
   const existing = getExistingBinding(DEFAULT_KEY);
   if (existing === null) {
-    if (existsSync5(sisyphusTmuxConfPath())) {
+    if (existsSync6(sisyphusTmuxConfPath())) {
       return {
         name: `Tmux keybind (${DEFAULT_KEY})`,
         status: "warn",
@@ -1526,7 +1642,7 @@ function checkTmuxKeybind() {
 }
 function checkGlobalDir() {
   const dir = globalDir();
-  if (existsSync5(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)` };
@@ -1580,7 +1696,7 @@ function checkNvim() {
     return { name: "nvim", status: "warn", detail: "Not installed", fix };
   }
   try {
-    const version = execSync7("nvim --version", { encoding: "utf-8", stdio: "pipe" }).split("\n")[0]?.replace("NVIM ", "");
+    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" };
@@ -1634,6 +1750,12 @@ function registerCompanionContext(program2) {
 }
 
 // src/cli/commands/getting-started.ts
+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"];
 }
@@ -1678,7 +1800,7 @@ function printStep0() {
 
 ## Tutorial Overview
 
-This tutorial has 5 steps. Share this overview so the user knows what's coming and can skip ahead:
+This tutorial has 6 steps. Share this overview so the user knows what's coming and can skip ahead:
 
 | Step | Topic | Command |
 |------|-------|---------|
@@ -1687,6 +1809,7 @@ This tutorial has 5 steps. Share this overview so the user knows what's coming a
 | 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>\`.
 
@@ -1776,9 +1899,12 @@ tmux split-window -h
 Tell them: "I just split your terminal. You should see two panes side by side."
 
 Explain navigation:
-- \`Ctrl-b\` then \`\u2192\` (right arrow): move to the right pane
-- \`Ctrl-b\` then \`\u2190\` (left arrow): move to the left pane
-- The prefix \`Ctrl-b\` is always pressed first, then released, then the arrow key
+- \`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.
 
@@ -1795,11 +1921,14 @@ Or tell them they can type \`exit\` in the extra pane to close it.
 
 - **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 mode**: \`Ctrl-b [\` \u2014 lets you scroll up through output. Press \`q\` to exit scroll mode.
+- **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-b + arrow keys?"
+Ask the user to confirm: "Can you navigate between panes with Ctrl+h and Ctrl+l?"
 
 Once confirmed, proceed:
 \`\`\`
@@ -1819,40 +1948,39 @@ function printStep2() {
 
 ## Instructions for Claude
 
-This step is OPTIONAL. Nvim is useful for reviewing agent work in tmux panes but not required.
+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 files in tmux panes. Want me to install it, or skip this step?"
+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)
 
-Teach exactly 3 things \u2014 no more:
+Briefly explain the key concept \u2014 nvim has two modes:
 
-1. **Open a file**: \`nvim filename.txt\`
-2. **Save and close**: \`ZZ\` (capital Z twice \u2014 hold Shift, press Z twice)
-3. **Quit without saving**: \`:q!\` (colon, q, exclamation mark, Enter)
+- **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.
 
-### Hands-on exercise
+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."
 
-Create a temporary file for practice:
+Open the bundled tutorial file in a split pane:
 \`\`\`
-echo "Hello from the sisyphus tutorial!" > /tmp/sisyphus-tutorial-test.txt
+cp ${templatePath("nvim-tutorial.txt")} /tmp/sisyphus-nvim-tutorial.txt
+tmux split-window -h "nvim /tmp/sisyphus-nvim-tutorial.txt"
 \`\`\`
 
-Walk them through:
-1. Open it: \`nvim /tmp/sisyphus-tutorial-test.txt\`
-2. Look around (they're in normal mode \u2014 arrow keys work for navigation)
-3. Close it: type \`ZZ\`
+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: "That's all you need. When you jump into a sisyphus agent's pane, you can use \`nvim\` to inspect files the agent is working on."
+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 open and close the file (or if they skipped).
+Ask if they were able to edit and save the file (or if they skipped).
 
 Proceed:
 \`\`\`
@@ -1862,13 +1990,75 @@ sisyphus getting-started --tutorial 3
 `);
 }
 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 {
+      rightOptionKeyStatus = `incorrect:${result.incorrectProfiles.join(",")}`;
+    }
+  }
   console.log(`
 <claude-instructions>
 # Sisyphus Getting Started \u2014 Step 3: Sisyphus Concepts & Keybinds
 
+## Environment Data
+- rightOptionKeyStatus: ${rightOptionKeyStatus}
+
 ## Instructions for Claude
 
-### 1. Explain the session model
+### 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:
 
@@ -1876,7 +2066,7 @@ 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  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
@@ -1890,40 +2080,36 @@ Key points:
 - Your session stays clean \u2014 you get a **dashboard** for monitoring
 - You can jump between your session and the sisyphus session to observe
 
-### 2. Teach keybinds
+### 3. Teach keybinds
 
-Two keybinds to remember:
+Two keybinds to remember (both use the RIGHT Option key):
 
 | Keybind | Action |
 |---------|--------|
-| \`M-s\` (Option+s) | Cycle through sisyphus sessions |
-| \`M-S\` (Option+Shift+s) | Jump back to dashboard |
-
-"M" means "Meta" which is the Option key on macOS. So \`M-s\` = hold Option, press s.
+| Right Option + s | Cycle through sisyphus sessions |
+| Right Option + Shift + s | Jump back to dashboard |
 
-### 3. Verify keybinds are installed
+### 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 either is missing, run: \`sisyphus setup-keybind\`
+If cycle script or keybind is missing, run: \`sisyphus setup-keybind\`
 
-### 4. Test the keybind
+### 5. Test the keybind
 
-Have the user try pressing \`Option+s\`. Nothing should happen yet (no sisyphus session running) \u2014 and that's fine. The important thing is it doesn't error.
+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 get a special character (like \xDF) instead of the keybind firing, explain:
-- Their terminal needs to send Option as Esc+ (Meta)
-- iTerm2: Settings \u2192 Profiles \u2192 Keys \u2192 Right Option Key \u2192 Esc+
-- Other terminals: look for "Meta key" or "Option sends" in preferences
+If they see \`\xDF\` or similar, circle back to the Right Option Key setup above.
 
-### 5. Verification
+### 6. Verification
 
 Confirm:
 - They understand the two-session model (their session vs sisyphus session)
-- \`sisyphus doctor\` shows keybinds installed
-- Option+s doesn't produce a special character
+- \`sisyphus doctor\` shows keybinds installed AND Right Option Key: Esc+
+- Right Option + s doesn't produce a special character
 
 Proceed:
 \`\`\`
@@ -1946,72 +2132,561 @@ This is the grand finale \u2014 a live demo session.
 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. Launch the demo
+### 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:
 
-Run this command:
+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):
 \`\`\`
-sisyphus start "Tutorial demo: explore this repository's structure, identify the main entry points, and write a brief summary of what each top-level directory contains" -c "This is a tutorial demo session. Be extra verbose in your planning and reports so the user watching can understand what's happening. Keep the scope small \u2014 2-3 agents max, 1-2 cycles."
+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"
 \`\`\`
 
-### 3. Walk through what's happening
+Tell the user:
 
-Guide the user through observing the session in real-time:
+> 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!
 
-**Step A: Dashboard**
-- The dashboard should auto-open. If not, run \`sisyphus dashboard\`
-- Point out: session status, cycle number, agent list
-- Tell them: "Watch the roadmap section \u2014 it updates as the orchestrator plans"
+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."
+\`\`\`
 
-**Step B: Jump to sisyphus session**
-- Have them press \`M-s\` (Option+s) to cycle to the sisyphus tmux session
-- They should see the orchestrator (yellow) working \u2014 reading files, planning
-- Point out: "Each pane is a separate Claude instance working independently"
+After launching, tell them:
 
-**Step C: Jump back**
-- Press \`M-S\` (Option+Shift+s) to jump back to the dashboard
-- Or \`M-s\` to cycle through
+> 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.
 
-**Step D: Watch the lifecycle**
-- As agents spawn, they'll appear in both the dashboard and the sisyphus session
-- Agents submit reports when done
-- The orchestrator respawns each cycle with fresh context
-- Eventually the session completes
+Wait for them to confirm they're back, then start live commentary.
 
-### 4. After completion
+### 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":
 
-- Run \`sisyphus status\` to see the final state
-- Show them the session directory: \`ls .sisyphus/sessions/\` \u2192 find the session \u2192 show \`roadmap.md\`
-- Explain: "Every session creates a roadmap, agent reports, and logs \u2014 all in .sisyphus/sessions/"
+- 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>
 
-### 5. Congratulations!
+<top-level-files>
+${topLevelFiles || "(could not list)"}
+</top-level-files>
 
-Wrap up with:
+## Instructions for Claude
 
-> You've completed the Sisyphus tutorial! Here's what you learned:
-> - tmux basics (sessions, panes, navigation)
-> - How sisyphus creates separate sessions for orchestrator + agents
-> - How to monitor with the dashboard and keybinds
-> - What a real session lifecycle looks like
->
-> **Ready for real work?**
-> \`sisyphus start "your actual task here"\`
+### 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.**
 >
-> **Tips:**
-> - Write requirements in a file and reference them: \`sisyphus start "Implement @requirements.md"\`
-> - Monitor actively \u2014 agents can get stuck. Use the dashboard's \`m\` key to message the orchestrator.
-> - Check \`sisyphus --help\` for all commands.
+> 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];
+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-4)", parseInt).action((opts) => {
+  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 > 4 || Number.isNaN(step)) {
-        console.error(`Invalid tutorial step: ${opts.tutorial}. Must be 0-4.`);
+      if (step < 0 || step > 5 || Number.isNaN(step)) {
+        console.error(`Invalid tutorial step: ${opts.tutorial}. Must be 0-5.`);
         process.exit(1);
       }
       STEPS[step]();
@@ -2026,8 +2701,8 @@ function registerGettingStarted(program2) {
 }
 
 // src/cli/commands/init.ts
-import { existsSync as existsSync6, mkdirSync as mkdirSync4, writeFileSync as writeFileSync4 } from "fs";
-import { join as join6 } 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
 
@@ -2038,9 +2713,9 @@ 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 = join6(cwd, ".sisyphus");
-    const configPath = join6(sisDir, "config.json");
-    if (existsSync6(configPath)) {
+    const sisDir = join7(cwd, ".sisyphus");
+    const configPath = join7(sisDir, "config.json");
+    if (existsSync7(configPath)) {
       console.log(`Already initialized: ${configPath}`);
       return;
     }
@@ -2048,8 +2723,8 @@ function registerInit(program2) {
     writeFileSync4(configPath, JSON.stringify(DEFAULT_CONFIG, null, 2) + "\n", "utf-8");
     console.log(`Created ${configPath}`);
     if (opts.orchestrator) {
-      const orchPath = join6(sisDir, "orchestrator.md");
-      if (!existsSync6(orchPath)) {
+      const orchPath = join7(sisDir, "orchestrator.md");
+      if (!existsSync7(orchPath)) {
         writeFileSync4(orchPath, ORCHESTRATOR_TEMPLATE, "utf-8");
         console.log(`Created ${orchPath}`);
       }
@@ -2064,10 +2739,10 @@ function registerInit(program2) {
 }
 
 // src/cli/commands/setup.ts
-import { execSync as execSync8 } from "child_process";
+import { execSync as execSync10 } from "child_process";
 function getTmuxVersion() {
   try {
-    return execSync8("tmux -V", { encoding: "utf-8", stdio: "pipe" }).trim();
+    return execSync10("tmux -V", { encoding: "utf-8", stdio: "pipe" }).trim();
   } catch {
     return "installed";
   }
@@ -2160,7 +2835,7 @@ if (nodeVersion < 22) {
 var program = new Command();
 program.name("sisyphus").description("tmux-integrated orchestration daemon for Claude Code").version(
   JSON.parse(
-    readFileSync5(join7(dirname3(fileURLToPath3(import.meta.url)), "..", "package.json"), "utf-8")
+    readFileSync5(join8(dirname4(fileURLToPath4(import.meta.url)), "..", "package.json"), "utf-8")
   ).version
 );
 program.configureHelp({
@@ -2203,7 +2878,7 @@ 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", "setup", "uninstall", "--version", "-V"];
-if (!existsSync7(globalDir()) && firstArg && !skipWelcome.includes(firstArg)) {
+if (!existsSync8(globalDir()) && firstArg && !skipWelcome.includes(firstArg)) {
   mkdirSync5(globalDir(), { recursive: true });
   console.log("");
   console.log("  Welcome to Sisyphus. Run 'sisyphus setup' to get started.");