foldrun 0.6.0 → 0.8.0

package/docs/getting-started.md

@@ -0,0 +1,142 @@
+# Getting started
+
+An agent is a folder. A flow is a numbered list. There is no build step — the
+files are the program — so the loop is edit, check, run, deploy.
+
+## Install and make something that runs
+
+```sh
+npm install -g foldrun
+export ANTHROPIC_API_KEY=sk-ant-...     # an API key from console.anthropic.com
+# or: export CLAUDE_CODE_OAUTH_TOKEN=...  from `claude setup-token` (see the CLI reference)
+
+foldrun init my-account
+cd my-account
+foldrun check                            # free: no model is called
+foldrun run publish --task "write about rain"
+```
+
+`init` scaffolds an **account folder** with one workspace in it, and that
+workspace already works: two agents, a flow that names them, an eval, and
+knowledge they share. `check` validates all of it offline —
+run it after edits the way you would run a typecheck. It is the cheapest
+feedback in the system and it catches a broken flow before a schedule fires it
+at 3am rather than after.
+
+## What you just made
+
+```
+my-account/
+  AGENTS.md                    context every workspace here inherits
+  library/                     tools, skills, scripts shared by all of them
+  workspaces/
+    main/
+      AGENTS.md                context every agent in THIS workspace sees
+      agents/researcher/agent.md  one role: persona, model, tools
+      agents/writer/agent.md
+      flows/publish.md         the steps, in order
+      knowledge/               what you tell the agents
+      memory/                  what they worked out — they write here
+      evals/                   tests for agents
+      CLAUDE.md                conventions, for your editor
+```
+
+That is the shape the platform keeps, so the folder you edit is the folder that
+runs. `--workspace <name>` names the first workspace (default `main`) and
+`foldrun new <name>` adds another. `foldrun init --flat` makes the older
+single-folder shape instead, and every command still reads it.
+
+`CLAUDE.md` is the one file foldrun never reads. It is there so Claude Code and
+its peers know the layout instead of guessing at it.
+
+## Writing an agent
+
+Frontmatter, then prose. **The prose is the system prompt**, so write it to be
+read by a model: what the role is for, what it must not do, what good looks
+like.
+
+```markdown
+---
+name: researcher
+description: Finds and summarises sources.
+model: default
+tools: [web, write]
+---
+
+You research a topic and report what you found. Prefer primary sources.
+Say when you could not find something rather than inferring it.
+```
+
+Only `name` and the prose are required. Every other field widens or narrows
+what the agent can reach, and the default is narrow.
+
+A field that names files — `tools:`, `skills:`, `agents:` — takes the same
+`[[link]]` the prose does, or a bare name; both mean the same thing. Use the
+block form when you link:
+
+```yaml
+tools:
+  - read              # a built-in group
+  - [[site_repo]]     # your own tools/site_repo.md
+```
+
+## If you use Claude Code
+
+A subagent at `.claude/agents/<name>.md` **deploys as a foldrun agent** — no
+conversion, no second format. Write it however Claude Code taught you and it
+becomes a role on the platform.
+
+## Running it somewhere that is not your laptop
+
+```sh
+foldrun login                            # approve it in the browser, once
+foldrun deploy                           # pushes this workspace
+foldrun invoke publish --wait            # runs it there
+```
+
+`foldrun login` signs in to the hosted platform; `foldrun login --url
+https://your-server` to your own. In CI, set `FOLDRUN_URL` and
+`FOLDRUN_TOKEN` (Settings → API keys) instead — see [Deploying](/deploying/).
+
+A deploy is checked before any of it goes live, and it refuses while a run is
+in flight — swapping files under a running flow means step 3 reads agents that
+step 1 never saw. `--force` overrides that when you mean to.
+
+It never touches `runs/`, `state/`, `secrets.json`, or memory an agent wrote
+that your push does not mention. Those belong to the platform, not to git: a
+deploy that reverted what an agent learned would make every run a little
+dumber.
+
+## Secrets
+
+```sh
+foldrun secrets set STRIPE_KEY          # prompted, never echoed, never in a file
+```
+
+Agents name them in `secrets:` and receive the value at run time. They are never
+written into the workspace, so a workspace is always safe to commit.
+
+## The checklist on the dashboard
+
+A new account's home page shows a **Getting started** card: create a
+workspace, write or deploy an agent, run a flow, get a run to finish, add a
+secret, schedule a flow or give it a webhook, invite a teammate, set up
+billing (where the plan asks for it) and install the CLI — "4 of 8", with the
+next step first and a link to where to do it. Each step is worked out from
+the account as it is (a run on record, a secret in the vault, a key minted
+for the CLI), so it ticks itself whichever way you did the thing; there is
+nothing to mark. **Dismiss** hides it for you alone; the line at the foot of
+the page brings it back, and it goes away by itself once every step is done.
+
+```sh
+foldrun onboarding                       # the same steps, in the terminal
+```
+
+The API is `GET /api/me/onboarding`; hiding the card is a person's own
+setting, so it is done from the dashboard, not with a key.
+
+## Where to go next
+
+- **The grammar** — every field an agent or flow can carry: Help
+- **The API** — driving a deployed workspace over HTTP: the API reference
+- **The CLI** — every command and flag: the CLI reference

