feat: add platform interface inventory and encryption registry

docs/PLATFORM_CONTROL_PLANE.md

@@ -0,0 +1,126 @@
+# Platform Control Plane And Self-Description
+
+## Objective
+
+GovOPlaN should be able to describe its installed structure without becoming a
+self-modifying application. The platform model is a declarative control plane:
+module manifests, UI contributions, schemas, policy provenance, runtime
+capabilities, and generated source evidence describe what can be configured.
+Ordinary administrators edit validated data through those contracts; they do
+not edit Python, TypeScript, routes, or database code from the product UI.
+
+This distinction provides the requested overview while preserving reviewable
+releases, module boundaries, migrations, and security controls.
+
+## Canonical Sources
+
+| Concern | Canonical source |
+| --- | --- |
+| Installed modules and dependency graph | Runtime `ModuleManifest` registry |
+| Backend routes | Registered FastAPI application; Python AST is build-time evidence |
+| Frontend routes and navigation | `PlatformWebModule` contributions |
+| View-filterable regions | Versioned `viewSurfaces` declarations |
+| Admin sections and module settings | `admin.sections`, including `moduleId`, `kind`, scope group, permission guards, and surface ID |
+| User settings | `settings.sections` and core settings schemas |
+| Labels and translations | Generated translation catalogs plus source usage |
+| Fields and help coverage | Shared form components plus generated TypeScript AST inventory |
+| API use by the WebUI | Typed API clients plus generated static reference inventory |
+| Effective configuration | Owning module data plus Policy provenance |
+
+Runtime introspection is authoritative for an installed system. Static source
+inventory is authoritative evidence for a checkout or release candidate. The
+two should be compared in CI and by Ops, not conflated.
+
+## Generated Inventory
+
+Run:
+
+```bash
+cd /mnt/DATA/git/govoplan
+./.venv/bin/python tools/inventory/platform-interface-inventory.py
+```
+
+The command writes:
+
+- `audit-reports/platform-inventory/platform-interface-inventory.json`
+- `audit-reports/platform-inventory/platform-interface-inventory.md`
+
+It combines:
+
+1. loaded module manifests
+2. TypeScript AST extraction of fields, label attributes, visible text,
+   translations, frontend routes, navigation, capabilities, and API references
+3. Python AST extraction of FastAPI route decorators and router prefixes
+
+The JSON includes exact repository, file, and line evidence. A missing-help
+entry is a review candidate because dynamic parent components may supply help.
+A backend route without a static frontend reference is also a review candidate:
+public APIs, workers, callbacks, health checks, connectors, and dynamic URL
+assembly are valid explanations.
+
+`--strict` currently enforces only translation-catalog completeness. Endpoint
+and help classifications need narrow reviewed baselines before they can become
+release gates.
+
+## Admin Information Architecture
+
+The Admin host uses a tree because system, tenant, group, user, and module
+settings form a hierarchy rather than one flat list. Every contributed section
+can identify:
+
+- its owning `moduleId`
+- whether it is `management` or `settings`
+- its system/tenant/group/user scope group
+- an optional future `parentId`
+- permission and View visibility requirements
+
+Existing panels remain their own render owners. The tree only changes discovery
+and grouping. A later embedded-settings contract may add named slots inside an
+owning page; it must not allow one module to import another module's private
+component.
+
+## Navigation And Workflow
+
+The intended maximum visible navigation stack is:
+
+1. global shell context
+2. one task/object navigation surface
+3. one workflow stage surface when a workflow is active
+
+Workflow instance pages should reuse the Campaign stage language: clear stage
+state, optional/skipped/blocked semantics, partial progress, and a stable current
+step. Workflow definition pages remain graph editors. Views may activate a
+focused workflow view that suppresses unrelated shell and module surfaces while
+retaining an explicit way out.
+
+Nested module submenus should not be added merely because a data hierarchy
+exists. Prefer a tree inside configuration/directory surfaces, tabs for sibling
+views, and the workflow stage rail for ordered work.
+
+## Safe Meta-Configuration
+
+The platform can eventually render many configuration editors from versioned
+JSON Schema and UI Schema supplied by modules. Generated editors remain bounded
+by:
+
+- explicit typed schemas and migrations
+- module-owned validation and preview
+- Policy locks and provenance
+- permission and View filtering
+- preflight, consequence, and rollback information
+- auditable apply operations
+
+Custom code, new routes, arbitrary SQL, and executable workflow nodes remain
+release artifacts. Modeling them as ordinary configuration would create an
+unreviewed code-execution and migration channel.
+
+## Next Enforcement Slices
+
+1. Require every WebUI module route and admin/settings contribution to have
+   matching manifest metadata or a reviewed exception.
+2. Add stable field IDs and optional help-topic IDs to shared field components.
+3. Classify each statically unreferenced backend endpoint by consumer type.
+4. Compare a running installation's OpenAPI and module registry against the
+   release inventory.
+5. Publish the sanitized installed-system structure through Ops/Docs for
+   authorized administrators.