portal-mojo 0.1.1 → 0.2.0

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/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/menus-and-access.md

@@ -72,6 +72,49 @@ 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