chore: sync GovOPlaN module split state

docs/DOCUMENTATION_LAYER_CONCEPT.md

@@ -6,6 +6,11 @@ GovOPlaN Docs provides a documentation layer that starts with the configured sys
 
 Only after that should the documentation provide evidence about what else might be possible: installed-but-disabled features, optional modules, extension points, product capabilities, or examples from other configurations.
 
+The editorial experience is defined in
+`docs/DOCUMENTATION_EXPERIENCE_CONCEPT.md`: workflow guidance, structure
+reference, and shared design-pattern explanations are separate reading modes
+over this configured-system model.
+
 ## Problem
 
 Traditional product documentation describes the full system. That creates avoidable complexity in configurable public-sector platforms because most users only need a slice of the system:
@@ -71,6 +76,7 @@ Evidence should be discoverable, but it should not be the primary reading path f
 The docs module should consume documentation sources through explicit contracts:
 
 - module manifest documentation metadata
+- module manifest runtime documentation providers
 - route metadata and page-level help references
 - capability metadata
 - configuration-package descriptions
@@ -80,6 +86,113 @@ The docs module should consume documentation sources through explicit contracts:
 
 Feature modules should contribute documentation metadata without the docs module importing their internals.
 
+### Module-Owned Documentation
+
+Documentation is distributed over the modules that own the behavior. A module can
+register durable topics directly in its `ModuleManifest.documentation` tuple.
+Use this for stable explanations such as the module purpose, common workflows,
+policy hierarchy, route meaning, and links to public docs or repository docs.
+
+When the text depends on active configuration, a module registers a provider in
+`ModuleManifest.documentation_providers`. The provider receives a
+`DocumentationContext` with the active registry, principal, settings, and a
+database session when available. The module can then describe the effective
+state without the docs module importing feature internals.
+
+For example, `govoplan-mail` contributes static documentation for reusable mail
+profiles and a runtime tenant policy topic. If the effective tenant mail policy
+limits sending to approved profile ids and disables user, group, and
+campaign-local profiles, the runtime docs state that users can choose approved
+profiles but cannot bring arbitrary SMTP or IMAP servers at lower scopes. If the
+policy allows lower scopes, the same topic explains which scopes may define
+profiles and whether credential inheritance is locked.
+
+Runtime providers must avoid leaking secrets. They should summarize posture,
+counts, source provenance, and enabling conditions rather than exposing
+credentials, hostnames, profile ids, or raw policy payloads unless the route is
+explicitly intended for that level of detail.
+
+### Conditions And Unlocks
+
+Documentation topics can declare conditions:
+
+- required modules
+- one-of module alternatives
+- modules that must be absent
+- required capabilities
+- required scopes or one-of scope alternatives
+- configuration keys that influence the topic
+
+The docs API classifies satisfied topics into their requested layer. Unsatisfied
+topics remain visible as available or evidence documentation when safe, with a
+reason such as a missing module, capability, or scope.
+
+Topics can also declare related modules and unlock notes. This lets a module
+state that additional behavior becomes available when another module is
+installed. Runtime docs should link to the configured local behavior first and
+then to public module documentation for broader examples.
+
+### Admin And User Documentation
+
+GovOPlaN has two documentation presentations over the same source model.
+
+Admin documentation is allowed to be technical. It can expose installed module
+ids, route contributions, API paths, permissions, capability names, server
+configuration keys, policy source chains, migration notes, and operator
+evidence. This is the right place to explain exactly why a setting is available,
+which API applies it, and which configuration key or policy source controls it.
+
+User documentation should be written for people without technical background. It
+should explain what the user can do, what they cannot do, and who to ask when a
+needed option is missing. It should avoid route names, API calls, raw policy
+payloads, internal module ids, and server configuration unless that information
+is genuinely meaningful to the user.
+
+Each `DocumentationTopic` declares `documentation_types`, currently `admin`,
+`user`, or both. Runtime providers receive the requested type in
+`DocumentationContext.documentation_type`, so they can generate different text
+from the same effective configuration. For example, mail admin docs can mention
+mail profile policy sources and API endpoints, while user docs can simply say
+whether the user may choose an approved mail profile or add a local mail server.
+
+The first presentation rule is:
+
+- admin docs show technical context and evidence tables
+- user docs show plain-language topics, examples, limits, and escalation paths
+- both presentations are filtered by installed modules, active configuration,
+  permissions, and safe disclosure rules
+
+### Localization
+
+Localization should be prepared before substantial documentation text is added.
+Every durable topic should have a stable `i18n_key`. The English source text can
+remain in the manifest or provider, but topics may include locale-specific
+`translations` for `title`, `summary`, and `body`.
+
+The docs API accepts a requested locale and falls back in this order:
+
+- exact locale, such as `de-AT`
+- base language, such as `de`
+- English translation if present
+- source text
+
+This keeps the first implementation simple while avoiding a later rewrite of
+every module documentation contribution. A later dedicated translation catalog
+can still use the same `i18n_key` values.
+
+### Public Documentation For Missing Modules
+
+The configured-system docs should not explain every uninstalled module in full.
+General documentation for the product and modules not installed in the current
+system belongs on `https://govplan.add-ideas.de/`, served by `govoplan-web`.
+
+Runtime documentation should link to the public page when:
+
+- an optional module is not installed
+- a feature is unlocked by adding another module
+- an example uses modules that are not active locally
+- a user needs conceptual background beyond the configured system
+
 ## Rendering Model
 
 The runtime docs UI should be context-aware:
@@ -111,6 +224,7 @@ The first implementation should define:
 - a configured/available/evidence classifier
 - a minimal API for current-context documentation
 - a WebUI route contribution for the documentation browser
+- a provider contract for configuration-derived runtime topics
 
 The first UI can be simple:
 
@@ -119,5 +233,6 @@ The first UI can be simple:
 - active policies
 - available-but-disabled evidence
 - source links to wiki or repository docs
+- module documentation topics with links and unlock notes
 
 Once the source model is stable, feature modules can add richer documentation contributions through their manifests and capabilities.