Add resource access explanation contract

docs/ACCESS_RBAC_MODEL.md

@@ -1,6 +1,6 @@
 # GovOPlaN RBAC And Resource-Access Model
 
-**Updated:** 2026-07-09
+**Updated:** 2026-07-11
 
 ## Authorization Equation
 
@@ -254,6 +254,61 @@ space/folder/file ownership:
 External file connections and spaces are additionally constrained by connector
 policy and owner/group assignment in the files module.
 
+## Resource Access Explanations
+
+The access module exposes a diagnostic endpoint for explaining why a principal
+can see or operate on a concrete resource:
+
+```text
+GET /api/v1/admin/access/resource-explanation
+```
+
+Required query values:
+
+| Field | Meaning |
+| --- | --- |
+| `user_id` | Tenant membership to explain. The current module UIs pass the signed-in user. |
+| `resource_type` | Module-owned type such as `file`, `folder`, or `campaign`. |
+| `resource_id` | Stable module resource identifier. |
+| `action` | Permission/action being explained, for example `files:file:read`. |
+| `tenant_id` | Optional tenant override for system/admin contexts. |
+
+The access module always contributes effective-scope provenance for the action.
+Installed modules may add resource provenance by exposing a
+`ResourceAccessExplanationProvider` through a capability consumed by access.
+Providers should return only facts they own, using these provenance kinds:
+
+| Kind | Meaning |
+| --- | --- |
+| `resource` | The concrete resource or an explicit not-found result. |
+| `owner` | Matching user/group ownership. |
+| `share` | Matching explicit user/group/tenant share. |
+| `policy` | Administrative bypass or policy-derived grant. |
+| `role` / `right` | Scope and role provenance from access itself. |
+
+Files currently registers `files.access` and explains file assets plus folders.
+Persisted folders use their database ID. Folder rows inferred from file paths use
+a deterministic virtual ID:
+
+```text
+virtual-folder:v1:<tenant_id>:<owner_type>:<owner_id>:<base64url(normalized_path)>
+```
+
+The files provider validates virtual folder IDs before returning provenance: the
+tenant and owner must match the resource ID, and at least one active file must
+exist below the normalized folder path. This keeps virtual folder explanations
+stable without forcing every inferred tree node to become a stored folder row.
+
+Campaign currently registers `campaigns.access` and explains the campaign
+ownership/sharing object itself. Finer-grained campaign sub-objects are tracked
+separately in `govoplan-campaign#50` until their resource identifiers and access
+rules are decided.
+
+Cross-user resource explanation is a policy feature, not a module-local UI
+detail. Until `govoplan-policy#6` is resolved, module UIs should default to
+current-user explanation and avoid importing access-admin user-picking
+components.
+
 ## Mail Servers
 
 | Scope | Meaning |