Sync wiki from project files

Codex-Project-Index.md

@@ -5,5 +5,6 @@
 This page is generated from repository and product-directory project files.
 
 - [Repo-README](Repo-README) - `/mnt/DATA/git/govoplan-docs/README.md`
-- [Repo-docs-DOCS-BACKLOG](Repo-docs-DOCS-BACKLOG) - `/mnt/DATA/git/govoplan-docs/docs/DOCS_BACKLOG.md`
+- [Repo-docs-DOCUMENTATION-EXPERIENCE-CONCEPT](Repo-docs-DOCUMENTATION-EXPERIENCE-CONCEPT) - `/mnt/DATA/git/govoplan-docs/docs/DOCUMENTATION_EXPERIENCE_CONCEPT.md`
 - [Repo-docs-DOCUMENTATION-LAYER-CONCEPT](Repo-docs-DOCUMENTATION-LAYER-CONCEPT) - `/mnt/DATA/git/govoplan-docs/docs/DOCUMENTATION_LAYER_CONCEPT.md`
+- [Repo-docs-INSTANCE-AWARE-DOCUMENTATION](Repo-docs-INSTANCE-AWARE-DOCUMENTATION) - `/mnt/DATA/git/govoplan-docs/docs/INSTANCE_AWARE_DOCUMENTATION.md`

Repo-README.md

@@ -1,4 +1,4 @@
-<!-- codex-wiki-sync:a96ca5fac540e0c9739aa625 -->
+<!-- codex-wiki-sync:8fabe92df17075c5e3483808 -->
 
 > Mirrored from `/mnt/DATA/git/govoplan-docs/README.md`.
 > Origin: `repository`.
@@ -7,6 +7,10 @@
 ---
 # govoplan-docs
 
+<!-- govoplan-repository-type:start -->
+**Repository type:** module (platform).
+<!-- govoplan-repository-type:end -->
+
 GovOPlaN Docs provides the documentation layer for configured GovOPlaN systems.
 
 It answers "what does this installation provide for me?" before it answers "what could the full product do?". The goal is to reduce documentation complexity by starting from installed modules, enabled configuration, tenant policy, role, route availability, and visible capabilities.
@@ -25,6 +29,14 @@ This repository owns:
 
 Core owns module discovery, configuration package loading, route registry, RBAC evaluation, capability registry, and shared WebUI shell behavior.
 
+While Docs is installed, its managed `docs_reader` tenant role is an automatic
+authenticated-member baseline. Access derives its narrow read grant from the
+active Docs manifest without per-user assignments or authorization-time writes,
+so ordinary users can open their configured handbook without an administrator
+assigning documentation access one account at a time.
+Administrative documentation remains separately protected by
+`docs:documentation:admin` or the applicable administration scope.
+
 ## Documentation model
 
 The docs module should render documentation in three layers:
@@ -49,3 +61,48 @@ Frontend package:
 ```
 
 Platform module manifests, configuration packages, release catalogs, and governance rules are documented in `govoplan-core/docs/`.
+
+Every module manifest must contribute a static documentation baseline for both
+the `user` and `admin` projections through `ModuleManifest.documentation`.
+Runtime providers may add actor- and configuration-specific detail, but they do
+not replace that baseline. A behavior change is complete only when the owning
+module updates the affected workflows, settings, permissions, limitations, and
+operational consequences. Validate workspace coverage with:
+
+```sh
+cd /mnt/DATA/git/govoplan
+./tools/checks/check-manifest-shapes.py
+```
+
+Feature content remains in the owning module. Docs indexes and renders the
+contributions without importing feature implementations.
+
+Capabilities can provide generic documentation without exposing their runtime
+provider implementation:
+
+```python
+ModuleManifest(
+    capability_factories={"example.lookup": build_lookup},
+    capability_documentation={
+        "example.lookup": CapabilityDocumentation(
+            label="Example lookup",
+            summary="Resolves records through the versioned lookup contract.",
+            contract_version="2",
+            stability="stable",
+            audience=("module_admin",),
+        ),
+    },
+)
+```
+
+Docs also projects the configured module release catalog and configuration
+package catalog through the public Core catalog contracts. Catalog trust,
+freshness, provenance, descriptions, and package requirements remain visible
+as typed evidence; provider objects, credentials, and secret configuration are
+never imported into the Docs WebUI.
+
+## Concept documents
+
+- `docs/DOCUMENTATION_LAYER_CONCEPT.md` defines the configured, available, and evidence documentation model.
+- `docs/INSTANCE_AWARE_DOCUMENTATION.md` defines the runtime context and condition model.
+- `docs/DOCUMENTATION_EXPERIENCE_CONCEPT.md` defines the workflow, structure/reference, and design-pattern documentation experience.

Repo-docs-DOCUMENTATION-EXPERIENCE-CONCEPT.md

@@ -1,4 +1,4 @@
-<!-- codex-wiki-sync:320c1518180535134dcd6e2d -->
+<!-- codex-wiki-sync:79d1d5dab4ce88cf88d311e4 -->
 
 > Mirrored from `/mnt/DATA/git/govoplan-docs/docs/DOCUMENTATION_EXPERIENCE_CONCEPT.md`.
 > Origin: `repository`.
@@ -33,7 +33,7 @@ It should not start from a full product manual. The current tenant, installed
 modules, enabled routes, permissions, and configuration decide what is shown as
 the default path.
 
-Tracking issue: `add-ideas/govoplan-docs#15`.
+Tracking issue: `GovOPlaN/govoplan-docs#15`.
 
 ## Editorial Pillars
 
