100 lines
3.7 KiB
Markdown
100 lines
3.7 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.
|
|
|
|
## 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.
|