@nijaru/tk 0.0.3 → 0.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nijaru/tk",
-	"version": "0.0.3",
+	"version": "0.0.4",
 	"description": "Minimal task tracker",
 	"type": "module",
 	"bin": {

package/src/cli.ts

@@ -13,11 +13,13 @@ import {
   green,
   red,
   yellow,
+  dim,
 } from "./lib/format";
 import { findRoot, setWorkingDir } from "./lib/root";
 import { parseId } from "./types";
 import type { Status, TaskWithMeta } from "./types";
 import { BASH_COMPLETION, ZSH_COMPLETION, FISH_COMPLETION } from "./lib/completions";
+import { MAIN_HELP, COMMAND_HELP } from "./lib/help";
 
 const VALID_STATUSES: Status[] = ["open", "active", "done"];
 const PROJECT_PATTERN = /^[a-z][a-z0-9]*$/;
@@ -40,7 +42,7 @@ const TASK_MUTATION_OPTIONS = {
 function validateProject(name: string): void {
   if (!PROJECT_PATTERN.test(name)) {
     throw new Error(
-      `Invalid project name: ${name}. Use lowercase letters and numbers, starting with a letter.`,
+      `Invalid project name: ${name}. Use lowercase letters and numbers, starting with a letter (e.g., 'api', 'web2').`,
     );
   }
 }
@@ -108,7 +110,7 @@ function resolveId(input: string | undefined, context: string): string {
   const matches = storage.findMatchingIds(input);
   if (matches.length > 1) {
     throw new Error(
-      `Ambiguous ID '${input}' matches ${matches.length} tasks: ${matches.join(", ")}`,
+      `Ambiguous ID '${input}' matches ${matches.length} tasks: ${matches.join(", ")}. Use more characters to narrow it down.`,
     );
   }
 
@@ -116,7 +118,7 @@ function resolveId(input: string | undefined, context: string): string {
   // and let getTask handle the "not found" error consistently.
   if (parseId(input)) return input;
 
-  throw new Error(`Task not found: ${input}`);
+  throw new Error(`Task not found: ${input}. Run 'tk ls' to see available tasks.`);
 }
 
 /**
@@ -126,7 +128,7 @@ function resolveId(input: string | undefined, context: string): string {
 function resolveTask(input: string | undefined, context: string): TaskWithMeta {
   const id = resolveId(input, context);
   const result = storage.getTask(id);
-  if (!result) error(`Task not found: ${id}`);
+  if (!result) error(`Task not found: ${id}. Run 'tk ls' to see available tasks.`);
 
   outputCleanup(id, result.cleanup);
   return result.task;
@@ -195,258 +197,12 @@ function error(message: string): never {
   process.exit(1);
 }
 
-function showHelp() {
-  console.log(`tk v${version} - Task tracker for AI agents
-
-USAGE:
-  tk <command> [options]
-
-COMMANDS:
-  init         Initialize .tasks/ directory
-  add          Create task
-  ls, list     List tasks
-  ready        List ready tasks (active/open + unblocked)
-  show         Show task details
-  start        Start working (open -> active)
-  done         Complete task
-  reopen       Reopen task
-  edit         Edit task
-  log          Add log entry
-  block        Add blocker
-  unblock      Remove blocker
-  rm, remove   Delete task
-  clean        Remove old done tasks
-  check        Check for data issues
-  config       Show/set configuration
-  completions  Output shell completions
-
-GLOBAL OPTIONS:
-  -C <dir>     Run in different directory
-  --json       Output as JSON
-  -h, --help   Show help
-  -V           Show version
-
-Run 'tk <command> --help' for command-specific options.
-`);
+function showHelp(): void {
+  console.log(MAIN_HELP);
 }
 
-function showCommandHelp(cmd: string) {
-  const helps: Record<string, string> = {
-    init: `tk init - Initialize .tasks/ directory
-
-USAGE:
-  tk init [options]
-
-OPTIONS:
-  -P, --project <name>   Set default project name
-`,
-    add: `tk add - Create a new task
-
-USAGE:
-  tk add <title> [options]
-
-OPTIONS:
-  -p, --priority <0-4>       Priority (0=none, 1=urgent, 2=high, 3=medium, 4=low)
-  -P, --project <name>       Project prefix for ID
-  -d, --description <text>   Description
-  -l, --labels <csv>         Labels (comma-separated)
-  -A, --assignees <csv>      Assignees (comma-separated, @me for git user)
-  --parent <id>              Parent task ID
-  --estimate <n>             Estimate (user-defined units)
-  --due <date>               Due date (YYYY-MM-DD or +Nh/+Nd/+Nw/+Nm)
-
-EXAMPLES:
-  tk add "Fix login bug" -p 1
-  tk add "New feature" -P api -l bug,urgent
-  tk add "Sprint task" --due +7d
-`,
-    ls: `tk ls - List tasks
-
-USAGE:
-  tk ls [options]
-
-OPTIONS:
-  -s, --status <status>   Filter by status (open, active, done)
-  -p, --priority <0-4>    Filter by priority
-  -P, --project <name>    Filter by project
-  -l, --label <label>     Filter by label
-  --assignee <name>       Filter by assignee
-  --parent <id>           Filter by parent
-  --roots                 Show only root tasks (no parent)
-  --overdue               Show only overdue tasks
-  -n, --limit <n>         Limit results (default: 20)
-  -a, --all               Show all (no limit)
-
-EXAMPLES:
-  tk ls -s open -p 1      # Urgent open tasks
-  tk ls --overdue         # Overdue tasks
-  tk ls -P api --roots    # Root tasks in api project
-`,
-    list: `tk list - List tasks (alias for 'ls')
-
-Run 'tk ls --help' for options.
-`,
-    ready: `tk ready - List ready tasks (active/open + unblocked)
-
-USAGE:
-  tk ready
-
-Shows active or open tasks that are not blocked by any incomplete task.
-`,
-    show: `tk show - Show task details
-
-USAGE:
-  tk show <id>
-
-EXAMPLES:
-  tk show tk-1
-  tk show 1        # If unambiguous
-`,
-    start: `tk start - Start working on a task
-
-USAGE:
-  tk start <id>
-
-Changes status from open to active.
-`,
-    done: `tk done - Complete a task
-
-USAGE:
-  tk done <id>
-
-Changes status to done.
-`,
-    reopen: `tk reopen - Reopen a task
-
-USAGE:
-  tk reopen <id>
-
-Changes status back to open.
-`,
-    edit: `tk edit - Edit a task
-
-USAGE:
-  tk edit <id> [options]
-
-OPTIONS:
-  -t, --title <text>         New title
-  -d, --description <text>   New description
-  -p, --priority <0-4>       New priority
-  -l, --labels <csv>         Replace labels (use +tag/-tag to add/remove)
-  -A, --assignees <csv>      Replace assignees
-  --parent <id>              Set parent (use - to clear)
-  --estimate <n>             Set estimate (use - to clear)
-  --due <date>               Set due date (use - to clear)
-
-EXAMPLES:
-  tk edit tk-1 -t "New title"
-  tk edit tk-1 -l +urgent     # Add label
-  tk edit tk-1 --due -        # Clear due date
-`,
-    log: `tk log - Add a log entry to a task
-
-USAGE:
-  tk log <id> "<message>"
-
-Message must be quoted.
-
-EXAMPLES:
-  tk log tk-1 "Started implementation"
-  tk log tk-1 "Blocked on API changes"
-`,
-    block: `tk block - Add a blocker dependency
-
-USAGE:
-  tk block <task> <blocker>
-
-The first task becomes blocked by the second.
-
-EXAMPLES:
-  tk block tk-2 tk-1    # tk-2 is blocked by tk-1
-`,
-    unblock: `tk unblock - Remove a blocker dependency
-
-USAGE:
-  tk unblock <task> <blocker>
-
-EXAMPLES:
-  tk unblock tk-2 tk-1
-`,
-    rm: `tk rm - Delete a task
-
-USAGE:
-  tk rm <id>
-
-EXAMPLES:
-  tk rm tk-1
-`,
-    remove: `tk remove - Delete a task (alias for 'rm')
-
-USAGE:
-  tk remove <id>
-`,
-    clean: `tk clean - Remove old completed tasks
-
-USAGE:
-  tk clean [options]
-
-OPTIONS:
-  --older-than <days>   Age threshold in days (default: from config, 14)
-  -f, --force           Remove all done tasks (ignores age and disabled state)
-
-EXAMPLES:
-  tk clean                  # Remove done tasks older than config.clean_after days
-  tk clean --older-than 30  # Remove done tasks older than 30 days
-  tk clean --force          # Remove all done tasks regardless of age
-`,
-    check: `tk check - Check for data issues
-
-USAGE:
-  tk check
-
-Scans all tasks for issues. Auto-fixable issues (orphaned references, ID
-mismatches) are fixed automatically. Unfixable issues (corrupted JSON) are
-reported for manual intervention.
-
-Note: Auto-fixing also happens during normal task operations (show, done,
-edit, etc.) - this command is for bulk cleanup or diagnostics.
-
-EXAMPLES:
-  tk check                  # Scan and fix all tasks
-`,
-    config: `tk config - Show or set configuration
-
-USAGE:
-  tk config                              Show all config
-  tk config project                      Show default project
-  tk config project <name>               Set default project
-  tk config project <new> --rename <old> Rename project (old-* → new-*)
-  tk config alias                        List aliases
-  tk config alias <name> <path>          Add alias
-  tk config alias --rm <name>            Remove alias
-
-EXAMPLES:
-  tk config project api
-  tk config project lsmvec --rename cloudlsmvec
-  tk config alias web src/web
-`,
-    completions: `tk completions - Output shell completions
-
-USAGE:
-  tk completions <shell>
-
-SHELLS:
-  bash   Bash completion script
-  zsh    Zsh completion script
-  fish   Fish completion script
-
-EXAMPLES:
-  eval "$(tk completions bash)"   # Add to ~/.bashrc
-  eval "$(tk completions zsh)"    # Add to ~/.zshrc
-`,
-  };
-
-  const help = helps[cmd];
+function showCommandHelp(cmd: string): void {
+  const help = COMMAND_HELP[cmd];
   if (help) {
     console.log(help);
   } else {
@@ -498,7 +254,7 @@ function main() {
       if (info.exists) {
         output(
           { path: info.tasksDir, created: false },
-          green(`Already initialized: ${info.tasksDir}`),
+          dim(`Already initialized: ${info.tasksDir}`),
         );
       } else {
         const path = storage.initTasks(values.project);
@@ -525,7 +281,8 @@ function main() {
       let parentId: string | undefined;
       if (values.parent) {
         const resolved = storage.resolveId(values.parent);
-        if (!resolved) error(`Parent task not found: ${values.parent}`);
+        if (!resolved)
+          error(`Parent task not found: ${values.parent}. Run 'tk ls' to see available tasks.`);
         parentId = resolved;
         const parentResult = storage.validateParent(parentId);
         if (!parentResult.ok) error(parentResult.error!);
@@ -571,7 +328,8 @@ function main() {
       let parentFilter: string | undefined;
       if (values.parent) {
         const resolved = storage.resolveId(values.parent);
-        if (!resolved) error(`Parent task not found: ${values.parent}`);
+        if (!resolved)
+          error(`Parent task not found: ${values.parent}. Run 'tk ls' to see available tasks.`);
         parentFilter = resolved;
       }
 
@@ -592,7 +350,10 @@ function main() {
 
     case "ready": {
       const list = storage.listReadyTasks();
-      output(list, formatTaskList(list));
+      output(
+        list,
+        formatTaskList(list, undefined, "No ready tasks. All tasks are either done or blocked."),
+      );
       break;
     }
 
@@ -660,7 +421,8 @@ function main() {
         resolvedParent = null;
       } else if (values.parent) {
         const resolved = storage.resolveId(values.parent);
-        if (!resolved) error(`Parent task not found: ${values.parent}`);
+        if (!resolved)
+          error(`Parent task not found: ${values.parent}. Run 'tk ls' to see available tasks.`);
         resolvedParent = resolved;
         const parentResult = storage.validateParent(resolvedParent, task.id);
         if (!parentResult.ok) error(parentResult.error!);
@@ -696,10 +458,13 @@ function main() {
     }
 
     case "block": {
-      if (!args[0] || !args[1]) error("Usage: tk block <task> <blocker>");
+      if (!args[0] || !args[1])
+        error(
+          "Two IDs required: tk block <task> <blocker>. The first task becomes blocked by the second.",
+        );
       const taskId = resolveId(args[0], "block");
       const blockerId = resolveId(args[1], "block");
-      if (taskId === blockerId) error("Task cannot block itself");
+      if (taskId === blockerId) error("Task cannot block itself.");
       const result = storage.addBlock(taskId, blockerId);
       if (!result.ok) error(result.error!);
       output(
@@ -710,7 +475,7 @@ function main() {
     }
 
     case "unblock": {
-      if (!args[0] || !args[1]) error("Usage: tk unblock <task> <blocker>");
+      if (!args[0] || !args[1]) error("Two IDs required: tk unblock <task> <blocker>.");
       const taskId = resolveId(args[0], "unblock");
       const blockerId = resolveId(args[1], "unblock");
       const removed = storage.removeBlock(taskId, blockerId);
@@ -726,7 +491,7 @@ function main() {
     case "remove": {
       const id = resolveId(args[0], "rm");
       const deleted = storage.deleteTask(id);
-      if (!deleted) error(`Task not found: ${id}`);
+      if (!deleted) error(`Task not found: ${id}. Run 'tk ls' to see available tasks.`);
       output({ id, deleted: true }, green(`Deleted: ${id}`));
       break;
     }
@@ -868,7 +633,7 @@ function main() {
             const alias = positionals[0];
             const path = positionals[1];
             if (!alias || !path || !alias.trim()) {
-              error("Alias name and path are required");
+              error("Alias name and path required: tk config alias <name> <path>");
             }
             const updated = storage.setAlias(alias, path);
             output(updated, green(`Added alias: ${alias} → ${path}`));
@@ -876,7 +641,10 @@ function main() {
             // List aliases
             const aliases = config.aliases;
             if (Object.keys(aliases).length === 0) {
-              output({ aliases: {} }, "No aliases defined.");
+              output(
+                { aliases: {} },
+                "No aliases defined. Add one with: tk config alias <name> <path>",
+              );
             } else {
               const lines = Object.entries(aliases)
                 .map(([a, p]) => `${a} → ${p}`)
@@ -887,7 +655,7 @@ function main() {
           break;
         }
         default:
-          error(`Unknown config command: ${subcommand}`);
+          error(`Unknown config command: ${subcommand}. Valid: project, alias.`);
       }
       break;
     }
@@ -905,7 +673,7 @@ function main() {
           console.log(FISH_COMPLETION);
           break;
         default:
-          error("Shell required: tk completions <bash|zsh|fish>");
+          error("Shell required: tk completions <bash|zsh|fish>. Add to your shell's rc file.");
       }
       break;
     }

package/src/db/storage.ts

@@ -158,7 +158,7 @@ export function renameProject(oldProject: string, newProject: string): RenameRes
   // Find tasks to rename
   const toRename = allTasks.filter((t) => t.project === oldProject);
   if (toRename.length === 0) {
-    throw new Error(`No tasks found with project "${oldProject}"`);
+    throw new Error(`No tasks found with project "${oldProject}". Run 'tk ls' to see projects.`);
   }
 
   // Check for collisions
@@ -166,7 +166,7 @@ export function renameProject(oldProject: string, newProject: string): RenameRes
   for (const task of toRename) {
     const newId = `${newProject}-${task.ref}`;
     if (existingIds.has(newId)) {
-      throw new Error(`Cannot rename: "${newId}" already exists`);
+      throw new Error(`Cannot rename: "${newId}" already exists. Choose a different project name.`);
     }
   }
 

package/src/lib/format.test.ts

@@ -92,13 +92,13 @@ describe("formatTaskRow", () => {
     expect(parts.length).toBe(4); // ID | PRIO | STATUS | TITLE
   });
 
-  test("truncates long project names to 6 chars", () => {
+  test("truncates long project names with ellipsis", () => {
     const longProjectTask: TaskWithMeta = {
       ...task,
       id: "mylongproject-a1b2",
     };
     const result = formatTaskRow(longProjectTask, false);
-    expect(result).toContain("mylong-a1b2");
+    expect(result).toContain("mylon…-a1b2");
     expect(result).not.toContain("mylongproject");
   });
 
@@ -130,8 +130,12 @@ describe("formatTaskRow", () => {
 });
 
 describe("formatTaskList", () => {
-  test("returns message for empty list", () => {
-    expect(formatTaskList([])).toBe("No tasks found.");
+  test("returns helpful message for empty list", () => {
+    expect(formatTaskList([])).toBe("No tasks found. Run 'tk add \"title\"' to create one.");
+  });
+
+  test("allows custom empty hint", () => {
+    expect(formatTaskList([], undefined, "Custom hint")).toBe("Custom hint");
   });
 
   test("includes header and divider", () => {

package/src/lib/format.ts

@@ -43,22 +43,28 @@ export function dim(msg: string): string {
   return shouldUseColor() ? `${DIM}${msg}${RESET}` : msg;
 }
 
-function formatId(id: string): string {
-  // Truncate project prefix to 6 chars, keep full 4-char ref
-  // "myproject-a1b2" -> "myproj-a1b2"
+function truncate(text: string, maxLen: number): string {
+  return text.length <= maxLen ? text : text.slice(0, maxLen - 1) + "…";
+}
+
+function formatId(id: string, maxLen = 11): string {
+  // Truncate project prefix to fit maxLen, keep full 4-char ref
+  // "myproject-a1b2" -> "mypr…-a1b2"
   const dash = id.lastIndexOf("-");
-  if (dash === -1) return id.slice(0, 11);
+  if (dash === -1) return truncate(id, maxLen);
   const project = id.slice(0, dash);
   const ref = id.slice(dash + 1);
-  const truncatedProject = project.length > 6 ? project.slice(0, 6) : project;
-  return `${truncatedProject}-${ref}`;
+  const maxProjectLen = maxLen - ref.length - 1; // -1 for dash
+  return project.length > maxProjectLen
+    ? `${truncate(project, maxProjectLen)}-${ref}`
+    : `${project}-${ref}`;
 }
 
 export function formatTaskRow(task: TaskWithMeta, useColor?: boolean): string {
   const color = useColor ?? shouldUseColor();
   const id = formatId(task.id).padEnd(11);
   const priority = formatPriority(task.priority).padEnd(4);
-  const title = task.title.slice(0, 50);
+  const title = truncate(task.title, 50);
   const isOverdue = task.is_overdue;
 
   let statusText: string = task.status;
@@ -78,8 +84,14 @@ export function formatTaskRow(task: TaskWithMeta, useColor?: boolean): string {
   return `${id} | ${priority} | ${status} | ${title}${overdueMarker}`;
 }
 
-export function formatTaskList(tasks: TaskWithMeta[], useColor?: boolean): string {
-  if (tasks.length === 0) return "No tasks found.";
+export function formatTaskList(
+  tasks: TaskWithMeta[],
+  useColor?: boolean,
+  emptyHint?: string,
+): string {
+  if (tasks.length === 0) {
+    return emptyHint ?? "No tasks found. Run 'tk add \"title\"' to create one.";
+  }
   const color = useColor ?? shouldUseColor();
 
   const header = "ID          | PRIO | STATUS       | TITLE";

package/src/lib/help.ts

@@ -0,0 +1,249 @@
+import { version } from "../../package.json";
+
+export const MAIN_HELP = `tk v${version} - Task tracker for AI agents
+
+USAGE:
+  tk <command> [options]
+
+COMMANDS:
+  init         Initialize .tasks/ directory
+  add          Create task
+  ls, list     List tasks
+  ready        List ready tasks (active/open + unblocked)
+  show         Show task details
+  start        Start working (open -> active)
+  done         Complete task
+  reopen       Reopen task
+  edit         Edit task
+  log          Add log entry
+  block        Add blocker
+  unblock      Remove blocker
+  rm, remove   Delete task
+  clean        Remove old done tasks
+  check        Check for data issues
+  config       Show/set configuration
+  completions  Output shell completions
+
+GLOBAL OPTIONS:
+  -C <dir>     Run in different directory
+  --json       Output as JSON
+  -h, --help   Show help
+  -V           Show version
+
+Run 'tk <command> --help' for command-specific options.
+`;
+
+export const COMMAND_HELP: Record<string, string> = {
+  init: `tk init - Initialize .tasks/ directory
+
+USAGE:
+  tk init [options]
+
+OPTIONS:
+  -P, --project <name>   Set default project name
+`,
+  add: `tk add - Create a new task
+
+USAGE:
+  tk add <title> [options]
+
+OPTIONS:
+  -p, --priority <0-4>       Priority (0=none, 1=urgent, 2=high, 3=medium, 4=low)
+  -P, --project <name>       Project prefix for ID
+  -d, --description <text>   Description
+  -l, --labels <csv>         Labels (comma-separated)
+  -A, --assignees <csv>      Assignees (comma-separated, @me for git user)
+  --parent <id>              Parent task ID
+  --estimate <n>             Estimate (user-defined units)
+  --due <date>               Due date (YYYY-MM-DD or +Nh/+Nd/+Nw/+Nm)
+
+EXAMPLES:
+  tk add "Fix login bug" -p 1
+  tk add "New feature" -P api -l bug,urgent
+  tk add "Sprint task" --due +7d
+`,
+  ls: `tk ls - List tasks
+
+USAGE:
+  tk ls [options]
+
+OPTIONS:
+  -s, --status <status>   Filter by status (open, active, done)
+  -p, --priority <0-4>    Filter by priority
+  -P, --project <name>    Filter by project
+  -l, --label <label>     Filter by label
+  --assignee <name>       Filter by assignee
+  --parent <id>           Filter by parent
+  --roots                 Show only root tasks (no parent)
+  --overdue               Show only overdue tasks
+  -n, --limit <n>         Limit results (default: 20)
+  -a, --all               Show all (no limit)
+
+EXAMPLES:
+  tk ls -s open -p 1      # Urgent open tasks
+  tk ls --overdue         # Overdue tasks
+  tk ls -P api --roots    # Root tasks in api project
+`,
+  list: `tk list - List tasks (alias for 'ls')
+
+Run 'tk ls --help' for options.
+`,
+  ready: `tk ready - List ready tasks (active/open + unblocked)
+
+USAGE:
+  tk ready
+
+Shows active or open tasks that are not blocked by any incomplete task.
+`,
+  show: `tk show - Show task details
+
+USAGE:
+  tk show <id>
+
+EXAMPLES:
+  tk show tk-1
+  tk show 1        # If unambiguous
+`,
+  start: `tk start - Start working on a task
+
+USAGE:
+  tk start <id>
+
+Changes status from open to active.
+`,
+  done: `tk done - Complete a task
+
+USAGE:
+  tk done <id>
+
+Changes status to done.
+`,
+  reopen: `tk reopen - Reopen a task
+
+USAGE:
+  tk reopen <id>
+
+Changes status back to open.
+`,
+  edit: `tk edit - Edit a task
+
+USAGE:
+  tk edit <id> [options]
+
+OPTIONS:
+  -t, --title <text>         New title
+  -d, --description <text>   New description
+  -p, --priority <0-4>       New priority
+  -l, --labels <csv>         Replace labels (use +tag/-tag to add/remove)
+  -A, --assignees <csv>      Replace assignees
+  --parent <id>              Set parent (use - to clear)
+  --estimate <n>             Set estimate (use - to clear)
+  --due <date>               Set due date (use - to clear)
+
+EXAMPLES:
+  tk edit tk-1 -t "New title"
+  tk edit tk-1 -l +urgent     # Add label
+  tk edit tk-1 --due -        # Clear due date
+`,
+  log: `tk log - Add a log entry to a task
+
+USAGE:
+  tk log <id> "<message>"
+
+Message must be quoted.
+
+EXAMPLES:
+  tk log tk-1 "Started implementation"
+  tk log tk-1 "Blocked on API changes"
+`,
+  block: `tk block - Add a blocker dependency
+
+USAGE:
+  tk block <task> <blocker>
+
+The first task becomes blocked by the second.
+
+EXAMPLES:
+  tk block tk-2 tk-1    # tk-2 is blocked by tk-1
+`,
+  unblock: `tk unblock - Remove a blocker dependency
+
+USAGE:
+  tk unblock <task> <blocker>
+
+EXAMPLES:
+  tk unblock tk-2 tk-1
+`,
+  rm: `tk rm - Delete a task
+
+USAGE:
+  tk rm <id>
+
+EXAMPLES:
+  tk rm tk-1
+`,
+  remove: `tk remove - Delete a task (alias for 'rm')
+
+USAGE:
+  tk remove <id>
+`,
+  clean: `tk clean - Remove old completed tasks
+
+USAGE:
+  tk clean [options]
+
+OPTIONS:
+  --older-than <days>   Age threshold in days (default: from config, 14)
+  -f, --force           Remove all done tasks (ignores age and disabled state)
+
+EXAMPLES:
+  tk clean                  # Remove done tasks older than config.clean_after days
+  tk clean --older-than 30  # Remove done tasks older than 30 days
+  tk clean --force          # Remove all done tasks regardless of age
+`,
+  check: `tk check - Check for data issues
+
+USAGE:
+  tk check
+
+Scans all tasks for issues. Auto-fixable issues (orphaned references, ID
+mismatches) are fixed automatically. Unfixable issues (corrupted JSON) are
+reported for manual intervention.
+
+Note: Auto-fixing also happens during normal task operations (show, done,
+edit, etc.) - this command is for bulk cleanup or diagnostics.
+
+EXAMPLES:
+  tk check                  # Scan and fix all tasks
+`,
+  config: `tk config - Show or set configuration
+
+USAGE:
+  tk config                              Show all config
+  tk config project                      Show default project
+  tk config project <name>               Set default project
+  tk config project <new> --rename <old> Rename project (old-* → new-*)
+  tk config alias                        List aliases
+  tk config alias <name> <path>          Add alias
+  tk config alias --rm <name>            Remove alias
+
+EXAMPLES:
+  tk config project api
+  tk config project lsmvec --rename cloudlsmvec
+  tk config alias web src/web
+`,
+  completions: `tk completions - Output shell completions
+
+USAGE:
+  tk completions <shell>
+
+SHELLS:
+  bash   Bash completion script
+  zsh    Zsh completion script
+  fish   Fish completion script
+
+EXAMPLES:
+  eval "$(tk completions bash)"   # Add to ~/.bashrc
+  eval "$(tk completions zsh)"    # Add to ~/.zshrc
+`,
+};