foldrun 0.8.0 → 1.0.0

package/docs/providers.md

@@ -1,5 +1,31 @@
 # Providers, by name
 
+## Your account's own model key
+
+The simplest way to bring a key: **Settings → Model provider**, or
+`foldrun account model set <provider> --key <api key>`, or
+`PUT /api/account/model`. Pick a name from the table below (or `custom`
+with a base URL and a format), paste an **API key**, and every step in
+every workspace runs on it. No `provider:` block is needed; one written in
+an agent, a workspace or the account's AGENTS.md still wins over it.
+
+The key is stored in the account's vault, encrypted under the account's own
+key, as `FOLDRUN_MODEL_PROVIDER`, `FOLDRUN_MODEL_API_KEY` and, for a custom
+endpoint, `FOLDRUN_MODEL_BASE_URL` and `FOLDRUN_MODEL_FORMAT`. The dashboard
+and the API show only its last four characters.
+
+**On a hosted platform every account brings its own key.** The platform's
+own model credential is for the operator's accounts
+(`FOLDRUN_PLATFORM_KEY_ACCOUNTS`); a step in any other account with no key
+of its own is refused before it starts — "no model key: …" on the run — and
+an eval's judge or "draft with AI" says the same. A **Claude login token**
+(`sk-ant-oat…`, from `claude setup-token`) is refused as a customer's key:
+Anthropic's terms do not let a third-party product run its customers on
+claude.ai logins. Use an API key from the provider.
+
+Tokens on your own key are billed by your provider, not by the platform
+([budgets and billing](budgets-and-billing.md)).
+
 What `provider: { name: … }` resolves to. Mirrors `foldrun-core/src/providers.ts`,
 checked against each provider's own documentation on 2026-09-02 and again on
 2026-09-06; the table below is what the runtime believes, and
@@ -178,6 +204,8 @@ what would be checked; `POST` forces one, for the minute after rotating a
 key. From the terminal, `foldrun account providers` prints the same table
 (✓, ✗ with the verdict, or · for never checked) and `--check` forces one;
 a dead key is a non-zero exit, so a deploy script can refuse to continue.
+In the dashboard, Settings → Model provider shows the same check per
+provider, with **Check now** (editor and above, since it spends a request).
 
 ## When a provider says no, the run says why
 

package/docs/runs.md

@@ -87,7 +87,11 @@ run until a person decides. Three doors open it, and the trace says which:
 - **the emailed link** — the notification carries approve and reject links
   when the install has a public URL;
 - **an external event** — a `wait: event` step is released by a POST to the
-  run's event URL, and what was posted reaches the next step.
+  run's event URL, and what was posted reaches the next step. A person can
+  release it the same way from the run page (or `approve` with a `payload`):
+  the payload reaches the step just the same, and the trace names them, not
+  "an external event". The approvers and self-approval rules below are for
+  gates that ask a person; a `wait: event` release asks for `run:start`.
 
 The answer typed at an `ask:` gate reaches the next step's prompt, so "GO,
 but skip the third one" is an instruction the publisher reads.
@@ -155,7 +159,8 @@ flow, a time window, or an explicit list of ids. It is the tool for the
 morning when one broken thing failed seventy runs. A call naming no filter is
 refused rather than treated as everything, `dryRun: true` shows what would be
 touched, and each run is its own outcome so one that cannot be stopped does
-not abort the rest.
+not abort the rest. On the runs pages, tick runs and choose **Stop** or
+**Rerun**: the bar makes this call, once per workspace in the selection.
 
 **Re-run from a group** (`from: N`) starts a new run at group N with the
 earlier groups recorded as skipped, not invented — the step reads what earlier

package/docs/security.md

