foldrun 0.6.0 → 0.7.2

package/README.md

@@ -25,18 +25,36 @@ Requires Node 22 or newer. `init` and `check` need no API key.
 
 ## What `init` gives you
 
+An **account folder** — the same shape the platform keeps, so what you reason
+about locally is what runs there:
+
 ```
-competitor-watch/
-├── AGENTS.md                    what every agent here shares
-├── agents/
-│   ├── researcher/agent.md
-│   └── writer/agent.md
-├── flows/publish.md             the steps, in order
-├── knowledge/house-style.md     given to them; they may read, never write
-├── memory/what-worked.md        what they learned; they write here
-└── evals/writer-quality.md      what "good" means, as a test
+competitor-watch/                 the account
+├── AGENTS.md                     config and context every workspace inherits
+├── library/                      skills, tools, scripts, knowledge shared by all of them
+│   ├── skills/  tools/  scripts/
+│   └── knowledge/  memory/
+└── workspaces/
+    └── main/                     the first workspace, ready to run
+        ├── AGENTS.md             what every agent HERE shares
+        ├── agents/
+        │   ├── researcher/agent.md
+        │   └── writer/agent.md
+        ├── flows/publish.md      the steps, in order
+        ├── knowledge/house-style.md  given to them; they may read, never write
+        ├── memory/what-worked.md     what they learned; they write here
+        └── evals/writer-quality.md   what "good" means, as a test
 ```
 
+`--workspace <name>` names that first workspace (default `main`), and
+`foldrun new <name>` adds another beside it. Every workspace in the account
+resolves `skills:`, `tools:` and `scripts:` against the shared `library/`,
+nearest-wins — its own file first, the library second.
+
+`foldrun init --flat <dir>` makes the older single-folder shape instead: no
+account around it, `agents/` and `flows/` at the root. **Every command still
+reads that shape**, unchanged, so a folder made before today keeps working.
+
 An agent is frontmatter for the machine and prose for the model:
 
 ```markdown
@@ -94,24 +112,77 @@ declared the same way.
 
 | | |
 |---|---|
-| `foldrun init [dir]` | create a workspace you can run immediately |
-| `foldrun check [dir]` | validate agents, flows, tools, evals and knowledge |
+| `foldrun init [dir]` | create an account folder with one workspace in it (`--flat` for the old shape) |
+| `foldrun new <name>` | another workspace in this account |
+| `foldrun agent new <name>` | one more agent in this workspace — also `flow new <name>` and `tool new <name>` |
+| `foldrun flow set\|trigger\|move-step\|copy-step\|paste\|draft <flow>` | the Flows page from a terminal: step options, the trigger, a drag, copy and paste, Draft with AI — the same core rewriters, a diff, refused when `check` would call it an error (`--to <ws>` edits the deployed copy) |
+| `foldrun guide` | the coding-agent rules, as Next.js writes them: a short block in `AGENTS.md` telling Claude Code, Cursor or Codex to read `foldrun docs` before editing, and `CLAUDE.md` importing it (`@AGENTS.md`). `init` writes them, `pull` refreshes them, `check` re-adds them when a coding agent runs it; only the marked block is ever rewritten (`--check`, `--print`) |
+| `foldrun docs [page]` | foldrun's docs from the copy this CLI ships, so a coding agent reads the version it is driving, offline (`--path` prints where) |
+| `foldrun check [dir]` | validate every workspace here, and the shared library |
+| `foldrun check --to <ws>` | validate the copy that is DEPLOYED — fetched from the platform, checked by the same rules |
+| `foldrun agent run <name>` | run one agent once on a platform, no flow (`--task "…"`, `--wait`, `--test`) |
+| `foldrun tool test <name>` | exercise one tool alone — no model, no run (`key=value` for its args) |
 | `foldrun run <target>` | run an agent or a flow |
 | `foldrun eval [name]` | run one eval, or all of them |
 | `foldrun extract [dir]` | move single-file script tools into folders |
 | `foldrun probe <model>` | live check: can this model hold a tool loop here? |
 | `foldrun logs [run-id]` | recent runs, or one run's full event trail |
+| `foldrun runs` | what has run lately, across the account — `--status`, `--since`, `--to`, `--limit` |
+| `foldrun report <run-id>` | one run, whole: every step, what it cost, what it wrote, what is still waiting (`--json` for the record) |
+| `foldrun approvals` | every gate waiting on a person, with its question and what it previews |
+| `foldrun approve <run-id>` | release a waiting gate — it asks first, `--yes` means it, `--note "…"` steers the step |
+| `foldrun reject <run-id>` | refuse one, `--note` being the reason |
+| `foldrun stop <run-id>` | kill a run in flight — it says what it will destroy, then asks (`--yes` means it) |
+| `foldrun answer <run-id> "…"` | answer the question an agent is asking mid-step (`--option <n>` picks a choice) |
+| `foldrun message <run-id> "…"` | say something to a running agent — it hears it after its next tool call |
+| `foldrun rerun <run-id>` | the same flow again from a step — `--from <n>` as the flow numbers them, or `--agent <name>` for the first step that agent runs; `--wait` follows it |
+| `foldrun schedule` | every flow in the account that fires on a clock, its cron line, and the next few times it fires |
+| `foldrun schedule tick` | fire whatever is due now — Settings' "Run scheduler now" |
+| `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 |
+| `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`) |
+| `foldrun onboarding` | the account's getting-started steps, done or not, the next one first |
+| `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`) |
+| `foldrun webhooks deliveries` | the `notify:` webhooks a workspace sent: status, attempts, the last answer (`--failed`, `--to`) — and `redeliver <id>` to send one again |
+| `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 |
+| `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 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) |
 | `foldrun secrets set NAME` | store a secret, prompted and never echoed |
