arkaos 4.31.0 → 4.32.0

package/README.md

@@ -2,7 +2,7 @@
 
 **The Operating System for AI Agent Teams.**
 
-89 agents. 17 departments. 329 skills. Enterprise frameworks. Multi-runtime. One install.
+89 agents. 17 departments. 330 skills. Enterprise frameworks. Multi-runtime. One install.
 
 ```bash
 npx arkaos install

package/THE-ARKAOS-GUIDE.md

@@ -1,6 +1,6 @@
 # The ArkaOS Guide
 
-> v4.31.0 — 89 agents, 17 departments, 329 skills, 297 commands, 16 ADRs.
+> v4.32.0 — 89 agents, 17 departments, 330 skills, 297 commands, 16 ADRs.
 > One file, everything you need to start. Generated by `scripts/guide_gen.py` — never hand-edited.
 
 ## What it is

package/VERSION

@@ -1 +1 @@
-4.31.0
+4.32.0

package/arka/SKILL.md

@@ -47,7 +47,7 @@ complementary, not alternatives.
 # ArkaOS — Main Orchestrator
 
 > **The Operating System for AI Agent Teams**
-> 89 agents. 17 departments. 329 skills. Multi-runtime. Dashboard. Knowledge RAG.
+> 89 agents. 17 departments. 330 skills. Multi-runtime. Dashboard. Knowledge RAG.
 
 ## ⛔ Evidence flow — 4 gates (NON-NEGOTIABLE)
 

package/config/claude-agents/brand-director.md

@@ -1,7 +1,7 @@
 ---
 name: brand-director
 description: >
-  Valentina — Creative Director (brand squad). Executes: brand identity creation, visual design direction, UX/UI strategy, design systems.
+  Valentina — Creative Director (brand squad). Executes: brand identity creation, reference-video visual analysis via dev/watch (complete frames + transcript — motion and art direction judged on evidence, never on screenshots), visual design direction, UX/UI strategy.
 model: sonnet
 ---
 

package/config/claude-agents/content-strategist.md

@@ -1,7 +1,7 @@
 ---
 name: content-strategist
 description: >
-  Rafael — Content Strategist (content squad). Executes: viral content design, hook writing & packaging, script structure, content operating systems.
+  Rafael — Content Strategist (content squad). Executes: viral content design, reference-video analysis via dev/watch (frames + timestamped transcript before judging any video), hook writing & packaging, script structure.
 model: sonnet
 ---
 

package/config/claude-agents/frontend-dev.md

@@ -1,7 +1,7 @@
 ---
 name: frontend-dev
 description: >
-  Diana — Senior Frontend Developer (dev squad). Executes: Vue 3 (Composition API), Nuxt 3, React 19 / Next.js 15, TypeScript.
+  Diana — Senior Frontend Developer (dev squad). Executes: Vue 3 (Composition API), motion-reference analysis via dev/watch (scroll/animation benchmarks from frames + transcript before implementing), Nuxt 3, React 19 / Next.js 15.
 model: opus
 ---
 

package/config/claude-agents/marketing-director.md

@@ -1,7 +1,7 @@
 ---
 name: marketing-director
 description: >
-  Luna — Marketing Director (marketing squad). Executes: growth strategy, content marketing, SEO, paid acquisition.
+  Luna — Marketing Director (marketing squad). Executes: growth strategy, video-ad teardown via dev/watch (hook, pacing and spoken-copy evidence from frames + transcript), content marketing, SEO.
 model: sonnet
 ---
 

package/config/claude-agents/scriptwriter.md

@@ -1,7 +1,7 @@
 ---
 name: scriptwriter
 description: >
-  Joana — Scriptwriter (content squad). Executes: video scriptwriting (YouTube, Reels, TikTok), cinematic narrative for short and long-form, storyboard-ready scene writing (scene/shot/VO/on-screen-text columns), narrative structure (hook-bridge-body-CTA; beat sheets; story circles).
+  Joana — Scriptwriter (content squad). Executes: video scriptwriting (YouTube, Reels, TikTok), reference-video teardown via dev/watch (hook, pacing and beat analysis from frames + transcript), cinematic narrative for short and long-form, storyboard-ready scene writing (scene/shot/VO/on-screen-text columns).
 model: opus
 ---
 

package/config/claude-agents/trends-analyst.md

@@ -1,7 +1,7 @@
 ---
 name: trends-analyst
 description: >
-  Margarida — Trends & Niche Analyst (content squad). Executes: trend detection across platforms (Agent-Reach: X, Reddit, YouTube, RSS, Exa), niche viability scoring (audience size, competition density, monetization path, brand fit), platform algorithm shift monitoring, whitespace analysis for new channels and formats.
+  Margarida — Trends & Niche Analyst (content squad). Executes: trend detection across platforms (Agent-Reach: X, Reddit, YouTube, RSS, Exa), viral-video deconstruction via dev/watch (scene-aware frames + transcript, timestamp-cited), niche viability scoring (audience size, competition density, monetization path, brand fit), platform algorithm shift monitoring.
 model: sonnet
 ---
 

package/config/claude-agents/video-producer.md

@@ -1,7 +1,7 @@
 ---
 name: video-producer
 description: >
-  Simão — Video Producer & Production Lead (content squad). Executes: video production pipelines (script → storyboard → assets → edit → render), Hyperframes video-as-code editing (HTML/CSS/JS + GSAP → MP4), Higgsfield generation orchestration (image, video, audio, motion control, upscale, reframe), shot lists and EDLs (scene/shot/VO/on-screen-text columns).
+  Simão — Video Producer & Production Lead (content squad). Executes: video production pipelines (script → storyboard → assets → edit → render), cut review via dev/watch (frame + transcript evidence on own renders before the Quality Gate), Hyperframes video-as-code editing (HTML/CSS/JS + GSAP → MP4), Higgsfield generation orchestration (image, video, audio, motion control, upscale, reframe).
 model: opus
 ---
 

package/config/skills-curated.yaml

@@ -24,7 +24,8 @@ curated_subskills:
   community: [moderation]
   content: [calendar, hook-write]
   dev: [api-design, architecture-design, clean-code-review, code-review,
-        db-design, refactor-plan, runbook, security-audit, spec, tdd-cycle]
+        db-design, refactor-plan, runbook, security-audit, spec, tdd-cycle,
+        watch]
   ecom: [cart-recovery, store-audit]
   finance: [financial-model, unit-economics]
   kb: [search-kb, zettelkasten-process]

package/config/skills-provenance.yaml

@@ -91,6 +91,12 @@ derived:
     origin: community
     source: https://github.com/nutlope/hallmark
     license: MIT
+  # Watch absorption campaign — video-input primitive derived from
+  # bradautomates/claude-video v0.2.0 (MIT), maintained natively.
+  departments/dev/skills/watch:
+    origin: community
+    source: https://github.com/bradautomates/claude-video
+    license: MIT
   # Marketing skills integration campaign — derived from
   # coreyhaines31/marketingskills (MIT). Frontmatter metadata must match
   # each entry field-for-field (test_registry_matches_frontmatter_field_for_field).

package/core/keys.py

@@ -7,15 +7,27 @@ import json
 import os
 import stat
 from pathlib import Path
-from typing import Optional
 
 KEYS_PATH = Path.home() / ".arkaos" / "keys.json"
 
 # Known providers with descriptions
 PROVIDERS = {
-    "OPENAI_API_KEY": {"name": "OpenAI", "used_for": "Whisper transcription, embeddings, GPT"},
-    "GOOGLE_API_KEY": {"name": "Google", "used_for": "Gemini API, Nano Banana, Google Cloud AI"},
-    "FAL_API_KEY": {"name": "fal.ai", "used_for": "Image generation, video generation"},
+    "OPENAI_API_KEY": {
+        "name": "OpenAI",
+        "used_for": "Whisper transcription (/watch fallback), embeddings, GPT",
+    },
+    "GOOGLE_API_KEY": {
+        "name": "Google",
+        "used_for": "Gemini API, Nano Banana, Google Cloud AI",
+    },
+    "FAL_API_KEY": {
+        "name": "fal.ai",
+        "used_for": "Image generation, video generation",
+    },
+    "GROQ_API_KEY": {
+        "name": "Groq",
+        "used_for": "Whisper transcription for /watch (whisper-large-v3 — cheaper, faster)",
+    },
 }
 
 
@@ -31,7 +43,7 @@ def _save(keys: dict[str, str]) -> None:
     os.chmod(KEYS_PATH, stat.S_IRUSR | stat.S_IWUSR)  # 600
 
 
-def get_key(name: str) -> Optional[str]:
+def get_key(name: str) -> str | None:
     """Get an API key by name. Also checks environment variables."""
     env_val = os.environ.get(name)
     if env_val:

package/departments/brand/agents/brand-director.yaml

@@ -52,6 +52,7 @@ authority:
 expertise:
   domains:
     - brand identity creation
+    - reference-video visual analysis via dev/watch (complete frames + transcript — motion and art direction judged on evidence, never on screenshots)
     - visual design direction
     - UX/UI strategy
     - design systems

package/departments/content/agents/content-strategist.yaml

@@ -48,6 +48,7 @@ authority:
 expertise:
   domains:
     - viral content design
+    - reference-video analysis via dev/watch (frames + timestamped transcript before judging any video)
     - hook writing & packaging
     - script structure
     - content operating systems

package/departments/content/agents/production/trends-analyst.yaml

@@ -45,6 +45,7 @@ authority:
 expertise:
   domains:
     - "trend detection across platforms (Agent-Reach: X, Reddit, YouTube, RSS, Exa)"
+    - viral-video deconstruction via dev/watch (scene-aware frames + transcript, timestamp-cited)
     - niche viability scoring (audience size, competition density, monetization path, brand fit)
     - platform algorithm shift monitoring
     - whitespace analysis for new channels and formats

package/departments/content/agents/production/video-producer.yaml

@@ -51,6 +51,7 @@ authority:
 expertise:
   domains:
     - video production pipelines (script → storyboard → assets → edit → render)
+    - cut review via dev/watch (frame + transcript evidence on own renders before the Quality Gate)
     - Hyperframes video-as-code editing (HTML/CSS/JS + GSAP → MP4)
     - Higgsfield generation orchestration (image, video, audio, motion control, upscale, reframe)
     - shot lists and EDLs (scene/shot/VO/on-screen-text columns)

package/departments/content/agents/scriptwriter.yaml

@@ -43,6 +43,7 @@ authority:
 expertise:
   domains:
     - video scriptwriting (YouTube, Reels, TikTok)
+    - reference-video teardown via dev/watch (hook, pacing and beat analysis from frames + transcript)
     - cinematic narrative for short and long-form
     - storyboard-ready scene writing (scene/shot/VO/on-screen-text columns)
     - narrative structure (hook-bridge-body-CTA; beat sheets; story circles)

package/departments/dev/agents/frontend-dev.yaml

@@ -47,6 +47,7 @@ authority:
 expertise:
   domains:
     - Vue 3 (Composition API)
+    - motion-reference analysis via dev/watch (scroll/animation benchmarks from frames + transcript before implementing)
     - Nuxt 3
     - React 19 / Next.js 15
     - TypeScript

package/departments/dev/skills/animated-website/SKILL.md

@@ -76,7 +76,20 @@ If the user gives just a video path and a vague concept, ask ONE clarifying ques
 
 ### Step 1: Analyze the Video
 
-Probe the video to understand what you're working with:
+**See the content first (dev/watch primitive).** Before any design decision,
+watch the source with the native `dev/watch` skill so overlay copy, section
+pacing and dwell points are grounded in what is actually on screen — the
+"complete frames" doctrine, never screenshots or guesses:
+
+```bash
+PY="$HOME/.arkaos/bin/arka-py"; command -v "$PY" >/dev/null || PY=python3
+"$PY" ~/.claude/skills/arka-watch/scripts/watch.py "/path/to/video.mp4" --no-whisper
+```
+
+Read every frame the report lists, note the key visual beats (`t=MM:SS`) —
+they become section boundaries and dwell points in Step 4.
+
+Then probe the technical metadata:
 
 ```bash
 ffprobe -v quiet -print_format json -show_format -show_streams "/path/to/video.mp4"

