For AI assistants
The reader of these docs is assumed to be working with an assistant, so that is a supported path rather than something tolerated.
/docs/all.md
Section titled â/docs/all.mdâEvery page, concatenated, in sidebar order, with stable headings and each pageâs URL under its title. Generated at build time from the same sources as the site by a script in the docs repository, never hand-maintained, so it cannot drift. Drop it into a context window and ask questions against it.
/llms.txt
Section titled â/llms.txtâThe conventional discovery file: what Beluga is, the key pages, a
link to all.md, and the invariants in brief.
The invariants page
Section titled âThe invariants pageâThe invariants is written to be pasted verbatim into an
assistantâs instructions or a forkâs CLAUDE.md. Those eight rules are the things
an assistant cannot know from general knowledge, and the things that produce code
which compiles, passes review, and is wrong when violated.
A CLAUDE.md for your fork is a ready-made file.
What an assistant gets wrong without this
Section titled âWhat an assistant gets wrong without thisâFrom experience, in order of cost:
- Verifying an outbound webhook against a re-serialised body. Passes in testing, fails on the first payload with different key ordering.
- Marking an order paid on the success redirect.
- Sending a price from the client âto save a queryâ.
- Adding a column to one dialect file.
- Mounting an admin route outside the admin router, or forgetting the security test.
- Writing to Stripe on save.
- Giving a digital product a weight of zero instead of excluding it.
Each is on the invariants page or in Gotchas.
In the repository itself
Section titled âIn the repository itselfâdocs/tasks/README.md holds the invariants and conventions;
docs/building-on-beluga.md is the map of which files are yours to change; and
the task briefs are written to be handed to an agent cold. An assistant pointed at
the repository should read those three before anything else.