Agents

The agent contract

Three altitudes of agent access, and where the machine-readable contracts live.

vosso is built to be operated by coding agents as first-class users: every effect is data, every render is deterministic, and every hosted change lands on an attributed version chain a human can read. This page is the map; the machine-readable contracts it points at are the law.

Three altitudes

Pick the smallest surface that does the job:

  1. A pasted prompt. Watch pages, the studio and the workspace all offer a copyable prompt that carries everything an agent needs for one task, including an ephemeral credential when one is called for. Zero setup.
  2. The contracts. Three plain-text files teach an agent the product end to end: /llms.txt routes by intent, /llms-full.txt is the complete take and CLI reference, and /llms-remix.txt is the HTTP contract for program remixing. They are the canonical terse reference; these docs are the human rendering of the same facts.
  3. The skills. npx skills add vosjs/skills installs the full workflow as agent skills, so the agent carries the quality bar and the loop with it instead of rediscovering them. See Install the skills.

The rules that hold everywhere

  • Pushes are private. A key can create and iterate but can never publish; making something public stays a human act on vos.so.
  • Attribute every push. --label says what changed in one imperative line; --note says why, in the words of the user's ask. The version history reads as a conversation, and an unlabelled push is a turn the human cannot read.
  • Humans win by default. Nodes a human edited in the studio since your last push are protected; you keep their values unless the user explicitly asked for that change. See Versions and conflicts.
  • Never print a credential. Not in output, not in logs, not in --json events. The tools are built so you never have to.

Reading these docs as an agent

Every docs page serves its markdown source at /docs/{page}.md, and /docs/llms.txt indexes the whole corpus with one line per page. Fetch the index, then only the pages your task needs.