# vos CLI — the complete take/capture agent reference (vos.so/llms-full.txt)

The vos CLI turns a scripted browser flow into a polished product video (auto zoom,
smoothed cursor, click effects, browser frame) — and every effect is DATA.
You (the agent) write a flow, the CLI records + plans, you edit JSON, you
re-render. The renders are deterministic: same take + same doc = same pixels.
Never re-record to fix pacing or zooms — edit doc.json and render again.

Install: npm i -D @vosjs/cli   (one binary, one package, MIT: the engine
verbs, the take pipeline AND all vos.so platform verbs. Until 0.9 the take
pipeline shipped separately as @vosso/vos-plugin, and before that as
@vosso/cli; both are shims now, and vos voila <verb> remains a hidden alias
for old scripts)
Needs: a Chromium-family browser (system Chrome auto-detected;
`npx playwright install chromium` or VOS_BROWSER_PATH otherwise) and network
at encode/render time (three/mediabunny load from esm.sh in render pages).
Conventions: logs → stderr, results → stdout; --json = NDJSON events ending
{"event":"done",…}; exit codes 0 ok / 1 error / 2 usage-or-strict / 3 no browser /
4 the recorder met a wall (a sign-in instead of the page; see "Sessions").
vos <verb> --help prints that verb's flags and exits 0 (0.41.1 and later).
A flag a verb never READ is never swallowed: the run exits 2 and stderr says
"vos <verb> RAN, and ignored --x (did you mean --y?)" with the flags the verb
reads. The command DID run, without that flag: fix the flag and run it again;
never treat that output as what you asked for. (A push that ran has pushed.)

## The take directory (the unit of work)

take/
  recording.webm   encoded footage (CFR WebM; recording.mp4 when a pull brought
                   it home in that container — read the name, never assume it)
  frames/          screencast JPEGs — encode intermediate, deletable (~1GB at 2K)
  cursor.json      synthesized CursorTrack (exact coords, element rects,
                   typing pings — when/where only, never text)
  meta.json        RecordingMeta (producer: "cli")
  actions.json     the script that produced it — the replay recipe
  doc.json         ProjectDoc — the editable surface (THE product artifact)
  vos.json         hosted tracking (vos id + base version), written by push/pull

## Commands

This machine (0.48 and later; no account). These four print NDJSON whenever
stdout is not a TTY, and every done event carries next_step.
vos setup [--agent claude,cursor,codex,copilot|all] [--global] [--no-skills]
          [--no-rules] [--no-browser] [--url <dev server>] [--json]
  Ready the computer for the loop: the vos skills into your agent's
  directories (npx skills add vosjs/skills -y; when skills.sh cannot be
  reached, the copy bundled in the package), a browser found in the
  recorder's order (VOS_BROWSER_PATH, system Chrome, Playwright's Chromium)
  or installed, ONE block between <!-- vos:begin --> and <!-- vos:end -->
  in AGENTS.md (CLAUDE.md when only that exists; a second run replaces its
  own text and never yours), then doctor. Agents are detected by directory
  (.claude, .cursor, .codex or .agents, .github/copilot; the home forms
  under --global); none found ⇒ the skills land in .agents/skills.
vos doctor [--url <dev server>] [--json]
  What is ready, in words: node, browser, ffmpeg (optional), the vos skills
  per agent, a credential (present or absent, never printed), and the dev
  server when --url names one. Exit 3 when no browser; next_step says the
  fix. Run it before the first record and whenever record exits 3.
vos whoami [--json]     the key's name and the account it belongs to, from
                        GET /api/user/whoami; never the key. Exit 1 when
                        nothing resolves (recording needs no account).
vos logout [--json]     remove ~/.config/vos/credentials (VOS_API_KEY in the
                        shell still resolves, and the answer says so).

vos create --actions actions.json [--url <url>] [--out take] [out.webm]
                 [--strict] [--allow-wall] [--max-duration <s>]
                 [--storage-state <file>] [--header name=value]...
                 [--browser-arg=<switch>]... [--keep-frames]
                 [--width] [--height] [--fps]
                 [--format webm|mp4] [--parallel N] [--draft] [--frame <kind>]
                 [--background <url|slug>] [--set path=value]... [--json]
  The one-shot verb (the vos <product> create namespace): record + auto-plan
  + render in one command and one browser session. The take dir still lands
  on disk, so the loop below (frames → edit doc.json → re-render) stays open.
  With --strict an incomplete recording aborts BEFORE the render (exit 2).
  Use create for the first pass; use the individual verbs to iterate.

vos record --actions actions.json [--url <url>] [--out take] [--strict]
           [--dry-run] [--allow-wall] [--max-duration <s>]
           [--storage-state <file>] [--header name=value]...
           [--browser-arg=<switch>]... [--keep-frames] [--json]
