foldrun 0.6.0 → 0.8.0

package/docs/self-hosting.md

@@ -0,0 +1,65 @@
+# Running it yourself
+
+There are two places a workspace runs, and the same folder moves between
+them unchanged.
+
+| shape | for | what is yours |
+|---|---|---|
+| **your machine** | one person, no server — the open-source CLI and runtime | 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 Apache-2.0
+on [GitHub](https://github.com/foldrun-io) and npm. 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 machine
+
+```sh
+npm install -g foldrun
+export ANTHROPIC_API_KEY=...            # an API key; or any provider via provider:
+foldrun init my-desk
+cd my-desk && foldrun check && foldrun run publish
+```
+
+Everything the format defines works here: agents, flows with groups and
+gates, tools in any language, skills, knowledge bundles, evals, `verify:`,
+`each:`, `budget:`. Runs are recorded under `.foldrun/` beside the workspace;
+secrets set with `foldrun secrets set` are encrypted there under a key the
+CLI makes on first use.
+
+What is different from the platform, and why:
+
+- **No schedules.** Nothing is running when your laptop is closed. `foldrun
+  run` is the trigger; cron on your own machine works if you want one.
+- **No sandbox by default.** Steps run as your user, in your workspace. Set
+  `FOLDRUN_RUN_ISOLATION=container` with Docker installed to get one hardened
+  container per step, the same executor the platform's single-box shape uses.
+- **Gates wait in the terminal.** A `!` step parks the run; `foldrun run`
+  shows the approval and waits for your answer.
+- **Budgets cap, and nothing meters.** `budget:` stops a run at its cap; the
+  cost of each step is on the record. No invoice, because the model bill is
+  yours.
+
+## Moving to the platform
+
+```sh
+foldrun login
+foldrun deploy                           # this folder → a workspace with the same name
+```
+
+Or push it: every workspace on the platform is a git remote. Nothing about
+the folder changes. What the platform adds is the operating around it —
+[Scheduling](scheduling), [Runs](runs) in gVisor sandboxes,
+[Secrets](secrets) in a vault, [Notifications](notifications),
+[Budgets and billing](budgets-and-billing), [Team and access](team-and-access).
+
+## Where the data is
+
+On your machine: in the folder. On the platform: your workspace's files and
+every run's record, on our data volume and in the file store, readable
+through the dashboard and the API, exportable as a git clone. A deploy never
+touches what an agent learned or a run recorded. See [Storage and
+sharing](storage-and-sharing) and [Security](security).

package/docs/status.md

@@ -0,0 +1,73 @@
+# Status and incidents
+
+Is it us or is it you? The platform answers that itself, in three places
+that read the same record:
+
+- **The status page** — [foldrun.io/status](https://foldrun.io/status/). A
+  static page on the website, not on the platform, so it still loads when
+  the platform does not. If it cannot reach the platform it says so: *status
+  unavailable — the platform may be down*, which is itself the answer.
+- **The dashboard banner** — an amber line across every page during
+  maintenance or a minor incident, red during a major one, with the latest
+  update. It goes when the incident is resolved. **Status** in the account
+  menu opens the status page.
+- **`foldrun status --platform`** — the same, in a terminal (`--json` for a
+  script). Plain `foldrun status`, which compares your folder with what is
+  deployed, now opens with one line saying whether the platform is
+  operational and lists any live incident.
+
+## What each component means
+
+| Component | Operational when | Measured from |
+|---|---|---|
+| Dashboard and API | the web tier answers and its database does | the request itself; the worker also fetches `/api/healthz` through the public address every five minutes |
+| Run workers | a worker holds the lease and nothing queued has waited over ten minutes | the worker lease and the queue's oldest job |
+| Scheduler | it has ticked in the last fifteen minutes | the samples themselves — they are written from inside the scheduler's tick, so a stale sample *is* a stopped scheduler |
+| Model providers | `api.anthropic.com` answers, and fewer than two step attempts in the last hour failed with a provider error (overloaded, rate limited, a 5xx; a refused credential only when two accounts saw one — one account's own expired key is that account's) | a reachability check, and the run records |
+| Email | `api.resend.com` answers | a reachability check; `unknown` on an install without a platform mail key |
+| Storage | the database answers and the workspace volume is writable | the same checks `healthz` makes |
+
+Each is `operational`, `degraded`, `outage`, `maintenance` or `unknown`
+(not measured — not counted against uptime). An incident or maintenance
+window the operator posted raises the components it names: a minor incident
+to `degraded`, a major one to `outage`.
+
+## Uptime history
+
+Every five minutes the worker that holds the scheduler lease records one
+sample per component. Ninety days are kept. A day's uptime is the share of
+its measured samples that were not an outage; a day with no samples has no
+figure rather than a hundred per cent. The status page draws these as 90
+bars per component, with the incidents of the same period below.
+
+These are the platform's own measurements of itself, from inside. They do
+not see a network problem between you and the platform — the page saying
+*unavailable* does.
+
+## Incidents and maintenance
+
+The super admin posts them from **Admin → Incidents** (or
+`/api/admin/incidents`): a title, what customers should read, the impact
+(minor or major) and the components affected. Each update adds a line with
+a status — `investigating`, `identified`, `monitoring`, `resolved`.
+Maintenance is a window with a start and an end; it shows as upcoming before
+it starts and as `maintenance` while it runs. Incidents are resolved, not
+deleted, so the history stays; deleting is for one posted by mistake. Every
+change is in the audit log as `status.*`.
+
+What customers see never includes who wrote an update.
+
+## Reading it from code
+
+`GET /api/status` and `GET /api/status/history?days=90` are open — no key —
+and readable cross-origin from foldrun.io. See [the API](api) for the
+shapes. The answer to `/api/status` is cached for fifteen seconds and never
+calls a provider per request.
+
+## On your own install
+
+The same routes and sampler run on a self-hosted install. Point the
+dashboard's **Status** link at your own page with `FOLDRUN_STATUS_PAGE_URL`,
+allow your page's origin with `FOLDRUN_STATUS_ORIGINS`, and see
+[Environment](environment) for the rest. Without a database, samples and
+incidents are files under `<data>/status/`.

package/docs/storage-and-sharing.md

@@ -0,0 +1,118 @@
+# Storage and sharing
+
+Two kinds of file live in a workspace, and the dashboard shows them on two
+pages. **Files** is the markdown source — agents, flows, tools, knowledge —
+the thing you edit and deploy. **Storage** is bytes: what agents produce
+and what people upload — reports, CSVs, images, PDFs. This page is about the
+second.
+
+## Where it lives, from an agent's point of view
+
+An agent writes a deliverable to `workspace/storage/` (the older
+`../../storage/` is the same place) and it appears on the workspace's Storage page after the
+step, kept and downloadable. Uploads dropped on that page land in the same
+directory and are there for the next run to read.
+
+Two neighbours are not storage:
+
+- **`outputs/`** is the step's scratch, archived with the run — read it from
+  the run page, not from Storage.
+- **`state/`** is what the next run needs — a cursor, a history line — and a
+  person rarely reads it.
+
+The rule: a value regenerated each run is `storage/`; a value accumulated
+across runs is `state/`.
+
+## Limits
+
+One object up to 512 MB; a workspace up to 5 GB, shown on the Storage page.
+Both are platform settings (`FOLDRUN_STORAGE_MAX_MB`,
+`FOLDRUN_STORAGE_QUOTA_MB`). Storage is metered per GB-month where billing is
+on.
+
+## Under the hood
+
+Blobs are content-addressed and go to object storage (S3-compatible — R2, S3
+— or local disk on a small install); the index of what exists stays with the
+workspace. Uploading the same bytes under a second name costs nothing, and a
+rename moves no data. A run pod never holds the bucket credential: it reads
+and writes through presigned URLs, so a step that goes wrong cannot list or
+delete what other workspaces stored.
+
+## Sharing a file
+
+Some work is not done until something outside can fetch the bytes — a
+Google Business Profile post will not accept image data and wants a URL it
+can GET for itself. A share is a public link to one file:
+
+```
+POST /api/workspaces/<ws>/shares   { "path": "storage/cover.jpg", "ttlDays": 7 }
+→ https://<your-install>/s/<token>
+```
+
+or **Share** on the run page's Out column, or on the Storage page, or from
+the terminal:
+
+```
+foldrun storage share cover.jpg --to <ws>        # 7 days; --ttl 30, or --forever
+foldrun storage shares --to <ws>                 # live links; --all shows expired and revoked
+foldrun storage unshare <token> --to <ws>
+```
+
+- Links expire in **7 days** unless you say otherwise; `null` never expires.
+- The token is 24 random bytes and never derived from the path; every failed
+  fetch is the same 404, so a guesser learns nothing.
+- Only `storage/`, `outputs/` and `files/` can be shared. An agent talked
+  into sharing is confined to what the workspace produced and can never hand
+  out `memory/`, a prompt, or a credential.
+- Revoking is permanent; a re-share mints a new token.
+
+Files written under **`storage/public/`** get a link automatically after the
+run — for the agent that needs a URL for what it just produced.
+
+Shares need the install to know its public address (`FOLDRUN_PUBLIC_URL`);
+without it the request answers `409` rather than minting a link that only
+works from inside.
+
+A share is a record the platform keeps, not a file in the workspace: minted
+from the dashboard or after a step, it lands in the platform's database,
+so every web and worker process sees the same links and a link survives a
+workspace being redeployed.
+
+## The account view
+
+Storage at the account level lists every workspace as its own section, each
+closed until you open it, with each file's size, age and share state. It is a
+view: a run still sees only its own workspace's folder.
+
+You can upload any file, of any type, to any workspace from there. Use
+**Upload** in the toolbar and pick the workspace, use the **Upload** button on
+a workspace's section, or drop files onto that section. From a terminal,
+`foldrun storage put` does the same, and it takes folders whole:
+
+```sh
+foldrun storage put report.pdf photos/ --into inspections/ --to blog-desk
+foldrun storage put draft.md --as drafts/today.md --to blog-desk
+```
+
+## Previews
+
+Click a file to read it without downloading it. Images, video, audio, PDFs
+and fonts play in the browser as themselves. Everything else is parsed on the
+server and drawn as what it is:
+
+| What | Formats |
+|---|---|
+| text and code | txt, md, mdx, json, yaml, csv as a table, source files, logs, anything that reads as text |
+| office | docx, xlsx, pptx, odt, ods, odp, rtf; legacy doc, xls and ppt as their text |
+| Apple and design | pages, numbers, key, sketch, xd by the preview picture inside them |
+| camera and layered images | RAW (cr2, nef, arw, dng and others), psd, tiff, heic by their embedded preview; svg and svgz as a picture |
+| mail and contacts | eml, mht, ics, vcf |
+| notebooks and links | ipynb, url, webloc |
+| archives | zip, tar, tgz, gz by their contents; 7z, rar and others by name only |
+| 3D | stl, obj, ply, glb, drawn and turned by dragging |
+
+A stored web page opens in a sandboxed frame with scripts off, and an SVG
+only as an image, so a file cannot run code on the dashboard. Anything the
+preview cannot read shows its first bytes, and the download button always
+gives the file itself. Files over 25 MB are not previewed.

package/docs/team-and-access.md

@@ -0,0 +1,146 @@
+# Team and access
+
+Every member and every API key has a role, and every write route asks for
+the least role that may take that action. Reads are open to every role: a
+viewer sees everything, including run output and files, because a platform
+whose supervisors cannot see what the agents did is not supervised.
+
+## Roles
+
+| role | may |
+|---|---|
+| **viewer** | read everything — workspaces, runs and their output, files, history, usage |
+| **editor** | + edit files, upload, deploy, push; run, stop, re-run, approve and promote runs; test tools |
+| **admin** | + create and delete workspaces; write secrets and connect credentials; mint keys; invite, re-role and remove editors and viewers |
+| **owner** | + billing; make and unmake admins; transfer the account |
+
+There is exactly one owner: the account's creator until they transfer it.
+The owner is never re-roled or removed — transfer first. Nobody changes their
+own role, and an admin cannot make or remove another admin: an admin who can
+promote peers is an owner with extra steps.
+
+A refused call answers `403` with the role that was needed.
+
+## Scoped members
+
+A member can be limited to some workspaces. The customer whose desk lives in
+one workspace sees that workspace's runs and files and nothing else; the
+sidebar, Find, the runs list and the approvals banner all filter to their
+scope. Scope is set on the invite and changed per member later.
+
+Secrets and OAuth connections follow the scope too. A scoped member or key
+sees and changes only its own workspaces' secrets and connections: not
+another workspace's, and not the account-level ones, which belong to
+everyone's workspaces at once.
+
+## Invites
+
+An invite carries a role, a workspace scope, and an email address it is bound
+to — only that address can accept it. It is sent through the account's email
+connection, or returned as a link to pass on yourself.
+
+## API keys
+
+A key is minted with a role (`editor` unless you say otherwise) and acts as
+the account with that role. It can never be wider than the person who made
+it: not a higher role, and not a workspace they cannot open — a key minted
+by someone scoped to two workspaces is scoped to those two. The git remote
+honours the same scope: pushing needs write on that workspace, and pushing
+the library needs admin. Two things a key cannot do: act against a named
+member — inviting, re-roling, removing, transferring need a signed-in person,
+because a key names an account and never a who — and exceed its role.
+A scoped admin sees and revokes only keys inside its own scope; a key wider
+than that, the owner's included, is not in its list.
+
+**Deploy keys** are keys scoped to one workspace's git remote, read or write.
+They clone and push that workspace and are refused everywhere else, which is
+what a CI job or a contractor's checkout should hold.
+
+A key **is** its account: the platform reads the account off the key, so one
+account's key can never reach another's workspaces. Someone who looks after
+several accounts — an agency, a reseller — holds one key per account and
+switches between them; the CLI stores each as a named profile. See
+[More than one account](cli#more-than-one-account).
+
+### Expiry, last use and rotation
+
+A key can be given an end when it is minted — 30, 90 or 365 days, or never
+(Settings → API keys offers 90 days first; `foldrun keys create ci --expires
+90d`; the API's `expires`). After it, the key is refused with a 401 that
+says it expired and on which day. The owner is emailed seven days before any
+key ends, once per key.
+
+Every key shows when it was created, when it was **last used** and roughly
+from where — the address cut to its /24 (or /48 for IPv6), never the whole
+of it. Last use is written at most once a minute per key, so a busy CI key
+does not turn every request into a write.
+
+**Rotate** mints a new key with the old one's label, role, workspaces and
+deploy scope — and, if the old one had an end, the same lifetime from today —
+and ends the old key: at once, or after a grace of an hour or a day so a CI
+job can be moved across first. In the dashboard it is the Rotate button on
+the key; `foldrun keys rotate <id> --grace 1h`; `POST /api/keys/<id>/rotate`.
+
+A key is rotated **once**. While the old key runs out its grace it shows
+**rotated → <new key>** (in `foldrun keys ls` too), and rotating it again is
+refused with `this key was already rotated to <prefix>…; rotate that one`.
+Lost the new key's secret? Rotate the **new** key: that mints another and
+ends the lost one. Rotating the old key again would have left the lost key
+working.
+
+## Audit log
+
+Settings → Audit log is the account's record of what people did: sign-ins
+(and refused ones), sign-outs and session revokes, password and email
+changes, MFA turned on or off, keys minted, rotated and revoked, invites,
+joins, role and scope changes, removals and ownership transfers, secrets
+set and deleted — **by name, never the value** — deploys, workspace deletes,
+plan and billing changes, the account export and a close request, and every
+time support viewed the account. Filter by time, action, person or
+workspace, page back, and download it as CSV for an auditor.
+
+The owner and admins who can open every workspace read it — people, or an
+`admin` key. A member or key scoped to some workspaces cannot: the log is
+the whole account's. It is the caller's own account, always; another
+account's entries are never in it. Entries are kept for the life of the
+account (no plan sets a shorter retention) and go when the account is
+deleted. Also `GET /api/audit` and `foldrun audit --since 7d --csv`.
+
+What agents did is a different record: every run's trail, under Runs.
+
+## Support access
+
+When you ask for help, foldrun support may open your account **read-only**
+to look: your dashboard as the owner sees it, for thirty minutes at most.
+They must give a reason, and it lands in your audit log word for word —
+"support viewed your account: Ticket 42: daily flow not starting" — with
+another line when the view ends. While it is open every change is refused,
+in one place for every route: nothing can be run, deployed, edited,
+invited, revoked or paid for, and the account export is refused too. The
+support person sees a bar on every page saying whose account it is, that it
+is read-only, how many minutes are left, and an Exit.
+
+There is no API key or CLI command for this, on purpose: looking inside a
+customer's account is an act a named person owns, from a browser, with a
+reason you can read.
+
+## Sessions
+
+Signing in creates a session; your Profile page lists them and revokes any
+one of them, which signs that device out without touching the others.
+Changing your password or email signs out every other session, and says
+how many. Sign-
+ins, key use and role changes are written to the account's audit log.
+
+## Appearance
+
+The dashboard comes in light and dark. **Profile → Appearance** picks one:
+**System** (the default) follows your computer's light or dark setting,
+**Light** and **Dark** stay put whatever it says. The choice is yours alone
+— it is kept on your profile, not in the browser, so it follows you to every
+browser you sign in on, and the page is drawn in it from the first paint.
+The sign-in pages, before anyone is signed in, follow the computer.
+
+The API is `GET` / `PATCH /api/me/preferences` with `{ theme }`. There is no
+CLI verb: a theme is how a browser draws the dashboard, and a terminal
+already draws in its own colours.