@vosjs/cli 0.83.0 → 0.83.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vosjs/cli",
-  "version": "0.83.0",
+  "version": "0.83.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/render-core": "^0.11.0",
     "@vosjs/shared": "^0.7.0",
     "@vosjs/elements": "^0.12.1",
     "@vosjs/editor": "^1.6.0",
+    "@vosjs/render-core": "^0.11.0",
     "@vosjs/studio-core": "^0.46.0",
-    "@vosjs/timeline": "^0.5.0",
-    "@vosjs/tween": "^0.8.3"
+    "@vosjs/tween": "^0.8.3",
+    "@vosjs/timeline": "^0.5.0"
   },
   "devDependencies": {
     "@types/node": "^22",

package/skills/VERSION

@@ -1 +1 @@
-0.27.0
+0.28.0

package/skills/product-video/SKILL.md

@@ -89,6 +89,25 @@ person before recording**; an answer that does neither was not an answer.
    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.
+   **Undo it in `teardown`** (`@vosjs/cli` 0.81 and later): the setup verbs,
+   run off camera after every rehearsal and take, and when one stops
+   early, so no rehearsal leaves a draft behind. When the video itself
+   deletes on camera what it made (a key created, then revoked), the
+   teardown is the net for a take that stopped before the delete: open it
+   with a guard on what the take created (`@vosjs/cli` 0.83 and later),
+   so a good take says `teardown: nothing to undo` instead of a failure.
+   ```json
+   "teardown": [
+     { "do": "press", "key": "Escape" },
+     { "do": "if", "selector": "[aria-label='Actions for CI deploy']" },
+     { "do": "click", "selector": "[aria-label='Actions for CI deploy']" },
+     { "do": "click", "selector": "role=menuitem[name='Revoke']" },
+     { "do": "click", "selector": "role=alertdialog >> role=button[name='Revoke']" }
+   ]
+   ```
+   A step that fails AFTER the guard is a real leftover: say it to the
+   person. Read the account back before you report (a `vos session exec`
+   script lists it) and say it holds what it held before.
 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
@@ -154,6 +173,17 @@ person before recording**; an answer that does neither was not an answer.
    steps as they are. Then the side-effect ledger (pre-flight, 3), then
    rehearse.
 
+   **Past what `look` reaches, script inside the session.** A state no
+   step reaches yet, what the account holds, a check after a flow: write
+   an ES module and run `vos session exec <app> script.mjs --url <page>`
+   (`@vosjs/cli` 0.81 and later). Its default export gets
+   `{ context, page, url, name }` on the profile exactly as `record` opens
+   it, and what it returns is printed. **Never open the session's profile
+   yourself** (Playwright's `launchPersistentContext`, a bundled Chromium, a
+   keychain flag): a browser that cannot read the profile's cookies starts
+   them over, the session is signed out for good, and the person signs in
+   again. Run one verb at a time on a session; two at once lock the profile.
+
    **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
@@ -250,6 +280,12 @@ person before recording**; an answer that does neither was not an answer.
    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.
+   **Recording again into a take you already cut** (a fixed step, a longer
+   hold, the product changed): add `--reuse` (`@vosjs/cli` 0.81 and later).
+   The new footage replaces the old and your cut (zooms, captions, layers,
+   cover, sound) is re-timed onto it in the same command; the last line
+   names what it kept and what could not follow. Without it the take is
+   planned fresh and the cut waits in `doc.prev.json`.
    (`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.)
@@ -302,9 +338,14 @@ person before recording**; an answer that does neither was not an answer.
    every zoom span is draggable.
 
 6c. **Pushing it to vos.so** (`vos push take`)? Set `still` in `doc.json`
-   (OUTPUT seconds) to the payoff first, the result the video is about,
-   never the opening: without one the cover is derived near the start,
-   usually a zoom on a navigation control under the first caption.
+   (OUTPUT seconds) to the payoff BEFORE the first push, the result the
+   video is about, never the opening: without one the cover is derived near
+   the start, usually a zoom on a navigation control or an empty field
+   under the first caption, and moving it after costs a second version.
+   `vos plan take --still <t>` writes it and `vos frames take --at-still`
+   shows it: look before the push. The push writes
+   `take/vos.json`: its `vosId` is the link (`https://vos.so/vos/<vosId>`).
+   Read the link there, never from filtered logs or a lookup script.
 
 7. **Package for the destination**: `references/destinations.md`.
 
@@ -383,3 +424,14 @@ when the ask is a release, not one video.
 - 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.
+- Opening a session's profile with your own Playwright: it signed a
+  founder's session out minutes after `vos look` had used it. Script
+  inside it with `vos session exec`.
+- Recording again into a cut take without `--reuse`: the fresh plan takes
+  the cut's place.
+- A teardown that undoes an on-camera delete with no `if` in front of its
+  undoing: every good take reports `TEARDOWN FAILED`, and a person learns
+  to ignore the line that one day is true.
+- Cutting a caption's `duration` because the plan said it outlasts its
+  step: the words then cannot be read. Shorten the words, or give the step
+  more `ms` and record again.

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

@@ -26,6 +26,13 @@ how-tos and the cuts a person had to redo on them.
    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.
+   It leaves when its step ends, or once its words are read when that is
+   later (17 characters a second, 1.2 to 3 s; `@vosjs/cli` 0.82 and later),
+   so a short caption on a quick step never lingers over the next one. A
+   caption the plan names as staying past its step has words that outrun
+   the beat: shorten them (an edit) or give the step more `ms` (a
+   re-record); never cut its `duration`, which takes the time its words
+   need to be read.
 
 3. **The result is the payoff, and the cold open.** Open on the finished
    result for a beat (a repeated segment at camera rest,

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

@@ -129,6 +129,19 @@ vos record --actions actions.json --out take --session acme --dry-run
 vos record --actions actions.json --out take --session acme --strict --json
 ```
 
+Anything else you need from the signed-in browser (what the account holds,
+a state no step reaches yet, a check that a flow cleaned up after itself)
+runs INSIDE the session (`@vosjs/cli` 0.81 and later):
+
+```bash
+vos session exec acme list-keys.mjs --url https://app.example.com/settings/keys
+```
+
+`list-keys.mjs` is an ES module whose default export receives
+`{ context, page, url, name }`, opened exactly as `record` opens the
+profile; what it returns is printed (`result` in `--json`). Never open the
+profile any other way: see the rules below.
+
 `--session` and `--storage-state` are two doors to one take; pass one.
 No file to mint, nothing in the take, nothing to delete: the profile lives
 under `~/.config/vos/sessions/` and `vos push` refuses a take that holds a
@@ -191,6 +204,13 @@ show, before anything is pushed further or handed over.
   mint again and it is a live credential for as long as it sits there.
 - **A session expires.** When a re-record that worked last week skips its
   first selector, re-walk the ladder before touching the script.
+- **Never open a session's profile yourself.** Not with Playwright's
+  `launchPersistentContext`, not with a bundled Chromium, not with a
+  keychain flag patched in. A browser that cannot decrypt the profile's
+  cookies starts the store over: measured, one such launch signed a session
+  out for the system Chrome too, and the person had to sign in again. Every
+  read goes through a vos verb (`look`, `record`, `session exec`), one at a
+  time: two verbs on one profile at once lock it.
 - **A person signing in will use their REAL account**, whatever you asked
   for: it is the one they have. The recorder looks for you (`@vosjs/cli`
   0.42 and later): the rehearsal ends with `EXPOSED in the frame`, naming

package/skills/vos-cut/SKILL.md

@@ -232,7 +232,9 @@ shows it): the result the cut is about, never the opening. Without one the
 cover is derived near the start, usually a zoom on a navigation control
 under the first caption.
 
-The base comes from `vos.json`. `409 stale_base` → `vos pull`, re-apply on
+The push writes `<take>/vos.json`: its `vosId` is the link
+(`https://vos.so/vos/<vosId>`); read it there, never from filtered logs or
+a lookup script. The base comes from `vos.json`. `409 stale_base` → `vos pull`, re-apply on
 top, push again. `409 protected_conflict` → keep the human's values unless
 the ask named that node (`--override <id>` only then). A 400 prints the
 field and its limit. Then `GET /api/vos/<id>`, follow