poddrill 0.1.0 → 0.2.0

package/.agents/skills/poddrill/SKILL.md

@@ -2,66 +2,68 @@
 name: poddrill
 description: >-
   Transcribe a podcast episode into timed text, group the voices, and store
-  a summary whose paragraphs cite that text. The agent reads the text, names
-  the voices, and writes the summary words. PodDrill stores the episode.
-  Use when fetching episode audio, starting a transcript, labeling speakers,
-  or writing a summary. When a session has no PodDrill tools, register the
-  client before transcribing. Do not use it to change the poddrill TypeScript.
+  a summary whose paragraphs cite that text. Use when the user says to set up
+  PodDrill, fetch episode audio, start a transcript, label speakers, or write
+  a summary. Do not use it to change the poddrill TypeScript.
 ---
 
 # PodDrill
 
-PodDrill is a toolset to make transcription and summary of podcast audio streamlined and structured. You may also use it for any other audio. It maps an episode (the audio) to cues, clusters those cues into speaker groups, and stores summaries. You decide how to use the toolset to answer user's request of audio summary.
+PodDrill maps an episode (the audio) to cues, clusters those cues into speaker groups, and stores summaries. You decide how to use the toolset to answer the user's request. You read the text, name the voices, and write the summary words. PodDrill stores the episode.
 
-Set up a workspace once, when it is missing. After that, read the one guide for the part you are doing. Leave the other guides unread. If an episode already has the asset you need, read it. Do not reprocess the audio again.
+Install once, with the sequence below. After that, read the one guide for the part you are doing. Leave the other guides unread. If an episode already has the asset you need, read it.
 
-## Cues
+## Install on this computer
 
-An asset maps each segment of the audio to text. That segment is a cue. A cue has the text and the times. You read the cues. You do not invent the text or the times.
+Do this once on the computer that will transcribe. Each step is safe to repeat. `localhost`, `grok-bot`, and `cursor-cloud` all run the local Python host on this computer. The provider id names that computer.
 
-Read cues only after the embedding is ready. A ready transcript can still be not-ready for cues.
+1. Install Node.js 20.19 or newer and `ffmpeg`. Use the Node `.tar.gz` archive from `https://nodejs.org/dist/v20.19.0/`, or run `npx -y node@20.19.0`. On macOS, `brew install ffmpeg`. On Linux, `sudo apt-get install -y ffmpeg`.
 
-## Speaker groups
+2. Install the npm package. Read the published `version` and run `npm install -g poddrill@<version>`. Do not use `@latest`. Cloning the git repository is not required. If you clone it, set `GIT_TERMINAL_PROMPT=0`.
 
-An asset clusters cues that sound like one voice. That cluster is a speaker group. You assign the group a name, `quote`, `ending`, or `undetermined`. The utility does not choose the name.
+3. Run `poddrill install-python`. This creates `~/.cache/poddrill/venv` and installs cactus-needle 3.2.0, numpy 2.5.4, and onnxruntime 1.31.0. It uses `uv` when `uv` is on PATH, and otherwise `python3 -m venv`. The npm package named cactus-needle is a different package.
 
-A summary does not require those labels.
+4. Run `poddrill fetch-weights`. This downloads `voxceleb_ECAPA512.onnx` from the pinned WeSpeaker commit, checks the byte size and SHA-256, and writes `~/.cache/poddrill/ecapa/voxceleb_ECAPA512.onnx`. WeSpeaker ECAPA-TDNN512 pretrained on VoxCeleb. VoxCeleb is used under CC BY 4.0. A later run leaves a matching file in place.
 
-## Summaries
+5. Run `poddrill client doctor --client cursor --json`. Use `grok_build` or `grok_bot` in place of `cursor` when that is the client. For every check whose `state` is `bad`, run the `fix` command on that check, then run doctor again. `yt-dlp` is optional and does not fail the command. `workspace` stays `pending` until setup. Stop this loop when doctor exits 0, or when the only `bad` check is `link`.
 
