portal-mojo 0.2.18 → 0.2.20

package/README.md

@@ -145,3 +145,15 @@ The non-negotiables live in the repo root `PLAN.md` ("Architecture rules") and
 boundary; failure is unmissable; controlled inputs only; models are
 definitions + hooks (TanStack Query owns cache); `ReactNode` slots, never
 trusted-HTML strings; both themes from day one.
+
+### Owner-only AI Assistant setup
+
+The Assistant domain includes a dedicated `/assistant/setup` page (also embedded
+under the Admin mount prefix), protected by the additive literal-superuser
+`AdminRoute.requireSuperuser` / `MenuItem.requireSuperuser` gate. It provides
+explicit key check/save and enablement, with separate advanced Platform key,
+deployed policy/safety, remote access and incident triage sections. Setup secrets
+and actions stay page-local and cache-free. Fresh-auth requires key re-entry,
+and deployment owns the runtime route. See [Admin Assistant](docs/admin-assistant.md)
+for exact schema-2 actions, lifecycle guarantees, mock showcase and verification;
+[Admin credentials](docs/admin-credentials.md) documents the shared core gate.

package/docs/README.md

@@ -41,7 +41,7 @@ everything: run the showcase (`npm run dev:showcase`) → **Develop → Componen
 | [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 |
 | [admin-push.md](admin-push.md) | Global Push admin: caller stats, global metrics, strict audits, templates, and cache-free FCM configuration |
-| [admin-assistant.md](admin-assistant.md) | Global Assistant streaming selection/reconciliation, strict projectors/blocks, context reuse, skills, and explicit tiered memory |
+| [admin-assistant.md](admin-assistant.md) | Owner-only AI Assistant Setup, credential/safety/remote controls and global Assistant streaming selection/reconciliation, strict projectors/blocks, context reuse, skills, and explicit tiered memory |
 | [ModelTable.md](ModelTable.md) | The server-driven table: columns, filters, selection/batch, chooser, persist, autoRefresh, expand, groupBy, export, skeleton |
 | [forms.md](forms.md) | The `Field` language, `SchemaForm`, `formModal`, `FormView` inline autosave + showWhen + tabsets |
 | [tabs-and-form-wizard.md](tabs-and-form-wizard.md) | Accessible Tabs variants and shared-state FormWizard, async finish, reset/roster semantics, modal helper |

package/docs/admin-assistant.md

@@ -2,7 +2,158 @@
 
 Import from `portal-mojo/admin`.
 
-`ASSISTANT_ADMIN_SECTION` registers Conversations, Skills, and Memory beneath the Assistant navigation group. Its section clause is global-only ANY-of `sys.view_admin` or `sys.assistant`; Memory narrows its route to `sys.assistant`, matching the backend. Active-group grants never reveal it. `AssistantLauncher` uses the section gate. `AssistantContextLauncher` additionally requires `sys.view_security` or `sys.security` and only accepts `incident.Incident` or `incident.Ticket`.
+`ASSISTANT_ADMIN_SECTION` registers Setup, Conversations, Skills, and Memory beneath the Assistant navigation group. Its section clause is global-only ANY-of `sys.view_admin` or `sys.assistant`; Memory narrows its route to `sys.assistant`, matching the backend. Active-group grants never reveal it. `AssistantLauncher` uses the section gate. `AssistantContextLauncher` additionally requires `sys.view_security` or `sys.security` and only accepts `incident.Incident` or `incident.Ticket`.
+
+## AI Assistant setup
+
+`AssistantSetupPage` is a dedicated global owner page at `/assistant/setup`, or
+`/system/assistant/setup` when the Admin helpers receive `mount: '/system'`.
+The literal `me.is_superuser === true` requirement applies before lazy loading,
+in grouped and ordinary menu entries, landing selection, direct component
+mounting and every action. Permission-driven `admin`, `manage_settings`,
+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.
+
+Model selection controls the protected runtime selection only when the backend
+returns a valid capability for the explicit Anthropic `auto:sonnet` policy.
+Fixed Anthropic policies, Bedrock and unavailable policies remain read-only.
+A deployment pin permits an owner manual override, but Automatic remains
+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
+`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.
+
+Refresh catalogue is an explicit backend request; only the backend contacts the
+provider. The browser never decides which model is newest. A refresh announces
+success only for `model.refresh.ok === true`, including when a manual pin
+remains selected. Failed/throttled/in-flight attempts may retain a fresh or
+stale cached resolution; the page reports its exact freshness, last successful
+fetch and attempt without claiming a newer model. Passive reads neither refresh
+the catalogue nor repeat the preceding explicit refresh outcome.
+
+Check public discovery explicitly probes this installation's public address
+(server cache: 60 seconds). Ordinary page reads trigger neither probe.
+
+Both credential drafts and all setup operations stay imperative and page-local.
+There is no autosave, model definition, Query/Mutation entry, browser
+persistence, export, URL value or secret-bearing mock history. The backend
+checks a replacement before encrypted storage; a candidate-only verification
+never updates the stored-key check record. Successful credential saves and
+clears empty the relevant draft. Clearing protected storage may reveal a
+deployment fallback, so the returned source remains authoritative. Fixed
+backend pre-write rejection/unreachable messages map to safe actionable copy;
+unknown failures refresh authoritative state and report an uncertain outcome
+without replaying the operation.
+
+One operation/confirmation lock, AbortSignal and live owner/session guard cover
+loads, confirmations, auth waits and late responses. Leaving the page,
+revocation, logout or explicit session replacement discards drafts and pending
+work. Ordinary same-tab token renewal preserves a draft. Cross-tab auth-storage
+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.
+
+Protocol helpers are exported from `portal-mojo/admin/assistant`:
+`getAssistantSetup(options, probe?)`, `mutateAssistantSetup(action, options)`,
+`assistantSetupSave(state, changes)`, `projectAssistantSetup`,
+`assistantSetupReadiness`, and `assistantSetupCredentialRefusal`. Options accept
+`signal` and a `beforeSend` validity guard; mutation helpers enforce same-origin
+before and after auth preflight and use the existing `mojoCall` envelope boundary.
+`schema_version: 2` responses are positively projected with bounds of 200
+model choices/connections/request aggregates and 100 breaker rows. Runtime IDs
+preserve provider punctuation; only manual pins use the backend's restricted
+81-character lowercase alphanumeric/dot/hyphen syntax.
+
+The additive wire fields live directly under `model`: `mode` (`auto`, `pinned`,
+`fixed`), `editable`, `policy_model`, `restriction` (empty, `fixed_policy`,
+`provider_unsupported`, `deployment_pin`, `policy_unavailable`), `discovery`
+(`status`: `fresh`, `stale`, `unavailable`, `not_applicable`; nullable ISO
+`fetched_at`, `attempted_at`, `expires_at`, `max_stale_at`; safe `error_code`),
+and `refresh` (`attempted`, nullable boolean `ok`, safe `code`). The client
+positively projects the complete valid set into optional `model.capability`.
+Absent, malformed or unknown capabilities keep runtime facts visible, with
+upgrade/read-only copy and no enabled selection action. No latest ID ships in
+the production UI; returned bounded choices supply the datalist.
+
+| Request | Exact body / query |
+|---|---|
+| Passive GET `/api/account/admin/assistant` | No probe parameters |
+| Explicit catalogue / discovery GET | `refresh=models` / `check=discovery` |
+| Save POST | `{action:'save',enabled:boolean,model?:string}` plus only intended optional `api_key`, `clear_api_key`, `handler_api_key`, `clear_handler_api_key`, `mcp_enabled`, `emergency_stop`, `autonomous_triage` |
+| Model selection POST | Exactly `{action:'set_model_selection',mode:'auto'}` (no `model`) or `{action:'set_model_selection',mode:'pinned',model:ID}`; `saved:boolean` |
+| Verify POST | `{action:'verify',target:'assistant'|'handler',api_key?}`; omitted candidate checks that exact stored credential |
+| Policy POST | Exactly `{action:'activate_policy'}`; `activated:boolean` |
+| Breaker POST | `{action:'reset_breaker',provider?:'anthropic'|'bedrock'}`; `reset:number` |
+| Historical triage POST | Exactly `{action:'historical_triage',before:ISO,limit:1..100}`; `queued:number` |
+| Disconnect POST | Exactly `{action:'revoke_grant',grant_id:positiveInteger}` or `{action:'revoke_all_grants'}`; `revoked:number` |
+
+Every mutation returns fresh `state` plus the action result. Verification may
+return `result.ok:false` in a successful envelope; that remains a failed check.
+Save always sends authoritative `enabled`. With a valid capability it omits
+`model` and cannot reset runtime selection; only the dedicated selection action
+can change it. Capability-absent older schema-2 servers retain the required
+`enabled`/legacy `model` baseline because they write both even when omitted.
+On delegated `auto:sonnet` routes, new servers reject a differing legacy model
+echo, preventing stale clients from reverting the active choice. Fixed policies,
+Bedrock and unavailable-policy routes retain an inert legacy writer; these
+values cannot change their deployed runtime model. Model actions carry no
+enabled/key/stop/MCP/triage fields, and all selection drafts reset from each
+authoritative response. Optional section switches are not
+echoed during unrelated saves, and effective stop is never used as the database
+stop. Replacement and clear are separate operations. The server retains its
+600-second fresh-auth, protected settings, auditing and same-origin checks;
+generic Settings still cannot write the Assistant-owned protected keys.
+
+Remote access off pauses existing grants without revoking them. The connection
+count remains the full server count when rows are capped at 200. Tools, Full API
+and combined grants are labeled separately; Full API carries the signed-in
+user's API authority. Disconnect all spans both resource paths for every user.
+Returned addresses are inert text/read-only select-to-copy inputs. Triage
+activation establishes the no-history watermark; historical processing requires
+an explicit cutoff, bounded limit and confirmation.
+
+The mock-only Assistant showcase adds Setup with explicit fake owner/denied
+permission-admin buttons, a one-shot fresh-auth challenge button, and ready, missing policy/key, handler, Bedrock, static
+stop, rejected key, discovery failure, bounded-grants and deployment-fallback
+scenarios. Model scenarios include manual pins, fixed policy, deployment pin
+(including an owner override), fresh/stale refresh failure, unavailable
+resolution, throttled/in-flight refresh, old-server capability absence and
+malformed capability. `fixture-sonnet-2099-01` and `fixture-sonnet-2099-02` are
+visibly fake future IDs; explicit catalogue refresh advances the fake catalogue,
+preserves manual pins, and returning to Automatic adopts the successor. Seeded `assistant.owner@nativemojo.com` is a literal superuser;
+`assistant.wildcard@nativemojo.com` has permission-driven admin only. Both use
+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.
 
 ## Conversation transport
 

package/docs/admin-credentials.md

@@ -26,6 +26,17 @@ use `basePath: ''`; its labeled routes become visible child links rather than
 claiming `/`. Prefixed sections receive an index redirect to the first route
 the current operator can see.
 
+## Literal-owner routes
+
+`AdminRoute.requireSuperuser?: boolean` is an additive opt-in gate. It requires
+literal `me.is_superuser === true` before a lazy page can load and during
+section/mount landing selection. `adminSectionsMenu` carries it into grouped
+and ordinary `MenuItem.requireSuperuser` entries. Permission-driven admin and
+group grants never satisfy it; existing permission semantics remain unchanged.
+Built-in Assistant Setup uses this gate and additionally checks live ownership
+and session lifetime within the component/actions. Toolkit consumers can opt
+into the same route/menu guard without changing other routes.
+
 ## Group API keys
 
 ```tsx
@@ -195,3 +206,30 @@ See [Admin modal policy](admin-modals.md) for header actions, content-only
 sections, supported lifecycle fields and retained irreversible exceptions.
 Group API keys and webhook subscriptions deactivate/reactivate; their built-in
 Delete controls are removed. Reveal, secret rotation and cache boundaries remain.
+
+## Protected ACME consumer purpose
+
+Literal deployment operators can open **Create ACME consumer key** from the
+existing fixed-Group or cross-Group API-key inventory. This lazy form resolves
+the selected original hub Group through the private shared-validation recipient
+endpoint. It displays the actual active Group name/UUID, the named ACME validation
+consumer purpose and the fixed `dnsman_acme_federation` consequence. A tenant or
+acting user cannot substitute for the original recipient. It has no freeform
+permission or JSON input. The server rechecks Group activity, expected label and
+protected grant at issuance and rejects key-backed sessions.
+
+Issue is separately confirmed, single-flight and session-bound. Its response is
+split before presentation: safe key metadata may be displayed; the transient
+token stays outside Query/Mutation caches, URL/history and storage. Closing the
+native token dialog drops that display. The existing explicit, audited
+`/api/group/apikey/<id>?graph=token` reveal remains the recovery route. A timeout
+may follow successful issuance: inspect the exact Group's recent inventory and
+use audited reveal before creating another successor. The form blocks automatic
+reissue and never retries after fresh authentication.
+
+Create a replacement, enter it normally in the receiving deployment's protected
+connection form, Preview/Publish, Apply and verify every expected node. Only then
+explicitly review/deactivate the old hub key using existing key controls. This
+form neither rotates nor retires keys, grants allocation trust, activates hub
+sharing or asserts cross-deployment verification. Existing in-place key rotation
+semantics remain unchanged and can invalidate the previous token immediately.

package/docs/admin-dns-certificates.md

@@ -120,3 +120,163 @@ npm run verify:admin-dns-records
 
 Live verification is read-only. Do not request or revoke a real certificate
 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
+Certificate **Delegation** show the same read-only facts. No new route or sidebar
+resource is added. The flow never reads certificate material.
+
+1. Select an authorized existing local Domain, or an eligible group and exact
+   apex name. Group selection uses `/api/dnsman/delegation/group-choice`, bounded
+   `search/start/size` and explicit `?id=` hydration. Product active-group context
+   and credential group choices do not authorize shared setup.
+2. Enter the existing public allocation target supplied by its controller and
+   **Inspect plan**. Inspection creates no connection or reference.
+3. **Prepare connection** and confirm the displayed domain/profile/target.
+   Preparation pauses direct local validation and renewal until authorization
+   and checking finish. Existing valid certificate material remains available.
+4. **Download request** saves `shared-validation-request.json`. Send it to the
+   allocation controller using your normal coordination channel. **Share request**
+   uses native file sharing when supported; **Copy request** is optional. Download
+   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 →
+   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
+   public fields fill the exact domain query; **Find allocations**, page if needed
+   and select the exact existing target. Only a matching request and resolved active
+   exact recipient enable **Review grant**, then **Allow issuance** after consent
+   names both apex and wildcard authority. No allocation is created.
+6. Back in the project, **Refresh**, **Connect approved validation**, then
+   **Check validation**. These are separate deliberate actions. Check requires
+   the approved existing one-hop `_acme-challenge.<apex>` CNAME.
+7. **Request wildcard certificate** issues this deployment's own apex-plus-
+   wildcard certificate. Existing valid exact-profile certificates remain in
+   place; queued work stays queued and due renewal reuses its lineage. Watch
+   the local certificate and separate renewal status, or Refresh after timeout.
+
+Only global DNS managers (`sys.manage_dns | sys.security`) see local mutation
+controls, and every action also requires the backend's current per-target flag.
+Controller operations additionally require v2 `shared_validation` and
+`can_manage_trust`, then exact-allocation authority. A human controller can have
+`can_consume:false`; local project setup uses the server-held project identity
+independently. Ordinary DNS managers cannot grant themselves trust. Groupless
+house domains are read-only and ineligible in this rollout; direct operation
+remains available and Portal never assigns a group automatically.
+
+### Local API and safe state
+
+| Method | Local route under `/api/dnsman` | Input |
+|---|---|---|
+| GET | `delegation/plan` | `{domain}` or `{group,name}`, optional `allocation_ref` |
+| POST | `delegation/connect` | Same target plus `allocation_ref`, optional explicit `restart:true` |
+| POST | `delegation/check` | `{delegation:<local id>}` |
+| POST | `delegation/request` | `{delegation:<local id>}`; no custom SANs, force or keys |
+| GET | `delegation/group-choice` | `id` or bounded `search/start/size` |
+
+All setup actions return Readiness v1. Portal strictly projects only public
+metadata and validates version, selected identity, source/target, fixed profile,
+booleans and enums. Expected 409s can include the same safe readiness DTO.
+Unknown containers and provider error text are discarded before state. Plans,
+descriptors and controller identities are modal-local; no draft is persisted or
+written to URLs, diagnostics or logs. Writes are imperative and non-retrying,
+freeze the scope, recheck auth/session/permission before send, and reject late
+responses after scope loss. After every attempted write, safe Domain,
+Certificate and legacy delegation caches are invalidated and plan/trust is
+refreshed. Ambiguous results require successful Refresh before another write.
+A 440 prompts authentication but never automatically repeats the operation.
+Every explicit session replacement, including the same user signing in again,
+clears controller capabilities, recipients and participant facts. Check controller
+access and select an authorized allocation again. A new grant also requires a matching imported request and freshly resolved active recipient.
+Closing a view cannot cancel a write already submitted.
+
+Controller POSTs use only the local `/api/dnsman/acme` endpoints:
+`capabilities {}`, `allocation/list {domain,cursor?}`,
+`trust/list {allocation_ref,cursor?}`,
+`trust/recipient {allocation_ref,consumer_project_uuid}`,
+`trust/grant {connection_request}` and
+`trust/revoke {allocation_ref,participant_ref}`. Each page contains at most 20
+rows. Only a capability-approved controller probes the allocation/trust routes;
+there is no arbitrary project directory, remote hub call, key provisioning or
+consumer/status call from a human JWT. Recipient and allocation authorization
+are repeated server-side on every operation.
+
+### Operator setup and mixed versions
+
+If the local plan says the hub is unconfigured or misconfigured, a deployment
+operator uses the existing server configuration delivery to set
+`DNSMAN_ACME_HUB_URL` to the already-used Maestro hub and
+`DNSMAN_ACME_HUB_API_KEY` to the already-provisioned protected project key in
+Django settings, normally `VAR_ROOT/django.conf`. Upgrade the hub first, then
+project API and every certificate worker; drain/restart old issuance workers
+before shared connections are accepted. Restart application and worker
+processes and **Refresh Portal**. A responsive API does not prove that workers
+were restarted; worker version is unknown unless authoritative telemetry exists.
+These settings are static deployment configuration, never DB Setting overrides,
+browser fields, arbitrary per-site URLs or values copied into descriptors.
+
+404/405 and unsupported new versions disable only shared setup; existing strict
+DNS config, direct-provider and legacy single-consumer certificate paths retain
+their contracts. 401/403 report access refusal instead of suggesting an upgrade.
+Disabled sharing, unconfigured/auth-rejected/unavailable hubs and unknown proof
+never display setup as complete. Portal does not bypass backend activation.
+
+### Repair and revocation
+
+ACME validation and traffic routing are separate. The validation CNAME does not
+route apex/www/API/app traffic. Follow the deployment's separate A/AAAA/CNAME
+traffic instructions. Missing, changed or chained validation proof shows the
+expected and bounded observed target and its check time. Ask the domain owner
+to restore the approved one-hop route after checking other consumers. Portal
+does not replace/remove that CNAME or rotate the allocation as a default repair.
+
+Controller maintenance starts cold with **Check controller access**, an **Exact
+ domain** and **Find allocations**. Native choices show target and owner UUID.
+**Next allocation page** / **First allocation page** and **Next project page** /
+**First project page** navigate bounded 20-row pages. Select an allocation to
+inspect participants, role, state, exact scope and revoked time. No request file
+or recipient lookup is needed for this path. An imported inactive consumer can
+fail recipient lookup while participant inspection, revoke and cleanup remain
+available. Owner participants cannot be revoked. **Refresh trust** checks current
+capabilities; an unsuccessful reconciliation blocks mutation until refresh succeeds.
+
+Controller revocation stops future DNS-01 validation for that project. Already-
+issued certificates remain valid until expiry or separate certificate revocation,
+and other trusted projects keep working. A 503 may occur after revocation was
+persisted; refreshed trust can say revoked while DNS cleanup remains unconfirmed.
+Retrying cleanup never regrants the reference. A revoked reference cannot be
+revived: the project must explicitly confirm **Prepare fresh request**, keep
+the existing target, and obtain a new exact controller grant.
+
+A valid local certificate with blocked/failed/retrying renewal is shown as
+“valid until …; renewal needs attention.” It is not labeled expired or revoked
+as a repair. Material custody is API-node evidence, not proof that any serving
+host installed that certificate. Shared pending/broken/revoked routing never
+permits fallback TXT writes through the direct provider. Private keys stay in
+each deployment.
+
+The mock showcase includes deterministic controller-maintenance pages and an inactive consumer, plus the complete project/controller handshake, viewer,
+revoked, pending/changed/chained DNS, disconnected/unconfigured/disabled hub,
+older API, failed renewal and 390px embedded-content scenarios. Scenario changes
+reset mock shared state; identity changes preserve it. Leaving the demo restores
+its default mock identity and scenario. `verify:admin-dns-shared-validation`
+runs API/projection and React StrictMode mounted contracts. Real browser proof
+remains required for focus, native-dialog stacking, clipboard and both themes.
+
+Owner and consumer project identities preserve existing lowercase16hex Group
+IDs as well as the previously supported32hex and canonical UUID forms. They
+are compared exactly and never padded, regenerated or rewritten. Client and
+participant references retain their strict UUID validation; a short project ID
+cannot stand in for either reference.
+
+
+Shared setup prerequisites now link literal deployment operators to the actual
+mount-aware Fleet shared-validation connection topic. It owns named approved
+profiles, write-only protected keys, expected/observed identity and revision-bound
+Preview/Publish/Apply. Ordinary DNS managers receive a concrete domain, next
+action and checked-time handoff with no private inputs or private API background
+calls. This route does not perform the protected hub activation ceremony.

package/docs/admin-dns.md

@@ -84,3 +84,19 @@ See [Admin modal policy](admin-modals.md) for header actions, content-only
 sections, supported lifecycle fields and retained irreversible exceptions.
 Provider credentials retire/reactivate through `is_active`, keeping history;
 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
+the same focused flow. See [the human walkthrough and exact
+contracts](admin-dns-certificates.md#shared-validation-setup).
+
+Shared setup uses independent Readiness v1/hub v2 adapters. It never changes the
+strict legacy `/config` response contract. A controller grant is explicit
+apex/wildcard certificate issuance authority; local DNS management alone cannot
+supply it. Only public five-field connection requests are copied. No private
+key, PEM, DNS credential or protected hub key is requested, read, persisted or
+logged. Deployment operators deliver static hub settings server-side and restart
+API/workers. Validation CNAME routing remains separate from traffic routing.

package/docs/admin-fleet-configuration.md

@@ -7,8 +7,9 @@ page checks `is_superuser === true` before fetching. Backend authority remains
 mandatory, including rejection of diagnostic/key-backed sessions and fresh auth.
 
 Applications register their schema in django-mojo. The page renders the returned
-section, label, description, default, type and restart requirement; no application
-setting names are hardcoded. Each field defaults to Keep current value. Set value
+section, label, description, default, type and restart requirement; application schemas remain server-owned. The three managed shared-validation
+connection fields route to the dedicated topic below, rather than appearing as
+independently editable generic fields. Each field defaults to Keep current value. Set value
 and Remove published override are explicit actions. Clearing falls back to base
 configuration/default; it does not promise erasure of a bootstrap secret.
 
@@ -48,3 +49,98 @@ example. Mock Portal uses representative registered settings and an offline node
 Django receives this page only after a canonical Portal artifact is built and
 vendored; follow `docs/admin-artifact.md` and the Django vendor tool. Ordinary
 Vite build output is not the canonical artifact.
+
+## Shared validation connection
+
+Operations → Fleet Configuration → Shared validation connection is a private, lazy
+route. It requires a current literal superuser; the server additionally requires
+an active interactive session, same-origin writes and fresh authentication.
+Key-backed sessions are rejected by the server even when their user is an owner.
+
+On the validation hub, update every expected node using the existing Deployments
+controls, then use **Enable shared validation** once. The compact hub section is
+independent of consumer connection configuration and uses the same Portal login,
+fresh authentication and native confirmation as the existing page. No separate
+operator service, login or wizard is required. Missing or incompatible deployment
+proof shows the ordinary prerequisite instead of an enabled action. Each issuer
+keeps its own ACME account, certificates and private keys; allocation trust still
+requires explicit approval in the DNS setup screen. Renewal remains automatic.
+
+`GET /api/account/admin/fleet/shared-validation/hub` returns
+`{version:1, enabled, configured, deployment_uuid, can_enable, reason}`.
+The deployment UUID is canonical lowercase with hyphens, unlike consumer project
+UUIDs. `POST` takes only `{deployment_uuid}` after confirmation. The backend
+rechecks the complete deployed roster and framework version atomically before
+enabling. A stale deployment, failed read or fresh-auth refusal requires Refresh
+and another deliberate review; mutations are never replayed. Keep the compatible
+framework on every node after enabling sharing.
+
+The panel consumes the private `/api/account/admin/fleet/shared-validation`
+contract. Choose a named approved hub profile, inspect its exact origin and
+original project UUID, then Keep, Replace or Disable the connection. Replacement
+is a normal write-only password field; blank preserves the existing credential.
+The approved catalog fixes the origin. Arbitrary URLs and raw JSON are not inputs.
+
+Project identity fields also accept existing lowercase16hex Group IDs, preserving
+the exact value through profiles, observations and protected key issuance. Fleet
+revisions/operation IDs remain32hex and deployment IDs remain canonical UUIDs.
+The legacy identity showcase fixture changes wire data only; no Group identity
+is migrated or rewritten.
+
+Preview probes the candidate without saving it. Publication has a separate
+confirmation, frozen against the preview and auth session. Publishing revalidates
+the catalog and expected revision; it does not Apply. Apply has another
+confirmation and targets the exact current revision. Every expected node must
+report installed, restarted and combined request-service/job-engine/scheduler
+health at that revision and the expected topic profile/project identity. Offline,
+draining, stale, partial and missing-node results remain unconfirmed. The UI
+polls at most120 observations and offers deliberate Refresh afterward. Verified
+connection identity with `sharing_ready=false` still needs sharing enabled on the
+approved hub. Refresh the connection after enabling it there.
+
+Create the replacement on the approved hub with the named **ACME validation
+consumer** key form. Preview/Publish, Apply, verify every expected node, then
+explicitly review and deactivate the old key in the hub inventory. Issuance,
+publication and successful dispatch never retire keys. Disable masks the whole
+connection tuple and base credential without deleting base settings or revoking
+remote trust; retained/shared identities can make disabling ineligible.
+
+Secrets remain in an uncontrolled mounted password input and a short-lived
+imperative request draft. They never enter Query/Mutation caches, URL/history,
+storage, receipts or logs. These new writes call `requestFreshAuth` without
+replaying the attempted action; the existing generic Fleet helpers keep their
+prior behavior. Auth/session change or unmount invalidates drafts and closes
+owned confirmations. Double activation is single-flight. A409 revision/catalog
+conflict or `configuration_busy` requires Refresh and a deliberate retry. An
+uncertain publication or issuance may have persisted; read authoritative status
+or exact Group inventory before another attempt.
+
+Unavailable APIs, missing DNSMan/publisher/delegation/schema/enrollment or an empty
+approved catalog render a concrete blocked state. Bootstrap supplies `admin_path`
+and permission facts for existing legacy System Setup, Deployments, topology and
+Fleet Scaling links. Links are same-origin and capability-gated. The backend's
+semantic `capacity` hint maps to the actual registered `#/fleet` route. These
+legacy destinations retain their protected confirmations, policy, release holds
+and IaC restrictions. This React topic reuses those controls without a new
+deployment or root authority service.
+
+The Runtime settings showcase mounts the actual connection panel with central
+mock scenarios and operator/ordinary-manager identities. The named
+`verify:admin-shared-validation-config` gate includes private DTO/API and mounted
+StrictMode contracts, and is included once by `verify:admin-contracts`. Browser
+proof remains necessary for real native dialogs, keyboard/focus and390px in both
+themes. Mock receipts are fixtures, never live configuration evidence.
+
+The private form uses an inline-size container: fact labels stack above UUIDs and
+revision values below420px of available content, including a narrow embedded
+Admin host. The existing Admin sidebar's Collapse control supplies its normal
+compact host at390px; the topic does not change global navigation behavior.
+
+Every successful authoritative refresh invalidates a preview when revision,
+catalog, profile, identity or credential facts change. Late preview/operation
+responses cannot restore spent consent or overwrite a newer observation. After
+the automatic observation limit, explicit Refresh re-observes the tracked exact
+operation and resets the read budget; it never dispatches another Apply. Only
+known healthy report/node statuses with no top-level or node error can turn the
+combined proof green. Apply/read replies remain bound to their exact operation
+ID and requested/tracked revision.

package/docs/admin-identity-directories.md

@@ -35,6 +35,18 @@ existing system permission gate and conditional queries. Parent, child, member
 and user navigation opens native detail modals while keeping the directory
 underneath.
 
+The Sub-Groups section carries the "Administrators can create sub-groups"
+switch for `sys.groups | sys.manage_groups` holders only; nobody else sees it.
+It reads `metadata.protected.allow_member_subgroups === true` (anything else
+is off) and changes it only through the django-mojo Group action
+`POST /api/group/<id> {"allow_member_subgroups": true|false}`, which answers
+`{"status": true, "allow_member_subgroups": <bool>}`. Never write
+`metadata.protected` directly: that path refuses `manage_groups` admins. The
+action needs django-mojo with #9126; the server refuses a caller without the
+global grant with 403 and a non-boolean with 400. While on, people who manage
+the group as members can create groups directly under it; the setting is not
+inherited by the new groups, and turning it off leaves existing groups alone.
+
 The group model and section code are adapted from the reference portal at
 `v0.2.5` commit `93c7fdfeb3096d33010e72bd4483cf9ca6e3d6f5`. The source hashes
 and corresponding package hashes are recorded in

package/docs/admin-identity-users.md

@@ -62,6 +62,16 @@ per endpoint, so `UserDetail` and the fleet-wide tables share one cache.
 
 ## Action contracts
 
+- **Set temporary password** is available in the user header menu and Security
+  section with `sys.users | sys.manage_users`. Confirmation identifies the user
+  and explains that their password is replaced and all sessions are revoked.
+  `POST /api/account/admin/user/password/temporary` sends only `{user: id}`
+  through `withFreshAuth` (440 prompts and retries once). The generated password
+  appears once in a copyable dialog; closing or losing permission removes it.
+  It never enters Query/Mutation cache, storage, or a toast. The server requires
+  a person session, restricts superuser recovery to superusers, and forces the
+  recipient to replace the password before completing sign-in. This uses the
+  existing django-mojo endpoint; no backend upgrade or new permission is added.
 - Username changes use the `change_username` POST_SAVE_ACTION, not a direct
   field save. Model saves/actions retry one fresh-auth 440 automatically;
   combined `disable_totp` writes explicitly use `withFreshAuth`.

package/docs/admin-modals.md

@@ -135,3 +135,31 @@ browser interactions for all family bodies, both themes, desktop/narrow,
 keyboard navigation and console checks. The lazy Showcase **Admin modal audit**
 demo supplies long-title, rich/zero/dot badges, nested editor, lifecycle-cancel and
 embedded-host cases. Existing ToastHost top-layer visibility work remains separate.
+
+## Shared validation confirmations
+
+The DNS shared-validation editor freezes the target group/domain, existing
+allocation and session while an operation is pending. Grant additionally freezes
+the imported request, active exact recipient UUID and client reference. Participant
+revoke/cleanup freezes the selected current-page participant independently of any
+request or recipient lookup; cleanup retry leaves the reference revoked.
+Its owner AbortSignal closes only its confirmation on unmount, scope loss or
+auth/session replacement; submitted writes can still persist. Escape/backdrop
+and Close are unavailable while the outer operation is pending.
+
+Prepare explains the pause of direct validation/renewal while valid material
+remains available. Grant names the exact project and apex/wildcard issuance
+authority and independent private-key custody. Revoke explains that future
+validation stops, already-issued certificates remain valid and other consumers
+keep working. Revoked references require a fresh, explicitly prepared request.
+No confirmation is inferred from a copied descriptor. Fresh authentication
+prompts without replay; every submitted result reconciles before another write.
+
+
+The protected connection topic separately confirms Publish and Apply, naming
+profile/project and exact revision consequences. The ACME consumer key form
+confirms the current original Group name/UUID and fixed protected purpose before
+issuance; its token display is transient and the existing audited reveal is
+available for recovery. Every owned nested dialog receives the auth-owner abort
+signal. Session replacement, scope loss and unmount close those dialogs; submitted
+writes may still persist and are never replayed after fresh authentication.