Luria documentation

Luria keeps a record of what a project knows — decisions, principles, a changelog, a devlog, or whatever families the project declares. Every entry has a name something can cite, a standing that says whether it still holds, and rules the lint enforces; every view is generated from those entries.

This page is the map, organized by what you are trying to do. (luria lint checks that every page in docs/ is listed here, so the map cannot silently rot.)

Already have a corpus? You do not need to redesign it into a Luria-shaped repository. Pick one distinction or dependency worth making explicit, wrap Luria around it, and add governance as it earns its keep: start with Adopt Luria around an existing corpus, then Adopting Luria and Importing an existing corpus.

Tutorials

Learn Luria by building a working record, start to finish.

• Quickstart — install, scaffold, file, lint: the whole loop in ten minutes, including breaking the record on purpose to see a finding.
• Build a governed RFC process — declare schemes, vocabularies and typed references for RFCs, decisions and implementations, then watch a supersession surface.
• Build a lineage with chains — state succession edges between entries and let Luria derive the line, its siblings, facets and invariant.
• Adopt Luria around an existing corpus — put a record around material that already exists.

Concepts

Understand the model and the distinctions Luria preserves. Read Concepts first; go to a focused page when you need one distinction in depth; go to Designing a record when you are making modeling choices for your own record.

• Concepts — the shortest complete mental model: entries, citations, the status field everything hangs off, and what a finding is.
• Identity, standing, and history — a name that persists while its standing changes; supersede vs. correct.
• Relations and chains — typed references, converses, and lines derived from succession edges.
• Vocabularies — closed value sets as constraints, classifications, and facets.
• Findings and truth maintenance — violations, warning classes, and acknowledgements.
• Sources and projections — what is authored, what is derived, and which command derives it.
• Record theory and self-governance — records whose subject includes their own rules.
• External knowledge and remotes — citing identities owned elsewhere.
• Designing a record — how to make modeling choices: what belongs in a record, which family fits which material, when two kinds of entry are two schemes, and what the schema can be made to refuse.
• Project memory — one application of Luria, not its definition: a software project’s decisions, principles, changelog and devlog, walked through the machine end to end (sources and views, the four families, statuses, constraints, references).

How-to guides

Accomplish a concrete task.

• Adopting Luria — bringing the record to an existing project, the CI wiring, and the published site.
• Importing an existing corpus — turning material that already exists as data into a record, and what that surfaces.
• Model and add relations
• Define and publish a chain
• Resolve, repair, and acknowledge findings
• Use merge-time identity allocation
• Use journals and fragment directories
• Reference remote knowledge
• Publish and export a record
• Run Luria in CI
• Promote a vocabulary to a scheme — when a value needs a parent, a status or relations, it is an entry; promote the vocabulary and keep its views.

Reference

Exact current behavior. Design rationale lives in the decisions and principles, and is cited rather than repeated.

• CLI reference — every command, flag by flag.
• Comment directives — acknowledging a lint finding where it happens, with the reason attached; also the fixture-code convention.
• Configuration — generated by luria index from the dataclasses that parse luria.yaml: every key, type, and default.
• The record — generated: the shape this project gave the machinery, what families exist, where entries are filed, and what to type to add one.

This project’s record

Luria’s own memory, kept with the tool it ships:

• Decisions — every architectural choice, with status, tags, and alternatives.
• Design principles — the standing values, one page, anchored for citation.
• Development log — the narrative: root causes, failed approaches, and the traps the next person would otherwise rediscover.
• Status reports — pending decisions and reference status: what awaits a human eye.

Contributing to the documentation

• Documenting Luria — how a page cites the record it depends on, and the house rules the lint enforces.