@vosjs/cli 0.47.0 → 0.48.0

package/skills/product-video/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: product-video
+description: Record and produce the demo video of a website, app, or feature with the vos CLI — the agent scripts the click path (actions.json), the recording auto-plans zooms, and every editing decision is data in doc.json, so fixes are edits and re-renders, never re-recordings. Renders are deterministic; export is free up to 4K with no watermark. Use when asked to make a product video, demo video, screen recording of a URL or feature, or a marketing clip, including a product behind a login (the session ladder: mint one from the project's own test auth before asking anyone), or when a feature was verified in agent-browser and that walk should become a take. A whole release's asset set (store listing, Product Hunt gallery, social cuts) is the launch-kit skill, which records through this one.
+license: MIT
+---
+
+# Product video (and the assets around it), end to end
+
+You are producing a shippable product asset — a polished video, a set of
+exact-size stills, or both — from a live web page, with the `vos` CLI.
+Everything is data: you write a flow script, the CLI records and plans, you
+tune JSON, you re-render. **Never re-record to fix pacing or zooms — edit
+`doc.json` and render again.** Quality bar: `references/taste.md` — follow
+its quality loop and judge stills multimodally.
+
+## Setup
+
+```bash
+npm i -D @vosjs/cli
+```
+
+One command, one package: `@vosjs/cli` is the open source (MIT) `vos`
+binary with the engine verbs, the take pipeline used here (record / plan /
+frames / render on screen recordings) and the vos.so platform verbs. (Until
+0.9 the take pipeline shipped separately as `@vosso/vos-plugin`; a project
+that still lists it can drop it.) Requirements:
+
+- **A Chromium**: system Chrome is found automatically; otherwise
+  `npx playwright install chromium` or point `VOS_BROWSER_PATH` at one.
+  Exit code 3 means no browser was found.
+- **Network at render time**: the render page loads three/mediabunny from
+  esm.sh. Recording also needs to reach the target URL. Fully offline
+  sandboxes cannot render — say so instead of shipping nothing.
+
+Conventions: logs → stderr, results → stdout; `--json` streams NDJSON ending
+with `{"event":"done",…}`; exit codes 0 ok / 1 error / 2 usage or strict
+failure / 3 no browser / 4 the recorder met a sign-in instead of the page
+(a missing or expired SESSION, never a script bug: `references/sessions.md`).
+`vos <verb> --help` prints that verb's flags (`@vosjs/cli` 0.41.1 and later).
+
+## Step 0 — pick the destination (it decides everything)
+
+| Destination | Viewport | Output | Extras |
+|---|---|---|---|
+| **Landing-page clip** (hero/section embed) | 2560×1440 (footage-native 2K) | webm → VP9 re-encode + poster | silent loop; see `references/destinations.md` |
+| **Launch video** (PH, social, store promo) | 2560×1440 or 1280×720 | mp4 (`--format mp4`, needs system Chrome) | music bed via `doc.audio` |
+| **Launch-kit stills** (store screenshots, tiles, OG) | sized to the asset | `frames --frame <t> --size WxH` PNGs from the same take | one take → every asset |
+| **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`.
+
+## The core loop (every destination)
+
+1. **Explore the target page** with your own tools (fetch HTML / Playwright).
+   Identify the 3–6 moments that tell ONE story. Collect STABLE selectors
+   (`a[href='…']`, ids, roles — not nth-child chains).
+   **Stage the content like a set**: the script must leave the product in
+   the state a proud screenshot would show — labels typed, real-looking
+   data, the feature mid-story. An empty canvas records fast and demos
+   nothing, and no downstream composition rescues it.
+
+   **Behind a login? Settle the session before the script.** A recorder
+   with no session records the wall (the sign-in page, or the public page
+   the site sends a stranger to) and the only symptom is a skipped
+   selector. Walk the ladder in `references/sessions.md` top to bottom and
+   stop at the first rung that holds: no wall (a demo mode, a local server
+   with auth off) → MINT a session from the test auth the project already
+   has (`playwright/.auth`, an `auth.setup.ts`, a seed script: look before
+   you ask anyone anything) → sign in off camera with `setup` in
+   `actions.json` (the password from `{ "env": "NAME" }`, never a literal) →
+   the human signs in once (`vos session open <url> --name <app>`, then
+   `--session <app>` on record) → the human records with the extension from the shot list
+   `vos actions script actions.json` prints, and you cut it. Every
+   rung ends in `setup`, a state file for `--storage-state`, or a named
+   session for `--session`. Never
+   type or accept a production password, keep the state file out of the
+   take directory and out of git, and record from a demo account: what the
+   account shows ships in the video.
+
+   **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
+   command rides beside its result, then convert:
+   ```bash
+   ab() { agent-browser "$@" --json | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const r=JSON.parse(s);process.stdout.write(JSON.stringify({command:process.argv.slice(1),...r})+"\n")})' -- "$@" >> steps.jsonl; }
+   ab open https://target.example; ab snapshot -i -u; ab click @e27
+   ab wait 800; ab snapshot -i          # the page changed: refs renumbered
+   ab fill @e2 query; ab press Enter
+   vos actions from-agent-browser steps.jsonl --out actions.json
+   ```
+   (a whole path run as one `agent-browser batch … --json > steps.jsonl`
+   already has that shape). The log is `steps.jsonl` in the directory you
+   stand in, so walk from one directory. Refs resolve through the last
+   `snapshot -i` before them, and they RENUMBER after a navigation and
+   again inside a dialog: re-snapshot after anything that changes the page
+   and read the refs before you name one (`-u` gives links their href).
+   Click the control, do not press its shortcut: ⌘K opens the dialog for a
+   human, but a keystroke is the one step the recorder cannot replay.
+   Whatever it cannot follow (a shortcut key, a drag, a second `open`) is
+   NAMED in the output, never dropped: read the notes, write those steps by
+   hand, then record.
+
+2. **Write `actions.json`**:
+   ```json
+   {
+     "url": "https://target.example",
+     "viewport": { "width": 1280, "height": 720 },
+     "steps": [
+       { "do": "wait", "ms": 800 },
+       { "do": "hover", "selector": "a[href='/pricing']", "ms": 700 },
+       { "do": "click", "selector": "#cta" },
+       { "do": "wait", "ms": 1500 },
+       { "do": "scroll", "dy": 400 },
+       { "do": "move", "x": 640, "y": 320 },
+       { "do": "wait", "ms": 900 }
+     ]
+   }
+   ```
+   Verbs: `wait` `hover` `click` `type` `scroll` `move` `drag`
+   (`type` = `{do:'type', selector, text, delayMs?, ms?, focus?}`: it clicks
+   the field, then types `text`; `focus:false` types into what is already
+   focused, for a submitting Enter)
+   (drag = real edits: `{do:'drag', selector|x,y, tx, ty, ms}` — slide a range
+   input, drag a canvas element, move a timeline clip). Pacing IS the zoom
+   plan: open `wait ≥700ms`; hover what matters 700–900ms (dwells become
+   zooms); a click's `ms` is READING time, held from the page's last change
+   (`@vosjs/cli` 0.47 and later; the recorder pays the settle itself), so
+   size it as a beat: about 1000ms after a navigation, 600ms after a
+   control, never padded for a slow page; end settled. Route the cursor away
+   from hover-triggered menus (taste.md, flow rules). Check with
+   `vos validate actions.json`.
+
+   Then REHEARSE it (`@vosjs/cli` 0.39 and later):
+   `vos record --actions actions.json --out take --dry-run`. Every step runs
+   against the real page, in order, because a later selector usually exists
+   only after an earlier click, but nothing is captured and nothing is
+   written: a missed selector is named in seconds (exit 2) instead of after
+   a real-time take and its encode, and a take already in `--out` keeps its
+   footage and its cut. It prints each step's rect in capture px, which is
+   what a pinned layer reads. Rehearse again after every script edit, and
+   record only a script that passes. A signed-in product rehearses the same
+   way: `--storage-state` and `--browser-arg=` apply to it too, and the
+   rehearsal ends by listing what the frame EXPOSES (an address, a key, a
+   card). Hide those with `mask` before you record:
+   `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.
+   (`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.)
+
+4. **Tune `doc.json`** (JSON Schema ships in the `@vosjs/cli` npm package:
+   `schema/doc.schema.json`):
+   - `zoom`: `[{in, out, level, cx, cy, source}]`, SOURCE seconds; levels
+     1.4–2.8; `cx/cy` NORMALIZED [0..1] (0.5,0.5 = center) — NOT pixels; set
+     `"source": "manual"` on spans you touch (survives re-plan).
+   - `segments` (trims) · `speed` (`rate` 0.1–16) · `frame.*` · `cursor`.
+   - `tilt`: `[{in, out, rx, ry, source}]`, SOURCE seconds — the 3D card
+     leans to the pose while active, returns to rest between. DEGREES
+     (±5..18 reads premium): +rx = top edge closer, +ry = left edge closer
+     (lean toward a right-side focus = negative `ry`). Spans ≥ 0.8s;
+     pair with zoom moments (same in/out chains the moves), one pose change
+     per ~5s beat. `"source": "manual"` on spans you touch;
+     `tiltStyle: "subtle"|"medium"|"strong"` records the auto wand.
+   - `frame.backgroundMedia`: a video loop / image behind the card —
+     `{"kind":"video","key":"/bg.webm","duration":10,"dim":0.2}`.
+     `key` = a file dropped in the take dir (`"/bg.webm"`) or a media URL;
+     video needs `duration` (OUTPUT-anchored modulo loop); `dim` 0..1 scrim.
+     Ambience, not a subject — dim it behind dense UI.
+   - `audio`: OUTPUT-anchored clips; `key` may be a file dropped into the
+     take dir (`"/music.mp3"`); gain/fades/loop. Muxed on full renders
+     (Opus/AAC); `--range` stays silent; forces single-flight.
+   - export: `{"resolution": "720p|1080p|2k|4k", "fps": 30}` — never above
+     the footage (validate warns).
+   Then `vos validate take --json` — lints must pass.
+
+5. **Look before you render** (the taste.md quality loop):
+   - `vos frames take --at-zooms --times 0,25%,50%,75%,100% --json` → judge
+     every still against taste.md, zoom apexes hardest.
+   - Iterate: edit doc.json → `vos render take check.webm --range a..b --draft`
+     (seconds, half res — never ship drafts) → re-frame the changed region.
+   - **Trying a presentation? Use a flag, not a scratch script.** `render`/`frames`
+     take doc overrides — `--set <path>=<value>` (repeatable; JSON-or-string),
+     `--frame <macos|windows|minimal|none>` (render), `--background <url>` — that
+     patch the doc in memory (doc.json untouched) and are lint-gated. So
+     `vos frames take --frame 2.0 --set frame.browserBar.kind=mac-light --set tilt[0].rx=8`
+     previews a framed, tilted card without touching the file.
+
+6. **Final render**: `vos render take out.webm --json` (or `--format mp4`).
+   Re-frame the final (`frames --at-zooms`) against taste.md before declaring
+   done. Renders are deterministic — only your edits change the output.
+
+6b. **Human review round** (when the ask involves one): `vos open take`
+   serves the take into the studio — your doc.json edits arrive intact and
+   every zoom span is draggable.
+
+7. **Package for the destination**: `references/destinations.md`.
+
+## Launch kit (one take → every store asset)
+
+The `launch-kit` skill owns this destination: it establishes the release,
+loops every channel against `channel-specs.json`, verifies each artifact
+against its spec, writes the `kit.json` manifest and pushes labelled for
+the release. The mechanics it loops are this skill's:
+`vos frames take --frame <t> --size WxH` per still spec, the mp4 render for
+video. Follow it when the ask is a release, not one video.
+
+## Gotchas
+
+- A WebGL-heavy page (a shader background, a 3D canvas) paints BLACK under
+  headless Chromium's software GL, and the recording has no way to say so:
+  the take looks right except for a dead canvas. Record such pages with
+  `VOS_BROWSER_PATH` pointing at system Chrome (a real GPU), and check the
+  digest's sheet for the canvas before cutting.
+- Render time ≈ 1.5× real-time at 1080p (a 12.5s take ≈ 19s; ~5s fixed
+  startup); `--parallel N` pays off on takes ≳30s (ignored when audio rides);
+  2K ≈ 2× per-frame cost. Recording is always real-time.
+- Footage resolution = viewport size — decide 2K at RECORD time, from the
+  DESTINATION's specs (a 720p take cannot honestly fill a 1080p video
+  spec). Coordinate steps (`x`/`y`/`drag`) are VIEWPORT pixels: a viewport
+  change means scaling every coordinate; selectors survive.
+- `vos plan take` regenerates only `source:"auto"` spans; manual spans survive.
+- Take dirs: `frames/` is a deletable encode intermediate (~1GB at 2K);
+  `recording.webm` is the re-render source — keep it.
+- A take of a local app prints `localhost/…` in the browser bar. Set
+  `frame.browserBar.url` to the real address, or `frame.browserBar.showUrl`
+  to `false`, in `doc.json`; it is data, so no re-record.
+- Started the app yourself to record it? Stop THAT process, by the PID you
+  saved or by its port (`lsof -ti :3000 -sTCP:LISTEN | xargs kill`). Never
+  `pkill -f "node server.js"` or any kill by pattern: it takes down every
+  matching process on the machine, the maker's other work included.
+- A take that opens on the wrong page, with its first selector skipped,
+  is usually a missing or expired session, not a broken script: re-walk
+  `references/sessions.md` before touching `actions.json`.
+- More failure modes: `references/troubleshooting.md`.
+
+
+## Avoid (the traps that shipped)
+
+- A zoom that opens before the click it frames: `validate` names it ("points
+  beside what was clicked"); start the span after the click, or aim at it.
+- A focus point in pixels: `cx`/`cy` are fractions of the frame.
+- A `type` verb's field click as a zoom target: the field's centre is empty;
+  frame the text, and open the span after the click.
+- Routing the cursor through a hover-triggered menu between beats.
+- A first frame or a last frame that cannot stand alone as a poster.
+- A frozen opening: a static landing page records as freeze-then-bang;
+  trim it or speed it, the story opens near the money shot.
+- A store screenshot cut from the composed frame: real UX is the page, full
+  bleed (`deliver` does this; a text-heavy page also wants a store-size take).
+- A sign-in in `steps`: every step there is in the footage and a typed
+  value is logged. It goes in `setup`, with the password from the shell
+  (`references/sessions.md`).
+- A real customer's account on screen: addresses, names and keys ship in
+  the video. Record from a demo or seeded account, read the rehearsal's
+  `EXPOSED` list, and `mask` what is left.
+- A `mask` with `as: "text"` over product copy or a number: that is no
+  longer a recording of the product.
+- A `.png` name on `vos still`: it writes WebP; convert, and `vos validate
+  <kit.json>` reads the bytes.

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

@@ -0,0 +1,71 @@
+# Destination packaging
+
+What to produce, at what size, for each place a product video or still
+lands. All assets come from ONE take — pick apex moments with
+`vos frames take --at-zooms`, then cut stills with
+`vos frames take --frame <t> --size WxH` and videos with render presets +
+`--range`.
+
+**Producing a full launch kit?** Use the `launch-kit` skill from this
+repo — it drives the whole per-channel loop against the machine-readable
+spec sheet (`schema/channel-specs.json` in `@vosjs/cli`) and verifies
+every asset in a manifest. The tables below are the quick reference for
+one-off cuts.
+
+## Landing-page embed (your site's hero or feature section)
+
+- Record at 2560×1440 so a 2K render is footage-native; render webm.
+- Re-encode for the page: a hero clip should be ≲2MB.
+  ```bash
+  ffmpeg -i in.webm -c:v libvpx-vp9 -crf 42 -b:v 0 -row-mt 1 -cpu-used 4 -an out.webm
+  ffmpeg -ss 0.4 -i out.webm -frames:v 1 -q:v 4 poster.jpg
+  ```
+- Embed as a silent autoplay loop: `<video autoplay muted loop playsinline
+  poster=…>`. **React gotcha**: React does not serialize the `muted`
+  attribute into SSR HTML, so browsers deny autoplay — set `muted` on the
+  element imperatively (a ref) or verify the attribute survives to the
+  served HTML.
+- Verify with a headless browser: `paused === false` and the expected
+  `videoWidth`. Keep media out of git; posters and clips belong on a CDN or
+  asset bucket.
+
+## GitHub README
+
+- A README loop must be an MP4 **≤10MB** (GitHub's inline-player cap).
+  Two-pass target bitrate from duration, H.264 for compatibility:
+  ```bash
+  # bitrate ≈ (10MB × 8) / duration_s, minus ~128k audio if any
+  ffmpeg -i in.webm -c:v libx264 -b:v <target>k -pass 1 -an -f mp4 /dev/null
+  ffmpeg -i in.webm -c:v libx264 -b:v <target>k -pass 2 -movflags +faststart out.mp4
+  ```
+- Repo social-preview image: 1280×640.
+
+## Store and directory listings
+
+| Channel | Asset | Size | Notes |
+|---|---|---|---|
+| Chrome Web Store | screenshots (≤5) | 1280×800 | content only, no device chrome |
+| Chrome Web Store | small promo tile | 440×280 | subject centered |
+| Chrome Web Store | marquee promo | 1400×560 | |
+| Chrome Web Store | icon | 128×128 | |
+| Product Hunt | thumbnail | 240×240 | GIF loops autoplay in the feed |
+| Product Hunt | gallery images | 1270×760 | first image is the header |
+
+## Social cuts
+
+| Channel | Asset | Size | Notes |
+|---|---|---|---|
+| YouTube | thumbnail | 1280×720 | |
+| X | feed video | 1200×675 (16:9) | ≤140s, H.264 — upload natively, never a link card |
+| LinkedIn | feed video/image | 1200×627 | native upload; mute-legible |
+| OG card (any link) | image | 1200×630 | |
+| Vertical (Shorts/Reels/TikTok) | video | 1080×1920 (9:16) | keep the subject inside the ~900×1160 center safe zone — platform chrome covers the rest |
+
+## Performance rules (every channel)
+
+- **Hook in 3 seconds** — the first frame and first beat carry the click.
+- **Mute-legible** — most feeds autoplay silent; the story must read without
+  audio (zooms and text do the narration).
+- **Native uploads** beat link embeds on every platform's algorithm.
+- Platform specs drift — re-verify sizes quarterly against the channel's
+  current docs.

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

@@ -0,0 +1,226 @@
+# Sessions: recording a product behind a login
+
+A recorder with no session records the wall: the sign-in page, or wherever
+the site sends a stranger (often a public page, with nothing on it that
+looks like a sign-in), and the only symptom is a skipped selector. Settle
+the session BEFORE you write the script.
+
+Walk the ladder top to bottom and stop at the first rung that holds. It is
+ordered by who pays. Rungs 0 to 2 cost the human nothing and survive every
+re-record; rung 3 costs one sign-in; rung 4 costs a recording. Jumping to
+rung 3 because it is the most general turns a loop that re-makes itself
+into a chore someone has to show up for.
+
+## 0. No wall
+
+A public page, a demo mode, a local dev server with auth off, a preview
+deployment. If the feature shows the same there, record there. A preview
+behind a bypass header alone (Vercel's `x-vercel-protection-bypass`) is
+`vos record … --header x-vercel-protection-bypass=$TOKEN` (0.43 and later):
+the token comes from the shell, never from the script.
+
+## 1. Mint, from the test auth the project already has
+
+You are usually standing in the maker's repo, and its e2e suite very often
+signs in with no human. Look before you ask anyone anything:
+
+- `playwright/.auth/*.json`, an `auth.setup.ts`, a `storageState` in
+  `playwright.config.*`
+- `@clerk/testing`; a Supabase service key in `.env.test`
+  (`auth.admin.generateLink`); a Firebase custom token
+- a seed script, a test-only sign-in route, a session table plus a signing
+  secret in the dev env
+
+Run what is there, WITH THE APP ALREADY RUNNING: a project's auth setup
+signs in through the real page, so it needs the server up first (usually
+`npx playwright test --project=setup`, or whatever the repo's README names).
+The artifact is a Playwright storage state, which is exactly what
+`--storage-state` takes:
+
+```bash
+vos record --actions actions.json --out take --storage-state "$STATE" --dry-run
+vos record --actions actions.json --out take --storage-state "$STATE" --strict --json
+```
+
+This is the only rung that works in CI, and the only one that survives take
+fifty. A Firebase session lives in IndexedDB, which a plain state file
+drops: save it with `context.storageState({ path, indexedDB: true })`
+(Playwright 1.51 and later).
+
+## 2. Script the form, off camera
+
+A local or self-hosted instance where you can create the account, or a
+seeded user whose password is in an env var. Put the sign-in in `setup`
+in `actions.json` (`@vosjs/cli` 0.43 and later): it runs after the first
+navigation and BEFORE a frame is captured, with no cursor, no frames and
+nothing in `meta.steps`, then the recorder opens `url` again and the take
+begins signed in. No state file, nothing to mint, nothing to delete.
+
+```json
+{
+  "url": "http://localhost:3000/dashboard",
+  "setup": [
+    { "do": "goto", "url": "http://localhost:3000/login" },
+    { "do": "type", "selector": "#email", "text": "demo@acme.test" },
+    { "do": "type", "selector": "#password", "text": { "env": "DEMO_PASSWORD" } },
+    { "do": "press", "key": "Enter", "ms": 800 }
+  ],
+  "steps": [ ... ]
+}
+```
+
+The password comes from the SHELL at run time (`{ "env": "NAME" }`) and is
+never logged or stored: the log names the field, never the value.
+`validate` refuses a literal typed into a password field, because
+`actions.json` is committed and pushed with the take. Export the variable
+in the shell that runs `vos record`; an unset one exits 2 in words. A
+setup selector that never appears fails the take before anything is
+recorded, so rehearse the setup with `--dry-run` like everything else. A
+wrong password runs the setup and then meets the wall (exit 4), which is
+the check working.
+
+The same field dismisses a cookie banner, a "choose your editor" modal or
+an onboarding tour off camera: a `click` on the dismiss, before the take.
+
+Never put the sign-in in `steps`: every step there is IN the footage, and
+a typed value is logged.
+
+On an older CLI, or for an account you are creating: a few lines of
+Playwright, then record with `--storage-state`. `playwright` is already
+installed (it arrives with `@vosjs/cli`), launch the SYSTEM Chrome
+(`channel: 'chrome'`), and run the script from INSIDE the project so the
+import resolves; only the STATE FILE lives outside the repo.
+
+```js
+import { chromium } from 'playwright'
+const browser = await chromium.launch({ channel: 'chrome' })
+const context = await browser.newContext()
+const page = await context.newPage()
+await page.goto('http://localhost:3000/login')
+await page.fill('input[name=email]', 'demo@acme.test')
+await page.fill('input[name=password]', process.env.DEMO_PASSWORD) // or, for an account you are creating, a random throwaway you never print
+await page.click('button[type=submit]')
+await page.waitForURL('**/dashboard')
+await context.storageState({ path: process.env.STATE })
+await browser.close()
+```
+
+## 3. The human signs in once
+
+A production app behind an emailed code, SSO, a passkey or a CAPTCHA:
+
+```bash
+vos session open https://app.example.com --name acme
+```
+
+A plain Chrome window opens on a profile vos owns (`@vosjs/cli` 0.45 and
+later). Tell the human one sentence: a browser window opened, sign in with
+a demo account and quit Chrome (⌘Q on a Mac; closing the window is not
+quitting, Chrome stays running and the command keeps waiting). The
+command returns when Chrome exits, and that is the moment the session is
+saved; "I signed in" and "the session is saved" are different things, and
+a person reports the first.
+It then prints what the session holds as counts and dates, never a value.
+Then:
+
+```bash
+vos session check acme --url https://app.example.com/dashboard   # still opens signed in? exit 0, or 4
+vos record --actions actions.json --out take --session acme --dry-run
+vos record --actions actions.json --out take --session acme --strict --json
+```
+
+`--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
+state file. A re-record that exits 4 is the session expired: `vos session
+check` says so and prints the `open` command to run again.
+
+Google sign-in refuses an automated browser, which is why `open` is a
+plain window: it goes through there. If the person cannot be at the
+keyboard now, go to rung 4; do not wait on a window nobody will close.
+
+On an older CLI: `npx playwright open --channel chrome
+--save-storage="$STATE" <url>` writes a state file when the window closes,
+for `--storage-state`. `--channel chrome` uses the system Chrome; without
+it the command wants Playwright's own Chromium, which is usually not
+installed.
+
+**The human is not there right now?** Do not open a window nobody will see
+and do not block on it. Get everything else ready (the script written and
+validated, a rehearsal that exits 4 to prove the wall is the only thing
+left), then STOP and leave the ask in the words you would say: the one
+`vos session open` command, "sign in with a demo account and quit
+Chrome", and the record command that follows. Ask, in the same note,
+whether there is a faster way in you cannot see (a seeded account, a test
+sign-in route): that turns the next re-record into rung 1.
+
+## 4. The human records, you cut
+
+Hand them the flow you worked out, as a shot list. Write `actions.json`
+as you would for any take, give the steps ids and captions a person could
+follow, then:
+
+```bash
+vos actions script actions.json
+```
+
+It prints the beats in plain words with the holds you asked for, the page
+to start on and about how long (`@vosjs/cli` 0.44 and later). Put that in
+your handoff with one sentence: record it with the vosso extension in your
+own signed-in browser, press the icon again to stop, and it lands on your
+shelf. When it does, `vos pull <vos-id> --out take --media` brings it down
+and you cut it (the `vos-cut` skill): the beats you wrote are the moments
+you will be looking for in the digest. This is a rung, not a failure. "I
+cannot get in; here is the shot list, record it and I will cut it" is the
+honest best thing, and the script survives for the day rung 1 or 2 opens.
+
+A recording a person made has no `mask` and no exposure list (the scan
+needs the page): look at the digest's frames yourself and say what they
+show, before anything is pushed further or handed over.
+
+## Rules, at every rung
+
+- **Never type, ask for, or accept a production password, code or token.**
+  If a human offers one in chat, decline and use rung 3.
+- **The state file holds live credentials.** Keep it outside every take
+  directory and outside git: a temp dir, or the gitignored path the project
+  already uses. `vos push` uploads the recording and `doc.json`, never a
+  state file, and nothing about a session ever goes to vos.so.
+- **Delete the state file when the video is done**, unless the project
+  keeps one on purpose (a gitignored `playwright/.auth`). It is cheap to
+  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.
+- **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
+  the KIND and the place of what it saw (an email address, something shaped
+  like a key, a card number or its visible tail; addresses on `example.com`
+  or a `.test` domain are demo data and are not reported). Read that list
+  BEFORE you record. It also lands in the done event's `exposures`, in
+  `vos validate <take>` and in the digest.
+- **Hide it before the camera rolls, with `mask` in `actions.json`.** The
+  selector in each report reaches that element and no other, so paste it:
+  ```json
+  "mask": [
+    { "selector": "nav > span", "as": "text", "text": "jane@acme.test" },
+    { "selector": ".card-number" }
+  ]
+  ```
+  `as: "text"` swaps the words, which reads as a product where a blur reads
+  as a redaction; the default blurs. It is applied before the first frame
+  and re-applied after every navigation and re-render, so the real value is
+  never in the recording. Use `text` for IDENTIFIERS only (an email, a
+  name, an account id). NEVER substitute product copy or a number: the
+  video stays true to the product, and that judgment is yours, no check
+  makes it for you. Rehearse again: the list should be empty, and a mask
+  that reached nothing fails the rehearsal by name.
+- A recording a HUMAN made (the last rung) has no mask: the scan needs the
+  page. Look at the frames yourself and say what they show.
+- The list is a floor, not a verdict. It reads text: a face, a logo, a
+  customer's name in a table, a private chart are yours to notice. Offer
+  the re-record from a demo account; do not decide for them.
+- **What the account shows ships in the video.** Use a demo or seeded
+  account, never a real customer's. Before you push, look at a frame for
+  email addresses, names, keys and card numbers, and re-record from an
+  account that does not show them.