elliot-stack 1.0.18 → 1.0.20

package/README.md

@@ -56,6 +56,17 @@ npx elliot-stack@latest
 
 External contributions are welcome via pull request. Direct pushes to `main` are blocked — fork the repo, push your changes to a branch, and open a PR. Only the maintainer (Elliot) can merge to `main` and cut releases. This is intentional: `elliot-stack` is a security-sensitive npm package and the release tag can only be pushed by the maintainer.
 
+### Testing locally
+
+Run the installer straight from your checkout to preview what a real install would do to your `~/.claude/`:
+
+```bash
+node bin/install.cjs            # dry run — previews changes, writes nothing
+node bin/install.cjs --install  # actually sync your local edits to ~/.claude/skills/
+```
+
+Run from the repo, the installer **dry-runs by default** so testing never clobbers your live `~/.claude/skills/` install. Pass `--install` once the preview looks right. (`--dry-run` forces a preview even under `npx`.)
+
 See [`docs/publishing.md`](docs/publishing.md) for the release flow and security model.
 
 ## License

package/bin/install.cjs

@@ -21,6 +21,19 @@ const PACKAGE_HOOKS_DIR = path.join(__dirname, '..', 'hooks');
 // ── Flags ──────────────────────────────────────────────────────────────────
 const SILENT = process.argv.includes('--silent');
 const STARTUP = process.argv.includes('--startup');
+// When run directly from the repo (not via npx/node_modules), default to dry-run
+// so local testing never silently clobbers the live ~/.claude/skills install.
+// Pass --install to actually write files, or --dry-run to force preview mode.
+const IS_LOCAL = !__dirname.includes('node_modules');
+const DRY_RUN = process.argv.includes('--dry-run') ||
+  (IS_LOCAL && !process.argv.includes('--install'));
+
+// ── Deprecated skills ──────────────────────────────────────────────────────
+// Skills that were renamed or removed. The installer removes these on every
+// run so users don't end up with both the old and new name installed.
+const DEPRECATED_SKILLS = [
+  'estack-prompt-builder', // renamed to estack-prompt-builder-coach
+];
 
 // ── Helpers ────────────────────────────────────────────────────────────────
 
