71 lines
2.2 KiB
Markdown
71 lines
2.2 KiB
Markdown
# 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.
|