trekoon 0.3.3 → 0.3.4

package/src/commands/help.ts

@@ -10,37 +10,38 @@ const ROOT_HELP = [
   "  trekoon [global-options] <command> [command-options]",
   "",
   "Global options:",
-  "  --json       Emit stable JSON machine output",
-  "  --toon       Emit true TOON-encoded output",
-  "  --compat <mode>  Enable explicit machine compatibility mode",
-  "  --help       Show root or command help",
+  "  --json       Structured JSON output",
+  "  --toon       TOON-encoded output (preferred for agents)",
+  "  --compat <mode>  Machine compatibility mode",
+  "  --help       Show help for root or a command",
   "  --version    Print CLI version",
   "",
   "Commands:",
-  "  help         Show root or command help",
-  "  init         Initialize repo-shared .trekoon storage and DB",
-  "  quickstart   Show shared-storage bootstrap + AI execution loop",
-  "  wipe         Remove repo-shared Trekoon state (requires --yes)",
-  "  board        Local board asset and browser commands",
-  "  epic         Epic lifecycle commands",
-  "  task         Task lifecycle commands",
-  "  subtask      Subtask lifecycle commands",
-  "  dep          Dependency graph commands",
-  "  events       Event retention and cleanup commands",
-  "  migrate      Migration status and rollback commands",
-  "  session      One-call agent orientation (diagnostics + sync + next task)",
-  "  sync         Cross-branch sync commands",
-  "  skills       Skill install/update/link (local and global)",
+  "  help         Show help for root or a command",
+  "  init         Create or re-bootstrap .trekoon storage",
+  "  quickstart   Storage model, agent loop, and common patterns",
+  "  wipe         Delete repo-wide .trekoon state (requires --yes)",
+  "  board        Open or update the local board",
+  "  epic         Create, list, update, search, and track epics",
+  "  task         Create, list, update, search, and complete tasks",
+  "  subtask      Create, list, update, and search subtasks",
+  "  dep          Manage dependency edges between tasks and subtasks",
+  "  events       Prune old sync event log rows",
+  "  migrate      Check schema version or roll back migrations",
+  "  session      Agent orientation (diagnostics + sync + next task)",
+  "  suggest      Priority-ranked next-action suggestions",
+  "  sync         Pull events and resolve conflicts across branches",
+  "  skills       Install, link, or update the Trekoon skill",
   "  update       Alias for skills update",
 ].join("\n");
 
 const INIT_HELP = [
   "Usage: trekoon init [--json|--toon]",
   "",
-  "Purpose:",
-  "  Initialize repo-scoped Trekoon storage (.trekoon) and database.",
-  "  In git worktrees, every worktree shares the same repository DB.",
-  "  Keep .trekoon gitignored; committing the SQLite DB is not a recovery path.",
+  "Creates or re-bootstraps the repo-scoped .trekoon directory and database.",
+  "In worktree setups, every worktree shares the same DB.",
+  "",
+  "Keep .trekoon gitignored. Committing the SQLite DB is not a recovery path.",
   "",
   "Examples:",
   "  trekoon init",
@@ -50,17 +51,19 @@ const INIT_HELP = [
 const QUICKSTART_HELP = [
   "Usage: trekoon quickstart [--json|--toon]",
   "",
-  "Purpose:",
-  "  Show shared-storage bootstrap, diagnostics, and the canonical AI loop.",
+  "Prints the storage model, agent execution loop, and common command patterns.",
+  "",
+  "Recommended startup flow:",
+  "  1. trekoon --toon session",
+  "  2. Stop if diagnostics report recoveryRequired or a tracked/ignored mismatch",
+  "  3. If behind: trekoon --toon sync pull --from main",
+  "  4. Claim work: trekoon --toon task update <task-id> --status in_progress",
+  "  5. Finish: trekoon --toon task done <task-id>",
   "",
-  "Flow:",
-  "  1) trekoon --toon init",
-  "  2) trekoon --toon sync status",
-  "  3) Fail fast on recoveryRequired or tracked/ignored mismatch diagnostics",
-  "  4) trekoon --toon task ready --limit 5",
-  "  5) trekoon --toon task next",
-  "  6) trekoon --toon dep reverse <task-or-subtask-id>",
-  "  7) trekoon --toon task update <task-id> --status in_progress",
+  "Manual bootstrap (if you need step-by-step):",
+  "  1. trekoon --toon init",
+  "  2. trekoon --toon sync status",
+  "  3. trekoon --toon task next",
   "",
   "Examples:",
   "  trekoon quickstart",
@@ -70,16 +73,14 @@ const QUICKSTART_HELP = [
 const WIPE_HELP = [
   "Usage: trekoon wipe --yes [--json|--toon]",
   "",
-  "Purpose:",
-  "  Remove the repository's shared Trekoon storage directory.",
-  "  In git worktrees this erases the same .trekoon state for every linked worktree.",
+  "Deletes the shared .trekoon directory for the entire repository.",
+  "In worktree setups, this erases state for every linked worktree.",
   "",
   "Options:",
-  "  --yes  Required confirmation for destructive repo-wide removal.",
+  "  --yes  Required. Confirms you want the destructive delete.",
   "",
-  "Recovery guidance:",
-  "  Use wipe only for explicit destructive recovery.",
-  "  Do not use wipe to fix gitignore mistakes or to replace bootstrap diagnostics.",
+  "This is a last-resort recovery tool. Don't use it to fix gitignore",
+  "issues or replace proper bootstrap diagnostics.",
   "",
   "Examples:",
   "  trekoon wipe --yes",
@@ -89,15 +90,12 @@ const BOARD_HELP = [
   "Usage: trekoon board <open|update>",
   "",
   "Subcommands:",
-  "  open",
-  "      Ensure board assets are installed, start a 127.0.0.1 board server,",
-  "      and launch the browser. Machine output includes server URL, fallback URL,",
-  "      and launch metadata.",
-  "  update",
-  "      Refresh board runtime assets only. Does not start the server or open a browser.",
+  "  open    Install board assets, start a local server on 127.0.0.1,",
+  "          and open the browser. Returns the board URL and a fallback URL.",
+  "  update  Refresh board runtime assets only. No server, no browser.",
   "",
-  "Environment overrides:",
-  "  TREKOON_BOARD_ASSET_ROOT  Optional asset source override for tests and local development.",
+  "Environment:",
+  "  TREKOON_BOARD_ASSET_ROOT  Override the bundled asset source (tests/dev only).",
   "",
   "Examples:",
   "  trekoon board open",
@@ -105,172 +103,135 @@ const BOARD_HELP = [
 ].join("\n");
 
 const EPIC_HELP = [
-  "Usage: trekoon epic <create|expand|list|show|search|replace|update|delete> [options]",
+  "Usage: trekoon epic <create|expand|list|show|search|replace|update|delete|progress> [options]",
   "",
-  "Create behavior:",
+  "Create:",
   "  trekoon epic create --title \"...\" --description \"...\" [--status <status>]",
   "  trekoon epic create --title \"...\" --description \"...\" [--task <spec>] [--subtask <spec>] [--dep <spec>]",
-  "  Preferred one-shot flow when the full tree is known up front.",
-  "  Uses the same compact spec grammar as epic expand and returns mappings/counts.",
+  "  When the full tree is known, the second form creates everything in one shot",
+  "  and returns mappings/counts. Same compact spec grammar as epic expand.",
   "",
-  "Expand behavior:",
+  "Expand:",
   "  trekoon epic expand <epic-id> [--task <spec>] [--subtask <spec>] [--dep <spec>]",
   "  --task <temp-key>|<title>|<description>|<status>",
-  `  --subtask <parent-ref>|<temp-key>|<title>|<description>|<status>  (use ${"@"}<temp-key> for newly declared parents)`,
-  `  --dep <source-ref>|<depends-on-ref>  (refs can be ids or ${"@"}<temp-key>)`,
-  "  Escapes inside compact specs: \\| for |, \\\\ for \\, \\n, \\r, \\t",
-  "",
-  "List behavior:",
-  "  Defaults:",
-  "    - Open statuses only: in_progress, in-progress, todo",
-  "    - Limit: 10",
-  "  Flags:",
-  "    --status <csv> | --limit <n> | --cursor <n> | --all | --view table|compact",
-  "  Pagination:",
-  "    - --cursor is offset-like",
-  "    - Machine modes expose meta.pagination.hasMore / nextCursor",
-  "  Constraints:",
-  "    - --all is mutually exclusive with --status, --limit, and --cursor",
-  "",
-  "Show behavior:",
-  "  Views:",
-  "    - table: default view",
-  "    - compact: epic summary",
-  "    - tree: hierarchy",
-  "    - detail: descriptions",
-  "  Machine default:",
-  "    - With --all, machine modes default to detail",
-  "",
-  "Search/Replace behavior:",
-  "  search:",
-  "    - trekoon epic search <epic-id> \"search text\"",
-  "    - Options: --fields title|description|title,description, --preview",
-  "    - Scope: epic title/description + descendant task/subtask title/description",
-  "  replace:",
-  "    - trekoon epic replace <epic-id> --search \"text\" --replace \"text\"",
-  "    - Preview is default; use --apply to mutate",
-  "    - --preview and --apply are mutually exclusive",
-  "",
-  "Update behavior:",
-  "  Repo-wide bulk mode:",
-  "    trekoon epic update --all --append <text> [--status <status>]",
-  "    trekoon epic update --ids <csv> --append <text> [--status <status>]",
-  "    - preserves existing per-row bulk behavior; not one atomic multi-row update",
-  "  Descendant cascade mode:",
-  "    trekoon epic update <epic-id> --all --status done|todo",
-  "    - cascades atomically through descendant tasks and subtasks",
-  "    - blocked descendants abort the whole update",
-  "    - cascade mode supports only --status done|todo",
-  "    - do not combine positional id + --all with --ids, --append, --description, or --title",
+  `  --subtask <parent-ref>|<temp-key>|<title>|<description>|<status>  (${"@"}<temp-key> for new parents)`,
+  `  --dep <source-ref>|<depends-on-ref>  (refs can be IDs or ${"@"}<temp-key>)`,
+  "  Escapes in compact specs: \\| for |, \\\\ for \\, \\n, \\r, \\t",
+  "",
+  "List:",
+  "  Defaults: open work only (in_progress, todo), limit 10.",
+  "  --status <csv> | --limit <n> | --cursor <n> | --all | --view table|compact",
+  "  Pagination: --cursor is offset-like. Machine output has meta.pagination.hasMore / nextCursor.",
+  "  --all is mutually exclusive with --status, --limit, and --cursor.",
+  "",
+  "Show:",
+  "  --view table (default) | compact | tree | detail",
+  "  With --all in machine mode, defaults to detail view.",
+  "",
+  "Search/Replace:",
+  "  trekoon epic search <epic-id> \"search text\" [--fields title|description|title,description] [--preview]",
+  "  Searches epic + descendant task/subtask titles and descriptions.",
+  "",
+  "  trekoon epic replace <epic-id> --search \"text\" --replace \"text\" [--apply]",
+  "  Preview is default. Use --apply to write changes. --preview and --apply are mutually exclusive.",
+  "",
+  "Update (bulk mode, no positional ID):",
+  "  trekoon epic update --all --append <text> [--status <status>]",
+  "  trekoon epic update --ids <csv> --append <text> [--status <status>]",
+  "  Per-row updates, not one atomic transaction.",
+  "",
+  "Update (cascade mode, with positional ID):",
+  "  trekoon epic update <epic-id> --all --status done|todo",
+  "  Cascades atomically through all descendant tasks and subtasks.",
+  "  Blocked descendants abort the whole update. Only --status done|todo is supported.",
+  "  Don't combine positional ID + --all with --ids, --append, --description, or --title.",
+  "",
+  "Progress:",
+  "  trekoon epic progress <epic-id>",
+  "  Returns done/in_progress/blocked/todo counts, readyCount, and nextCandidate.",
 ].join("\n");
 
 const TASK_HELP = [
   "Usage: trekoon task <create|create-many|list|show|ready|next|done|search|replace|update|delete> [options]",
   "",
-  "Create-many behavior:",
+  "Create-many:",
   "  trekoon task create-many --epic <epic-id> --task <spec> [--task <spec> ...]",
   "  --task <temp-key>|<title>|<description>|<status>",
-  "  Rejects unexpected positional arguments and empty required fields.",
-  "  Repeated --task flags are applied in the order provided.",
-  "  Escapes inside compact specs: \\| for |, \\\\ for \\, \\n, \\r, \\t",
-  "",
-  "List behavior:",
-  "  Defaults:",
-  "    - Open statuses only: in_progress, in-progress, todo",
-  "    - Limit: 10",
-  "  Flags:",
-  "    --epic <id> | --status <csv> | --limit <n> | --cursor <n> | --all | --view table|compact",
-  "  Pagination:",
-  "    - --cursor is offset-like",
-  "    - Machine modes expose meta.pagination.hasMore / nextCursor",
-  "  Constraints:",
-  "    - --all is mutually exclusive with --status, --limit, and --cursor",
-  "",
-  "Show behavior:",
-  "  Views:",
-  "    - table: default view",
-  "    - compact: task summary",
-  "    - tree: hierarchy",
-  "    - detail: descriptions",
-  "  Machine default:",
-  "    - With --all, machine modes default to detail",
-  "",
-  "Ready/Next behavior:",
-  "  ready:",
-  "    - Returns deterministic unblocked candidates",
-  "    - Sort order: status, blockers, createdAt, id",
-  "    - Options: --limit <n>, --epic <id>",
-  "  next:",
-  "    - Returns top ready candidate",
-  "    - Option: --epic <id>",
-  "",
-  "Search/Replace behavior:",
-  "  search:",
-  "    - trekoon task search <task-id> \"search text\"",
-  "    - Options: --fields title|description|title,description, --preview",
-  "    - Scope: task title/description + descendant subtask title/description",
-  "  replace:",
-  "    - trekoon task replace <task-id> --search \"text\" --replace \"text\"",
-  "    - Preview is default; use --apply to mutate",
-  "    - --preview and --apply are mutually exclusive",
-  "",
-  "Update behavior:",
-  "  Repo-wide bulk mode:",
-  "    trekoon task update --all --append <text> [--status <status>]",
-  "    trekoon task update --ids <csv> --append <text> [--status <status>]",
-  "    - preserves existing per-row bulk behavior; not one atomic multi-row update",
-  "  Descendant cascade mode:",
-  "    trekoon task update <task-id> --all --status done|todo",
-  "    - cascades atomically through descendant subtasks",
-  "    - blocked descendants abort the whole update",
-  "    - cascade mode supports only --status done|todo",
-  "    - do not combine positional id + --all with --ids, --append, --description, or --title",
+  "  Multiple --task flags are applied in order.",
+  "  Escapes in compact specs: \\| for |, \\\\ for \\, \\n, \\r, \\t",
+  "",
+  "List:",
+  "  Defaults: open work only (in_progress, todo), limit 10.",
+  "  --epic <id> | --status <csv> | --limit <n> | --cursor <n> | --all | --view table|compact",
+  "  Pagination: --cursor is offset-like. Machine output has meta.pagination.hasMore / nextCursor.",
+  "  --all is mutually exclusive with --status, --limit, and --cursor.",
+  "",
+  "Show:",
+  "  --view table (default) | compact | tree | detail",
+  "  With --all in machine mode, defaults to detail view.",
+  "",
+  "Ready/Next:",
+  "  ready  Returns unblocked candidates sorted by status, blockers, createdAt, id.",
+  "         Options: --limit <n>, --epic <id>",
+  "  next   Returns the top ready candidate. Option: --epic <id>",
+  "",
+  "Done:",
+  "  trekoon task done <task-id>",
+  "  Marks the task complete, auto-transitions through in_progress if needed,",
+  "  reports unblocked downstream tasks, warns about open subtasks, and returns",
+  "  the next ready candidate.",
+  "",
+  "Search/Replace:",
+  "  trekoon task search <task-id> \"search text\" [--fields title|description|title,description] [--preview]",
+  "  Searches task + descendant subtask titles and descriptions.",
+  "",
+  "  trekoon task replace <task-id> --search \"text\" --replace \"text\" [--apply]",
+  "  Preview is default. Use --apply to write changes. --preview and --apply are mutually exclusive.",
+  "",
+  "Update (bulk mode, no positional ID):",
+  "  trekoon task update --all --append <text> [--status <status>]",
+  "  trekoon task update --ids <csv> --append <text> [--status <status>]",
+  "  Per-row updates, not one atomic transaction.",
+  "",
+  "Update (cascade mode, with positional ID):",
+  "  trekoon task update <task-id> --all --status done|todo",
+  "  Cascades atomically through descendant subtasks.",
+  "  Blocked descendants abort the whole update. Only --status done|todo is supported.",
+  "  Don't combine positional ID + --all with --ids, --append, --description, or --title.",
 ].join("\n");
 
 const SUBTASK_HELP = [
   "Usage: trekoon subtask <create|create-many|list|search|replace|update|delete> [options]",
   "",
-  "Create-many behavior:",
+  "Create-many:",
   "  trekoon subtask create-many [<task-id>] [--task <task-id>] --subtask <spec> [--subtask <spec> ...]",
   "  --subtask <temp-key>|<title>|<description>|<status>",
-  "  Positional <task-id> and --task may be combined only when equal.",
-  "  Rejects extra positional arguments and empty required fields.",
-  "  Repeated --subtask flags are applied in the order provided.",
-  "  Escapes inside compact specs: \\| for |, \\\\ for \\, \\n, \\r, \\t",
-  "",
-  "List behavior:",
-  "  Defaults:",
-  "    - Open statuses only: in_progress, in-progress, todo",
-  "    - Limit: 10",
-  "  Flags:",
-  "    --task <id> | --status <csv> | --limit <n> | --cursor <n> | --all | --view table|compact",
-  "  Pagination:",
-  "    - --cursor is offset-like",
-  "    - Machine modes expose meta.pagination.hasMore / nextCursor",
-  "  Constraints:",
-  "    - --all is mutually exclusive with --status, --limit, and --cursor",
-  "",
-  "Search/Replace behavior:",
-  "  search:",
-  "    - trekoon subtask search <subtask-id> \"search text\"",
-  "    - Options: --fields title|description|title,description, --preview",
-  "    - Scope: subtask title/description only",
-  "  replace:",
-  "    - trekoon subtask replace <subtask-id> --search \"text\" --replace \"text\"",
-  "    - Preview is default; use --apply to mutate",
-  "    - --preview and --apply are mutually exclusive",
-  "",
-  "Update behavior:",
-  "  Repo-wide bulk mode:",
-  "    trekoon subtask update --all --append <text> [--status <status>]",
-  "    trekoon subtask update --ids <csv> --append <text> [--status <status>]",
-  "    - preserves existing per-row bulk behavior; not one atomic multi-row update",
-  "  Positional-id cascade syntax:",
-  "    trekoon subtask update <subtask-id> --all --status done|todo",
-  "    - accepted for contract consistency",
-  "    - behaves like a normal single-subtask status update",
-  "    - positional id + --all supports only --status done|todo",
-  "    - do not combine positional id + --all with --ids, --append, --description, or --title",
+  "  Positional <task-id> and --task can be combined only when equal.",
+  "  Multiple --subtask flags are applied in order.",
+  "  Escapes in compact specs: \\| for |, \\\\ for \\, \\n, \\r, \\t",
+  "",
+  "List:",
+  "  Defaults: open work only (in_progress, todo), limit 10.",
+  "  --task <id> | --status <csv> | --limit <n> | --cursor <n> | --all | --view table|compact",
+  "  Pagination: --cursor is offset-like. Machine output has meta.pagination.hasMore / nextCursor.",
+  "  --all is mutually exclusive with --status, --limit, and --cursor.",
+  "",
+  "Search/Replace:",
+  "  trekoon subtask search <subtask-id> \"search text\" [--fields title|description|title,description] [--preview]",
+  "  Searches subtask title and description only.",
+  "",
+  "  trekoon subtask replace <subtask-id> --search \"text\" --replace \"text\" [--apply]",
+  "  Preview is default. Use --apply to write changes. --preview and --apply are mutually exclusive.",
+  "",
+  "Update (bulk mode, no positional ID):",
+  "  trekoon subtask update --all --append <text> [--status <status>]",
+  "  trekoon subtask update --ids <csv> --append <text> [--status <status>]",
+  "  Per-row updates, not one atomic transaction.",
+  "",
+  "Update (positional-ID cascade syntax):",
+  "  trekoon subtask update <subtask-id> --all --status done|todo",
+  "  Accepted for consistency, but just updates the one subtask (no descendants).",
+  "  Don't combine positional ID + --all with --ids, --append, --description, or --title.",
 ].join("\n");
 
 const DEP_HELP = [
@@ -278,13 +239,12 @@ const DEP_HELP = [
   "",
   "Subcommands:",
   "  add <source-id> <depends-on-id>",
-  "      Create dependency edge: source depends on depends-on.",
+  "      Create a dependency edge: source depends on depends-on.",
   "  add-many --dep <source-ref>|<depends-on-ref> [--dep <spec> ...]",
-  "      Create validated dependency edges from compact specs in order.",
-  "      Standalone add-many resolves persisted ids only; @<temp-key>",
-  "      refs are reserved for higher-level compact batch workflows.",
+  "      Create multiple edges from compact specs in order.",
+  "      Uses persisted IDs only; @<temp-key> refs are for batch workflows.",
   "  remove <source-id> <depends-on-id>",
-  "      Remove one dependency edge if it exists.",
+  "      Remove one dependency edge.",
   "  list <source-id>",
   "      Show direct dependencies for a node.",
   "  reverse <target-id>",
@@ -300,13 +260,12 @@ const DEP_HELP = [
 const EVENTS_HELP = [
   "Usage: trekoon events prune [--dry-run] [--archive] [--retention-days <n>]",
   "",
-  "Purpose:",
-  "  Manage retention for internal sync event log rows.",
+  "Cleans up old sync event log rows.",
   "",
   "Options:",
-  "  --dry-run             Preview candidate/archive/delete counts only.",
-  "  --archive             Copy pruned rows to event_archive before delete.",
-  "  --retention-days <n>  Keep last n days (positive integer, default 90).",
+  "  --dry-run             Preview counts only, don't delete anything.",
+  "  --archive             Copy pruned rows to event_archive before deleting.",
+  "  --retention-days <n>  Keep the last n days (positive integer, default 90).",
   "",
   "Examples:",
   "  trekoon events prune --dry-run",
@@ -318,10 +277,8 @@ const MIGRATE_HELP = [
   "Usage: trekoon migrate <status|rollback> [--to-version <n>]",
   "",
   "Subcommands:",
-  "  status",
-  "      Show current schema version, latest version, and pending count.",
-  "  rollback [--to-version <n>]",
-  "      Roll back migrations; default target is one version back.",
+  "  status                Show current schema version, latest version, and pending count.",
+  "  rollback [--to-version <n>]  Roll back migrations. Defaults to one version back.",
   "",
   "Examples:",
   "  trekoon migrate status",
@@ -334,22 +291,32 @@ const SYNC_HELP = [
   "",
   "Subcommands:",
   "  status [--from <branch>]",
-  "      Show ahead/behind counts and pending conflicts vs source branch (default: main).",
+  "      Ahead/behind counts and pending conflicts vs a source branch (default: main).",
   "  pull --from <branch>",
-  "      Pull and apply upstream tracker events from a source branch.",
+  "      Pull upstream tracker events from a source branch.",
   "  conflicts list [--mode pending|all]",
-  "      List sync conflicts (default mode: pending).",
+  "      List sync conflicts (default: pending only).",
   "  conflicts show <conflict-id>",
   "      Show full details for one conflict.",
-  "  resolve <conflict-id> --use ours|theirs",
-  "      Resolve a pending conflict by selecting ours or theirs.",
+  "  resolve <conflict-id> --use ours|theirs [--dry-run]",
+  "      Resolve a conflict. --dry-run previews without writing.",
+  "",
+  "Ours vs theirs:",
+  "  Conflicts are field-level (e.g., status, title, description on one entity).",
+  "  --use ours   Keep the current DB value. Nothing is written.",
+  "  --use theirs  Overwrite the DB field with the source-branch value.",
   "",
-  "Compatibility mode:",
+  "  Example: epic abc123, field: status",
+  "    ours (current DB): in_progress",
+  "    theirs (source branch): done",
+  "    --use ours  -> stays in_progress",
+  "    --use theirs -> becomes done",
+  "",
+  "Compatibility:",
   "  --compat legacy-sync-command-ids",
-  "      Emits legacy sync command IDs (sync_status, sync_pull, ...)",
-  "      in machine output only and includes deprecation metadata.",
-  "      Migration: remove --compat and consume dotted IDs (sync.status).",
-  "      Planned compatibility window closes after 2026-09-30.",
+  "      Emits legacy sync command IDs (sync_status, sync_pull, ...) in machine",
+  "      output. Includes deprecation metadata. Window closes after 2026-09-30.",
+  "      Migration: drop --compat and use dotted IDs (sync.status).",
   "",
   "Examples:",
   "  trekoon sync status",
@@ -362,15 +329,17 @@ const SYNC_HELP = [
 ].join("\n");
 
 const SESSION_HELP = [
-  "Usage: trekoon session [--json|--toon]",
+  "Usage: trekoon session [--epic <epic-id>] [--json|--toon]",
+  "",
+  "One-call agent orientation. Opens the DB once and returns:",
+  "  - diagnostics: storageMode, recoveryRequired, recoveryStatus",
+  "  - sync: ahead/behind counts and pendingConflicts vs main",
+  "  - next: full task tree with subtasks for the top ready candidate (null if none)",
+  "  - nextDeps: blocker list with statuses (empty if none)",
+  "  - readiness: readyCount and blockedCount across all open tasks",
   "",
-  "Purpose:",
-  "  One-call agent orientation. Opens DB once and returns:",
-  "    - diagnostics: storageMode, recoveryRequired, recoveryStatus",
-  "    - sync: ahead/behind counts and pendingConflicts vs main",
-  "    - next: full task tree with subtasks for the top ready candidate (null if none)",
-  "    - nextDeps: blocker list with statuses for the next task (empty if none)",
-  "    - readiness: readyCount and blockedCount across all open tasks",
+  "Options:",
+  "  --epic <epic-id>  Scope readiness to a specific epic.",
   "",
   "Output modes:",
   "  human  Multi-section summary (default in TTY)",
@@ -380,42 +349,59 @@ const SESSION_HELP = [
   "Examples:",
   "  trekoon session",
   "  trekoon --toon session",
+  "  trekoon --toon session --epic <epic-id>",
   "  trekoon --json session",
 ].join("\n");
 
+const SUGGEST_HELP = [
+  "Usage: trekoon suggest [--epic <epic-id>] [--json|--toon]",
+  "",
+  "Returns up to 3 priority-ranked next-action suggestions based on recovery",
+  "state, sync status, task readiness, and epic progress.",
+  "",
+  "Options:",
+  "  --epic <epic-id>  Scope suggestions to a specific epic.",
+  "",
+  "Categories:",
+  "  recovery   Storage needs repair",
+  "  sync       Behind main or pending conflicts",
+  "  execution  In-progress or ready tasks to pick up",
+  "  planning   All blocked, epic close, or empty tracker",
+  "",
+  "Each suggestion includes an action, a ready-to-run command, and a reason.",
+  "",
+  "Examples:",
+  "  trekoon suggest",
+  "  trekoon --toon suggest",
+  "  trekoon --toon suggest --epic <epic-id>",
+].join("\n");
+
 const SKILLS_HELP = [
   "Usage:",
   "  trekoon skills install [--link --editor opencode|claude|pi] [--to <path>] [--allow-outside-repo]",
   "  trekoon skills install -g|--global [--editor opencode|claude|pi]",
   "  trekoon skills update",
   "",
-  "Purpose:",
-  "  Install or refresh the Trekoon skill asset locally or globally.",
-  "",
-  "Local install behavior (default):",
-  "  - Creates a directory symlink at <cwd>/.agents/skills/trekoon pointing to",
-  "    the bundled package source, so the skill always matches the installed version.",
-  "  - Use --link to also create an editor symlink named 'trekoon'.",
-  "  - --editor is required when --link is used (opencode|claude|pi).",
-  "  - --to overrides the symlink root for --link only.",
-  "  - Without --allow-outside-repo, link targets must resolve inside repo.",
-  "  - --allow-outside-repo requires --link and disables that boundary check.",
-  "",
-  "Global install behavior (-g|--global):",
-  "  - Creates a global anchor symlink at ~/.agents/skills/trekoon pointing to",
-  "    the bundled package source.",
-  "  - Creates per-editor symlinks under each editor's global skills directory",
-  "    (~/.claude/skills/, ~/.config/opencode/skills/, ~/.pi/skills/).",
-  "  - Use --editor to install for a single editor only.",
-  "",
-  "Update behavior:",
-  "  - Probes and repairs both global and local anchor/editor symlinks.",
-  "  - Reports per-entry status: ok, repointed, created, migrated, skipped.",
-  "  - Skips entries that are not installed; creates local editor links when",
-  "    the editor config dir exists.",
-  "",
-  "Alias:",
-  "  trekoon update → trekoon skills update",
+  "Installs or refreshes the Trekoon skill so AI agents can plan and execute.",
+  "",
+  "Local install (default):",
+  "  Creates a symlink at .agents/skills/trekoon pointing to the bundled source,",
+  "  so the skill always matches the installed CLI version.",
+  "  --link            Also create an editor symlink named 'trekoon'.",
+  "  --editor <name>   Required with --link (opencode|claude|pi).",
+  "  --to <path>       Override the symlink root for --link only.",
+  "  --allow-outside-repo  Allow links outside the repo (requires --link).",
+  "",
+  "Global install (-g|--global):",
+  "  Creates a global symlink at ~/.agents/skills/trekoon and per-editor symlinks",
+  "  under each editor's global skills directory.",
+  "  --editor <name>   Install for a single editor only.",
+  "",
+  "Update:",
+  "  Probes and repairs both global and local symlinks.",
+  "  Reports per-entry status: ok, repointed, created, migrated, skipped.",
+  "",
+  "Alias: trekoon update -> trekoon skills update",
   "",
   "Examples:",
   "  trekoon skills install",
@@ -441,6 +427,7 @@ const COMMAND_HELP: Record<string, string> = {
   events: EVENTS_HELP,
   migrate: MIGRATE_HELP,
   sync: SYNC_HELP,
+  suggest: SUGGEST_HELP,
   skills: SKILLS_HELP,
   update: "Usage: trekoon update [--json|--toon]\n\nAlias for: trekoon skills update\n\nProbes and repairs all installed global and local skill symlinks.",
   help: "Usage: trekoon help [command] [--json|--toon]",