Add a documentation library of canonical cross-repo guides

[leynos]

Summary

Estate repositories each carry copies of the shared guidance documents under docs/, and those copies have drifted apart as individual repositories fixed, extended, or trimmed them. This branch surveys the docs/ directory of every repository in the estate inventory (104 repositories), identifies the 41 documents that recur across repositories as general guidance, and merges each set of variants into one canonical edition under a new documentation-library/ directory.

For general guidance the base is the most complete and most recent edition; for a library's users' guide the base is the library's own repository. Every other variant was diffed against the base, additions of general benefit were folded in, and repository-specific detail (project names, local paths, Makefile targets, product data models) was generalized or removed. Names that recur but are always repository-specific (users-guide.md, developers-guide.md, roadmap.md, contents.md, repository-layout.md, execution plans, audits) were excluded.

The library introduces inline code spans, product names, placeholder tokens, and verbatim citation titles that the shared spelling dictionary flags, so the shared dictionary data/typos-oxendict-base.toml gains narrow ignore patterns that every consuming repository inherits on its next refresh; typos.toml is regenerated and unchanged.

Review walkthrough

• Start with documentation-library/README.md for the survey method, the base-selection rules, and the conventions the canonical editions follow.
• The catalogue lists every document grouped by domain with its estate copy and variant counts; the library users' guides table names each guide's upstream repository.
• The heaviest merges are documentation-style-guide.md (32 variants across 85 copies), scripting-standards.md (29 variants), rust-doctest-dry-guide.md (26 variants), and rust-testing-with-rstest-fixtures.md (24 variants).
• data-model-driven-card-architecture.md required the deepest generalization: every source copy embedded a product data model, which is replaced with a neutral catalogue example.
• v2a-front-end-stack.md is the estate's shared front-end model, reconciled from three copies; the axinite-mockup copy is an older SolidJS and Kobalte edition whose framework choices are excluded, and the sections overlapping sibling documents now link to them.
• documentation-style-guide.md gains a migration-guide section codifying the estate's one-guide-per-release format, and four bullets at line 138 specifying the empathy, accessibility, comprehensiveness, and tested-correctness qualities a user's guide needs.
• tests/test_typos_rollout.py covers the narrowed spelling exceptions in three layers: presence, precision, and an anti-regression test that strips every shared pattern from an inline code span and asserts the neighbouring misspellings survive. tests/test_typos_spelling_gate.py adds a behavioural check that runs the pinned typos binary over fixtures pairing each exempt token with a real misspelling.
• documentation-library/testing-async-falcon-endpoints.md injects the service into the Falcon resource instead of reaching for a module-level singleton, so the test passes a narrow fake rather than patching a dotted import path.
• docs/users-guide.md gains a section pointing readers to the library and describing how to refresh a repository copy.
• data/typos-oxendict-base.toml adds the ignore patterns to the shared dictionary so consumers do not repeat them locally. Each matches an exact exceptional token rather than the inline-code span around it, so unrelated misspellings in the same identifier are still reported; typos.toml is the regenerated output and carries no hand edits.

Validation

Rebase base: origin/main at 1eb47c0.

• make check-fmt: pass (no formatter configured)
• make markdownlint: pass, 159 files, 0 errors
• make lint: pass, 32 skill manifests validated
• make typecheck: pass (syntax check)
• make test: pass, 704 passed, 3 snapshots
• make spelling: pass
• make nixie: pass, all Mermaid diagrams validated

Notes

• Two documents override the largest-variant default on evidence: the rstest fixtures guide uses the axinite edition (pins rstest = "0.26.1", repaired attribute placeholders) and the Fluent guide uses the theoremc edition (repairs a truncated derive and converts stray citation digits to footnotes).
• Integration corrected regressions that a byte-for-byte adoption would have imported: the Falcon testing guide compares response.status_code with HTTPStatus values rather than Falcon's status strings, and the OpenTofu coding standards keep first-use acronym expansions as the style guide requires.
• Library users' guides are taken from each library's own docs/users-guide.md (or usage-guide.md for cmd-mox); vendored copies proved to be older snapshots, so few additions were imported from them.
• Migration guides for estate libraries (for example the rstest-bdd and ortho-config version migration guides) are versioned, upstream-owned documents and were not included.
• Two genuine typos found in source copies (exitsts, and an unbalanced EXPLAIN ANALYZE reference) are fixed in the canonical editions.
• The v2a document's third copy lives in axinite-mockup, which the estate inventory does not list. The README records that a copy held only by an off-inventory repository can escape the survey.
• The daisyUI guide's source copies used first- and second-person voice; the canonical edition is rewritten in the third person as the documentation style guide requires.

Follow-up issues

The library's examples are not yet executed by any test. Nine issues track
adding behavioural tests, batched by language and domain, covering all 1,127
fenced examples across the 42 documents:

• Test every example in the Rust testing and verification guides (150 examples) #141 Rust testing and verification guides (150 examples)
• Test every example in the Rust library and runtime guides (139 examples) #142 Rust library and runtime guides (139 examples)
• Test every example in the Python testing guides (83 examples) #143 Python testing guides (83 examples)
• Test every example in the Python application, scripting and CLI guides (136 examples) #144 Python application, scripting and CLI guides (136 examples)
• Test every example in the TypeScript React architecture guides (161 examples) #145 TypeScript React architecture guides (161 examples)
• Test every example in the Tailwind and daisyUI styling guides (321 examples) #146 Tailwind and daisyUI styling guides (321 examples)
• Test every example in the OpenTofu and HCL infrastructure guides (41 examples) #147 OpenTofu and HCL infrastructure guides (41 examples)
• Test every example in the Copier templating guides (81 examples) #148 Copier templating guides (81 examples)
• Test every example in the cross-language engineering practice guides (15 examples) #149 Cross-language engineering practice guides (15 examples)

References

• Lody session: https://lody.ai/leynos/sessions/2f27a6b3-b1ba-4fb4-98fb-5ac1c8aaa8a7

🤖 Generated with Claude Code