---
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:

1. What the 9 new skills do (so the agent knows when to invoke them)
2. The new `archive-crawler.scan_paths:` config requirement
3. The new `gbrain skillpack uninstall` subcommand
4. 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

```bash
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:

```bash
# 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`:

```yaml
# 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:

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

```bash
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:

```bash
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

```bash
# 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.
