foldrun 26.3.3 → 26.3.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -30,9 +30,9 @@ foldrun deploy # push the account (or `deploy <workspace>`) to the p
30
30
 
31
31
  | Path | What |
32
32
  |---|---|
33
- | `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) |
33
+ | `AGENTS.md` | the account's shared context and defaults — every agent in every project reads it (except the managed coding-agent block, which the runtime strips) |
34
34
  | `workspaces/<name>/` | one workspace: a desk, a pipeline, a product |
35
- | `workspaces/<name>/AGENTS.md` | that workspace's context and settings |
35
+ | `workspaces/<name>/AGENTS.md` | that project's context and settings |
36
36
  | `workspaces/<name>/agents/<name>/agent.md` | one role: its persona, model, tools |
37
37
  | `workspaces/<name>/flows/<name>.md` | steps, in order, naming the agents that run them |
38
38
  | `workspaces/<name>/knowledge/` | reference material agents read |
@@ -42,7 +42,7 @@ foldrun deploy # push the account (or `deploy <workspace>`) to the p
42
42
  | `workspaces/<name>/tools/` | a folder tool: its definition and its code together |
43
43
  | `workspaces/<name>/scripts/` | code the agents call, referenced by `scripts:` |
44
44
  | `workspaces/<name>/state/` | what runs accumulate. Yours to read, never deployed over |
45
- | `library/` | skills, tools, scripts and knowledge shared by every workspace here |
45
+ | `library/` | skills, tools, scripts and knowledge shared by every project here |
46
46
  | `.claude/agents/<name>.md` | a Claude Code subagent — deploys AS an agent |
47
47
 
48
48
  `knowledge/` is what you tell the agents; `memory/` is what they worked out.
@@ -78,26 +78,26 @@ api workspaces/$WS/flows/<flow>/run -X POST # start one
78
78
 
79
79
  | Route (`/api/workspaces/<ws>` unless noted) | Methods | For |
80
80
  |---|---|---|
81
- | `/` | GET DELETE PATCH | the workspace itself |
81
+ | `/` | GET DELETE PATCH | the project itself |
82
82
  | `/deploy` | POST | what `foldrun deploy` calls |
83
83
  | `/source` | GET PUT PATCH DELETE | read and write single files |
84
84
  | `/runs` · `/runs/<id>` | GET · GET DELETE | list runs; one run, every step |
85
85
  | `/runs/<id>/stream` | GET | live events, server-sent |
86
86
  | `/runs/<id>/stop` · `/rerun` · `/approve` | POST | kill it; again from a step; release a gate |
87
87
  | `/flows` · `/flows/<f>` · `/flows/<f>/run` | GET POST · POST DELETE PATCH · POST | list, create, edit, start |
88
- | `/agents` · `/agents/<a>/run` · `/agents/import` | GET POST · POST · GET POST | list agents, run one, copy one in from another workspace |
88
+ | `/agents` · `/agents/<a>/run` · `/agents/import` | GET POST · POST · GET POST | list agents, run one, copy one in from another project |
89
89
  | `/evals` · `/evals/<e>/run` | GET POST · POST | list evals, run one |
90
90
  | `/tools/<t>/test` | POST | exercise one tool alone |
91
91
  | `/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 |
92
92
  | `/triggers?since=` | GET | why nothing ran: fired vs started per flow, with reasons |
93
93
  | `/hooks/<f>/rotate` | POST | new webhook token for a flow |
94
- | `/export` · `/import` | GET · POST | the workspace, a flow (`?kind=flow&name=`) or an agent as a .zip; take one in (`?dryRun=1` first, `?overwrite=1` to replace) |
95
- | `/restore` | POST | the workspace's source back to a point in its history — `dryRun` first, then `confirm` |
94
+ | `/export` · `/import` | GET · POST | the project, a flow (`?kind=flow&name=`) or an agent as a .zip; take one in (`?dryRun=1` first, `?overwrite=1` to replace) |
95
+ | `/restore` | POST | the project's source back to a point in its history — `dryRun` first, then `confirm` |
96
96
  | `/notify/deliveries` · `/notify/deliveries/<id>/redeliver` | GET · POST | every notify: webhook sent and each attempt; send one again |
97
97
  | `/api/secrets` · `/api/schedule` · `/api/account` · `/api/keys` | account-level | the vault, the clock, defaults, API keys |
98
98
  | `/api/me/notifications` | GET PATCH | what mail you get, per category; a key acts for whoever minted it |
99
99
 
100
- A key carries a role (viewer, editor, admin) and a workspace scope no wider
100
+ A key carries a role (viewer, editor, admin) and a project scope no wider
101
101
  than the person who minted it. Team, profile and MFA routes are a person's
102
102
  alone and refuse a key. The full reference with request and response shapes
103
103
  is the platform's `docs/api.md`.
package/docs/deploying.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Deploying
2
2
 
3
- A workspace deploys by sending its files: `foldrun deploy` from a folder,
3
+ A project deploys by sending its files: `foldrun deploy` from a folder,
4
4
  from your laptop or from CI. Every deploy is checked before anything goes
5
5
  live, refuses to swap files under a run in flight, and never touches what
