Three layers of docs (in-binary Example: blocks, AGENTS.md, README.md) have drifted from the actual cobra definitions in ~15 verified spots. Each one misleads someone copy-pasting.

README.md

• L170-171: documents global flags --api-key KEY and --base-url URL that do not exist (root.go defines only config/org/env/output/dry-run/debug/fields). Copy-paste → unknown flag. Point to SYLLABLE_API_KEY + config envs instead.
• L110, L169: claims staging/dev are built-in env aliases. Only prod is built in (cmd/root.go:412-418); others must be configured. (Repo-root CLAUDE.md flag table repeats this.)
• L309, L390, L439: arg/name drift (see AGENTS.md below).

In-binary Example: blocks (broken as shipped)

• cmd/users.go:25-40: examples use numeric IDs (users get 10) but all four commands are email-keyed → every example 404s.
• cmd/outbound.go:28: batches requests abc-123 — command is add-requests and it POSTs (not a read).
• cmd/channels.go:36: channels targets get 5 — command needs 2 args.
• dashboards: example shows fetch-info --file query.json; the command only has --name. Help also recommends the four subcommands AGENTS.md marks deprecated — set cobra's Deprecated: field on them.

AGENTS.md

• L275 + README L309: channels targets list <channel-id> documents a positional that's silently ignored (lists ALL targets) — also add cobra.NoArgs to the leaf.
• L351 batches requests → real name add-requests; L285-290 twilio subcommands documented without the required <channel-id>; L401/411/420 insights updates documented without the required id positional; L424 insights tool-definitions list — no such subcommand.
• L5 vs L106 contradict each other on whether a binary is checked in (L106 is stale — none is).
• L157 "All list commands support --search" is false (events, insights).

Fix: one doc pass against --help. Longer-term, generate the command-reference sections from cobra to prevent recurrence. Effort: M.