# Instance-Aware Documentation

The docs module renders documentation for the current GovOPlaN instance instead
of showing a static product manual.

## Inputs

The documentation context is built from:

- enabled module manifests
- frontend routes and navigation metadata
- module permissions and the current principal's granted scopes
- documentation topics contributed by manifests
- runtime documentation providers contributed by modules
- optional dependencies and declared capabilities

## Layers

| Layer | Meaning |
| --- | --- |
| `always` | Generic platform concepts that are useful in every deployment. |
| `configured` | Documentation for installed modules/features visible in this instance. |
| `available` | Installed features hidden by missing permissions or unmet conditions. |
| `evidence` | Hints for unavailable optional modules, missing capabilities, or external evidence sources. |

Normal user documentation should emphasize `always` and `configured` content.
Admin documentation may show all layers plus route, permission, module, and
capability diagnostics.

## Conditions

Documentation topics can declare:

- required modules
- any-of module sets
- modules that must be absent
- required capabilities
- required scopes
- any-of scope sets
- related configuration keys

The API returns both a human-readable `reason` and structured `blockers`:

```json
{
  "reason": "missing modules: mail; missing scopes: mail:profile:read",
  "blockers": {
    "modules": ["mail"],
    "capabilities": [],
    "scopes": ["mail:profile:read"]
  }
}
```

The WebUI must display the reason and, when present, the blocker lists. This
prevents dead-end instructions: users see whether a feature is unavailable
because a module is missing, a capability is not registered, or their current
permissions do not expose it.

## Module Guidance

Module docs should not hard-code assumptions about sibling modules. A module
should contribute conditional topics such as:

- "Send selected file by mail" requiring `files` and `mail`
- "Campaign attachments from storage" requiring `campaigns` and `files`
- "Mailbox diagnostics" requiring `mail.devMailbox`

The docs module remains the renderer. Feature modules own their subject matter
and describe unlocks through manifest metadata.

## Ownership And Disclosure Rules

The ownership rule is the same for all documentation layers: the module or
repository that owns the behavior owns the durable explanation. The docs module
owns classification, filtering, search, route contribution, and rendering. It
does not own feature-module business rules, policy semantics, or current issue
state.

Use these sources for these purposes:

| Source | Purpose |
| --- | --- |
| Runtime docs providers | Effective, actor-aware explanation of the configured system. |
| Repository docs | Durable architecture, module contracts, runbooks, and governance decisions. |
| Synced Gitea wiki pages | Published copy of durable documentation for browsing and linking. |
| Gitea issues | Active backlog state, acceptance criteria, blockers, and closure evidence. |

Runtime docs may link to issues when an unavailable feature is planned or a
known limitation is relevant, but the UI must label that link as active work.
It must not treat open issues as shipped behavior.

Safe disclosure is evaluated before a topic is returned. Missing permission,
missing module, and missing capability explanations should be useful but
minimal. User docs explain the blocker and who can resolve it. Admin docs can
include route ids, scopes, capability names, configuration keys, and policy
provenance only when the actor has permission to inspect those details. Secrets,
tokens, private keys, credentials, raw policy payloads, and unrelated personal
data are never returned as documentation content.