Sync Repo-README from project files

Repo-README.-.md

@@ -0,0 +1,65 @@
+<!-- codex-wiki-sync:a11a85133e0b1a1ce88a3e6f -->
+
+> Mirrored from `/mnt/DATA/git/govoplan-views/README.md`.
+> Origin: `repository`.
+> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
+
+---
+# govoplan-views
+
+<!-- govoplan-repository-type:start -->
+**Repository type:** module (platform).
+<!-- govoplan-repository-type:end -->
+
+`govoplan-views` provides governed, task-focused interface projections for
+GovOPlaN. A View selects modules, navigation entries, routes, sections, and
+actions that should be shown for a particular task without changing the
+underlying authorization decision.
+
+The module owns versioned View definitions, immutable revisions, assignments
+at system, tenant, group, and user scope, effective-view resolution, and the
+user's current selection. Core owns the surface contract and applies the
+effective projection to the shared shell. Modules announce their selectable
+surface hierarchy in their manifests and WebUI contributions.
+
+Views are presentation filters, never security boundaries. Hidden routes still
+use their normal permission checks. Required Views retain the View selector and
+administration surfaces needed to inspect and change the assignment, preventing
+administrators from locking an installation out of its own configuration.
+
+## Administration
+
+The module contributes **Views** sections to system and tenant administration.
+Administrators can:
+
+- create a draft from the currently installed surface catalogue
+- choose modules, navigation entries, routes, sections, and actions
+- publish immutable revisions
+- make a published View available, default, or required at system, tenant,
+  group, or user scope
+- pin an assignment to its published revision or let it follow later published
+  revisions
+- inspect and remove references to surfaces retired by a module
+
+Required assignments are validated by the backend. They must retain the Views
+selector, the Access administration route, and the administration section able
+to remove the assignment. If an installed-module change leaves an active View
+without a reachable navigation entry and route, Core shows the normal
+authorized interface and reports the stale projection instead of trapping the
+user.
+
+## Development
+
+Install the module as an editable package alongside Core and include `views` in
+`ENABLED_MODULES`. Core's registered-module migration runner applies
+the Views migration on startup.
+
+```bash
+pip install -e ../govoplan-views
+python -m unittest discover -s ../govoplan-views/tests -v
+```
+
+Workflow declares the resolver as an optional contract so a future workflow
+instance runtime can activate a pinned View revision. Workflow-driven
+activation and Policy ceilings remain separate follow-up work; neither is
+required for manually assigned and selected Views.