version: 0.21.0 feature_pitch: headline: "Code Cathedral II — chunk-grain FTS, qualified symbols, structural edges." one_liner: "Natural-language queries now rank docstring matches first. CHUNKER_VERSION 3→4 rolls the new chunker over existing code pages automatically on next sync." user_action_required: true

v0.21.0 — Code Cathedral II

This release is the biggest code-search upgrade in gbrain history. Chunk-grain FTS with doc_comment Weight A ranks natural-language queries against docstrings above prose. CHUNKER_VERSION 3 → 4 folds into content_hash so every existing code page re-chunks. File classifier widened from 9 to 35 extensions. Markdown fence extraction, sync --all cost preview, and reconcile-links batch command ship alongside the chunker upgrade.

Schema migrations applied automatically

v27 — cathedral_ii_foundation — adds code_edges_chunk, code_edges_symbol, sources.chunker_version, and new content_chunks columns (parent_symbol_path, doc_comment, symbol_name_qualified, search_vector). Includes the chunk-grain FTS trigger that builds from setweight(to_tsvector('english', doc_comment), 'A') || setweight(to_tsvector('english', chunk_text), 'B') || setweight(to_tsvector('english', symbol_name_qualified), 'A').
v28 — cathedral_ii_chunk_fts_backfill — populates search_vector on every existing chunk so day-1 queries already rank correctly.

These run as part of gbrain upgrade → gbrain apply-migrations. No manual DDL needed.

What the agent should do after upgrading

Confirm migrations landed:
```
gbrain doctor
```
Look for schema_version: 28. If lower, run gbrain apply-migrations --yes.
Pick a backfill path. The CHUNKER_VERSION bump + sources.chunker_version gate means existing code pages must re-chunk for the new shape to take effect. Two paths:

Automatic (recommended): next gbrain sync --source <id> detects the version mismatch and forces a full re-walk regardless of git HEAD equality. No cost preview, no user interaction. The Layer 12 SP-1 fix from codex's second-pass review.

Immediate: preview cost, then reindex every code page now.
```
gbrain reindex-code --dry-run       # preview token count + $USD cost
gbrain reindex-code --yes           # reindex all code pages
gbrain reindex-code --source <id> --yes  # scope to one source
```
On non-TTY (automation / cron) reindex-code without --yes emits a ConfirmationRequired envelope and exits 2 — same shape as sync --all. The envelope matches v0.19.0's StructuredAgentError.
Verify chunk-grain FTS works. A query that mentions a concept in a docstring (not just the function body) should rank higher than a page that mentions it only in prose:
```
gbrain query "whatever your docstring says"
```
Expected: top hit is the chunk whose doc_comment matches.
(Optional) Reconcile doc↔impl links. v0.19.0 Layer 6 forward-extracted code refs from markdown pages when they imported, but edges dropped if the code page hadn't imported yet. v0.21.0's reconcile-links batch-scans every markdown page and idempotently reinserts missing edges:
```
gbrain reconcile-links              # full run
gbrain reconcile-links --dry-run    # preview only
gbrain reconcile-links --json       # machine output
```
Respects auto_link=false config (prints warn + exits 0 when disabled).

Widened file classifier — more languages sync now

Previous classifier recognized 9 extensions as code. v0.21.0 widens to 35 (Rust, Ruby, Java, C#, C/C++, Swift, Kotlin, Scala, PHP, Elixir, Elm, OCaml, Dart, Zig, Solidity, Lua, shell, etc.). If your repo contains source files in languages beyond TS/JS/Py/Go, they'll flow through the code chunker on next sync. No action needed — detectCodeLanguage handles dispatch.

Flag in `pending-host-work.jsonl`

The migration orchestrator emits a backfill-prompt phase that prints the two backfill choices directly. No pending-host-work.jsonl entry is written — the choice is user-driven and ephemeral (either reindex now or wait for next sync).

When NOT to run the migration

Never skip it. v0.21.0 is fully backward-compatible at the API level (page-grain FTS shape preserved externally; chunk-grain is internal only). Skipping the migration means agents miss doc_comment Weight A ranking and the chunker_version gate never fires — existing code pages silently stay on CHUNKER_VERSION 3 forever until you sync with --full.

v0.21.0