arkaos 4.30.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.30.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.30.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/governance/evidence_checks.py

@@ -42,7 +42,7 @@ TIMEOUT_SECONDS = 300
 COVERAGE_THRESHOLD = 80.0
 ALL_CHECKS: tuple[str, ...] = (
     "lint", "typecheck", "tests", "coverage", "security-grep", "spellcheck",
-    "ui-screenshot",
+    "ui-screenshot", "design-slop",
 )
 
 # ui-screenshot artifact contract (Excellence Reform PR-D3): captures land
@@ -52,6 +52,26 @@ UI_EVIDENCE_DIR = Path(".arka") / "evidence" / "ui"
 UI_SCREENSHOT_WINDOW_HOURS = 24
 UI_SCREENSHOT_MIN_BYTES = 10 * 1024
 
+# design-slop: the deterministic static half of the visual-review loop.
+# Shells the external `impeccable` npm CLI (46 anti-pattern rules, no
+# LLM) over the CHANGED UI files only — never a whole-tree scan. The
+# gate never installs anything (supply-chain: `npx --no-install`).
+# Modes via ``governance.designSlop`` in ``~/.arkaos/config.json``:
+# off → skip · warn (default) → advisory summary, never fails ·
+# hard → `warning` findings fail; `advisory` findings never fail.
+DESIGN_SLOP_TIMEOUT = 120
+_DESIGN_SLOP_MIN_NODE = (22, 12)
+
+
+def _design_slop_config_path() -> Path:
+    """Resolved at call time so tests can redirect HOME (never baked)."""
+    return Path.home() / ".arkaos" / "config.json"
+
+
+def _design_slop_telemetry_path() -> Path:
+    """Resolved at call time so tests can redirect HOME (never baked)."""
+    return Path.home() / ".arkaos" / "telemetry" / "design-slop.jsonl"
+
 _MAX_SUMMARY_CHARS = 800
 _MAX_GREP_HITS = 20
 
@@ -661,6 +681,169 @@ def _check_ui_screenshot(
     )
 
 
