docs: declare institutional architecture boundary

AGENTS.md

@@ -0,0 +1,16 @@
+# GovOPlaN Admin Codex Guide
+
+## Scope
+
+This repository owns generic administration sections, governance templates, configuration packages, and operator-facing module lifecycle controls.
+
+## 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 Admin 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
+
+- Consume module metadata and extension points; do not import optional module internals.
+- Keep package mutation in the trusted installer process rather than request handlers.

src/govoplan_admin/backend/manifest.py

@@ -3,7 +3,8 @@ from __future__ import annotations
 from govoplan_admin.backend.db import models as admin_models  # noqa: F401 - populate Admin ORM metadata
 from govoplan_core.core.access import CAPABILITY_AUTH_PERMISSION_EVALUATOR, CAPABILITY_AUTH_PRINCIPAL_RESOLVER
 from govoplan_core.core.module_guards import persistent_table_uninstall_guard
-from govoplan_core.core.modules import FrontendModule, MigrationSpec, ModuleContext, ModuleManifest
+from govoplan_core.core.modules import DocumentationTopic, FrontendModule, MigrationSpec, ModuleContext, ModuleManifest
+from govoplan_core.core.provider_governance import declared_module_architecture
 from govoplan_core.core.views import ViewSurface
 from govoplan_core.db.base import Base
 
@@ -21,6 +22,27 @@ manifest = ModuleManifest(
     version="0.1.8",
     required_capabilities=(CAPABILITY_AUTH_PRINCIPAL_RESOLVER, CAPABILITY_AUTH_PERMISSION_EVALUATOR),
     route_factory=_route_factory,
+    documentation=(
+        DocumentationTopic(
+            id="admin.workspace",
+            title="Use the administration workspace",
+            summary="The administration workspace shows only the sections supplied by enabled modules and allowed by the current account's permissions.",
+            body="System and tenant administration share one workspace. Available sections can include settings, configuration changes and packages, governance templates, groups, and module lifecycle controls. A missing section normally means that its owning module is disabled or the current account lacks the required authority.",
+            documentation_types=("user",),
+            audience=("tenant_admin", "system_admin", "operator"),
+            metadata={"kind": "reference"},
+        ),
+        DocumentationTopic(
+            id="admin.governance-and-module-lifecycle",
+            title="Govern configuration and module lifecycle",
+            summary="Admin owns reusable governance templates, configuration packages, and the operator-facing module lifecycle queue.",
+            body="Configuration packages import or export module-owned configuration; they do not install software. Module catalog actions create reviewed install, update, activation, deactivation, or retirement requests for the trusted installer process. Governance templates materialize approved role and group structures through the owning Access contracts.",
+            documentation_types=("admin",),
+            audience=("system_admin", "operator", "module_admin"),
+            related_modules=("access", "audit", "ops"),
+            metadata={"kind": "reference"},
+        ),
+    ),
     frontend=FrontendModule(
         module_id="admin",
         package_name="@govoplan/admin-webui",
@@ -42,6 +64,17 @@ manifest = ModuleManifest(
             label="Admin",
         ),
     ),
+    architecture=declared_module_architecture(
+        layer="runtime_meta",
+        kind="presentation",
+        maturity="vertical_slice",
+        documentation_ref="README.md",
+        test_ref="tests/test_catalog_plan.py",
+        known_limits=("Some module-specific administration surfaces still own their own navigation and release evidence.",),
+        owned_concepts=("administration workspace", "configuration package workflow", "module lifecycle request"),
+        non_owned_concepts=("module installation effect", "access policy", "module-owned settings"),
+        operations_docs=("README.md",),
+    ),
 )