package/docs/glossary.md

@@ -0,0 +1,78 @@
+# Glossary
+
+**account** — the top level: people, keys, the library, the wallet, and the
+workspaces under it. Has one owner.
+
+**agent** — one role: a folder with an `agent.md` whose frontmatter grants and
+whose prose is the prompt.
+
+**AGENTS.md** — context and defaults, at the account and at each workspace.
+Prose accumulates downward; a frontmatter key replaces whole.
+
+**budget** — a cap: per run (in a flow, or on an agent for its own steps),
+per workspace over a day, week or month, per account the same. Unset is no
+limit.
+
+**conclusion** — a step's final reply, as opposed to every turn joined. What
+checks and headlines read.
+
+**desk** — an everyday name for a workspace that does one job on its own —
+a blog desk, a Reddit desk — its agents and flows, running on a schedule.
+Nothing in the format is called a desk; it is a workspace.
+
+**deploy** — pushing a workspace's source tree to the platform, by
+`foldrun deploy` or `git push`. Never touches runs, state, secrets or memory.
+
+**eval** — a test for an agent or a flow: a task and what a good answer
+must contain. Runs on every push.
+
+**flow** — orchestration: a numbered list of steps. Same number, same time.
+
+**gate** — a step that parks the run for a person (`!`, `approve:`, `ask:`).
+
+**group** — the steps that share a number. A step is handed every earlier
+group's replies.
+
+**headline** — the first meaningful line of a step's conclusion. The run's
+headline is the last step's.
+
+**knowledge** — what people give an agent. Read by all, written by none.
+
+**library** — the account's shared tools, skills, knowledge and memory.
+Nearest wins: a workspace shadows it by defining the same name.
+
+**memory** — what an agent learned, one fact per file. The one place it
+writes without a grant.
+
+**preview** — a copy of a workspace deployed from a branch, evals run,
+schedules off, deleted with the branch.
+
+**run** — the record of a flow being driven: every step, event and cost.
+
+**sandbox** — where a step executes: a container or a gVisor pod, made for
+the step and destroyed after it.
+
+**share** — a public link to one file in `storage/`, tokened, expiring.
+
+**skill** — a capability an agent loads when a task matches, in the open
+Agent Skills format. Inherited unless allowlisted.
+
+**state** — what the next run needs from this one. Travels with a deploy,
+never overwritten by one.
+
+**storage** — bytes a person reads or downloads. Regenerated each run.
+
+**tier** — `fast`, `default`, `max`: which brain, resolved to a model by the
+platform so agents do not rot when models are renamed.
+
+**tool** — what an agent may call: an API, a script, an MCP server. Granted
+by name in `tools:`; absent unless named.
+
+**trigger** — how a flow starts: a person, a schedule, a webhook, an email,
+another flow, a file, a URL that changed.
+
+**verify** — a check on a step's outcome: a shell command, or `contains:`,
+`matches:`, `file:`, `judge:`. Where arithmetic goes.
+
+**workspace** — a folder, and the unit of editing, deploying, permission,
+budget and backup.

package/docs/harness.md

