docs: declare institutional architecture boundary

AGENTS.md

@@ -0,0 +1,16 @@
+# GovOPlaN Notifications Codex Guide
+
+## Scope
+
+This repository owns durable in-product notifications, preferences, delivery attempts, the notification center, and optional channel dispatch.
+
+## 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 Notifications 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
+
+- Producing modules own notification meaning; Notifications owns durable delivery state.
+- Use optional Mail and Portal capabilities without importing their internals.

src/govoplan_notifications/backend/manifest.py

@@ -5,6 +5,7 @@ from pathlib import Path
 from govoplan_core.core.access import CAPABILITY_AUTH_PERMISSION_EVALUATOR, CAPABILITY_AUTH_PRINCIPAL_RESOLVER
 from govoplan_core.core.module_guards import drop_table_retirement_provider, persistent_table_uninstall_guard
 from govoplan_core.core.modules import (
+    DocumentationTopic,
     FrontendModule,
     FrontendRoute,
     MigrationSpec,
@@ -14,6 +15,7 @@ from govoplan_core.core.modules import (
     PermissionDefinition,
     RoleTemplate,
 )
+from govoplan_core.core.provider_governance import declared_module_architecture
 from govoplan_core.core.notifications import CAPABILITY_NOTIFICATIONS_DISPATCH
 from govoplan_core.core.views import ViewSurface
 from govoplan_core.db.base import Base
@@ -92,6 +94,28 @@ manifest = ModuleManifest(
     role_templates=ROLE_TEMPLATES,
     route_factory=_notifications_router,
     tenant_summary_providers=(_tenant_summary,),
+    documentation=(
+        DocumentationTopic(
+            id="notifications.center-and-preferences",
+            title="Use the notification center",
+            summary="The title-bar badge and notification center collect durable notices that require attention outside an immediate request.",
+            body="Open the notification center to read, acknowledge, or follow notifications from enabled modules. Preferences control eligible delivery channels and categories. Disabling an optional external channel does not remove the in-product notification unless the originating module's retention policy does so.",
+            documentation_types=("user",),
+            audience=("user",),
+            related_modules=("mail", "calendar", "scheduling", "workflow_engine"),
+            metadata={"kind": "reference"},
+        ),
+        DocumentationTopic(
+            id="notifications.delivery-operations",
+            title="Operate notification delivery",
+            summary="Notifications persists message intent and bounded per-channel attempts before workers dispatch optional delivery channels.",
+            body="Producing modules emit notifications through the dispatch capability and do not own delivery credentials. In-product delivery is the baseline. Production email delivery is available only through an enabled Mail capability; file delivery remains development-only. Operators can inspect pending and failed attempts and retry only outcomes that are safe to repeat.",
+            documentation_types=("admin",),
+            audience=("tenant_admin", "operator", "module_admin"),
+            related_modules=("mail", "audit", "ops"),
+            metadata={"kind": "reference"},
+        ),
+    ),
     frontend=FrontendModule(
         module_id=MODULE_ID,
         package_name="@govoplan/notifications-webui",
@@ -147,6 +171,18 @@ manifest = ModuleManifest(
             fromlist=["dispatch_capability"],
         ).dispatch_capability(context),
     },
+    architecture=declared_module_architecture(
+        layer="communication_participation",
+        kind="runtime",
+        maturity="vertical_slice",
+        documentation_ref="docs/NOTIFICATION_INBOX_BOUNDARY.md",
+        test_ref="tests/test_notifications.py",
+        known_limits=("Production email delivery depends on the optional Mail capability and does not provide an independent transport.",),
+        owned_concepts=("notification", "notification preference", "notification delivery attempt"),
+        non_owned_concepts=("mail transport", "domain event", "portal message"),
+        recovery_docs=("docs/EMAIL_DELIVERY.md",),
+        operations_docs=("docs/EMAIL_DELIVERY.md",),
+    ),
 )