+def _design_slop_mode() -> str:
+    """Resolve ``governance.designSlop`` to 'off' | 'warn' | 'hard'."""
+    config = _design_slop_config_path()
+    if not config.exists():
+        return "warn"
+    try:
+        data = json.loads(config.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return "warn"
+    raw = data.get("governance", {}).get("designSlop", "warn")
+    if raw in (False, "off", "false"):
+        return "off"
+    if raw in (True, "hard", "true"):
+        return "hard"
+    return "warn"
+
+
+def _resolve_detector(project_dir: Path) -> list[str] | None:
+    """Locate the impeccable CLI without ever installing it."""
+    direct = shutil.which("impeccable")
+    if direct:
+        return [direct]
+    local = project_dir / "node_modules" / ".bin" / "impeccable"
+    if local.is_file():
+        return [str(local)]
+    if shutil.which("npx"):
+        return ["npx", "--no-install", "impeccable"]
+    return None
+
+
+def _node_supports_detector() -> bool:
+    """True when `node --version` meets the detector's floor (22.12)."""
+    node = shutil.which("node")
+    if not node:
+        return False
+    try:
+        proc = subprocess.run(
+            [node, "--version"], capture_output=True, text=True, timeout=10,
+        )
+        major, minor = proc.stdout.strip().lstrip("v").split(".")[:2]
+        return (int(major), int(minor)) >= _DESIGN_SLOP_MIN_NODE
+    except (OSError, ValueError, subprocess.TimeoutExpired):
+        return False
+
+
+def _record_design_slop(payload: dict) -> None:
+    """Best-effort telemetry append; never raises into the gate."""
+    try:
+        target = _design_slop_telemetry_path()
+        target.parent.mkdir(parents=True, exist_ok=True)
+        with target.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps({"ts": time.time(), **payload}) + "\n")
+    except OSError:
+        pass
+
+
+def _design_slop_verdict(
+    findings: list[dict], mode: str, n_files: int, command_str: str,
+) -> CheckResult:
+    """Turn parsed detector findings into the check verdict."""
+    warnings = [f for f in findings if f.get("severity") != "advisory"]
+    advisories = [f for f in findings if f.get("severity") == "advisory"]
+    top = "; ".join(
+        f"{f.get('file', '?')}:{f.get('line', '?')} {f.get('antipattern', '?')}"
+        for f in (warnings + advisories)[:10]
+    )
+    counts = (
+        f"{len(warnings)} warning(s), {len(advisories)} advisory finding(s)"
+    )
+    if warnings and mode == "hard":
+        summary = f"{counts} across {n_files} changed UI file(s): {top}"
+        passed = False
+    elif findings:
+        # Only warning-severity findings ever fail (and only in hard
+        # mode) — never promise a hard failure for advisory-only runs.
+        escalation = (
+            " — fails when governance.designSlop=hard" if warnings else ""
+        )
+        summary = (
+            f"ADVISORY: {counts} across {n_files} changed UI "
+            f"file(s){escalation}: {top}"
+        )
+        passed = True
+    else:
+        summary = f"0 findings across {n_files} changed UI file(s)"
+        passed = True
+    return CheckResult(
+        check="design-slop", ran=True, passed=passed,
+        command=command_str, exit_code=2 if findings else 0,
+        summary=summary[:_MAX_SUMMARY_CHARS],
+    )
+
+
+def _check_design_slop(
+    project_dir: Path, changed: list[str] | None,
+    test_command: str | None, timeout: int,
+) -> CheckResult:
+    """Deterministic AI-design-slop detection over changed UI files.
+
+    Composition: ``frontend_gate`` is the pre-edit nudge (PreToolUse),
+    this check is the static deterministic half, ``ui-screenshot`` is
+    the pixel-artifact half, and Francisca supplies judgment. Fail-open
+    by design: a missing detector, an old node, a timeout or unreadable
+    output SKIP with a note — the gate never blocks on tooling absence
+    and never installs anything.
+    """
+    mode = _design_slop_mode()
+    if mode == "off":
+        return _skip("design-slop", "disabled by governance.designSlop flag")
+    if not changed:
+        return _skip("design-slop", "no changed files provided")
+    try:
+        from core.workflow.frontend_gate import is_ui_file
+    except Exception:
+        return _skip("design-slop", "frontend_gate unavailable")
+    ui_changed = [
+        f for f in changed
+        if is_ui_file(f) and (project_dir / f).is_file()
+    ]
+    if not ui_changed:
+        return _skip("design-slop", "no UI files changed")
+    detector = _resolve_detector(project_dir)
+    if detector is None:
+        return _skip(
+            "design-slop",
+            "impeccable CLI not installed (npm i -D impeccable, or re-run "
+            "the ArkaOS installer) — skipped",
+        )
+    if not _node_supports_detector():
+        return _skip("design-slop", "node >= 22.12 required by the detector")
+    argv = [*detector, "detect", *ui_changed, "--json"]
+    command_str = shlex.join(argv)
+    try:
+        proc = subprocess.run(
+            argv, cwd=project_dir, capture_output=True, text=True,
+            timeout=min(timeout, DESIGN_SLOP_TIMEOUT),
+        )
+    except subprocess.TimeoutExpired:
+        return CheckResult(
+            check="design-slop", ran=True, passed=None,
+            command=command_str, exit_code=None, summary="timeout",
+        )
+    except (OSError, FileNotFoundError):
+        return _skip("design-slop", "detector could not be executed")
+    if proc.returncode not in (0, 2):
+        tail = (proc.stderr or proc.stdout or "").strip()[-200:]
+        return _skip("design-slop", f"detector error (exit {proc.returncode}): {tail}")
+    try:
+        findings = json.loads(proc.stdout or "[]")
+        assert isinstance(findings, list)
+    except (json.JSONDecodeError, AssertionError):
+        return _skip("design-slop", "unparseable detector output — skipped")
+    result = _design_slop_verdict(findings, mode, len(ui_changed), command_str)
+    _record_design_slop({
+        "project_dir": str(project_dir), "mode": mode,
+        "ui_files": len(ui_changed),
+        "warnings": sum(1 for f in findings if f.get("severity") != "advisory"),
+        "advisories": sum(1 for f in findings if f.get("severity") == "advisory"),
+        "outcome": "fail" if result.passed is False else "pass",
+    })
+    return result
+
+
 _CHECK_DISPATCH = {
     "lint": _check_lint,
     "typecheck": _check_typecheck,
@@ -669,6 +852,7 @@ _CHECK_DISPATCH = {
     "security-grep": _check_security_grep,
     "spellcheck": _check_spellcheck,
     "ui-screenshot": _check_ui_screenshot,
+    "design-slop": _check_design_slop,
 }
 
 

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/brand/skills/design-review/SKILL.md

@@ -112,6 +112,12 @@ For every captured surface, annotate deviations with exact values
 - **Benchmark contrast** — for each major finding, one line on what the
   named benchmark does instead.
 
+> The deterministic half of this review also runs mechanically as the
+> QG evidence check `design-slop` (`core.governance.evidence_checks` —
+> the external `impeccable` detector over changed UI files, fail-open);
+> cite its finding `antipattern` ids in verdicts when the report
+> carries them.
+
 ## Slop gates (pre-verdict — MANDATORY)
 
 Before issuing any verdict, run the reviewed surfaces through

package/departments/brand/skills/ux-audit/SKILL.md

@@ -103,7 +103,10 @@ benchmark contrast, concrete fix.
    — no memory-based auditing.
 4. **Slop pass** — run the 58 gates (`slop-test.md`) and name every hit
    from `anti-patterns.md`; check reflex-reject violations against the
-   squad reference §11 and design-law breaches against §12.
+   squad reference §11 and design-law breaches against §12. The
+   deterministic half runs mechanically as the QG check `design-slop`
+   (external `impeccable` detector, fail-open) — cite its `antipattern`
+   ids when its report is on record.
 5. **Accessibility pass** — keyboard-only run, focus visibility,
    contrast (AA), `prefers-reduced-motion`, semantic landmarks.
 6. **Responsive pass** — 390 / 768 / 1440; layout integrity, target

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).