Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Add a stability page: which release the default install follows and how it changes (#9435)

Garry Tan59dafb03cd4b
diff --git a/README.md b/README.md
index 2340cb4a7c..139a686147 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,10 @@ GBrain is MIT-licensed and free to self-host, and it starts with no API keys: se
| MCP from its guide | [ChatGPT](docs/mcp/CHATGPT.md), [Claude Desktop](docs/mcp/CLAUDE_DESKTOP.md), [Claude Cowork](docs/mcp/CLAUDE_COWORK.md), [Perplexity](docs/mcp/PERPLEXITY.md), [Grok Build](docs/mcp/GROK.md), [Grok Bot](docs/guides/grok-bot.md), [Muse](docs/guides/muse.md), [Windsurf and other stdio clients](#connect-gbrain-to-your-ai-client-mcp) |
| Any other coding agent | Paste the [install prompt](#heres-how-to-self-host-it) below |
+## Stability
+
+New releases come out many times a day, but the install command below gives you the **stable channel**: a release reaches it only after the full test suite and a two-hour, 600,000-page load test pass on that exact release, and only when an important fix is waiting or stable is a week old. Updates are never installed without your say-so unless you turn on automatic upgrades. After an upgrade, gbrain shows a one-time notice listing what changed in behaviour. [docs/STABILITY.md](docs/STABILITY.md) explains how often stable moves, how to pin a version or go back, and what the faster alpha channel is for.
+
## Install
> [!TIP]
diff --git a/changelog.d/capy-stability-page.md b/changelog.d/capy-stability-page.md
new file mode 100644
index 0000000000..a7d1795398
--- /dev/null
+++ b/changelog.d/capy-stability-page.md
@@ -0,0 +1,5 @@
+**New page, docs/STABILITY.md: which release the default install follows, how a release becomes stable, and how to pin a version or go back.**
+
+### Added
+- `docs/STABILITY.md` explains that the README install command follows the stable channel, what a release has to pass before it becomes stable, when stable moves, how to stay on stable, pin an exact release or return to an earlier one, where behaviour changes are announced, and what the faster alpha channel is for. Nothing in gbrain changes; the page describes what it already does.
+- The README has a short Stability section that links to the page, and `llms.txt` / `llms-full.txt` list it.
diff --git a/docs/STABILITY.md b/docs/STABILITY.md
new file mode 100644
index 0000000000..ed4eca6a81
--- /dev/null
+++ b/docs/STABILITY.md
@@ -0,0 +1,90 @@
+# Stability: which gbrain you get and how it changes
+
+gbrain ships new releases many times a day. Most people should not run every one of them, and by default they don't: a normal install follows the **stable channel**, which only moves to a release after it has passed extra testing. This page says what that means in practice and how to choose something slower or faster.
+
+## What the default install gives you
+
+The install command in the README, `bun install -g github:garrytan/gbrain#stable`, installs the current stable release. `git clone --branch stable` does the same. A new brain created by `gbrain init` (no earlier config file) is set to the stable channel, and an install with no channel set follows stable too. Every update path follows the channel in effect: the update notice, `gbrain check-update`, `gbrain upgrade`, `gbrain self-upgrade` and the opt-in automatic upgrades.
+
+Check which channel you are on with `gbrain doctor`, which prints `channel=<channel>` when one is set.
+
+## How a release becomes stable
+
+1. **Every release passes the full test suite first.** A release is published only after the full unit and end-to-end test runs pass on its exact code.
+2. **A stable candidate then passes a production-shaped test.** gbrain runs a two-hour load test on a brain of 600,000 pages, at two network delays (2 ms and 65 ms), with privacy probes. It must pass the privacy-leak, read-error, version-skew, process-health and session checks in every run. The test has to have run on the release's exact files; a test of a nearby commit doesn't count.
+3. **Stable moves only for a reason.** A scheduled check runs twice a day (05:17 and 13:17 UTC). It promotes the newest release that passed step 2, and only when there is a reason to move:
+ - an important fix (a security, regression or data-loss fix, or a fix for something that blocks people) has been released but is not in stable yet, or
+ - stable is more than 7 days old and a newer release exists.
+
+ With no reason, stable stays where it is.
+4. **The record is public.** Each promotion writes `stable.json` on the `stable-record` branch (version, commit, the test run that qualified it, and any withdrawn releases) and a permanent `stable-v<version>` tag. Your gbrain reads that file and refuses an update whose record is missing or incomplete; it never falls back to a non-stable release.
+
+## How often stable moves
+
+The scheduled check can move it at most twice a day; a maintainer can also promote, or roll back, by hand. An important fix can move it on any day. If nothing important is waiting, the 7-day rule is the next reason for stable to move, though it still waits for a release that passed the test in step 2.
+
+What that has meant so far: the first stable release was v0.60.474.0 on 28 October 2026. Between then and 15 November 2026 stable moved 9 more times: once on 6 November, 9.7 days later, and then on each of the 8 days from 8 to 15 November, because an important fix was waiting on each of those days. Each move carried every change released since the one before. To see the current pace, list every stable release:
+
+```bash
+git ls-remote --tags --refs https://github.com/garrytan/gbrain 'refs/tags/stable-v*'
+```
+
+## Staying on stable
+
+Do nothing; it is the default. To set it explicitly, or to come back to it from the fast channel:
+
+```bash
+gbrain config set self_upgrade.channel stable
+gbrain upgrade --dry-run --json # what an upgrade would install, installing nothing
+```
+
+gbrain never downgrades you by itself. If you ran ahead on the fast channel and switch back, you stay on your release until stable passes it. The one exception is a release that was withdrawn (listed as `known_bad` in the stable record): an install on it is offered the current stable release, even when that is older.
+
+Updates are not applied by themselves unless you opt in. The default `self_upgrade.mode` is `notify`: you are told an update exists and nothing is installed without your say-so.
+
+## Pinning a version
+
+Install an exact release tag with this command. Its first line checks that the tag exists. Its second line removes any gbrain Bun already has installed, because installing one tag over another can leave the old version running and damage Bun's global package list. Its third line installs the tag:
+
+```bash
+git ls-remote --exit-code --tags https://github.com/garrytan/gbrain refs/tags/v<version> >/dev/null && \
+ { ! bun pm ls -g 2>/dev/null | grep -q 'gbrain@' || bun remove -g gbrain; } && \
+ bun add -g --backend=copyfile github:garrytan/gbrain#v<version>
+```
+
+Replace `<version>` with a release number, for example `0.60.722.0`. The second line skips the removal when Bun has no gbrain installed, so the same command works on a machine that never had gbrain.
+
+A tag-pinned install stays on that release through `bun update`. `gbrain upgrade` is what moves it, so don't run it while you want to stay put. To stop update checks and update notices as well:
+
+```bash
+gbrain config set self_upgrade.mode off
+```
+
+## Going back to an earlier release
+
+Nothing is rolled back for you. To return to an earlier release, reinstall its tag:
+
+```bash
+git ls-remote --exit-code --tags https://github.com/garrytan/gbrain refs/tags/v<previous> >/dev/null && \
+ { ! bun pm ls -g 2>/dev/null | grep -q 'gbrain@' || bun remove -g gbrain; } && \
+ bun add -g --backend=copyfile github:garrytan/gbrain#v<previous>
+```
+
+The first line checks that the tag exists before anything is removed. If an upgrade fails to start, `gbrain upgrade` prints the steps for your install type. A bun-link (git clone) install goes back with `git -C <clone> checkout <previous sha> && bun install`.
+
+Know one limit before you go back. Upgrades can move your database to a newer schema, and an older gbrain will then refuse to set up that schema, with the code `client_behind`. Reads and ordinary commands on the older gbrain still work. The fix is to upgrade that copy again.
+
+## Where changes that need your attention are announced
+
+- **The upgrade notice.** After an upgrade, the first command (or the first tool result an agent gets) shows a one-time `behavior_changes` notice. It lists each behaviour change in the releases you skipped over, in plain sentences, often naming the setting that turns it off. Read it again at any time with `gbrain doctor --only behavior_changes`.
+- **The changelog.** [CHANGELOG.md](../CHANGELOG.md) has an entry for every release.
+- **The GitHub release.** When stable moves, its GitHub release becomes "Latest" and its notes list every changelog entry since the previous stable release. While this rule is new, Latest can still point at a newer release that is not stable; that ends the first time stable passes it.
+
+## What the fast builds are for
+
+Every release is also published on the **alpha** channel, as a GitHub pre-release. Alpha is for people who want each fix the hour it lands, and its releases are the pool stable promotes from. Switch with `gbrain config set self_upgrade.channel alpha` (`latest` is accepted as another name for it), or try one upgrade without changing your setting with `gbrain upgrade --channel alpha`. The git tag that tracks alpha is called `latest-stable` for historical reasons. It is the alpha line, not the stable channel.
+
+## More detail
+
+- [Upgrades and auto-update](guides/upgrades-auto-update.md): channels, the stable record, automatic upgrades, restarts and recovery.
+- [Releasing](RELEASING.md#daily-stable-check): the daily stable check and promotion rules, for maintainers.
diff --git a/llms-full.txt b/llms-full.txt
index 38f83eb8fb..7cb39087f4 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -2781,6 +2781,103 @@ TTY-only (`GBRAIN_BANNER=1` forces it, `GBRAIN_NO_BANNER=1` hides it).
---
+## docs/STABILITY.md
+
+Source: https://raw.githubusercontent.com/garrytan/gbrain/master/docs/STABILITY.md
+
+# Stability: which gbrain you get and how it changes
+
+gbrain ships new releases many times a day. Most people should not run every one of them, and by default they don't: a normal install follows the **stable channel**, which only moves to a release after it has passed extra testing. This page says what that means in practice and how to choose something slower or faster.
+
+## What the default install gives you
+
+The install command in the README, `bun install -g github:garrytan/gbrain#stable`, installs the current stable release. `git clone --branch stable` does the same. A new brain created by `gbrain init` (no earlier config file) is set to the stable channel, and an install with no channel set follows stable too. Every update path follows the channel in effect: the update notice, `gbrain check-update`, `gbrain upgrade`, `gbrain self-upgrade` and the opt-in automatic upgrades.
+
+Check which channel you are on with `gbrain doctor`, which prints `channel=<channel>` when one is set.
+
+## How a release becomes stable
+
+1. **Every release passes the full test suite first.** A release is published only after the full unit and end-to-end test runs pass on its exact code.
+2. **A stable candidate then passes a production-shaped test.** gbrain runs a two-hour load test on a brain of 600,000 pages, at two network delays (2 ms and 65 ms), with privacy probes. It must pass the privacy-leak, read-error, version-skew, process-health and session checks in every run. The test has to have run on the release's exact files; a test of a nearby commit doesn't count.
+3. **Stable moves only for a reason.** A scheduled check runs twice a day (05:17 and 13:17 UTC). It promotes the newest release that passed step 2, and only when there is a reason to move:
+ - an important fix (a security, regression or data-loss fix, or a fix for something that blocks people) has been released but is not in stable yet, or
+ - stable is more than 7 days old and a newer release exists.
+
+ With no reason, stable stays where it is.
+4. **The record is public.** Each promotion writes `stable.json` on the `stable-record` branch (version, commit, the test run that qualified it, and any withdrawn releases) and a permanent `stable-v<version>` tag. Your gbrain reads that file and refuses an update whose record is missing or incomplete; it never falls back to a non-stable release.
+
+## How often stable moves
+
+The scheduled check can move it at most twice a day; a maintainer can also promote, or roll back, by hand. An important fix can move it on any day. If nothing important is waiting, the 7-day rule is the next reason for stable to move, though it still waits for a release that passed the test in step 2.
+
+What that has meant so far: the first stable release was v0.60.474.0 on 28 October 2026. Between then and 15 November 2026 stable moved 9 more times: once on 6 November, 9.7 days later, and then on each of the 8 days from 8 to 15 November, because an important fix was waiting on each of those days. Each move carried every change released since the one before. To see the current pace, list every stable release:
+
+```bash
+git ls-remote --tags --refs https://github.com/garrytan/gbrain 'refs/tags/stable-v*'
+```
+
+## Staying on stable
+
+Do nothing; it is the default. To set it explicitly, or to come back to it from the fast channel:
+
+```bash
+gbrain config set self_upgrade.channel stable
+gbrain upgrade --dry-run --json # what an upgrade would install, installing nothing
+```
+
+gbrain never downgrades you by itself. If you ran ahead on the fast channel and switch back, you stay on your release until stable passes it. The one exception is a release that was withdrawn (listed as `known_bad` in the stable record): an install on it is offered the current stable release, even when that is older.
+
+Updates are not applied by themselves unless you opt in. The default `self_upgrade.mode` is `notify`: you are told an update exists and nothing is installed without your say-so.
+
+## Pinning a version
+
+Install an exact release tag with this command. Its first line checks that the tag exists. Its second line removes any gbrain Bun already has installed, because installing one tag over another can leave the old version running and damage Bun's global package list. Its third line installs the tag:
+
+```bash
+git ls-remote --exit-code --tags https://github.com/garrytan/gbrain refs/tags/v<version> >/dev/null && \
+ { ! bun pm ls -g 2>/dev/null | grep -q 'gbrain@' || bun remove -g gbrain; } && \
+ bun add -g --backend=copyfile github:garrytan/gbrain#v<version>
+```
+
+Replace `<version>` with a release number, for example `0.60.722.0`. The second line skips the removal when Bun has no gbrain installed, so the same command works on a machine that never had gbrain.
+
+A tag-pinned install stays on that release through `bun update`. `gbrain upgrade` is what moves it, so don't run it while you want to stay put. To stop update checks and update notices as well:
+
+```bash
+gbrain config set self_upgrade.mode off
+```
+
+## Going back to an earlier release
+
+Nothing is rolled back for you. To return to an earlier release, reinstall its tag:
+
+```bash
+git ls-remote --exit-code --tags https://github.com/garrytan/gbrain refs/tags/v<previous> >/dev/null && \
+ { ! bun pm ls -g 2>/dev/null | grep -q 'gbrain@' || bun remove -g gbrain; } && \
+ bun add -g --backend=copyfile github:garrytan/gbrain#v<previous>
+```
+
+The first line checks that the tag exists before anything is removed. If an upgrade fails to start, `gbrain upgrade` prints the steps for your install type. A bun-link (git clone) install goes back with `git -C <clone> checkout <previous sha> && bun install`.
+
+Know one limit before you go back. Upgrades can move your database to a newer schema, and an older gbrain will then refuse to set up that schema, with the code `client_behind`. Reads and ordinary commands on the older gbrain still work. The fix is to upgrade that copy again.
+
+## Where changes that need your attention are announced
+
+- **The upgrade notice.** After an upgrade, the first command (or the first tool result an agent gets) shows a one-time `behavior_changes` notice. It lists each behaviour change in the releases you skipped over, in plain sentences, often naming the setting that turns it off. Read it again at any time with `gbrain doctor --only behavior_changes`.
+- **The changelog.** [CHANGELOG.md](../CHANGELOG.md) has an entry for every release.
+- **The GitHub release.** When stable moves, its GitHub release becomes "Latest" and its notes list every changelog entry since the previous stable release. While this rule is new, Latest can still point at a newer release that is not stable; that ends the first time stable passes it.
+
+## What the fast builds are for
+
+Every release is also published on the **alpha** channel, as a GitHub pre-release. Alpha is for people who want each fix the hour it lands, and its releases are the pool stable promotes from. Switch with `gbrain config set self_upgrade.channel alpha` (`latest` is accepted as another name for it), or try one upgrade without changing your setting with `gbrain upgrade --channel alpha`. The git tag that tracks alpha is called `latest-stable` for historical reasons. It is the alpha line, not the stable channel.
+
+## More detail
+
+- [Upgrades and auto-update](guides/upgrades-auto-update.md): channels, the stable record, automatic upgrades, restarts and recovery.
+- [Releasing](RELEASING.md#daily-stable-check): the daily stable check and promotion rules, for maintainers.
+
+---
+
## docs/protocol/AGENT_OPERATOR_v1.md
Source: https://raw.githubusercontent.com/garrytan/gbrain/master/docs/protocol/AGENT_OPERATOR_v1.md
@@ -4424,6 +4521,10 @@ GBrain is MIT-licensed and free to self-host, and it starts with no API keys: se
| MCP from its guide | [ChatGPT](docs/mcp/CHATGPT.md), [Claude Desktop](docs/mcp/CLAUDE_DESKTOP.md), [Claude Cowork](docs/mcp/CLAUDE_COWORK.md), [Perplexity](docs/mcp/PERPLEXITY.md), [Grok Build](docs/mcp/GROK.md), [Grok Bot](docs/guides/grok-bot.md), [Muse](docs/guides/muse.md), [Windsurf and other stdio clients](#connect-gbrain-to-your-ai-client-mcp) |
| Any other coding agent | Paste the [install prompt](#heres-how-to-self-host-it) below |
+## Stability
+
+New releases come out many times a day, but the install command below gives you the **stable channel**: a release reaches it only after the full test suite and a two-hour, 600,000-page load test pass on that exact release, and only when an important fix is waiting or stable is a week old. Updates are never installed without your say-so unless you turn on automatic upgrades. After an upgrade, gbrain shows a one-time notice listing what changed in behaviour. [docs/STABILITY.md](docs/STABILITY.md) explains how often stable moves, how to pin a version or go back, and what the faster alpha channel is for.
+
## Install
> [!TIP]
diff --git a/llms.txt b/llms.txt
index f1f141556b..57893b47aa 100644
--- a/llms.txt
+++ b/llms.txt
@@ -27,6 +27,7 @@ Repo: https://github.com/garrytan/gbrain
- [docs/architecture/thin-client.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/architecture/thin-client.md): The thin-client / remote-MCP / cross-modal routing seam: isThinClient detection, callRemoteTool, SSRF-hardened URL validation, per-command routing.
- [docs/architecture/brains-and-sources.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/architecture/brains-and-sources.md): The two axes: a brain is which database, a source is which repo inside it. Resolution precedence for --brain and --source, topologies, Git as the parent of a source with a checkout (mixed, strict, mirror, database-only), entity identity across sources, cross-source links and what confines remote callers.
- [INSTALL_FOR_AGENTS.md](https://raw.githubusercontent.com/garrytan/gbrain/master/INSTALL_FOR_AGENTS.md): Step-by-step agent installation (steps 0-9): install, keyless init, the first-run decision bundle, harness wiring, verification and upgrades.
+- [docs/STABILITY.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/STABILITY.md): Which release the default install follows (the stable channel), how a release becomes stable, how often stable moves, staying on stable, pinning a version, going back, where behaviour changes are announced, and what the alpha channel is for.
- [docs/protocol/AGENT_OPERATOR_v1.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/protocol/AGENT_OPERATOR_v1.md): The agent operator contract: read `code`, follow `fix.next` (run / ask_user / tell_user_to_run / wait / report), run `fix.verify`. Error envelope, notices and mute, effects/actor/next table, consent and preapproval, exit codes, marker grammar, compatibility policy, first run, and how to make gbrain work better for your user.
- [skills/RESOLVER.md](https://raw.githubusercontent.com/garrytan/gbrain/master/skills/RESOLVER.md): Skill dispatcher. Read first for any task.
- [README.md](https://raw.githubusercontent.com/garrytan/gbrain/master/README.md): Project overview, benchmarks, 30-minute setup.
diff --git a/scripts/llms-config.ts b/scripts/llms-config.ts
index 058341a126..985bc1f307 100644
--- a/scripts/llms-config.ts
+++ b/scripts/llms-config.ts
@@ -96,6 +96,11 @@ export const SECTIONS: DocSection[] = [
description: "Step-by-step agent installation (steps 0-9): install, keyless init, the first-run decision bundle, harness wiring, verification and upgrades.",
path: "INSTALL_FOR_AGENTS.md",
},
+ {
+ title: "docs/STABILITY.md",
+ description: "Which release the default install follows (the stable channel), how a release becomes stable, how often stable moves, staying on stable, pinning a version, going back, where behaviour changes are announced, and what the alpha channel is for.",
+ path: "docs/STABILITY.md",
+ },
{
title: "docs/protocol/AGENT_OPERATOR_v1.md",
description: