foldrun 2.7.0 → 2.8.1

package/LICENSE

@@ -1,39 +1,105 @@
-foldrun proprietary licence
+# Functional Source License, Version 1.1, ALv2 Future License
 
-Copyright (c) 2026 foldrun. All rights reserved.
+## Abbreviation
 
-This software, its source code and its documentation are the property of
-foldrun. They are licensed, not sold.
+FSL-1.1-ALv2
 
-You may install and run the foldrun packages published to npm (`foldrun`
-and `@foldrun/core`) to write, check, run and deploy your own agents,
-flows and workspaces, on your own machines and with the foldrun platform.
-That includes the copies installing and running need, for your own use:
-package caches and mirrors, CI and build machines, container images and
-backups.
+## Notice
 
-You may not, except where the law allows it despite this restriction:
-copy, modify, merge, publish, distribute, sublicense, rent or sell the
-software or any part of it; reverse engineer, decompile or disassemble it;
-or use it to build a product or service that competes with foldrun.
+Copyright 2026 foldrun
 
-What you write with the software (your agents, flows, knowledge and other
-files) is yours.
+## Terms and Conditions
 
-Third-party components the software includes or installs (its npm
-dependencies) remain under their own licences.
+### Licensor ("We")
 
-This licence ends automatically if you break its terms, and you must then
-stop using the software.
+The party offering the Software under these Terms and Conditions.
 
-Versions published before 17 October 2026 under the Apache License 2.0
-remain available under that licence for those versions only.
+### The Software
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. TO THE EXTENT THE
-LAW ALLOWS, IN NO EVENT SHALL FOLDRUN BE LIABLE FOR ANY CLAIM, DAMAGES OR
-OTHER LIABILITY ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
-ITS USE.
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
 
-Questions: hello@foldrun.io
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/LICENSING.md

@@ -0,0 +1,101 @@
+# Licensing
+
+foldrun is **source-available** under the **Functional Source License,
+Version 1.1, with an Apache 2.0 future licence** (`FSL-1.1-ALv2`). The full
+terms are in [LICENSE](LICENSE); they are the standard FSL text, unchanged,
+and they are what binds. This page explains them in plain English. If the
+two ever disagree, LICENSE wins.
+
+## In one paragraph
+
+Use foldrun for anything except selling it, or offering it to others as a
+product or service that competes with foldrun. Personal use and use inside
+your own company are free, at any size. Every version becomes Apache 2.0,
+with no restrictions, two years after it is released.
+
+## What you may do, free
+
+- **Use it yourself**: on your laptop, on your own server, for your own
+  agents and flows.
+- **Use it inside your company or organisation**, of any size, for your own
+  work: your team's agents, your internal automations, your CI.
+- **Read, change and fork the code**, and keep your changes private or
+  share them, as long as the result is used for one of the purposes on
+  this list.
+- **Teach and research with it** (non-commercial education and research).
+- **Set it up for a client as a consultant or agency**, as long as the
+  client is the one using it, for their own purposes, under these same
+  terms.
+
+## What needs a commercial licence
+
+The licence calls these a *Competing Use*: making foldrun available **to
+others** in a **commercial** product or service that substitutes for
+foldrun, substitutes for a foldrun product or service that existed when that
+version was released, or offers the same or substantially similar
+functionality. For example:
+
+- running foldrun, or a modified copy, as a hosted agent platform that other
+  people or companies sign up to or pay for;
+- reselling it, white-labelling it, or bundling it into a product you sell
+  whose value is what foldrun does;
+- selling access to a managed foldrun instance.
+
+If you want to do any of these, or are not sure whether your use counts,
+write to **hello@foldrun.io**. Commercial licences are available.
+
+## The two-year rule
+
+Each version is offered under FSL from the day it is released. On the
+second anniversary of that release, that version is **also** available under
+the Apache License 2.0 — irrevocably, for everyone, for any purpose. Newer
+versions are not affected until they reach their own second anniversary.
+
+## Versions released under other terms
+
+| Versions | Licence |
+|---|---|
+| released before 17 October 2026 | Apache License 2.0 |
+| released 17 October 2026 up to the first FSL release | the foldrun proprietary licence that shipped in each package |
+| the first FSL release and later | FSL-1.1-ALv2 (this page) |
+
+A version keeps the licence it was released under.
+
+## What stays yours
+
+What you write with foldrun — your agents, flows, knowledge, skills, tools,
+evals and the outputs of your runs — is yours. This licence covers foldrun's
+code, not your work.
+
+## Name and logo
+
+The licence does not give you the foldrun name, logo or other trademarks,
+except to say truthfully where the code came from. A fork you distribute
+needs its own name.
+
+## Third-party code
+
+foldrun's dependencies, and anything it installs, stay under their own
+licences.
+
+## Patents
+
+Using foldrun for a permitted purpose includes a licence to any foldrun
+patents that use needs. That patent licence ends for anyone who sues claiming
+the software infringes a patent.
+
+## No warranty
+
+foldrun is provided as is, with no warranty, and with no liability for
+damages, as LICENSE sets out in full.
+
+## Contributing
+
+Contributions are welcome. Before we merge one, we ask you to agree that we
+may release it under these terms and under commercial licences, so the
+project can keep both. We will send the agreement with your first pull
+request.
+
+## Questions
+
+hello@foldrun.io. This page is a summary to help you, not legal advice.

