docs(docs): define safe configured task projections

This commit is contained in:
2026-07-21 18:40:08 +02:00
parent 0f41e02428
commit bbe3c7d163
2 changed files with 51 additions and 26 deletions

View File

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