portal-mojo 0.2.20 → 0.2.22

package/docs/README.md

@@ -14,11 +14,17 @@ everything: run the showcase (`npm run dev:showcase`) → **Develop → Componen
 | [realtime.md](realtime.md) | Auth-challenged WebSocket lifecycle, heartbeat/backoff, refcounted topics, typed event projection, deterministic mock |
 | [auth-pages.md](auth-pages.md) | The in-app auth pages: routes + guard, `VITE_MOJO_AUTH` switch, fresh-auth (440 step-up) modal, MFA panel, password tools |
 | [admin-credentials.md](admin-credentials.md) | Group API keys and webhook subscriptions — dual-mount pages, lossless per-endpoint rate limits, permission registry, secret-safe create/reveal/rotation |
+| [admin-presentation.md](admin-presentation.md) | KISS presentation rules, shared styles and required rendered visual QA |
 | [admin-dashboard.md](admin-dashboard.md) | Package-owned global Admin landing, authoritative signals, independent gates, caller-isolated caches, and root fallback |
 | [admin-cloudwatch.md](admin-cloudwatch.md) | Global EC2/RDS/Redis CloudWatch charts, exact resource/fetch wires, constrained controls, refresh ownership, and modal details |
 | [admin-monitoring.md](admin-monitoring.md) | Monitoring Admin registration, logs, and exact Redis-backed metrics-permission mutations |
 | [admin-metrics-explorer.md](admin-metrics-explorer.md) | Read-only recorded-metrics discovery, full-slug adapters, KPI/fan-out/scalar contracts, and cache identity |
 | [admin-settings.md](admin-settings.md) | Runtime settings admin — direction-aware atomic writes, write-only secrets, and global/group scope |
+| [admin-deployments.md](admin-deployments.md) | API serving/attempt evidence, WebApp release recovery, durable onboarding, transient CI keys and real uploads |
+| [admin-dns-domains.md](admin-dns-domains.md) | Simple domain inventory, exact-name registration/adoption/purchase, focused registrar settings and DNS links |
+| [admin-maintenance.md](admin-maintenance.md) | Independent AWS upgrade scans and framework policy, exact confirmation, observation and uncertain operation guards |
+| [admin-geolocation.md](admin-geolocation.md) | Owner-only GeoIP provider setup, ordered fallbacks, transient credential verification and publishing |
+| [admin-operational-fleet.md](admin-operational-fleet.md) | Operational health matrix, exact backend grants, reviewed stored capacity plans and bounded batch observation |
 | [admin-fleet-configuration.md](admin-fleet-configuration.md) | Superuser structured configuration publishing, version restore and per-node application evidence |
 | [admin-bouncer.md](admin-bouncer.md) | Bouncer decisions, device investigations, and bot-signature administration with token-safe caching |
 | [admin-security-tickets.md](admin-security-tickets.md) | Ticket queue, KISS detail modal, notes, approvals, and Maestro sync contract |
@@ -36,7 +42,7 @@ everything: run the showcase (`npm run dev:showcase`) → **Develop → Componen
 | [admin-dns-registrar.md](admin-dns-registrar.md) | Domain search/quote/purchase, one-use token custody, durable-ledger reconciliation, scoped registrant PII, and manual House adoption |
 | [admin-storage.md](admin-storage.md) | Global S3 buckets, masked storage backends, explicit policy-backed File uploads, capability-safe FileView/shares, and finite rendition convergence |
 | [admin-media-rendering.md](admin-media-rendering.md) | Storage → Media rendering: the three FILEMAN_RENDITIONS_* settings as a descriptor-driven form — delta-from-defaults writes, inline 400 routing, reset by writing `{}` |
-| [admin-edge.md](admin-edge.md) | Edge vhosts by template kind with a shape-first wizard, `site_api` routes and their create order, declared upstreams, and the fleet blocklist with log-first modes. |
+| [admin-edge.md](admin-edge.md) | Serving hostname configuration with Address → Routing → Certificate → Review creation, independently admitted node posture and bounded hosting readiness, `site_api` routes and their create order, declared upstreams, and the fleet blocklist with log-first modes. |
 | [admin-shortlinks.md](admin-shortlinks.md) | Global shortlink operations, destination-free caches, bounded click history, and reconciled one-shot mutations |
 | [admin-messaging.md](admin-messaging.md) | SES domains/mailboxes/sent/templates plus public contact requests, with write-only credentials and offline HTML previews |
 | [admin-phonehub.md](admin-phonehub.md) | Global Phone Hub: evidence-backed lookup, sanitized SMS audits, and write-only provider configuration |

package/docs/admin-assistant.md

@@ -15,24 +15,44 @@ Assistant permissions and member/group grants cannot satisfy it. The server
 also rejects confined ApiKey/GroupScopedToken sessions and enforces person
 ownership; the client does not invent a broader per-user-key ban.
 
