foldrun 0.5.0 → 0.7.2

package/docs/coding-agents.md

@@ -0,0 +1,224 @@
+# Working with a coding agent
+
+The page a coding agent (Claude Code, Cursor, Codex) should read first in a
+foldrun account, and the one `foldrun init` points it to. A foldrun account
+is agents, flows and knowledge as markdown. There is no build — the files ARE
+the program — so the loop is edit, check, run, deploy.
+
+`foldrun init` writes a short block into the account's `AGENTS.md`, between
+`<!-- BEGIN:foldrun-agent-rules -->` markers, telling the coding agent to
+read these docs before it writes anything, and a `CLAUDE.md` that imports it.
+The block is for the tool editing the folder: the runtime strips it before
+the rest of `AGENTS.md` reaches your agents. `foldrun guide` re-adds or
+refreshes it; `foldrun docs <page>` prints any page of these docs, from the
+copy that ships with your CLI, so a coding agent always reads the version it
+is working against.
+
+## The loop
+
+```sh
+foldrun check              # validate everything, offline, no model calls
+foldrun run <flow>         # run it locally against real models
+foldrun eval               # run the evals
+foldrun deploy             # push the account (or `deploy <workspace>`) to the platform
+```
+
+`check` is cheap and catches a broken flow before a schedule fires it at
+3am. Run it after every edit, the way you would run a typecheck.
+
+## Where things go
+
+| Path | What |
+|---|---|
+| `AGENTS.md` | the account's shared context and defaults — every agent in every workspace reads it (except the managed coding-agent block, which the runtime strips) |
+| `workspaces/<name>/` | one workspace: a desk, a pipeline, a product |
+| `workspaces/<name>/AGENTS.md` | that workspace's context and settings |
+| `workspaces/<name>/agents/<name>/agent.md` | one role: its persona, model, tools |
+| `workspaces/<name>/flows/<name>.md` | steps, in order, naming the agents that run them |
+| `workspaces/<name>/knowledge/` | reference material agents read |
+| `workspaces/<name>/memory/` | what past runs learned — agents write here themselves |
+| `workspaces/<name>/evals/` | tests for agents, same idea as unit tests |
+| `workspaces/<name>/skills/` | a procedure an agent can follow, named in `skills:` |
+| `workspaces/<name>/tools/` | a folder tool: its definition and its code together |
+| `workspaces/<name>/scripts/` | code the agents call, referenced by `scripts:` |
+| `workspaces/<name>/state/` | what runs accumulate. Yours to read, never deployed over |
+| `library/` | skills, tools, scripts and knowledge shared by every workspace here |
+| `.claude/agents/<name>.md` | a Claude Code subagent — deploys AS an agent |
+
+`knowledge/` is what you tell the agents; `memory/` is what they worked out.
+Regenerated every run means a file; accumulated across runs means `state/`.
+
+A subagent you write in Claude Code is imported as `agents/<name>/agent.md`
+at deploy, no conversion. Write it either way.
+
+## What a deploy does NOT touch
+
+`runs/`, `state/`, `storage/`, `secrets.json`, the trigger log, and any
+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 never go in these files. `foldrun secrets set NAME` puts them in the
+vault, and agents reference them by name.
+
+## Talking to the platform
+
+The CLI is local except for `deploy`, `pull`, `runs`, `logs`, `invoke` and
+friends, which talk to the platform you signed in to (`foldrun login`, or
+`FOLDRUN_URL` + `FOLDRUN_TOKEN`). Everything the CLI does, the HTTP API does
+too, with the same key:
+
+```sh
+api() { p=$1; shift; curl -sS -H "authorization: Bearer $FOLDRUN_TOKEN" "$FOLDRUN_URL/api/$p" "$@"; }
+
+api workspaces/$WS/runs                       # recent runs, newest first
+api workspaces/$WS/runs/<id>                  # the full trail of one
+api workspaces/$WS/runs/<id>/stream           # follow a live one (SSE)
+api workspaces/$WS/flows/<flow>/run -X POST   # start one
+```
+
+| Route (`/api/workspaces/<ws>` unless noted) | Methods | For |
+|---|---|---|
+| `/` | GET DELETE PATCH | the workspace itself |
+| `/deploy` | POST | what `foldrun deploy` calls |
+| `/source` | GET PUT PATCH DELETE | read and write single files |
+| `/runs` · `/runs/<id>` | GET · GET DELETE | list runs; one run, every step |
+| `/runs/<id>/stream` | GET | live events, server-sent |
+| `/runs/<id>/stop` · `/rerun` · `/approve` | POST | kill it; again from a step; release a gate |
+| `/flows` · `/flows/<f>` · `/flows/<f>/run` | GET POST · POST DELETE PATCH · POST | list, create, edit, start |
+| `/agents` · `/agents/<a>/run` | GET POST · POST | list agents, run one |
+| `/evals` · `/evals/<e>/run` | GET POST · POST | list evals, run one |
+| `/tools/<t>/test` | POST | exercise one tool alone |
+| `/storage` · `/storage/download` · `/storage/upload-url` · `/storage/preview` · `/shares` | GET POST PUT DELETE · GET · POST · GET · POST GET DELETE | files agents produced and people uploaded, any type; a file parsed for reading; public links to them |
+| `/triggers?since=` | GET | why nothing ran: fired vs started per flow, with reasons |
+| `/hooks/<f>/rotate` | POST | new webhook token for a flow |
+| `/restore` | POST | the workspace's source back to a point in its history — `dryRun` first, then `confirm` |
+| `/notify/deliveries` · `/notify/deliveries/<id>/redeliver` | GET · POST | every notify: webhook sent and each attempt; send one again |
+| `/api/secrets` · `/api/schedule` · `/api/account` · `/api/keys` | account-level | the vault, the clock, defaults, API keys |
+| `/api/me/notifications` | GET PATCH | what mail you get, per category; a key acts for whoever minted it |
+
+A key carries a role (viewer, editor, admin) and a workspace scope no wider
+than the person who minted it. Team, profile and MFA routes are a person's
+alone and refuse a key. The full reference with request and response shapes
+is the platform's `docs/api.md`.
+
+Debugging a failed run is usually: `foldrun runs --status failed`, `foldrun
+report <id>` to read which step failed and what it cost, fix the markdown,
+`foldrun deploy`, then `foldrun rerun <id> --from <step>`. `foldrun triggers`
+answers "why did nothing run".
+
+## Writing a flow
+
+A numbered list of steps. The number is the GROUP: same number means those
+steps run in parallel, and the flow waits for all of them before the next.
+
+```markdown
+---
+trigger: manual          # manual | schedule | webhook
+schedule: "0 9 * * 1"    # cron, when trigger: schedule
+timezone: Australia/Sydney
+model: default           # a default for every step here
+effort: low
+overlap: skip            # skip | queue — what a second run does while one is live
+priority: normal         # high | normal | low — where its runs stand in the queue
+---
+
+1. [[researcher]] — Find three sources on {{topic}}.
+2. [[writer]] — Draft from what the researcher found.
+   model: max
+   verify: judge: the draft cites every source
+3?. [[editor]] — Tighten it.
+4!. [[publisher]] — Publish it.
+```
+
+`3?.` is optional — it may be skipped. `4!.` needs a human to approve before
+it runs. `[[flow:other-flow]]` in place of an agent runs another flow as a
+step.
+
+Indented under a step, any of:
+
+| | |
+|---|---|
+| `approve: true` | stop for a human (`!` is shorthand for this) |
+| `when: <condition>` | run only if it holds |
+| `case: <value>` / `else: true` | branch on the previous step's result |
+| `retry: 2` | re-run on failure, up to 5 |
+| `timeout: 900` | seconds before the step is cut off |
+| `verify: <shell>` | the step fails unless the command exits 0 |
+| `verify: judge: <claim>` | a model grades the claim against the output |
+| `verify: contains:` / `not-contains:` / `matches:` / `file:` | the cheap checks, no shell |
+| `model:` / `effort:` | override the flow's default for this step |
+| `loop: 3` / `until: <condition>` | repeat until it holds, at most 5 |
+| `each: lines` · `each: rows of <path>` · `each: items` | run once per line / CSV row / JSON element of the previous result |
+| `max: 10` | cap how many iterations `each:` produces |
+| `on-fail: [[agent]]` | who handles it when this step fails |
+| `wait: 30m` · `wait: event` | pause; or hold until something POSTs the run's event URL |
+| `ask: <question>` | ask a human, use the answer |
+| `preview: draft/*.mdx` | what the approval box shows — paths under `storage/`, globs allowed |
+| `delegate: [[a]], [[b]]` | hand the step to whichever fits, up to 5 |
+| `output: json` | the reply ends with one JSON value; the next step gets it as data |
+
+A `verify:` with no assertion prefix is a **shell command**, not a sentence.
+`verify: the reply names the file it wrote` runs a program called `the` and
+fails every run with `command not found`. The prefixes are `contains:`,
+`not-contains:`, `matches:`, `file:` and `judge:` — put `judge: ` in front of
+a claim in English. `foldrun check` errors on this.
+
+`matches:` and `contains:` test the step's **last turn**, so they grade the
+agent's prose. Where the step writes the artefact, verify the artefact
+instead — the stronger check, and the one that does not depend on how the
+model phrased itself.
+
+## Writing an agent
+
+Frontmatter then prose. The prose IS the system prompt, so write it to be
+read by a model: what this role is for, what it must not do, what good looks
+like.
+
+```markdown
+---
+name: researcher
+description: Finds and summarises sources.
+model: default              # fast | default | max
+effort: low                 # how hard to think about it
+size: large                 # small | large | heavy — the sandbox it rents
+tools: [web, read, my-folder-tool]  # built-ins and your own tools/, one list
+disallowedTools: [Bash]     # subtract from what it would otherwise have
+skills: [house-style]       # from skills/
+scripts: [summarise.py]     # from scripts/, each becomes a callable tool
+apis: [{ name: crm }]       # an HTTP API, as a tool
+mcpServers: {}              # an MCP server, as a tool
+agents: [writer]            # colleagues this one may consult
+secrets: [CRM_TOKEN]        # from the vault — never written in these files
+provider: {}                # BYOK: your own model credential
+permissionMode: plan        # plan first, act once approved
+runtime:                    # only if scripts need packages
+  packages: [requests]
+---
+
+You research a topic and report what you found...
+```
+
+Only `name` and the prose are required. Every other field widens or narrows
+what the agent can reach, and the default is narrow.
+
+`runtime:` installs pip/npm packages in the sandbox each agent runs in. Pin
+versions the normal way (`pandas>=2`, `lodash@^4`). Python and Node are
+supported; anything else should ship as a committed binary.
+
+Link documents to each other with `[[wikilinks]]` — the name, not the path.
+
+## The CLI, in one screen
+
+```
+foldrun init [dir] · new <name> · agent new · flow new · tool new
+foldrun check [--to <ws>] · run <target> · eval [name] · probe <model>
+foldrun deploy [dir|ws] · pull [ws] · status [ws] · workspaces · source <verb>
+foldrun runs · logs [id] · report <id> · triggers · schedule · approvals
+foldrun invoke <flow> [--wait|--watch|--once <key>] · rerun <id> --from <n> · stop <id>
+foldrun approve <id> · reject <id> · storage ls|cat|get|put|rm|share|shares|unshare
+foldrun secrets set|ls|rm|status · connect NAME · account [providers] · billing
+foldrun login · logout · whoami · keys ls|create|revoke · doctor
+```
+
+`foldrun <command> --help` explains any of them, and `foldrun docs cli` is the
+whole reference.

