docs: live sync setup + verification runbook + API key loading (#24)

* docs: add SKILLPACK Section 18 — Live Sync (MUST ADD)

Contract-first guide for keeping the vector DB in sync with the brain
repo. Documents the pooler prerequisite (Session mode required for
transactions), sync + embed primitives, four example approaches (cron,
--watch, webhook, git hook), isSyncable exclusions, silent skip warning,
and OpenClaw/Hermes cron registration examples.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: add GBRAIN_VERIFY.md installation verification runbook

Six-check runbook: schema (doctor), skillpack loaded, auto-update,
live sync (coverage check + embed check + end-to-end push-and-search
test), embedding coverage, brain-first lookup protocol. Emphasizes
"sync ran" != "sync worked" — the real test is searching for corrected
text after a push.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: add setup Phases H (Live Sync) and I (Verification)

Phase H: MUST ADD live sync setup — pooler prerequisite check, automatic
sync configuration (agent picks approach), sync+embed chaining, coverage
verification. Phase I: run GBRAIN_VERIFY.md end-to-end before declaring
setup complete.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: add install steps 8-9 (live sync + verification)

Step 8: set up automatic sync with SKILLPACK Section 18 reference.
Step 9: run GBRAIN_VERIFY.md runbook. Add GBRAIN_VERIFY.md to docs
section.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: add API key loading instructions to CLAUDE.md

Source ~/.zshrc before running Tier 2 tests so OPENAI_API_KEY and
ANTHROPIC_API_KEY are available. Without this, embedding and skills
tests skip silently.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: bump version to v0.5.0

Live sync, verification runbook, API key loading instructions.
Version markers updated in SKILLPACK and RECOMMENDED_SCHEMA.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: add anti-hand-roll rule to skill routing in CLAUDE.md

Explicitly prohibit manually running git commit + push + gh pr create
when /ship is available. /ship handles VERSION, CHANGELOG,
document-release, reviews, and coverage audit. Hand-rolling skips
all of these. Added "commit and ship" / "push and ship" variants
to the ship routing rule.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: changelog voice rule + rewrite 0.5.0 changelog to sell the upgrade

CLAUDE.md: add changelog voice guidance — lead with benefits, not
implementation details. Make users want to upgrade.

CHANGELOG: rewrite 0.5.0 entries from dry feature descriptions to
capability-focused bullets ("your brain never falls behind" not
"SKILLPACK Section 18 added").

SKILLPACK Section 17: update the auto-update message template to
instruct agents to sell the upgrade, not just summarize the diff.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: add v0.5.0 migration directive for live sync + verification

Agents upgrading from v0.4.x will automatically: check their pooler
connection string, set up automatic sync, and run the verification
runbook. Without this migration file, upgrading agents would learn
about live sync (by re-reading Section 18) but wouldn't set it up.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: sharpen migration file guidance in CLAUDE.md

Replace vague "requires agent action" with concrete trigger list:
new setup steps existing users don't have, MUST ADD skillpack sections,
schema changes, deprecated commands, new verification steps, new crons.
Add the key test: "if an existing user upgrades and does nothing else,
will their brain work worse?"

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: make Section 17 upgrade flow work for direct user requests

Section 17 was structured as a cron-initiated flow only. An agent
handling "upgrade gbrain" might just run the command and stop, missing
the post-upgrade steps where the value is (re-read skills, run
migrations, schema sync). Added explicit entry point for direct
upgrade requests. Made Steps 2-4 more concrete about where to find
files and why migrations can't be skipped.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* test: add E2E sync tests — git-to-DB pipeline (11 tests)

Tests the full sync lifecycle against real Postgres+pgvector:
- First sync imports all pages from a git repo
- Second sync with no changes returns up_to_date
- Incremental sync picks up new files (add → commit → sync → verify)
- Incremental sync picks up modifications — THE CRITICAL TEST:
  corrected text appears in DB and keyword search after sync
- Incremental sync handles deletes
- Non-syncable files are excluded (README, .raw/, ops/)
- Sync state (last_commit, last_run) persisted to config
- Sync logged to ingest_log
- --full reimports everything
- --dry-run shows changes without applying

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: strengthen CLAUDE.md to always run ALL test tiers

Replace passive "source zshrc" suggestion with ALWAYS directive.
Explicitly state that "run all tests" means ALL tiers including
Tier 2 with API keys. Do not skip Tier 2 just because keys need
loading.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: Tier 2 E2E tests — correct openclaw CLI invocation

The tests used `openclaw -p` which doesn't exist. The correct command
is `openclaw agent --local --agent <id> --message <prompt>`. Also fixed
JSON output parsing (structured JSON goes to stderr, not stdout — use
non-JSON mode instead). Fixed ingest test to assert on agent response
text rather than test DB state (the agent writes to its own configured
DB, not the ephemeral test DB).

82 tests pass, 0 fail, 0 skip across all 5 E2E files.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

skills/migrations/v0.5.0.md

@@ -0,0 +1,50 @@
+# 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)

skills/setup/SKILL.md

@@ -224,6 +224,56 @@ If they agree:
 
 If already configured or user declines, skip.
 
+## Phase H: Live Sync Setup (MUST ADD)
+
+The brain repo is the source of truth. If sync doesn't run automatically, the
+vector DB falls behind and gbrain returns stale answers. This phase is not optional.
+
+Read `docs/GBRAIN_SKILLPACK.md` Section 18 for the full reference. Key points:
+
+1. **Check the connection pooler first.** Sync uses transactions on every import.
+   If `DATABASE_URL` uses Supabase's Transaction mode pooler, sync will throw
+   `.begin() is not a function` and silently skip most pages. Verify the connection
+   string uses Session mode (port 6543, Session mode) or direct (port 5432).
+
+2. **Set up automatic sync.** Choose the approach that fits your environment:
+   - **Cron** (recommended for agents): register a cron every 5-30 minutes:
+     `gbrain sync --repo /data/brain && gbrain embed --stale`
+   - **Watch mode**: `gbrain sync --watch --repo /data/brain` under a process
+     manager. Pair with a cron fallback (watch exits after 5 consecutive failures).
+   - **Webhook or git hook**: if available in your environment.
+
+3. **Verify sync works.** Don't just check that the command ran. Check that it
+   worked:
+   - `gbrain stats` should show page count close to syncable file count in the repo.
+   - If page count is way too low, the pooler bug is silently skipping pages.
+   - Push a test change and confirm it appears in `gbrain search`.
+
+4. **Chain sync + embed.** Always run both: `gbrain sync --repo <path> && gbrain
+   embed --stale`. For small syncs, embeddings are generated inline. The `embed
+   --stale` is a safety net for any stale chunks.
+
+Tell the user: "Live sync is configured. The brain will stay current automatically.
+I'll verify it's working in the next phase."
+
+## Phase I: Full Verification
+
+Run the full verification runbook to confirm the entire installation is working.
+
+1. Read `docs/GBRAIN_VERIFY.md`
+2. Execute each check in order
+3. Report results to the user
+4. Fix any failures before declaring setup complete
+
+Every check in the runbook should pass. The most important one is check 4 (live
+sync actually works): push a change, wait for sync, search for the corrected text.
+"Sync ran" is not the same as "sync worked."
+
+Tell the user: "I've verified the full GBrain installation. Here's the status of
+each check: [list results]. Everything is working / [specific item] needs attention."
+
+If already configured or user declines, skip.
+
 ## Schema State Tracking
 
 After presenting the recommended directories (Phase C/E) and the user selects which
@@ -245,3 +295,8 @@ re-suggesting things the user already declined.
 - `gbrain doctor --json` -- health check
 - `gbrain check-update --json` -- check for updates
 - `gbrain embed refresh` -- generate embeddings
+- `gbrain embed --stale` -- backfill missing embeddings
+- `gbrain sync --repo <path>` -- one-shot sync from brain repo
+- `gbrain sync --watch --repo <path>` -- continuous sync polling
+- `gbrain config get sync.last_run` -- check last sync timestamp
+- `gbrain stats` -- page count + embed coverage