crewly 1.13.1 → 1.14.1

package/config/constants.ts

@@ -873,6 +873,14 @@ export const AGENT_SUSPEND_CONSTANTS = {
 	ALWAYS_ON_ROLES: ['orchestrator', 'auditor'] as const,
 	/** Idle timeout in ms before a worker agent is stopped (default 30 min) */
 	AGENT_IDLE_STOP_TIMEOUT_MS: 1_800_000,
+	/**
+	 * Do not idle-stop an agent whose next cron run is due within this many
+	 * minutes. Killing it only to respawn it for the cron costs a cold start
+	 * (init prompt + registration + recall, ~0.5-1M input tokens on Codex)
+	 * every single run — a 15-minute cron under a 10-minute idle timeout
+	 * paid that 50 times a day on steamfun-ops (2026-09-16).
+	 */
+	CRON_KEEPALIVE_WINDOW_MINUTES: 30,
 } as const;
 
 // ========================= SERVER PROCESS CONSTANTS =========================

package/config/roles/orchestrator/prompt.md

@@ -618,6 +618,29 @@ After queueing, continue the turn normally. A separate `wiki-process-queue` run
 
 The trigger debounces — replying does not cause re-fire. Ignoring it means the next fire arrives 4h later and the counter shows zero queue-adds, which Steve will notice during audits.
 
+## Context Hygiene — keep tool output small (2026-09-16) — MANDATORY
+
+Every byte a command prints stays in your context for the rest of the
+session and is re-sent to the model on every subsequent call. On a
+long-running box the cost of the session is dominated by this, not by
+the work itself. Rules:
+
+1. **Never dump raw output.** No bare `cat` of a file, no raw `curl`/API
+   JSON, no `rg` across a tree. Pipe through `jq '<selector>'`,
+   `head -n 40`, `grep`, or `wc -l` and ask for exactly the field you need.
+2. **`get-team-status` is compact by default.** Only pass `--full` when a
+   specific field is missing from the compact view.
+3. **Bridge-auto wiki WIs: one pass, then stop.** If `wiki-migrate --apply`
+   reports `applied: 0`, there is nothing left to migrate right now — say so
+   in `complete-task` and move on. Do not re-run scan + apply in the same
+   turn, and do not re-check "just in case"; the bridge backs off on its
+   own when nothing changed.
+4. **One reminder covers all queued WorkItems.** A `[CREWLY-DISPATCH]` that
+   lists several WIs means: process all of them in this turn. Do not wait
+   for a separate message per item.
+5. **Reflect / bookkeep messages list every vault at once.** Handle the
+   whole list in one sweep and reply once.
+
 ## Turn-end "idle-drain" checklist (2026-05-26) — MANDATORY
 
 Before yielding the turn, run this 5-step check. **Task work always wins** — only drain wiki when you're genuinely idle, never block a chat reply or active WI on wiki maintenance.

package/config/skills/agent/core/reply-channel/SKILL.md

@@ -36,9 +36,15 @@ user's chat UI sees it.
 bash config/skills/agent/core/reply-channel/execute.sh \
   --channel <channelId> \
   --content "your reply text" \
+  [--thread <messageId>] \
   [--cmid <clientMessageId>]
 ```
 
+`--thread` replies inside an existing thread. When the prompt you received
+came from a **Slack team channel** it names the thread id
+(`--thread <id>`); pass it through so your reply shows up in the same Slack
+thread, under your own name.
+
 Or with JSON:
 
 ```bash

package/config/skills/agent/core/reply-channel/execute.sh

