mirror of
https://github.com/garrytan/gstack.git
synced 2026-09-15 09:25:28 +02:00
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:
co-authored by
Claude Fable 5
parent
e7110aac93
commit
1ac4683b7b
+12
-11
@@ -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: <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.
|
||||
|
||||
Reference in New Issue
Block a user