docs: sweep drift that predates this release

Surfaced by the /document-release audit; every fix verified against the
current binaries:

- gstack-brain-init was replaced by gstack-artifacts-init in v1.27.0.0
  (hard-delete, no compat shim), but README, USING_GBRAIN_WITH_GSTACK,
  docs/gbrain-sync.md, and docs/gbrain-sync-errors.md still instructed
  users to run it — command-not-found on every follow. Same sweep updates
  ~/.gstack-brain-remote.txt to the canonical ~/.gstack-artifacts-remote.txt
  (legacy name still honored on restore, noted where users copy the file).
- gbrain-sync-errors.md headings re-matched to the literal messages the
  binaries print today (the doc's whole value is grep-by-exact-message):
  'gstack-artifacts-init: ~/.gstack/ is already a git repo pointing at:',
  'Remote not reachable via SSH:', 'Failed to create or find ...'. The
  already-a-repo fix now leads with the command's own set-url suggestion.
- docs/gbrain-sync.md 'Under the hood' linked a plan file that does not
  exist in the repo; replaced with the decisions themselves.
- SIDEBAR_MESSAGE_FLOW startup timeline: /pty-session responds with
  {terminalPort, sessionId, attachToken, leaseExpiresAt} (v1.44 shape,
  verified at browse/src/server.ts:1860), not the retired
  {terminalPort, ptySessionToken} pair.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Garry Tan
2026-08-13 18:28:46 -07:00
co-authored by Claude Fable 5
parent e7110aac93
commit 1ac4683b7b
5 changed files with 36 additions and 30 deletions
+12 -11
View File
@@ -31,7 +31,7 @@ it; you can append your own entries below the marker line.
## First-run setup (3090 seconds)
```bash
gstack-brain-init
gstack-artifacts-init
```
The command:
@@ -41,7 +41,7 @@ The command:
gstack-brain-$USER`). Any git remote works — GitHub, GitLab, Gitea,
self-hosted.
3. Pushes an initial commit with just the config.
4. Writes `~/.gstack-brain-remote.txt` (URL-only, no secrets —
4. Writes `~/.gstack-artifacts-remote.txt` (URL-only, no secrets —
safe to copy to another machine).
5. Wires the gstack-brain repo into your local gbrain as a federated
source (via `gbrain sources add` + `git worktree`) so `gbrain search`
@@ -65,14 +65,15 @@ Your answer is persisted. You won't be asked again.
## Cross-machine workflow
On machine A: run `gstack-brain-init` once. That's it — every skill
On machine A: run `gstack-artifacts-init` once. That's it — every skill
invocation now drains the sync queue at its start and end boundaries
(~200800 ms network pause per skill).
On machine B:
1. Copy `~/.gstack-brain-remote.txt` from machine A to machine B
(password manager, dotfile repo, USB stick — your call).
1. Copy `~/.gstack-artifacts-remote.txt` from machine A to machine B
(password manager, dotfile repo, USB stick — your call; the legacy
`~/.gstack-brain-remote.txt` name is still recognized).
2. Run any gstack skill. The preamble sees the URL file and prints:
```
BRAIN_SYNC: brain repo detected: <url>
@@ -180,7 +181,7 @@ This:
Add `--delete-remote` to also delete the private GitHub repo (GitHub only,
uses `gh repo delete`).
Re-init anytime with `gstack-brain-init`.
Re-init anytime with `gstack-artifacts-init`.
## Troubleshooting
@@ -189,8 +190,8 @@ error message gstack-brain may print, with problem / cause / fix for each.
## Under the hood
For the architectural decisions behind this feature (allowlist vs
denylist, daemon vs preamble-boundary sync, JSONL merge driver, privacy
stop-gate), see the
[approved plan](../system-instruction-you-are-working-jaunty-kahn.md) in
the gstack plans directory.
The architectural decisions behind this feature: allowlist over denylist
(unknown files stay local by default), preamble-boundary sync over a daemon
(no background process to babysit), a JSONL merge driver so concurrent
machines union their queues instead of conflicting, and a privacy stop-gate
that asks once before anything syncs.