videoclaw 3.0.0-alpha.1

package/skills/help/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: help
+description: Guide on using VideoClaw
+---
+
+# How OMX Works
+
+**You don't need to learn any commands!** OMX enhances Codex CLI with intelligent behaviors that activate automatically.
+
+## What Happens Automatically
+
+| When You... | I Automatically... |
+|-------------|-------------------|
+| Give me a complex task | Parallelize and delegate to specialist agents |
+| Ask me to plan something | Start a planning interview |
+| Need something done completely | Persist until verified complete |
+| Work on UI/frontend | Activate design sensibility |
+| Say "stop" or "cancel" | Intelligently stop current operation |
+
+## Magic Keywords (Optional Shortcuts)
+
+You can include these words naturally in your request for explicit control:
+
+| Keyword | Effect | Example |
+|---------|--------|---------|
+| **ralph** | Persistence mode | "ralph: fix all the bugs" |
+| **ralplan** | Iterative planning | "ralplan this feature" |
+| **ulw** | Max parallelism | "ulw refactor the API" |
+| **plan** | Planning interview | "plan the new endpoints" |
+
+**ralph includes ultrawork:** When you activate ralph mode, it automatically includes ultrawork's parallel execution. No need to combine keywords.
+
+## Stopping Things
+
+Just say:
+- "stop"
+- "cancel"
+- "abort"
+
+I'll figure out what to stop based on context.
+
+## First Time Setup
+
+If you haven't configured OMX yet:
+
+```
+/omx-setup
+```
+
+This is the **only command** you need to know. It downloads the configuration and you're done.
+
+If you only need lightweight directory guidance scaffolding for `AGENTS.md` files, use:
+
+```bash
+omx agents-init .
+```
+
+That command is intentionally narrower than full setup: it only bootstraps `AGENTS.md` files for the target directory and its immediate child directories.
+
+## For 2.x Users
+
+Your old commands still work! `/ralph`, `/ultrawork`, `/plan`, etc. all function exactly as before.
+
+But now you don't NEED them - everything is automatic.
+
+---
+
+## Usage Analysis
+
+Analyze your VideoClaw usage and get tailored recommendations to improve your workflow.
+
+> Note: This replaces the former `/learn-about-omc` skill.
+
+### What It Does
+
+1. Reads token tracking from `~/.omx/state/token-tracking.jsonl`
+2. Reads session history from `.omx/state/session-history.json`
+3. Analyzes agent usage patterns
+4. Identifies underutilized features
+5. Recommends configuration changes
+
+### Step 1: Gather Data
+
+```bash
+# Check for token tracking data
+TOKEN_FILE="$HOME/.omx/state/token-tracking.jsonl"
+SESSION_FILE=".omx/state/session-history.json"
+CONFIG_FILE="$HOME/.codex/.omx-config.json"
+
+echo "Analyzing OMX Usage..."
+echo ""
+
+# Check what data is available
+HAS_TOKENS=false
+HAS_SESSIONS=false
+HAS_CONFIG=false
+
+if [[ -f "$TOKEN_FILE" ]]; then
+  HAS_TOKENS=true
+  TOKEN_COUNT=$(wc -l < "$TOKEN_FILE")
+  echo "Token records found: $TOKEN_COUNT"
+fi
+
+if [[ -f "$SESSION_FILE" ]]; then
+  HAS_SESSIONS=true
+  SESSION_COUNT=$(cat "$SESSION_FILE" | jq '.sessions | length' 2>/dev/null || echo "0")
+  echo "Sessions found: $SESSION_COUNT"
+fi
+
+if [[ -f "$CONFIG_FILE" ]]; then
+  HAS_CONFIG=true
+  DEFAULT_MODE=$(cat "$CONFIG_FILE" | jq -r '.defaultExecutionMode // "not set"')
+  echo "Default execution mode: $DEFAULT_MODE"
+fi
+```
+
+### Step 2: Analyze Agent Usage (if token data exists)
+
+```bash
+if [[ "$HAS_TOKENS" == "true" ]]; then
+  echo ""
+  echo "TOP AGENTS BY USAGE:"
+  cat "$TOKEN_FILE" | jq -r '.agentName // "main"' | sort | uniq -c | sort -rn | head -10
+
+  echo ""
+  echo "MODEL DISTRIBUTION:"
+  cat "$TOKEN_FILE" | jq -r '.modelName' | sort | uniq -c | sort -rn
+fi
+```
+
+### Step 3: Generate Recommendations
+
+Based on patterns found, output recommendations:
+
+**If high Opus usage (>40%) and no ecomode:**
+- "Consider using ecomode for routine tasks to save tokens"
+
+**If no team usage:**
+- "Try /team for coordinated review workflows"
+
+**If no security-reviewer usage:**
+- "Use security-reviewer after auth/API changes"
+
+**If defaultExecutionMode not set:**
+- "Set defaultExecutionMode in /omx-setup for consistent behavior"
+
+### Step 4: Output Report
+
+Format a summary with:
+- Token summary (total, by model)
+- Top agents used
+- Underutilized features
+- Personalized recommendations
+
+### Example Output
+
+```
+📊 Your OMX Usage Analysis
+
+TOKEN SUMMARY:
+- Total records: 1,234
+- By Reasoning Effort: high 45%, medium 40%, low 15%
+
+TOP AGENTS:
+1. executor (234 uses)
+2. architect (89 uses)
+3. explore (67 uses)
+
+UNDERUTILIZED FEATURES:
+- ecomode: 0 uses (could save ~30% on routine tasks)
+- team: 0 uses (great for coordinated workflows)
+
+RECOMMENDATIONS:
+1. Set defaultExecutionMode: "ecomode" to save tokens
+2. Try /team for PR review workflows
+3. Use explore agent before architect to save context
+```
+
+### Graceful Degradation
+
+If no data found:
+
+```
+📊 Limited Usage Data Available
+
+No token tracking found. To enable tracking:
+1. Ensure ~/.omx/state/ directory exists
+2. Run any OMX command to start tracking
+
+Tip: Run /omx-setup to configure OMX properly.
+```
+
+## Need More Help?
+
+- **README**: https://github.com/davendra/videoclaw
+- **Issues**: https://github.com/davendra/videoclaw/issues
+
+---
+
+*Version: 4.2.3*