@@ -15,7 +15,7 @@ print_usage() {
   cat <<'EOF_USAGE'
 Usage:
   # CLI flags (preferred)
-  bash execute.sh --channel <channelId> --content "reply text" [--cmid <clientMessageId>]
+  bash execute.sh --channel <channelId> --content "reply text" [--thread <messageId>] [--cmid <clientMessageId>]
 
   # Content from stdin
   echo "multi-line reply" | bash execute.sh --channel chan-1
@@ -27,6 +27,8 @@ Options:
   --channel   | -c   Target channel id (required)
   --content   | -m   Reply text (required unless piped via stdin)
   --content-file     Read reply text from a file path
+  --thread    | -t   Thread root message id — reply inside that thread
+                     (Slack team channels: keeps the reply in the same Slack thread)
   --cmid             Optional client-message-id for idempotency
   --json      | -j   Raw JSON payload
   --help      | -h   Show this help
@@ -37,6 +39,7 @@ INPUT_JSON=""
 CHANNEL_ID=""
 CONTENT=""
 CMID=""
+THREAD_ID=""
 
 # Detect legacy JSON argument as $1
 if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
@@ -62,6 +65,10 @@ while [[ $# -gt 0 ]]; do
       CMID="$2"
       shift 2
       ;;
+    --thread|-t)
+      THREAD_ID="$2"
+      shift 2
+      ;;
     --json|-j)
       INPUT_JSON="$2"
       shift 2
@@ -95,6 +102,7 @@ except Exception as e:
     sys.exit(0)
 print('CHANNEL=' + str(d.get('channelId', '')))
 print('CMID=' + str(d.get('clientMessageId', '')))
+print('THREAD=' + str(d.get('threadId', '')))
 # content is multi-line safe — use base64
 import base64
 c = d.get('content', '')
@@ -109,6 +117,7 @@ PY
       case "$line" in
         CHANNEL=*) [ -z "$CHANNEL_ID" ] && CHANNEL_ID="${line#CHANNEL=}";;
         CMID=*) [ -z "$CMID" ] && CMID="${line#CMID=}";;
