Příručka — Prismatic Majordomus

Příručka vysvětluje Majordomus čtenáři v jeho jazyce: co to je, jak do něj relace vstupuje, co změnu odmítá, kde žijí paměť a pravidla, jak se stroje koordinují a jaká jsou vlastní čísla repozitáře. Je to jedna interaktivní stránka na jazyk a sestavuje se z tohoto repozitáře.

První vydání je české, handbook/cs/. Druhý jazyk je druhý adresář.

Sestavit

python3 handbook/build.py

Stránka přistane v target/handbook/cs/prirucka-majordomusu.html. Otevřete ji v prohlížeči; server nepotřebuje. Sestavení trvá asi sedmnáct sekund a čte jen tento strom.

Co se píše a co se odvozuje

Část	Odkud pochází
próza kapitoly	psáno ručně, v jazyce vydání, pod `handbook/<language>/`
čítárna: každý dokument, rozhodnutí, pravidlo, tvrzení a případ užití, vykreslené na místě	soubory, které git sleduje, čtené `handbook/corpus.py`
odkazy mezi dokumenty a co odkazuje zpět	vypočteno z těchto souborů
mapa druhů, toky a to, co obklopuje jeden objekt	`docs/generated/graph.json`, zhuštěno `handbook/graph.py`
průzkumník, kontroly, repozitář v číslech	registr, `.ai/repo/ci/gates.yaml` a historie, které čte `handbook/derive_data.py`
„na čem tato kapitola spočívá“, pod každou kapitolou	deklarované kotvy kapitoly a to, na co odkazuje její text, rozřešené vůči grafu
každé číslo v popisku	zástupný symbol, který vyplní build

Nic ve druhém sloupci se nepíše do kapitoly. Postavená stránka se necommituje.

Ani edice nevolí žádnou barvu. Její stylesheet pojmenovává role, které deklaruje share/design/tokens.yaml, build vkládá projekci, která těmto rolím dává hodnoty v obou tématech, a grafy čtou kategorické řady ze stránky za běhu; design-check drží edici tohoto pravidla jako každý jiný povrch.

Co to drží v souladu s repozitářem

Každá kapitola deklaruje, na čem stojí, v handbook/<language>/chapter_sources.py: dokumenty, funkce produktu, moduly schopností, příkazy, rozhodnutí, pravidla a tvrzení, jako reference do grafu repozitáře. Sestavení odmítne, s kódem 10:

odkaz, který graf už nenese, protože věc byla odstraněna nebo přejmenována;
kapitola, která necituje nic z repozitáře;
popisek, který žádá údaj, jejž odvozená data nemají;
odvozená data, jejichž klíče se změnily pod stránkou, která je čte (handbook/shape/).

Kontrola handbook-check spouští tento build při každé změně, takže změna, která přejmenuje dokument, o němž kapitola je, selže tam, kde vzniká. Oprava patří do stejné změny: upravit kapitolu, nebo ponechat jméno. Pravidlo je project.the-handbook-is-built-from-the-tree a rozhodnutí je ADR 0149.

Edice a jazykové pravidlo

Pracovní artefakty tohoto repozitáře jsou anglicky. Vydání je obsah adresovaný čtenáři, jako přeložená stránka webu, a project.english-only ho připouští za tří podmínek: je handbook/<language>/; jeho edition.toml deklaruje tento jazyk; a scripts/ci/english-only-allow.txt ho deklaruje jako edition <directory> <language> <why>. Generátor vedle vydání není uvnitř žádného a zůstává anglicky.

Chcete-li přidat edici, zkopírujte stávající, přeložte její texty, změňte lang v jejím edition.toml, přejmenujte adresář na daný jazyk a edici deklarujte. Odvozeniny jsou sdílené.

Testy

test/cases/2984_a_handbook_edition_is_built_from_the_tree.sh sestaví edici a každé zamítnutí dokáže mutací. Vlastní prohlížečové testy edice jsou pod handbook/cs/tests/; vyžadují Playwright a prohlížeč, čtou sestavenou stránku a spouštějí se ručně:

node handbook/cs/tests/pw-evidence.js

Co tu ještě není

Publikovaný web handbook nenabízí a nemá přepínač jazyka. Obojí by byly projekce toho, co tento adresář sestavuje. Handbook je také publikován, ručně, jako artefakt mimo tento repozitář; ta kopie je sestavena stejným příkazem.

PERSONAL_MODE.md, kapitola příručky, která existuje i jako anglický dokument.
CI.md pro to, jak se vybírá kontrola.
DOCTRINE.md pro to, co je pravidlo a co ho dokazuje.