@foldrun/core 0.4.0 → 0.6.0

package/dist/src/secrets.js

@@ -22,6 +22,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { dataRoot } from "./paths.js";
 import { platform } from "./platform.js";
+import { fetchUntrusted } from "./untrusted-fetch.js";
 /**
  * GCM's auth tag, pinned to its full 16 bytes at every cipher call. Without
  * `authTagLength`, Node accepts whatever length `setAuthTag` is handed — 4, 8,
@@ -75,20 +76,83 @@ function secretsFile(tenant, workspace) {
     return path.join(base, "secrets.json");
 }
 function read(tenant, workspace) {
-    const f = secretsFile(tenant, workspace);
-    if (!fs.existsSync(f))
+    return readFile(secretsFile(tenant, workspace));
+}
+// ------------------------------------------------------------ safe writes
+//
+// A vault file is read, changed and written back. It was written in place,
+// with no lock: two saves at once kept one; a crash mid-write left half a
+// file, which is an account that cannot authenticate anything; and the boot
+// re-wrap ran in every pod at once through ONE shared temp name, so two pods
+// could interleave into it and rename a corrupt file into place.
+//
+// Now every change goes through mutateVaultFile: an exclusive lock file
+// (O_EXCL, which NFS 4.1 and EFS honour, so it holds across pods), the read
+// and the change under it, a temp file unique to this writer, and a rename —
+// atomic on the same filesystem, so a reader sees the old file or the new
+// one, never half. A lock older than LOCK_STALE_MS is a crashed holder.
+const LOCK_STALE_MS = 30_000;
+const LOCK_WAIT_MS = 10_000;
+const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+function readFile(file) {
+    if (!fs.existsSync(file))
         return {};
     try {
-        return JSON.parse(fs.readFileSync(f, "utf8"));
+        return JSON.parse(fs.readFileSync(file, "utf8"));
     }
     catch {
         return {};
     }
 }
-function write(tenant, workspace, data) {
-    const f = secretsFile(tenant, workspace);
-    fs.mkdirSync(path.dirname(f), { recursive: true });
-    fs.writeFileSync(f, JSON.stringify(data, null, 2), { mode: 0o600 });
+function lockVault(file) {
+    const lock = `${file}.lock`;
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    for (;;) {
+        try {
+            const fd = fs.openSync(lock, "wx", 0o600);
+            fs.writeSync(fd, `${process.pid}@${new Date().toISOString()}`);
+            fs.closeSync(fd);
+            return () => fs.rmSync(lock, { force: true });
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            try {
+                if (Date.now() - fs.statSync(lock).mtimeMs > LOCK_STALE_MS) {
+                    fs.rmSync(lock, { force: true }); // a holder that died; take it over
+                    continue;
+                }
+            }
+            catch {
+                continue; // released between the open and the stat
+            }
+            if (Date.now() > deadline)
+                throw new Error("the vault is busy — another change is being saved; try again");
+            sleep(25);
+        }
+    }
+}
+/**
+ * Change one vault file safely: `change` gets what is stored now and returns
+ * the new contents, or null to leave the file untouched. Returns what is
+ * stored after.
+ */
+export function mutateVaultFile(file, change) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const release = lockVault(file);
+    try {
+        const current = readFile(file);
+        const next = change(structuredClone(current));
+        if (next === null)
+            return current;
+        const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(next, null, 2), { mode: 0o600 });
+        fs.renameSync(tmp, file);
+        return next;
+    }
+    finally {
+        release();
+    }
 }
 export const SECRET_NAME = /^[A-Z][A-Z0-9_]{1,63}$/;
 export function setSecret(tenant, name, value, workspace, kind) {
@@ -98,13 +162,14 @@ export function setSecret(tenant, name, value, workspace, kind) {
     if (value.length > 8192)
         throw new Error("secret too long");
     const sealed = encryptValue(tenant, value);
-    const all = read(tenant, workspace);
-    all[name] = {
-        ...sealed,
-        updatedAt: new Date().toISOString(),
-        ...(kind ? { kind } : {}),
-    };
-    write(tenant, workspace, all);
+    mutateVaultFile(secretsFile(tenant, workspace), (all) => {
+        all[name] = {
+            ...sealed,
+            updatedAt: new Date().toISOString(),
+            ...(kind ? { kind } : {}),
+        };
+        return all;
+    });
 }
 /**
  * Which key writes this account's records.
@@ -190,9 +255,12 @@ export function getSecret(tenant, name, workspace) {
     return shared === null ? null : { value: shared, scope: "account" };
 }
 export function deleteSecret(tenant, name, workspace) {
-    const all = read(tenant, workspace);
-    delete all[name];
-    write(tenant, workspace, all);
+    mutateVaultFile(secretsFile(tenant, workspace), (all) => {
+        if (!(name in all))
+            return null;
+        delete all[name];
+        return all;
+    });
 }
 // Metadata only — never values. Without a workspace this lists the account
 // store; with one it lists what that workspace actually resolves, marking
@@ -288,47 +356,47 @@ export function rotateMasterKey(tenant, from, to) {
     const rewritten = [];
     const unreadable = [];
     for (const { file } of secretFiles(tenant)) {
-        const all = JSON.parse(fs.readFileSync(file, "utf8"));
-        const next = {};
         let count = 0;
-        for (const [name, rec] of Object.entries(all)) {
-            // A record under the ACCOUNT's key is not under the install key, so
-            // rotating the install key must not touch it — re-encrypting it here
-            // with a key it was never sealed with is how a rotation would destroy a
-            // vault it was meant to protect. Rotating the install key now re-wraps
-            // the account keys instead, which is a handful of small values rather
-            // than every secret on the box.
-            if (rec.k === "tenant") {
-                next[name] = rec;
-                continue;
+        mutateVaultFile(file, (all) => {
+            const next = {};
+            for (const [name, rec] of Object.entries(all)) {
+                // A record under the ACCOUNT's key is not under the install key, so
+                // rotating the install key must not touch it — re-encrypting it here
+                // with a key it was never sealed with is how a rotation would destroy a
+                // vault it was meant to protect. Rotating the install key now re-wraps
+                // the account keys instead, which is a handful of small values rather
+                // than every secret on the box.
+                if (rec.k === "tenant") {
+                    next[name] = rec;
+                    continue;
+                }
+                let plain;
+                try {
+                    const d = crypto.createDecipheriv("aes-256-gcm", oldKey, Buffer.from(rec.iv, "base64"), GCM);
+                    d.setAuthTag(Buffer.from(rec.tag, "base64"));
+                    plain = Buffer.concat([d.update(Buffer.from(rec.data, "base64")), d.final()]).toString("utf8");
+                }
+                catch {
+                    unreadable.push(name);
+                    next[name] = rec; // untouched
+                    continue;
+                }
+                const iv = crypto.randomBytes(12);
+                const c = crypto.createCipheriv("aes-256-gcm", newKey, iv, GCM);
+                const enc = Buffer.concat([c.update(plain, "utf8"), c.final()]);
+                next[name] = {
+                    iv: iv.toString("base64"),
+                    tag: c.getAuthTag().toString("base64"),
+                    data: enc.toString("base64"),
+                    updatedAt: rec.updatedAt, // rotation is not an edit
+                    // Kept: without it an oauth2 secret stops being refreshed after a
+                    // rotation, and a file/ssh/api secret stops being materialised.
+                    ...(rec.kind ? { kind: rec.kind } : {}),
+                };
+                count++;
             }
-            let plain;
-            try {
-                const d = crypto.createDecipheriv("aes-256-gcm", oldKey, Buffer.from(rec.iv, "base64"), GCM);
-                d.setAuthTag(Buffer.from(rec.tag, "base64"));
-                plain = Buffer.concat([d.update(Buffer.from(rec.data, "base64")), d.final()]).toString("utf8");
-            }
-            catch {
-                unreadable.push(name);
-                next[name] = rec; // untouched
-                continue;
-            }
-            const iv = crypto.randomBytes(12);
-            const c = crypto.createCipheriv("aes-256-gcm", newKey, iv, GCM);
-            const enc = Buffer.concat([c.update(plain, "utf8"), c.final()]);
-            next[name] = {
-                iv: iv.toString("base64"),
-                tag: c.getAuthTag().toString("base64"),
-                data: enc.toString("base64"),
-                updatedAt: rec.updatedAt, // rotation is not an edit
-            };
-            count++;
-        }
-        // Write via a temp file in the same directory: a half-written secrets.json
-        // is an account that cannot authenticate anything.
-        const tmp = `${file}.rotating`;
-        fs.writeFileSync(tmp, JSON.stringify(next, null, 2), { mode: 0o600 });
-        fs.renameSync(tmp, file);
+            return next;
+        });
         rewritten.push({ file, secrets: count });
     }
     return { rewritten, unreadable };
@@ -372,12 +440,12 @@ async function exchange(config, cacheKey) {
             client_secret: config.client_secret,
             ...(config.extra ?? {}),
         });
-        const res = await fetch(config.token_url, {
+        const res = await fetchUntrusted(config.token_url, {
             method: "POST",
             headers: { "content-type": "application/x-www-form-urlencoded" },
             body: body.toString(),
             signal: AbortSignal.timeout(15_000),
-        });
+        }, { sameOrigin: true });
         const payload = (await res.json().catch(() => ({})));
         if (!res.ok || !payload.access_token) {
             throw new Error(`token refresh failed (${res.status}): ${payload.error_description ?? payload.error ?? "no access_token in the reply"}`);
@@ -499,7 +567,7 @@ async function exchangeServiceAccount(config, cacheKey) {
         signer.update(`${header}.${claim}`);
         const signature = base64url(signer.sign(config.private_key));
         const jwt = `${header}.${claim}.${signature}`;
-        const res = await fetch(config.token_url, {
+        const res = await fetchUntrusted(config.token_url, {
             method: "POST",
             headers: { "content-type": "application/x-www-form-urlencoded" },
             body: new URLSearchParams({
@@ -507,7 +575,7 @@ async function exchangeServiceAccount(config, cacheKey) {
                 assertion: jwt,
             }).toString(),
             signal: AbortSignal.timeout(15_000),
-        });
+        }, { sameOrigin: true });
         const payload = (await res.json().catch(() => ({})));
         if (!res.ok || !payload.access_token) {
             throw new Error(`service account exchange failed (${res.status}): ${payload.error_description ?? payload.error ?? "no access_token"}`);
@@ -626,33 +694,34 @@ export function rewrapTenantSecrets(tenant) {
     let moved = 0;
     const unreadable = [];
     for (const { file } of secretFiles(tenant)) {
-        const all = JSON.parse(fs.readFileSync(file, "utf8"));
-        const plain = new Map();
-        let pending = 0;
-        for (const [name, rec] of Object.entries(all)) {
-            if (rec.k === "tenant")
-                continue; // already moved
-            const value = decrypt(tenant, rec);
-            if (value === null) {
-                unreadable.push(name);
-                continue;
+        // Under the vault's lock: every pod runs this at boot, and a save made
+        // between our read and our write must not be lost.
+        mutateVaultFile(file, (all) => {
+            const plain = new Map();
+            const unreadableHere = [];
+            for (const [name, rec] of Object.entries(all)) {
+                if (rec.k === "tenant")
+                    continue; // already moved
+                const value = decrypt(tenant, rec);
+                if (value === null) {
+                    unreadableHere.push(name);
+                    continue;
+                }
+                plain.set(name, value);
             }
-            plain.set(name, value);
-            pending += 1;
-        }
-        // Nothing to do, or something could not be read — leave the file alone.
-        // A partial conversion is worse than none, because the half that moved is
-        // no longer openable by the key the other half still needs.
-        if (pending === 0 || unreadable.length)
-            continue;
-        const next = { ...all };
-        for (const [name, value] of plain) {
-            next[name] = { ...encryptValue(tenant, value), updatedAt: all[name].updatedAt, ...(all[name].kind ? { kind: all[name].kind } : {}) };
-        }
-        const tmp = `${file}.rewrap`;
-        fs.writeFileSync(tmp, JSON.stringify(next, null, 2), { mode: 0o600 });
-        fs.renameSync(tmp, file);
-        moved += pending;
+            unreadable.push(...unreadableHere);
+            // Nothing to do, or something in THIS file could not be read — leave it
+            // alone. A partial conversion is worse than none, because the half that
+            // moved is no longer openable by the key the other half still needs.
+            if (plain.size === 0 || unreadableHere.length)
+                return null;
+            const next = { ...all };
+            for (const [name, value] of plain) {
+                next[name] = { ...encryptValue(tenant, value), updatedAt: all[name].updatedAt, ...(all[name].kind ? { kind: all[name].kind } : {}) };
+            }
+            moved += plain.size;
+            return next;
+        });
     }
     return { moved, unreadable };
 }

package/dist/src/starter.d.ts

@@ -18,4 +18,13 @@ export interface StarterFile {
  * workspace somewhere would be worse than no starter.
  */
 export declare function accountFiles(account: string): StarterFile[];
+/**
+ * What an account folder ignores, at its own root.
+ *
+ * The workspace scaffold has always shipped one of these; an account folder is
+ * the thing that gets committed now, and the key that decrypts its secrets
+ * lives at ITS root — `<account>/.foldrun/` — so the guard has to be here too
+ * or the first `git add .` commits the vault key.
+ */
+export declare function accountGitignore(): StarterFile;
 export declare function starterFiles(workspace: string): StarterFile[];

package/dist/src/starter.js

@@ -64,6 +64,36 @@ dropped further down.
         },
     ];
 }