-The basic section shows deployment readiness, exact provider/model/key
-selection, Automatic — latest Sonnet or an explicit manual pin, credential source and optional server hint, blank replacement input,
-Check and save key, Check current key and enable/disable. A configured key and
-an enabled switch do not prove readiness. `route.ready` describes configuration,
-not current provider health. Unknown routes remain unknown: a missing
-credential can cause the backend to omit the entire route. Only an explicit
-`handler` route points to the Platform credential section. Bedrock uses AWS
-identity from deployment. Assistant, Platform and AWS credentials never
-substitute for one another. Missing Assistant/realtime applications are also
-reported. Runtime model identifiers preserve provider punctuation, including
-Bedrock colons; only a manual pin uses the backend's restricted pin syntax.
-
-Advanced native details separate Platform credentials, deployed policy/safety,
-remote access/connections and incident triage. Policy activation acknowledges
-the deployed policy on this node, does not edit it and never establishes
-fleet-wide agreement. Static, database and effective emergency stops are
-separate; only the database switch is writable. Activation and breaker reset
-cannot release a stop.
+The page separates **AI Assistant** from **MCP connections** with two task
+tabs. AI Assistant is the built-in provider-backed chat and incident processing;
+MCP serves tools to external agents that bring their own AI. MCP does not
+require an Assistant provider key, model selection, policy acknowledgement or
+enabled chat switch. The MCP tab shows its address, independent access switch,
+public discovery check and connections directly; AI readiness warnings remain
+in the AI tab. Ordinary reads probe neither provider nor public discovery.
+
+The AI tab starts with a compact status overview: the enabled switch, current
+provider/model and selected connection, followed by Safety & usage and Incident
+triage. Configure model and Manage keys open focused native dialogs. The API
+keys dialog separates Assistant and Platform keys with two task tabs; Safety &
+usage separates Policy & stops from Usage & recovery. Incident triage is a
+direct dialog. Keyboard-accessible info icons hold catalogue metadata,
+credential explanations, policy/admission diagnostics, connection dates and
+the triage watermark. Errors, failed checks, emergency stops and operation
+consequences stay visible beside their actions. No expandable sections or
+single-item side navigation are used.
+
+A configured key and enabled switch do not prove readiness. `route.ready`
+describes configuration, not current provider health. Unknown routes remain
+unknown: a missing credential can cause the backend to omit the entire route.
+A handler route opens Manage keys on Platform key. Bedrock uses deployment AWS
+identity; the key dialog explains that browser keys cannot configure it.
+Assistant, Platform and AWS credentials never substitute for one another.
+Missing Assistant/realtime applications are reported. Runtime model identifiers
+preserve provider punctuation, including Bedrock colons; only a manual pin uses
+the backend's restricted pin syntax.
+
+Policy activation acknowledges the deployed policy on this node, does not edit
+it and never establishes fleet-wide agreement. Static, database and effective
+emergency stops are separate; only the database switch is writable. Activation
+and breaker reset cannot release a stop. Destructive and consequential actions
+use a nested confirmation, initially focused on Cancel. During an operation,
+repeat submission, task tabs and native Escape/backdrop/close are locked. Cancel
+returns to the task without making a request. Closing a task or changing key
+types clears unsaved secret drafts; reopening model selection restores the
+saved value. All dialogs unmount with the owner/session boundary.
 
 Model selection controls the protected runtime selection only when the backend
 returns a valid capability for the explicit Anthropic `auto:sonnet` policy.
@@ -42,8 +62,7 @@ unavailable until deployment removes that pin. Mode is authoritative even when
 a fixed route retains an inert legacy `selected` value.
 
 The exact resolved runtime identifier (`model.effective`) and source are
-separate from the selection draft and `route.ready`. Advanced → Deployed policy
-and safety contains the raw policy model and admission diagnostic. The additive
+separate from the selection draft and `route.ready`. Safety & usage → Policy & stops → the Deployed policy info icon contains the raw policy model and admission diagnostic. The additive
 `route.can_invoke` reports admission to the guarded request path: a cold
 automatic catalogue can admit a request while configuration readiness remains
 false. It does not prove that a usable model or healthy provider is ready.
@@ -78,7 +97,7 @@ changes conservatively discard it: the shared auth API cannot distinguish
 renewal from same-person replacement across tabs. A 440 uses the existing
 fresh-auth UI after clearing credential drafts; even successful reauthentication
 requires explicit re-entry/retry. No secret is silently replayed. Confirmation
-is page-local, focuses Cancel, and ends with the page/session scope.
+is a page-owned native dialog, focuses Cancel, and ends with the page/session scope.
 
 Protocol helpers are exported from `portal-mojo/admin/assistant`:
 `getAssistantSetup(options, probe?)`, `mutateAssistantSetup(action, options)`,
