Architecture

Files are the truth; the index is disposable

Everything people and agents write is a plain file in git: Markdown entries, instrument files, catalogue reviews and experiment folders. rnd.db is a SQLite index built from those files. It is gitignored and can be deleted at any time.

entries/YYYY/*.md ─┐
instruments/*.md  ─┼─► model.py (parse + validate) ─► store.py ─► rnd.db (FTS5)
catalogs/*/       ─┘                                                 │
                                                                     ▼
                                  cli.py ◄── search · show · list · tools · stats · sql
                                    │
                                    └──► readouts.py ─► readouts KBs (read-only)

All modules live in mcptoolshop_rnd/; rnd/ is a compatibility alias that re-exports them.

Modules

module	job
mcptoolshop_rnd/frontmatter.py	a small YAML-subset parser (scalars, wrapped scalars, inline and block lists, lists of maps, block scalars), so there is no PyYAML dependency
mcptoolshop_rnd/model.py	the vocabularies (kinds, tiers, confidence) and entry validation, which reports errors and warnings rather than raising
mcptoolshop_rnd/catalog.py	catalogue sync through the GitHub GraphQL API (via gh), lanes and families, and merging the studio review
mcptoolshop_rnd/store.py	the SQLite schema, index build, change detection and search
mcptoolshop_rnd/readouts.py	federated, read-only search over each readouts knowledge base’s FTS table
mcptoolshop_rnd/cli.py	the argparse front end, structured errors and exit codes

Index lifecycle

• Change detection. A fingerprint over every input file (the file count plus the newest modification time) is stored in the index. Any read command compares it and rebuilds when it differs.
• Safe rebuild. The build writes a temporary database and swaps it in only when every file validates. A file with errors leaves the last good index in place, and readers are told so.
• Read-only readers. Queries open the index with mode=ro, so rnd sql cannot change it.

Catalogues

A catalogue is three files under catalogs/<name>/:

• source.json: where it comes from (upstream repo, path, licence).
• catalog.json: the snapshot, pinned to an upstream commit. Generated by rnd catalog sync; never hand-edited.
• review.json: the studio’s fit (direct, adjacent, general) and notes, per family and per item. People edit this, and validation rejects unknown fits and items.

Instruments

An instrument is an entry with kind: instrument in instruments/, plus instrument_status, invoke, when and where. When a studio repo becomes a tool that research can use, its instrument file is added or updated in the same change.

Readouts federation

rnd readouts finds each knowledge base by its folder layout, opens its SQLite database read-only, and queries its own full-text table. Words are prefix-matched and ANDed, or ORed with --any. It never writes to readouts. The two stores stay independent, so the bench can be messy without touching the shelf.