govoplan-docs/docs/INSTANCE_AWARE_DOCUMENTATION.md

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:

{
  "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.