@@ -44,7 +57,8 @@ function walkDir(dir, base) {
 function computeFileHash(filePath) {
   if (!fs.existsSync(filePath)) return null;
   const hash = crypto.createHash('sha256');
-  hash.update(fs.readFileSync(filePath));
+  const raw = fs.readFileSync(filePath);
+  hash.update(Buffer.from(raw.toString('utf8').replace(/\r\n/g, '\n')));
   return hash.digest('hex');
 }
 
@@ -54,9 +68,9 @@ function computeSkillHash(skillDir) {
   const files = walkDir(skillDir, skillDir);
   for (const relPath of files) {
     const fullPath = path.join(skillDir, relPath);
-    const contents = fs.readFileSync(fullPath);
+    const raw = fs.readFileSync(fullPath);
     hash.update(relPath.replace(/\\/g, '/'));
-    hash.update(contents);
+    hash.update(Buffer.from(raw.toString('utf8').replace(/\r\n/g, '\n')));
   }
   return hash.digest('hex');
 }
@@ -137,7 +151,9 @@ function getSkillDescription(skillDir) {
 
 // ── Hook setup ─────────────────────────────────────────────────────────────
 
-function setupStartupHook() {
+// Returns true if the hook was added (or would be added in dryRun), false if
+// it was already configured. In dryRun mode nothing is written to disk.
+function setupStartupHook(dryRun) {
   let settings = {};
   if (fs.existsSync(SETTINGS_FILE)) {
     try {
@@ -160,6 +176,8 @@ function setupStartupHook() {
     }
   }
 
+  if (dryRun) return true;
+
   if (!settings.hooks) settings.hooks = {};
   if (!settings.hooks.SessionStart) settings.hooks.SessionStart = [];
 
@@ -181,7 +199,9 @@ function setupStartupHook() {
   return true;
 }
 
-function setupRepoSearchNudgeHook() {
+// Returns true if the hook was added (or would be added in dryRun), false if
+// it was already configured. In dryRun mode nothing is written to disk.
+function setupRepoSearchNudgeHook(dryRun) {
   let settings = {};
   if (fs.existsSync(SETTINGS_FILE)) {
     try {
@@ -203,6 +223,8 @@ function setupRepoSearchNudgeHook() {
     }
   }
 
+  if (dryRun) return true;
+
   if (!settings.hooks) settings.hooks = {};
   if (!settings.hooks.PostToolUse) settings.hooks.PostToolUse = [];
 
@@ -223,6 +245,29 @@ function setupRepoSearchNudgeHook() {
 // ── Main ────────────────────────────────────────────────────────────────────
 
 async function main() {
+  // 0. Remove deprecated skills (renamed/deleted from the package)
+  if (fs.existsSync(SKILLS_DIR)) {
+    const newChecksums0 = fs.existsSync(CHECKSUMS_FILE)
+      ? (() => { try { return JSON.parse(fs.readFileSync(CHECKSUMS_FILE, 'utf8')); } catch (_) { return {}; } })()
+      : {};
+    let changed = false;
+    for (const name of DEPRECATED_SKILLS) {
+      const dir = path.join(SKILLS_DIR, name);
+      if (fs.existsSync(dir)) {
+        if (!DRY_RUN) fs.rmSync(dir, { recursive: true, force: true });
+        delete newChecksums0[name];
+        changed = true;
+        if (!SILENT && !STARTUP) {
+          console.log((DRY_RUN ? '  [dry run] Would remove deprecated skill: ' : '  Removed deprecated skill: ') + name);
+        }
+      } else if (newChecksums0[name]) {
+        delete newChecksums0[name];
+        changed = true;
+      }
+    }
+    if (changed && !DRY_RUN) fs.writeFileSync(CHECKSUMS_FILE, JSON.stringify(newChecksums0, null, 2));
+  }
+
   // 1. Scan package skills
   if (!fs.existsSync(PACKAGE_SKILLS_DIR)) {
     if (!SILENT && !STARTUP) {
@@ -287,7 +332,7 @@ async function main() {
     } else if (currentHash !== storedChecksums[name]) {
       // Stored checksum exists but current doesn't match — user modified it
       modifiedSkills.push(name);
-      if (storedChecksums[name] !== packageHashes[name]) {
+      if (currentHash !== packageHashes[name]) {
         needsUpdate.push(name);
       }
     } else if (currentHash !== packageHashes[name]) {
@@ -467,32 +512,39 @@ async function main() {
         console.log('    - ' + filename);
       }
     }
-    console.log('\nChoose an action:');
-    console.log('  [o] Overwrite all (replace with latest)');
-    console.log('  [s] Skip all (keep local versions)');
-    console.log('  [m] Merge (backup local, install new, merge in Claude Code)');
-    console.log('  [a] Abort (cancel installation)');
-    console.log('');
 
-    const answer = await promptChar('Your choice (o/s/m/a): ');
-
-    if (answer === 'a') {
-      console.log('Installation aborted.');
-      process.exit(0);
-    } else if (answer === 's') {
-      modifiedAction = 'skip';
-    } else if (answer === 'm') {
-      modifiedAction = 'merge';
-    } else if (answer === 'o') {
+    if (DRY_RUN) {
+      console.log('\n[dry run] Would prompt: overwrite / skip / merge / abort');
+      console.log('[dry run] Showing what would happen with default overwrite...');
       modifiedAction = 'overwrite';
     } else {
-      console.log('Invalid choice. Installation aborted.');
-      process.exit(1);
+      console.log('\nChoose an action:');
+      console.log('  [o] Overwrite all (replace with latest)');
+      console.log('  [s] Skip all (keep local versions)');
+      console.log('  [m] Merge (backup local, install new, merge in Claude Code)');
+      console.log('  [a] Abort (cancel installation)');
+      console.log('');
+
+      const answer = await promptChar('Your choice (o/s/m/a): ');
+
+      if (answer === 'a') {
+        console.log('Installation aborted.');
+        process.exit(0);
+      } else if (answer === 's') {
+        modifiedAction = 'skip';
+      } else if (answer === 'm') {
+        modifiedAction = 'merge';
+      } else if (answer === 'o') {
+        modifiedAction = 'overwrite';
+      } else {
+        console.log('Invalid choice. Installation aborted.');
+        process.exit(1);
+      }
     }
   }
 
   // 8. Install skills
-  fs.mkdirSync(SKILLS_DIR, { recursive: true });
+  if (!DRY_RUN) fs.mkdirSync(SKILLS_DIR, { recursive: true });
   const newChecksums = Object.assign({}, storedChecksums);
   let installedCount = 0;
   const mergedSkills = [];
@@ -506,23 +558,29 @@ async function main() {
         continue;
       }
       if (modifiedAction === 'merge') {
-        backupSkill(name);
+        if (!DRY_RUN) backupSkill(name);
         mergedSkills.push(name);
-        console.log('  Backed up ' + name + ' → ~/.claude/.estack-backup/' + name);
+        console.log((DRY_RUN ? '  [dry run] Would back up ' : '  Backed up ') + name + ' → ~/.claude/.estack-backup/' + name);
       }
       // overwrite or merge — fall through to install
     } else if (!needsUpdate.includes(name) && fs.existsSync(path.join(SKILLS_DIR, name))) {
       // Already installed and up-to-date
+      if (DRY_RUN) console.log('  [dry run] Up to date (no change): ' + name);
       continue;
     }
-    copyDir(path.join(PACKAGE_SKILLS_DIR, name), path.join(SKILLS_DIR, name));
+    const isUpdate = fs.existsSync(path.join(SKILLS_DIR, name));
+    if (!DRY_RUN) copyDir(path.join(PACKAGE_SKILLS_DIR, name), path.join(SKILLS_DIR, name));
     newChecksums[name] = packageHashes[name];
     installedCount++;
-    console.log('  Installed ' + name);
+    if (DRY_RUN) {
+      console.log('  [dry run] Would ' + (isUpdate ? 'update ' : 'install ') + name);
+    } else {
+      console.log('  Installed ' + name);
+    }
   }
 
   // 8b. Install hooks
-  fs.mkdirSync(HOOKS_DIR, { recursive: true });
+  if (!DRY_RUN) fs.mkdirSync(HOOKS_DIR, { recursive: true });
   let installedHookCount = 0;
   const mergedHooks = [];
 
@@ -535,33 +593,48 @@ async function main() {
         continue;
       }
       if (modifiedAction === 'merge') {
-        backupHook(filename);
+        if (!DRY_RUN) backupHook(filename);
         mergedHooks.push(filename);
-        console.log('  Backed up hook ' + filename + ' → ~/.claude/.estack-backup/hooks/' + filename);
+        console.log((DRY_RUN ? '  [dry run] Would back up hook ' : '  Backed up hook ') + filename + ' → ~/.claude/.estack-backup/hooks/' + filename);
       }
       // overwrite or merge — fall through to install
     } else if (!hooksNeedingUpdate.includes(filename) && fs.existsSync(path.join(HOOKS_DIR, filename))) {
       // Already installed and up-to-date
+      if (DRY_RUN) console.log('  [dry run] Up to date (no change): hook ' + filename);
       continue;
     }
-    fs.copyFileSync(path.join(PACKAGE_HOOKS_DIR, filename), path.join(HOOKS_DIR, filename));
+    const isHookUpdate = fs.existsSync(path.join(HOOKS_DIR, filename));
+    if (!DRY_RUN) fs.copyFileSync(path.join(PACKAGE_HOOKS_DIR, filename), path.join(HOOKS_DIR, filename));
     newChecksums['hook:' + filename] = packageHookHashes[filename];
     installedHookCount++;
-    console.log('  Installed hook ' + filename);
+    if (DRY_RUN) {
+      console.log('  [dry run] Would ' + (isHookUpdate ? 'update hook ' : 'install hook ') + filename);
+    } else {
+      console.log('  Installed hook ' + filename);
+    }
   }
 
   // 9. Write checksums
-  fs.writeFileSync(CHECKSUMS_FILE, JSON.stringify(newChecksums, null, 2));
+  if (!DRY_RUN) fs.writeFileSync(CHECKSUMS_FILE, JSON.stringify(newChecksums, null, 2));
 
   // 10. Setup startup hook and repo-search nudge hook
-  const hookInstalled = setupStartupHook();
-  const nudgeHookInstalled = setupRepoSearchNudgeHook();
+  // In dry-run these inspect settings.json read-only and report would-be action.
+  const hookInstalled = setupStartupHook(DRY_RUN);
+  const nudgeHookInstalled = setupRepoSearchNudgeHook(DRY_RUN);
 
   // 11. Summary output
-  console.log('\nestack installed successfully!\n');
-  console.log('  ' + installedCount + ' skill' + (installedCount !== 1 ? 's' : '') + ' installed to ~/.claude/skills/');
-  if (installedHookCount > 0) {
-    console.log('  ' + installedHookCount + ' hook' + (installedHookCount !== 1 ? 's' : '') + ' installed to ~/.claude/hooks/');
+  if (DRY_RUN) {
+    console.log('\n[dry run] No files were changed. Run with --install to apply.\n');
+    console.log('  ' + installedCount + ' skill' + (installedCount !== 1 ? 's' : '') + ' would be installed/updated in ~/.claude/skills/');
+    if (installedHookCount > 0) {
+      console.log('  ' + installedHookCount + ' hook' + (installedHookCount !== 1 ? 's' : '') + ' would be installed/updated in ~/.claude/hooks/');
+    }
+  } else {
+    console.log('\nestack installed successfully!\n');
+    console.log('  ' + installedCount + ' skill' + (installedCount !== 1 ? 's' : '') + ' installed to ~/.claude/skills/');
+    if (installedHookCount > 0) {
+      console.log('  ' + installedHookCount + ' hook' + (installedHookCount !== 1 ? 's' : '') + ' installed to ~/.claude/hooks/');
+    }
   }
   console.log('');
   console.log('Skills available:');
@@ -582,15 +655,27 @@ async function main() {
     console.log('Backed up to ~/.claude/.estack-backup/hooks/');
   }
 
-  if (hookInstalled) {
-    console.log('\nAuto-update hook added to ~/.claude/settings.json');
-    console.log('Skills will update automatically when you start Claude Code.');
+  if (DRY_RUN) {
+    if (hookInstalled) {
+      console.log('\n[dry run] Would add auto-update hook to ~/.claude/settings.json');
+    } else {
+      console.log('\nAuto-update hook already configured (no change).');
+    }
+    if (nudgeHookInstalled) {
+      console.log('[dry run] Would register repo-search nudge hook in settings.json.');
+    } else {
+      console.log('Repo-search nudge hook already configured (no change).');
+    }
   } else {
-    console.log('\nAuto-update hook already configured.');
-  }
-
-  if (nudgeHookInstalled) {
-    console.log('Repo-search nudge hook registered in settings.json.');
+    if (hookInstalled) {
+      console.log('\nAuto-update hook added to ~/.claude/settings.json');
+      console.log('Skills will update automatically when you start Claude Code.');
+    } else {
+      console.log('\nAuto-update hook already configured.');
+    }
+    if (nudgeHookInstalled) {
+      console.log('Repo-search nudge hook registered in settings.json.');
+    }
   }
 
   console.log('');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elliot-stack",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "description": "Elliot's skill stack for Claude Code — install via npx elliot-stack@latest",
   "bin": {
     "elliot-stack": "bin/install.cjs"

package/skills/estack-read-claude-session-history/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: estack-read-claude-session-history
+description: (read-claude-session-history) Invoke for ANY task involving Claude Code session history, transcripts, or .jsonl files — this is the only way to read, parse, or search them; do not attempt to use Bash or Read on .jsonl directly. Use for: recovering context after /compact ("what were we doing before compact"), advisor response retrieval ("what did the advisor say"), subagent output collection ("get all subagent finals"), cross-project session search by keyword, session listing and triage, UUID and title lookup, resume-command generation, file-edit and tool-call forensics, session diff between two sessions or subagents, weekly work journal, day timeline of activity blocks and idle gaps, engagement/attention-time accounting (active vs elapsed time, break detection, parallel-chat-safe totals), recovering from .claude-backups after data loss, session count queries, and reading the last agent message before a crash or interrupt. Trigger phrases: "session history", "before compact", "what did claude do", "what did I work on", "search my sessions", "find that session", "what did the advisor say", "what did the agent edit", "from the backup", "list my sessions", "subagent outputs", "session journal", "resume previous", "which files did claude touch", "go back and look", "what did I do yesterday", "where did my day go", "timeline of my day", "how much time on", "how long did that actually take", "how much did I actually work", "active time", "time I spent".
+---
+
+# Read Claude Session History
+
+Search, read, recover, and compare Claude Code session history — across the current session, prior sessions, sibling subagents, all projects, and `.claude-backups` snapshots.
+
+Sessions are stored as `.jsonl` files. Reading them raw is hopeless: 1,000–5,000+ lines of dense JSON per session, 33+ project directories, hundreds of historical sessions. This skill wraps a single CLI that knows the entry schema and exposes ~20 modes.
+
+## Quick start
+
+```bash
+PY="C:\Users\2supe\.claude\skills\read-claude-session-history\scripts\read_transcript.py"
+
+# What was the last thing the agent said in this session?
+python "$PY" --file <current-session.jsonl> --mode last
+
+# Get a 6-line summary of any session (intent, last activity, edits, tool counts, subagent fanout)
+python "$PY" --file <session.jsonl> --mode brief
+
+# Recover what got cut off by the most recent /compact
+python "$PY" --file <session.jsonl> --mode pre-compact
+
+# Find a session by UUID prefix across all projects
+python "$PY" --mode lookup --uuid abc123de
+
+# Search every session in every project for a phrase
+python "$PY" --mode search --all-projects --query "supabase migration"
+
+# Pull subagent outputs from a fan-out investigation
+python "$PY" --file <parent.jsonl> --mode subagent-finals
+
+# Block-grouped timeline of a whole day across all sessions, with idle gaps
+python "$PY" --mode timeline --date yesterday
+
+# How much focused time did today actually consume? (your attention, not Claude's)
+python "$PY" --mode engagement --date today
+
+# Any mode as structured JSON for piping into the next step
+python "$PY" --mode list --project keel --since 7d --format json
+```
+
+## Time handling — READ THIS before doing anything with time
+
+**Every time the CLI displays is already the user's local time.** JSONL files store
+UTC; the script converts on output. Do NOT add or subtract timezone offsets
+yourself, do NOT cross-reference file mtimes to infer the timezone, and do NOT
+treat raw `"timestamp"` fields from a .jsonl (which ARE UTC) as comparable to CLI
+output. If you need a different zone, pass `--tz` (IANA name like
+`America/New_York`, `UTC`, or an offset like `-4`) — never convert manually.
+`--since/--until/--date` specs are interpreted in that same display timezone.
+
+## Decision tree
+
+```
+What are you trying to do?
+│
+├─ Read the current session / one specific session
+│  ├─ Last assistant message ──────────────────── --mode last
+│  ├─ All advisor responses ───────────────────── --mode advisor
+│  ├─ Content cut off by /compact ─────────────── --mode pre-compact
+│  ├─ Full human-readable dump ────────────────── --mode dump (size-aware)
+│  ├─ 6-line summary for triage ───────────────── --mode brief
+│  └─ Schema/structural diagnosis ─────────────── --mode debug
+│
+├─ Find a session I don't have the path for
+│  ├─ By UUID prefix ──────────────────────────── --mode lookup --uuid <prefix>
+│  ├─ By title or first prompt ────────────────── --mode find --title|--first-prompt
+│  └─ Generate a `claude --resume` command ───── --mode resume-cmd --uuid <prefix>
+│
+├─ Search content
+│  ├─ One session ─────────────────────────────── --mode search --file …
+│  ├─ One project ─────────────────────────────── --mode search --cwd …
+│  ├─ All projects ────────────────────────────── --mode search --all-projects
+│  └─ Filter to user msgs / tool-use inputs ──── --role user --in tool_use
+│
+├─ Forensics on a session
+│  ├─ Chronological tool-call log ────────────── --mode changelog
+│  ├─ Every file touched ─────────────────────── --mode file-edits
+│  └─ Every tool call (optionally filtered) ──── --mode tool-calls --tool Bash,Edit
+│
+├─ Subagent (fan-out) work
+│  ├─ List spawned subagents ─────────────────── --mode subagent-list
+│  ├─ Get every subagent's final message ─────── --mode subagent-finals
+│  └─ Forensics on one subagent ──────────────── --mode subagent-tools|subagent-files --subagent …
+│
+├─ Cross-cutting reporting
+│  ├─ "What did I do this week?" ──────────────── --mode journal --since 7d
+│  ├─ "What was I doing, when?" / day map ─────── --mode timeline --date yesterday
+│  ├─ "How long did X actually take ME?" ──────── --mode engagement --date … | --project … | --file …
+│  ├─ Count sessions matching a query ─────────── --mode count --query …
+│  └─ Resume where I left off in this project ─── --mode resume-prev --cwd …
+│
+└─ Compare two sessions or two sibling subagents
+   └─ Interleaved diff ──────────────────────── --mode diff --file-a … --file-b …  (or --subagents-of …)
+```
+
+## Quick reference
+
+| Mode | Required flags | Returns |
+|---|---|---|
+| `last` | `--file` | Last N assistant text outputs |
+| `advisor` | `--file` | All `advisor_tool_result` payloads |
+| `pre-compact` | `--file` | 40 exchanges before the most recent `/compact` |
+| `dump` | `--file` | Human-readable dump (auto-degrades on transcripts >5MB) |
+| `search` | `--query` + scope | Matches windowed for context (supports `--role`, `--in text|tool_use|thinking|all`) |
+| `debug` | `--file` | Entry/block type distributions + probes |
+| `brief` | `--file` | 6-line summary: uuid·project·mtime·status / intent / last / edits / tools / subagents |
+| `list` | `--cwd` or `--all-projects` | Rich table: mtime, size, uuid, msg count, flags, status, title |
+| `lookup` | `--uuid <prefix>` | Absolute path (exit 1 missing, exit 2 ambiguous) |
+| `find` | `--title` or `--first-prompt` | Sessions ranked by recency |
+| `resume-cmd` | `--uuid <prefix>` | `cd <cwd>; claude --resume <uuid>` snippet |
+| `changelog` | `--file` | `HH:MM:SS  TOOL  one-line-summary`, day-grouped |
+| `file-edits` | `--file` | Unique paths sorted with op tags |
+| `tool-calls` | `--file` (+ `--tool` filter) | Timestamped per-call blocks |
+| `subagent-list` | `--file` | List sibling subagents with agentType + description |
+| `subagent-finals` | `--file` | Every subagent's final assistant message |
+| `subagent-tools` | `--subagent` | Forensics on one subagent |
+| `subagent-files` | `--subagent` | Files one subagent touched |
+| `resume-prev` | `--cwd` | Banner + dump-style tail of last 10 exchanges |
+| `count` | `--query` (+ scope) | `<N>` to stdout, summary to stderr |
+| `journal` | `--since` (+ scope) | Per-session 5-line block: date·uuid / prompt / ended / edits / tools |
+| `timeline` | `--date` or `--since/--until` (defaults: today, all projects) | Map of WHAT was active WHEN: blocks + idle gaps (no attention claim — that's `engagement`) |
+| `engagement` | `--date` or `--since/--until` or `--file` (defaults: today, all projects) | YOUR attention time: active vs elapsed + ratio per session, parallel-chat-safe totals, breaks |
+| `diff` | `--file-a` + `--file-b` OR `--subagents-of` | Timestamp-interleaved A>/B> output |
+
+## Global flags
+
+- `--root {live|mirror|snapshot-24h|snapshot-1w|snapshot-1mo|<abs-path>}` — read from a `.claude-backups` mirror or snapshot instead of live. Default `live`.
+- `--cwd <path>` — single-project scope. Use the original working directory (e.g. `"C:\Users\2supe\Other Claude Code"`).
+- `--all-projects` — walk every project under `--root`.
+- `--project <name>` — filter projects by name substring, case-insensitive, matches encoded or decoded form (`--project keel`, `--project "Other Claude Code"`). Works on `list`, `journal`, `search`, `count`, `find`, `timeline`, `engagement`. Use this instead of `--cwd` when you know the project's name but not its exact path. (Note: for `engagement`, scope filters which sessions are *reported* — the attention stream is always computed across all projects so parallel chats never double-count.)
+- `--file <path>` — single-session scope.
+- `--since <spec>` / `--until <spec>` — accepts ISO date, ISO datetime, relative (`30m`, `24h`, `7d`, `1w`, `1mo`), named (`today`, `yesterday`, `now`).
+- `--date <spec>` — single-day window for `timeline` (`--date yesterday`, `--date 2026-06-01`).
+- `--gap <spec>` — idle-gap threshold for `timeline` blocks (`15m` default, `1h`).
+- `--break <spec>` — break threshold for `engagement` (`10m` default; `5m` strict, `20m` forgiving). Gaps between your prompts longer than this count as breaks unless you replied right after Claude finished working.
+- `--tz <spec>` — display timezone override (IANA name, `UTC`, or offset like `-4`). Default: system local time.
+- `--format json` (or `--json`) — structured JSON output on every mode (except the legacy `--list`/`--list-subagents` aliases). Pipe-friendly: paths are strings, timestamps ISO.
+- `--exclude-current` — drop the current session (detected via `CLAUDE_SESSION_ID`) from `list`, `journal`, `search`, `count`, `timeline`, and `engagement`.
+- `--include-subagents` — fold subagent finals into `brief`, `last`, `dump` output, each tagged `[subagent <id-short> · <agentType>]`.
+- `--force-dump` — bypass the 5 MB `dump` guard.
+- `-n N` — count modifier (default 5 for `last`, 80 for `dump`, 10 for `resume-prev`).
+
+The current session is marked with `[*]` in `list` output. Status glyphs: ✓ clean, ! interrupted, ? pending-user, ● active. Sessions with a compact marker get `[C]`; sessions with subagents get `[S]`.
+
+## Backup-aware reads
+
+In March 2026 a Claude Code auto-update deleted live `.jsonl` transcripts (GitHub #41591). To survive that class of incident, this machine maintains four backup roots under `C:\Users\2supe\.claude-backups\`:
+
+- `mirror` — continuous mirror
+- `snapshot-24h` — 24-hour-old snapshot
+- `snapshot-1w` — 1-week-old snapshot
+- `snapshot-1mo` — 1-month-old snapshot
+
+Any mode accepts `--root <name>`. The resolved root is printed to stderr.
+
+```bash
+# Find a session that was deleted from live but still in yesterday's snapshot
+python "$PY" --root snapshot-24h --mode lookup --uuid <prefix>
+
+# Compare today's mirror against a week ago to confirm what was lost
+python "$PY" --root snapshot-1w --cwd "C:\Users\2supe\Other Claude Code" --list
+```
+
+See `references/recipes.md` → "Deletion-incident recovery" for the full playbook.
+
+## Common workflows
+
+| Need | Command |
+|---|---|
+| Recover advisor output that scrolled out of context | `--file <session> --mode advisor` |
+| Get back to what you were doing before `/compact` | `--file <session> --mode pre-compact` |
+| Fan-out triage: 14 subagents, want all of their finals | `--file <parent> --mode subagent-finals` (or `--mode brief --include-subagents`) |
+| Find "that session where I asked about supabase rate limits" | `--mode search --all-projects --query "supabase rate limits"` |
+| Resume a project after a few days away | `--mode resume-prev --cwd "<project path>"` |
+| Daily/weekly journal | `--mode journal --since 7d --all-projects` |
+| "Where did yesterday go?" (map of activity) | `--mode timeline --date yesterday` |
+| "How much did I actually work today?" | `--mode engagement --date today` |
+| "How much time on Keel today?" | `--mode engagement --project keel --date today` |
+| "How long did that session take me?" | `--mode engagement --file <session.jsonl>` |
+| Feed session data into a script | any mode + `--format json` |
+
+See `references/recipes.md` for fuller multi-step workflows.
+
+## Windows notes
+
+- Use `python` (not `python3`) on this Windows setup.
+- The script handles UTF-8 stdout/stderr internally — both PowerShell and Bash work fine for single commands.
+- **Piping `--format json` into another command: use Bash.** PowerShell 5.1 pipes inject a UTF-8 BOM and re-encode through the console codepage, breaking `json.load` (see `references/recipes.md` §5c for the PowerShell workaround).
+- File paths with spaces need quoting: `--cwd "C:\Users\2supe\Other Claude Code"`.
+
+## Reference docs
+
+- `references/modes.md` — complete per-mode reference (every flag, every example, exit codes).
+- `references/jsonl-schema.md` — entry/block schema, subagent meta sidecars, compact-marker shape.
+- `references/recipes.md` — multi-step workflows (post-compact recovery, find-then-dump, deletion recovery, week-in-review journal, sibling-agent diff).
+
+## When the modes return empty
+
+If a mode returns empty/unexpected output, run `--mode debug` first. It prints the entry-type distribution, content-block types, and probes for advisor + compact markers — useful when the transcript schema has drifted or when a session was truncated.