136 lines
5.6 KiB
Markdown
136 lines
5.6 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 returns only active, safely projected topics. Admin
|
|
documentation may show all layers plus route, permission, module, and capability
|
|
diagnostics, but it requires the separate administrative documentation
|
|
authority.
|
|
|
|
The managed `docs_reader` role grants `docs:documentation:read` automatically
|
|
to every authenticated tenant membership while Docs is installed. This only
|
|
opens the user projection: each contributed workflow still needs its own
|
|
module, capability, permission, and runtime-policy conditions so baseline Help
|
|
Center access does not imply authority to perform every documented task.
|
|
|
|
This permission binding is a strict source contract. Every user workflow topic
|
|
must declare at least one `DocumentationCondition`, and every alternative in
|
|
its `conditions` tuple must include `required_scopes` or `any_scopes`. Module,
|
|
capability, or configuration conditions alone are not sufficient because topic
|
|
conditions are alternatives: one unscoped alternative would bypass all scoped
|
|
ones. Manifest validation blocks a release containing such a topic, and Docs
|
|
omits a non-compliant runtime-provider topic from the user projection.
|
|
|
|
## 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 as technical provenance
|
|
|
|
Configuration keys are descriptive metadata; they are not evaluated as
|
|
conditions. Configuration-dependent guidance belongs in an owning module's
|
|
runtime provider.
|
|
|
|
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"]
|
|
}
|
|
}
|
|
```
|
|
|
|
Raw blockers and scope names are part of the administrator projection. The user
|
|
projection omits inactive topics instead of returning their protected body,
|
|
metadata, and blocker identifiers. A module can contribute a separate, safe
|
|
plain-language escalation topic when users need to know that an administrator
|
|
must enable something.
|
|
|
|
## Task metadata
|
|
|
|
Workflow topics can supply `outcome`, `prerequisites`, `steps`, `result`, and
|
|
`verification`. Runtime providers can additionally supply:
|
|
|
|
- `current_configuration`: bounded plain-language facts for this actor and
|
|
installation;
|
|
- `limitations`: bounded, actionable caveats; and
|
|
- `constraints`: records with `id`, `label`, `description`, and optional
|
|
user-safe `values` needed to complete the task.
|
|
|
|
The Docs API validates and whitelists those fields for the user projection.
|
|
Modules remain responsible for authorization and for preserving policy
|
|
semantics. Constraints must never contain secrets, internal policy-source ids,
|
|
unrelated topology, or raw policy payloads.
|
|
|
|
## 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. User docs contain
|
|
only active topics, runtime and HTTPS public links, and a bounded metadata
|
|
whitelist. 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.
|