foldrun 19.0.2 → 19.2.0

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/README.md CHANGED
@@ -139,7 +139,7 @@ declared the same way.
139
139
  | `foldrun schedule tick` | fire whatever is due now — Settings' "Run scheduler now" |
140
140
  | `foldrun backups` | how the account is backed up and the snapshots it is in; `backups request --what runs --at "<when>" [--to <ws>]` asks the platform team for a restore, `backups requests` lists them |
141
141
  | `foldrun restore <ws> --to <commit\|time\|3d>` | a workspace's source back as it was then — shows the change, asks for the name typed back (`--dry-run`, `--yes`) |
142
- | `foldrun onboarding` | the account's getting-started steps, done or not, the next one first |
142
+ | `foldrun onboarding` | the account's getting-started steps, done or not, the next one first; `--to <workspace>` adds that workspace's checklist |
143
143
  | `foldrun triggers` | why nothing ran: per flow, how often its trigger fired, how often that became a run, and every reason for the difference (`--since <days>`, `--to`) |
144
144
  | `foldrun webhooks deliveries` | the `notify:` webhooks a workspace sent: status, attempts, the last answer (`--failed`, `--to`) — and `redeliver <id>` to send one again |
145
145
  | `foldrun notifications` | what mail you get, per category; `set <category> on\|off` (`--to <workspace>` for run alerts and approvals) — security, invites, billing and account mail are always sent |
@@ -227,7 +227,8 @@ foldrun deploy
227
227
  foldrun invoke publish --wait
228
228
  ```
229
229
 
230
- `foldrun login --url https://your-platform` signs in to your own installation.
230
+ `foldrun login` signs in to the hosted platform, https://dash.foldrun.io;
231
+ `foldrun login --url https://your-platform` (or `FOLDRUN_URL`) to your own installation.
231
232
  In CI, set `FOLDRUN_URL` and `FOLDRUN_TOKEN` instead — the environment always
232
233
  wins over the credentials file, so a job never reads one from disk.
233
234
 
package/bin/foldrun.mjs CHANGED
@@ -286,6 +286,7 @@ Signing in
286
286
  session: cookies, storage and the browser identity it needs
287
287
  foldrun logout forget this machine's key, and revoke it where allowed
288
288
  foldrun whoami who you are on the platform: account, role, workspaces
289
+ foldrun signup status can a stranger sign up on the platform: free sign-up, paid sign-up, and the plans sold while paid is in effect — the open /api/signup, no key sent (--url, --json; exits 1 when it does not answer)
289
290
  foldrun me the person this machine is signed in as: name, address, timezone (--json)
290
291
  foldrun me name <first> [last] set your name (--clear for none) · foldrun me timezone <zone|auto> the zone you read times in
291
292
  foldrun team who is in the account: role, the workspaces each may open, when they joined (--json)
@@ -295,7 +296,7 @@ Signing in
295
296
  foldrun team remove <email|id> remove a member — asks first (--yes with no terminal); their keys and pending invites stop. Transfer stays in Settings → Team
296
297
  foldrun team invites the account's pending invites — address or "anyone with the link", role, workspaces, who made it, when it expires, its id (--all for accepted, revoked and expired too; --json). Never the link: each works once, shown only to its maker
