feat(docs): define semantic subject contract

docs/DOCUMENTATION_MAP.md

@@ -22,6 +22,7 @@ operator, and roadmap pages.
 | Cross-module information governance adoption | `INFORMATION_GOVERNANCE_ADOPTION.md` | Manifest evidence and enforcement rules for temporal browsing, purpose-aware access, retention, and institutional context. |
 | Data-subject access and erasure requests | `DATA_SUBJECT_REQUESTS.md` | Provider-owned search and mutation, explicit coverage, governed export, retained evidence, permissions, and idempotent execution. |
 | Context-sensitive F1 help | `CONTEXTUAL_HELP_CONTRACT.md` | Focus, route, module-manifest documentation contexts, Docs projection, and hosted fallback. |
+| Semantic documentation subjects | `SEMANTIC_DOCUMENTATION_SUBJECTS.md` | Stable configured-artifact identity, safe provider discovery, revision review, authorization, and lifecycle semantics. |
 | German localization and help quality gate | `LOCALIZATION_AND_HELP_QUALITY.md` | German reference locale, new-installation default, catalog completeness, automatic page associations, and explicit-help review priorities. |
 | Postbox E2EE target architecture | `POSTBOX_E2EE_ARCHITECTURE.md` | Strategic encrypted postbox/mailbox model, key ownership, role mailbox semantics, and retraction limits. |
 | Shared state, runtime coordination, and recovery | `STATE_AND_RECOVERY_CONTRACT.md` | State profiles, object storage, node registration/drain, fenced leases, migration ordering, and recovery evidence. |

docs/MODULE_ARCHITECTURE.md

@@ -1621,6 +1621,17 @@ URLs never contain credentials; only credential-envelope references cross the
 contract. Provider-specific details belong in sanitized provenance rather than
 in a shared domain schema.
 
+## Semantic Documentation Subject Contract
+
+Optional modules expose configured artifacts that can be documented through
+the module-scoped `documentation.semantic_subjects.<module_id>` capability.
+Core supplies stable tenant-scoped references, typed nested anchors, safe
+localized descriptors, revision/fingerprint review signals, and explicit
+availability states. Providers remain responsible for authorization and do not
+expose configuration payloads or credentials. Docs discovers the capability
+and owns authored content; it does not import feature internals. See
+`SEMANTIC_DOCUMENTATION_SUBJECTS.md` for the contract and adoption rules.
+
 ## Build And Verification
 
 Backend verification from core:

docs/SEMANTIC_DOCUMENTATION_SUBJECTS.md

@@ -0,0 +1,118 @@
+# Semantic Documentation Subjects
+
+## Purpose And Ownership
+
+The semantic-documentation subject contract lets an optional module expose the
+configured artifacts that administrators may document: for example a form, a
+form field, a workflow, or a workflow state. It is a discovery and resolution
+contract, not a second configuration API.
+
+The module that owns an artifact also owns its subject provider, authorization,
+identity, revision, route, and lifecycle semantics. Docs may discover those
+providers through Core and attach authored documentation to their stable
+references. Docs must not import the feature module, read its tables, or copy
+configuration content into a generic index.
+
+This contract is additive to manifest `DocumentationTopic` contributions and
+configured-state `documentation_providers`. Every providing module must retain
+static user and administrator documentation baselines. The baselines explain
+the feature even when the provider is disabled, unavailable, or has no
+configured subjects.
+
+## Identity And Versioning
+
+`SemanticDocumentationSubjectReference` identifies a subject with:
+
+- owning module and tenant;
+- a module-defined subject kind and stable identifier;
+- an optional typed nested anchor, such as `field/registration-number`;
+- the revision and canonical fingerprint observed when documentation was
+  authored or reviewed.
+
+The `stable_key` derives only from identity. A rename or configuration revision
+therefore does not detach existing documentation. A nested anchor has its own
+identity so a field can be documented independently from its form.
+
+Providers must resolve an old reference as one of:
+
+- `available`: the observed revision/fingerprint is still current;
+- `changed`: the same stable subject has changed and may need review;
+- `superseded`: another stable reference replaced it;
+- `missing`: the subject was removed or is no longer resolvable;
+- `temporarily_unavailable`: the provider cannot currently determine state.
+
+Absence is not authorization. A provider returns `None` when the principal may
+not learn whether a subject exists. Core also rejects cross-tenant list and
+resolution requests before calling a provider.
+
+## Safe Projection
+
+Descriptors contain only bounded, explicit presentation fields: localized
+labels and descriptions, breadcrumbs, a local route, audience,
+classification, and required scopes. They must not contain credentials,
+personal data, arbitrary provider metadata, configuration payloads, or the
+authored documentation itself. Routes are application-local and are still
+subject to normal route authorization.
+
+The fingerprint is a review signal, not a concurrency token or a content hash
+that callers may use to reconstruct configuration. Providers should calculate
+it from the smallest canonical JSON projection whose semantic changes require
+documentation review. Volatile timestamps and secrets must be excluded.
+
+## Provider Registration
+
+A provider is registered under its exact module-scoped capability name:
+
+```python
+from govoplan_core.core.modules import CapabilityDocumentation
+from govoplan_core.core.semantic_documentation import (
+    SEMANTIC_DOCUMENTATION_SUBJECT_CONTRACT_VERSION,
+    semantic_documentation_subject_capability,
+)
+
+capability = semantic_documentation_subject_capability("forms")
+
+manifest = ModuleManifest(
+    id="forms",
+    # ...
+    capability_factories={capability: build_semantic_subject_provider},
+    capability_documentation={
+        capability: CapabilityDocumentation(
+            label="Form semantic subjects",
+            summary="Lists authorized configured forms and fields for Docs.",
+            contract_version=SEMANTIC_DOCUMENTATION_SUBJECT_CONTRACT_VERSION,
+            documentation_types=("admin", "user"),
+        )
+    },
+    documentation=(admin_baseline, user_baseline),
+)
+```
+
+The capability is `documentation.semantic_subjects.<module_id>`. Registry
+validation rejects a mismatched owner, missing capability documentation, a
+wrong contract version, or missing static baselines.
+
+`list_semantic_documentation_subjects` performs authorized, paginated discovery
+across installed providers. `resolve_semantic_documentation_subject` targets
+one owner without loading another feature module. Providers must apply the
+current tenant and principal on every call and must not infer visibility from a
+previous list result.
+
+## Lifecycle And Integration Rules
+
+- Keep subject and anchor identifiers stable across display-name and route
+  changes.
+- Return `superseded` only with the replacement reference; do not silently
+  rewrite stored references.
+- Return a reason code for missing or temporarily unavailable subjects without
+  exposing sensitive detail.
+- Reauthorize both discovery and resolution. Stored documentation references
+  confer no access to a live artifact.
+- Treat a changed fingerprint as a request for editorial review. It does not
+  automatically invalidate or publish authored documentation.
+- Removing a feature module leaves references resolvable as provider
+  unavailable. Docs can preserve history without importing the module.
+
+Forms, Workflow, and later modules should implement their subject providers in
+their own repositories. Docs owns the authored semantic-documentation records,
+review workflow, and projection UI.