@vosjs/cli 0.46.1 → 0.48.0

package/skills/vos-create/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: vos-create
+description: Create vos programs in the user's own style — pull their vos.so folder, read every recipe (.md) and exemplar in it, author VosConfigJson that follows them, validate + render + judge headlessly, and push into that folder as attributed versions the human edits in the studio. Use when asked to make a vos “like my X folder” / “in my usual style”, to build or extend a collection, or to spread a signed-off seed into variants.
+license: MIT
+---
+
+# Create in the user's style, from their folder
+
+You create **vos programs that belong to a folder**: the user's folder on
+vos.so is the collection, its `.md` files (recipes) are the style, its
+voses are the exemplars. This skill carries only MECHANICS and the
+universal craft floor. Taste is user data and lives in their folders,
+never here. Authoring rules (schema, dialect, knobs) live in the
+`vos-authoring` skill; knob and Looks craft in the `vos-remix` skill's
+params-knobs reference. This skill adds the folder contract, the loop and
+the process around them.
+
+There is no inbox and no house style file. Dedup is the folder's own
+contents; the shelf is the record.
+
+## Setup
+
+```bash
+npm i -D @vosjs/cli   # folder, fetch, check, still, render, push
+```
+
+Credentials, in this order, never printed: `VOS_API_KEY`, then the first
+line of `~/.config/vos/credentials`, then `vos login` (a browser sign-in
+that mints a key for this machine). Every HTTP call below is
+`Authorization: Bearer <key>` against `https://vos.so/api`. Keys create
+PRIVATE work only and can never publish.
+
+## The five steps
+
+### 1. Resolve the target folder
+
+The user names it, or you ask which. `vos folder list` (or
+`GET /api/folders`) finds it by name or slug across all levels; then pull
+it:
+
+```
+GET https://vos.so/api/folders/{id}
+```
+
+One pull is the whole context package: the folder's own `recipes` (bodies
+inlined), its `inheritedRecipes` (ancestor recipes, root first, each
+marked with its source folder; they BIND this folder), exemplar `voses`
+with `contentUrls`, and `assets`. Subfolders are listed, not inlined: a
+pull is the folder's own contents.
+
+No folder yet? Create one, **always with a description**:
+
+```bash
+vos folder create <name> --desc "<one line on what this collection is>"
+```
+
+A folder minted without a description is a naming failure; the
+description is what the folder page and every future pull read.
+
+### 2. Read EVERY `.md`, then the exemplars
+
+Read every recipe body, the folder's own AND the inherited ones, and 1 to
+3 exemplar configs or docs through their `contentUrls`. Recipes are
+role-named facets, named in CAPS the way `CLAUDE.md` is: `TASTE.md` is
+the judging bar, `DESIGN.md` the technique spec, and whatever else the
+user's intent created (`MOTION.md`, `COPY.md`, `BRAND.md`, ...). A recipe
+is the file a collection reads before it makes anything, and the name is
+what says so; a recipe you file is stored with its stem uppercased, so
+write it that way and the shelf shows what you wrote. The platform
+enforces no taxonomy beyond that; you read all of them. The binding
+rule:
+
+- Recipes and exemplars **override every default this skill or the
+  authoring skill has**. Their duration is the duration; their palette
+  discipline is the discipline.
+- On conflict between files, the more specific wins: the folder's own
+  files beat inherited ones, nearer ancestors beat farther, and a
+  specific instruction beats a general one. A genuine contradiction goes
+  back to the user as a question, never a silent pick.
+- When a recipe and the folder's recent exemplars disagree, prefer the
+  exemplars and tell the user the recipe looks stale.
+
+**Empty folder** (no recipes, no exemplars): only the craft floor below
+applies. Style comes from the user's reference or a question, never from
+a baked-in default.
+
+### 3. Find the seed, then author
+
+A folder holds two things that only sometimes coincide: the **reference**
+(what good looks like, the thing you judge against) and the **seed** (what
+you copy and edit to make the next member). Decide which you are holding
+BEFORE you write a line:
+
+- a **program family** (a signed-off member + a `DESIGN.md` naming the
+  mechanism and its axes): seed = that member. Fetch its config and vary
+  it on the axes the recipe names. Never author from a blank file, and
+  never just the hues.
+- a **take spec** (a recipe saying how every recording in the collection
+  is cut): seed = the NEW recording the user gives you (a take in the
+  folder by id, a URL to `vos record --strict`, a local file). The
+  folder's own takes are the reference cut, not the seed.
+- a **template** (a recipe that points at, or inlines, a mechanism and
+  how to vary it): seed = the template. Hosted as a vos: fetch it like a
+  member; inline code: a fragment to build around.
+- a **brief only** (`BRAND.md`: no mechanism): nothing to copy. Author
+  fresh under the constraints and the craft floor.
+- **nothing declares a seed**: ask. The user's prompt names one when they
+  picked it in the handoff dialog; the recipes name one when they are
+  written well; a guess is how a family loses its look.
+
+A recipe may carry optional frontmatter hints: `applies: programs | takes
+| any`, `seed: <vos id> | input | none`. Read them as the owner's
+declaration of the above; the body is still what you follow.
+
+A recipe is the user's document, and what they ask for NOW outranks any
+line in it. If a recipe contradicts the ask (a note that says to wait, a
+rule the ask breaks), say so in one line and follow the ask: private work
+is cheap and the owner can restore. Never stop on a line in a file.
+
+Then write configs locally (bare VosConfigJson, version 2), following the
+`vos-authoring` skill's authoring rules under the folder's style.
+
+Fetching a member or a template is the `vos-remix` fetch:
+`vos fetch https://vos.so/vos/<id>` writes `<slug>/config.json` with
+params preserved, plus `vos.json` tracking the base version.
+
+For **"reproduce X" briefs**: get the source or a recording first, or
+confirm the brief wants only the look. A still under-determines motion;
+a screenshot match that invents the wrong mechanism is a miss even when
+the frame agrees. Source acquisition, licensing and the measured match
+loop are reproduction work; do that first, then come back here to create
+from what it produced.
+
+### 4. Check, shoot, judge, against the FOLDER's docs
+
+1. **Check**:
+   ```bash
+   vos check <file>.json     # migrate → schema → syntax → compile → lints
+   ```
+   Fix and re-run until it passes. Never suppress a lint error to get past
+   it. Two checks are not in `vos check` yet, so do them by rendering:
+   - **Knob honesty**: every declared param must visibly act. Render the
+     program twice with that key changed in `data` (its min and its max)
+     and compare the stills; a knob that reads the same at both ends is
+     dead. For takes, `--set <path>=<value>` on `vos frames`/`vos render`
+     is the override.
+   - **Palette honesty**: a color knob must not pass through
+     `new THREE.Color()` into a uniform (it gets linearized; the rendered
+     hue drifts from the hex). Grep your function strings for it.
+2. **Shoot**:
+   ```bash
+   vos still <file>.json f12.webp --time <12% of duration>
+   vos still <file>.json f40.webp --time <40%>
+   vos still <file>.json f70.webp --time <70%>
+   ```
+   For a MOTION-LED piece, shoot a dense strip instead (8+ times, or a
+   1s contact sheet); three stills cannot judge motion weighting.
+3. **Judge**: score the frames against the craft floor below AND the
+   folder's own docs. A collection piece answers to both the collection's
+   `DESIGN.md` and the inherited `TASTE.md`. Revise and repeat (max 3
+   rounds); if it still fails, drop it and say why. Never push work you
+   would not defend.
+
+### 5. Push INTO the folder, iterate as versions
+
+```bash
+vos push <file>.json --title "…" --desc "one line" --tags a,b \
+  --folder <folderId|slug> --label "what you did" --note "why: the ask"
+```
+
+Pass `--label` and `--note` on EVERY push, the first one included: a
+create stamps them on v1, and the history is the conversation the human
+reads. The push creates a PRIVATE vos on the key owner's shelf, filed
+into the folder you pulled; preview and thumbnail render on the cloud off
+the save itself. Iterate with `--vos <id>` against the tracked base (the
+`vos-remix` loop: `vos pull` before every round, human-edited nodes are
+protected, `--override` only on explicit instruction). Keys can never
+publish; promoting is the human's gesture on vos.so.
+
+**Look at what landed.** Every push renders a still within about 15
+seconds: `GET /api/vos/{id}`, follow `contentUrls.thumbnail`, and view the
+image before reporting done. A push you never looked at is not finished.
+
+**Pace a batch**: back-to-back pushes are fine at the quota (the render
+queue spaces browser launches and backs off itself). Verify state after a
+batch with a folder pull, never by grepping the push log.
+
+**Write findings back.** When you learn something about the family (a
+parameter range that bands, a duration that reads better), append it to
+the relevant recipe under a dated `## Agent notes` heading:
+`PUT /api/assets/{id}/file` with the full markdown body (recipes only,
+≤64KB). Never rewrite the owner's rules. The
+replaced body is kept: `GET /api/assets/{id}/file?prev=1` reads it and
+`POST /api/assets/{id}/file/restore` swaps it back.
+
+## The family process: seed, look, spread
+
+New-family work is **1 seed + a recipe**, never a batch. A batch
+replicates a bug into every member at once; a single seed catches a
+direction change at n=1, then spreads cheaply. This is judgment, not a
+gate: there is no status line to write or obey, and the user's ask
+always decides.
+
+1. Author ONE seed, land it in the folder, write (or update) the family's
+   `DESIGN.md` with the mechanism, axes and palette rules.
+2. Show it. The human iterates with you (attributed versions). When they
+   ask for variants, that IS the sign-off; when a folder holds one young
+   member and the ask is open-ended, make one first and say why.
+3. Spread when asked. **Variants vary composition axes** (structure,
+   motion grammar, density, camera), never just hues; a hue-only spread
+   reads as one tile ten times. Cap a spread at about 10 so the shelf
+   review stays a 5-minute task.
+
+## Craft floor (universal, lintable: the bar that is NOT taste)
+
+- **Compiles and validates**: `vos check` passes clean; never suppress.
+- **Deterministic**: seek is a pure function of t (no `Date.now` or
+  `Math.random` in frame paths; the determinism lint enforces it).
+- **Loop-seam math**: for looping pieces, phases must be integer multiples
+  over the duration so frame(0) ≈ frame(end). Stills cannot show the
+  seam; verify it in the math.
+- **Honest knobs**: 2 to 4 declared params, every one visibly acting at
+  both ends of its range. Fewer honest knobs beat many.
+- **Knobs are read in `onFrame`, every frame**, never snapshotted into
+  uniforms inside `createContent`. The editor delivers a knob edit as
+  live data that only swaps `ctx.data`; a creation-time snapshot never
+  updates until refresh.
+- **Non-blank first frame**: the ~12% frame doubles as the thumbnail; no
+  black, empty or "hasn't started yet" openings.
+- **No banding, no clipping**: add grain against banding; keep bloom off
+  blowout (strength ≤ ~0.8 unless the folder's docs demand it); no
+  visible tiling seams or hard aliasing.
+- **Palette honesty**: color knobs never pass through `new THREE.Color()`
+  into uniforms; build the raw vector from the hex.
+- **Server-render constraints** (the preview fleet is software-GL): no
+  `THREE.DoubleSide` on transmission materials, no `dispersion`, every
+  fetched asset an absolute `https` URL the fleet can reach.
+
+Everything past this line (duration, density, mood, materials, palette
+discipline) is the folder's to say.
+
+## Report
+
+End with one table: `slug · concept · tags · outcome` (pushed / dropped +
+why), plus the folder URL (`https://vos.so/app/projects?folder=<slug>`).
+State failures plainly: a dropped design is a correct outcome, not an
+error to hide.
+
+## Hard rules
+
+- References are creative direction. Porting external code needs a
+  compatible license AND the user's explicit direction; branded or
+  trademarked compositions are refused.
+- Never publish, never flip visibility. Pushes are private by
+  construction; promotion is a human decision on vos.so.
+- The shelf is the human's: create folders and file YOUR work; never
+  rename, move, delete or reorder what they made.
+- Never print a credential, in output, logs or the report.

package/skills/vos-cut/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: vos-cut
+description: Cut a screen recording (a vosso take) into the product video it was recorded for, from its evidence, with the vos CLI — read the take's digest (the moments the cursor track says mattered, each with a footage frame and a crop), narrate beats, edit doc.json by exception over the planners, verify with stills, and push an attributed version the human fine-tunes at vos.so; every edit is a data patch, so a re-cut never re-records. Use when asked to edit or cut a recording, make a product video or what's-new clip from a take, cut it like the last one, or cut a series of recordings in one style.
+license: MIT
+---
+
+# Cut a take from its evidence
+
+You are cutting a RECORDING somebody made (a vosso take: `recording.webm` +
+`cursor.json` + `meta.json` + `doc.json`), not recording one. Recording from
+a script is the `product-video` skill; programs are `vos-create`/`vos-remix`.
+
+The loop is: **see → narrate → decide by exception → verify → push → (human
+looks) → re-cut**. Every step names the verb that does it. The document is
+`doc.json`; the contract for its fields and units is
+https://vos.so/llms-full.txt. Nothing here re-records a human's take, ever:
+a cut cannot fix footage, and if the footage cannot carry the ask, you say so
+in the note and stop.
+
+## Setup
+
+```bash
+npm i -D @vosjs/cli   # fetch, digest, plan, frames, render, push, pull
+```
+
+Credentials, in this order, never printed: `VOS_API_KEY`, then the first
+line of `~/.config/vos/credentials`, then `vos login` (a browser sign-in that
+mints a key for this machine). Keys create PRIVATE work only and can never
+publish. A Chromium is needed for `digest`, `frames` and `render`.
+
+## 0. Ground rules that override everything below
+
+- **Never read the video.** Your eyes are `vos digest`: `digest.json`, then
+  `sheet.png`, then a crop only where you must decide. A 90s take is ~35
+  moments and ~25-40k image tokens if you read every image; the sheet plus
+  the decisive crops is ~10k. The done event prints the estimate.
+- **Edit by exception.** The planners (zoom, speed, tilt) already answered
+  WHERE every click, typing session, scroll run and idle gap is. `plan` in
+  the digest holds their spans and `proposed` names the ones under each
+  moment. Keep, merge, drop or retime those; add only what a planner cannot
+  know (which lone click deserves a beat, a caption, a speed-through that is
+  boring but not idle). Every span you touch carries `"source": "manual"`.
+  A proposal you DROP goes into `rejected` (`[{id, lane, in, out}]`, the
+  lane and its source extent) so no re-plan, and no re-record carried by
+  `plan --reuse`, proposes that beat again; the studio writes it itself
+  when a human deletes an auto span.
+- **Point with a layer, not the camera.** When the cut points at a
+  component (a button, a card, a code block) and the zoom would magnify
+  pixels, redraw it as an html layer in `doc.json` (`overlays[]` with
+  `kind: "html"`: the markup, the CSS in the product's own type, the design
+  box in 1080p px) placed beside its subject, never over it. You have the
+  product's real components in the repo; use them. The markup is well-formed
+  XML and `vos validate` says what would not paint; a CSS animation runs on
+  the wall clock and is refused in favour of `anim` and `motion`.
+- **The doc's units, copied, never converted.** A moment's `focus` is a zoom
+  span's `cx`/`cy`; its `rect` is what the zoom must contain. `source`
+  extents are footage seconds (zoom/speed/tilt/segments); `output` extents
+  are rendered seconds (overlays/audio). Pixel values anywhere are the #1
+  mistake.
+- **Human edits are sacred.** `doc.manual` in the digest counts spans a human
+  decided; a push that touches a node the human edited since your base 409s
+  as `protected_conflict`. Keep their values unless the ask names that exact
+  node.
+- **Three rounds alone, then a human.** Round = edit → validate → frames →
+  judge. If it will not land in three, push the best round and say why.
+- **The ask decides; the folder's recipes rank next; these defaults last.**
+  A recipe line the recent members contradict is called stale in your note,
+  not obeyed.
+
+## 1. See
+
+```bash
+vos fetch <vosId> --media        # a hosted take you did not record (doc + footage home)
+vos pull <take> --media          # a take dir already linked to vos.so
+vos folder pull <slug> --media   # a project's takes, recipes included
+vos plan <take> --style <seed doc.json|vosId>   # in a series: the seed's style, by data
+vos digest <take> [--transcript whisper.json] [--style <seed>]
+```
+
+Read, in this order:
+
+1. `digest.json` → `take` (duration, page, has cursor/mic), `moments`
+   (id, kind, source/output windows, focus, rect, activity, proposed, said),
+   `plan`, `doc.manual`. A take with `hasCursor: false` (a browser-recorder
+   take) lists head/tail/scenes only: pace by `activity`, zoom only where the
+   ask names a place, and say in the note that the take had no cursor track.
+2. `sheet.png` → the crops in time order, ids burned in. This is the film at
+   a glance.
+3. `m<nn>.crop.png` for the moments the ask or the recipe makes decisive;
+   `m<nn>.full.png` only for context (what page, what section).
+
+Reading a crop: what is in focus (a control, a field, content); what it says
+(the label, the value typed); is the click's consequence visible in the next
+moment's frame or in a `scene` moment right after it. A `scene` is a
+frame-diff jump (a navigation, a dialog); look at its full frame to name it.
+
+Two things the crops say that the click list does not: a click cluster whose
+`rect` is most of the frame is a DRAG (aiming, scrubbing, moving a thing),
+not a target; and an "idle" gap whose `activity` stays above ~0.1 is the
+video PLAYING, not idle. Neither wants the planner's proposal.
+
+If a folder is involved, read EVERY `.md` in it (own and inherited) before
+you decide anything.
+
+## 2. Narrate
+
+Write 3-6 beats into your working notes, each with its moment ids, what it
+SHOWS (from the crops) and what it is FOR (from the recipe, the page title,
+`said`, or the ask). Example:
+
+```
+B1 m01-m04  the gallery: browse, pick a program            (open wide, one card zoom)
+B2 m05-m06  Remix opens the studio                          (the scene is the payoff)
+B3 m07-m12  knobs: five slider drags on the remix panel     (one held zoom, 2× over the middle)
+B4 m13-m14  the result plays out                            (release, settle)
+```
+
+No ask came with the take? Infer one from the recording (what it shows,
+where it would be shown, how long it should be) and STATE IT in the version
+note, so the human corrects the ask before the cut when it is wrong.
+
+If the ask names a beat ("make the export part snappier"), map it to moment
+ids FIRST and touch nothing outside them.
+
+## 3. Decide, by exception
+
+Per beat, against `plan` and the recipe:
+
+- **Zoom.** Keep the planner's span when it frames the beat; merge adjacent
+  proposals into one held span when they are one beat (one zoom per beat,
+  never per click); drop a proposal on a click that is not a beat; add a
+  span on a lone click the planner skipped when the crop shows it is the
+  moment. Level from the rect: a small control wants 1.8-2.2, a panel
+  1.4-1.6; when the target is most of the frame's width, the framing lint
+  decides the level, obey it. `cx`/`cy` = the moment's `focus`. Ids you
+  mint: `u1`, `u2`… In an editor recording, zoom the LANE where a span
+  appears, never the canvas being dragged. Release a zoom BEFORE a click
+  that navigates, so the page swap plays wide.
+- **Speed.** Keep proposals on typing/idle/scroll; add `2×`-`3×` on a stretch
+  whose `activity` is low and no beat needs, or under drag clusters; never
+  over a beat's payoff, never over playback.
+- **Tilt.** Only if the camera style has one (`tiltStyle`/the style's
+  personality) and a beat earns punctuation. One pose per ~5s, ±5..18°.
+- **Trim.** Head and tail: cut to the first and last thing that matters
+  (`segments`), leaving ~0.5s of settle at the end. Loading screens are cut.
+- **Text.** A caption per beat that has something to say, at a cadence (one
+  every 5-10s, 2.5-4s each, never two at once), in the product's words and
+  the video's intention; lower-third `y ≈ 0.82`; OUTPUT seconds; never over
+  the clicked control (validate warns). The clip's shape is `{ "id", "kind":
+  "text", "text", "start", "duration", "transform": { "x": 0.5, "y": 0.82 } }`
+  (`start` and `duration`, never `in`/`out`, which are the source lanes').
+  Give it a `box` (`{ "color": "#111111" }`) when the ground under it is
+  light (an editor's timeline is), and judge every caption at its own
+  instant. One caption per film is too sparse for a film that explains a
+  flow; zero is right only when the recipe or the ask says no text.
+- **Style.** In a series, `vos plan --style <seed>` BEFORE you cut: it copies
+  the seed's `zoomStyle`/`zoomParams`/`speedParams`/`tiltStyle`/`frame`/
+  `cursor`/`cam`/`export` and re-plans the auto spans under them. Never
+  restate those numbers in a recipe; the seed's doc is their home.
+
+Write the patch as EDITS to `doc.json`, never a rewrite. Keep every field you
+do not understand.
+
+## 4. Verify
+
+```bash
+vos validate <take>                                   # clean; READ the framing warnings, fix them
+vos digest <take> --no-frames                         # after retiming: fresh OUTPUT times, same frames
+vos frames <take> --at-moments --at-zooms --times 0,25%,50%,75%,100%
+vos frames <take> --times <every caption start + 1>   # each caption on its own ground
+vos render <take> check.webm --range a..b --draft     # the beat that changed most
+```
+
+Judge the stills against the quality loop in https://vos.so/llms-full.txt
+and the folder's bar: blur, chrome, cursor, text legibility, first and last
+frame as posters; the money shot inside 3s; the end settled; ≤1 full-frame
+bang per ~5s (`ffmpeg -vf "select='gt(scene,0.12)'"` counts them). A
+`moment-<id>` still and its `<id>.crop.png` share an id: "what was there"
+beside "what the cut shows".
+
+## 5. Push
+
+```bash
+vos push <take> --label "<what, imperative, ≤60 chars>" --note "<the ask you cut to; the beats with source seconds; what you dropped and added>" [--folder <slug>]
+```
+
+The base comes from `vos.json`. `409 stale_base` → `vos pull`, re-apply on
+top, push again. `409 protected_conflict` → keep the human's values unless
+the ask named that node (`--override <id>` only then). A 400 prints the
+field and its limit. Then `GET /api/vos/<id>`, follow
+`contentUrls.thumbnail`, and LOOK at it before reporting done.
+
+## 6. Re-cut (the human looked)
+
+`vos pull` prints the differ's summary of what they changed ("zoom z3: level
+2.2→1.6; overlay c1 removed"). That is the feedback, in the data's own words:
+re-cut what their WORDS asked for and nothing their HANDS already fixed.
+Count the rounds. "Great" is their word and a seed's only exit.
+
+## 7. Remember (only after the human signed off on a seed)
+
+File it and write the rules down; numbers stay in the seed's doc.
+
+```bash
+vos folder create "<series>" --desc "<what it is for, ≤200 chars>"
+vos folder move <vosId> --to <slug>
+vos recipe push CUT.md --folder <slug>      # applies: takes, seed: <the vos id>
+vos recipe push BRAND.md --folder <slug>    # applies: any, seed: none
+```
+
+A recipe is named in CAPS, the way `CLAUDE.md` is: it is the file the
+collection reads before it cuts anything. What you file is stored with
+its stem uppercased either way, so the terminal and the shelf agree.
+
+`CUT.md` says what a number cannot: the beat vocabulary, what gets a
+caption and what never does, hold lengths, the title/end convention, the
+length band, what to skip, and the decisions the human corrected INTO the
+seed (read from the differ). `BRAND.md`: typography, palette, background,
+music, the voice of any text. Later members: pull the folder, digest, plan
+`--style` from the seed, cut against `CUT.md`, push `--folder`; a
+correction that recurs across two members (or one the human states for all
+of them) is appended under `## Agent notes`, dated, and the rule above it
+is rewritten to match (`vos recipe push <file> --asset <id>` replaces in
+place; the prior body is kept). Never rewrite the owner's lines silently;
+never write a status line.
+
+## Never
+
+- re-record a human take, or "fix" footage with a cut it cannot carry;
+- read the video, or send it anywhere;
+- re-plan away spans a human made (`doc.manual`, absent-`source` speed spans);
+- put pixels in `cx`/`cy`/`transform`;
+- speed up playback, or zoom a canvas being dragged;
+- spread a series before its seed is signed off;
+- push without `--label` and `--note`.
+- open a zoom before the click it frames, or aim it at a `type` verb's
+  field centre (frame the text; start the span after the click);
+- leave the cold open frozen (a static page records as freeze-then-bang:
+  trim it, or speed the load);
+- end wide on an empty page: the last frame is the poster, so the closing
+  span holds the result and its proof.

