portal-mojo 0.2.2 → 0.2.4

package/README.md

@@ -67,6 +67,9 @@ are identical in both forms.
   (`panel`, `chip`, `tbl`, …) styled by the app's `theme.css` under
   `data-theme="light"` **and** `"dark"` (reference set:
   `apps/portal/src/theme.css`).
+  This includes the `.guardrail*` rules behind `confirmGuardrail`
+  (reference: `apps/portal/src/theme/guardrail.css`) — the package ships no
+  CSS, so an app that opens a guardrail must carry that block.
 - **Tailwind scan of this package.** In an installed app's CSS:
   `@source "../node_modules/portal-mojo/src";` (adjust the relative path from
   that CSS file). Utility classes used in package components are generated by

package/docs/DetailView.md

@@ -37,7 +37,7 @@ of the toolkit it must render inside the app's `QueryClientProvider`
     contextMenu={[
         { label: 'Resend invite', icon: 'bi-envelope-paper', when: (u) => u?.last_login == null, onSelect: ... },
         { divider: true },
-        { label: 'Delete', icon: 'bi-trash', danger: true, permissions: ['manage_users', 'users'], onSelect: ... },
+        { label: 'Deactivate', icon: 'bi-pause-circle', permissions: ['manage_users', 'users'], disabled: pending, onSelect: ... },
     ]}
     sections={[
         { key: 'profile', label: 'Profile', icon: 'bi-person', render: () => <>…</> },
@@ -64,16 +64,16 @@ trap — those belong to the host dialog). The affordance follows the callback:
 - **Pass a history-back handler** when a routed record page should keep the
   ✕ as "back" (`onClose={() => navigate(-1)}` — linkable record routes read
   well this way).
-- **Modal hosts MUST pass it.** Inside `modal.detail` this ✕ is the modal's
-  only visible dismiss — the envelope has no header X of its own, only
-  Escape/backdrop — and TypeScript no longer enforces the prop. Omitting it
-  in a modal yields an Escape-only dialog.
+- **Modal hosts pass it** for the normal identity-header close. The flush
+  envelope supplies a fallback close during loading/error states without a
+  DetailView header; Escape/backdrop follow the live `canDismiss` gate.
 
-Sizing is the consuming app's concern: `.detail` carries
-`min-height`/`max-height: 82vh` in the app `theme.css` (base at
-`apps/portal/src/theme.css`) — page hosts relax it there. This is distinct
-from the C1 chrome (`.rail-badge`, `.dv-menu*`, `.dv-keep`) that lives in
-`theme/detailview.css` (see Pitfalls).
+Sizing is the consuming app's concern. Only `.mojo-modal-flush > .detail`
+receives a viewport-height limit; page/embedded bodies have no modal minimum
+or maximum. At narrow container widths an in-flow section button expands the
+same filtered rail entries, including rich, zero and dot badges. No native
+select stringification or second top-layer overlay is involved. The chrome
+lives in `theme/detailview.css` in both consuming apps.
 
 ## Permission-gated sections (fail-closed)
 
@@ -110,7 +110,7 @@ follows. There is no imperative handle.
 
 ## Header kebab menu
 
-`contextMenu?: Array<{ label, icon?, permissions?, when?, onSelect, danger? } | { divider: true }>`
+`contextMenu?: Array<{ label, icon?, permissions?, when?, onSelect, danger?, disabled? } | { divider: true }>`
 renders a three-dot button in the header gutter (before the close X, when one renders) that
 opens a `Popover` menu (`placement: bottom-end`, top-layer — works inside
 `modal.detail`). Filtering is `ContextMenu.visibleItems` parity:
@@ -172,10 +172,12 @@ permission behavior, not misconfig.
 | `FlatRow` | label + value row; `action` adds the edit pencil (`actionIcon` to override, e.g. `bi-plus-lg` for empty values) |
 | `SecurityItem` | icon + title + description row with a trailing slot (badge/button) |
 
-Conventions from the Users proof: pencil actions open `formModal` with
-current values as `initial`; a danger action lives in a `.danger-zone`
-block at the bottom of a section; fields the wire doesn't carry for other
-users (me-graph only: `has_passkey`, `requires_mfa`) don't get rows.
+Pencil actions open `formModal` with current values as `initial`. Current-record
+operations live in the header menu or focused dialogs; content rails never
+contain danger/action panes. Child-specific actions remain contextual. Fields
+the wire does not carry for other users (`has_passkey`, `requires_mfa`) do not
+get rows. See [Admin modal policy](admin-modals.md) for lifecycle exceptions.
+`active.disabled` and menu-entry `disabled` block repeat submission while pending.
 
 ## Pitfalls
 
@@ -192,3 +194,5 @@ users (me-graph only: `has_passkey`, `requires_mfa`) don't get rows.
 - The styles for the C1 chrome live in `apps/portal/src/theme/detailview.css`
   (`.rail-badge`, `.rail-dot`, `.dv-menu*`, `.dv-keep`) — tokens only,
   both themes.
+
+Keyboard selection in the compact section rail returns focus to the visible section toggle before the rail collapses. The desktop rail retains ordinary button focus.

package/docs/ModelTable.md

@@ -110,6 +110,32 @@ passed to every run — e.g. collect ONE disable reason) →
 / `"N succeeded, M failed"` (warning) / `"failed for all N"` → always
 clear selection + invalidate.
 
