Documentation System

Famulus documentation is intentionally split between hand-written narrative and generated inventory/coverage surfaces. This file explains the automation behind that split.

What Is Hand-Written

Almost everything is. The generated set is the short one, so the rule runs the other way: a file is generated when it carries an AUTO-GENERATED marker or is named under What Is Generated. Everything else is written by hand.

• README.md
• docs/*.md — the top-level Famulus pages, except the generated skill index
• docs/officina/**.md — the framework documentation
• docs/quickstarts/*.md
• docs/domains/*.md
• docs/contributors/*.md
• explanatory reference docs under references/

Quickstarts carry user-facing setup and workflow guidance. Domain documents carry concise domain summaries around their generated inventories. The other hand-written files carry contributor explanations, examples, and design rationale.

Two of these entries carry generated blocks without being generated themselves — the domain documents and contributors/README.md embed coverage blocks between markers. Hand-written and generated is a property of the region, not only of the file.

What Is Generated

The generated Markdown surfaces are:

• docs/skills.md — the complete skill inventory
• embedded coverage blocks inside the domain and contributor docs

Those surfaces are derived from live skills/*/blueprint.yaml files plus the descriptions in each skill's SKILL.md.

Centralized Code Home

Documentation generation and documentation-validation support live in docs_tooling/.

That module owns:

• loading the live skill catalog
• taxonomy and coverage contracts
• rendering the skill index
• rendering coverage blocks for hand-written docs
• shared support used by validators

Top-level scripts should stay thin wrappers around docs_tooling/.

The bounded website assembler also lives on this side of the boundary:

• scripts/docs-site.py
• docs_tooling/site.py

MkDocs owns Markdown rendering, navigation, search, local serving, and static site output. The repository-owned assembler decides which sources are public and rewrites links to unpublished repository content.

Generated Blocks

Coverage blocks are embedded between markers such as:

<!-- BEGIN AUTO-GENERATED DOCS: personal-assistance -->
...
<!-- END AUTO-GENERATED DOCS: personal-assistance -->

Do not edit the contents inside those markers by hand. Edit the surrounding prose if you need a better explanation, and rerun the generator if the skill inventory changed.

Regenerating Doc Artifacts

From the repo root:

python3 scripts/generate-doc-artifacts.py

This regenerates:

• docs/skills.md
• embedded coverage blocks in the domain docs
• embedded coverage blocks in docs/contributors/README.md

Local Browsing

Install the documentation dependencies, then serve the same bounded site that is published through GitHub Pages:

python3 -m pip install -r requirements-docs.txt
./scripts/docs-site.py serve

The site includes:

• the repository README.md as the website homepage
• docs/README.md as the /documentation/ index
• every regular file under docs/, recursively, except the private subtrees
• non-Markdown assets under docs/, when present
• the generated interactive repository blueprint graph
• configured published graphs, currently the math-dependency example

docs/plans/ and docs/superpowers/ are the private documentation subtrees, named in _PRIVATE_SUBTREES in the assembler. They hold working notes and implementation plans, which live under docs/ so an assistant can read them and are not documentation. docs/superpowers/ is gitignored as well, but the assembler walks the working tree rather than the index, so the exclusion has to be stated here too or a local build would publish what the site does not. Links to files in either subtree, and to repository source code outside docs/, open the corresponding GitHub page.

To build without starting the local server:

./scripts/docs-site.py build

Both commands write only under the ignored _build/docs-site/ tree, apart from the existing generated-Markdown refresh performed by scripts/generate-doc-artifacts.py.

Validators

Documentation conformance is enforced by repo validators under validators/, not by prose-shape pytest tests.

The key validators are:

• validators/readme_user_contract.py
• validators/domain_docs_cover_blueprints.py
• validators/contributor_docs_contract.py
• validators/generated_skill_docs.py

Run them through:

python3 repo_checks.py --suite validators

Adding a New Doc Contract

When you add a new documentation contract:

1. Add or update the shared logic in docs_tooling/.
2. Add or update the hand-written doc that owns the prose.
3. Add marker blocks if the doc needs generated coverage content.
4. Add or update the validator module under validators/.
5. Regenerate docs and run validators.

This keeps the rules in one place and avoids scattering doc-generation logic across unrelated scripts.

For the local pre-commit order, GitHub Actions behavior, and Python test-suite boundaries, see docs/testing.md.