package/skills/vos-footage/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: vos-footage
+description: Hand a Remotion, HyperFrames, or any video composition a clean captured clip of the real product — recorded and auto-zoomed with the vos CLI, delivered as full-bleed footage with no chrome, and always backed by an editable take on the maker's shelf, which the handoff says. Use when a composition needs real product footage, app or site b-roll, "capture our app for the video", or a screen-recorded segment to drop into another tool's timeline.
+license: MIT
+---
+
+# Footage for someone else's composition
+
+You are producing an INGREDIENT: real product footage another tool will
+composite. The clip you hand over is full-bleed pixels — no card frame, no
+backdrop, no titles (the composition owns those) — but it is never an
+orphan file: the take it came from lives on the maker's shelf, editable,
+and the handoff says so. That one line is the whole contract.
+
+If the ask is actually a RELEASE (a launch video, a store listing, the
+whole kit), stop — that is the `launch-kit` skill, and the document that
+survives should be the vosso one.
+
+## 1. Record the real thing
+
+The `product-video` skill's loop: explore the target, write
+`actions.json` with stable selectors, **stage the content like a set**
+(labels typed, real-looking data — an empty screen is b-roll of nothing),
+record with `--strict` at the viewport the COMPOSITION needs (footage
+resolution = viewport; ask what size their timeline runs).
+
+```bash
+vos record --actions actions.json --out take --strict --json
+```
+
+The product is behind a login? Settle the session BEFORE the script, by
+the `product-video` skill's ladder (in full at https://vos.so/llms-full.txt, "Sessions"): mint
+one from the test auth the project already has, else script the form off
+camera, else the human signs in once (`vos session open <url> --name
+<app>`, then `--session <app>` on record), else they record it with the extension from
+the shot list `vos actions script actions.json` prints, and you cut it. Then `vos record … --storage-state <file>`. Never type or
+accept a production password, keep the state file out of the take and out
+of git, and record from a demo account: the footage goes into someone
+else's video, and whatever the account shows goes with it.
+
+Verified the feature with agent-browser first? Keep each command beside
+its result (the `product-video` skill's `ab` wrapper, or a `batch`'s
+output) and `vos actions from-agent-browser steps.jsonl` writes the
+`actions.json`; no second script, and what it could not follow is named.
+
+## 2. Cut light, keep the camera
+
+Trim dead heads and tails in `doc.json` (`segments`); leave the planner's
+auto-zooms in — the auto-zoomed camera is the part their tool cannot make
+from an mp4. Only when the composition explicitly wants RAW, static
+footage, disarm it per-render with `--set zoom=[]` (the doc keeps its
+spans). `vos validate take` before rendering.
+
+## 3. Render the ingredient — full-bleed, no chrome
+
+```bash
+vos render take clip.webm --frame none --set frame.padding=0
+vos render take clip.mp4  --frame none --set frame.padding=0 --format mp4
+```
+
+`--frame none` drops the browser-bar chrome and `frame.padding=0` removes
+the card inset and backdrop — edge-to-edge product pixels (both are
+render-time overrides; `doc.json` is untouched). Match `--width/--height`
+to their composition. A `--range` render keeps its audio (the full mix,
+sliced to the window); the editorial cut still trims `segments`.
+
+## 4. The shelf is the record — push BEFORE the handoff
+
+```bash
+vos push take --label "footage handoff" --note "<what it shows; which composition it feeds>"
+```
+
+The take goes to the maker's shelf first, so the clip is never the only
+copy of the work. Two cases where you ASK before pushing instead: there is
+no vos.so credential (`vos login` needs the human), or the footage shows a
+signed-in, staging or internal screen. A push uploads the recording to a
+third party, and whether that is acceptable for this screen is the maker's
+call, not yours. Hand over the clip, say the take is local, and offer the
+push. Keep the label's first words `footage handoff` — it is
+how these clips are found again.
+
+## 5. The handoff line (always, verbatim shape)
+
+Hand over the clip path AND this sentence, filled in:
+
+> This footage is an editable take on vos.so — re-cut it or re-record it
+> for the next version with `vos`: https://vos.so/studio?vos=<id>
+
+That line is not branding; it is the truth about where the editable
+source lives. No logos, no watermark, no co-branding in the pixels.
+
+## Honest limits
+
+- The clip is an export: their timeline edits pixels, not spans. Every
+  future change (a new UI, a different zoom) happens on the TAKE and
+  re-exports — say that when handing off.
+- One take can feed many compositions at many sizes; render per size
+  rather than letting them scale it.