gbrain/skills/migrations/v0.9.0.md

version, feature_pitch

version

feature_pitch

0.9.0

headline description tiers 5 new deterministic tools, smart file uploads, production-grade skills gbrain publish, backlinks, lint, report, and upload-raw. Code+skill pairs -- deterministic TypeScript does the work, skills tell the agent when to use it. Plus TUS resumable uploads, .redirect.yaml pointers, and battle-tested skill patterns. name description setup Core tools (everyone) publish, backlinks, lint, report -- zero external deps, work immediately. gbrain check-update && gbrain upgrade name description setup With Supabase Storage upload-raw, signed-url, file migration lifecycle. Large files in cloud, git stays lean. Configure storage backend, then gbrain files mirror + redirect.

v0.9.0 Migration: Deterministic Tools + Smart File Storage

This is a major upgrade. GBrain now ships deterministic tools alongside skills -- code for data, LLMs for judgment. No database schema changes required.

What's New: 5 Deterministic Commands

These commands run without LLM calls. They are the "code" half of the Thin Harness, Fat Skills pattern.

1. gbrain publish -- shareable HTML from brain pages

gbrain publish brain/people/jane-doe.md                    # local HTML
gbrain publish brain/people/jane-doe.md --password         # auto-generated pw
gbrain publish brain/people/jane-doe.md --password "pw"    # custom pw
gbrain publish brain/people/jane-doe.md --out share.html   # custom output

Strips private data (frontmatter, citations, confirmations, brain links, timeline). Optional AES-256-GCM encryption with client-side decryption. Dark/light mode, mobile-optimized. Self-contained HTML, no server needed.

Skill: skills/publish/SKILL.md tells the agent when to publish, defaults (always encrypt), and sharing workflows (local file, cloud upload + signed URL, static hosting).

2. gbrain check-backlinks check/fix -- enforce the Iron Law

gbrain check-backlinks check --dir /path/to/brain     # report missing back-links
gbrain check-backlinks fix --dir /path/to/brain        # create them
gbrain check-backlinks fix --dir /path/to/brain --dry-run  # preview

Scans all pages for entity mentions (links to people/ and companies/), checks if those entity pages link back. Creates timeline entries for missing back-links.

3. gbrain lint [--fix] -- catch LLM slop

gbrain lint /path/to/brain               # report issues
gbrain lint /path/to/brain --fix         # auto-fix what's fixable
gbrain lint brain/people/jane.md         # lint single file

Catches: LLM preambles ("Of course! Here is..."), wrapping code fences, placeholder dates (YYYY-MM-DD, XX-XX), missing frontmatter, broken citations, empty sections. --fix strips the fixable ones automatically.

4. gbrain report -- audit trail

gbrain report --type enrichment-sweep --title "Weekly Sweep" --content "..."
echo "report body" | gbrain report --type meeting-sync --title "Daily Sync"

Creates: brain/reports/{type}/{YYYY-MM-DD-HHMM}.md with frontmatter. Used by the maintain skill for enrichment sweeps, backlink checks, lint runs.

5. gbrain files upload-raw -- smart file uploads

gbrain files upload-raw <file> --page <slug> --type <type>
gbrain files signed-url <storage-path>

Auto-routes by size: < 100 MB text stays in git, >= 100 MB or media goes to cloud storage via TUS resumable upload (6 MB chunks with retry). Creates .redirect.yaml pointers in the brain repo.

Agent Instructions

Step 1: Verify upgrade

gbrain --version   # should show 0.9.0
gbrain doctor --json

Step 2: Replace custom scripts with built-in commands

This is the key step. If your agent uses custom scripts for any of these operations, swap them for the built-in gbrain commands:

Old pattern (custom script)	New pattern (built-in)
node scripts/brain-publish.mjs <page>	gbrain publish <page> --password
node scripts/upload-raw-source.mjs <file> --page <slug>	gbrain files upload-raw <file> --page <slug>
node scripts/save-report.mjs --cron <type>	gbrain report --type <type> --content "..."
node scripts/validate-brain-links.mjs	gbrain files verify
node scripts/migrate-brain-files.mjs	gbrain files mirror + redirect
Manual back-link checking	gbrain check-backlinks check --dir <brain>
Manual page quality review	gbrain lint <brain> --fix

