poddrill 0.1.1 → 0.2.1

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

@@ -2,74 +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 the user says to set up PodDrill on this computer, when fetching
-  episode audio, starting a transcript, labeling speakers, or writing a summary.
-  When a session has no PodDrill tools, install the requirements, register the
-  client, and set up the workspace 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.
 
-Find the package, install the requirements, register the client, and set up the workspace once. 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.
 
-## Find the package
+## Install on this computer
 
-The npm package is `poddrill`. Before it is on disk, read the published `version` and use `npx -y poddrill@<version>`. After it is installed, `<version>` is the `version` field in that package's `package.json`. Do not use `@latest`.
+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.
 
-Install Node.js 22.18 or newer, `ffmpeg` on `PATH`, and the Python package `cactus-needle` 3.2.0. The npm package named cactus-needle is a different package. Place the ECAPA file at `~/.cache/poddrill/ecapa/voxceleb_ECAPA512.onnx`, or set `PODDRILL_EMBED_WEIGHTS` to another path. This package does not install those, and it has no download URL for the ECAPA file.
+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`.
 
-## Cues
+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 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.
+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.
 
-Read cues only after the embedding is ready. A ready transcript can still be not-ready for cues.
+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.
 
-## Speaker groups
+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`.
 
-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.
+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.
 
-A summary does not require those labels.
+   `poddrill bootstrap --provider localhost --queue-length 4` runs steps 3, 4, and 6.
 
-## Summaries
+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.
 
-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.
+8. Run `poddrill client doctor --client cursor --json` again. Exit 0 means every required check is ok.
 
-## The episode
+A later refresh of clients that already have an entry is `poddrill client plan --linked --json`, then `poddrill client apply --yes --linked` after approval.
 
-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.
+## Python
 
-## Register the client
+`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.
 
-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`.
+## Stop
 
-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.
+`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.
 
-Then run `npx -y poddrill@<version> client plan --client cursor --json`.
+## Cues
 
-After that plan is approved, run `npx -y poddrill@<version> client apply --yes --client cursor`.
+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.
 
-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.
+Read cues only after the embedding is ready. A ready transcript can still be not-ready for cues.
 
-## Set up once
+## Speaker groups
 
-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`.
+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.
 
-Run setup once in that workspace. The provider is the computer you are running on.
+A summary does not require those labels.
 
-```
-poddrill setup --provider <id> --queue-length 4
-```
+## Summaries
 
-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`.
+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.
 
-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.
+## The episode
 
-Stop the owner before you change setup. A running owner rejects a different provider, queue length, fleet limit, or embedding limit.
+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
 
@@ -79,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

@@ -10,16 +10,31 @@ Copy this to the agent.
 Set up PodDrill on this computer.
 ```
 
-The npm package is `poddrill`. The agent installs that package and the requirements below, then follows the skill shipped in the package.
+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.
 
 ## Requirements
 
-The computer that runs PodDrill needs Node.js 22.18 or newer, `ffmpeg` on `PATH`, and the Python package `cactus-needle` 3.2.0. The npm package named cactus-needle is a different package.
+The computer that runs PodDrill needs:
 
-That computer also needs the ECAPA weights file. The default path is `~/.cache/poddrill/ecapa/voxceleb_ECAPA512.onnx`. `PODDRILL_EMBED_WEIGHTS` selects another path.
+- 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.
 
-Grok Bot cannot write its server entry. It prints the custom server to add. Add that server in the Grok Bot chat.
+`poddrill client doctor` prints a `fix` command for every check that is not ok. `poddrill bootstrap` runs `install-python`, `fetch-weights`, and `setup`.
+
+Without `PODDRILL_WORKSPACE`, every command uses `~/poddrill`. `poddrill stop` stops the running owner.
+
+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 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);