vos record --hosted --actions actions.json [--url <url>] [--out take]
           [--title "…"] [--folder <id>] [--header name=value]... [--json]
  Drives the page, synthesizes the cursor track, encodes, auto-plans zooms.
  ALWAYS pass --strict: any skipped selector or networkidle timeout exits 2
  with machine-readable skipped[] in the done event. A skip = broken flow —
  fix the selector and re-record; never ship around it.
  REHEARSE FIRST: add --dry-run to the exact command you are about to run.
  Every step runs against the real page, in order (a later selector usually
  exists only after an earlier click), but nothing is captured and nothing
  is written: the pointer lands instead of travelling, pauses are cut to a
  beat, and the take beside it keeps its footage, its cut and its script (a
  real re-record moves doc.json aside; a rehearsal does not). Lookups keep
  their whole timeout, so a miss there is a miss in the take. It prints each
  step with the rect it resolved, in capture px (the rects a pin or
  vos callout --step reads), and exits 2 on any miss. A script is found
  broken in seconds, not after a real-time take and its encode. The Next:
  line it prints is the same command without --dry-run, session flags
  included (0.41.1 and later; an older rehearsal drops --storage-state
  from that line, so add it back before you paste it).
  Re-recording into an existing take replaces the FOOTAGE, never the cut
  (RK2): doc.json survives as doc.prev.json, actions.json and vos.json stay,
  and vos plan <take> --reuse re-times the cut onto the new recording.
  meta.json carries steps (when each actions step ran, source seconds);
  give steps an id so anchors survive script edits. Recording is real-time.
  --max-duration <seconds> (default: the hosted cap, read live from
  GET https://vos.so/api/limits → limits.recordingMaxSeconds, 1800 = 30 min
  today; the built-in 1800 applies offline): the
  capture stops there and the done event says so (capped: true, the
  remaining steps did not run); with --strict that exits 2. A take longer
  than 30 min is refused by vos push (413), so cut the flow, not the cap.
  --hosted (0.49+): NO BROWSER HERE? A cloud agent, a CI runner or a chat
  host records on vos.so instead. The same script goes up (POST
  /api/record/jobs), the fleet records, plans and lands the take as a
  PRIVATE vos with its doc.json and its digest, and the take comes home
  into --out with its media (vos fetch --media), the directory every other
  verb reads. Needs a credential (vos login, or VOS_API_KEY). What travels:
  the script, the viewport, every --header value (a preview's bypass
  token) and the value of every { "env": "NAME" } a setup step reads, from
  this shell, for the job's life; the platform stores the script with the
  values stripped and never the env or the headers. What never travels: a
  session (--session and --storage-state are refused; a Cookie header is
  refused by the platform), because none of a person's ever reaches
  vos.so. A page behind a sign-in fails on the fleet in words naming the
  ladder below, exit 4, and the empty vos it would have landed on is taken
  down; a private-network URL (localhost, 10.x, a .local name) is refused
  before a job exists, so a dev server needs a tunnel or a preview
  deployment. The fleet records up to 10 minutes at 1280x720 by default
  (viewport in actions.json, 640..1920 wide); 20 hosted takes per account
  per day. --dry-run stays a local act. --title and --folder <id> name the
  landing.
  THE WALL CHECK (0.41 and later): once the first navigation settles, and
  before a frame is captured, record, create and --dry-run ask whether the
  recorder landed where it was sent. Refused with exit 4 and a sentence
  ("asked for /dashboard, landed on /login: no session for app.acme.com"):
  the URL answered 401/403, the recorder was sent to an identity provider
  or a sign-in path, or the page is a sign-in form rendered in place. A
  redirect somewhere else with no sign-in in sight (a site that shows
  strangers a public page) is refused under --strict and in a rehearsal,
  and only warned about otherwise. Nothing is recorded and nothing is
  cleared: a re-record's old footage survives a refusal. Exit 4 is never a
  script bug: do not touch actions.json, walk the ladder in "Sessions".
  --json carries a wall event (kind, level, asked, landed, refused).
  --allow-wall records the page anyway (a video OF a sign-in page is a
  legitimate take); meta.wall and the digest's take.wall then say so, and
  a digest that prints WALL is footage of the wrong page: re-record it
  with a session before cutting it.
  WHAT THE FRAME SHOWS (0.42 and later): after the page opens and after
  every step the recorder reads the text visible in the viewport and
  reports the KIND of sensitive-looking thing it saw and where, never the
  string: email (an address, except on example.com or a .test/.example/
  .invalid/.localhost domain, which is what demo data should use), key
  (sk_live_, ghp_, github_pat_, xoxb-, AKIA, vos_sk_, a JWT), card (13 to
  19 digits passing Luhn), card-tail (•••• 4242). A rehearsal ends with
  the list, so read it BEFORE you record; it also rides the done event's
  exposures[], meta.exposures[] ({step, kind, selector, rect, seen};
  step -1 = as the page opened), vos validate <take> warnings and the
  digest's take.exposures. Warnings, never failures: a product may show
  addresses on purpose. The selector reaches that element and no other,
  so it pastes into a mask.
  "mask" in actions.json hides a selector BEFORE the first frame and
  keeps it hidden across navigations and re-renders, so the real value is
  never in a frame, never in recording.webm, never pushed:
    "mask": [{ "selector": "nav > span", "as": "text", "text": "jane@acme.test" },
             { "selector": ".card-number" }]
  as "blur" (default) blurs; as "text" swaps the words, for IDENTIFIERS
  only (an email, a name, an account id), never product copy or a number:
  the video stays true to the product, and no check makes that call for
  you. A form control is always blurred. A mask whose selector reached no
  element hid nothing: it fails --strict and a rehearsal by name, and
  meta.masks[] carries each mask's hits. A blur added later in doc.json
  is not a fix: the real value is still in recording.webm.
  "setup" in actions.json (0.43 and later): steps that run BEFORE the camera
  rolls (a sign-in form, a cookie banner, an onboarding tour), verbs goto,
  click, type, press, wait. They run after the first navigation and before
  a frame is captured, as plain actions with no cursor, no frames, no pace
  and nothing in meta.steps; then the recorder opens url again and the
  take begins where the setup left it. A type step's text may be
  { "env": "NAME" }, read from the shell at run time and never logged or
  stored (the log names the field, never the value); a literal typed into
  a password field is refused by validate, because actions.json is
  committed and pushed with the take. A setup selector that never appears
  fails the take before anything is recorded (exit 2); an unset variable
  exits 2 in words. Rehearse the setup with --dry-run like everything else.
    "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 }]
  --header name=value, repeatable (0.43 and later): a request header on
  every request the recording browser makes; the rehearsal's Next: line
  carries it.
  --session <name> (0.45 and later): record on a profile the person signed
  in to with vos session open. One door; --storage-state is the other,
  never both. The rehearsal's Next: line carries it.
  --storage-state <file>: a Playwright storage state, so the take is of a
  SIGNED-IN product. Where the file comes from is the ladder in "Sessions"
  below: walk it top to bottom. It holds live credentials: never commit it,
  never push it, never put it in a take directory.
  --browser-arg=<switch>, repeatable: extra Chromium switches, every one
  kept in order. A switch starts with --, so it is written with =. A page
  that asks for the microphone or camera needs BOTH
  --browser-arg=--use-fake-ui-for-media-stream and
  --browser-arg=--use-fake-device-for-media-stream (the device switch alone
  is refused). An unpacked extension does NOT load this way: it needs a
  persistent, headed, bundled-Chromium context, which record does not run.
  The screencast frames are released once the recording is encoded (they
  are most of a take's bytes and vos digest reads the video without them);
  --keep-frames keeps them.

vos port inventory <page.html|project dir> [--render <their render.mp4>] [--out port] [--json]
vos port scaffold [--from port/inventory.json] [--out port/program] [--json]
vos build <program.mjs> [--out config.json] [--json]
vos compare <program dir|config.json> --against <their render.mp4>
           [--times a,b,50%] [--every 1] [--threshold 0.95] [--out compare] [--json]
  BRING A FINISHED PIECE (0.54+; the vos-port skill): a HyperFrames
  composition, a hand-rolled page or a Remotion project's render becomes a
  program whose words and colours are data. inventory reads the piece as a
  browser renders it into port/inventory.json: words with their computed
  faces, sizes and colours, the palette from custom properties, faces
  matched to the font catalog (or missing), media with their windows, the
  scenes a timeline reveals, the CSS no element can say, and for a canvas
  page the words and faces its scripts name; a HyperFrames word is laid
  out where it settles in its scene. A Remotion project (0.55+; run npm
  install in it first) is bundled with its own @remotion/bundler and read
  the same way: its <Sequence>s are the scenes, named by what they hold,
  its colour constants name the palette, <Audio> is the score. For every
  source, each scene's ground is measured and a word animated letter by
  letter is one split word; stills come from the render beside it. When
  the piece needs a painter or its code springs or uses noise, the
  scaffold (0.56+) writes the PAINTER STARTER as content.refs.lib:
  spring (Remotion's spring to the frame), springTo (that spring on the
  timeline, one step per frame), interpolate, bezier, seeded noise2D and
  noise3D, random; use these, never another engine's source. A source's
  spring goes ON THE TIMELINE with the spring ease (0.57+, engine
  @vosjs/timeline 0.5): ease 'spring(damping, stiffness, mass)', defaults
  10, 100, 1, with duration lib.springSeconds({ damping, stiffness }),
  moves exactly as Remotion's spring; a longer duration stretches it as
  durationInFrames does. Never compute a spring in onFrame.
  scaffold writes port/program/: program.mjs (every word a bound
  element, every colour a key, knobs over them, a label and a TODO per
  scene, a painter starter only where needed), doc.json (the score as a
  track), config.json, and port/REPORT.md (substitutions, gaps). The
  agent translates the motion where it says TODO. build turns real
  functions into config.json and refuses a module-scope read, syntax the
  page cannot run and non-JSON data (config.sources.json maps each
  function to its line). compare scores every sampled frame against the
  source's render (SSIM, ffmpeg on PATH) and writes source | vos |
  difference sheets; it exits 1 when ANY frame is under the threshold,
  because a missing element is one frame's failure: look at the sheets.

vos ingest <video.webm|mp4> [--cursor <trace.zip|steps.jsonl|cursor.csv>]
           [--as footage|take] [--out take] [--offset <ms>] [--viewport WxH]
           [--background <slug|url|none>] [--json]
  ALREADY HAVE A VIDEO? (0.50+) A cloud agent's PR video, a Playwright
  run's video.webm, a Loom export: the file becomes recording.<container>
  (stream-copied into a seekable container, or copied as it is), meta.json
  comes from the file's own dimensions, length and frame rate, and a trace
  recorded beside it becomes cursor.json, so the planner has clicks to
  zoom on. Three trace shapes: a Playwright trace.zip (clicks with their
  points and times, from the page's creation; the run's own recordVideo
  webm is the matching video), stamped JSON records (one per line:
  {"ts":<ms>,"command":["click","@e1"],"point":{"x":..,"y":..}}), or a CSV
  of t,x,y,type (ms, viewport px; move|down|up|click|scroll). Without a
  trace the take has no cursor track and NOTHING IS PLANNED, and the done
  event says so: place zooms by eye (vos frames <take> --times …, then
  doc.json). What a trace cannot give is named, never guessed:
  agent-browser's own log carries neither timestamps nor coordinates, so
  stamp ts and a point per command when you keep one, or replay the walk
  with vos actions from-agent-browser + vos record instead. --offset
  shifts a trace whose zero is not the video's; --viewport names the
  coordinate space when the video was scaled. A headed capture with the
  real pointer baked in shows two cursors under a trace's drawn one; turn
  the drawn cursor off in doc.json for those. The studio reads the same
  traces: drop the video WITH its trace on https://vos.so/studio in one
  gesture and it opens planned.
  FINISHED FOOTAGE (0.52+): a file with no trace is read as finished (a
  render from HyperFrames or Remotion, a film) and opens BARE: no card, no
  browser bar, no drawn cursor or webcam, exported at its own frame rate.
  A screen demo with no trace (a Loom) says --as take for the card;
  --as footage says the opposite outright. The studio's drop does the same.

vos plan <take> [--fresh] [--reuse [--from <doc.json>]]
                [--style <doc.json|vosId>] [--with <doc.json|vosId>[@end|@start|@step:<id>|@<s>]]...
                [--motion] [--headline "…"] [--kicker "…"]
                [--launch LAUNCH.md] [--brand BRAND.md] [--music <slug|mood|none>]
                [--entrance tilt-in|pull-out|rise|fade|none] [--end-card on|none|<doc.json|vosId>]
                [--captions none] [--clicks none] [--release v2.1] [--json]
  Re-plans auto zooms from the cursor track. source:"manual" spans are
  PRESERVED; only source:"auto" suggestions regenerate. --fresh discards doc.json.
  A DELETED proposal stays deleted: when you remove a source:"auto" zoom,
  tilt or speed span, add it to doc.rejected ([{id, lane, in, out}], the
  lane and the SOURCE extent; the studio writes this itself on delete) and
  no re-plan, here or under --reuse, proposes that beat again.
  --style copies a signed-off take's STYLE FIELDS onto this one before the
  planners run (zoomStyle, zoomParams, speedParams, tiltStyle, frame, cursor,
  cam, export — never its spans, overlays or audio), so a series shares its
  look by data and the folder's CUT.md only has to say what a number cannot.
  A --style reference that is a POSTER carries its LAYOUT too: the card's
  placement and presentation, its stage clips by id (stage-title,
  stage-kicker, stage-brand, stage-mark; the release's words patched in
  from LAUNCH.md's headline and kicker roles, BRAND.md's wordmark, or
  --headline/--kicker; the brand's mark from BRAND.md logoUrl fetched into
  <take>/brand/ for stage-mark), its rest lean (one whole-take tilt span
  where this take has none), its trailing freeze. What could not follow is
  said in words. A poster is a plain take document; a layout is a poster
  on a shelf, applied by copy, never a name the document learns.
  THE MOTION IS THE DOCUMENT'S, IN ONE VOCABULARY: every visual thing (the
  card, a text, image or video clip, a prop) carries anim.enter, anim.exit
  and anim.idle (a kind, or {kind, seconds, and for words unit, direction,
  stagger}); the output lasts until the last clip ends; the card is on
  screen exactly while its clip runs (the footage, freezes included) and
  leaves at its end, its exit over the clip's last seconds like every
  clip's (recede steps back, then fades), so clips past the footage play
  over the ground alone and an end card keeps the card as a FREEZE of the
  last frame under its words. There is no
  end-card field and no entrance field. A COMPONENT is a TEMPLATE: a plain
  take on a shelf whose clips carry stable ids, laid onto a take at an
  anchor and stamped from (where its clips came from): LAUNCH.md with:
  <ref>[@end|@start|@step:<id>|@<s>], … or --with (repeatable); endCard:
  <ref> names one at the end; a ref is a doc.json, a take dir or a vos id.
  A fresh plan proposes the card's enter (tilt-in by default), the
  templates named, the END CARD when endCard is on or absent (the official
  End card template on vos.so, laid at the end with the release's words and
  the mark, from: endcard; offline, the house one: the
  headline, the release line, the wordmark and BRAND.md's mark as clips
  after the footage over a receding card, from: endcard), a caption per
  actions.json step at the step's moment, a music bed by LAUNCH.md's music
  slug or mood, and a click sound on every press when the take has no mic,
  with stable ids (bed, click-<n>, caption-<step>), so the studio plays
  what the kit will render, and a transition at every page change the
  recorder marked (meta.steps[].navigated: the outgoing clip ends on the
  frame before the change, the incoming begins once the page has settled;
  transitions: slide|fade|scale|none, slide by default, --transitions).
  LAUNCH.md's entrance, transitions, endCard, with, captions, music and
  clicks roles (or the flags) change or switch each off. A
  refresh never re-proposes (a deleted clip stays deleted); --motion
  re-proposes on purpose, replacing only its own work. The older spellings
  (frame.entrance, endCard, a clip's enter/exit/fx, a prop's animation)
  are read into anim and vos validate says so.
  A field absent on the reference is removed here too (the seed's absence is
  a choice). Takes a doc.json on disk or a hosted take's id (key-aware).
  --reuse (RK2, the re-render loop): apply a PREVIOUS cut of the same script
  to this take's NEW footage — default source is the doc.prev.json a
  re-record preserved (--from names another). Style copies like --style;
  the human's camera spans and trims re-time onto the new recording (an
  explicit span anchor {step, at, offset} resolves against meta.steps and
  wins; everything else maps piecewise through matched step edges); overlays,
  audio and objects carry at their OUTPUT times; autos re-plan. The done
  event's reuse block reports anchored/mapped counts and NAMES whatever
  could not follow (a vanished step, a span off the new take's end) — read
  the flagged list and fix by exception, never re-cut from scratch.

vos brand <url> [--out BRAND.md] [--json]
  The product's brand kit, WITNESSED, as a BRAND.md recipe. Reads
  /design.md when the site publishes one (the convention beside
  /llms.txt: font names, logo assets, an avoid list), /llms.txt for the
  name and the claim, then the page itself in a browser: the body ground,
  the surfaces, the h1 and body faces and inks, the accent buttons and
  links agree on, theme-color, the icons, og:image. The frontmatter carries
  the roles the poster family binds (bgA/bgB/bgC, ink, accent, fontDisplay,
  fontBody, logoUrl, iconUrl, ogImage, wordmark); the prose says where
  every value came from and quotes the site's own avoid list verbatim.
  Resolve the brand BEFORE any asset is authored (a template's own palette
  on a deliverable is the trap); file it with vos recipe push BRAND.md
  --folder <slug>, and re-run after a redesign.
vos digest <take> [--out dir] [--full 960] [--crop 640] [--no-frames]
                 [--transcript <file.json>] [--style <doc.json|vosId>] [--json]
  How you SEE a recording before you cut it (never read the video). Writes
  <take>/digest/: digest.json + one FOOTAGE frame and a crop around the
  target per moment + sheet.png (the contact sheet, ids burned in).
  A MOMENT is what the cursor track says mattered: click clusters, typing
  sessions, scroll runs, dwells, idle gaps, plus head, tail and scene changes
  (a frame-diff jump). Each carries source + output extents, "at" (the framed
  instant), "focus" {cx,cy} and "rect" in the doc's NORMALIZED units (copy
  them straight into a zoom span), "activity" (fraction of pixels that
  changed, per SOURCE second — "nothing happened here" as a number), and
  "proposed" (the zoom/speed/tilt ids the planners would put there; "plan"
  holds those spans in full). "doc.manual" counts what a human already
  decided. Read digest.json, then the sheet, then crops only where you must
  decide; the done event's tokensEstimate is the price of reading all
  of it (--full/--crop shrink it). A take with no cursor track (browser
  recorder) yields head/tail/scenes only: pace by activity, zoom only where
  the ask names a place. --transcript merges Whisper-shaped segments
  ({segments:[{start,end,text}]}, SOURCE seconds) as "said" per moment; a
  transcript.json beside the take is picked up unasked. Run the
  transcription yourself — no audio leaves the machine for it. A caption
  never repeats the narration. With the activity bins in hand the speed
  proposals also tell PLAYBACK from idle (an idle gap whose pixels keep
  changing is the video playing, never sped up), and vos plan reads the same
  bins from digest/ when it exists.
  --style REPORTS a reference doc's style fields (zoomStyle, zoomParams,
  speedParams, tiltStyle, frame, cursor, cam, export) under "style".
  No browser where you run? The platform can digest a hosted take for you
  (its owner or an admin; admin-only while the fleet decode is unmetered):
  POST https://vos.so/api/vos/{id}/digest {versionId?} → 202 {jobId,
  digestUrl}; then GET {digestUrl} answers 404 until the job lands (about a
  minute for a 90s take) and the same digest.json after; its PNGs are at
  {digestUrl}/<m03.crop.png|m03.full.png|sheet.png>. Same document, same
  units, same bins as the local verb.