package/docs/deploying.md

@@ -0,0 +1,77 @@
+# Deploying
+
+A workspace deploys by pushing files. Two doors, one mechanism: `foldrun
+deploy` from a folder, or `git push` to the remote every workspace has.
+Both are checked before anything goes live, both refuse to swap files under
+a run in flight, and neither touches what the platform owns.
+
+## From a folder
+
+```sh
+foldrun login                            # once per machine: approve in the browser
+foldrun check                            # first, always — it costs nothing
+foldrun deploy                           # this folder → the workspace named after it
+foldrun deploy --to leads --commit $(git rev-parse HEAD)
+```
+
+In CI there is no browser: set `FOLDRUN_URL` and `FOLDRUN_TOKEN` (a key from
+Settings → API keys, or `foldrun keys create`) and the same commands run.
+
+## From git
+
+Every workspace is a git remote:
+
+```sh
+git clone https://foldrun:<api-key>@app.example.com/git/<account>/<workspace>.git
+# edit, commit
+git push origin main                     # deploys, and runs the evals
+```
+
+Any username, an API key as the password. A **deploy key** — minted for one
+workspace, read or write, with `foldrun keys create ci --for <workspace>
+--access write` or on the Settings page — is what a CI job or a contractor
+should hold; it is refused on every other workspace and on every other route.
+
+Push a branch other than `main` and you get a **preview**: a workspace named
+`<workspace>-preview-<branch>` deployed from that branch, with its evals run
+there, its schedules never fired, and its source's secrets. Deleting the
+branch deletes it.
+
+## What a deploy checks
+
+The tree is validated the way `foldrun check` validates it — a step naming an
+agent that does not exist, a tool that resolves to nothing, a knowledge
+concept with no `type:` — and a push with issues is refused with the list.
+Git says so at push time; the workspace on disk is unchanged.
+
+## What a deploy never touches
+
+`runs/`, `state/`, `secrets.json`, and any memory an agent wrote that the
+push does not mention. A deploy that reverted what an agent learned would
+make every run a little dumber, and a deploy that reset a cursor would make
+the next run redo a fortnight.
+
+## Runs in flight
+
+A push while a run is in flight — including one parked at an approval gate
+— is **accepted but not applied**. Git warns at push time, and the platform
+applies it the moment those runs finish. Swapping files under a running flow
+would mean step 3 reads agents step 1 never saw. `foldrun deploy --force`
+overrides that when you mean it.
+
+## History and rollback
+
+Every change to a workspace is a revision — a push, a dashboard edit, an
+agent's memory write — with who, when, and a diff, on the workspace's
+History page and at `/api/workspaces/<ws>/history`. A deploy's revision id
+is its commit.
+
+A rollback is a deploy of an earlier ref (`POST …/repo {action: deploy, ref}`
+or the History page), and it lands as a **new commit on `main`** — history
+moves forward, never rewrites.
+
+## Mirroring
+
+A workspace can mirror to a repository you host — GitHub, GitLab — over
+https with a token held as the `MIRROR_TOKEN` secret. The platform's remote
+stays the mechanism; the mirror is the copy you read elsewhere.

