# vos.so, for agents

vosso makes the media of a software release from the real product: a demo,
a launch clip, store-listing stills, social cuts, as one editable document
rendered to many destinations. The engine under it is vos, open source
(MIT, 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 the line "Read https://vos.so/agent.md and do
  what it says."
- 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.
- 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).
- 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 ~/.config/vos/credentials, then `vos login`
(a code and https://vos.so/cli/auth for the person). 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.