portal-mojo 0.2.19 → 0.2.21

package/docs/admin-geolocation.md

@@ -0,0 +1,100 @@
+# GeoLocation provider setup
+
+`GeoLocationPage` (`portal-mojo/admin/operations`) is the global Operations →
+GeoLocation surface. GeoIP Cache inspects IPs; Fleet Configuration applies
+published settings. Dashboard is unchanged. Hosts may override the mount-derived Fleet link with
+`fleetConfigurationPath`; Showcase opens the actual Fleet Configuration page with a return link.
+
+Admission requires literal `is_superuser === true` and a current interactive
+session. The backend also rejects key-backed sessions, requires same-origin
+POSTs and authentication within 600 seconds. Global/group grants do not replace
+these checks. `usePrivateOperator` remounts on session change, aborts requests and
+owned dialogs, and rechecks authority before sending and accepting responses.
+
+## Tasks
+
+Primary, fallback and ordered additional providers form one visible configuration task,
+with add, remove and move controls. MojoVerify credentials and threat sharing sit
+below the chain. One retained draft and Save/Discard footer cover the form; there
+is no tab navigation for parts of the same task. The uncontrolled password element
+stays mounted while editing, and shared Tabs is unchanged.
+
+MojoVerify always uses `https://api.mojoverify.com`; no URL control is shown.
+Older origins remain readable, but this page stages the hosted URL and warns
+that switching requires a replacement key. Provider names are human-readable;
+unknown configured identifiers are retained. New additional rows exclude primary,
+fallback and existing rows. Runtime deduplicates the chain; existing overlaps are
+not silently rewritten. Non-Mojo credentials are configured outside this endpoint.
+The server's values are authoritative: setup defaults differ from runtime defaults.
+
+No key shows **Add key**; a configured key shows **Replace key** and **Remove
+key**. Test key sits with the credential. Blank replacement preserves the stored
+key; confirmed removal is staged until Save changes and does not revoke remotely.
+Save/Discard reflect actual draft changes. Refresh and the page-owned Open Fleet Configuration link confirm before discarding an
+unsaved draft. Keep editing preserves both provider selections and the entered key;
+explicit departure wipes the key before navigation. An in-flight operation cannot
+be interrupted through that link. Info popovers hold secondary explanations; Configuration information
+opens a focused native dialog for revision and publication facts. No disclosure
+sections or sidebar modal are used.
+
+Last stored-key check shows its historical outcome and timestamp separately from
+the draft result. Pending activation and Open Fleet Configuration remain visible.
+A false pending flag concerns only this request node, never proves fleet health.
+
+## Private protocol
+
+`readGeoLocation()` positively projects only `provider_setup` from schema-v1
+`/api/account/admin/settings`. Catalog, SMS, unknown fields and raw credentials
+are discarded. Form state is imperative, outside Query/Mutation caches.
+
+`buildGeoPayload(action, configuration_revision, draft, keyEdit)` sends exactly
+`{action,topic:'geoip',providers:{expected_revision,geoip}}`. The revision is sent
+even when null. The five static keys are primary, fallback, additional, Mojo URL
+and sync. Untouched/blank replacement omits credentials; nonempty replacement
+adds `GEOIP_API_KEY_MOJO`; confirmed removal adds `clear_api_key:true`.
+Additional providers are unique and ordered, at most 16. Identifiers match
+`^[a-z][a-z0-9_-]{0,31}$`. HTTPS origins permit no credentials, path, query,
+fragment or alternate port (443 allowed); keys are at most 4096 characters.
+
+Secrets stay only in the password DOM and short-lived request objects, whose
+raw key is deleted in `finally`. They never enter React/Query/Mutation state,
+URLs, storage, logs or mock observations. Editing retains the element and candidate;
+Save attempts, explicit discard, fresh-auth refusal, session change and unmount
+clear it. A stable ref callback wipes the password element before detachment;
+removing the DOM node alone is insufficient. Writes are single-flight. A 440 invokes fresh authentication without
+replaying; Refresh and a deliberate retry are required. Stale revisions
+(400 “changed; reload before publishing”, or 409), unreadable state and uncertain
+saves require authoritative Refresh before another write.
+
+Test verifies **only MojoVerify credentials**, regardless of primary. It requires
+the five delegated descriptor keys but not Fleet bucket/object/KMS/restart
+availability; Save requires the publishing plane. Sharing requires the remote
+key's `geoip_sync` permission. The current backend also verifies Mojo on every
+Save except explicit removal: selecting another primary does not enable an
+independent no-Mojo setup. This page does not invent provider-chain testing,
+other-provider key editing, provisioning, revocation or an Apply endpoint.
+
+A draft-key test does not rewrite stored verification. The backend's stored-test
+predicate is no replacement plus the node-loaded origin and sync value; chain
+changes do not affect it. Tests reread stored evidence without rebasing the
+draft's revision. Revision changes or lost normalization authority block retry;
+publishing-only unavailability does not block diagnostics. Loaded/desired origin
+drift can prevent stored-key reuse until Fleet apply or explicit replacement.
+
+Save rereads authoritative configuration. `published:true` means static
+publication with restart pending; `unchanged:true` can still mean the database
+credential changed. Neither result proves activation. Failed, stale and uncertain
+requests keep errors actionable and never become successful saves.
+
+## Verification
+
+`geo-provider-mock.ts` supplies isolated safe observations (action, key action,
+stored-test predicate, expected revision), with no submitted key retained.
+Scenarios include no-key setup, real registry names, unknown/empty registry,
+publishing unavailable, stale/fresh-auth/uncertain outcomes and loaded-origin drift.
+Showcase's GeoLocation demo mounts the actual page. Run
+`npm run verify:admin-geolocation` and `npm run verify:admin-geolocation-mounted`;
+JSDOM behavior does not establish native focus or layout. Inspect both apps,
+light/dark, desktop/390px, opened dialogs and error recovery per
+[Admin presentation](admin-presentation.md). The scoped stylesheet is included
+through `portal-mojo/styles.css`.

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-maintenance.md

