@vibeframe/cli 0.99.1 → 0.101.0

package/CONTEXT.md

@@ -8,13 +8,14 @@ a shell command. The same surface is exposed as MCP tools through
 
 For the full reference (every flag, default, enum), read
 [`docs/cli-reference.md`](../../docs/cli-reference.md) — auto-generated
-from `vibe schema --list`. This file is the *agent quickstart*: rules,
+from `vibe schema --list`. This file is the _agent quickstart_: rules,
 conventions, and discovery hooks.
 
 ## Discovery (use these first)
 
 ```bash
 vibe schema --list --json              # All commands with paths + descriptions
+vibe schema --list --surface public    # Small first-run/product command surface
 vibe schema <group>.<leaf> --json      # JSON Schema for one command
 vibe doctor --json                     # Configured API keys + filter availability
 vibe guide <topic> --json              # Step-by-step guides (motion | scene | pipeline)
@@ -29,7 +30,7 @@ vibe guide <topic> --json              # Step-by-step guides (motion | scene | p
 2. **`--dry-run` before any paid call** — returns a `costUsd` estimate
    in the JSON envelope without spending. Validates inputs.
 3. **`--stdin` for complex options** — `echo '{"key":"value"}' | vibe
-   <cmd> --stdin --json`. CLI flags still win on conflict.
+<cmd> --stdin --json`. CLI flags still win on conflict.
 4. **`--fields <list>`** — limit JSON output fields on read-heavy
    commands (e.g. `--fields "path,duration"`).
 5. **`--describe`** — print a command's JSON Schema and exit (no
@@ -37,30 +38,34 @@ vibe guide <topic> --json              # Step-by-step guides (motion | scene | p
 
 ## Cost tiers
 
-| Tier | Commands | Per-call cost |
-|------|----------|---------------|
-| Free | `detect *`, `edit silence-cut/fade/noise-reduce/text-overlay/interpolate`, `timeline *`, `scene lint/list-styles`, `audio duck` | $0 |
-| Low | `inspect *`, `audio transcribe/list-voices`, `generate image` | $0.01–0.10 |
-| High | `generate video`, `edit image`, `edit grade/reframe/speed-ramp` | $1–5 |
-| Very High | `remix *` (highlights, auto-shorts, regenerate-scene), `vibe build` (full pipeline) | $5–50+ |
+| Tier      | Commands                                                                                                                        | Per-call cost |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| Free      | `detect *`, `edit silence-cut/fade/noise-reduce/text-overlay/interpolate`, `timeline *`, `scene lint/list-styles`, `audio duck` | $0            |
+| Low       | `inspect *`, `audio transcribe/list-voices`, `generate image`                                                                   | $0.01–0.10    |
+| High      | `generate video`, `edit image`, `edit grade/reframe/speed-ramp`                                                                 | $1–5          |
+| Very High | `remix *` (highlights, auto-shorts, regenerate-scene), `vibe build` (full pipeline)                                             | $5–50+        |
 
 > Rule: **confirm with the user before any High / Very-High call**.
 
 ## JSON envelope
 
 ### Success
+
 ```json
 {
   "command": "<group> <leaf>",
   "elapsedMs": 12345,
   "costUsd": 0.07,
   "warnings": [],
-  "data": { /* command-specific */ },
+  "data": {
+    /* command-specific */
+  },
   "dryRun": true
 }
 ```
 
 ### Error (stderr)
+
 ```json
 {
   "success": false,
@@ -72,13 +77,13 @@ vibe guide <topic> --json              # Step-by-step guides (motion | scene | p
 }
 ```
 
-| Code | Exit | Meaning | Recovery |
-|------|------|---------|----------|
-| `USAGE_ERROR` | 2 | bad arg | check `vibe schema <cmd>` |
-| `NOT_FOUND` | 3 | file missing | verify path |
-| `AUTH_ERROR` | 4 | key missing/invalid | `vibe doctor` |
-| `API_ERROR` | 5 | provider failed | retry if `retryable: true` |
-| `NETWORK_ERROR` | 6 | connection | retry with backoff |
+| Code            | Exit | Meaning             | Recovery                   |
+| --------------- | ---- | ------------------- | -------------------------- |
+| `USAGE_ERROR`   | 2    | bad arg             | check `vibe schema <cmd>`  |
+| `NOT_FOUND`     | 3    | file missing        | verify path                |
+| `AUTH_ERROR`    | 4    | key missing/invalid | `vibe doctor`              |
+| `API_ERROR`     | 5    | provider failed     | retry if `retryable: true` |
+| `NETWORK_ERROR` | 6    | connection          | retry with backoff         |
 
 ## Authentication
 
@@ -107,13 +112,15 @@ export IMGBB_API_KEY="..."         # Local image upload (Seedance image-to-video
 The **storyboard project** is the primary product lane. `STORYBOARD.md`
 and `DESIGN.md` are the source of truth; generated files under
 `compositions/` are artifacts. Use `vibe storyboard *` for narrow cue
