portal-mojo 0.2.20 → 0.2.21

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 |

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`).

package/docs/client.md

@@ -458,3 +458,10 @@ now **rejects** a flat HTTP-200 refusal (top-level `success:false`) with
 - `err.errorCode` carries the refusal code and `err.data` the full reply, so
   the server's reason is no longer lost.
 - `defineModel` actions and `mojoAction` behave as before.
+
+`mojoCall` accepts optional `idempotencyKey` for a reviewed operation receipt. The
+transport validates 1–128 ASCII receipt characters (`A-Z`, `a-z`, `0-9`, `.`, `_`,
+`:`, `-`) and emits only the `Idempotency-Key` header. It does not expose arbitrary
+custom headers or record the key with sensitive bodies. Preserve the same receipt
+for a deliberate retry of the same operation; observe uncertain outcomes before
+creating another operation.

package/docs/combobox.md

@@ -19,6 +19,7 @@ interface ComboOption {
     value: ComboValue;
     label: string;          // what the input displays
     description?: string;   // muted second line in the list
+    disabled?: boolean;    // shown but never committed
     meta?: Record<string, unknown>;  // opaque; returned via onSelect
 }
 
@@ -32,6 +33,8 @@ interface ComboOption {
     minChars={0}    // typing auto-opens the list only at ≥ N chars
     maxSuggestions={10}  // caps the rendered list AND keyboard wraparound
     placeholder disabled readOnly required id className
+    inputRef={fieldRef} // input focus target for form validation
+    aria-label="Output" aria-describedby="output-help" aria-invalid={invalid}
 />
 ```
 
@@ -103,3 +106,18 @@ strings.
   containers and native dialogs do not clip it.
 - Styles live in `packages/portal-mojo/src/styles/components/combobox.css` (tokens only, both
   themes) and ship in `portal-mojo/styles.css`.
+
+## Fixed-choice dropdowns
+
+Use `allowCustom={false}` for enums and filters. Pass the same string/number
+type to `value` and each option. Disabled options remain visible (including
+a saved, unavailable selection); pointer, typed settlement and arrow navigation
+cannot commit them. Permission loss closes the list and discards the draft.
+Use `id` with a label or `aria-label`/`aria-labelledby`; description and validation
+attributes reach the input. `inputRef` supports validation focus.
+
+For short fixed lists that must show every choice, set `maxSuggestions` to the
+list length; searchable catalogs may retain the default cap. Shared tables,
+chart settings, filters and schema select fields use this same component.
+
+The chevron is a pointer shortcut for the input. It is hidden from assistive technology so a wrapping field label does not include redundant button text; the combobox input owns the name and keyboard interaction.

package/docs/popover.md

@@ -95,9 +95,10 @@ that here would close both layers on one keypress.)
 Outside-mousedown does NOT stop propagation: the click still activates
 whatever was under it (click a second trigger → this popover closes and
 that one opens). Clicks on the anchor are never "outside" — the anchor's
-own click handler owns its toggle. The listener attach is deferred one
-tick so the interaction that opened the popover can't immediately close
-it (source parity).
+own click handler owns its toggle. Outside-click registration waits one tick so the opener cannot close its own
+menu. Escape registration runs in a layout effect, before the opening frame
+paints. Only the most recently opened popover handles Escape; a dialog opened
+above its owner keeps its own dismissal behavior.
 
 ## Styling
 
@@ -125,7 +126,7 @@ baked in 20px padding + 260px min-width for its one tenant, the calendar
   to the consuming control.
 - The opening interaction can be `click` or `mousedown`-driven; both are
   safe. But if you open programmatically and simultaneously flip other
-  document state, remember listeners attach a tick later.
+  document state, only outside-click registration waits a tick. Escape protection is immediate.
 - Placement flips only bottom→top (per source). If content can be taller
   than the viewport, cap and scroll it in YOUR content styles.
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "portal-mojo",
-    "version": "0.2.20",
+    "version": "0.2.21",
     "description": "React portal toolkit for django-mojo — typed client + params store, mission-control UI, dependency-free SVG charts, admin section bundles.",
     "type": "module",
     "license": "Apache-2.0",

package/src/admin/core/OperationsHelp.tsx

