setup

What this skill does

# Setup GBrain

Set up GBrain from scratch. Target: working brain in under 5 minutes.

## Contract

- Setup completes with a working brain verified by `gbrain doctor --json` (all checks OK).
- The brain-first lookup protocol is injected into the project's AGENTS.md or equivalent.
- Live sync is configured and verified (a test change pushed and found via search).
- Schema state is tracked in `~/.gbrain/update-state.json` so future upgrades know what the user adopted or declined.
- No Supabase anon key is requested; GBrain uses only the database connection string.

## Install (if not already installed)

```bash
bun add github:garrytan/gbrain
```

## How GBrain connects

GBrain connects directly to Postgres over the wire protocol. NOT through the
Supabase REST API. You need the **database connection string** (a `postgresql://` URI),
not the project URL or anon key. The password is embedded in the connection string.

Use the **Transaction pooler** connection string (port 6543), not the direct
connection (port 5432). The direct hostname resolves to IPv6 only, which many
environments can't reach. Find it: click **Connect** in the top navigation bar,
then **Connection String** > **Transaction pooler**, and copy the string.

**Do NOT ask for the Supabase anon key.** GBrain doesn't use it.

## Why Supabase

Supabase gives you managed Postgres + pgvector (vector search built in) for $25/mo:
- 8GB database + 100GB storage on Pro tier
- No server to manage, automatic backups, dashboard for debugging
- pgvector pre-installed, just works
- Alternative: any Postgres with pgvector extension (self-hosted, Neon, Railway, etc.)

## Prerequisites

- A Supabase account (Pro tier recommended, $25/mo) OR any Postgres with pgvector
- An OpenAI API key (for semantic search embeddings, ~$4-5 for 7,500 pages)
- A git-backed markdown knowledge base (or start fresh)

## Available init options

- `gbrain init --supabase` -- interactive wizard (prompts for connection string)
- `gbrain init --url <connection_string>` -- direct, no prompts
- `gbrain init --non-interactive --url <connection_string>` -- for scripts/agents
- `gbrain doctor --json` -- health check after init

There is no `--local`, `--sqlite`, or offline mode. GBrain requires Postgres + pgvector
(local PGLite or remote Supabase / self-hosted).

## Phase A.5: Choose Topology (run BEFORE Phase A)

GBrain supports three deployment shapes. Pick the right one before installing,
because picking wrong creates contention or duplicate work that's painful to
unwind. Read `docs/architecture/topologies.md` for the full picture; the short
version:

Ask the user this BEFORE running `gbrain init`:

> "Three deployment shapes:
>  1. **Single brain (default)** — one machine, one DB, one agent. Pick this if
>     unsure.
>  2. **Cross-machine thin client** — your brain lives on another machine
>     (e.g. brain-host) running `gbrain serve --http`, and this install just
>     calls it over MCP. No local DB on this machine.
>  3. **Per-worktree code + shared remote artifacts** — Conductor users with
>     multiple worktrees indexing the same code repo. Each worktree owns its
>     own code engine; artifacts live on a shared remote brain. For code
>     engines, configure Voyage's code-tuned model:
>     `gbrain init --pglite --embedding-model voyage:voyage-code-3 --embedding-dimensions 1024`
>     (full guidance in `docs/architecture/topologies.md` Topology 3).
>
>  Which fits?"

### If the user picks 1 (single brain) — proceed to Phase A

Continue with the existing `gbrain init --supabase` / `--pglite` setup below.

### If the user picks 2 (cross-machine thin client)

1. **Confirm a host already exists.** Ask: "Is the remote `gbrain serve --http`
   already running on the host machine?" If no, the user needs to set up the
   host first (Phases A-C on the host, then `gbrain serve --http`). Don't try
   to run init on this machine until the host is up.

2. **Get OAuth credentials from the host operator.** Ask the user to run
   on the host:
   ```bash
   gbrain auth register-client <name> \
     --grant-types client_credentials \
     --scopes read,write,admin
   ```
   The `admin` scope is required because `gbrain remote ping` and
   `gbrain remote doctor` (Tier B convenience commands) call MCP ops with
   `admin` scope. `read,write` alone breaks ping/doctor.

3. **Run thin-client init on this machine:**
   ```bash
   gbrain init --mcp-only \
     --issuer-url https://<host>:<port> \
     --mcp-url https://<host>:<port>/mcp \
     --oauth-client-id <id> \
     --oauth-client-secret <secret>
   ```
   Or set `GBRAIN_REMOTE_CLIENT_SECRET` env var instead of the flag (preferred
   for headless / scripted setup). Pre-flight runs three smoke probes; any
   failure surfaces an actionable error.

4. **Configure your agent's MCP client.** Add a server entry pointing at
   `<mcp_url>` with the bearer token. See `docs/mcp/CLAUDE_DESKTOP.md`,
   `docs/mcp/CLAUDE_CODE.md`, etc. for per-client snippets.

5. **Verify with `gbrain doctor`.** Thin-client doctor runs OAuth discovery,
   token round-trip, and MCP smoke against the host. Should report
   `mode: thin-client` with all checks green.

6. **Skip Phases B, C, C.5, and H entirely.** They're for local engines.
   The host's autopilot handles sync/extract/embed. Thin clients consume
   only.

7. **Continue to Phase D (brain-first lookup).** It works identically over
   MCP — the agent uses the same brain-ops skill to query/search/get_page,
   they just round-trip through the host's `gbrain serve --http`.

If init reports "thin-client config already present", a previous setup
already configured this machine. Refusing without `--force` is the correct
behavior; either accept the existing config or pass `--force` to refresh.

### If the user picks 3 (split-engine per-worktree)

This shape requires per-worktree wiring that gstack handles, not gbrain
directly. gbrain's role is just to run a local engine when `GBRAIN_HOME` is
set — that already works.

Point the user at `docs/architecture/topologies.md` (the Topology 3 section)
for the wiring recipe, then continue with Phase A as normal — `gbrain init`
on this machine sets up the artifact brain (the "default" home). The
per-worktree code engines are configured per-worktree as gstack creates them.

If the user has a remote artifact brain (Topology 2 + 3 combined), follow
the thin-client setup above for the artifact brain instead of Phase A.

## Phase A: Supabase Setup (recommended)

Guide the user through creating a Supabase project:

1. "Go to https://supabase.com and sign up or log in."
2. "Click 'New Project' in the top left."
   - Name: `gbrain`
   - Region: pick the one closest to you
   - Database password: generate a strong one and save it
3. "Wait about 2 minutes for the project to initialize."
4. "Find the connection string: click **Connect** in the top navigation bar,
   then **Connection String** > **Transaction pooler**, and copy the string
   (port 6543)."
5. Initialize gbrain:
   ```bash
   gbrain init --non-interactive --url "postgresql://postgres.[ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres"
   ```
6. Verify: `gbrain doctor --json`

**OpenClaw/Hermes agent instructions:** Store the Supabase access token in your persistent
env as `SUPABASE_ACCESS_TOKEN`. gbrain doesn't store it, you need it for future
`gbrain doctor` runs. Generate at: https://supabase.com/dashboard/account/tokens

## Phase B: BYO Postgres (alternative)

If the user already has Postgres with pgvector:

1. Get the connection string from the user.
2. Run: `gbrain init --non-interactive --url "<connection_string>"`
3. Verify: `gbrain doctor --json`

If the connection fails with ECONNREFUSED and the URL contains `supabase.co`,
the user probably pasted the direct connection (IPv6 only). Guide them to the
Transaction pooler string instead (see Phase A step 4).

## Phase C: First Import

1. **Discover markdown repos.** Scan the environment for git repos with m