package/docs/evals.md

@@ -0,0 +1,90 @@
+# Evals
+
+An eval is a markdown file under `evals/` that runs an agent or a flow against
+a task and asserts something about the reply. It is how a change to a prompt
+stops being a guess.
+
+```markdown
+---
+name: writer-quality
+agent: writer            # or `flow: publish`
+model: fast              # the judge's model, not the agent's
+---
+
+## mentions the audience
+task: Write a short draft about cleaning a rain gauge.
+expect:
+  - contains: farmer
+  - not-contains: leverage
+  - judge: speaks to working farmers, not to gardeners
+
+## quotes the real price
+task: Write one line quoting the price of the RG-40.
+expect:
+  - contains: $34
+```
+
+Each `##` heading is one case: a `task:` and the `expect:` list it must
+satisfy. The heading is the case's name, so make it the thing being checked.
+
+## Frontmatter
+
+| field | |
+|---|---|
+| `name` | the eval's identity |
+| `agent` **or** `flow` | what runs. A flow eval runs the whole flow per case |
+| `model` | the **judge's** tier, not the subject's — cases run the agent on its own model |
+| `effort` | the judge's effort. PASS/FAIL against one sentence is not deep work |
+| `trigger` | `deploy` (default) or `manual` |
+| `inputs` | `true` makes the file a flow's saved inputs, not a test: its cases are named tasks for [Run with…](flows#run-with-saved-inputs) and `foldrun invoke --inputs`, and nothing runs them as an eval |
+| `live` | an eval's runs are [test runs](runs#test-runs) — nothing outward, `state/` untouched — unless this says `true`. A flow eval that must really send to prove itself opts in; nothing opts in by accident |
+
+## Assertions
+
+| | |
+|---|---|
+| `contains:` | the text must appear |
+| `not-contains:` | the text must not appear |
+| `matches:` | a regular expression over the reply |
+| `file:` | the path exists and is non-empty |
+| `run:` | a shell command that must exit 0 |
+| `judge:` | a model grades the reply against this sentence |
+
+**Deterministic checks run first and cost nothing.** The judge only runs if they
+pass — there is no point paying a model to grade output already known to be
+wrong. The same vocabulary is a step's `verify:`, so a flow and an eval say
+"the output must mention the price" in one sentence.
+
+## When they run
+
+`trigger: deploy` — the default — runs the eval on every deploy of the
+workspace, which is what makes it a regression test rather than a thing someone
+remembers to click. Results land in `evals/.results/`, and a dated line goes to
+`history.jsonl` so movement is visible across weeks.
+
+On a platform an eval's run goes through the same queue as every other run,
+so it counts against the account's `concurrency:` and waits its turn.
+
+`trigger: manual` keeps it off every push. **Use it for `flow:` evals**: a flow
+eval runs the entire flow once per case, so a three-case eval on an hour-long
+flow is three hours and the full cost, on every deploy.
+
+## Promoting a run
+
+A run that went wrong is a case you already have — the task is on record, and
+so is the answer. **Promote to eval** on the run page writes it into `evals/`
+with the task filled in, so the fix has a test before it has a diff. A run that
+was itself an eval case is refused: promote the run it was checking.
+
+## The loop
+
+```sh
+foldrun check           # free — no model is called
+foldrun eval            # the assertions
+foldrun run <agent>     # the real thing
+```
+
+`check` is the typecheck: a step naming an agent that does not exist, a tool or
+skill that resolves to nothing, a `delegate:` or `on-fail:` that names nobody,
+a cron that fires eleven times where you meant once. It costs nothing, so run
+it on every edit and let evals cover what only a model can answer.

