govoplan-docs/README.md

# govoplan-docs

<!-- govoplan-repository-type:start -->
**Repository type:** module (platform).
<!-- govoplan-repository-type:end -->

GovOPlaN Docs provides the documentation layer for configured GovOPlaN systems.

It also stores tenant-owned semantic documentation for stable configured subjects. See [Tenant semantic documentation](docs/SEMANTIC_DOCUMENTATION.md) for lifecycle, authorization, publication policy, export, recovery, and provider obligations.

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:

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

Frontend package:

```text
@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:

```sh
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:

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

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.

Static topics localize title, summary, and body through `translations`.
Rendered metadata such as steps, fields, limitations, consequences, and
verification uses Core's opt-in `structured_translation_version="1"` plus
`structured_translations` contract. The registry validates exact shape before
Docs overlays the requested locale. The public catalog reports structured
adoption separately. A reviewed coverage-baseline file sets monotonic minima
and maxima so publication CI also rejects localization or coverage regressions
after generated output is refreshed.

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:

```python
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.