package/README.md

@@ -146,8 +146,8 @@ declared the same way.
 | `foldrun storage <verb>` | what a workspace produced: `ls [prefix]`, `cat <path>`, `get <path>` — with when each file was written and which run wrote it. `put <file|folder>...` uploads any files (`--into <folder/>`, `--as <path>` for one), `rm <path>` removes one, and `share`, `shares`, `unshare` manage public links |
 | `foldrun storage put <file>` | upload a file into a workspace's storage (`--as <path>` names it) — also `rm <path>` |
 | `foldrun storage share <path>` | a public link to one produced file (`--ttl <days>`, default 7; `--forever`) — also `shares` (`--all`) and `unshare <token>` |
-| `foldrun billing` | the account's balance and its recent ledger entries, with what each was for |
-| `foldrun billing credit <usd>` | credit added by hand — only on an install without Stripe (self-hosted, dev) |
+| `foldrun billing` | the account's balance and its recent ledger entries, with what each was for — on foldrun's hosted platform (a self-hosted install has no billing) |
+| `foldrun billing credit <usd>` | credit added by hand — on foldrun's hosted platform without Stripe (dev) |
 | `foldrun billing plans` | the plans and this cycle's credits — also `plan <id>`, `plan cancel`, `plan resume`, `top-up <usd>`, `card` (Stripe's own pages for anything with a card) |
 | `foldrun account` | the account's defaults: timezone, notify, budget, concurrency — also `set <key> <value>` and `clear <key>` |
 | `foldrun account providers` | which model providers the account's files use and whether each key still answers (`--check` asks now) |
@@ -234,5 +234,10 @@ wins over the credentials file, so a job never reads one from disk.
 
 ## Licence
 
-Proprietary; see [LICENSE](LICENSE). Versions published before 17 October
-2026 were Apache-2.0 and stay so.
+Source-available under the [Functional Source License 1.1, Apache 2.0 future
+licence](LICENSE) (`FSL-1.1-ALv2`). Use it for anything except offering it to
+others as a competing commercial product or service: personal use and use
+inside your own company are free, at any size. Each version becomes Apache 2.0
+two years after its release. [LICENSING.md](LICENSING.md) explains what is
+allowed and what needs a commercial licence (hello@foldrun.io), and which
+licence earlier versions shipped under.

package/docs/api-usage.md

@@ -36,7 +36,7 @@ Every response says which version answered it, in `Foldrun-Version`.
 - **An unknown version** — a typo, a date that was never released, one
   retired after its support window — is a `400`, not a silent fallback to
   current. The body says why in a form code can act on:
-  `{ "error": "…", "code": "unknown_api_version", "known": ["2026-10-01"] }`
+  `{ "error": "…", "code": "unknown_api_version", "known": ["2026-10-01", "2026-10-26"] }`
   (`code` is `bad_api_version` when the header is not a `YYYY-MM-DD` date).
 - **What moves the version**: only a change an existing caller would break
   on — a field removed or renamed, a type changed, a status code changed. A