@@ -0,0 +1,133 @@
+# Maintenance
+
+```tsx
+import { MaintenancePage } from 'portal-mojo/admin/operations';
+```
+
+`MaintenancePage` supplies one global Operations destination at `maintenance`.
+It renders Database, Cache and Framework as independent evidence sections.
+Page admission is AWS read (`manage_aws`) **or** framework read
+(`view_platform`, `manage_platform`, `admin`), with literal superuser bypass.
+Each read uses the Fleet exact backend permission helper; group membership,
+the frontend admin wildcard and `comms` do not grant AWS authority.
+
+A scan reports offered major upgrades, region, scan time, scheduled-scanning
+state and each warning's exact IAM action. It supplies no complete inventory
+counts. Empty findings mean **No offered major upgrades found in this scan**.
+Partial or unavailable scans never establish support coverage. Standard and
+extended deadlines are separate; an unpublished deadline remains unknown.
+Targets and resource identifiers retain their server spelling. Release notes
+accept credential-free HTTPS links only.
+
+Writes additionally require platform management authority and current managed
+infrastructure proof. Bootstrap has its own independent dashboard permission:
+without that grant the page retains authorized inventory but cannot establish
+mode or offer writes. External infrastructure remains readable and explains
+that IaC owns changes. Missing, denied or malformed mode proof blocks writes.
+The backend remains authoritative for interactive, non-key-backed access and
+600-second fresh authentication.
+
+The native confirmation names current and target versions, outage/restart
+impact, and snapshot-based recovery. Type the exact case-sensitive resource
+identifier and explicitly choose Immediately or Next maintenance window.
+`apply_immediately` is a real boolean, including `false`. Changing evidence or
+session closes the old confirmation. Confirmation is single-flight; transport
+uses `mojoCall`, AbortSignals and a final session/authority fence without retry,
+`withFreshAuth`, Query mutations or raw fetch.
+
+After acceptance the exact resource and target are observed every ten seconds,
+at most 180 times. Completion requires both `settled === true` and
+`upgraded === true`. A target version before settlement, old available version,
+missing resource, denied/malformed read, or mixed cache member versions remains
+unconfirmed. Timeout retains the receipt and offers explicit status refresh.
+
+Attempts are scoped by installation and actor in a module registry, surviving
+dialog closure, navigation/remount, timeout, ordinary token renewal and a new
+session for the same actor. Unmount/session changes abort local observations;
+provider work can continue. An attempted/unknown provider outcome never unlocks
+another apply merely because a refreshed report still offers the old version.
+A completed receipt permits a new, different offered target with new consent;
+switching only the timing never bypasses the same-target guard.
+Reconcile the provider operation and maintenance window. A definitive refusal
+before provider work can be cleared only by a deliberate successful Refresh
+Maintenance and a new confirmation. A 440 requests authentication once and
+never replays the write.
+
+Framework shows installed/latest versions, check time/source, pin policy,
+update availability and the backend blocker. Held/pinned versions use
+“Resume and update”. The operation clears the pin and
+redeploys the last converged application SHA. Policy clearing and deployment
+acceptance are separate facts: a 503 or lost response can leave automatic policy
+active with unknown deployment acceptance. That attempt remains guarded across
+remount and reauthentication. Refresh Framework and inspect Deployments even
+when no deployment ID was returned. Acceptance points to Deployments and never
+claims fleet completion. The separate Update policy dialog saves Automatic (`""`), Hold (`"hold"`) or an
+exact version through `POST /api/account/admin/advanced/settings` with only
+`framework_pin`. It requires an active literal superuser and fresh authentication;
+this page also keeps external infrastructure read-only. Syntax validation does
+not verify that an exact version is published. Hold resolves the last converged
+framework version. Saving policy never submits a deployment. The framework
+Update action explicitly clears that policy and requests latest; it cannot
+deploy an exact selection while retaining the pin.
+
+A successful policy response followed by matching live policy readback completes
+that policy attempt. A lost/uncertain response remains guarded even if the
+desired value is later observed: current value does not prove request ownership
+or that a delayed writer finished. There is no policy revision or durable receipt
+lookup. Reconcile server audit before further policy writes; there is no reset
+button. Generic Settings directs `EDGE_FRAMEWORK_VERSION` to the mounted
+Maintenance owner, rather than submitting through the rejected generic writer.
+
+Framework submissions with an acknowledged UUID observe that exact deployment
+and SHA through the bounded platform deployments collector. Only `converged`,
+`failed`, and `superseded` release its submission guard for a different target;
+`verified`, `partial`, `unknown`, absence, and errors do not. Deployment terminal
+status is distinct from requested framework-version proof. That requires a
+nonempty unique frozen runner roster, unique matching proof for each runner,
+exact UUID/full SHA/version, and fresh valid observation timestamps. Missing
+version proof remains explicit even when deployment converges. Lost acceptance
+without a UUID cannot be reconciled from the latest same-SHA row.
+
+Submitted operations remain compact rows across categories; View progress opens
+a focused dialog with target, timing, last successful observation, current/pending
+and member versions, or correlated deployment evidence. Manual refresh only reads.
+Aurora settlement proves cluster-level state, not individual database members.
+Module-memory receipts survive navigation and same-actor renewal; a full browser
+reload loses them. Durable reload-safe reconciliation needs backend support.
+
+`maintenanceDeploymentsHref(pathname)` preserves an embedded Admin prefix.
+`MaintenancePage` also accepts an explicit `deploymentsHref`, `pollInterval`
+and `pollLimit`; production defaults are ten seconds and 180 observations.
+
+Mock integration: call `maintenanceMock(path, method, body, params, context)`
+only for its owned paths. It returns `undefined` for every sibling path.
+`context` contains authenticated user, claim-derived `keyBacked` and `fresh`.
+Use `readMaintenanceBootstrapFacts()` in the **single central bootstrap
+composer**; Maintenance does not claim that endpoint. Preserve its explicit
+`bootstrap` denied/malformed scenario and derive mode and managed capability
+from the same facts. `MAINTENANCE_SCENARIOS` and `setMockMaintenanceScenario`
+exercise partial scans, waiting/settlement, provider uncertainty and Framework
+policy/deployment uncertainty through the actual page.
+
+Integration manifest: lazy-load `admin/maintenance/MaintenancePage.tsx`; global
+section id/path `maintenance`, label Maintenance, navigationGroup operations,
+nav union `sys.manage_aws | sys.view_platform | sys.manage_platform | sys.admin`.
+Import `styles/components/admin-maintenance.css`; register `AdminMaintenanceDemo`
+from `apps/showcase/src/pages/components/demos-admin-maintenance.tsx` lazily.
+Register `verify-admin-maintenance.mjs` and `verify-admin-maintenance-mounted.mjs`
+once each; the harness is an imported test adapter, not a command. Public index
+exports are MaintenancePage, maintenanceDeploymentsHref, maintenanceAccess,
+frameworkActionLabel, MAINTENANCE_ENDPOINTS and maintenanceCompleted.
+
+Resource rows keep the offered version, provider state and upgrade action visible. Support deadlines, member evidence and recovery notes remain under each row’s disclosure. Dates use compact local presentation and preserve the original wire value in their title. Framework policy uses readable labels; missing or refused evidence remains explicit.
+
+### KISS presentation
+
+Database, Cache and Django-MOJO use tabs when multiple categories are authorized.
+A reader with only one authorized category sees its panel directly without a tab strip. Scan metadata is collapsed; scan errors, incomplete evidence and scanning-off warnings stay above the tabs. Submitted operations remain visible independently of the selected category. See [visual QA](admin-presentation.md).
+
+Standard support deadlines within 30 days or overdue remain visible on resource rows;
+standard and extended support stay separate. Missing support dates are not
+interpreted as supported. Framework status distinguishes current, policy-paused
+published versions, and unavailable/latest-unknown evidence, with source details
+in accessible info popovers.