6
6
  the platform owns.
@@ -16,18 +16,18 @@ foldrun deploy --to leads --commit $(git rev-parse HEAD)
16
16
 
17
17
  In CI there is no browser: set `FOLDRUN_URL` and `FOLDRUN_TOKEN` (a key from
18
18
  Settings → API keys, or `foldrun keys create`) and the same commands run. A
19
- key for CI should open the one workspace it deploys:
19
+ key for CI should open the one project it deploys:
20
20
  `foldrun keys create ci --workspaces leads`.
21
21
 
22
22
  `--commit` records which commit of your own repository the files came from;
23
- the workspace page and its History show it.
23
+ the project page and its History show it.
24
24
 
25
25
  ## Your own GitHub or GitLab
26
26
 
27
27
  Keep the folder in your own repository and deploy it from CI with the
28
28
  commands above. A connected app — a push to your main branch deploys,
29
29
  other branches become previews, a check on every commit — is coming, for
30
- GitHub first, then GitLab. Until 17 October 2026 every workspace was also a
30
+ GitHub first, then GitLab. Until 17 October 2026 every project was also a
31
31
  git remote on the platform, with deploy keys, branch previews, a mirror and
32
32
  a GitHub push webhook; those went, and history moved to the platform's own
33
33
  snapshots (below).
@@ -37,7 +37,7 @@ snapshots (below).
37
37
  The tree is validated the way `foldrun check` validates it — a step naming an
38
38
  agent that does not exist, a tool that resolves to nothing, a knowledge
39
39
  concept with no `type:` — and a deploy with issues is refused with the list.
40
- The workspace on disk is unchanged.
40
+ The project on disk is unchanged.
41
41
 
42
42
  ## What a deploy never touches
43
43
 
@@ -55,8 +55,8 @@ overrides that when you mean it.
55
55
 
56
56
  ## History and rollback
57
57
 
58
- Every change to a workspace is a revision — a deploy, a dashboard edit, an
59
- import — with who, when and a diff, on the workspace's History page and at
58
+ Every change to a project is a revision — a deploy, a dashboard edit, an
59
+ import — with who, when and a diff, on the project's History page and at
60
60
  `/api/workspaces/<ws>/history`. Every revision also keeps a snapshot of the
61
61
  whole source as it stood just after it: the platform's own deploy history,
62
62
  so rolling back never needs a repository.
package/docs/evals.md CHANGED
@@ -33,7 +33,7 @@ satisfy. The heading is the case's name, so make it the thing being checked.
33
33
  |---|---|
34
34
  | `name` | the eval's identity |
35
35
  | `agent` **or** `flow` | what runs. A flow eval runs the whole flow per case |
36
- | `model` | the **judge's** tier, not the subject's — cases run the agent on its own model. Unset, the workspace's `judge:` in `AGENTS.md` (see [The four jobs](four-jobs#judge--the-evaluation-default)), else the fast tier |
36
+ | `model` | the **judge's** tier, not the subject's — cases run the agent on its own model. Unset, the project's `judge:` in `AGENTS.md` (see [The four jobs](four-jobs#judge--the-evaluation-default)), else the fast tier |
37
37
  | `effort` | the judge's effort. PASS/FAIL against one sentence is not deep work |
