oh-my-agent-commandcode 0.0.0-stage → 20.38.4

package/skills/oma-translation/resources/translation-rubric.md

@@ -0,0 +1,126 @@
+# Translation Quality Rubric
+
+5 criteria, each scored on a 10-point scale. Total 50 points.
+
+**This file is language-neutral.** Criterion 1 (Naturalness) and criterion 3
+(Register) can only be scored against the target language's own conventions, so
+score them with `lang/{code}.md` open. A draft that passes every red flag here
+and fails its language profile's self-check is not a passing translation.
+
+## Criteria
+
+### 1. Naturalness (10 pts)
+Does it read like it was originally written in the target language?
+
+| Score | Description |
+|-------|-------------|
+| 9-10 | Native speaker cannot tell it's a translation |
+| 7-8 | Reads naturally with minor awkwardness |
+| 5-6 | Understandable but clearly "translated" |
+| 3-4 | Awkward phrasing, unnatural word order |
+| 1-2 | Word-for-word translation, painful to read |
+
+Red flags:
+- Source language word order leaking through
+- Unnatural particles or prepositions
+- Overly long sentences that should be split
+- Pronouns handled against the target's pro-drop behavior
+- Europeanized patterns: unnecessary connectives, passive voice abuse, noun pile-up, over-nominalization, cleft sentence calques
+- Any rule in the target's language profile marked as a block-level failure
+
+### 2. Accuracy (10 pts)
+Is the meaning fully preserved?
+
+| Score | Description |
+|-------|-------------|
+| 9-10 | Meaning, nuance, and intent fully preserved |
+| 7-8 | Core meaning preserved, minor nuance loss |
+| 5-6 | Main idea correct but some details lost |
+| 3-4 | Partial meaning distortion |
+| 1-2 | Meaning significantly changed or wrong |
+
+Red flags:
+- Added meaning not in source
+- Omitted important qualifiers
+- Reversed logic (negation errors)
+- Hallucinated content
+- Emotional connotations flattened (e.g., "alarming" rendered as a neutral "surprising" rather than something that carries concern)
+- Figurative language translated literally when the image doesn't work in target language
+
+### 3. Register Consistency (10 pts)
+Does the tone match the configured register throughout?
+
+The register system itself is language-specific (sentence endings, T-V
+distinction, honorific paradigms, or none of these). Read the "Register" section
+of `lang/{code}.md` before scoring this criterion.
+
+| Score | Description |
+|-------|-------------|
+| 9-10 | Perfect register match, consistent throughout |
+| 7-8 | Mostly consistent with rare slips |
+| 5-6 | Noticeable register shifts |
+| 3-4 | Inconsistent: mixes formal and casual |
+| 1-2 | Wrong register entirely |
+
+Red flags:
+- Register drift between the opening and the closing of a document
+- Mixing two register systems that the target treats as mutually exclusive
+- Formal vocabulary in casual context or vice versa
+- Honorific or politeness level that the source does not support
+
+### 4. Terminology (10 pts)
+Are domain terms consistent and correct?
+
+| Score | Description |
+|-------|-------------|
+| 9-10 | All glossary terms applied, consistent throughout |
+| 7-8 | Glossary followed with 1-2 misses |
+| 5-6 | Some terms inconsistent across strings |
+| 3-4 | Multiple glossary violations |
+| 1-2 | Glossary ignored |
+
+Red flags:
+- Same source term translated differently in same batch
+- Glossary term overridden without justification
+- Technical term translated when it should stay in English
+
+### 5. Technical Integrity (10 pts)
+Are placeholders, formatting, and structure preserved?
+
+| Score | Description |
+|-------|-------------|
+| 9-10 | All placeholders, tags, and structure intact |
+| 7-8 | Intact with minor formatting differences |
+| 5-6 | One placeholder or tag issue |
+| 3-4 | Multiple broken placeholders |
+| 1-2 | Structure significantly damaged |
+
+Red flags:
+- Modified or deleted `{variables}`
+- Broken HTML/markdown tags
+- Changed JSON/YAML key names
+- Added or removed line breaks that affect rendering
+
+## Scoring Guide
+
+| Total | Grade | Action |
+|-------|-------|--------|
+| 45-50 | Excellent | Ship as-is |
+| 38-44 | Good | Minor polish recommended |
+| 30-37 | Acceptable | Review flagged items before shipping |
+| 20-29 | Needs work | Re-translate problem sections |
+| < 20 | Reject | Full re-translation required |
+
+## Quick Self-Check (for translator)
+
+Before submitting, verify:
+- [ ] Read the full translation aloud: does it flow?
+- [ ] Glossary terms are consistent across all strings
+- [ ] Register matches config from start to finish
+- [ ] All placeholders survived intact
+- [ ] No source language word order leaking through
+- [ ] Emotional connotations preserved (not flattened into neutral words)
+- [ ] Figurative language handled naturally (interpret/substitute/retain, not literal calques)
+- [ ] No Europeanized patterns (passive voice, noun pile-up, forced pronouns, unnecessary connectives)
+- [ ] Translator's notes are concise, accurate, and calibrated to target audience
+- [ ] The target language's own self-check in `lang/{code}.md` passed

