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.

## Finding and grouping help

The Help Center searches authorized titles, summaries, body text, area names,
and public topic tags. The shared multi-selection list filter uses OR between
selected tags; Select all removes the restriction, Clear all yields no results.
Search results deduplicate semantic topic IDs. Selecting a result clears the
filters and opens its topic.

Topics by area groups each topic under its source module and authorized related
modules. Contributors may add public keyword strings in `metadata.tags` and
additional stable module IDs in `metadata.areas`. The Docs-owned
user projection accepts up to 32 tags of at most 80 characters and 32 explicit
area IDs of at most 255 characters. The
`area_module_ids` response is authoritative: user responses omit related areas
without an actor-visible route, while preserving the topic's source area.
Existing role, tenant, locale, version, and configured-state topic authorization
is unchanged. Tags are public descriptive content, not a place for private
configuration, credentials, or hidden capability names.

Topic IDs identify content; parent-qualified navigation occurrence IDs identify
one position in the tree. `topic` URLs remain supported; a tree click also sets
`occurrence`, so reload highlights and reveals only the selected position.
Expanding a repeated topic never expands its other occurrences.

### Deutsch

Die Suche berücksichtigt berechtigte Titel, Zusammenfassungen, Thementexte,
Bereichsnamen und öffentliche Schlagwörter. Mehrere ausgewählte Schlagwörter
werden mit ODER verknüpft. Alle auswählen entfernt die Einschränkung; Auswahl
aufheben ergibt keine Treffer. Suchergebnisse enthalten jedes Thema einmal.
Die Auswahl eines Treffers setzt die Filter zurück und öffnet das Thema.

Themen nach Bereich ordnet Beiträge dem Quellmodul und berechtigten verwandten
Modulen zu. Modulautoren können öffentliche Stichwörter in `metadata.tags` und
weitere stabile Modulkennungen in `metadata.areas` angeben. Für Benutzer werden
verwandte Bereiche ohne sichtbare Route nicht ausgegeben. Suche und Filter
erweitern niemals die Dokumentationsberechtigung. Zugangsdaten und private
Konfiguration gehören nicht in Schlagwörter.

Ein Thema kann in mehreren Zweigen erscheinen. Eine positionsbezogene Kennung
im Link speichert, welches Vorkommen ausgewählt wurde. Nur dieses Vorkommen
wird hervorgehoben; Aufklappen öffnet nicht zugleich die anderen Fundstellen.

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