From 6fd142f00772a1843b2bece2b779189dd5dcbb21 Mon Sep 17 00:00:00 2001
From: Paul Buetow <paul@buetow.org>
Date: Sun, 22 Mar 2026 20:53:36 +0200
Subject: docs: update README and usage.md with new ask subcommands

---
 README.md     |  7 +++++--
 docs/usage.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++-------
 2 files changed, 56 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index f3a3a40..872c23a 100644
--- a/README.md
+++ b/README.md
@@ -13,9 +13,12 @@ It has got improved capabilities for Go code understanding (for example, create
 * LSP in-editor chat with the LLM
 * Stand-alone command line tool for LLM interaction
   - Includes `--tps-simulation` to preview how fast a model would feel by streaming placeholder text or piped stdin at a chosen token-per-second rate
-* Taskwarrior proxy for agent-managed project work
+* Task management CLI for agent-managed project work
   - Entrypoint: `ask`
-  - Automatically scopes Taskwarrior commands to `project:<repo> +agent`
+  - Auto-scopes to `project:<repo> +agent` (derived from git repo root)
+  - Never exposes numeric task IDs — uses UUIDs only
+  - Machine-friendly output: UUID-only tables, suppressed decorative text
+  - Subcommands: `ask add`, `ask list`, `ask info`, `ask annotate`, `ask start`, `ask stop`, `ask done`, `ask priority`, `ask tag`, `ask dep`, `ask urgency`, `ask modify`, `ask denotate`, `ask delete`, `ask export`
 * Parallel completions and CLI responses from multiple providers/models for side-by-side comparison
 * **MCP server for prompt/runbook management** (`hexai-mcp-server`) - **⚠️ DEPRECATED/EXPERIMENTAL**
   - Create, update, delete, and retrieve prompts via MCP protocol
diff --git a/docs/usage.md b/docs/usage.md
index d712f1e..ce79af6 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -123,16 +123,60 @@ hexai --tps-simulation 12-18
 cat SOMEFILE.txt | hexai --tps-simulation 20
 ```
 
-## Taskwarrior proxy
+## Task management
+
+`ask` is a task management CLI for the current git project. It auto-scopes to `project:<repo> +agent` so all operations are confined to the current project.
+
+`ask` never exposes numeric task IDs — it uses UUIDs for all task references. Output is machine-friendly: UUID-only tables, suppressed decorative text, and structured formats.
+
+`ask` must be run inside a git repository so the project name can be derived from the repo root.
+
+### Subcommands
+
+| Subcommand | Description |
+|---|---|
+| `ask add "description"` | Create a new task |
+| `ask add priority:H "description"` | Create task with priority |
+| `ask add +tag "description"` | Create task with tag |
+| `ask list` | List pending tasks (UUID-only table) |
+| `ask list +READY` | List only ready tasks |
+| `ask list +BLOCKED` | List blocked tasks |
+| `ask list +tag` | Filter by tag |
+| `ask list started` | List started tasks |
+| `ask list limit:N` | Limit results |
+| `ask list sort:priority-,urgency-` | Sort by priority then urgency |
+| `ask info <uuid>` | Show task details |
+| `ask annotate <uuid> "note"` | Add annotation |
+| `ask start <uuid>` | Start working on a task |
+| `ask stop <uuid>` | Stop work on a task |
+| `ask done <uuid>` | Mark task complete |
+| `ask priority <uuid> H\|M\|L` | Set priority |
+| `ask tag <uuid> +tag` | Add tag |
+| `ask tag <uuid> -tag` | Remove tag |
+| `ask dep add <uuid> <dep-uuid>` | Add dependency |
+| `ask dep rm <uuid> <dep-uuid>` | Remove dependency |
+| `ask dep list <uuid>` | List dependencies |
+| `ask urgency` | List tasks by urgency |
+| `ask modify <uuid> <args...>` | General-purpose modify |
+| `ask denotate <uuid> "text"` | Remove annotation |
+| `ask delete <uuid>` | Delete a task |
+| `ask export` | Raw JSON export |
 
-Use `ask` when you want Taskwarrior automatically scoped to the current git repo and the `+agent` tag.
+### Examples
+
+```sh
+# Create a task
+ask add priority:H "Implement new feature"
 
-- `ask list`
-- `ask add priority:H "Implement X"`
-- `ask uuid:1234 annotate "Delivered Y"`
-- `ask 42 done`
+# List tasks
+ask list +READY limit:5
 
-`ask` pre-sets `project:<repo> +agent` and then forwards the remaining arguments to Taskwarrior unchanged, so normal reports, filters, UUID selectors, and commands still work. It must be run inside a git repository so the project name can be derived from the repo root.
+# Start working
+ask start 9a3cfcb4-742e-4a38-ac91-e9b36594bff0
+
+# Done
+ask done 9a3cfcb4-742e-4a38-ac91-e9b36594bff0
+```
 
 ## Hexai Action (TUI)
 
-- 
cgit v1.2.3