@@ -153,7 +172,7 @@ fake password `mojo`. No real credentials or deployment changes belong in demos.
 `verify:admin-assistant-setup` covers wire contracts, owner navigation/admission,
 projections and mounted auth/draft/confirmation/fresh-auth/transport/cache
 lifecycle; it is wired into `verify:release`. Browser checks separately establish
-both-theme layout, native details, keyboard controls and console behavior.
+both-theme layout, native dialogs, help popovers, keyboard controls and console behavior.
 
 ## Conversation transport
 
@@ -218,9 +237,42 @@ per-type schemas/caps; unknown/malformed blocks drop. Context references are
 inert and allowlisted. Action choices require confirmation, then their bounded
 value is sent attachment-free through the ordinary REST POST.
 
+## Management pages
+
+Conversations and Skills use a clean searchable list with URL-backed pagination
+and Refresh. Searches target conversation titles or skill names. Record details
+open in compact native dialogs without tabs or a side rail. Conversations label
+messages with their actual owner and compare the viewer separately; foreign
+history shows an explicit viewing-only notice and no composer. Owned history
+retains realtime/REST transport selection, completed attachments and no automatic
+resend after an unknown outcome. New conversations start from the app's Assistant
+button.
+
+Skill details show trigger phrases and readable ordered steps. Tool identifiers,
+dates and secondary explanations use info popovers. Automatic execution remains
+visibly called out: read-only steps can run automatically; changes still require approval. The sole lifecycle action deactivates/reactivates through the
+existing endpoint, then reloads authoritative state; no create/delete UI is added.
+
+The page lifetime is keyed to person, auth-session revision and global permissions.
+Late reads cannot replace newer results. Writes check live authority after auth
+preflight, use synchronous single-flight guards and lock native dismissal while
+pending. Private history/memory stays component-local. The Dashboard is unchanged.
+
 ## Memory
 
-Global and user tiers require the global Assistant grant. Group memory first chooses from a bounded normal `/api/group` request and supplies that id as normal request context (`?group=<id>`). A group id is never put in the memory body and ambient group state is never consulted. Keys are limited to 64 lowercase alphanumeric/colon/underscore/hyphen characters; values are limited to 500 characters.
+Global and user tiers require the global Assistant grant. Group memory first chooses from a searchable normal `/api/group` picker and supplies that id as normal request context (`?group=<id>`). A group id is never put in the memory body and ambient group state is never consulted. Keys start with a lowercase letter or number and are limited to 64 lowercase alphanumeric/colon/underscore/hyphen characters; values are limited to 500 characters.
+
+Memory uses Personal, Global and Group tabs because they select different
+Assistant audiences. Lists show saved values with Edit and Remove actions; Add
+opens a focused Key/Value dialog. Existing keys are immutable, duplicate new keys
+cannot overwrite a saved value, and changing audience/group discards unsaved
+drafts. The searchable group picker replaces the previous first-50 limit. Group
+membership checks remain explicit and inherited; missing/refused checks are
+visible. Members with the global Assistant grant can inspect group memory;
+editing additionally requires inherited member Assistant authority or superuser. Shared edits name their audience, removal names its key and audience and
+initially focuses Cancel. Writes keep errors in the dialog, retain drafts on
+refusal and never replay automatically. Refresh failures are distinct from empty
+memory. Saved entries are not silently truncated to the first 100.
 
 ## Shell ownership
 

package/docs/admin-deployments.md