-Summary is an asset of an episode. An episode can have multiple summary asset. You use the cues when you write a summary. PodDrill stores paragraphs that cite cues, then an episode summary written from the paragraph text. You choose which cues to include and you write the words. You do not write the file yourself.
+6. Run `poddrill setup --provider localhost --queue-length 4`. Without `PODDRILL_WORKSPACE`, setup and every other command use `~/poddrill`. For `ja`, `ko`, or `zh`, read the weights guide and pass `--model-weights` on that same command. `en`, `de`, `fr`, `es`, `it`, `nl`, and `pl` do not need Moonshine weights.
 
-## The episode
+   `poddrill bootstrap --provider localhost --queue-length 4` runs steps 3, 4, and 6.
 
-You keep the source list. The utility keeps the episode. The episode holds the transcript, the cues, the groups, the labels, and the summaries in your filesystem. Do not copy artifact state, progress, paths, or labels into the source list.
+7. Register the client. Run `poddrill client plan --client cursor --json`. After that plan is approved, run `poddrill client apply --yes --client cursor`. Grok Bot prints a sentence with the absolute Node binary, `dist/cli.js`, and an env block (`PATH`, `PODDRILL_PYTHON`, `PODDRILL_WORKSPACE`, `PODDRILL_EMBED_WEIGHTS`). Add that custom server in the Grok Bot chat. It does not write a config file.
+
+8. Run `poddrill client doctor --client cursor --json` again. Exit 0 means every required check is ok.
+
+A later refresh of clients that already have an entry is `poddrill client plan --linked --json`, then `poddrill client apply --yes --linked` after approval.
 
-## Register the client
+## Python
 
-When this session has no PodDrill tools, register the client before setting up a workspace. `<version>` is the `version` field in this package's `package.json`. Do not use `@latest`.
+`PODDRILL_PYTHON` selects the interpreter. Pass `--python` or set `PODDRILL_PYTHON` on setup to store an absolute path in `poddrill.json`. Otherwise PodDrill uses `~/.cache/poddrill/venv/bin/python` when that file exists, then `python3`. Install yt-dlp and moonshine-voice into that same interpreter. The current yt-dlp and moonshine-voice releases are unpinned.
 
-Run `npx -y poddrill@<version> client doctor --client cursor --json`. Use `grok_build` or `grok_bot` in place of `cursor` when that is the client.
+## Stop
 
-Then run `npx -y poddrill@<version> client plan --client cursor --json`.
+`poddrill stop` stops the running owner. Setup rejects a change while the owner is running. Run `poddrill stop` before you change the provider, queue length, fleet limit, or embedding limit.
 
-After that plan is approved, run `npx -y poddrill@<version> client apply --yes --client cursor`.
+## Cues
 
-A later refresh of clients that already have an entry is `npx -y poddrill@<version> client plan --linked --json`, then `npx -y poddrill@<version> client apply --yes --linked` after approval. Grok Bot prints a sentence and does not write a config file. Add that custom server in the Grok Bot chat. It runs on the bot's computer.
+An asset maps each segment of the audio to text. That segment is a cue. A cue has the text and the times. You read the cues. You do not invent the text or the times.
 
-## Set up once
+Read cues only after the embedding is ready. A ready transcript can still be not-ready for cues.
 
-Set `PODDRILL_WORKSPACE` to a directory outside the git tree that contains this skill. Without that variable, `setup` uses the current directory and every other command uses `~/poddrill`.
+## Speaker groups
 
-Run setup once in that workspace. The provider is the computer you are running on.
+An asset clusters cues that sound like one voice. That cluster is a speaker group. You assign the group a name, `quote`, `ending`, or `undetermined`. The utility does not choose the name.
 
-```
-poddrill setup --provider <id> --queue-length 4
-```
+A summary does not require those labels.
 
-If you are the Grok Bot agent, `<id>` is `grok-bot`. If you are the Cursor cloud agent, `<id>` is `cursor-cloud`. That computer is the host. Otherwise `<id>` is `localhost`.
+## Summaries
 