package/docs/admin-modals.md

@@ -11,6 +11,20 @@ or rename an action pane to disguise it. Genuine autosave fields remain content.
 A nested child may have its own contextual actions. Evidence such as a firewall
 log's Action **column** describes the event and is not an operation section.
 
+Serving hostname inspection uses a compact `modal.open` with horizontal task
+tabs instead of a side rail: Overview, conditional Routes and Settings.
+Certificate details and a direct certificate editor are available in Overview.
+Its Hostname/Certificate/Settings editor and Hostname → Certificate → Review
+create flow keep one draft. The launcher guards native dismissal while any write or
+route preflight is pending; focused child editors retain the same owner lifetime.
+This is scoped to Serving and does not change the shared DetailView contract.
+
+Deployments likewise uses compact `modal.open` task dialogs: API Overview/Nodes/
+Activity; WebApp Overview/Deployments/Releases/Deploy/Settings. Read-only actors
+omit deployment controls, and attempt viewers get a direct overview when there
+is no admitted node evidence. Workflow, integration, setup identity and profile
+editing use focused child dialogs. No shared DetailView default is changed.
+
 Use `modal-pad`, `modal-title`, `modal-message`, grouped fields and `modal-actions`.
 Cancel precedes the primary button. Pending operations disable repeat submission;
 `canDismiss` also protects native Escape/backdrop dismissal during a write.
