bothy

The book the next session reads.

A bothy is a stone shelter in the hills, left unlocked for whoever comes next and kept by the people who use it. Inside is a book where each traveler writes what they found — which paths are open, which are blocked and until when — so the next person, arriving cold, can act on it.

bothy is that book for a repository worked on by humans and coding agents. It keeps the typed, numbered facts a project rules by — decisions, parks (scope deferred with the trigger that reopens it), principles, claims about the world and how well they are known, findings, ledger rows — as structured text in git. It checks that every id is unique, every citation resolves, and every ruling is still cited by the code or test that holds it. It renders the markdown people read. And it assembles the context an agent needs for one task, in one call, measured in tokens.

bothy check                    # ids, fields, citations; exit 1 on any failure
bothy show B3                  # one ruling, what it names, what cites it
bothy list parks --area cli    # everything this area has deferred, with its trigger
bothy list decisions --uncited # rulings no code, test or document names yet
bothy pack --area check        # what a session reads before touching the checks
bothy render --check           # the markdown on disk matches the source
bothy new decision --area cli --title "..." --ruling -   # the next id, a new file
bothy amend B3                 # a ruling changed today: date it
bothy park fire K8 --by <id>   # a trigger fired: stop the park, name the ruling

The read examples are real: they run against this repository's own book. The last three write to it, so they show the form: <id> is the ruling you would write first.

The source is TOML anyone can edit with a text editor, one entry per file. The index is built in memory every run and never written. The markdown is a projection. Those three roles — intent, derivation, rendering — are the design.

Status: check, list, show, pack, import, render, new, amend and park fire work. Bothy's own book under bothy/ is twenty-seven rulings and fifteen parks, the first thirty written by hand before the tool existed and the rest by bothy new; docs/book.md is its rendering. import reads acquisition's markdown registry whole, 108 decisions, 53 parks, 6 principles and 5 invariants, with no exception, and render writes six of its eight registry files back byte for byte; the other two differ only by the marker order and index order the design brief predicted. A second grammar, bothy import acquisition-master, reads the registers on acquisition's master branch into the two other kinds that exist, claims and findings: 80 claims and 78 findings with no exception, under a second bothy.toml that declares no area. Ledger rows are parked (K14). Acquisition adopts the tool when its search slice closes; until then it is read-only test data. Everything the tool writes for a reader is written for the smallest model in use. Start at AGENTS.md; the design is docs/design-brief.md.

Leave it as you'd wish to find it.