crewly 1.11.2 → 1.11.4

package/config/skills/agent/core/accept-task/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: Accept Task
-description: Accept and take the next available task from the task queue.
+description: "Accept and take the next available task from the task queue. Use when an agent is idle and ready to pick up the highest-priority unassigned task. For assigning tasks to specific agents, use assign-task instead."
 version: 1.0.0
 category: task-management
 skillType: claude-skill
@@ -37,21 +37,49 @@ execution:
 
 # Accept Task
 
-Accept and take the next available task from the task queue. The backend assigns the highest-priority unassigned task to your session.
+Accept and take the next available task from the task queue. The backend selects the highest-priority unassigned task and assigns it to the requesting agent's session.
+
+## When to Use
+
+Run this skill when the agent is idle and ready to pick up new work. The backend automatically selects the highest-priority unassigned task; assignment is keyed by the agent's session.
 
 ## Parameters
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
-| `sessionName` | Yes | Your agent session name |
-| `teamMemberId` | No | Your team member ID for targeted assignment |
+| `sessionName` | Yes | The agent's session name (e.g., `dev-1`) |
+| `projectPath` | No | Project path to scope task selection |
+| `taskGroup` | No | Task group to filter available tasks |
+
+## Examples
 
-## Example
+### Accept the next available task
 
 ```bash
-bash config/skills/agent/accept-task/execute.sh '{"sessionName":"dev-1"}'
+bash config/skills/agent/core/accept-task/execute.sh '{"sessionName":"dev-1"}'
+```
+
+### Accept within a specific project and task group
+
+```bash
+bash config/skills/agent/core/accept-task/execute.sh '{"sessionName":"dev-1","projectPath":"/path/to/project","taskGroup":"frontend"}'
 ```
 
 ## Output
 
