chore: sync GovOPlaN module split state

docs/INSTANCE_AWARE_DOCUMENTATION.md

@@ -0,0 +1,70 @@
+# Instance-Aware Documentation
+
+The docs module renders documentation for the current GovOPlaN instance instead
+of showing a static product manual.
+
+## Inputs
+
+The documentation context is built from:
+
+- enabled module manifests
+- frontend routes and navigation metadata
+- module permissions and the current principal's granted scopes
+- documentation topics contributed by manifests
+- runtime documentation providers contributed by modules
+- optional dependencies and declared capabilities
+
+## Layers
+
+| Layer | Meaning |
+| --- | --- |
+| `always` | Generic platform concepts that are useful in every deployment. |
+| `configured` | Documentation for installed modules/features visible in this instance. |
+| `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.
+
+## Conditions
+
+Documentation topics can declare:
+
+- required modules
+- any-of module sets
+- modules that must be absent
+- required capabilities
+- required scopes
+- any-of scope sets
+- related configuration keys
+
+The API returns both a human-readable `reason` and structured `blockers`:
+
+```json
+{
+  "reason": "missing modules: mail; missing scopes: mail:profile:read",
+  "blockers": {
+    "modules": ["mail"],
+    "capabilities": [],
+    "scopes": ["mail:profile:read"]
+  }
+}
+```
+
+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.
+
+## Module Guidance
+
+Module docs should not hard-code assumptions about sibling modules. A module
+should contribute conditional topics such as:
+
+- "Send selected file by mail" requiring `files` and `mail`
+- "Campaign attachments from storage" requiring `campaigns` and `files`
+- "Mailbox diagnostics" requiring `mail.devMailbox`
+
+The docs module remains the renderer. Feature modules own their subject matter
+and describe unlocks through manifest metadata.