Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

docs: RELEASING and the npm_squat key-file entry name the stable install ref

garrytanac4919c3253d
diff --git a/docs/RELEASING.md b/docs/RELEASING.md
index 22f8cd578a..dc51b17fc5 100644
--- a/docs/RELEASING.md
+++ b/docs/RELEASING.md
@@ -572,12 +572,13 @@ succeed on the release commit.
The **final step of the release job** force-advances the `latest-stable` tag to
the gated release commit (`git push origin "+${RELEASE_SHA}:refs/tags/latest-stable"`).
-`latest-stable` is the single sanctioned distribution ref: the README paste
+`latest-stable` is the alpha line (every published release) that the `latest`
+update channel reads. New users start on the `stable` tag instead
+([Stable channel promotion](#stable-channel-promotion)): the README paste
block, the `BOOTSTRAP_FOR_AGENTS.md` fetch URL, and
-`bun install -g github:garrytan/gbrain#latest-stable` all reference it
-permanently, so paste blocks copied into the wild never rot and there is no 404
-window between VERSION landing and assets publishing.
-`scripts/check-bootstrap-tag.sh` keeps the entry docs pinned to this ref.
+`bun install -g github:garrytan/gbrain#stable` all reference it, and
+`scripts/check-bootstrap-tag.sh` keeps the entry docs pinned to `stable` and
+refuses `latest-stable` there.
Because it moves ONLY after binaries + provenance attestation have fully
published, a half-built release never advances it. If the tag-advance step
diff --git a/docs/architecture/key-files/core-utilities-1.md b/docs/architecture/key-files/core-utilities-1.md
index 3f214614f4..7a321d7383 100644
--- a/docs/architecture/key-files/core-utilities-1.md
+++ b/docs/architecture/key-files/core-utilities-1.md
@@ -64,7 +64,7 @@ The `src/core/cycle.ts` entry is on its own page: [Core Cycle primitive](core-cy
- `src/core/mcp-usage.ts` — `readClientOpUsage(engine, {days})`: the ONE shared reader over `mcp_request_log`, consumed by `gbrain auth clients --usage`, the advisor `mcp-client-fit` collector, and `scripts/derive-starter-ops.ts`. Encodes the row-hygiene rules once (`normalizeLoggedOperation`): JSON-RPC method rows (`tools/list`, `initialize`, …) and `surface_change` audit rows drop; the legacy `tools/call:<name>` prefix strips to the op name, and the hygiene check re-runs on the stripped name (`tools/call:tools/list` is still not an op call). Only `status IN ('success','success_with_warnings')` rows count as usage — denied or erroring traffic cannot "use" its way into starter derivation or advisor fit findings. Windows on `created_at` (rides `idx_mcp_log_time_agent`); plain SQL through `engine.executeRaw`, both engines. Behavioral automation classification: `likely_automation` = >90% of calls are `context_pack`/`delta` boundary verbs (the hook lane is stdio and never logs, so there is no name convention to key on). Sees HTTP clients ONLY — stdio never writes the log. Pinned by test/mcp-usage.test.ts.
-- `src/core/npm-squat-check.ts` — doctor's `npm_squat`: classifies `gbrain` on PATH plus `npm root -g` and Bun global packages. Foreign winner: ask_user remove (npm/bun only from its own global dir, else the user's step); `#latest-stable` + #218 only when no gbrain is left. Windows: MSYS paths, `.exe`. Tests: `npm-squat-check`, `doctor-npm-squat`.
+- `src/core/npm-squat-check.ts` — doctor's `npm_squat`: classifies `gbrain` on PATH plus `npm root -g` and Bun global packages. Foreign winner: ask_user remove (npm/bun only from its own global dir, else the user's step); `#stable` + #218 only when no gbrain is left. Windows: MSYS paths, `.exe`. Tests: `npm-squat-check`, `doctor-npm-squat`.
- `src/core/operations-descriptions.ts` — Constants module for tool descriptions. Pinned via `test/operations-descriptions.test.ts`. Houses `GET_RECENT_SALIENCE_DESCRIPTION`, `FIND_ANOMALIES_DESCRIPTION`, `GET_RECENT_TRANSCRIPTS_DESCRIPTION` plus `LIST_PAGES_DESCRIPTION`, `QUERY_DESCRIPTION`, `SEARCH_DESCRIPTION`. Stable surface for the Tier-2 LLM routing eval — keeping them here keeps the test from binding to whatever is in `operations.ts` at test-run time. Description-edit checklist for `QUERY_DESCRIPTION` / `SEARCH_DESCRIPTION` (and any other text a starter tool serves): no pre-merge lane carries a provider key, so run the routing eval yourself with `GBRAIN_TEST_KEEP_PROVIDER_KEYS=1 bun test test/e2e/salience-llm-routing.test.ts` (Haiku 4.5 at temperature 0, ≈ $0.04; a `search`/`query` rewrite can move concept phrasings such as "all the people that work on X" from `query` to `search` without any unit test noticing), then `bun test test/mcp-schema-budget.test.ts` (per-tool budget, 25,000-character served starter ceiling and its 200-character headroom floor, `MINIMUM_GUIDANCE` pins), `test/operations-descriptions.test.ts`, `test/mcp-instructions-batching.test.ts`, and regenerate with `bun run build:operation-manifest`, `bun run scripts/generate-tool-catalog.ts` and `GBRAIN_TEST_UPDATE_GOLDENS=1 bun test test/cli-goldens.test.ts`. Both descriptions say that people/companies/projects by topic are `query` work: Haiku 4.5 otherwise reads "all the X that do Y" as a `search` list lookup (measured at temperature 1: 28/80 concept phrasings misrouted without the clause, 1/80 with it).