@@ -70,7 +84,8 @@ the inventory using `node scripts/verify-admin-modals.mjs --write-inventory`.
 | Storage/shortlinks | Bucket, FileManager, File, shortlink; owner/backend/test/CORS/upload/rendition/share | FileManager/shortlink/share active state; no File disable promise; bucket empty only |
 | Email/support | Domain, mailbox, sent message, template, contact; credentials/onboarding/audit/reconcile/test/template/status | Preserve evidence; separate mailbox directions and support status |
 | Phone/Push | Number, SMS, config, device, delivery, template; lookup/test/config editors | Config/template lifecycle; number/SMS/device/delivery evidence retained |
-| Edge | Vhost with nested routes; shape-first wizard, route editor, upstream declare/retire, blocklist entry editor | Vhost and upstream enabled state; upstreams retire and are never deleted; vhost, route and blocklist deletion are retained operations |
+| Operations | Fleet capacity planning, Maintenance exact resource/window confirmation, GeoLocation local key-removal confirmation, API/WebApp detail and focused onboarding/recovery/upload/credential flows | No generic deployment/release edits or deletion; staged intent, observed receipts and transient secrets remain distinct |
+| Edge | Vhost with nested routes; Hostname → Certificate → Review creation, route editor, upstream declare/retire, blocklist entry editor | Vhost and upstream enabled state; upstreams retire and are never deleted; vhost, route and blocklist deletion are retained operations |
 | Assistant/settings | Conversation, Skill, Setting; feed continuation, scoped memory, typed settings editor | Owner-only continuation; Skill active selection; memory is scoped editing |
 
 ## Resource lifecycle matrix
@@ -93,7 +108,7 @@ the inventory using `node scripts/verify-admin-modals.mjs --write-inventory`.
 | Push config / template | Existing active selection with separate manage/test grants |
 | Assistant conversation | Retain history; no arbitrary REST save or invented archive |
 | Assistant Skill | Existing `is_active` save requires `sys.view_admin`; authoritative reload after mutation |
-| Edge vhost | Enable/disable from the header; Edit and Delete in the header menu. Disabling keeps the row and is how a replacement is staged |
+| Edge vhost | Enable/disable and Edit in the header; Delete in the header menu. Disabling keeps the row and is how a replacement is staged |
 | Edge upstream | `is_enabled` only. Retire (platform administrators) disables and keeps the row; server `CAN_DELETE=False` |
 | Edge blocklist entry | Mode is the lifecycle: `off` parks an entry without losing it. Deletion is a retained operation |
 | Other logs/devices/history | Read-only by default, even where low-level REST supports DELETE |