@@ -0,0 +1,201 @@
+# Deployments
+
+`DeploymentsPage` contributes one global Operations workspace. The Admin section
+singleton belongs to `admin/domains/operations.ts`; its route lazily imports the
+page. `WebAppDetail({id,onClose})` is a focused `modal.open` task dialog.
+Import these through `portal-mojo/admin/operations` after central registration.
+The domain's owned stylesheet is `styles/components/admin-deployments.css`.
+
+API and WebApp lanes are independently admitted. API sections require exact global
+`view_platform|manage_platform|admin`; `view_platform_security` alone never fetches
+deployments. WebApps require exact global `view_dns|manage_dns|security` in this
+Admin workspace. The finite Fleet `backendGlobalCan` helper reproduces backend
+category expansion; the frontend's broader admin wildcard does not admit reads.
+Inactive lanes and denied identities mount no domain query. No active group is
+inherited. Explicit owning-group action scope is separate from page scope.
+
+API uses `GET /api/account/admin/platform?sections=deployments,api`. The last
+converged serving SHA and its observation date remain separate from the latest
+attempt. Server node summary distinguishes restart proof, reported success,
+dispatched and failed nodes. Durable diagnosis is separate from replaceable node
+observations. Unknown and stale states remain visible. Recovery supports retry
+same SHA, verify and converge according to the exact attempt status matrix; each
+confirmation refreshes the attempt first. Retry sends a stable bounded
+`Idempotency-Key`, then watches its returned attempt ID. There is no arbitrary SHA
+input, API rollback, framework update or pin editor.
+
+WebApp summary lists are bounded to 50 with honest truncation disclosure. Full
+summary, default graph ownership, registered release history and deployment
+attempt history are separate reads. The default graph is positively projected:
+no bucket, prefix, key, unrelated group data or raw metadata reaches Query.
+Full summary's latest attempt has no release identity; the detail resolves its
+exact app/attempt-filtered generic history record before naming the version.
+Generic attempt graphs omit the parent, so the request binds both `webapp` and
+`id`, asks for one row, and validates the returned attempt and release IDs.
+Ordinary viewers are never sent to the stronger rollout-status endpoint: it
+requires WebApp SAVE authority. Admitted operators can inspect node evidence
+through that endpoint. Selected active attempts use bounded, owner-fenced
+observation; terminal outcomes invalidate the owning summary and history.
+The current release pointer is desired content, never proof of fleet convergence.
+HTTPS health and active certificates are independent observations.
+
+Rollback requires `manage_webapp` plus the owning object's SAVE authority (`manage_dns|security`).
+Current-user membership may be resolved only for that known app's owning group;
+global grants bypass unnecessary membership reads. Bootstrap eligible groups do
+not grant or narrow existing-app custom actions. Manual release registration has
+its own exact object SAVE predicate (`manage_dns|security`); read-only `view_dns` does not grant release registration; workflow generation requires security or
+both WebApp and DNS management. A 403 removes app mutation controls for that
+session. The backend remains authoritative for all object, actor, origin,
+interactive and freshness rules.
+
+Release and deployment history have separate paged views. Eligible release rows
+open a preselected rollback; the focused chooser also pages beyond the first 25.
+Rollback selects a concrete noncurrent release in `uploaded|live|superseded`,
+requires typed `app/version`, refreshes ownership/current pointer and the exact app/target-filtered release, then
+sends `{webapp,release,group}`. It watches the exact returned deployment through
+`/api/edge/release/deployment/ID`, validating deployment/app/release identities.
+Only `live` is success. `rolled_back` means the attempted version was unsuccessful;
+a failed rollout can leave mixed nodes. An uncertain rollback is not replayed on
+remount. Its safe receipt blocks conflicting app mutations while it is unsettled.
+
+Before creation, App and Build options share one retained draft. After creation,
+only the current server task appears beside noninteractive App → Address →
+Repository → HTTPS progress; operation/revision/activity live in Setup details.
+Closing preserves setup; cancelling server setup requires explicit confirmation.
+New WebApp uses separately admitted bootstrap eligibility and server onboarding
+options/precheck. Missing destination or allowed bucket blocks creation with a concrete prerequisite. Existing workspaces precheck their concrete address before create. New-workspace intent deliberately has no domain before create and does not require an invented ready verdict. Defaults are production, main,
+dist and the first allowed bucket. The durable server operation owns cursor,
+revision, status, activity and resources. Choose/cancel use its latest observation;
+a revision/lease refusal requires another detail read, never repeated POST.
+Unknown cursors and parked waiting states stop automatic reads. Optional GitHub
+verification preserves `unavailable` versus explicit attestation. Closing does not
+cancel server work. A matching actor/origin safe receipt resumes by operation UUID;
+an app without such a receipt shows unfinished diagnostics without creating a
+replacement resource. An uncertain create can be deliberately retried only with
+its immutable profile and UUID after an exact 404 observation.
+
+Deploy opens its GitHub, Upload and Other CI methods directly. Workflow and
+Other CI instructions use focused dialogs. Linked-key controls follow observed
+state: create when unlinked; rotate when linked; revoke only an active key. Both
+CI methods expose these controls. Deploy setup lazy-loads key/upload surfaces.
+Generated YAML stays outside
+Query and references one repository secret named `MOJO_DEPLOY_KEY`. Copy/download
+instructions leave installation to the operator. Keys are revealed in one focused
+transient dialog, cleared on close, authority/session replacement or unmount.
+Receipt replay with `token:null` says the secret is unavailable and requires an
+explicit new rotation. Rotate/revoke explain CI impact; existing content remains
+independent. Revoke's backend freshness window is 300 seconds; other sensitive
+custom actions use 600. A 440 prompts through `requestFreshAuth` but never replays
+the POST; refresh and renewed explicit consent are required.
+
+Built artifact upload is register → anonymous checksum-bound PUT → complete →
+exact deployment observation. Files are normalized relative paths, reject
+traversal/collisions, and are hashed with SHA-256 before registration. Defaults
+are 5000 files and 1 GiB; backend limits may be lower. Signed destinations and File
+objects stay transient. Each PUT uses only the returned exact checksum header,
+raw bytes, `credentials:omit`, `redirect:error` and no API bearer. A failed/CORS
+PUT stops completion. Resume requires reselecting and hashing an identical
+manifest before registration remints URLs; a verified release with no uploads is
+handled. Saved receipts contain only actor/origin, finite IDs, immutable safe
+profile/address or normalized manifest, never key material or signed URLs.
+
+`useDeploymentObservation` reads only known identities, stops on terminal,
+parked/unknown cursor, failure, owner disposal or a bounded deadline, and skips
+hidden or blurred documents. Refresh/Resume resets the read budget without
+creating a new server operation. Native Escape/backdrop dismissal and repeated
+submission are locked during HTTP writes. Observations can stop after close;
+submitted server work persists and is reconciled from safe receipts.
+
+Mock integration uses `deploymentsMock(path,opts,{user,keyBacked,authTime,group?,
+interactive?})`, returning `undefined` for unrelated paths. The central bootstrap
+composer consumes `readDeploymentBootstrapFacts(caller)` and merges only its
+explicit WebApp fields. `deploymentMockStorageFetch` is an explicit mock-only
+secondary PUT simulator; real deployments use browser fetch. Scenario controls
+and `AdminDeploymentsDemo` exercise authority splits, current-A/failed-B,
+reported/partial/unknown/stale evidence, same-SHA retry, rolled-back/mixed WebApps,
+setup prerequisites, cursor/lease refusal, uncertain create, key replay, upload
+failure and bounded observation. Fixtures establish UI contracts, not live rollout.
+
+The supported profile editor writes only `display_name`, `environment`,
+`github_repository`, `deployment_ref` and `build_output` through the existing
+WebApp model save. It requires exact SAVE authority independently of
+`manage_webapp`; owner, bucket, release pointer, slug and credential fields are
+not editable here. The API wire field is `github_repository`, while the display
+DTO calls it `repository`. Save re-reads ownership and all baseline values,
+refuses observed drift, then reads back the saved profile. This is a client
+stale-value check, not an atomic server revision condition. Profile changes do
+not deploy content or update a workflow already installed in GitHub.
+
+A lost profile-save response retains its submitted receipt and blocks another
+save. Reload shows current values but does not prove the earlier writer finished.
+Only after that read may an operator explicitly acknowledge the unknown prior
+writer with the app-specific phrase. Acknowledgment sends no POST; a new change
+and fresh preflight are still required. A late observed commit refuses the next
+save. Known profile 440 refusal settles its unsent receipt and never replays the
+POST. No profile patch or secret is retained in the receipt.
+
+Run `node scripts/verify-admin-deployments.mjs` and
+`node scripts/verify-admin-deployments-mounted.mjs`, then repository typecheck.
+The first covers positive projection, authority/status/receipt/wire contracts and
+actual client idempotency headers in both transports. Mounted StrictMode tests
+hold responses to exercise single-flight, unsettled rollback remounts, owner
+replacement, fresh auth without replay, one-time key replay, denied no-request
+lanes, safe operation resume, terminal/parked/error/timeout and observer disposal.
+The additional `verify:admin-deployments-setup-mounted` and
+`verify:admin-webapp-inspection-mounted` commands cover state-aware setup,
+later-page target preflight, ordinary CI viewers/observation, scoped refresh and
+profile stale/unknown/fresh-auth journeys. The integration owner runs the
+reviewed modal inventories and actual
+light/dark, narrow and native-dialog browser verification.
+
+
+New workspace continuation uses the exact `operation.group.id` returned by durable
+create. That group identity is saved separately from the immutable create profile;
+resuming never rewrites `group_intent:new` into another create body. The address
+cursor reads options for that concrete group and explicitly links to the host's
+registered Domains destination when configured and independently admitted. A new
+workspace starts without an own/ancestor domain; configure or connect one for the
+named group, refresh options, then precheck the address and submit the returned
+`domain`/normalized `label` with the latest operation revision. Continue stays
+unavailable with a concrete prerequisite until an actual address choice exists.
+The frontend never borrows an installation-wide or unrelated workspace domain.
+
+A WebApp deployment marked `superseded` with `terminal:true` stops observation and
+settles its receipt, with `success:false`. It is not a successful rollout.
+
+Upload receipts durably record `completion_submitted`, the completion timestamp,
+and bounded prior deployment IDs before sending completion. Completion is a new
+promotion request: after an earlier failed, rolled-back or superseded attempt,
+repeating it can create another deployment. A lost response therefore blocks
+implicit registration/completion even after remount or same-manifest reselection.
+Reconcile reads the owning app summary/history and validates exact app, release,
+version and newly observed deployment identity before observing terminal outcome.
+Ambiguity remains unknown. Only a separately typed, freshly rechecked new deployment
+consent permits resetting the local upload phase; that consent sends no POST and
+requires a subsequent deliberate reselect/upload/deploy action. It neither erases
+an earlier attempt nor silently replays it. The mock follows the backend's narrow
+reuse rule: current release plus an active/live attempt, not permanent reuse for
+every release ID.
+
+
+Owner lifetimes survive React development StrictMode's setup/cleanup/setup replay.
+Query closures keep a stable identity/scope handle whose live signal is renewed
+before read effects resume; they do not retain an aborted first-render controller.
+Actual unmount, actor/session replacement and authority or active-state changes
+abort the old lifetime and discard late results. The mounted harness places
+StrictMode above the providers/router so React 19 actually replays initial effects,
+and verifies cold authorized bootstrap/platform reads through an asynchronous
+transport gate as well as real owner cancellation.
+
+### KISS presentation
+
+API and WebApps are distinct tasks; hosts admitting only one lane show no tab
+strip. Creation appears only in WebApps. The API lane shows last convergence and
+attempts, keeps unavailable/stale evidence visible, and puts secondary collector
+facts behind an info icon. API inspection separates Overview, Nodes and Activity
+and offers recovery only on the latest applicable attempt. WebApp inspection
+separates Overview, Deployments, Releases, Deploy and Settings; wholly read-only
+viewers omit Deploy. Useful node evidence adds tabs to an attempt dialog only
+when there is more than one content area. No single-item side rail or long
+collapsible section is introduced. Admin Dashboard stays unchanged. See
+[visual QA](admin-presentation.md).