@@ -0,0 +1,128 @@
+# The harness
+
+The model decides. The harness decides what that decision may touch, and what
+counts as done.
+
+Everything in this page already exists somewhere else in these docs: gates are
+in [Flows](flows), budgets in [Budgets](budgets-and-billing), grants in
+[Agents](agents). This page is the other way round: not what each field does,
+but **what a step needs before it is safe to leave running while you sleep.**
+
+## The five jobs
+
+| job | what it answers | where it lives |
+|---|---|---|
+| Reach | what may it touch | `tools:`, `secrets:`, the sandbox, the egress boundary |
+| Truth | how do we know it worked | `verify:`, `confirm=`, `until:` |
+| Cost | what does being wrong cost | `budget:`, `timeout:`, `max:` |
+| Consent | who says yes to the irreversible | `4!.`, `ask:`, `preview:` |
+| Memory | how do we find out afterwards | the run record, `notify:`, the ledger |
+
+A gap in any one is a different accident. A step with no reach limit does harm.
+A step with no truth check **reports success it did not earn**, which is worse,
+because nobody comes looking.
+
+## The checklist
+
+Run any step that acts on the outside world through these eight.
+
+**1. Can it only do its job?**
+Grant the tools it needs and no more. An agent that must not edit gets `read`,
+not `write`. The publisher that posts should not hold the tool that rewrites
+what it is posting — on 2026-09-14 a send step edited its own gate file to get
+past a guard, and the fix was taking the editing tools away, not asking it
+nicely.
+
+**2. Does the runtime know it worked?**
+"The tool returned ok" is not evidence. A save can report success and revert.
+Use `confirm=` on a browser call that writes, and `verify:` on the step:
+
+```markdown
+2. [[publisher]] — post the approved draft
+   verify: matches: (^|\n)[#*_>\s]*GOOD\b.*/comments/
+```
+
+**3. Does the failure say what to do?**
+A check that fails with "exit 1" costs somebody an hour. Write the fix into
+the message:
+
+```markdown
+   verify: node -e "const fs=require('fs');if(!fs.existsSync('workspace/storage/unanswered.csv')){console.error('the scan wrote no storage/unanswered.csv, and the next step fans out over it. Fix: run the tool once per office and let it write the file.');process.exit(1)}"
+```
+
+**4. Is a retry safe?**
+`retry:` is for flakiness — a timeout, a 503, a cold start. It is not for a
+refusal. A credential that was rejected will be rejected again, and repeating
+a refused write is how a silent 403 becomes a block on your whole address.
+When a step can be refused rather than merely fail, say so in the agent: one
+`BLOCKED` reply naming the secret to renew, and no second attempt.
+An outward step is not retried when its check fails after its tools ran:
+the email went, and a retry would send it again. A failure mid-send is still
+retried, so `check` and `deploy` warn on `retry:` on any outward step.
+
+**5. Who approves the irreversible?**
+`!` or `ask:` on the step that spends money, sends mail or publishes, with
+`preview:` pointing at the artefact itself. The gate belongs **where the
+irreversible thing happens**, not at the end of the flow: everything before it
+should be research that costs cents.
+
+**5b. Does the tool say it is outward?**
+Mark it `outward: true` in the tool's frontmatter. `check` then refuses any
+step that grants it without a `verify:` or a gate, so the rule on this page
+stops being advice.
+
+**6. Is it recorded before it happens?**
+Write the ledger row before the call, with the run id and the external id,
+`pending` first and the outcome after. A row written afterwards is missing
+exactly when you need it: when the call half-succeeded.
+
+**7. Will you hear about it?**
+`notify:` with at least `failed`. A desk nobody is told about is a desk that
+fails quietly for a week.
+
+**8. What did it cost?**
+Every step records its own cost and the run carries the total. Add `budget:`
+where you want a ceiling; leave it off where you do not. Unset means no limit,
+and the platform invents no default.
+
+## Truth is the one people skip
+
+Reach and consent feel like security, so they get done. Truth feels like
+paperwork, so it gets skipped, and it is the one that fails silently.
+
+The pattern to internalise: **a write is not done until something other than
+the writer says so.** In a browser that is `confirm=`, which reloads the page
+and requires the change to be in what the server returns. For a file it is a
+`verify:` that reads the file back. For an outward action it is the ledger row
+and the read-back of the external record.
+
+On 2026-09-17 a desk drove Medium for hours. Every fill reported ok, every Save
+reported ok, and every value was gone on the next load, because a Cloudflare
+challenge had quietly started refusing writes. Nothing in the logs was false.
+There was simply nothing in the system that asked the server what it had.
+
+## The harness has to guard itself
+
+Everything above is about an agent's work. The same questions apply to the
+platform's own credentials, and they are easier to get wrong because nothing
+fails until everything does.
+
+The rule that matters: **a credential is read when it is used, never held from
+boot.** The platform's model key is a mounted file, read per step
+(`FOLDRUN_MODEL_KEY_FILE`), so a refresh reaches the next step by itself.
+Before that it was an environment variable, and since refreshing an OAuth
+token revokes the old one, every refresh needed a restart that could not
+happen while work was in flight. That is not a scheduling problem to be tuned;
+it is a design where the correct behaviour is impossible on a busy day.
+
+If you take one thing from this section: a credential your system cannot
+reload without stopping is a credential that will expire at the worst moment,
+and the failure will look like something else.
+
+## What this does not cover
+
+The harness constrains an agent; it does not make it correct. A step can pass
+every check in this page and still write a bad article, pick the wrong lawyer
+or mis-read a rule. That is what [evals](evals) are for, and what a reviewer
+step is for. The checklist keeps a wrong answer cheap and visible; it does not
+make the answer right.