-For `ja`, `ko`, or `zh`, read the weights guide and pass `--model-weights` on that same setup command. `en`, `de`, `fr`, `es`, `it`, `nl`, and `pl` do not need weights.
+Summary is an asset of an episode. An episode can have multiple summary assets. You use the cues when you write a summary. PodDrill stores paragraphs that cite cues, then an episode summary written from the paragraph text. You choose which cues to include and you write the words. You do not write the file yourself.
 
-Stop the owner before you change setup. A running owner rejects a different provider, queue length, fleet limit, or embedding limit.
+## The episode
+
+You keep the source list. The utility keeps the episode. The episode holds the transcript, the cues, the groups, the labels, and the summaries in your filesystem. Do not copy artifact state, progress, paths, or labels into the source list.
 
 ## Start an episode
 
@@ -71,12 +73,14 @@ Pass `--language <code>` on `poddrill start` when the episode is not English. Th
 
 `poddrill start` returns before the transcript exists. Poll `poddrill episode <id>` until the transcript artifact `state` is `ready` or `failed`. The id is `ep_` plus the first 16 hex characters of the sha256 of the file bytes.
 
-The transcript is done when that `state` is `ready`. Exit 0 does not mean the transcript is done. If it is missing or `failed`, pass the same WAV to `poddrill start` again. The episode id does not change.
+The transcript is done when that `state` is `ready`. Exit 0 does not mean the transcript is done. If the transcript or the embedding is missing or `failed`, pass the same WAV to `poddrill start` again. The episode id does not change. `created` is false, and the failed artifact runs again.
 
 ## Read a result
 
 Parse the JSON line on stdout. `episode` exits 0 when the id is unknown. `not-ready` exits 0. `start` exits 1 when `kind` is `rejected` or `full`. MCP returns that same JSON. `isError` is true only when the text starts with `{"kind":"error"`.
 
+`poddrill --help` and `poddrill --version` print plain text and exit 0.
+
 ## Present the summary
 
 Present the summary in the format preferred or prescribed by users, but always grounded by the summary constructed via poddrill.

package/.agents/skills/poddrill/references/fetch-audio.md

@@ -16,14 +16,14 @@ The script refuses a destination inside the git tree that contains the script. P
 
 ## yt-dlp
 
-If the feed has no audio URL, or the script does not get the file, install the current yt-dlp and run that module. The printed line is the download path.
+If the feed has no audio URL, or the script does not get the file, install the current yt-dlp into the PodDrill Python and run that module. The version is unpinned. On a PEP 668 Python, install into the venv from `poddrill install-python`, or set `PODDRILL_PYTHON` to an interpreter that allows pip. A pipx install or a standalone yt-dlp binary also works. The printed line is the download path.
 
 ```
-python3 -m pip install --upgrade yt-dlp
-python3 -m yt_dlp -x --no-playlist --print after_move:filepath -o "<directory>/download.%(ext)s" "<page-url>"
+"$PODDRILL_PYTHON" -m pip install --upgrade yt-dlp
+"$PODDRILL_PYTHON" -m yt_dlp -x --no-playlist --print after_move:filepath -o "<directory>/download.%(ext)s" "<page-url>"
 ```
 
