--- version: 0.9.0 feature_pitch: headline: "5 new deterministic tools, smart file uploads, production-grade skills" description: "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." tiers: - name: "Core tools (everyone)" description: "publish, backlinks, lint, report -- zero external deps, work immediately." setup: "gbrain check-update && gbrain upgrade" - name: "With Supabase Storage" description: "upload-raw, signed-url, file migration lifecycle. Large files in cloud, git stays lean." setup: "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](https://x.com/garrytan/status/2042925773300908103) pattern. ### 1. `gbrain publish` -- shareable HTML from brain pages ```bash 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 ```bash 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 ```bash 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 ```bash 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 ```bash gbrain files upload-raw --page --type gbrain files signed-url ``` 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 ```bash 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 ` | `gbrain publish --password` | | `node scripts/upload-raw-source.mjs --page ` | `gbrain files upload-raw --page ` | | `node scripts/save-report.mjs --cron ` | `gbrain report --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 ` | | Manual page quality review | `gbrain lint --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 \ --page --type transcript # New: gbrain files upload-raw --page --type transcript ``` ``` # Old: node /data/.openclaw/workspace/scripts/brain-publish.mjs --password # New: gbrain publish --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 ```bash # 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: ```bash # 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: ```bash gbrain files status gbrain files mirror gbrain files redirect ``` ### Step 5: Update cron jobs If you have cron jobs that call custom scripts, update them: ```bash # Old cron entry: */30 * * * * node /path/to/scripts/validate-brain-links.mjs # New: */30 * * * * gbrain files verify ``` ### Step 6: Add new maintenance crons (recommended) ```bash # 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 ```bash 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 ```