portal-mojo 0.1.0

package/docs/README.md

@@ -0,0 +1,98 @@
+# portal-mojo — component & client reference
+
+Reference docs for every export, written to be loaded into an AI coding
+context. Each page states the import path, the API surface, the wire
+contract it speaks, and the invariants that must hold. Live demos for
+everything: run the showcase (`npm run dev:showcase`) → **Develop → Components**.
+
+| Page | Covers |
+|---|---|
+| [client.md](client.md) | Transport, envelope boundary, `mojoList/Get/Save/Delete/Download/Metrics`, `mojoCall`, `mojoQueryDefaults`, mock vs live |
+| [defineModel.md](defineModel.md) | Model definitions + hooks, POST_SAVE_ACTIONS, `fetchOne`, cache keys |
+| [params.md](params.md) | `useTableParams` — the single source of truth for table state; persistence blob |
+| [auth.md](auth.md) | Login flows, token upkeep, hosted-auth (bouncer page) bridge, auth events |
+| [realtime.md](realtime.md) | Auth-challenged WebSocket lifecycle, heartbeat/backoff, refcounted topics, typed event projection, deterministic mock |
+| [auth-pages.md](auth-pages.md) | The in-app auth pages: routes + guard, `VITE_MOJO_AUTH` switch, fresh-auth (440 step-up) modal, MFA panel, password tools |
+| [admin-credentials.md](admin-credentials.md) | Group API keys and webhook subscriptions — dual-mount pages, permission registry, secret-safe create/reveal/rotation |
+| [admin-dashboard.md](admin-dashboard.md) | Package-owned global Admin landing, authoritative signals, independent gates, caller-isolated caches, and root fallback |
+| [admin-cloudwatch.md](admin-cloudwatch.md) | Global EC2/RDS/Redis CloudWatch charts, exact resource/fetch wires, constrained controls, refresh ownership, and modal details |
+| [admin-monitoring.md](admin-monitoring.md) | Monitoring Admin registration, logs, and exact Redis-backed metrics-permission mutations |
+| [admin-metrics-explorer.md](admin-metrics-explorer.md) | Read-only recorded-metrics discovery, full-slug adapters, KPI/fan-out/scalar contracts, and cache identity |
+| [admin-settings.md](admin-settings.md) | Runtime settings admin — direction-aware atomic writes, write-only secrets, and global/group scope |
+| [admin-bouncer.md](admin-bouncer.md) | Bouncer decisions, device investigations, and bot-signature administration with token-safe caching |
+| [admin-security-tickets.md](admin-security-tickets.md) | Ticket queue, KISS detail modal, notes, approvals, and Maestro sync contract |
+| [admin-incidents.md](admin-incidents.md) | Incident/event triage, forensic detail, merge semantics, and sanitized export boundary |
+| [admin-rules.md](admin-rules.md) | Always-inactive RuleSet authoring and the lossless, runtime-effective handler-chain builder |
+| [admin-members.md](admin-members.md) | Global membership table/detail, no-oracle admission, extensible grants, Group-detail composition, and unsupported-operation boundaries |
+| [admin-identity-users.md](admin-identity-users.md) | Global Users table and 14-section detail, system gates, action contracts, and one-time credential invariants |
+| [admin-devices-geoip.md](admin-devices-geoip.md) | Fleet device triage, the login-location world map with country drill-down, and the GeoIP dossier — expiry-aware enforcement, the never-cached raw provider record, and the backend traps the port encodes |
+| [admin-jobs.md](admin-jobs.md) | Jobs engine — runner fleet, per-channel queue depth, the segmented job table with armed cancel and republishing retry, the dry-run-first control plane, scheduled tasks with a global-only gate, and the thirteen backend corrections the port encodes |
+| [admin-network-security.md](admin-network-security.md) | Perimeter control — blocked IPs, the firewall log, kernel IP sets and the geofencing page (posture, rules, simulator, evidence, exemptions), with the DSL projection and every backend correction the port encodes |
+| [admin-dns.md](admin-dns.md) | Global DNS foundation — capability gates, safe typed resources, provider credential lifecycle, and secret/PII/material boundaries |
+| [admin-dns-records.md](admin-dns-records.md) | Domain inventory/KISS detail and id-less live DNS records — complete-set writes, explicit corrections, stale preflight, and provider behavior |
+| [admin-dns-certificates.md](admin-dns-certificates.md) | Certificate custody and ACME lifecycle — in-zone requests, delegation readiness, house gates, renewal-aware bounded polling, and the no-material boundary |
+| [admin-dns-registrar.md](admin-dns-registrar.md) | Domain search/quote/purchase, one-use token custody, durable-ledger reconciliation, scoped registrant PII, and manual House adoption |
+| [admin-storage.md](admin-storage.md) | Global S3 buckets, masked storage backends, explicit policy-backed File uploads, capability-safe FileView/shares, and finite rendition convergence |
+| [admin-shortlinks.md](admin-shortlinks.md) | Global shortlink operations, destination-free caches, bounded click history, and reconciled one-shot mutations |
+| [admin-messaging.md](admin-messaging.md) | SES domains/mailboxes/sent/templates plus public contact requests, with write-only credentials and offline HTML previews |
+| [admin-phonehub.md](admin-phonehub.md) | Global Phone Hub: evidence-backed lookup, sanitized SMS audits, and write-only provider configuration |
+| [admin-push.md](admin-push.md) | Global Push admin: caller stats, global metrics, strict audits, templates, and cache-free FCM configuration |
+| [admin-assistant.md](admin-assistant.md) | Global Assistant streaming selection/reconciliation, strict projectors/blocks, context reuse, skills, and explicit tiered memory |
+| [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 |
+| [DetailView.md](DetailView.md) | The UserView-style detail surface + row/section primitives |
+| [feedback.md](feedback.md) | Awaitable `modal.*`, `toast.*` |
+| [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 |
+| [loading.md](loading.md) | `Spinner`, `busy()`/`busyWhile()` blocking overlay, `ViewLoader`, `InlineLoader`, `Busy` — the anti-flash delay rule and skeleton-vs-loader guidance |
+| [popover.md](popover.md) | Anchored top-layer popover shell — placement, reposition, outside/Escape close, the dialog stacking story |
+| [taginput.md](taginput.md) | Chip/tag entry — CSV wire shape, keyboard matrix, validation + inline errors |
+| [combobox.md](combobox.md) | The house autocomplete — options with descriptions/meta, commit-only change pipeline, allowCustom, ARIA |
+| [location-address.md](location-address.md) | Six-endpoint LocationClient, private provider sessions, stale guards, controlled AddressField, atomic form patching |
+| [calendar.md](calendar.md) | The picker engine + `dateFns` namespace — three precisions, range anchor/preview, drill-down zoom |
+| [datepicker.md](datepicker.md) | Single-value picker shell — precisions, display-format stripping, clear/required/inline states |
+| [daterange.md](daterange.md) | Range picker + PresetRail — quick ranges, precision modes, the FilterBar daterange dialog |
+| [timezone-select.md](timezone-select.md) | IANA zone picker over ComboBox — offset labels, local default, alias tolerance, commit-only |
+| [timepicker.md](timepicker.md) | Stepper time entry — 12h/24h, minute step math, min/max, ISO/IANA/object serialization, embed mode |
+| [datetimepicker.md](datetimepicker.md) | Calendar + time + timezone in one popover — DST-correct offsets, boundary-day clamping |
+| [collection-select.md](collection-select.md) | Single record picker — server search, id→label hydration, null sentinel, shared cache keys |
+| [multiselect-dropdown.md](multiselect-dropdown.md) | Static checkbox dropdown — summarized trigger, Done footer, disabled options |
+| [collection-multiselect.md](collection-multiselect.md) | Server-backed multi-pick dropdown (panel variant available) — model binding, 400ms search, select/deselect-all, shift-click ranges |
+| [detail-primitives.md](detail-primitives.md) | StatusPanel, FlowStrip, Timeline, KnownFieldsCard, MetadataSection, StackTraceView — the detail-page pack |
+| [dataview.md](dataview.md) | Auto-inferring key/value grid + safe JSON viewer — schema or inference, nested records |
+| [markdown.md](markdown.md) | MarkdownView — server render via docit, allowlist sanitizer trust model, client fallback |
+| [record-feed.md](record-feed.md) | RecordFeed — ticket/incident adapters, chronological latest-window normalization, optimistic sends, controlled mode |
+| [right-panel.md](right-panel.md) | Explicit opt-in persistent shell slot — provider state, focus/Escape semantics, route preservation, responsive layout |
+| [charts.md](charts.md) | `SeriesChart`, `MetricsChart` (+stats/data dialogs, custom `dt_*` range), `MetricsMiniWidget`, `KPITile/KPIStrip`, `CircularProgress`, `PieChart`, `exportChartPng`, the metrics wire shape |
+| [worldmap.md](worldmap.md) | `WorldMap` — dependency-free geo map (no tiles/CDN/network), the projection math, `COUNTRY_CENTROIDS`/`COUNTRY_OPTIONS`, metrics-slug→country binding, and the injectable `land` seam |
+| [menus-and-access.md](menus-and-access.md) | Menu registry + SidebarNav; `useMe`/`useCan`/`Guarded`; group context |
+| [grouping-and-fmt.md](grouping-and-fmt.md) | `groupBy*` helpers, `fmt.*` formatters |
+
+## Non-negotiables (apply to every page below)
+
+1. **Tables are SERVER-driven.** Sort, search, filters and paging are wire
+   params django-mojo answers. Nothing filters/sorts rows client-side; if
+   you are about to `Array.filter` table rows, stop — write a param.
+2. **One envelope-unwrap boundary** (`client.ts`). A failed save REJECTS —
+   never resolve failure as success, never sniff `resp.data.data`.
+3. **Models are definitions, not instances** (`defineModel`). TanStack Query
+   owns cache/reactivity; there is no second ownership system.
+4. **Controlled inputs, one value pipeline.** A control can never display a
+   value its state doesn't hold. Unknown option values fall back to a
+   default WITH a `console.warn` — never to rendering nothing.
+5. **Both themes, day one.** Style with tokens from `apps/portal/src/theme.css`
+   (`--surface`, `--ink`, `--mute`, `--accent`, …) and verify under
+   `data-theme="light"` AND `"dark"`.
+6. **django-mojo datetimes are epoch SECONDS** on the wire. `fmt.*` accepts
+   them directly; do not `new Date(epochSeconds)` without ×1000.
+7. **The mock speaks the exact wire contract** (`src/client/mock.ts`). When a
+   contract detail changes, the mock changes in the same commit — it is the
+   contract's executable spec.
+
+## Working agreement
+
+Every new component ships with: a page here, a demo section in the
+playground (`apps/showcase/src/pages/components/`), and a browser
+verification in both themes.

package/docs/admin-assistant.md

@@ -0,0 +1,72 @@
+# Admin Assistant
+
+Import from `portal-mojo/admin`.
+
+`ASSISTANT_ADMIN_SECTION` registers Conversations, Skills, and Memory beneath the Assistant navigation group. Its section clause is global-only ANY-of `sys.view_admin` or `sys.assistant`; Memory narrows its route to `sys.assistant`, matching the backend. Active-group grants never reveal it. `AssistantLauncher` uses the section gate. `AssistantContextLauncher` additionally requires `sys.view_security` or `sys.security` and only accepts `incident.Incident` or `incident.Ticket`.
+
+## Conversation transport
+
+- An owned, text-only conversation uses realtime only when the shared transport
+  is authenticated and the caller locally has `sys.view_admin`, matching the
+  WebSocket handler's narrower server check. The client sends exactly
+  `{type:'assistant_message',message,conversation_id?}`. A caller with only
+  `sys.assistant`, any send with attachments, an unavailable socket, and a
+  foreign inspect-only conversation stay on REST. Messages are never
+  auto-resubmitted across paths.
+- `POST /api/assistant` sends `{message, conversation_id?, attachments?}`.
+  `attachments` is omitted for text-only sends or contains 1–5 unique positive
+  ids from completed authoritative queue references.
+- Realtime positively projects only `assistant_thinking`, `assistant_text`,
+  `assistant_tool_call`, `assistant_plan`, `assistant_plan_update`,
+  `assistant_response`, and `assistant_error`, whether they arrive directly or
+  through the transport's one wrapper boundary. Thinking, text, tool, plan,
+  update, and response events require a positive `conversation_id` and are
+  correlated to the active turn. `assistant_error` alone may omit it; such an
+  uncorrelated server error terminates the active turn. Tool state retains
+  bounded name/status/count only; raw input and the terminal `tool_calls_made`
+  list never enter UI state, caches, logs, or mock observations. Plans omit
+  tool inputs. Terminal duplication is checked only with the backend's
+  authoritative `message_id` (never a guessed local id).
+- A disconnect for a known conversation waits for reauthentication, then
+  reconciles from `/api/assistant/conversation/<id>?graph=detail`. A disconnect
+  during the first send before `assistant_thinking` supplies a conversation id
+  is explicitly **outcome unknown**: the conversation list is refreshed, the
+  optimistic message remains visibly uncertain, and the client never resends
+  or guesses a conversation. Server-side permission revocation remains
+  authoritative but can only be observed by the socket on a handled request or
+  reconnect; locally observed permission loss immediately clears this
+  consumer's transient stream/subscriptions without disabling the shared
+  provider.
+- `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.
+- 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
+capacity five. Its immutable groupless destination sends no manager/group/use
+selector. Partial upload batches retain completed references alongside
+failed/retryable rows; only completed ids are sent atomically with required
+text. Cancel/retry/recover/remove are real queue actions, duplicate local files
+collapse, and successful sends alone clear completed candidates. Permission
+loss, logout, owner/conversation change, or unmount disposes outstanding work.
+
+User history accepts only `type:'attachment'` blocks and positively rebuilds
+each File to `{id,filename,content_type,category}` before state/render. These
+chips have no URL or download action: they are metadata references and do not
+auto-ingest File contents. Assistant-generated `type:'file'` blocks remain a
+separate URL-bearing download-card schema. Other structured blocks retain their
+per-type schemas/caps; unknown/malformed blocks drop. Context references are
+inert and allowlisted. Action choices require confirmation, then their bounded
+value is sent attachment-free through the ordinary REST POST.
+
+## Memory
+
+Global and user tiers require the global Assistant grant. Group memory first chooses from a bounded normal `/api/group` request and supplies that id as normal request context (`?group=<id>`). A group id is never put in the memory body and ambient group state is never consulted. Keys are limited to 64 lowercase alphanumeric/colon/underscore/hyphen characters; values are limited to 500 characters.
+
+## Shell ownership
+
+The production Admin and showcase auth roots each mount one generic
+`RealtimeProvider`; it is auth-owned, not `sys.view_admin`-owned. The production
+Admin shell still mounts exactly one `RightPanelProvider` and one
+`RightPanelSlot`. Permission loss or logout closes and unmounts Assistant
+content. Incident and Ticket record details remain KISS modals; their Assistant
+buttons only create the separate Assistant panel session.

package/docs/admin-bouncer.md

@@ -0,0 +1,120 @@
+# Admin Bouncer
+
+`portal-mojo/admin` packages the global Bouncer operator surfaces: the signal
+decision feed, device reputation histories, and bot-signature CRUD. They mount
+through the same `AdminSection` contract in the standalone admin portal or an
+embedded `/system` admin area.
+
+## Routes and gates
+
+`BOUNCER_ADMIN_SECTION` has `basePath: 'security/bouncer'` and contributes:
+
+- `security/bouncer/signals` — decision feed and graph-qualified detail
+- `security/bouncer/devices` — fingerprints, risk tiers, related history
+- `security/bouncer/signatures` — signature create/edit/batch management
+
+All Bouncer gates are explicitly system-pinned. The view union mirrors the
+django-mojo models exactly:
+
+```ts
+[
+  'sys.manage_users',
+  'sys.view_security',
+  'sys.manage_security',
+  'sys.security',
+  'sys.users',
+]
+```
+
+Signature mutations use the narrower backend save union of
+`sys.manage_users | sys.manage_security | sys.security | sys.users`. A device's
+Incidents section is independently gated by `sys.view_security | sys.security`;
+an operator who can inspect Bouncer records through a user-management grant
+does not thereby receive incident access.
+
+The package admin barrel must register the section before the shell builds
+routes or menus:
+
+```ts
+import { BOUNCER_ADMIN_SECTION } from './bouncer';
+
+const sections = [BOUNCER_ADMIN_SECTION];
+adminSectionRoutes(sections, { mount: '/system' });
+adminSectionsMenu(sections, { mount: '/system' });
+```
+
+The generated route element and sidebar item apply the same gates, so direct
+URLs fail closed as well as hidden menu links.
+
+## Signal cache contract
+
+Lists force `graph=list` and every row passes through
+`sanitizeBouncerSignalRow()`. Details deliberately do not use the generic
+`useOne()` key: `useBouncerSignalDetail(id)` requests `graph=detail` and caches
+under:
+
+```ts
+['/api/account/bouncer/signal', 'one', id, { graph: 'detail' }]
+```
+
+This prevents a sparse default/list row from satisfying a detail viewer. The
+sanitizer deletes the backend-only top-level `token_nonce` before either list
+or detail data can enter TanStack Query. Portal types and renderers do not
+declare or display that field. django-mojo cleanup is tracked separately; it is
+not a portal dependency.
+
+`ModelTable` also passes the model-normalized list parameters to exports, not
+the raw URL parameters. Consequently a persisted or hand-edited
+`graph=detail` is removed and replaced by `graph=list` before a signal JSON or
+CSV export reaches the server; the detail-only field cannot bypass the Query
+sanitizer through the download path.
+
+Signal decisions include all live enum values: `allow`, `monitor`, `block`, and
+`log`. Detail shows identity layers, triggered rules, the nested default device
+and GeoIP graphs, and client/server JSON through the escaped `JsonBlock`
+boundary.
+
+## Device history
+
+Device details use the endpoint's default graph. Related signal and incident
+tables are intentionally small local components: their pagination lives in
+component state, not the URL parameter store, and they do not nest
+`ModelTable`. This keeps switching a detail rail section from rewriting or
+colliding with the parent page's table URL.
+
+Related signals query the signal endpoint by MUID. Related incidents query
+`/api/incident/incident` with `category__startswith=security:bouncer` and
+`search=<device muid>`, matching web-mojo and the model's `details` search
+contract. The reporter does not populate Incident `model_name`/`model_id`, so
+those fields must not be used as a relationship filter. Incident rows remain
+typed independently from incident events.
+Matching rows open the shared incident forensic detail while preserving this
+prefix-plus-MUID contract.
+
+## Signature writes
+
+The exact `sig_type` values are:
+
+```text
+ip | subnet_24 | subnet_16 | user_agent | fingerprint | signal_set
+```
+
+Create always sends `source: 'manual'`; edit never rewrites the source. The
+confidence parser accepts the full inclusive `0..100` range and preserves
+numeric zero. Enable and disable batches call ordinary per-record saves. Delete
+is intentionally absent: django-mojo's `BotSignature.RestMeta` does not declare
+`CAN_DELETE`, and the live endpoint rejects DELETE even though the mock once
+accepted it. No batch or action endpoints are invented, so partial failures use
+`ModelTable`'s normal `Promise.allSettled` reporting.
+
+## Styling and showcase
+
+The package emits semantic `bouncer-*` classes and imports no application CSS.
+Consumers must include `theme/admin-bouncer.css` after the shared token
+definitions. The repository keeps matching leaf files in `apps/portal` and
+`apps/showcase`, consistent with the current intentional theme duplication.
+
+The showcase's `AdminBouncerDemo` switches among the three real package pages
+so only one URL-backed top-level table is mounted at a time. Open signal/device
+rows to exercise details; use the signatures page to exercise ordinary mock
+mutations.

package/docs/admin-cloudwatch.md

@@ -0,0 +1,38 @@
+# Admin CloudWatch
+
+```tsx
+import {
+    CloudWatchDashboardPage, CloudWatchChart,
+    CLOUDWATCH_ADMIN_SECTION, loadCloudWatchSeries,
+} from 'portal-mojo/admin';
+```
+
+The package owns one global, no-group CloudWatch page at `/cloudwatch` standalone and `/system/cloudwatch` embedded. Its exact gate is `sys.manage_aws`. It contributes one Observability → CloudWatch navigation item and registers no resource-record routes; resource inspection stays in KISS detail modals.
+
+## Dashboard contract
+
+The page renders exactly twelve charts: four EC2 (`cpu`, `net_out`, `memory`, `disk`), four RDS (`cpu`, `conns`, `read_latency`, `write_latency`), and four ElastiCache Redis (`cpu`, `conns`, `cache_misses`, `cache_hits`). ELB and Lambda are explicitly absent because django-mojo's `ACCOUNT_NAMESPACE` exposes neither account type.
+
+The first four charts mount immediately and the other eight mount near the viewport. One page control owns manual and five-minute refreshes; child `MetricsChart`s hide their own refresh control and react to a shared `refreshSignal`. Resource detail metrics use the same pattern inside the modal.
+
+CloudWatch supports only `minutes`, `hours`, and `days` on this surface. `MetricsChart.allowedGranularities` omits the unsupported week/month controls while retaining the normal range, type, stats, and data-table controls.
+
+## Wire contracts
+
+`GET /api/aws/cloudwatch/resources` returns resource arrays at the envelope's top level, not under `data`:
+
+```json
+{"status":true,"ec2":[],"rds":[],"redis":[]}
+```
+
+Every object is allowlist-projected and validated inside the TanStack query function before it can enter cache. Redis `num_nodes` must be a positive integer. Provider errors are redacted and bounded before being thrown into query state.
+
+`GET /api/aws/cloudwatch/fetch` requires `account` and `category` and answers with the metrics-style nested map:
+
+```json
+{"status":true,"data":{"data":{"friendly-name":[1,2]},"labels":["10:00","11:00"]}}
+```
+
+The loader forwards only `account`, `category`, optional non-empty `slugs`, `granularity`, `stat`, and `dt_start`/`dt_end`. An empty slug selection omits `slugs` entirely so the backend discovers all resources; sending `slugs=` would mean an explicitly empty selection.
+
+EC2 requests may use the Name tag or raw instance ID. Responses always key the series by the friendly slug. A detail modal therefore requests the immutable raw ID but deliberately displays the friendly response name. Duplicate EC2 Name tags are a backend limitation: its reverse map chooses the last resource for a friendly-name request, and its response map collapses same-name series. The UI shows both friendly slug and raw ID in inventory/detail so operators can disambiguate and targets details by raw ID, but cannot recover two same-name response keys from one fetch.

package/docs/admin-credentials.md

@@ -0,0 +1,116 @@
+# Admin credentials
+
+`portal-mojo/admin` ships the group API-key and webhook-subscription domain as
+one reusable credential implementation. The same components back GroupDetail,
+the standalone admin portal, and an embedded `/system` admin mount.
+
+## Routes and access
+
+The built-in `ADMIN_SECTIONS` contribution mounts these standalone routes:
+
+- `/api-keys` — cross-group API keys
+- `/webhook-subscriptions` — cross-group webhook subscriptions
+
+Both the sidebar entries and generated React Router elements require
+`sys.manage_groups` or `sys.groups`. `adminSectionRoutes()` applies the section
+gate and the route gate independently, so a direct URL fails closed just like
+the menu. Embedded portals pass a mount to both helpers:
+
+```tsx
+const routes = adminSectionRoutes(ADMIN_SECTIONS, { mount: '/system' });
+const menu = adminSectionsMenu(ADMIN_SECTIONS, { mount: '/system' });
+```
+
+`AdminSection.basePath` defaults to the section id. A root-level section may
+use `basePath: ''`; its labeled routes become visible child links rather than
+claiming `/`. Prefixed sections receive an index redirect to the first route
+the current operator can see.
+
+## Group API keys
+
+```tsx
+import {
+  GroupApiKeysSection,
+  GroupApiKeysPage,
+  registerGroupApiKeyPermissions,
+} from 'portal-mojo/admin';
+
+<GroupApiKeysSection group={{ id: 42, name: 'Acme' }} />
+```
+
+Both fixed-group credential sections accept an optional permission override:
+
+```tsx
+<GroupApiKeysSection group={group} permission={GLOBAL_CREDENTIAL_PERMS} />
+<WebhookSubscriptionsSection group={group} permission={GLOBAL_CREDENTIAL_PERMS} />
+```
+
+Omitting `permission` preserves group-portal behavior through
+`GROUP_CREDENTIAL_PERMS`. The app-local global Group Admin passes the
+system-pinned `GLOBAL_CREDENTIAL_PERMS`; the wrapper checks that clause before
+mounting its list, so denied operators issue no credential background query.
+
+Creation uses `useCreateGroupApiKey()`, not the generic model save hook. The
+backend create echo contains `{token, ...row}`; the hook splits it immediately,
+writes only the safe row to TanStack Query, and passes the token through a
+one-shot callback while the mutation is still pending. MutationCache resolves
+with only the scrubbed row; the callback lifetime ends when the dialog closes.
+A later operator reveal is a deliberate
+`graph=token` request through `fetchApiKeyToken()`. django-mojo audits that graph
+as `api_key:token_read`, and the response never enters Query cache.
+
+All ordinary API-key lists force `graph=default`, discard URL/persisted
+`graph` and unsupported search params before creating a query key, and scrub
+token fields from every list/detail/save result before any cache write.
+
+Create sends only permission controls whose value is `true`. Edit compares only
+controls that were actually rendered and sends a partial permission dictionary;
+unknown or protected grants are therefore preserved, while a visible changed
+grant may send `false` to revoke it.
+
+The permission catalog is live and injectable:
+
+```ts
+registerGroupApiKeyPermissions([
+  { name: 'view_orders', label: 'View Orders' },
+  {
+    name: 'settle_orders',
+    label: 'Settle Orders',
+    grantPermissions: ['sys.manage_orders'],
+  },
+]);
+```
+
+Registration replaces the same permission name and appends new names. Mounted
+editors subscribe to changes. `grantPermissions` gates the control itself; the
+backend remains authoritative on every save.
+
+## Webhooks
+
+```tsx
+import { WebhookSubscriptionsSection } from 'portal-mojo/admin';
+
+<WebhookSubscriptionsSection group={{ id: 42, name: 'Acme' }} />
+```
+
+Webhook forms edit only `url`, `events`, and `is_active`. TagInput CSV values
+pass through `normalizeWebhookEvents()` before save. Metadata is intentionally
+absent: the default graph does not return it, so a generic edit form cannot seed
+or safely preserve the object.
+
+The signing secret belongs to the group, not one subscription. It is never
+fetched on render because the reveal endpoint auto-mints on first use. Reveal
+and confirmed rotation are explicit button actions.
+
+## Styling contract
+
+Credential components render the existing semantic `ga-*` classes and never
+import an application stylesheet. A consuming portal or showcase must include
+the `group-admin.css` semantic rules in its theme entry, as the repository's
+`apps/portal/src/theme.css` and `apps/showcase/src/theme.css` do today.
+
+## Personal keys are separate
+
+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`.

package/docs/admin-dashboard.md

@@ -0,0 +1,15 @@
+# Admin dashboard
+
+`AdminDashboardPage` is the package-owned global Admin landing at `/` in the standalone portal and `/system` when embedded. Import it, its data helpers, and `ADMIN_DASHBOARD_PERMISSIONS` from `portal-mojo/admin`.
+
+The page uses only authoritative django-mojo signals: time series `user_activity_day`, `group_activity_day`, `api_calls`, and `api_errors`; global scalars `total_users` and `total_groups`; and `size=0` counts for open incidents, failed jobs, and bounced sent email. Scalar values must be finite non-negative strings or numbers. Malformed values surface as errors rather than fabricated zeroes.
+
+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.
+
+Attention links preserve the exact server filter in the URL:
+
+- `/security/incidents?status=open`
+- `/jobs/list?status=failed`
+- `/email/sent?status=bounced`