mirror of https://github.com/garrytan/gstack.git
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
parent
e7110aac93
commit
1ac4683b7b
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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:<terminalPort>/ws`,
|
||||
│ [`gstack-pty.<token>`])
|
||||
|
|
|
|||
|
|
@ -9,8 +9,9 @@ the command output.
|
|||
|
||||
## `BRAIN_SYNC: brain repo detected: <url>`
|
||||
|
||||
**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 <url>`
|
||||
## `gstack-artifacts-init: ~/.gstack/ is already a git repo pointing at: <url>`
|
||||
|
||||
**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 <url>` (the
|
||||
command's own suggestion), or `gstack-brain-uninstall` first, then re-init
|
||||
with the new URL. Neither deletes your data.
|
||||
|
||||
---
|
||||
|
||||
## `Remote not reachable: <url>`
|
||||
## `Remote not reachable via SSH: <url>`
|
||||
|
||||
**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 '<name>'`
|
||||
## `Failed to create or find '<name>'. Try --remote <url>.`
|
||||
|
||||
**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
|
||||
<url>` to re-seed the canonical config.
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue