docs¶
It used to be a single file (ANOTACOES.md, 1949 lines). It became six, because a god
file hides things: with 98 closed entries mixed in with 15 open ones, finding what to do
today meant scrolling through six months of history.
The split is by function, not by topic. What you read every day (the rules), what you act on (the open items) and what you look up (the history) have different rhythms.
| File | What it is | When you read it |
|---|---|---|
| rules.md | The repo's 18 rules | Before deciding anything |
| open-items.md | What is still open | When picking what to work on |
| history/ | What was done and why, a folder per year and a file per month | "What happened that day?" |
| notes/ | One page per module: why it is the way it is, and the traps | "Why is THIS module like this?" |
| ideas.md | Considered, not decided yet | When planning |
| arch-linux.md | A closed chapter + how to open the archive | Rarely |
| arch-parity-audit.md | main against nixos, area by area: what was ported, replaced, dropped and still missing |
Before retiring the Arch refs |
| guides/ | Step by step for what Nix cannot reach (BIOS, Secure Boot, router, Windows), plus the reusable TEST protocols | When reinstalling, working outside the repo, or validating a change |
This tree is also a site. https://dotfiles.v1cferr.dev/ renders exactly these files, with search and a nav grouped by subject. The files did not move to match that nav, and notes/repo/site.md says why.
Conventions¶
The rule numbering is API. The code cites "rule 11" and "rule 14" in more than seventy comments. Renumbering would break all of them silently: a new rule goes in at the end, a dead rule gets struck through instead of disappearing.
A good entry explains the WHY and the trap, not the what, because the code already says the what. The most valuable entries here are the ones recording something TRIED AND REJECTED, because they keep the next person (or you in six months) from repeating it.
A finished item migrates from open-items.md to history/<month>.md. One file only
grows, the other one shrinks.
History is append-only, notes are kept current. The diary keeps a stale entry, because a
diary that gets edited stops being evidence. A notes/ page that stops being true is a bug
(rule 16).