7f156c8873
* 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>
60 lines
2.7 KiB
Markdown
60 lines
2.7 KiB
Markdown
# 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)
|
|
|
|
1. Clone: `git clone https://github.com/garrytan/gbrain ~/gbrain && cd ~/gbrain`
|
|
2. Install: `bun install`
|
|
3. Init the brain: `gbrain init` (defaults to PGLite, zero-config). For 1000+ files or
|
|
multi-machine sync, init suggests Postgres + pgvector via Supabase.
|
|
4. Read [`./INSTALL_FOR_AGENTS.md`](./INSTALL_FOR_AGENTS.md) for the full 9-step flow
|
|
(API keys, identity, cron, verification).
|
|
|
|
## Read this order
|
|
|
|
1. `./AGENTS.md` (this file) — install + operating protocol.
|
|
2. [`./CLAUDE.md`](./CLAUDE.md) — architecture reference, key files, trust boundaries,
|
|
test layout.
|
|
3. [`./skills/RESOLVER.md`](./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/ENGINES.md),
|
|
[`docs/guides/live-sync.md`](./docs/guides/live-sync.md),
|
|
[`docs/mcp/DEPLOY.md`](./docs/mcp/DEPLOY.md).
|
|
- **Debug:** [`docs/GBRAIN_VERIFY.md`](./docs/GBRAIN_VERIFY.md),
|
|
[`docs/guides/minions-fix.md`](./docs/guides/minions-fix.md), `gbrain doctor --fix`.
|
|
- **Migrate:** [`docs/UPGRADING_DOWNSTREAM_AGENTS.md`](./docs/UPGRADING_DOWNSTREAM_AGENTS.md),
|
|
[`skills/migrations/`](./skills/migrations/), `gbrain apply-migrations`.
|
|
- **Everything else:** [`./llms.txt`](./llms.txt) is the full documentation map.
|
|
[`./llms-full.txt`](./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`.
|