docs(cli): generated agent-discoverable command & flag reference (DRG-483)

README.md

@@ -245,22 +245,37 @@ Run `speechify mcp install --print` to see the exact command for your setup —
 the CLI is published, it spawns the running binary by absolute path rather than a
 bare `speechify` on your `PATH`.
 
+## Reference
+
+Full, agent-discoverable docs cover every command and flag. They're **generated
+from the CLI itself**, so they can't drift from what the binary accepts:
+
+- [`llms.txt`](llms.txt) — the [llms.txt](https://llmstxt.org)-standard index.
+- [`llms-full.txt`](llms-full.txt) — every command and flag in one file.
+- [`docs/`](docs/) — one page per command, plus [global options](docs/global-options.md).
+
+Regenerate after changing any command or flag with `pnpm docs:generate`; a test in
+the suite fails if the checked-in copies are out of date.
+
 ## Development
 
 ```bash
 pnpm install
-pnpm build       # tsup → dist/bin.js (executable, shebang'd)
+pnpm build         # tsup → dist/bin.js (executable, shebang'd)
 pnpm typecheck
-pnpm test
-pnpm lint        # biome
+pnpm test          # includes the docs drift guard
+pnpm lint          # biome
+pnpm docs:generate # rewrite llms.txt, llms-full.txt and docs/ from the CLI
 
 node dist/bin.js whoami
 ```
 
 ## Architecture
 
-`src/auth/session.ts` resolves an API key (flag / env / stored) into a single
-`AuthContext` (the Bearer). `src/core/client.ts` wraps the `@speechify/api` SDK
-for TTS. Commands in `src/commands/` are thin adapters over `src/core/`;
-`src/mcp/` relays a local stdio MCP client to the hosted Speechify MCP server,
-forwarding the resolved Bearer upstream.
+`src/program.ts` assembles the commander command tree (side-effect-free) and
+`src/bin.ts` runs it. `src/auth/session.ts` resolves an API key (flag / env /
+stored) into a single `AuthContext` (the Bearer). `src/core/client.ts` wraps the
+`@speechify/api` SDK for TTS. Commands in `src/commands/` are thin adapters over
+`src/core/`; `src/mcp/` relays a local stdio MCP client to the hosted Speechify MCP
+server, forwarding the resolved Bearer upstream. `src/docs/reference.ts` walks the
+command tree to generate the reference docs.

docs/api.md

@@ -0,0 +1,26 @@
+<!-- Generated by `pnpm docs:generate` from the CLI definitions. Do not edit by hand. -->
+
+# speechify api
+
+Authenticated raw request to any API endpoint (gh-api style).
+
+## Usage
+
+```
+speechify api <endpoint> [options]
+```
+
+## Arguments
+
+- `<endpoint>` — API path (e.g. v1/voices, leading slash optional) or a full https:// URL
+
+## Options
+
+- `-X, --method <method>` — HTTP method (default GET, or POST when a body is present)
+- `-f, --field <key=value...>` — body field key=value; repeatable, builds a JSON body (true/false/null and numbers become typed; use --data for literal strings)
+- `-d, --data <data>` — raw request body; @file reads a file, - reads stdin
+- `-q, --query <key=value...>` — query parameter key=value; repeatable
+- `-H, --header <header...>` — extra header 'Key: Value'; repeatable
+- `-i, --include` — include the response status line and headers in the output
+
+Global options apply here too — see [global options](./global-options.md).

docs/global-options.md

@@ -0,0 +1,16 @@
+<!-- Generated by `pnpm docs:generate` from the CLI definitions. Do not edit by hand. -->
+
+# Global options
+
+These flags are accepted by every `speechify` command (and its subcommands).
+
+- `--api-key <key>` — Speechify API key (overrides login / $SPEECHIFY_API_KEY)
+- `--api-version <date>` — pin the Speechify-Version header (ISO date, e.g. 2026-06-27)
+- `--base-url <url>` — override the API origin (defaults to $SPEECHIFY_BASE_URL or production)
+- `--json` — emit machine-readable JSON on stdout
+- `--agent-friendly` — JSON output plus explanatory context for AI agents
+- `--no-input` — never prompt; return a needs-input spec instead
+
+Environment equivalents: `$SPEECHIFY_API_KEY` (`--api-key`), `$SPEECHIFY_BASE_URL`
+(`--base-url`), `$SPEECHIFY_API_VERSION` (`--api-version`). An explicit flag always
+wins over the environment.

docs/login.md

@@ -0,0 +1,13 @@
+<!-- Generated by `pnpm docs:generate` from the CLI definitions. Do not edit by hand. -->
+
+# speechify login
+
+Validate a Speechify API key and store it for later commands.
+
+## Usage
+
+```
+speechify login [options]
+```
+
+Global options apply here too — see [global options](./global-options.md).

docs/logout.md

@@ -0,0 +1,13 @@
+<!-- Generated by `pnpm docs:generate` from the CLI definitions. Do not edit by hand. -->
+
+# speechify logout
+
+Forget the stored API key.
+
+## Usage
+
+```
+speechify logout [options]
+```
+
+Global options apply here too — see [global options](./global-options.md).

docs/mcp-install.md

@@ -0,0 +1,20 @@
+<!-- Generated by `pnpm docs:generate` from the CLI definitions. Do not edit by hand. -->
+
+# speechify mcp install
+
+Install the MCP relay into local AI clients (Claude Code, Cursor, Claude Desktop, …).
+
+## Usage
+
+```
+speechify mcp install [options]
+```
+
+## Options
+
+- `--client <ids...>` — client id(s): claude-code, cursor, claude-desktop, windsurf, vscode
+- `--all` — install into every detected client
+- `--print` — print the config block instead of writing it
+- `--embed-key` — embed $SPEECHIFY_API_KEY in the client env (default: rely on the stored session)
+
+Global options apply here too — see [global options](./global-options.md).

docs/mcp.md

@@ -0,0 +1,21 @@
+<!-- Generated by `pnpm docs:generate` from the CLI definitions. Do not edit by hand. -->
+
+# speechify mcp
+
+Relay the local MCP client to Speechify's hosted MCP server over stdio, for AI agents.
+
+## Usage
+
+```
+speechify mcp [options]
+```
+
+## Options
+
+- `--url <url>` — upstream MCP endpoint to relay to (default: `https://mcp.speechify.ai/mcp`)
+
+## Subcommands
+
+- [speechify mcp install](./mcp-install.md) — Install the MCP relay into local AI clients (Claude Code, Cursor, Claude Desktop, …).
+
+Global options apply here too — see [global options](./global-options.md).

docs/say.md

@@ -0,0 +1,32 @@
+<!-- Generated by `pnpm docs:generate` from the CLI definitions. Do not edit by hand. -->
+
+# speechify say
+
+Synthesize speech from text and save (or play) the audio.
+
+## Usage
+
+```
+speechify say [text] [options]
+```
+
+## Arguments
+
+- `[text]` — text (or SSML) to synthesize; omit to read from --input-file or stdin
+
+## Options
+
+- `-v, --voice <id>` — voice id (see `speechify voices list`) (default: `george`)
+- `--model <model>` — synthesis model (choices: `simba-english`, `simba-multilingual`, `simba-3.0`, `simba-3.2`)
+- `-f, --format <format>` — output audio format (choices: `wav`, `mp3`, `ogg`, `aac`, `pcm`; default: `mp3`)
+- `--language <locale>` — input language, e.g. en-US
+- `-o, --out <path>` — output file (default ./speech.<format>); "-" writes raw audio to stdout
+- `--play` — play the audio after synthesis
+- `--loudness-normalization` — normalize loudness to -14 LUFS
+- `--no-text-normalization` — keep numbers/dates as written instead of spelled out
+- `--input-file <path>` — read input text from a file
+- `--stream` — stream the audio as it is generated (up to 20000 characters, lower time to first byte); wav is unavailable
+- `--output-format <format>` — exact codec/sample rate/bitrate, e.g. pcm_16000 or mp3_24000_64 (--stream only; replaces --format) (choices: `pcm_8000`, `pcm_16000`, `pcm_22050`, `pcm_24000`, `pcm_44100`, `pcm_48000`, `mp3_22050_32`, `mp3_22050_64`, `mp3_22050_96`, `mp3_22050_128`, `mp3_22050_192`, `mp3_24000_32`, `mp3_24000_64`, `mp3_24000_96`, `mp3_24000_128`, `mp3_24000_192`, `ulaw_8000`, `ogg_24000`, `aac_24000`)
+- `--force` — overwrite the default output file (speech.<format>) if it already exists
+
+Global options apply here too — see [global options](./global-options.md).

docs/voices-get.md

@@ -0,0 +1,17 @@
+<!-- Generated by `pnpm docs:generate` from the CLI definitions. Do not edit by hand. -->
+
+# speechify voices get
+
+Show one voice: its models, locales, tags, and preview URLs.
+
+## Usage
+
+```
+speechify voices get [voice-id] [options]
+```
+
+## Arguments
+
+- `[voice-id]` — id of the voice to show (see `speechify voices list`); omit to be prompted
+
+Global options apply here too — see [global options](./global-options.md).

docs/voices-list.md

@@ -0,0 +1,19 @@
+<!-- Generated by `pnpm docs:generate` from the CLI definitions. Do not edit by hand. -->
+
+# speechify voices list
+
+List available voices (built-in and cloned).
+
+## Usage
+
+```
+speechify voices list [options]
+```
+
+## Options
+
+- `--locale <locale>` — filter by locale prefix, e.g. "en" (all English) or "en-US" (exact)
+- `--gender <gender>` — filter by gender (choices: `male`, `female`, `not_specified`)
+- `--search <text>` — case-insensitive match against voice id, name, and tags
+
+Global options apply here too — see [global options](./global-options.md).

docs/voices.md

@@ -0,0 +1,16 @@
+<!-- Generated by `pnpm docs:generate` from the CLI definitions. Do not edit by hand. -->
+
+# speechify voices
+
+Voice catalog.
+
+## Usage
+
+```
+speechify voices [options]
+```
+
+## Subcommands
+
+- [speechify voices list](./voices-list.md) — List available voices (built-in and cloned).
+- [speechify voices get](./voices-get.md) — Show one voice: its models, locales, tags, and preview URLs.

docs/whoami.md

@@ -0,0 +1,17 @@
+<!-- Generated by `pnpm docs:generate` from the CLI definitions. Do not edit by hand. -->
+
+# speechify whoami
+
+Show how you're authenticated (flag / env / stored API key).
+
+## Usage
+
+```
+speechify whoami [options]
+```
+
+## Options
+
+- `--check` — verify the credential against the API (exits non-zero when invalid)
+
+Global options apply here too — see [global options](./global-options.md).