package/docs/admin-dns-certificates.md

@@ -123,8 +123,8 @@ without separate operator authorization.
 
 ## Shared validation setup
 
-Use **Domains → Shared validation setup**, or **Set up shared validation** in a
-group-managed Domain or Certificate header menu. Domain **Validation** and
+Use **Domains → Advanced → Shared validation setup**, or **Set up shared validation** in a
+group-managed Domain or Certificate header menu. Domain **Advanced validation** and
 Certificate **Delegation** show the same read-only facts. No new route or sidebar
 resource is added. The flow never reads certificate material.
 
@@ -143,7 +143,7 @@ resource is added. The flow never reads certificate material.
    stays available after copy/share denial or cancellation. The canonical file is
    at most 2048 UTF-8 bytes and has exactly `version:1`, `consumer_project_uuid`,
    `client_ref`, `domain`, `allocation_ref`, with no wrapper, key, token or scope.
-5. The controller opens their deployment’s **Domains → Shared validation setup →
+5. The controller opens their deployment’s **Domains → Advanced → Shared validation setup →
    Controller review**, checks access and uses **Import request**. There is no JSON
    editor or controller URL. Empty, oversized, malformed, noncanonical or extra-field
    files are refused before installation. Import alone grants nothing. The named

package/docs/admin-dns-domains.md

