From 1ac4683b7b83b4d1e7bed954072c6b94b41f22d5 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Thu, 13 Aug 2026 18:28:46 -0700 Subject: [PATCH] docs: sweep drift that predates this release MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- README.md | 2 +- USING_GBRAIN_WITH_GSTACK.md | 8 +++++--- docs/designs/SIDEBAR_MESSAGE_FLOW.md | 5 +++-- docs/gbrain-sync-errors.md | 28 +++++++++++++++------------- docs/gbrain-sync.md | 23 ++++++++++++----------- 5 files changed, 36 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 9eb7ba6a3..04879e812 100644 --- a/README.md +++ b/README.md @@ -420,7 +420,7 @@ The skill asks once per repo. The decision is sticky across worktrees and branch **GStack memory sync (different feature, same private-repo infra).** Optionally pushes your gstack state (learnings, CEO plans, design docs, retros, developer profile) to a private git repo so your memory follows you across machines, with a one-time privacy prompt (everything allowlisted / artifacts only / off) and a defense-in-depth secret scanner that blocks AWS keys, tokens, PEM blocks, and JWTs before they leave your machine. ```bash -gstack-brain-init +gstack-artifacts-init ``` **Running gstack in Conductor?** Conductor explicitly strips `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` from every workspace's process env, so paid evals and gbrain embeddings won't work out of the box. Set `GSTACK_ANTHROPIC_API_KEY` and `GSTACK_OPENAI_API_KEY` in Conductor's workspace env config instead — gstack's TS entry points promote them to canonical names at runtime. Full details and the contributor checklist for adding the import to new entry points: [Conductor + GSTACK_* env vars](USING_GBRAIN_WITH_GSTACK.md#conductor--gstack_-env-vars). diff --git a/USING_GBRAIN_WITH_GSTACK.md b/USING_GBRAIN_WITH_GSTACK.md index 4634b93b5..dd03c7836 100644 --- a/USING_GBRAIN_WITH_GSTACK.md +++ b/USING_GBRAIN_WITH_GSTACK.md @@ -169,14 +169,16 @@ This is different from gbrain itself. Your gstack state (`~/.gstack/` — learni Turn it on with: ```bash -gstack-brain-init +gstack-artifacts-init ``` You'll get a one-time privacy prompt: **everything allowlisted** / **artifacts only** (plans, designs, retros, learnings — skip behavioral data like timelines) / **off**. Every skill run syncs the queue at start and end — no daemon, no background process. Secret-shaped content (AWS keys, GitHub tokens, PEM blocks, JWTs, bearer tokens) is blocked from sync before it leaves your machine. -**On a new machine:** Copy `~/.gstack-brain-remote.txt` over, run `gstack-brain-restore`, and yesterday's learnings surface on today's laptop. +**On a new machine:** Copy `~/.gstack-artifacts-remote.txt` over (the legacy +`~/.gstack-brain-remote.txt` name still works), run `gstack-brain-restore`, and +yesterday's learnings surface on today's laptop. Full guide: [docs/gbrain-sync.md](docs/gbrain-sync.md). Error index: [docs/gbrain-sync-errors.md](docs/gbrain-sync-errors.md). @@ -241,7 +243,7 @@ Gbrain itself ships with these that gstack wraps: | `~/.gstack/.setup-gbrain.lock.d` | Concurrent-run lock (atomic mkdir). Released on normal exit + SIGINT. | | `~/.gstack/.brain-queue.jsonl` | Pending sync entries for gstack memory sync | | `~/.gstack/.brain-last-push` | Timestamp of last sync push (for `/health` scoring) | -| `~/.gstack-brain-remote.txt` | URL of your gstack memory sync remote (safe to copy between machines) | +| `~/.gstack-artifacts-remote.txt` | URL of your gstack memory sync remote (safe to copy between machines; legacy name `~/.gstack-brain-remote.txt` still read) | | `~/.gstack/.setup-gbrain-inflight.json` | Reserved for future `--resume-provision` persisted state | ### Environment variables diff --git a/docs/designs/SIDEBAR_MESSAGE_FLOW.md b/docs/designs/SIDEBAR_MESSAGE_FLOW.md index 93c95a9da..ae46df16f 100644 --- a/docs/designs/SIDEBAR_MESSAGE_FLOW.md +++ b/docs/designs/SIDEBAR_MESSAGE_FLOW.md @@ -71,8 +71,9 @@ T+1-3s Extension loads, sidebar opens T+ready tryAutoConnect calls connect() ├── POST /pty-session (Authorization: Bearer AUTH_TOKEN) - │ └── server mints session token, posts /internal/grant to agent - │ └── responds with {terminalPort, ptySessionToken} + │ └── server mints attach token, posts /internal/grant to agent + │ └── responds with {terminalPort, sessionId, attachToken, + │ leaseExpiresAt} ├── GET /claude-available (preflight) ├── new WebSocket(`ws://127.0.0.1:/ws`, │ [`gstack-pty.`]) diff --git a/docs/gbrain-sync-errors.md b/docs/gbrain-sync-errors.md index 85a25b717..c18ae4d31 100644 --- a/docs/gbrain-sync-errors.md +++ b/docs/gbrain-sync-errors.md @@ -9,8 +9,9 @@ the command output. ## `BRAIN_SYNC: brain repo detected: ` -**Problem.** You're on a machine that has `~/.gstack-brain-remote.txt` (copied -from another machine) but no local git repo at `~/.gstack/.git`. +**Problem.** You're on a machine that has `~/.gstack-artifacts-remote.txt` +(or the legacy `~/.gstack-brain-remote.txt`, copied from another machine) but +no local git repo at `~/.gstack/.git`. **Cause.** You've set up GBrain sync elsewhere and your gstack hasn't been restored on this machine yet. @@ -115,23 +116,24 @@ ledger with `gstack-egress list`; verify its hash chain with --- -## `gstack-brain-init: ~/.gstack/.git is already a git repo pointing at ` +## `gstack-artifacts-init: ~/.gstack/ is already a git repo pointing at: ` **Problem.** You tried to init with a remote URL that doesn't match the -existing one. +existing one. The command refuses to overwrite. -**Cause.** You already ran `gstack-brain-init` with a different remote. +**Cause.** You already ran `gstack-artifacts-init` with a different remote. **Fix.** Either: -- Use the existing remote: run `gstack-brain-init` without `--remote`, or +- Use the existing remote: run `gstack-artifacts-init` without `--remote`, or with the matching URL. -- Switch remotes: `gstack-brain-uninstall` first, then re-init with the new - URL. This does not delete your data. +- Switch remotes: `git -C ~/.gstack remote set-url origin ` (the + command's own suggestion), or `gstack-brain-uninstall` first, then re-init + with the new URL. Neither deletes your data. --- -## `Remote not reachable: ` +## `Remote not reachable via SSH: ` **Problem.** Init couldn't reach the git remote to verify connectivity. @@ -149,7 +151,7 @@ If that fails, check: --- -## `gstack-brain-init: failed to create or find ''` +## `Failed to create or find ''. Try --remote .` **Problem.** Auto-repo-creation via `gh repo create` failed and the repo isn't discoverable via `gh repo view` either. @@ -164,7 +166,7 @@ gh auth status If unauth'd, run `gh auth login`. If the repo name collides, pass a different name: ```bash -gstack-brain-init --remote git@github.com:YOURUSER/custom-name.git +gstack-artifacts-init --remote git@github.com:YOURUSER/custom-name.git ``` --- @@ -191,7 +193,7 @@ gstack session, or (b) a previous failed restore left partial state. **Fix (three options).** 1. **If this machine's state should become the new truth**: run - `gstack-brain-init` instead of restore — this creates a brand-new brain + `gstack-artifacts-init` instead of restore — this creates a brand-new brain repo from this machine's state. 2. **If you want to adopt the remote and discard this machine's state**: @@ -212,7 +214,7 @@ and `.gitattributes`. **Cause.** You pointed restore at a random git repo, or someone deleted the canonical config files from the brain repo. -**Fix.** Verify the URL. If it's correct, run `gstack-brain-init --remote +**Fix.** Verify the URL. If it's correct, run `gstack-artifacts-init --remote ` to re-seed the canonical config. --- diff --git a/docs/gbrain-sync.md b/docs/gbrain-sync.md index d6e91542d..6a484909b 100644 --- a/docs/gbrain-sync.md +++ b/docs/gbrain-sync.md @@ -31,7 +31,7 @@ it; you can append your own entries below the marker line. ## First-run setup (30–90 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 (~200–800 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: @@ -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.