feature_pitch: | v0.25.1 ships the book-mirror flagship plus 8 research-flavored pairings, a real `gbrain skillpack uninstall`, and a hardened privacy CI guard. Existing brains: zero schema migration. Optional new capability: 9 markdown skills installable into your workspace via `gbrain skillpack install --all`.

v0.25.1 — Skills wave migration

TL;DR

If you already have v0.24.0 installed, gbrain upgrade does it. There is no schema migration. Existing brains work unchanged.

This file exists for agents reading the skill set after upgrade. It explains:

What the 9 new skills do (so the agent knows when to invoke them)
The new archive-crawler.scan_paths: config requirement
The new gbrain skillpack uninstall subcommand
The new gbrain book-mirror CLI

Step 0: Watch for the post-install advisory (NEW in v0.25.1)

Every gbrain init and gbrain post-upgrade now ends by printing an agent-readable advisory listing the recommended new skills. If you ran gbrain upgrade and saw a banner like:

========================================================================
gbrain 0.25.1 — RECOMMENDED SKILLS FOR THE AGENT TO INSTALL
========================================================================

…that's the advisory. It explicitly asks you (the agent) to surface the skill list to the user, ask them whether to install, and run the right gbrain skillpack install command if they say yes. Do that first, then return here for the rest.

If the advisory didn't print, your workspace already has all 9 v0.25.1 skills installed (or no managed block was detected). Continue with the verification steps below.

Step 1: Verify the upgrade landed

gbrain --version                  # expect: gbrain 0.25.1
gbrain skillpack list             # expect: 34 skills (was 25 before)
gbrain skillpack uninstall --help # expect: "Inverse of install" in help

If gbrain --version reports 0.24.x, run gbrain upgrade first.

Step 2: Install the new skills (optional)

The 9 new skills are in the bundle but only become active in your workspace after explicit install:

# install just the flagship:
gbrain skillpack install book-mirror

# OR install everything new at once:
gbrain skillpack install --all

The 9 new skills:

book-mirror — flagship. Two-column personalized chapter-by-chapter book analysis. Pairs with gbrain book-mirror CLI.
article-enrichment — turns raw article dumps into structured pages with verbatim quotes.
strategic-reading — reads a book through one specific problem-lens with a do/avoid/watch-for playbook.
concept-synthesis — deduplicates raw concept stubs into a tiered intellectual map.
perplexity-research — brain-augmented web research focused on what's NEW vs already-known.
archive-crawler — universal archivist for personal file archives (REQUIRES gbrain.yml allow-list, see Step 3).
academic-verify — traces a research claim through publication → methodology → raw data → independent replication.
brain-pdf — renders any brain page to publication-quality PDF via the gstack make-pdf binary.
voice-note-ingest — captures voice notes with exact-phrasing preservation; routes to originals/concepts/people/companies/ideas.

Step 3: Configure `archive-crawler` if you installed it

archive-crawler is the only skill in this wave with a hard configuration requirement. It refuses to run unless you explicitly list paths it's permitted to scan in your brain repo's gbrain.yml:

# brain-repo/gbrain.yml
archive-crawler:
  scan_paths:
    - ~/Documents/writing/
    - ~/Dropbox/Archive/
    - /mnt/backup/old-letters/
  # Optional deny list (paths inside scan_paths to exclude):
  # deny_paths:
  #   - ~/Documents/finances/
  #   - ~/Documents/medical/

Without scan_paths, the skill refuses to run. This is deliberate safety: the agent will not infer what's safe to read.

If you skipped installing archive-crawler, no action needed.

Step 4: Use `gbrain book-mirror` (optional, the flagship)

The skill (skills/book-mirror/SKILL.md) walks the agent through:

Locate or download the EPUB / PDF (manual; the skill explains)
Extract chapter text via BeautifulSoup4 (EPUB) or pdftotext -layout (PDF) — produces *.txt files in a temp dir.
Build a context pack (USER.md + SOUL.md + recent reflections
- topic-relevant brain searches).
Invoke the CLI:

gbrain book-mirror \
  --chapters-dir /tmp/books/this-book/chapters \
  --context-file /tmp/books/this-book/context.md \
  --slug this-book \
  --title "This Book Title" \
  --author "Some Author"

Costs ~$0.30 per chapter at Opus (default model). The CLI prints a cost estimate and prompts for confirmation before launching.

Output lands at media/books/<slug>-personalized.md in your brain.

Step 5: `gbrain skillpack uninstall` (when you want it)

If you ever want to remove a skill from your workspace:

gbrain skillpack uninstall book-mirror

Symmetric to install:

Refuses if the slug isn't in gbrain's cumulative-slugs receipt (won't nuke a row you hand-added — exit 2 with a clear message pointing you at manual cleanup).
Refuses if any installed file diverges from the bundle (you've edited it locally) unless you pass --overwrite-local.
Atomic: if any file is blocked, the whole uninstall refuses before any file is removed. No half-uninstalled state.

Step 6: Privacy CI guard (operator-relevant only if you ship gbrain forks)

scripts/check-privacy.sh now also blocks /data/brain/ and /data/.openclaw/ literals in tracked files (these are fork-specific filesystem paths from gbrain's upstream). Seven historical files are allow-listed. If your fork has bun run test wired up, this runs automatically.

If your fork hits an unexpected privacy-guard failure, check that the path actually needs to be in committed code (vs read from environment / config) and add to the script's allow-list with a comment if legitimate.

Verify the outcome

# Skills installed?
gbrain skillpack list | grep -E "book-mirror|article-enrichment|strategic-reading"

# Doctor reports clean?
gbrain doctor --json | jq '.status'   # expect: "ok"

# CLI commands wired?
gbrain --tools-json | grep -i book-mirror   # may not list since it's CLI-only
gbrain skillpack uninstall --help | head -1

If anything fails

File an issue at https://github.com/garrytan/gbrain/issues with:

output of gbrain doctor --json
contents of ~/.gbrain/upgrade-errors.jsonl if it exists
which step in this migration broke

Thank you. The cross-model review trail (Eng + Codex outside voice) caught real bugs before they shipped, but production exposes things review cannot. Your feedback closes the loop.

v0.25.1