portal-mojo 0.1.0 → 0.2.0

package/README.md

@@ -13,12 +13,53 @@ Live demos for everything: run `npm run dev:showcase` → **Develop → Componen
 
 ## Subpath surfaces
 
+The `client/runtime`, `ui/shell`, `admin/registry`, and Assistant launcher
+subpaths are stable, narrow package boundaries for first-party portal shells
+and advanced hosts. They intentionally expose only the runtime pieces needed
+at application startup; use the broader compatibility surfaces when those
+additional exports are required.
+
 | Subpath | Surface |
 |---|---|
 | `portal-mojo/client` | Typed django-mojo protocol layer: envelope unwrap at exactly one boundary (a failed save **rejects**), `start`/`size` paging, `'-field'` sort, Django lookups, the URL-synced `useTableParams` store (single source of truth for table state), TanStack Query hooks. Auth client: password / magic-link / passkey login, forgot/reset, cross-origin handoff (`?auth_code=` scrub-before-network), single-flight refresh + pre-request gate (synthetic-401 reject, `/api/token/refresh` recursion guard), `X-Mojo-UID` device header, `getAuthSnapshot`/`subscribeAuth` for React. Auth-challenged realtime transport: `RealtimeProvider`/`RealtimeClient`, refcounted topics, typed event projection, and a deterministic mock. Boot auth with `initAuth()`. The in-memory HTTP mock transport lives here too — it is the wire contract's executable spec and evolves in lockstep with the client (any seeded active user logs in with email + `"mojo"`). |
+| `portal-mojo/client/runtime` | Stable, narrow client boundary for first-party application runtime code. It omits eager mock-test controls; the mock transport itself loads on the first mock request. |
 | `portal-mojo/ui` | Mission-control UI: `ModelTable`, `FilterBar`/`FilterPills`, `SchemaForm`/`formModal`, `DetailView`, `RecordFeed`, `AttachmentQueue`/`UploadQueue`, `ImageEditor`/`imageEditorModal`, awaitable native-`<dialog>` `modal`, `toast`, `ThemeProvider`, `Guarded` (permission slot), `GroupSwitcher` (searchable tree selector), `RequiresGroup`, the sidebar engine (`registerMenus`/`setDefaultMenu` registry + `SidebarNav` — static or searchable accordion with a compact icon rail; global and group scopes are explicit), `Badge`/`MetricCard`/`Spark`, `fmt` formatter namespace. |
+| `portal-mojo/ui/shell` | Stable, narrow boundary for application-shell primitives: theme, guards, menus/sidebar, right panel, modal/toast hosts, password helpers, and formatters. |
 | `portal-mojo/charts` | Dependency-free SVG charts: `SeriesChart` (line/bar/area, stacked bars, legend toggle, crosshair tooltip) and `MetricsChart` (granularity/range/type control bar for `/api/metrics/fetch`). |
-| `portal-mojo/admin` | Global Admin **section bundles**, dual-mount: the standalone back-office portal mounts all of them at root; a product portal embeds them under a global "System" area. `AdminSection` contract + `adminSectionsMenu()` (sections → domain-grouped sidebar menu, mount-point-relative, with section + route permission clauses). Admin scope masks active-group membership even when embedded. Reusable domains include credentials, monitoring, security operations, settings, Bouncer, Members, and the Assistant control plane with narrow realtime streaming plus authoritative REST fallback/reconciliation. |
+| `portal-mojo/admin/core` | Side-effect-light Admin contracts and host: `AdminSection`, the discriminated `AdminRoute` XOR, `adminSectionRoutes`, `adminSectionsMenu`, and `AdminLazyPage`. |
+| `portal-mojo/admin/registry` | Stable, narrow built-in `ADMIN_SECTIONS` roster for first-party hosts, without broad page barrels. It installs the optional Email→DNS adapter synchronously so communications routes work before DNS navigation. |
+| `portal-mojo/admin/assistant/launcher` | Stable, narrow shell launcher boundary without the Assistant page/data barrel. |
+| `portal-mojo/admin/{identity,security,observability,operations,infrastructure,communications,assistant}` | Narrow domain APIs and registry contributions. Built-in routes use leaf-module `loadComponent` loaders; importing `infrastructure` synchronously installs the optional Email→DNS adapter. |
+| `portal-mojo/admin` | Compatibility aggregate containing every historical named export and the stable `ADMIN_SECTIONS` roster. It intentionally installs the DNS adapter and Rule field registration synchronously. New code should prefer `admin/core` plus the domains it consumes. |
+
+### Admin route contract
+
+Routes are an explicit XOR. A host-owned page stays synchronous; a packaged
+page supplies a separately named loader. The host never guesses from whether a
+value is callable.
+
+```tsx
+const extension: AdminSection = {
+  id: 'billing', title: 'Billing', icon: 'bi-receipt',
+  permissions: ['sys.billing'],
+  routes: [{ path: '', component: BillingHome }],
+};
+
+const packaged: AdminSection = {
+  id: 'audit', title: 'Audit', icon: 'bi-journal-text',
+  permissions: ['sys.view_logs'],
+  routes: [{
+    path: '',
+    loadComponent: () => import('./AuditPage').then(({ AuditPage }) => ({ default: AuditPage })),
+  }],
+};
+```
+
+Lazy loading, chunk-error recovery, and retry render inside section and route
+permission guards, so a denied route never invokes its loader. Routes stay
+mount-relative: pass no mount for `#/…`, or `{mount: '/system'}` for the same
+sections under `#/system/…`. Root denial and first-visible fallback semantics
+are identical in both forms.
 
 ## What the consuming app must provide
 