@@ -262,6 +262,9 @@ Workflow topics:
 - keep each step actionable
 - mention blockers where the user would encounter them
 - link to field/reference topics instead of repeating field tables
+- for every user-facing workflow, declare one or more conditions and put
+  `required_scopes` or `any_scopes` on every condition alternative; the release
+  gate rejects an unscoped alternative
 
 Reference topics:
 

Repo-docs-DOCUMENTATION-LAYER-CONCEPT.md

@@ -1,4 +1,4 @@
-<!-- codex-wiki-sync:60b27ca254fbe87a2c172238 -->
+<!-- codex-wiki-sync:14c99d76ad20ae1d21c43118 -->
 
 > Mirrored from `/mnt/DATA/git/govoplan-docs/docs/DOCUMENTATION_LAYER_CONCEPT.md`.
 > Origin: `repository`.
@@ -13,6 +13,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:
@@ -78,6 +83,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
@@ -87,6 +93,135 @@ 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.
+
+Every manifest must retain at least one static topic for each of the `user` and
+`admin` projections. A shared topic may serve both only when its language and
+disclosure level are appropriate for both audiences. A module that is still a
+seed should state that limitation plainly rather than documenting an unfinished
+screen as available. `documentation_providers` enrich this baseline; they do
+not replace it because a provider may be unavailable before configuration or
+database access succeeds.
+
+Documentation is part of a behavior change's completion criteria. The owning
+module updates affected workflows, fields and settings, permissions, optional
+integration behavior, failure or limitation explanations, and operator
+consequences in the same change. The workspace manifest-shape check enforces
+the static audience baseline:
+
+```sh
+cd /mnt/DATA/git/govoplan
+./tools/checks/check-manifest-shapes.py
+```
+
+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 runtime effective-policy topics. The provider evaluates the
+current actor and scope. A custom-profile task appears only when that actor has
+the relevant authority and the effective user policy permits it; the task then
+states the host/domain bounds and separate credential authority needed to
+complete it.
+
+Runtime providers must avoid leaking secrets. They should summarize posture,
+counts, source provenance, and enabling conditions. A provider may disclose a
+host or domain pattern only when the actor is authorized and that exact value is
+necessary to complete the documented task. Credentials, usernames, profile
+ids, source ids, unrelated topology, and raw policy payloads remain excluded.
+
+### 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 can remain visible in the administrator projection when
+safe. The user projection omits them so a protected body or metadata payload is
+not disclosed merely because a condition failed.
+
+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 a separately authorized technical projection. 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 require `docs:documentation:admin` or the compatible settings
+  administration authority and show technical context and evidence tables
+- user docs are the default and show only active plain-language topics,
+  examples, limits, and safe 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:
@@ -104,7 +239,50 @@ The UI should make the current context explicit enough to avoid confusion, but i
 
 ## Governance
 
-Durable context belongs in repository docs and synced wiki pages. Active work belongs in Gitea issues. Runtime documentation should link both where helpful, but it should distinguish stable explanation from changing backlog state.
+### Source Ownership
+
+Documentation ownership follows behavior ownership:
+
+- runtime documentation topics belong to the module that owns the route,
+  policy, workflow, capability, or data model being explained
+- repository docs belong to the repository that owns the implementation or
+  durable architecture decision
+- synced Gitea wiki pages are a publication surface for durable context, not a
+  separate source of truth
+- active Gitea issues are the source of truth for current work state,
+  acceptance criteria, blockers, and triage decisions
+
+The docs module renders and classifies documentation. It should not become the
+owner of feature-module explanations, and it should not copy backlog state into
+runtime documentation as if it were stable product behavior. When runtime docs
+link to an issue, they must present it as changing work state. When runtime docs
+link to repository docs or wiki pages, they may present the linked material as
+durable context if the owning repository treats it that way.
+
+Durable context belongs in repository docs and synced wiki pages. Active work
+belongs in Gitea issues. Runtime documentation should link both where helpful,
+but it should distinguish stable explanation from changing backlog state.
+
+### Privacy And Permission Boundaries
+
+Documentation is still a governed interface. Role-aware documentation must never
+use help text as a side channel for data, configuration, or capability details
+that the actor could not otherwise see.
+
+User-facing topics may explain that a feature is unavailable and identify the
+kind of blocker, such as missing permission, disabled module, locked policy, or
+administrator configuration. They should not expose internal module ids, raw
+scope names, policy payloads, hostnames, tenant identifiers, profile ids, or
+other operational details unless the actor is already allowed to inspect that
+information.
+
+Admin-facing topics may expose technical provenance, route ids, API paths,
+capabilities, configuration keys, policy source chains, and migration notes when
+the actor has the relevant administrative permission. Even then, runtime
+providers must summarize secrets and sensitive values as posture, counts, or
+source provenance. Credentials, tokens, private keys, raw payloads, and
+person-specific data stay out of documentation responses unless a dedicated
+audited administration route explicitly provides them.
 
 Documentation sources should be auditable when they affect compliance, operator procedure, or policy explanation. Configuration-derived documentation should identify the source configuration package or policy source where possible.
 
@@ -118,6 +296,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:
 
@@ -126,5 +305,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.

Repo-docs-INSTANCE-AWARE-DOCUMENTATION.md

@@ -0,0 +1,142 @@
+<!-- codex-wiki-sync:d9c87205c3338fa4a60fc289 -->
+
+> Mirrored from `/mnt/DATA/git/govoplan-docs/docs/INSTANCE_AWARE_DOCUMENTATION.md`.
+> Origin: `repository`.
+> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
+
+---
+# 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.