.nornir doc templates — which class, when
Rule: every substantive .nornir/*.md starts from one of these templates. These files are the copy-from source for ALL nordisk repos' .nornir/, not just dwarves — copy one, rename it (<thing>-design.md, etc.), fill the <ANGLE BRACKET> placeholders.
The doc classes actually in use
| Class | Header line | Use it for | Template |
design |
<!-- nornir:class: design --> |
What a thing IS — parts, shape, why. States facts, not how-to. | _TEMPLATE-design.md |
guide |
<!-- nornir:class: guide --> |
How to drive it — the f0 end-to-end workflow + surfaces. |
_TEMPLATE-guide.md |
idiot |
<!-- nornir:class: idiot --> |
Zero-knowledge walkthrough — cold shell → one useful result, every step. (file name: <thing>-for-idiots.md) |
_TEMPLATE-for-idiots.md |
reasoning |
<!-- nornir:class: reasoning --> |
Why a decision — the problem a naive fix can't solve, what we compute instead. | _TEMPLATE-reasoning.md |
history |
<!-- nornir:class: history --> |
Dated session/landing logs — records, not curated design. (no template — append-only prose) | |
readme |
GENERATED banner (see template) | The repo-root README source (.nornir/README.md → generated README.md). |
_TEMPLATE-README.md |
Conventions
- The class rides in an HTML comment
<!-- nornir:class: X -->at the top;guide/idiotdocs also often restate it as a> **Class:** \X`` blockquote with the audience. - A
designdoc names its function axis (f0whole,f1..fnparts) and stays strict — what-it-is only; it links its siblingguideandfor-idiots. - The trio per subject:
<thing>-design.md(what) ·<thing>-guide.md(how) ·<thing>-for-idiots.md(cold-start). Deeper area notes get their owndesign/reasoning. - README is generated — edit
.nornir/README.md, never the root copy; keep it lean and link.nornir/{README-full,design,guide,for-idiots}.md. - ⛔ No AI attribution anywhere. Plain numbers (no thousands separators). Never document Njord.