@vosjs/cli 0.81.0 → 0.81.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vosjs/cli",
-  "version": "0.81.0",
+  "version": "0.81.1",
   "description": "The vos CLI: record the real product from a scripted browser flow, auto-zoom from the cursor track, cut as data in doc.json, render deterministic video, deliver a release's video cuts per destination spec, and sync with vos.so. One binary, every verb, MIT.",
   "type": "module",
   "license": "MIT",
@@ -52,13 +52,13 @@
     "mediabunny": "^1.55.7",
     "playwright": "^1.49.0",
     "@vosjs/core": "^0.31.0",
-    "@vosjs/editor": "^1.6.0",
     "@vosjs/elements": "^0.12.1",
+    "@vosjs/editor": "^1.6.0",
     "@vosjs/shared": "^0.7.0",
     "@vosjs/render-core": "^0.10.0",
     "@vosjs/studio-core": "^0.46.0",
-    "@vosjs/tween": "^0.8.3",
-    "@vosjs/timeline": "^0.5.0"
+    "@vosjs/timeline": "^0.5.0",
+    "@vosjs/tween": "^0.8.3"
   },
   "devDependencies": {
     "@types/node": "^22",

package/skills/VERSION

@@ -1 +1 @@
-0.26.0
+0.27.0

package/skills/launch-kit/SKILL.md

@@ -244,3 +244,10 @@ by data. Never spread before the seed is signed off.
 - A hand-typed dimension: every size comes from `channel-specs.json`.
 - The save beat on a demo instance that disables writes: say so in
   `skipped`, never fake the click.
+- A zoom trusted because the track lists it: `frames --at-zooms` renders
+  each apex beside its zoom-off twin and names one that matches; read the
+  stills before `deliver`, never the list.
+- A rehearsal that presses a step that spends or creates in the shipped
+  product: `--dry-run` CLICKS. Guard the spend (`"guard": "spend"` + `id`,
+  recorded only with `--confirm <id>`) and write the side-effect ledger
+  before the first rehearsal (the `product-video` skill's pre-flight).

package/skills/product-video/SKILL.md

@@ -52,6 +52,69 @@ failure / 3 no browser / 4 the recorder met a sign-in instead of the page
 | **Quick demo** (issue, PR, chat) | 1280×720 | webm, defaults | speed over polish; drafts acceptable here ONLY |
 
 Per-channel dimensions and byte budgets: `references/destinations.md`.
+A **how-to** (one flow in a product, from a door to its result, for a docs
+page or a changelog) takes the quick demo's viewport or the launch video's,
+and its own grammar: `references/how-to.md`.
+
+## Pre-flight: six answers before the first take
+
+A flow in somebody's product has consequences the footage does not show:
+two rehearsals left two untitled drafts in a founder's projects and both
+appeared in the recorded sidebar; a rehearsal that reaches "Generate"
+spends a credit; a result that arrives twelve minutes later is a second
+take without a plan for it. Answer these BEFORE `vos look`, the script or a
+rehearsal. **Each answer either changes the script or is said to the
+person before recording**; an answer that does neither was not an answer.
+
+1. **The door.** Which way through the product does the video walk, and
+   which others exist (a guided flow, a prompt box, an apps menu, a
+   template)? A how-to walks ONE. When there are several, list them and
+   confirm the door with the person before scripting; a door that works
+   under automation beats a recommended one that does not, and hiding the
+   automation from the site is never the answer (find another door, or
+   hand the shot list to a person: `references/sessions.md`, rung 4).
+2. **Whose account, face and work.** What the signed-in account shows ships
+   in the video: its avatar, its name, its recent items, the titles of its
+   other projects. A demo account is the answer; when the person records
+   from their own, say what will show before the take. The rehearsal
+   reports an address, a key or a card as EXPOSED (mask those), and the
+   account's own name and its recent lists as NOTICES: those are the
+   person's call. Say they will be on screen and offer the one-line `mask`;
+   never mask a name by default, and a face is yours to notice and theirs
+   to decide.
+3. **What the flow CREATES.** Write the side-effect ledger: for each step,
+   what it leaves in the product (a draft, a project, a message, a file, a
+   row), remembering that `--dry-run` CLICKS, so every rehearsal creates
+   them too. Say the ledger to the person before the first rehearsal when
+   the product is a real account, and report it at the end so they can
+   delete what was made. A product where creating is cheap (a sandbox, a
+   seeded local instance) needs the ledger written, not asked.
+4. **What it SPENDS.** A step that costs something real (a generation, a
+   purchase, a message sent, a deploy) carries `"guard": "spend"` and an
+   `id`. A rehearsal hovers it and never presses it; `vos record` refuses
+   the take before a browser opens unless the command names the step
+   (`--confirm <id>`), and the done event records that it was pressed.
+   Name the spend to the person in words ("one generation") and get the
+   yes before the record; the consent then lives in the file and the
+   command line, where a reviewer can read it.
+5. **Is the result async, and how long.** A product that finishes later (a
+   render, a generation, a deploy) is ONE take with an `await` step: the
+   capture stops, the page is polled off camera, the capture resumes when
+   the predicate holds, and the cut carries the measured time
+   (`{elapsed}` in the next caption; `references/how-to.md`). Wait for
+   what only the NEW result has (a percentage that appears, then goes;
+   never a title an older item shares), size `timeout` from what the
+   product measured last time, and `download` the output into
+   `take/outputs/` so the join can play it. On the hosted recorder the
+   waits come out of the footage cap: say how long before choosing it.
+6. **Does sound matter.** The recorder captures frames. Sound a page plays
+   through a `<video>` or `<audio>` element is kept (`@vosjs/cli` 0.79 and
+   later: each heard source lands in `meta.media` and the plan places a
+   clip per interval); sound a page synthesizes with Web Audio is not
+   heard, and a downloaded output's own sound rides as a clip through
+   `vos join`. When the sound IS the point (a voice preview, a generated
+   clip) and the product synthesizes it, say so before recording and plan
+   the download; when it is not, say the video is silent and score it.
 
 ## The core loop (every destination)
 
@@ -81,6 +144,16 @@ Per-channel dimensions and byte budgets: `references/destinations.md`.
    take directory and out of git, and record from a demo account: what the
    account shows ships in the video.
 
+   **Never script a signed-in page blind.** `vos look <url> --session <app>`
+   (or `--storage-state`; `@vosjs/cli` 0.78 and later) opens the page
+   through the door the recorder will use and prints a screenshot plus
+   every control in view with ONE proposed selector each, counted UNIQUE
+   or AMBIGUOUS by the recorder's own engine; `--click <selector>` shows
+   what a click opens before the script relies on it, and refuses a control
+   whose words mean spend, delete or submit. Take UNIQUE selectors into
+   steps as they are. Then the side-effect ledger (pre-flight, 3), then
+   rehearse.
+
    **Verified the feature with agent-browser already?** Keep that walk and
    skip the second script. agent-browser's `--json` result does not say
    what ran (`scroll` answers `{scrolled:true}`), so wrap each call so the
@@ -170,9 +243,13 @@ Per-channel dimensions and byte budgets: `references/destinations.md`.
    `references/sessions.md`.
 
 3. **Record**: `vos record --actions actions.json --out take --strict --json`
-   `--strict` always: skipped selector / networkidle timeout → exit 2 with
-   `skipped[]` in the done event. A skip means the flow is broken — fix it,
-   never ship around it. The take auto-encodes and auto-plans.
+   `--strict` always: a skipped selector, a failed `expect`, a click on a
+   disabled control, a timed-out `await` or a capped take → exit 2 with
+   `skipped[]` in the done event (a first load that never goes network-idle
+   is a note, not a failure, since `@vosjs/cli` 0.78). A skip means the
+   flow is broken — fix it, never ship around it. A guarded step records
+   only with `--confirm <id>` (pre-flight, 4). The take auto-encodes and
+   auto-plans.
    (`vos create --actions actions.json out.webm --strict` is the one-shot
    record+render verb — fine for a quick first pass, but THIS skill's loop
    reviews frames before rendering, so prefer the separate verbs here.)
@@ -295,3 +372,14 @@ when the ask is a release, not one video.
   one per gesture): mark the payoff steps and plan `--zooms per-beat`.
 - Trusting `--strict` for the scene: it proves the steps ran, not that the
   app holds what the beat shows. Check with `expect` + `js` + `equals`.
+- Trusting a zoom because the track lists it: two of a film's four zooms
+  never rendered and the list said they did. `frames --at-zooms` renders
+  each apex beside its zoom-off twin and names an apex that matches its
+  twin; read the stills, never the list.
+- A rehearsal that presses a step that spends: `--dry-run` CLICKS. A
+  spending step carries `"guard": "spend"` and an `id`, so the rehearsal
+  hovers it and `record` refuses it without `--confirm <id>`; a step that
+  only creates goes in the side-effect ledger before the first rehearsal.
+- Scripting a signed-in product blind: `vos look` first, then the ledger,
+  then the rehearsal. Guessing selectors from a public page costs a take
+  per guess.

package/skills/product-video/references/how-to.md

@@ -0,0 +1,78 @@
+# The how-to: one flow, one door, the result first
+
+A how-to shows a person how to reach ONE result in a product: "make a
+cinematic shot in HeyGen", "put a video on vos.so". It is the clip a docs
+page, a changelog entry or a support answer embeds, and it is judged by
+whether a viewer can repeat the path. The marketing rules in `taste.md`
+still hold (one idea, open on the money shot, end settled); these are the
+rules that are specific to the genre. They came out of three agent-made
+how-tos and the cuts a person had to redo on them.
+
+## The grammar
+
+1. **One door.** A product usually has several ways to the same result
+   (a guided flow, a prompt box, an apps menu, a template). The video walks
+   ONE, and the person named it before the script was written (the
+   pre-flight in `SKILL.md`). Two doors in one clip read as two videos;
+   a door that works under automation beats the recommended one that does
+   not (never hide the automation from a site; pick the door that works, or
+   hand the shot list to a person).
+
+2. **One caption per step, in the product's own words for the control.**
+   The caption names the control the way the product labels it, as a verb
+   phrase: "Open Apps", "Choose Cinematic Shots", "Press Generate". Not a
+   sentence about the feature, not marketing copy, nothing the footage does
+   not show. It sits on the step whose action it describes (`caption` on
+   the step in `actions.json`; `vos plan` and `vos join --captions` land
+   each one anchored to its step, so a re-record carries it). One caption
+   is one beat; a step with no caption is part of the beat before it.
+
+3. **The result is the payoff, and the cold open.** Open on the finished
+   result for a beat (a repeated segment at camera rest,
+   `segments[].camera: "rest"`, the `vos-cut` skill's "Assemble"), then
+   the path from the door, then the result again, settled, as the last
+   frame. The result's step is the beat marked `"zoom": true`; the path's
+   clicks stay wide unless one of them is the point. `still` sits on the
+   result, never on the door.
+
+4. **A recap card that lists the path.** The last thing on screen is the
+   path as a list, in the captions' own words, in order ("Apps → Cinematic
+   Shots → Describe the shot → Generate"), on the plate after the card
+   fades (`frame.anim.exit: "fade"` plus layers past the footage), never
+   over a frozen frame. A viewer who looked away for the middle leaves with
+   the path.
+
+5. **Measured times only.** When the product takes time off camera (`await`
+   in the script), the cut says how long it took in the words the
+   measurement gives: `{elapsed}` in the caption after the wait prints the
+   measured time ("8 minutes later, the shot is ready"), or write the
+   number read from `meta.skips[].ms` ("About 8 minutes later"). Never a
+   round number nobody measured, never "instantly" or "in seconds", and
+   never a speed read off a capture (the recorder loads the page too).
+
+6. **Music lands on the result.** `vos score --track <slug> --at <result
+   step id>` puts the track's swell on the payoff; a how-to with a voice
+   or the product's own sound (a generated video playing) keeps the bed
+   under it (`--gain`). The downloaded output's own sound rides as a clip
+   through `vos join`.
+
+7. **As long as its path.** A how-to is not held to the 30 s marketing
+   band; it is held to its beats: about 1 s of reading after a page
+   changes, 0.6 s after a control, the waits cut out, nothing padded.
+   Run 3's how-to was 36 s for seven steps and an 8-minute generation.
+
+## The checks, in order
+
+```bash
+vos validate actions.json                     # the captions sit on the steps they describe
+vos record --actions actions.json --out take --dry-run   # the door opens, the guard hovers, the wait is timed
+vos record --actions actions.json --out take --strict --json --confirm <spend id>
+vos plan take --zooms per-beat --still <result output s>
+vos frames take --at-zooms                    # every apex beside its zoom-off twin
+vos frames take --times <each caption start + 1>   # every caption on its own ground, in the product's words
+vos check-video out.mp4                       # one cut per 5 s at most, the first and last frames stand alone
+```
+
+A caption the footage does not show, a time that was not measured, a second
+door, or a result that is not the first and last frame each send the cut
+back a round, not the recording.

package/skills/product-video/references/taste.md

@@ -25,6 +25,10 @@ The rubric for judging a take before its render ships. Judge stills
    Launch videos may run longer but every scene must still earn its seconds.
 3. **End settled.** Close on a resolved state (result visible, motion parked),
    never mid-action — the loop point should read as intentional.
+   A **how-to** (one flow to one result, for a docs page or a changelog)
+   keeps all three and adds its own: one door, one caption per step in
+   the product's words for the control, the result as the cold open and
+   the last frame, a recap card, measured times only (`how-to.md`).
 
 ## Flow authoring (actions.json)
 

package/skills/product-video/references/troubleshooting.md

@@ -49,14 +49,18 @@ selector matched no element, so whatever it was for may be showing.
 
 ## Strict-mode failures (exit 2)
 
-`vos record --strict` exits 2 when a selector was skipped or a navigation
-never reached networkidle, with `skipped[]` in the `--json` done event.
+`vos record --strict` exits 2 when a selector was skipped, an `expect`
+failed, a click landed on a disabled control, an `await` timed out or the
+take hit its cap, with `skipped[]` in the `--json` done event.
 
 - A skipped selector means the flow is broken: the element wasn't there, the
   selector is unstable (nth-child chains), or the page needed more settle
   time. Fix the actions.json — never ship a take that silently skipped steps.
-- Networkidle timeouts on pages with long-polling/websockets: add explicit
-  `wait` steps after navigation instead of relying on networkidle.
+- A first load that never goes network-idle (long-polling, websockets: most
+  SaaS) is a note (`navTimeout`), never a strict failure, since `@vosjs/cli`
+  0.78, and since 0.79 a take starts once the DOM has stopped changing
+  (`ready: "dom"`, the default; `networkidle` is the opt-in). On an older
+  CLI, add explicit `wait` steps after navigation instead of relying on it.
 - Always pass `--strict`. The lenient default exits 0 over broken flows,
   which is how bad takes ship.
 

package/skills/vos-cut/SKILL.md

@@ -102,6 +102,27 @@ video PLAYING, not idle. Neither wants the planner's proposal.
 If a folder is involved, read EVERY `.md` in it (own and inherited) before
 you decide anything.
 
+**Before the first cut, four answers from the frames** (a human's take has
+no mask and no exposure list; the scan needs the page):
+
+1. **Whose account, face and work is on screen.** An address, a key or a
+   card in a frame is said before anything is pushed, and the honest fix
+   is a re-record from a demo account, since a blur in `doc.json` leaves
+   the value in the footage `vos push` uploads. The person's own name,
+   face, avatar and recent items are theirs to show: say they are on
+   screen, never treat them as a defect.
+2. **Which door the footage walks.** A how-to names ONE way to the result.
+   A recording that wanders through two (a guided flow abandoned for an
+   apps menu) is cut to the one that reached the result, and the note says
+   which.
+3. **Where time was skipped.** A scripted take's off-camera wait is in
+   `meta.skips` and `vos info` prints it; the caption after it carries the
+   MEASURED time, never a round number nobody measured.
+4. **What the sound is.** The take's own sound (a mic), the sound the page
+   played (`meta.media`, placed as `source: "page"` clips by the plan),
+   the sound a downloaded output brought through `vos join`. The cut keeps
+   a sound the beat is about and never speeds over it.
+
 ## 2. Narrate
 
 Write 3-6 beats into your working notes, each with its moment ids, what it
@@ -163,6 +184,16 @@ Per beat, against `plan` and the recipe:
   light (an editor's timeline is), and judge every caption at its own
   instant. One caption per film is too sparse for a film that explains a
   flow; zero is right only when the recipe or the ask says no text.
+- **A how-to** (one flow to one result, for a docs page or a changelog)
+  has a grammar of its own: one caption per STEP, in the product's own
+  words for the control as a verb phrase ("Open Apps", "Press Generate"),
+  anchored to the step (`anchor: { step }`) so a re-record carries it;
+  the result as the cold open (a repeated segment at camera rest) and as
+  the last frame, with `still` on it and the one `"zoom": true` mark;
+  a recap card listing the path in the captions' words on the plate after
+  the card fades; an off-camera wait said in measured time (`{elapsed}`
+  in the caption after it); music scored `--at` the result's step. Never
+  a caption the footage does not show, never a second door.
 - **Style.** In a series, `vos plan --style <seed>` BEFORE you cut: it copies
   the seed's `zoomStyle`/`zoomParams`/`speedParams`/`tiltStyle`/`frame`/
   `cursor`/`cam`/`export` and re-plans the auto spans under them. Never
@@ -254,6 +285,9 @@ never write a status line.
   start, under the first caption);
 - open a zoom before the click it frames, or aim it at a `type` verb's
   field centre (frame the text; start the span after the click);
+- trust a zoom because the track lists it: `frames --at-zooms` renders
+  each apex beside its zoom-off twin and names one that matches its twin;
+  a listed zoom that never rendered has shipped in a film before;
 - leave the cold open frozen (a static page records as freeze-then-bang:
   trim it, or speed the load);
 - end wide on an empty page: the last frame is the poster, so the closing