diff --git a/.claude/.gitignore b/.claude/.gitignore
new file mode 100644
index 0000000..d884526
--- /dev/null
+++ b/.claude/.gitignore
@@ -0,0 +1,2 @@
+# Backup files
+*.bak
diff --git a/.claude/scripts/tbd-session.sh b/.claude/scripts/tbd-session.sh
new file mode 100755
index 0000000..ab249be
--- /dev/null
+++ b/.claude/scripts/tbd-session.sh
@@ -0,0 +1,77 @@
+#!/bin/bash
+# Ensure tbd CLI is installed and run tbd prime for Claude Code sessions
+# Installed by: tbd setup --auto
+# This script runs on SessionStart and PreCompact
+
+# Get npm global bin directory (if npm is available)
+NPM_GLOBAL_BIN=""
+if command -v npm &> /dev/null; then
+    NPM_PREFIX=$(npm config get prefix 2>/dev/null)
+    if [ -n "$NPM_PREFIX" ] && [ -d "$NPM_PREFIX/bin" ]; then
+        NPM_GLOBAL_BIN="$NPM_PREFIX/bin"
+    fi
+fi
+
+# Add common binary locations to PATH (persists for entire script)
+# Include npm global bin if found
+export PATH="$NPM_GLOBAL_BIN:$HOME/.local/bin:$HOME/bin:/usr/local/bin:$PATH"
+
+# Function to ensure tbd is available
+ensure_tbd() {
+    # Check if tbd is already installed
+    if command -v tbd &> /dev/null; then
+        return 0
+    fi
+
+    echo "[tbd] CLI not found, installing..."
+
+    # Try npm first (most common for Node.js tools)
+    if command -v npm &> /dev/null; then
+        echo "[tbd] Installing via npm..."
+        npm install -g get-tbd 2>/dev/null || {
+            # If global install fails (permissions), try local install
+            echo "[tbd] Global npm install failed, trying user install..."
+            mkdir -p ~/.local/bin
+            npm install --prefix ~/.local get-tbd
+            # Create symlink if needed
+            if [ -f ~/.local/node_modules/.bin/tbd ]; then
+                ln -sf ~/.local/node_modules/.bin/tbd ~/.local/bin/tbd
+            fi
+        }
+    elif command -v pnpm &> /dev/null; then
+        echo "[tbd] Installing via pnpm..."
+        pnpm add -g get-tbd
+    elif command -v yarn &> /dev/null; then
+        echo "[tbd] Installing via yarn..."
+        yarn global add get-tbd
+    else
+        echo "[tbd] ERROR: No package manager found (npm, pnpm, or yarn required)"
+        echo "[tbd] Please install Node.js and npm, then run: npm install -g get-tbd"
+        return 1
+    fi
+
+    # Verify installation
+    if command -v tbd &> /dev/null; then
+        echo "[tbd] Successfully installed to $(which tbd)"
+        return 0
+    else
+        echo "[tbd] WARNING: tbd installed but not found in PATH"
+        echo "[tbd] Checking common locations..."
+        # Try to find and add to path (include npm global bin)
+        for dir in "$NPM_GLOBAL_BIN" ~/.local/bin ~/.local/node_modules/.bin /usr/local/bin; do
+            if [ -n "$dir" ] && [ -x "$dir/tbd" ]; then
+                export PATH="$dir:$PATH"
+                echo "[tbd] Found at $dir/tbd"
+                return 0
+            fi
+        done
+        echo "[tbd] Could not locate tbd after installation"
+        return 1
+    fi
+}
+
+# Main
+ensure_tbd || exit 1
+
+# Run tbd prime with any passed arguments (e.g., --brief for PreCompact)
+tbd prime "$@"
diff --git a/.claude/settings.json b/.claude/settings.json
index f3bfe80..2e33638 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -10,6 +10,15 @@
             "timeout": 120
           }
         ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/scripts/tbd-session.sh"
+          }
+        ]
       }
     ],
     "PostToolUse": [
@@ -22,6 +31,17 @@
           }
         ]
       }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/scripts/tbd-session.sh --brief"
+          }
+        ]
+      }
     ]
   }
 }
diff --git a/.claude/skills/tbd/SKILL.md b/.claude/skills/tbd/SKILL.md
index 91441f8..38f184e 100644
--- a/.claude/skills/tbd/SKILL.md
+++ b/.claude/skills/tbd/SKILL.md
@@ -1,128 +1,254 @@
 ---
-name: tbd
-description: Lightweight, git-native issue tracking (aka beads) for AI agents. Use for creating, planning, updating, and tracking issues with dependencies. Invoke when user mentions tbd, beads, to-do lists, planning, tracking tasks, issues, or bugs.
 allowed-tools: Bash(tbd:*), Read, Write
+description: |-
+  Git-native issue tracking (beads), coding guidelines, knowledge injection, and spec-driven planning for AI agents. Drop-in replacement for bd/Beads with simpler architecture.
+  Use for: tracking issues/beads with dependencies, creating bugs/features/tasks, planning specs, implementing features from specs, code reviews, committing code, creating PRs, loading coding guidelines (TypeScript, Python, TDD, golden testing, Convex, monorepo patterns), code cleanup, research briefs, architecture docs, agent handoffs, and checking out third-party library source code.
+  Invoke when user mentions: tbd, beads, bd, shortcuts, issues, bugs, tasks, features, epics, todo, tracking, specs, planning, implementation, validation, guidelines, templates, commit, PR, pull request, code review, testing, TDD, test-driven, golden testing, snapshot testing, TypeScript, Python, Convex, monorepo, cleanup, dead code, refactor, handoff, research, architecture, labels, search, checkout library, source code review, or any workflow shortcut.
+name: tbd
 ---
-# tbd Workflow
-
-`tbd` provides lightweight, git-native task and issue tracking using beads, which are
-just lightweight issues managed from the CLI.
+<!-- DO NOT EDIT: Generated by tbd setup.
+Run 'tbd setup' to update.
+-->
 
-> **Context Recovery**: Run `tbd prime` after compaction, clear, or new session.
-> Hooks auto-call this in Claude Code when .tbd/ detected.
+---
+title: tbd Workflow
+description: Full tbd workflow guide for agents
+---
+**`tbd` helps humans and agents ship code with greater speed, quality, and discipline.**
 
-# SESSION CLOSING PROTOCOL
+1. **Beads**: Git-native issue tracking (tasks, bugs, features).
+   Never lose work across sessions.
+   Drop-in replacement for `bd`.
+2. **Spec-Driven Workflows**: Plan features → break into beads → implement
+   systematically.
+3. **Knowledge Injection**: 17+ engineering guidelines (TypeScript, Python, TDD,
+   testing, Convex, monorepos) available on demand.
+4. **Shortcuts**: Reusable instruction templates for common workflows (code review,
+   commits, PRs, cleanup, handoffs).
 
-**CRITICAL**: Before saying “done” or “complete”, you MUST run this checklist:
+## Installation
 
-```
-[ ] 1. Stage and commit: git add + git commit
-[ ] 2. Push to remote: git push
-[ ] 3. Start CI watch (BLOCKS until done): gh pr checks <PR> --watch 2>&1
-[ ] 4. While CI runs: tbd close/update <id> for issues worked on
-[ ] 5. While CI runs: tbd sync
-[ ] 6. Return to step 3 and CONFIRM CI passed
-[ ] 7. If CI failed: fix, re-push, restart from step 3
+```bash
+npm install -g get-tbd@latest
+tbd setup --auto --prefix=<name>   # Fresh project (--prefix is REQUIRED: 2-8 alphabetic chars recommended. ALWAYS ASK THE USER FOR THE PREFIX; do not guess it)
+tbd setup --auto                   # Existing tbd project (prefix already set)
+tbd setup --from-beads             # Migration from .beads/ if `bd` has been used
 ```
 
-## NON-NEGOTIABLE Requirements
+## Routine Commands
 
-### CI: Wait for `--watch` to finish
+```bash
+tbd --help    # Command reference
+tbd status    # Status
+tbd doctor    # If there are problems
 
