/** * llms-config — single source of truth for llms.txt + llms-full.txt. * * Consumed by scripts/build-llms.ts (emits llms.txt, llms-full.txt) and * test/build-llms.test.ts (asserts paths resolve, content contract holds). * * Adding a doc? Add it here and run `bun run build:llms`. The drift-detection * test fails CI if you forget. * * Fork-friendliness: `rawBaseUrl` reads from `LLMS_REPO_BASE` so forks can * regenerate without manual URL rewrites: * LLMS_REPO_BASE=https://raw.githubusercontent.com/fork-org/gbrain/main bun run build:llms */ export type DocEntry = { title: string; description: string; path: string; includeInFull?: boolean; }; export type DocSection = { heading: string; optional?: boolean; entries: DocEntry[]; }; export const PROJECT = { name: "GBrain", summary: "GBrain is a personal knowledge brain and GStack mod for agent platforms. Pluggable engines (PGLite default, Postgres+pgvector for scale), contract-first operations, 26 fat-markdown skills. Teaches agents brain ops, ingestion, enrichment, scheduling, identity, and access control.", repoUrl: "https://github.com/garrytan/gbrain", rawBaseUrl: process.env.LLMS_REPO_BASE ?? "https://raw.githubusercontent.com/garrytan/gbrain/master", }; export const SECTIONS: DocSection[] = [ { heading: "Core entry points", entries: [ { title: "AGENTS.md", description: "Start here if you are not Claude Code. Install order, trust boundary, skill resolver, config/debug/migration pointers.", path: "AGENTS.md", }, { title: "CLAUDE.md", description: "Orientation + resolver. North Star, two axes, architecture + cross-cutting invariants, the reference map pointing at on-demand docs, and the inline ship IRON RULES.", path: "CLAUDE.md", }, { title: "docs/architecture/KEY_FILES.md", description: "Per-file index for the gbrain repo: what each src/ file does + its load-bearing invariants. The on-demand detail CLAUDE.md's reference map routes to.", path: "docs/architecture/KEY_FILES.md", // Link-only until compressed to current-state (still large pre-compression). // Flip to inlined once the doc-history compression lands and the bundle // budget is re-measured. includeInFull: false, }, { title: "docs/architecture/thin-client.md", description: "The thin-client / remote-MCP / cross-modal routing seam: isThinClient detection, callRemoteTool, SSRF-hardened URL validation, per-command routing.", path: "docs/architecture/thin-client.md", includeInFull: false, }, { title: "INSTALL_FOR_AGENTS.md", description: "9-step agent installation.", path: "INSTALL_FOR_AGENTS.md", }, { title: "skills/RESOLVER.md", description: "Skill dispatcher. Read first for any task.", path: "skills/RESOLVER.md", }, { title: "README.md", description: "Project overview, benchmarks, 30-minute setup.", path: "README.md", }, ], }, { heading: "Configuration", entries: [ { title: "docs/ENGINES.md", description: "PGLite vs Postgres trade-off and when to migrate.", path: "docs/ENGINES.md", }, { title: "docs/GBRAIN_RECOMMENDED_SCHEMA.md", description: "MECE directory structure (people/, companies/, concepts/).", path: "docs/GBRAIN_RECOMMENDED_SCHEMA.md", // v0.40.6.0: 64KB reference doc. Web index entry stays; the single-fetch // bundle gets the README + setup guides instead. Keeps llms-full.txt // under the 600KB budget as CLAUDE.md grows with each release. includeInFull: false, }, { // Re-inlined: the CLAUDE.md resolver restructure (per-file index moved to // docs/architecture/KEY_FILES.md, link-only) freed ~530KB of bundle // headroom, so this value-explainer rides the single-fetch bundle again. title: "docs/what-schemas-unlock.md", description: "Why schemas matter: 7 killer use cases (4000 invisible meetings, founder ops brain, research brain, legal brain, team brain, agent-as-co-curator) + the structural argument for typed page kinds. Read this before pitching schema authoring (v0.40.7.0).", path: "docs/what-schemas-unlock.md", }, { title: "docs/schema-author-tutorial.md", description: "5-minute walkthrough: fork the bundled pack, add a custom `researcher` type, backfill existing pages via `gbrain schema sync --apply`, prove the T1.5 wiring via `gbrain whoknows` (v0.40.7.0).", path: "docs/schema-author-tutorial.md", }, { title: "docs/guides/live-sync.md", description: "Incremental markdown sync setup.", path: "docs/guides/live-sync.md", }, { title: "docs/guides/cron-schedule.md", description: "Recurring job scheduling.", path: "docs/guides/cron-schedule.md", }, { title: "docs/guides/minions-deployment.md", description: "Deploying the gbrain jobs worker: crontab + watchdog, inline --follow, systemd/Procfile/fly.toml, upgrade checklist.", path: "docs/guides/minions-deployment.md", // v0.41.8.0: 13KB deployment runbook. Web index entry stays; // single-fetch bundle drops it to keep under FULL_SIZE_BUDGET // (CLAUDE.md grew past 600KB once master's v0.41.2-v0.41.6 + // this wave's annotations landed). Operators read this once; // agents rarely need it in context. includeInFull: false, }, { title: "docs/guides/quiet-hours.md", description: "Notification hold + timezone-aware delivery.", path: "docs/guides/quiet-hours.md", }, { title: "docs/guides/scaling-skills.md", description: "Three-tier architecture for agents with 300+ skills: always-loaded, resolver-routed, and dormant. Per-turn token math, the v0.41.7.0 compact list-format resolver, and the `gbrain doctor` safety net. 306 skills, ~21K tokens freed per turn, zero capability loss.", path: "docs/guides/scaling-skills.md", }, { title: "docs/guides/push-context.md", description: "Push-based context: the brain volunteers confidence-gated pages from the rolling conversation window. Three channels (ambient reflex, volunteer_context op, gbrain watch), config knobs, and the volunteered-vs-used feedback loop.", path: "docs/guides/push-context.md", }, { title: "docs/mcp/DEPLOY.md", description: "MCP server deployment.", path: "docs/mcp/DEPLOY.md", }, ], }, { heading: "AI providers", entries: [ { title: "docs/ai-providers/zeroentropy.md", description: "ZeroEntropy zembed-1 embedding + zerank-2 reranker (hosted): API key, embedding switch, reranker config.", path: "docs/ai-providers/zeroentropy.md", // Setup walkthrough — discoverable in the index, not inlined in the // single-fetch bundle (keeps llms-full.txt under FULL_SIZE_BUDGET). includeInFull: false, }, { title: "docs/ai-providers/llama-server-reranker.md", description: "Local reranker via llama.cpp --reranking: Qwen3-Reranker or self-hosted ZE weights, --alias setup, gbrain config keys, cold-start timeout, budget-cap interaction.", path: "docs/ai-providers/llama-server-reranker.md", includeInFull: false, }, ], }, { heading: "Debugging", entries: [ { title: "docs/GBRAIN_VERIFY.md", description: "7-check post-setup verification. Start here when something feels off.", path: "docs/GBRAIN_VERIFY.md", }, { title: "docs/guides/minions-fix.md", description: "Troubleshooting the Minions job queue.", path: "docs/guides/minions-fix.md", }, { title: "docs/integrations/reliability-repair.md", description: "Data integrity recovery.", path: "docs/integrations/reliability-repair.md", }, ], }, { heading: "Migrations", entries: [ { title: "docs/UPGRADING_DOWNSTREAM_AGENTS.md", description: "Patches for downstream agent skill forks. One section per release.", path: "docs/UPGRADING_DOWNSTREAM_AGENTS.md", // Excluded from inlined bundle (v0.41.7.0): 25KB of release-by-release // migration patches that are valuable as a reference but don't need // to ride along in every llms-full.txt fetch. Pushes the bundle back // under FULL_SIZE_BUDGET after the v0.41.7.0 scaling-skills guide // landed. includeInFull: false, }, { title: "skills/migrations/", description: "Per-version (v0.5.0 - v0.14.1) agent-executable migration instructions.", path: "skills/migrations/", }, { title: "CHANGELOG.md", description: "Release-summary voice + itemized changes + self-repair block per version.", path: "CHANGELOG.md", includeInFull: false, }, ], }, { heading: "Contributing", optional: true, entries: [ { title: "docs/TESTING.md", description: "Test command tiers, the test-isolation lint (R1-R4), the canonical PGLite block, withEnv, the E2E DB lifecycle, and the file taxonomy. Maintainer-facing.", path: "docs/TESTING.md", includeInFull: false, }, { title: "docs/RELEASING.md", description: "Full release + contributor process: pre-ship test requirements, the CHANGELOG voice + release-summary template, the 'To take advantage of vX' block, version migrations, GitHub Actions SHA refresh, PR conventions, community-PR-wave. (Ship IRON RULES stay inline in CLAUDE.md.)", path: "docs/RELEASING.md", includeInFull: false, }, ], }, { heading: "Philosophy", optional: true, entries: [ { title: "docs/ethos/THIN_HARNESS_FAT_SKILLS.md", description: "Why skills live in markdown.", path: "docs/ethos/THIN_HARNESS_FAT_SKILLS.md", includeInFull: false, }, { title: "docs/ethos/MARKDOWN_SKILLS_AS_RECIPES.md", description: "Homebrew for Personal AI.", path: "docs/ethos/MARKDOWN_SKILLS_AS_RECIPES.md", includeInFull: false, }, ], }, { heading: "Optional", optional: true, entries: [ { title: "docs/designs/", description: "Forward-looking designs.", path: "docs/designs/", includeInFull: false, }, { title: "docs/architecture/infra-layer.md", description: "Shared infra patterns.", path: "docs/architecture/infra-layer.md", includeInFull: false, }, ], }, ]; export const INLINE_TIPS = [ "`gbrain doctor [--json] [--fast] [--fix]` - built-in health checks.", "`gbrain orphans [--json]` - pages with zero inbound wikilinks.", "`gbrain repair-jsonb [--dry-run]` - repair v0.12.0 double-encoded JSONB rows.", "`gbrain upgrade` runs post-upgrade + apply-migrations.", ]; // Target ~800KB so llms-full.txt fits in ~200k-token contexts with room to spare. // Bumped 600KB→700KB in v0.41.9.0, then 700KB→750KB once CLAUDE.md crossed 700KB, // then 750KB→800KB in v0.42.10.0 when the #972 global-basename Key Files annotation // (landing alongside master's #1696/#1699 waves) crossed the 750KB line. CLAUDE.md // is ~540KB+ (the bulk of the bundle) and grows ~5-15KB per release with each // feature's Key Files annotation. CLAUDE.md is the whole point of the one-fetch // bundle, so it stays inlined; the budget tracks its legitimate growth. Still fits // comfortably in 200k+ context models. // Generator prints a WARN if exceeded; ship with includeInFull=false exclusions. export const FULL_SIZE_BUDGET = 800_000;