mirror of
https://github.com/garrytan/gbrain.git
synced 2026-07-27 21:19:18 +00:00
Garry TanandClaude Fable 5
2d3847da00
Post-ship doc verification against the release diff (#2095 push-based context + #2084 superset hardening), with a cross-model doc review: - push-context.md: version tag corrected to v0.42.43.0; per-call knobs now cover prior_context/days and watch's flag surface accurately; feedback-log writes described as best-effort; synopsis fence-strip described as unconditional. - CLAUDE.md: stale operation count (~47 -> ~90); volunteer_context release reference corrected to v0.42.43.0. - KEY_FILES.md: ci-local entry rewritten to current topology (4-shard parallel default, four Postgres services, transaction-mode PgBouncer + GBRAIN_PGBOUNCER_URL/_DIRECT_URL exports); stale E2E file counts dropped from the selector entry. - TESTING.md: inventory entries for the new #2084 structural pins (cli-exit-verdict-pin, cli-pipe-truncation), the push-context test suite (volunteer-context, watch-command, watch-sigint.serial, cli-format-volunteer), migrate v117 coverage, and the two new E2E files (pgbouncer-teardown env gating, volunteer-context-postgres RLS pin); check:all row corrected (not a superset of verify). - AGENTS.md + RELEASING.md: ci:local descriptions updated to the sharded + pooler topology. - CHANGELOG (wording only, entry preserved): "retrieved" instead of "opened" for the used-signal, pooler scoped to the local CI gate, feedback log labeled best-effort. - llms-config.ts: index the new push-context guide; bundles regenerated (build:llms) and freshness test green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
314 lines
12 KiB
TypeScript
314 lines
12 KiB
TypeScript
/**
|
|
* 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;
|