package/skills/higgsfield-generate/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: higgsfield-generate
+description: |
+  Higgsfield bridge for videoclaw agents. Use when the user wants
+  Higgsfield AI generation, Marketing Studio ad videos, product photoshoots,
+  Soul identity training, marketplace cards, image-to-video, or finished-video
+  virality scoring. This skill reuses the public MIT-licensed
+  higgsfield-ai/skills command intelligence without vendoring the whole repo.
+---
+
+# Higgsfield Generate
+
+This is a videoclaw bridge skill for Higgsfield AI. It routes requests into the
+official `higgsfield` CLI while keeping videoclaw's core production state in the
+`vclaw video ...` surface when a project artifact trail is needed.
+
+## Source And Reuse Boundary
+
+Reference source:
+- `higgsfield-ai/skills` at commit `5af0258255919ff918390ee82b498727ca8e8b89`
+- Version observed: `0.3.0`
+- License: MIT
+
+Reuse stance:
+- Reuse the command patterns, model-routing heuristics, and UX guardrails.
+- Do not vendor Higgsfield's setup script into videoclaw.
+- Do not add `higgsfield` as a hard dependency of videoclaw.
+- Keep Higgsfield authentication interactive and external to videoclaw.
+- If a result needs project history, save the returned media URL/path into the
+  relevant videoclaw project artifact or handoff note after generation.
+
+## Bootstrap
+
+Before running a Higgsfield command:
+
+```bash
+command -v higgsfield
+higgsfield account status
+```
+
+If the CLI is missing, install it from Higgsfield's official installer:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh
+```
+
+If auth is missing or expired, ask the user to run:
+
+```bash
+higgsfield auth login
+```
+
+Do not handle credentials directly.
+
+## Route Selection
+
+Use this skill for:
+- Branded ad video, UGC, unboxing, product demo, presenter ad, TV spot
+- Product photoshoot, hero banner, Pinterest pin, social carousel, ad creative
+  pack, virtual try-on, marketplace cards
+- Soul Character training or face-faithful identity reuse
+- Image-to-video or video generation when the user explicitly asks for
+  Higgsfield models
+- Finished-video hook, attention, retention, or virality scoring
+
+Prefer videoclaw's native `video-framework` / `ugc` / `movie-director` skills
+when the user wants a full videoclaw project with approvals, checkpoints,
+review UI, candidate selection, publish gates, or Obsidian portfolio tracking.
+
+## Commands
+
+### Generic Image Or Video
+
+Pick a model using the Higgsfield model catalog:
+
+```bash
+higgsfield model list --json
+higgsfield model get <model_id> --json
+```
+
+Submit and wait in one call:
+
+```bash
+higgsfield generate create <model_id> \
+  --prompt "<prompt>" \
+  --wait
+```
+
+Useful defaults:
+- Image/design/text-heavy visuals: `gpt_image_2`
+- Serious image-to-video or cinematic clips: `seedance_2_0`
+- Character/reference-image work: `nano_banana_2`
+- Branded ads: `marketing_studio_video` or `marketing_studio_image`
+- Virality scoring: `brain_activity`
+
+### Product Photoshoot
+
+Use the dedicated backend enhancer instead of freehanding a raw image prompt:
+
+```bash
+higgsfield product-photoshoot create \
+  --mode <product_shot|lifestyle_scene|closeup_product_with_person|moodboard_pin|hero_banner|social_carousel|ad_creative_pack|virtual_model_tryout|conceptual_product|restyle> \
+  --prompt "<short product/use-case intent>" \
+  --image <path-or-upload-id> \
+  --count <1-10>
+```
+
+### Marketing Studio Video
+
+Use this for UGC, presenter, unboxing, product showcase, review, TV spot, and
+try-on videos.
+
+```bash
+higgsfield generate create marketing_studio_video \
+  --prompt "<ad concept>" \
+  --mode <ugc|ugc_how_to|ugc_unboxing|product_showcase|product_review|tv_spot|wild_card|ugc_virtual_try_on|virtual_try_on> \
+  --duration 15 \
+  --aspect_ratio 9:16 \
+  --wait
+```
+
+When the user gives a product URL:
+
+```bash
+higgsfield marketing-studio products fetch --url <product-url> --wait
+higgsfield generate create marketing_studio_video \
+  --url <product-url> \
+  --mode ugc \
+  --duration 15 \
+  --aspect_ratio 9:16 \
+  --wait
+```
+
+### Virality Predictor
+
+Use `brain_activity` for finished-video analysis:
+
+```bash
+higgsfield generate create brain_activity \
+  --video <local-video-path-or-upload-id> \
+  --wait
+```
+
+Return the useful score/report summary and report link. Do not dump raw JSON
+unless the user asks for machine-readable output.
+
+## Videoclaw Hand-Off
+
+For standalone Higgsfield generation, return URLs directly.
+
+For a videoclaw project, record the hand-off clearly:
+
+```bash
+vclaw video set-meta --project <slug> --tag higgsfield --tag external-provider
+vclaw video status --project <slug>
+```
+
+If the Higgsfield output becomes an input for videoclaw post-production, attach
+or import the media through the existing project flow rather than inventing a
+new artifact shape.
+
+## Guardrails
+
+- Do not silently replace a requested Higgsfield route with Veo, Seedance,
+  Runway, or local image generation.
+- Do not expose raw job IDs in normal chat unless they are needed for polling or
+  debugging.
+- Do not batch-question. Ask only for the missing product, avatar, aspect ratio,
+  or mode needed for the next command.
+- Do not copy Higgsfield's whole skill repository into videoclaw. Treat it as an
+  upstream reference and keep this bridge thin.

package/skills/improvement-run/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: improvement-run
+description: Use when asked to run an improvement pass, audit-and-fix sweep, hardening pass, or docs/IMPROVE_PROMPT.md over this codebase — or any request to "make the codebase more robust" that spans multiple areas (handlers, transports, schemas, tests, docs, guardrails) and will land as multiple PRs.
+---
+
+# Improvement Run
+
+## Overview
+
+A discovery → verify → plan-gate → batched-implementation pipeline for whole-codebase improvement, proven on the 2026-06-13 run (PRs #149/#150/#152/#153, suite 2243→2279). Core principle: **audit findings are claims, not facts — adversarially verify before ranking, and separate authoring from verification.** The full reusable prompt lives in `docs/IMPROVE_PROMPT.md`; this skill is the execution method.
+
+## Phase 0 — Baseline in isolation
+
+- Create a worktree with a session-specific suffix (`git worktree add ../videoclaw-v3-<suffix> -b <branch> origin/main`); symlink `node_modules` from the main tree.
+- Run `npm run build && npm run test:node` serially there. **Never pipe test output through `tail`/`grep` in the same command — it masks the exit code.** Capture to a file.
+- A mass failure that is contiguous from some test file onward = environmental (a concurrent `npm run build` did `rmSync('dist')` mid-run), not real breakage. Re-run alone before believing it.
+
+## Phase 1 — Parallel audit, then adversarial verification
+
+- Fan out read-only Explore agents over independent areas (CLI dispatch/handlers, `src/video/*` domain, provider transports, schemas-vs-writers, test suite, docs-vs-behavior, smokes/guardrails). Each prompt must include: the ADR constraints as **fixed decisions, not findings** (no-silent-fallback, on-disk source of truth, Asset Library identity, approval gate, review-state ladder); a findings format (`TITLE | file:line | evidence | impact H/M/L | effort S/M/L | fix | test-that-would-catch-it`); and "report only what you verified by reading code".
+- **Re-verify every top-ranked claim yourself before it anchors the plan.** Expect roughly a third to be wrong. Check the tests first: behavior pinned by a test (e.g. `status.test.ts:287` pins the 'missing' review-state semantics) is intent, not a bug. Check command handlers before believing spend/free claims (`reroll-scene` only *requests*; the render happens at next `execute`).
+- Present ranked findings + batch plan and **pause for approval** — scope is the user's call. Include a "deliberately not doing" list (improvement ≠ churn).
+
+## Phase 2 — Batched implementation
+
+Per batch (PR-sized): change + the test that would have caught it → `npm run build` → full serial suite in the worktree → targeted guardrails (`check:cleanroom-docs`, `check:skill-frontdoor` for docs/skills) → commit → push → PR → fresh-context verifier agent on the diff → squash-merge → for stacked batches, `git rebase --onto origin/main <prev-branch> <branch>`.
+
+- **Commit within minutes of creating files.** Concurrent sessions adopt discovered worktrees: this run lost five uncommitted test files and an edit to one. Foreign files in `git status` = move to a NEW worktree immediately; leave theirs untouched.
+- Follow the CLAUDE.md registration checklist for any new command/artifact (handler + dispatch + schema + COMMANDS + count assertion + test + README + CLI_REFERENCE).
+- Verifier agents must be told the spec item-by-item and that the **report is the first priority**. Explore agents reliably end mid-exploration without a verdict — `SendMessage` the agent: "Stop exploring; write the report NOW with unverified items marked."
+
+## Phase 3 — Final pre-flight and closeout
+
+- `git checkout --detach origin/main` in the worktree → `npm run check:release-readiness-lite` (the real gate; exit code + "checks passed" line).
+- `graphify update .` in the main tree after `git pull --ff-only`; delete merged remote branches; `git worktree remove` yours (never one holding foreign WIP); write a memory entry with suite numbers and refuted findings.
+- Final report: lead with what's measurably better and the evidence (suite delta, pre-flight result), then per-PR detail, then what was deliberately not done.
+
+## Red flags
+
+| Symptom | Reality |
+|---|---|
+| "The audit agent said it's a bug" | Claims, not facts — read the code and its tests yourself first |
+| 251 failures appear mid-run | Concurrent dist wipe; re-run serially alone |
+| Background task "completed (exit 0)" after `\| tail` | The pipe ate the exit code; check the captured log's `# fail` line |
+| Verifier's last message is "Let me check…" | It died mid-exploration; nudge for the verdict before trusting silence |
+| "I'll commit after the suite finishes" | That window is when concurrent sessions eat uncommitted work |
+| Finding survives because it *sounds* plausible | Refuted-by-test-pin and refuted-by-reading were ⅓ of findings |

package/skills/motion-reel/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: motion-reel
+description: >
+  Turn a talking-head video into a polished motion-graphics reel — synced
+  lower-thirds, anchor-word headlines, and concept icons/infographics driven by
+  what is being said. Renders a finished reel locally (reliable, free, on the exact
+  footage) and emits a Flow hand-off pack for the premium Omni-animated version.
+  Use when the user wants to "animate this video", "add overlays / motion graphics",
+  "illustrate my speech", "make a reel", or hands a talking-head clip for overlays.
+triggers:
+  - "animate this video"
+  - "add overlays"
+  - "add motion graphics"
+  - "illustrate my speech"
+  - "motion for this reel"
+  - "make a reel"
+  - "overlay reel"
+  - "gemini omni"
+  - "motion overlay"
+---
+
+# Motion Reel
+
+Front door for `vclaw video motion-overlay`. The framework already does the work:
+ingest → transcribe → slice into ≤10s takes → compose per-take prompts → render. This
+skill drives the interactive choices and hands back two outputs:
+
+1. a **finished reel rendered locally** (no provider, no spend, no moderation — works
+   on the user's exact footage), and
+2. a **Flow hand-off pack** (one clip + ready-to-paste prompt per take) for when the
+   user wants Google Flow's Omni engine to animate it for real.
+
+> Why both: Flow's API safety-blocks the "edit my video" V2V op for every input, and
+> its current web editor won't accept a video upload — so the premium Omni path is
+> manual (paste each take + prompt in Flow's web UI). The local render is the reliable
+> deliverable; the pack is the upgrade path.
+
+## When to use
+
+The user hands a talking-head clip and wants overlays / "animate this" / "make a reel".
+
+## Sequence
+
+### 1. Get the source clip
+A path to the talking-head `.mp4`. If they have not recorded yet, recommend the
+**overlay** or **split** layout so they frame the speaker to leave room for graphics.
+
+### 2. Ask the look (AskUserQuestion)
+- **Layout** — `split` (graphics top, speaker bottom) · `overlay` (graphics over the
+  speaker, safe areas) · `motion-only` (speaker removed, full-frame graphics) ·
+  `avatar-host` (an identity-locked character delivers the lines — needs
+  `--gb-character Name:ID` + `--gb-character-image`).
+- **Style** — `apple-clean` (rounded frosted, premium) · `editorial-dark` (full-bleed
+  poster, bold caps) · `knowledge-tool` (serif, `[[ ]]` brackets, lavender).
+- **Extras** — `--headlines` (giant anchor-word beats) and/or `--icons` (concept
+  icons + stat callouts synced to the speech). Optional `--kicker "BRAND"` and
+  `--accent "#RRGGBB"`.
+
+### 3. Render the reel + emit the pack
+```
+vclaw video motion-overlay --input <clip> --output-dir <work> \
+  --delivery flow-web --layout <L> --style <S> [--headlines] [--icons] \
+  [--kicker "BRAND"] [--accent "#RRGGBB"]
+```
+`--delivery flow-web` renders the local reel **and** writes `<work>/flow-pack/`.
+(For just the local reel, use `--delivery local`. For the gated API V2V path,
+`--delivery flow-api --execute --confirm-spend`.)
+
+The CLI prints JSON: `localReelPath` (the finished reel) and `flowPackDir`.
+
+### 4. Show it
+Open `localReelPath` for review (force Google Chrome on macOS):
+```
+open -a "Google Chrome" <localReelPath>
+```
+
+### 5. Report both outputs
+- "Your reel is ready: `<localReelPath>` (rendered locally — your exact footage)."
+- "Flow pack: `<flowPackDir>` — to get Omni's real animation, upload each
+  `take-NN.mp4` into Flow's web editor and paste `take-NN.txt`, download the results
+  into a `done/` folder, then I'll stitch them back with the original audio."
+
+### 6. Restitch the Omni outputs (when they come back)
+```
+vclaw video motion-overlay --input <clip> --output-dir <work> --restitch <done-dir>
+```
+Re-muxes each animated take with its original audio and concatenates the final reel
+(`<work>/motion-overlay-reel.mp4`).
+
+## Optional: drive Flow's web editor
+
+If the user asks you to do the Flow paste-and-generate yourself, you can attempt it
+with the gstack browser (`/connect-chrome` → drive the Flow project). This is
+**best-effort**: Flow's Agent UI currently only accepts image uploads, so a video
+upload may be refused — confirm the upload works before promising a result, and fall
+back to the manual pack + `--restitch` if it does not.
+
+## Notes
+- Default to `--delivery flow-web` so the user always gets a reel now *and* the upgrade
+  path. Use `--delivery local` if they only want the local reel.
+- The original audio is always preserved.
+- See `docs/MOTION_OVERLAY.md` for the full flag surface and the styles/icons catalog.