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

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