-The `--watch` flag blocks until ALL checks complete.
-Do NOT see “passing” in early output and move on—wait for the **final summary** showing
-all checks passed.
+tbd setup --auto   # Run any time to refresh setup
+tbd prime      # Restore full context on tbd after compaction
+```
 
-### tbd: Update issues and sync
+## CRITICAL: You Operate tbd — The User Doesn’t
+
+**You are the tbd operator:** Users talk naturally; you translate their requests to tbd
+actions. DO NOT tell users to run tbd commands.
+That’s your job.
+
+- **WRONG**: "Run `tbd create` to track this bug"
+
+- **RIGHT**: *(you run `tbd create` yourself and tell the user it’s tracked)*
+
+**Welcoming a user:** When users ask “what is tbd?”
+or want help → run `tbd shortcut welcome-user`
+
+## User Request → Agent Action
+
+| User Says | You (the Agent) Run |
+| --- | --- |
+| **Issues/Beads** |  |
+| "There's a bug where ..." | `tbd create "..." --type=bug` |
+| "Create a task/feature for ..." | `tbd create "..." --type=task` or `--type=feature` |
+| "Let's work on issues/beads" | `tbd ready` |
+| "Show me issue X" | `tbd show <id>` |
+| "Close this issue" | `tbd close <id>` |
+| "Search issues for X" | `tbd search "X"` |
+| "Add label X to issue" | `tbd label add <id> <label>` |
+| "What issues are stale?" | `tbd stale` |
+| **Planning & Specs** |  |
+| "Plan a new feature" / "Create a spec" | `tbd shortcut new-plan-spec` |
+| "Break spec into beads" | `tbd shortcut plan-implementation-with-beads` |
+| "Implement these beads" | `tbd shortcut implement-beads` |
+| **Code Review & Commits** |  |
+| "Review this code" / "Code review" | `tbd shortcut review-code` |
+| "Review this PR" | `tbd shortcut review-github-pr` |
+| "Commit this" / "Use the commit shortcut" | `tbd shortcut code-review-and-commit` |
+| "Create a PR" / "File a PR" | `tbd shortcut create-or-update-pr-simple` |
+| "Merge main into my branch" | `tbd shortcut merge-upstream` |
+| **Guidelines & Knowledge** |  |
+| "Use TypeScript best practices" | `tbd guidelines typescript-rules` |
+| "Use Python best practices" | `tbd guidelines python-rules` |
+| "Build a TypeScript CLI" | `tbd guidelines typescript-cli-tool-rules` |
+| "Improve monorepo setup" | `tbd guidelines pnpm-monorepo-patterns` or `bun-monorepo-patterns` |
+| "Add golden/e2e testing" | `tbd guidelines golden-testing-guidelines` |
+| "Use TDD" / "Test-driven development" | `tbd guidelines general-tdd-guidelines` |
+| "Convex best practices" | `tbd guidelines convex-rules` |
+| **Documentation** |  |
+| "Research this topic" | `tbd shortcut new-research-brief` |
+| "Document architecture" | `tbd shortcut new-architecture-doc` |
+| **Cleanup & Maintenance** |  |
+| "Clean up this code" / "Remove dead code" | `tbd shortcut code-cleanup-all` |
+| "Fix repository problems" | `tbd doctor --fix` |
+| **Sessions & Handoffs** |  |
+| "Hand off to another agent" | `tbd shortcut agent-handoff` |
+| "Check out this library's source" | `tbd shortcut checkout-third-party-repo` |
+| *(your choice whenever appropriate)* | `tbd list`, `tbd dep add`, `tbd close`, `tbd sync`, etc. |
+
+## CRITICAL: Session Closing Protocol
+
+**Before saying “done”, you MUST complete this checklist:**
 
-Every session must end with tbd in a clean state:
-- Close/update **every issue** you worked on
-- Run `tbd sync` and confirm it completed
+```
+[ ] 1. git add + git commit
+[ ] 2. git push
+[ ] 3. gh pr checks <PR> --watch 2>&1 (IMPORTANT: WAIT for final summary, do NOT tell user it is done until you confirm it passes CI!)
+[ ] 4. tbd close/update <id> for all beads worked on
+[ ] 5. tbd sync
+[ ] 6. CONFIRM CI passed (if failed: fix, run tests, re-push, restart from step 3)
+```
 
 **Work is not done until pushed, CI passes, and tbd is synced.**
 
-## Core Rules
+## Bead Tracking Rules
 
-- Track *all task work* not being done immediately as beads using `tbd` (discovered
-  work, future work, TODOs for the session, multi-session work)
-- When in doubt, prefer tbd for tracking tasks, bugs, and issues
-- Use `tbd create` for creating beads
-- Git workflow: update or close issues and run `tbd sync` at session end
-- If not given specific directions, check `tbd ready` for available work
+- Track all task work not done immediately as beads (discovered work, TODOs,
+  multi-session work)
+- When in doubt, create a bead
+- Check `tbd ready` when not given specific directions
+- Always close/update beads and run `tbd sync` at session end
 
-## Essential Commands
+## Commands
 
 ### Finding Work
 
-- `tbd ready` - Show issues ready to work (no blockers)
-- `tbd list --status open` - All open issues
-- `tbd list --status in_progress` - Your active work
-- `tbd show <id>` - Detailed issue view with dependencies
+| Command | Purpose |
+| --- | --- |
+| `tbd ready` | Beads ready to work (no blockers) |
+| `tbd list --status open` | All open beads |
+| `tbd list --status in_progress` | Your active work |
+| `tbd show <id>` | Bead details with dependencies |
 
 ### Creating & Updating
 
-- `tbd create "title" --type task|bug|feature --priority P2` - New issue
-  - Priority: P0-P4 (P0=critical, P2=medium, P4=backlog).
-    Do NOT use "high"/"medium"/"low"
-- `tbd update <id> --status in_progress` - Claim work
-- `tbd update <id> --assignee username` - Assign to someone
-- `tbd close <id>` - Mark complete
-- `tbd close <id> --reason "explanation"` - Close with reason
-- **Tip**: When creating multiple issues, use parallel subagents for efficiency
-
-### Dependencies & Blocking
-
-- `tbd dep add <issue> <depends-on>` - Add dependency (issue depends on depends-on)
-- `tbd blocked` - Show all blocked issues
-- `tbd show <id>` - See what’s blocking/blocked by this issue
-
-### Sync & Collaboration
-
-- `tbd sync` - Sync with git remote (run at session end)
-- `tbd sync --status` - Check sync status without syncing
-
-Note: `tbd sync` handles all git operations for issues--no manual git push needed.
-
-### Project Health
-
-- `tbd stats` - Project statistics (open/closed/blocked counts)
-- `tbd doctor` - Check for issues (sync problems, missing hooks)
-
-## Common Workflows
-
-**Starting work:**
-
-```bash
-tbd ready                              # Find available work
-tbd show <id>                          # Review issue details
-tbd update <id> --status in_progress   # Claim it
-```
-
-**Completing work:**
-
-```bash
-tbd close <id>    # Mark complete
-tbd sync          # Push to remote
-```
-
-**Creating dependent work:**
-
-```bash
-tbd create "Implement feature X" --type feature
-tbd create "Write tests for X" --type task
-tbd dep add <tests-id> <feature-id>   # Tests depend on feature
-```
-
-## Setup Commands
-
-- `tbd setup claude` - Install Claude Code hooks and skill file
-- `tbd setup cursor` - Create Cursor IDE rules file
-- `tbd setup codex` - Create/update AGENTS.md for Codex
-- `tbd setup beads --disable` - Migrate from Beads to tbd
+| Command | Purpose |
+| --- | --- |
+| `tbd create "title" --type task\|bug\|feature --priority=P2` | New bead (P0-P4, not "high/medium/low") |
+| `tbd update <id> --status in_progress` | Claim work |
+| `tbd close <id> [--reason "..."]` | Mark complete |
+
+### Dependencies & Sync
+
+| Command | Purpose |
+| --- | --- |
+| `tbd dep add <bead> <depends-on>` | Add dependency |
+| `tbd blocked` | Show blocked beads |
+| `tbd sync` | Sync with git remote (run at session end) |
+| `tbd stats` | Project statistics |
+| `tbd doctor` | Check for problems |
+| `tbd doctor --fix` | Auto-fix repository problems |
+
+### Labels & Search
+
+| Command | Purpose |
+| --- | --- |
+| `tbd search <query>` | Search issues by text |
+| `tbd label add <id> <label>` | Add label to issue |
+| `tbd label remove <id> <label>` | Remove label from issue |
+| `tbd label list` | List all labels in use |
+| `tbd stale` | List issues not updated recently |
+
+### Documentation
+
+| Command | Purpose |
+| --- | --- |
+| `tbd shortcut <name>` | Run a shortcut |
+| `tbd shortcut --list` | List shortcuts |
+| `tbd guidelines <name>` | Load coding guidelines |
+| `tbd guidelines --list` | List guidelines |
+| `tbd template <name>` | Output a template |
 
 ## Quick Reference
 
-- **Priority levels**: 0=critical, 1=high, 2=medium (default), 3=low, 4=backlog
-- **Issue types**: task, bug, feature, epic
-- **Status values**: open, in_progress, closed
-- **JSON output**: Add `--json` to any command for machine-readable output
+- **Priority**: P0=critical, P1=high, P2=medium (default), P3=low, P4=backlog
+- **Types**: task, bug, feature, epic
+- **Status**: open, in_progress, closed
+- **JSON output**: Add `--json` to any command
+
+<!-- BEGIN SHORTCUT DIRECTORY -->
+## Available Shortcuts
+
+Run `tbd shortcut <name>` to use any of these shortcuts:
+
+| Name | Description |
+| --- | --- |
+| agent-handoff | Generate a concise handoff prompt for another coding agent to continue work |
+| checkout-third-party-repo | Get source code for libraries and third-party repos using git. Essential for reliable source code review. Prefer this to web searches or fetching of web pages from github.com as it is far more effective (github.com blocks web scraping from main website). |
+| code-cleanup-all | Full cleanup cycle including duplicate removal, dead code, and code quality improvements |
+| code-cleanup-docstrings | Review and add concise docstrings to major functions and types |
+| code-cleanup-tests | Review and remove tests that do not add meaningful coverage |
+| code-review-and-commit | Run pre-commit checks, review changes, and commit code |
+| coding-spike | Prototype to validate a spec through hands-on implementation |
+| create-or-update-pr-simple | Create or update a pull request with a concise summary |
+| create-or-update-pr-with-validation-plan | Create or update a pull request with a detailed test/validation plan |
+| implement-beads | Implement beads from a spec, following TDD and project rules |
+| merge-upstream | Merge origin/main into current branch with conflict resolution |
+| new-architecture-doc | Create an architecture document for a system or component design |
+| new-guideline | Create a new coding guideline document for tbd |
+| new-plan-spec | Create a new feature planning specification document |
+| new-research-brief | Create a research document for investigating a topic or technology |
+| new-shortcut | Create a new shortcut (reusable instruction template) for tbd |
+| new-validation-plan | Create a validation/test plan showing what's tested and what remains |
+| plan-implementation-with-beads | Create implementation beads from a feature planning spec |
+| precommit-process | Full pre-commit checklist including spec sync, code review, and testing |
+| review-code | Comprehensive code review for uncommitted changes, branch work, or GitHub PRs |
+| review-code-python | Python-focused code review (language-specific rules only) |
+| review-code-typescript | TypeScript-focused code review (language-specific rules only) |
+| review-github-pr | Review a GitHub pull request with follow-up actions (comment, fix, CI check) |
+| revise-all-architecture-docs | Comprehensive revision of all current architecture documents |
+| revise-architecture-doc | Update an architecture document to reflect current codebase state |
+| setup-github-cli | Ensure GitHub CLI (gh) is installed and working |
+| sync-failure-recovery | Handle tbd sync failures by saving to workspace and recovering later |
+| update-specs-status | Review active specs and sync their status with tbd issues |
+| welcome-user | Welcome message for users after tbd installation or setup |
+
+## Available Guidelines
+
+Run `tbd guidelines <name>` to apply any of these guidelines:
+
+| Name | Description |
+| --- | --- |
+| backward-compatibility-rules | Guidelines for maintaining backward compatibility across code, APIs, file formats, and database schemas |
+| bun-monorepo-patterns | Modern patterns for Bun-based TypeScript monorepo architecture |
+| cli-agent-skill-patterns | Best practices for building TypeScript CLIs that function as agent skills in Claude Code and other AI coding agents |
+| commit-conventions | Conventional Commits format with extensions for agentic workflows |
+| convex-limits-best-practices | Comprehensive reference for Convex platform limits, workarounds, and performance best practices |
+| convex-rules | Guidelines and best practices for building Convex projects, including database schema design, queries, mutations, and real-world examples |
+| electron-app-development-patterns | Guidelines for Electron development ecosystems including npm, pnpm, and Bun, with security baselines and framework comparisons |
+| error-handling-rules | Rules for handling errors, failures, and exceptional conditions |
+| general-coding-rules | Rules for constants, magic numbers, and general coding practices |
+| general-comment-rules | Language-agnostic rules for writing clean, maintainable comments |
+| general-eng-assistant-rules | Rules for AI assistants acting as senior engineers, including objectivity and communication guidelines |
+| general-style-rules | Style guidelines for auto-formatting, emoji usage, and output formatting |
+| general-tdd-guidelines | Test-Driven Development methodology and best practices |
+| general-testing-rules | Rules for writing minimal, effective tests with maximum coverage |
+| golden-testing-guidelines | Guidelines for implementing golden/snapshot testing for complex systems |
+| pnpm-monorepo-patterns | Modern patterns for pnpm-based TypeScript monorepo architecture |
+| python-cli-patterns | Modern patterns for Python CLI application architecture |
+| python-modern-guidelines | Guidelines for modern Python projects using uv, with a few more opinionated practices |
+| python-rules | General Python coding rules and best practices |
+| release-notes-guidelines | Guidelines for writing clear, accurate release notes |
+| tbd-sync-troubleshooting | Common issues and solutions for tbd sync and workspace operations |
+| typescript-cli-tool-rules | Rules for building CLI tools with Commander.js, picocolors, and TypeScript |
+| typescript-code-coverage | Best practices for code coverage in TypeScript with Vitest and v8 provider |
+| typescript-rules | TypeScript coding rules and best practices |
+| typescript-sorting-patterns | Deterministic sorting patterns and comparison chains for TypeScript |
+| typescript-yaml-handling-rules | Best practices for parsing and serializing YAML in TypeScript |
+
+<!-- END SHORTCUT DIRECTORY -->
diff --git a/.tbd/.gitignore b/.tbd/.gitignore
index 76d040f..ba9b282 100644
--- a/.tbd/.gitignore
+++ b/.tbd/.gitignore
@@ -9,3 +9,13 @@ data-sync/
 
 # Temporary files
 *.tmp
+
+# Synced documentation cache (regenerated by tbd sync --docs)
+docs/
+
+# Local state
+state.yml
+
+# Migration backups (local only, not synced)
+backups/
+*.temp
diff --git a/.tbd/config.yml b/.tbd/config.yml
index 550c56b..62f0a82 100644
--- a/.tbd/config.yml
+++ b/.tbd/config.yml
@@ -1,9 +1,89 @@
 display:
   id_prefix: try
+# Documentation cache configuration.
+# files: Maps destination paths (relative to .tbd/docs/) to source locations.
+#   Sources can be:
+#   - internal: prefix for bundled docs (e.g., "internal:shortcuts/standard/code-review-and-commit.md")
+#   - Full URL for external docs (e.g., "https://raw.githubusercontent.com/org/repo/main/file.md")
+# lookup_path: Search paths for doc lookup (like shell $PATH). Earlier paths take precedence.
+#
+# To sync docs: tbd sync --docs
+# To check status: tbd sync --status
+#
+# Auto-sync: Docs are automatically synced when stale (default: every 24 hours).
+# Configure with settings.doc_auto_sync_hours (0 = disabled).
+docs_cache:
+  files:
+    guidelines/backward-compatibility-rules.md: internal:guidelines/backward-compatibility-rules.md
+    guidelines/bun-monorepo-patterns.md: internal:guidelines/bun-monorepo-patterns.md
+    guidelines/cli-agent-skill-patterns.md: internal:guidelines/cli-agent-skill-patterns.md
+    guidelines/commit-conventions.md: internal:guidelines/commit-conventions.md
+    guidelines/convex-limits-best-practices.md: internal:guidelines/convex-limits-best-practices.md
+    guidelines/convex-rules.md: internal:guidelines/convex-rules.md
+    guidelines/electron-app-development-patterns.md: internal:guidelines/electron-app-development-patterns.md
+    guidelines/error-handling-rules.md: internal:guidelines/error-handling-rules.md
+    guidelines/general-coding-rules.md: internal:guidelines/general-coding-rules.md
+    guidelines/general-comment-rules.md: internal:guidelines/general-comment-rules.md
+    guidelines/general-eng-assistant-rules.md: internal:guidelines/general-eng-assistant-rules.md
+    guidelines/general-style-rules.md: internal:guidelines/general-style-rules.md
+    guidelines/general-tdd-guidelines.md: internal:guidelines/general-tdd-guidelines.md
+    guidelines/general-testing-rules.md: internal:guidelines/general-testing-rules.md
+    guidelines/golden-testing-guidelines.md: internal:guidelines/golden-testing-guidelines.md
+    guidelines/pnpm-monorepo-patterns.md: internal:guidelines/pnpm-monorepo-patterns.md
+    guidelines/python-cli-patterns.md: internal:guidelines/python-cli-patterns.md
+    guidelines/python-modern-guidelines.md: internal:guidelines/python-modern-guidelines.md
+    guidelines/python-rules.md: internal:guidelines/python-rules.md
+    guidelines/release-notes-guidelines.md: internal:guidelines/release-notes-guidelines.md
+    guidelines/tbd-sync-troubleshooting.md: internal:guidelines/tbd-sync-troubleshooting.md
+    guidelines/typescript-cli-tool-rules.md: internal:guidelines/typescript-cli-tool-rules.md
+    guidelines/typescript-code-coverage.md: internal:guidelines/typescript-code-coverage.md
+    guidelines/typescript-rules.md: internal:guidelines/typescript-rules.md
+    guidelines/typescript-sorting-patterns.md: internal:guidelines/typescript-sorting-patterns.md
+    guidelines/typescript-yaml-handling-rules.md: internal:guidelines/typescript-yaml-handling-rules.md
+    shortcuts/standard/agent-handoff.md: internal:shortcuts/standard/agent-handoff.md
+    shortcuts/standard/checkout-third-party-repo.md: internal:shortcuts/standard/checkout-third-party-repo.md
+    shortcuts/standard/code-cleanup-all.md: internal:shortcuts/standard/code-cleanup-all.md
+    shortcuts/standard/code-cleanup-docstrings.md: internal:shortcuts/standard/code-cleanup-docstrings.md
+    shortcuts/standard/code-cleanup-tests.md: internal:shortcuts/standard/code-cleanup-tests.md
+    shortcuts/standard/code-review-and-commit.md: internal:shortcuts/standard/code-review-and-commit.md
+    shortcuts/standard/coding-spike.md: internal:shortcuts/standard/coding-spike.md
+    shortcuts/standard/create-or-update-pr-simple.md: internal:shortcuts/standard/create-or-update-pr-simple.md
+    shortcuts/standard/create-or-update-pr-with-validation-plan.md: internal:shortcuts/standard/create-or-update-pr-with-validation-plan.md
+    shortcuts/standard/implement-beads.md: internal:shortcuts/standard/implement-beads.md
+    shortcuts/standard/merge-upstream.md: internal:shortcuts/standard/merge-upstream.md
+    shortcuts/standard/new-architecture-doc.md: internal:shortcuts/standard/new-architecture-doc.md
+    shortcuts/standard/new-guideline.md: internal:shortcuts/standard/new-guideline.md
+    shortcuts/standard/new-plan-spec.md: internal:shortcuts/standard/new-plan-spec.md
+    shortcuts/standard/new-research-brief.md: internal:shortcuts/standard/new-research-brief.md
+    shortcuts/standard/new-shortcut.md: internal:shortcuts/standard/new-shortcut.md
+    shortcuts/standard/new-validation-plan.md: internal:shortcuts/standard/new-validation-plan.md
+    shortcuts/standard/plan-implementation-with-beads.md: internal:shortcuts/standard/plan-implementation-with-beads.md
+    shortcuts/standard/precommit-process.md: internal:shortcuts/standard/precommit-process.md
+    shortcuts/standard/review-code-python.md: internal:shortcuts/standard/review-code-python.md
+    shortcuts/standard/review-code-typescript.md: internal:shortcuts/standard/review-code-typescript.md
+    shortcuts/standard/review-code.md: internal:shortcuts/standard/review-code.md
+    shortcuts/standard/review-github-pr.md: internal:shortcuts/standard/review-github-pr.md
+    shortcuts/standard/revise-all-architecture-docs.md: internal:shortcuts/standard/revise-all-architecture-docs.md
+    shortcuts/standard/revise-architecture-doc.md: internal:shortcuts/standard/revise-architecture-doc.md
+    shortcuts/standard/setup-github-cli.md: internal:shortcuts/standard/setup-github-cli.md
+    shortcuts/standard/sync-failure-recovery.md: internal:shortcuts/standard/sync-failure-recovery.md
+    shortcuts/standard/update-specs-status.md: internal:shortcuts/standard/update-specs-status.md
+    shortcuts/standard/welcome-user.md: internal:shortcuts/standard/welcome-user.md
+    shortcuts/system/shortcut-explanation.md: internal:shortcuts/system/shortcut-explanation.md
+    shortcuts/system/skill-brief.md: internal:shortcuts/system/skill-brief.md
+    shortcuts/system/skill.md: internal:shortcuts/system/skill.md
+    templates/architecture-doc.md: internal:templates/architecture-doc.md
+    templates/plan-spec.md: internal:templates/plan-spec.md
+    templates/research-brief.md: internal:templates/research-brief.md
+  lookup_path:
+    - .tbd/docs/shortcuts/system
+    - .tbd/docs/shortcuts/standard
 settings:
   auto_sync: false
-  index_enabled: true
+  doc_auto_sync_hours: 24
+  use_gh_cli: true
 sync:
   branch: tbd-sync
   remote: origin
+tbd_format: f03
 tbd_version: 0.1.3
diff --git a/AGENTS.md b/AGENTS.md
index 5de06c2..1614c2f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -29,127 +29,246 @@ IMPORTANT: You MUST read ./docs/development.md and ./docs/docs-overview.md for p
 
 
 <!-- BEGIN TBD INTEGRATION -->
-# tbd Workflow
+---
+title: tbd Workflow
+description: Full tbd workflow guide for agents
+---
+**`tbd` helps humans and agents ship code with greater speed, quality, and discipline.**
+
+1. **Beads**: Git-native issue tracking (tasks, bugs, features).
+   Never lose work across sessions.
+   Drop-in replacement for `bd`.
+2. **Spec-Driven Workflows**: Plan features → break into beads → implement
+   systematically.
+3. **Knowledge Injection**: 17+ engineering guidelines (TypeScript, Python, TDD,
+   testing, Convex, monorepos) available on demand.
+4. **Shortcuts**: Reusable instruction templates for common workflows (code review,
+   commits, PRs, cleanup, handoffs).
+
+## Installation
 
-`tbd` provides lightweight, git-native task and issue tracking using beads, which are
-just lightweight issues managed from the CLI.
-
-> **Context Recovery**: Run `tbd prime` after compaction, clear, or new session.
-> Hooks auto-call this in Claude Code when .tbd/ detected.
-
-# SESSION CLOSING PROTOCOL
-
-**CRITICAL**: Before saying “done” or “complete”, you MUST run this checklist:
-
-```
-[ ] 1. Stage and commit: git add + git commit
-[ ] 2. Push to remote: git push
-[ ] 3. Start CI watch (BLOCKS until done): gh pr checks <PR> --watch 2>&1
-[ ] 4. While CI runs: tbd close/update <id> for issues worked on
-[ ] 5. While CI runs: tbd sync
-[ ] 6. Return to step 3 and CONFIRM CI passed
-[ ] 7. If CI failed: fix, re-push, restart from step 3
+```bash
+npm install -g get-tbd@latest
+tbd setup --auto --prefix=<name>   # Fresh project (--prefix is REQUIRED: 2-8 alphabetic chars recommended. ALWAYS ASK THE USER FOR THE PREFIX; do not guess it)
+tbd setup --auto                   # Existing tbd project (prefix already set)
+tbd setup --from-beads             # Migration from .beads/ if `bd` has been used
 ```
 