package/skills/oma-video/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: oma-video
+description: Create videos through the OMA video CLI, or analyze and edit
+  existing clips with media tools. Use for frame extraction, visual analysis,
+  silence cuts, dubbing assembly, sound effects, scripts, and composition;
+  audio-only work uses oma-voice.
+---
+
+# Video Router
+
+## Scheduling
+
+### Goal
+
+Create a playable video, or derive requested frames, analysis, or edits from an
+existing clip while retaining its source timeline.
+
+### Intent signature
+
+- Create a short, explainer, or recorded demo.
+- Extract frames, count visible objects, remove pauses, or assemble a dubbed clip.
+- Add sound effects to a video or check its soundtrack against the picture.
+
+### When to use
+
+Use this skill for a short/reel, README or code explainer, demo walkthrough, or
+analysis and editing of an existing video.
+
+| Request | Mode | Default aspect | Required source |
+|---|---|---|---|
+| Short, reel, social clip | `shorts` | `9:16` | Topic or brief |
+| README, code, data explanation | `explainer` | `16:9` | Topic or source path |
+| Demo or walkthrough | `demo` | `16:9` | Human recording via `--capture` |
+
+Processing a supplied or already-rendered video conditionally loads the upstream
+`kajisho5/ffmpeg-skill` through `resources/existing-media.md`. This is separate
+from the OMA creation modes. Sound effects, a sound-designed soundtrack, or
+listening checks on a video's audio conditionally load `Leonxlnx/earshot`
+through `resources/sound-design.md`.
+
+### When NOT to use
+
+Use `oma-image` for a still image, `oma-slide` for a deck, `oma-voice` for
+audio only, and `oma-explanation` for an interactive HTML explainer. Route
+transcription, synthesis, and TTS duration fitting to `oma-voice`, and spoken
+translation to `oma-translation`; this skill owns their placement in video.
+Live streaming is out of scope.
+
+### Expected inputs
+
+A creation brief, or an existing clip plus the requested analysis/edit, selected
+streams, timing or sampling requirements, and output path.
+
+### Expected outputs
+
+A generated video and its asset bus, or requested frames/analysis/edited media
+with source timestamps and the parameters used to derive them.
+
+### Dependencies
+
+Creation requires the selected OMA providers/compositor. For processing supplied
+or rendered video, use the runtime skill catalog first; otherwise load
+`kajisho5/ffmpeg-skill` with `bunx skills use` as described in the conditional
+resource. Its complete support bundle, Python, FFmpeg/FFprobe and any
+operation-specific capabilities are required. Sound effects and audio listening
+use the upstream earshot skills plus a resolved earshot runtime with
+FFmpeg/FFprobe; never install it without consent. Visual interpretation uses the
+host vision tool. Report unavailable capabilities rather than invent results.
+
+## Structural Flow
+
+For supplied or already-rendered video, use the existing-media branch in the
+canonical path. The upstream skill owns its scripts, flags, templates,
+`project.json` and mechanical editing workflow. OMA retains source-timeline
+evidence and the visual, speech and editorial decisions described there. Its
+project format is separate from the OMA creation asset bus below.
+For creation, inputs are a brief plus optional mode, aspect, locale, captions,
+visual, voice, music, duration, compositor, capture path, and seed. Outputs live in
+`.agents/results/videos/<timestamp>-<shortid>-<mode>/`:
+
+- `script.json`, `timing.json`, and `render-spec.json` form the deterministic
+  asset bus.
+- Captions and acquired audio/visual assets are recorded in `manifest.json`
+  with hashes, providers, cost, warnings, and exit code.
+- A successful real render contains `<mode>-<slug>.mp4`, an encoded video
+  stream, and a positive ffprobe duration.
+
+`OMA_VIDEO_MOCK=1` is a test harness only. It can create deterministic text
+placeholders with an `.mp4` name; those files are never a user deliverable. A
+missing HyperFrames/MPT toolchain, an un-authored composition, a render error, or
+an invalid video fails with diagnostics and leaves the script/render spec for
+recovery.
+
+### Decide and confirm
+
+For creation, infer mode when clear: short/reel -> `shorts`;
+README/code/data/explain -> `explainer`; demo/walkthrough/capture -> `demo`.
+For a one-line creation request, state
+the inferred mode, aspect, duration, visual strategy, captions, locale, and
+voice/music before invoking. Do not make the user complete a questionnaire
+when those defaults are clear.
+
+Ask only when it changes the result: an ambiguous mode/source, a required demo
+recording, or a cost confirmation. Respect an explicit mode, aspect, duration,
+captions, or voice verbatim.
+
+For a demo, a human records the screen and controls login. `--source web --url`
+provides context only; it never automates login or starts a recorder. Without
+`--capture`, return guided capture instructions and stop.
+
+## Logical Operations
+
+### Guardrails
+
+1. Keep output and capture paths inside `$PWD` unless external output is
+   explicitly allowed. Validate capture formats and copy external assets into
+   the run directory. Mask URL query/hash tokens in logs and manifests.
+2. Provider configuration is key-optional: use the configured chain. Paid
+   providers require their environment key and the cost guardrail. Local
+   fallbacks may replace voice, visuals, captions, or music; record coverage in
+   warnings. A compositor failure is never a fallback video.
+3. Before a paid provider action or rerun, compare the planning estimate with
+   `cost.guardrail_usd` or `--max-usd` and reuse existing spend authorization.
+   In an active OMA video workflow, record the actual paid, limited, fallback, or
+   declined choice before executing it (execution protocol Step 2). Pass `--yes`
+   or `OMA_VIDEO_YES=1` only for an already authorized paid action; the event does
+   not grant permission.
+4. For creation, respect `limits.max_duration_sec` (180) and
+   `limits.max_scenes` (40). Cancel subprocess work on SIGINT/SIGTERM.
+5. Keep run directories. Never auto-prune a user’s video artifacts.
+   A demo capture is inspected for personal information and masked before
+   render (`resources/hyperframes-authoring/demo.md`); an unchecked capture is
+   not rendered.
+6. Creation via `oma video generate --dry-run` writes only planning artifacts
+   and does no provider render. It does not prove an MP4 exists. For delegated
+   media work, follow the loaded upstream operation's dry-run contract.
+
+### Canonical command path
+
+1. Supplied or already-rendered video: load `resources/existing-media.md`.
+   Resolve the upstream skill, follow its supported operation, and retain OMA
+   timeline and interpretation evidence. These operations do not pass through
+   `oma video generate` or the creation-only limits above.
+2. New video: use the commands below and the creation pipeline. Keep existing
+   `shorts`, `explainer`, and `demo` behavior.
+3. Sound effects or soundtrack listening on either path: load
+   `resources/sound-design.md`. earshot supplies the sounds and the listening
+   evidence; OMA keeps cue times, placement in the composition, and delivery.
+
+```bash
+# Plan or create the asset bus. Supply --script whenever an agent authored it.
+oma video generate "Jeju coffee" --mode shorts --aspect 9:16 \
+  --captions tiktok --script ./script.json --output json
+
+# Deterministic planning only; no real render or provider work.
+oma video generate "explain this project" --mode explainer --seed 42 --dry-run
+
+# Human-recorded demo input.
+oma video generate "feature walkthrough" --mode demo --capture <absolute-path>.mp4
+
+# Scaffold the per-run HyperFrames project, author index.html as instructed,
+# then render and validate the encoded output.
+oma video compose <runDir> --output json
+oma video render <runDir> --output json
+
+# Diagnose required toolchains without changing a run.
+oma video doctor
+oma video provider list
+```
+
+`oma video generate --output json` returns
+`{exitCode, runDir, manifestPath, scriptPath, renderSpecPath, warnings, error}`.
+Read video and asset paths from the manifest; the JSON envelope has no
+`outputs` field.
+
+### Failure and recovery
+
+- Missing HyperFrames composition: `oma video compose <runDir>` prepares the
+project and authoring contract. Author `<runDir>/hyperframes/index.html` using
+the generated `AUTHORING.md`, then invoke `oma video render <runDir>`. The
+command lints, renders, and ffprobes the output. Fix a reported composition
+or toolchain failure and re-run; return a failure report when it cannot render.
+
+- Missing MPT toolchain: `--compositor mpt` requires the installed checkout, its virtual environment,
+and ffmpeg. Use `oma video doctor --install-mpt` when setup is authorized and
+available. MPT setup failures, driver failures, and non-video output fail with
+the diagnostic; they do not write a placeholder MP4.
+
+For creation, success means all asset schemas and manifest hashes validate and a
+real MP4 passes video-stream and duration validation. A partial success may use a
+key-free visual, timing, caption, or music fallback, but it still requires that
+real video validation.
+
+## References
+
+### Conditional resources
+
+Load only what the task needs:
+
+- `resources/execution-protocol.md` for the creation pipeline, failure
+  mapping, and JSON reporting rules.
+- `resources/existing-media.md` when processing supplied or rendered video:
+  upstream skill loading, source-timeline evidence and visual/speech decisions.
+- `resources/sound-design.md` when a video needs sound effects, foley, ambience
+  or soundtrack review: earshot routing, cue placement and listening evidence.
+- `resources/vendor-matrix.md` before changing providers, keys, cost, or
+  fallback order.
+- `resources/script-schema.md` when authoring or validating `--script` input.
+- `resources/prompt-tips.md` when turning a brief into scene prompts.
+- `resources/motion-principles.md` when authoring `script.json` or the
+  composition: scene cast, motion, text, narration sync and diagram rules.
+- `resources/hyperframes-authoring/README.md` and the selected mode guide before
+  writing `index.html`.
+- `resources/checklist.md` before handing a newly generated video to a user.
+
+### Verification
+
+For CLI/runtime changes, add a regression test for the affected success and
+failure paths. At minimum run the focused Vitest files, for example:
+
+```bash
+cd cli
+bunx vitest run commands/video/providers/compositor.test.ts \
+  commands/video/orchestrator.test.ts
+bunx biome check commands/video/providers/compositor.ts \
+  commands/video/providers/compositor.test.ts
+```
+
+Do not run a live render merely to test documentation or a mock-only branch.