+/**
+ * What an account folder ignores, at its own root.
+ *
+ * The workspace scaffold has always shipped one of these; an account folder is
+ * the thing that gets committed now, and the key that decrypts its secrets
+ * lives at ITS root — `<account>/.foldrun/` — so the guard has to be here too
+ * or the first `git add .` commits the vault key.
+ */
+export function accountGitignore() {
+    return {
+        path: ".gitignore",
+        content: `# The key that decrypts every secret in this account, plus the local run
+# store. Never commit these.
+.foldrun/
+
+# Written by runs, not by you.
+workspaces/*/runs/
+workspaces/*/outputs/
+state/
+storage/
+# The link a running step keeps in its agent folder (workspace/ for the
+# shell); removed when the step ends, ignored in case one is left behind.
+workspaces/*/agents/*/workspace
+
+.env
+.env.local
+.DS_Store
+`,
+    };
+}
 export function starterFiles(workspace) {
     return [
         {
@@ -98,6 +128,9 @@ Context every agent here shares. Prices, rules, anything they should all know.
 # Written by runs, not by you.
 runs/
 outputs/
+# The link a running step keeps in its agent folder (workspace/ for the
+# shell); removed when the step ends, ignored in case one is left behind.
+agents/*/workspace
 
 .env
 .env.local
@@ -114,6 +147,8 @@ effort: high
 tools:
   - web
   - read
+web:
+  actions: [search, fetch]
 ---
 
 Pick exactly one topic, in a short paragraph, and say who it helps and why now.
@@ -126,7 +161,7 @@ Do not write the article.
 name: writer
 description: Turns a brief into a short draft.
 tools:
-  - files
+  - write
 ---
 
 Write a short draft from the brief you were given. Save it to outputs/draft.md.
@@ -209,6 +244,10 @@ foldrun deploy --url <server> --token $FOLDRUN_TOKEN
 \`check\` is cheap and catches a broken flow before a schedule fires it at 3am.
 Run it after edits, the way you would run a typecheck.
 
+A deploy that would delete files this folder no longer has lists them and
+stops: with no terminal it is refused. Tell the person what it would delete; add \`--yes\`
+only when they asked for exactly that deletion.
+
 ## Where things go
 
 | Path | What |
@@ -231,10 +270,23 @@ Regenerated every run means a file; accumulated across runs means \`state/\`.
 That last row is worth knowing: a subagent you write in Claude Code is imported
 as \`agents/<name>/agent.md\` at deploy, no conversion. Write it either way.
 
+## Paths inside a workspace
+
+An agent's working directory is \`agents/<name>/\`. Write every path to the
+workspace's own folders as \`workspace/…\` — \`workspace/storage/report.csv\`,
+\`workspace/state/cursor.json\` — in an agent's prose, in flow options
+(\`each: rows of\`, \`when: rows of\`, \`verify:\`, \`preview:\`, \`schema:\`) and in
+script arguments. It resolves the same in the file tools, the shell, scripts
+and checks. The older \`../../storage/…\` reaches the same place and still
+works; \`foldrun check\` suggests the new spelling where it sees it.
+A Node script started as \`node workspace/tools/x/run.mjs\` is its own main
+module there, so its \`import.meta.url\` entry check runs (it did not before
+2 Oct 2026 and exited 0 doing nothing).
+
 ## What a deploy does NOT touch
 
-\`runs/\`, \`state/\`, \`secrets.json\`, and any memory an agent wrote that your
-push does not mention. Those belong to the platform, not to git — a deploy that
+\`runs/\`, \`state/\`, \`storage/\`, \`secrets.json\`, the trigger log, and any
+memory an agent wrote that your push does not mention. Those belong to the platform, not to git — a deploy that
 reverted what an agent learned would make every run a little dumber.
 
 Secrets never go in these files. \`foldrun secrets\` puts them in the vault, and
@@ -270,19 +322,32 @@ All of it, \`/api/workspaces/<workspace>\` unless noted:
 | \`/runs/<id>/stop\` | POST | kill it — destroys the sandbox too |
 | \`/runs/<id>/rerun\` | POST | again, or from a chosen step |
 | \`/runs/<id>/approve\` | POST | release a run waiting on a human |
+| \`/runs/<id>/answer\` | POST | answer a question an agent is asking mid-step (\`tools: [ask]\`) |
+| \`/runs/<id>/message\` | POST | tell a running step something; \`step\` picks one of a parallel group |
 | \`/flows\` · \`/flows/<f>\` | GET POST · POST DELETE PATCH | list, create, edit |
 | \`/flows/<f>/run\` | POST | start a flow |
 | \`/agents\` · \`/agents/<a>/run\` | GET POST · POST | list agents, run one |
 | \`/evals\` · \`/evals/<e>/run\` | GET POST · POST | list evals, run one |
 | \`/tools/<t>/test\` | POST | exercise one tool alone |
-| \`/storage\` · \`/storage/download\` · \`/storage/upload-url\` | GET POST PUT DELETE · GET · POST | workspace files |
+| \`/storage\` · \`/storage/download\` · \`/storage/upload-url\` · \`/storage/preview\` | GET POST PUT DELETE · GET · POST · GET | workspace files, any type; \`preview\` returns one parsed for reading |
 | \`/assets\` | POST | upload an asset |
 | \`/hooks/<f>/rotate\` | POST | new webhook token for a flow |
+| \`/notify/deliveries\` · \`/notify/deliveries/<id>/redeliver\` | GET · POST | every notify: webhook sent and each attempt; send one again |
+| \`/restore\` | POST | the workspace's source back to a point in its history — \`dryRun\` first, then \`confirm\` |
 | \`/vocabulary\` | GET | what this workspace's documents may say |
 
 Account-level, outside \`/workspaces\`: \`/api/secrets\`, \`/api/keys\`, \`/api/schedule\`,
 \`/api/approvals\`, \`/api/usage\`, \`/api/library/<kind>\`, \`/api/team\`, \`/api/billing\`,
-\`/api/healthz\` (open) and \`/api/metrics\` (Prometheus).
+\`/api/me/notifications\` (what mail you get; a key acts for whoever minted it),
+\`/api/account/backups\` (snapshots, restore requests), \`/api/me/onboarding\` (getting started),
+\`/api/healthz\` and \`/api/version\` (open), \`/api/changelog\` (release notes)
+and \`/api/metrics\` (Prometheus).
+
+Every call answers — and the CLI sends — \`Foldrun-Version: YYYY-MM-DD\` (dated API
+versions; an account pin in Settings → API), \`X-RateLimit-*\` headers (a \`429\`
+carries \`Retry-After\`), and writes that start work take an \`Idempotency-Key\`
+(a retry with the same key replays the first answer). The whole surface as
+OpenAPI 3.1: \`/api/openapi.json\` (open), or \`foldrun api spec --out openapi.json\`.
 
 Debugging a failed run is usually: \`runs\` to find it, \`runs/<id>\` to read which
 step failed and what it cost, fix the markdown, \`deploy\`, then \`rerun\`.
@@ -295,6 +360,11 @@ git push endpoint.
 
 A numbered list of steps. The number is the GROUP: same number means those
 steps run in parallel, and the flow waits for all of them before the next.
+The dashboard's canvas and the CLI edit the same file: \`foldrun flow show
+<flow>\` draws it, \`foldrun flow add <flow> <pattern>\` inserts a pattern
+(chain, parallel, router, fan-out, loop, approval, ask, wait, rescue,
+subflow), \`foldrun flow rm-step\` removes a step, and \`foldrun agent link
+<agent> --subagent|--consult|--can-ask\` wires agents together.
 
 \`\`\`markdown
 ---
@@ -310,7 +380,7 @@ priority: normal         # high | normal | low — where its runs stand in the q
 1. [[researcher]] — Find three sources on {{topic}}.
 2. [[writer]] — Draft from what the researcher found.
    model: max
-   verify: the draft cites every source
+   verify: judge: the draft cites every source
 3?. [[editor]] — Tighten it.
 4!. [[publisher]] — Publish it.
 \`\`\`
@@ -323,11 +393,14 @@ Indented under a step, any of:
 | | |
 |---|---|
 | \`approve: true\` | stop for a human (\`!\` is shorthand for this) |
-| \`when: <condition>\` | run only if it holds |
+| \`when: <MARKER>\` | run only if a line of the previous result begins with it |
+| \`when: rows of <path>\` | run only if that CSV has a data row — for the steps after an \`each:\` |
 | \`case: <value>\` / \`else: true\` | branch on the previous step's result |
 | \`retry: 2\` | re-run on failure, up to 5 |
 | \`timeout: 900\` | seconds before the step is cut off |
-| \`verify: <claim>\` | the step fails unless this is true of its output |
+| \`verify: <shell>\` | the step fails unless the command exits 0; the reply is in \`$FOLDRUN_REPLY_FILE\` |
+| \`verify: judge: <claim>\` | a model grades the claim against the output |
+| \`verify: contains:\` / \`not-contains:\` / \`matches:\` / \`file:\` | the cheap checks, no shell |
 | \`model:\` / \`effort:\` | override the flow's default for this step |
 | \`loop: 3\` / \`until: <condition>\` | repeat until it holds, at most 5 |
 | \`each: lines\` | run once per line of the previous result |
@@ -344,6 +417,7 @@ Indented under a step, any of:
 | \`each: items\` | run once per element of the previous step's JSON array |
 | \`parallel: 3\` | how many \`each:\` instances run at once — default all |
 | \`max_turns: 20\` | the most model turns before the step is stopped, beside \`budget:\` and \`timeout:\` |
+| \`limits: {web.search: 10}\` | this step's call limits, over the agent's key by key |
 
 ## Writing an agent
 
@@ -357,14 +431,17 @@ description: Finds and summarises sources.
 model: default              # fast | default | max
 effort: low                 # how hard to think about it
 size: large                 # small | large | heavy — the sandbox it rents
-tools: [WebSearch, Read, my-folder-tool]  # built-ins and your own tools/, one list
+tools: [web, read, ask, my-folder-tool]  # built-ins and your own tools/, one list; \`ask\` lets it ask you mid-step
 disallowedTools: [Bash]     # subtract from what it would otherwise have
 skills: [house-style]       # from skills/
 scripts: [summarise.py]     # from scripts/, each becomes a callable tool
 apis: [{ name: crm }]       # an HTTP API, as a tool
 mcpServers: {}              # an MCP server, as a tool
-agents: [writer]            # colleagues this one may consult
-secrets: [CRM_TOKEN]        # from the vault — never written in these files
+agents: [writer]            # colleagues this one may consult (an answer, no tools)
+subagents: [researcher]     # colleagues it may delegate a job to (own context, own tools ≤ its own)
+secrets: [CRM_TOKEN]        # keys the agent uses itself; a tool's own come with the tool
+limits: {web.search: 40, crm: 20, calls: 300}  # per step; a call past a limit is refused, never run
+timezone: Australia/Sydney  # the calendar it works to — IANA name or UTC+10
 provider: {}                # BYOK: your own model credential
 permissionMode: plan        # plan first, act once approved
 runtime:                    # only if scripts need packages
@@ -377,6 +454,10 @@ You research a topic and report what you found...
 Only \`name\` and the prose are required. Every other field widens or narrows
 what the agent can reach, and the default is narrow.
 
+\`timezone:\` is nearest-wins all the way down: the agent's own, else its
+flow's, else the workspace's AGENTS.md, else the account's, else UTC. It sets
+\`TZ\` and the date the agent is told, so a Sydney desk stamps the Sydney date.
+
 \`runtime:\` installs pip/npm packages in the sandbox each agent runs in. Pin
 versions the normal way (\`pandas>=2\`, \`lodash@^4\`). Python and Node are
 supported; anything else should ship as a committed binary.