-## NON-NEGOTIABLE Requirements
+## Routine Commands
 
-### CI: Wait for `--watch` to finish
+```bash
+tbd --help    # Command reference
+tbd status    # Status
+tbd doctor    # If there are problems
 
-The `--watch` flag blocks until ALL checks complete.
-Do NOT see “passing” in early output and move on—wait for the **final summary** showing
-all checks passed.
+tbd setup --auto   # Run any time to refresh setup
+tbd prime      # Restore full context on tbd after compaction
+```
 
-### tbd: Update issues and sync
+## CRITICAL: You Operate tbd — The User Doesn’t
+
+**You are the tbd operator:** Users talk naturally; you translate their requests to tbd
+actions. DO NOT tell users to run tbd commands.
+That’s your job.
+
+- **WRONG**: "Run `tbd create` to track this bug"
+
+- **RIGHT**: *(you run `tbd create` yourself and tell the user it’s tracked)*
+
+**Welcoming a user:** When users ask “what is tbd?”
+or want help → run `tbd shortcut welcome-user`
+
+## User Request → Agent Action
+
+| User Says | You (the Agent) Run |
+| --- | --- |
+| **Issues/Beads** |  |
+| "There's a bug where ..." | `tbd create "..." --type=bug` |
+| "Create a task/feature for ..." | `tbd create "..." --type=task` or `--type=feature` |
+| "Let's work on issues/beads" | `tbd ready` |
+| "Show me issue X" | `tbd show <id>` |
+| "Close this issue" | `tbd close <id>` |
+| "Search issues for X" | `tbd search "X"` |
+| "Add label X to issue" | `tbd label add <id> <label>` |
+| "What issues are stale?" | `tbd stale` |
+| **Planning & Specs** |  |
+| "Plan a new feature" / "Create a spec" | `tbd shortcut new-plan-spec` |
+| "Break spec into beads" | `tbd shortcut plan-implementation-with-beads` |
+| "Implement these beads" | `tbd shortcut implement-beads` |
+| **Code Review & Commits** |  |
+| "Review this code" / "Code review" | `tbd shortcut review-code` |
+| "Review this PR" | `tbd shortcut review-github-pr` |
+| "Commit this" / "Use the commit shortcut" | `tbd shortcut code-review-and-commit` |
+| "Create a PR" / "File a PR" | `tbd shortcut create-or-update-pr-simple` |
+| "Merge main into my branch" | `tbd shortcut merge-upstream` |
+| **Guidelines & Knowledge** |  |
+| "Use TypeScript best practices" | `tbd guidelines typescript-rules` |
+| "Use Python best practices" | `tbd guidelines python-rules` |
+| "Build a TypeScript CLI" | `tbd guidelines typescript-cli-tool-rules` |
+| "Improve monorepo setup" | `tbd guidelines pnpm-monorepo-patterns` or `bun-monorepo-patterns` |
+| "Add golden/e2e testing" | `tbd guidelines golden-testing-guidelines` |
+| "Use TDD" / "Test-driven development" | `tbd guidelines general-tdd-guidelines` |
+| "Convex best practices" | `tbd guidelines convex-rules` |
+| **Documentation** |  |
+| "Research this topic" | `tbd shortcut new-research-brief` |
+| "Document architecture" | `tbd shortcut new-architecture-doc` |
+| **Cleanup & Maintenance** |  |
+| "Clean up this code" / "Remove dead code" | `tbd shortcut code-cleanup-all` |
+| "Fix repository problems" | `tbd doctor --fix` |
+| **Sessions & Handoffs** |  |
+| "Hand off to another agent" | `tbd shortcut agent-handoff` |
+| "Check out this library's source" | `tbd shortcut checkout-third-party-repo` |
+| *(your choice whenever appropriate)* | `tbd list`, `tbd dep add`, `tbd close`, `tbd sync`, etc. |
+
+## CRITICAL: Session Closing Protocol
+
+**Before saying “done”, you MUST complete this checklist:**
 
