foldrun 26.3.4 → 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.
- package/bin/foldrun.mjs +60 -60
- package/docs/a2a.md +12 -12
- package/docs/agents.md +21 -21
- package/docs/api-usage.md +2 -2
- package/docs/api.md +98 -98
- package/docs/assistant.md +21 -21
- package/docs/backups-and-restore.md +11 -11
- package/docs/budgets-and-billing.md +21 -21
- package/docs/checks.md +19 -19
- package/docs/cli.md +100 -100
- package/docs/coding-agents.md +8 -8
- package/docs/deploying.md +7 -7
- package/docs/evals.md +6 -6
- package/docs/extract.md +1 -1
- package/docs/faq.md +5 -5
- package/docs/feature-flags.md +1 -1
- package/docs/flows.md +14 -14
- package/docs/four-jobs.md +5 -5
- package/docs/getting-started.md +10 -10
- package/docs/glossary.md +9 -9
- package/docs/hooks.md +5 -5
- package/docs/how-it-works.md +1 -1
- package/docs/introduction.md +4 -4
- package/docs/knowledge-and-memory.md +6 -6
- package/docs/mcp.md +15 -15
- package/docs/network.md +9 -9
- package/docs/notifications.md +16 -16
- package/docs/oauth.md +1 -1
- package/docs/providers.md +6 -6
- package/docs/runs.md +28 -28
- package/docs/scheduling.md +1 -1
- package/docs/secrets.md +22 -22
- package/docs/security.md +15 -15
- package/docs/self-hosting.md +18 -18
- package/docs/status.md +1 -1
- package/docs/storage-and-sharing.md +14 -14
- package/docs/team-and-access.md +29 -29
- package/docs/tools.md +20 -20
- package/docs/troubleshooting.md +4 -4
- package/docs/workspaces.md +43 -43
- package/package.json +1 -1
- package/src/commands.mjs +131 -131
- package/src/guide.mjs +1 -1
package/docs/tools.md
CHANGED
|
@@ -61,14 +61,14 @@ headers:
|
|
|
61
61
|
| `timeout` | seconds a call may take; without one the call runs until it finishes |
|
|
62
62
|
| `rate` | calls per second from one step — `5/s`, `100/m`; a call over the limit waits, it does not fail |
|
|
63
63
|
| `openapi` | a URL or file; turns one generic tool into typed ones, one per operation |
|
|
64
|
-
| `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
|
|
64
|
+
| `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 project, so a vendor renaming an operation cannot empty it |
|
|
65
65
|
|
|
66
66
|
**The body is the manual.** Everything under a `tool.md`'s frontmatter goes
|
|
67
67
|
to the model with the tool, after `description:` — how to call it, what it
|
|
68
68
|
refuses, what its output means, examples of a call (up to 6,000 characters;
|
|
69
69
|
a longer body is cut there and says so). A single-file tool's fenced program
|
|
70
70
|
is code, not guidance, and stays out. This holds for script and HTTP tools
|
|
71
|
-
alike,
|
|
71
|
+
alike, project or library.
|
|
72
72
|
|
|
73
73
|
The model never sees a credential — the host substitutes it as the request
|
|
74
74
|
goes out. The method allowlist protects against the agent; the key's own scopes
|
|
@@ -167,7 +167,7 @@ holds its value — bind a key you would not hand the agent.
|
|
|
167
167
|
|
|
168
168
|
Resolution is **nearest wins**: an agent's own beats its project's, which beats
|
|
169
169
|
the account library. So a shared integration is defined once for the whole
|
|
170
|
-
account and rotating its credential is a single edit — and a
|
|
170
|
+
account and rotating its credential is a single edit — and a project can
|
|
171
171
|
still shadow it by defining the same name locally.
|
|
172
172
|
|
|
173
173
|
The Library page lists, for every shared file, which agents granted it and
|
|
@@ -183,7 +183,7 @@ gallery is a shelf beneath your account library, laid down on the box at
|
|
|
183
183
|
boot, so a platform upgrade reaches every account at once.
|
|
184
184
|
|
|
185
185
|
**Installing** is still there, and it means something narrower now: it
|
|
186
|
-
copies the tool or skill into your account library (or one
|
|
186
|
+
copies the tool or skill into your account library (or one project), and
|
|
187
187
|
your copy shadows the platform's by name. A copy you have **not edited**
|
|
188
188
|
follows the gallery: every platform deploy brings it to the current
|
|
189
189
|
version. A copy you **have** edited is yours and is never changed under
|
|
@@ -199,7 +199,7 @@ not one of the skills an agent with no `skills:` list inherits.
|
|
|
199
199
|
`foldrun run` and `foldrun eval` fetch the gallery before they start and keep
|
|
200
200
|
a copy under `~/.foldrun/gallery/<host>/`, so an agent granting `web`
|
|
201
201
|
runs locally exactly as it does on a deploy, with the same lookup order: the
|
|
202
|
-
|
|
202
|
+
project's copy, then the account library's, then the shelf. Offline, the
|
|
203
203
|
last copy is used and the run says so. `foldrun gallery` lists the shelf and
|
|
204
204
|
marks which entries your account keeps its own copy of, `foldrun gallery pull`
|
|
205
205
|
refreshes the copy by hand, and `foldrun gallery upgrade <name>` is the
|
|
@@ -465,7 +465,7 @@ None of the actions hardcodes a country. `web action=search` asks the engine in
|
|
|
465
465
|
agent's `language:` — and for its region when the tag carries one, as
|
|
466
466
|
`en-AU` or `pt-BR` — `web action=browse` reports it as the page's locale, and
|
|
467
467
|
`web action=fetch` sends it as `Accept-Language`. The value cascades from the agent
|
|
468
|
-
to its
|
|
468
|
+
to its project to the account, and is English when nobody set it; see
|
|
469
469
|
[`language:`](agents#language--the-language-this-agent-works-in). A
|
|
470
470
|
country the tag does not carry comes from
|
|
471
471
|
[`region:`](agents#region--the-country-this-agent-works-for) — `language: en`
|
|
@@ -856,7 +856,7 @@ web:
|
|
|
856
856
|
|
|
857
857
|
A setting the vendor has no option for fails `foldrun check`, naming the
|
|
858
858
|
vendors that do — the same rule as an action. `keep` stores the vendor's
|
|
859
|
-
context or profile id in the
|
|
859
|
+
context or profile id in the project's `state/web-browse/`, so the next run
|
|
860
860
|
signs in as the last one left off; it uses the vendor's own browser context
|
|
861
861
|
as it stands, so `user_agent`, `device`, `locale`, `timezone` and
|
|
862
862
|
`identities` beside it are refused. ZenRows' browser refuses a changed user
|
|
@@ -922,11 +922,11 @@ exactly as it always did.
|
|
|
922
922
|
| `delta` | with `mode=aria`: `true` returns only what changed since the last snapshot of the same page in this session, or one line saying nothing did |
|
|
923
923
|
| `annotate` | with `mode=screenshot`: `true` draws a box and its number on every element that can be acted on, and lists them — the numbers are `"@e4"` |
|
|
924
924
|
| `visual` | with `mode=diff`: `true` compares pixels, not words — what share changed, where, and `outputs/diff.png` with the changes in red |
|
|
925
|
-
| `init` |
|
|
925
|
+
| `init` | project paths of scripts run in every page before its own |
|
|
926
926
|
| `allowed_domains` | the only domains the browser may reach — pages, scripts, fetches, sockets. From the block, a call may narrow it, never widen it |
|
|
927
927
|
| `boundaries` | `true` wraps the page's words in markers with a fresh nonce |
|
|
928
928
|
| `webgpu` | `true` gives the page WebGPU, on a software GPU where there is none |
|
|
929
|
-
| `extensions` |
|
|
929
|
+
| `extensions` | project paths of unpacked Chrome extensions; the browser then runs in the step, in Chromium |
|
|
930
930
|
| `ignore_https_errors` | `true` opens a page whose certificate does not check out |
|
|
931
931
|
| `cpu_profile` | a `.cpuprofile` path — where the page's JavaScript spent its time, for DevTools |
|
|
932
932
|
| `state_key` | the NAME of a secret whose value encrypts the `state` login at rest (AES-256-GCM) |
|
|
@@ -1233,7 +1233,7 @@ page it opened the session that belongs to one site. A `cookies=` on the call
|
|
|
1233
1233
|
is the caller's own decision and is used as given.
|
|
1234
1234
|
|
|
1235
1235
|
`web: {browse: browserbase}` still means exactly what it did, so no file needs
|
|
1236
|
-
changing. A block may sit on the agent, the
|
|
1236
|
+
changing. A block may sit on the agent, the project's `AGENTS.md` or the
|
|
1237
1237
|
account's; the nearest one wins and replaces the others whole. **A call
|
|
1238
1238
|
argument beats the file** — `browser=`, `user_agent=`, `device=`, `locale=`,
|
|
1239
1239
|
`timezone=` — so the block is a default. The exceptions are what the agent
|
|
@@ -1347,14 +1347,14 @@ follows it.
|
|
|
1347
1347
|
the page cannot know, so words a site wrote to look like instructions stay
|
|
1348
1348
|
labelled as the site's. It is a label, not a wall.
|
|
1349
1349
|
|
|
1350
|
-
`init:` runs
|
|
1350
|
+
`init:` runs project scripts in every page before the page's own — a
|
|
1351
1351
|
stub for an analytics call, a polyfill. `extensions:` loads unpacked Chrome
|
|
1352
|
-
extensions from the
|
|
1352
|
+
extensions from the project; the browser then runs in the step rather than
|
|
1353
1353
|
the account's pod, in Chromium (branded Chrome no longer loads them).
|
|
1354
1354
|
`webgpu: true` and `ignore_https_errors: true` do what they say. `state_key:`
|
|
1355
1355
|
names a secret whose value encrypts the `state=` login at rest with
|
|
1356
1356
|
AES-256-GCM, so a session cookie in `state/` is not a login anyone who can
|
|
1357
|
-
read the
|
|
1357
|
+
read the project can use; declare the secret under `secrets:`. An
|
|
1358
1358
|
encrypted state without its key is refused rather than started signed out.
|
|
1359
1359
|
|
|
1360
1360
|
**A sign-in the model never sees.** A `login` step takes a credential
|
|
@@ -1498,7 +1498,7 @@ names it, in this run or a run next month. It is the agent's own login,
|
|
|
1498
1498
|
made with `actions` from credentials it can see — or a login a cookie secret
|
|
1499
1499
|
seeded, when `state_key` encrypts it (below). Without a key `state` refuses
|
|
1500
1500
|
`cookies=` and a session they seeded, and it always refuses `storage=`,
|
|
1501
|
-
because `state/` is a
|
|
1501
|
+
because `state/` is a project file every later step can read, and a vault
|
|
1502
1502
|
secret written there in the clear would stop being one. `mode=diff` keeps its
|
|
1503
1503
|
baselines in the same place, under `state/browser/diff/`, for the same
|
|
1504
1504
|
reason: they must outlive the run.
|
|
@@ -1646,7 +1646,7 @@ included. Reads: `Read`/`Glob`/`Grep`, `web` search, fetch, crawl, map,
|
|
|
1646
1646
|
extract and answer, a browse that only looks (navigates, scrolls, waits,
|
|
1647
1647
|
screenshots, extracts, hovers), a GET or HEAD to an API, the `search`,
|
|
1648
1648
|
`history` and `desks` tools and a consult. Writes: any file written or
|
|
1649
|
-
edited (`state/`, `memory/`, the
|
|
1649
|
+
edited (`state/`, `memory/`, the project), Bash, every script tool, an
|
|
1650
1650
|
API call that is not a GET, a web action a paid provider answers, `web
|
|
1651
1651
|
action=monitor` (it keeps state), a browse that clicks, fills, types,
|
|
1652
1652
|
presses, selects, uploads, signs in, accepts a dialog, solves a captcha or
|
|
@@ -1872,7 +1872,7 @@ Values are whole numbers, 1 or more; to withhold a tool, leave it out of
|
|
|
1872
1872
|
sub-agents count toward the step that delegated: their calls pass the same
|
|
1873
1873
|
check.
|
|
1874
1874
|
- **A refused call counts toward nothing**, and neither does one another
|
|
1875
|
-
check refused (a path outside the
|
|
1875
|
+
check refused (a path outside the project, a tool not granted).
|
|
1876
1876
|
- **Every step has two by default: `calls: 1000` and `repeat: 25`** (since
|
|
1877
1877
|
13 Nov 2026). A model that keeps calling — the same call, or anything at
|
|
1878
1878
|
all — is refused, not paid for until the step's `timeout:`. Set either key
|
|
@@ -1882,7 +1882,7 @@ Values are whole numbers, 1 or more; to withhold a tool, leave it out of
|
|
|
1882
1882
|
the model kept calling — it is stuck*. A model told "no" that often is not
|
|
1883
1883
|
going to stop by itself.
|
|
1884
1884
|
- **Nearest wins, per key.** The platform's defaults, then the account's
|
|
1885
|
-
`AGENTS.md`, then the
|
|
1885
|
+
`AGENTS.md`, then the project's, then the agent's own, then a flow step's
|
|
1886
1886
|
`limits: {web.search: 10}` option. A key set nearer replaces that key;
|
|
1887
1887
|
the others stand.
|
|
1888
1888
|
- **On the trace.** The step lists its limits (the defaults included) when it starts, each refusal
|
|
@@ -1927,7 +1927,7 @@ Only names and descriptions sit in context; the agent reads the full file when
|
|
|
1927
1927
|
a task matches. So an agent can carry many skills for a few tokens each — which
|
|
1928
1928
|
is the reason to move a procedure out of `agent.md` in the first place.
|
|
1929
1929
|
|
|
1930
|
-
Skills are discovered in the agent's own `skills/`, the
|
|
1930
|
+
Skills are discovered in the agent's own `skills/`, the project's, the
|
|
1931
1931
|
account library, and the cross-client `.agents/skills/` convention that other
|
|
1932
1932
|
tools read and write. A skill written here drops into them, and one they
|
|
1933
1933
|
install is visible here. The platform's [gallery](#the-gallery--platform-maintained-tools-and-skills)
|
|
@@ -1946,8 +1946,8 @@ credential** — the vault stores the refresh recipe (`token_url`, `client_id`,
|
|
|
1946
1946
|
`client_secret`, `refresh_token`) and the host exchanges it for a live access
|
|
1947
1947
|
token immediately before every use, cached until near expiry.
|
|
1948
1948
|
|
|
1949
|
-
Resolution is nearest-wins across the
|
|
1950
|
-
log says which store each one came from — a
|
|
1949
|
+
Resolution is nearest-wins across the project and account vaults, and the run
|
|
1950
|
+
log says which store each one came from — a project quietly falling back to
|
|
1951
1951
|
an account credential is the kind of thing you want to see rather than infer.
|
|
1952
1952
|
|
|
1953
1953
|
### Connecting a provider
|
package/docs/troubleshooting.md
CHANGED
|
@@ -61,9 +61,9 @@ A cap over time, reached. New runs refuse until the window turns — tomorrow,
|
|
|
61
61
|
next week, the new month — in the account's own `timezone:`. Raise it in
|
|
62
62
|
Settings or in the file, or remove the line.
|
|
63
63
|
|
|
64
|
-
## "was denied: … is outside this
|
|
64
|
+
## "was denied: … is outside this project"
|
|
65
65
|
|
|
66
|
-
The agent reached for a path outside its
|
|
66
|
+
The agent reached for a path outside its project — `/tmp/something`, an
|
|
67
67
|
absolute path, a checkout a tool made — and was refused. The message names
|
|
68
68
|
the path it probably meant. It costs a turn, nothing more; if one step
|
|
69
69
|
collects many, name the exact path in its prompt (`workspace/storage/x.md`).
|
|
@@ -82,9 +82,9 @@ until it is there.
|
|
|
82
82
|
|
|
83
83
|
## The run is parked and nobody knows
|
|
84
84
|
|
|
85
|
-
Check the account's `notify:` — a
|
|
85
|
+
Check the account's `notify:` — a project that declared its own block
|
|
86
86
|
replaced the account's whole, and may have dropped `awaiting-approval`. The
|
|
87
|
-
dashboard banner shows every parked run across
|
|
87
|
+
dashboard banner shows every parked run across projects regardless.
|
|
88
88
|
|
|
89
89
|
## It ran on the wrong model
|
|
90
90
|
|
package/docs/workspaces.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Projects
|
|
2
2
|
|
|
3
|
-
A
|
|
3
|
+
A project is a folder, and the folder is the unit of everything: it is what
|
|
4
4
|
you edit, deploy, permission, budget and back up. An account holds several —
|
|
5
5
|
one per job, in practice — and they share nothing unless it is put in the
|
|
6
6
|
account's library on purpose.
|
|
@@ -31,8 +31,8 @@ Every one of those is optional except `AGENTS.md` and at least one agent.
|
|
|
31
31
|
|
|
32
32
|
## The account around it
|
|
33
33
|
|
|
34
|
-
On the platform a
|
|
35
|
-
beside the account's own `AGENTS.md` and the library every
|
|
34
|
+
On the platform a project never stands alone: it lives under an account,
|
|
35
|
+
beside the account's own `AGENTS.md` and the library every project there
|
|
36
36
|
shares.
|
|
37
37
|
|
|
38
38
|
```
|
|
@@ -45,35 +45,35 @@ my-account/
|
|
|
45
45
|
```
|
|
46
46
|
|
|
47
47
|
`foldrun init` makes exactly that on a laptop, and `foldrun new <name>` adds
|
|
48
|
-
another
|
|
48
|
+
another project to it, so the folder you edit is the folder that runs. See
|
|
49
49
|
[the CLI reference](cli#the-shape-of-a-folder) for the commands that act on the
|
|
50
50
|
whole account — `check`, `deploy`, `pull`, `status`, `workspaces` — and for the
|
|
51
51
|
one scope that has no API: the account's own `AGENTS.md` is not pushed or
|
|
52
52
|
pulled, only edited in Settings.
|
|
53
53
|
|
|
54
|
-
A single folder with `agents/` and `flows/` at its root is still a
|
|
54
|
+
A single folder with `agents/` and `flows/` at its root is still a project
|
|
55
55
|
and still works everywhere; `foldrun init --flat` makes one.
|
|
56
56
|
|
|
57
|
-
## A new
|
|
57
|
+
## A new project starts blank
|
|
58
58
|
|
|
59
|
-
**Create
|
|
60
|
-
`template: true`, and `foldrun new <name>` all make a
|
|
59
|
+
**Create project** on the dashboard, `POST /api/workspaces` with
|
|
60
|
+
`template: true`, and `foldrun new <name>` all make a project with nothing in
|
|
61
61
|
it to delete: an `AGENTS.md` (plus, on a laptop, the `.gitignore` that keeps
|
|
62
62
|
its secret key out of git and a `CLAUDE.md` for your coding tool). No example
|
|
63
63
|
agents, no flow. `foldrun new <name> --starter` and `starter: true` still make
|
|
64
64
|
the example researcher, writer and `publish` flow; `foldrun init` makes it for
|
|
65
|
-
an account's first
|
|
65
|
+
an account's first project, which the getting-started guide runs.
|
|
66
66
|
|
|
67
|
-
A
|
|
68
|
-
warning. A flow that names an agent the
|
|
67
|
+
A project with no agents yet deploys; `check` and the deploy say so as a
|
|
68
|
+
warning. A flow that names an agent the project lacks is still an error.
|
|
69
69
|
|
|
70
70
|
### Importing an agent you already have
|
|
71
71
|
|
|
72
|
-
The agents worth having in a new
|
|
72
|
+
The agents worth having in a new project are often ones already written in
|
|
73
73
|
another: **Import agent** on the Agents page (and in the empty state of a blank
|
|
74
|
-
|
|
74
|
+
project) lists every agent in the account's other projects you can read,
|
|
75
75
|
and copies the one you pick. From a terminal, `foldrun agent import
|
|
76
|
-
<workspace>/<agent>` does it between
|
|
76
|
+
<workspace>/<agent>` does it between projects of an account folder, or on the
|
|
77
77
|
platform with `--to <workspace>`; the route is `POST
|
|
78
78
|
/api/workspaces/<ws>/agents/import` with `{ from, agent, as? }`.
|
|
79
79
|
|
|
@@ -81,7 +81,7 @@ What is copied is what the agent **is**: `agent.md` and its own `skills/`,
|
|
|
81
81
|
`scripts/` and `knowledge/`. What it **accumulated** stays where it was learned:
|
|
82
82
|
`memory/`, `outputs/`, `state/` and session files. A name already taken is
|
|
83
83
|
refused — import it under another name with `--as` / `as`, which rewrites its
|
|
84
|
-
`name:`. The import then says what the copy uses that this
|
|
84
|
+
`name:`. The import then says what the copy uses that this project lacks —
|
|
85
85
|
tools, skills, scripts, secrets — without refusing: set the secret, import the
|
|
86
86
|
tool, and it runs. The copy is independent; editing one does not change the
|
|
87
87
|
other.
|
|
@@ -91,14 +91,14 @@ other.
|
|
|
91
91
|
Agent import works inside one account. To move a desk to another account or
|
|
92
92
|
installation — or to hand someone a flow — export it as a `.zip`:
|
|
93
93
|
|
|
94
|
-
- **A workspace:** Settings → **Export and import** → **Export
|
|
94
|
+
- **A workspace:** Settings → **Export and import** → **Export project**.
|
|
95
95
|
- **A flow:** **Export** on its card on the Flows page. The package holds the
|
|
96
96
|
flow, every flow it runs as a step, every agent those steps name (with
|
|
97
97
|
`on-fail:`, `delegate:` and the colleagues those agents consult or delegate to),
|
|
98
|
-
and the
|
|
98
|
+
and the project tools, skills and scripts they grant — including the
|
|
99
99
|
script a single-file tool's `run:` names.
|
|
100
100
|
- **An agent:** **Export** on its page: its folder (what agent import copies)
|
|
101
|
-
and the
|
|
101
|
+
and the project tools, skills and scripts it grants. Colleagues it consults
|
|
102
102
|
are named, not carried.
|
|
103
103
|
|
|
104
104
|
A package is authored source only: `AGENTS.md` and the `agents/`, `flows/`,
|
|
@@ -106,13 +106,13 @@ A package is authored source only: `AGENTS.md` and the `agents/`, `flows/`,
|
|
|
106
106
|
`memory/`, `state/`, `outputs/`, storage, runs, `.env` files or a secret's
|
|
107
107
|
value. The secrets it uses travel by **name**, so the importer knows what to
|
|
108
108
|
set. An agent with no `skills:` line gets every skill in scope at run time, so
|
|
109
|
-
its package carries every
|
|
109
|
+
its package carries every project skill.
|
|
110
110
|
|
|
111
111
|
Anything else in a zip — memory, state, a `.gitignore` or `CLAUDE.md` beside a
|
|
112
112
|
folder you zipped yourself — is **not imported**, and the preview lists it.
|
|
113
113
|
|
|
114
114
|
To import, use **Import .zip** on the Flows or Agents page or in Settings, or
|
|
115
|
-
**Add new → Import
|
|
115
|
+
**Add new → Import project** on the home page. You pick the file and first
|
|
116
116
|
see a preview, with nothing written yet:
|
|
117
117
|
|
|
118
118
|
- what it adds;
|
|
@@ -124,8 +124,8 @@ see a preview, with nothing written yet:
|
|
|
124
124
|
An import never deletes anything, and it is all or nothing: a file it cannot
|
|
125
125
|
write (a folder already in its place, a link on the way) refuses the whole
|
|
126
126
|
import before anything is written. It lands as one revision, so History can
|
|
127
|
-
restore what it replaced. A
|
|
128
|
-
that
|
|
127
|
+
restore what it replaced. A project package imported under a new name makes
|
|
128
|
+
that project. A `.zip` of a project folder made by hand (a Mac's
|
|
129
129
|
Compress included) imports the same way.
|
|
130
130
|
|
|
131
131
|
From a terminal: `foldrun export [workspace] [--flow <name> | --agent <name>]`
|
|
@@ -135,11 +135,11 @@ The routes are `GET /api/workspaces/<ws>/export` and
|
|
|
135
135
|
|
|
136
136
|
## `AGENTS.md` — context and defaults
|
|
137
137
|
|
|
138
|
-
The body is prose every agent in the
|
|
138
|
+
The body is prose every agent in the project sees before its own prompt.
|
|
139
139
|
Put the things that are true of the whole desk there: the business, the
|
|
140
140
|
standing rules, what the reader is like.
|
|
141
141
|
|
|
142
|
-
The frontmatter is the
|
|
142
|
+
The frontmatter is the project's defaults:
|
|
143
143
|
|
|
144
144
|
```yaml
|
|
145
145
|
---
|
|
@@ -155,12 +155,12 @@ provider: # see Providers
|
|
|
155
155
|
---
|
|
156
156
|
```
|
|
157
157
|
|
|
158
|
-
`owner:` names the person accountable for the
|
|
158
|
+
`owner:` names the person accountable for the project's agents and flows.
|
|
159
159
|
Each agent and flow may name its own; one that does not takes the
|
|
160
|
-
|
|
160
|
+
project's, and a project that does not takes the account's.
|
|
161
161
|
|
|
162
162
|
`telemetry:` sends each finished run to an OpenTelemetry collector as one
|
|
163
|
-
trace; a
|
|
163
|
+
trace; a project's block replaces the account's whole. See
|
|
164
164
|
[Runs](runs#sending-the-trace-to-your-own-tracing).
|
|
165
165
|
|
|
166
166
|
The frontmatter may also group these defaults by the job they do —
|
|
@@ -170,7 +170,7 @@ same keys at the top. See [The four jobs](four-jobs) for which key goes where.
|
|
|
170
170
|
|
|
171
171
|
`network_enforce: true` refuses a site off a step's [`network:`](network)
|
|
172
172
|
list instead of only naming it in the trace. The account's `true` holds for
|
|
173
|
-
every
|
|
173
|
+
every project; a project can add it for itself but not drop the
|
|
174
174
|
account's. See [Network](network#report-only-then-refuse).
|
|
175
175
|
|
|
176
176
|
`capture:` says what runs record of each tool call: `full` (the default —
|
|
@@ -180,18 +180,18 @@ only). See [Runs](runs#what-a-run-records).
|
|
|
180
180
|
There is an `AGENTS.md` one level up too — the account's — and the two
|
|
181
181
|
compose in a way worth learning once:
|
|
182
182
|
|
|
183
|
-
- **Prose accumulates.** The account's body is added to every
|
|
183
|
+
- **Prose accumulates.** The account's body is added to every project's,
|
|
184
184
|
so a rule written at the account cannot be dropped below it.
|
|
185
|
-
- **A frontmatter key replaces whole.** A
|
|
185
|
+
- **A frontmatter key replaces whole.** A project that sets `notify:`
|
|
186
186
|
replaces the account's `notify:` entirely — it does not merge into it. To
|
|
187
187
|
inherit a key, say nothing about it.
|
|
188
188
|
|
|
189
|
-
The second rule is the one that surprises people: a
|
|
189
|
+
The second rule is the one that surprises people: a project that declares
|
|
190
190
|
its own `notify:` block silently stops receiving the account's default.
|
|
191
191
|
|
|
192
192
|
### The clock, all the way down
|
|
193
193
|
|
|
194
|
-
`timezone:` is the one default with levels below the
|
|
194
|
+
`timezone:` is the one default with levels below the project as well as
|
|
195
195
|
above it, because a flow's schedule and an agent's own calendar are both real
|
|
196
196
|
things to set. Nearest wins, and every level inherits the one above it unless
|
|
197
197
|
it says otherwise:
|
|
@@ -214,21 +214,21 @@ to the next level with one line in the trace rather than failing the step.
|
|
|
214
214
|
## Pausing runs — the kill switch
|
|
215
215
|
|
|
216
216
|
When something is going wrong — an agent posting what it should not, a
|
|
217
|
-
loop spending money — pause the
|
|
217
|
+
loop spending money — pause the project, or the whole account, from its
|
|
218
218
|
Settings → Policies → Pause runs, `foldrun workspace pause` / `foldrun account pause`, or
|
|
219
219
|
the API (`POST /api/workspaces/<ws>/pause`, `POST /api/account/pause`).
|
|
220
220
|
|
|
221
221
|
While paused, nothing new starts: a schedule's fire, a webhook delivery, a
|
|
222
222
|
chained flow, a person's Run and a rerun are all refused, and the
|
|
223
|
-
|
|
223
|
+
project's Triggers page logs each refused fire as *paused by a
|
|
224
224
|
person*. A refused fire is not run later. A run that was queued before
|
|
225
225
|
the pause and has not begun waits until the resume. Add `--stop` (or tick
|
|
226
226
|
*Also stop the runs going now*) to stop the runs already going — and the
|
|
227
227
|
queued and parked ones — as well; without it, a run already under way
|
|
228
228
|
finishes.
|
|
229
229
|
|
|
230
|
-
The account's pause holds every
|
|
231
|
-
lifts it; a
|
|
230
|
+
The account's pause holds every project, and only the account's resume
|
|
231
|
+
lifts it; a project paused on its own stays paused when the account
|
|
232
232
|
resumes. Who paused and why is on the page, on every dashboard page while
|
|
233
233
|
the account is paused, and in the audit log (`workspace.paused`,
|
|
234
234
|
`account.resumed`, …). A scheduled fire inside a pause is not reported as a
|
|
@@ -238,10 +238,10 @@ deploy never lifts it.
|
|
|
238
238
|
## The account library
|
|
239
239
|
|
|
240
240
|
`<account>/library/` holds tools, skills, knowledge and memory shared by every
|
|
241
|
-
|
|
242
|
-
|
|
241
|
+
project. Resolution is nearest-wins: an agent's own file beats the
|
|
242
|
+
project's, which beats the library's. So a shared integration — the tool
|
|
243
243
|
that clones your website, the skill that explains how — is defined once, and
|
|
244
|
-
a
|
|
244
|
+
a project that needs a different version shadows it by defining the same
|
|
245
245
|
name locally.
|
|
246
246
|
|
|
247
247
|
From inside a run the library is read-only, reached as `account/…`
|
|
@@ -272,17 +272,17 @@ memory an agent wrote that your deploy does not mention. Those belong to the
|
|
|
272
272
|
platform, not to your source, and a deploy that reverted what an agent learned would
|
|
273
273
|
make every run a little dumber.
|
|
274
274
|
|
|
275
|
-
The agent engine's own files are not
|
|
275
|
+
The agent engine's own files are not project content either. Each step
|
|
276
276
|
runs in a sandbox on the Claude Agent SDK — the engine, whichever model
|
|
277
277
|
answers — and the engine writes its settings and session transcripts in the
|
|
278
278
|
agent's folder there (`agents/<name>/.claude.json`, `agents/<name>/.claude/`).
|
|
279
279
|
They stay in the sandbox: never copied back, never copied in. (Your own
|
|
280
|
-
`.claude/agents/*.md` at the
|
|
280
|
+
`.claude/agents/*.md` at the project root is different — a Claude Code
|
|
281
281
|
subagent you wrote, deployed as an agent.)
|
|
282
282
|
|
|
283
283
|
A deploy while a run is in flight is refused, saying which runs hold it; a
|
|
284
284
|
run parked at an approval gate counts as in flight. See [Deploying](deploying).
|
|
285
285
|
|
|
286
|
-
Trying a change to a live desk without touching it is a second
|
|
286
|
+
Trying a change to a live desk without touching it is a second project —
|
|
287
287
|
`foldrun deploy --to <workspace>-try`. Branch previews come back with the
|
|
288
288
|
GitHub and GitLab app.
|