The README explains the thesis in prose and shows real output, but there is no picture of how the pieces fit. Two diagrams are missing (tracked in TODO.md §16):
- Capture path — agent hook →
attempt-hook → spool → daemon → WAL → segments, and where the CLI, UI, MCP server and sync client attach.
- Storage layout — WAL frames, memtable, Arrow IPC segments, manifest generations, and the
.atdb container. docs/storage-format.md is the authority for every box and arrow.
What to do
Hand-authored SVG (or a Mermaid block that renders on GitHub), committed under docs/media/, referenced from README.md and docs/rfcs/0002-storage-engine.md.
- It must be readable on both a light and a dark GitHub background — either neutral strokes that work on both, or a
<picture> element with a light and a dark asset.
- Every label must match a real identifier in the code. A diagram that invents a component is worse than no diagram.
Done when
Both diagrams are in the README/RFC and someone who has not read the code can say what writes to what.
Good first issue for someone who likes drawing systems; ask in the issue if any box is unclear and it will be explained.
The README explains the thesis in prose and shows real output, but there is no picture of how the pieces fit. Two diagrams are missing (tracked in
TODO.md§16):attempt-hook→ spool → daemon → WAL → segments, and where the CLI, UI, MCP server and sync client attach..atdbcontainer.docs/storage-format.mdis the authority for every box and arrow.What to do
Hand-authored SVG (or a Mermaid block that renders on GitHub), committed under
docs/media/, referenced fromREADME.mdanddocs/rfcs/0002-storage-engine.md.<picture>element with a light and a dark asset.Done when
Both diagrams are in the README/RFC and someone who has not read the code can say what writes to what.
Good first issue for someone who likes drawing systems; ask in the issue if any box is unclear and it will be explained.