-Every session must end with tbd in a clean state:
-- Close/update **every issue** you worked on
-- Run `tbd sync` and confirm it completed
+```
+[ ] 1. git add + git commit
+[ ] 2. git push
+[ ] 3. gh pr checks <PR> --watch 2>&1 (IMPORTANT: WAIT for final summary, do NOT tell user it is done until you confirm it passes CI!)
+[ ] 4. tbd close/update <id> for all beads worked on
+[ ] 5. tbd sync
+[ ] 6. CONFIRM CI passed (if failed: fix, run tests, re-push, restart from step 3)
+```
 
 **Work is not done until pushed, CI passes, and tbd is synced.**
 
-## Core Rules
+## Bead Tracking Rules
 
-- Track *all task work* not being done immediately as beads using `tbd` (discovered
-  work, future work, TODOs for the session, multi-session work)
-- When in doubt, prefer tbd for tracking tasks, bugs, and issues
-- Use `tbd create` for creating beads
-- Git workflow: update or close issues and run `tbd sync` at session end
-- If not given specific directions, check `tbd ready` for available work
+- Track all task work not done immediately as beads (discovered work, TODOs,
+  multi-session work)
+- When in doubt, create a bead
+- Check `tbd ready` when not given specific directions
+- Always close/update beads and run `tbd sync` at session end
 
