docs: cover shipped CLI command groups and guard README drift

README.md

@@ -71,10 +71,54 @@ recoup sandboxes create --command "ls -la"  # Create and run a command
 recoup orgs list           # List your organizations
 ```
 
+### Songs
+
+```bash
+recoup songs presets
+recoup songs analyze --audio "https://example.com/track.mp3" --preset catalog_metadata
+recoup songs analyze --audio "https://example.com/track.mp3" --prompt "Describe the production style"
+```
+
+Replace the example URL with your public audio URL. Every analysis requires audio
+and exactly one of `--preset` or `--prompt`.
+
+### Emails
+
+```bash
+recoup emails --text "Here is your weekly summary."
+recoup emails --text "Here is the update." --subject "Update" --chat-id <chat-id>
+```
+
+The recipient is resolved from your API key. `--subject` is optional; `--chat-id`
+adds a chat link. Use `recoup emails --help` for HTML, CC and organization-account options.
+
+### Content
+
+```bash
+recoup content templates
+recoup content validate --artist <artist-id>
+recoup content estimate --batch 2 --compare
+recoup content create --artist <artist-id> --template artist-caption-bedroom
+```
+
+Estimates use GET and do not start generation. `content create` starts the pipeline
+and returns run IDs; use those IDs with `tasks status` to check progress.
+
+### Tasks
+
+```bash
+recoup tasks status --run <run-id>
+recoup tasks status --run <run-id> --json
+```
+
 ### Global Flags
 
 All commands support `--json` for machine-readable JSON output.
 
+This command reference follows the source in this checkout. Run `recoup --version`
+and `recoup --help` to inspect your installed package; source changes alone do not
+establish that a new npm version has been published.
+
 ## Configuration
 
 | Variable | Required | Description |

__tests__/readmeCommands.test.ts

@@ -0,0 +1,22 @@
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { expect, it } from "vitest";
+
+it("documents every command group advertised by the built CLI", () => {
+  const help = execFileSync(process.execPath, [join(__dirname, "..", "dist", "bin.cjs"), "--help"], {
+    encoding: "utf8",
+    env: {},
+  });
+  const commands = help.split("Commands:\n")[1];
+  expect(commands).toBeDefined();
+  const names = [...commands.matchAll(/^  ([a-z][a-z-]*)\b/gm)]
+    .map(match => match[1])
+    .filter(name => name !== "help");
+  expect(names.length).toBeGreaterThan(0);
+  const readme = readFileSync(join(__dirname, "..", "README.md"), "utf8");
+  const examples = [...readme.matchAll(/```bash\n([\s\S]*?)```/g)]
+    .flatMap(match => [...match[1].matchAll(/^recoup ([a-z][a-z-]*)\b/gm)])
+    .map(match => match[1]);
+  expect(names.filter(name => !examples.includes(name))).toEqual([]);
+});