-edits and direct Markdown edits for larger creative rewrites. Use
+edits, and use `vibe storyboard revise --dry-run` for project-aware
+LLM revisions to `STORYBOARD.md`. Use direct Markdown edits for larger
+design rewrites. Use
 `vibe inspect project`, `vibe inspect render --cheap`, and `vibe scene repair`
 for deterministic local review and mechanical composition fixes. Semantic
 creative fixes belong to the host agent.
 
 ```
-init --from → storyboard validate → plan → build → inspect → render  # storyboard-to-video
+init --from → storyboard revise → storyboard validate → plan → build → inspect → render
 generate / edit / inspect / remix                          # one-shot media tools
 scene / timeline                                            # lower-level authoring
 run / agent / schema / context                              # automation + agents
@@ -126,20 +133,72 @@ CLI flag → per-beat STORYBOARD.md cue → vibe.config.json →
 legacy vibe.project.yaml → configured/env default → VibeFrame default
 ```
 
+Build planning contract:
+
+`vibe plan --json` emits `data.kind:"build-plan"`, `schemaVersion:"1"`,
+`status:"ready"|"invalid"`, `summary`, `providerResolution`, cache-aware
+per-asset plans, asset reference metadata (`sourcePath`, `referenceError`),
+`validation`, `retryWith`, and `nextCommands`. `backdrop`, `video`, `music`,
+`narration`, and generic `asset` cues may point at existing project-local media;
+those are planned as `reason:"referenced-asset"` with no provider spend, while
+invalid/out-of-project paths are surfaced before provider dispatch. `vibe plan`,
+`vibe build --dry-run`, and `vibe build` validate `STORYBOARD.md` before cost
+caps or provider dispatch. Invalid storyboards exit non-zero with
+`code:"STORYBOARD_VALIDATION_FAILED"` and `retryWith` entries for
+`storyboard validate` / `storyboard revise`.
+
+Build repair contract:
+
+Real `vibe build` runs deterministic scene repair after compose
+(sub-compositions only) and after sync (including root `index.html`) before
+render. Failed repair returns `code:"SCENE_REPAIR_FAILED"` and
+`sceneRepair:{ran,stage,status,score,fixed,remainingIssues,retryWith}`; use
+those `retryWith` commands before trying to render. `vibe scene repair`
+also repairs deterministic root timeline drift: clip refs, root duration, and
+root narration audio wiring.
+
+Asset stage failure contract:
+
+If assets fail during a full build, `vibe build` stops before compose/render
+and returns `currentStage:"assets"` with `code:"ASSET_REFERENCE_INVALID"`,
+`code:"MISSING_API_KEY"`, or `code:"ASSET_GENERATION_FAILED"` plus
+`suggestion`, `recoverable:true`, and `retryWith`.
+Compose failures use `code:"COMPOSE_FAILED"` and render failures use the
+render code or `code:"RENDER_FAILED"`; both include `currentStage`,
+`suggestion`, `recoverable:true`, and `retryWith`.
+
+Review report contract:
+
+`vibe inspect project` and `vibe inspect render` write
+`review-report.json` by default. The file uses `kind:"review"`,
+`mode:"project"|"render"`, `status`, `score`, `issues[]`,
+`summary:{issueCount,errorCount,warningCount,infoCount,fixOwners}`,
+`sourceReports`, and `retryWith`. Each issue has `fixOwner:"vibe"` for
+deterministic CLI recovery or `fixOwner:"host-agent"` for storyboard/design/
+composition edits the host agent should make. Use `retryWith` first, then
+hand remaining `host-agent` issues to the agent.
+
+Product surface contract:
+
+`vibe schema --list` includes `surface`, `replacement`, and `note`.
+Prefer `vibe schema --list --surface public` for first-run/product workflows.
+Use `legacy` commands only for compatibility and inspect `replacement` first.
+
 ## Per-group invariants
 