package/docs/faq.md

@@ -0,0 +1,53 @@
+# FAQ
+
+**Is this a framework?** No. There is nothing to import. An agent is a folder,
+a flow is a numbered list in a markdown file, and the CLI or the platform
+reads them. You can write a working workspace in an editor with no
+dependency installed.
+
+**Do I need an account to try it?** No. `npm install -g foldrun`, a model key,
+and `foldrun init` gives you a workspace that runs on your machine. The
+account is for running it somewhere that is not your laptop, on a schedule,
+with a team.
+
+**Which models does it use?** Whatever you point it at. `model:` takes a
+tier — `fast`, `default`, `max` — and the platform resolves the tier to a
+model. Bring your own key for any provider that speaks the Anthropic or the
+Chat Completions API, per account or per workspace, and the platform bills
+you nothing for those tokens. See [Providers](providers).
+
+**Can agents reach the internet?** Yes — the public internet, as themselves,
+with the secrets they were granted. Not private networks, not the cloud
+metadata endpoint, not the platform's own API or database.
+
+**Can an agent change my website / my CRM / my repository?** Only if its
+file names a tool that can, and the reference pattern is to give that tool
+only to the step after a human gate. An agent with no tool that writes cannot
+write, whatever it is told.
+
+**What stops a runaway?** Three caps — per run, per workspace per month, per
+account per month — and the stop button, which destroys the sandbox. A
+step with no `timeout:` runs until it finishes; that is deliberate, and the
+caps are the ceiling.
+
+**How do I know what happened while I was asleep?** The run's headline: the
+first line of the last step's reply, which is the runs-list row and the
+subject of the notification. Ask your agents to open with a verdict and the
+inbox becomes a status board.
+
+**Can two flows write to the same repository?** Yes, and they should not do
+it in the same hour. Give each writer its own day, or chain one after the
+other with `trigger: flow`.
+
+**I use Claude Code. Does that help?** A subagent at
+`.claude/agents/<name>.md` deploys as a foldrun agent with no conversion.
+The scaffolded `CLAUDE.md` tells your editor the layout.
+
+**Where is my data?** In your workspace's folder, as files — on your machine,
+or on the hosted platform's data volume — and its blobs in the
+file store. Nothing is hidden in a database only the platform can read, and
+a deploy never touches what an agent learned or a run recorded.
+
+**Can I run it on my own hardware?** The CLI and runtime, yes — that is
+what they are for, and they are open source. The platform itself is hosted
+only. See [Running it yourself](self-hosting).