For each replacement:

1. Find references to the old script in your AGENTS.md, skills, or cron jobs
2. Replace with the gbrain command
3. The gbrain command uses your configured storage backend automatically

Example: update AGENTS.md or skill files:

# Old:
node /data/.openclaw/workspace/scripts/upload-raw-source.mjs <file> \
  --page <slug> --type transcript

# New:
gbrain files upload-raw <file> --page <slug> --type transcript

# Old:
node /data/.openclaw/workspace/scripts/brain-publish.mjs <page> --password

# New:
gbrain publish <page> --password

# Old:
node /data/.openclaw/workspace/scripts/save-report.mjs \
  --cron "enrichment-sweep" --title "Enrichment Sweep" --content "..."

# New:
gbrain report --type enrichment-sweep --title "Enrichment Sweep" --content "..."

Step 3: Run the new tools on your brain

# Check back-link health
gbrain check-backlinks check --dir /path/to/brain

# If gaps found, fix them:
gbrain check-backlinks fix --dir /path/to/brain --dry-run   # preview
gbrain check-backlinks fix --dir /path/to/brain              # apply

# Lint for quality issues
gbrain lint /path/to/brain

# If fixable issues found:
gbrain lint /path/to/brain --fix --dry-run   # preview
gbrain lint /path/to/brain --fix              # apply

# Save a report of what you fixed
gbrain report --type migration \
  --title "v0.9.0 Migration" \
  --content "Ran backlinks fix (N gaps fixed) and lint --fix (M issues fixed)." \
  --dir /path/to/brain

Step 4: Configure storage backend (if not already done)

If your brain repo has binary files (images, PDFs, audio, video), configure cloud storage to keep git lean:

# Supabase Storage (recommended if you already use Supabase)
gbrain config set storage.backend supabase
gbrain config set storage.bucket brain-files
gbrain config set storage.projectUrl https://YOUR-PROJECT.supabase.co
gbrain config set storage.serviceRoleKey YOUR_SERVICE_ROLE_KEY

# Or S3-compatible (AWS, Cloudflare R2, MinIO)
gbrain config set storage.backend s3
gbrain config set storage.bucket brain-files
gbrain config set storage.region us-east-1
gbrain config set storage.accessKeyId YOUR_KEY
gbrain config set storage.secretAccessKey YOUR_SECRET

Then migrate existing binaries:

gbrain files status
gbrain files mirror <brain-dir>
gbrain files redirect <brain-dir>

Step 5: Update cron jobs

If you have cron jobs that call custom scripts, update them:

# Old cron entry:
*/30 * * * * node /path/to/scripts/validate-brain-links.mjs

# New:
*/30 * * * * gbrain files verify

Step 6: Add new maintenance crons (recommended)

# Daily backlink check + auto-fix
0 3 * * * gbrain check-backlinks fix --dir /path/to/brain

# Weekly lint + auto-fix
0 4 * * 0 gbrain lint /path/to/brain --fix

Step 7: Review skill updates

The skill files have been updated to reference gbrain commands:

• skills/ingest/SKILL.md -- uses gbrain files upload-raw for raw sources
• skills/maintain/SKILL.md -- uses gbrain check-backlinks, gbrain lint, gbrain report
• skills/publish/SKILL.md -- NEW skill for gbrain publish
• skills/enrich/SKILL.md -- references gbrain files upload-raw for raw API data
• skills/_brain-filing-rules.md -- documents .redirect.yaml format and commands

Read the updated skills to pick up the new patterns.

Step 8: Done

mkdir -p ~/.gbrain/migrations
echo '{"version":"0.9.0","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","status":"complete","tools_available":["publish","backlinks","lint","report","upload-raw","signed-url"],"scripts_replaced":true}' >> ~/.gbrain/migrations/completed.jsonl