+`confirm` is the permission step and takes three forms:
+
+| `confirm` | Behaviour |
+|---|---|
+| `string` (default `"<label> N item(s)?"`) | `modal.confirm` with that copy; `danger` styles the button. |
+| `false` | No prompt. |
+| `(rows) => Promise<boolean>` | **Replaces** the built-in confirm — resolve `false` to cancel. `prepare` still runs after it. Open a `confirmGuardrail` here for a batch that takes a tenant dark or can't be undone. |
+
+Ask permission in `confirm`, collect input in `prepare` — don't fold a
+guardrail into `prepare` and return `null` to cancel; that conflates
+"nothing collected" with "declined".
+
+```tsx
+{
+    key: 'revoke', label: 'Remove access', danger: true,
+    confirm: (rows) => confirmGuardrail({
+        title: `Remove access for ${rows.length} members?`,
+        effect: <>They lose all access the moment each call lands.</>,
+        why: [<>Accounts stay; grants go — re-inviting restores a fresh preset, not the old unlocks.</>],
+        confirmText: `Remove ${rows.length}`,
+        typeToConfirm: rows.length >= 5 ? String(rows.length) : undefined,
+    }),
+    run: (row) => revoke(row),
+}
+```
+
 `runBatch` executes exactly once for selection-wide operations such as incident
 merge. A rejection produces one actionable error; cancellation mutates
 nothing. Selection clears and the endpoint invalidates after a non-cancelled

package/docs/README.md