-| `foldrun deploy [dir]` | push a workspace into an installation |
-| `foldrun invoke <flow>` | start a flow on a running platform (`--watch` streams its trace) |
+| `foldrun secrets clients` | OAuth clients saved on the platform — `add`, `rm`; `connect NAME --client <name>` runs a consent from one. `secrets set NAME --kind file\|ssh\|api\|service-account\|m2m` for the other shapes |
+| `foldrun deploy [dir]` | push the whole account — or `deploy <workspace>` for one of them |
+| `foldrun pull [workspace]` | bring the platform's account down here (refuses to clobber local edits) |
+| `foldrun status [workspace]` | per workspace: added, changed, and what moved on the platform since your last deploy |
+| `foldrun workspaces` | what exists here and there — also `rm <name>` (`--platform --yes` to delete it there) |
+| `foldrun library` | the account's shared library on the platform: `ls`, `cat`, `put`, `rm` |
+| `foldrun find <words>` | the dashboard's ⌘K search, across the account |
+| `foldrun history restore <path> --id <rev>` | one file back as a revision left it, as a new revision |
+| `foldrun invoke <flow>` | start a flow on a running platform (`--watch` streams its trace; `--once <key>` makes a retry a no-op rather than a second run) |
 | `foldrun open [page]` | the dashboard for this workspace, in the browser |
 | `foldrun login` | sign this machine in from the browser — no key to copy |
 | `foldrun whoami` | who you are on the platform: account, role, workspaces |
+| `foldrun preferences` | your theme on the platform — `set theme system\|light\|dark` |
+| `foldrun api version` | the API version pin and rate limits — `pin <date>`, `unpin` |
+| `foldrun changelog` | the platform's release notes |
 | `foldrun doctor` | check the path to the platform: node, CLI, account, DNS, a timed `/api/healthz` — exit 1 if any line fails |
 | `foldrun keys ls` | the account's API keys — also `create <label>`, `revoke <id>` |
 
 `foldrun --help` lists every flag.
 
+`foldrun tool test <name> --to <workspace> key=value` is how you find out a
+tool works before a flow depends on it. It runs the real thing — the HTTP
+request, the script, the MCP handshake — and prints what the tool printed, how
+long it took, and any secret it needed by NAME and never by value. It waits
+five minutes by default, because a tool that scrapes or crawls takes as long as
+it takes; `--timeout <seconds>` waits longer.
+
+`foldrun agent run <name> --to <workspace> --task "…"` runs one agent once, as
+a flow of one step with no flow file. It prints the run id and how to follow
+it; `--wait` holds on and prints the same report `foldrun report` would.
+
 **`check` is the one to run in CI.** It costs nothing and catches what
 otherwise surfaces as a confidently wrong answer at 3am: a step naming an agent
 that doesn't exist, a tool whose program isn't on disk, an eval pointing at a
@@ -134,10 +205,21 @@ an API and never reach the model.
 
 ## Running it somewhere else
 
-`foldrun deploy` pushes a workspace into an installation — your own, or a
+`foldrun deploy` pushes this account into an installation — your own, or a
 hosted one — and `foldrun invoke <flow> --wait` starts a flow there and prints
 the result. A deploy never touches run history, state, secrets, or memory an
-agent wrote: those belong to the installation, not to your git repo.
+agent wrote: those belong to the installation, not to your git repo. It never
+removes a workspace either: one that exists on the platform and not in your
+folder is left exactly as it is, and `foldrun workspaces rm <name> --platform
+--yes` is the deliberate way to delete one.
+
+Inside an account folder the workspace-scoped commands take the workspace as a
+positional — `foldrun secrets blog-desk set TOKEN`, `foldrun runs blog-desk` —
+or need nothing at all when there is only one.
+
+One gap worth knowing: the platform has no account-file endpoint, so the
+account's own `AGENTS.md` is not pushed or pulled. `deploy` and `pull` say so
+rather than dropping it quietly; edit it in Settings on the platform.
 
 ```sh
 foldrun login                    # approve it in the browser, once per machine