videoclaw 3.0.0-alpha.1

package/docs/OBSIDIAN.md

@@ -0,0 +1,300 @@
+# Obsidian operator workspace
+
+`videoclaw` ships first-class **Obsidian** support so the operator can run the production
+portfolio from a knowledge-base UI rather than from terminal output. The repo writes a vault of
+machine-generated notes that mirror the canonical project state — dashboards, queues, metrics, health,
+timelines, dependencies, and per-project notes — all regenerated from a single command.
+
+> **Obsidian is a view, not the source of truth.** The repo state on disk
+> (`projects/<slug>/`, `artifacts/`, `checkpoints/`, `events/`) is canonical.
+> The Obsidian vault is a regenerable rendering of that state.
+
+---
+
+## What this gives you
+
+- **A control plane that isn't a terminal.** Browse the active queue, blockers, owners, dependencies,
+  and review-state ladder from a normal Obsidian sidebar.
+- **Linkable, navigable history.** Every project gets its own note with frontmatter, artifact references,
+  and bidirectional backlinks into dashboard notes.
+- **Honest health visibility.** Dashboards count missing approvals, stale reviews, blocked work, and due
+  risk — backed by the same `doctor-portfolio` and `metrics` machinery that drives reporting.
+- **Zero lock-in.** Notes are plain markdown files that live wherever you point `--output-dir`. You can
+  delete the vault any time and regenerate from canonical state with one command.
+
+---
+
+## Vault layout
+
+<p align="center"><img src="./assets/diagram-obsidian-vault.jpg" alt="Obsidian vault layout — root folder ops/obsidian containing 14 dashboard notes plus a Projects subfolder with one markdown note per project slug" width="100%" /></p>
+
+```text
+ops/obsidian/                 # vault root (path is your choice via --output-dir)
+├── Dashboard.md              # top-of-vault summary; start here
+├── Active.md                 # projects currently in flight
+├── Needs Review.md           # awaiting director-mode storyboard approval
+├── Blocked.md                # explicitly blocked-by something or someone
+├── Complete.md               # published / shipped / archived
+├── Metrics.md                # counts, rates, score averages, byReviewState
+├── Health.md                 # doctor-portfolio rollup
+├── Next Actions.md           # urgency-ordered action queue
+├── Dependencies.md           # blocker graph
+├── Timeline.md               # event timeline across the portfolio
+├── Trends.md                 # per-snapshot trend table
+├── History.md                # snapshot list
+├── Changes.md                # snapshot diff narrative
+├── Owner Workload.md         # owner-by-owner project load
+├── Templates/                # scaffolded once; not regenerated with project data
+│   └── Project Template.md
+├── Views/                    # scaffolded once; not regenerated with project data
+│   ├── Operations Runbook.md
+│   └── Board Guide.md
+└── Projects/                 # one note per project
+    ├── <slug>.md
+    ├── <slug>.md
+    └── <slug>.md
+```
+
+Every dashboard note below the vault root is regenerated from canonical state on each `sync-obsidian` run,
+so the vault is safe to delete and rebuild. The `Templates/` and `Views/` seed notes are scaffolded once
+(by `scaffold-obsidian-vault`, which `sync-obsidian` also runs first) and not overwritten with project data.
+
+---
+
+## Setup
+
+### One-time scaffold
+
+```bash
+vclaw video scaffold-obsidian-vault --output-dir ./ops/obsidian
+```
+
+This creates the vault root with a placeholder `Dashboard.md`, the `Projects/` folder, and the
+`Templates/` (`Project Template.md`) and `Views/` (`Operations Runbook.md`, `Board Guide.md`) seed
+notes. The other 13 dashboard notes are not created here — they are written by `sync-obsidian`. You can
+open the folder as an Obsidian vault immediately.
+
+### Single-project export
+
+```bash
+vclaw video export-obsidian \
+  --project my-project \
+  --output-dir ./ops/obsidian/Projects
+```
+
+Writes one project note for `my-project` and nothing else. Useful for incremental updates between
+full syncs.
+
+### Full sync (the common case)
+
+```bash
+vclaw video sync-obsidian --root . --output-dir ./ops/obsidian
+```
+
+Regenerates **every** dashboard note plus a project note for every project under `--root`. Idempotent —
+running it twice produces the same vault. This is what you call after a meaningful CLI change.
+
+The `--mode` flag (`storyboard` or `director`) filters the vault to one production mode if you maintain
+separate vaults per mode.
+
+---
+
+## The 14 dashboard notes
+
+| Note | What it shows | When to check |
+|---|---|---|
+| **Dashboard.md** | Portfolio summary: total projects, current state breakdown, top metrics, links to other notes. | First thing every morning. |
+| **Active.md** | Every project currently in flight (pre-publish, not blocked). | Whenever you want a "what's actually moving" view. |
+| **Needs Review.md** | Projects in `awaiting-approval` (director-mode storyboard awaiting your sign-off). Includes link to each `storyboard.md` review file and review freshness. | Before approving any director-mode execution. |
+| **Blocked.md** | Projects with explicit `blockedBy` or `blockedReason` set on the manifest. | When triaging — what's stuck and why. |
+| **Complete.md** | Published, shipped, or archived projects. | Retrospectives; reuse-as-template candidates. |
+| **Metrics.md** | Counts, rates, score averages, `byReviewState` breakdown (`missing` / `current` / `stale`). | Weekly portfolio review. |
+| **Health.md** | `doctor-portfolio` rollup: missing artifacts, stale reviews while approval is pending, broken stage states, count of projects in each failure mode. | Whenever Metrics looks off, or before a release. |
+| **Next Actions.md** | Urgency-ordered action queue. For director-mode awaiting-approval projects, links directly to the active `storyboard.md` review and shows review freshness. | Daily triage — what to do next. |
+| **Dependencies.md** | Blocker graph across the portfolio (who is blocked by whom). | When unblocking work or planning a freeze. |
+| **Timeline.md** | Event timeline across the portfolio, drawn from `events/events.jsonl` per project. | Investigating "what happened when?". |
+| **Trends.md** | Per-snapshot trend table (totals, completion rate, average score, blocked / needs-review counts, platforms, legacy-import drift across persisted `report-snapshot`s). | Tracking portfolio movement over time. |
+| **History.md** | Snapshot list: every persisted `report-snapshot` with its headline counts and file path. | Finding a baseline to diff against. |
+| **Changes.md** | Snapshot diff narrative: what's new since the last `report-snapshot`. Surfaces review-state transitions (`missing → current`, `current → stale`). | Before standups; before publishing reports. |
+| **Owner Workload.md** | Owner-by-owner project load with priorities and due risk. | Resourcing conversations. |
+
+---
+
+## Project notes
+
+Each project under `--root` gets its own note at `Projects/<slug>.md`. Project notes carry **frontmatter**
+that Obsidian treats as queryable properties.
+
+### Frontmatter schema
+
+`exportProjectToObsidian` (`src/video/obsidian-export.ts`) emits **snake_case** YAML keys (with a few
+camelCase reference-sheet keys). The fields actually written to each `Projects/<slug>.md` are:
+
+| Field | Source | Purpose |
+|---|---|---|
+| `title` | `project.json` | Note title (the slug) |
+| `slug` | `project.json` | Stable project identifier |
+| `production_mode` | `project.json` | Production mode (`storyboard` / `director`) |
+| `target_runtime_seconds` | brief | Final video length target |
+| `clip_duration_seconds` | brief | Per-clip duration |
+| `genre` | brief (director-mode) | Selected genre |
+| `platform` | brief | Target platform |
+| `style` / `color_grading` | brief | Creative direction |
+| `legacy_import_*` | derived | Legacy-import diagnostics (`manifest_present`, `queue_file_present`, `queue_status_mismatch`, `nested_output_root_detected`) |
+| `ops_status` | derived | Lifecycle state (`active`, `needs-review`, `blocked`, `complete`, ...) |
+| `score` | scorecard | Composite quality/health score |
+| `score_band` | scorecard | Score bucket (e.g. `green` / `amber` / `red`) |
+| `owner` | `set-meta` | Responsible operator |
+| `priority` | `set-meta` | `low` / `medium` / `high` / `critical` |
+| `due_date` | `set-meta` | ISO date the project is due |
+| `due_risk` | derived | `none` / `at-risk` / `overdue` |
+| `blocked_reason` | `set-meta` | Free-form blocker description |
+| `execution_profile_aspect_ratio` / `_quality` / `_resolution` / `_audio` / `_outputs` | manifest | Execution profile, split into one key per field |
+| `tags` | `set-meta` | Free-form tags for grouping |
+| `blocked_by` | `set-meta` | Slugs of blocking projects |
+| `next_stage` | derived | Next canonical stage (or `null` when complete) |
+| `storyboard_review_state` | derived | `missing` / `current` / `stale` (the review-state ladder) |
+| `storyboard_review_exists` / `_path` / `_generated_at` / `_stale` | derived | Active `storyboard.md` existence, path, regenerated-at, and staleness |
+| `review_report_verdict` / `review_publish_ready` | review report | Review verdict and publish-ready truth |
+| `referenceSheetCount` / `referenceSheetTypes` / `referenceSheetCollisions` | reference-sheet store | Sheet count, comma-joined types, and whether any per-scene role collides |
+| `sceneSelectionCoverage` / `sceneCandidatesTotal` | scene-selection store | `withSelection/sceneCount` coverage string and total candidate count |
+| `completed_stages` / `pending_stages` / `artifact_files` | derived | Stage and artifact lists |
+| `characters` / `character_bindings` / `prompt_guidance` | character store / status | Character names, bindings (`name:gb:refs`), and prompt-guidance names |
+
+> `characterProfiles` and `characterHydrationSummary` are **not** in the per-project frontmatter — those
+> live only in the Dashboard table source. When a scene-candidates artifact exists, the export also writes
+> per-scene notes under `Projects/<slug>/Scenes/<i>.md`.
+
+These fields are queryable in Obsidian via the [Dataview](https://blacksmithgu.github.io/obsidian-dataview/)
+plugin if you want to roll your own ad-hoc views.
+
+### Note body
+
+Below the frontmatter, each project note contains:
+
+- **Stage status** — current checkpoint and next action
+- **Character bindings** — referenced scene characters with stored Go Bananas IDs and reference assets
+- **Storyboard review** — link to `storyboard.md` plus review-state and freshness
+- **Recent events** — tail of `events/events.jsonl`
+- **Artifact links** — direct paths into the canonical JSON contracts
+- **Cost estimate** — if computed, the approval-gate cost and wall-time estimate
+
+---
+
+## The daily operator loop
+
+<p align="center"><img src="./assets/diagram-obsidian-loop.jpg" alt="Daily operator loop — five-step circular workflow: make changes via vclaw, sync vault, read Dashboard, triage queue, update metadata, then back to making changes" width="100%" /></p>
+
+A typical day for an operator running a multi-project portfolio:
+
+1. **Make changes** — use the CLI to advance work: `brief`, `storyboard`, `produce`, `review`, `publish`,
+   `set-meta`, `approve`, etc.
+2. **Sync the vault** — `vclaw video sync-obsidian` regenerates every dashboard note plus all project
+   notes from canonical state.
+3. **Read the Dashboard** — open `Dashboard.md`, then drill into `Active.md`, `Health.md`, and
+   `Needs Review.md` for the high-signal views.
+4. **Triage the queue** — open `Next Actions.md` to see the urgency-ordered action queue. Director-mode
+   approvals link straight to the active `storyboard.md`.
+5. **Update metadata** — change owners, priorities, due dates, blockers, or approval state via the CLI
+   (`set-meta`, `approve`). Repeat from step 2.
+
+The loop is intentionally one-directional: you never edit notes by hand and expect them to flow back to
+canonical state. The CLI is the only writer.
+
+---
+
+## Common workflows
+
+### "What needs my approval today?"
+
+1. `vclaw video sync-obsidian`
+2. Open `Needs Review.md`
+3. Click into each project; expand the linked `storyboard.md`
+4. Run `vclaw video approve --project <slug>` for the ones you sign off on
+5. Re-sync
+
+### "What's blocked and on whom?"
+
+1. Open `Blocked.md` for the explicit blockers
+2. Cross-reference with `Dependencies.md` for the blocker graph
+3. Use `set-meta --blocked-by <slug> --blocked-reason "<text>"` to update state from the CLI
+
+### "Who is overloaded?"
+
+1. Open `Owner Workload.md` for the owner-by-owner picture
+2. Sort by priority/due risk
+3. Reassign via `set-meta --owner <name>`
+
+### "What changed since yesterday?"
+
+1. Run `vclaw video report-snapshot` once a day to persist a baseline
+2. Open `Changes.md` for the diff narrative — this surfaces review-state transitions and snapshot deltas
+3. Use `report-diff --from <snapshot-path> --to <snapshot-path>` for explicit point-to-point comparison
+
+### "Is the portfolio healthy?"
+
+1. Open `Health.md` for the doctor-portfolio rollup
+2. Cross-reference `Metrics.md` for `byReviewState` and approval-queue depth
+3. Use `vclaw video doctor-project --project <slug>` to dive into a specific project
+
+---
+
+## Maintenance loop
+
+Recommended local rhythm:
+
+```bash
+vclaw video metrics                          # quick sanity check
+vclaw video next-actions                     # what's urgent
+vclaw video doctor-portfolio                 # health rollup
+vclaw video report-snapshot                  # persist baseline for diffs
+vclaw video sync-obsidian                    # regenerate the vault
+```
+
+Run after meaningful CLI changes. The packaged pre-flight is the safer alternative if you want to
+catch regressions before syncing:
+
+```bash
+npm run check:release-readiness-lite
+```
+
+---
+
+## Tips
+
+- **Treat the vault as a build artifact.** Don't hand-edit notes. Rebuild instead.
+- **Pin `Dashboard.md`** as the Obsidian default note so it's the first thing you see.
+- **One vault per mode** if you run both `storyboard` and `director` at scale — pass `--mode` to filter.
+- **Combine with [Dataview](https://blacksmithgu.github.io/obsidian-dataview/)** for custom queries on
+  the project frontmatter (e.g. *"show all director-mode projects with stale reviews owned by X"*).
+- **Version the vault** in a separate git repo if you need historical state — but remember canonical
+  history already lives in `events/events.jsonl` and `artifacts/history/`.
+
+---
+
+## Source of truth
+
+The repo state on disk is **always canonical**. The Obsidian vault is a regenerable view.
+
+If a vault note disagrees with the CLI, the CLI is right — re-sync. If the CLI disagrees with what
+actually shipped, the artifact JSON in `projects/<slug>/artifacts/` is right — let `doctor` find the
+drift.
+
+```text
+canonical state on disk
+        │
+        ▼
+    sync-obsidian       ← regenerates everything
+        │
+        ▼
+  Obsidian vault        ← view layer; safe to delete
+```
+
+---
+
+## See also
+
+- [`README.md`](../README.md) — repo front door
+- [`docs/SKILLS.md`](./SKILLS.md) — comprehensive skills reference
+- [`docs/OPERATIONS.md`](./OPERATIONS.md) — day-to-day maintenance loop, including the preview/delivery portal and the overnight batch video queue
+- [`docs/CLI_REFERENCE.md`](./CLI_REFERENCE.md) — full CLI surface

package/docs/OPERATIONS.md

@@ -0,0 +1,142 @@
+# Operations
+
+## Canonical project flow
+
+1. `video init`
+2. `video brief`
+3. `video storyboard`
+4. `video assets`
+5. `video review-ui` or `video review-autopilot` for production handoff; `video review --verdict pass` only when equivalent review evidence already exists
+6. `video publish`
+
+Publish handoff is canonical only when `review-report.json` has
+`verdict: "pass"` and `metrics.publishReady: true`.
+
+## Recommended maintenance loop
+
+1. Run `vclaw video metrics`
+2. Run `vclaw video next-actions`
+3. Run `vclaw video doctor-portfolio`
+4. Run `vclaw video report-snapshot`
+5. Run `vclaw video sync-obsidian`
+6. Run `npm run smoke:runtime` after meaningful runtime changes
+7. Run `npm run smoke:native-veo` after changing the built-in `veo-useapi` (native Veo) path
+8. Run `npm run smoke:character-hydration` after changing create-time cast hydration or approval-gate cost behavior
+9. Run `npm run smoke:execution-cancel` after changing adapter cancel behavior or the project-level cancel path
+10. Run `npm run smoke:portfolio` after changing index/report/CSV visibility
+11. Run `npm run check:movie-director-wrappers` after editing bundled Director helper scripts
+12. Run `npm run check:cleanroom-docs` after editing clean-room-facing docs and skills
+13. Run `npm run check:skill-frontdoor` after editing repo-local skill `SKILL.md` files
+14. Run `npm run check:artifact-schema-coverage` after editing JSON Schemas under `schemas/video/` or canonical artifact contracts
+15. Use `npm run check:release-readiness-lite` when you want the fast all-in-one local verification bundle, including the isolated image-storyboard E2E
+
+## Management views
+
+1. `metrics`: counts, rates, score averages
+2. `workload`: owner-by-owner project load
+3. `next-actions`: actionable queue ordered by urgency
+4. `dependencies`: blocker graph
+5. `report`: full machine-readable portfolio state
+6. `report-diff`: compare portfolio snapshots
+7. `trends`: historical trend points
+
+## Delivery (preview & delivery portal)
+
+The review/delivery portal is the ops surface for shipping finished work to clients:
+
+1. `portal --project <slug> [--client <name>] [--run <id>] [--surface edit|review|client-review|preview|compare|index]` generates the standardized HTML surface(s) locally.
+2. `publish-preview --project <slug> --client <name> --bucket <bucket> [--run <id>] [--surface ... (default preview)] [--public-base-url <url>] [--wrangler-bin <path>] [--dry-run]` builds a deterministic R2 upload plan from the HTML file and its local refs, then runs `wrangler r2 object put` per item; `--project`, `--client`, and `--bucket` are all required. Keys land under `clients/<client>/<project>/runs/<run>/` (each segment slugified).
+3. `publish-portal-index --bucket <bucket> [--client <name>] [--public-base-url <url>] [--wrangler-bin <path>] [--dry-run]` uploads a client or global index linking into the published run folders.
+
+See [`docs/preview-portal-audit.md`](./preview-portal-audit.md) for the full publish contract.
+
+## Overnight batch video queue
+
+For unattended, many-job backfill runs (e.g. consistency tests or draft fan-outs):
+
+1. `batch-submit --manifest <path> --out <dir> [--route runway-useapi|dreamina-useapi|seedance-direct]` compiles an operator manifest into one execution payload and persists `<dir>/batch-queue.json`. The default route is the **free** `runway-useapi` explore mode (low-res, slow); target `dreamina-useapi` or `seedance-direct` for paid hi-res.
+2. `batch-monitor --out <dir> [--once] [--max-minutes <n>]` polls, downloads completed scenes to `scene-<i>.mp4`, copies each to `clips/<jobId>.mp4`, and writes `<dir>/batch-status.json`. It is idempotent/resumable — re-running only advances `pending → done/failed` and never re-downloads completed clips, so `batch-monitor --out <dir> --once` is safe to schedule via launchd.
+3. `batch-status --out <dir>` reports the current queue state.
+
+## Health model
+
+Use these commands together:
+
+1. `doctor-project` for one project
+2. `doctor-portfolio` for all projects
+3. `readiness` to understand whether a project has the minimum artifacts required to move toward runtime execution
+4. `plan` to confirm the selected provider route
+5. `produce --dry-run` to validate the payload shape before live submission
+6. `produce` with a configured adapter to submit live work while keeping the assets stage `pending`
+7. `execute-status` to poll the adapter, ingest outputs, and advance the project to `review`
+8. `execute-cancel` to attempt to cancel an in-flight live job and mark the assets stage failed with an explicit operator action trail
+9. For `seedance-direct` and `veo-useapi`, prefer the built-in adapter path first and configure only `..._SUBMIT_CMD` / `..._POLL_CMD` / `..._CANCEL_CMD` unless you need a full custom adapter override
+10. For `seedance-direct`, you can now skip command shims entirely and rely on `SUTUI_API_KEY` plus the built-in native transport
+11. `clone-execute` is the shortest path for template-driven text-to-video work when you want clone planning and runtime execution in one command
+12. Use `set-execution-profile` when you need to retune ratio/quality/audio/outputs after the brief is already written
+13. Use `status`, `report`, `export-csv`, and Obsidian sync to verify the active execution profile, prompt guidance, review verdict, and publish-ready truth before expensive runs
+14. Use `cost-estimate` before live execution; it uses static defaults until completed Seedance USD telemetry exists, then reports `estimateSource: "historical-telemetry"`
+15. Inspect `projects/<slug>/events/events.jsonl` for `generation.telemetry.recorded` events when debugging provider costs, timings, failed polls, or output-ingest counts
+
+## Generation telemetry
+
+Live and dry-run execution append `generation.telemetry.recorded` events to the
+project event ledger. Submitted runs record route, task, prompt, duration, and
+reference-count metadata. Poll refreshes record pending/completed/failed status,
+output counts, provider cost fields, provider timing fields, and issues.
+
+Only completed `seedance-direct` records with provider-reported USD are used as
+cost-estimate samples. Credits are stored as telemetry but not converted to USD.
+
+Full guide: [`docs/GENERATION_TELEMETRY.md`](./GENERATION_TELEMETRY.md).
+
+`execution-plan` and `execute` remain available as compatibility aliases over
+`plan` and `produce`.
+
+## Project metadata expectations
+
+Recommended project metadata:
+
+1. `owner`
+2. `priority`
+3. `dueDate`
+4. `tags`
+5. `blockedBy`
+6. `blockedReason`
+
+## Reports and snapshots
+
+1. `report` gives the current full state
+2. `report` includes execution profile and prompt guidance when available
+3. `report-snapshot` persists the current state to `reports/history/`
+4. `report-history` lists snapshots
+5. `report-diff` compares snapshots
+6. `export-csv` writes spreadsheet-friendly exports
+
+## Reproducible smoke
+
+Use:
+
+```bash
+npm run smoke:runtime
+npm run smoke:native-veo
+npm run smoke:character-hydration
+npm run smoke:execution-cancel
+npm run smoke:portfolio
+npm run smoke:reference-sheets
+npm run smoke:scene-candidates
+npm run check:movie-director-wrappers
+npm run check:cleanroom-docs
+npm run check:skill-frontdoor
+npm run check:artifact-schema-coverage
+```
+
+This validates the documented local happy path and prints the generated machine-readable
+artifacts so runtime regressions are easier to spot than with tests alone.
+
+For a packaged one-command pass that builds once, runs the Node suite once, and
+then executes the main smokes, isolated image-storyboard E2E, and guardrails:
+
+```bash
+npm run check:release-readiness-lite
+```

package/docs/OPERATOR_HANDOFF.md

@@ -0,0 +1,108 @@
+# Operator Handoff
+
+Use this when handing `videoclaw` to someone who needs to run the video
+workflow, review work, or understand whether a project is safe to publish.
+
+Installed CLI examples use `vclaw`. In a source checkout, run `npm run build`
+first and replace `vclaw` with `node dist/cli/vclaw.js`.
+
+## The Four Workflows
+
+1. `video-production-handoff` moves one project from intent to review and
+   publish handoff.
+2. `video-review-ui-qa` checks browser review, mobile/desktop behavior, and CLI
+   alignment.
+3. `video-portfolio-ops` manages multiple projects, reports, CSV, and Obsidian
+   dashboards.
+4. `video-release-readiness` proves the repo/package is ready for handoff.
+
+These are workflow skills, not replacements for CLI commands. The command
+surface stays the same; the skills tell operators which commands to use and in
+what order.
+
+## 1. Start A Project
+
+```bash
+vclaw video create "A 20s product story for ..." --project <slug> --production-mode director
+vclaw video status --project <slug>
+vclaw video plan --project <slug>
+```
+
+The expected result is a project with canonical JSON artifacts under
+`projects/<slug>/artifacts/` and a clear next stage. If `plan` is blocked, use
+the blocker text directly; do not switch provider routes silently.
+
+## 2. Review The Work
+
+Use the browser station when a human needs to inspect stills, references, 4K
+handoff assets, or final assembly checks:
+
+```bash
+vclaw video review-ui --project <slug>
+```
+
+Use the non-interactive path only when completed storyboard still candidates
+already exist:
+
+```bash
+vclaw video review-autopilot --project <slug>
+```
+
+After either path, verify CLI truth:
+
+```bash
+vclaw video status --project <slug>
+vclaw video next-actions
+vclaw video doctor-project --project <slug>
+```
+
+Publish handoff is ready only when `review-report.json` has both:
+
+1. `verdict: "pass"`
+2. `metrics.publishReady: true`
+
+A stale checkpoint, marker-only 4K flag, or legacy pass report without
+`metrics.publishReady: true` is still review work.
+
+## 3. Manage The Portfolio
+
+```bash
+vclaw video metrics
+vclaw video next-actions
+vclaw video doctor-portfolio
+vclaw video report
+vclaw video export-csv
+vclaw video sync-obsidian
+```
+
+The CSV and Obsidian handoff should expose the same review truth as `status`:
+`reviewReportVerdict` and `reviewPublishReady`. If portfolio output disagrees
+with `doctor-project` or the Review UI, treat that as a product bug before
+spending provider time.
+
+## 4. Release Check
+
+Before handing off a repo build or package candidate:
+
+```bash
+npm run check:release-readiness-lite
+npm pack --dry-run --json
+git diff --check
+```
+
+The package dry-run must include docs, schemas, `dist/cli/`, `dist/video/`, the
+bundled Review UI, and shipped skills. It must exclude `projects/`, test output,
+generated verification artifacts, and `.tgz` archives.
+
+## What To Report
+
+For a clean handoff, report:
+
+1. project slug and current next action
+2. review verdict and `reviewPublishReady` value
+3. any doctor blockers
+4. portfolio export location if produced
+5. verification commands run and whether they passed
+
+Do not publish externally, delete projects, clear outputs, or run paid provider
+work unless that action is explicitly approved for the current handoff.