@@ -135,3 +150,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.

package/docs/admin-operational-fleet.md

@@ -0,0 +1,206 @@
+# Operational Fleet
+
+`FleetOverview` is the reusable health matrix at the top of the global Dashboard.
+`FleetPage` presents a separate standalone workspace at the mount-relative `/fleet` destination. Its task dialogs and styles are isolated from `FleetOverview`; the Admin Dashboard keeps its existing overview, disclosure, editor and behavior.
+Import both, `backendGlobalCan`, contracts and pure staging helpers from
+`portal-mojo/admin` (or `portal-mojo/admin/infrastructure`). The scale editor loads
+only when opened. Existing Dashboard directory, activity and login panels remain
+below this component.
+
+```tsx
+<FleetOverview mount="/product/control" />
+<FleetPage mount="/product/control" />
+```
+
+Both accept optional `mount`, `links` and `showConfigurationLink` props. The mount
+is inferred from the current dashboard pathname, removing a final `/fleet` on
+that page; pass it explicitly in a custom host. `links` maps source names to
+`{ to: 'relative/registered/route', grants: ['exact_backend_key'], superuser?: true }`
+or `null` to suppress a destination. Hosts with a partial registry must suppress
+or replace unavailable destinations. Built-in links target existing Admin pages
+only; Fleet Configuration remains its separate advanced superuser destination.
+Use `showConfigurationLink={false}` when that destination is not mounted.
+`FleetOverview` also accepts `headingLevel` (`1 | 2`, default `2`); use `1` when
+rendering it as a standalone page. `FleetPage` supplies its own level-one Fleet heading.
+`capacityDetails="modal"` replaces the capacity disclosure with a button and a
+read-only modal. This option applies to `FleetOverview`. The reusable overview defaults to `"inline"` to preserve the current Admin Dashboard. `FleetPage` always uses the standalone tabbed capacity inspector.
+
+## Authority and evidence
+
+`backendGlobalCan(user, grant | grants)` checks global permissions only. It mirrors
+Python truthiness of JSON values and the finite `helpers/perms.py` categories:
+`users`, `groups`, `security`, `comms`, `jobs`, `metrics`, `files` imply only their
+own `view_`/`manage_` checks. It has no group membership or implicit `admin`
+wildcard. In particular `comms` and `admin` do not imply `manage_aws`.
+
+The dashboard request needs `view_admin | manage_users | manage_settings | admin`
+or literal superuser. Capacity reads separately require `manage_aws` or literal
+superuser. Every request and query key is bound to actor plus session revision;
+ordinary token renewal preserves that revision. Each denied read is suppressed.
+Source statuses and server timestamps survive independently. The availability
+headline is the server verdict; attention counts never recompute it. Missing
+jobs/check observations stay unknown. Wholly restricted sections collapse to
+one Restricted row. Unconfigured SMS/email and zero-ticket rows are absent.
+Dashboard data is positively projected before Query storage; arbitrary nested
+provider output and deployment stderr never enter this cache.
+
+Load-balancer target health, fixed ingress addresses, and stable node outbound
+addresses are distinct observations. Unknown egress reads say unavailable, never
+an empty allowlist. Serving-process database/Redis reader routing is explicitly
+per process. Database and cache members retain their own lifecycle/status. An Aurora reader absent from filtered instance facts may carry null class/status with unknown lifecycle. That database remains transition-blocked while node/cache evidence and independently supported changes remain available.
+
+## Standalone Fleet workspace
+
+`FleetPage` lazy-loads `FleetWorkspace`, and each inspection, editing and progress
+body loads only when opened. Its scoped `.fleet-page` and
+`.fleet-standalone-dialog` styles do not change the Dashboard. Infrastructure and Operations task tabs keep
+the backend availability verdict and each source status. Overall observation age
+is visible; each source timestamp stays in its info popover, while stale sources
+also show their age inline. Stale thresholds remain in info popovers; refreshing never relabels
+old evidence as current. Missing sources stay unknown, denied sections stay
+restricted. Authorized, mounted related destinations are direct links on source names;
+unauthorized destinations are omitted. Info popovers contain evidence, not navigation.
+
+The primary action is **Change capacity**. **Inspect capacity** opens App nodes,
+Database, Redis and Addresses tabs. Fleet outbound allowlist, fallback attachments,
+reserved addresses and fixed load-balancer ingress appear separately. **Copy
+allowlist** requires every availability proof, an enabled observed policy and no
+pending nodes. Missing evidence never becomes an empty allowlist. Database and
+Redis reader routing explicitly describe the serving process.
+
+The standalone editor uses one `CapacityDraft` from `standalone-data.ts` across
+App nodes, Database and Redis tabs. App nodes has Add nodes and Remove nodes tasks.
+Additions require an explicit healthy, registered, running, settled source; its
+size and target groups are shown, and Change subnet opens a focused override dialog.
+Removal retains the existing self-node and healthy-floor checks; the server also
+re-proves each target group's floor and ownership.
+
+Every database member shows its exact ID, role and **current** class. Its size
+select and remove checkbox target that ID; there is no automatic reader selection
+or shared existing-reader sizing fan-out. Newly added readers inherit the current
+source class, even when the writer also resizes. Observe their concrete IDs after
+creation and resize separately. For a Redis group, stage size **or** replica
+count in one plan. The other control is locked until the first returns to current
+values; apply, refresh and separately review the second change. The pure compiler
+rejects mixed-dimension intents independently of those controls because the
+current backend cannot quote them cumulatively.
+
+The explicit **Review changes (N)** button is the only plan request. It replaces
+the editor with the authoritative server plan, including step order, warnings,
+unknown prices, expiry and exact-plan consent. Review shows only allowlisted
+server parameters for source node, subnet, target size, count and immediate-apply
+mode when the server reports supported scalar values. Draft intent never fills
+in missing plan facts. Source choices include the exact node ID. **Back to changes**
+preserves the draft and invalidates consent. No background/debounced quote is
+requested by the standalone editor. **Refresh and clear changes** explicitly discards the draft
+before reading fresh inventory; there is no silent reset. Initial open also
+requires a fresh observation before staging. Apply uses only `fleetOperations`.
+Both standalone and Dashboard changes require a literal superuser, an interactive
+user credential and backend fresh authentication. A 440 opens fresh authentication,
+spends consent and requires an explicit refreshed review; planning and applying
+are never automatically replayed.
+
+**View capacity progress** is independently available when an in-session operation
+record is retained with a non-idle status and the account has capacity-read
+authority, including external infrastructure, unavailable inventories and non-superuser
+readers. It uses the same in-session operation record as Dashboard. It never
+hydrates an operation from storage or creates another coordinator. When an apply
+reply is lost, the exact batch ID can be entered for read-only reconciliation of
+the retained plan. Matching terminal evidence is required before another change.
+Keep the current document open while reconciling: a full document reload loses
+the in-memory operation record. Batch-ID entry reconciles a retained plan and
+does not import an arbitrary operation after reload. Actor/session changes and
+permission loss fence requests and close owned dialogs;
+Escape/backdrop and explicit close are locked while requests are pending.
+
+The Showcase demo uses `FleetPage` and a focused Demo controls dialog. Scenario
+switching is disabled during unresolved operations. Read-only mock batch IDs are
+available through Refresh mock evidence so lost replies can be reconciled without
+clearing the browser's guard.
+
+## Dashboard reviewed scaling
+
+Scaling requires a literal superuser with capacity authority and a browser user
+session. External infrastructure remains read-only. The backend enforces its
+credential provenance and 600-second freshness requirement. A 440 opens the
+existing fresh-auth handler, spends consent, and requires explicit refreshed
+review. Neither planning nor applying is automatically replayed.
+
+The existing Dashboard focused native dialog refreshes inventory before staging. Local intent is
+compiled into at most 20 steps, then debounced about 400ms into
+`POST /api/aws/capacity/plan {steps}`. Displayed order, descriptions, warnings,
+prices and expiry come from that stored plan. Null prices are unknown. Editing,
+refreshing, expiry, permission loss or session replacement invalidates consent.
+A synchronous guard protects submission, including duplicate activation.
+`POST /api/aws/capacity/plan/apply` sends only `{plan_id}`.
+
+Node removal stages drain then terminate, excludes this serving node, requires
+identified self and complete inventory, and retains one currently healthy target.
+Unproven additions never satisfy the healthy floor. A freshly observed owned,
+unregistered, settled node gets a separate Terminate drained node recovery path;
+AWS ownership and drain completion are re-proved by the server. App size remains
+informational. Add-node placement omits empty fields and locally validates subnet
+shape; AWS proves the source, VPC, availability zone and address suitability.
+
+Database writer and existing-reader sizes are independent curated keys. Reader
+resizing fans out over surviving concrete reader IDs with different current
+classes; staged removals are excluded. New readers inherit the **current** source
+class, even when the writer also resizes in the plan. Refresh their concrete IDs
+after creation and separately review resizing them. Writer resizing causes
+minutes offline. Redis sizing applies to the whole group; replica counts retain
+the server minimum and the editor explains rolling or downtime impact before
+review. All count/cache/database resize steps explicitly send
+`apply_immediately: true`.
+
+## Observation and uncertain outcomes
+
+`fleetOperations` lives outside component/dialog state. Its records contain safe
+IDs and observed batch facts, keyed by installation and actor. Unresolved state
+survives dialog closure, Dashboard/Fleet navigation, and same-actor reauthentication;
+it does not survive a full document reload. Keep the current document open when
+reconciling an uncertain submission. New sends and read replies are still fenced
+to the exact session revision. A
+different actor sees no previous actor record. No credentials or mutation drafts
+are stored locally. The coordinator never replays a mutation. Expiry or session refusal at the final transport boundary is provably unsent: refresh inventory and review again. A transport failure after that boundary remains unknown and retains the reconciliation guard.
+
+Running batches are observed about every ten seconds, with a backstop covering
+90 minutes per step. Completed steps remain visible on failure; nothing rolls
+back. `stalled` directs the operator to the jobs runner/cleanup channel. Poll
+failures and exhausted budgets say progress unknown and offer explicit observation
+refresh. A duplicate apply receipt follows its existing batch. Stale/expired plans
+require another review.
+
+A lost apply reply retains the submitted plan ID and blocks new mutations, even
+when no batch ID was acknowledged. Closing, refreshing inventory, signing in
+again as the same actor, and selecting a mock scenario do not clear this block.
+Inspect capacity server logs and AWS state, obtain the exact plan's batch ID, and
+enter it for read-only observation. Only matching terminal evidence resolves the
+block; an unrelated batch is refused. Ambiguous provider outcomes remain unknown.
+
+## Mock and executable verification
+
+`client/operational-fleet-mock.ts` is mock-only and exports:
+
+- `handleOperationalFleetMock(path, method, body, params, actor, authTime)` → an
+  envelope, `undefined` for unowned routes, or an intentional lost-response error.
+  The central mock supplies its validated actor/global grants and bearer auth time;
+  optional `actor.credential_kind` identifies a confirmed confined credential.
+- `mockOperationalFleetScenarios`, `setMockOperationalFleetScenario`,
+  `getMockOperationalFleetScenario`, and read-only `getMockOperationalFleetBatchIds`.
+
+The default fixture includes asymmetric reader classes. Scenarios cover external,
+restricted, partial, transitioning/drained nodes, missing evidence, unknown prices,
+stale/expired/duplicate plans, partial failures, stalled progress and lost replies.
+Changing scenario resets the simulated server, not the browser operation record.
+
+Run `npm run verify:admin-fleet-workspace` for standalone compiler and mounted coverage, plus `node scripts/verify-admin-operational-fleet.mjs` and
+`node scripts/verify-admin-operational-fleet-mounted.mjs`. The mounted verifier uses
+an isolated injected transport and rejects every real host. It exercises actual
+React components in StrictMode, custom embedded mounts, denied request suppression,
+cancellation, stale responses, single-flight, fresh-auth without replay, cross-page
+progress and unknown-outcome reconciliation. Browser light/dark, narrow layout,
+native focus and console proof belong to the integrated closing run.
+
+### KISS presentation
+
+The Dashboard overview uses its existing compact service/status rows and modal Details. The separate Fleet workspace uses compact evidence cards and info popovers. Both editors retain a single draft across App nodes, Database and Redis tabs; the standalone editor enters review only through Review changes and discards consent on Back. All staged changes appear in one exact server-plan review. See [visual QA](admin-presentation.md).

