diff --git a/scripts/work/cli.mjs b/scripts/work/cli.mjs
index cd3ff66..24a8311 100644
--- a/scripts/work/cli.mjs
+++ b/scripts/work/cli.mjs
@@ -1,11 +1,25 @@
 #!/usr/bin/env node
 /**
- * pnpm work — CLI for the local work-system.
+ * pnpm work — CLI for the local work-system. Routes subcommands to their
+ * respective modules (state-builder, dispatch, decompose, prd-ship). Each
+ * subcommand module also exposes a `runCli(args)` entry point that this
+ * file calls directly; the sibling modules NEVER run as a side effect of
+ * being imported.
  *
  * Subcommands:
- *   rebuild-state   Rewrites docs/work/_state.json from the current markdown
- *   status          Prints a tree of all epics + their stories
- *   next            Prints the first non-done story in the first non-done epic
+ *   rebuild-state      Rewrites docs/work/_state.json from the current markdown
+ *   status             Prints a tree of all epics + their stories
+ *   next               Prints the first ready story (or "All done" / "Blocked: ...")
+ *   ready              Prints every ready story
+ *   blocked            Prints every blocked story + what each is waiting on
+ *   dispatch           Print the next dispatch plan; with --execute invokes
+ *                      sandcastle to run the implementer + reviewer pair
+ *   decompose <id>     Validate an approved PRD + print the decompose plan;
+ *                      with --execute invokes sandcastle's decomposer agent
+ *                      to write the epic folder + per-story files
+ *   prd-ship <id>      Flip a PRD's status to `shipped` (run after its
+ *                      seed epic completes); --commits / --auto-commits
+ *                      optional; idempotent on already-shipped
  */
 import fs from "node:fs";
 import path from "node:path";
diff --git a/scripts/work/prd-ship.mjs b/scripts/work/prd-ship.mjs
index c54314c..5d3f7ac 100644
--- a/scripts/work/prd-ship.mjs
+++ b/scripts/work/prd-ship.mjs
@@ -3,11 +3,12 @@
  *
  * Invoked when an epic completes and its seed PRD's implementation is fully
  * landed. Writes back to the PRD's frontmatter:
- *   - status: <approved|in-review|draft> -> shipped
+ *   - status: <approved|in-review> -> shipped
  *   - shipped: <ISO date> (today, UTC)
  *   - shipping-commits: [<sha1>, <sha2>, ...] (optional)
  *
- * Refuses to flip from `draft` (must go through human review first).
+ * Refuses to flip from `draft` (must go through human review first —
+ * draft -> approved is the human step, NOT automated by this command).
  * Refuses to flip if already `shipped` (idempotent fail-soft).
  *
  * Usage: