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

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:

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