docs: declare institutional architecture boundary

AGENTS.md

@@ -0,0 +1,16 @@
+# GovOPlaN Tenancy Codex Guide
+
+## Scope
+
+This repository owns tenant lifecycle, tenant administration, tenant context resolution, and tenant settings over Core's shared scope storage.
+
+## Documentation Contract
+
+- Treat documentation as part of every behavior change. Update this module's manifest-driven `DocumentationTopic` contributions for affected user and administrator behavior.
+- Keep feature content here; `govoplan-docs` projects it without importing Tenancy internals.
+- Maintain a static user/admin baseline and run `/mnt/DATA/git/govoplan/tools/checks/check-manifest-shapes.py` after behavior or manifest changes.
+
+## Boundaries
+
+- Core owns shared scope storage; Access owns authentication and permission evaluation.
+- Preserve tenant isolation, ownership, and lifecycle recovery guarantees.

src/govoplan_tenancy/backend/manifest.py

@@ -6,7 +6,8 @@ from govoplan_core.core.access import (
     CAPABILITY_AUTH_TENANT_CONTEXT_SWITCHER,
     CAPABILITY_TENANCY_TENANT_RESOLVER,
 )
-from govoplan_core.core.modules import FrontendModule, ModuleContext, ModuleManifest
+from govoplan_core.core.modules import DocumentationTopic, FrontendModule, ModuleContext, ModuleManifest
+from govoplan_core.core.provider_governance import declared_module_architecture
 from govoplan_core.core.views import ViewSurface
 
 
@@ -41,6 +42,28 @@ manifest = ModuleManifest(
     capability_factories={
         CAPABILITY_TENANCY_TENANT_RESOLVER: _tenant_resolver,
     },
+    documentation=(
+        DocumentationTopic(
+            id="tenancy.current-context",
+            title="Work in the correct tenant context",
+            summary="The active tenant determines which tenant-scoped data, roles, settings, and module configuration are visible for a request.",
+            body="Accounts with access to more than one tenant can switch context through the platform tenant selector. Switching changes the active scope; it does not copy data or grant new authority. Always verify the selected tenant before creating or changing tenant-owned records.",
+            documentation_types=("user",),
+            audience=("user", "tenant_admin"),
+            related_modules=("access",),
+            metadata={"kind": "reference"},
+        ),
+        DocumentationTopic(
+            id="tenancy.lifecycle-and-settings",
+            title="Administer tenant lifecycle and settings",
+            summary="Tenancy adds explicit tenant creation, activation, context resolution, and tenant-owned settings over Core's shared scope storage.",
+            body="A tenant is a concrete administrative and data boundary. Tenant lifecycle changes must preserve ownership and recovery guarantees for module-owned records. Tenancy contributes system tenant management and tenant settings to the shared administration workspace; without this module, the Core and Access baseline can operate in single-scope compatibility mode.",
+            documentation_types=("admin",),
+            audience=("system_admin", "tenant_admin", "operator"),
+            related_modules=("access", "admin", "audit"),
+            metadata={"kind": "reference"},
+        ),
+    ),
     frontend=FrontendModule(
         module_id="tenancy",
         package_name="@govoplan/tenancy-webui",
@@ -61,6 +84,18 @@ manifest = ModuleManifest(
             ),
         ),
     ),
+    architecture=declared_module_architecture(
+        layer="institutional_foundation",
+        kind="foundation",
+        maturity="vertical_slice",
+        documentation_ref="docs/TENANCY_MODULE_BOUNDARY.md",
+        test_ref="tests/test_tenant_lifecycle.py",
+        known_limits=("Cross-region tenant relocation and complete major-version recovery evidence are not implemented.",),
+        owned_concepts=("tenant lifecycle", "tenant context", "tenant settings"),
+        non_owned_concepts=("account authorization", "organization hierarchy", "module-owned tenant data"),
+        recovery_docs=("docs/TENANCY_MODULE_BOUNDARY.md",),
+        security_docs=("docs/TENANCY_MODULE_BOUNDARY.md",),
+    ),
 )