package/docs/how-it-works.md

@@ -0,0 +1,255 @@
+# How it works
+
+Eight nouns, one reference syntax, and a flow that is a numbered list. Nothing
+here is a framework you import — every one of these is a markdown file you can
+open, diff and review.
+
+## The eight nouns
+
+Four are **grants**: an agent has them because its file says so, and reading
+that one file tells you the blast radius.
+
+| | |
+|---|---|
+| **agent** | one role — a folder with an `agent.md` |
+| **flow** | orchestration — a numbered list of steps |
+| **tool** | what it may call: an API, a script, or an MCP server |
+| **skill** | a capability it loads when a task matches |
+
+Four are **places**: always there, never granted. They differ only by who may
+write.
+
+| | who writes | |
+|---|---|---|
+| **knowledge/** | nobody | given to it; reading is denied to nothing, writing to everything |
+| **memory/** | the agent | what it learned, one fact per file, indexed |
+| **state/** | the workspace | the bookmark between runs |
+| **storage/** | anyone | bytes, not source — PDFs, CSVs, images |
+
+The line between the last two is worth learning early: a value **regenerated**
+each run is `storage/`; a value **accumulated** across runs is `state/`.
+
+Capability is opt-in, knowledge cascades. `tools:` grants nothing until you
+name it. `skills:` is the opposite — leave it out and the agent inherits every
+skill in scope; write it and it becomes an allowlist. An empty `skills: []`
+therefore withholds all of them, which is legal and almost never what someone
+means.
+
+## `[[name]]` — the one reference syntax
+
+The rule is one sentence: **if it names a file, you can link it.** Agents,
+flows, skills, tools, knowledge and memory are files. Secrets, `model:`,
+`size:` and `effort:` are values, and are never linked.
+
+| where | what it means |
+|---|---|
+| first link on a step line | **structural** — the agent that step runs |
+| `[[flow:weekly]]` on a step line | a whole flow, composed in place |
+| in any prose | resolved to the real relative path before the model sees it |
+| `[[storage/leads.csv]]` | that file |
+| `[[storage/]]`, `[[state/]]` | the folder, when you mean *where* rather than *which* |
+| in `tools:`, `skills:`, `agents:`, `delegate:`, `after:` | the same name, spelled as a link |
+
+Names match on filename **or** the document's own `title:`/`name:`, blind to
+case, hyphens and underscores — so a link survives a rename that a literal
+path would not. Anything unmatched passes through as written: the syntax is
+sugar over paths, never a gate, and a typo never breaks a run.
+
+Two details worth knowing:
+
+- **Links expand only where text becomes a prompt** — an agent's body, a step's
+  instruction, an eval's task. Inside a knowledge or tool document they stay
+  literal, because there the link is for the person reading.
+- **In `tools:`, the brackets mean "mine."** A bare `search` is the platform's
+  search group; `[[search]]` is your `tools/search.md`. That is the only way
+  to grant a tool named after a built-in.
+
+```yaml
+tools:
+  - read              # a built-in group
+  - [[site_repo]]     # your own tools/site_repo.md
+```
+
+Use the block form when you link. To YAML, `[[x]]` is a nested list, so the
+inline `tools: [read, [[site_repo]]]` parses correctly but reads badly.
+
+The idiom to write by: **link what you read, spell out what you write.** A link
+points at something that exists — an input. An output destination does not
+exist yet, so it stays a literal path.
+
+## A flow is a numbered list
+
+Steps run in ascending order, and each receives the previous group's results.
+Output passing is the default, not configuration.
+
+```markdown
+1. [[researcher]] — gather this week's competitor updates
+2. [[writer]] — turn the research into a 300-word digest at outputs/digest.md
+```
+
+**Steps sharing a number run in parallel**, and the next group receives every
+result, labelled per agent. The number is the whole scheduling model:
+
+```markdown
+1. [[researcher]] — gather the facts
+2. [[optimist]] — argue the bull case
+2. [[skeptic]] — argue the bear case
+3. [[editor]] — weigh both and write the verdict
+```
+
+`2?` marks a step optional — it fails without failing the flow. `2!` parks it
+for a human.
+
+### Routing
+
+`case:` steps in one group are exclusive branches: the first whose text appears
+in the previous results runs, and an `else:` step runs when none matched.
+
+```markdown
+1. [[classifier]] — reply with exactly one word, BUG or QUESTION
+2. [[debugger]] — investigate and fix
+   case: BUG
+2. [[writer]] — answer it clearly
+   case: QUESTION
+2. [[triager]] — neither label fit; say what is missing
+   else: true
+```
+
+`when:` is the non-exclusive sibling — every matching step runs. That is why
+routing has its own word instead of being a mode on `when:`.
+
+### The critic loop
+
+```markdown
+1. [[writer]] — draft the post
+2. [[editor]] — review it; end your reply with APPROVED when it is ready
+   loop: 3
+   until: APPROVED
+```
+
+The marker must stand **alone on its own line**. "APPROVED once the citation is
+fixed" contains the word but is a rejection, and reading it as a pass would end
+the loop with the correction unmade — which is the failure the loop exists to
+prevent. Generate–critique–revise, with the model deciding only whether to say
+the word and the file deciding the shape.
+
+### Fan-out
+
+```markdown
+1. [[scout]] — list the competitor URLs, one per line
+2. [[analyst]] — analyse this one site
+   each: lines
+   max: 10
+```
+
+The declared shape stays one line in the file; the width comes from the data.
+`each: items` fans out over the array an earlier `output: json` step returned,
+and `each: rows of workspace/storage/leads.csv` over a CSV.
+
+### Composition
+
+A step may name a flow instead of an agent — `1. [[flow:weekly]] — …` — and its
+steps run in place, keeping their own parallelism. Cycles, and nesting past
+three levels, are errors.
+
+## Working as a team
+
+Three ways for agents to reach each other, in increasing order of how much the
+model decides:
+
+**Steps** — you decide who runs next. The default, and the one to prefer.
+
+**Consult** (`agents:`) — a specialist answers one question, inline:
+
+```yaml
+agents:
+  - [[fact-checker]]
+  - [[researcher]]
+```
+
+Each becomes a `consult_<name>(question)` tool. The colleague's persona answers
+one self-contained question as a **toolless** call, with the spend landing on
+the calling step. Depth is one — consultants cannot consult further. It is
+deliberately weak: a consult is asking a specialist what they think, not handing
+over the task.
+
+**Delegate** (`delegate:`) — the model picks, from a list you wrote:
+
+```markdown
+2. [[triager]] — decide who should take this
+   delegate: enricher, emailer, writer
+```
+
+The agent ends its reply with `agent: instruction` lines, choosing only from the
+declared set (at most five). The picks run as a fresh group immediately after,
+and both the set and the picks are on the record. Choosing nobody is a normal
+outcome.
+
+What all three have in common is the line the format holds: a model chooses
+*what to do within a step*; the **file** decides what happens after it. There is
+no free-form handoff between agents, because that pattern's common failure is a
+loop where every agent re-plans and nobody owns the task.
+
+## Gates, failure and cost
+
+| option | what it does |
+|---|---|
+| `approve: true` / `ask: <question>` | park until a person releases it; the answer typed at the gate reaches the prompt |
+| `wait: 3d` / `wait: event` | hold for a duration, or until something POSTs the run's event URL |
+| `retry: <n>` | attempts after the first, up to 5 |
+| `on-fail: <agent>` | another agent takes the step over, with the failure as context |
+| `verify: <command>` | a shell command, or `contains:` / `matches:` / `file:` / `judge:` |
+| `timeout: <seconds>` | **the only clock there is** |
+
+Two of those deserve emphasis. **Without `timeout:`, a step runs until it
+finishes** — the platform sets no clock of its own anywhere, so every limit that
+exists is one written in a markdown file. And **`verify:` is where anything
+decided by arithmetic goes**: step options are matched as text, deliberately, so
+a threshold belongs in a command that can be tested — `verify: jq -e '.total > 0'`
+— rather than in a comparison in frontmatter.
+
+## Picking the model
+
+`model:` takes a tier — `fast`, `default`, `max` — rather than a model id, so
+agents do not rot when models are renamed. `effort:` is the orthogonal half:
+which brain, versus how long it thinks. `fast` + `max` is a real pairing — the
+cheap model, told to take its time.
+
+Resolution is nearest-wins — the step, then the flow, then the agent — and the
+run trace names which level won, so "why did this run on haiku" is answerable
+from the run rather than by opening three files.
+
+```markdown
+---
+name: digest
+model: fast              # every step, unless the step says otherwise
+---
+
+1. [[scout]] — list the URLs
+2. [[analyst]] — the one hard step
+   model: max
+   effort: xhigh
+```
+
+Match the tier to the work, not to the importance of the desk. A step that
+reads a page and pulls out three fields is a `fast` step even when the report
+it feeds is the point of the week; a step that weighs two arguments and picks
+one is not. See [Providers](providers) for pointing a tier at your own
+endpoint, which is how a tier becomes cheaper still.
+
+## Choosing between the shapes
+
+| you want | use |
+|---|---|
+| a second opinion inside one step | `agents:` consult |
+| the model to pick who is next, from a short list | `delegate:` |
+| you to decide who is next | numbered steps |
+| N of the same work | `each:` |
+| a quality gate | `loop:` + `until:` |
+| reuse across flows | `[[flow:name]]` |
+| a person | `approve:` / `ask:` |
+
+`foldrun check` validates all of this offline, before any model is called: a
+step naming an agent that does not exist, a `delegate:` or `on-fail:` that
+names nobody, a tool or skill that resolves to nothing. Run it the way you
+would run a typecheck.

package/docs/introduction.md

@@ -0,0 +1,47 @@
+# Introduction
+
+Agents are just folders. foldrun is the platform that runs them: an agent is
+a folder with an `agent.md` in it; a flow is a numbered
+list of steps; a tool is a file that says what may be called. There is no
+build step and no SDK to import — the files are the program — so the same
+folder runs on your laptop with the CLI or on the hosted platform,
+unchanged.
+
+## What it is for
+
+Work that a person used to do on a schedule, and that a model can now do with
+supervision: the weekly report, the nightly import, the morning scan of what
+changed, the draft that a human approves before it goes out. Each of those is
+a flow. Each role in it is an agent. The person who used to do the work
+becomes the person who reads the headline and clicks approve.
+
+The design bets on three things:
+
+- **Files are the right unit.** An agent's prompt, its tools, its knowledge
+  and what it has learned are all files you can open, diff, review and put in
+  git. Nothing is hidden in a database that only the platform can read.
+- **The file decides, the model works.** A flow says who runs and in what
+  order; a model decides only what to do inside its step. There is no
+  free-form handoff between agents, because that is where systems loop.
+- **Capability is a grant, not an instruction.** An agent can call a tool
+  because its file names it. An agent that cannot write to your website has
+  no tool that writes, rather than a paragraph asking it not to.
+
+## Two ways to run it
+
+| | you need | what runs where |
+|---|---|---|
+| **Locally** | `npm install -g foldrun` and a model key | everything on your machine; no account, no server |
+| **Hosted** | an account | ours: schedules, sandboxes, a vault, a team |
+
+The same workspace moves between them with `foldrun deploy` or a `git push`.
+Start locally; that is where every workspace should be born. The CLI and
+runtime are open source (Apache-2.0); the platform is not distributed — see
+[Running it yourself](self-hosting).
+
+## Where to go
+
+- [Getting started](getting-started) — install, make a workspace, run it.
+- [How it works](how-it-works) — the eight nouns and the flow grammar, in one read.
+- [Workspaces](workspaces), [Agents](agents), [Flows](flows), [Tools](tools) — the format, field by field.
+- [Runs](runs), [Budgets and billing](budgets-and-billing), [Security](security) — what happens when it runs.