package/docs/DetailView.md

@@ -8,7 +8,7 @@ import {
 ```
 
 The record-detail surface: identity header (avatar, title, subtitle,
-chips, optional active switch, kebab menu, close) over a left rail of
+chips, optional active switch, kebab menu, optional close) over a left rail of
 sections with side-label dividers. Open it inside `modal.detail(...)` for
 the standard row-click experience. Ported from web-mojo `SideNavView.js`
 (sections, gating, badges) + `ContextMenu.js` (the kebab).
@@ -31,7 +31,7 @@ of the toolkit it must render inside the app's `QueryClientProvider`
     title={...} subtitle={u.email}
     chips={[{ icon: 'bi-patch-check-fill', text: 'Email', tone: 'success' }]}
     active={{ value: u.is_active, onChange: (next) => ... }}
-    onClose={onClose}
+    onClose={onClose}   // optional — omit for page hosts (no ✕ renders)
     badges={{ sessions: openSessions }}
     menuContext={u}
     contextMenu={[
@@ -54,6 +54,27 @@ of the toolkit it must render inside the app's `QueryClientProvider`
   `{divider: 'Label'}` side-labels.
 - `initialSection` picks the starting rail entry.
 
+## Page embedding — `onClose` is optional
+
+The ✕ is the component's only modal coupling (no Escape handling, no focus
+trap — those belong to the host dialog). The affordance follows the callback:
+
+- **Omit `onClose`** for a routed-page/embedded host — no close affordance
+  renders and no CSS overrides are needed.
+- **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.
+
+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).
+
 ## Permission-gated sections (fail-closed)
 
 `Section.permissions` is a permission name or an ANY-of array, resolved
@@ -90,7 +111,7 @@ follows. There is no imperative handle.
 ## Header kebab menu
 
 `contextMenu?: Array<{ label, icon?, permissions?, when?, onSelect, danger? } | { divider: true }>`
-renders a three-dot button in the header gutter (before the close X) that
+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:
 

package/docs/ModelTable.md

@@ -45,6 +45,50 @@ drives the sort param. `render` is the ONE cell prop (no formatter/template
 aliases). `hideable: false` locks a column in the chooser (identity
 columns).
 
+**Cells never crash the page.** django-mojo graphs expand FK fields
+per-graph, so a cell value can flip from `"GC"` to `{id, code, name, …}`
+without a frontend change. The default (no-`render`) leg degrades an object
+to `fmt.code(value)` or a visible `[object]` marker plus one `console.warn`
+naming the column. A custom `render` runs inside `RenderGuard` — a per-cell
+error boundary — so a callback that throws on the new shape, or returns an
+element with the raw object nested inside, degrades to a dim `[render
+error]` marker instead of white-screening. `rowExpand` and
+`groupHeaderLabel` are guarded the same way. Render FK-ish fields through
+`fmt.code()` (see grouping-and-fmt.md) so the cell shows the code instead
+of a marker.
+
+## fixedParams — locked scope
+
+`fixedParams?: Params | null` is table IDENTITY, not table state: tenant /
+group / graph scope merged into every wire request (list, export, exporter
+callback) AFTER filter state and model normalization. It never renders a
+pill, survives Clear all, is excluded from view persistence and the URL —
+a bookmarked `?group=9` or a persisted view saved before the page was
+scope-migrated is silently dropped rather than resurrected as a removable
+filter.
+
+- **Scope belongs in `fixedParams`; user-editable filter DEFAULTS belong
+  in `defaultParams`.** A tenant key in `defaultParams` is one click from
+  an un-scoped table — the bug class this prop closes. Passing the same
+  key in both warns once (the `defaultParams` copy is dead).
+- **The merge runs after `normalizeListParams`** — positive-projection
+  normalizers would otherwise silently strip an un-allowlisted scope key
+  and the request would go out unscoped. Consequence: `fixedParams.graph`
+  overrides a normalizer-pinned graph (that's the documented
+  `graph: 'full'` use).
+- **`null` means "scope pending"**: the table renders its skeleton and
+  fetches nothing until scope resolves — an async-scoped table must never
+  fire (and cache) an unscoped first request. `undefined` means the table
+  is unscoped by design and fetches normally.
+- **Reserved keys can't be locked** (`start`/`size`/`page`/`sort`/
+  `search`) — they'd fight the pager/sort/search UI; ignored with one
+  console.warn.
+- **A scope flip is a filter change to the user**: changing `fixedParams`
+  resets to page 1 and clears row selection (a batch action must never
+  fire against ids selected under the previous scope).
+- **Presets must not carry fixed keys** — their writes are scrubbed from
+  filter state, so such a preset never matches as active.
+
 ## Filters (see also forms.md dialog types)
 
 `FilterDef` types: `text` (`__icontains`), `select`, `multiselect`

package/docs/README.md

@@ -62,6 +62,7 @@ everything: run the showcase (`npm run dev:showcase`) → **Develop → Componen
 | [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 |
+| [route-error.md](route-error.md) | `RouteError`/`RouteErrorCard` — the route-level last-resort error card, the error-handling ladder, two-level `errorElement` wiring |
 | [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 |

package/docs/admin-assistant.md

@@ -9,20 +9,22 @@ Import from `portal-mojo/admin`.
 - 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
+  `{type:'assistant_message',message,request_id,conversation_id?}`, with a fresh
+  canonical UUID per turn. 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`,
+- Realtime accepts these Assistant event shapes only as exact direct frames;
+  topic-wrapped or broadcast Assistant-shaped traffic is ignored. It 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
+  `assistant_response`, and `assistant_error`. Thinking, text, tool, plan,
+  update, response, and error events require the exact `request_id` sent for
+  the active turn. Non-error events also require a positive `conversation_id`;
+  an error may omit only the conversation id. 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
@@ -37,6 +39,11 @@ Import from `portal-mojo/admin`.
   reconnect; locally observed permission loss immediately clears this
   consumer's transient stream/subscriptions without disabling the shared
   provider.
+- Direct-source binding and the echoed `request_id` jointly isolate concurrent
+  turns, including turns in the same conversation. Missing or mismatched IDs
+  are ignored; if no correlated acknowledgement arrives within ten seconds,
+  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.
 - A foreign conversation visible to an administrator is inspect-only. Only `conversation.user.id === me.id` enables continuation.

package/docs/charts.md

@@ -58,6 +58,13 @@ daterange triple — `/api/metrics/fetch` ignores it silently. web-mojo sent
 />
 ```
 
+> **Money in charts:** metric values reach `valueFormatter` (and the KPITile
+> `formatter`) as plain numbers with no unit semantics. If a series carries
+> money, keep it in integer minor units end-to-end and write
+> `(n) => fmt.currency(n)` — never pre-convert to dollars (renders 100×
+> small). Avg/Median stats and "nice" Y-ticks pass DERIVED, possibly
+> fractional cents; `fmt.currency` rounds them for display.
+
 Legend entries toggle series; hover shows the crosshair index tooltip;
 ticks are "nice"-rounded; container width is measured (no viewBox
 smearing).

package/docs/client.md

@@ -61,6 +61,115 @@ Mock-only contract controls are exported in development: call
 `armMockReauth(method, path)` to make one authenticated method+path match
 answer 440. Ordinary requests and real transports are unaffected.
 
+## Actions — `mojoAction` / `readActionResult`
+
+django-mojo POST_SAVE_ACTION handlers can refuse **inside an HTTP 200**, in
+two wire shapes — flat `{success:false, code, error}` or wrapped
+`{status:true, data:{success:false, …}}` — which the unwrap boundary
+deliberately passes through (envelope `status:false` is a different failure
+and already rejects). Never hand-sniff these shapes; there is one reader:
+
+- `readActionResult(body)` → `{ok, code, error, payload}`. `payload` merges
+  the envelope with the action dict (action fields win), so one-shot
+  secrets/counters read from one place whichever direction they rode.
+  Payload `status:false` (the `revoke_sessions` spelling) also refuses;
+  bodies with no flag resolve `ok: true`.
+- `mojoAction(endpoint, id, action, payload?)` — the raw-path primitive:
+  POSTs `{[action]: payload ?? true}` to `endpoint/<id>` under
+  `withFreshAuth`, normalizes the reply, and **REJECTS with
+  `ActionRefusedError`** (a `MojoError` with `status: 200`, `errorCode` =
+  the refusal code, `message` = the server's text) on an inside-the-200
+  refusal. Returns the `ActionResult` on success.
+
+Which to use: **model-bound → `defineModel(...).useAction`** (same
+normalizer + cache maintenance; see defineModel.md "Action refusals" for
+`refusal: 'reject' | 'return'`); **raw one-off action POST →
+`mojoAction`**; **never** parse `success`/`status` off an action body at a
+call site. Diagnostics whose flag is a result datum (connection testers)
+either declare `refusal:'return'` on the model or stay as bespoke raw
+readers with a comment.
+
+## Endpoint scoping — the middle tier
+
+The model layer scopes reliably; everything hand-rolled with `useQuery` +
+`mojoCall` historically forgot the scope param — the largest bug class in the
+first consumer audit (eight files, every one a raw read or verb missing its
+`group`). The middle tier makes the raw path as safe as the blessed one:
+apps *declare* their scoped endpoint families once, and every helper —
+plus a dev tripwire in the transport itself — enforces the declaration.
+
+### `registerEndpointScope(prefix | prefix[], {key?, required?, format?})`
+
+App-side, at boot (before the first fetch). Longest registered prefix wins;
+re-registering a prefix replaces it. `key` defaults to `'group'`, `required`
+defaults to `true`; `format` maps the group id to the wire value for
+spellings like `account=group-<pk>`:
+
+```ts
+registerEndpointScope('/api/wallet/', { key: 'group' });
+registerEndpointScope('/api/mojoverify/', { key: 'group' });
+registerEndpointScope('/api/store/order', { key: 'gid' });
+registerEndpointScope('/api/billing/', { key: 'account', format: (id) => `group-${id}` });
+```
+
+The base admin portal registers none — it is deliberately no-group. A
+`required` scope that cannot be resolved fails loudly (throw or disabled
+query, below); `required: false` families only inject when a group is active.
+
+### Where the group id comes from
+
+`GroupProvider` **owns** the active group — context stays the React-side
+source of truth — and mirrors its *resolved* group into a module-level
+signal (`setActiveGroupSignal` / `getActiveGroupId`) so plain functions can
+read it. Do not read `localStorage.active_group_id` yourself instead: the
+URL `?group=` param BEATS the stored id (group.tsx resolution order), and
+only the provider computes that resolution — the signal always reflects it.
+An explicit `group` option on any helper beats the signal.
+
+### `useScopedQuery<T>(path, params?, {read?, group?, ...queryOpts})`
+
+`useQuery` over a scoped GET. The registered spelling is injected into the
+request params, and the group id rides the query key —
+`[path, params, gid]` — so a brand switch can never serve another brand's
+cached rows, while invalidation by `[path]` prefix keeps working. Keep that
+key discipline if you write a raw scoped query by hand.
+
+When a REQUIRED scope has no active group, the query renders **disabled** —
+and a disabled query has *neither data nor error*. Do not draw an empty box
+or a spinner that never resolves: state the wait honestly at the call site
+("select a brand to load …").
+
+### `mojoScopedCall` / `mojoRpc`
+
+- `mojoScopedCall(path, opts)` — `mojoCall` with the registered scope
+  injected: into `params` for parameter-only requests, into the `body` when
+  a body is present. Throws in dev when a REQUIRED scope cannot be resolved
+  — an unscoped write to a scoped family must never leave the machine.
+- `mojoRpc<T>(path, body, opts?)` — the scoped RPC verb: POST `body` under
+  `withFreshAuth` with the scope injected; resolves `env.data as T`.
+  Action-shaped `{key: payload}` saves belong to `mojoAction`, not here.
+
+### `mojoAction` body injection
+
+`mojoAction(endpoint, id, action, payload?)` consults the same registry:
+for a scope-registered family with an active group, the scope key is
+injected into the action POST body alongside `{[action]: payload}` — the
+wallet-verbs class: actions the backend refuses for brand-scoped operators
+without `group`. With nothing registered (the base admin) the injection is
+inert.
+
+### The dev tripwire — and `unscoped: true`
+
+`assertScoped` runs inside the unwrap boundary on **every** dev request: a
+registered-REQUIRED path whose params *and* body both lack the scope key
+throws before the request leaves the machine, naming the registration and
+the fix. So even a raw `mojoCall` that bypasses every helper still fails at
+the desk, not in production data. Passing the scope explicitly satisfies it;
+for the rare genuinely-global call to a scoped family, mark it
+`{ unscoped: true }` — an explicit, greppable opt-out. Production builds
+skip the check (`import.meta.env.DEV` only); it is a development tripwire,
+not a runtime gate.
+
 ## Mock admin contracts
 
 The mock carries measured GroupView/admin transports, not UI-shaped

package/docs/dataview.md

@@ -126,7 +126,7 @@ grids stops being readable.
 | `email` | `<a href="mailto:…">` |
 | `url` / `file` | `<a target="_blank" rel="noopener noreferrer">` + external-link icon |
 | `phone` | `<a href="tel:…">` around `fmt.phone` (digits + `+` only in the href) |
-| `currency` | `fmt.currency`; `EUR`/`GBP` from the key, else `USD`. **Integer → cents, fractional → major units** |
+| `currency` | `fmt.currency`; `EUR`/`GBP` from the key, else `USD`. **Integer (or integer-string) → cents; fractional (number or string) → major units** |
 | `filesize` | `fmt.filesize` (decimal KB/MB/GB) |
 | `percent` | `fmt.percent`; **`\|v\| ≤ 1` is scaled ×100**, anything larger is already a percentage |
 | `number` | `count`/`total`/`followers`/`views` → `fmt.compact` at ≥1000 else `fmt.number`; `score`/`rating` → `fmt.number(v, 1)` when fractional; `version` / the word `id` → verbatim; else `fmt.number` |
@@ -182,8 +182,11 @@ Truncated text keeps the full value on a `title` attribute.
 
 - **Money is CENTS when it's an integer.** django-mojo stores minor units,
   so `plan_amount: 129900` → `$1,299.00` while `overage_price: 4.75` →
-  `$4.75`. A record that breaks that convention needs an explicit
-  `format`.
+  `$4.75` — and wire decimal STRINGS classify the same way, so
+  `overage_price: '4.75'` (the DecimalField shape) is also `$4.75`. A
+  whole-dollar decimal string (`'12.00'`) parses to an integer and reads as
+  cents (`$0.12`) — inherently ambiguous; a record that breaks the
+  convention needs an explicit `format`.
 - **Percent auto-scales below 1.** `error_rate: 0.0182` → `2%`;
   `error_rate: 12` → `12%`. A ratio that legitimately exceeds 1 needs an
   explicit `format`.

package/docs/defineModel.md

@@ -55,16 +55,63 @@ action-specific payload. **Which one is DECLARED, never sniffed:**
 
 - `response: 'row'` (default) → `ActionOutcome.row` is the refreshed record
   (written through to the cache).
-- `response: 'payload'` → `row` is null; read `outcome.body` (e.g.
-  `body.message` for `revoke_sessions` — toast the server's text).
+- `response: 'payload'` → `row` is null; read `outcome.result.payload`
+  (e.g. `result.payload.message` for `revoke_sessions` — toast the
+  server's text). `outcome.body` remains the raw unwrapped envelope.
 
 Invoke: `await disableAction.mutateAsync({ id, payload: { reason: 'abuse' } })`.
 `payload` defaults to `{}`; handlers treat the value as a dict. Errors
 (e.g. `"reason must be one of: abuse, admin"`) REJECT with the server's
 message.
 
+## Action refusals
+
+django-mojo action handlers can refuse **inside an HTTP 200**. The reply
+reaches the client in one of two wire shapes:
+
+```jsonc
+{"success": false, "code": "ALREADY_DISABLED", "error": "…"}          // flat (JsonResponse verbatim)
+{"status": true, "data": {"success": false, "code": "…", "error": "…"}} // wrapped (save-and-respond)
+```
+
+This is NOT the envelope failure: envelope-level `status:false` already
+rejects at the unwrap boundary (`MojoError`). The action-refusal layer sits
+above it and is handled by `useAction` automatically:
+
+- **`refusal: 'reject'` (default)** — a `success:false` (or payload
+  `status:false`) reply REJECTS with **`ActionRefusedError`**, so a refusal
+  can never read as done. The error extends `MojoError` with `status: 200`
+  (the HTTP layer succeeded — the HANDLER said no), `message` = the server's
+  `error` text, `errorCode` = the semantic refusal `code`, and
+  `result`/`data` = the merged payload (may hold evidence such as the
+  current row state). Call sites need only their ordinary
+  `catch (err) { toast.error(err.message) }`.
+- **`refusal: 'return'`** — declare this when the flag is a DIAGNOSTIC
+  RESULT, not a refusal (e.g. a connection test answering
+  `{success, key_count}`). The mutation resolves either way; read
+  `outcome.result` (`{ok, code, error, payload}`). Declared, never sniffed.
+
+`ActionOutcome.result` is the normalized reply for every action:
+`result.payload` merges the envelope with the action dict (action fields
+win), so one-shot secrets and counters read from one place regardless of
+which wire shape arrived. For `refusal:'reject'` actions `result.ok` is
+always `true` on the resolved path — a refusal already rejected.
+
+Oddball: `User.revoke_sessions` spells the flag `status` inside its payload
+(`{status: true, message}` on success). Only `status === false` refuses, so
+its truthy success value — and payloads with no flag at all — resolve
+normally.
+
 ## Pitfalls
 
+**FK fields are graph-shaped.** The backend controls graph definitions, so
+an FK field your UI reads as a scalar (`row.currency === "GC"`) can start
+arriving expanded (`{id, code, name, …}`) — or as the bare pk — when a
+graph changes. Render such fields through `fmt.code(value)` or a `render`
+callback that handles all three shapes; never hand the raw field to JSX.
+The shared primitives degrade instead of crashing (`safeNode`/`RenderGuard`),
+but app JSX outside them is unguarded.
+
 - Don't build a second store around these hooks — pages read query state.
 - The action-name union isn't typed; an undeclared name throws in dev the
   first time the hook renders (fail loud, not a 404 later).

package/docs/grouping-and-fmt.md

@@ -54,7 +54,7 @@ the type checker and was the source's silent-failure vector) and the
 | Fn | Notes |
 |---|---|
 | `fmt.number(v, decimals=0, fallback='—')` | thousands separators: `1234567` → `1,234,567`. *Deviation:* source defaulted to 2 decimals; portal columns are counts |
-| `fmt.currency(v, code='USD', {unit, decimals, fallback})` | `129900` → `$1,299.00`. **Input is CENTS by default** — django-mojo stores money as integer minor units (`cents_to_currency`) so it never touches a float; pass `{unit:'major'}` for a dollars value or a zero-decimal currency (JPY). *Deviation:* arg 2 is an ISO **code**, not a symbol — the source's own callers passed `currency("EUR")` and got `EUR1,299.00`. An unknown code warns once and falls back to USD |
+| `fmt.currency(v, code='USD', {unit, decimals, fallback})` | `129900` → `$1,299.00`. **Input is CENTS by default** — django-mojo stores money as integer minor units (`cents_to_currency`) so it never touches a float; pass `{unit:'major'}` for a dollars value or a zero-decimal currency (JPY). *Deviation:* arg 2 is an ISO **code**, not a symbol — the source's own callers passed `currency("EUR")` and got `EUR1,299.00`. An unknown code warns once and falls back to USD. **End-to-end rule: ALL money crosses the wire as integer minor units — format at the edge, never pre-convert.** Troubleshooting: amounts 100× small = you passed dollars; 100× large = you passed cents with `unit:'major'` |
 | `fmt.percent(v, decimals=0, multiply=true, fallback='—')` | `0.856` → `86%`; `multiply=false` when the value is already a percentage |
 | `fmt.compact(v, decimals=1, fallback='—')` | `1234` → `1.2K`, `3400000` → `3.4M`. Uppercase K/M/B (source casing); caps at B, so `1e12` reads `1000.0B`. Below 1,000 the raw number passes through unseparated |
 | `fmt.filesize(v, binary=false, decimals=1, fallback='—')` | `1536` → `1.5 KB`; `binary` switches to 1024/`KiB`. Whole bytes stay integral (`999 B`); caps at TB. Negatives degrade readably (`-500 B`) |
@@ -69,6 +69,7 @@ the type checker and was the source's silent-failure vector) and the
 | `fmt.truncateFront(v, length=8, prefix='...', fallback='—')` | keeps only the TAIL: `...2eZvKY` |
 | `fmt.mask(v, char='*', showLast=4, fallback='—')` | all-but-last-4: `************1111`. Values no longer than `showLast` return intact. *Fixes a source bug:* `showLast:0` masked the string and re-appended it whole (`slice(-0)` is `slice(0)`) |
 | `fmt.slug(v, separator='-')` | **fallback is `''`**, not `—` (a slug of nothing is nothing). *Deviations:* accents fold to ASCII (`Café` → `cafe`, matching django-mojo's `strip_accents`) instead of being dropped (`caf`); the separator is regex-escaped — the source interpolated it raw, so `slug(v,'.')` misbehaved and `slug(v,'')` threw on an empty quantifier |
+| `fmt.code(v, fallback='')` | **FK-safe display for coded wire fields.** django-mojo graphs expand FK fields per-graph — the same field is `"GC"` on one graph, `{id, code, name, …}` on another, and the bare pk when the graph omits it. `code()` renders every shape: string → itself, expanded row → `.code` ?? `.name`, pk number → `"3"`. **Fallback is `''`** (like `slug`) so it composes into template strings; cells that want `—` pass it explicitly. An object with no usable code/name warns once and returns the fallback. *Deviation from the wmx-admin-v2 `codeOf` source:* a pk number renders as its digits, not `''` — an unexpanded FK is data |
 | `fmt.phone(v, fallback='—')` | **DISPLAY ONLY.** E.164 (`+15555550142`) stays the wire shape — django-mojo REJECTS pretty formats on save, so never round-trip this into a field. US 10/11-digit → `(555) 555-0142` / `+1 (555) 555-0142`; anything else (a real international number) is returned trimmed and unchanged. *Deviation:* the source stripped the leading `+`, turning valid E.164 into digit soup. No `<a href="tel:">` — links are components |
 
 ### Duration + booleans
@@ -85,6 +86,21 @@ the type checker and was the source's silent-failure vector) and the
 | `fmt.initials(name)` | 1–2 letters; null-safe (`'?'` for empty — live rows carry `display_name: null`) |
 | `fmt.inferTone(value)` | status text → Badge tone ('active'→success, 'banned'→danger, booleans, …) |
 
+### FK fields change shape per graph — render them through `fmt.code`
+
+A raw object rendered as a React child crashes the page (`Objects are not
+valid as a React child`), and django-mojo makes that a live hazard: the
+backend controls graph definitions, so a field your column renders as a
+string can start arriving as an expanded row object without any frontend
+change. wmx-admin-v2 white-screened a production table exactly this way.
+Any FK-ish field (`currency`, `group`, `owner`, …) rendered in JSX goes
+through `fmt.code(value)` — or a `render` callback that handles both
+shapes. The shared primitives (ModelTable cells, DetailView sections and
+badges, the card formatter hooks) degrade to a readable value plus one
+`console.warn` instead of crashing (see `safeNode`/`RenderGuard` in the
+ModelTable doc), but app-composed JSX outside those paths is on its own —
+use the formatter.
+
 Formatters NEVER throw on bad input — they degrade (rule: a formatter is
 the last thing allowed to take down a row). Every one is null/undefined-safe,
 parses strictly (`"12 items"` is NOT 12 — it degrades, unlike the source's

package/docs/image-editor.md

@@ -64,6 +64,19 @@ These helpers operate on logical pixels and do not mount UI, upload Files,
 persist state, or initiate a browser download. `decodeImageSource` is the one
 exception that performs the URL fetch described above.
 
+## Browser-work limits
+
+The public low-level constants make the editor's availability boundary explicit:
+`MAX_IMAGE_SOURCE_BYTES` is 25,000,000 bytes, `MAX_IMAGE_DIMENSION` is 8,192
+pixels, `MAX_IMAGE_PIXELS` is 16,000,000 pixels per decoded/intermediate/final
+surface, and `MAX_IMAGE_EDITOR_OPERATIONS` is 20. Every operation output is
+checked before raster allocation. Initial transforms and filters must remain
+inside the same ranges as the controls (scale 0.1–5; brightness, contrast, and
+saturation 0–200; hue 0–360; blur 0–10; grayscale and sepia 0–100). URL bodies
+are streamed to the byte ceiling, and source replacement or unmount aborts the
+fetch and `<img>` fallback where the browser permits; `createImageBitmap` itself
+is not abortable, so a stale result is closed immediately on resolution.
+
 ## Composition and history
 
 Operations are immutable and chronological. Transform creates a logical

package/docs/menus-and-access.md

@@ -58,6 +58,63 @@ Admin section bundles contribute through `adminSectionsMenu`. Use
 experience. Routes remain mount-relative; multiple embedded root sections
 share one `/system` landing instead of emitting duplicate index routes.
 
+Import the route/menu machinery from `portal-mojo/admin/core`, then import only
+the registry domains the shell installs. The stable domains are `identity`,
+`security`, `observability`, `operations`, `infrastructure`, `communications`,
+and `assistant`. `portal-mojo/admin` remains the compatibility aggregate and
+retains every historical export, but deliberately performs the legacy DNS and
+Rule-field setup at import time.
+
+Built-in routes use `loadComponent`; external sections may use `component`.
+These properties are mutually exclusive. Loading and retryable error states
+live inside both permission guards, so access denial performs no page import.
+The infrastructure entry installs the optional managed-DNS adapter
+synchronously, which makes Email-first navigation safe even before any DNS page
+chunk has loaded. `admin/core` performs neither DNS nor field registration.
+
+### Flat sections (`presentation: 'flat'`)
+
+A section whose children should render as FLAT top-level sidebar rows under
+labeled group dividers — no accordion (the persona-lens shape: a Settings
+lens whose sidebar reads Brand / Access / Activity as divider groups):
+
+```ts
+{
+    id: 'settings', label: 'Settings', icon: 'bi-gear', route: '/settings',
+    presentation: 'flat', group: 'Brand',       // labels the hoisted home row
+    children: [
+        { label: 'Brand profile', route: '/settings/brand', group: 'Brand' },
+        { label: 'Members', route: '/settings/members', group: 'Access' },
+        // a nested child stays an accordion among the flat rows
+        { label: 'Reports', group: 'Access', children: [/* … */] },
+    ],
+}
+```
+
+`SidebarNav` applies the exported pure `flattenMenuItems(items, ctx)`
+automatically; flag-less menus pass through by identity. Semantics:
+
+- **Divider on group CHANGE** (run semantics) — a repeated non-consecutive
+  label is two runs. A registry divider immediately followed by the first
+  group divider collapses (later wins).
+- **The section's `route` hoists first** as its home row, `exact`-matched so
+  it never prefix-lights over deep routes. The label stays the section's own
+  (no auto-"Overview" — name it what you mean).
+- **Nested children hoist as accordions** and RESET the run, so the next
+  flat row re-emits its divider.
+- **Icons fall back to the section's**; a child's `group` label joins its
+  search `keywords`.
+- **Gates compose section ∧ child** — a child's own `permissions` never
+  bypass the section gate (stricter than the wmx source, deliberately: it
+  matches the admin nav's clause idiom). An invisible flat parent drops its
+  whole section.
+- **Flat is presentation only.** Route resolution (`resolveActiveMenu`)
+  walks the original tree, so active-menu selection cannot disagree with
+  what renders. Rail density is an authoring concern — nest a long group.
+
+The personas layer's `sectionMenuEntries` still pre-flattens its own menus;
+converging it onto flat sections is a named follow-up.
+
 ## Permissions (A2) — client gates, server authority
 
 `Me.permissions` is a dict; truthy `true` OR `1` grants. Semantics

package/docs/params.md

@@ -34,6 +34,18 @@ unless `defaults.sort`), `page` (1-based), `size`.
 Every write goes through the URL (`replace`), so table state deep-links and
 survives reloads by construction.
 
+## `excludeKeys` — the fixedParams scrub
+
+`useTableParams(defaults, defaultFilters, excludeKeys?)`: keys in the set
+never become filter state — dropped from the URL-derived filters memo, the
+`defaultFilters` seed, and `applySaved`'s persisted filters. ModelTable
+passes its `fixedParams` keys here so locked scope cannot re-enter as a
+removable pill via a bookmark or a stale persisted view. This does not
+bend the store's rule: the store remains the single source of truth for
+table STATE (what the user did); `fixedParams` is table IDENTITY (what
+the table is) and deliberately lives outside it, merged onto the wire
+after normalization. Pass a render-stable Set — it is a memo dependency.
+
 ## `registerNonFilterParams(...keys)` — params the PAGE owns
 
 Everything in the query string that isn't `search/sort/page/size` is treated