38
38
  | `trigger` | `deploy` (default), `manual`, or `runs` — grade real finished runs instead of running cases (see [Grading live runs](#grading-live-runs)) |
39
39
  | `sample` | `trigger: runs` — the percent of finished runs graded, 0 to 100 (default 25) |
@@ -60,12 +60,12 @@ wrong. The same vocabulary is a step's `verify:`, so a flow and an eval say
60
60
  ## When they run
61
61
 
62
62
  `trigger: deploy` — the default — runs the eval on every deploy of the
63
- workspace, which is what makes it a regression test rather than a thing someone
63
+ project, which is what makes it a regression test rather than a thing someone
64
64
  remembers to click. Results land in `evals/.results/`, and a dated line goes to
65
65
  `history.jsonl` so movement is visible across weeks.
66
66
 
67
- Each line is stamped with the commit the workspace was running (a git sha, or
68
- a revision id `r-…` when it was edited on the platform), and the workspace's
67
+ Each line is stamped with the commit the project was running (a git sha, or
68
+ a revision id `r-…` when it was edited on the platform), and the project's
69
69
  **Observe** page reads them as **Evals by change**: each eval's latest score
70
70
  against its most recent run on a *different* commit, the biggest drop first.
71
71
  Not the run before — two runs on one commit differ only by the model, and a
@@ -115,7 +115,7 @@ expect:
115
115
  hash of the run id, so the same run is always in or out.
116
116
  - **When.** The platform grades a few runs every five minutes, at most four
117
117
  per account a pass, so a backlog drains steadily rather than spending at
118
- once. A paused account or workspace is not graded.
118
+ once. A paused account or project is not graded.
119
119
  - **The checks.** `contains:`, `not-contains:` and `judge:`, cheap ones
120
120
  first; the judge only runs when they pass. `file:` and `run:` are refused
121
121
  (`foldrun check` and the deploy say so): a finished run's sandbox is gone,
@@ -128,7 +128,7 @@ expect:
128
128
  after an hour, three times at most.
129
129
  - **What it costs.** One judge call per `judge:` line per graded run — at
130
130
  most five lines in a grader — on the account's own model key like any
131
- eval judge. A paused account or workspace is not graded, by the pass or
131
+ eval judge. A paused account or project is not graded, by the pass or
132
132
  by **Grade a run**. The card shows what the
133
133
  judges cost; the runs' own cost is on the runs.
134
134
 
package/docs/extract.md CHANGED
@@ -135,7 +135,7 @@ The answer:
135
135
 
136
136
  Every route, field and refusal is in [api](api.md#files-to-text). Starting
137
137
  an extraction of a file you send takes what starting a run takes; reading a
138
- stored file takes read access to its workspace, writing its `.txt` beside it
138
+ stored file takes read access to its project, writing its `.txt` beside it
139
139
  takes write access.
140
140
 
141
141
  ## Engines and their licences
package/docs/faq.md CHANGED
@@ -2,11 +2,11 @@
2
2
 
3
3
  **Is this a framework?** No. There is nothing to import. An agent is a folder,
4
4
  a flow is a numbered list in a markdown file, and the CLI or the platform
5
- reads them. You can write a working workspace in an editor with no
5
+ reads them. You can write a working project in an editor with no
6
6
  dependency installed.
7
7
 
8
8
  **Do I need an account to try it?** No. `npm install -g foldrun`, a model key,
9
- and `foldrun init` gives you a workspace that runs on your machine. The
9
+ and `foldrun init` gives you a project that runs on your machine. The
10
10
  account is for running it somewhere that is not your laptop, on a schedule,
11
11
  with a team.
12
12
 
@@ -14,7 +14,7 @@ with a team.
14
14
  tier — `fast`, `default`, `max` — and the platform resolves the tier to a
15
15
  model. Bring your own key for any provider that speaks the Anthropic or the
16
16
  Chat Completions API — once for the whole account in Settings → Models
17
- (`foldrun account model set`), or per workspace or agent with a `provider:`
17
+ (`foldrun account model set`), or per project or agent with a `provider:`
18
18
  block — and the platform bills you nothing for those tokens. On a hosted
19
19
  platform every account brings its own API key — Claude login tokens are not
20
20
  accepted — or, on foldrun's own platform, chooses **foldrun's models**:
@@ -31,7 +31,7 @@ file names a tool that can, and the reference pattern is to give that tool
31
31
  only to the step after a human gate. An agent with no tool that writes cannot
32
32
  write, whatever it is told.
33
33
 
34
- **What stops a runaway?** Three caps — per run, per workspace per month, per
34
+ **What stops a runaway?** Three caps — per run, per project per month, per
35
35
  account per month — and the stop button, which destroys the sandbox. A
36
36
  step with no `timeout:` runs until it finishes; that is deliberate, and the
37
37
  caps are the ceiling.
@@ -49,7 +49,7 @@ other with `trigger: flow`.
49
49
  `.claude/agents/<name>.md` deploys as a foldrun agent with no conversion.
50
50
  The scaffolded `CLAUDE.md` tells your editor the layout.
51
51
 
52
- **Where is my data?** In your workspace's folder, as files — on your machine,
52
+ **Where is my data?** In your project's folder, as files — on your machine,
53
53
  or on the hosted platform's data volume — and its blobs in the
54
54
  file store. Nothing is hidden in a database only the platform can read, and
55
55
  a deploy never touches what an agent learned or a run recorded.
@@ -36,7 +36,7 @@ account in the beta first, then for a rollout, then for everyone. The
36
36
  features are finished, but may still change.
37
37
 
38
38
  Joining or leaving is the account's own choice, made by an admin of every
39
- workspace, and it can be undone at any time:
39
+ project, and it can be undone at any time:
40
40
 
41
41
  - the dashboard: **Settings → General → Beta features**;
42
42
  - `foldrun account beta on` (or `off`; bare `foldrun account beta` shows where
package/docs/flows.md CHANGED
@@ -103,7 +103,7 @@ begins.
103
103
  | `loop:` | send the flow back one group up to N times (capped at 5) |
104
104
  | `until:` | the marker that ends the loop |
105
105
  | `output:` | `json` — the reply must end with one ```json block, parsed and passed on losslessly |
106
- | `schema:` | with `output: json` — the JSON Schema the value must satisfy: one-line JSON, a YAML block under the key, or a file under the workspace |
106
+ | `schema:` | with `output: json` — the JSON Schema the value must satisfy: one-line JSON, a YAML block under the key, or a file under the project |
107
107
  | `model:` | override the tier for this step |
108
108
  | `effort:` | override how hard it thinks for this step |
109
109
  | `max_output_tokens:` | the longest one model reply may be for this step, in tokens — over the flow's and the agent's |
@@ -111,12 +111,12 @@ begins.
111
111
  | `timeout:` | seconds, or `90s` / `15m` / `4h` / `3d` — **the only clock there is** |
112
112
  | `max_turns:` | the most model turns before the step is stopped (1 to 500) — the third bound beside `budget:` and `timeout:` |
113
113
  | `limits:` | this step's call limits, on one line — `limits: {web.search: 10, calls: 50}` — over the agent's, key by key. A call past one is refused, never run ([Tools](tools#limits--how-many-calls-a-step-may-make)) |
114
- | `verify:` | a shell command, or an assertion (`contains:`, `matches:`, `file:`, `judge:`). The shell runs in the agent's folder and gets the step's final turn in the file `$FOLDRUN_REPLY_FILE`; `workspace/…` reaches the workspace root there, and in `file: workspace/storage/x.md`; `node workspace/tools/x/check.mjs` runs as its own main module, so a check it makes counts ([Agents](agents#where-files-live-from-the-agents-point-of-view)). The check runs on what is left of the step's `timeout:` (at least 30 s of it); with no `timeout:` it has no clock either. A stop ends it |
114
+ | `verify:` | a shell command, or an assertion (`contains:`, `matches:`, `file:`, `judge:`). The shell runs in the agent's folder and gets the step's final turn in the file `$FOLDRUN_REPLY_FILE`; `workspace/…` reaches the project root there, and in `file: workspace/storage/x.md`; `node workspace/tools/x/check.mjs` runs as its own main module, so a check it makes counts ([Agents](agents#where-files-live-from-the-agents-point-of-view)). The check runs on what is left of the step's `timeout:` (at least 30 s of it); with no `timeout:` it has no clock either. A stop ends it |
115
115
  | `approve:` | park until a person releases it |
116
116
  | `ask:` | the same gate carrying a question; the typed answer reaches the prompt (a plain approval with no note reaches it as "approved with no note") |
117
117
  | `preview:` | what the gate shows: paths under `storage/` (a `workspace/storage/` prefix is accepted), comma-separated, globs allowed — `draft/*.mdx, draft/images/*.webp`; at most 12 files |
118
118
  | `wait:` | `3d` (`s`/`m`/`h`/`d`, capped at 30 days) or `event` — the run page shows the event URL and can release it with a payload, recorded as released by you (approve with `payload`) |
119
- | `on-fail:` | another agent takes the step over, with the failure as context — and, for a gated step, the person's approval and answer, which it acts within. The rescuer owes what the step owed: its `verify:`, its `output:`, and a `loop:` step's `until:` marker (a loop that runs out of cycles goes to its rescuer too). A `verify:` that accepts `BLOCKED` never fails, so it never reaches the rescuer. A step refused by the model supply itself — a spent usage window, a credential refused — is not handed to a rescuer on the same supply (the same `provider:`, or both on the workspace's): it would be refused the same way, and the issue is filed as the cap or the credential |
119
+ | `on-fail:` | another agent takes the step over, with the failure as context — and, for a gated step, the person's approval and answer, which it acts within. The rescuer owes what the step owed: its `verify:`, its `output:`, and a `loop:` step's `until:` marker (a loop that runs out of cycles goes to its rescuer too). A `verify:` that accepts `BLOCKED` never fails, so it never reaches the rescuer. A step refused by the model supply itself — a spent usage window, a credential refused — is not handed to a rescuer on the same supply (the same `provider:`, or both on the project's): it would be refused the same way, and the issue is filed as the cap or the credential |
120
120
  | `delegate:` | the step's agent picks who runs next, from this set |
121
121
 
122
122
  ### What is retried without a `retry:`
@@ -132,7 +132,7 @@ tried again whoever wrote the flow:
132
132
  | a `web` provider timed out or answered busy | tried three times, about 2 s and 6 s apart (see the web tool) |
133
133
 
134
134
  None of the step-level ones runs again once a tool that can act outside the
135
- workspace has run in that attempt: the post may already be up. When a step
135
+ project has run in that attempt: the post may already be up. When a step
136
136
  still fails, the run says so — `notify:` sends `failed` (and `blocked`, for a
137
137
  run that finished but refused), and the run page's **Re-run from here**,
138
138
  `foldrun rerun <run-id> --from <n>` or `POST …/runs/<id>/rerun` start it
@@ -192,7 +192,7 @@ On a day with nothing in the queue the writer skips itself, and without the
192
192
  `when:` the sheet and the gate would still run — a skipped fan-out leaves no
193
193
  result, so there is no marker to read, and a person is asked to approve
194
194
  nothing. With it, the run ends after the scan. A missing file, a header on
195
- its own, or a path outside the workspace all skip, and the step says which.
195
+ its own, or a path outside the project all skip, and the step says which.
196
196
 
197
197
  For `case:` it matters more, because routing is exclusive. A label picked
198
198
  out of a sentence does not merely run an extra step: "this is not a
@@ -270,7 +270,7 @@ rides the run record as `data`. A shell `verify:` receives it on stdin.
270
270
  ```
271
271
 
272
272
  One-line JSON works too (`schema: {"type": "array"}`), and so does a file
273
- under the workspace (`schema: workspace/schemas/lead.json`, JSON or YAML). The
273
+ under the project (`schema: workspace/schemas/lead.json`, JSON or YAML). The
274
274
  schema is quoted whole in the step's prompt, so the model is told what it
275
275
  must produce rather than left to guess from field names, and the value is
276
276
  checked where it is parsed. One that does not fit fails the step with the
@@ -322,7 +322,7 @@ normal outcome, recorded as one.
322
322
  |---|---|
323
323
  | `name` | the flow's identity |
324
324
  | `description` | what it is for |
325
- | `owner` | the person who answers for it — an email or a name; unset, the workspace's `owner:`, then the account's |
325
+ | `owner` | the person who answers for it — an email or a name; unset, the project's `owner:`, then the account's |
326
326
  | `trigger` | how it starts — see below |
327
327
  | `schedule` / `timezone` | 5-field cron, and the zone it fires in — which is also the calendar every step in this flow works to (see below) |
328
328
  | `at` | ISO 8601 instant, for `trigger: once` |
@@ -334,7 +334,7 @@ normal outcome, recorded as one.
334
334
  | `model` / `effort` | defaults for every step |
335
335
  | `max_output_tokens` | every step's longest reply, in tokens, unless the step says (over the agent's) |
336
336
  | `budget` | the most one run may spend, in USD — a number, or `unlimited`; unset is no limit |
337
- | `compute` | what one run's steps may hold together at once — `{ vcpu: 2, memory: 4Gi, disk: 20Gi }`, any of them. Each run has its own; it only narrows the workspace's and account's. A step past it waits for one of its run's steps to finish; one bigger than it fails at once ([four levels](budgets-and-billing#compute-at-four-levels)) |
337
+ | `compute` | what one run's steps may hold together at once — `{ vcpu: 2, memory: 4Gi, disk: 20Gi }`, any of them. Each run has its own; it only narrows the project's and account's. A step past it waits for one of its run's steps to finish; one bigger than it fails at once ([four levels](budgets-and-billing#compute-at-four-levels)) |
338
338
  | `overlap` | `skip` or `queue` when a run is already live |
339
339
  | `issues` | `stay-open` (the default: a person resolves this flow's [issues](runs#issues)) or `auto-close` (a run that goes fine closes them) |
340
340
  | `priority` | `high`, `normal` or `low` — where this flow's runs stand in the queue against everyone else's |
@@ -455,7 +455,7 @@ The rules, all of them:
455
455
 
456
456
  A filtered delivery counts toward nothing: not `idempotency:`, not
457
457
  `throttle:`, not `debounce:`, not `disable_after:`. A paused account or
458
- workspace is still told it is paused first. `filter:` on a `schedule`,
458
+ project is still told it is paused first. `filter:` on a `schedule`,
459
459
  `once`, `watch` or `manual` flow does nothing, and `foldrun check` says so.
460
460
 
461
461
  Try a delivery without sending one: the Triggers page has a **Test filter**
@@ -510,7 +510,7 @@ and a slow run may still be doing the work. What to do about it is yours.
510
510
 
511
511
  `approvers:` is the list of email addresses that may decide this flow's
512
512
  gates, or the single word `admins` for anyone at admin or above. Unset, the
513
- existing rule applies: anyone who can run the workspace can answer.
513
+ existing rule applies: anyone who can run the project can answer.
514
514
 
515
515
  Whatever the list says, **nobody approves a run they started themselves**. A
516
516
  gate exists so a second person looks, and a run someone kicked off and then
@@ -542,7 +542,7 @@ a literal, never an expression, so the cap is readable off the file. An
542
542
  agent's own `budget:` — the most it may spend in one run — applies to its
543
543
  steps too, and the tighter of the two wins. It is shared the same way: the
544
544
  agent's steps running at once split what is left of it, so a fan-out of
545
- twenty copies cannot spend the agent's cap twenty times. The workspace's and the
545
+ twenty copies cannot spend the agent's cap twenty times. The project's and the
546
546
  account's caps over time still apply on top.
547
547
 
548
548
  `overlap:` decides what a new fire does while a run of the same flow is live.
@@ -732,14 +732,14 @@ inputs file — in this folder, or the deployed copy with `--to <workspace>`.
732
732
 
733
733
  **Draft with AI** (beside New flow) and **Redraft with AI** (on a card) take
734
734
  a description in words and propose the flow file, plus an `agent.md` for each
735
- agent it needs that the workspace does not have — existing agents are used by
735
+ agent it needs that the project does not have — existing agents are used by
736
736
  name. The proposal is checked with the deploy's own checks and the flow lint
737
737
  `foldrun check` runs; if they find errors the model is shown them and
738
738
  repairs once, and anything still wrong is listed beside the files. Each file
739
739
  is shown as a diff against what is there. **Nothing is written** until you
740
740
  press Save and confirm; then each file is saved as an ordinary revision.
741
741
 
742
- The model is the workspace's own Anthropic-format `provider:` when it has
742
+ The model is the project's own Anthropic-format `provider:` when it has
743
743
  one (a Chat-Completions provider is refused), else the platform's models,
744
744
  billed to the account like a run (one ledger line, flow `ai-draft`). A
745
745
  description is at most 4,000 characters and an answer at most 8,000 tokens.
@@ -766,5 +766,5 @@ abc`, `retry: 9`, `loop: 0`, `each: columns`, `output: yaml` each fail
766
766
  second.
767
767
 
768
768
  A required step failing fails the flow, and the remaining groups are skipped. A
769
- workspace with one agent and no flows is normal — `foldrun run <agent>` runs it
769
+ project with one agent and no flows is normal — `foldrun run <agent>` runs it
770
770
  as a one-step flow, so there is a single execution path either way.
package/docs/four-jobs.md CHANGED
@@ -64,7 +64,7 @@ as `verify:` and `limits:` under a step, stay where they are.
64
64
  other document, `governance:` and the rest are that document's own words
65
65
  and are left as written.
66
66
  - **The cascade is unchanged.** The account's `AGENTS.md`, then the
67
- workspace's, then the agent, then the step: a block at one level and a flat
67
+ project's, then the agent, then the step: a block at one level and a flat
68
68
  key at another combine exactly as two flat keys would.
69
69
 
70
70
  ## `judge:` — the evaluation default
@@ -72,8 +72,8 @@ as `verify:` and `limits:` under a step, stay where they are.
72
72
  `judge: {model, effort}` in `AGENTS.md` is the model, and how hard it
73
73
  thinks, for every grader in the workspace: each eval's `judge:` checks and
74
74
  every flow step's `verify: judge:`. An eval that names its own `model:` keeps
75
- it. Unset, judges run on the fast tier. Field by field, the workspace's wins:
76
- a workspace that sets only `effort` keeps the account's `model`.
75
+ it. Unset, judges run on the fast tier. Field by field, the project's wins:
76
+ a project that sets only `effort` keeps the account's `model`.
77
77
 
78
78
  ## Where each job shows
79
79
 
@@ -86,10 +86,10 @@ a workspace that sets only `effort` keeps the account's `model`.
86
86
 
87
87
  `foldrun jobs` prints all four; with `--to <workspace>`, each field's value
88
88
  there, the account's, and how the two combine. They do not all simply
89
- override: `network_enforce` is on when either turns it on, a workspace's
89
+ override: `network_enforce` is on when either turns it on, a project's
90
90
  `budget` and the account's both apply, `hooks` run from both, `network`
91
91
  takes its level from the nearest setting and its sites from every level, `limits` merge key by key, `judge`
92
92
  field by field, and `priority` and `concurrency` are read from the account
93
93
  alone. The rest — `owner`, `notify`, `alerts`, `telemetry` and others — the
94
- workspace's replaces the account's whole. Fields the CLI cannot set (`limits`,
94
+ project's replaces the account's whole. Fields the CLI cannot set (`limits`,
95
95
  `network`, `hooks`, `capture`, …) are written in `AGENTS.md`.
@@ -16,8 +16,8 @@ foldrun check # free: no model is called
16
16
  foldrun run publish --task "write about rain"
17
17
  ```
18
18
 
19
- `init` scaffolds an **account folder** with one workspace in it, and that
20
- workspace already works: two agents, a flow that names them, an eval, and
19
+ `init` scaffolds an **account folder** with one project in it, and that
20
+ project already works: two agents, a flow that names them, an eval, and
21
21
  knowledge they share. `check` validates all of it offline —
22
22
  run it after edits the way you would run a typecheck. It is the cheapest
23
23
  feedback in the system and it catches a broken flow before a schedule fires it
@@ -42,7 +42,7 @@ my-account/
42
42
  ```
43
43
 
44
44
  That is the shape the platform keeps, so the folder you edit is the folder that
45
- runs. `--workspace <name>` names the first workspace (default `main`) and
45
+ runs. `--workspace <name>` names the first project (default `main`) and
46
46
  `foldrun new <name>` adds another. `foldrun init --flat` makes the older
47
47
  single-folder shape instead, and every command still reads it.
48
48
 
@@ -114,21 +114,21 @@ foldrun secrets set STRIPE_KEY # prompted, never echoed, never in a fil
114
114
  ```
115
115
 
116
116
  Agents name them in `secrets:` and receive the value at run time. They are never
117
- written into the workspace, so a workspace is always safe to commit.
117
+ written into the project, so a project is always safe to commit.
118
118
 
119
119
  ## The checklist on the dashboard
120
120
 
121
- The first time you open an account that has no workspace, the dashboard
121
+ The first time you open an account that has no project, the dashboard
122
122
  starts you in the **welcome flow** (`/dashboard/welcome`): add your model key
123
123
  (on a hosted platform, where the account brings its own — every run is
124
124
  refused until it has one), choose what to start with — the demo pipeline, a
125
- blank workspace, an imported .zip, the CLI, or connecting your AI app over
125
+ blank project, an imported .zip, the CLI, or connecting your AI app over
126
126
  MCP — then run it once and watch each step live, ending on the run's page or,
127
127
  if it stops, the reason and the Doctor. Every screen can be skipped, and the
128
128
  flow picks up wherever the account really is, however you did the work.
129
129
 
130
130
  After that the home page shows a **Getting started** card: add your model
131
- key, create a workspace, write or deploy an agent, run a flow, get a run to
131
+ key, create a project, write or deploy an agent, run a flow, get a run to
132
132
  finish, add a secret, schedule a flow or give it a webhook, invite a
133
133
  teammate, set up billing (where the plan asks for it) and install the CLI —
134
134
  "4 of 8", with the next step opened up and a link to where to do it, and
@@ -143,10 +143,10 @@ models, billed in credits). A step's **…** menu hides that step for you; the
143
143
  card's hides the whole card, and the line at the foot of the page brings it
144
144
  back. It goes away by itself once every step is done.
145
145
 
146
- Each workspace's overview has a **Workspace checklist** of what a desk needs
146
+ Each project's overview has a **Project checklist** of what a desk needs
147
147
  before it can be left to run on its own: a flow that ran to the end, a
148
148
  schedule or webhook, an owner, an eval, and `notify:` so someone is told
149
- when a run fails — each ticked from the workspace itself (the owner and
149
+ when a run fails — each ticked from the project itself (the owner and
150
150
  `notify:` count when the account's AGENTS.md sets them), each a link to
151
151
  where it is done. Hide an item, or the card, for yourself.
152
152
 
@@ -162,5 +162,5 @@ a key.
162
162
  ## Where to go next
163
163
 
164
164
  - **The grammar** — every field an agent or flow can carry: Help
165
- - **The API** — driving a deployed workspace over HTTP: the API reference
165
+ - **The API** — driving a deployed project over HTTP: the API reference
166
166
  - **The CLI** — every command and flag: the CLI reference
package/docs/glossary.md CHANGED
@@ -6,26 +6,26 @@ to outside agents holding an **A2A key**; an agent's `remotes:` are the
6
6
  outside agents it may call. See [A2A](a2a).
7
7
 
8
8
  **account** — the top level: people, keys, the library, the wallet, and the
9
- workspaces under it. Has one owner.
9
+ projects under it. Has one owner.
10
10
 
11
11
  **agent** — one role: a folder with an `agent.md` whose frontmatter grants and
12
12
  whose prose is the prompt.
13
13
 
14
- **AGENTS.md** — context and defaults, at the account and at each workspace.
14
+ **AGENTS.md** — context and defaults, at the account and at each project.
15
15
  Prose accumulates downward; a frontmatter key replaces whole.
16
16
 
17
17
  **budget** — a cap: per run (in a flow, or on an agent for its own steps),
18
- per workspace over a day, week or month, per account the same. Unset is no
18
+ per project over a day, week or month, per account the same. Unset is no
19
19
  limit.
20
20
 
21
21
  **conclusion** — a step's final reply, as opposed to every turn joined. What
22
22
  checks and headlines read.
23
23
 
24
- **desk** — an everyday name for a workspace that does one job on its own —
24
+ **desk** — an everyday name for a project that does one job on its own —
25
25
  a blog desk, a Reddit desk — its agents and flows, running on a schedule.
26
- Nothing in the format is called a desk; it is a workspace.
26
+ Nothing in the format is called a desk; it is a project.
27
27
 
28
- **deploy** — sending a workspace's source tree to the platform with
28
+ **deploy** — sending a project's source tree to the platform with
29
29
  `foldrun deploy`. Never touches runs, state, secrets or memory.
30
30
 
31
31
  **eval** — a test for an agent or a flow: a task and what a good answer
@@ -44,12 +44,12 @@ headline is the last step's.
44
44
  **knowledge** — what people give an agent. Read by all, written by none.
45
45
 
46
46
  **library** — the account's shared tools, skills, knowledge and memory.
47
- Nearest wins: a workspace shadows it by defining the same name.
47
+ Nearest wins: a project shadows it by defining the same name.
48
48
 
49
49
  **memory** — what an agent learned, one fact per file. The one place it
50
50
  writes without a grant.
51
51
 
52
- **preview** — a copy of a workspace deployed from a branch, evals run,
52
+ **preview** — a copy of a project deployed from a branch, evals run,
53
53
  schedules off, deleted with the branch.
54
54
 
55
55
  **run** — the record of a flow being driven: every step, event and cost.
@@ -79,5 +79,5 @@ another flow, a file, a URL that changed.
79
79
  **verify** — a check on a step's outcome: a shell command, or `contains:`,
80
80
  `matches:`, `file:`, `judge:`. Where arithmetic goes.
81
81
 
82
- **workspace** — a folder, and the unit of editing, deploying, permission,
82
+ **project** — a folder, and the unit of editing, deploying, permission,
83
83
  budget and backup.
package/docs/hooks.md CHANGED
@@ -20,10 +20,10 @@ hooks: [no-force-push]
20
20
  ```
21
21
 
22
22
  `hooks:` in an agent's frontmatter turns hooks on for that agent. The same
23
- key in a workspace's `AGENTS.md` turns them on for every agent in it, and in
24
- the account's `AGENTS.md` for every agent in every workspace. They run in
25
- that order (account, workspace, agent), each name once. A name is looked up
26
- in the workspace's `hooks/` first, then the library's. A name that resolves
23
+ key in a project's `AGENTS.md` turns them on for every agent in it, and in
24
+ the account's `AGENTS.md` for every agent in every project. They run in
25
+ that order (account, project, agent), each name once. A name is looked up
26
+ in the project's `hooks/` first, then the library's. A name that resolves
27
27
  to nothing is a `foldrun check` error, and a step that names one is refused
28
28
  rather than run without its hooks.
29
29
 
@@ -115,7 +115,7 @@ a `tool.call` hook uses a provider's own search.
115
115
 
116
116
  Every refusal, rewrite, added context and failure is a line on the step's
117
117
  trail (`hook no-force-push denied Bash: force push — use --force-with-lease`)
118
- and a badge on the run page. The workspace's Hooks page lists its hooks and
118
+ and a badge on the run page. The project's Hooks page lists its hooks and
119
119
  what each one refused or rewrote lately.
120
120
 
121
121
  ## Trying one
@@ -23,7 +23,7 @@ write.
23
23
  |---|---|---|
24
24
  | **knowledge/** | nobody | given to it; reading is denied to nothing, writing to everything |
25
25
  | **memory/** | the agent | what it learned, one fact per file, indexed |
26
- | **state/** | the workspace | the bookmark between runs |
26
+ | **state/** | the project | the bookmark between runs |
27
27
  | **storage/** | anyone | bytes, not source — PDFs, CSVs, images |
28
28
 
29
29
  The line between the last two is worth learning early: a value **regenerated**
@@ -35,15 +35,15 @@ The design bets on three things:
35
35
  | **Your own server** | Docker and the public repositories | the whole platform on one machine of yours, for you or your organisation |
36
36
  | **Hosted** | an account | ours: schedules, sandboxes, a vault, a team — nothing to run |
37
37
 
38
- The same workspace moves between them with `foldrun deploy`.
39
- Start locally; that is where every workspace should be born. foldrun is
38
+ The same project moves between them with `foldrun deploy`.
39
+ Start locally; that is where every project should be born. foldrun is
40
40
  source-available under the Functional Source License: free for your own
41
41
  use and your organisation's, not for offering it to others as a service —
42
42
  see [Running it yourself](self-hosting).
43
43
 
44
44
  ## Where to go
45
45
 
46
- - [Getting started](getting-started) — install, make a workspace, run it.
46
+ - [Getting started](getting-started) — install, make a project, run it.
47
47
  - [How it works](how-it-works) — the eight nouns and the flow grammar, in one read.
48
- - [Workspaces](workspaces), [Agents](agents), [Flows](flows), [Tools](tools) — the format, field by field.
48
+ - [Projects](workspaces), [Agents](agents), [Flows](flows), [Tools](tools) — the format, field by field.
49
49
  - [Runs](runs), [Budgets and billing](budgets-and-billing), [Security](security) — what happens when it runs.
@@ -8,14 +8,14 @@ one that repeats itself.
8
8
  |---|---|---|
9
9
  | **knowledge/** | people | what you tell the agents: reference material, standards, the price list |
10
10
  | **memory/** | the agent | what it worked out: one fact per file, indexed |
11
- | **state/** | the workspace | the bookmark between runs: a cursor, an append-only history |
11
+ | **state/** | the project | the bookmark between runs: a cursor, an append-only history |
12
12
  | **storage/** | anyone | bytes a person reads — see [Storage and sharing](storage-and-sharing) |
13
13
 
14
14
  ## Knowledge is given, not learned
15
15
 
16
- `knowledge/` at the workspace is read by every agent there; `knowledge/`
16
+ `knowledge/` at the project is read by every agent there; `knowledge/`
17
17
  inside an agent's folder by that agent alone; the account library's by
18
- every workspace. Writing to any of them is denied outright — through the
18
+ every project. Writing to any of them is denied outright — through the
19
19
  file tools and through a script. An agent that rewrites the price list it was
20
20
  handed has corrupted its own source of truth; what it discovers goes to
21
21
  `memory/`.
@@ -47,7 +47,7 @@ writes it there and finds it next run — and a deploy never overwrites memory
47
47
  a push does not mention, so what was learned survives the next edit to the
48
48
  prompt.
49
49
 
50
- Memory is per agent by default; the workspace's `memory/` is shared by the
50
+ Memory is per agent by default; the project's `memory/` is shared by the
51
51
  desk, and the library's by the account.
52
52
 
53
53
  ## Finding it: search and history
@@ -55,7 +55,7 @@ desk, and the library's by the account.
55
55
  Two tool groups give an agent its own past at scale:
56
56
 
57
57
  - **`tools: [search]`** — `search_files(query)`: ranked full-text search over
58
- knowledge, memory, state and storage, at the agent's, the workspace's and
58
+ knowledge, memory, state and storage, at the agent's, the project's and
59
59
  the library's scope. Lexical (BM25), not embeddings — nothing leaves the
60
60
  box, and the queries an agent makes are rare exact tokens where that
61
61
  wins. Behind it is an inverted index built inside the step on the first
@@ -64,7 +64,7 @@ Two tool groups give an agent its own past at scale:
64
64
  re-read, and nothing is persisted, so the index can never be stale across
65
65
  a deploy or a hand edit. Search first, then read the hit.
66
66
  - **`tools: [history]`** — `recall_runs()` and `read_run(id)`: what this
67
- workspace's earlier runs concluded and what their steps said. A reporter
67
+ project's earlier runs concluded and what their steps said. A reporter
68
68
  that wants "what did last week's run find" asks, rather than being handed
69
69
  every prior run.
70
70