From 2ab89eb809afcf7c25350570c43a0588fc9d7654 Mon Sep 17 00:00:00 2001
From: Albrecht Degering <albrecht@degering.name>
Date: Sat, 1 Aug 2026 17:48:40 +0200
Subject: [PATCH] docs: declare institutional architecture boundary

---
 AGENTS.md                                | 16 ++++++++++
 src/govoplan_tenancy/backend/manifest.py | 37 +++++++++++++++++++++++-
 2 files changed, 52 insertions(+), 1 deletion(-)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..2e27339
--- /dev/null
+++ b/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.
diff --git a/src/govoplan_tenancy/backend/manifest.py b/src/govoplan_tenancy/backend/manifest.py
index 6b1b98d..c350cfd 100644
--- a/src/govoplan_tenancy/backend/manifest.py
+++ b/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",),
+    ),
 )