papers/cards/: structured paper entry pointspapers/notes/: freeform reading and implementation notesquestions/: open questions that own the graph edgesinsights/: reusable claims backed by links, experiments, or work experiencecodes/types/: stable code category hubs that appear as graph-visible summary nodescodes/readings/: concrete source-reading notes that link directly to one or more code types
- Create one card and one note for every new paper.
- Create new paper cards, paper notes, and question notes from the templates in
templates/, not from blank files. - Put AlphaXiv and the concise summary in the card.
- Put freeform analysis only in the note file.
- Add paper relationships only under
questions/* -> ## Related Papers. - Every card must link to its note using
../notes/<paper_id>-note.md. - Every note must link back to its card using
../cards/<paper_id>.md. - Every question must link only to
../papers/cards/<paper_id>.md. - Create
code-typenotes incodes/types/*andcode-readingnotes incodes/readings/*. - Add code relationships only under
codes/readings/* -> ## Related Code Types. - Every code-reading note must link to code types using canonical
../types/<code_id>.mdtargets. - Use
views/paper-view.mdfor the paper table and Graph view for the big picture. - The main Graph view includes only
questions,papers/cards,codes/types, andcodes/readings. - Create insight notes from
templates/insight.mdorscripts/new-insight.py, and keep them scoped to a single claim.
- Use ASCII
paper_idvalues such aspi05,PI07, andgr00t-n1. - Paper card filename:
papers/cards/<paper_id>.md - Paper note filename:
papers/notes/<paper_id>-note.md - Keep the displayed title human-readable, for example
PI0.5. - Keep identifier casing consistent across filenames, frontmatter, and links.
- Install Python 3.8+ and make sure
pythonworks in your terminal from the repo root.
Use the scaffold script to create a matching paper card and note:
python scripts/new-paper.py --paper-id Much_Ado_About_Noising --title "Much Ado About Noising: Dispelling the Myths of Generative Robotic Control" --alphaxiv "https://arxiv.org/pdf/2512.01809"Optional metadata can be filled during creation with --year, --pdf, and --code.
The script renders templates/paper-card.md and templates/paper-note.md, so those templates are the scaffold source of truth.
Use the insight scaffold script to create a working claim note:
python scripts/new-insight.py --insight-id pretrain-not-fully-converged --claim "Pretraining need not fully converge for downstream performance"The script renders templates/insight.md.
Use the ## Evidence section for paper links, experiment references, or concise work experience notes.
Create code category notes from templates/code-type.md and concrete source-reading notes from templates/code-reading.md.
Use these rules:
- Save category notes as
codes/types/<code_id>.md. - Save reading notes as
codes/readings/<reading_id>.md. - Put code-type links only under
## Related Code Types. - Link code types with canonical paths such as
../types/infra.md. - Use the global Graph view to inspect the code-type and code-reading subgraph alongside question and paper-card nodes.
Run the vault integrity checker from the repo root:
python scripts/check-vault.pyIt verifies that every paper card has a matching note, every note has a matching card, card-note links are mutual, paper cards contain the required frontmatter for views/paper-view.md, question files link only to canonical ../papers/cards/<paper_id>.md targets, code-type files contain the required frontmatter, and code-reading files link to canonical ../types/<code_id>.md targets.
The script exits with 0 and prints Vault check passed. when no issues are found, or exits with 1 and prints the collected [ERROR] lines followed by Vault check failed with <n> issue(s)..
Run the Python regression suite from the repo root:
python -m unittest discover -s tests -p "test_*.py" -v