package/docs/admin-presentation.md

@@ -0,0 +1,51 @@
+# Admin presentation and visual QA
+
+Use intuitive, simple screens with clean spacing. Keep only important data and
+short action-oriented copy on the primary surface. Use tabs, modals and help
+popovers only when they improve the task. Tabs separate
+distinct jobs; do not split a few related fields across tiny panels or render
+a one-item tab strip. Use focused modals for substantial inspection/confirmation
+and keyboard-accessible info popovers for secondary explanations. Keep navigation
+directly discoverable rather than hiding destination links inside help. On pages
+that already scroll, use modals/popovers rather
+than collapsible detail sections. Compact disclosures such as Maintenance are
+fine; this is contextual. Preserve Admin Dashboard as-is unless Ian explicitly
+requests a change; separate Fleet work must not alter it. Keep action-specific errors, unknown outcomes and concrete
+interruptions visible where the operator needs them. Permission/consent/session
+and no-replay checks are behavioral requirements, not prose to remove.
+
+Both applications import `portal-mojo/styles.css`. Never add app-local copies of
+package component CSS: unlayered stale copies override the canonical layer.
+Showcase owns only tokens, chrome and demo-only styling. Test fixture controls
+are demo-only, separate from the product's UI.
+
+## Required acceptance
+
+1. Run `npm run verify:admin-presentation`. It compiles each app's real theme
+   through Vite and checks the six operations layouts, plus the shared style
+   entrypoint. A CSS file existing on disk does not prove it is loaded.
+2. Wait for actual loaded data and controls, not just a heading, spinner or
+   skeleton. Inspect initial-viewport screenshots of **all six** screens
+   (GeoLocation, Fleet, Maintenance, Deployments, Domains, Serving) in light and
+   dark at desktop and 390px. Revisit each image; producing one is not review.
+3. Check computed page/row display, padding/gap and heading size. Check field
+   separation, alignment, readable contrast, wrapping and no page overflow.
+   Tables may scroll inside their own container. Inspect internal scroll areas
+   and sticky actions, not just document width.
+4. Open help, tabs, details and dialogs. Verify popovers inside a native dialog,
+   Escape/outside dismissal, readable fields and reachable actions at narrow
+   width. Inspect every changed surface, including errors and unknown outcomes.
+5. Exercise mock workflows: provider test/save, a combined scaling draft retained
+   across tabs and exact plan review, maintenance outage/resource confirmation,
+   API/WebApp tabs and recovery/setup, Domain actions/details, Serving wizard.
+   Cancel billable/destructive actions unless a test explicitly owns the mock.
+6. Repeat a smoke check in the actual Admin shell and built Showcase output.
+   Check the browser console and run focused behavior contracts plus typecheck.
+   DOM-only tests verify behavior; they cannot certify layout or visual quality.
+   At mobile width, verify navigation starts collapsed, expands over the page,
+   closes with Escape/outside activation or navigation, and preserves the saved
+   desktop preference when returning to a wider viewport.
+
+Keep screenshot evidence and the screen/theme/viewport/interaction results on
+the Maestro item. State whether evidence is mock or live. A preview link must
+work when handed over; the development server's lifetime is part of that check.