-## Essential Commands
+## Commands
 
 ### Finding Work
 
-- `tbd ready` - Show issues ready to work (no blockers)
-- `tbd list --status open` - All open issues
-- `tbd list --status in_progress` - Your active work
-- `tbd show <id>` - Detailed issue view with dependencies
+| Command | Purpose |
+| --- | --- |
+| `tbd ready` | Beads ready to work (no blockers) |
+| `tbd list --status open` | All open beads |
+| `tbd list --status in_progress` | Your active work |
+| `tbd show <id>` | Bead details with dependencies |
 
 ### Creating & Updating
 
-- `tbd create "title" --type task|bug|feature --priority P2` - New issue
-  - Priority: P0-P4 (P0=critical, P2=medium, P4=backlog).
-    Do NOT use "high"/"medium"/"low"
-- `tbd update <id> --status in_progress` - Claim work
-- `tbd update <id> --assignee username` - Assign to someone
-- `tbd close <id>` - Mark complete
-- `tbd close <id> --reason "explanation"` - Close with reason
-- **Tip**: When creating multiple issues, use parallel subagents for efficiency
-
-### Dependencies & Blocking
-
-- `tbd dep add <issue> <depends-on>` - Add dependency (issue depends on depends-on)
-- `tbd blocked` - Show all blocked issues
-- `tbd show <id>` - See what’s blocking/blocked by this issue
-
-### Sync & Collaboration
-
-- `tbd sync` - Sync with git remote (run at session end)
-- `tbd sync --status` - Check sync status without syncing
-
-Note: `tbd sync` handles all git operations for issues--no manual git push needed.
-
-### Project Health
-
-- `tbd stats` - Project statistics (open/closed/blocked counts)
-- `tbd doctor` - Check for issues (sync problems, missing hooks)
-
-## Common Workflows
-
-**Starting work:**
-
-```bash
-tbd ready                              # Find available work
-tbd show <id>                          # Review issue details
-tbd update <id> --status in_progress   # Claim it
-```
-
-**Completing work:**
-
-```bash
-tbd close <id>    # Mark complete
-tbd sync          # Push to remote
-```
-
-**Creating dependent work:**
-
-```bash
-tbd create "Implement feature X" --type feature
-tbd create "Write tests for X" --type task
-tbd dep add <tests-id> <feature-id>   # Tests depend on feature
-```
-
-## Setup Commands
-
-- `tbd setup claude` - Install Claude Code hooks and skill file
-- `tbd setup cursor` - Create Cursor IDE rules file
-- `tbd setup codex` - Create/update AGENTS.md for Codex
-- `tbd setup beads --disable` - Migrate from Beads to tbd
+| Command | Purpose |
+| --- | --- |
+| `tbd create "title" --type task\|bug\|feature --priority=P2` | New bead (P0-P4, not "high/medium/low") |
+| `tbd update <id> --status in_progress` | Claim work |
+| `tbd close <id> [--reason "..."]` | Mark complete |
+
+### Dependencies & Sync
+
+| Command | Purpose |
+| --- | --- |
+| `tbd dep add <bead> <depends-on>` | Add dependency |
+| `tbd blocked` | Show blocked beads |
+| `tbd sync` | Sync with git remote (run at session end) |
+| `tbd stats` | Project statistics |
+| `tbd doctor` | Check for problems |
+| `tbd doctor --fix` | Auto-fix repository problems |
+
+### Labels & Search
+
+| Command | Purpose |
+| --- | --- |
+| `tbd search <query>` | Search issues by text |
+| `tbd label add <id> <label>` | Add label to issue |
+| `tbd label remove <id> <label>` | Remove label from issue |
+| `tbd label list` | List all labels in use |
+| `tbd stale` | List issues not updated recently |
+
+### Documentation
+
+| Command | Purpose |
+| --- | --- |
+| `tbd shortcut <name>` | Run a shortcut |
+| `tbd shortcut --list` | List shortcuts |
+| `tbd guidelines <name>` | Load coding guidelines |
+| `tbd guidelines --list` | List guidelines |
+| `tbd template <name>` | Output a template |
 
 ## Quick Reference
 
-- **Priority levels**: 0=critical, 1=high, 2=medium (default), 3=low, 4=backlog
-- **Issue types**: task, bug, feature, epic
-- **Status values**: open, in_progress, closed
-- **JSON output**: Add `--json` to any command for machine-readable output
+- **Priority**: P0=critical, P1=high, P2=medium (default), P3=low, P4=backlog
+- **Types**: task, bug, feature, epic
+- **Status**: open, in_progress, closed
+- **JSON output**: Add `--json` to any command
+
+<!-- BEGIN SHORTCUT DIRECTORY -->
+## Available Shortcuts
+
+Run `tbd shortcut <name>` to use any of these shortcuts:
+
+| Name | Description |
+| --- | --- |
+| agent-handoff | Generate a concise handoff prompt for another coding agent to continue work |
+| checkout-third-party-repo | Get source code for libraries and third-party repos using git. Essential for reliable source code review. Prefer this to web searches or fetching of web pages from github.com as it is far more effective (github.com blocks web scraping from main website). |
+| code-cleanup-all | Full cleanup cycle including duplicate removal, dead code, and code quality improvements |
+| code-cleanup-docstrings | Review and add concise docstrings to major functions and types |
+| code-cleanup-tests | Review and remove tests that do not add meaningful coverage |
+| code-review-and-commit | Run pre-commit checks, review changes, and commit code |
+| coding-spike | Prototype to validate a spec through hands-on implementation |
+| create-or-update-pr-simple | Create or update a pull request with a concise summary |
+| create-or-update-pr-with-validation-plan | Create or update a pull request with a detailed test/validation plan |
+| implement-beads | Implement beads from a spec, following TDD and project rules |
+| merge-upstream | Merge origin/main into current branch with conflict resolution |
+| new-architecture-doc | Create an architecture document for a system or component design |
+| new-guideline | Create a new coding guideline document for tbd |
+| new-plan-spec | Create a new feature planning specification document |
+| new-research-brief | Create a research document for investigating a topic or technology |
+| new-shortcut | Create a new shortcut (reusable instruction template) for tbd |
+| new-validation-plan | Create a validation/test plan showing what's tested and what remains |
+| plan-implementation-with-beads | Create implementation beads from a feature planning spec |
+| precommit-process | Full pre-commit checklist including spec sync, code review, and testing |
+| review-code | Comprehensive code review for uncommitted changes, branch work, or GitHub PRs |
+| review-code-python | Python-focused code review (language-specific rules only) |
+| review-code-typescript | TypeScript-focused code review (language-specific rules only) |
+| review-github-pr | Review a GitHub pull request with follow-up actions (comment, fix, CI check) |
+| revise-all-architecture-docs | Comprehensive revision of all current architecture documents |
+| revise-architecture-doc | Update an architecture document to reflect current codebase state |
+| setup-github-cli | Ensure GitHub CLI (gh) is installed and working |
+| sync-failure-recovery | Handle tbd sync failures by saving to workspace and recovering later |
+| update-specs-status | Review active specs and sync their status with tbd issues |
+| welcome-user | Welcome message for users after tbd installation or setup |
+
+## Available Guidelines
+
+Run `tbd guidelines <name>` to apply any of these guidelines:
+
+| Name | Description |
+| --- | --- |
+| backward-compatibility-rules | Guidelines for maintaining backward compatibility across code, APIs, file formats, and database schemas |
+| bun-monorepo-patterns | Modern patterns for Bun-based TypeScript monorepo architecture |
+| cli-agent-skill-patterns | Best practices for building TypeScript CLIs that function as agent skills in Claude Code and other AI coding agents |
+| commit-conventions | Conventional Commits format with extensions for agentic workflows |
+| convex-limits-best-practices | Comprehensive reference for Convex platform limits, workarounds, and performance best practices |
+| convex-rules | Guidelines and best practices for building Convex projects, including database schema design, queries, mutations, and real-world examples |
+| electron-app-development-patterns | Guidelines for Electron development ecosystems including npm, pnpm, and Bun, with security baselines and framework comparisons |
+| error-handling-rules | Rules for handling errors, failures, and exceptional conditions |
+| general-coding-rules | Rules for constants, magic numbers, and general coding practices |
+| general-comment-rules | Language-agnostic rules for writing clean, maintainable comments |
+| general-eng-assistant-rules | Rules for AI assistants acting as senior engineers, including objectivity and communication guidelines |
+| general-style-rules | Style guidelines for auto-formatting, emoji usage, and output formatting |
+| general-tdd-guidelines | Test-Driven Development methodology and best practices |
+| general-testing-rules | Rules for writing minimal, effective tests with maximum coverage |
+| golden-testing-guidelines | Guidelines for implementing golden/snapshot testing for complex systems |
+| pnpm-monorepo-patterns | Modern patterns for pnpm-based TypeScript monorepo architecture |
+| python-cli-patterns | Modern patterns for Python CLI application architecture |
+| python-modern-guidelines | Guidelines for modern Python projects using uv, with a few more opinionated practices |
+| python-rules | General Python coding rules and best practices |
+| release-notes-guidelines | Guidelines for writing clear, accurate release notes |
+| tbd-sync-troubleshooting | Common issues and solutions for tbd sync and workspace operations |
+| typescript-cli-tool-rules | Rules for building CLI tools with Commander.js, picocolors, and TypeScript |
+| typescript-code-coverage | Best practices for code coverage in TypeScript with Vitest and v8 provider |
+| typescript-rules | TypeScript coding rules and best practices |
+| typescript-sorting-patterns | Deterministic sorting patterns and comparison chains for TypeScript |
+| typescript-yaml-handling-rules | Best practices for parsing and serializing YAML in TypeScript |
+
+<!-- END SHORTCUT DIRECTORY -->
 <!-- END TBD INTEGRATION -->