@@ -41,8 +41,9 @@ everything: run the showcase (`npm run dev:showcase`) → **Develop → Componen
 | [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 |
+| [admin-modals.md](admin-modals.md) | Admin modal inventory, presentation, resource lifecycle and retained exception policy |
 | [DetailView.md](DetailView.md) | The UserView-style detail surface + row/section primitives |
-| [feedback.md](feedback.md) | Awaitable `modal.*`, `toast.*` |
+| [feedback.md](feedback.md) | Awaitable `modal.*`, `toast.*`, `confirmGuardrail` (the are-you-sure-and-here-is-why stop) |
 | [idioms.md](idioms.md) | ArmedButton (two-step confirm), `undoToast` (grace-period undo), `progressToast` — the dangerous-action trio |
 | [file-upload-ux.md](file-upload-ux.md) | Pure file validation, accessible picker/drop controls, bounded component-local upload queues, recovery, and completion callbacks |
 | [image-editor.md](image-editor.md) | Full-resolution crop/transform/filter composition, bounded history, PNG Blob results, modal helper, and ImageField pre-upload editing |

package/docs/admin-assistant.md

@@ -45,7 +45,9 @@ Import from `portal-mojo/admin`.
   the outcome is marked unknown, the list is refreshed, and the send is never
   retried automatically.
 - `POST /api/assistant/context` sends only `{model, pk}`. The returned conversation id is immediately fetched from `/api/assistant/conversation/<id>?graph=detail`; the client never synthesizes or reposts context text.
-- Conversation and Skill lists/details/deletes are imperative and component-local. They do not use `defineModel`, Query cache, `ModelTable`, a `RecordFeed` adapter, persistence, or exports.
+- Conversation and Skill lists/details are imperative and component-local.
+  Built-in Delete controls are absent. Skill deactivation/reactivation requires
+  `sys.view_admin` and reloads authoritative state; conversations retain history. They do not use `defineModel`, Query cache, `ModelTable`, a `RecordFeed` adapter, persistence, or exports.
 - A foreign conversation visible to an administrator is inspect-only. Only `conversation.user.id === me.id` enables continuation.
 
 `AssistantFeed` uses controlled `RecordFeed` plus the shared attachment queue at

package/docs/admin-credentials.md

@@ -187,3 +187,10 @@ the `group-admin.css` semantic rules in its theme entry, as the repository's
 The personal `/api/account/api_keys` page and `/api/auth/generate_api_key` flow
 are intentionally unchanged. This package domain owns only group-scoped
 `/api/group/apikey` credentials and `/api/group/webhook_subscriptions`.
+
+## Modal lifecycle convention
+
+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.

package/docs/admin-dashboard.md

@@ -6,7 +6,7 @@ The page uses only authoritative django-mojo signals: time series `user_activity
 
 Each panel owns an independent permission gate. A caller without metrics access can still see authorized incident, job, email, or login-geography panels, and no denied panel issues a request. Every dashboard query cache key includes the authenticated caller UID. Login geography starts at the previous 30-day date and deliberately omits `dr_end`, matching the backend's instant-bound semantics.
 
-The dashboard section contributes the single Overview → Dashboard menu entry. If the caller has none of the aggregate dashboard grants, the root route redirects to their first visible Admin route; if no Admin route is visible it renders Access denied.
+The dashboard section contributes a direct, top-level Dashboard menu entry instead of wrapping it in an Overview category. If the caller has none of the aggregate dashboard grants, the root route redirects to their first visible Admin route; if no Admin route is visible it renders Access denied.
 
 Attention links preserve the exact server filter in the URL:
 

package/docs/admin-dns.md

@@ -69,8 +69,7 @@ Verification is transactional at the UI boundary: a failed first link adds
 nothing; a failed rotation rejects, preserves the previous masks/encrypted
 pair, and refetches the now-unverified row with its provider error. Successful
 verification replaces the masks and marks the row verified. Viewer-only users
-can inspect safe rows; managers can link, rotate, activate/retire, and arm
-deletion.
+can inspect safe rows; managers can link, rotate and activate/retire; built-in deletion is absent.
 
 ## Themes and showcase
 
@@ -78,3 +77,10 @@ The page composes existing portal primitives and semantic tokens; it adds no
 fixed colors or theme-specific stylesheet. The executable three-leg showcase
 is **Develop → Components → Admin → DNS**: live manager lifecycle,
 viewer-only contract, and malformed-capability unavailable state.
+
+## Modal lifecycle convention
+
+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.

package/docs/admin-incidents.md

@@ -37,9 +37,16 @@ Rows, history, optimistic notes, mutation variables, curated copy surfaces, and
 exports pass through a recursive non-mutating sanitizer. It redacts normalized
 secret keys, auth/header blocks, JWT/Bearer values, sensitive URL/form params,
 and parsed bodies; evidence/traces are explicitly bounded. Heuristic redaction
-cannot guarantee arbitrary opaque prose, so raw JSON is not rendered or
-exported. `createSafeExporter` sanitizes before accumulation and projects only
-declared fields.
+cannot guarantee arbitrary opaque prose, so exports remain sanitized and
+project only declared fields through `createSafeExporter`.
+
+Incident and Event detail have one intentional operator-facing exception:
+**Raw data** shows the exact record returned by Django's authenticated detailed
+endpoint. That includes every top-level field, complete metadata, and expanded
+relations such as an Incident's `ip_info`. Each uses a separate TanStack Query
+cache key so the raw record cannot replace sanitized rows used by tables,
+drill-ins, exports, activity, or formatted sections. Django remains the
+authorization boundary for what those endpoints return.
 
 Before that recursive sanitizer runs, every history `media` value is positively
 rebuilt to exactly `id`, `filename`, `content_type`, and `category`; URLs,
@@ -53,6 +60,22 @@ the child reveals the parent. Ticket/rule/AI/network-response/dashboard controls
 remain excluded. Bouncer discovery stays category-prefix plus MUID search
 because its reporter writes MUID into incident details.
 
+Incidents with a source address add a formatted **Source** section. It promotes
+the detailed graph's `ip_info` into location/network, risk and reputation,
+effective block/whitelist state, checked-firewall reconciliation, observation
+times, and incident connection context. The address and action open the shared
+GeoIP dossier from the existing cache table (never a billed provider lookup).
+Missing enrichment stays visibly unknown; the exact `ip_info` object remains in
+Raw data.
+
+MojoSec events add a dedicated formatted section over the backend's fixed,
+server-derived `metadata.mojosec` projection. It promotes the detection and
+sensor identity, timing, policy revision, recommendation, and every currently
+validated evidence field—including sudo command provenance and receipt
+semantics. The separate Raw data section preserves the complete response for
+operator investigation. The top-level `geo_ip` display string is shown in
+Source when Django supplies it.
+
 ## Backend evidence
 
 The contract was checked against django-mojo source rather than inferred from

package/docs/admin-jobs.md

@@ -309,11 +309,14 @@ Two more corrections found while building, refining 6 and the gate table:
   blanket success.
 - **Purge is dry-run first.** The dialog runs `dry_run:true` and reports
   "N jobs would be deleted before `<cutoff>`"; only the armed confirm performs
-  the real run, which is read from `deleted`. Fixes the source's wrong
-  `data.count` read.
+  the real run, which is read from `deleted`. Preview parameters and generation
+  are captured; changing filters or replacing a preview resets arming. The
+  preview is an estimate: execution recalculates cutoff and includes cascaded
+  event/log rows. Inputs/dismissal lock during execution; failure requires a new
+  preview; actual cutoff and counts remain visible.
 - **Armed confirmations** for purge, clear-queue, clear-stuck,
-  cleanup-consumers, shutdown, broadcast `shutdown`, force-scheduler-lead and
-  task delete. `clear-queue` sends `confirm:"yes"` **only after** arming: the
+  cleanup-consumers, shutdown, broadcast `shutdown`, force-scheduler-lead. Scheduled-task Delete is absent; enabled state
+  preserves task-result history. `clear-queue` sends `confirm:"yes"` **only after** arming: the
   token is a server-side safety gate, and pre-satisfying it (as web-mojo did on
   every call) removes the safety rather than honouring it.
 - **KISS modals.** Job, runner, scheduled-task and task-result inspection are

package/docs/admin-messaging.md

@@ -25,9 +25,10 @@ Domain credentials are write-only. Secret-bearing saves, onboarding, audit,
 reconcile, and send are imperative and never use MutationCache. Audit is POST,
 has no automatic retry, and always refreshes because it persists readiness.
 Create reports only that the row was created: django-mojo's best-effort
-create-time audit/reconcile can fail after the row exists. Delete warns that
-local mailboxes and sent audit history disappear while SES/SNS/S3/DNS
-resources may remain.
+create-time audit/reconcile can fail after the row exists. Built-in domain,
+mailbox, template and contact deletion is absent so local audit history stays
+available. No archive field is invented. Mailbox inbound/outbound flags remain
+independent; support status changes use their existing status permission.
 
 Onboarding composes the shared `FormWizard`. Managed mode is available only
 when the optional DNS Admin integration resolves the normalized domain and
@@ -46,8 +47,8 @@ Stable mock identities (password `mojo`):
 
 - `email.operator@nativemojo.com` — email only (`comms`).
 - `support.viewer@nativemojo.com` — contact read only.
-- `support.manager@nativemojo.com` — contact read/update/delete.
-- `support.manage-only@nativemojo.com` — delete authority but intentionally no page view.
+- `support.manager@nativemojo.com` — contact read/status update; the low-level delete gate is not a UI action.
+- `support.manage-only@nativemojo.com` — low-level delete authority but intentionally no page view or status-write grant.
 - `showcase.operator@nativemojo.com` — executable showcase coverage.
 
 Live verification is read-only by default. Never create/edit/delete a domain,

package/docs/admin-modals.md

@@ -0,0 +1,122 @@
+# Admin modal presentation and lifecycle
+
+Admin inspection uses `modal.detail` and `DetailView`: identity, useful subtitle and
+chips, supported lifecycle state, a contextual header menu, and close. Navigation
+contains record content. Editors and operations use focused `modal.open` or
+`formModal` dialogs. Tables remain pages and retain their URL/query state.
+
+A current-record action belongs in the header menu or a focused dialog. Do not
+create Delete, Danger, Manage, Control, Operations or Actions navigation sections,
+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.
+
+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.
+Cancellation preserves data. Errors retain authoritative state and surface a
+refusal. Fresh authentication, write-only secrets and resource-specific imperative
+save/reconciliation helpers stay in force. Closing a view never cancels a server
+operation that has already started.
+
+The content rail becomes a collapsible in-flow button list at narrow **container**
+widths. Both presentations use the same permission-filtered sections, active key,
+rich ReactNode badges (including zero and dots), dividers and keep-alive state.
+Revoked sections unmount. Modal height limits use available dynamic viewport
+height; embedded/page hosts have no modal minimum or maximum and may omit
+`onClose`. A flush modal has a fallback close control while its body loads or
+fails; successful DetailView bodies supply the normal header close.
+
+## Executable inventory
+
+`scripts/admin-modal-inventory.json` records file, owner, launcher/helper, body,
+category, helper target, parent flow and expression fingerprint. The finite AST
+scanner follows imported aliases, namespace/destructured/generic modal calls,
+named forwarding helpers, literal dynamic imports and resolved section literals,
+arrays, conditionals, spreads and explicit pushes. Unrelated table columns are
+not section configurations. Assignment, unsupported mutation/property forwarding,
+unknown computed members and unclassified modal references fail review.
+
+`scripts/admin-modal-review.json` contains the reviewed semantics of generic
+modal bodies and destructive exceptions. Editors are classified by their actual
+body, not by whether the launcher happens to be `formModal`. Forwarders inherit
+categories from their target; a flow with multiple categories is `nested-flow`.
+Unknown syntax requires an exact expression/fingerprint mapping with a reason,
+classification and runtime case; stale mappings fail. This is a finite syntax
+contract, not a general JavaScript evaluator. When changing a surface, review the
+body, permission/lifecycle behavior and matching runtime evidence before updating
+the inventory using `node scripts/verify-admin-modals.mjs --write-inventory`.
+
+## Family map
+
+| Family | Record bodies and focused flows | Lifecycle policy |
+|---|---|---|
+| Groups and members | Group, Member, nested parent/subgroup/user; admission/invite, disable reason, auth configuration/reset | Existing disable/reactivate and inherited configuration semantics |
+| Users and credentials | User, group API key, webhook; profile/password/MFA/avatar/passkey/OAuth/personal keys, reveal/rate limits/rotation | Header lifecycle; deactivate group keys/webhooks; child credentials stay focused |
+| Bouncer and device intelligence | Signal, device, signature, login/location/GeoIP dossiers; signature editor, lookup/threat/enforcement | Evidence retained; signature lifecycle and explicit enforcement remain |
+| Security operations | Ticket, Incident, Event, RuleSet; feed/attachments, status/LLM/Assistant, conditions/handler editor | Header operations; properties remain content; RuleSet deactivation |
+| Monitoring and CloudWatch | Log, resource/dashboard/metrics drills, chart/data/range/permission dialogs | Read-only evidence; explicit permission reset |
+| Jobs | Job, runner, schedule, result; retry/cancel/payload/broadcast, schedule editor, queue maintenance | Schedule enabled state; runner controls focused; bounded purge only |
+| Network/geofence | IPSet, blocked IP, GeoIP; expiry/editor/sync/source refresh, policy/reset/allowlist | IPSet disable/enable; no unsupported IPSet DELETE |
+| DNS | Domain, certificate, credential, purchase; record set, credential rotation/link, revoke/onboard/contact | Retire credentials; certificate revoke; provider record-set removal only |
+| 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 |
+| 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
+
+| Resource | Built-in Admin behavior |
+|---|---|
+| User / Group / Member | Existing deactivate/reactivate actions; preserve reason, fresh-auth and membership rules |
+| Group API key / webhook | Toggle `is_active`; retain history; reveal and rotate remain credential-safe |
+| RuleSet / schedule | Disable/reactivate; no parent/result cascade deletion. Disabling a schedule does not cancel already published jobs |
+| IPSet | Existing enable/disable/sync/source refresh; server `CAN_DELETE=False` |
+| DNS credential | Retire/reactivate and rotate with `sys.manage_dns OR sys.security` |
+| FileManager | Existing active state and provider/owner operations via atomic imperative save |
+| File | No File, filename-confirmation or batch Delete; no active toggle. Delivery URLs and file-backed shortlinks do not consistently enforce File active state |
+| Shortlink / File share | Deactivate/reactivate using existing reconciler; preserve click history. Previously issued destinations cannot be recalled |
+| Email domain / template | Retain rows; no delete or invented archive flag |
+| Mailbox | Independent inbound/outbound flags; no delete or synthetic combined active flag |
+| Support contact | Existing status transition using the status gate; delete permission does not grant status-write authority |
+| Phone cache / SMS audit | Retain evidence; deleting a local row cannot recall a provider delivery |
+| Phone config | Existing `is_active` through write-only-secret-safe save; disabling restores backend fallback. Test mode is not a disable switch |
+| 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 |
+| Other logs/devices/history | Read-only by default, even where low-level REST supports DELETE |
+
+The public low-level exported delete APIs remain compatible. Built-in controls
+are a narrower product contract. File delivery enforcement, email archival and
+conversation archival require backend work before new lifecycle UI is added.
+
+## Retained irreversible operations
+
+| Operation | Authority and confirmation contract |
+|---|---|
+| Rule condition removal | `sys.manage_security OR sys.security`; selected children of the exact parent, freshly read before confirmation. ALL removal broadens matching, ANY removal narrows it while conditions remain; last removal makes either mode catch-all. Warn when active. After partial refusal, refresh parent and children and report counts |
+| OAuth unlink | Live owner or `sys.manage_users OR sys.users`, plus caller restriction; confirm provider and user. Removes association only; reconnect requires provider authorization. Preserve server lockout refusal |
+| Passkey removal | Live owner or user-management grant; confirm friendly name, relying party and user. Disable remains reversible; removal requires reenrollment and never erases a physical device |
+| Memory key removal | `sys.assistant`; selected group additionally requires inherited member `assistant` authority or superuser. Confirm tier/group/key, freeze scope, recheck authority, no optimistic deletion |
+| DNS record-set removal | DNS manage gate, provider capability and record coordinator. Preview all values, apex/service impact and exact name/type; stale-state preflight and reconcile failures; no domain deletion |
+| Empty bucket | `sys.manage_aws OR sys.files`, then fresh auth; header to focused armed confirmation and exact case-sensitive bucket name. Removes objects, versions, markers and multipart uploads; retains bucket. Display partial/unknown outcomes and always refresh |
+| Jobs retention purge | `sys.manage_jobs OR sys.jobs`; dry-run estimate bound to normalized days/status plus generation. Editing/replacing preview resets arming. Ignore stale/unmounted responses; lock inputs/dismissal during execution. Report actual cutoff and cascade-inclusive counts; rejection requires another preview |
+| Queue/consumer cleanup | Jobs manage grant, exact channel/scope and armed confirmation; queue clear sends `confirm:yes` only after consent and may cancel pending database jobs. Report partial outcomes |
+
+Other non-row removals retain their scoped editor semantics: rate-limit override
+clear, secret clear, inherited auth/geofence reset, metrics permission clear,
+registrant clear, geofence exemption removal, unsaved handler entries, local
+upload candidates and supported avatar/attachment detachment. Explain fallback
+and inheritance rather than promising restoration of discarded values.
+
+## Verification
+
+Run `verify:admin-modals`, `verify:admin-modal-scanner`,
+`verify:admin-modal-lifecycle` and `verify:admin-modal-mounted`. The mounted Node
+assertions use JSDOM and React StrictMode for asynchronous scope/effect behavior;
+they do not establish native dialog stacking, focus or layout. Use actual mock
+browser interactions for all family bodies, both themes, desktop/narrow,
+390px embedded hosts and short viewports, including nested dialogs, rich badges,
+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.

package/docs/admin-network-security.md

@@ -337,7 +337,7 @@ shows the server's own message.
 
 Anything that reaches the fleet is an `ArmedButton` whose armed label names the
 blast radius: the rules replace (with a plain-language clause diff), override
-removal, ipset enable / disable / sync / refresh / delete, allowlist removal and
+removal, ipset enable / disable / sync / refresh, allowlist removal and
 whitelist removal. Operations that need input (a reason, an expiry) use
 `formModal` instead — an armed button cannot collect input.
 
@@ -345,9 +345,9 @@ whitelist removal. Operations that need input (a reason, an expiry) use
 
 Do not add these back.
 
-1. **Batch delete of IP sets.** Multi-selecting kernel firewall sets and deleting
-   them in one irreversible action is exactly the shape #1097 warned about.
-   Delete is single-record and armed, from the detail modal.
+1. **IPSet deletion.** The backend has `CAN_DELETE=False`; both single-record
+   and batch Delete are absent. Header actions use the supported enabled state,
+   sync and source-refresh operations with focused confirmation.
 2. **Creating a block from the Blocked IPs table.** The backend supports it and
    web-mojo did not expose it either. Unblock and whitelist — both *relaxing* —
    are exposed.

package/docs/admin-phonehub.md

@@ -7,21 +7,39 @@ Import `PhoneHubPage`, the three individual pages, models, permission clauses, a
 - `POST /api/phonehub/number/normalize` is public. `normalizePhoneNumber()` accepts the backend result only when it is strict E.164.
 - `POST /api/phonehub/number/lookup` requires authentication and is offered only under `PHONE_LOOKUP_UI_PERMISSIONS`. The helper always normalizes first. For a new or expired record it omits `force_refresh` so the backend's normal lookup path refreshes once. For a known-fresh record it requires confirmation, then sends `force_refresh: true`. A successful response must provide a first lookup timestamp/count or advance one of them relative to the prior row; a 2xx stale row is rejected as provider failure evidence.
 - `PhoneNumberModel` requests the default graph but positively sanitizes every row before Query. Raw `lookup_data` is never retained or exported.
-- `SmsModel` is an audit-only surface. It requests the default graph and positively projects known display fields before Query; raw metadata, provider payloads, and provider message ids are discarded. Its client exporter is bounded and omits message bodies, errors, user/group details, and raw fields. There is no send UI.
-- `PhoneConfigModel` reads sanitized scalar/default-graph rows. Saves and `test_connection` use imperative, cache-free calls. Secret inputs are DOM refs, not React or Query state: blank means untouched and is omitted; replacement must be non-empty; clear sends `null` only after a separate confirmation. Responses are allowlisted before cache reconciliation. This surface edits existing provider credentials; it does not provision Django user/group API keys.
+- `SmsModel` reads SMS audit records. It requests the default graph and positively projects known display fields before Query; raw metadata, provider payloads, and provider message ids are discarded. Its client exporter is bounded and omits message bodies, errors, user/group details, and raw fields.
+- The SMS table's **Send SMS** action opens a focused composer for one recipient and a custom message. It normalizes the recipient through the existing public endpoint, then calls `POST /api/phonehub/sms/send` with exactly `{to_number, body}`. The message body is preserved verbatim. This is global sending through the effective system configuration/default sender: no ambient group, provider override, metadata, or audit-creation call. Drafts and allowlisted receipts stay local to the dialog, outside MutationCache. Sending rechecks the original actor and current permissions after normalization and immediately before transport. A synchronous guard blocks repeat clicks; native Escape/backdrop and Cancel are locked while pending.
+- A successful HTTP envelope can contain a `failed` or `undelivered` SMS record: render that status as failure. Other returned statuses remain literal; only `delivered` confirms delivery. The default graph does not expose `is_test`, so a `sent` receipt does not claim a real delivery. Transport/malformed-receipt failures retain the draft and ask the operator to check SMS Audit before retrying. Every attempted send invalidates the audit list; refresh failure cannot turn a completed send into a retry. Provider refusal is demonstrated in the mock with a recipient ending in `0000`; no mock request contacts a provider.
+- `PhoneConfigModel` reads sanitized scalar/default-graph rows. Saves and `test_connection` use imperative, cache-free calls. The editor follows web-mojo's provider-conditional layout: selecting Twilio, AWS SNS, or Mojo Remote shows and submits only that provider's connection fields. Mojo Remote uses `https://api.mojoverify.com` when the saved URL is unset or the editor is switched to Mojo; an explicitly configured custom URL is preserved. Secret inputs are DOM refs, not React or Query state: blank means untouched and is omitted; replacement must be non-empty; clear sends `null` only after a separate confirmation. Switching providers resets pending clears, and hidden provider credentials remain untouched. Responses are allowlisted before cache reconciliation. This surface edits existing provider credentials; it does not provision Django user/group API keys.
+
+Connection tests read the provider's `success` verdict, not the outer REST
+`status`. A failed or missing verdict is an error; `test_mode` is a warning
+that the provider was not contacted. Results persist inside the detail modal
+on both sections, alongside a toast. Scope is labeled in the header and
+Connection section. Editing is disabled while a connection test is pending, so an old response
+cannot certify replacement credentials. Saving clears the previous test result.
+The stored URL is shown literally; a saved URL plus `missing_credentials` for
+Mojo means the API key is absent. Re-enter it in Edit configuration and save;
+blank password inputs preserve existing values and do not prove a key exists.
 
 ## Exact permissions
 
-Every exported array is an ANY-of clause and retains the `sys.` UI namespace. Number view is `view_phone_numbers | manage_phone_numbers | comms | manage_users`; save is `manage_phone_numbers | comms | manage_users`; delete is only `manage_phone_numbers`. SMS view is `view_sms | manage_sms | comms | owner | manage_notifications`; save is `manage_sms | comms | manage_notifications`; delete is `manage_sms | manage_notifications`. Config view/save is `manage_phone_config | manage_groups | comms`; delete is `manage_phone_config | manage_groups`. The server remains authoritative.
+Every exported array is an ANY-of clause and retains the `sys.` UI namespace. Number view is `view_phone_numbers | manage_phone_numbers | comms | manage_users`; save is `manage_phone_numbers | comms | manage_users`; delete is only `manage_phone_numbers`. SMS view is `view_sms | manage_sms | comms | owner | manage_notifications`; save is `manage_sms | comms | manage_notifications`; delete is `manage_sms | manage_notifications`. Config view/save is `manage_phone_config | manage_groups | comms`; delete is `manage_phone_config | manage_groups`. These delete clauses describe low-level API compatibility; built-in number,
+SMS and config Delete controls are absent. The composer additionally requires
+`sys.send_sms | sys.comms`; audit read/manage grants alone never allow sending.
+It remains inside the existing SMS-view audience. Config deactivation uses the
+credential-safe imperative save path. The server remains authoritative.
 
 Group choices are fetched only with a separate global group-directory clause and are capped at 100 basic rows. Without that grant the editor does not issue a group-directory request and preserves the existing scope (or creates a system default).
 
 ## Provider and deletion reality
 
-Phone lookup is always the global Twilio Lookup integration; it is not group-configured. Stored Twilio and AWS credentials can be tested, but the current SMS send implementation only consults a per-group configuration for `provider="mojo"`. Twilio/AWS configurations otherwise fall through to global Twilio send settings, and AWS sending is not wired. `test_mode` only short-circuits connection testing; it does not block sending.
+Phone lookup uses the global Twilio Lookup integration. Mojo SMS delivery uses the selected PhoneConfig’s saved remote URL and encrypted API key. Twilio SMS delivery uses a complete saved credential pair from the selected config, rejects a partial pair, and falls back to global settings only when neither credential is stored. Its sender uses the config’s from number when set, otherwise the global default. AWS credentials can be stored and tested, but AWS delivery is not wired. `test_mode` only short-circuits connection testing; it does not block sending.
 
-An active group config wins; otherwise `PhoneConfig.get_for_group` falls back to the first active system default. Deleting or deactivating a group config restores that fallback. Deleting a group cascades its config and SMS rows. Deleting a user cascades their SMS rows. Deleting a config does not delete SMS audit rows. Deleting an SMS row affects only local audit storage and cannot recall provider delivery.
+An active group config wins; otherwise `PhoneConfig.get_for_group` falls back to the first active system default. Deactivating a group config restores that fallback; Admin exposes this reversible lifecycle. Deleting a group cascades its config and SMS rows. Deleting a user cascades their SMS rows. Deleting a config does not delete SMS audit rows. Deleting an SMS row affects only local audit storage and cannot recall provider delivery.
 
 ## Reuse rules
 
-Use KISS detail modals, not `:id` routes. Never add provider payloads to a model graph, cache, error, export, or request history. Never reuse `PhoneConfigModel.useSave()` for credentials. Do not add SMS sending or API-key provisioning to this admin area without a new reviewed contract.
+Use KISS detail modals, not `:id` routes. Never add provider payloads to a model graph, cache, error, export, or request history. Never reuse `PhoneConfigModel.useSave()` for credentials or `SmsModel.useSave()` to deliver messages. Sending follows the contract above; API-key provisioning remains separate.
+
+Verify with `npm run verify:admin-sms-compose`, `npm run verify:admin-phonehub`, and the Admin modal inventory check. The mounted composer regression covers permissions, concurrent clicks, permission revocation, exact global payloads, uncertain results, failed receipts, cache isolation and audit refresh. Use the Phone Hub showcase to click the composer in both themes and at narrow widths.

package/docs/admin-push.md

@@ -34,3 +34,10 @@ FCM writes are imperative and cache-free. A service account textarea is an uncon
 Connection testing calls only `POST /api/account/devices/push/config/<id>/test` with an empty body. The backend uses its dummy token to validate credentials. The portal never accepts a device token. It also does not expose `/send`, caller `/test`, delivery retry, device registration/unregistration, or any delete action.
 
 All four REST models have live `CAN_DELETE = false`; the mock returns 403 without removing or cascading anything. Templates/configs can be created and edited under their save clauses. Devices and deliveries remain investigative here.
+
+## Modal lifecycle convention
+
+See [Admin modal policy](admin-modals.md) for header actions, content-only
+sections, supported lifecycle fields and retained irreversible exceptions.
+Config/template active-state controls live in the detail header. Config saves
+retain write-only credential handling, and test sends keep their separate gate.

package/docs/admin-rules.md

@@ -85,3 +85,11 @@ The showcase demo is under **Admin → Rule Engine** and includes supported
 steps, notification target commas, duplicate/extra parameters, unsupported
 content, structural errors, move/remove actions, exact raw serialization, and
 the empty-chain case.
+
+## Modal lifecycle convention
+
+See [Admin modal policy](admin-modals.md) for header actions, content-only
+sections, supported lifecycle fields and retained irreversible exceptions.
+RuleSet parents deactivate. Child removal confirms fresh parent/mode/selection;
+ALL broadens, ANY narrows while nonempty, and the last removal is catch-all.
+Partial deletion refreshes authoritative parent and condition state.

package/docs/admin-shortlinks.md

@@ -18,7 +18,8 @@ Neither table supports search or export, and list parameters are allowlisted.
 
 ## Mutations and short URLs
 
-Create, active-state changes, and delete are imperative one-shot requests. They
+Create and active-state changes are imperative one-shot requests. Built-in
+Admin deletion is absent; exported low-level delete helpers remain compatible. They
 do not claim fresh-auth protection the backend does not provide and do not use
 retrying mutation hooks. Every outcome runs an authoritative reconciliation in
 `finally` semantics. If reconciliation itself fails, the UI warns that the

package/docs/admin-storage.md

@@ -65,7 +65,8 @@ FileManager DELETE and `check_public_access` are absent.
 `FileModel` forces the list graph and normal saves to `filename`, `is_public`,
 and explicit `group`. Group moves refetch and compare the authoritative FK.
 Selection supports public/private, explicit prepared group move, safe
-same-gesture download, and all-settled confirmed delete. Authorized operators
+same-gesture download. File deletion is absent from detail and batch controls;
+`is_active` is not presented as a safe revocation mechanism. Authorized operators
 also get **Add File** and a drag-only whole-page drop overlay. Both open one
 configuration modal; the bounded queue lives above it, so closing the modal
 does not cancel work or discard outcomes.

package/docs/auth.md

@@ -30,6 +30,34 @@ onAuth('logout', () => queryClient.invalidateQueries());   // every cached answe
 - Events for `onAuth`: `'login' | 'logout' | 'refreshed' | 'refresh-failed'
   | 'unauthorized'`.
 
+Both localStorage and sessionStorage keep the existing token keys. Refresh
+preserves the chosen storage, including sessions with only a valid refresh token
+at boot. Password login can replace malformed/expired credentials without the
+old dead session blocking its own recovery request.
+
+## Packaged Django Admin
+
+The generic auth client has no Admin side effects. The packaged app installs
+its app-local source coordinator before `initAuth`, awaits hosted exchange and
+source readiness before creating its router, and wraps all lazy loaders.
+It uses the page's own API origin and hosted auth. Source grants renew at 70%
+of their effective lifetime, independently of access-token refresh; focus and
+suspended-tab recovery recheck the grant. Eager recovery preserves the route.
+
+The app's `revokeAdminSourceSession()` first persists a nonsecret logout
+tombstone, clears credentials, then waits for the shared exclusive Web Lock and
+the completed `DELETE <admin>/_session` response. It must be awaited by app
+sign-out callers; generic `logout()` retains its existing synchronous semantics
+for ordinary toolkit consumers. All legacy/gate/Portal participants share
+`mojo:admin-source-session:v1` (lock and channel) and
+`mojo:admin-source-generation:v1` (authoritative localStorage record and per-tab
+sessionStorage binding). No credentials appear in coordination messages/storage.
+
+The complete app contract is in the producer repository's
+`docs/admin-artifact.md`; the frozen source fixture is
+`scripts/fixtures/admin-source-session-v1.json`. Django owns real cookie race
+and protected-browser acceptance against the exact artifact manifest digest.
+
 ## Hosted auth pages (the django-mojo "bouncer" pages)
 
 The backend serves themed login/register pages at `<origin>/auth` (behind

package/docs/client.md

@@ -10,6 +10,13 @@ import {
 
 ## Transport
 
+- The controlled Django Admin artifact explicitly selects packaged mode:
+  `isPackagedAdmin()` is true, `apiOrigin()` is `window.location.origin`, and
+  `usingMockTransport()` is false. Every API path stays `/api/...`, independently
+  of the Admin asset mount. Upload/provider credentials retain their existing
+  isolation; realtime, hosted auth, exports and Shortlinks reuse `apiOrigin()`.
+  This mode is set by the Admin producer, not by ordinary deployment dotenv.
+
 - `VITE_MOJO_API` unset → the in-memory mock answers every call
   (`npm run dev`). Set to a django-mojo origin → real backend
   (`npm run dev:live`, configured in `apps/portal/.env.live`).
@@ -27,6 +34,11 @@ status, semantic `error_code`, and structured safe failure evidence. Nothing out
 parses envelopes; `mojoCall(path, {method, params, body})` is the typed
 escape hatch for protocol modules and returns the unwrapped `Envelope`.
 
+`FetchOpts.beforeSend` is an optional synchronous final validity check, invoked
+after the auth gate refreshes credentials and before headers/network activity.
+The packaged app uses it to recheck its source-generation binding at the cookie
+boundary. Throwing rejects the request. Ordinary consumers need no callback.
+
 Live non-2xx responses and mock `status:false` envelopes preserve the same
 shape. Modern envelopes use numeric top-level `code` plus a string semantic
 `error_code`; numeric legacy `error_code` remains a status fallback. Failed