package/docs/admin-signin.md

@@ -12,9 +12,11 @@ The page has two parts:
   layout/appearance/accent color, hero panel, sign-in heading/copy/methods,
   registration, custom CSS. It edits the same keys a group admin edits in the
   group **Configure Auth** dialog; a group's own settings still override these.
-- **Providers** — one card each for Google, Apple and GitHub: an Enabled
+- **Providers** — one card per provider the server lists (Google, Apple,
+  GitHub and, from django-mojo's Microsoft sign-in, Microsoft): an Enabled
   switch, a read-only callback URL with a Copy button, the credential fields,
-  a Ready / Needs setup badge, and a link to the provider's console.
+  a Ready / Needs setup badge, any server notices, and a link to the
+  provider's console.
 
 KISS by design: trusted admins, no step-up auth, no confirmation beyond a
 browser `confirm()` before clearing a stored value.
@@ -38,6 +40,14 @@ One endpoint, both methods, django-mojo envelope.
   multiline, configured, source, value, hint}`. `source` is `admin`,
   `deployment` (shown as "Set in server config") or `none`. Secret fields
   never carry `value`; `hint` (e.g. `…a1b2`) is shown when present.
+- Optional `notices[]` on a provider: `{tone, text}`, `tone` one of `info`,
+  `warning` or `danger` (for example a Microsoft client secret nearing or past
+  its recorded expiry). Each renders as its own `role="status"` note under
+  the Needs setup note, in order; any other tone renders as `info`. An absent
+  or empty list renders nothing, so older backends are unaffected.
+- Provider `name` tokens with a built-in label and icon: `google`, `apple`,
+  `github`, `microsoft` (`bi-microsoft`). Any other name falls back to the
+  server's `label` and a key icon.
 
 `POST /api/account/admin/signin` returns the same full payload, which the page
 writes straight into its query cache (`SIGNIN_QUERY_KEY`).