+        THREAD=*) [ -z "$THREAD_ID" ] && THREAD_ID="${line#THREAD=}";;
         CONTENT_B64=*) [ -z "$CONTENT" ] && CONTENT="$(echo "${line#CONTENT_B64=}" | base64 -d 2>/dev/null)";;
       esac
     done <<< "$EXTRACTED"
@@ -131,12 +140,15 @@ fi
 # Build JSON body. Export CONTENT/CMID so python can read them safely without
 # quoting the values through the shell (avoids escaping hell for multi-line
 # content with quotes, backslashes, backticks, etc.).
-BODY=$(CONTENT="$CONTENT" CMID="$CMID" python3 -c '
+BODY=$(CONTENT="$CONTENT" CMID="$CMID" THREAD_ID="$THREAD_ID" python3 -c '
 import os, json
 p = {"content": os.environ["CONTENT"], "contentType": "markdown"}
 cmid = os.environ.get("CMID", "")
 if cmid:
     p["clientMessageId"] = cmid
+thread = os.environ.get("THREAD_ID", "")
+if thread:
+    p["threadId"] = thread
 print(json.dumps(p))
 ')
 

package/config/skills/agent/core/slack-post/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: slack-post
+description: Start a Slack conversation yourself — post to a channel or DM a person, under your own Slack identity. Use it to raise something proactively, not to answer a message you were already sent (that is reply-channel).
+version: 1.0.0
+category: communication
+skillType: claude-skill
+assignableRoles:
+  - team-leader
+  - tpm
+  - developer
+  - frontend-developer
+  - backend-developer
+  - fullstack-dev
+  - qa
+  - qa-engineer
+  - designer
+  - product-manager
+  - architect
+  - generalist
+  - sales
+  - support
+  - marketing
+triggers:
+  - slack post
+  - message slack
+  - dm on slack
+  - tell the team on slack
+tags:
+  - communication
+  - slack
+  - proactive
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 20000
+---
+
+# slack-post
+
+Send a Slack message on your own initiative. If you have a Slack identity of
+your own, the message comes from your bot user, so a DM is a real conversation
+between that person and you. Otherwise it goes out through the shared Crewly
+bot carrying your name and icon.
+
+## When to use
+
+- Something you found needs a human's attention now, and nobody asked you.
+- You finished long-running work and the person who wanted it is not in the
+  thread any more.
+- You need one specific person, so a DM beats the team channel.
+
+**Do not use it to answer a message you were handed.** A prompt that starts
+with `[CHAT:<channelId>]` is answered with `reply-channel`, which keeps your
+reply in the same Slack thread.
+
+## Invocation
+
+```bash
+bash config/skills/agent/core/slack-post/execute.sh \
+  --target "#general" \
+  --text "Deploy finished, staging is on 1.4.2."
+```
+
+```bash
+# DM a person by handle
+bash config/skills/agent/core/slack-post/execute.sh --target "@steve" --text "..."
+
+# Reply inside an existing Slack thread
+bash config/skills/agent/core/slack-post/execute.sh --target C0123ABCD --thread 1712345678.000100 --text "..."
+
+# Long text from a file, or piped
+bash .../execute.sh --target "#general" --text-file /tmp/report.md
+echo "..." | bash .../execute.sh --target "@steve"
+```
+
+## Target syntax
+
+| Target | Goes to |
+|---|---|
+| `#general` or `general` | that channel |
+| `C0123ABCD` | that channel by id |
+| `D0123ABCD` | an already-open DM |
+| `@steve` | a DM with that person |
+| `U0123ABCD` | a DM with that user id |
+
+Slack ids are upper-case and channel names are lower-case, which is how the
+two are told apart. Write ids exactly as Slack shows them.
+
+## Options
+
+| Flag | Short | Description |
+|---|---|---|
+| `--target` | `-c` | Channel or person (required) |
+| `--text` | `-m` | Message text (required unless piped or `--text-file`) |
+| `--text-file` | | Read the text from a file |
+| `--thread` | `-t` | Slack thread timestamp to reply inside |
+| `--json` | `-j` | Raw JSON payload |
+
+## Environment
+
+- `CREWLY_SESSION_NAME` — your agent session, attached automatically. The post
+  is sent under that agent's identity, so this must be set.
+- `CREWLY_API_URL` — defaults to `http://localhost:8787`.
+
+## Output
+
+On success, JSON on stdout:
+
+```json
+{"success":true,"channelId":"C-GEN","messageTs":"1712345678.000200","kind":"channel","postedAs":"agent"}
+```
+
+`postedAs` is `agent` when your own Slack bot sent it, `crewly` when the shared
+bot did.
+
+## Failures worth knowing
+
+| Message contains | What to do |
+|---|---|
+| `No Slack channel named` | check the name, or the bot cannot see it (private channel needs an invite) |
+| `No Slack user matches` | the handle is wrong; ask for the exact Slack handle |
+| `invite ... into the channel` | a private channel the bot is not in; ask a human to invite it |
+| `reinstall the app` | the Slack app is missing a scope; tell the owner |
+| `Slack is not connected` | Slack is not configured on this install; stop, do not retry |

package/config/skills/agent/core/slack-post/execute.sh

@@ -0,0 +1,127 @@
+#!/bin/bash
+# slack-post — send a Slack message on the agent's own initiative.
+#
+# Posts to a channel or opens a DM, under the calling agent's Slack identity
+# (its own bot user when it has one). The shared `api_call` helper attaches
+# `X-Agent-Session: $CREWLY_SESSION_NAME`, which the backend uses to pick that
+# identity — without it the request is refused.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../../_common/lib.sh"
+
+print_usage() {
+  cat <<'EOF_USAGE'
+Usage:
+  bash execute.sh --target <#channel|@user|C…|D…|U…> --text "message" [--thread <ts>]
+
+  echo "message" | bash execute.sh --target "#general"
+  bash execute.sh --target "@steve" --text-file /tmp/report.md
+  bash execute.sh '{"target":"#general","text":"hi","threadTs":"100.1"}'
+
+Options:
+  --target    | -c   Channel or person (required)
+  --text      | -m   Message text (required unless piped or --text-file)
+  --text-file        Read the message text from a file
+  --thread    | -t   Slack thread timestamp to reply inside
+  --json      | -j   Raw JSON payload
+  --help      | -h   Show this help
+EOF_USAGE
+}
+
+INPUT_JSON=""
+TARGET=""
+TEXT=""
+THREAD_TS=""
+
+# Legacy JSON as the first positional argument
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  INPUT_JSON="$1"
+  shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --target|-c) TARGET="$2"; shift 2 ;;
+    --text|-m) TEXT="$2"; shift 2 ;;
+    --text-file) TEXT="$(cat "$2")"; shift 2 ;;
+    --thread|-t) THREAD_TS="$2"; shift 2 ;;
+    --json|-j) INPUT_JSON="$2"; shift 2 ;;
+    --help|-h) print_usage; exit 0 ;;
+    *) echo "Unknown argument: $1" >&2; print_usage >&2; exit 2 ;;
+  esac
+done
+
+# Fall back to stdin for the body
+if [ -z "$TEXT" ] && [ -z "$INPUT_JSON" ] && [ ! -t 0 ]; then
+  TEXT="$(cat)"
+fi
+
+if [ -n "$INPUT_JSON" ]; then
+  EXTRACTED=$(INPUT_JSON="$INPUT_JSON" python3 -c '
+import base64, json, os, sys
+try:
+    d = json.loads(os.environ["INPUT_JSON"])
+except Exception as e:
+    print("PARSE_ERROR:" + str(e)); sys.exit(0)
+print("TARGET=" + str(d.get("target", "")))
+print("THREAD=" + str(d.get("threadTs", d.get("thread", ""))))
+print("TEXT_B64=" + base64.b64encode(str(d.get("text", "")).encode("utf-8")).decode("ascii"))
+')
+  if echo "$EXTRACTED" | grep -q '^PARSE_ERROR'; then
+    echo '{"success":false,"error":"invalid JSON payload"}' >&2
+    exit 2
+  fi
+  while IFS= read -r line; do
+    case "$line" in
+      TARGET=*) [ -z "$TARGET" ] && TARGET="${line#TARGET=}" ;;
+      THREAD=*) [ -z "$THREAD_TS" ] && THREAD_TS="${line#THREAD=}" ;;
+      TEXT_B64=*) [ -z "$TEXT" ] && TEXT="$(echo "${line#TEXT_B64=}" | base64 -d 2>/dev/null)" ;;
+    esac
+  done <<< "$EXTRACTED"
+fi
+
+if [ -z "$TARGET" ]; then
+  echo '{"success":false,"error":"--target is required (#channel, @user, or a Slack id)"}' >&2
+  exit 2
+fi
+if [ -z "$TEXT" ]; then
+  echo '{"success":false,"error":"--text is required (or pipe it via stdin)"}' >&2
+  exit 2
+fi
+if [ -z "${CREWLY_SESSION_NAME:-}" ]; then
+  echo '{"success":false,"error":"CREWLY_SESSION_NAME is unset — the post needs an agent identity"}' >&2
+  exit 2
+fi
+
+# Convert literal \n to real newlines, matching the other comm skills
+_NL=$'\n'; TEXT="${TEXT//\\n/$_NL}"
+
+BODY=$(TARGET="$TARGET" TEXT="$TEXT" THREAD_TS="$THREAD_TS" python3 -c '
+import json, os
+p = {"target": os.environ["TARGET"], "text": os.environ["TEXT"]}
+ts = os.environ.get("THREAD_TS", "")
+if ts:
+    p["threadTs"] = ts
+print(json.dumps(p))
+')
+
+if RESPONSE=$(api_call POST "/slack/post" "$BODY" 2>&1); then
+  echo "$RESPONSE" | python3 -c '
+import json, sys
+try:
+    d = json.load(sys.stdin).get("data") or {}
+except Exception:
+    print("{\"success\":true}"); raise SystemExit(0)
+print(json.dumps({
+    "success": True,
+    "channelId": d.get("channelId", ""),
+    "messageTs": d.get("messageTs", ""),
+    "kind": d.get("kind", ""),
+    "postedAs": d.get("postedAs", ""),
+}))
+'
+  exit 0
+else
+  echo "{\"success\":false,\"error\":$(echo "$RESPONSE" | python3 -c 'import json,sys;print(json.dumps(sys.stdin.read()))')}"
+  exit 1
+fi

package/config/skills/agent/remote-browser/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: Remote Browser
+description: "Drive the user's real Chrome browser through the Crewly Chrome Extension. Navigate, click, fill forms, screenshot, read text, run JS, inspect cookies/console. Each agent gets its own bound tab, so concurrent agents never fight over the active tab. Plain HTTP + bash — usable by any agent runtime, not just Claude."
+version: 1.0.0
+category: browser
+skillType: claude-skill
+assignableRoles:
+  - developer
+  - qa
+  - researcher
+  - marketing
+triggers:
+  - remote browser
+  - drive chrome
+  - control my browser
+  - use my chrome
+  - browser automation
+  - fill the form
+  - take a screenshot of the page
+  - scrape the page
+tags:
+  - browser
+  - chrome
+  - extension
+  - automation
+  - scraping
+---
+
+# Remote Browser
+
+Control the user's **real, logged-in Chrome** — their sessions, their cookies,
+their extensions — through the Crewly Chrome Extension.
+
+```
+agent → bash execute.sh → POST /api/browser/* → WebSocket → Chrome Extension → real tab
+```
+
+The transport is plain HTTP from a bash script, so **any agent runtime can use
+it** (Claude Code, Codex, Gemini CLI, a cron job). There is no MCP dependency
+and nothing model-specific.
+
+## Why this and not a headless browser
+
+Use this when the task needs the user's **actual logged-in state** — an account
+only they are signed into, a site behind SSO, a page whose content differs for
+an authenticated user. For anything that works logged-out, a headless browser is
+cheaper and will not disturb the user's window.
+
+## Usage
+
+Two equivalent calling conventions:
+
+```bash
+# JSON argument
+bash execute.sh '{"action":"navigate","url":"https://example.com"}'
+
+# Flags
+bash execute.sh --action navigate --url https://example.com
+bash execute.sh -a click -s "#submit"
+```
+
+`bash execute.sh --help` prints the action list.
+
+## Actions
+
+### Page control
+| Action | Required | Optional |
+|---|---|---|
+| `navigate` | `--url` | |
+| `screenshot` | | |
+| `full-page-screenshot` | | scrolls and stitches the whole page |
+| `read-text` | | `--selector` (defaults to whole page) |
+| `scroll` | | `--params` e.g. `'{"direction":"down","amount":3}'` |
+| `scroll-in-element` | | `--params` with a selector + direction |
+
+### Interaction
+| Action | Required | Optional |
+|---|---|---|
+| `click` | `--selector` | or `--params` for coordinate clicks |
+| `fill` | `--selector` `--value` | replaces the field's contents |
+| `type` | `--selector` `--text` | types keystroke by keystroke |
+| `hover` | `--selector` | |
+| `press-key` | `--params` e.g. `'{"key":"Enter"}'` | |
+| `select-option` | `--selector` + one of `--value` / `--params` with `label` or `index` | resolution order: value → label → index |
+| `set-file-input` | `--params` with selector + file path | |
+
+### Reading the page
+| Action | Required | Optional |
+|---|---|---|
+| `get-element` | `--selector` | |
+| `get-interactive-elements` | | `--params` — buttons/links/inputs with refs |
+| `search-text` | `--text` | locate text on the page |
+| `list-options` | `--selector` | enumerate a `<select>` |
+| `wait-for-selector` | `--selector` | blocks until it appears |
+| `execute-js` | `--code` | alias: `execute`. Raw JS in page context |
+
+### Browser state
+| Action | Notes |
+|---|---|
+| `tabs` | list open tabs |
+| `cookies` | optional `?domain=` on the endpoint |
+| `console` | recent console messages; optional `?clear=true` |
+| `local-storage` | `--params` to scope the read |
+| `status` | extension connection status |
+| `instances` | connected browser instances |
+| `proxy-connect` | manually connect the proxy to Cloud Relay |
+
+### Tab binding
+| Action | Notes |
+|---|---|
+| `bind-tab` | bind a tab to this agent; `--active` foregrounds it (default: background) |
+| `unbind-tab` | release the tab and close it |
+
+## Per-agent tab binding
+
+This is what makes the skill safe to run from several agents at once.
+
+When `CREWLY_SESSION_NAME` is set in the agent's environment it is forwarded as
+the `X-Agent-Session` header, and the backend dispatches each command to **that
+agent's own tab** instead of whatever tab the user is looking at.
+
+- The first command from a fresh agent auto-binds a new background tab.
+- The resulting id is cached at
+  `~/.crewly/runtime/<agentSession>/browser-tab-id`, so later calls skip the
+  bind round-trip.
+- Concurrent agents therefore never steal each other's page — and never yank
+  the user's foreground tab out from under them.
+
+Escape hatches:
+
+| Flag | Effect |
+|---|---|
+| `--tab-id <n>` | pin one call to a specific tab (tests, debugging) |
+| `--no-bind` | drop the session header and use the legacy active-tab path |
+| `--active` | with `bind-tab`, open the tab in the foreground |
+
+With `CREWLY_SESSION_NAME` unset, behaviour falls back to the legacy active-tab
+path, so scripts written before per-tab dispatch keep working unchanged.
+
+## Examples
+
+```bash
+# Read a page that requires the user's login
+bash execute.sh -a navigate -u "https://app.example.com/reports"
+bash execute.sh -a wait-for-selector -s ".report-table"
+bash execute.sh -a read-text -s ".report-table"
+
+# Fill and submit a form
+bash execute.sh -a fill -s "#email" -v "someone@example.com"
+bash execute.sh -a type -s "#note" -t "Following up on the quote"
+bash execute.sh -a click -s "button[type=submit]"
+
+# Pull structured data out of the DOM
+bash execute.sh -a execute-js -c '[...document.querySelectorAll(".row")].map(r=>r.innerText)'
+
+# Explicit lifecycle when doing a long multi-step job
+bash execute.sh -a bind-tab
+# ... many commands ...
+bash execute.sh -a unbind-tab
+```
+
+## Prerequisites
+
+- Crewly backend running, with the Chrome Extension connected
+  (`bash execute.sh -a status` to confirm)
+- `curl` and `jq` in PATH
+
+## Cautions
+
+- **This is the user's real browser.** Actions have real effects under their
+  real identity: a click can send a message, place an order, or delete
+  something. Confirm before anything irreversible or outward-facing.
+- Never enter passwords, card numbers, or other credentials — ask the user to
+  do it themselves in their own window.
+- Avoid clicking elements that raise native `alert()` / `confirm()` dialogs:
+  they block the extension until dismissed by hand.
+- Always `unbind-tab` when a job is done, or abandoned tabs accumulate in the
+  user's window.

package/config/skills/agent/xiaoyuzhoufm-transcript/SKILL.md

@@ -1,29 +1,37 @@
 ---
 name: xiaoyuzhoufm-transcript
-description: Extract and transcribe 小宇宙 (Xiaoyuzhou FM) podcast episodes. Downloads audio from episode URL and uses Gemini Audio API for transcription with speaker identification and timestamps.
+description: Extract and transcribe 小宇宙 (Xiaoyuzhou FM) podcast episodes. Resolves an episode URL to its audio, then transcribes with Whisper via the transcribe-audio skill — local whisper.cpp by default (free, offline), OpenAI Whisper API as fallback. Segment-level timestamps.
 category: content
 assignableRoles:
   - "*"
-version: "1.0.0"
+version: "2.0.0"
 tags:
   - podcast
   - transcript
   - audio
-  - gemini
+  - whisper
   - xiaoyuzhou
   - chinese
 ---
 
 # 小宇宙 Podcast Transcript
 
-Extract and transcribe podcast episodes from 小宇宙 (Xiaoyuzhou FM) using Gemini Audio API.
+Turn a 小宇宙 episode URL into a timestamped transcript.
 
 ## Pipeline
 
 ```
-Episode URL → Fetch HTML → Extract audio URL → Download m4a → Upload to Gemini → Transcribe → Output
+Episode URL → Fetch HTML → Extract audio URL → Download m4a
+                                                    ↓
+                                    transcribe-audio (Whisper) → Markdown + JSON
 ```
 
+This skill owns the 小宇宙 half — resolving an episode page to its audio and
+labelling the result. Transcription is delegated to the `transcribe-audio`
+skill, so there is one Whisper integration in the repo rather than two, and
+this skill inherits its engine selection, normalization and long-file handling
+for free.
+
 ## Usage
 
 ```bash
@@ -36,8 +44,12 @@ bash execute.sh '{"url":"https://www.xiaoyuzhoufm.com/episode/...","outputFile":
 # Transcribe a local audio file (skip download)
 bash execute.sh '{"audioFile":"/path/to/podcast.m4a"}'
 
-# Specify language hint
-bash execute.sh '{"url":"...","language":"Chinese"}'
+# Language hint (ISO-639-1) — helps on mixed Chinese/English episodes
+bash execute.sh '{"url":"...","language":"zh"}'
+
+# Force an engine
+bash execute.sh '{"url":"...","engine":"local"}'
+bash execute.sh '{"url":"...","engine":"openai"}'
 ```
 
 ## Parameters
@@ -47,7 +59,8 @@ bash execute.sh '{"url":"...","language":"Chinese"}'
 | `url` | Yes* | 小宇宙 episode URL |
 | `audioFile` | Yes* | Path to local audio file (alternative to url) |
 | `outputFile` | No | Save transcript as markdown to this path |
-| `language` | No | Language hint for Gemini (default: auto-detect) |
+| `language` | No | Language hint, ISO-639-1 (`zh`, `en`, `ja`…). Default: auto-detect |
+| `engine` | No | `auto` (default), `local`, or `openai` — passed to `transcribe-audio` |
 
 *Either `url` or `audioFile` is required.
 
@@ -58,28 +71,39 @@ bash execute.sh '{"url":"...","language":"Chinese"}'
   "success": true,
   "title": "Episode Title",
   "url": "https://www.xiaoyuzhoufm.com/episode/...",
-  "audioUrl": "https://media.xyzcdn.net/.../audio.m4a",
-  "model": "gemini-2.5-flash-preview-05-20",
-  "transcriptLength": 12345,
-  "transcript": "**Speaker 1:** [00:00:00] Welcome to the show..."
+  "audioUrl": "https://media.xyzcdn.net/...",
+  "engine": "whisper.cpp",
+  "language": "zh",
+  "duration": 4437,
+  "transcriptLength": 41234,
+  "transcript": "[00:00:00] ...\n[00:00:07] ..."
 }
 ```
 
 ## Transcript Format
 
-- Speaker turns identified with `**Speaker Name:** text`
-- Timestamps at segment/topic changes: `[HH:MM:SS]`
-- Preserves original language (Chinese/English/mixed)
+- One line per segment, prefixed `[HH:MM:SS]`
+- Original language preserved (Chinese / English / mixed)
 
 ## Prerequisites
 
-- `GEMINI_API_KEY` environment variable or configured in Settings > API Keys
-- `curl` and `jq` available in PATH
-- Internet access to xiaoyuzhoufm.com and Gemini API
+- `curl` and `jq` in PATH
+- Whatever `transcribe-audio` needs: `ffmpeg`, plus either a local whisper.cpp
+  install (`whisper-cli` + a `ggml-*` model) or `OPENAI_API_KEY` for the fallback
+- Internet access to xiaoyuzhoufm.com (and to the OpenAI API only if the local
+  engine is unavailable)
+
+**No Gemini key is required.** On the default local path the transcription runs
+entirely offline at zero per-use cost.
 
 ## Notes
 
-- Audio files are typically 30-90 minutes (20-80 MB)
-- Gemini processing takes 30-120 seconds depending on audio length
-- Maximum wait time: 5 minutes for Gemini processing
-- Temp files are auto-cleaned on exit
+- Episodes are typically 30–90 minutes (20–80 MB)
+- Local whisper.cpp roughly tracks real time on Apple Silicon; a 75-minute
+  episode takes on the order of ten minutes
+- Temp files (page HTML, downloaded audio) are auto-cleaned on exit — including
+  on interrupt, so a killed run leaves nothing behind and also keeps nothing
+  to resume from
+- **No speaker identification.** The previous Gemini-based version labelled
+  speaker turns; Whisper does not do diarization, so output is timestamped
+  segments only