@@ -0,0 +1,98 @@
+# Domains
+
+Import `DomainsPage` from `portal-mojo/admin/infrastructure`. The global DNS
+inventory lives at the host's `/dns/domains` mount. Server search, filters,
+sort and paging stay on `DomainModel` with `admin:dns:domains` persistence.
+Scope comes from each row, never the active product group. An absent expiry
+means **Unknown**, not Never. Narrow layouts combine provider, scope and status
+under the name so the Records action stays visible.
+
+## Everyday tasks
+
+**Add domain** opens three explicit choices: **Connect GoDaddy domain**,
+**Buy domain**, and literal-superuser **Adopt Route 53 zone**. Purchasing has its
+own read-only ledger shortcut. **More domain actions → Shared validation setup**
+keeps external-domain/controller setup available without an existing domain.
+Viewers get inspection and Purchases; writes require global
+`sys.manage_dns | sys.security`. Platform adoption/assignment additionally require
+literal interactive `is_superuser`; backend gates remain authoritative.
+
+A row opens a compact native dialog with Overview, provider-applicable DNS
+records, Certificates, and manager Registration. It has no side rail or nested
+registration disclosure. Only the selected task mounts. The same record panel
+serves the standalone Records page; its type filter is controlled by that page's
+URL or locally when embedded. Serving is an explicit sibling route under the
+observed Admin mount. Extra registered domain links retain their own gates.
+
+## Connect, repair and adopt
+
+Connect selects one explicit authorized group through bounded
+`/api/dnsman/credential/group-choice`, then an active, verified GoDaddy
+credential in that exact group. Changing group clears credential state and
+fences late replies. **Link credential** opens the existing write-only credential
+editor locked to that group; a verified return resumes the same domain draft.
+There is no generic group list, free-form group id or provider-account discovery.
+The ownership probe sends exactly `{ group, domain, credential }` and spends no
+money. Domain names are normalized before submission.
+
+An existing GoDaddy domain with an unusable linked credential offers **Repair
+linked credential**. Rotation verifies the same credential/group, clears raw
+password refs, then refreshes safe credential and domain projections. This does
+not expose an arbitrary credential-FK reassignment: the backend has no same-group
+validation for that generic save. A domain with no linked credential cannot be
+silently attached to a newly linked one.
+
+Adoption reviews one exact existing public zone name and Platform scope before
+posting `{ domain }`. It never supplies `group`/`create_zone` or discovers the AWS
+account. Native dismissal is guarded during review and mutation. Cancel review
+writes nothing. Unknown onboarding outcomes require inventory/provider review;
+submitted forms never repeat their request.
+
+A Platform domain offers **Assign to group** to literal superusers. Choose the
+destination, review domain/from/to, and type the exact destination name. The UI
+checks current authority, current domain ownership and the exact authorized group
+again before `{ domain, group }`. Already-grouped rows never offer reassignment.
+A lost receipt retains **Refresh owner** and refuses replay, even if the fresh
+read still says Platform; a read cannot prove an older write has finished.
+
+All onboarding writes check their owner at the transport's `beforeSend` boundary,
+after any asynchronous auth refresh. Credential/purchase step-up continuations
+perform that same check. A replacement session never inherits old consent.
+
+## Registration
+
+Registration starts with an explicit manager-only **Read registration**. WHOIS
+contacts stay in the mounted dialog, outside Query, URLs, storage and logs.
+Route 53 DNS hosting alone never admits registrar edits: the returned registrar
+must identify Amazon Registrar/Route 53. Hosted-zone-only, unavailable or unknown
+registrations remain read-only. GoDaddy registration tasks hand off to its account;
+Mojo remains certificate-only. No manual Renew action is invented.
+
+Confirmed Route 53 registration offers focused settings and contacts dialogs.
+Auto-renew uses the existing best-effort boolean save; privacy uses its dedicated
+all-contact action. Fresh owner/registrar/value preflight precedes writes. Only
+live WHOIS readback can establish observed values; an accepted DB save is not
+provider proof. Unknown outcomes lock the submitted editor and never replay.
+An unchanged desired DB value may not re-run a failed model hook; the registrar
+account handoff remains available.
+
+Contact inspection groups identity, email/phone and postal address. Identical
+Registrant/Admin/Technical contacts share one view; differing contacts get useful
+role tabs. Editing keeps one draft across Contact/Address tabs. **Replace all
+contacts** explicitly replaces all three roles, matching the backend contract.
+Entering edit mode never submits. Registry extension fields are preserved locally.
+Pending operations guard tab switches, native dismissal and repeated writes.
+
+## Purchase and QA
+
+Buying is restricted to one quoted year until the backend binds multi-year
+payable totals. Privacy limits and acknowledged downgrades stay visible.
+See [registrar flows](admin-dns-registrar.md) for exact confirmation and recovery.
+
+`verify:admin-domains` includes delayed-auth transport fences.
+`verify:admin-domains-mounted` runs onboarding, assignment/filter/credential,
+registration and purchase/contact journey contracts, including StrictMode and
+stale-session/scope cases. JSDOM establishes behavior only. Closing acceptance
+uses actual Portal and built Showcase screenshots and interactions in light/dark,
+desktop and 390px; see [visual QA](admin-presentation.md). No live registrar
+purchase or infrastructure mutation is required for this mock acceptance.