@@ -0,0 +1,10 @@
+import { useId, useRef, useState, type ReactNode } from 'react';
+import { Popover } from '../../ui/Popover';
+
+/** Keep explanatory copy one deliberate action away from the working surface. */
+export function OperationsHelp({ label, children }: { label: string; children: ReactNode }) {
+    const anchor = useRef<HTMLButtonElement>(null);
+    const [open, setOpen] = useState(false);
+    const id = useId();
+    return <><button ref={anchor} type="button" className="ops-help" aria-label={`About ${label}`} aria-expanded={open} aria-controls={open ? id : undefined} onClick={event => { event.preventDefault(); setOpen(value => !value); }}><i className="bi bi-question-circle" aria-hidden="true" /></button><Popover anchorRef={anchor} open={open} onClose={() => setOpen(false)} id={id} aria-label={`About ${label}`} className="ops-help-content">{children}</Popover></>;
+}

package/src/admin/core/index.ts

@@ -7,6 +7,7 @@ import { isChunkLoadError } from '../../ui/route-error';
 import { GroupContext } from '../../client/group-context';
 import { hasPermission, useMe } from '../../client/me';
 import type { PermSpec } from '../../client/model';
+import { AdminRouteContext, type AdminRouteContextValue } from './route-context';
 import { Guarded } from '../../ui/Guarded';
 import type { MenuConfig, MenuItem } from '../../ui/menu-registry';
 
@@ -127,7 +128,7 @@ function routeElement(route: AdminRoute): ReactNode {
         : createElement(route.component);
 }
 
-function guardedElement(section: AdminSection, route: AdminRoute, sections: readonly AdminSection[], mount: string): ReactNode {
+function guardedElement(section: AdminSection, route: AdminRoute, sections: readonly AdminSection[], mount: string, context: AdminRouteContextValue): ReactNode {
     const fallback = route.fallbackToFirstVisible
         ? createElement(AdminMountLanding, { sections: sections.filter((candidate) => candidate !== section), mount })
         : createElement(AdminDenied);
@@ -146,9 +147,9 @@ function guardedElement(section: AdminSection, route: AdminRoute, sections: read
     // navigation between packaged admin pages silently stopped rendering
     // (reproduced in both the reference portal and a consumer). The key
     // forces a fresh mount, and a fresh Suspense, per route.
-    return createElement(AdminGlobalScope, { key: relativePath(mount, section.basePath ?? section.id, route.path), children: createElement(Guarded, {
+    return createElement(AdminRouteContext.Provider, { key: relativePath(mount, section.basePath ?? section.id, route.path), value: context, children: createElement(AdminGlobalScope, { children: createElement(Guarded, {
         permission: section.permissions, fallback, children: routeGuarded,
-    }) });
+    }) }) });
 }
 
 /** Admin is global even when embedded beneath a product portal's provider. */
@@ -182,6 +183,7 @@ function AdminMountLanding({ sections, mount }: { sections: readonly AdminSectio
 export function adminSectionRoutes(sections: readonly AdminSection[], opts: { mount?: string } = {}): RouteObject[] {
     const mount = relativePath(opts.mount ?? '');
     const routes: RouteObject[] = [];
+    const context: AdminRouteContextValue = { mount: absolutePath(mount), paths: sections.flatMap((section) => section.routes.map((route) => absolutePath(mount, section.basePath ?? section.id, route.path))) };
     const rootSections = sections.filter((section) => relativePath(section.basePath ?? section.id) === '');
     const rootHasIndex = rootSections.some((section) => section.routes.some((route) => relativePath(route.path) === ''));
     if (mount && rootSections.length > 0 && !rootHasIndex) routes.push({
@@ -198,7 +200,7 @@ export function adminSectionRoutes(sections: readonly AdminSection[], opts: { mo
         });
         for (const route of section.routes) routes.push({
             path: relativePath(mount, base, route.path),
-            element: guardedElement(section, route, sections, mount),
+            element: guardedElement(section, route, sections, mount, context),
         });
     }
     return routes;

package/src/admin/core/route-context.ts

@@ -0,0 +1,6 @@
+import { createContext, useContext } from 'react';
+
+/** Internal registration facts for mount-aware links; never an authority decision. */
+export interface AdminRouteContextValue { mount: string; paths: readonly string[] }
+export const AdminRouteContext = createContext<AdminRouteContextValue | null>(null);
+export const useAdminRouteContext = () => useContext(AdminRouteContext);