Files

Garry Tan 7f156c8873 feat: v0.15.0 llms.txt + llms-full.txt + AGENTS.md (#294 )

* feat: llms.txt + llms-full.txt + AGENTS.md (v0.15.0)

Ship three new public artifacts at the repo root so agents that aren't
Claude Code can discover GBrain documentation cleanly:

- AGENTS.md — ~45-line install + operating protocol for non-Claude agents
  (Codex, Cursor, OpenClaw, Aider). Covers install, read order, trust
  boundary, config/debug/migration pointers, fork regeneration. Uses
  relative links so it survives fork/rename.
- llms.txt — llmstxt.org-spec index (H1 + blockquote + Core entry points /
  Configuration / Debugging / Migrations / Philosophy / Optional H2s).
- llms-full.txt — same index with core docs inlined for single-fetch
  ingestion. ~225KB, well under the 600KB FULL_SIZE_BUDGET.

Generator-driven via scripts/build-llms.ts + scripts/llms-config.ts.
LLMS_REPO_BASE env var makes it fork-friendly. bun run build:llms
regenerates both outputs deterministically.

test/build-llms.test.ts has 7 cases: paths resolve on disk, generator
idempotent, llms.txt spec shape, checked-in files match generator output
(drift guard), content contract (RESOLVER / AGENTS / INSTALL referenced),
AGENTS mirrors README + INSTALL_FOR_AGENTS install path, llms-full.txt
under size budget.

Leverage point per Codex review: README.md + INSTALL_FOR_AGENTS.md
install prompts now tell agents to fetch AGENTS.md first. Without this,
the new files were invisible.

Drive-by fix: INSTALL_FOR_AGENTS.md:136 had `git pull origin main` while
the repo's default branch is master (origin/HEAD -> master). Corrected.

Plan + reviews: /plan-eng-review CLEARED, /codex adversarial review
found 15 issues — 7 folded in directly, 3 user tension decisions, 5
stayed as NOT-in-scope with reasoning.

Version bumps to 0.15.0 (new public-artifact feature surface per Step 12
of /ship feature-signal heuristic).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: normalize VERSION to 3-digit to match master

master uses 3-digit semver (0.14.2); my earlier /ship bumped VERSION to
the 4-digit gstack format (0.15.0.0). Revert to 0.15.0 to match
package.json (already 3-digit) and master's convention.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-21 11:51:32 -07:00

2.7 KiB

Raw Permalink Blame History

Agents working on GBrain

This is your install + operating protocol. Claude Code reads ./CLAUDE.md automatically. Everyone else (Codex, Cursor, OpenClaw, Aider, Continue, or an LLM fetching via URL): start here.

Install (5 min)

Clone: git clone https://github.com/garrytan/gbrain ~/gbrain && cd ~/gbrain
Install: bun install
Init the brain: gbrain init (defaults to PGLite, zero-config). For 1000+ files or multi-machine sync, init suggests Postgres + pgvector via Supabase.
Read ./INSTALL_FOR_AGENTS.md for the full 9-step flow (API keys, identity, cron, verification).

Read this order

./AGENTS.md (this file) — install + operating protocol.
./CLAUDE.md — architecture reference, key files, trust boundaries, test layout.
./skills/RESOLVER.md — skill dispatcher. Read before any task.

Trust boundary (critical)

GBrain distinguishes trusted local CLI callers (OperationContext.remote = false, set by src/cli.ts) from untrusted agent-facing callers (remote = true, set by src/mcp/server.ts). Security-sensitive operations like file_upload tighten filesystem confinement when remote = true and default to strict behavior when unset. If you are writing or reviewing an operation, consult src/core/operations.ts for the contract.

Common tasks

Configure: docs/ENGINES.md, docs/guides/live-sync.md, docs/mcp/DEPLOY.md.
Debug: docs/GBRAIN_VERIFY.md, docs/guides/minions-fix.md, gbrain doctor --fix.
Migrate: docs/UPGRADING_DOWNSTREAM_AGENTS.md, skills/migrations/, gbrain apply-migrations.
Everything else: ./llms.txt is the full documentation map. ./llms-full.txt is the same map with core docs inlined for single-fetch ingestion.

Before shipping

Run bun test plus the E2E lifecycle described in ./CLAUDE.md (spin up the test Postgres container, run bun run test:e2e, tear it down). Ship via the /ship skill, not by hand.

Privacy

Never commit real names of people, companies, or funds into public artifacts. See the Privacy rule in ./CLAUDE.md. GBrain pages reference real contacts; public docs must use generic placeholders (alice-example, acme-example, fund-a).

Forks

If you are a fork, regenerate llms.txt + llms-full.txt with your own URL base before publishing: LLMS_REPO_BASE=https://raw.githubusercontent.com/your-org/your-fork/main bun run build:llms.

2.7 KiB Raw Permalink Blame History