package/skills/oma-video/config/video-config.yaml

@@ -0,0 +1,60 @@
+# oma-video skill configuration — NO LONGER READ BY THE CLI.
+#
+# Editing this file has no effect. Put your overrides under `video:` in
+# .agents/oma-config.yaml, which `oma update` preserves; this file is
+# overwritten. `oma update` runs migration 022, which moves anything you had
+# changed here into oma-config for you.
+#
+# The values below are the frozen migration 022 baseline, not current defaults.
+# Keep them unchanged so migration 022 can identify historical user overrides.
+# Current defaults (HyperFrames) live in cli/io/video/config.ts.
+default_output_dir: .agents/results/videos
+default_mode: shorts
+default_aspect: auto
+default_locale: en
+default_captions: tiktok
+default_visual: auto
+default_voice: none
+default_music: none
+default_compositor: hyperframes
+default_timeout_sec: 600
+
+providers:
+  script:
+    order: [agent-script]
+  voice:
+    order: [oma-voice]
+  visual:
+    order: [oma-image, pexels, pixelle]
+  caption:
+    order: [oma-captions]
+  # Capture dispatch is currently driven by --source directly
+  # (cli/commands/video/orchestrator/capture.ts): --source web -> guided/cap,
+  # --source file -> guided/cap. This key mirrors the code default and is
+  # informational only — the orchestrator does not walk it as a chain.
+  capture:
+    order: [cap]
+  # Strudel renders the BGM bed offline (headless Chrome + OfflineAudioContext).
+  # Deps are AGPL and opt-in: `oma video doctor --install-strudel`.
+  music:
+    order: [strudel]
+  compositor:
+    order: [hyperframes, mpt]
+  # Paid providers — auto-enabled only when their env key is present (backend
+  # rule 11: real path gated on key, key-free fallback otherwise).
+  pexels:
+    enabled: false
+    envVar: PEXELS_API_KEY
+  pixelle:
+    enabled: false
+    envVar: RUNNINGHUB_API_KEY
+
+cost:
+  guardrail_usd: 0.20
+
+limits:
+  max_duration_sec: 180
+  max_scenes: 40
+
+naming:
+  single_folder_pattern: "{timestamp}-{shortid}-{mode}"

