Native documentation platform

docs-sites.toml is the machine-readable contract for the six repositories that make up the native HSSM documentation platform. It records what is live, what is being adopted, the shared toolchain, the build interface, and the workflow and brand distribution destinations. The manifest owns the common top-level navigation; page groupings and content beneath it remain repository-owned.

Sites and adoption state

Repository	Profile	Current state	Documentation root
HSSM	library	live	docs/
ssm-simulators	library	live	docs/
LANfactory	library	live	docs/
LAN_pipeline_minimal	operational	live	docs/
HSSMCortex	operational	live	docs/
HSSMSpine	orchestration	live	_docs/

state describes adoption of this documentation contract, not package maturity. This table reflects the 2026-08-24 closeout; docs-sites.toml is the authoritative current source. Manifest consumers operate on live sites by default. A planned site becomes live only after its native docs build, caller workflow, and published URL are working; tools may target a planned site explicitly during that migration.

Profiles make the quality rubric proportional to the site:

• library sites teach and reference a public Python API.
• operational sites teach a runnable system, its configuration, and its operating procedures; an exhaustive Python API is not inherently required.
• orchestration sites explain cross-repository policy and workflows; their reference surface is contracts, manifests, and contributor procedures.

Canonical navigation

Every native site exposes these top-level sections in this exact order and with these exact labels: Home, Learn, How-to guides, Explanations, and Reference. Profiles change what belongs beneath a section, not its label or position. Additional material such as contributing guidance is nested under the appropriate canonical section instead of creating another top-level section.

Every site uses Material for MkDocs and enables the built-in search plugin. Repositories may add profile-specific plugins, but they may not remove search. MkDocs validation sets omitted_files, absolute_links, unrecognized_links, and anchors to warn; strict builds promote any of those warnings to failures.

Pinned toolchain

Every native site uses Python 3.12 and uv 0.12.2. The shared documentation dependency pins are MkDocs 1.6.1, Material for MkDocs 9.7.7, mkdocs-redirects 1.2.2, mkdocs-autorefs 1.4.4, mkdocs-jupyter 0.26.3, mkdocstrings 1.0.6, and the mkdocstrings Python handler 2.0.5. The manifest is the source of truth for these values. Repositories with a tracked docs lock run their build with --locked; HSSM and LANfactory instead declare every direct docs dependency at the exact manifest version without tracking a lock; and HSSMSpine records the exact set in requirements-docs.txt. These are three supported reproducibility modes, not a requirement that every site commit a lockfile.

Repository build interface

Each adopted repository exposes the same two-command maintainer interface:

./scripts/docs.sh build
./scripts/docs.sh serve

build installs or selects the repository's pinned docs environment, performs a strict build, and writes the rendered site to site/. serve uses the same environment and starts the local MkDocs preview. Repositories own the implementation because their generated reference, notebook, and system dependency needs differ. The shared workflow deliberately accepts no install or command input and always invokes build.

Linux system dependencies are selected with one closed system_profile: none, blas-lapack, or gsl. The reusable workflow rejects every other value before installation.

Build profiles

The shared interface has three repository-owned operating models:

• A library build installs the project together with its exact documentation dependencies so generated API reference imports the package it documents. HSSM also runs its committed-output weight guard before the strict build.
• An operational build creates a docs-only environment and uses --no-install-project. It must not pull CUDA, Cognee, or other runtime stacks, and it must not need credentials, external services, or a running cluster to build or preview the site.
• An orchestration build uses HSSMSpine's isolated, exact requirements-docs.txt; it does not install ecosystem packages merely to render coordination guidance.

Notebook execution remains package-owned because each repository knows which scientific dependencies, fixtures, and cadence make its examples trustworthy. The reusable workflow builds the committed documentation through docs.sh; it does not define a cross-repository notebook-execution command.

Shared build and deployment

HSSMSpine's .github/workflows/reusable-docs.yml is the canonical source. As long as the Spine remains private, every external repository vendors that file byte-for-byte at the same path and its thin caller invokes the repository-local copy. This gives public repositories no runtime dependency on private-repository visibility or Actions access while retaining one reviewed implementation to synchronize.

The vendored workflow builds through the fixed script above, uploads a GitHub Pages artifact only for a trusted main push or main manual dispatch, and deploys that artifact with the least permissions needed. A scheduled linkcheck never uploads or deploys. Deployments are serialized per caller repository and an in-progress deployment is never cancelled. Rendered external-link checking runs when the caller was started by a weekly schedule or manual dispatch.

Triggers, path filters, caller-run concurrency policy, and the system_profile choice remain caller-owned. The reusable workflow owns only safe deployment serialization, declares only workflow_call, does not reach into callers with secrets, and does not accept arbitrary shell commands.

A caller grants the deployment job only the permissions it can use and calls the checked repository-local copy:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  docs:
    uses: ./.github/workflows/reusable-docs.yml
    with:
      system-profile: none

The caller also owns a root .lychee.toml. On weekly schedules and manual dispatches, the reusable workflow applies it to the rendered site/**/*.html. Before checking, it mounts site/ below the caller's repository name so root-relative GitHub project-site URLs resolve against the current artifact. Link checking is not part of the local docs.sh interface.

Workflow changes start in the Spine and are then copied into selected external repositories with sync_docs_workflow.py; the local copy and caller change are reviewed in that repository like any other CI change. An eventual migration to lnccbrown/HSSMSpine/.github/workflows/reusable-docs.yml@<full-commit-sha> after the Spine becomes public is explicitly deferred to a separate rollout. Until then, callers must not mix external Spine references with the local-copy model.

Shared brand and site-owned legal text

The four files listed under [brand] are vendored byte-for-byte beneath each site's documentation root. main.html reads extra.release_announcement; released packages enable the release link while non-release sites leave it disabled. The shared ecosystem link strip lives in its own partial. Each MkDocs config mirrors brand.exclude_docs so theme Jinja sources are consumed by Material but are not copied into rendered site/ and mistaken for reader-facing HTML by the link checker.

Each repository copies its legal_notice from the corresponding manifest entry into MkDocs copyright. Legal text is deliberately not used as an ecosystem navigation container: common links belong to the shared partial, while licensing and ownership remain accurate for each repository.

Run the manifest consumers from the spine:

python scripts/sync_docs_brand.py --check
python scripts/sync_docs_workflow.py --check
python scripts/check_docs_contract.py
actionlint .github/workflows/*.yml

The two sync commands check live sites by default. Use --repo <name> to work on one planned site during adoption, or --all to check every applicable site; workflow vendoring excludes HSSMSpine itself because it is the canonical source. The final command is the local equivalent of the pinned actionlint 1.7.12 check in CI.