package/departments/dev/skills/watch/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: dev/watch
+description: >
+  Watch a video (URL or local file) so the agent can answer questions about
+  what is on screen and what is said. Downloads with yt-dlp, extracts
+  auto-scaled frames with ffmpeg (scene-aware or fast keyframes, near-duplicate
+  dedup), pulls a timestamped transcript (native captions first, Whisper API
+  fallback), and prints frame paths for the agent to Read. TRIGGER: a video
+  URL (YouTube, Loom, TikTok, X, Vimeo…) or local video file plus a question;
+  "vê este vídeo", "analisa este vídeo", "watch this video", "o que acontece
+  em/aos X min", reference-video analysis before design work, video deliverable
+  review in the Quality Gate, screen-recording bug reports, "/dev watch".
+  SKIP: video PRODUCTION or generation -> content/video-produce or Higgsfield;
+  turning a video into a scroll site -> dev/animated-website (it calls this
+  skill for its analysis phase); audio-only transcription of a podcast with no
+  visual questions -> run --detail transcript and summarize.
+allowed-tools: [Read, Bash, AskUserQuestion]
+metadata:
+  origin: community
+  source: https://github.com/bradautomates/claude-video
+  license: MIT
+---
+
+<!-- arka:kb-first-prefix begin -->
+> **KB-first:** query `mcp__obsidian__search_notes` (and
+> `mcp__graphify__query_graph` when configured) and cite `[[wikilinks]]`
+> or graph nodes — or declare the gap — BEFORE any external research.
+> Full doctrine: `arka/SKILL.md` (KB-First Research).
+<!-- arka:kb-first-prefix end -->
+
+# /watch — video input for ArkaOS agents
+
+You don't have a video input; this skill gives you one. A bundled Python
+pipeline gets captions first, downloads only what it needs, extracts frames
+as JPEGs, produces a timestamped transcript, and prints frame paths. You then
+`Read` each frame to see the video and answer grounded in evidence — the way
+the "frames COMPLETOS" doctrine requires for reference-video analysis.
+
+Absorbed from `bradautomates/claude-video` v0.2.0 (MIT) and maintained
+natively by ArkaOS. ArkaOS-specific behavior: config lives in
+`~/.arkaos/watch.env`, API keys resolve from `/arka keys`
+(`~/.arkaos/keys.json`) before any .env file, and every run appends a usage
+record to `~/.arkaos/telemetry/watch-usage.jsonl` (frames + estimated image
+tokens) so CostGovernor sees video analysis cost.
+
+## Resolve `SKILL_DIR` (before any command)
+
+Set `SKILL_DIR` to the absolute path of the directory containing THIS
+SKILL.md (your harness showed it when you Read this file). The scripts are at
+`SKILL_DIR/scripts/`. Guard once:
+
+```bash
+[ -f "$SKILL_DIR/scripts/watch.py" ] || { echo "watch.py not under $SKILL_DIR" >&2; exit 1; }
+```
+
+Run scripts with the canonical ArkaOS interpreter when present, else python3:
+
+```bash
+PY="$HOME/.arkaos/bin/arka-py"; command -v "$PY" >/dev/null || PY=python3
+```
+
+## Step 0 — preflight (silent on success)
+
+```bash
+"$PY" "${SKILL_DIR}/scripts/setup.py" --check
+```
+
+Exit 0 → proceed without comment (keyless-after-setup counts as ready — do
+NOT announce that setup is complete). Non-zero:
+
+| Exit | Meaning | Action |
+|------|---------|--------|
+| 2 | ffmpeg / ffprobe / yt-dlp missing or broken (a binary that dies at load counts as missing) | run `"$PY" "${SKILL_DIR}/scripts/setup.py"` — auto-installs via brew on macOS, prints commands elsewhere |
+| 3 | genuine first run, no Whisper key | encourage a key (see Keys); user may decline → proceed with `--no-whisper` |
+| 4 | both | installer, then key |
+
+`--json` gives the structured status (`status`, `can_proceed`, `first_run`,
+`missing_binaries`, `whisper_backend`, `watch_detail`, `config_file`).
+First-run flow: install binaries first, let the installer scaffold
+`~/.arkaos/watch.env`, then ask the detail preference below.
+
+**Keys (Whisper fallback):** preferred home is `/arka keys` —
+`OPENAI_API_KEY` (whisper-1) or `GROQ_API_KEY` (whisper-large-v3, cheaper —
+preferred when both exist). Resolution order: environment →
+`~/.arkaos/keys.json` → `~/.arkaos/watch.env` → `./.env`. A missing key is
+encouraged, never a blocker: captions cover most public videos free.
+
+**First-run detail preference:** ask once via `AskUserQuestion` (order
+lightest→heaviest, keep "(recommended)" on balanced): `transcript` (no
+frames) · `efficient` (keyframes, cap 50) · `balanced` (recommended —
+scene-aware, cap 100) · `token-burner` (uncapped). Write the bare
+`WATCH_DETAIL=<value>` line (no inline comment) into `~/.arkaos/watch.env`,
+then `SETUP_COMPLETE=true`.
+
+## Invoke
+
+```bash
+"$PY" "${SKILL_DIR}/scripts/watch.py" "<url-or-path>"
+```
+
+Flags: `--detail transcript|efficient|balanced|token-burner` ·
+`--start T` / `--end T` (SS, MM:SS, HH:MM:SS — focused mode, denser fps) ·
+`--timestamps T1,T2,…` (pin frames at transcript-flagged moments) ·
+`--max-frames N` · `--resolution W` (default 512; 1024 only to read on-screen
+text — ~4× image tokens) · `--fps F` (≤2) · `--out-dir DIR` ·
+`--whisper groq|openai` · `--no-whisper` · `--no-dedup`.
+
+Then: **Read every frame path the report lists, in one parallel batch.**
+Frames carry `t=MM:SS` absolute timestamps aligned with the transcript.
+Answer citing timestamps; with no question, summarize structure, key moments,
+and spoken content. At `transcript` detail, still synthesize a summary — never
+paste the raw transcript.
+
+Cleanup: the report prints the work dir — `rm -rf` it unless follow-ups are
+likely. Follow-ups reuse what is already in context; do NOT re-run.
+
+## Frame budget discipline
+
+Cost is dominated by frames (~197 image tokens each at 512px). Full-video
+budgets by duration: ≤30s ~30 · ≤1min ~40 · ≤3min ~60 · ≤10min ~80 · >10min
+sparse (warning printed). When the user names a moment or the video exceeds
+~10 minutes, prefer focused mode (`--start`/`--end` — up to 2 fps) over a
+sparse full scan. Dedup collapses held slides and static recordings before
+the cap so the budget buys distinct content.
+
+**Transcript-cue frames:** scene selection misses deictic moments ("look
+here", "as you can see") because pointing is low visual change. Read the
+transcript, judge which cues matter (ignore rhetorical "look…"), re-run with
+`--timestamps 4:32,7:10` pointed at the downloaded file in the work dir.
+
+## KB write-back (summaries become notes)
+
+When the user asks to keep the analysis ("summarize this to a note",
+"guarda isto na KB") — or when the analysis is reference research worth
+keeping (competitor teardown, course/talk notes) — write the summary to the
+Obsidian vault via `mcp__obsidian__write_note`: YAML frontmatter (`type:
+video-analysis`, source URL, duration, transcript source), key moments as a
+timestamped list, and `[[wikilinks]]` to related notes. One note per video;
+a playlist becomes a set of notes plus a MOC. Ask before writing when the
+user did not request persistence.
+
+## Failure modes
+
+- Download fails (login/region-locked) → tell the user plainly; don't retry.
+- No captions AND no key → frames-only, say so, offer `/arka keys`.
+- Whisper chunk failures → transcript is partial; noted on stderr; retry with
+  the other backend if needed.
+- Long-video warning → acknowledge it and offer a focused re-run.
+- Client-confidential recordings → run `--no-whisper` (audio must not leave
+  the machine; only extracted audio ever goes to a Whisper API, and only
+  when captions are missing).
+
+## Security
+
+Local-only except: extracted mono audio → `api.groq.com` /
+`api.openai.com`, only on Whisper fallback. yt-dlp requests public data; no
+accounts, no cookies. Keys are never logged or echoed. Working files stay in
+the work dir; config/keys in `~/.arkaos/` (0600).
+
+Scripts: `watch.py` (entry) · `download.py` (yt-dlp) · `frames.py` (ffmpeg +
+dedup) · `transcribe.py` (captions) · `whisper.py` (Groq/OpenAI clients) ·
+`setup.py` (preflight/installer) · `config.py` (paths, keys, telemetry).

package/departments/dev/skills/watch/references/claude-video.LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bradley Bonanno
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/departments/dev/skills/watch/scripts/config.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""Shared /watch configuration helpers (ArkaOS-native).
+
+Every filesystem anchor resolves at CALL time, never import time, so a
+redirected HOME (tests, sandboxes) always takes effect. Key resolution
+order: environment -> ~/.arkaos/keys.json (managed by `/arka keys`) ->
+~/.arkaos/watch.env -> ./.env.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+DEFAULT_DETAIL = "balanced"
+
+DETAILS = {"transcript", "efficient", "balanced", "token-burner"}
+
+
+def arkaos_home() -> Path:
+    """User-data root — ~/.arkaos, or ARKAOS_HOME when set."""
+    override = os.environ.get("ARKAOS_HOME")
+    if override:
+        return Path(override).expanduser()
+    return Path.home() / ".arkaos"
+
+
+def config_file() -> Path:
+    return arkaos_home() / "watch.env"
+
+
+def keys_file() -> Path:
+    return arkaos_home() / "keys.json"
+
+
+def telemetry_file() -> Path:
+    return arkaos_home() / "telemetry" / "watch-usage.jsonl"
+
+
+def read_env_file(path: Path | None = None) -> dict[str, str]:
+    if path is None:
+        path = config_file()
+    values: dict[str, str] = {}
+    if not path.exists():
+        return values
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return values
+    for line in lines:
+        raw = line.strip()
+        if not raw or raw.startswith("#") or "=" not in raw:
+            continue
+        key, _, value = raw.partition("=")
+        value = value.strip()
+        if len(value) >= 2 and value[0] in ('"', "'") and value[-1] == value[0]:
+            value = value[1:-1]
+        else:
+            # Strip an inline comment (a '#' preceded by whitespace) from an
+            # unquoted value. Without this, `WATCH_DETAIL=balanced  # note`
+            # parses as "balanced  # note", fails validation, and silently
+            # falls back to the default. Keeps '#' inside quotes / API keys.
+            for i, ch in enumerate(value):
+                if ch == "#" and i > 0 and value[i - 1] in " \t":
+                    value = value[:i].rstrip()
+                    break
+        values[key.strip()] = value
+    return values
+
+
+def read_keys_json() -> dict[str, str]:
+    """API keys stored by `/arka keys` (~/.arkaos/keys.json). Fail-open."""
+    path = keys_file()
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    return {str(k): str(v) for k, v in data.items() if v}
+
+
+def resolve_api_key(name: str) -> str | None:
+    """env -> ~/.arkaos/keys.json -> ~/.arkaos/watch.env -> ./.env."""
+    value = os.environ.get(name)
+    if value and value.strip():
+        return value.strip()
+    value = read_keys_json().get(name)
+    if value and value.strip():
+        return value.strip()
+    for path in (config_file(), Path.cwd() / ".env"):
+        value = read_env_file(path).get(name)
+        if value and value.strip():
+            return value.strip()
+    return None
+
+
+def get_config() -> dict[str, object]:
+    file_values = read_env_file()
+
+    detail = (
+        os.environ.get("WATCH_DETAIL")
+        or file_values.get("WATCH_DETAIL")
+        or DEFAULT_DETAIL
+    )
+    if detail not in DETAILS:
+        detail = DEFAULT_DETAIL
+
+    return {
+        "detail": detail,
+        "config_file": str(config_file()),
+    }
+
+
+def frame_cap(detail: str) -> int | None:
+    if detail == "efficient":
+        return 50
+    if detail == "balanced":
+        return 100
+    if detail == "token-burner":
+        return None
+    if detail == "transcript":
+        return None
+    return 100
+
+
+def record_telemetry(event: dict) -> None:
+    """Append one usage record to ~/.arkaos/telemetry/watch-usage.jsonl.
+
+    Observability must never break a watch run: filesystem failures
+    (OSError) are reported to stderr and swallowed (fail-open). Callers
+    pass only JSON-serializable scalars, so serialization cannot raise.
+    """
+    try:
+        path = telemetry_file()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        record = {"ts": round(time.time(), 3), **event}
+        with path.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(record, ensure_ascii=False) + "\n")
+    except OSError as exc:
+        print(f"[watch] telemetry write skipped: {exc}", file=sys.stderr)