docs: declare institutional architecture boundary

AGENTS.md

@@ -0,0 +1,16 @@
+# GovOPlaN Poll Codex Guide
+
+## Scope
+
+This repository owns reusable poll definitions, options, invitations, signed participation, responses, closing semantics, and result aggregation.
+
+## 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 Poll 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
+
+- Scheduling adds meeting-specific workflow and Calendar integration; Evaluation owns surveys and scoring.
+- Keep Access optional and preserve atomic participation constraints.

src/govoplan_poll/backend/manifest.py

@@ -13,6 +13,7 @@ from govoplan_core.core.modules import (
     PermissionDefinition,
     RoleTemplate,
 )
+from govoplan_core.core.provider_governance import declared_module_architecture
 from govoplan_core.core.poll import CAPABILITY_POLL_SCHEDULING
 from govoplan_core.core.poll_participation import CAPABILITY_POLL_PARTICIPATION_GATEWAY
 from govoplan_core.db.base import Base
@@ -77,11 +78,26 @@ DOCUMENTATION = (
             "or adapter-provided participant flows."
         ),
         layer="available",
-        documentation_types=("admin",),
+        documentation_types=("admin", "user"),
-        audience=("operator", "module_admin", "product_owner"),
+        audience=("user", "operator", "module_admin", "product_owner"),
         related_modules=("scheduling", "evaluation", "calendar", "campaigns", "portal"),
         metadata={"seed": True},
     ),
+    DocumentationTopic(
+        id="poll.participation-and-results",
+        title="Respond to a poll",
+        summary="Polls can collect single or multiple choices, yes/no, yes/no/maybe, ranked choices, and availability responses.",
+        body=(
+            "An invitation or signed participation link determines which poll and participant identity a response belongs to. "
+            "The poll policy controls anonymity, response updates, result visibility, open and close times, and whether Maybe is allowed. "
+            "Submitting a response is atomic: capacity and choice constraints are checked before the saved response replaces any earlier answer."
+        ),
+        layer="configured",
+        documentation_types=("user",),
+        audience=("user", "participant", "organizer"),
+        related_modules=("scheduling", "evaluation"),
+        metadata={"kind": "reference"},
+    ),
 )
 
 
@@ -164,6 +180,18 @@ manifest = ModuleManifest(
         ),
     ),
     documentation=DOCUMENTATION,
+    architecture=declared_module_architecture(
+        layer="communication_participation",
+        kind="domain",
+        maturity="vertical_slice",
+        documentation_ref="README.md",
+        test_ref="tests/test_service.py",
+        known_limits=("Advanced voting methods, production notification profiles, and reference accessibility evidence remain incomplete.",),
+        owned_concepts=("poll", "poll option", "poll invitation", "poll response"),
+        non_owned_concepts=("scheduling request", "calendar event", "evaluation rubric"),
+        recovery_docs=("README.md",),
+        security_docs=("README.md",),
+    ),
 )