@@ -46,6 +46,13 @@ Every response says which version answered it, in `Foldrun-Version`.
   pinned before it gets the response transformed back to the shape its
   version promised.
 
+The versions so far:
+
+| Version | What changed |
+|---|---|
+| `2026-10-26` | `GET /api/usage`: `ledger.providerCostUsd` and `ledger.marginUsd` are withdrawn. They were the platform's own accounting of your lines, not part of your account. A caller pinned to `2026-10-01` still gets both keys, as `null`: the values are withheld, not reproduced. |
+| `2026-10-01` | The first dated version. Every CLI released so far sends it. |
+
 The CLI sends the version it was built for on every call. When a platform
 refuses it, every command stops with exit 1 and says which side is older:
 a platform older than the CLI names the CLI released with it

package/docs/api.md

@@ -343,7 +343,7 @@ Reads return which secrets exist, never their values.
 | `/api/usage/history?days=` | GET | charged spend by flow, by agent and by workspace over time, read from the ledger rather than the run records — so it survives runs being pruned and reports what was billed rather than what was consumed. Buckets by week over three weeks, by day under. Each series carries its periods, its total, and the change between the last two COMPLETE periods, so a partial week never reads as a collapse. `unattributedUsd` is charges from before a line recorded its flow. A caller scoped to some workspaces sees only the charges in those; `days` 1–365, default 56 |
 | `/api/account/model` | GET, PUT, DELETE | the account's own model key — what every step runs on unless an agent, workspace or the account's AGENTS.md names a `provider:`. GET: `{ set, provider, baseUrl, format, keyHint, runsOn, platformKeyAllowed }` — never the key, only its last four characters; `runsOn` is `account` (its own key), `platform` (the platform's credential, for the operator's accounts) or `none` (runs are refused until a key is set). PUT `{ provider, apiKey, baseUrl?, format? }` (needs `secrets:write`): `provider` is a preset name (anthropic, openrouter, openai, groq, … — see providers) or `custom` with an https `baseUrl` and a `format` (anthropic or openai); a Claude login token (sk-ant-oat…) is refused for any account not allowed the platform's credential. Stored as the account secrets `FOLDRUN_MODEL_PROVIDER`, `FOLDRUN_MODEL_API_KEY`, `FOLDRUN_MODEL_BASE_URL`, `FOLDRUN_MODEL_FORMAT`. DELETE removes them. Honours Idempotency-Key on PUT; audited as model.key_set / model.key_removed |
 | `/api/account/providers` | GET, POST | GET: the model providers this account's files actually use — each one's preset name, where it is declared, the model a check would send — plus the last daily health check. POST forces one now, which spends one minimal request at each distinct endpoint, and needs the permission that runs |
