foldrun 0.6.0 → 0.7.2

package/docs/troubleshooting.md

@@ -0,0 +1,155 @@
+# Troubleshooting
+
+The failures people actually hit, what the platform is telling you, and the
+fix. Every one of these leaves its reason in the run's events; read those
+before anything else.
+
+## When a provider says no
+
+The status code decides what happens next, and the runtime already acts on
+the difference:
+
+| code | what it means | what the runtime does |
+|---|---|---|
+| **400** | the request is malformed | fails the step — retrying sends the same thing |
+| **401 / 403** | not signed in, or not allowed | tries the fallback provider if one is declared |
+| **402** | out of credit | fallback provider; often a reservation against a large token ceiling rather than an empty account |
+| **404** | no such model or path | fails; usually a base_url with the wrong `format:` |
+| **422** | understood and refused | fails, with the reason in the step's output |
+| **429** | too many requests | **waits and asks again** — up to three times, 2s / 4s / 8s with jitter, honouring a `retry-after` the provider names, on the same key. A 429 that mentions quota, credit or billing is the account, not the traffic, and goes to the fallback instead |
+| **500 / 502 / 503 / 529** | broken or busy at their end | same wait-and-retry as 429 |
+
+Every wait is a line in the run log (`provider busy … waiting 3.4s, attempt
+1 of 3`), so a slow run reads as slow rather than mysterious. Only after the
+retries are spent is the fallback provider tried.
+
+## "verify … → no match"
+
+The step's `verify: matches:` or `contains:` did not find its text in what
+the agent concluded. The check reads the step's **final reply**, and its
+first line is the run's headline — so a reporter that opened with "Done."
+and put the verdict on line three fails a `^BAD` check with the right
+verdict sitting there. Tell the agent the first line *is* the verdict, and
+move a step that cannot manage it to a stronger tier.
+
+## "each: the previous group produced no items"
+
+`each: lines` splits what the previous step concluded into lines and found
+none. Usually the step wrote its list to a file and replied with a sentence.
+Either have it reply with the list, or use `each: rows of <file>` — a file
+has no turns and is the better contract for a list that must arrive exactly.
+
+## "over budget — $x spent of the flow's $y"
+
+The run crossed its `budget:` between two groups; the remaining steps were
+skipped. Look at which step spent it: a fast-tier agent writing a file one
+line per call, re-sending its whole context each time, is the usual culprit.
+Put `model:` on that step, tell the agent to write each file once, and set
+the cap at two or three times a normal run so real work never trips it.
+
+## "over budget — nothing left to spend before this step (budget: on the … agent)"
+
+The agent's own `budget:` — the most it may spend in one run — was used up
+by its earlier steps in this run, so this one was refused before it started.
+Raise the number in that agent's `agent.md`, or take it out: unset is no
+limit. The same line with `budget: in the flow file` is the flow's cap and
+lives there instead.
+
+## "is at its budget — $x spent today of $y/day"
+
+A cap over time, reached. New runs refuse until the window turns — tomorrow,
+next week, the new month — in the account's own `timezone:`. Raise it in
+Settings or in the file, or remove the line.
+
+## "was denied: … is outside this workspace"
+
+The agent reached for a path outside its workspace — `/tmp/something`, an
+absolute path, a checkout a tool made — and was refused. The message names
+the path it probably meant. It costs a turn, nothing more; if one step
+collects many, name the exact path in its prompt (`workspace/storage/x.md`).
+
+## "this push is not live yet — runs in flight"
+
+The push was accepted and will apply when the runs finish. A run parked at
+an approval gate counts. Decide the gate, or wait; `foldrun deploy --force`
+applies over a running flow when you mean it.
+
+## "missing `type:` — OKF requires a non-empty type on every concept"
+
+A file under `knowledge/` has no `type:` in its frontmatter. Add one
+(`type: Reference` is fine for a table or a list); the push is refused
+until it is there.
+
+## The run is parked and nobody knows
+
+Check the account's `notify:` — a workspace that declared its own block
+replaced the account's whole, and may have dropped `awaiting-approval`. The
+dashboard banner shows every parked run across workspaces regardless.
+
+## It ran on the wrong model
+
+`model:` resolves nearest-wins: the step, then the flow, then the agent. A
+flow with `model: fast` in its frontmatter runs every step on the fast tier
+whatever each agent says. The run trace names which level won
+(`model: haiku — flow`). Put `model:` on the step to lift one.
+
+## The schedule fired more often than it should
+
+When day-of-month and day-of-week are both restricted, cron ORs them.
+`0 5 1-7 * 5` fires every Friday and every day of the first week. Use a
+plain day of month for a monthly job.
+
+## Approval emails have no links
+
+The install has no `FOLDRUN_PUBLIC_URL`, or it points at an address that no
+longer resolves. The worker logs why, once. Set it to the origin people
+actually reach the install on.
+
+## A step's file never appeared in Storage
+
+The agent wrote to `outputs/` (the run's scratch, archived with the run) or
+to a path relative to somewhere it was not. Deliverables go to
+`workspace/storage/`; the run page's Out column shows what actually landed
+and where.
+
+## The browser came back with `[page rendered empty]`
+
+The page loaded, but nothing was on it — and the reason is in the same run
+log, one line above `page: <url>`: `page errors:` (an uncaught error in the
+page's own script), `page console:` (what it logged as an error),
+`requests failed:` (a script or an API call that never landed) or
+`requests refused:` (one the server answered 4xx/5xx). A single-page app
+that renders after load usually shows as none of these — give it a
+`wait_for` selector. A blocked resource you asked to `block` is never
+counted. For the whole picture, call again with `mode: network`: the page's
+own status and redirect chain first, then every request it made.
+
+## A browser action on `"@e4"` failed
+
+The number came from the last `mode=aria` in the same `session`, and the
+next call loaded the page fresh, so the tool looked for what the number
+pointed at — its role and name — and the message says which of three things
+happened:
+
+- `nothing is numbered yet` — no `mode=aria` ran in this `session` first,
+  or it ran under a different `session` name. The numbers are per session.
+- `is not on the page now` — the element is gone: a different page, a
+  signed-out view, a list that changed. Read it again with `mode=aria`.
+- `the page has 3 of those now and had 2` — the same button appears a
+  different number of times than when it was numbered, so which one was
+  meant is a guess the tool will not make. Read it again with `mode=aria`.
+
+In each case the fix is the same: take a fresh `mode=aria`
+(`interactive=true` for just the controls) and use its numbers. An element
+with no role and no text — a bare wrapper — cannot be found again at all;
+use a CSS selector for it.
+
+## The browser's output was cut at 18,000 characters
+
+The cap is on what the model sees, not on what was kept. `mode: markdown`
+writes all of it to `outputs/page.md`, `meta` to `outputs/meta.json`,
+`table` to `outputs/tables.json`, `network` to `outputs/network.json`, an
+`extract` step to `outputs/extracted.json` — the truncation line names the
+file. Read the file in the next step, or narrow the call: `wait_for` a
+specific section, `block="image,font,media"` so the page is text, or an
+`extract` step whose rows are exactly what you wanted.

package/docs/versions.md

@@ -0,0 +1,79 @@
+# Versions and releases
+
+The hosted platform deploys itself whenever its code changes — there is no
+release train and nobody decides "this is a release". Every deploy that comes
+up healthy is one, and gets a name.
+
+## The scheme
+
+```
+v2026.10.01.3
+ │    │  │  └─ the third deploy that day
+ │    │  └──── day   (UTC)
+ │    └─────── month
+ └──────────── year
+```
+
+CalVer with a daily counter, not semver. A box that ships every push to main
+would have a bot bumping a patch number forever, and the numbers would mean
+nothing; a date says when, and sorts. A rollback redeploys an older version
+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`).
+
+## Where to see it
+
+| Where | What |
+|---|---|
+| The sidebar's foot | `foldrun v2026.10.01.3`, linking to What's new |
+| **What's new** (`/dashboard/whats-new`) | every recent release, newest first, with what changed in each — grouped Features, Fixes, Docs and Other |
+| **Settings → About** | the version, when it was released, the API version, and each component's commit |
+| `GET /api/version` | the same as JSON, no key needed — see the [API reference](api#versions) |
+| `GET /api/changelog` | the release notes as JSON, with a key |
+| Any `/api` response | the `X-Foldrun-Version`, `X-Foldrun-Api` and `X-Foldrun-Cli` headers |
+| `foldrun version` | this CLI, its core, and the platform it talks to |
+
+An open dashboard tab checks every few minutes, and when you come back to it,
+whether the platform has moved on. If it has, a small notice offers a reload
+and a link to What's new. It never reloads by itself.
+
+## Release notes
+
+The deploy writes them: for each release, the commits between the version
+before and this one, in every part, grouped from what each commit says —
+Features, Fixes, Docs (anything in the docs, or that says it is docs) and
+Other (dependencies, tests, the deploy's own plumbing). The groups are read
+from the words of a commit subject, so a fix described without the word may
+land under Features. A release whose changes could not be read says so
+rather than showing an empty list.
+
+A self-hosted or locally built install has no notes and reports `dev`, or
+whatever `FOLDRUN_VERSION` it was started with.
+
+## The API version
+
+`api` in `/api/version`, and the `X-Foldrun-Api` header, is a date —
+`2026-10-01` — that changes only when a route changes in a way an existing
+caller would break on. A new route or a new field in an answer does not move
+it. Breaking changes are announced in the release notes of the version that
+makes them.
+
+## CLI compatibility
+
+The CLI talks to the platform over the same HTTP API as everything else, so
+an older CLI keeps working against a newer platform; what it lacks are the
+newest commands. Each platform version records the CLI released with it
+(`packages.cli` in `/api/version`, and `X-Foldrun-Cli` on every response):
+
+- `foldrun version` compares that with its own version and warns when the
+  platform's is newer.
+- Any other command that reaches the platform prints one dim line when the
+  platform's CLI is newer — at most once a day, only in a terminal, and
+  never in a script or CI. `FOLDRUN_NO_UPDATE_NOTICE=1` turns it off.
+- `foldrun --version` prints the CLI's version and nothing else, offline.
+
+To update: `npm i -g foldrun@latest`.

package/docs/workspaces.md

@@ -0,0 +1,160 @@
+# Workspaces
+
+A workspace is a folder, and the folder is the unit of everything: it is what
+you edit, deploy, permission, budget and back up. An account holds several —
+one per job, in practice — and they share nothing unless it is put in the
+account's library on purpose.
+
+## The layout
+
+```
+my-desk/
+  AGENTS.md            context every agent here sees, and the workspace's defaults
+  agents/<name>/       one folder per role
+    agent.md           frontmatter, then the prompt
+    knowledge/         given to this agent only
+    memory/            what this agent learned
+    outputs/           this step's scratch — archived with the run
+    scripts/           code this agent's tools run
+  flows/<name>.md      a numbered list of steps
+  tools/<name>.md      what may be called — an API, a script, an MCP server
+  skills/<name>/       a capability, in the open Agent Skills format
+  evals/<name>.md      tests
+  knowledge/           given to every agent in the workspace
+  memory/              what they learned, shared
+  state/               what the next run needs from this one
+  storage/             files a person reads or downloads
+  scripts/             code shared by this workspace's tools
+```
+
+Every one of those is optional except `AGENTS.md` and at least one agent.
+
+## The account around it
+
+On the platform a workspace never stands alone: it lives under an account,
+beside the account's own `AGENTS.md` and the library every workspace there
+shares.
+
+```
+my-account/
+  AGENTS.md            config and context every workspace here inherits
+  library/             tools, skills, scripts, knowledge, memory — shared
+  workspaces/
+    my-desk/           the tree above
+    ads-desk/
+```
+
+`foldrun init` makes exactly that on a laptop, and `foldrun new <name>` adds
+another workspace to it, so the folder you edit is the folder that runs. See
+[the CLI reference](cli#the-shape-of-a-folder) for the commands that act on the
+whole account — `check`, `deploy`, `pull`, `status`, `workspaces` — and for the
+one scope that has no API: the account's own `AGENTS.md` is not pushed or
+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.
+
+## `AGENTS.md` — context and defaults
+
+The body is prose every agent in the workspace sees before its own prompt.
+Put the things that are true of the whole desk there: the business, the
+standing rules, what the reader is like.
+
+The frontmatter is the workspace's defaults:
+
+```yaml
+---
+timezone: Australia/Sydney
+budget: 60                     # a cap in USD for this workspace — per month; or 60/day, 60/week; unset is no limit
+notify:
+  email: ops@example.com
+  events: [failed, awaiting-approval, completed]
+provider:                      # see Providers
+  base_url: https://openrouter.ai/api/v1
+  token: ${OPENROUTER_API_KEY}
+---
+```
+
+There is an `AGENTS.md` one level up too — the account's — and the two
+compose in a way worth learning once:
+
+- **Prose accumulates.** The account's body is added to every workspace's,
+  so a rule written at the account cannot be dropped below it.
+- **A frontmatter key replaces whole.** A workspace that sets `notify:`
+  replaces the account's `notify:` entirely — it does not merge into it. To
+  inherit a key, say nothing about it.
+
+The second rule is the one that surprises people: a workspace that declares
+its own `notify:` block silently stops receiving the account's default.
+
+### The clock, all the way down
+
+`timezone:` is the one default with levels below the workspace as well as
+above it, because a flow's schedule and an agent's own calendar are both real
+things to set. Nearest wins, and every level inherits the one above it unless
+it says otherwise:
+
+```
+agent frontmatter → flow frontmatter → workspace AGENTS.md →
+account AGENTS.md → FOLDRUN_TIMEZONE → UTC
+```
+
+Whichever level wins sets `TZ`, the date in the agent's prompt, and
+`$FOLDRUN_DATE` in its scripts and its `verify:` shell — so "today" means the
+same thing to every part of a step. Each step's trace names the zone and the
+level it came from.
+
+The value is an IANA name (`Australia/Sydney`) or a plain fixed offset —
+`UTC+10`, `GMT-5`, `+10:00`, `-05:30`, or a bare `UTC`. `foldrun check` and a
+deploy both refuse anything else; a bad value that reaches a run falls through
+to the next level with one line in the trace rather than failing the step.
+
+## The account library
+
+`<account>/library/` holds tools, skills, knowledge and memory shared by every
+workspace. Resolution is nearest-wins: an agent's own file beats the
+workspace's, which beats the library's. So a shared integration — the tool
+that clones your website, the skill that explains how — is defined once, and
+a workspace that needs a different version shadows it by defining the same
+name locally.
+
+From inside a run the library is read-only, reached as `account/…`
+(`account/knowledge/prices.md`). The Library page in the dashboard lists,
+for every shared file, which agents use it and where a nearer copy overrides
+it — that list is the blast radius of changing it.
+
+## Where a run's files go
+
+Three directories look alike and are not:
+
+| directory | who reads it next | survives a deploy | example |
+|---|---|---|---|
+| `outputs/` | this step, and the archive | no — it is the run's | a draft, a fetched page |
+| `storage/` | a person | yes | the weekly report, a CSV, an image |
+| `state/` | the next run | yes, and a deploy never overwrites it | a cursor, an append-only history |
+
+The test is not "is it important", it is **who reads it next**. A value
+regenerated every run is `storage/`; a value accumulated across runs is
+`state/`. From an agent, write `workspace/storage/x.md` and
+`workspace/state/x.md` — the older `../../storage/x.md` is the same place. See [Storage and sharing](storage-and-sharing).
+
+## What a deploy touches
+
+A deploy — `foldrun deploy`, or a `git push` to the workspace's remote —
+replaces the source tree: agents, flows, tools, skills, evals, knowledge,
+`AGENTS.md`. It **never** touches `runs/`, `state/`, `secrets.json`, or any
+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.
+
+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).
+
+## Previews
+
+Push a branch instead of `main` and the platform deploys a copy of the
+workspace named `<workspace>-preview-<branch>` from that branch's tree, runs
+its evals there, and never fires its schedules. It reads the source
+workspace's secrets. Deleting the branch deletes the preview. It is how a
+change to a live desk gets tried without touching the live desk.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foldrun",
-  "version": "0.6.0",
+  "version": "0.7.2",
   "description": "Agents are just folders. Write them, check them, run them — on your machine.",
   "license": "Apache-2.0",
   "type": "module",
@@ -11,18 +11,22 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@foldrun/core": "^0.4.0"
+    "@foldrun/core": "^0.5.0"
   },
   "files": [
     "bin",
     "src",
-    "README.md"
+    "README.md",
+    "docs"
   ],
   "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-secrets.test.ts tests/cli-check-library.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",
+    "test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.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",
     "release": "node scripts/release.mjs",
-    "typecheck": "tsc -p tsconfig.json"
+    "typecheck": "tsc -p tsconfig.json",
+    "docs:sync": "node scripts/sync-docs.mjs",
+    "prepack": "node scripts/sync-docs.mjs --check",
+    "prepare": "(test ! -f .githooks/install.sh || sh .githooks/install.sh)"
   },
   "repository": {
     "type": "git",