vos frames <take> [--times 0,25%,50%,75%,100%] [--frame <t>] [--at-zooms]
                 [--at-moments] [--size WxH] [--out dir] [--json]
  PNG stills from the COMPOSED take (frame, zoom, cursor, effects — what the
  video will show). Times are OUTPUT seconds or % of duration. --at-zooms adds
  every zoom span's apex — judge those hardest; --at-moments adds every digest
  moment that survives into the output (named moment-<id>-<t>s.png, so a
  still and its footage crop share an id). --frame <t> --size WxH emits an
  exact-resolution still (posters, OG cards, store screenshots — CWS wants
  1280x800). ~2s for a sheet. This is how you LOOK at your work — use it.

vos render <take> [out.webm] [--width] [--height] [--fps] [--format webm|mp4]
                 [--parallel N] [--range a..b] [--draft]
                 [--frame <kind>] [--background <url|slug>] [--set path=value]... [--json]
  Deterministic render. --range a..b (OUTPUT seconds) + --draft (half res,
  low bitrate) spot-checks a doc edit in seconds — never ship a draft.
  --format mp4 needs system Chrome (AVC). --parallel N shards long takes
  (pays off ≳30s; ignored when audio is present).
  Audio: doc.audio clips mix + mux on single-flight renders (Opus for webm,
  AAC→Opus for mp4); a --range render keeps its audio (the full-timeline
  mix, sliced to the range window).
  The output's NAME picks the container (0.52+): out.mp4 is mp4, and a
  --format that contradicts it is refused. A PROGRAM renders the same way
  (vos render config.json out.mp4): its doc.json sound is mixed in, and
  --set data.<key>=<value> checks a knob without a second config. vos still
  <config.json> takes --times 0,1.5,50% (one browser) and writes .png or
  .jpg by name.