-JSON with the assigned task details including path, description, and priority. Returns an empty result if no tasks are available.
+JSON object with the assigned task details including task ID, description, priority, and status. Returns an empty result if no tasks are available.
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Missing required parameter: sessionName` | `sessionName` not provided | Include `sessionName` in the JSON input |
+| `curl failed with exit code N` | Backend not running | Start the Crewly backend |
+| Empty result | No unassigned tasks in queue | Wait and retry, or create new tasks |
+
+## Related Skills
+
+- `read-task` — view details of a specific task without accepting it
+- `complete-task` — mark an accepted task as done
+- `report-progress` — update progress on the current task
+- `get-my-tasks` — list all tasks assigned to the agent

package/config/skills/agent/core/poll-tasks/execute.sh

@@ -64,6 +64,15 @@ fi
 
 # ---------------------------------------------------------------------------
 # Step 1: Query available WorkItems from Task Pool
+#
+# Primary query: owner=agent (normal task-pool queue).
+# Fallback query: target=$SESSION_NAME — picks up orchestrator/TL-owned
+# WorkItems delegated directly to this agent. Without the fallback,
+# direct delegations would never be seen by poll-tasks because they
+# do not match owner=agent. (D8 defect: previously the target= query
+# only fired on HTTP error from the primary, not on count=0, so direct
+# delegations sat in the pool indefinitely while the agent reported
+# "no work".)
 # ---------------------------------------------------------------------------
 
 QUERY_PARAMS="?types=${TYPES}&owner=agent"
@@ -77,6 +86,22 @@ AVAILABLE_RESPONSE=$(api_call GET "/task-pool${QUERY_PARAMS}" 2>&1) || {
 
 AVAILABLE_COUNT=$(printf '%s' "$AVAILABLE_RESPONSE" | jq -r '.count // 0')
 
+# When the primary owner=agent query yields no items, also probe the
+# target= namespace before declaring no work. If the fallback returns
+# items, they are by definition pinned to this agent — record the first
+# item's id so Step 3 can claim it explicitly (the server-side FIFO
+# picker filters owner=agent and would otherwise ignore these items).
+TARGET_PINNED_ID=""
+if [ "$AVAILABLE_COUNT" -eq 0 ]; then
+  TARGET_RESPONSE=$(api_call GET "/task-pool?types=${TYPES}&target=${SESSION_NAME}" 2>&1) || TARGET_RESPONSE=""
+  TARGET_COUNT=$(printf '%s' "$TARGET_RESPONSE" | jq -r '.count // 0' 2>/dev/null || echo 0)
+  if [ "$TARGET_COUNT" -gt 0 ]; then
+    AVAILABLE_RESPONSE="$TARGET_RESPONSE"
+    AVAILABLE_COUNT="$TARGET_COUNT"
+    TARGET_PINNED_ID=$(printf '%s' "$TARGET_RESPONSE" | jq -r '(.data // [])[0].id // empty')
+  fi
+fi
+
 if [ "$AVAILABLE_COUNT" -eq 0 ]; then
   # No available work — return early
   jq -n \
@@ -123,15 +148,25 @@ fi
 # We pass our agentId and filters so the server picks the best match.
 # ---------------------------------------------------------------------------
 
-CLAIM_BODY=$(jq -n \
-  --arg agentId "$SESSION_NAME" \
-  --arg types "$TYPES" \
-  '{
-    agentId: $agentId,
-    filters: {
-      types: ($types | split(","))
-    }
-  }')
+# When a target-pinned item was found via the fallback query, claim it
+# by explicit workItemId — the server-side FIFO picker filters owner=agent
+# and would not return orchestrator-owned items via the unfiltered claim.
+if [ -n "$TARGET_PINNED_ID" ]; then
+  CLAIM_BODY=$(jq -n \
+    --arg agentId "$SESSION_NAME" \
+    --arg workItemId "$TARGET_PINNED_ID" \
+    '{agentId: $agentId, workItemId: $workItemId}')
+else
+  CLAIM_BODY=$(jq -n \
+    --arg agentId "$SESSION_NAME" \
+    --arg types "$TYPES" \
+    '{
+      agentId: $agentId,
+      filters: {
+        types: ($types | split(","))
+      }
+    }')
+fi
 
 CLAIM_RESPONSE=$(api_call POST "/task-pool/claim" "$CLAIM_BODY" 2>&1) || {
   CLAIM_ERROR="$CLAIM_RESPONSE"

package/config/skills/agent/core/poll-tasks/execute.test.sh

@@ -199,6 +199,104 @@ else
 fi
 assert_eq "empty types uses role default" "delegate,project_task,review" "$FINAL_TYPES2"
 
+# ---------------------------------------------------------------------------
+# Test 7: D8 fallback — target= query when owner=agent yields zero
+#
+# Mirrors the production logic: when the primary owner=agent response has
+# count=0, we should adopt the target= response if it contains any items,
+# and record the first item's id as TARGET_PINNED_ID so the claim step
+# can claim by workItemId rather than by FIFO filters.
+# ---------------------------------------------------------------------------
+echo "Test 7: D8 fallback for orchestrator-owned target items"
+
+OWNER_AGENT_EMPTY='{"success":true,"data":[],"count":0}'
+TARGET_RESPONSE_HIT='{"success":true,"data":[
+  {"id":"wi-orc-1","type":"delegate","owner":"orchestrator","target":"agent-1","status":"queued"},
+  {"id":"wi-orc-2","type":"delegate","owner":"orchestrator","target":"agent-1","status":"queued"}
+],"count":2}'
+
+# Simulate the merge step
+AVAILABLE_RESPONSE_SIM="$OWNER_AGENT_EMPTY"
+AVAILABLE_COUNT_SIM=$(printf '%s' "$AVAILABLE_RESPONSE_SIM" | jq -r '.count // 0')
+TARGET_PINNED_ID_SIM=""
+if [ "$AVAILABLE_COUNT_SIM" -eq 0 ]; then
+  TARGET_RESPONSE_SIM="$TARGET_RESPONSE_HIT"
+  TARGET_COUNT_SIM=$(printf '%s' "$TARGET_RESPONSE_SIM" | jq -r '.count // 0')
+  if [ "$TARGET_COUNT_SIM" -gt 0 ]; then
+    AVAILABLE_RESPONSE_SIM="$TARGET_RESPONSE_SIM"
+    AVAILABLE_COUNT_SIM="$TARGET_COUNT_SIM"
+    TARGET_PINNED_ID_SIM=$(printf '%s' "$TARGET_RESPONSE_SIM" | jq -r '(.data // [])[0].id // empty')
+  fi
+fi
+
+assert_eq "fallback adopts target response count" "2" "$AVAILABLE_COUNT_SIM"
+assert_eq "fallback pins first target item id" "wi-orc-1" "$TARGET_PINNED_ID_SIM"
+
+# When BOTH queries are empty, AVAILABLE_COUNT stays 0 and no pin is set
+AVAILABLE_RESPONSE_EMPTY="$OWNER_AGENT_EMPTY"
+AVAILABLE_COUNT_EMPTY=$(printf '%s' "$AVAILABLE_RESPONSE_EMPTY" | jq -r '.count // 0')
+TARGET_PINNED_ID_EMPTY=""
+if [ "$AVAILABLE_COUNT_EMPTY" -eq 0 ]; then
+  TARGET_RESPONSE_EMPTY='{"success":true,"data":[],"count":0}'
+  TARGET_COUNT_EMPTY=$(printf '%s' "$TARGET_RESPONSE_EMPTY" | jq -r '.count // 0')
+  if [ "$TARGET_COUNT_EMPTY" -gt 0 ]; then
+    AVAILABLE_RESPONSE_EMPTY="$TARGET_RESPONSE_EMPTY"
+    AVAILABLE_COUNT_EMPTY="$TARGET_COUNT_EMPTY"
+    TARGET_PINNED_ID_EMPTY=$(printf '%s' "$TARGET_RESPONSE_EMPTY" | jq -r '(.data // [])[0].id // empty')
+  fi
+fi
+assert_eq "both-empty leaves count at 0" "0" "$AVAILABLE_COUNT_EMPTY"
+assert_eq "both-empty leaves pin empty" "" "$TARGET_PINNED_ID_EMPTY"
+
+# When owner=agent has items already, fallback must NOT fire
+OWNER_AGENT_HIT='{"success":true,"data":[
+  {"id":"wi-agent-1","type":"project_task","owner":"agent","status":"queued"}
+],"count":1}'
+AVAILABLE_RESPONSE_PRI="$OWNER_AGENT_HIT"
+AVAILABLE_COUNT_PRI=$(printf '%s' "$AVAILABLE_RESPONSE_PRI" | jq -r '.count // 0')
+TARGET_PINNED_ID_PRI=""
+if [ "$AVAILABLE_COUNT_PRI" -eq 0 ]; then
+  TARGET_PINNED_ID_PRI="should-not-be-set"
+fi
+assert_eq "primary-hit keeps count=1" "1" "$AVAILABLE_COUNT_PRI"
+assert_eq "primary-hit leaves pin empty (no fallback)" "" "$TARGET_PINNED_ID_PRI"
+
+# ---------------------------------------------------------------------------
+# Test 8: Claim body shape — workItemId vs filters
+#
+# When TARGET_PINNED_ID is set, the claim body must include workItemId.
+# Otherwise it uses the FIFO filters shape. Both are accepted by the
+# /task-pool/claim endpoint, but only the workItemId form will claim
+# orchestrator-owned items.
+# ---------------------------------------------------------------------------
+echo "Test 8: Claim body shape"
+
+build_claim_body() {
+  local pinned="$1" session="$2" types="$3"
+  if [ -n "$pinned" ]; then
+    jq -nc \
+      --arg agentId "$session" \
+      --arg workItemId "$pinned" \
+      '{agentId: $agentId, workItemId: $workItemId}'
+  else
+    jq -nc \
+      --arg agentId "$session" \
+      --arg types "$types" \
+      '{agentId: $agentId, filters: {types: ($types | split(","))}}'
+  fi
+}
+
+PINNED_BODY=$(build_claim_body "wi-orc-1" "agent-1" "delegate,project_task")
+assert_json_field "pinned body has workItemId" "$PINNED_BODY" ".workItemId" "wi-orc-1"
+assert_json_field "pinned body has agentId" "$PINNED_BODY" ".agentId" "agent-1"
+assert_json_field "pinned body has no filters" "$PINNED_BODY" ".filters" "null"
+
+FIFO_BODY=$(build_claim_body "" "agent-1" "delegate,project_task")
+assert_json_field "fifo body has agentId" "$FIFO_BODY" ".agentId" "agent-1"
+assert_json_field "fifo body has no workItemId" "$FIFO_BODY" ".workItemId" "null"
+assert_json_field "fifo body types[0]" "$FIFO_BODY" ".filters.types[0]" "delegate"
+assert_json_field "fifo body types[1]" "$FIFO_BODY" ".filters.types[1]" "project_task"
+
 # ---------------------------------------------------------------------------
 # Summary
 # ---------------------------------------------------------------------------

package/config/skills/agent/core/record-learning/execute.sh

@@ -1,6 +1,18 @@
 #!/bin/bash
 # Record a learning or insight for team knowledge sharing.
 # Supports CLI flags (preferred) and legacy JSON.
+#
+# Karpathy-lite preflight (ARCHIVIST-V2.f1):
+#   Before persisting, the learning text is checked against the 4 rules of
+#   the Karpathy-lite Entity-Centric format defined in SKILL.md:
+#     1. [[Entity]] opener — HARD reject (always).
+#     2. Sentence count 1..3 — soft warn (HARD with --strict).
+#     3. Linked or sourced — soft warn (HARD with --strict).
+#     4. No log-style "I/We …" opener — soft warn (HARD with --strict).
+#
+# Flags:
+#   --strict           Escalate rules 2..4 to hard rejects (CI / Archivist v2).
+#   --no-preflight     Skip the local preflight (escape hatch).
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "${SCRIPT_DIR}/../../_common/lib.sh"
@@ -10,6 +22,8 @@ AGENT_ID=""
 AGENT_ROLE=""
 PROJECT_PATH=""
 LEARNING=""
+STRICT=0
+SKIP_PREFLIGHT=0
 
 # Detect legacy JSON argument
 if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
@@ -39,12 +53,32 @@ while [[ $# -gt 0 ]]; do
       LEARNING="$(cat "$2")"
       shift 2
       ;;
+    --strict)
+      STRICT=1
+      shift
+      ;;
+    --no-preflight)
+      SKIP_PREFLIGHT=1
+      shift
+      ;;
     --json|-j)
       INPUT_JSON="$2"
       shift 2
       ;;
     --help|-h)
-      echo "Usage: execute.sh --agent dev-1 --role developer --project /path --learning 'What I learned'"
+      cat <<'EOF'
+Usage: execute.sh --agent <id> --role <role> --project <path> --learning '<text>' [--strict] [--no-preflight]
+
+Karpathy-lite preflight rules (see SKILL.md):
+  1. [[Entity]] opener (HARD)
+  2. 1..3 sentences (soft, hard with --strict)
+  3. Linked or sourced (soft, hard with --strict)
+  4. No log-style "I/We" opener (soft, hard with --strict)
+
+Flags:
+  --strict        Escalate rules 2..4 to hard rejects.
+  --no-preflight  Skip local preflight checks (escape hatch).
+EOF
       exit 0
       ;;
     --)
@@ -79,6 +113,10 @@ if [ -n "$INPUT_JSON" ]; then
   [ -z "$AGENT_ROLE" ] && AGENT_ROLE=$(printf '%s' "$INPUT" | jq -r '.agentRole // empty')
   [ -z "$PROJECT_PATH" ] && PROJECT_PATH=$(printf '%s' "$INPUT" | jq -r '.projectPath // empty')
   [ -z "$LEARNING" ] && LEARNING=$(printf '%s' "$INPUT" | jq -r '.learning // empty')
+  if [ "$STRICT" -eq 0 ]; then
+    JSON_STRICT=$(printf '%s' "$INPUT" | jq -r '.strict // empty')
+    [ "$JSON_STRICT" = "true" ] && STRICT=1
+  fi
 fi
 
 require_param "agentId (--agent)" "$AGENT_ID"
@@ -86,13 +124,64 @@ require_param "agentRole (--role)" "$AGENT_ROLE"
 require_param "projectPath (--project)" "$PROJECT_PATH"
 require_param "learning (--learning)" "$LEARNING"
 
+# ---------- Karpathy-lite preflight ----------
+# Local checks for fast feedback. Canonical implementation lives in
+# backend/src/services/memory/learning-format.validator.ts (full Jest tests).
+# This bash mirror covers the most common rules (1 + 4) so agents get immediate
+# stderr feedback without paying an HTTP round-trip.
+if [ "$SKIP_PREFLIGHT" -eq 0 ]; then
+  PREFLIGHT_FAIL=0
+
+  # Rule 1 — [[Entity]] opener (HARD always).
+  TRIMMED_LEARNING="${LEARNING#"${LEARNING%%[![:space:]]*}"}"  # left-trim whitespace
+  if ! [[ "$TRIMMED_LEARNING" =~ ^\[\[[^\]]+\]\] ]]; then
+    SNIPPET="${TRIMMED_LEARNING:0:80}"
+    [ "${#TRIMMED_LEARNING}" -gt 80 ] && SNIPPET="${SNIPPET}…"
+    {
+      echo "✗ record-learning rule 1 (entity_opener): missing leading [[Entity]] opener — required for Archivist v2 join key."
+      echo "  Got:    \"${SNIPPET}\""
+      echo "  Fix:    Lead with [[Entity Name]]. Example: \"[[Fts5IndexService]] FTS5 rank is negative; invert. PR #320\""
+      echo "  See:    config/skills/agent/core/record-learning/SKILL.md § Mandated Format: Karpathy-lite"
+    } >&2
+    PREFLIGHT_FAIL=1
+  fi
+
+  # Rule 4 — log-style "I/We" opener (soft warn; hard with --strict).
+  STRIPPED_LEARNING="${TRIMMED_LEARNING}"
+  if [[ "$STRIPPED_LEARNING" =~ ^\[\[[^\]]+\]\][[:space:]]* ]]; then
+    PREFIX_MATCH="${BASH_REMATCH[0]}"
+    STRIPPED_LEARNING="${STRIPPED_LEARNING#"$PREFIX_MATCH"}"
+  fi
+  if [[ "$STRIPPED_LEARNING" =~ ^[Ii][[:space:]\'] ]] || [[ "$STRIPPED_LEARNING" =~ ^[Ww]e[[:space:]\'] ]]; then
+    {
+      echo "⚠ record-learning rule 4 (no_log_style): log-style opener detected (\"I …\" / \"We …\")."
+      echo "  Fix:    Lead with [[Entity]] then state the insight. Avoid first-person narrative."
+      echo "  See:    config/skills/agent/core/record-learning/SKILL.md § Mandated Format: Karpathy-lite"
+    } >&2
+    if [ "$STRICT" -eq 1 ]; then
+      PREFLIGHT_FAIL=1
+    fi
+  fi
+
+  if [ "$PREFLIGHT_FAIL" -eq 1 ]; then
+    echo "record-learning preflight rejected. Re-run with corrected text, or use --no-preflight to bypass." >&2
+    exit 2
+  fi
+fi
+# ---------- end preflight ----------
+
 # Build body using env vars for safe escaping
 export _LRN_AGENT="$AGENT_ID"
 export _LRN_ROLE="$AGENT_ROLE"
 export _LRN_PROJECT="$PROJECT_PATH"
 export _LRN_CONTENT="$LEARNING"
+export _LRN_STRICT="$STRICT"
 
-BODY=$(jq -n '{agentId: env._LRN_AGENT, agentRole: env._LRN_ROLE, projectPath: env._LRN_PROJECT, learning: env._LRN_CONTENT}')
-unset _LRN_AGENT _LRN_ROLE _LRN_PROJECT _LRN_CONTENT
+if [ "$STRICT" -eq 1 ]; then
+  BODY=$(jq -n '{agentId: env._LRN_AGENT, agentRole: env._LRN_ROLE, projectPath: env._LRN_PROJECT, learning: env._LRN_CONTENT, strict: true}')
+else
+  BODY=$(jq -n '{agentId: env._LRN_AGENT, agentRole: env._LRN_ROLE, projectPath: env._LRN_PROJECT, learning: env._LRN_CONTENT}')
+fi
+unset _LRN_AGENT _LRN_ROLE _LRN_PROJECT _LRN_CONTENT _LRN_STRICT
 
 api_call POST "/memory/record-learning" "$BODY"

package/config/skills/agent/core/register-self/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: Register Self
-description: Register the agent as active with the Crewly backend. Must be called on startup.
+description: "Register the agent as active with the Crewly backend on startup. Use when an agent first launches and needs to join the team and become visible to the orchestrator. For confirming responsiveness after registration, use heartbeat instead."
 version: 1.0.0
 category: system
 skillType: claude-skill
@@ -36,19 +36,62 @@ execution:
 
 # Register Self
 
-Register this agent as active with the Crewly backend. This must be the first skill you run on startup.
+Register the agent as active with the Crewly backend. This must be the first skill run on agent startup to join the team and become visible to the orchestrator.
+
+## When to Use
+
+Run this skill immediately after the agent process starts. Registration makes the agent visible in the team dashboard and enables it to receive tasks, messages, and heartbeat checks. Without registration, the orchestrator cannot assign work to the agent.
 
 ## Parameters
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
-| `role` | Yes | Agent role (e.g., "developer", "qa", "tpm") |
-| `sessionName` | Yes | Your session name (from your identity) |
-| `teamMemberId` | No | Your team member ID |
-| `claudeSessionId` | No | Claude session ID for resume support |
+| `sessionName` / `--session` | Yes | Agent session name (e.g., `dev-1`) |
+| `role` / `--role` | Yes | Agent role: `developer`, `qa`, `tpm`, `designer`, `product-manager`, etc. |
+| `teamMemberId` / `--team-member` | No | Team member UUID for identity linking |
+| `claudeSessionId` / `--claude-session` | No | Claude session ID for resume support |
+
+## Examples
+
+### Register using CLI flags (preferred)
+
+```bash
+bash config/skills/agent/core/register-self/execute.sh --session dev-1 --role developer
+```
+
+### Register with all options
+
+```bash
+bash config/skills/agent/core/register-self/execute.sh --session dev-1 --role qa --team-member tm-abc123 --claude-session cs-xyz789
+```
 
-## Example
+### Register using legacy JSON argument
 
 ```bash
