@jamesaphoenix/tx-cli 0.4.3

package/dist/help.js

@@ -0,0 +1,1366 @@
+/**
+ * CLI help text for all commands
+ */
+import { CLI_VERSION } from "./version.js";
+export const HELP_TEXT = `tx v${CLI_VERSION} - Task management for AI agents and humans
+
+Usage: tx <command> [arguments] [options]
+
+Tasks:
+  init                    Initialize task database
+  add <title>             Create a new task
+  list                    List tasks
+  ready                   List ready tasks (no blockers)
+  show <id>               Show task details
+  update <id>             Update task
+  done <id>               Mark task complete
+  reset <id>              Reset task to ready (recover from stuck)
+  delete <id>             Delete task
+  block <id> <blocker>    Add blocking dependency
+  unblock <id> <blocker>  Remove blocking dependency
+  children <id>           List child tasks
+  tree <id>               Show task subtree
+  try <id> <approach>     Record an attempt on a task
+  attempts <id>           List attempts for a task
+  claim                   Claim a task with a lease
+  claim:release           Release a claim on a task
+  claim:renew             Renew the lease on a claim
+
+Context & Learnings:
+  learning:add            Add a learning
+  learning:search         Search learnings
+  learning:recent         List recent learnings
+  learning:helpful        Record learning helpfulness
+  learning:embed          Compute embeddings for learnings
+  context                 Get contextual learnings for a task
+  learn                   Attach a learning to file/glob pattern
+  recall                  Query learnings for a path
+
+Sync:
+  sync export             Export tasks to JSONL file
+  sync import             Import tasks from JSONL file
+  sync status             Show sync status
+  sync claude             Sync tasks to Claude Code team directory
+  sync codex              Sync tasks to Codex (coming soon)
+
+Traces:
+  trace list              Show recent runs with event counts
+  trace show              Show metrics events for a run
+  trace transcript        Display raw transcript content
+  trace stderr            Display stderr content
+  trace errors            Show recent errors across all runs
+
+Bulk Operations:
+  bulk done <id...>       Complete multiple tasks
+  bulk score <n> <id...>  Set score for multiple tasks
+  bulk reset <id...>      Reset multiple tasks to ready
+  bulk delete <id...>     Delete multiple tasks
+
+Docs:
+  doc add <kind> <name>   Create a doc (overview, prd, design)
+  doc edit <name>         Open doc YAML in $EDITOR
+  doc show <name>         Show doc details
+  doc list                List all docs
+  doc render [name]       Render MD files + regenerate index
+  doc lock <name>         Lock doc (immutable)
+  doc version <name>      Create new version from locked doc
+  doc link <from> <to>    Link two docs
+  doc attach <task> <doc> Link task to doc
+  doc patch <design> <n>  Create design patch on locked doc
+  doc validate            Warn about unlinked tasks
+  doc drift <name>        Detect drift between doc and tasks
+
+Invariants:
+  invariant list          List all invariants
+  invariant show <id>     Show invariant details
+  invariant record <id>   Record pass/fail check result
+  invariant sync          Sync invariants from doc YAML to DB
+
+Cycle Scan:
+  cycle                   Run cycle-based issue discovery scan
+
+Utilities:
+  stats                   Show queue metrics and health overview
+  validate                Run pre-flight database health checks
+  migrate status          Show database migration status
+  doctor                  Run system diagnostics for troubleshooting
+  dashboard               Start API server + dashboard and open in browser
+  mcp-server              Start MCP server (JSON-RPC over stdio)
+
+Global Options:
+  --json                  Output as JSON
+  --db <path>             Database path (default: .tx/tasks.db)
+  --help                  Show help
+  --version               Show version
+
+Run 'tx help <command>' or 'tx <command> --help' for command-specific help.
+
+Examples:
+  tx init
+  tx add "Implement auth" --score 800
+  tx add "Login page" --parent tx-a1b2c3d4 --score 600
+  tx list --status backlog,ready
+  tx ready --json
+  tx block <task-id> <blocker-id>
+  tx done <task-id>`;
+export const commandHelp = {
+    init: `tx init - Initialize task database
+
+Usage: tx init [--db <path>]
+
+Initializes the tx database and required tables. Creates .tx/tasks.db
+by default. Safe to run multiple times (idempotent).
+
+Options:
+  --db <path>   Database path (default: .tx/tasks.db)
+  --help        Show this help
+
+Examples:
+  tx init                     # Initialize in .tx/tasks.db
+  tx init --db ~/my-tasks.db  # Use custom path`,
+    add: `tx add - Create a new task
+
+Usage: tx add <title> [options]
+
+Creates a new task with the given title. Tasks start with status "backlog"
+and default score 500.
+
+Arguments:
+  <title>         Required. The task title (use quotes for multi-word titles)
+
+Options:
+  --parent, -p <id>       Parent task ID (for subtasks)
+  --score, -s <n>         Priority score 0-1000 (default: 500, higher = more important)
+  --description, -d <text> Task description
+  --json                  Output as JSON
+  --help                  Show this help
+
+Examples:
+  tx add "Implement auth"
+  tx add "Login page" --parent tx-a1b2c3d4 --score 600
+  tx add "Fix bug" -s 800 -d "Urgent fix for login"`,
+    list: `tx list - List tasks
+
+Usage: tx list [options]
+
+Lists all tasks, optionally filtered by status. Shows task ID, status,
+score, title, and ready indicator (+).
+
+Options:
+  --status <s>     Filter by status (comma-separated: backlog,ready,active,done)
+  --limit, -n <n>  Maximum tasks to show
+  --json           Output as JSON
+  --help           Show this help
+
+Examples:
+  tx list                          # List all tasks
+  tx list --status backlog,ready   # Only backlog and ready tasks
+  tx list -n 10 --json             # Top 10 as JSON`,
+    ready: `tx ready - List ready tasks
+
+Usage: tx ready [options]
+
+Lists tasks that are ready to work on (status is workable and all blockers
+are done). Sorted by score, highest first.
+
+Options:
+  --limit, -n <n>  Maximum tasks to show (default: 10)
+  --json           Output as JSON
+  --help           Show this help
+
+Examples:
+  tx ready             # Top 10 ready tasks
+  tx ready -n 5        # Top 5 ready tasks
+  tx ready --json      # Output as JSON for scripting`,
+    show: `tx show - Show task details
+
+Usage: tx show <id> [options]
+
+Shows full details for a single task including title, status, score,
+description, parent, blockers, blocks, children, and timestamps.
+
+Arguments:
+  <id>    Required. Task ID (e.g., tx-a1b2c3d4)
+
+Options:
+  --json  Output as JSON
+  --help  Show this help
+
+Examples:
+  tx show tx-a1b2c3d4
+  tx show tx-a1b2c3d4 --json`,
+    update: `tx update - Update a task
+
+Usage: tx update <id> [options]
+
+Updates one or more fields on an existing task.
+
+Arguments:
+  <id>    Required. Task ID (e.g., tx-a1b2c3d4)
+
+Options:
+  --status <s>          New status (backlog|ready|planning|active|blocked|review|human_needs_to_review|done)
+  --title <t>           New title
+  --score <n>           New score (0-1000)
+  --description, -d <text>  New description
+  --parent, -p <id>     New parent task ID
+  --json                Output as JSON
+  --help                Show this help
+
+Examples:
+  tx update tx-a1b2c3d4 --status active
+  tx update tx-a1b2c3d4 --score 900 --title "High priority bug"`,
+    done: `tx done - Mark task complete
+
+Usage: tx done <id> [options]
+
+Marks a task as complete (status = done). Also reports any tasks
+that become unblocked as a result.
+
+Arguments:
+  <id>    Required. Task ID (e.g., tx-a1b2c3d4)
+
+Options:
+  --json  Output as JSON (includes task and newly unblocked task IDs)
+  --help  Show this help
+
+Examples:
+  tx done tx-a1b2c3d4
+  tx done tx-a1b2c3d4 --json`,
+    reset: `tx reset - Reset task to ready status
+
+Usage: tx reset <id> [options]
+
+Resets a task back to ready status, regardless of current status.
+Use this to recover from stuck tasks (e.g., worker killed mid-task).
+
+Arguments:
+  <id>    Required. Task ID (e.g., tx-a1b2c3d4)
+
+Options:
+  --json  Output as JSON
+  --help  Show this help
+
+Examples:
+  tx reset tx-a1b2c3d4              # Reset stuck active task
+  tx reset tx-a1b2c3d4 --json`,
+    delete: `tx delete - Delete a task
+
+Usage: tx delete <id> [options]
+
+Permanently deletes a task. Also removes any dependencies involving
+this task.
+
+Arguments:
+  <id>    Required. Task ID (e.g., tx-a1b2c3d4)
+
+Options:
+  --json  Output as JSON
+  --help  Show this help
+
+Examples:
+  tx delete tx-a1b2c3d4`,
+    block: `tx block - Add blocking dependency
+
+Usage: tx block <task-id> <blocker-id> [options]
+
+Makes one task block another. The blocked task cannot be ready until
+the blocker is marked done. Circular dependencies are not allowed.
+
+Arguments:
+  <task-id>     Required. The task that will be blocked
+  <blocker-id>  Required. The task that blocks it
+
+Options:
+  --json  Output as JSON
+  --help  Show this help
+
+Examples:
+  tx block tx-abc123 tx-def456   # tx-def456 blocks tx-abc123`,
+    unblock: `tx unblock - Remove blocking dependency
+
+Usage: tx unblock <task-id> <blocker-id> [options]
+
+Removes a blocking dependency between two tasks.
+
+Arguments:
+  <task-id>     Required. The task that was blocked
+  <blocker-id>  Required. The task that was blocking it
+
+Options:
+  --json  Output as JSON
+  --help  Show this help
+
+Examples:
+  tx unblock tx-abc123 tx-def456`,
+    children: `tx children - List child tasks
+
+Usage: tx children <id> [options]
+
+Lists all direct children of a task (tasks with this task as parent).
+Shows task ID, status, score, title, and ready indicator (+).
+
+Arguments:
+  <id>    Required. Parent task ID (e.g., tx-a1b2c3d4)
+
+Options:
+  --json  Output as JSON
+  --help  Show this help
+
+Examples:
+  tx children tx-a1b2c3d4
+  tx children tx-a1b2c3d4 --json`,
+    tree: `tx tree - Show task subtree
+
+Usage: tx tree <id> [options]
+
+Shows a task and all its descendants in a tree view. Useful for
+visualizing task hierarchy.
+
+Arguments:
+  <id>    Required. Root task ID (e.g., tx-a1b2c3d4)
+
+Options:
+  --json  Output as JSON (nested structure with childTasks array)
+  --help  Show this help
+
+Examples:
+  tx tree tx-a1b2c3d4
+  tx tree tx-a1b2c3d4 --json`,
+    try: `tx try - Record an attempt on a task
+
+Usage: tx try <task-id> <approach> --failed|--succeeded [reason]
+
+Records an attempt made on a task. Useful for tracking what approaches
+have been tried and their outcomes. Helps agents avoid repeating
+failed approaches.
+
+Arguments:
+  <task-id>    Required. Task ID (e.g., tx-a1b2c3d4)
+  <approach>   Required. Description of the approach tried
+
+Flags (mutually exclusive, one required):
+  --failed     Mark the attempt as failed
+  --succeeded  Mark the attempt as succeeded
+
+Options:
+  [reason]     Optional reason/explanation after the flag
+  --json       Output as JSON
+  --help       Show this help
+
+Examples:
+  tx try tx-abc123 "Used Redux" --failed "Too complex for this use case"
+  tx try tx-abc123 "Used Zustand" --succeeded
+  tx try tx-abc123 "Direct state prop drilling" --failed --json`,
+    attempts: `tx attempts - List attempts for a task
+
+Usage: tx attempts <task-id> [--json]
+
+Lists all attempts recorded for a task, sorted by most recent first.
+Shows the approach tried, outcome (success/failure), reason if any,
+and timestamp.
+
+Arguments:
+  <task-id>  Required. Task ID (e.g., tx-a1b2c3d4)
+
+Options:
+  --json     Output as JSON (full attempt array)
+  --help     Show this help
+
+Examples:
+  tx attempts tx-abc123
+  tx attempts tx-abc123 --json`,
+    "mcp-server": `tx mcp-server - Start MCP server
+
+Usage: tx mcp-server [options]
+
+Starts the Model Context Protocol (MCP) server for integration with
+AI agents. Communicates via JSON-RPC over stdio.
+
+Options:
+  --db <path>  Database path (default: .tx/tasks.db)
+  --help       Show this help
+
+Examples:
+  tx mcp-server
+  tx mcp-server --db ~/project/.tx/tasks.db`,
+    sync: `tx sync - Manage JSONL sync and platform integrations
+
+Usage: tx sync <subcommand> [options]
+
+Subcommands:
+  export    Export all tasks and dependencies to JSONL file
+  import    Import tasks from JSONL file (timestamp-based merge)
+  status    Show sync status and whether database has unexported changes
+  auto      Enable or disable automatic sync on mutations
+  compact   Compact JSONL file by deduplicating operations
+  claude    Write tasks to Claude Code team task directory
+  codex     Write tasks to Codex (coming soon)
+
+Run 'tx sync <subcommand> --help' for subcommand-specific help.
+
+Examples:
+  tx sync export               # Export to .tx/tasks.jsonl
+  tx sync import               # Import from .tx/tasks.jsonl
+  tx sync status               # Show sync status
+  tx sync auto --enable        # Enable auto-sync
+  tx sync compact              # Compact JSONL file
+  tx sync claude --team my-team  # Push tasks to Claude Code team`,
+    "sync export": `tx sync export - Export tasks to JSONL
+
+Usage: tx sync export [options]
+
+Exports tasks and dependencies from the database to JSONL files.
+The files can be committed to git for sharing across machines.
+
+Options:
+  --path <p>        Output file path for tasks (default: .tx/tasks.jsonl)
+  --json            Output result as JSON
+  --help            Show this help
+
+Examples:
+  tx sync export                    # Export tasks only
+  tx sync export --json             # Export as JSON`,
+    "sync import": `tx sync import - Import tasks from JSONL
+
+Usage: tx sync import [options]
+
+Imports tasks from JSONL files into the database. Uses timestamp-based
+conflict resolution: newer records win. Safe to run multiple times.
+
+Options:
+  --path <p>        Input file path for tasks (default: .tx/tasks.jsonl)
+  --json            Output result as JSON
+  --help            Show this help
+
+Examples:
+  tx sync import                    # Import tasks only
+  tx sync import --json             # Import as JSON`,
+    "sync status": `tx sync status - Show sync status
+
+Usage: tx sync status [--json]
+
+Shows the current sync status including:
+- Number of tasks in database
+- Number of operations in JSONL file
+- Whether database has unexported changes (dirty)
+- Auto-sync enabled status
+
+Options:
+  --json  Output as JSON
+  --help  Show this help
+
+Examples:
+  tx sync status
+  tx sync status --json`,
+    "sync auto": `tx sync auto - Manage automatic sync
+
+Usage: tx sync auto [--enable | --disable] [--json]
+
+Controls whether mutations automatically trigger JSONL export.
+When auto-sync is enabled, any task create/update/delete will
+automatically export to the JSONL file.
+
+Options:
+  --enable   Enable auto-sync
+  --disable  Disable auto-sync
+  --json     Output as JSON
+  --help     Show this help
+
+Without flags, shows current auto-sync status.
+
+Examples:
+  tx sync auto              # Show current status
+  tx sync auto --enable     # Enable auto-sync
+  tx sync auto --disable    # Disable auto-sync`,
+    "sync claude": `tx sync claude - Write tasks to Claude Code team directory
+
+Usage: tx sync claude --team <name> [options]
+       tx sync claude --dir <path> [options]
+
+Writes all non-done tx tasks as individual JSON files to a Claude Code
+team's task directory. Tasks appear immediately in the team's TaskList.
+This is a one-way sync: tx is the source of truth.
+
+Teammates should run 'tx done <txId>' when they complete a task to
+write back to the tx database.
+
+Options:
+  --team <name>   Claude Code team name (resolves to ~/.claude/tasks/<name>/)
+  --dir <path>    Direct path to task directory (alternative to --team)
+  --json          Output result as JSON
+  --help          Show this help
+
+Workflow:
+  1. Create team:  Teammate.spawnTeam("my-team")
+  2. Sync tasks:   tx sync claude --team my-team
+  3. Spawn agents: Task tool with team_name="my-team"
+  4. Writeback:    Teammates run 'tx done <txId>' on completion
+
+Examples:
+  tx sync claude --team my-team          # Write to ~/.claude/tasks/my-team/
+  tx sync claude --dir /tmp/tasks        # Write to custom directory
+  tx sync claude --team my-team --json   # JSON output with stats`,
+    "sync codex": `tx sync codex - Write tasks to Codex (coming soon)
+
+Usage: tx sync codex [options]
+
+Writes tasks to OpenAI Codex's task format. Not yet implemented.
+
+Options:
+  --help  Show this help`,
+    "sync compact": `tx sync compact - Compact JSONL file
+
+Usage: tx sync compact [--path <path>] [--json]
+
+Compacts the JSONL file by:
+- Keeping only the latest state for each entity
+- Removing deleted tasks (tombstones)
+- Removing removed dependencies
+
+This reduces file size and improves import performance.
+
+Options:
+  --path <p>  JSONL file path (default: .tx/tasks.jsonl)
+  --json      Output as JSON
+  --help      Show this help
+
+Examples:
+  tx sync compact                       # Compact default file
+  tx sync compact --path ~/shared.jsonl # Compact specific file`,
+    migrate: `tx migrate - Manage database schema migrations
+
+Usage: tx migrate <subcommand> [options]
+
+Subcommands:
+  status    Show current schema version and pending migrations
+
+Run 'tx migrate <subcommand> --help' for subcommand-specific help.
+
+Examples:
+  tx migrate status               # Show migration status`,
+    "migrate status": `tx migrate status - Show migration status
+
+Usage: tx migrate status [--json]
+
+Shows the current schema version, latest available version, applied
+migrations, and any pending migrations that will be applied on next
+database open.
+
+Options:
+  --json  Output as JSON
+  --help  Show this help
+
+Examples:
+  tx migrate status
+  tx migrate status --json`,
+    "learning:add": `tx learning:add - Add a learning
+
+Usage: tx learning:add <content> [options]
+
+Creates a new learning entry. Learnings are pieces of knowledge that can
+be retrieved based on task context.
+
+Arguments:
+  <content>  Required. The learning content/insight to store
+
+Options:
+  -c, --category <cat>     Category tag (e.g., database, auth, api)
+  --source-ref <ref>       Reference to source (e.g., task ID, file path)
+  --source-type <type>     Source type: manual, compaction, run, claude_md (default: manual)
+  --json                   Output as JSON
+  --help                   Show this help
+
+Examples:
+  tx learning:add "Always use transactions for multi-step DB operations"
+  tx learning:add "Rate limit is 100 req/min" -c api
+  tx learning:add "Migration requires downtime" --source-ref tx-abc123`,
+    "learning:search": `tx learning:search - Search learnings
+
+Usage: tx learning:search <query> [options]
+
+Searches learnings using hybrid BM25 + vector search with RRF fusion.
+Returns results ranked by relevance.
+
+Arguments:
+  <query>  Required. Search query (keywords or phrase)
+
+Options:
+  -n, --limit <n>      Maximum results (default: 10)
+  --min-score <n>      Minimum relevance score 0-1 (default: 0.3)
+  --json               Output as JSON
+  --help               Show this help
+
+Examples:
+  tx learning:search "database transactions"
+  tx learning:search "authentication" -n 5 --json`,
+    "learning:recent": `tx learning:recent - List recent learnings
+
+Usage: tx learning:recent [options]
+
+Lists the most recently created learnings.
+
+Options:
+  -n, --limit <n>  Maximum results (default: 10)
+  --json           Output as JSON
+  --help           Show this help
+
+Examples:
+  tx learning:recent
+  tx learning:recent -n 5 --json`,
+    "learning:helpful": `tx learning:helpful - Record learning helpfulness
+
+Usage: tx learning:helpful <id> [options]
+
+Records whether a learning was helpful (outcome feedback). This improves
+future retrieval by boosting helpful learnings in search results.
+
+Arguments:
+  <id>  Required. Learning ID (number)
+
+Options:
+  --score <n>  Helpfulness score 0-1 (default: 1.0)
+  --json       Output as JSON
+  --help       Show this help
+
+Examples:
+  tx learning:helpful 42
+  tx learning:helpful 42 --score 0.8`,
+    "learning:embed": `tx learning:embed - Compute embeddings for learnings
+
+Usage: tx learning:embed [options]
+
+Computes vector embeddings for learnings to enable semantic search.
+Requires TX_EMBEDDINGS=1 environment variable to be set.
+
+Options:
+  --embedder <type>  Select embedder: auto (default), openai, local, noop
+                     Overrides TX_EMBEDDER environment variable
+  --all              Re-embed all learnings (default: only those without embeddings)
+  --status           Show embedding coverage status
+  --json             Output as JSON
+  --help             Show this help
+
+Embedder Types:
+  auto     Auto-detect based on available API keys and packages
+  openai   Use OpenAI text-embedding-3-small (requires OPENAI_API_KEY)
+  local    Use local node-llama-cpp with embeddinggemma-300M
+  noop     Disable embeddings (for testing)
+
+Examples:
+  TX_EMBEDDINGS=1 tx learning:embed                    # Embed with auto-detection
+  TX_EMBEDDINGS=1 tx learning:embed --embedder openai  # Force OpenAI embedder
+  TX_EMBEDDINGS=1 tx learning:embed --embedder local   # Force local embedder
+  TX_EMBEDDINGS=1 tx learning:embed --all              # Re-embed all learnings
+  tx learning:embed --status                           # Show embedding coverage
+  tx learning:embed --status --embedder openai         # Show status with embedder info`,
+    context: `tx context - Get contextual learnings for a task
+
+Usage: tx context <task-id> [options]
+
+Retrieves learnings relevant to a specific task based on its title and
+description. Uses hybrid BM25 + vector search with RRF fusion, optional
+re-ranking and MMR diversification.
+
+Arguments:
+  <task-id>  Required. Task ID (e.g., tx-a1b2c3d4)
+
+Options:
+  --json               Output as JSON
+  --inject             Write to .tx/context.md for injection
+  --retriever <path>   Use custom retriever module (exports Layer<RetrieverService>)
+  --help               Show this help
+
+Custom Retriever Format:
+  The module should export a default Layer that provides RetrieverService:
+
+  // my-retriever.ts
+  import { Layer, Effect } from "effect"
+  import { RetrieverService } from "@jamesaphoenix/tx-core"
+
+  export default Layer.succeed(RetrieverService, {
+    search: (query, options) => Effect.gen(function* () {
+      // Custom Pinecone/Weaviate/Chroma implementation
+      return yield* myVectorSearch(query, options)
+    }),
+    isAvailable: () => Effect.succeed(true)
+  })
+
+Examples:
+  tx context tx-a1b2c3d4
+  tx context tx-a1b2c3d4 --json
+  tx context tx-a1b2c3d4 --inject
+  tx context tx-a1b2c3d4 --retriever ./my-retriever.ts`,
+    learn: `tx learn - Attach a learning to a file path or glob pattern
+
+Usage: tx learn <path> <note> [options]
+
+Stores a file-specific note that can be recalled when working on matching files.
+Supports glob patterns for matching multiple files.
+
+Arguments:
+  <path>    Required. File path or glob pattern (e.g., src/services/*.ts)
+  <note>    Required. The note/learning to attach
+
+Options:
+  --task <id>   Associate with a task ID
+  --json        Output as JSON
+  --help        Show this help
+
+Examples:
+  tx learn "src/db.ts" "Always run migrations in a transaction"
+  tx learn "src/services/*.ts" "Services must use Effect-TS patterns"
+  tx learn "*.test.ts" "Use vitest describe/it syntax" --task tx-abc123`,
+    recall: `tx recall - Query file learnings by path
+
+Usage: tx recall [path] [options]
+
+Retrieves file-specific learnings. If a path is provided, returns learnings
+matching that path (using glob patterns). Without a path, returns all learnings.
+
+Arguments:
+  [path]    Optional. File path to match against stored patterns
+
+Options:
+  --json    Output as JSON
+  --help    Show this help
+
+Examples:
+  tx recall                           # List all file learnings
+  tx recall "src/db.ts"               # Learnings for specific file
+  tx recall "src/services/task.ts"    # Matches patterns like src/services/*.ts
+  tx recall --json`,
+    help: `tx help - Show help
+
+Usage: tx help [command]
+       tx --help
+       tx <command> --help
+
+Shows general help or help for a specific command.
+
+Examples:
+  tx help           # General help
+  tx help add       # Help for 'add' command
+  tx add --help     # Same as above`,
+    trace: `tx trace - Execution tracing for debugging run failures
+
+Usage: tx trace <subcommand> [options]
+
+Subcommands:
+  list                  Show recent runs with event counts
+  show <run-id>         Show metrics events for a run
+  transcript <run-id>   Display raw transcript content
+  stderr <run-id>       Display stderr content
+  errors                Show recent errors across all runs
+
+Run 'tx trace <subcommand> --help' for subcommand-specific help.
+
+Examples:
+  tx trace list                    # Recent runs with span counts
+  tx trace list --hours 48         # Runs from last 48 hours
+  tx trace show run-abc123         # Metrics events for a run
+  tx trace show run-abc123 --full  # Combined events + tool calls timeline
+  tx trace transcript run-abc123   # Raw JSONL transcript
+  tx trace stderr run-abc123       # Stderr output for debugging
+  tx trace errors                  # Recent errors across all runs
+  tx trace errors --hours 48       # Errors from last 48 hours`,
+    "trace list": `tx trace list - Show recent runs with event counts
+
+Usage: tx trace list [options]
+
+Lists recent runs from the database with their agent, task, status, span count,
+and relative time. Useful for quick overview of recent execution activity.
+
+Options:
+  --hours <n>       Time window in hours (default: 24)
+  --limit, -n <n>   Maximum number of results (default: 20)
+  --json            Output as JSON
+  --help            Show this help
+
+Examples:
+  tx trace list                    # Recent runs (last 24h)
+  tx trace list --hours 48         # Last 48 hours
+  tx trace list --limit 10         # Top 10 only
+  tx trace list --json             # JSON output for scripting`,
+    "trace show": `tx trace show - Show metrics events for a run
+
+Usage: tx trace show <run-id> [options]
+
+Displays operational metrics events (spans, metrics) recorded during a run.
+With --full, also includes tool calls from the transcript file, interleaved
+by timestamp for comprehensive debugging.
+
+Arguments:
+  <run-id>   Required. Run ID (e.g., run-abc12345)
+
+Options:
+  --full     Combine events timeline with transcript tool calls
+  --json     Output as JSON
+  --help     Show this help
+
+Output (default):
+  Shows run metadata (agent, task, status, times) followed by metrics events
+  in chronological order with their duration and status.
+
+Output (--full):
+  Shows a combined timeline that interleaves:
+  - [span] Operational spans with timing data
+  - [metric] Custom metrics
+  - [tool] Tool calls from the transcript (e.g., Bash, Read, Edit)
+
+  This is useful for understanding exactly what the agent was doing at each
+  point in time, correlating service operations with agent tool usage.
+
+Examples:
+  tx trace show run-abc123           # Metrics events only
+  tx trace show run-abc123 --full    # Combined timeline with tool calls
+  tx trace show run-abc123 --json    # JSON output for scripting`,
+    "trace errors": `tx trace errors - Show recent errors across all runs
+
+Usage: tx trace errors [options]
+
+Aggregates errors from multiple sources:
+- Failed runs (runs with status='failed')
+- Error spans (operations that threw exceptions)
+- Error events (explicit error events)
+
+Useful for quickly identifying patterns in failures across multiple runs.
+
+Options:
+  --hours <n>       Time window in hours (default: 24)
+  --limit, -n <n>   Maximum number of results (default: 20)
+  --json            Output as JSON
+  --help            Show this help
+
+Examples:
+  tx trace errors                  # Recent errors (last 24h)
+  tx trace errors --hours 48       # Last 48 hours
+  tx trace errors --limit 10       # Top 10 only
+  tx trace errors --json           # JSON output for scripting`,
+    claim: `tx claim - Claim a task for a worker with a lease
+
+Usage: tx claim <task-id> <worker-id> [options]
+
+Claims a task for a worker, preventing other workers from claiming it.
+The claim has a lease duration; if the lease expires, the task becomes
+claimable again. Workers should renew leases for long-running tasks.
+
+Arguments:
+  <task-id>     Required. Task ID (e.g., tx-a1b2c3d4)
+  <worker-id>   Required. Worker ID (e.g., worker-abc12345)
+
+Options:
+  --lease <m>   Lease duration in minutes (default: 30)
+  --json        Output as JSON
+  --help        Show this help
+
+Examples:
+  tx claim tx-abc123 worker-def456              # Claim with default 30m lease
+  tx claim tx-abc123 worker-def456 --lease 60   # Claim with 60m lease
+  tx claim tx-abc123 worker-def456 --json       # JSON output`,
+    "claim:release": `tx claim:release - Release a claim on a task
+
+Usage: tx claim:release <task-id> <worker-id> [options]
+
+Releases a worker's claim on a task, allowing other workers to claim it.
+Only the worker holding the claim can release it.
+
+Arguments:
+  <task-id>     Required. Task ID (e.g., tx-a1b2c3d4)
+  <worker-id>   Required. Worker ID that holds the claim
+
+Options:
+  --json   Output as JSON
+  --help   Show this help
+
+Examples:
+  tx claim:release tx-abc123 worker-def456
+  tx claim:release tx-abc123 worker-def456 --json`,
+    "claim:renew": `tx claim:renew - Renew the lease on a claim
+
+Usage: tx claim:renew <task-id> <worker-id> [options]
+
+Extends the lease on an existing claim. Use this for long-running tasks
+to prevent the claim from expiring. Maximum 10 renewals by default.
+
+Arguments:
+  <task-id>     Required. Task ID (e.g., tx-a1b2c3d4)
+  <worker-id>   Required. Worker ID that holds the claim
+
+Options:
+  --json   Output as JSON
+  --help   Show this help
+
+Fails if:
+  - No active claim exists for this task and worker
+  - The lease has already expired
+  - Maximum renewals (10) have been exceeded
+
+Examples:
+  tx claim:renew tx-abc123 worker-def456
+  tx claim:renew tx-abc123 worker-def456 --json`,
+    validate: `tx validate - Database health checks
+
+Usage: tx validate [options]
+
+Performs comprehensive pre-flight checks on the database:
+- Database integrity (SQLite PRAGMA integrity_check)
+- Schema version verification
+- Foreign key constraint validation
+- Orphaned dependency detection
+- Invalid status values scan
+- Missing parent references
+
+Use before running agents or after sync import to catch corruption early.
+
+Options:
+  --fix    Auto-fix what's fixable (orphaned deps, invalid statuses, missing parent refs)
+  --json   Output as JSON
+  --help   Show this help
+
+Exit Codes:
+  0        Database is valid (no errors)
+  1        Validation failed (errors found)
+
+Examples:
+  tx validate              # Run all checks
+  tx validate --fix        # Auto-fix fixable issues
+  tx validate --json       # Machine-readable output`,
+    stats: `tx stats - Show queue metrics and health overview
+
+Usage: tx stats [options]
+
+Displays aggregate statistics about the task queue including:
+- Task counts by status with percentages
+- Ready tasks grouped by priority (score range)
+- Completion activity (last 24h, 7d, avg per day)
+- Active and expired claim counts
+
+Options:
+  --json   Output as JSON
+  --help   Show this help
+
+Examples:
+  tx stats              # Show queue metrics
+  tx stats --json       # Machine-readable output`,
+    bulk: `tx bulk - Batch operations on multiple tasks
+
+Usage: tx bulk <subcommand> <args...> [options]
+
+Subcommands:
+  done <id...>           Complete multiple tasks at once
+  score <n> <id...>      Set priority score for multiple tasks
+  reset <id...>          Reset multiple tasks to ready status
+  delete <id...>         Delete multiple tasks
+
+Operations are executed sequentially. Each task is processed independently;
+failures on one task do not prevent processing of the remaining tasks.
+A summary of successes and failures is printed at the end.
+
+Options:
+  --json   Output as JSON
+  --help   Show this help
+
+Examples:
+  tx bulk done tx-abc123 tx-def456 tx-ghi789
+  tx bulk score 900 tx-abc123 tx-def456
+  tx bulk reset tx-abc123 tx-def456
+  tx bulk delete tx-abc123 tx-def456 --json`,
+    doctor: `tx doctor - System diagnostics for troubleshooting
+
+Usage: tx doctor [options]
+
+Runs diagnostic checks to help troubleshoot issues:
+- Database file exists and is readable
+- WAL mode enabled
+- Schema version matches expected
+- Effect services are properly wired
+- Stale claims and workers
+- Task and learning counts
+- ANTHROPIC_API_KEY availability for LLM features
+
+Options:
+  --verbose, -v  Include detailed output for each check
+  --json         Output as JSON
+  --help         Show this help
+
+Exit Codes:
+  0        All checks pass (healthy)
+  1        One or more checks failed
+
+Examples:
+  tx doctor              # Run diagnostics
+  tx doctor --verbose    # Include detailed output
+  tx doctor --json       # Machine-readable output`,
+    dashboard: `tx dashboard - Start API server + dashboard and open in browser
+
+Usage: tx dashboard [options]
+
+Starts the dashboard API server (port 3001) and Vite dev server (port 5173),
+then opens the dashboard in Brave Browser (falls back to Chrome).
+
+Options:
+  --no-open    Start servers without opening browser
+  --port <n>   Custom API server port (default: 3001)
+
+Press Ctrl+C to stop both servers.
+
+Examples:
+  tx dashboard              # Start and open in Brave/Chrome
+  tx dashboard --no-open    # Start without opening browser
+  tx dashboard --port 3002  # Custom API port`,
+    doc: `tx doc - Docs as primitives (DD-023)
+
+Usage: tx doc <subcommand> [options]
+
+Subcommands:
+  add <kind> <name>     Create a doc (overview, prd, design)
+  edit <name>           Open doc YAML in $EDITOR
+  show <name>           Show doc details (--md for rendered markdown)
+  list                  List all docs (--kind, --status filters)
+  render [name]         Render MD files + regenerate index
+  lock <name>           Lock doc (immutable after locking)
+  version <name>        Create new version from locked doc (copies content)
+  link <from> <to>      Link two docs (auto-infers link type)
+  attach <task> <doc>   Link task to doc (--type implements|references)
+  patch <design> <name> Create design patch on locked doc
+  validate              Warn about tasks not linked to docs
+  drift <name>          Detect drift between doc and linked tasks
+
+Run 'tx doc <subcommand> --help' for subcommand-specific help.
+
+Examples:
+  tx doc add overview system-design
+  tx doc add design DD-023 --title "Docs as Primitives"
+  tx doc render
+  tx doc lock DD-023
+  tx doc version DD-023
+  tx doc validate`,
+    "doc add": `tx doc add - Create a new doc
+
+Usage: tx doc add <kind> <name> [--title <title>]
+
+Creates a new doc with template YAML content. The file is written to
+.tx/docs/<kind>/<name>.yml (overview docs go to .tx/docs/<name>.yml).
+
+Arguments:
+  <kind>    Required. Doc kind: overview, prd, design
+  <name>    Required. Doc name (e.g., DD-023-docs-as-primitives)
+
+Options:
+  --title, -t <title>   Doc title (defaults to name)
+  --json                Output as JSON
+  --help                Show this help
+
+Notes:
+  - Only ONE overview doc is allowed per project
+  - YAML content is the source of truth; MD is generated via 'tx doc render'
+
+Examples:
+  tx doc add overview system-design --title "System Design & Invariants"
+  tx doc add prd PRD-023 --title "Docs as Primitives"
+  tx doc add design DD-023 --title "Docs as Primitives"`,
+    "doc edit": `tx doc edit - Open doc YAML in editor
+
+Usage: tx doc edit <name>
+
+Opens the doc's YAML file in $EDITOR (defaults to vi).
+
+Arguments:
+  <name>    Required. Doc name
+
+Examples:
+  tx doc edit DD-023
+  EDITOR=code tx doc edit DD-023`,
+    "doc show": `tx doc show - Show doc details
+
+Usage: tx doc show <name> [--md] [--json]
+
+Shows metadata for a doc. Use --md to display rendered markdown content.
+
+Arguments:
+  <name>    Required. Doc name
+
+Options:
+  --md      Show rendered markdown content instead of metadata
+  --json    Output as JSON
+  --help    Show this help
+
+Examples:
+  tx doc show DD-023
+  tx doc show DD-023 --md
+  tx doc show DD-023 --json`,
+    "doc list": `tx doc list - List all docs
+
+Usage: tx doc list [--kind <k>] [--status <s>] [--json]
+
+Lists all docs with their kind, version, status, and title.
+
+Options:
+  --kind, -k <kind>     Filter by kind (overview, prd, design)
+  --status, -s <status> Filter by status (changing, locked)
+  --json                Output as JSON
+  --help                Show this help
+
+Examples:
+  tx doc list
+  tx doc list --kind design
+  tx doc list --status locked --json`,
+    "doc render": `tx doc render - Render MD files from YAML
+
+Usage: tx doc render [name] [--json]
+
+Reads YAML source files and generates markdown. Always regenerates
+index.yml and index.md alongside any specific doc.
+
+Arguments:
+  [name]    Optional. Specific doc to render (default: all)
+
+Options:
+  --json    Output as JSON
+  --help    Show this help
+
+Examples:
+  tx doc render           # Render all docs + index
+  tx doc render DD-023    # Render specific doc + index`,
+    "doc lock": `tx doc lock - Lock a doc
+
+Usage: tx doc lock <name> [--json]
+
+Locks a doc, making it immutable. Renders final MD. To make changes
+to a locked doc, create a new version (tx doc version) or a patch
+(tx doc patch).
+
+Arguments:
+  <name>    Required. Doc name
+
+Options:
+  --json    Output as JSON
+  --help    Show this help
+
+Examples:
+  tx doc lock DD-023`,
+    "doc version": `tx doc version - Create new version from locked doc
+
+Usage: tx doc version <name> [--json]
+
+Creates a new version (v2, v3, etc.) by copying the locked doc's content.
+The new version starts in 'changing' status and can be edited.
+
+Arguments:
+  <name>    Required. Doc name (must be locked)
+
+Options:
+  --json    Output as JSON
+  --help    Show this help
+
+Examples:
+  tx doc version DD-023    # Creates DD-023 v2 from locked v1`,
+    "doc link": `tx doc link - Link two docs
+
+Usage: tx doc link <from-name> <to-name> [--type <link-type>]
+
+Creates a link between two docs. Link type is auto-inferred from
+doc kinds (overview->prd, prd->design, etc.) unless overridden.
+
+Arguments:
+  <from-name>   Required. Source doc name
+  <to-name>     Required. Target doc name
+
+Options:
+  --type <type>   Link type (overview_to_prd, overview_to_design,
+                  prd_to_design, design_patch). Auto-inferred if omitted.
+  --json          Output as JSON
+  --help          Show this help
+
+Examples:
+  tx doc link system-design PRD-023
+  tx doc link PRD-023 DD-023`,
+    "doc attach": `tx doc attach - Link task to doc
+
+Usage: tx doc attach <task-id> <doc-name> [--type <link-type>]
+
+Links a task to a doc. Allowed even on locked docs (Class A bugs
+can reference locked designs).
+
+Arguments:
+  <task-id>     Required. Task ID (e.g., tx-a1b2c3d4)
+  <doc-name>    Required. Doc name
+
+Options:
+  --type <type>   Link type: implements (default) or references
+  --json          Output as JSON
+  --help          Show this help
+
+Examples:
+  tx doc attach tx-abc123 DD-023
+  tx doc attach tx-abc123 DD-023 --type references`,
+    "doc patch": `tx doc patch - Create design patch on locked doc
+
+Usage: tx doc patch <design-name> <patch-name> [--title <title>]
+
+Creates a new design doc linked as a patch to a locked design doc.
+Use for Class B bug fixes on locked designs.
+
+Arguments:
+  <design-name>   Required. Name of locked design doc to patch
+  <patch-name>    Required. Name for the patch doc
+
+Options:
+  --title, -t <title>   Patch title (defaults to patch name)
+  --json                Output as JSON
+  --help                Show this help
+
+Examples:
+  tx doc patch DD-023 DD-023-patch-1 --title "Fix rendering edge case"`,
+    "doc validate": `tx doc validate - Warn about unlinked tasks
+
+Usage: tx doc validate [--json]
+
+Checks all tasks and warns about any that are not linked to a design doc.
+Does not block operations (warn-only enforcement).
+
+Options:
+  --json    Output as JSON
+  --help    Show this help
+
+Examples:
+  tx doc validate
+  tx doc validate --json`,
+    "doc drift": `tx doc drift - Detect drift between doc and tasks
+
+Usage: tx doc drift <name> [--json]
+
+Checks for drift between a doc and its linked tasks. Reports tasks
+that are linked but may not be covered in the doc's work breakdown.
+
+Arguments:
+  <name>    Required. Doc name
+
+Options:
+  --json    Output as JSON
+  --help    Show this help
+
+Examples:
+  tx doc drift DD-023
+  tx doc drift DD-023 --json`,
+    invariant: `tx invariant - Manage structured invariants (DD-023)
+
+Usage: tx invariant <subcommand> [options]
+
+Subcommands:
+  list                  List all invariants (--subsystem, --enforcement filters)
+  show <id>             Show invariant details
+  record <id>           Record pass/fail check result
+  sync                  Sync invariants from doc YAML files to DB
+
+Run 'tx invariant <subcommand> --help' for subcommand-specific help.
+
+Examples:
+  tx invariant list
+  tx invariant list --subsystem docs
+  tx invariant show INV-DOC-001
+  tx invariant record INV-DOC-001 --passed
+  tx invariant sync`,
+    "invariant list": `tx invariant list - List all invariants
+
+Usage: tx invariant list [--subsystem <s>] [--enforcement <e>] [--json]
+
+Lists all invariants with their rule, enforcement type, and status.
+
+Options:
+  --subsystem, -s <sub>     Filter by subsystem (e.g., docs, task-management)
+  --enforcement, -e <type>  Filter by enforcement type (integration_test, linter, llm_as_judge)
+  --json                    Output as JSON
+  --help                    Show this help
+
+Examples:
+  tx invariant list
+  tx invariant list --subsystem docs
+  tx invariant list --enforcement integration_test --json`,
+    "invariant show": `tx invariant show - Show invariant details
+
+Usage: tx invariant show <id> [--json]
+
+Shows full details for an invariant including rule, enforcement type,
+subsystem, test/lint/prompt references, and status.
+
+Arguments:
+  <id>    Required. Invariant ID (e.g., INV-001, INV-DOC-001)
+
+Options:
+  --json    Output as JSON
+  --help    Show this help
+
+Examples:
+  tx invariant show INV-001
+  tx invariant show INV-DOC-001 --json`,
+    "invariant record": `tx invariant record - Record invariant check result
+
+Usage: tx invariant record <id> --passed|--failed [--details <text>]
+
+Manually records the result of checking an invariant. In v1, all
+checks are manual. Automated runners (test, lint, LLM) are v2.
+
+Arguments:
+  <id>    Required. Invariant ID (e.g., INV-001)
+
+Flags (one required):
+  --passed    Record a passing check
+  --failed    Record a failing check
+
+Options:
+  --details, -d <text>  Additional details about the check
+  --json                Output as JSON
+  --help                Show this help
+
+Examples:
+  tx invariant record INV-001 --passed
+  tx invariant record INV-DOC-001 --failed --details "Missing test coverage"
+  tx invariant record INV-001 --passed --json`,
+    cycle: `tx cycle - Run cycle-based issue discovery scan
+
+Usage: tx cycle --task-prompt <text|file> [options]
+
+Dispatches sub-agent swarms to scan for codebase issues, deduplicates
+findings against known issues using LLM-as-judge, and optionally fixes them.
+Repeats in rounds within each cycle until convergence.
+
+Options:
+  --task-prompt <text|file>   Area/work being reviewed (required)
+  --scan-prompt <text|file>   What sub-agents look for (optional)
+  --name <text>              Cycle name (shown in dashboard)
+  --description <text>       Cycle description
+  --cycles <N>               Number of cycles (default: 1)
+  --max-rounds <N>           Max rounds per cycle (default: 10)
+  --agents <N>               Parallel scan agents per round (default: 3)
+  --model <model>            LLM model (default: claude-opus-4-6)
+  --fix                      Enable fix agent between scan rounds
+  --scan-only                Skip fix phase (explicit default)
+  --dry-run                  Report only, no DB writes
+  --score <N>                Base score for new tasks (default: 500)
+  --json                     Output as JSON
+
+Examples:
+  tx cycle --task-prompt "Review core services" --scan-prompt "Find bugs"
+  tx cycle --task-prompt "Auth module" --scan-only --name "Auth review"
+  tx cycle --task-prompt "Review core" --agents 2 --model claude-sonnet-4-5-20250929
+  tx cycle --task-prompt "Full review" --cycles 3 --fix`,
+    "invariant sync": `tx invariant sync - Sync invariants from doc YAML to DB
+
+Usage: tx invariant sync [--doc <name>] [--json]
+
+Parses invariant definitions from doc YAML files and upserts them
+into the database. Invariants removed from YAML are deprecated.
+
+Options:
+  --doc <name>   Only sync invariants from a specific doc
+  --json         Output as JSON
+  --help         Show this help
+
+Examples:
+  tx invariant sync                    # Sync all docs
+  tx invariant sync --doc DD-023       # Sync specific doc
+  tx invariant sync --json`
+};
+//# sourceMappingURL=help.js.map