297
298
  foldrun team invites revoke <id> take an invite back: its link stops working at once (an admin's; a key may)
298
- foldrun onboarding the account's getting-started steps, done or not, the next one first (--json)
299
+ foldrun onboarding the account's getting-started steps, done or not, the next one first; --to <workspace> adds that workspace's checklist (--json)
299
300
  foldrun preferences your own settings on the platform — the theme; set theme system|light|dark (a key acts for whoever minted it)
300
301
  foldrun doctor check the path to the platform: node, CLI, model credential, account, DNS, a timed /api/healthz
301
302
  foldrun accounts every account signed in on this machine, and which one is active
package/docs/api.md CHANGED
@@ -18,7 +18,7 @@ proof instead of a key: a token or signature (`/s/<token>`, `/api/hooks`,
18
18
  `/api/billing/partner/…` (a storefront's signature),
19
19
  `/api/billing/confirm`), the sign-in and recovery steps (`/api/auth/signup`,
20
20
  `login`, `forgot`, `reset`, `verify`, `mfa/verify`, `session`, `/api/cli/login`,
21
- `/api/cli/login/<id>`, `/api/cli/authorize` GET, `/api/oauth/callback`), `/api/healthz`, `/api/status`, `/api/status/history`, `/api/version` and `/api/openapi.json` — and an AI app's OAuth sign-in to `/api/mcp`: `/api/mcp/oauth/register` (open, as the protocol needs) and `/api/mcp/oauth/token` (its code and PKCE verifier, or its refresh token, are the proof).
21
+ `/api/cli/login/<id>`, `/api/cli/authorize` GET, `/api/oauth/callback`), `/api/healthz`, `/api/status`, `/api/status/history`, `/api/signup`, `/api/version` and `/api/openapi.json` — and an AI app's OAuth sign-in to `/api/mcp`: `/api/mcp/oauth/register` (open, as the protocol needs) and `/api/mcp/oauth/token` (its code and PKCE verifier, or its refresh token, are the proof).
22
22
 
23
23
  ```
24
24
  Authorization: Bearer <api-key> # machines. Settings → API keys
@@ -471,7 +471,7 @@ X-Foldrun-Cli: 0.6.0 # the CLI released with this version (absent
471
471
 
472
472
  | Route | Methods | |
473
473
  |---|---|---|
474
- | `/api/auth/signup` | POST | `email`, `password`, `account`, `invite`, `setup`. An install with `FOLDRUN_SETUP_TOKEN` set creates its first account only with `setup` equal to it (403 otherwise); once an account exists the token does nothing. Rate limited per address and per caller. With signups closed every address gets the same refusal, so the form cannot be used to discover which addresses are registered |
474
+ | `/api/auth/signup` | POST | `email`, `password`, `account`, `invite`, `setup`. An install with `FOLDRUN_SETUP_TOKEN` set creates its first account only with `setup` equal to it (403 otherwise); once an account exists the token does nothing. Without an invite, a new account comes in by the first-account exception or free sign-up (`signup.open`) — decided again inside the write, so two first sign-ups at once make one owner; an invite needs no switch. A body with `plan` is refused (400): paid sign-up is not offered by this route yet. Rate limited per address and per caller. With signups closed every address gets the same refusal, so the form cannot be used to discover which addresses are registered |
475
475
  | `/api/auth/login` | POST | `email`, `password`. Wrong passwords are limited per account: 8 a quarter hour from one caller when a trusted proxy names the caller (`FOLDRUN_TRUST_PROXY`), so a stranger failing as someone locks out only themselves, and 40 from every caller together, reaching which mails the person; with no caller address, 8 per account from anyone. A 429 carries `Retry-After` |
476
476
  | `/api/auth/logout` | POST | ends the session |
477
477
  | `/api/auth/session` | GET | who am I |
@@ -505,7 +505,7 @@ signed-in person, never by a key — mints an ordinary API key at their role.
505
505
  | `/api/cli/login/<id>` | GET | `{ status }` — `pending`, `denied`, `expired`, or `approved` with `token`, `account`, `email`, `role`. The key is returned once; the request is gone after |
506
506
  | `/api/cli/authorize` | GET, POST | `?code=` describes the request: machine, expiry, `createdAt`, `requestedFrom` (the asking network as an IPv4 /24 or IPv6 /48, from the trusted proxy — null when not known), `requestedCountry` (behind Cloudflare; else null), `sameNetwork` (whether the browser looking is on that network; null when either is not known) and `approveBy`. POST `{ code, decision }` from a session approves (mints the key, labelled `cli · <hostname>`, ending in 90 days — the CLI renews it itself before then, see `/api/keys/<id>/rotate`) or denies — `decision` is `approve` or `deny`, and absent approves; any other word is a `400`. A request more than five minutes old can no longer be approved (`410`; it can still be denied) — device-code phishing, RFC 8628 §5.4. Every role may sign its own CLI in; an owner's key is an admin's |
507
507
  | `/api/me` | GET | who is calling: `account`, `owner`, `role`, `workspaces` (null: all), and the `actor` — a person's email, or a key's id, label, prefix, who minted it, `expiresAt` (null: never) and `origin` (`cli-login` for a key `foldrun login` minted, else null); `person` — `{ email, firstName, lastName, timezone }` for a signed-in session or a `foldrun login` key, null for any other key |
508
- | `/api/me/onboarding` | GET, PATCH | the account's getting-started steps, each derived from what is really there — `{ steps: [{ id, title, why, href, cli?, done }], done, total, complete, next, dismissed, dismissedAt }`. Steps: `model` (first; only for an account that must bring its own key — done once it has one, or a `provider:` block in the account's AGENTS.md), `workspace`, `agent` (an agent written or deployed after the workspace was made), `run`, `success` (a completed run), `secret`, `trigger` (a schedule or webhook), `teammate` (a second member), `billing` (hosted, not fully waived: a saved card or a plan), `cli` (any API key or CLI login). A caller scoped to some workspaces is answered over those workspaces alone — no other workspace's name is in a step's `href`. PATCH `{ dismissed: true or false }` hides or brings back the dashboard card for the signed-in person (kept in their prefs); a key reads `dismissed: false` and cannot PATCH |
508
+ | `/api/me/onboarding` | GET, PATCH | the account's getting-started steps, each derived from what is really there — `{ steps: [{ id, title, why, href, cli?, done, hidden }], done, total, complete, next, upNext, hidden, dismissed, dismissedAt, welcomedAt }`. Steps: `model` (first; only for an account that must bring its own key — done once it has one, or a `provider:` block in the account's AGENTS.md), `workspace`, `agent` (an agent written or deployed after the workspace was made), `run`, `success` (a completed run), `secret`, `trigger` (a schedule or webhook), `teammate` (a second member), `billing` (hosted, not fully waived: a saved card or a plan), `cli` (any API key or CLI login). `next` is the first step not done; `upNext` the first neither done nor hidden by this person; `hidden` the step ids they hid; `welcomedAt` when they first opened the welcome flow (`/dashboard/welcome`; the home page sends a person there once, the first time they open an account with no workspace). `?workspace=<name>` adds `checklist: { workspace, items: [{ id, title, why, href, done, hidden }], done, total, complete, dismissed, show }` — that workspace's checklist: `run` (a flow that ran to the end), `trigger` (a schedule or webhook), `owner` (`owner:` by the cascade), `eval`, `notify` (`notify:` with an address or URL, the workspace's or the account's); a workspace outside the caller's scope, or none, is a `404`. A caller scoped to some workspaces is answered over those workspaces alone — no other workspace's name is in a step's `href`. PATCH, for the signed-in person (kept in their prefs), any of: `{ dismissed: true or false }` hides or brings back the dashboard card; `welcomed: true` records the welcome flow as seen; `hide: [step ids]`, `show: [step ids]` hide or bring back single steps; `checklist: { workspace, dismissed?, hide?: [item ids], show?: [item ids] }` the same for a workspace's checklist. An unknown id is a `400`. A key reads nothing hidden and `dismissed: false`, and cannot PATCH |
509
509
  | `/api/me/inbox` | GET, POST | your inbox — what waits on you across the workspaces you may see. GET `{ person, items: [{ id, kind (approval, question, issue, proposal, run), bucket (mine, started, team), why, workspace, title, detail, at, href, read, dismissed }], counts: { mine, started, team, unread } }`, newest first. `mine` is assigned to you (named in `approvers:`, owner of the flow or agent, or you asked for the proposal); `started` is runs you started — failed or BLOCKED/BAD this week, a gate on one (someone else decides it), a question it asked; `team` is the rest that waits in your workspaces. By default `mine` and `started`; `?bucket=mine\|started\|team\|all`, `?kind=`, `?workspace=`, `?dismissed=1` for what you set aside. `counts.unread` is unread `mine` + `started`. POST `{ ids \| id, action: read\|unread\|dismiss\|restore }` changes your view only — dismissing never decides a gate or resolves an issue; ids name an occurrence, so a thing that happens again is new. A key acts for the person who minted it, inside the key's own scope; one no person minted is a `400` |
510
510
  | `/api/me/notifications` | GET, PATCH | what mail you get. GET `{ email, categories: [{ category, label, description, required, why?, perWorkspace, enabled, workspaces: { <ws>: bool } }] }` for `security`, `invites`, `billing`, `account` (required — always sent) and `run-alerts`, `approvals` (per workspace), `low-balance`, `product-updates`. PATCH `{ category, enabled, workspace? }` or `{ preferences: [ … ] }`; answers the same as GET. Turning a required category off is a `409` with the reason; `workspace` on an account-wide category is a `400`; `enabled: true` account-wide clears that category's per-workspace offs. A key acts for the person who minted it |
511
511
  | `/api/me/preferences` | GET, PATCH | your own display preferences: `{ theme, runViews }` — `theme` is `system` (the default: follow the computer's light or dark setting), `light` or `dark`; `runViews` your saved run searches, `[{ name, query }]` (see [Runs](runs#searching-runs)). PATCH `{ theme }` and/or `{ runViews }` (the whole list, at most 20, each query of the runs filters) answers the same; anything else is a `400`. Kept in your prefs, so it follows you to every browser; the dashboard applies it on the server, before the first paint. A key acts for the person who minted it; a key minted by nobody is a `400` |
package/docs/cli.md CHANGED
@@ -133,7 +133,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
133
133
  | `foldrun export [workspace]` | a deployed workspace as a `.zip` — agents, flows, tools, skills, scripts, evals, knowledge; never memory, state, storage or a secret's value. `--flow <name>` exports that flow with every flow and agent it runs and the tools, skills and scripts they grant; `--agent <name>` that agent and what it grants. Written under the name the platform gives it (`<ws>.zip`, `<ws>-flow-<name>.zip`); `--file <path>` (`-` for stdout), `--force` to replace (`GET …/export`) |
134
134
  | `foldrun import <file.zip>` | take a package in: first shows what it adds, what is identical, what it would replace and what it still needs (secrets, tools, skills, scripts, agents, flows), then asks. Never deletes; replacing a file needs `--overwrite`. `--to <workspace>` (a name that does not exist makes it, from a workspace package), `--dry-run` previews only (`--json` for the plan), `--yes` with no terminal (`POST …/import`) |
135
135
  | `foldrun status [workspace]` | per workspace: what is added, changed and only-on-the-platform, plus which files moved there since your last deploy from here. Reads only |
136
- | `foldrun status --platform` | is the platform up: overall, each component (dashboard and API, run workers, scheduler, model providers, email, storage) and any incident or maintenance the operator posted, with its latest update. Reads the open `/api/status` — no key needed; the signed-in platform, `--url`, or app.foldrun.io. `--json` prints the answer as is. Exits 1, saying *status unavailable — the platform may be down*, when it does not answer. Plain `foldrun status` opens with the same one-line verdict |
136
+ | `foldrun status --platform` | is the platform up: overall, each component (dashboard and API, run workers, scheduler, model providers, email, storage) and any incident or maintenance the operator posted, with its latest update. Reads the open `/api/status` — no key needed; the signed-in platform, `--url` / `FOLDRUN_URL`, or the default, dash.foldrun.io. `--json` prints the answer as is. Exits 1, saying *status unavailable — the platform may be down*, when it does not answer. Plain `foldrun status` opens with the same one-line verdict |
137
137
  | `foldrun status --platform --history` | what the status page draws as bars: each component's uptime over the window and a mark per day — up, degraded or maintenance, an outage, or no samples — then the incidents and maintenance in it, from the open `GET /api/status/history?days=<n>`. `--days 1-90` (default 90), `--json` |
138
138
  | `foldrun workspaces` | what exists here, what exists on the platform, which are both — also `new <name>`, and `rm <name>` (locally; `--platform --yes` deletes it there). `--json`: `{ platform, workspaces: [{ name, here, platform }], error? }`, exit 1 when the platform could not be read |
139
139
  | `foldrun workspaces show <name>` | what is deployed in one workspace (`GET /api/workspaces/<name>`): its agents with model and description, its flows and how each fires, and its files counted by top-level folder. `--json` for the document |
@@ -150,6 +150,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
150
150
  | `foldrun login <site> --url <address>` | a browser window to sign in to a site by hand; the session is stored for an agent |
151
151
  | `foldrun logout` | forget this machine's key, and revoke it if `login` made it |
152
152
  | `foldrun whoami` | who you are on the platform: account, role, which workspaces |
153
+ | `foldrun signup status` | can a stranger sign up on the platform, and how: **free** sign-up (an account without paying) open or closed, **paid** sign-up (choosing a plan — foldrun's hosted platform only, in effect only while payments are ready) open or closed, and while paid is open the plans it sells. Reads the open `GET /api/signup` — what foldrun.io's sign-up buttons read — and never sends a key, whatever `--url` names; the signed-in platform, `--url` / `FOLDRUN_URL`, or the default, dash.foldrun.io. `--json` prints the answer as is. Exits 1 when the platform does not answer or answers another shape. What each switch is SET to, and why paid is not in effect, is the operator console's |
153
154
  | `foldrun team` | who is in the account (`GET /api/team`): each member's email, role (the owner marked), the workspaces they may open — a scoped key sees only the ones it shares — and when they joined. `--json` |
154
155
  | `foldrun team invite [email]` | invite someone (`POST /api/team`): `--role viewer\|editor\|admin` (default editor), `--workspaces a,b` or `--all` (omitted: every workspace, unless you are scoped — then name them), `--no-send` to mail nothing. Without an address the link works for whoever has it. Prints the link once: it works one time, for seven days, and is shown only to you. `--json`. Like every `team` write, it is a person's: it works from your own `foldrun login` on this machine, never from a key made by hand, and it acts at the lower of that sign-in's role and yours now — an owner's sign-in here is an admin, so inviting, changing or removing an admin stays in Settings → Team |
155
156
  | `foldrun team role <email\|id> <role>` | change a member's role to viewer, editor or admin (`PATCH /api/team/members/<id>`); the member by address (any case) or id. Their keys above the new role stop. Nobody changes their own role, and owner is transferred, not set |
@@ -160,7 +161,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
160
161
  | `foldrun me timezone <zone\|auto>` | the zone you read times in (`POST /api/auth/timezone`), e.g. `Australia/Sydney`; `auto` goes back to the browser's. Password, email, two-step sign-in and sessions stay in Settings → Profile |
161
162
  | `foldrun team invites` | the account's pending invites (`GET /api/team/invites`): the address, or "anyone with the link", role, workspaces, who made it, when it expires, and its id. `--all` adds accepted, revoked and expired ones; `--json`. Never the link: an invite works once and its link is shown only to the person who made it. An admin's (`team:manage`), a key included; a scoped key sees the invites inside its scope |
162
163
  | `foldrun team invites revoke <id>` | take an invite back (`DELETE /api/team/invites/<id>`): its link stops working at once. One already revoked or expired says so and changes nothing; one already accepted is refused (remove the member in Settings → Team instead). An admin invite is the owner's to revoke |
163
- | `foldrun onboarding` | the account's getting-started steps — the model key (where the account brings its own), workspace, agent, a run, a run that completes, a secret, a schedule or webhook, a teammate, billing where the plan asks for it, the CLI — each worked out from what is really there, with the next one first and where to do it (`--json`). The dashboard card is hidden per person from the dashboard |
164
+ | `foldrun onboarding` | the account's getting-started steps — the model key (where the account brings its own), workspace, agent, a run, a run that completes, a secret, a schedule or webhook, a teammate, billing where the plan asks for it, the CLI — each worked out from what is really there, with the next one first and where to do it (`--json`). `--to <workspace>` adds that workspace's checklist: a flow that ran to the end, a schedule or webhook, an owner, an eval, `notify:` — each with where it is done (`GET /api/me/onboarding?workspace=`). Hiding the card, a step or a checklist item is per person, from the dashboard |
164
165
  | `foldrun preferences` | your own settings on the platform — today the theme (`system`, `light`, `dark`), kept with you on every browser; `preferences set theme dark` changes it (`/api/me/preferences`; a key acts for whoever minted it) |
165
166
  | `foldrun api spec` | the platform's OpenAPI 3.1 document, from `GET /api/openapi.json` (no key needed) — to stdout, or `--out <file>`. Every other command sends `Foldrun-Version` (the API version this CLI was built for), an `Idempotency-Key` on each write (reused on its own retry), and waits out one `429` for `Retry-After` before saying so. See [Using the API](api-usage) |
166
167
  | `foldrun api version` | Settings → API: the API version this account's requests get when they send no `Foldrun-Version`, whether it is pinned, every version still served, the rate limits, and the last 30 days: requests by version, and any deprecated route the account still calls — by which key or person, and when it stops answering. `api version pin <YYYY-MM-DD>` pins it, `unpin` goes back to current (`PATCH /api/account/api`; an admin's) |
@@ -279,7 +280,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
279
280
  | `--note "<text>"` | `approve`: guidance the approved step reads in its prompt — "approve, but skip the Sydney batch". `reject`: the reason, recorded on the trace |
280
281
  | `--read-only` | `mcp`: offer the AI app only the tools that read — no `run_flow`, `decide_approval`, `answer_question`, `message_run` or `stop_run` |
281
282
  | `--yes` | skip the confirmation, deliberately: `approve`, `stop`, `deploy` (when it would delete files), and a bulk `stop` or `rerun`, `flow rotate-hook`, `flow draft`, `assistant`, `mcp disconnect`, `a2a cancel`, `history restore`, `restore`, `billing plan`, `repo deploy`/`merge`, `workspace set name`, and every delete — `runs rm`, `storage rm`, `storage unshare`, `source rm`, `secrets rm`, `keys revoke`, `workspaces rm`. Required when there is no terminal to ask; without it nothing is deleted |
282
- | `--json` | `report`: the raw run record instead of the report. `observe`, `usage`, `workspaces`, `workspaces show`, `agent ls`, `flow ls`, `agent import --list`, `assistant`, `backups requests`, `status --platform --history`, `team`, `secrets ls`, `triggers`, `storage ls --all`: the raw document |
283
+ | `--json` | `report`: the raw run record instead of the report. `observe`, `usage`, `workspaces`, `workspaces show`, `agent ls`, `flow ls`, `agent import --list`, `assistant`, `backups requests`, `status --platform --history`, `signup status`, `team`, `secrets ls`, `triggers`, `storage ls --all`: the raw document |
283
284
  | `--events <a,b>` | `account set notify`: which events are notified on — `failed`, `awaiting-approval`, `completed` |
284
285
  | `--watch` | `invoke`: follow the run's trace here as it happens; the exit code is the run's |
285
286
  | `--print` | `open`: print the URL, do not open it |
@@ -490,8 +491,8 @@ the same platform** — an agency looking after four customers keeps four,
490
491
  and switches between them without pasting a key:
491
492
 
492
493
  ```sh
493
- foldrun login --url https://app.foldrun.io # as acme
494
- foldrun login --url https://app.foldrun.io # as beta, in a second browser
494
+ foldrun login --url https://dash.foldrun.io # as acme
495
+ foldrun login --url https://dash.foldrun.io # as beta, in a second browser
495
496
  foldrun accounts # both, ● on the active one
496
497
  foldrun use acme # from here on, acme
497
498
  foldrun logs --profile beta --to leads # just this once, beta
@@ -525,7 +526,7 @@ foldrun keys create "alex's laptop" --role admin
525
526
  The key is printed once. They send it to you; you store it as a profile:
526
527
 
527
528
  ```sh
528
- foldrun login --url https://app.foldrun.io --token <the key> --profile acme
529
+ foldrun login --url https://dash.foldrun.io --token <the key> --profile acme
529
530
  ```
530
531
 
531
532
  The key carries the role it was minted with, so an `editor` key cannot
@@ -118,27 +118,46 @@ written into the workspace, so a workspace is always safe to commit.
118
118
 
119
119
  ## The checklist on the dashboard
120
120
 
121
- A new account's home page shows a **Getting started** card: add your model
122
- key (on a hosted platform, where the account brings its own), create a
123
- workspace, write or deploy an agent, run a flow, get a run to finish, add a
124
- secret, schedule a flow or give it a webhook, invite a teammate, set up
125
- billing (where the plan asks for it) and install the CLI — "4 of 8", with the
126
- next step first and a link to where to do it. Each step is worked out from
127
- the account as it is (a run on record, a secret in the vault, a key minted
128
- for the CLI), so it ticks itself whichever way you did the thing; there is
129
- nothing to mark. While an account has no model key every run is refused, so
130
- every dashboard page also carries a banner saying so, with a link to
131
- Settings → Model provider (`foldrun account model set anthropic --key …`,
132
- or on foldrun's own platform `foldrun account model use foldrun --provider anthropic`
133
- to run on foldrun's models, billed in credits). **Dismiss** hides it for you alone; the line at the foot of
134
- the page brings it back, and it goes away by itself once every step is done.
121
+ The first time you open an account that has no workspace, the dashboard
122
+ starts you in the **welcome flow** (`/dashboard/welcome`): add your model key
123
+ (on a hosted platform, where the account brings its own — every run is
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
126
+ MCP — then run it once and watch each step live, ending on the run's page or,
127
+ if it stops, the reason and the Doctor. Every screen can be skipped, and the
128
+ flow picks up wherever the account really is, however you did the work.
129
+
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
132
+ finish, add a secret, schedule a flow or give it a webhook, invite a
133
+ teammate, set up billing (where the plan asks for it) and install the CLI —
134
+ "4 of 8", with the next step opened up and a link to where to do it, and
135
+ **Resume setup** back into the welcome flow. Each step is worked out from the
136
+ account as it is (a run on record, a secret in the vault, a key minted for
137
+ the CLI), so it ticks itself whichever way you did the thing; there is
138
+ nothing to mark. While an account has no model key every dashboard page also
139
+ carries a banner saying so, with a link to Settings → Model provider
140
+ (`foldrun account model set anthropic --key …`, or on foldrun's own platform
141
+ `foldrun account model use foldrun --provider anthropic` to run on foldrun's
142
+ models, billed in credits). A step's **…** menu hides that step for you; the
143
+ card's hides the whole card, and the line at the foot of the page brings it
144
+ back. It goes away by itself once every step is done.
145
+
146
+ Each workspace's overview has a **Workspace checklist** of what a desk needs
147
+ before it can be left to run on its own: a flow that ran to the end, a
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
150
+ `notify:` count when the account's AGENTS.md sets them), each a link to
151
+ where it is done. Hide an item, or the card, for yourself.
135
152
 
136
153
  ```sh
137
154
  foldrun onboarding # the same steps, in the terminal
155
+ foldrun onboarding --to my-desk # and that workspace's checklist
138
156
  ```
139
157
 
140
- The API is `GET /api/me/onboarding`; hiding the card is a person's own
141
- setting, so it is done from the dashboard, not with a key.
158
+ The API is `GET /api/me/onboarding` (`?workspace=` for the checklist);
159
+ hiding is a person's own setting, so it is done from the dashboard, not with
160
+ a key.
142
161
 
143
162
  ## Where to go next
144
163
 
@@ -77,7 +77,11 @@ whoever ran it (the token is `FOLDRUN_SETUP_TOKEN` in `~/foldrun/.env`, and
77
77
  does nothing once the owner exists). With `FOLDRUN_BIND` set to one address
78
78
  the link uses that address; from another machine, open it through the
79
79
  tunnel the installer prints (`ssh -o ExitOnForwardFailure=yes -L …`), never
80
- over plain http. Then sign the CLI in and deploy:
80
+ over plain http. After the owner, the install takes new accounts only on an
81
+ invite (Settings → Team) unless you open sign-up to strangers with
82
+ `FOLDRUN_OPEN_SIGNUP=1`; with it off, `/signup` says registration is closed
83
+ and `GET /api/signup` answers `{ "free": false, "paid": false, "plans": [] }`.
84
+ Then sign the CLI in and deploy:
81
85
 
82
86
  ```sh
83
87
  npm install -g foldrun
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "foldrun",
3
- "version": "19.0.2",
3
+ "version": "19.2.0",
4
4
  "description": "Agents are just folders. Write them, check them, run them — on your machine.",
5
5
  "license": "FSL-1.1-ALv2",
6
6
  "type": "module",
package/src/commands.mjs CHANGED
@@ -4422,7 +4422,9 @@ async function connect(positional, flags) {
4422
4422
 
4423
4423
  // ---------------------------------------------------------------- login
4424
4424
 
4425
- const DEFAULT_PLATFORM = "https://app.foldrun.io";
4425
+ // The hosted platform, when nothing names one (--url, FOLDRUN_URL, the
4426
+ // profile `foldrun login` last signed in to). Written once, here.
4427
+ const DEFAULT_PLATFORM = "https://dash.foldrun.io";
4426
4428
 
4427
4429
  function openInBrowser(target) {
4428
4430
  // A server-supplied address: only a web page, never a file, an app or a
@@ -5487,6 +5489,59 @@ async function platformStatusCmd(flags) {
5487
5489
  return 0;
5488
5490
  }
5489
5491
 
5492
+ /**
5493
+ * `foldrun signup status` — can a stranger sign up on this platform, and
5494
+ * how: free sign-up, paid sign-up, and the plans it sells while paid is in
5495
+ * effect. The open GET /api/signup the public site's buttons read; no key is
5496
+ * ever sent with it, whatever platform --url names. For an operator checking
5497
+ * what foldrun.io now sees after flipping a switch (the console shows each
5498
+ * switch as set and as in effect), or a self-hoster checking theirs.
5499
+ * Exits 1 when the platform does not answer or answers something else.
5500
+ */
5501
+ async function signupCmd(positional, flags) {
5502
+ const verb = positional[0] ?? "status";
5503
+ if (verb !== "status") throw new Error(`signup: unknown verb "${verb}" — status`);
5504
+ const url = remoteUrl(flags) ?? DEFAULT_PLATFORM;
5505
+ let res;
5506
+ try {
5507
+ res = await remoteFetch(url, "/api/signup", {}, { seconds: timeoutSeconds(flags) });
5508
+ } catch (err) {
5509
+ const error = err instanceof Error ? err.message : String(err);
5510
+ if (flags.json === true) console.log(JSON.stringify({ url, error }, null, 2));
5511
+ else console.log(`\n ${c.red("✗")} ${url} did not answer (${error})\n`);
5512
+ return 1;
5513
+ }
5514
+ /** @type {any} */
5515
+ const body = await res.json().catch(() => null);
5516
+ const shaped = body && typeof body === "object" && typeof body.free === "boolean" && typeof body.paid === "boolean" && Array.isArray(body.plans);
5517
+ if (!res.ok || !shaped) {
5518
+ const error = !res.ok ? `/api/signup → HTTP ${res.status}` : "/api/signup answered something that is not { free, paid, plans }";
5519
+ if (flags.json === true) console.log(JSON.stringify({ url, error }, null, 2));
5520
+ else console.log(`\n ${c.red("✗")} ${error} — ${url}\n`);
5521
+ return 1;
5522
+ }
5523
+ if (flags.json === true) {
5524
+ console.log(JSON.stringify(body, null, 2));
5525
+ return 0;
5526
+ }
5527
+ const door = (open) => (open ? c.green("open") : c.dim("closed"));
5528
+ console.log(`\n ${c.bold("sign-up")} ${c.dim(url)}\n`);
5529
+ console.log(` free ${door(body.free)}`);
5530
+ console.log(` paid ${door(body.paid)}`);
5531
+ if (!body.free && !body.paid) console.log(`\n ${c.dim("new account registration is closed — invites still work")}`);
5532
+ if (body.plans.length) {
5533
+ console.log(`\n ${c.dim("plans")}`);
5534
+ for (const p of body.plans) {
5535
+ const price = p.price && typeof p.price.amount === "number" ? `${(p.price.amount / 100).toFixed(p.price.amount % 100 ? 2 : 0)} ${String(p.price.currency ?? "").toUpperCase()}/${p.price.interval ?? "month"}` : "—";
5536
+ console.log(` ${String(p.name ?? p.id).padEnd(10)} ${price.padEnd(14)} ${c.dim(`${p.credits ?? "?"} credits · ${p.vcpu ?? "?"} vCPU · ${p.memoryGiB ?? "?"} GiB${p.priority ? " · high-priority lane" : ""}`)}`);
5537
+ }
5538
+ } else if (body.paid) {
5539
+ console.log(`\n ${c.dim("no plans listed")}`);
5540
+ }
5541
+ console.log();
5542
+ return 0;
5543
+ }
5544
+
5490
5545
  /**
5491
5546
  * `foldrun status --platform --history [--days n]` — what the status page
5492
5547
  * draws as bars: each component's uptime per day over the window (1–90,
@@ -12023,23 +12078,41 @@ async function historyCmd(positional, flags, layout) {
12023
12078
 
12024
12079
  /**
12025
12080
  * `foldrun onboarding` — the account's getting-started steps, each worked
12026
- * out from what is really there, the next one first. Hiding the dashboard
12027
- * card is a person's own setting, so it is done there, not with a key.
12081
+ * out from what is really there, the next one first. `--to <workspace>`
12082
+ * adds that workspace's checklist (a flow that ran to the end, a trigger,
12083
+ * an owner, an eval, notify:). Hiding the dashboard card, a step or a
12084
+ * checklist item is a person's own setting, so it is done there, not with
12085
+ * a key.
12028
12086
  */
12029
12087
  async function onboardingCmd(flags) {
12030
12088
  const url = platformFor(flags, "onboarding");
12031
- const o = await remoteCall(url, flags, "/api/me/onboarding");
12089
+ const ws = typeof flags.to === "string" && flags.to ? flags.to : null;
12090
+ if (flags.to !== undefined && !ws) throw new Error("`foldrun onboarding --to <workspace>` — name the workspace whose checklist you want");
12091
+ const o = await remoteCall(url, flags, `/api/me/onboarding${ws ? `?workspace=${encodeURIComponent(ws)}` : ""}`);
12032
12092
  if (flags.json === true) {
12033
12093
  console.log(JSON.stringify(o, null, 2));
12034
12094
  return 0;
12035
12095
  }
12096
+ const base = String(url).replace(/\/$/, "");
12036
12097
  console.log(`\n ${c.bold("Getting started")} ${c.dim(`${o.done} of ${o.total}${o.complete ? " — all done" : ""}`)}\n`);
12037
12098
  for (const s of o.steps ?? []) {
12038
12099
  const mark = s.done ? c.green("✓") : s.id === o.next?.id ? c.yellow("→") : c.dim("○");
12039
12100
  console.log(` ${mark} ${s.done ? c.dim(s.title) : c.bold(s.title)}`);
12040
12101
  if (!s.done) {
12041
12102
  console.log(` ${c.dim(s.why)}`);
12042
- console.log(` ${c.dim(`${String(url).replace(/\/$/, "")}${s.href}${s.cli ? ` · ${s.cli}` : ""}`)}`);
12103
+ console.log(` ${c.dim(`${base}${s.href}${s.cli ? ` · ${s.cli}` : ""}`)}`);
12104
+ }
12105
+ }
12106
+ if (!o.complete) console.log(`\n ${c.dim(`step by step in the browser: ${base}/dashboard/welcome`)}`);
12107
+ const cl = o.checklist;
12108
+ if (cl) {
12109
+ console.log(`\n ${c.bold(`${cl.workspace} checklist`)} ${c.dim(`${cl.done} of ${cl.total}${cl.complete ? " — all done" : ""}`)}\n`);
12110
+ for (const i of cl.items ?? []) {
12111
+ console.log(` ${i.done ? c.green("✓") : c.dim("○")} ${i.done ? c.dim(i.title) : c.bold(i.title)}`);
12112
+ if (!i.done) {
12113
+ console.log(` ${c.dim(i.why)}`);
12114
+ console.log(` ${c.dim(`${base}${i.href}`)}`);
12115
+ }
12043
12116
  }
12044
12117
  }
12045
12118
  console.log();
@@ -14550,6 +14623,8 @@ export async function run(command, positional, flags, workspace, layout) {
14550
14623
  return logout(flags);
14551
14624
  case "whoami":
14552
14625
  return whoami(flags);
14626
+ case "signup":
14627
+ return signupCmd(positional, flags);
14553
14628
  case "doctor":
14554
14629
  return doctor(flags);
14555
14630
  case "version":