package/skills/oma-video/resources/checklist.md

@@ -0,0 +1,26 @@
+# Checklist: before you run `oma video generate`
+
+- [ ] Mode is set or inferable (shorts / explainer / demo) and the topic/source is clear (see `prompt-tips.md`).
+- [ ] `--aspect` matches the mode (9:16 shorts, 16:9 explainer/demo) or is `auto`.
+- [ ] Duration ≤ 180s and the script stays ≤ 40 scenes.
+- [ ] `--output-dir` is inside the project, or `--allow-external-output` is set.
+- [ ] For `demo`: `--capture <path>` exists, is absolute + inside `$PWD`, and is a valid video format — or you accept the guided protocol.
+- [ ] Provider readiness checked with `oma video doctor` (Node/Chromium/FFmpeg · Voicebox MCP or VoiceStudio · oma-image vendors · Pixelle-MCP · Cap).
+- [ ] Paid visuals (Pexels / Pixelle) have their env key set, OR you accept the key-free oma-image fallback.
+- [ ] Pixelle-MCP, if used: one-time explicit consent + source review done; `--max-usd` set for RunningHub credits.
+- [ ] Estimated cost is acceptable. Run `--dry-run` first for unfamiliar combinations.
+- [ ] Secrets are not in the brief, or `--no-brief-in-manifest` is set.
+
+# Checklist: after the run
+
+- [ ] The run directory contains `script.json`, `timing.json`, `render-spec.json`, `captions.srt`/`.vtt`, the `<mode>-<slug>.mp4`, and `manifest.json`.
+- [ ] Every asset-bus schema validates (`schemaVersion: "1.0"`).
+- [ ] `manifest.json` records each provider, asset `sha256` hashes, cost breakdown, and the exit code.
+- [ ] `warnings[]` annotates any fallback taken (e.g. Pexels key absent -> oma-image stills, translator absent -> source locale).
+- [ ] External assets were copied into the run dir and hashed (no URL refs).
+- [ ] The mp4 has a video stream and positive duration (the CLI ffprobe check passed). A deterministic placeholder is valid only under `OMA_VIDEO_MOCK=1` tests and is never a deliverable.
+- [ ] For a demo capture: sampled frames were inspected, every personal detail is cropped out or covered with an opaque layer, and the masked regions are listed in the report (see `hyperframes-authoring/demo.md`).
+- [ ] If sound effects were placed: the upstream kit check is clean, each `<audio>` start comes from `kit.lock.json`, and the report quotes earshot `timeline` sync and loudness readings (see `sound-design.md`).
+- [ ] Re-rendering with `oma video render <runDir>` reproduces the same output from `render-spec.json`.
+- [ ] If results are consumed downstream, the consumer parses the `--output json` stdout envelope `{exitCode, runDir, manifestPath, scriptPath, renderSpecPath, warnings, error}` (there is no `outputs` key) and reads output/asset paths from the manifest at `manifestPath`.
+- [ ] Old run directories under `.agents/results/videos/` are pruned **manually** when no longer needed — every run adds a new dir and the CLI never auto-deletes them.

