feat: add registration access ui contracts

docs/registration-and-access-management-ui.md

@@ -0,0 +1,128 @@
+# Registration And Access Management UI
+
+Status: implemented headless UI contract slice
+Date: 2026-06-15
+Related workplan: USER-WP-0014
+
+## Purpose
+
+This slice adds an optional NetKingdom registration and access-management UI
+contract over the headless `UserEngineService`. It is not a credential UI and
+does not own browser state. It provides transport-neutral screen models,
+route contracts, and an accessible HTML renderer that web, desktop, or CLI
+adapters can serve.
+
+## Information Architecture
+
+The implemented UI facade exposes these primary areas:
+
+- registration
+- prepared rights
+- active hat
+- profile
+- onboarding
+- admin
+
+The supported views cover registration start/resume, factor status,
+registration completion, prepared-account review and claim, active hat
+selection, onboarding status, admin prepared accounts, admin access profiles,
+and admin onboarding diagnostics.
+
+## Public Facade
+
+`RegistrationAccessManagementUi` lives in `user_engine.ui` and is exported from
+`user_engine`.
+
+It exposes:
+
+- `information_architecture()`
+- `api_contract()`
+- `start_registration(...)`
+- `attach_factor(...)`
+- `complete_registration(...)`
+- `registration_screen(...)`
+- `prepared_rights_review(...)`
+- `accept_prepared_claim(...)`
+- `deny_prepared_claim(...)`
+- `hat_selection_view(...)`
+- `select_hat(...)`
+- `admin_dashboard(...)`
+- `render_html(...)`
+
+## Route Contract
+
+The UI route contract maps thin transport routes to existing headless service
+facades:
+
+- `registration.start` -> `start_registration`
+- `registration.factor` -> `attach_registration_factor`
+- `registration.complete` -> `complete_registration`
+- `prepared_account.review` -> `list_prepared_accounts`
+- `prepared_account.accept` -> `claim_prepared_account`
+- `prepared_account.deny` -> UI dismiss decision
+- `access_profile.select_hat` -> `select_active_hat`
+- `admin.dashboard` -> diagnostics/list views
+
+Proofing, IAM, authorization, notification, and protected service consoles
+remain adapter boundaries.
+
+## Registration Flow
+
+The self-service UI facade can start registration, attach adapter-supplied
+factor evidence, show safe factor status by type, enforce UI terms/consent
+before completion, and show the resulting NetKingdom ID.
+
+Factor values are never rendered. The flow displays factor types and status,
+not email addresses, phone numbers, postal addresses, eID payloads, provider
+tokens, or challenge material.
+
+## Prepared Rights
+
+Prepared-account review displays pending packages by id, display name,
+required factor types, entitlement kinds, and status. Required factor values
+are redacted. Accepting a package calls `claim_prepared_account`. Denying a
+package is an explicit UI dismiss state and does not mutate prepared-account
+domain state.
+
+## Hats And Active Context
+
+The active-hat view lists access profiles and the current active context.
+Selecting a hat calls `select_active_hat`; the domain service still enforces
+tenant, membership, factor, approval, and authorization rules. The UI does not
+display hidden policy logic or final authorization decisions.
+
+## Admin Surface
+
+The admin dashboard composes existing diagnostics and list operations:
+
+- registration diagnostics
+- tenant diagnostics
+- prepared-account counts
+- access-profile counts
+- onboarding diagnostics
+
+The dashboard intentionally reports counts and lifecycle gaps without exposing
+factor values, prepared-account factor matches, profile default values, claim
+values, or raw proofing payloads.
+
+## Accessibility And Layout
+
+The renderer emits semantic landmarks:
+
+- `banner`
+- `navigation`
+- `main`
+
+Sections are linked from navigation, action controls expose `aria-label`, and
+mobile/desktop layout metadata is available through the screen model. Mobile
+screens use one column with a 44px minimum touch target; desktop screens use a
+two-column workbench layout.
+
+## Current Limits
+
+- This slice does not ship a web server, JavaScript client, or CSS bundle.
+- Browser persistence is not authoritative over domain state.
+- The HTML renderer is a verification artifact and adapter starting point, not
+  a final branded application.
+- Credential entry, password reset, passkeys, MFA challenges, token issuance,
+  notifications, and service-specific consoles remain outside user-engine.