diff --git a/docs/project/specs/active/plan-2026-01-31-manual-testing-workflows.md b/docs/project/specs/active/plan-2026-01-31-manual-testing-workflows.md
new file mode 100644
index 0000000..b32f9a1
--- /dev/null
+++ b/docs/project/specs/active/plan-2026-01-31-manual-testing-workflows.md
@@ -0,0 +1,1046 @@
+# Plan Spec: Manual Testing Workflows and Validation Modes
+
+**Status**: PLANNING
+
+## Purpose
+
+This plan designs features to support "manual" test scripts - tests that facilitate
+human or agent review rather than strict pass/fail automation. This addresses use
+cases where outputs are inherently variable (LLM responses, web search results) or
+require subjective evaluation (visual UX, complex formatting).
+
+## Background
+
+### Current Tryscript Model
+
+Tryscript is designed as an automated golden test framework:
+
+1. Run commands, capture outputs
+2. Compare against expected golden outputs
+3. Pass if matches (with elision patterns), fail otherwise
+4. Exit with non-zero status on any failure
+
+This works well for deterministic CLIs but breaks down for:
+
+- **Variable outputs**: LLM/AI responses, web scraping, search results, timestamps
+- **Subjective evaluation**: Visual appearance, UX flows, formatting quality
+- **Quality evaluation (evals)**: Search relevance, ranking quality, precision/recall metrics
+- **Exploratory testing**: New feature development, debugging sessions
+- **Documentation verification**: Ensuring examples still run correctly
+
+### Beyond Simple Diffs
+
+The current model assumes comparison via text diff, but many evaluation scenarios
+need richer comparison methods:
+
+- **Side-by-side comparison**: View previous and current outputs together
+- **Metric-based evaluation**: Precision, recall, relevance scores
+- **LLM-assisted evaluation**: Use another model to judge quality/similarity
+- **Custom evaluators**: Scripts that produce comparison reports
+
+These scenarios require a generalization beyond "diff the outputs" to "evaluate
+the outputs" with configurable comparison strategies.
+
+### The "Update and Review" Workflow
+
+Users have discovered an informal workflow:
+
+```bash
+# Run in update mode (always captures actual output)
+tryscript run tests/llm-responses.tryscript.md --update
+
+# Review the diff to manually validate
+git diff tests/llm-responses.tryscript.md
+```
+
+This works but has friction:
+
+- Tests still "pass" (exit 0) even when review is needed
+- No way to distinguish automated vs manual tests
+- No structured way to document review criteria
+- CI/CD doesn't know to pause for review
+
+### User Request
+
+The user wants to:
+
+1. Formalize workflows for manual testing scenarios
+2. Potentially add a "validation mode" concept (binary vs manual)
+3. Create a playbook documenting best practices and anti-patterns
+4. Streamline the update-and-review workflow
+
+## Design Philosophy
+
+### Tryscript as "Jupyter Notebooks for CLI Testing"
+
+A useful mental model: tryscript files are like Jupyter notebooks for CLI testing.
+
+| Jupyter Notebooks | Tryscript Files |
+|-------------------|-----------------|
+| Run code cells, capture outputs | Run commands, capture outputs |
+| Outputs stored in `.ipynb` | Outputs stored in `.tryscript.md` |
+| Rerun to update outputs | `--update` to refresh outputs |
+| Visual inspection of results | `git diff` to review changes |
+| Share notebooks for collaboration | Commit files to git for review |
+
+Both provide **structured, reproducible, reviewable** execution with captured outputs.
+
+### Principles
+
+1. **Build on existing tools**: `tryscript run --update` + `git diff` already works.
+   Minimize new features; maximize reuse.
+
+2. **Everything is a file diff**: All comparison ultimately reduces to diffing the
+   tryscript markdown file before and after. Even "side-by-side" is just showing
+   the old and new outputs.
+
+3. **Non-interactive, agent-friendly**: All workflows must work from command line
+   without interactive prompts. Agents should be able to run, inspect, and review.
+
+4. **Prose is documentation**: Review criteria are just regular markdown text in
+   the test file. No special syntax needed.
+
+5. **Simple format, flexible workflows**: Keep the tryscript format unchanged.
+   Different workflows are achieved through CLI options and shell composition.
+
+### The Core Workflow (Already Works Today)
+
+```bash
+# 1. Run tests with update mode
+tryscript run tests/evals/*.tryscript.md --update
+
+# 2. Review changes with standard git diff
+git diff tests/evals/
+
+# 3. Accept or reject
+git add tests/evals/ && git commit -m "Update baselines"
+# or
+git checkout -- tests/evals/  # Reject changes
+```
+
+This workflow is already sufficient for most manual testing needs. The question
+is: what minimal enhancements would make it more streamlined?
+
+## Summary of Task
+
+Implement and document features for manual/review-based testing:
+
+| Phase | Feature | Value | Complexity |
+|-------|---------|-------|------------|
+| I | Documentation: Testing Playbook | Establish patterns and anti-patterns | Low |
+| II | `--review` mode | Run + update + show diffs (no pass/fail) | Low |
+| III | `validation` frontmatter option | Per-file binary vs manual designation | Low |
+| IV | Review annotations in test files | Document expected behavior for reviewers | Low |
+| V | CI integration patterns | GitHub Actions examples for manual review | Low |
+| VI | Comparison modes | Side-by-side, evaluators, LLM-assisted (future) | Medium |
+
+## Backward Compatibility
+
+| Area | Compatibility Level | Notes |
+|------|---------------------|-------|
+| CLI behavior | Additive | New `--review` flag, existing flags unchanged |
+| Config schema | Additive | New optional `validation` field |
+| Test file syntax | Additive | New optional annotations |
+| Exit codes | Unchanged | Default behavior preserved |
+
+---
+
+## Phase I: Testing Playbook Documentation
+
+### Overview
+
+Create comprehensive documentation covering tryscript use cases, workflows, best
+practices, and anti-patterns. This establishes patterns before adding features.
+
+### Document Structure
+
+Create `packages/tryscript/docs/playbook.md`:
+
+```markdown
+# Tryscript Testing Playbook
+
+A guide to effective CLI testing patterns and workflows.
+
+## Use Cases
+
+### 1. Deterministic CLI Testing (Default)
+
+**Best for**: CLIs with predictable outputs, version strings, help text, file
+operations.
+
+**Characteristics**:
+- Same input → same output (minus timestamps, paths)
+- Failures indicate regressions
+- Fully automatable in CI
+
+**Example**:
+```yaml
+---
+sandbox: true
+path: [$TRYSCRIPT_PACKAGE_BIN]
+---
+
+# Test: Version command
+
+```console
+$ my-cli --version
+my-cli v1.0.0
+? 0
+```
+
+# Test: Help output
+
+```console
+$ my-cli --help
+Usage: my-cli [command] [options]
+
+Commands:
+  init    Initialize a new project
+  build   Build the project
+...
+? 0
+```
+```
+
+**Elision patterns for variability**:
+```console
+$ my-cli build
+Build started at [..]
+...
+Build completed in [..]ms
+? 0
+```
+
+### 2. LLM/AI Response Testing
+
+**Best for**: Testing CLI wrappers around LLMs, AI assistants, chat interfaces.
+
+**Characteristics**:
+- Outputs vary between runs
+- "Correct" is subjective (tone, completeness, accuracy)
+- Human review needed for quality assessment
+
+**Workflow**:
+```bash
+# Capture current behavior
+tryscript run tests/llm.tryscript.md --update
+
+# Review the outputs manually
+git diff tests/llm.tryscript.md
+
+# If acceptable, commit as new baseline
+git add tests/llm.tryscript.md
+git commit -m "Update LLM response baselines"
+```
+
+**Example with review guidance**:
+```yaml
+---
+validation: manual
+---
+
+# Test: Summarization quality
+
+The summary should be 2-3 sentences and capture the main points of the article.
+
+```console
+$ ai-cli summarize article.txt
+[.. summary text varies ..]
+? 0
+```
+```
+
+### 3. Web Scraping / Search Results
+
+**Best for**: CLIs that fetch web content, search APIs, live data.
+
+**Characteristics**:
+- Content changes over time
+- Structure may be stable even if content varies
+- May need to verify "something reasonable" returned
+
+**Pattern - Structure validation**:
+```console
+$ web-cli search "nodejs tutorials"
+Results for "nodejs tutorials":
+...
+Found [..] results
+? 0
+```
+
+**Pattern - Snapshot for reference**:
+```yaml
+---
+validation: manual
+---
+
+# Test: Search returns results
+
+Should return 5+ relevant results with titles and URLs.
+
+```console
+$ web-cli search "rust programming"
+[.. search results vary ..]
+? 0
+```
+```
+
+### 4. Quality Evaluation (Evals)
+
+**Best for**: Search engines, recommendation systems, ranking algorithms, any system
+where you need to evaluate quality rather than exact correctness.
+
+**Characteristics**:
+- Results may differ but both be "correct"
+- Comparison is about quality levels, not exact matches
+- May need precision/recall or relevance metrics
+- Diff isn't meaningful; side-by-side or scored comparison is better
+
+**Use cases**:
+- Search engine result quality over time
+- Recommendation relevance evaluation
+- Content ranking regression testing
+- A/B comparison of algorithm changes
+
+**Pattern - Search quality eval**:
+```yaml
+---
+validation: manual
+---
+
+# Eval: Product search relevance
+
+Top 5 results should be relevant to query. No obviously wrong results in top 10.
+Compare precision@10 with previous baseline.
+
+```console
+$ search-cli query "wireless headphones under $100"
+[.. search results ..]
+? 0
+```
+```
+
+**Workflow for evals** (using existing tools):
+```bash
+# Run evals and capture new baselines
+tryscript run tests/evals/*.tryscript.md --update
+
+# Review changes with git diff
+git diff tests/evals/
+
+# If acceptable, commit as new baseline
+git add tests/evals/ && git commit -m "Update eval baselines"
+```
+
+**What the reviewer sees**:
+```
+Eval: Product search relevance
+
+Previous results:           Current results:
+─────────────────           ─────────────────
+1. Sony WH-1000XM4          1. Sony WH-1000XM5
+2. Bose QC45                2. Bose QC45
+3. Apple AirPods Pro        3. JBL Tune 760NC
+4. JBL Tune 760NC           4. Apple AirPods Pro
+5. Anker Soundcore          5. Anker Soundcore Q20
+
+Observations:
+- Top result changed (XM4 → XM5) - expected, newer model
+- Positions 3-4 swapped - acceptable
+- Overall relevance maintained ✓
+```
+
+### 5. Visual/UX Output Testing
+
+**Best for**: CLIs with formatted output, progress bars, tables, colors.
+
+**Characteristics**:
+- Visual correctness hard to assert automatically
+- Screenshots or terminal recordings may supplement
+- Alignment, formatting, color choices need human eye
+
+**Pattern**:
+```yaml
+---
+validation: manual
+env:
+  FORCE_COLOR: "1"  # Enable colors for review
+---
+
+# Test: Table formatting
+
+Columns should be aligned and headers should be bold.
+
+```console
+$ report-cli show --format table
+[.. formatted table output ..]
+? 0
+```
+```
+
+### 6. Interactive/Multi-step Workflows
+
+**Best for**: CLIs with prompts, wizards, complex state.
+
+**Characteristics**:
+- Output depends on timing, user choices
+- May need fixture setup
+- Often better tested with unit tests + limited E2E
+
+**Pattern - Scripted input**:
+```console
+$ echo -e "project-name\ny\n" | wizard-cli init
+? Project name: project-name
+? Confirm? (y/n): y
+Created project-name/
+? 0
+```
+
+## Workflows
+
+### Automated Testing (CI)
+
+Standard tryscript in CI pipelines:
+
+```yaml
+# .github/workflows/test.yml
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm ci
+      - run: npm run build
+      - run: npx tryscript run
+```
+
+### Manual Review Testing
+
+For tests requiring human judgment:
+
+```yaml
+# .github/workflows/manual-review.yml
+jobs:
+  update-baselines:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm ci
+      - run: npm run build
+
+      # Update baselines and create PR for review
+      - run: npx tryscript run tests/manual/*.tryscript.md --update
+
+      - name: Check for changes
+        id: changes
+        run: |
+          if git diff --quiet tests/manual/; then
+            echo "changed=false" >> $GITHUB_OUTPUT
+          else
+            echo "changed=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create review PR
+        if: steps.changes.outputs.changed == 'true'
+        run: |
+          git checkout -b update-baselines-$(date +%Y%m%d)
+          git add tests/manual/
+          git commit -m "chore: update manual test baselines for review"
+          gh pr create --title "Review: Updated test baselines" \
+            --body "These test outputs have changed. Please review."
+```
+
+### Development/Exploratory Testing
+
+When building new features:
+
+```bash
+# Create a scratch test file
+cat > tests/scratch.tryscript.md << 'EOF'
+---
+sandbox: true
+---
+
+# Exploring new feature
+
+```console
+$ my-cli new-command --help
+```
+EOF
+
+# Run and capture output
+tryscript run tests/scratch.tryscript.md --update
+
+# Iterate until output looks right
+# Then move to permanent test file
+```
+
+## Best Practices
+
+### DO: Use Elision Patterns Liberally
+
+```console
+# Good: Handles variable content
+$ cli build
+Build started at [..]
+...
+Completed in [..]ms
+? 0
+
+# Bad: Brittle, breaks on any change
+$ cli build
+Build started at 2024-01-15T10:30:00Z
+Processing file1.ts
+Processing file2.ts
+Completed in 234ms
+? 0
+```
+
+### DO: Separate Deterministic and Manual Tests
+
+```
+tests/
+├── cli.tryscript.md           # Automated, run in CI
+├── help.tryscript.md          # Automated
+└── manual/
+    ├── llm-responses.tryscript.md   # Requires review
+    └── visual-output.tryscript.md   # Requires review
+```
+
+### DO: Document Review Criteria
+
+```yaml
+---
+validation: manual
+---
+
+# Test: Error message quality
+
+<!--
+REVIEW CRITERIA:
+- Error should mention the invalid flag name
+- Should suggest valid alternatives
+- Tone should be helpful, not accusatory
+-->
+
+```console
+$ my-cli --invlaid-flag
+[.. error message ..]
+? 1
+```
+```
+
+### DON'T: Use Manual Tests for Deterministic Behavior
+
+If output can be matched with patterns, use automated testing:
+
+```yaml
+# Bad: Marked manual but could be automated
+---
+validation: manual
+---
+
+```console
+$ cli --version
+v1.2.3
+? 0
+```
+
+# Good: Automated test with pattern
+```console
+$ cli --version
+v[..]
+? 0
+```
+```
+
+### DON'T: Ignore Failing Manual Tests
+
+Manual tests should still run and show differences:
+
+```bash
+# Run manual tests to see what changed
+tryscript run tests/manual/ --update
+
+# Review every change, don't blindly commit
+git diff tests/manual/
+```
+
+### DON'T: Put Secrets in Test Files
+
+Even manual tests shouldn't contain real credentials:
+
+```yaml
+# Bad
+env:
+  API_KEY: "sk-live-abc123..."
+
+# Good
+env:
+  API_KEY: "test-key"
+  # Or use environment variable from CI
+```
+
+## Anti-Patterns
+
+### Anti-Pattern: Empty Expected Output
+
+```console
+# Bad: Accepts any output
+$ cli do-something
+? 0
+
+# Better: At least verify structure
+$ cli do-something
+...
+Done
+? 0
+```
+
+### Anti-Pattern: Overly Broad Elision
+
+```console
+# Bad: Matches anything
+$ cli complex-operation
+...
+? 0
+
+# Better: Pin stable parts
+$ cli complex-operation
+Starting complex operation...
+...
+Operation completed successfully.
+? 0
+```
+
+### Anti-Pattern: Testing Implementation Details
+
+```console
+# Bad: Tests internal log format
+$ cli build
+[DEBUG] Loading config from ./config.json
+[DEBUG] Found 3 source files
+[DEBUG] Compiling file 1/3...
+
+# Better: Test user-facing output
+$ cli build
+Building project...
+...
+Build complete.
+? 0
+```
+
+### Anti-Pattern: Flaky Time-Dependent Tests
+
+```console
+# Bad: Depends on execution speed
+$ cli slow-operation
+Completed in 1.234s
+? 0
+
+# Good: Use elision
+$ cli slow-operation
+Completed in [..]
+? 0
+```
+```
+
+### Files to Create
+
+| File | Description |
+|------|-------------|
+| `packages/tryscript/docs/playbook.md` | Main playbook document (above) |
+
+### Acceptance Criteria
+
+- [ ] Playbook covers all major use cases
+- [ ] Each use case has concrete examples
+- [ ] Best practices are actionable
+- [ ] Anti-patterns show both bad and good alternatives
+- [ ] CI workflow examples are copy-pasteable
+
+---
+
+## Phase II: `--review` Mode
+
+### Overview
+
+Add a `--review` flag that combines update mode with explicit diff display, exiting
+successfully to indicate "review needed" rather than "tests passed."
+
+### CLI Changes
+
+```bash
+# New flag
+tryscript run tests/manual/*.tryscript.md --review
+
+# Behavior:
+# 1. Run all tests
+# 2. Update expected outputs with actual
+# 3. Show unified diff of all changes
+# 4. Exit 0 (review mode doesn't "fail")
+```
+
+### Implementation
+
+**New option** in `run.ts`:
+
+```typescript
+interface RunOptions {
+  // ... existing options ...
+  review?: boolean;  // New: run + update + show diff
+}
+
+.option('--review', 'Run tests, update outputs, show diff for review')
+```
+
+**Behavior**:
+
+```typescript
+if (opts.review) {
+  // Force update mode
+  opts.update = true;
+
+  // After running, show cumulative diff
+  for (const fileResult of fileResults) {
+    if (!fileResult.passed) {
+      const { updated, diff } = await updateTestFile(fileResult.file, fileResult.results);
+      if (updated && diff) {
+        console.log(colors.header(`\n${fileResult.file.path}`));
+        console.log(diff);
+      }
+    }
+  }
+
+  // Exit 0 in review mode
+  process.exit(0);
+}
+```
+
+### Output Format
+
+```
+$ tryscript run tests/manual/ --review
+
+tests/manual/llm-responses.tryscript.md
+  ● Updated: Test: Summarization (output changed)
+  ● Updated: Test: Translation (output changed)
+  ✓ Test: Simple echo
+
+Diff:
+
+--- tests/manual/llm-responses.tryscript.md
++++ tests/manual/llm-responses.tryscript.md (updated)
+@@ -10,7 +10,7 @@
+ ```console
+ $ ai summarize text.txt
+-The text discusses AI ethics and safety concerns...
++The text explores considerations around AI development...
+ ? 0
+ ```
+
+Review complete. 2 tests updated.
+```
+
+### Acceptance Criteria
+
+- [ ] `--review` implies `--update`
+- [ ] Shows unified diff of all changes
+- [ ] Exits 0 (not failure)
+- [ ] Works with `--filter` to review subset
+- [ ] Clear output indicating review mode
+
+---
+
+## Phase III: `validation` Frontmatter Option
+
+### Overview
+
+Add a `validation` field to test file frontmatter to declare whether a test file
+should be treated as binary (automated pass/fail) or manual (requires review).
+
+### Syntax
+
+```yaml
+---
+validation: binary   # Default: standard pass/fail (omitting is same as binary)
+---
+
+---
+validation: manual   # Outputs are expected to vary; review needed
+---
+```
+
+### Behavior Changes
+
+| Mode | Default run | `--review` run | CI behavior |
+|------|-------------|----------------|-------------|
+| `binary` | Pass/fail | Pass/fail | Block on failure |
+| `manual` | Warn if changed | Update + show diff | Create review PR |
+
+**Default run with manual files**:
+
+```bash
+$ tryscript run
+
+tests/cli.tryscript.md
+  ✓ Test: Version
+  ✓ Test: Help
+
+tests/manual/llm.tryscript.md (manual validation)
+  ⚠ Test: Summary (output differs - review needed)
+  ✓ Test: Simple prompt
+
+2 passed, 0 failed, 1 needs review
+```
+
+### Implementation
+
+**Schema** (`types.ts`):
+
+```typescript
+export const TestConfigSchema = z.object({
+  // ... existing fields ...
+  validation: z.enum(['binary', 'manual']).optional().default('binary'),
+});
+```
+
+**Runner changes**:
+
+```typescript
+// When validation: manual, don't count differences as failures
+if (config.validation === 'manual' && !result.passed) {
+  result.needsReview = true;
+  result.passed = true;  // Don't fail the test
+}
+```
+
+**Summary reporting**:
+
+```typescript
+interface TestRunSummary {
+  // ... existing fields ...
+  totalNeedsReview: number;
+}
+```
+
+### Acceptance Criteria
+
+- [ ] `validation: binary` behaves as current default
+- [ ] `validation: manual` doesn't fail on output differences
+- [ ] Summary shows "needs review" count
+- [ ] Exit code reflects only binary test failures
+- [ ] `--review` mode works with both validation types
+
+---
+
+## Phase IV: Review Guidance in Markdown
+
+### Overview
+
+Review criteria are simply written as regular markdown prose in the test file.
+No special syntax needed - the markdown description before each test block
+naturally serves as documentation for what to look for.
+
+### Example
+
+```yaml
+---
+validation: manual
+---
+
+# Test: AI Response Quality
+
+The response should be helpful and accurate. The tone should be professional,
+and the model should not hallucinate facts.
+
+```console
+$ ai-cli ask "What is the capital of France?"
+[.. AI response ..]
+? 0
+```
+```
+
+### Why Plain Markdown
+
+- **Already supported**: Tryscript files are markdown, prose is natural
+- **No parsing needed**: No special syntax to implement
+- **Readable in any context**: Works in GitHub, editors, `cat`, etc.
+- **Self-documenting**: The test file explains itself
+
+### Acceptance Criteria
+
+- [ ] Documentation updated to show prose-based review guidance
+- [ ] Examples use plain markdown, not special annotations
+
+---
+
+## Phase V: CI Integration Patterns
+
+### Overview
+
+Document and provide examples for integrating manual tests into CI/CD workflows.
+
+### GitHub Actions Workflow
+
+**`.github/workflows/manual-tests.yml`**:
+
+```yaml
+name: Manual Test Review
+
+on:
+  schedule:
+    - cron: '0 6 * * 1'  # Weekly on Monday
+  workflow_dispatch:
+
+jobs:
+  update-manual-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - run: npm ci
+      - run: npm run build
+
+      - name: Run manual tests in review mode
+        run: npx tryscript run 'tests/manual/**/*.tryscript.md' --review
+        continue-on-error: true
+
+      - name: Check for changes
+        id: changes
+        run: |
+          if git diff --quiet tests/manual/; then
+            echo "changed=false" >> $GITHUB_OUTPUT
+          else
+            echo "changed=true" >> $GITHUB_OUTPUT
+            git diff tests/manual/ > /tmp/changes.diff
+          fi
+
+      - name: Create Pull Request
+        if: steps.changes.outputs.changed == 'true'
+        uses: peter-evans/create-pull-request@v5
+        with:
+          branch: update-manual-tests
+          title: 'chore: Update manual test baselines'
+          body: |
+            ## Manual Test Baseline Updates
+
+            The following manual tests have updated outputs that require review:
+
+            ```diff
+            $(cat /tmp/changes.diff)
+            ```
+
+            Please review the changes to ensure they are acceptable.
+          commit-message: 'chore: update manual test baselines'
+          labels: |
+            needs-review
+            tests
+```
+
+### Filtering Manual vs Binary Tests
+
+```yaml
+# Run only binary tests (default CI)
+- run: npx tryscript run --filter-validation binary
+
+# Run only manual tests for review
+- run: npx tryscript run --filter-validation manual --review
+```
+
+### Acceptance Criteria
+
+- [ ] GitHub Actions example is complete and tested
+- [ ] Example creates PR with diff
+- [ ] Documentation covers common CI platforms
+- [ ] Filter by validation mode works
+
+---
+
+## Phase VI: Advanced Comparison (Future, If Needed)
+
+### Overview
+
+Most comparison needs are met by `git diff`. This phase documents potential
+extensions that could be added if simple diffs prove insufficient.
+
+### Use Standard Tools First
+
+Before adding custom comparison modes, consider:
+
+```bash
+# Side-by-side diff (already available)
+git diff --word-diff tests/evals/
+diff -y old.txt new.txt
+
+# Custom comparison with shell scripts
+./scripts/compare-outputs.sh tests/evals/search.tryscript.md
+
+# LLM-assisted review (pipe to Claude, etc.)
+git diff tests/evals/ | claude "Review these changes for quality regressions"
+```
+
+### Potential Future Extensions
+
+If standard tools prove insufficient, consider:
+
+| Feature | When Needed | Complexity |
+|---------|-------------|------------|
+| `--diff-format side-by-side` | If git diff isn't readable enough | Low |
+| `--post-update-hook ./script.sh` | Run custom script after update | Low |
+| Built-in LLM comparison | If manual review is too slow | High |
+
+### Philosophy
+
+> "The simplest thing that could possibly work" - Ward Cunningham
+
+Start with `tryscript run --update && git diff`. Add features only when the
+simple approach proves inadequate for real use cases.
+
+---
+
+## Implementation Order
+
+| Phase | Feature | Dependencies | Priority |
+|-------|---------|--------------|----------|
+| I | Playbook documentation | None | High |
+| II | `--review` mode | None | High |
+| III | `validation` option | Playbook for context | Medium |
+| IV | Review guidance (prose) | None | Low (just documentation) |
+| V | CI patterns | I, II | Medium |
+| VI | Advanced comparison | Proven need | Low (future, maybe never) |
+
+**Recommended approach**: Implement Phase I first to establish patterns, then II
+for the core workflow improvement. Validate that the simple approach works before
+adding complexity. Phase VI may never be needed.
+
+---
+
+## Outstanding Questions
+
+1. **Exit code in review mode**: Should `--review` always exit 0, or exit with
+   a distinct code (e.g., 2) to indicate "changes for review"?
+   - **Recommendation**: Exit 0. Review mode is informational, not a gate.
+
+2. **Mixing binary and manual in one file**: Should this be allowed?
+   - **Recommendation**: Validation is per-file. Mixed files should be split.
+
+3. **Default for manual validation**: When `validation: manual`, should
+   `--update` be implicit?
+   - **Recommendation**: No. Explicit is better. `--review` handles this.
+
+4. **Integration with `--fail-fast`**: How should `--fail-fast` work with
+   manual tests?
+   - **Recommendation**: `--fail-fast` only applies to binary tests.
+
+5. **Filter syntax**: `--filter-validation` or `--validation-filter`?
+   - **Recommendation**: `--filter-validation manual|binary` for consistency.
+
+6. **Is `validation: manual` even needed?**: Could we just use file organization
+   (e.g., `tests/evals/` vs `tests/`) instead of frontmatter?
+   - **Recommendation**: Start with file organization, add frontmatter only if needed.