package/docs/admin-dns-records.md

@@ -14,7 +14,7 @@ import {
 
 The one canonical DNS section is `id: "dns"`, `basePath: "dns"`, in Infrastructure. Its routes are ordered `domains`, `records`, `certificates`, `purchases`, `registrant`, `credentials`. The read surfaces accept the global, system-pinned any-of view clause `sys.view_dns | sys.manage_dns | sys.security`; registrant and record mutation controls use `sys.manage_dns | sys.security`. Group/member grants never open Admin.
 
-Domains uses the server-backed `DomainModel` list and `modal.detail`. Detail composes Overview, DNS Records, and the bounded Certificates section; Records is the same `DnsRecordsPanel` used by the standalone page. That page owns only `domain` and `record_type` in the URL. It may select the first active domain only when `domain` is absent. Invalid, denied, missing, and inactive deep links are preserved and shown as errors.
+Domains uses the server-backed `DomainModel` list and compact native task dialog. Detail composes Overview, applicable DNS records, bounded Certificates and manager Registration; Records is the same `DnsRecordsPanel` used by the standalone page. That page owns only `domain` and `record_type` in the URL. An embedded panel owns a local type filter when no controlled value is supplied. It may select the first active domain only when `domain` is absent. Invalid, denied, missing, and inactive deep links are preserved and shown as errors.
 
 ## Wire contract
 

package/docs/admin-dns-registrar.md

@@ -10,13 +10,28 @@ The wizard asks for one explicit group through bounded `/api/dnsman/credential/g
 
 `POST /registrar/quote` returns `{purchase,name,price,currency,years,token,expires,privacy_supported}`. The raw token lives only in an immutable ref in the mounted wizard. It is never state, URL data, Query/Mutation cache data, mock request history, or durable mock data. The exact tuple binds purchase id, token, group, normalized domain, years, decimal price, currency, and expiry. Any upstream change or expiry clears it.
 
-The operator types the exact normalized domain before the single-flight, nonretry `POST /registrar/purchase`. The token is removed from the ref before the request. Success and every exception reconcile through an imperative `GET /purchase/<id>?graph=default`; one non-overlapping bounded-backoff loop follows `submitted` to a durable terminal row. Timeout hands the operator to the ledger.
-
-After purchase is attempted, the wizard cannot retry or requote. A failed, ambiguous, or timed-out result always says that money may have moved and directs the operator to the AWS Route 53 Domains operation console and durable ledger first.
+The portal purchases **one year** only. The backend currently keeps raw TLD
+registration price separately from years, so the UI does not multiply it into an
+allegedly authoritative multi-year payable total. `privacy_supported` is part of
+the retained quote identity; an unsupported registry is explained before consent,
+and an acknowledged `privacy_downgraded` result stays visible.
+
+The operator types the exact normalized domain before the single-flight, nonretry `POST /registrar/purchase`. The token is removed from the ref before the request. Success and every exception reconcile through an imperative `GET /purchase/<id>?graph=default`; one non-overlapping bounded-backoff loop follows `submitted` to a durable terminal row. Timeout keeps exact **View purchase** and **Refresh** actions available. Each
+refresh reads the retained purchase ID and never submits another purchase. A
+completed receipt opens the acknowledged domain ID when available; the ledger
+graph has no domain FK, so other completed receipts use a mount-relative
+name-filtered inventory handoff.
+
+After purchase is attempted, the wizard cannot retry or requote. A final
+transport owner check runs after the asynchronous auth gate and before every
+permitted 440 continuation. Session replacement stops that continuation. Only
+the purchase ID/owner survives a same-user revision change, giving an exact-ID
+recovery view; a different user receives none of the previous recovery state. A failed, ambiguous, or timed-out result always says that money may have moved and directs the operator to the AWS Route 53 Domains operation console and durable ledger first.
 
 ## Purchase ledger
 
-`DomainPurchaseModel` lists only `graph=basic`: id, domain, status, price, and currency. Export/download and alternate graphs are rejected. Clicking a row performs an imperative default-graph read into a KISS modal; the detail response and redacted error are modal-local and never Query-cached.
+`DomainPurchaseModel` lists only `graph=basic`: id, domain, status, price, and currency. Export/download and alternate graphs are rejected. Clicking a row performs an imperative default-graph read into a focused modal
+with an exact-ID Refresh action; the detail response and redacted error are modal-local and never Query-cached.
 
 ## Registrant PII
 
@@ -24,6 +39,16 @@ The contact page starts with no scope and no contact. Operators explicitly choos
 
 An inherited group response renders a blank form and only the backend-authored boolean status; inherited values are never disclosed. Normal editable values may seed from that scope's database row or the House settings-file response. `Fax` and opaque `ExtraParams` are preserved only when the original response is a direct database row for the exact same scope. They are never carried across scope, inheritance, or deployment-file override boundaries.
 
+## Scoped purchase contact setup
+
+A missing-contact search offers **Set up contact** without discarding the explicit
+purchasing group or intended name. `RegistrantContactPage` accepts optional
+`initialGroup`, `lockScope`, `onSaved`, `onClose`, and `onBusyChange` for that
+focused native dialog. Reads are explicit manager-only, fenced by scope/session,
+and never Query-cached. Contact/Address tabs keep one draft; save returns to the
+same purchase search and rechecks scoped capabilities. There is no active-group
+fallback. The standalone page retains its explicit scope chooser.
+
 ## House adoption
 
 House adoption is a separate, literal-superuser-only menu option. The operator types one exact existing name and submits `/registrar/adopt` without `group`. The UI never calls `/registrar/discover`, auto-discovers account domains, or silently assigns the adopted asset to a tenant.

package/docs/admin-dns.md

@@ -37,6 +37,8 @@ domain includes registration/hosted-zone presence, safe zone metadata,
 tracking/adoption state, and a reason. `untracked=true` returns only untracked
 rows; discovery and assignment remain interactive-superuser operations.
 
+The everyday inventory and three onboarding actions are documented in [admin-dns-domains.md](admin-dns-domains.md).
+
 The operator registrar workflow is documented in [admin-dns-registrar.md](admin-dns-registrar.md). It does not use discovery: House adoption is manual exact-name only. Purchase tokens remain transient, all post-confirmation outcomes reconcile through the read-only ledger, and contact PII remains imperative/local.
 
 These responses require local call-flow handling and must never enter Query or
@@ -87,9 +89,8 @@ rotation remains write-only and imperative. Built-in credential Delete is absent
 
 ## Shared wildcard validation
 
-The existing Domains header offers **Shared validation setup** to global DNS
-managers even when server setup needs an operator. Domain detail includes
-read-only **Validation**; its header action and Certificate Delegation compose
+Domains offers **More domain actions → Shared validation setup** to global DNS
+managers even when server setup needs an operator. Domain Overview offers the focused **Shared validation** action; Certificate Delegation composes
 the same focused flow. See [the human walkthrough and exact
 contracts](admin-dns-certificates.md#shared-validation-setup).