@@ -134,6 +134,20 @@ name only — for the owner and admins to read or export. Support can view an
 account only [read-only, for thirty minutes, with a reason the customer
 reads](team-and-access#support-access).
 
+## Your terminal
+
+The CLI prints what a platform sends it — agents' replies, logs, files,
+release notes, errors — and a terminal obeys escape sequences hidden in
+text: it can move the cursor and overwrite a line, clear the screen, retitle
+the window, write your clipboard, or show a link that goes somewhere else.
+So nothing the CLI prints carries them. The only ones that get through are
+the CLI's own colours, and every other control character but newline and
+tab is removed, on a terminal and through a pipe alike. Content you asked for
+byte for byte — `foldrun source cat`, `storage cat`, `library cat`, a
+download or CSV to stdout, `api spec` — is exact when it goes into a file or
+another program, and filtered like everything else when it lands on a
+screen. `--json` is exact too: JSON writes control characters as escapes.
+
 ## What is still yours to think about
 
 - A model reading a web page reads whatever is on it. Give the agent the

package/docs/tools.md

@@ -54,7 +54,7 @@ headers:
 
 | field | |
 |---|---|
-| `base` | the URL every call is relative to |
+| `base` | the URL every call is relative to. `${FOLDRUN_API_URL}` is this install's own API (`base: ${FOLDRUN_API_URL}`), so a tool that reads the account's runs never names a host; a base naming it on an install that has no public address is reported unavailable |
 | `methods` | the verb allowlist — a tool that declares none is read-only |
 | `headers` | `${SECRET}` placeholders, resolved host-side at call time |
 | `query` | query parameters appended to every call — for an API that carries its key in the query string; a `${SECRET}` is resolved host-side |
@@ -63,6 +63,13 @@ headers:
 | `openapi` | a URL or file; turns one generic tool into typed ones, one per operation |
 | `operations` | only these operations, by `operationId` or `METHOD /path`; the generic tool is withheld. It fails closed: if the document does not load or none of them resolve, the API has no tools that run, never the generic one. Keep an allowlisted document in the workspace, so a vendor renaming an operation cannot empty it |
 
+**The body is the manual.** Everything under a `tool.md`'s frontmatter goes
+to the model with the tool, after `description:` — how to call it, what it
+refuses, what its output means, examples of a call (up to 6,000 characters;
+a longer body is cut there and says so). A single-file tool's fenced program
+is code, not guidance, and stays out. This holds for script and HTTP tools
+alike, workspace or library.
+
 The model never sees a credential — the host substitutes it as the request
 goes out. The method allowlist protects against the agent; the key's own scopes
 protect against everyone else, so pair a read-only tool with a read-only key.
@@ -221,6 +228,14 @@ the agent — which is already the model — to answer from; `extract` by
 `schema=` or `prompt=`, which needs a model to read the page, needs a
 provider.
 
+Granting `web` grants **Read** with it: several actions write what they
+found to a file and say so (a screenshot, a crawl, a page saved whole), and
+an agent told to read a file it could not open was refused. `disallowedTools:
+[Read]` takes it away again. A provider that times out or answers busy (429,
+5xx) is asked twice more, about 2 s and 6 s apart, before the action reports
+it unreachable — a fan-out of many steps asking one provider at once is the
+usual cause.
+
 ```yaml
 tools: [web]
 web:
@@ -1393,11 +1408,36 @@ own defaults.
 next one: the cookies and localStorage the call ends with are written to
 `workspace/state/browser/<name>.json` and loaded before any later call that
 names it, in this run or a run next month. It is the agent's own login,
-made with `actions` from credentials it can see — `state` refuses
-`cookies=` and `storage=` and a session those seeded, because `state/` is a
-workspace file every later step can read, and a vault secret written there
-would stop being one. `mode=diff` keeps its baselines in the same place,
-under `state/browser/diff/`, for the same reason: they must outlive the run.
+made with `actions` from credentials it can see — or a login a cookie secret
+seeded, when `state_key` encrypts it (below). Without a key `state` refuses
+`cookies=` and a session they seeded, and it always refuses `storage=`,
+because `state/` is a workspace file every later step can read, and a vault
+secret written there in the clear would stop being one. `mode=diff` keeps its
+baselines in the same place, under `state/browser/diff/`, for the same
+reason: they must outlive the run.
+
+**A cookie secret that seeds a saved login.** Some sites — Google above all —
+rotate their sign-in cookies while they are used, so a copied `Cookie` line in
+the vault goes stale within the hour and every later run meets a sign-in
+page. Put `state:` and `state_key:` beside `cookies:` in the block:
+
+```yaml
+web:
+  browse:
+    cookies: YOUTUBE_COOKIES
+    cookie_domain: .youtube.com
+    state: youtube
+    state_key: BROWSER_STATE_KEY
+secrets: [YOUTUBE_COOKIES, BROWSER_STATE_KEY]
+```
+
+The first call seeds from the secret; every call saves the session it ends
+with, encrypted, and the next loads that rather than the vault's copy. The
+state file records which secret seeded it and a keyed fingerprint of its
+value, so pasting fresh cookies into the secret seeds it again. Script in the
+page (`js`, `eval`, a `get` of storage) stays refused on such a login, as it
+is on the secret itself. `check` refuses `state` beside `cookies` without
+`state_key`.
 
 ### Where the browser runs
 

package/docs/versions.md

@@ -22,8 +22,70 @@ under its own name — `v2026.09.30.2` deployed again is still `v2026.09.30.2`.
 Behind each name are the commits of the parts that make up the platform —
 `core` (the runtime), `platform` (queue, worker, storage, billing), `web` (the
 dashboard and the API), `docs` and `infra` — recorded when it was deployed.
-The `foldrun` CLI and `@foldrun/core` on npm are packages a person publishes,
-and keep ordinary semver (`0.6.0`).
+The `foldrun` CLI and `@foldrun/core` on npm are packages, and follow
+semantic versioning instead — see [the packages](#the-packages).
+
+## The packages
+
+`foldrun` (the CLI) and `@foldrun/core` follow
+[Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) from 1.0.0:
+
+| | Means | Example |
+|---|---|---|
+| Patch | a bug fix, nothing new — safe to update | 1.4.2 → 1.4.3 |
+| Minor | a new feature; everything that worked still works | 1.4.2 → 1.5.0 |
+| Major | a breaking change: something old stops working or works differently | 1.4.2 → 2.0.0 |
+
+What the promise covers is the public API. For the CLI that is every command
+and flag `foldrun --help` lists, and the Node.js version it needs. For
+`@foldrun/core` it is `@foldrun/core` itself and the subpaths in its
+`package.json` under `foldrun.publicApi`. Other `@foldrun/core/*` modules can
+be imported, but they are internal and may change in any release.
+
+The release decides the number, not a person's memory. It compares the
+public API at the last release with the new one. Anything gone, or a
+function that now needs more arguments, makes it a major. Anything new makes
+it at least a minor. A change in behaviour that the API cannot show is marked
+in the commit, and that makes it a major too. A major's release notes open
+with **Breaking changes**, saying what stops working.
+
+Nothing is removed without warning. A command, flag or export is first marked
+deprecated, in a minor, and still works. It is taken out in a later major.
+Both are in the release notes.
+
+Pre-releases, like `1.5.0-rc.1`, are published under npm's `next` tag. So
+`npm install -g foldrun` gets the last stable release, and
+`npm install -g foldrun@next` gets the pre-release. A stable CLI never
+suggests updating to a pre-release.
+
+`npm install -g foldrun@^1` stays within 1.x, so nothing that works breaks
+under it. Every release is listed in each package's `CHANGELOG.md` and on
+GitHub Releases.
+
+## Rollback and the database
+
+A rollback redeploys older code, but not an older database: the schema stays
+where the newest release left it, because migrations only run forwards. So
+every migration has to work with the code of the release before it — the
+expand/contract rule. A release only expands: a new table, a nullable column,
+a column with a `DEFAULT`, an index. Taking something away that released code
+still uses — dropping or renaming a table or column, changing a column's
+type, making a column `NOT NULL` with no default, dropping a constraint or a
+default, `TRUNCATE`, a `DELETE` with no `WHERE` — is the contract half, and
+ships a release later, once no deployed version reads it. A migration that
+has been released is never edited; the next change is a new file.
+
+The platform enforces this. `scripts/migration-guard.mjs` in
+`foldrun-platform` reads the migrations added since the deployed version (in
+CI, since the commit a push or pull request started from) and refuses those
+statements, in CI and in the pre-push hook. A deliberate contract step says so
+on the line above the statement, with a reason, and is reported rather than
+refused:
+
+```sql
+-- migration-guard: contract api_keys.label unread since v2026.09.30.1
+ALTER TABLE "api_keys" DROP COLUMN "label";
+```
 
 ## Where to see it
 

package/docs/workspaces.md

@@ -54,6 +54,85 @@ pulled, only edited in Settings.
 A single folder with `agents/` and `flows/` at its root is still a workspace
 and still works everywhere; `foldrun init --flat` makes one.
 
+## A new workspace starts blank
+
+**Create workspace** on the dashboard, `POST /api/workspaces` with
+`template: true`, and `foldrun new <name>` all make a workspace with nothing in
+it to delete: an `AGENTS.md` (plus, on a laptop, the `.gitignore` that keeps
+its secret key out of git and a `CLAUDE.md` for your coding tool). No example
+agents, no flow. `foldrun new <name> --starter` and `starter: true` still make
+the example researcher, writer and `publish` flow; `foldrun init` makes it for
+an account's first workspace, which the getting-started guide runs.
+
+A workspace with no agents yet deploys; `check` and the deploy say so as a
+warning. A flow that names an agent the workspace lacks is still an error.
+
+### Importing an agent you already have
+
+The agents worth having in a new workspace are often ones already written in
+another: **Import agent** on the Agents page (and in the empty state of a blank
+workspace) lists every agent in the account's other workspaces you can read,
+and copies the one you pick. From a terminal, `foldrun agent import
+<workspace>/<agent>` does it between workspaces of an account folder, or on the
+platform with `--to <workspace>`; the route is `POST
+/api/workspaces/<ws>/agents/import` with `{ from, agent, as? }`.
+
+What is copied is what the agent **is**: `agent.md` and its own `skills/`,
+`scripts/` and `knowledge/`. What it **accumulated** stays where it was learned:
+`memory/`, `outputs/`, `state/` and session files. A name already taken is
+refused — import it under another name with `--as` / `as`, which rewrites its
+`name:`. The import then says what the copy uses that this workspace lacks —
+tools, skills, scripts, secrets — without refusing: set the secret, import the
+tool, and it runs. The copy is independent; editing one does not change the
+other.
+
+### Export and import
+
+Agent import works inside one account. To move a desk to another account or
+installation — or to hand someone a flow — export it as a `.zip`:
+
+- **A workspace:** Settings → **Export and import** → **Export workspace**.
+- **A flow:** **Export** on its card on the Flows page. The package holds the
+  flow, every flow it runs as a step, every agent those steps name (with
+  `on-fail:`, `delegate:` and the colleagues those agents consult or delegate to),
+  and the workspace tools, skills and scripts they grant — including the
+  script a single-file tool's `run:` names.
+- **An agent:** **Export** on its page: its folder (what agent import copies)
+  and the workspace tools, skills and scripts it grants. Colleagues it consults
+  are named, not carried.
+
+A package is authored source only: `AGENTS.md` and the `agents/`, `flows/`,
+`evals/`, `knowledge/`, `skills/`, `tools/` and `scripts/` folders. It never holds
+`memory/`, `state/`, `outputs/`, storage, runs, `.env` files or a secret's
+value. The secrets it uses travel by **name**, so the importer knows what to
+set. An agent with no `skills:` line gets every skill in scope at run time, so
+its package carries every workspace skill.
+
+Anything else in a zip — memory, state, a `.gitignore` or `CLAUDE.md` beside a
+folder you zipped yourself — is **not imported**, and the preview lists it.
+
+To import, use **Import .zip** on the Flows or Agents page or in Settings, or
+**Add new → Import workspace** on the home page. You pick the file and first
+see a preview, with nothing written yet:
+
+- what it adds;
+- what is already identical;
+- which files it would **replace** (only with a tick);
+- what it needs that this account lacks: secrets, library tools and skills,
+  scripts, agents and flows it names.
+
+An import never deletes anything, and it is all or nothing: a file it cannot
+write (a folder already in its place, a link on the way) refuses the whole
+import before anything is written. It lands as one revision, so History can
+restore what it replaced. A workspace package imported under a new name makes
+that workspace. A `.zip` of a workspace folder made by hand (a Mac's
+Compress included) imports the same way.
+
+From a terminal: `foldrun export [workspace] [--flow <name> | --agent <name>]`
+and `foldrun import <file.zip> --to <workspace> [--dry-run] [--overwrite]`.
+The routes are `GET /api/workspaces/<ws>/export` and
+`POST /api/workspaces/<ws>/import` (`?dryRun=1`, `?overwrite=1`).
+
 ## `AGENTS.md` — context and defaults
 
 The body is prose every agent in the workspace sees before its own prompt.
@@ -147,6 +226,14 @@ memory an agent wrote that your push does not mention. Those belong to the
 platform, not to git, and a deploy that reverted what an agent learned would
 make every run a little dumber.
 
+The agent engine's own files are not workspace content either. Each step
+runs in a sandbox on the Claude Agent SDK — the engine, whichever model
+answers — and the engine writes its settings and session transcripts in the
+agent's folder there (`agents/<name>/.claude.json`, `agents/<name>/.claude/`).
+They stay in the sandbox: never copied back, never copied in. (Your own
+`.claude/agents/*.md` at the workspace root is different — a Claude Code
+subagent you wrote, deployed as an agent.)
+
 A push while a run is in flight is accepted and applied when the run
 finishes; git tells you so at push time. A run parked at an approval gate
 counts as in flight. See [Deploying](deploying).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foldrun",
-  "version": "0.8.0",
+  "version": "1.0.0",
   "description": "Agents are just folders. Write them, check them, run them — on your machine.",
   "license": "Apache-2.0",
   "type": "module",
@@ -11,7 +11,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@foldrun/core": "^0.6.0"
+    "@foldrun/core": "^1.0.0"
   },
   "files": [
     "bin",
@@ -21,7 +21,7 @@
   ],
   "scripts": {
     "e2e": "FOLDRUN_E2E=1 FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-e2e-XXXXXX) node --test --test-timeout=300000 tests/e2e.test.ts",
-    "test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts",
+    "test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-frontmatter.test.ts tests/cli-agent-import.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts tests/cli-flags.test.ts tests/cli-api-coverage.test.ts tests/cli-hooks.test.ts tests/cli-release.test.ts tests/cli-terminal.test.ts",
     "release": "node scripts/release.mjs",
     "typecheck": "tsc -p tsconfig.json",
     "docs:sync": "node scripts/sync-docs.mjs",
@@ -47,7 +47,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@types/node": "^22.20.2",
+    "@types/node": "^26.6.4",
     "gray-matter": "^4.0.3",
     "typescript": "^5.9.3"
   }