# v0.5.0 Migration: Live Sync + Verification

This migration runs automatically when upgrading from v0.4.x to v0.5.0.

## 1. Set up live sync (MUST DO)

Your brain repo is the source of truth. Until now, `gbrain sync` had to be run
manually, which meant the vector DB could silently fall behind. Corrections to
brain pages wouldn't appear in search until someone remembered to sync.

**Read GBRAIN_SKILLPACK.md Section 18** for the full guide. The short version:

1. **Check your connection string.** If `DATABASE_URL` uses Supabase's Transaction
   mode pooler, sync will silently skip most pages (`.begin() is not a function`).
   Switch to Session mode pooler or direct connection. This is the #1 cause of
   "sync ran but nothing happened."

2. **Set up automatic sync.** Pick what fits your environment:
   - Cron (recommended for agents): `gbrain sync --repo /path/to/brain && gbrain embed --stale` every 5-30 min
   - Watch mode: `gbrain sync --watch --repo /path/to/brain` under a process manager
   - GitHub webhook or git hook for instant sync

3. **Verify it works.** Don't just check that the command ran. Push a test change
   to the brain repo, wait for the sync cycle, then `gbrain search` for the new
   content. If the old content comes back, sync failed silently.

## 2. Run the verification runbook

New in v0.5.0: `docs/GBRAIN_VERIFY.md` is a 6-check runbook that catches silent
failures. Run through it once after upgrading:

```bash
gbrain doctor --json          # schema OK
gbrain config get sync.last_run   # recent timestamp
gbrain stats                  # page count + embed coverage
gbrain search "test query"   # search returns results
gbrain embed --stale          # catch unembedded chunks
gbrain check-update --json    # update check working
```

The critical check: compare page count (`gbrain stats`) against syncable file count
in the repo. If page count is significantly lower, the pooler bug is silently
skipping pages. Fix the connection string and run `gbrain sync --full`.

## 3. Tell the user what happened

After completing steps 1-2, report:
- Whether live sync was set up and which approach was chosen
- Verification results (all 6 checks)
- Any issues found and how they were fixed (especially the pooler bug)
