foldrun 0.9.0 → 1.1.0

package/docs/tools.md

@@ -123,6 +123,12 @@ a `name @ url` is refused, with a line in the log.
 never seen the program, and say when to use the tool in `description` — that
 sentence is what decides whether it gets called at all.
 
+The program gets each argument the agent fills in as a long flag,
+`--<name> <value>`: the tool above runs as
+`run.py --query "SELECT …" --files sales.csv`. An argument left out or empty
+is not passed, so give optional ones a default in the program. What it
+prints, stdout and stderr together, is what the agent reads back.
+
 ## MCP — someone else's tools
 
 ```yaml
@@ -1408,11 +1414,36 @@ own defaults.
 next one: the cookies and localStorage the call ends with are written to
 `workspace/state/browser/<name>.json` and loaded before any later call that
 names it, in this run or a run next month. It is the agent's own login,
-made with `actions` from credentials it can see — `state` refuses
-`cookies=` and `storage=` and a session those seeded, because `state/` is a
-workspace file every later step can read, and a vault secret written there
-would stop being one. `mode=diff` keeps its baselines in the same place,
-under `state/browser/diff/`, for the same reason: they must outlive the run.
+made with `actions` from credentials it can see — or a login a cookie secret
+seeded, when `state_key` encrypts it (below). Without a key `state` refuses
+`cookies=` and a session they seeded, and it always refuses `storage=`,
+because `state/` is a workspace file every later step can read, and a vault
+secret written there in the clear would stop being one. `mode=diff` keeps its
+baselines in the same place, under `state/browser/diff/`, for the same
+reason: they must outlive the run.
+
+**A cookie secret that seeds a saved login.** Some sites — Google above all —
+rotate their sign-in cookies while they are used, so a copied `Cookie` line in
+the vault goes stale within the hour and every later run meets a sign-in
+page. Put `state:` and `state_key:` beside `cookies:` in the block:
+
+```yaml
+web:
+  browse:
+    cookies: YOUTUBE_COOKIES
+    cookie_domain: .youtube.com
+    state: youtube
+    state_key: BROWSER_STATE_KEY
+secrets: [YOUTUBE_COOKIES, BROWSER_STATE_KEY]
+```
+
+The first call seeds from the secret; every call saves the session it ends
+with, encrypted, and the next loads that rather than the vault's copy. The
+state file records which secret seeded it and a keyed fingerprint of its
+value, so pasting fresh cookies into the secret seeds it again. Script in the
+page (`js`, `eval`, a `get` of storage) stays refused on such a login, as it
+is on the secret itself. `check` refuses `state` beside `cookies` without
+`state_key`.
 
 ### Where the browser runs
 

package/docs/versions.md

@@ -22,8 +22,45 @@ under its own name — `v2026.09.30.2` deployed again is still `v2026.09.30.2`.
 Behind each name are the commits of the parts that make up the platform —
 `core` (the runtime), `platform` (queue, worker, storage, billing), `web` (the
 dashboard and the API), `docs` and `infra` — recorded when it was deployed.
-The `foldrun` CLI and `@foldrun/core` on npm are packages a person publishes,
-and keep ordinary semver (`0.6.0`).
+The `foldrun` CLI and `@foldrun/core` on npm are packages, and follow
+semantic versioning instead — see [the packages](#the-packages).
+
+## The packages
+
+`foldrun` (the CLI) and `@foldrun/core` follow
+[Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) from 1.0.0:
+
+| | Means | Example |
+|---|---|---|
+| Patch | a bug fix, nothing new — safe to update | 1.4.2 → 1.4.3 |
+| Minor | a new feature; everything that worked still works | 1.4.2 → 1.5.0 |
+| Major | a breaking change: something old stops working or works differently | 1.4.2 → 2.0.0 |
+
+What the promise covers is the public API. For the CLI that is every command
+and flag `foldrun --help` lists, and the Node.js version it needs. For
+`@foldrun/core` it is `@foldrun/core` itself and the subpaths in its
+`package.json` under `foldrun.publicApi`. Other `@foldrun/core/*` modules can
+be imported, but they are internal and may change in any release.
+
+The release decides the number, not a person's memory. It compares the
+public API at the last release with the new one. Anything gone, or a
+function that now needs more arguments, makes it a major. Anything new makes
+it at least a minor. A change in behaviour that the API cannot show is marked
+in the commit, and that makes it a major too. A major's release notes open
+with **Breaking changes**, saying what stops working.
+
+Nothing is removed without warning. A command, flag or export is first marked
+deprecated, in a minor, and still works. It is taken out in a later major.
+Both are in the release notes.
+
+Pre-releases, like `1.5.0-rc.1`, are published under npm's `next` tag. So
+`npm install -g foldrun` gets the last stable release, and
+`npm install -g foldrun@next` gets the pre-release. A stable CLI never
+suggests updating to a pre-release.
+
+`npm install -g foldrun@^1` stays within 1.x, so nothing that works breaks
+under it. Every release is listed in each package's `CHANGELOG.md` and on
+GitHub Releases.
 
 ## Rollback and the database
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foldrun",
-  "version": "0.9.0",
+  "version": "1.1.0",
   "description": "Agents are just folders. Write them, check them, run them — on your machine.",
   "license": "Apache-2.0",
   "type": "module",
@@ -11,7 +11,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@foldrun/core": "^0.7.0"
+    "@foldrun/core": "^1.1.0"
   },
   "files": [
     "bin",
@@ -21,7 +21,7 @@
   ],
   "scripts": {
     "e2e": "FOLDRUN_E2E=1 FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-e2e-XXXXXX) node --test --test-timeout=300000 tests/e2e.test.ts",
-    "test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-frontmatter.test.ts tests/cli-agent-import.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts tests/cli-flags.test.ts tests/cli-api-coverage.test.ts",
+    "test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-frontmatter.test.ts tests/cli-agent-import.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts tests/cli-flags.test.ts tests/cli-api-coverage.test.ts tests/cli-hooks.test.ts tests/cli-release.test.ts tests/cli-terminal.test.ts tests/cli-network.test.ts tests/cli-assistant.test.ts",
     "release": "node scripts/release.mjs",
     "typecheck": "tsc -p tsconfig.json",
     "docs:sync": "node scripts/sync-docs.mjs",