-Write `<directory>` outside this git repository. If that command does not get the audio, read [Usage and options](https://github.com/yt-dlp/yt-dlp#usage-and-options).
+`poddrill client doctor` reports yt-dlp as optional and prints that pip command when it is missing. Write `<directory>` outside this git repository. If that command does not get the audio, read [Usage and options](https://github.com/yt-dlp/yt-dlp#usage-and-options).
 
 ## Other audio
 

package/.agents/skills/poddrill/references/select-models.md

@@ -1,14 +1,16 @@
 # Set up Moonshine weights
 
-PodDrill does not download the weights. Install the package, download the model with word timestamps, then pass the returned directory to setup.
+PodDrill does not download the Moonshine weights. Install the current moonshine-voice release into the PodDrill Python, download the model with word timestamps, then pass the returned directory to setup. The version is unpinned. On a PEP 668 Python, use the venv from `poddrill install-python`.
 
-Install the package first.
+Install the package first. `$PODDRILL_PYTHON` is the interpreter PodDrill spawns.
 
 ```
-pip install moonshine-voice
+"$PODDRILL_PYTHON" -m pip install moonshine-voice
 ```
 
-`python -m moonshine_voice.download` on moonshine-voice 0.1.5 exits unless you pass `--stt`. That command prints `Downloaded model path:`. The directory on that line does not include the attention decoder, so word timestamps stay empty. Call `get_model_for_language` with `include_word_timestamps=True` instead. The returned path is the directory setup stores.
+A missing package fails with: `Install moonshine-voice into the PodDrill Python: "$PODDRILL_PYTHON" -m pip install moonshine-voice`.
+
+`"$PODDRILL_PYTHON" -m moonshine_voice.download` on moonshine-voice 0.1.5 exits unless you pass `--stt`. That command prints `Downloaded model path:`. The directory on that line does not include the attention decoder, so word timestamps stay empty. Call `get_model_for_language` with `include_word_timestamps=True` instead. The returned path is the directory setup stores.
 
 Setup still needs `--provider` and `--queue-length`. Use the provider the skill already named. Add `--model-weights` to that command.
 

package/README.md

@@ -1,29 +1,40 @@
 # PodDrill
 
-PodDrill transcribes episode audio into timed text, groups the voices, and stores a summary.
+PodDrill is a skill that transcribes episode audio into timed text, groups the voices, and stores a summary.
 
-## Requirements
+## Say this
 
-Use Node.js 22.18 or newer.
+Copy this to the agent.
 
-A transcript also needs ffmpeg and the Python package cactus-needle 3.2.0. That Python package is not the npm package named cactus-needle.
+```text
+Set up PodDrill on this computer.
+```
 
-## Run
+The supported install is the npm package. Read the published `version` and run `npm install -g poddrill@<version>`. Cloning this repository is not required. If you clone it, set `GIT_TERMINAL_PROMPT=0`. The agent then follows the skill shipped in the package.
 
-From this repository, run the command.
+## Requirements
 
-```
-node src/cli.ts
-```
+The computer that runs PodDrill needs:
 
-`npm run build` writes `dist`. The published package runs `dist/cli.js`, because Node does not strip TypeScript inside `node_modules`.
+- Node.js 20.19 or newer. Install the `.tar.gz` archive from `https://nodejs.org/dist/v20.19.0/`, or run `npx -y node@20.19.0`. The published CLI is plain JavaScript. The tests in this repository use `node --experimental-strip-types` and need a newer Node.
+- `ffmpeg` on `PATH`.
+- A Python interpreter with cactus-needle 3.2.0, numpy 2.5.4, and onnxruntime 1.31.0. The npm package named cactus-needle is a different package. `poddrill install-python` creates `~/.cache/poddrill/venv` and installs those pins. It uses `uv` when `uv` is on PATH, and otherwise `python3 -m venv`. `PODDRILL_PYTHON` selects another absolute interpreter, and setup stores that path in `poddrill.json`.
+- The ECAPA weights file. `poddrill fetch-weights` downloads `voxceleb_ECAPA512.onnx` from the pinned WeSpeaker commit, checks its size and SHA-256, and writes `~/.cache/poddrill/ecapa/voxceleb_ECAPA512.onnx`. `PODDRILL_EMBED_WEIGHTS` selects another path. WeSpeaker ECAPA-TDNN512 pretrained on VoxCeleb. VoxCeleb is used under CC BY 4.0.
 
-The npm package is not published yet. After it is published, run `npx poddrill`.
+`poddrill client doctor` prints a `fix` command for every check that is not ok. `poddrill bootstrap` runs `install-python`, `fetch-weights`, and `setup`.
 
-## Workspace
+Without `PODDRILL_WORKSPACE`, every command uses `~/poddrill`. `poddrill stop` stops the running owner.
 
-Set `PODDRILL_WORKSPACE` to a directory outside this repository. Then run `poddrill setup` in that directory.
+Grok Bot cannot write its server entry. It prints the custom server to add: the absolute Node binary, `dist/cli.js`, and an env block. Add that server in the Grok Bot chat.
+
+## Tests
+
+`npm test` runs the unit tests. Those tests use `node --experimental-strip-types`.
+
+`npm run test:smoke` runs a clean-home install, downloads the ECAPA file, and transcribes a short generated clip through `dist/cli.js`. It needs `python3` with `ensurepip`, `ffmpeg`, and `espeak-ng`. If one of those is missing, the test skips and names the missing tool. This repository has no CI workflow. Run `npm run test:smoke` on a computer that has those tools. Build `dist/` with `npm run build` first.
 
 ## License
 
-MIT License. Copyright (c) 2026 Jianyu Zhao.
+MIT License. Copyright 2026 Jianyu Zhao.
+
+The ECAPA weights are separate from this license. WeSpeaker ECAPA-TDNN512 pretrained on VoxCeleb. VoxCeleb is used under CC BY 4.0.

package/dist/cli.js

@@ -1,26 +1,56 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
 import { realpath } from "node:fs/promises";
-import { isAbsolute, resolve } from "node:path";
+import { isAbsolute } from "node:path";
 import { fileURLToPath } from "node:url";
 import { clientMain, workspaceSetupCollision } from "./client.js";
-import { asRecord, errorCode } from "./disk.js";
+import { asRecord, errorCode, pathExists } from "./disk.js";
+import { embedWeightsPath } from "./embed.js";
 import { isModelId } from "./models.js";
-import { callOwner, ownerAlive, proxyMcp, render, serve } from "./owner.js";
-import { resolveWorkspace, setupWorkspace } from "./workspace.js";
+import { nodeInstallMessage, nodeMeetsMinimum } from "./node-version.js";
+import { callOwner, ownerAlive, proxyMcp, pythonForOwner, render, serve } from "./owner.js";
+import { readPackageIdentity } from "./package-identity.js";
+import { installPython } from "./python-env.js";
+import { fetchEcapa } from "./weights.js";
+import { defaultWorkspacePath, resolveWorkspace, setupWorkspace } from "./workspace.js";
 const usage = [
     "usage: poddrill setup --provider <id> --queue-length <n> [--fleet-limit <n>] [--whistle-limit <n>]",
-    "[--model-fleet <id>=<count>] [--model-weights <id>=<path>] [--embedding-limit <n>]",
+    "[--model-fleet <id>=<count>] [--model-weights <id>=<path>] [--embedding-limit <n>] [--python <path>]",
+    "| install-python | fetch-weights | bootstrap [--provider <id>] [--queue-length <n>]",
     "| start <path> [--language <code>] | episode <episodeId> | cues <episodeId> [--limit <n>] [--after <cueId>] [--group-id <id>] [--hosts]",
     "| label-groups <episodeId> <json> | start-summary <episodeId> | set-summary <episodeId> <summaryId> <json>",
-    "| put-paragraph <episodeId> <summaryId> <json> | post-paragraph <episodeId> <summaryId> <json> | summary <episodeId> <summaryId> | audit <episodeId> | serve | mcp",
+    "| put-paragraph <episodeId> <summaryId> <json> | post-paragraph <episodeId> <summaryId> <json> | summary <episodeId> <summaryId> | audit <episodeId>",
+    "| serve | stop | mcp [--selftest] | --help | --version",
 ].join(" ");
 async function main() {
+    if (!nodeMeetsMinimum(process.versions.node)) {
+        await emit(render({ kind: "error", message: nodeInstallMessage(process.versions.node) }), 1);
+    }
     const command = process.argv[2];
     switch (command) {
+        case "--help":
+        case "-h":
+        case "help":
+            await emit(helpText(), 0);
+        case "--version":
+        case "-v":
+        case "version":
+            await emit(await versionText(), 0);
         case "setup":
             await runSetup(process.argv.slice(3));
             return;
+        case "install-python":
+            await runInstallPython();
+            return;
+        case "fetch-weights":
+            await runFetchWeights();
+            return;
+        case "bootstrap":
+            await runBootstrap(process.argv.slice(3));
+            return;
+        case "stop":
+            await runStop();
+            return;
         case "client": {
             const rendered = await clientMain(process.argv.slice(3), process.env, import.meta.url);
             await emit(rendered.text, rendered.exitCode);
@@ -60,7 +90,7 @@ async function main() {
             await serve(await resolveWorkspace(process.env), false);
             return;
         case "mcp":
-            await runMcp();
+            await runMcp(process.argv.slice(3));
             return;
         default:
             await emit(render({ kind: "error", message: usage }), 1);
@@ -91,6 +121,7 @@ async function runSetup(args) {
     const fleetLimit = sharedLimit(fleetText, whistleText);
     const modelFleet = modelFleetFrom(fleetArgs);
     const modelWeights = modelWeightsFrom(weightArgs);
+    const python = await chosenPython(args);
     const root = await workspaceArg();
     const alive = await ownerAlive(root);
     const result = await setupWorkspace({
@@ -101,6 +132,7 @@ async function runSetup(args) {
         ...(modelFleet === undefined ? {} : { modelFleet }),
         ...(modelWeights === undefined ? {} : { modelWeights }),
         ...(embeddingText === undefined ? {} : { embeddingLimit: Number(embeddingText) }),
+        ...(python === undefined ? {} : { python }),
         ownerAlive: alive,
     });
     await emit(render(publicSetup(result)), result.kind === "ready" ? 0 : 1);
@@ -262,7 +294,66 @@ async function runEpisode(episodeId) {
     await ensureOwner(root);
     await emit(await callOwner(root, { op: "episode", episodeId }), 0);
 }
-async function runMcp() {
+async function runInstallPython() {
+    const installed = await installPython(process.env, import.meta.url);
+    await emit(render({ kind: "ready", ...installed }), 0);
+}
+async function runFetchWeights() {
+    const fetched = await fetchEcapa(embedWeightsPath(process.env));
+    await emit(render({ kind: "ready", ...fetched }), 0);
+}
+async function runBootstrap(args) {
+    const provider = flag(args, "--provider") ?? "localhost";
+    const queueText = flag(args, "--queue-length") ?? "4";
+    if (!isCountText(queueText) || flag(args, "--provider") === "") {
+        await emit(render({ kind: "error", message: usage }), 1);
+    }
+    const installed = await installPython(process.env, import.meta.url);
+    const weights = await fetchEcapa(embedWeightsPath(process.env));
+    const root = await workspaceArg();
+    const alive = await ownerAlive(root);
+    const result = await setupWorkspace({
+        root,
+        provider,
+        queueLength: Number(queueText),
+        python: installed.python,
+        ownerAlive: alive,
+    });
+    if (result.kind !== "ready") {
+        await emit(render(publicSetup(result)), 1);
+    }
+    await emit(render({
+        kind: "ready",
+        python: installed.python,
+        installer: installed.installer,
+        weights,
+        setup: publicSetup(result),
+    }), 0);
+}
+async function runStop() {
+    const root = await resolveWorkspace(process.env);
+    if (!(await ownerAlive(root))) {
+        await emit(render({ kind: "ready", state: "stopped" }), 0);
+    }
+    const text = await callOwner(root, { op: "stop" });
+    await emit(text, text.includes("\"kind\":\"error\"") ? 1 : 0);
+}
+async function runMcp(args) {
+    if (args.includes("--selftest")) {
+        const root = await resolveWorkspace(process.env);
+        const python = await pythonForOwner(process.env, root);
+        await emit(render({
+            kind: "ready",
+            execPath: process.execPath,
+            script: fileURLToPath(import.meta.url),
+            env: {
+                PATH: process.env["PATH"] ?? "",
+                PODDRILL_PYTHON: python,
+                PODDRILL_WORKSPACE: defaultWorkspacePath(process.env),
+                PODDRILL_EMBED_WEIGHTS: embedWeightsPath(process.env),
+            },
+        }), 0);
+    }
     const root = await resolveWorkspace(process.env);
     if (await ownerAlive(root)) {
         await proxyMcp(root);
@@ -296,6 +387,7 @@ function publicSetup(result) {
                 queueLength: result.report.config.queueLength,
                 fleetLimit: result.report.config.fleetLimit,
                 embeddingLimit: result.report.config.embeddingLimit,
+                ...(result.report.config.python === undefined ? {} : { python: result.report.config.python }),
             };
         case "rejected":
             return {
@@ -317,8 +409,7 @@ function isCountText(text) {
     return /^[1-9]\d*$/.test(text);
 }
 async function workspaceArg() {
-    const configured = process.env["PODDRILL_WORKSPACE"];
-    const candidate = resolve(configured === undefined || configured === "" ? process.cwd() : configured);
+    const candidate = defaultWorkspacePath(process.env);
     try {
         return await realpath(candidate);
     }
@@ -430,6 +521,68 @@ function splitPair(text) {
     }
     return { left: text.slice(0, index), right: text.slice(index + 1) };
 }
+async function chosenPython(args) {
+    const flagged = flag(args, "--python");
+    const fromEnv = process.env["PODDRILL_PYTHON"];
+    const flaggedSet = flagged !== undefined && flagged !== "";
+    const envSet = fromEnv !== undefined && fromEnv !== "";
+    if (!flaggedSet && !envSet) {
+        return undefined;
+    }
+    if (flaggedSet && envSet && flagged !== fromEnv) {
+        await emit(render({ kind: "error", message: `python ${flagged} and PODDRILL_PYTHON ${fromEnv} differ` }), 1);
+    }
+    const chosen = flaggedSet ? flagged : fromEnv;
+    if (typeof chosen !== "string" || !isAbsolute(chosen)) {
+        await emit(render({ kind: "error", message: `python must be an absolute path, got ${String(chosen)}` }), 1);
+    }
+    if (typeof chosen !== "string" || !(await pathExists(chosen))) {
+        await emit(render({ kind: "error", message: `python interpreter not found at ${String(chosen)}` }), 1);
+    }
+    if (typeof chosen !== "string") {
+        await emit(render({ kind: "error", message: "python must be an absolute path" }), 1);
+    }
+    return chosen;
+}
+function helpText() {
+    const lines = [
+        "poddrill transcribes audio, groups voices, and stores a summary.",
+        "",
+        "Commands:",
+        "  setup --provider <id> --queue-length <n> [--fleet-limit <n>] [--embedding-limit <n>]",
+        "        [--model-fleet <id>=<count>] [--model-weights <id>=<path>] [--python <path>]",
+        "  install-python     create ~/.cache/poddrill/venv and install pinned Python packages",
+        "  fetch-weights      download the pinned ECAPA file and check its sha256",
+        "  bootstrap [--provider <id>] [--queue-length <n>]",
+        "                     install-python, fetch-weights, then setup",
+        "  start <path> [--language <code>]",
+        "  episode <episodeId>",
+        "  cues <episodeId> [--limit <n>] [--after <cueId>] [--group-id <id>] [--hosts]",
+        "  label-groups <episodeId> <json>",
+        "  start-summary <episodeId>",
+        "  set-summary <episodeId> <summaryId> <json>",
+        "  put-paragraph <episodeId> <summaryId> <json>",
+        "  post-paragraph <episodeId> <summaryId> <json>",
+        "  summary <episodeId> <summaryId>",
+        "  audit <episodeId>",
+        "  serve",
+        "  stop               stop the running owner",
+        "  mcp [--selftest]",
+        "  client doctor|plan|apply",
+        "",
+        "  --help             show this text",
+        "  --version          print the package version",
+        "",
+        "Providers localhost, grok-bot, and cursor-cloud all run the local Python host on this computer.",
+        "Every command uses PODDRILL_WORKSPACE, or ~/poddrill when that variable is unset.",
+        "Python is PODDRILL_PYTHON, then the path stored by setup, then ~/.cache/poddrill/venv/bin/python, then python3.",
+    ];
+    return `${lines.join("\n")}\n`;
+}
+async function versionText() {
+    const identity = await readPackageIdentity(import.meta.url);
+    return `poddrill ${identity.version}\n`;
+}
 function delay(ms) {
     return new Promise((resolve) => {
         setTimeout(resolve, ms);