-| `/api/usage` | GET | what has been spent, by meter; each bucket's tokens are `inputTokens` (all input), `outputTokens`, `cacheReadTokens` and `cacheWriteTokens` (the part of the input the prompt cache served and stored), and `cacheHitRate` — reads over `measuredInputTokens`, the input of steps that report the split, `null` when none do. A key or member scoped to some workspaces sees those workspaces, and totals over them; the ledger figures are the account's, as the wallet's are |
+| `/api/usage` | GET | what has been spent, by meter; each bucket's tokens are `inputTokens` (all input), `outputTokens`, `cacheReadTokens` and `cacheWriteTokens` (the part of the input the prompt cache served and stored), and `cacheHitRate` — reads over `measuredInputTokens`, the input of steps that report the split, `null` when none do. A key or member scoped to some workspaces sees those workspaces, and totals over them; `ledger` is the account's `balanceUsd` and `chargedUsd` (all time), the account's as the wallet's are — since API version `2026-10-26` nothing else; earlier pins see `providerCostUsd` and `marginUsd` as `null` |
 | `/api/approvals` | GET | every gate waiting on a person, across workspaces — one entry per waiting **step** (`workspace`, `runId`, `flow`, `step`, `agent`, `question`, `asked`, `waitingSince`), oldest first. By step status, not run status: a decided gate leaves the list at once, before the worker resumes the run. `wait: event` steps are not listed; no button answers them. Beside it, `questions`: every question an agent is asking mid-step in a running run (`kind: "question"`, `id`, `workspace`, `runId`, `flow`, `agent`, `question`, `options?`, `askedAt`) — answered with `…/runs/<id>/answer` |
 | `/api/insights?days=&workspace=` | GET | recurring problems found in the runs of the window (see [Runs](runs#insights)): `{ days, insights: [{ id, kind, workspace, agent, tool?, title, why, fix, credits, steps, evidence: [{ workspace, runId, step }] }] }`. `kind` is `cache` (an agent's big prompt mostly uncached), `big-result` (a tool result over 20k characters sent again on every later model call), `retry-loop` (a tool erroring three or more times in a step) or `timeout` (steps using 80% or more of their `timeout:`); `credits` is about what it cost in the window, null when it is not money. `days` 1–30, 7 unasked. A key scoped to some workspaces sees theirs |
 | `/api/issues?status=&workspace=` | GET | the account's issues: what went wrong, grouped and kept open until a person resolves it (see [Runs](runs#issues)). One issue is one desk's flow failing at one agent, or ending BLOCKED or BAD, or one platform cause across desks. Each carries `id`, `kind` (`platform`, `failed`, `blocked`, `bad`, `missed` — a scheduled fire that started no run), `status` (`open`, `acknowledged`, `snoozed`, `resolved`), `regressed` and `sinceRevision` (it was resolved and came back, since the revision its new run ran), `snoozedFor`, `workspace`/`workspaces`, `what`, `agent`, `reason`, `action` (what to do), `firstSeen`, `lastSeen`, `count`, the newest `runs`, `recoveredAt` (the flow's newest good run since — it closes nothing), `acknowledged`, `snoozedUntil`, `resolved` and the `history` of what people did. `status` is `active` unasked (open + acknowledged), or `open`, `acknowledged`, `snoozed`, `resolved`, `all`; `workspace` keeps the ones that hit it. A key scoped to some workspaces sees the issues of those |
@@ -419,7 +419,7 @@ so a client learns what it is talking to without a second request:
 
 ```
 X-Foldrun-Version: v2026.10.01.3   # the platform's version
-X-Foldrun-Api: 2026-10-01          # the API contract — moves only on a breaking change
+X-Foldrun-Api: 2026-10-26          # the API contract — moves only on a breaking change
 X-Foldrun-Cli: 0.6.0               # the CLI released with this version (absent when unknown)
 ```
 

package/docs/cli.md

@@ -149,7 +149,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
 | `foldrun billing` | the account's balance, whether billing is on at all, what the platform is currently waiving, and the recent ledger entries with what each was for — a run names its workspace, flow and run id; an adjustment carries its own note. `--limit <n>` shows more. `statement [YYYY-MM]` is a month of the ledger (this month by default) — `--csv` for the file an accountant wants, to stdout or `--file <path>`. `wallet` is the burn, the runway and auto top-up; `wallet set auto-top-up --threshold <usd> --amount <usd>` turns it on (a refill of 5–500), `set auto-top-up off` turns it off, `set email <address>` is where receipts go. `details` is who invoices are made out to; `details set --name "…" --abn … --address "line1, city, state, postcode, AU" --email …` changes it, merged with what is there. `portal` prints a link to Stripe's billing portal. Changing the wallet, the details, and the portal are the account owner's; anyone else is told so |
 | `foldrun billing plans` | the Plans page: every plan with its monthly fee, credits, runs at once and workspaces, which one the account is on and this cycle's credits left (`GET /api/billing/plans`). `billing plan <id>` chooses one — a first plan answers with Stripe's checkout page, a change on a live plan is prorated at Stripe at once (asks first; `--yes`); `plan cancel` stops it at the end of the cycle, `plan resume` undoes that until then (`POST`/`DELETE /api/billing/subscribe`) |
 | `foldrun billing top-up <usd>` | the Payment page's top-up: Stripe's checkout page for that amount, opened in the browser (`--no-browser`, or no terminal, prints it). The credit lands when Stripe confirms the payment. `billing card` is the same for saving a card for auto top-up. Both need `billing:manage` |
-| `foldrun billing credit <usd>` | put credit on the balance by hand (`POST /api/billing { usd, note }`, `--note "…"` on the ledger line) — only on an install without Stripe, a self-hosted or dev platform; once billing is live the platform refuses it and top-ups go through `billing top-up`. The dashboard's Billing → Add credit does the same while billing is off. Needs `billing:manage` |
+| `foldrun billing credit <usd>` | put credit on the balance by hand (`POST /api/billing { usd, note }`, `--note "…"` on the ledger line) — on foldrun's hosted platform where Stripe is not connected (a dev install); once billing is live the platform refuses it and top-ups go through `billing top-up`. The dashboard's Billing → Add credit does the same while billing is off. Needs `billing:manage`. A self-hosted install has no billing |
 | `foldrun gallery` | the tools the platform ships to every account (`web`), and for each whether this account keeps its own copy and whether that copy still matches. `pull` lays the shelf down under `~/.foldrun/gallery/<host>/` for offline runs (`foldrun run` and `foldrun eval` refresh it themselves before each run); `upgrade <tool>` replaces the account's copy with the current gallery version, the old one a revision back |
 | `foldrun identity` | keyless cloud identity: the issuer your cloud must trust and the subject each agent's tokens carry (`GET /api/identity`); `--to <workspace>` fills the workspace in, `--json` |
 | `foldrun jobs` | the four jobs — governance, guardrail, observability, evaluation — and every `AGENTS.md` field of each, with what is set (`GET /api/account/jobs`). `--to <workspace>` shows the workspace's value beside the account's and how the two combine; `--json` the document. `account set <job>.<field>` and `workspace set <job>.<field>` refuse a field that scope cannot set and name the `AGENTS.md` to write it in. See [The four jobs](four-jobs) |

package/docs/introduction.md

@@ -32,12 +32,14 @@ The design bets on three things:
 | | you need | what runs where |
 |---|---|---|
 | **Locally** | `npm install -g foldrun` and a model key | everything on your machine; no account, no server |
-| **Hosted** | an account | ours: schedules, sandboxes, a vault, a team |
+| **Your own server** | Docker and the public repositories | the whole platform on one machine of yours, for you or your organisation |
+| **Hosted** | an account | ours: schedules, sandboxes, a vault, a team — nothing to run |
 
 The same workspace moves between them with `foldrun deploy`.
-Start locally; that is where every workspace should be born. The CLI and
-runtime are free from npm; the platform is not distributed — see
-[Running it yourself](self-hosting).
+Start locally; that is where every workspace should be born. foldrun is
+source-available under the Functional Source License: free for your own
+use and your organisation's, not for offering it to others as a service —
+see [Running it yourself](self-hosting).
 
 ## Where to go
 

package/docs/self-hosting.md

@@ -1,20 +1,58 @@
 # Running it yourself
 
-There are two places a workspace runs, and the same folder moves between
+There are three places a workspace runs, and the same folder moves between
 them unchanged.
 
 | shape | for | what is yours |
 |---|---|---|
 | **your machine** | one person, no server — the foldrun CLI and runtime, free from npm | everything: the files, the runs, the model bill |
-| **the hosted platform** | a team; schedules, sandboxes, gates, a vault, a dashboard | your workspaces and their records; we run the machines |
-
-The framework — the format, the runner, the checks, the CLI — is free to
-install from npm (`foldrun`, `@foldrun/core`) and use under foldrun's
-licence, which ships in each package. The platform that runs it
-for other people (the queue and its worker, per-step sandboxes on a cluster,
-metering, tenancy) is ours and is not distributed: there is no self-hosted
-platform. If you need it inside your own network, that is a conversation —
-write to hello@foldrun.io.
+| **your own server** | you or your organisation on one machine: the dashboard, schedules, sandboxes, gates, a vault and a team, with Docker Compose | everything, and the machine |
+| **the hosted platform** | a team that would rather not run anything | your workspaces and their records; we run the machines |
+
+foldrun is **source-available** under the Functional Source License 1.1
+(FSL-1.1-ALv2): the format, the runner, the checks, the CLI, the engine and
+the dashboard are free to use, change and run for yourself and inside your
+own organisation, at any size. What needs a commercial licence is offering
+foldrun to others as a product or service that competes with it. Each
+release becomes Apache 2.0 two years after it ships. The licence and a
+plain-English summary are in each repository (`LICENSE`, `LICENSING.md`);
+for a commercial licence, write to hello@foldrun.io.
+
+A self-hosted server has no billing: nothing is charged, and spend budgets
+(`budget:`) still hold.
+
+## Your own server
+
+One machine with Docker. The platform runs in one container — the dashboard,
+the API, the scheduler and the queue — and every agent step runs in a
+throwaway container beside it, started through the Docker socket.
+
+```sh
+mkdir foldrun && cd foldrun
+for r in foldrun-core foldrun-platform foldrun-web foldrun-docs; do
+  git clone https://github.com/foldrun-io/$r
+done
+cd foldrun-web/self-hosting
+echo "FOLDRUN_SECRET_KEY=$(openssl rand -hex 32)" > .env
+echo "FOLDRUN_PUBLIC_URL=http://<host>:3900" >> .env   # the address people open
+docker compose up -d --build
+```
+
+Then open `http://<host>:3900/signup` (the first account needs no flag),
+sign the CLI in to it, and deploy an account folder:
+
+```sh
+npm install -g foldrun
+foldrun login --url http://<host>:3900   # approve in the browser; or --token <a key from Settings>
+foldrun deploy                           # from the account folder
+```
+
+`docker-compose.yml` beside the Dockerfile lists every setting with what it
+does: the install's model key (or none, and each account brings its own),
+open sign-up (off), retention. `FOLDRUN_PUBLIC_URL` is required: CLI sign-in,
+approve links, password resets and shares are made with it, so it must be
+the address people actually open. Back up the `foldrun-data` volume and `FOLDRUN_SECRET_KEY` and
+you have backed the install up.
 
 ## Your machine
 

package/docs/versions.md

@@ -119,8 +119,8 @@ whatever `FOLDRUN_VERSION` it was started with.
 ## The API version
 
 `api` in `/api/version`, and the `X-Foldrun-Api` header, is a date —
-`2026-10-01` — that changes only when a route changes in a way an existing
-caller would break on. A new route or a new field in an answer does not move
+`2026-10-26` now, after `2026-10-01` — that changes only when a route changes
+in a way an existing caller would break on ([the list](api-usage#versions)). A new route or a new field in an answer does not move
 it. Breaking changes are announced in the release notes of the version that
 makes them.
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "foldrun",
-  "version": "2.7.0",
+  "version": "2.8.1",
   "description": "Agents are just folders. Write them, check them, run them — on your machine.",
-  "license": "SEE LICENSE IN LICENSE",
+  "license": "FSL-1.1-ALv2",
   "type": "module",
   "bin": {
     "foldrun": "bin/foldrun.mjs"
@@ -11,12 +11,13 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@foldrun/core": "^2.11.0"
+    "@foldrun/core": "^2.12.1"
   },
   "files": [
     "bin",
     "src",
     "README.md",
+    "LICENSING.md",
     "docs"
   ],
   "scripts": {
@@ -46,7 +47,7 @@
   "devDependencies": {
     "@types/node": "^26.6.4",
     "gray-matter": "^4.0.3",
-    "typescript": "^6.0.3"
+    "typescript": "^7.0.2"
   },
   "overrides": {
     "zod": "4.6.7"

package/src/commands.mjs

@@ -883,6 +883,7 @@ async function scanCore() {
 }
 
 // The scanner module, once scanCore has loaded it — categoryOf and SARIF read it.
+/** @type {any} */
 let scanRules = null;
 
 const SECURITY_CATEGORIES = new Set(["secret", "security", "content", "supply-chain"]);
@@ -1027,6 +1028,7 @@ function narrowCheck(findings, root, opts, label, accountRoot = root) {
   }
   let baselined = 0;
   if (opts.baseline && fs.existsSync(file)) {
+    /** @type {any} */
     let b = null;
     try {
       b = JSON.parse(fs.readFileSync(file, "utf8"));
@@ -1540,6 +1542,7 @@ async function checkHooks(workspace, agents, libraryRoot, platform, note) {
   missing("account AGENTS.md", accountNames);
   missing("AGENTS.md", workspaceNames);
 
+  /** @type {any} */
   let resolveSearch = null;
   try {
     ({ resolveSearch } = /** @type {any} */ (await import("@foldrun/core/providers")));
@@ -1812,6 +1815,7 @@ async function probeCmd(modelArg) {
   // provider gets the same translator a run would, on loopback, for the
   // length of the probe — so what passes here passes there.
   let env = { ...process.env };
+  /** @type {any} */
   let translator = null;
   // No AGENTS.md, or no provider block, means Anthropic direct — like a run.
   // Anything else that goes wrong here is said, not swallowed: a provider
@@ -2446,6 +2450,7 @@ async function versionCmd(flags) {
   const url = remoteUrl(flags);
   /** @type {Record<string, any> | null} */
   let platform = null;
+  /** @type {string | null} */
   let unreachable = null;
   if (url) {
     try {
@@ -3671,6 +3676,7 @@ async function connect(positional, flags) {
   // secret, nothing typed. The redirect is the platform's own callback, which
   // rewrites the same secret at the same scope; we wait for it to land.
   if (url && !flags["client-id"] && !env("OAUTH_CLIENT_ID") && flags["new-client"] !== true) {
+    /** @type {any} */
     let started = null;
     try {
       started = await remoteCall(url, flags, "/api/oauth/reconnect", {
@@ -4492,6 +4498,7 @@ async function deployAccount(layout, flags, only) {
 
 /** "<profile> (<email or key label>)" — who a deploy is about to act as,
  *  asked of the platform once per command. */
+/** @type {string | null} */
 let identityCache = null;
 async function deployIdentity(url, flags) {
   if (identityCache) return identityCache;
@@ -4889,6 +4896,7 @@ async function pullCmd(layout, flags, only) {
 
   let written = 0;
   for (const f of incoming) {
+    /** @type {string | null} */
     let before = null;
     try {
       before = fs.readFileSync(f.file, "utf8");
@@ -4968,6 +4976,7 @@ async function workspacesCmd(positional, flags, layout) {
 
   const here = layout.workspaces;
   let there = [];
+  /** @type {string | null} */
   let reach = null;
   if (url) {
     try {
@@ -5591,16 +5600,12 @@ async function billingCmd(flags) {
   const entries = body.entries ?? [];
 
   console.log(`\n  ${balance > 0 ? c.green("✓") : c.red("✗")} balance ${c.bold(`$${balance.toFixed(2)}`)}  ${c.dim(body.enabled ? "billing on" : "billing off — nothing is charged on this install")}`);
-  if (body.enabled && balance <= 0) {
-    console.log(`  ${c.red("the wallet is empty")} ${c.dim("— the account is in overdraft; top it up before anything is expected to run")}`);
-  }
-
-  // What the platform is waiving says more than the balance does: a run
-  // charged $0 with models waived is a run whose model credit is being
-  // absorbed, and that is the state people mistake for "it is working".
-  const waived = [...new Set(entries.flatMap((e) => e.waived ?? []))];
-  if (waived.length) {
-    console.log(`  ${c.amber("⏸")} ${c.dim(`${waived.join(", ")} ${waived.length === 1 ? "is" : "are"} being waived on recent runs — those lines are charged $0`)}`);
+  // What the account should be told — an empty wallet, an overdraft, a
+  // waiver — as the platform words it: it knows the gate, the overdraft and
+  // the waivers; the numbers here do not say enough to guess.
+  for (const notice of Array.isArray(body.notices) ? body.notices : []) {
+    const empty = /wallet is empty/.test(notice);
+    console.log(`  ${empty ? c.red("✗") : c.amber("⏸")} ${empty ? notice : c.dim(notice)}`);
   }
 
   const limit = Number(flags.limit) > 0 ? Math.floor(Number(flags.limit)) : 15;
@@ -8068,6 +8073,7 @@ function writeIfUnchanged(desk, rel, before, next) {
 
 /** Throw, as writeIfUnchanged does, when a desk file no longer reads `before`. */
 function assertUnchanged(desk, rel, before) {
+  /** @type {string | null} */
   let now = null;
   try {
     now = fs.readFileSync(path.join(desk.dir, rel), "utf8");