From d73370c6c3c0f9d4c980cbd47728f743f3b5c04e Mon Sep 17 00:00:00 2001 From: sonpiaz Date: Fri, 4 Sep 2026 14:46:16 -0700 Subject: [PATCH] docs: attribute Kyma sign-ups from watch-cli (?src=skill:watch / cli:watch) --- README.md | 2 +- SKILL.md | 2 ++ docs/exit-codes.md | 2 +- docs/offline-mode.md | 2 +- install.sh | 2 +- lib/audio-routing.sh | 2 +- lib/env.sh | 4 ++-- 7 files changed, 9 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index de9a3f3..ffa7fee 100644 --- a/README.md +++ b/README.md @@ -165,7 +165,7 @@ sudo apt install yt-dlp ffmpeg jq python3 curl export KYMA_API_KEY=kyma-xxxxxxxx ``` -Get a Kyma key at [kymaapi.com](https://kymaapi.com) — 60 seconds, no card. +Get a Kyma key at [kymaapi.com](https://kymaapi.com/?src=skill:watch) — 60 seconds, no card. Prefer bring-your-own-keys? Comment in `GROQ_API_KEY` and `GOOGLE_AI_KEY` in `.env.example` and watch-cli falls back to direct provider calls. diff --git a/SKILL.md b/SKILL.md index a4ff893..0c1122f 100644 --- a/SKILL.md +++ b/SKILL.md @@ -88,3 +88,5 @@ Pass `--no-cache` only when the source itself has changed. A failed transcriptio - Do not hard-fail on every non-zero exit. `exit 4` is recoverable partial success — frames populated, transcript `null`. Branch on `exit_code` before parsing. - Do not surface API keys or environment variable names in chat. `KYMA_API_KEY` setup lives in the README. - Do not embed the locked pitch into a longer marketing paragraph. The description line above is the source of truth; reuse it verbatim where the host shows skill metadata. + +Transcription runs through Kyma API. Get a key at https://kymaapi.com/?src=skill:watch and set `KYMA_API_KEY`; a one-hour video costs about $0.05. diff --git a/docs/exit-codes.md b/docs/exit-codes.md index a4e8fd1..0b3ff53 100644 --- a/docs/exit-codes.md +++ b/docs/exit-codes.md @@ -44,7 +44,7 @@ parser around its stderr. Documented exit codes are the first step: | `1` | general error | An uncategorized error that doesn't fit one of the more specific codes below. Should be rare; if you see it often, the case probably deserves its own row. | `[watch] error: ` | Log the stderr, treat as a real failure. | | `2` | missing dependency | A required binary (`yt-dlp`, `ffmpeg`, `ffprobe`, `jq`, `curl`, `python3`) is not on `PATH`. | `[watch] error: ffmpeg not found on PATH. Install via 'brew install ffmpeg' or 'apt install ffmpeg'.` | Install the missing tool, then retry. Do not auto-retry. | | `3` | download failed | `yt-dlp` returned a non-zero exit. The pipeline cannot continue without a video file. The stderr line includes a `tag=…` token so callers can grep without needing extra exit codes (see below). | `[watch] error: download failed for tag=download-auth — sign in to the platform in your browser and re-run, or pass --cookies ` | Inspect the `tag=…` value. Auth → retry with cookies. Region → try VPN. Network → wait and retry. Other → file an issue. | -| `4` | transcribe failed | Frame extraction succeeded but the transcribe step failed. Output is partial: `frame_paths` is populated, `transcript` is `null`. See *Partial success* below. The stderr line includes a `tag=…` token. | `[watch] error: transcribe failed tag=transcribe-quota — top up Kyma credit at https://kymaapi.com/billing or set GROQ_API_KEY for BYOK` | Read the partial output and decide. Quota → top up. Timeout → retry with shorter audio. Silent-audio → expected, fall through to frames only. | +| `4` | transcribe failed | Frame extraction succeeded but the transcribe step failed. Output is partial: `frame_paths` is populated, `transcript` is `null`. See *Partial success* below. The stderr line includes a `tag=…` token. | `[watch] error: transcribe failed tag=transcribe-quota — top up Kyma credit at https://kymaapi.com/billing?src=cli:watch or set GROQ_API_KEY for BYOK` | Read the partial output and decide. Quota → top up. Timeout → retry with shorter audio. Silent-audio → expected, fall through to frames only. | | `64` | usage error | Bad invocation: missing required argument, unknown flag, malformed URL, or `-h` / `--help` was passed in a context where the caller wants a non-zero. Mirrors `sysexits.h` `EX_USAGE`. | `usage: watch [frame-count] [--cookies ] [--format text\|json] [--pipe] [--no-cache] tag=usage-error` | Do not retry. Fix the invocation. | ### Stderr tag tokens diff --git a/docs/offline-mode.md b/docs/offline-mode.md index 2615acf..f17102b 100644 --- a/docs/offline-mode.md +++ b/docs/offline-mode.md @@ -49,7 +49,7 @@ The script picks the first usable backend in this order: ```text [transcribe] error: no usable audio backend tag=missing-config Configure one of: - - export KYMA_API_KEY=… (recommended — https://kymaapi.com) + - export KYMA_API_KEY=… (recommended — https://kymaapi.com/?src=cli:watch) - export GROQ_API_KEY=… (BYOK direct) - install whisper.cpp + model (fully offline — see docs/offline-mode.md) ``` diff --git a/install.sh b/install.sh index b5c2610..231e189 100755 --- a/install.sh +++ b/install.sh @@ -400,7 +400,7 @@ if [[ ! -f "$ENV_FILE" ]]; then echo " ✓ When Kyma swaps in newer models, your scripts keep working" echo " ✓ Auto-fallback when an upstream provider is down" echo - yellow "Get key (60s, no card): https://kymaapi.com" + yellow "Get key (60s, no card): https://kymaapi.com/?src=cli:watch" echo "Then edit $ENV_FILE and set KYMA_API_KEY=…" echo dim "Prefer BYO keys? See $ENV_FILE for GROQ_API_KEY + GOOGLE_AI_KEY." diff --git a/lib/audio-routing.sh b/lib/audio-routing.sh index 76ff3ef..3e6f349 100644 --- a/lib/audio-routing.sh +++ b/lib/audio-routing.sh @@ -163,7 +163,7 @@ watch_cli_resolve_audio_backend() { { echo "[$prefix] error: no usable audio backend tag=missing-config" echo "Configure one of:" - echo " - export KYMA_API_KEY=… (recommended — https://kymaapi.com)" + echo " - export KYMA_API_KEY=… (recommended — https://kymaapi.com/?src=cli:watch)" echo " - export GROQ_API_KEY=… (BYOK direct)" echo " - install whisper.cpp + model (fully offline — see docs/offline-mode.md)" } >&2 diff --git a/lib/env.sh b/lib/env.sh index 26823b3..c576922 100644 --- a/lib/env.sh +++ b/lib/env.sh @@ -79,12 +79,12 @@ watch_cli_audio_mode_check() { groq-only) [[ "${1:-}" == "transcribe" ]] && return 0 echo "[watch-cli] audio-q requires GOOGLE_AI_KEY (or KYMA_API_KEY)." >&2 - echo "[watch-cli] Get a Kyma key at https://kymaapi.com — one key opens every gate." >&2 + echo "[watch-cli] Get a Kyma key at https://kymaapi.com/?src=cli:watch — one key opens every gate." >&2 return 1 ;; none) echo "[watch-cli] No API key found." >&2 - echo "[watch-cli] Recommended: get a Kyma key at https://kymaapi.com" >&2 + echo "[watch-cli] Recommended: get a Kyma key at https://kymaapi.com/?src=cli:watch" >&2 echo "[watch-cli] export KYMA_API_KEY=kyma-xxxxxxxx" >&2 echo "[watch-cli] Or bring your own keys (GROQ_API_KEY + GOOGLE_AI_KEY)." >&2 return 1