From bbe3c7d16335a642980fc705be8acd517dde3d6e Mon Sep 17 00:00:00 2001 From: Albrecht Degering Date: Tue, 21 Jul 2026 18:40:08 +0200 Subject: [PATCH] docs(docs): define safe configured task projections --- docs/DOCUMENTATION_LAYER_CONCEPT.md | 33 +++++++++++---------- docs/INSTANCE_AWARE_DOCUMENTATION.md | 44 +++++++++++++++++++++------- 2 files changed, 51 insertions(+), 26 deletions(-) diff --git a/docs/DOCUMENTATION_LAYER_CONCEPT.md b/docs/DOCUMENTATION_LAYER_CONCEPT.md index fbe9f99..b0cd766 100644 --- a/docs/DOCUMENTATION_LAYER_CONCEPT.md +++ b/docs/DOCUMENTATION_LAYER_CONCEPT.md @@ -100,17 +100,17 @@ 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. +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 rather than exposing -credentials, hostnames, profile ids, or raw policy payloads unless the route is -explicitly intended for that level of detail. +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 @@ -123,9 +123,10 @@ Documentation topics can declare conditions: - 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. +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 @@ -136,7 +137,7 @@ then to public module documentation for broader examples. GovOPlaN has two documentation presentations over the same source model. -Admin documentation is allowed to be technical. It can expose installed module +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, @@ -157,8 +158,10 @@ 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 +- 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 diff --git a/docs/INSTANCE_AWARE_DOCUMENTATION.md b/docs/INSTANCE_AWARE_DOCUMENTATION.md index e3ed290..add65ef 100644 --- a/docs/INSTANCE_AWARE_DOCUMENTATION.md +++ b/docs/INSTANCE_AWARE_DOCUMENTATION.md @@ -23,9 +23,10 @@ The documentation context is built from: | `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 should emphasize `always` and `configured` content. -Admin documentation may show all layers plus route, permission, module, and -capability diagnostics. +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 @@ -37,7 +38,11 @@ Documentation topics can declare: - required capabilities - required scopes - any-of scope sets -- related configuration keys +- 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`: @@ -52,10 +57,27 @@ The API returns both a human-readable `reason` and structured `blockers`: } ``` -The WebUI must display the reason and, when present, the blocker lists. This -prevents dead-end instructions: users see whether a feature is unavailable -because a module is missing, a capability is not registered, or their current -permissions do not expose it. +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 @@ -90,9 +112,9 @@ 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. Missing permission, -missing module, and missing capability explanations should be useful but -minimal. User docs explain the blocker and who can resolve it. Admin docs can +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