docs(docs): define safe configured task projections

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
+profiles and runtime effective-policy topics. The provider evaluates the
-limits sending to approved profile ids and disables user, group, and
+current actor and scope. A custom-profile task appears only when that actor has
-campaign-local profiles, the runtime docs state that users can choose approved
+the relevant authority and the effective user policy permits it; the task then
-profiles but cannot bring arbitrary SMTP or IMAP servers at lower scopes. If the
+states the host/domain bounds and separate credential authority needed to
-policy allows lower scopes, the same topic explains which scopes may define
+complete it.
-profiles and whether credential inheritance is locked.
 
 Runtime providers must avoid leaking secrets. They should summarize posture,
-counts, source provenance, and enabling conditions rather than exposing
+counts, source provenance, and enabling conditions. A provider may disclose a
-credentials, hostnames, profile ids, or raw policy payloads unless the route is
+host or domain pattern only when the actor is authorized and that exact value is
-explicitly intended for that level of detail.
+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
+The docs API classifies satisfied topics into their requested layer.
-topics remain visible as available or evidence documentation when safe, with a
+Unsatisfied topics can remain visible in the administrator projection when
-reason such as a missing module, capability, or scope.
+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
+- admin docs require `docs:documentation:admin` or the compatible settings
-- user docs show plain-language topics, examples, limits, and escalation paths
+  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
 

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.
+Normal user documentation returns only active, safely projected topics. Admin
-Admin documentation may show all layers plus route, permission, module, and
+documentation may show all layers plus route, permission, module, and capability
-capability diagnostics.
+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
+Raw blockers and scope names are part of the administrator projection. The user
-prevents dead-end instructions: users see whether a feature is unavailable
+projection omits inactive topics instead of returning their protected body,
-because a module is missing, a capability is not registered, or their current
+metadata, and blocker identifiers. A module can contribute a separate, safe
-permissions do not expose it.
+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,
+Safe disclosure is evaluated before a topic is returned. User docs contain
-missing module, and missing capability explanations should be useful but
+only active topics, runtime and HTTPS public links, and a bounded metadata
-minimal. User docs explain the blocker and who can resolve it. Admin docs can
+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