-| Group | Key rule |
-|-------|----------|
-| `generate` | Always `--dry-run` first. Costs money. `-p` selects provider; default routes via key availability. `--no-wait` returns local job ids. |
-| `edit` | FFmpeg-only leaves (silence-cut, fade, noise-reduce, text-overlay, interpolate) are free. caption/grade/reframe/image need API keys. |
-| `inspect` | `inspect project` and `inspect render --cheap` are local. Use `inspect render --ai` for final Gemini critique; Gemini media/review calls are low cost. |
-| `audio` | `transcribe` low cost (Whisper). `dub` is full pipeline (medium-high). `duck` is free. |
-| `remix` | **Confirm with user.** Multi-step, high cost ($5–50+). Always `--dry-run`. |
-| `detect` | Free, FFmpeg only. No keys. |
-| `project / timeline` | Free. All mutating leaves support `--dry-run`. |
-| `scene` | `lint` and `list-styles` free; `add` may invoke TTS + image-gen. |
-| `init / build / render` | Top-level project flow. `init` is idempotent (existing files preserved without `--force`). |
-| `status` | Free/local by default. Use `status job` and `status project` to inspect async jobs and latest build/review reports. |
+| Group                   | Key rule                                                                                                                                                                                                           |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `generate`              | Always `--dry-run` first. Costs money. `-p` selects provider; default routes via key availability. `--no-wait` returns local job ids.                                                                              |
+| `edit`                  | FFmpeg-only leaves (silence-cut, fade, noise-reduce, text-overlay, interpolate) are free. caption/grade/reframe/image need API keys.                                                                               |
+| `inspect`               | `inspect project` and `inspect render --cheap` are local. Use `inspect render --ai` for final Gemini critique; Gemini media/review calls are low cost.                                                             |
+| `audio`                 | `transcribe` low cost (Whisper). `dub` is full pipeline (medium-high). `duck` is free.                                                                                                                             |
+| `remix`                 | **Confirm with user.** Multi-step, high cost ($5–50+). Always `--dry-run`.                                                                                                                                         |
+| `detect`                | Free, FFmpeg only. No keys.                                                                                                                                                                                        |
+| `project / timeline`    | Free. All mutating leaves support `--dry-run`.                                                                                                                                                                     |
+| `scene`                 | `lint` and `list-styles` free; `add` may invoke TTS + image-gen.                                                                                                                                                   |
+| `init / build / render` | Top-level project flow. `init` is idempotent. `build --stage assets` may return async job ids for video/music cues; poll with `status project --refresh`. Real `build` auto-repairs scene artifacts before render. |
+| `storyboard`            | `list/get/set/move/validate` are local. `revise` uses a composer LLM, validates before writing, and should be run with `--dry-run` first.                                                                          |
+| `status`                | Free/local by default. `status job` returns a flat `kind:"job"` payload plus the raw record; `status project` returns `kind/status/currentStage/beats/jobs/build/review/retryWith` for resume decisions.           |
 
 ## Common patterns
 
@@ -148,7 +207,7 @@ legacy vibe.project.yaml → configured/env default → VibeFrame default
 ```bash
 vibe generate image "hero shot" -o hero.png --json
 vibe generate video "motion prompt" -i hero.png -o hero.mp4 --json
-vibe generate speech "narration text" -o voice.mp3 --json
+vibe generate narration "narration text" -o voice.mp3 --json
 vibe generate music "mood description" -o bgm.mp3 -d 10 --json
 ```
 
@@ -156,19 +215,39 @@ vibe generate music "mood description" -o bgm.mp3 -d 10 --json
 
 ```bash
 vibe init my-video --from "45-second launch video" --visual-style "Swiss Pulse" --json
+vibe storyboard revise my-video --from "make the hook sharper" --dry-run --json
 # edit my-video/STORYBOARD.md, my-video/DESIGN.md
 vibe storyboard validate my-video --json
 vibe plan my-video --json
 vibe build my-video --dry-run --max-cost 5 --json
 vibe build my-video --max-cost 5 --json
+vibe status project my-video --refresh --json  # when build returns pending-jobs
 vibe inspect project my-video --json
 vibe render my-video -o renders/final.mp4 --json
 vibe inspect render my-video --cheap --json
 vibe inspect render my-video --ai --json
+
+# Single-beat loop
+vibe build my-video --beat hook --stage sync --json
+vibe inspect project my-video --beat hook --json
+vibe render my-video --beat hook --json
+vibe inspect render my-video --beat hook --cheap --json
 vibe status project my-video --json
 vibe scene repair --project my-video --json
 ```
 
+### Machine status contract
+
+`build-report.json` keeps the detailed `beats[]` array and also includes `kind:"build"`, `status`, `currentStage`, `providerResolution`, `beatSummary`, `jobs[]`, `sceneRepair`, `stageReports`, `warnings`, and `retryWith`. Each beat keeps legacy flat asset fields and nested `narration`, `backdrop`, `video`, and `music` objects with provider/path/status/sourcePath/cache metadata, plus a nested `composition` object with path/existence/status/cacheKey visibility. `render-report.json` records the latest render output, including `beat` when `vibe render --beat <id>` is used.
+
+`vibe status job --json` emits the normal success envelope with `data.kind:"job"`, flat job fields (`id`, `jobType`, `provider`, `status`, timestamps), `progress`, `result`, `retryWith`, and the raw `job` record for compatibility.
+
+`vibe status project --json` emits `data.kind:"project"`, `status`, `currentStage`, `beats:{total,assetsReady,compositionsReady,needsAuthor}`, `jobs.latest`, `build`, `review`, `warnings`, and `retryWith`. `review` includes `mode`, `issueCount`, `errorCount`, `warningCount`, `infoCount`, `fixOwners`, `sourceReports`, and its own `retryWith`; top-level `retryWith` carries the next resume command. Use `retryWith` rather than guessing the next command.
+
+### Storyboard revision contract
+
+`vibe storyboard revise --json` emits `data.kind:"storyboard-revision"`, `provider`, `summary`, `changedBeats`, `validation`, `wrote`, `warnings`, and `retryWith`. On failure it does not write `STORYBOARD.md`; inspect `data.code`, `data.message`, and `data.retryWith`.
+
 ### Lower-level timeline (NLE-style)
 
 ```bash