# vos.so, for agents

vosso (vos.so) is a free screen recorder with automatic zoom, and a CLI that lets your coding agent record your real product, cut the demo video and host it at a link that keeps every version. It runs on Vos, the open-source (MIT) video engine.

It makes the video of a software release from the real product: a demo, a
launch clip, social cuts, as one editable document rendered to many
destinations. The engine's source is at https://github.com/vosjs/vos.
Agents edit JSON and re-render; the preview is the render.

## Start here

- https://vos.so/agent.md: the setup procedure, from a clean machine to a take open
  in the studio. A person hands you a line that names the task and this
  address: "Record a demo video of this app with vosso. The steps are at https://vos.so/agent.md. Give me the vos.so link when it's done."
  The file says what it may ask of you and what it never will.
- https://vos.so/host.md: the hosting procedure, for a video the person already
  made (HyperFrames, Remotion, a page, a script): rewrite it into a program
  and give back a link that plays it and that anyone can change. Its line:
  "Put my video on vos.so. The steps are at https://vos.so/host.md. Give me the link when it's done."
- Skills: `npx skills add vosjs/skills` (index at
  https://vos.so/.well-known/skills/index.json, also under
  /.well-known/agent-skills/). Each skill's description says what ask it
  answers.
- CLI: `npm i -D @vosjs/cli`, then `npx vos setup` (npm: @vosjs/cli).
  Records and renders locally with no account; `vos doctor` says what
  is ready; --json streams NDJSON; exit codes 0 ok, 1 error, 2 usage, 3
  no browser, 4 the recorder met a sign-in.

## Contracts

- https://vos.so/llms.txt: routes by ask, terse.
- https://vos.so/llms-full.txt: the complete CLI reference (every verb, every
  doc.json field and its units, the session ladder).
- https://vos.so/llms-remix.txt: the HTTP contract for programs (fetch, edit,
  push; folders and recipes; the 3D recipe).
- https://vos.so/design.md: vosso's own brand, for anything made on its behalf.
- https://vos.so/docs/llms.txt: every docs page as markdown.

## What you may call

All under https://vos.so/api. A bearer attaches your identity; most reads need
none.

- GET /vos, GET /vos/:id, GET /vos/:id/config: public programs and their
  source. GET /vos/official: the gallery.
- POST /vos, POST /vos/:id/versions, GET /vos/:id/changes: the versioned
  loop (a content key; keys create private work and can never publish).
- POST /vos/validate: the create ladder as a dry run, always 200 with ok.
- GET /folders, GET /folders/:id: a person's projects and recipes (a key).
  PATCH /folders/:id {description}: the one field of a project a key may
  change; its name, place and audience are a person's, signed in.
  POST /vos/:id/position {to | before | after}: where one of your own
  videos sits in its project, one video at a time (a key).
- POST /assets/uploads (then its parts and /complete): every file, of any
  kind and size, read and typed by its bytes (a key).
- GET /assets (?kind, ?q, ?limit), GET /assets/:id, GET /user/usage: what a
  person's library holds, what uses a file, and the storage it takes (a key).
- POST /render/jobs: the Render API, content-addressed (a key).
- GET /fonts, GET /music, GET /backdrops, GET /limits: the catalogs and the
  free plan's numbers.
- GET /user/whoami: the account behind a key and the key's own name,
  never the key (what `vos whoami` prints).
- POST /claim: push a program for preview with no account (a 72-hour link).
- POST /product-feedback: tell the founder what broke, auth optional.

Credentials: VOS_API_KEY, then the account in use at ~/.config/vos/credentials
(`vos whoami` says which; `vos switch <handle>` changes it, since a person
who signed in as themselves and as an organization has both stored), then
`vos login` (a code and https://vos.so/cli/auth for the person, who picks the
account there). Never print one. No session of a person's ever reaches vos.so.

## Rules

- Local by default: record and render on the machine; push only when asked.
- Every push renders a still within about fifteen seconds; look at it.
- A stale push answers 409 with the changes you missed; rebase, never force.
- Humans publish. Keys cannot.

Contact: https://vos.so/feedback, or the endpoint above.