-bash config/skills/agent/core/register-self/execute.sh '{"role":"developer","sessionName":"dev-1"}'
+bash config/skills/agent/core/register-self/execute.sh '{"sessionName":"dev-1","role":"developer"}'
 ```
+
+### Register via stdin pipe
+
+```bash
+echo '{"sessionName":"dev-1","role":"developer"}' | bash config/skills/agent/core/register-self/execute.sh
+```
+
+## Output
+
+JSON confirmation from `POST /api/teams/members/register` containing the registered agent's details including session name, assigned role, and team membership status.
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Missing required parameter: sessionName (--session)` | Session name not provided | Pass `--session <name>` or include `sessionName` in JSON |
+| `Missing required parameter: role (--role)` | Role not provided | Pass `--role <role>` or include `role` in JSON |
+| `Unknown argument: <arg>` | Unrecognized CLI flag | Check spelling; run with `--help` for usage |
+| `curl failed with exit code N` | Backend not running | Start the Crewly backend |
+
+## Related Skills
+
+- `heartbeat` — confirm the agent is still responsive after registration
+- `get-my-context` — retrieve the agent's current role and team context
+- `accept-task` — pick up the first available task after registering

package/config/skills/agent/transcribe-audio/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: transcribe-audio
+description: Transcribe a local audio (or video) file to text with timestamps using Whisper. Defaults to local whisper.cpp (free, offline, word/segment-level timestamps) and automatically falls back to the OpenAI Whisper API (whisper-1) when the local engine is not installed. Any agent can call it for meetings, podcasts, voice notes, interviews, or video audio tracks.
+category: content
+assignableRoles:
+  - "*"
+version: "1.0.0"
+tags:
+  - audio
+  - transcribe
+  - transcription
+  - whisper
+  - whisper.cpp
+  - openai
+  - speech-to-text
+  - timestamps
+---
+
+# Transcribe Audio (Whisper)
+
+Transcribe a **local audio or video file** into text with timestamps. This is the
+general-purpose Whisper-based speech-to-text skill — distinct from
+`xiaoyuzhoufm-transcript` (which is the Gemini-based podcast/video research skill;
+this skill does **not** replace it).
+
+## Engines
+
+| Engine | When used | Cost | Network | Timestamps |
+|--------|-----------|------|---------|------------|
+| **whisper.cpp** (local, `large-v3-turbo`) | Default — used whenever the binary + model are present | Free | Offline | Segment + word-level |
+| **OpenAI Whisper API** (`whisper-1`) | Fallback — used when local is unavailable, or forced via `engine:"openai"` | ~$0.006/min | Required | Segment + word-level |
+
+**Default = `auto`:** prefer local whisper.cpp (free, private, offline, no per-use
+cost — ideal for unattended agents), and transparently fall back to the OpenAI API
+when the local engine is not installed. This gives zero-cost transcription where the
+local model exists and zero-install reliability everywhere else. Force a specific
+engine with `engine:"local"` or `engine:"openai"`.
+
+## Usage
+
+```bash
+# Auto engine (local if available, else OpenAI). Prints JSON to stdout.
+bash execute.sh '{"audioFile":"/path/to/recording.m4a"}'
+
+# Save as Markdown (timestamped transcript)
+bash execute.sh '{"audioFile":"/path/to/recording.mp3","outputFile":"./transcript.md"}'
+
+# Save as JSON (full structured segments)
+bash execute.sh '{"audioFile":"/path/to/recording.wav","outputFile":"./transcript.json"}'
+
+# Language hint (ISO-639-1, e.g. en / zh / ja). Default: auto-detect
+bash execute.sh '{"audioFile":"/path/to/recording.m4a","language":"zh"}'
+
+# Force a specific engine
+bash execute.sh '{"audioFile":"/path/to/x.wav","engine":"local"}'
+bash execute.sh '{"audioFile":"/path/to/x.wav","engine":"openai"}'
+
+# A video file works too — the audio track is extracted automatically
+bash execute.sh '{"audioFile":"/path/to/clip.mp4"}'
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `audioFile` | Yes | Path to a local audio or video file (m4a, mp3, wav, aac, ogg, flac, mp4, mov…) |
+| `outputFile` | No | Save the transcript to this path. `.json` → structured JSON; anything else → Markdown |
+| `language` | No | Language hint (ISO-639-1). Default: auto-detect |
+| `engine` | No | `auto` (default), `local`, or `openai` |
+
+## Output (stdout JSON)
+
+```json
+{
+  "success": true,
+  "engine": "whisper.cpp",
+  "language": "en",
+  "durationSec": 11.0,
+  "text": "Full transcript as one block of text...",
+  "segments": [
+    { "start": 0.0, "end": 2.5, "text": "Hello everyone", "speaker": "Unknown" }
+  ],
+  "segmentCount": 1,
+  "outputFile": "/abs/path/transcript.md"
+}
+```
+
+`speaker` is `"Unknown"` unless the chosen engine returns diarization (neither
+default engine performs speaker separation today; the field is reserved so
+downstream consumers have a stable shape).
+
+## Dependencies & Setup
+
+- **`ffmpeg`** — required for both engines (audio is normalized to 16 kHz mono WAV).
+  Install: `brew install ffmpeg`.
+- **Local engine (`whisper.cpp`)** — needs the `whisper-cli` binary and a model file:
+  - Binary: `brew install whisper-cpp` (provides `whisper-cli`). Override with `FLOPOST_WHISPER_BIN`.
+  - Model: `ggml-large-v3-turbo-q5_0.bin` in `~/.flopost/whisper/` or `~/.cache/whisper-models/`. Override with `FLOPOST_WHISPER_MODEL`.
+  - If the binary or model is missing, the skill falls back to OpenAI (or reports a clear hint when `engine:"local"` is forced).
+- **OpenAI engine** — needs an OpenAI API key. Resolution order:
+  1. `OPENAI_API_KEY` environment variable (injected by Crewly secrets).
+  2. Crewly Settings → API Keys (`GET http://localhost:8787/api/settings` → `data.apiKeys.global.openai`).
+  No key is ever hard-coded.
+
+## Notes
+
+- Engine detection and key resolution lift the proven logic from Flopost
+  (`desktop/server/whisperModule.ts` and `service/lib/video/transcriptionService.ts`).
+- Long files: whisper.cpp handles arbitrary length locally. The OpenAI API enforces a
+  25 MB upload limit; for larger files prefer the local engine.