vos deliver <take> --to cws,producthunt,x,linkedin,og,github,youtube (or all)
                 [--release v2.1] [--launch LAUNCH.md]
                 [--look plate|gradient|dark|none] [--brand BRAND.md] [--composed]
                 [--set path=value] [--out dir] [--times a,b|step:<id>] [--range a..b]
                 [--parallel N] [--json]
  The release's assets in one pass, RENDERED and VERIFIED; it composes
  nothing. Loops the verified channel specs (schema/channel-specs.json:
  sizes, ceilings, the word policy and the safe rect per destination).
  Every artifact is VERIFIED against its spec; a miss or an unfillable
  floor lands in skipped[] with the reason, never padding. kit.json beside
  the assets (<take>/kit, --out overrides) records every asset, the moments
  and their sources, each card's poster (class, file, the vos it tracks),
  shot rect and text boxes, and skipped[].
  THE MOMENTS come from the story: every step's end plus a settle (the end
  of the wait the script placed after a click that navigates), then the
  zoom apexes, then a spread; each candidate is read once as the real page
  and a blank one (a wallpaper, an empty canvas) is dropped, two of one
  frame collapse to one, every drop said. --times takes seconds, percents
  or step:<id>[+offset].
  THE LOOK presents the card: BRAND.md beside the take (or --brand) decides
  from its look role or its own ground (a paper site is a plate, a dark
  site is dark, else the gradient; --look overrides, none = the pre-look
  crops; no brand = the house gradient). Card-genre stills with no
  template and every video cut sit at ~84% of the width with headroom, an
  ambient plus a contact shadow, a hairline when card and ground are both
  light; a wide frame runs the card off the bottom. Screenshot-genre stills
  (CWS screenshots, the PH gallery) never take a look: the REAL PAGE, full
  bleed, camera and chrome dropped (store policy); --composed keeps them,
  and the picture pass then refuses the still.
  MANY MEDIA IN ONE TAKE (concat): doc.media[] holds the take's other
  recordings or uploads, each the source shape with an id; a segment on one
  ({ in, out, media: "m1" }) plays it after or between the primary's clips,
  and a zoom, tilt, speed, freeze or cam-move span names the media its
  source seconds belong to (absent = the primary, source). A recording is
  media plus the facts only a capture has (a cursor track, the page URL,
  steps): a file has none, so it gets no dot and no auto-zoom, and the
  browser bar is still allowed on it. vos plan proposes on every media
  from its own track; vos validate measures a span against its own media;
  vos push and vos pull --media carry every media. The primary's sound
  plays at the primary's moments; another media's own audio is not spliced
  into the cut yet. A media wears its OWN card: media[].frame carries the
  card-owned fields (placement and size as inset, browserBar, radius,
  shadow, shadowContact, shadowColor, border, borderWidth, borderColor,
  fit, focus, focusFollow) over the take's frame while it plays; absent
  fields fall to the take's, the bar names the media's recorded page and
  an upload with no page wears none. The frame-wide fields (aspectRatio,
  padding, background, backgroundMedia, anim) stay the take's.
  TRANSITIONS: segments[].anim says how a footage clip meets the clip
  beside it (exit at the boundary after it, enter at the one before: slide
  | fade | scale | none; a slide names its side, left|right|up|down, in
  from the right and out to the left by default; a step its seconds, 0.15
  to 2, never longer than half the shorter clip). An exit and the next
  clip's enter at one boundary run together as a push: the incoming clip
  plays live, the outgoing holds its last frame and moves away, the camera
  rests through the window, one cursor dot crosses between the cards. The
  first clip's enter and the last clip's exit are the card's own
  (frame.anim.enter also takes slide). A page change inside one recording
  is two clips of one media with the load between them cut.
  MANY CARDS: an image or video overlay may show a document media by
  reference (key "media:<id>"; "media:" alone is the primary), with its
  cursor track and recorded page, and may wear a card (frame: browserBar,
  lean {rx, ry} in degrees, shadow, shadowContact, shadowColor, cursor),
  drawn by the card painter on its own plane above the primary card with
  the media's cursor dot and click rings inside it. A layer without frame
  is the flat picture. The primary card stays primary: the sequence, the
  camera and the cut are its.
  THE STILL, the frame that stands for a take (the shelf's cover, the frame
  a kit's card destinations render): still in doc.json (OUTPUT seconds; vos
  plan --still <t>, LAUNCH.md still:) when the author set it, else where
  the take's OWN last freeze begins (a poster's rest; a template's freezes,
  stamped from, never count), else the hero moment after the card and the
  opening clips have entered. vos frames --at-still renders it; a plan
  never moves a still the author set.
  A POSTER IS A DOCUMENT: a plain take whose card sits where the poster
  wants it (frame.inset, negative sides bleed), leans (the tilt track),
  carries the words and the mark as clips with stable ids (stage-title,
  stage-kicker, stage-brand, stage-mark), and ends on a trailing freeze whose
  start is the still. Each card destination (OG, LinkedIn, X, the YouTube
  thumbnail, the CWS tile + marquee, GitHub social preview) renders from the
  poster document of its aspect CLASS (landscape, square, portrait, tile),
  found beside the take as poster/<class>/doc.json (poster/doc.json serves
  every class) or named in LAUNCH.md (poster: <path>, poster-landscape: …;
  a doc.json, or a pulled poster take that renders over its own footage),
  at the document's STILL (its own last freeze, the composed frame before
  nothing moves, or the still the author named). Make one with vos plan <poster take> --style <a poster
  on your shelf> --headline "…" (the layout is copied, the words typed in)
  or by hand in doc.json, verify it with vos frames and vos validate
  --picture, push it like any take. A class with no document is the take's
  own frame, said once in skipped[]. Never a template name, never a layout
  enum: a layout is an exemplar plus a recipe line (POSTER.md).
  THE CUTS PLAY THE DOCUMENT: the card's anim, the templates' clips, the
  captions and the sound are what vos plan proposed into doc.json (or what
  the maker set in the studio). deliver applies each destination's
  MECHANICS and nothing more: the README loop drops the card's motion,
  every clip a template placed, the captions and the sound (it must be
  seamless); a channel that autoplays muted (LinkedIn,
  the OG card's video) drops the bed; the 9:16 cut is a reframe whose crop
  follows the camera; a loop destination the take outruns takes the first
  seconds up to its cap.
  Store uploads stay manual by policy: hand the human the kit directory
  and the manifest.

vos validate <kit.json> [--picture] [--json]
  The kit's verifier. The spec pass re-measures every asset from its BYTES
  (a .png that is really WebP, a size or a duration the manifest lies
  about, a still-set under its count, a byte ceiling) against the channel
  specs. --picture adds what each asset LOOKS like, read from its pixels,
  every finding with a code, a severity, a fix hint and a box: blank (a
  wallpaper or an empty canvas where the product should be), duplicate
  (cards of one frame; two is a note, three fails), subject (a card off the
  60 to 92% band, or a crop where a card was asked for; a composed store
  screenshot), separation (a light card on a light ground with no shadow
  halo and no drawn edge), halfsize (a tile that loses its edges when the
  store shrinks it), and, where the manifest records text boxes, sliced,
  safe (the destination's safe rect and word policy) and contrast (APCA Lc
  60 headline / 75 body); a video's first and last frames through ffmpeg
  (firstlast: a cold open on nothing, an end on nothing). An error fails
  the verdict beside the spec problems.

vos judge <kit.json> --against <MANIFEST.json> [--out dir] [--json]
  The kit beside its references. The manifest names the maker's reference
  set (a private folder; id, file, role, layout, facts, rule per asset).
  For every still with a reference of its role (a template family, a card
  genre, a video's first frame) the verb writes two sheets at a common
  height (the asset left, then right, so order cannot bias the call), the
  rubric beside them, and judge.json with a slot per pair; the agent
  judges pairwise, both orders, and the verb reports the win rate beside
  the spec and picture counts (parity 50%; under 40% is not ready to
  market). No model runs inside the verb.

Doc overrides (render + frames) — check any presentation from the CLI without
editing doc.json (disk untouched; the patched doc is LINT-GATED, so a bad
override fails like a bad doc.json). Reach for a flag, not a bespoke harness —
verifying a field and shipping it as a feature are the same act.
  --set path=value   patch any field, repeatable; JSON value when it parses else
                     a string. e.g. --set tilt[0].rx=8 --set frame.padding=120
                     --set frame.browserBar.kind=mac-light --set zoom[0].level=3
  --frame <kind>     (render only — frames --frame <t> is the time selector; set
                     the frame kind on frames via --set frame.browserBar.kind)
                     macos | mac-dark | windows | windows-dark | minimal | none
  --background <url|slug> background media: a URL (kind inferred; .webm/.mp4 =
                     video @10s loop, image otherwise) or a backdrop SLUG from
                     GET /api/backdrops (the set; resolved to its loop and its
                     own period); "none" clears it

vos open <take> [--studio <url>] [--print]
  Serves the take and loads it into the studio (?take=<server>) —
  doc.json arrives INTACT, a human can drag every zoom span. Serves until
  Ctrl-C. The studio is https://vos.so by default (0.48 and later; VOS_ORIGIN
  moves it, --studio http://localhost:6060 for a dev server); --print skips
  the browser. The first time, Chrome (142 and later) asks the person to let
  vos.so reach their local network, a prompt by the address bar: tell them
  to allow it; until then the studio says it could not reach the take.
  In-studio scripting: window.__vos = { openTake, getDoc, edit, undo, redo,
  setSelection } — edits ride the patch store (undoable, like a user's).

vos push <take> [--vos <id>] [--title <t>] [--label <l>] [--note <n>]
                [--folder <id|slug>] [--override <id>]... [--yes]
                [--key <vos_sk_…>] [--json]
  The hosted iteration loop (a content key: --key, VOS_API_KEY, or
  ~/.config/vos/credentials via vos login).
  Uploads the recording ONCE (content-addressed — re-pushes reuse it and
  never count against the 20 recordings/24h; the server measures the
  take, and one over 30 min is refused 413,
  1.5GB is the byte ceiling, and 5 GB of assets per account is the storage
  ceiling — a 409 says to delete a recording to make room),
  lowers doc.json, and creates a PRIVATE vos (first push asks; --yes for
  headless) or a new version against your recorded base (vos.json).
  A take pushes to the vos in its vos.json. --vos <id> on a take with NO
  vos.json ADOPTS that vos: its head is read and named as the base, and the
  take becomes its next version. That is the door for a take re-recorded
  from scratch; never vos pull into it first, pull writes the hosted doc
  over the local one. --vos that disagrees with vos.json, and the flags only
  a program push reads (--slug, --desc, --tags, --base, --remix-of), are
  refused before anything uploads.
  Version pushes are quota'd at 200/24h per key across every vos (429):
  verify a round locally with render/frames and push when it is done.
  A stale base prints the human's typed changelog and exits 1 — run pull,
  re-apply your change on top, push again. A protected conflict means the
  human touched those spans in the studio since your last push: keep their
  values, or --override <id> ONLY when the user asked for that change.
  ALWAYS pass --label (what you did, imperative one-liner) and --note (why:
  the user's ask, one sentence) on every push, the FIRST one included (a
  create mints v1 and stamps them too) — the version history reads
  as a conversation, and an unlabelled push is a turn the human cannot
  read. --note is what the human reads first. History rows and shelf tiles
  name the tool that pushed: @vosjs/cli 0.51+ reads it from the agent's
  environment (claude-code vos-cli), and VOS_CLIENT overrides it (e.g.
  VOS_CLIENT=claude-code/2.1) — display-only; authorship trust always comes
  from the key.
  Cutting a take "in the style of" one of the user's folders? The folder's
  recipes are a SPEC for how every recording there is cut; the seed is the
  NEW recording, the folder's own takes are the reference. Pull the folder
  first (llms-remix.txt, Folders & recipes), apply the spec to doc.json,
  push --folder <id|slug>. Every push renders a still: GET /api/vos/{id}
  (the answer is { vos: { ... } }), follow vos.contentUrls.thumbnail, look
  at it before you report done.
  --wait (0.52+) stays until the version's still has rendered and prints
  its absolute still and preview links. --still <seconds> (0.53+) sets a PROGRAM's
  cover (doc.json "still", kept by every later push); without one the
  platform shoots an early frame. The studio's Cover mark sets it too. A new vos pushed without --folder
  lands unfiled at the root of the shelf, and the done line says so.
  A push carries every local file the document names (0.59+): a take's
  mic and cam beside its recording, picture and video overlays, 3D props
  (a .glb), and sound, each uploaded once and reused on a re-push. Before
  0.59 a take's local mic and cam were dropped and a program sent only
  its sound.
  YOUR OWN FILES, ONE RULE: bring a file with vos asset push (or let vos
  push upload what the program declares), name it in "assets", read it as
  ctx.assets.<name>. Never host a file somewhere else to link it, and
  never type its address into a function. vos assets ls shows what is
  already there.
  A PROGRAM'S OWN FILES are declared (0.60.1+, @vosjs/core 0.27): name
  each picture, video or model in config.json
  ("assets": { "logo": { "ref": "./logo.png", "kind": "image" } }) and
  read ctx.assets.logo, or "$assets.logo" in an element. The path lives in
  config.json's directory or below; one that climbs out is refused, so
  copy a shared file in. vos render, still and preview serve the local
  file to the page; vos push uploads it once (pictures and SVG, video,
  sound, .glb, and since 0.61 fonts and HDR maps) and stores the program
  naming it asset:<id>, while config.json on disk keeps its path. Never type a file's URL or path inside a function:
  it does not load on a server render of a private vos and it does not
  follow a remix. A --claimable push carries no files, so it is refused
  when the manifest names local ones: push with a key.
  SOUND (0.52+) is a track, never an element: name the file in doc.json
  (audio: [{ id, key: "score.ogg", name, start, in, out, duration, gain,
  fadeIn, fadeOut }]) beside the config or the take; vos push uploads it
  and keys the hosted asset, vos render of a program mixes it, the studio
  shows it with gain and fades. vos check warns on an audio element.
  Taking a vos down: vos delete <id|watch-url|dir> (0.52+; asks, or --yes
  headless; a dir that tracked it is unlinked), or DELETE /api/vos/{id}
  with the owner's key. Deleting MOVES IT TO TRASH: nothing is erased, the
  answer is { trashed: true, restoreUntil, restore }, and it stays
  restorable until that date (30 days). vos delete --dry-run (0.59+)
  names what would move and changes nothing: asked to clean up, show
  that list first. If you deleted something by mistake, restore it and
  say so:
    vos trash                         (0.59+; what is in Trash, by whom)
    vos restore <id|watch-url> [...]  (0.59+; back as it was)
    vos trash restore --since 1h      (0.59+; everything THIS key trashed
                                       since then; --by <key name> for
                                       another key's)
  or over HTTP:
    POST https://vos.so/api/vos/{id}/restore        (back as it was)
    GET  https://vos.so/api/trash                   (what is in Trash, by whom)
    POST https://vos.so/api/trash/restore  { "keyId", "since" }
                                  (everything that key trashed since then)
  You cannot make a delete final: only the person can, on the web, at
  vos.so/app/trash. A key deletes only when its owner gave it the delete
  scope (403 says so), and at most 20 things an hour (429). If storage is
  full, tell the person how much is in Trash (GET /api/trash → bytes) and
  where to empty it; deleting does not free room by itself. A vos with no
  version (a refused hosted take's empty shell) is the one thing a delete
  erases.

vos push <config.json> --claimable [--share] [--prompt "<text>"] [--title <t>] [--slug <s>] [--json]
  NO credential needed, PROGRAMS ONLY (a config.json; takes carry
  recordings, which need an account). Creates a claimable vos and prints a
  claim link: hand it to the user and NOWHERE else — it is the only
  reference and the only credential. The link lasts 72h; unclaimed work is
  deleted after that (deliberate cleanup, not data loss — re-push if it
  lapses). Claiming moves the vos into the user's projects and starts its
  hosted preview; iterate after that with their key (vos push --vos <id>).
  Cannot iterate (--claimable with --vos is refused). Config ≤200KB, 5
  pushes/24h per network. THE FILES RIDE TOO (0.63+): every local file the
  program names (config.assets, an element's src, a font's url, a path in
  data, the document's overlays, props and sound) crosses through the
  claim's own upload session, opened with no credential and spent by the
  claim: at most 12 files and 50 MB, sound up to 5 min, video up to 60 s,
  only pictures, SVG, video, sound, models, fonts and HDR. Until the person
  claims it, the claim link is the only way to read them; at the claim they
  are theirs. --share leads the claim page with "Claim and share" (one
  press: claimed and a link anyone can watch); --prompt shows the prompt
  that made it on the watch page (ask first; any program push takes it).
  What a push could not carry is a {"event":"warning"} under --json.
  Raw HTTP: POST https://vos.so/api/claim/uploads → { uploadToken }, then
  each file through POST /api/claim/uploads/files (the account door's
  protocol: begin, parts, /complete, the token as bearer), then POST
  https://vos.so/api/claim { title, slug?, config, prompt?, share?,
  uploadToken? } → { claimUrl, expiresAt, files }. A signed-in vos takes a
  prompt by PATCH /api/vos/<id> { prompt } (null takes it down). The whole
  hosting door: https://vos.so/host.md.

vos pull <take> [--vos <id>] [--media] [--key <vos_sk_…>] [--json]
  Prints what the human changed since your last push (semantic diff per
  version: "zoom z3: level 2.2→1.8" + their notes + the protected span
  list) and writes the head's doc.json back into the take dir, re-anchored
  to the local recording. ALWAYS pull before editing a pushed take. The
  human opens the same take at https://vos.so/studio?vos=<id> — their
  saves join the same version history yours do.
  --media brings the footage HOME: downloads the recording (and mic/cam
  sidecars) beside the doc with your key, re-anchors the doc's keys to the
  local files and writes meta.json/cursor.json, so digest, frames and render
  run on a pulled take exactly as on a local one. A take you did not record
  starts here: vos fetch <vosId> --media (or vos folder pull <slug> --media
  for a project's takes), then vos digest. A private recording needs a
  content key of its owner; files already on disk are kept, never re-fetched.

vos validate <actions.json|take> [--json]
  actions.json: structural check. take: doc.json semantic lints — span
  overlap/bounds, zoom level 1..5, cx/cy in [0..1], speed rate 0.1..16,
  export enums, footage-honesty warning. Must pass before you render.
  A layer that OUTLIVES THE FOOTAGE is a warning to act on: a recording's
  output runs to the end of its last visual clip, so an overlay left behind
  by a trim silently lengthens the render and the clip ends on bare backdrop
  with a note floating on nothing. Overlays are OUTPUT-anchored and a trim
  never moves them: re-place it (vos callout with the same --id), shorten
  it, or put a freeze under it (a freeze counts as footage).
  Also PROBES remote media (doc keys, config element srcs, fonts, data
  URLs): a reference that answers >=400 is a PROBLEM in words ("media
  unreachable ... a render will quietly carry on without it"); a probe
  that cannot run (offline) is only a warning.
  Framing warnings (read them, never suppress them): a zoom that does not
  CONTAIN what was clicked under it is pointing at the past ("points beside
  what was clicked at 12.1s"), and a layer whose box sits over the thing
  being clicked, as the camera shows it at that moment, hides the subject
  (the fix is named: pin it). Both are checked against the cursor track's
  target rects, so a browser-recorder take warns nothing. A pin that names
  nothing is a PROBLEM in words (an unknown or skipped step, a step that
  touched nothing, two referents, a rect in pixels); a scroll or navigation
  inside a pinned layer's window, or a frame with no room beside the
  referent, is a warning.

vos actions from-agent-browser <steps.jsonl> [--out actions.json] [--url <url>] [--viewport WxH] [--json]
vos session open <url> --name <app>        (0.45 and later) a plain Chrome window on a
  vos-owned profile under ~/.config/vos/sessions/<name>: the person signs in and
  closes it; returns then, and prints counts, origins and the newest expiry, never
  a value (--json neither). Exit 1 when nothing landed.
vos session check <name> [--url <url>]     what it holds; with --url, whether it still
  opens the page signed in: exit 0, or 4 with the open command to run again
vos session list | rm <name>
vos actions script <actions.json> [--json]
  The flow as numbered beats in words, for a person recording it by hand
  (0.44 and later): a caption leads its beat, a text selector is said as
  its words, an id as a name; setup steps are named as theirs to do first.
  The walk an agent made in agent-browser becomes actions.json, so a
  feature verified there is a take with no second script. Input: one
  record per command in agent-browser's own batch shape,
  {command:[…], …result}. A bare --json result does not say what ran
  (scroll answers {scrolled:true}), so wrap each call:
    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; }
  or keep a batch's output. Refs (@e27) resolve through the last
  snapshot -i before them to role=<role>[name="<name>"] (-u gives links
  their href); CSS passes through; fill/type become type, press Enter a
  newline into the last field, set viewport the viewport, the first open
  the URL. Reads (get, is, eval, screenshot, tab, session, close) are
  ignored. What the recorder cannot follow (a shortcut key, a drag, a
  coordinate click, a second open, a step that failed in the walk) is
  NAMED in the output, never dropped: read the notes, write those steps by
  hand, then vos record --actions actions.json --strict.

Platform verbs (programs, not takes — the llms-remix.txt loop as commands;
take DIRECTORIES given to push/pull route through the take pipeline above):
vos login [--key vos_sk_…] [--no-browser]  browser sign-in: prints a code +
                                           a vos.so/cli/auth URL (relay both
                                           to the human, keep it running —
                                           the key stores itself in
                                           ~/.config/vos/credentials).
                                           --key skips the browser
vos fetch <vosId|watch-url> [--out dir] [--media]
                                           config.json + vos.json (params
                                           kept). --media (0.60.1+) brings
                                           a program's declared files home
                                           under assets/ and points its
                                           manifest at them
vos check <config.json> [--json]           local: migrate → schema → syntax →
                                           compile → determinism/dialect/font
                                           lints (undeclared font.family warns
                                           — see config.fonts in llms-remix)
                                           and the declared-file lints: a
                                           "$assets.name" naming nothing,
                                           a declared path that is no file,
                                           a hosted file typed in code
vos push  <config.json> [--vos id] [--title t] [--slug s] [--remix-of id]
          [--desc d] [--tags a,b] [--folder <folderId|slug>]
          [--note n] [--label l] [--base versionId] [--override id]...
                                           create a PRIVATE vos with lineage
                                           (--desc/--tags/--folder file and
                                           describe it at create), or iterate
                                           with --vos; the base defaults to
                                           vos.json's tracked one (stale ⇒
                                           409 WITH the platform's typed
                                           changes); keys never publish
vos pull  [dir] [--since versionId] [--check]
                                           the changelog since your base:
                                           attributed versions + summaries +
                                           protected human-edited nodes; syncs
                                           config.json (backup kept), repoints
                                           the base — re-apply, then push
vos duplicate <vosId|watch-url> [--json]   a private sibling of YOUR OWN vos,
                                           head only, in the same folder,
                                           named "Copy of <title>". For
                                           someone else's work the verb is
                                           remix: fetch it and push with
                                           --remix-of instead
vos folder list                            your folders as a tree, with counts
vos folder create <name> [--parent <folderId|slug>] [--desc <text>]
                                           add a folder (nests ≤5 deep)
vos folder move <vosId|assetId|url>... --to <folderId|slug|none>
                                           file voses AND assets into a
                                           folder (none unfiles). Add-only:
                                           rename/delete/reorder stay human
                                           gestures on vos.so
vos folder pull <folderId|slug> [--out dir]
                                           the folder's context package on
                                           disk: recipes/ (+ _inherited/),
                                           members/<slug>/config.json and
                                           doc.json where the version carries
                                           a document (a take, or a program
                                           with layers), each tracked
                                           so vos push lands as a version;
                                           one line per recipe prints its
                                           applies / seed hints
vos asset rename <assetId> <newname.ext>   rename one of your assets in place
                                           (the extension keeps its kind)
vos asset push <file...> [--folder <folderId|slug>]
                                           add files to the library (0.61+):
                                           models (.glb), pictures and SVG,
                                           fonts, HDR maps, sound, video,
                                           captions. The platform reads each
                                           file: the result's "kind" is what
                                           the bytes are, "filename" the name
                                           it is stored under, "ref" its
                                           asset:<id> (what a program's
                                           "assets" takes), "url" the key a
                                           doc.json takes, "reused" true when
                                           you already held those bytes, and
                                           "notes" sentences to pass on (an
                                           SVG is stored as a picture only,
                                           so its scripts are removed). Since
                                           0.63 it also prints the line that
                                           declares the file in "assets". A
                                           file vosso has no use for is
                                           refused in words before anything
                                           is sent. GET /api/limits lists each
                                           kind's formats, size cap and daily
                                           rate
vos asset import <url> [--name <file>] [--folder <slug>]
                 [--license <text>] [--attribution <text>]
                                           (0.63+) fetch a file from an
                                           address and add it, with where it
                                           came from kept beside it. ALWAYS
                                           say the license: only bring a file
                                           its license lets the person use
vos assets ls [--kind <kind>] [--folder <slug>|none] [--q <text>]
              [--sort recent|size|name] [--limit <n>]
                                           (0.63+) what the library holds: id,
                                           kind, size, whether a program uses
                                           it, library or attached. LOOK HERE
                                           before uploading a file again
vos assets usage                           (0.63+) storage held, of how much,
                                           and the part in Trash; the day's
                                           uploads per kind against each rate.
                                           Deleting does not free storage:
                                           only a person emptying Trash does
vos assets why <assetId>                   (0.63+) every program that uses a
                                           file, and how: why it is kept
vos recipe push <FILE.md> --folder <folderId|slug>
vos recipe push <FILE.md> --asset <assetId>
                                           put a recipe on the shelf: --folder
                                           creates it filed there, --asset
                                           replaces one in place (same id,
                                           prior body kept). Read with
                                           vos folder pull. NAME IT IN CAPS
                                           (CUT.md, BRAND.md) — a recipe is
                                           read before anything is made, the
                                           CLAUDE.md role; what a key files
                                           is stored uppercased either way

Creating in the user's style: their project folders hold exemplar voses,
assets and recipe documents an agent should pull before authoring — the
HTTP contract (GET /api/folders, POST /api/vos with folderId) is in
llms-remix.txt ("Folders & recipes").

## Sessions (the product is behind a login)

A recorder with no session meets the wall: the sign-in page, or wherever
the site sends a stranger. From 0.41 record refuses that take with exit 4
and says so; an older CLI records it, and the only symptom is a skipped
selector. Either way, settle the session BEFORE the script. Walk this 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.

(On the fleet, vos record --hosted, only rungs 0 and 1 apply, and rung 1
only as "setup" steps fed from { "env": "NAME" } on the request: a session
never reaches vos.so, so a wall there is a refusal in words that names this
ladder and points back to a machine with a browser.)

0. NO WALL. A public page, a demo mode, a local dev server with auth off, a
   preview deployment. Prefer it when the feature shows the same there. A
   preview behind a bypass header alone is --header name=value on record
   (0.43 and later), the token from the shell, never the script. On a
   machine with nothing installed yet, https://vos.so/agent.md is the
   procedure that ends on this rung: install, find the product, record it,
   open it in the studio, a credential last.
1. MINT, from the test auth the project already has. You are usually in the
   maker's repo, and its e2e suite very often signs in with no human: look
   for 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 and 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; usually
   npx playwright test --project=setup). The artifact is a Playwright
   storage state, which is exactly what --storage-state takes. Look for
   this FIRST, before asking anyone anything: it needs no human and it is
   the only rung that works in CI. (A Firebase session lives in IndexedDB: save the state with
   context.storageState({ path, indexedDB: true }), Playwright 1.51+.)
2. SIGN IN OFF CAMERA, IN THE SCRIPT. A local or self-hosted instance with
   a seeded user whose password is in an env var: put the sign-in in
   "setup" in actions.json (0.43 and later; see the record verb above).
   It runs before a frame is captured, the password comes from the shell
   ({ "env": "NAME" }) and is never logged or stored, and the take begins
   signed in with no state file at all. For an account you must CREATE, or
   an older CLI: a few lines of Playwright, save
   context.storageState({ path }), then record with --storage-state.
   playwright already arrived with @vosjs/cli; launch the system Chrome
   (chromium.launch({ channel: 'chrome' })), and run the script from INSIDE
   the project so the import resolves (only the STATE file stays outside).
   An account you create gets a random throwaway password you never print.
   Never
   put the sign-in in actions.json: every step there is IN the footage, and
   a typed value is logged.
3. THE HUMAN SIGNS IN ONCE. A production app behind an emailed code, SSO, a
   passkey or a CAPTCHA. Run
   vos session open <url> --name <app>          (0.45 and later)
   and 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 when the session is saved; it then prints what the session
   holds as counts and dates, never a value. Then record with
   --session <app> (one door; --storage-state is the other, never both),
   and vos session check <app> --url <url> says in words whether it still
   opens the page (exit 4 = expired, with the open command to run again).
   Nothing to mint, nothing in the take, nothing to delete: the profile
   lives under ~/.config/vos/sessions/ and vos push refuses a take holding
   a state file. Google sign-in refuses an automated browser, which is why
   open is a plain window. On an older CLI:
   npx playwright open --channel chrome --save-storage=<state.json> <url>
   writes a state file for --storage-state when the window closes.
   THE HUMAN IS AWAY? Do not
   open a window nobody will see. Get the script written and validated,
   rehearse once to prove the wall is the only thing left, then STOP and
   leave the ask in words: that one command, "sign in with a demo account
   and quit Chrome", and a script that finishes from the state file.
   Ask in the same note for a faster way in (a seeded account, a test
   sign-in route): that makes the next re-record rung 1. Google sign-in
   usually refuses an automated browser ("this browser may not be secure"):
   when it does, go to rung 4, do not fight it.
4. THE HUMAN RECORDS, YOU CUT. Write actions.json as for any take, with
   ids and captions a person could follow, then vos actions script
   actions.json (0.44 and later) prints it as numbered beats in words with
   the holds you asked for, the page to start on and about how long. Hand
   that over with one sentence: record it with the vosso extension in your
   own signed-in browser, press the icon again to stop. Then vos pull
   <vos-id> --out take --media and cut it (the vos-cut skill); the beats
   you wrote are the moments to look for in the digest. A person's
   recording has no mask and no exposure list, so look at the frames
   yourself. This is a rung, not a failure.

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 a gitignored path the project
  already uses for it). vos push uploads the recording and doc.json, never a
  state file, and nothing about a session ever goes to vos.so.
- A session expires. When a re-record that worked last week skips its first
  selector, re-walk the ladder before touching the script.
- What the account SHOWS ships in the video: use a demo or seeded account,
  never a real customer's. A person who signs in for you will use their
  REAL account, whatever you asked: read the rehearsal's exposure list and
  mask what it names (above). The list reads text only: faces, a
  customer's name in a table, a private chart are yours to notice.

## actions.json (the flow recipe)

{ "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": "type", "selector": "input[name=email]", "text": "demo@example.com" },
    { "do": "scroll", "dy": 400 },
    { "do": "move", "x": 640, "y": 320 } ] }

Verbs: wait · hover · click · type · scroll · move · drag (press-move-release:
drag an element, slide a range input, move a timeline clip — start = selector
center or x/y, end = tx/ty, eased over ms). Selectors: prefer stable
ones (a[href='…'], ids, roles — never nth-child chains).
THE RECORDER'S PACE IS THE SCRIPT'S: a gesture is driven by the clock (a
page that answers each pointer sample slowly costs samples, never
seconds), the pointer travels at a hand's pace, typing is paced at
delayMs, and the only pauses are the ones the script names — wait, a
hover's ms (the dwell), a drag's ms (the travel), a click's ms (the READ
after the page settled, 0.47 and later: held from the page's last visual
change, the recorder pays the settle itself by watching the screencast, so
the same ms reads the same on every run; default 150) and ms on type/
scroll (the settle after the gesture; defaults 150/200). A 25 s script
records in about 25 s plus the gestures. vos record ends with a pace line
(what the script asked, what the gestures added, what the page cost, the
steps that ran slow) and the --json done event carries it as pace; read
it before adding speed spans, which are a choice, not a repair.
PACING IS THE ZOOM PLAN (the planner reads your dwells and your typing):
- open with wait ≥700ms (hydration + a settled first frame)
- hover the things that matter 700–900ms — those dwells BECOME the zooms
- typing is a zoom signal: a type step earns a held frame on its field (the
  click into it opens the span; the camera releases after the last char).
  ~0.6s+ of typing qualifies — pace delayMs like a person (60–90ms), not a paste
- a click's ms is a reading beat: about 1000 after a navigation, 600 after a
  control, never padded for a slow page (the recorder pays the settle); end
  with a settle wait (last frame = poster)
- route the cursor AWAY from hover-triggered menus (they open and blur the
  page behind their scrim); path through page content, not along the nav
- footage resolution = viewport size (dsf 1) — want a 2K video? record at
  2560x1440. Decide at RECORD time; upscaling later is dishonest (validate warns)

## doc.json (the editable document — full JSON Schema ships in the npm
## package at schema/doc.schema.json)

A doc.json is one of TWO documents, told apart by its anchor:
  - a RECORDING document (a take): source + the tracks below. Every
    field below is the recording document's.
  - a PROGRAM document: program + the shared layers (overlays, objects,
    audio, speed, export). program.tweenEdits retimes the config's
    recorded tweens by spec index ({ startTime?, duration?, ease? });
    program.duration is the program's own length when the config's is a
    placeholder. In a program DIRECTORY doc.json omits program.config
    (config.json IS the config); on the wire it carries it. A bare program
    (no layers, no tween edits) has NO doc — config only, as ever. vos
    push/fetch/pull/validate handle both; vos digest reads recordings only.

Time is SECONDS everywhere. zoom/segments/speed are SOURCE-time (footage-
anchored: they follow footage through trims). audio is OUTPUT-time.

  zoom: [{ id, in, out, level, cx, cy, ease?, transition?, focusMode?, source? }]
    level 1..5 (1.4–2.8 reads well; >3x only for genuine detail, briefly).
    cx/cy = focus point as NORMALIZED [0..1] fractions of the video frame
    (0.5, 0.5 = center). NOT PIXELS — pixel values are the #1 agent mistake.
    transition: "instant" | "fast" | "smooth" (default) | "slow" — the
    SPEED of this span's ramps (in, out, and a chained pan arriving here).
    instant = hard cut, fast ≈ half the stock ramp, slow ≈ 1.6×. The same
    field exists on tilt and camMotion spans with the same words.
    focusMode "auto" = camera follows the cursor (needs a cursor track).
    source: "auto" = planner suggestion (replaced on re-plan); set "manual"
    on any span you add or edit — manual spans are never touched.
    Auto ids say their origin: z0… click clusters, k0… typing sessions (a
    frame held on the field being typed into), d0… dwells.
    anchor?: { step, at?, offset? } (zoom/speed/tilt spans, RK2) ties a
    span to an actions.json step (id or index) so vos plan --reuse
    re-times it EXACTLY onto a re-recording — in/out stay authoritative,
    lowering never reads it. Anchor the spans you care about.
  segments: [{ in, out }]   kept footage spans — trim dead time here
  speed: [{ id, in, out, rate, source? }]   rate 0.1..16. The planner
    proposes source:"auto" spans for typing passages, scroll runs and idle
    gaps (ids s0…); set source:"manual" on spans you add or edit — manual
    (or absent-source) spans survive a re-plan. speedParams overrides the
    thresholds/rates (idleMin/idleRate/typingMin/typingRate/scrollMin/
    scrollRate; defaults idle ≥5s→4×, typing ≥3s→3×, scroll ≥2.5s→2×).
  zoomStyle: "glide" (default) | "focus" | "cinema" | "snappy" | "cut"
             | "none"
    glide = one steady zoom that travels between clicks (1.3–1.8×);
    focus = a zoom per click, framed and released, no travel (1.4–2.0×);
    cinema = slow moves and long holds, for content that is watched
    (1.3–1.8×); snappy = quick cycles (1.4–2.2×); cut = instant zoom-ins
    (1.4–2.0×); none = no automatic zooms (manual spans move like glide).
    Every style times the tilt track to its own zoom tempo, so a lean
    lands with its zoom; how far the card leans is tiltStyle. "keynote"
    and "drift" are RETIRED names that still read: glide + tiltStyle
    medium and cinema + tiltStyle subtle (write those instead).
  tilt?: [{ id, in, out, rx, ry, ease?, transition?, source? }]
    Card tilt regions (SOURCE-anchored like zoom, non-overlapping): while
    active the 3D card leans to this pose; between spans it returns to the
    FLAT rest (there is no static card pose). rx/ry are DEGREES
    (±45 hard, ±5..18 reads premium) — NOT radians, NOT fractions.
    Direction: +rx brings the TOP edge toward the camera, +ry the LEFT edge;
    to lean toward a right-side focus use NEGATIVE ry. Ramps and chains
    are the camera style's own (glide 0.6s in / 0.5s out, chained under
    3s; cinema 1.2s / 1.0s under 3.5s), so a lean lands with its zoom.
    Spans need ≥ 0.8s to settle. source "auto" = Dynamic-tilt suggestion
    (replaced on re-plan); set "manual" on spans you add or edit.
    Pacing: tilt is punctuation — at most one pose change per ~5s beat,
    pair it with the zoom moments (same in/out chains the two camera moves),
    never float + strong tilt together on dense UI footage.
  tiltStyle?: "off" | "subtle" | "medium" | "strong"
    Dynamic-tilt wand intensity: the studio derives source:"auto" tilt spans
    FROM the zoom spans (lean toward each zoom's focus, max 5/9/14 deg).
    Absent = off (every style ships flat; intensity is this dial, never a
    style's name).
  cam: { visible, x?, y?, position, size, shape, mirror, window?,
         radius?, border?, shadow? }
    radius = rounded corner in design px (default 18); border = { width
    design px (default 3; 0 = none), color } (default white at 0.9);
    shadow = none|soft|strong (default soft). Absent = the house look.
    Webcam bubble style — the REST pose (only applies when the take has a
    cam track, source.camKey). x/y = bubble CENTER as frame fractions
    [0..1] (win over the position corner anchor); size = diameter as a
    fraction of frame height; shape circle|rounded; window = SOURCE-time
    { in, out } visibility span (absent = the whole take).
  camMotion?: [{ id, in, out, x?, y?, size?, ease?, transition?, source? }]
    ANIMATED cam layout (SOURCE-anchored like zoom/tilt, non-overlapping):
    while a span is active the bubble holds its pose — x/y center fractions
    + size (0.08..0.6) — and morphs there over ~0.65s, settled at span
    start; outside spans it returns to the rest pose (doc.cam); spans
    ≤ ~1.2s apart in output time morph pose-to-pose without returning to
    rest. Absent pose fields inherit the rest pose (a span may move without
    resizing). Spans need ≥ 0.5s to settle. The signature move: park the
    bubble small in a corner, then give it a span front-and-center
    (x 0.5, y 0.55, size 0.45) while you talk to camera, and it morphs
    there and back on its own. Quick check:
    frames take --set 'camMotion=[{"id":"m1","in":3,"out":8,"x":0.5,"size":0.45}]'.
  audio: [{ id, key, name, start, in, out, duration, gain, fadeIn, fadeOut,
            loop?, loopLen?, duck? }]
    OUTPUT-anchored music/SFX. key may be a file you drop into the take dir
    ("/music.mp3") or a hosted catalog track:
    https://assets.vos.so/music/<slug>.mp3 (CC0, loudness-normalized;
    catalog with slugs/moods/durations: GET https://vos.so/api/music, SFX
    at https://assets.vos.so/audio-sfx/<slug>.wav). A music BED: start 0,
    gain ~0.5, duck: true under a voiced recording, loop + loopLen = output
    duration when the track is shorter than the cut (or trim out to the cut).
    gain 0..1. Muxed on full renders only.
  micGain?: 0..1 — VOICE master gain (the mic sidecar on split extension
    takes with source.micKey, else the recording's own audio). 0 = muted.
  systemGain?: 0..1 — system/tab-audio master gain, split takes only (the
    recording's own track when a mic sidecar exists). 0 = muted.
  frame: { background (CSS underlay), backgroundMedia?, padding, radius,
           shadow 0..1, border 0..1, borderWidth?, borderColor?, aspectRatio,
           fit?: "contain"|"cover", focus?: { cx, cy },
           browserBar: { kind: mac|windows|minimal|none } }
    fit (RK1): how footage meets an off-ratio frame. contain (default)
    letterboxes the card onto the background; cover makes the padded area
    the card and FILLS it with footage, cropped around focus (normalized
    video fractions, the zoom cx/cy convention; absent = center, clamped
    gap-free). What a 440x280 store tile or a 2.5:1 marquee demands —
    vos deliver already sets it for cover-fit still destinations.
    border is the card stroke's SWITCH and its alpha (0 = off); borderWidth
    is design px (absent = 1.5) and borderColor any CSS colour (absent =
    #ffffff), drawn at that alpha. The stroke grows OUTWARD from the card's
    edge (a CSS outline), so it never covers the recording.
    backgroundMedia: { kind: "video"|"image", key, duration?, dim } — a vos
    animation or image BEHIND the card. key = media URL or take-dir file
    ("/bg.webm"); a video needs duration (loop length — OUTPUT-anchored modulo,
    so trims/speed never retime it); dim 0..1 = black scrim for legibility.
    THE SET: GET https://vos.so/api/backdrops (no auth) → [{ slug, title,
    duration, ground, urls: { "1080p", "2k"?, poster } }]. Write key =
    urls["1080p"], duration = duration, and frame.background = ground (the
    loop's own colour, painted before the first decoded frame). A loop's
    length is a fact of the asset, never a knob. Under the card, outside the
    zoom; fail-open to the CSS background.
  overlays?: [{ id, kind: "text", start, duration, text, preset, size?, color?,
                family?, weight?, italic?, align?, letterSpacing?, lineHeight?,
                stroke?, box?, maxWidth?, transform: { x, y, scale, rotation },
                enter?, exit?, fx? }]
    Screen-space text clips ABOVE the card, outside the zoom — OUTPUT-anchored
    (start = final-cut seconds; trims/speed never retime a title). Presets:
    "title" (Lexend 600 · 64px) | "caption" (Lexend 400 · 32px) |
    "label" (JetBrains Mono · 22px); size override 12–200; "\n" breaks lines.
    STYLED WORDS ARE RUNS: text is a string, or a list of runs when parts of
    it are set differently:
      "text": [{ "text": "Ship " }, { "text": "faster", "weight": 700, "underline": true }]
    A run is a piece of text plus the fields in which it departs from the
    layer: weight (700 is bold; snapped to the family's hosted weights),
    italic, color, underline, strike, highlight (a colour behind it). There
    is NO markup in the words (an asterisk is an asterisk), a style may start
    and end anywhere, a run may hold "\n", and a per-word or per-character
    reveal keeps every unit in its own style. The retired emphasis field and
    its *markers* are still read; vos validate prints the runs to write.
    family = a hosted catalog family name (GET https://vos.so/api/fonts;
    unknown names fall back to the preset font on the render fleet); weight
    snaps to the weights the catalog hosts; italic is synthesized oblique.
    align = left|center|right (multi-line, default center); letterSpacing in
    design px (-10..60); lineHeight multiplier (0.8..3, default 1.25).
    stroke = outline under the fill: { color, width 0.5..40 design px }.
    box = background pill behind the text: { color, opacity? 0..1,
    paddingX?/paddingY?/radius? in EMs (defaults 0.6/0.35/0.25) } — scales
    with the text through size, transform.scale and resolution alike.
    maxWidth = wrap budget as a FRACTION of the frame width (0.1..1):
    greedy word wrap at measured widths, no intra-word breaks; absent =
    lines break only on "\n". Wrap composes with fx (units regroup onto
    wrapped lines; with unit "line", each WRAPPED line animates).
    transform.x/y are FRACTIONS of the frame [0..1] — the zoom cx/cy
    convention: 0.5/0.5 = center at ANY aspect ratio, a caption's lower
    third y ≈ 0.82; positions survive aspect-ratio switches. NOT pixels
    (validate errors on pixel-looking values, warns off-frame). enter/exit:
    rise|fade|none (~0.35s; defaults rise/fade). Fonts load from the CDN at
    render start, fail-open. Quick check: frames take --set 'overlays=[…]'.
    pin (ANY overlay kind) = the layer's REFERENT, the thing on the page it
    is about: { step | press | rect, side?, gap?, mark?, leader?, color? }.
    A pinned layer is placed a gap off one side of the referent and follows
    it as the camera moves (the layer keeps its screen size; only its place
    follows), so the statement and its subject stay bound. step = a
    recorder step (actions.json id, else its index in meta.steps; hover,
    click, type and drag steps carry the element's rect, kept by the
    recorder on meta.steps[].rect); press = SOURCE seconds, the nearest
    press names the element (a human recording has no steps); rect = video
    fractions [0..1], never pixels. side = auto (default: the first of
    right, left, below, above whose box fits inside the frame through the
    layer's life, else the roomiest) | right | left | below | above; gap =
    design px (24); mark = ring | underline, a standing highlight on the
    referent for the layer's life; leader = a hairline from the layer to
    the referent with a dot at the referent; color = their ink (default
    white over a dark rim). transform.x/y stay the fallback for a pin that
    cannot resolve, and validate says why. A layer with no referent is a
    CAPTION: place it in the margin, never over the app. Try: frames take
    --at 3 --set 'overlays=[{...,"pin":{"step":"copy","mark":"ring"}}]'.
    THE CALLOUT GRAMMAR (write callouts with the verb, never CSS by hand):
      vos callout <take> note|tag|code --step <id> [--kicker "…"] [--title "…"]
        [--body "…"] [--code "…"|--code-file f] [--seconds 3] [--side …]
        [--mark ring|underline|none] [--leader] [--color #hex]
        [--brand BRAND.md | --ground #hex --accent #hex --font "…"]
        [--body-px <n>]
        [--id x] [--print] [--json]
    Three shapes a viewer learns once: note (a kicker, a title, a line),
    tag (one label on the accent), code (the payload block). The card is
    composed from the product's REGISTER — BRAND.md beside the take (vos
    brand <url> --out <take>/BRAND.md: bgA is the ground, accent, fontBody;
    a brand whose accent is RESERVED, a recorder's red that marks time and
    nothing else, names a callout role in the kit and the notes speak in
    that hue instead) or the flags — by the distinguishability rules: it
    INVERTS the app's
    value in the product's hue (a light app gets a dark card, a dark app a
    light one), keeps the accent for the kicker, sets its title at 1.35× the
    app's body AS SEEN ON SCREEN at the layer's start (the camera's level is
    read from the document), lifts on a real shadow and a hairline, rises
    in and fades out. --body-px <n> instead sets the body size on the
    DELIVERED frame and is never rescaled: a rich capture (2560 wide on a
    padded frame) sits near scale 0.6, where every default lands on the
    grammar's floor (11 / 20 / 15 px) and reads small; --body-px 21 gives
    15 / 28 / 21. The verb prints the three sizes and the scale it measured
    (sizes in --json). --color paints the pin's mark and leader, never the
    kicker, which is the accent. A face is written under the hosted
    catalog's name (Inter Variable becomes Inter), or it would fall back. Its window opens a beat after the step's press lands
    and closes before the next scroll or navigation; it is pinned to the
    step. --at <s> --seconds <n> places one without a step; --print prints
    the clip instead of writing it. vos validate <take> --picture renders
    the footage under every html layer and reports the ΔE between the
    card's ground and what it covers: under 8 a PROBLEM (the card reads as
    one more panel of the app), under 16 a warning; an unpinned html or
    media layer whose window holds a step with an element gets the pin
    named in a warning.
    fx = entrance animation (text only), pure f(t) — scrub, export and
    chunked server renders agree by construction:
      { fx: fade|rise|pop|blur|typewriter, unit?: block|line|word|char,
        direction?: forward|reverse|center, stagger?: 0..2 s, duration? }
    fx OWNS the entrance (enter is ignored; exit stays). unit default block
    (= the legacy enter, generalized); char is grapheme-safe. stagger is
    seconds between unit starts (defaults: typewriter 0.05, others 0.06
    when unit ≠ block; clamped so the entrance fits the clip). typewriter
    is a step reveal by unit count — pair it with unit char or word.
    Try: frames take --set 'overlays=[{...,"fx":{"fx":"typewriter","unit":"char"}}]'.
    Media kinds (image|video): key (take-dir file or URL — REQUIRED),
    width = FRACTION of the frame width (default 0.35; height follows the
    media's aspect, × transform.scale), radius design px (default 12),
    opacity 0..1, loop (video; else the last frame holds),
    shadow "none"|"soft"|"strong" (default soft — the house card look),
    border { width design px, color } (absent = none). Video time is
    CLIP-LOCAL (t − start) and muted — soundtracks belong to doc.audio.
    HTML kind: { id, kind: "html", start, duration, html, css?, box: { width,
    height }, bleed?, fonts?, width?, opacity?, live?, data?, transform,
    anim?, motion? }.
    A UI component authored as MARKUP and CSS, laid out and painted by the
    browser and composited over the footage, sharp at ANY export size (it is
    rasterized from source, never magnified from the footage). Point at a
    component with a layer, not a zoom. html is well-formed XML (<br />,
    &amp;, quoted attributes; validate refuses the rest in words, because a
    malformed layer decodes to nothing and says nothing). box is the design
    box in 1080p px (the frame is 1920 wide); width defaults to the design
    size (the box plus its bleed over 1920). A callout names what it is
    about with pin (above) and is placed beside it; the gap is measured
    from the box, never the bleed. The CSS IS the chrome (shadow,
    radius, border); bleed = room for what paints outside the box, derived
    from the shadows when absent. A font-family the CSS names resolves
    against the hosted catalog (GET https://vos.so/api/fonts) at every
    font-weight it names; a face outside the catalog rides fonts: [{ family,
    url }]. An image inside is inlined for you when its URL is on
    https://assets.vos.so/ (the platform's own catalogs). Any other
    address paints blank (an SVG image fetches nothing), a file of your
    own on vos.so included, so inline it as a data: URI. A STILL layer's animation or transition runs on the WALL CLOCK,
    never the timeline, so the export cannot match the preview: animate the
    layer with anim and motion, or make it LIVE. live: true re-rasterizes
    the layer per frame at clip-local t: its @keyframes are scrubbed to t
    (paused, delayed by -t; fold any animation-delay into the keyframes),
    and {{t}} / {{data.<name>}} placeholders in the markup and CSS fill from
    the clock and the clip's data ({ name: string | number | boolean },
    written as text), so a counter, a progress bar or a typed line come out
    on the timeline's clock in the preview, a still and every export chunk
    alike. No key, radius, shadow, border, loop or frame: the layer refuses
    them by name. Never re-hosted, never an upload. Quick check: frames take --at 3 --set 'overlays=[{"id":"h0",
    "kind":"html","start":1,"duration":4,"html":"<div class=\"c\">Open
    Code</div>","css":".c{font-family:'Inter';background:#0b0b0d;color:#fff;
    padding:20px;border-radius:16px;box-shadow:0 24px 60px rgba(0,0,0,.45)}",
    "box":{"width":452,"height":132},"transform":{"x":0.7,"y":0.5}}]'.
    motion = pose keyframes (ANY overlay kind) — the transform animated
    over CLIP-LOCAL time, pure f(t):
      motion: [{ at, x?, y?, scale?, rotation?, opacity?, ease? }]
    "at" is seconds from the clip's start (poses ride along when the clip
    moves). Values interpolate across the gap between poses (default ease
    power2.inOut; a hold is two identical poses); the base transform holds
    until the first pose, and absent pose fields inherit it — so
    [{at:0},{at:2,x:0.8,scale:1.4}] slides and grows the element over its
    first two seconds. opacity is a 0..1 MULTIPLIER on the clip's alpha.
    Try: frames take --set 'overlays=[{...,"motion":[{"at":0},{"at":2,"x":0.8}]}]'.
  objects?: [{ id, asset: { kind: "primitive", shape: "cube"|"sphere"|"torus"|
               "knot", color? } | { kind: "gltf", key } | { kind: "text3d",
               text, typeface?, material?, color?, depth?, bevel? },
               span?: { start, duration },
               transform3d: { x, y, z, rx, ry, rz, scale },
               animation?: "spin"|"float"|null }]
    World-space 3D props between the card and overlays (V3; the drafted V4
    engine spec). x/y = FRACTIONS of the frame; z = world units toward the
    camera from the card plane (0 = on it; 0.5 floats in front — props may
    overhang the card); scale = fraction of frame height (default 0.18);
    span = OUTPUT seconds with soft fades (absent = always); animations are
    deterministic. gltf keys load real GLBs (URL or take-dir file),
    bbox-normalized so scale matches primitives; fail-open.
    motion = pose keyframes over transform3d, CLIP-LOCAL time (seconds from
    span.start; 0 when span-less):
      motion: [{ at, x?, y?, z?, rx?, ry?, rz?, scale?, ease? }]
    Same semantics as overlay motion (interpolate-over-gap, absent fields
    inherit the base, default ease power2.inOut); spin/float presets compose
    ADDITIVELY on top — a prop can fly in on poses while it spins.
    text3d = extruded 3D text (TX7): typeface is a catalog slug or family
    (Lexend | Space Grotesk | Bebas Neue | Archivo Black | Anton | Righteous
    | Playfair Display | Fraunces | Pacifico | JetBrains Mono; unknown falls
    back to Lexend); material: standard|metal|glass|neon (fleet-audited —
    single-sided, no dispersion; default standard); depth = extrusion as a
    fraction of glyph height (0.02..1, default 0.25); bevel default true.
    Geometry is bbox-normalized like GLB, so scale means the same thing.
    Edits are live data edits (the mesh pool rebuilds by asset signature).
  cursor: visible/hideWhenIdle/smoothing/size/click-effect styling.
    visible:false hides the drawn dot only — the track still drives
    cursor-follow zoom, and click effects keep drawing (turn those off with
    clickFx.style:"none"). hideWhenIdle (default true) fades the dot out
    after ~1s parked and back in when it moves; scrolling does not count as
    movement, and it is always back at full opacity on a click
  export: { resolution: "720p"|"1080p"|"2k"|"4k", fps: 30|60, format: "mp4" }
    never set resolution above the footage (validate warns which preset
    "matches the recording")

## The quality loop (do this, in order)

0. record --dry-run --json         → exit 2? fix the script; nothing was spent
                                     exit 4? no session: walk "Sessions"
1. record --strict --json          → exit 2? fix the flow, re-record
2. validate take --json            → lints must pass
3. frames take --at-zooms --json   → LOOK at every still (zoom apexes hardest):
   subject composed with breathing room? text legible? cursor resting on the
   subject? nothing unintentionally blurred? first/last frame poster-worthy?
4. edit doc.json → render --range a..b --draft → re-frame the changed region
5. full render → frames --at-zooms once more before declaring done

Story rules: ONE idea per clip; open near the money shot (point visible in
3s); 8–15s is the marketing sweet spot, ≤30s max; end settled — the last
frame loops into the first.

## Timings (M-series laptop, measured)

Record = real-time + a few seconds encode. Render ≈ 1.5x real-time at 1080p
(12.5s take ≈ 19s; ~5s is fixed browser+CDN startup). Draft range check ≈ 5s.
Frames sheet ≈ 2s. 2K ≈ 2x per-frame cost.

## Headless captures of vos.so itself

Append ?theme=dark|light to any vos.so URL for a deterministic theme (persists
to localStorage before first paint — no hydration race).

## Smoothness (the north star — the record done event measures it)

record reports dead (0.46 and later): a still frame under a PARKED cursor
past the beat it takes to read what changed, per step — {ms, pct, steps:[{step,
id, do, settledMs, heldMs, deadMs}]}, where settledMs is how long the page kept
changing after the step's press and heldMs how long the settled frame was then
held. The beat is ~1 s after a page changed, 0.6 s after a control did. Keep
dead.pct ≤ 20 and no single dead hold over 1.5 s; the take-ready line names the
steps. freezes[] + freezePct (stretches ≥400ms with no visual change) stay as
the plain fact of stillness and are NOT a defect on their own: a page being
read is content, and a workspace tour is mostly still. Never choose a flow to
make freezePct smaller. Fixes, in order:
- cut the named steps' ms to their beat: a hold is what it takes to read what
  changed
- keep motion in frame where the flow allows: hover things that respond with
  motion (vos.so gallery cards play their video preview on hover — the best
  dwell target), live canvases, scrolls
- trim what's left: segments cut dead heads/tails; speed spans compress lulls
- full-frame bangs (filter clicks, navigations) read as jump cuts — let them
  happen WIDE (zoom into the result, not the trigger); census your final
  render with ffmpeg select='gt(scene,0.12)' — every detection should be a
  transition you chose.

## Credentials (only cloud features need one)

Everything in this file runs locally with NO auth. Cloud seams (pushing a
saved program to vos.so, the Render API) ride an API key. Resolution order
before asking the user: 1. the VOS_API_KEY environment variable ·
2. ~/.config/vos/credentials (first line; vos login writes it) ·
3. a vos_rg_ remix grant
embedded in your prompt (24h, bound to one source vos). A person signed in
on vos.so may hand you a line naming https://vos.so/h/vos_ho_…: that link
is a SETUP GRANT, and vos login --handoff <that url> (0.48.1 and later)
exchanges it, once, for a content key named cli:<hostname> with no click
from them; the link then expires, and a second exchange says so. It can
do nothing else (no read, no push), so never send it as a bearer. No
credential resolves? Run vos login: it prints a code and an approval URL
(vos.so/cli/auth?code=…) — relay BOTH to the human and keep the command
running. They sign in, check the code matches, click Approve, and the CLI
stores the key itself (a content key named cli:<hostname>, revocable at
vos.so/app/api). The code lasts 15 minutes; denial and expiry exit with
the reason. Humans can also mint durable keys at https://vos.so/app/api.
Never print a credential — vos login never prints one either, not even in
--json events. The push/remix contract lives at
https://vos.so/llms-remix.txt

## Feedback (when a vosso tool breaks on you)

POST https://vos.so/api/product-feedback with
{ "kind": "problem"|"idea"|"other", "message": "<what happened, ≥10 chars>",
  "surface": "cli"|"api" } — auth optional (a bearer key attaches your
identity so the founder can reply). Rate limit 10/day. The founder reads
every submission; include the failing command and the done-event error when
reporting a CLI problem. Humans use https://vos.so/feedback

## Links

- https://vos.so/agents — the agent page (the loop, the Action, the contract)
- https://vos.so/agents — the agent door (stack table, CLAUDE.md rules block)
- https://vos.so/llms-remix.txt — remix a vos program with your agent + push it back
- https://www.npmjs.com/package/@vosjs/cli — README = canonical reference
- https://github.com/vosjs/vos — the MIT engine underneath