docs(docs): define safe configured task projections
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user