It answers "what does this installation provide for me?" before it answers "what could the full product do?". The goal is to reduce documentation complexity by starting from installed modules, enabled configuration, tenant policy, role, route availability, and visible capabilities.

Ownership

This repository owns:

backend module manifest docs
configured-system documentation indexing
documentation source and contribution contracts
role-aware and tenant-aware documentation filtering
evidence pages for disabled, unavailable, or optional capabilities
documentation route contributions and future WebUI package @govoplan/docs-webui
documentation sync/import tooling that belongs to the runtime docs layer rather than the repository maintenance scripts

Core owns module discovery, configuration package loading, route registry, RBAC evaluation, capability registry, and shared WebUI shell behavior.

While Docs is installed, its managed docs_reader tenant role is an automatic authenticated-member baseline. Access derives its narrow read grant from the active Docs manifest without per-user assignments or authorization-time writes, so ordinary users can open their configured handbook without an administrator assigning documentation access one account at a time. Administrative documentation remains separately protected by docs:documentation:admin or the applicable administration scope.

Documentation model

The docs module should render documentation in three layers:

Configured: installed and enabled behavior that applies to the current tenant, organization, role, or route.
Available: installed but disabled or hidden behavior that can be enabled by configuration or permission.
Evidence: referenced capabilities, modules, examples, or product documentation that explain what else may be possible without making it the primary reading path.

Module integration

Backend entry point:

[project.entry-points."govoplan.modules"]
docs = "govoplan_docs.backend.manifest:get_manifest"

Frontend package:

@govoplan/docs-webui

Platform module manifests, configuration packages, release catalogs, and governance rules are documented in govoplan-core/docs/.

Every module manifest must contribute a static documentation baseline for both the user and admin projections through ModuleManifest.documentation. Runtime providers may add actor- and configuration-specific detail, but they do not replace that baseline. A behavior change is complete only when the owning module updates the affected workflows, settings, permissions, limitations, and operational consequences. Validate workspace coverage with:

cd /mnt/DATA/git/govoplan
./tools/checks/check-manifest-shapes.py

Feature content remains in the owning module. Docs indexes and renders the contributions without importing feature implementations.

Public documentation export

The public website is generated from the same static DocumentationTopic contributions that power the in-product documentation. Export every installed module, or every module checkout in a workspace, with:

govoplan-docs-export-public \
  --workspace-root /mnt/DATA/git \
  --output public/docs/v1/catalog.json \
  --coverage-output docs/DOCUMENTATION_COVERAGE.md

Use --check in publication CI to reject a stale checked-in catalog. Dynamic documentation_providers remain instance-only because their output can depend on permissions, policy, configuration, and live provider state; the export records which modules have such additional documentation.

Pressing F1 resolves the focused field or action first, then its containing dialog or section, current page, and owning module. The shell sends the focused context together with fallback_context and module; Docs selects the first visible exact, page-level, or module-level topic after applying audience and permission filtering. Modules announce exact route and control identities in static topic metadata.help_contexts.

Capabilities can provide generic documentation without exposing their runtime provider implementation:

ModuleManifest(
    capability_factories={"example.lookup": build_lookup},
    capability_documentation={
        "example.lookup": CapabilityDocumentation(
            label="Example lookup",
            summary="Resolves records through the versioned lookup contract.",
            contract_version="2",
            stability="stable",
            audience=("module_admin",),
        ),
    },
)

Docs also projects the configured module release catalog and configuration package catalog through the public Core catalog contracts. Catalog trust, freshness, provenance, descriptions, and package requirements remain visible as typed evidence; provider objects, credentials, and secret configuration are never imported into the Docs WebUI.

Module-owned external-provider runtime state is also projected through the Core contract. Administrative documentation may show sanitized binding-level state; ordinary-user documentation receives only aggregate configured, active, authority, health, freshness, conflict, recovery, and observation fields. URLs, credential references, provider error text, and binding identifiers are excluded from the user projection.

Concept documents

docs/DOCUMENTATION_LAYER_CONCEPT.md defines the configured, available, and evidence documentation model.
docs/INSTANCE_AWARE_DOCUMENTATION.md defines the runtime context and condition model.
docs/DOCUMENTATION_EXPERIENCE_CONCEPT.md defines the workflow, structure/reference, and design-pattern documentation experience.
Core's DocumentationHelpLink is the stable route/field/blocker entry point into a topic or help context, with hosted fallback when this module is not active.