docs: fix dg listen examples and drop deprecated dg transcribe references (#53)

## Summary

Three doc bugs surfaced during Hasan's end-to-end command testing for
the launch blog.

| Bug | Where | Cause |
|---|---|---|
| `dg transcribe` references in user-facing docs |
`web/src/pages/index.astro`, `README.md`, `AGENTS.md` | Earlier commit
[`4676d34`](4676d34) replaced
some `dg transcribe` references with `dg listen` but missed several. `dg
transcribe` is now a hidden, deprecated alias for `dg listen` (kept for
backwards compat) and shouldn't be advertised. |
| `dg listen ... -o json` rejected by Click | landing page, `README.md`,
`dg listen --help` examples, listen `agent_help` text | `-o`/`--output`
is defined on the cli group at
[`src/deepctl/main.py:127`](https://github.com/deepgram/cli/blob/main/src/deepctl/main.py#L127),
not on subcommands. Correct invocation is `dg -o json listen audio.mp3`.
The wrong-position form 401s with "no such option: -o". |
| `jq '.full_result.results.channels[0]...'` returns `null` | `dg listen
--help` example | The listen command's JSON output
([`command.py:1062`](https://github.com/deepgram/cli/blob/main/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py#L1062))
writes `result.full_result` directly to stdout, so the actual top level
is `.results.channels[0]...`. The `.full_result.` prefix in the example
was wrong. |

Bugs (2) and (3) compound: running the example verbatim (`dg listen
audio.mp3 -o json | jq '.full_result.results...'`) fails twice. Click
rejects `-o` at the subcommand position, jq parses the failure output
and returns null, and the user concludes the CLI is broken.

## What changes

- `README.md` — 4 example snippets (`dg transcribe` → `dg listen`, `-o
json` repositioned)
- `AGENTS.md` — 1 flow example. Catalog row updated: replaced the `dg
transcribe` row with the canonical `dg listen` row, with a note that `dg
transcribe` is a hidden deprecated alias.
- `web/src/pages/index.astro` — 6 examples across the JSON-LD FAQ, hero,
CLI command catalog, and JSON-pipeline demo strip.
- `packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py` — the
entry in `examples` (jq path + flag position) and the `agent_help`
string (`-o json` repositioned, alias deprecation note clarified).

No code-logic changes. The fix is purely the documented invocations and
jq path.

## Verification

- `ruff format --check src/ packages/*/src` clean
- `ruff check src/ packages/*/src` clean
- `mypy --strict src/ packages/*/src` clean (112 source files)
- Grep sweep for `dg transcribe` returns only intentional
alias-documentation lines (the catalog row noting the alias, the
`agent_help` string mentioning the alias, the listen module's docstring
noting transcribe is registered as an alias)
- Grep sweep for `listen ... -o json` returns nothing in the
wrong-position form

## Out of scope

The listen command's JSON output structure is what it is, but worth
flagging for a future pass: when `result.full_result` is set we strip
the wrapping `ListenResult` model and emit the raw Deepgram response.
When `full_result` is `None` (e.g. live caption mode after streaming) we
emit the wrapping model. So the JSON shape isn't 100% consistent across
modes. Not changing here, but worth tracking.

## Companion follow-up

The `dg transcribe` package (`deepctl-cmd-transcribe`) remains in the
repo as a deprecated, hidden alias. We can drop it in a future major
release. Not part of this PR.

Author: lukeocodes

AGENTS.md

@@ -49,7 +49,7 @@ The CLI uses Python entry points for zero-config plugin discovery:
 ### Data Flow
 
 ```
-User runs: dg transcribe audio.wav --output json
+User runs: dg --output json listen audio.wav
   │
   ▼
 main() → preprocess_hyphenated_commands() → cli()
@@ -601,7 +601,7 @@ Each package is versioned independently via release-please.
 | `dg login` | `deepctl-cmd-login` | No | Browser-based or API key authentication |
 | `dg logout` | `deepctl-cmd-login` | No | Clear credentials |
 | `dg profiles` | `deepctl-cmd-login` | No | Manage named profiles |
-| `dg transcribe` | `deepctl-cmd-transcribe` | Yes | Speech-to-text for files and URLs |
+| `dg listen` | `deepctl-cmd-listen` | Yes | Unified speech-to-text (files, URLs, mic, stdin streaming). `dg transcribe` is a hidden, deprecated alias kept for backwards compat. |
 | `dg projects` | `deepctl-cmd-projects` | Yes | List/manage Deepgram projects |
 | `dg usage` | `deepctl-cmd-usage` | Yes | View usage statistics |
 | `dg api` | `deepctl-cmd-api` | Yes | Raw API requests (`dg api GET /v1/projects`) |

README.md

@@ -95,7 +95,7 @@ dg listen keynote.mp3 --diarize --model nova-3
 dg listen https://cdn.example.com/podcast.mp3
 
 # Pipe to jq for scripting
-dg listen standup.mp3 -o json \
+dg -o json listen standup.mp3 \
   | jq '.results.channels[0].alternatives[0].transcript'
 
 # Live microphone with interim (partial) results
@@ -163,8 +163,8 @@ dg mcp --transport sse --port 8000
 Transcribe audio files, URLs, or live microphone input.
 
 ```bash
-dg transcribe meeting.wav --diarize --smart-format
-dg transcribe https://example.com/audio.mp3 --model nova-3
+dg listen meeting.wav --diarize --smart-format
+dg listen https://example.com/audio.mp3 --model nova-3
 dg listen --mic --model nova-3 --language en-US
 cat audio.raw | dg listen --encoding linear16 --sample-rate 16000
 ```
@@ -280,7 +280,7 @@ export DEEPGRAM_API_KEY="your-key"
 export DEEPGRAM_PROJECT_ID="your-project-id"
 
 # Non-interactive usage
-dg transcribe recording.wav
+dg listen recording.wav
 dg speak "Deploy complete" -o notification.mp3
 dg keys --create --comment "ci-key" --scopes member
 dg keys --delete KEY_ID --yes

packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py

@@ -86,16 +86,17 @@ class ListenCommand(BaseCommand):
         "dg listen https://example.com/call.mp3 --diarize",
         "dg listen --mic --model nova-3 --interim",
         "dg listen audio.mp3 --diarize --summarize --save-to transcript.txt",
-        "dg listen audio.mp3 -o json | jq '.full_result.results.channels[0].alternatives[0].transcript'",
+        "dg -o json listen audio.mp3 | jq '.results.channels[0].alternatives[0].transcript'",
         "ffmpeg -i video.mp4 -f s16le -ar 16000 -ac 1 - | dg listen --encoding linear16",
         "dg listen -  # read raw audio from stdin interactively",
     ]
     agent_help = (
         "Unified speech-to-text command. Auto-detects input mode from the SOURCE "
         "argument (file path or URL), --mic flag, or stdin pipe. Supports diarization "
         "(--diarize), summarization (--summarize), topic detection (--topics), "
-        "smart formatting, and all Deepgram models. Use -o json for machine-readable "
-        "output of the full Deepgram API response. `dg transcribe` is an alias."
+        "smart formatting, and all Deepgram models. Use `dg -o json listen ...` for "
+        "machine-readable output of the full Deepgram API response. `dg transcribe` "
+        "is a hidden, deprecated alias."
     )
 
     def get_arguments(self) -> list[dict[str, Any]]:

web/src/pages/index.astro

@@ -370,7 +370,7 @@ const commandCards: CommandCard[] = [
             "name": "How do I transcribe an audio file with the Deepgram CLI?",
             "acceptedAnswer": {
               "@type": "Answer",
-              "text": "After logging in with 'dg login', run: dg transcribe recording.wav. You can also transcribe URLs (dg transcribe https://example.com/audio.mp3), enable speaker diarization (--diarize), select a model (--model nova-3), and export to JSON (--output json)."
+              "text": "After logging in with 'dg login', run: dg listen recording.wav. You can also transcribe URLs (dg listen https://example.com/audio.mp3), enable speaker diarization (--diarize), select a model (--model nova-3), and export JSON for scripting (dg -o json listen recording.wav)."
             }
           },
           {
@@ -650,7 +650,7 @@ const commandCards: CommandCard[] = [
           </div>
           <div class="p-5 font-mono text-sm leading-7 space-y-0.5">
             <div class="text-dg-muted text-xs"># Transcribe + extract with jq</div>
-            <div><span class="text-dg-green">$</span> <span class="text-dg-fog"> dg transcribe call.mp3 -o json \</span></div>
+            <div><span class="text-dg-green">$</span> <span class="text-dg-fog"> dg -o json listen call.mp3 \</span></div>
             <div class="pl-5 text-dg-fog">| jq <span class="text-amber-400">'.results.channels[0]
     .alternatives[0].transcript'</span></div>
             <div class="text-dg-muted pt-0.5 text-xs">"Hello and welcome to our Q1 review..."</div>
@@ -660,7 +660,7 @@ const commandCards: CommandCard[] = [
             <div class="pl-5 text-dg-fog">| ffplay -nodisp -autoexit -</div>
 
             <div class="text-dg-muted text-xs pt-3"># Stream mic → log</div>
-            <div><span class="text-dg-green">$</span> <span class="text-dg-fog"> dg listen --mic -o json | tee log.jsonl</span></div>
+            <div><span class="text-dg-green">$</span> <span class="text-dg-fog"> dg -o json listen --mic | tee log.jsonl</span></div>
           </div>
         </div>
       </div>
@@ -776,7 +776,7 @@ const commandCards: CommandCard[] = [
             <div class="text-dg-muted text-xs"># Authenticate</div>
             <div><span class="text-dg-green">$</span> <span class="text-dg-fog"> dg login</span></div>
             <div class="text-dg-muted text-xs pt-2"># Transcribe</div>
-            <div><span class="text-dg-green">$</span> <span class="text-dg-fog"> dg transcribe audio.mp3</span></div>
+            <div><span class="text-dg-green">$</span> <span class="text-dg-fog"> dg listen audio.mp3</span></div>
             <div class="text-dg-muted text-xs pt-2"># Explore</div>
             <div><span class="text-dg-green">$</span> <span class="text-dg-fog"> dg --help</span></div>
           </div>
@@ -812,7 +812,7 @@ const commandCards: CommandCard[] = [
               </p>
               <code class="inline-block font-mono text-xs px-4 py-2.5 rounded-xl text-dg-fog"
                     style="background:#0b0b0c; border: 1px solid #2c2c33;">
-                dg transcribe audio.mp3 --agent-friendly
+                dg listen audio.mp3 --agent-friendly
               </code>
             </div>
 
@@ -909,7 +909,7 @@ const commandCards: CommandCard[] = [
     ],
     // ── JSON pipeline ─────────────────────────────
     [
-      { p: '❯ ', t: "dg listen standup.mp3 -o json | jq '.results.channels[0].alternatives[0].transcript'", c: '' },
+      { p: '❯ ', t: "dg -o json listen standup.mp3 | jq '.results.channels[0].alternatives[0].transcript'", c: '' },
       { p: '',   t: '"Blocked on auth; need a review on PR 847 by EOD."', c: '#edede2' },
       { p: '',   t: '', c: '' },
     ],