package/skills/oma-video/resources/execution-protocol.md

@@ -0,0 +1,122 @@
+# Video Agent - Execution Protocol
+
+## Step -1: Clarify / Infer Mode (agent-side, before `oma video generate`)
+
+Run the **Clarification Protocol** in `SKILL.md` before shelling out. Infer the
+mode from keywords (shorts/reels/쇼츠/릴스 -> shorts; README/code/data/explain/설명
+-> explainer; demo/walkthrough/capture/데모 -> demo) and show the user the inferred
+plan when the brief is a one-liner.
+
+## Step 0: Parse Request
+
+1. Extract the brief and flags from the invocation.
+2. Resolve defaults from shipped code defaults -> the `video:` section of `.agents/oma-config.yaml` -> env vars -> CLI flags (lowest to highest precedence). `config/video-config.yaml` is not consulted.
+3. Validate:
+   - `mode` ∈ {`shorts`, `explainer`, `demo`}.
+   - `aspect` ∈ {`9:16`, `16:9`, `1:1`, `auto`} (`auto` snaps to the mode default: shorts -> 9:16, explainer/demo -> 16:9).
+   - `captions` ∈ {`tiktok`, `lower-third`, `none`}; `visual` ∈ {`auto`, `generate`, `stock`, `aigc`, `slide`}.
+   - `music` ∈ {`upbeat`, `calm`, `cinematic`, `lofi`, `piano`, `none`}; `compositor` ∈ {`hyperframes`, `mpt`}.
+   - `duration` ≤ `limits.max_duration_sec` (180); resulting `scenes` ≤ `limits.max_scenes` (40).
+   - `out` is inside `$PWD` unless `--allow-external-output`.
+   - For `demo`: `--capture` (if given) exists, is absolute + `$PWD`-guarded, and is a valid video format.
+4. If invalid: exit code 4 with a message identifying the offending field.
+
+## Step 0.5: Mode Routing
+
+- **shorts** (9:16): synthetic from the topic. Default visual = static oma-image stills.
+- **explainer** (16:9 / 9:16): from README / code / data. Default visual = oma-slide frames + oma-image diagrams.
+- **demo** (16:9): from a screen capture. If no `--capture` and Cap is unavailable -> emit the **guided capture protocol** (Step 4b) and stop.
+
+## Step 1: Provider Availability + Selection
+
+1. Call `available()` on every registered provider in parallel (`oma video provider list`).
+2. For each capability, walk `providers.<capability>.order`:
+   - The first available provider wins.
+   - Paid providers (`pexels`, `pixelle`) are skipped unless their env key is present (`enabled` gate).
+   - On chain exhaustion for a required capability -> exit 5 naming the capability.
+3. Log `using: <provider>` per capability to stderr before generation.
+
+## Step 2: Cost Guardrail
+
+1. Estimate cost = sum of each selected provider's `estimateCost()` (most are `$0`; Pixelle/RunningHub credits are non-zero).
+2. If `--dry-run`: emit `script.json` / `render-spec.json` / `manifest.json`, skip rendering, exit 0.
+3. Before a non-dry run whose estimate reaches the guardrail or whose paid-provider choice requires authorization, reuse existing authorization for that provider, amount, and scope. Resolve only missing authorization. In an active OMA video workflow, emit `video.cost-confirmation` with the current script/provider-plan `instanceId`, actual paid/limited/fallback/declined action, rationale, and planning-manifest evidence; verify with `--instance` before the provider action (workflow Step 4 owns the command template).
+4. The CLI throws a cost-guardrail error and exits 1 when the cumulative provider estimate reaches the threshold without `--yes`; it does not collect a workflow decision through an interactive prompt. Planning may hit the same guard: retain the error/manifest estimate or rerun with `--dry-run --yes` to finish planning without paid generation or rendering. Keep `--dry-run` on that planning rerun. On a non-dry run, pass `--yes` / `OMA_VIDEO_YES=1` only when the paid action is already authorized. A declined path may be replaced by an authorized key-free plan and re-planned. A new provider or increased estimate must fit current authorization before paid work resumes.
+
+## Step 3: Cancellation Setup
+
+1. Install `SIGINT` / `SIGTERM` handlers that call `AbortController.abort()`.
+2. Thread the signal into every provider call and into the render subprocess.
+
+## Step 4: Pipeline (asset bus)
+
+```
+brief ─► [ScriptProvider] ─► script.json {scenes[], narration[], onScreenText[]}
+script.json ─► parallel:
+   ├► [VoiceProvider]   ─► audio/narration-01.wav (single joined track) + timing.json
+   ├► [VisualProvider]  ─► visuals/scene-NN.*
+   └► [CaptionProvider] ─► captions.srt / captions.vtt
+all assets ─► render-spec.json ─► [Compositor: HyperFrames] ─► <mode>-<slug>.mp4
+```
+
+1. **Script**: AgentScriptProvider writes `script.json` (start of the determinism boundary).
+2. **Voice**: oma-voice synthesizes narration on the `voice.backend` speech backend (Voicebox, or VoiceStudio; `auto` tries Voicebox first) -> a **single** `audio/narration-01.wav` (all scene lines joined into one track; per-line offsets live in `timing.json`). Fallback: estimated timing (no wav).
+3. **Visuals**: walk the visual chain. oma-image stills (key-free default) / oma-slide frames (explainer) / Pexels (key) / Pixelle (key). Aspect -> 16-multiple size; HyperFrames crops to the exact frame.
+4. **Captions**: oma-captions builds `captions.srt` + `captions.vtt` from `timing.json`. For a non-source locale, translate via oma-translation (key-free); absent -> warn + keep source.
+5. **render-spec**: compose `render-spec.json` (the deterministic compute boundary) from the assets + seed.
+6. **Render**: the compositor consumes `render-spec.json`.
+
+### Step 4b: Guided Capture Protocol (demo, no capture)
+
+State plainly to the user: **"Demo capture is performed by a human."** Then:
+1. Instruct: record the walkthrough with Cap (or any recorder) at 16:9.
+2. Ask the user to re-run with `--capture <absolute-path>.mp4`.
+3. Stop without rendering (capture-required is a guided stop, not a hard error).
+
+## Step 5: Compositor Render
+
+<!-- oma-docs:ignore-start -->
+- **HyperFrames (default, live)**: `generate` emits the asset bus and a pending HTML project at `<runDir>/hyperframes/`. Read its `AUTHORING.md`, the listed upstream API skills, and `resources/hyperframes-authoring/<mode>.md`. Author `index.html` with local assets and seekable animation. Run `oma video render <runDir> --output json`: lint → strict render → ffprobe stream/dimensions/duration checks → manifest update. Fix reported failures and re-render.
+<!-- oma-docs:ignore-end -->
+- **Failure**: a missing toolchain, render failure, missing video stream, or non-positive duration is a failure with diagnostics. Keep the run directory and recovery artifacts; do not write a placeholder MP4. `OMA_VIDEO_MOCK=1` permits deterministic placeholders for tests only.
+- **MPT (`--compositor mpt`)**: inject the agent-written script (custom-script mode); keys env-only + log masking. It requires the installed checkout, venv, and ffmpeg; setup or render failures fail with diagnostics.
+
+## Step 6: Write Artifacts
+
+1. Copy every external asset into the run dir and hash it (`sha256`); no URL refs.
+2. Validate each asset-bus schema (`script` / `timing` / `render-spec` / `manifest`) — `schemaVersion` must be `"1.0"`.
+3. Build `manifest.json`: `runId`, `mode`, `providers{...}`, `assets[{path,sha256,bytes,seed}]`, `outputs{video,durationSec,sha256}`, `cost{usd,breakdown}`, `warnings[]`, `exitCode`.
+4. If `--no-brief-in-manifest`: replace `prompt` with `promptSha256`.
+
+## Step 7: Report
+
+1. Print a one-line status per capability to stderr:
+   - `[oma video] <capability> <provider> ok (Xs)`
+   - `[oma video] <capability> <provider> fallback -> <fallback>`
+2. Print the run-dir path and, only on success, the validated mp4 path.
+3. For `--output json`: write `{exitCode, runDir, manifestPath, scriptPath, renderSpecPath, warnings, error}` to stdout as one JSON object (no `outputs` key — read output/asset paths from the manifest at `manifestPath`).
+
+## Step 8: Exit Code Aggregation (aligned with `oma search fetch`)
+
+- Success (playable mp4 with a video stream and positive duration + valid manifest) -> exit 0. Asset-provider fallbacks are recorded in `warnings`.
+- Otherwise pick the most specific code:
+  - `safety-refused` -> 2
+  - `not-found` (profile/asset) -> 3
+  - `schema-validation` / invalid input -> 4
+  - `provider-unavailable` / `auth-required` -> 5
+  - `timeout` -> 6
+  - otherwise -> 1
+
+## On Error
+
+| Situation | Action |
+|-----------|--------|
+| No provider for a required capability | Exit 5, print `Run: oma video doctor` |
+| HyperFrames or MPT toolchain not bootstrapped | Exit 1 + `oma video doctor` remediation; retain render-spec and authored composition for recovery |
+| No speech backend reachable (Voicebox / VoiceStudio) | Fall back to estimated timing; still emit captions (whisper.cpp hop deferred: `TODO(oma-deferred): whisper-cpp`) |
+| Pexels / Pixelle key absent | Skip provider; fall through to oma-image stills; annotate coverage in `warnings` |
+| `demo` with no capture + no Cap | Guided protocol (Step 4b); stop without rendering |
+| `--capture` outside `$PWD` or wrong format | Exit 4 with the path/format problem |
+| Cost over guardrail, declined | Exit 1 |
+| Timeout | Exit 6, manifest records `after_ms` |
+| Cancelled (Ctrl+C) | Exit 130 (signal); no manifest if abort was pre-write |