portal-mojo 0.2.7 → 0.2.9

package/docs/admin-edge.md

@@ -0,0 +1,210 @@
+# Edge Admin
+
+```ts
+import {
+    EDGE_ADMIN_SECTION, VhostsPage, VhostDetail, VhostWizard, openVhostWizard,
+    UpstreamsPage, BlocklistPage, EdgeVhostModel, EdgeRouteModel,
+    EdgeUpstreamModel, EdgeBlocklistModel, buildVhostPayload,
+} from 'portal-mojo/admin';
+```
+
+The same names are on `portal-mojo/admin/infrastructure`.
+
+`EDGE_ADMIN_SECTION` contributes Infrastructure routes at `edge/vhosts` and
+`edge/upstreams` (or the same paths under an embedded `/system` mount). The
+fleet blocklist is a route of Network Security, at
+`security/network/edge-blocklist`. There are no record routes: a vhost opens in
+`modal.detail`.
+
+Consumer contract: django-mojo `mojo/apps/edge/`. The mock in
+`client/mock.ts` returns the same graphs and the same refusals, word for word
+where the server has words.
+
+## Permissions
+
+- Vhosts, routes, upstreams — view: `sys.view_dns | sys.manage_dns | sys.security`.
+- Vhosts, routes — change or delete: `sys.manage_dns | sys.security`.
+- Upstreams — switch on or off: `sys.manage_dns | sys.security`.
+- Upstreams — declare or retire: `me.is_superuser === true`. The server gate
+  is `require_platform_admin`, which also refuses API keys.
+- Blocklist — view: `sys.view_security | sys.manage_security | sys.security`
+  (`EDGE_BLOCKLIST_VIEW_PERMS`). This is wider than `SECURITY_VIEW_PERMS`: the
+  server lets `manage_security` view, and manage does not imply view on the
+  client, so the clause is spelled out.
+- Blocklist — change or delete: `sys.manage_security | sys.security`.
+
+A section gate and a route gate both apply. A security-only operator is denied
+every DNS-gated section, which is why the blocklist does not live under Edge.
+The blocklist has no group: a member-scoped grant and `?group=` open nothing.
+
+**House rows.** A vhost on a group-less domain is platform property. It never
+appears in a non-superuser's list, even with a global grant, and its detail,
+its routes and creating one are refused to everyone else. The vhost graphs
+carry `domain: basic`, which has no `group`, so house-ness cannot be read off a
+vhost row. The wizard's domain picker passes `group__isnull: false` for
+non-superusers so a house domain is never offered to someone who would be
+refused at Finish.
+
+## Endpoints
+
+| Address | Verbs | Notes |
+|---|---|---|
+| `/api/edge/vhost` (+`/<id>`) | list, read, create, update, delete | `list` graph for tables, `default` for one row |
+| `/api/edge/route` (+`/<id>`) | list, read, create, update, delete | `site_api` vhosts only; filter `vhost` |
+| `/api/edge/upstream` (+`/<id>`) | list, read, update | update writes `is_enabled` only; no create, no delete |
+| `/api/edge/upstream/declare` | POST | `{name, kind, host+port \| socket_path, group?}`; platform administrators |
+| `/api/edge/upstream/retire` | POST | `{upstream}`; disables, keeps the row; platform administrators |
+| `/api/edge/blocklist` (+`/<id>`) | list, read, create, update, delete | fleet-wide |
+
+## The four kinds
+
+The wizard never shows a kind dropdown over one long form. Its first step is
+four cards in plain words; the following steps show only that shape's settings.
+
+| Kind | Card | Needs | May carry | Refuses |
+|---|---|---|---|---|
+| `api` | API host | `upstream` | `quiet_paths`, `serve_static` | `spa`, `redirect_to` |
+| `site` | Static site or SPA | — | `spa` | `upstream`, `quiet_paths`, `serve_static`, `redirect_to` |
+| `site_api` | Site + API paths | routes | `spa`, `serve_static`, `quiet_paths` | whole-host `upstream`, `redirect_to` |
+| `redirect` | Redirect | `redirect_to` | — | everything else |
+
+`buildVhostPayload(draft, { create })` is the one place a draft becomes a
+request. It sends each knob the chosen kind does not carry as its empty value,
+so a draft that visited another shape cannot leak that shape's settings, and
+an edit that changes kind clears what the old kind held. It never sends
+`mojosec_policy`. A vhost that carries an edge evidence policy therefore cannot
+change kind, or its single-page-app switch on a `site`, from here: the server
+requires the policy's response class to match and refuses, and its message is
+shown.
+
+Shared rules, each mirrored by a validator in `edge/models.ts`:
+
+- `label`: empty serves the bare domain, `*` the wildcard, otherwise one DNS
+  label. The address (`server_name`) is derived, never typed.
+- `body_size_mb`: whole number, 1 to 4096, default 50. Not offered for a
+  redirect.
+- `pool`: must be one the deployment declares (`EDGE_POOLS`, default
+  `["default"]`). The refusal names the declared set.
+- `domain`: set once. An edit shows it read-only and never sends it.
+- `redirect_to`: a host name. No scheme, path, port or wildcard.
+- A route prefix or quiet path starts with `/`, uses letters, digits, `.`,
+  `_`, `-` and `/`, and has no `//` or `..`. A route prefix cannot be `/`.
+
+## What is checked when
+
+The server checks most things on every save. Two things are checked **only
+when the row is enabled**:
+
+- the certificate belongs to the vhost's domain and covers its address;
+- no other enabled row has the same domain and label.
+
+So a disabled row may hold a certificate that does not cover it yet, and may
+share a name with a live row. That is how a replacement is staged: create it
+disabled, then disable the old one and enable the new one. The wizard warns
+when the chosen certificate does not cover the address (`certificateCovers`,
+which knows that a wildcard covers exactly one label and never the apex) and
+still lets the row be saved disabled.
+
+## The create order for `site_api`
+
+A quiet path on a `site_api` vhost must sit under one of its route prefixes,
+and the server reads those prefixes from the stored row. A create that carries
+quiet paths is therefore always refused with "none declared". The only order
+that works is:
+
+1. create the vhost, **disabled** and without quiet paths;
+2. create its routes, one at a time;
+3. save the vhost once more with the quiet paths and the enablement the user
+   chose.
+
+The wizard does exactly this. Step 3 always runs, so the enable-time checks
+happen at the end and a failure part-way never leaves a live vhost with no
+routes. If a step is refused the wizard stays open and says which step and
+what already exists. Finishing again continues from there: it never posts the
+vhost a second time and never repeats a route that landed.
+
+The server will store an enabled `site_api` vhost with no routes. The wizard
+does not: at least one valid route is required at the settings step and again
+at review.
+
+In edit mode routes are read-only, with a pointer to the detail view, which
+owns adding, changing and deleting them. Changing a `site_api` vhost to
+another kind while it has routes is blocked with the count; the server refuses
+it too. Until the stored routes have been read, or if that read fails, the
+wizard does not judge quiet paths against them and leaves that to the server.
+
+## Vhost detail
+
+The detail follows the admin modal contract (`admin-modals.md`). The header
+switch enables and disables. Edit and Delete are in the header menu, shown
+only with the manage grant. Delete asks for confirmation, names the address,
+says its routes go with it, and points at Disable as the choice that can be
+undone. A refused enable shows the server's message in the overview. Routes
+are content: the Routes section lists them and owns add, change and delete.
+
+## Upstreams
+
+An upstream is a destination a vhost may proxy to. Only `is_enabled` can be
+written on one; its name and destination are fixed when it is declared. The
+list shows the active group's upstreams and the shared ones. Retiring disables
+the row and keeps it: vhosts and routes that reach it stop being served and
+are not repointed. The retire control names that consequence before it acts.
+The wizard's upstream pickers list enabled upstreams only.
+
+## Blocklist
+
+An entry matches an IP network or a user-agent pattern, in one of four modes:
+`log` (recorded, still served — the default), `enforce` (refused), `allow` (an
+exemption) and `off`. Create an entry in `log`, watch the edge watch log for
+it, then switch it to `enforce`. A change reaches the fleet in about ten
+minutes.
+
+An `ip` value is stored as its network: `10.1.2.3/8` is saved as `10.0.0.0/8`.
+The editor shows the saved value from the response.
+
+## Not built here
+
+- **Claim-reserved.** The plan for this page asked for a superuser control to
+  claim a reserved name. django-mojo removed the reserved-name mechanism, its
+  field and its action (commit `bc2c57b1`, in every release since v1.7.1), so
+  there is nothing for such a control to call.
+- **`mojosec_policy`.** Shown read-only on the vhost detail. It is set by the
+  platform and never sent from here.
+- **Web apps, releases and alias addresses.** An alias address appears in the
+  vhost list like any other row; `alias_of` is in no graph, so it cannot be
+  told apart, and a refused edit shows the server's message.
+
+## Pitfalls
+
+- Do not send `quiet_paths` on a `site_api` create. See the create order.
+- Do not treat a saved, enabled row as proof the certificate covers it from
+  the client check alone; the server's answer on save is the proof.
+- The mock's messages for database uniqueness (a second enabled vhost on one
+  name, a repeated route prefix, a repeated blocklist value, a repeated
+  upstream name) are the mock's own words. The server reports these from a
+  database constraint, and its wording was not measured.
+- The server parses a blocklist address with Python's `ipaddress` and compiles
+  a user-agent pattern with Python's `re`, and the mock follows Python, not
+  JavaScript: `010.1.2.3` and `\q` are refused, `10.0.0.0/255.0.0.0`,
+  `(?i)bot` and `a*+` are accepted. The reason after "does not compile" is the
+  mock's own wording. The editor's own check is only a first pass and never
+  compiles the pattern; the server's answer on save is the verdict.
+- A vhost update that names an upstream or certificate that does not exist is
+  refused by the mock with the same words as a missing one. The server's
+  wording for an unknown id was not measured.
+- The declare-upstream dialog and the blocklist editor refuse Escape and the
+  backdrop while their write is in flight, and the editor's save and delete
+  share one pending state. `npm run verify:admin-edge` holds each write open
+  and checks this.
+
+## Themes and showcase
+
+Styles live in `src/styles/components/admin-edge.css` and ship in
+`portal-mojo/styles.css`; the app declares the tokens. They are built from
+tokens only, so both themes render from one sheet. The showcase still carries
+its own identical copy until it adopts the package stylesheet. The showcase
+demo (Develop → Components → Admin → Edge) runs the shipped pages against the
+mock under five identities: platform administrator, DNS manager, DNS viewer,
+security manager and security viewer.
+
+`npm run verify:admin-edge` is the executable contract.

package/docs/admin-identity-directories-sources.json

@@ -25,8 +25,8 @@
       "source_path": "apps/portal/src/pages/ApiKeysPage.tsx",
       "source_sha256": "3d338cf77c3110b72a9361565c1cced10a7fccc52c486e3dafda119d66c676b2",
       "package_path": "packages/portal-mojo/src/admin/identity/users/PersonalApiKeysPage.tsx",
-      "package_sha256": "f377d8a97b5c0ccbce745c333fdd7e4a5fd5f5a89b868b058677b31e3efe64ff",
-      "adaptation": "Expanded row facts and actions are presented in a native DetailView modal that observes the current API key record."
+      "package_sha256": "0c1e1efd34f515e4b5dc994ce34be1446eb13d1486deea3e9641565215edb6ad",
+      "adaptation": "Expanded row facts and actions are presented in a native DetailView modal that observes the current API key record. Every list and export is pinned to the signed-in user with fixedParams, and the table is not mounted before that user is known."
     },
     {
       "source_path": "apps/portal/src/pages/GroupDetail.tsx",

package/docs/admin-identity-directories.md

@@ -54,6 +54,15 @@ revoke remains armed because it rotates the secret and cannot be undone. There
 is no delete action. This page does not use the separate group credential
 endpoint.
 
+The page lists the signed-in user's own keys only. The endpoint serves every
+user's keys to a caller holding `users` or `manage_users` who sends no `user`,
+so the page passes `fixedParams={{ user: me.id }}`: every list and export
+request carries it, and it cannot be cleared from the URL, a saved view or a
+preset. Until the signed-in user is loaded the page shows a placeholder and
+mounts no table, so no unscoped list or export can go out. An administrator
+reads another user's keys per user, in that user's detail under Users. Plain
+users reach their own keys in "My account".
+
 The Personal API Keys route was added to the package identity section registry
 alongside Users, Members, Groups, Credentials and Sign-in. Compatibility page
 paths in the reference app re-export the package-owned pages, and its menu and

package/docs/admin-identity-users.md

@@ -1,7 +1,7 @@
 # Admin Users
 
-Reusable global User administration for django-mojo. Consumers must include
-the semantic `user-admin.css` stylesheet used by the portal and showcase.
+Reusable global User administration for django-mojo. Its semantic
+`user-admin.css` stylesheet ships in `portal-mojo/styles.css`.
 
 ```tsx
 import {

package/docs/admin-jobs.md

@@ -52,7 +52,7 @@ stuck work, purge history — plus the cron-style scheduled tasks whose backend
 django-mojo has always shipped and whose admin page web-mojo never wired up.
 
 Demo: showcase → Admin → **Jobs engine**. Styles:
-`apps/{portal,showcase}/src/theme/admin-jobs.css` (byte-identical).
+`packages/portal-mojo/src/styles/components/admin-jobs.css`.
 Verifier: `npm run verify:admin-jobs`.
 
 Wire facts below come from django-mojo `mojo/apps/jobs/` (`models/job.py`,
@@ -424,6 +424,6 @@ from hand-built `JobsStats` objects (and, for `JobRunnersStrip`, a demo-only
 branched for the demo.
 
 Styles are semantic `jobs-*` classes, tokens only, both themes:
-`apps/{portal,showcase}/src/theme/admin-jobs.css`, imported from each app's
-`theme.css`. The verifier asserts the two copies stay byte-identical and that
-neither contains a raw hex colour.
+`packages/portal-mojo/src/styles/components/admin-jobs.css`, imported by the
+package's `src/styles/index.css`. The verifier asserts that import and that
+the file contains no raw hex colour.

package/docs/admin-media-rendering.md

@@ -0,0 +1,142 @@
+# Media rendering admin
+
+```ts
+import {
+    MediaRenderingPage, readRenditionOptions, findCategoryRows, valueToDraft, draftToValue,
+    validateDraft, routeRenditionError, saveCategoryValue, resetCategory, fieldType,
+    renditionRoleLabel,
+} from 'portal-mojo/admin/infrastructure';
+```
+
+Storage → Media rendering edits how django-mojo's fileman builds thumbnails,
+previews and transcodes, and which of those run after an upload. It is a form
+over three ordinary `Setting` rows — `FILEMAN_RENDITIONS_IMAGE`, `_VIDEO`,
+`_DOCUMENT` — built entirely from the backend's descriptor (django-mojo #7728,
+`docs/web_developer/fileman/renditions.md`). Nothing about roles, defaults,
+fields, choices or limits is hardcoded: a role the framework adds appears
+without a portal release.
+
+## Route and access
+
+`STORAGE_ADMIN_SECTION` registers `storage/rendering` (label "Media
+rendering") with the Settings page's gate, `sys.manage_settings | sys.groups`
+— the page writes Setting rows, so it carries the Setting write audience, not
+the storage one. The section audience includes those two grants so a
+settings-only operator can reach the page; the other storage routes keep their
+own clauses. Member grants never satisfy the gate.
+
+The descriptor itself (`GET /api/fileman/renditions/options`) is readable by
+`manage_settings | manage_files | files | groups`; a `files`-only operator can
+read it elsewhere but cannot open this editor.
+
+Global scope only. There is no group selector; group-scoped overrides stay on
+the generic Settings page.
+
+## Wire contract
+
+**Read:** `GET /api/fileman/renditions/options` → `data.categories.<image|video|document>`:
+
+| Field | Used for |
+|---|---|
+| `key` | the Setting key to write |
+| `defaults` | one row per role, in served order; the greyed values |
+| `automatic_default` | the "runs on upload" default set |
+| `override` | the global **database** row, parsed, or `null`. A deployment-file value is applied but not reported here |
+| `effective` | defaults with the override (and any file value) applied; shown only as a read-only "In effect: …" hint where it differs from the draft |
+| `role_kinds`, `fields`, `choices`, `limits` | which fields a role renders, their enum values and inclusive numeric bounds |
+
+`data.engine` is read-only on this page (`ffmpeg`; the key stays on Settings
+until a second engine exists).
+
+**Row lookup:** `findCategoryRows(key)` lists `/api/settings?key=<KEY>&group__isnull=true`
+with raw `mojoList` — `SettingModel.normalizeListParams` strips `key`, so the
+model's list hook cannot do this. More than one global row for a key disables
+Save and Reset with a notice naming the ids: `Setting.Meta.ordering = ["key"]`
+leaves the server's `.first()` undefined among duplicates, so editing one could
+change a row the renderer never reads.
+
+**Write:** the whole category as one object — `POST /api/settings` to create
+(`{key, is_secret: false, group: null, value}`) or `POST /api/settings/<id>`
+to update (`{value}`). The value is sent as an object; the server stores it as
+JSON text. Imperative `mojoSave` under `withFreshAuth`; a failure rejects.
+
+**Reset = write `{}`.** The live `Setting` model declares no `CAN_DELETE`, so
+`DELETE /api/settings/<id>` answers 403 — the backend doc's DELETE instruction
+does not work live. `{}` is the documented "defaults" value and the endpoint
+reports it as `override: null`; the row stays, harmlessly. Reset is disabled
+when there is no row or the override is already null.
+
+## Mapper invariants (`rendition-settings.ts`)
+
+- **Draft seeds from `defaults ⊕ override`**, never from `effective`. Seeding
+  from `effective` would mark a deployment-file value as changed on an
+  untouched form and copy it into a DB row on the first Save.
+- **`draftToValue` emits deltas against the defaults**, not against the
+  previous override: a field restored to its default disappears from the row.
+  Empty role objects are omitted; `{}` means defaults. Save is disabled when
+  the emitted value equals the current override.
+- **One typing rule, `fieldType(category, kind, name)`**: `choice` when
+  `choices[kind][name]` exists, else `number` when the name is in `limits`
+  (checked in that order — the server lists a bound for every option name it
+  limits anywhere in the category, so document `quality`, a choice on pdf
+  roles, also appears under `limits`), `boolean`
+  when a default of that kind holds a boolean (today `audio`), else `string`.
+  Inputs coerce on change through `coerceFieldValue`; `<input type=number>`
+  strings never reach the payload (the server refuses `"300"`).
+- **`_automatic`** is compared as a set and emitted only when it differs from
+  `automatic_default`, in default order with additions appended in `defaults`
+  key order (the renderer runs roles in list order). Roles the defaults do not
+  declare are dropped on read, as the server's `merge` does.
+- **The mp4-only trio** (`codec`, `crf`, `preset`) is the one rule not in the
+  descriptor: it is hidden and stripped from the payload while a role's format
+  (draft, else default) is not `mp4`. Switching the format back restores the
+  draft values. Format wins over codec, exactly as the server validates.
+- A field with no default (image `format`/`quality` — renderer class
+  attributes, not `default_renditions`) renders unset with a "renderer
+  default" placeholder; setting it emits it, clearing it omits it again.
+
+## Validation and the 400 slot
+
+`validateDraft` mirrors the server's checks with the server's wording (whole
+number / between min and max / one of … / `2000k or 2M` / `HH:MM:SS`). It is
+**advisory**: inputs carry `min`/`max`/`step`, the hint shows inline as the
+admin types, but Save stays enabled and the server decides. Gating on the
+client copy would make the 400 path unreachable and drift from the server.
+
+A refused save routes through `routeRenditionError(message, knownRoles)`:
+
+| Message | Lands |
+|---|---|
+| `<role>.<option>: …` | under that field, same slot as the hint |
+| `<role>: …` | under that role's row |
+| `_automatic: …` | beside the "runs on upload" switches |
+| anything else, or a role not on screen | the panel-level alert |
+
+Never a generic toast.
+
+## Mock
+
+`client/renditions-mock.ts` copies the renderers' `default_renditions`,
+automatic roles, `OPTION_SCHEMA`, limits and the error grammar verbatim.
+`describeRenditions(globalRows)` serves the descriptor from the mock's global
+Setting rows; `validateRenditionSetting(key, value)` runs on every
+`/api/settings` create/update whose key is a rendition key and answers
+`{status: false, error, error_code: 400}` before the row mutates. DELETE stays
+403. The mock seeds `FILEMAN_RENDITIONS_VIDEO = {"video_hevc": {"crf": 24}}`
+so a changed field sits beside greyed defaults on first load. Personas with
+the gate: `security.manager@nativemojo.com`, `showcase.operator@nativemojo.com`
+(password `mojo`).
+
+## Pitfalls
+
+- `DocumentRenderer` on django-mojo `main` (2026-10-10) has no
+  `config_category`, so `FILEMAN_RENDITIONS_DOCUMENT` is validated and
+  described but not yet applied by the renderer. The Documents tab ships per
+  contract; the override takes effect once the renderer honours it.
+- Changing options never touches existing files: open a file under Storage →
+  Files and use **Regenerate renditions** to see the result.
+- `video_hevc` is never automatic unless `_automatic` names it; H.265 costs
+  several times the H.264 encode time and does not play in every browser, so
+  keep `video_mp4` as the compatibility rendition (the Video tab says so).
+
+Verification: `npm run verify:admin-media-rendering`.

package/docs/admin-modals.md

@@ -62,6 +62,7 @@ the inventory using `node scripts/verify-admin-modals.mjs --write-inventory`.
 | Storage/shortlinks | Bucket, FileManager, File, shortlink; owner/backend/test/CORS/upload/rendition/share | FileManager/shortlink/share active state; no File disable promise; bucket empty only |
 | Email/support | Domain, mailbox, sent message, template, contact; credentials/onboarding/audit/reconcile/test/template/status | Preserve evidence; separate mailbox directions and support status |
 | Phone/Push | Number, SMS, config, device, delivery, template; lookup/test/config editors | Config/template lifecycle; number/SMS/device/delivery evidence retained |
+| Edge | Vhost with nested routes; shape-first wizard, route editor, upstream declare/retire, blocklist entry editor | Vhost and upstream enabled state; upstreams retire and are never deleted; vhost, route and blocklist deletion are retained operations |
 | Assistant/settings | Conversation, Skill, Setting; feed continuation, scoped memory, typed settings editor | Owner-only continuation; Skill active selection; memory is scoped editing |
 
 ## Resource lifecycle matrix
@@ -84,6 +85,9 @@ the inventory using `node scripts/verify-admin-modals.mjs --write-inventory`.
 | Push config / template | Existing active selection with separate manage/test grants |
 | Assistant conversation | Retain history; no arbitrary REST save or invented archive |
 | Assistant Skill | Existing `is_active` save requires `sys.view_admin`; authoritative reload after mutation |
+| Edge vhost | Enable/disable from the header; Edit and Delete in the header menu. Disabling keeps the row and is how a replacement is staged |
+| Edge upstream | `is_enabled` only. Retire (platform administrators) disables and keeps the row; server `CAN_DELETE=False` |
+| Edge blocklist entry | Mode is the lifecycle: `off` parks an entry without losing it. Deletion is a retained operation |
 | Other logs/devices/history | Read-only by default, even where low-level REST supports DELETE |
 
 The public low-level exported delete APIs remain compatible. Built-in controls
@@ -101,6 +105,9 @@ conversation archival require backend work before new lifecycle UI is added.
 | DNS record-set removal | DNS manage gate, provider capability and record coordinator. Preview all values, apex/service impact and exact name/type; stale-state preflight and reconcile failures; no domain deletion |
 | Empty bucket | `sys.manage_aws OR sys.files`, then fresh auth; header to focused armed confirmation and exact case-sensitive bucket name. Removes objects, versions, markers and multipart uploads; retains bucket. Display partial/unknown outcomes and always refresh |
 | Jobs retention purge | `sys.manage_jobs OR sys.jobs`; dry-run estimate bound to normalized days/status plus generation. Editing/replacing preview resets arming. Ignore stale/unmounted responses; lock inputs/dismissal during execution. Report actual cutoff and cascade-inclusive counts; rejection requires another preview |
+| Edge vhost deletion | `sys.manage_dns OR sys.security`; house vhosts are platform administrators only. Header menu to a focused confirmation naming the address. Stops serving the name and deletes its routes with it; the confirmation points at Disable as the reversible choice |
+| Edge route removal | Same grant, inside the vhost's Routes content with an armed control naming the prefix. Requests under the prefix stop being proxied. A quiet path left without a covering route makes the vhost's next save fail, and the server's message is shown |
+| Edge blocklist entry removal | `sys.manage_security OR sys.security`; armed control in the entry's editor. The entry leaves every node within about ten minutes. `off` is the reversible choice |
 | Queue/consumer cleanup | Jobs manage grant, exact channel/scope and armed confirmation; queue clear sends `confirm:yes` only after consent and may cancel pending database jobs. Report partial outcomes |
 
 Other non-row removals retain their scoped editor semantics: rate-limit override

package/docs/admin-monitoring.md

@@ -93,7 +93,7 @@ current contract.
 ## Styling and showcase
 
 Monitoring components use semantic `monitoring-*` classes and application
-tokens only. A consuming app must include `admin-monitoring.css`. This repo's
-portal and showcase theme entries do so. The showcase's Admin Monitoring demo
-contains static request, response, JSON, and HTML-looking plain-text cases for
-both-theme verification without mutating a backend.
+tokens only. `admin-monitoring.css` ships in `portal-mojo/styles.css`. The
+showcase's Admin Monitoring demo contains static request, response, JSON, and
+HTML-looking plain-text cases for both-theme verification without mutating a
+backend.

package/docs/admin-network-security.md

@@ -33,8 +33,8 @@ Perimeter control: block an abusive IP right now, whitelist a customer's NAT,
 maintain country and datacenter CIDR sets synced to the firewall fleet, set
 geographic policy — and prove the policy does what you think with a built-in
 simulator before it bites real traffic. Demo: showcase → Admin → **Network
-security**. Styles: `apps/{portal,showcase}/src/theme/admin-network.css`
-(byte-identical).
+security**. Styles:
+`packages/portal-mojo/src/styles/components/admin-network.css`.
 
 ## Surfaces
 

package/docs/admin-phonehub.md

@@ -13,7 +13,10 @@ Import `PhoneHubPage`, the three individual pages, models, permission clauses, a
 - `PhoneConfigModel` reads sanitized scalar/default-graph rows. Saves and `test_connection` use imperative, cache-free calls. The editor follows web-mojo's provider-conditional layout: selecting Twilio, AWS SNS, or Mojo Remote shows and submits only that provider's connection fields. Mojo Remote uses `https://api.mojoverify.com` when the saved URL is unset or the editor is switched to Mojo; an explicitly configured custom URL is preserved. Secret inputs are DOM refs, not React or Query state: blank means untouched and is omitted; replacement must be non-empty; clear sends `null` only after a separate confirmation. Switching providers resets pending clears, and hidden provider credentials remain untouched. Responses are allowlisted before cache reconciliation. This surface edits existing provider credentials; it does not provision Django user/group API keys.
 
 Connection tests read the provider's `success` verdict, not the outer REST
-`status`. A failed or missing verdict is an error; `test_mode` is a warning
+`status`. The real wire answers the test flat (the action dict verbatim, as
+the mock now does too), so the call passes `refusal: 'return'`: a failed
+verdict is an answer for inline display, not a rejected request. A failed or
+missing verdict is an error; `test_mode` is a warning
 that the provider was not contacted. Results persist inside the detail modal
 on both sections, alongside a toast. Scope is labeled in the header and
 Connection section. Editing is disabled while a connection test is pending, so an old response

package/docs/admin-storage.md

@@ -8,8 +8,11 @@ import {
 ```
 
 `STORAGE_ADMIN_SECTION` contributes global/no-group Infrastructure routes at
-`storage/buckets`, `storage/backends`, and `storage/files` (or the same paths
-under an embedded `/system` mount). There are no record routes: buckets,
+`storage/buckets`, `storage/backends`, `storage/files` and `storage/rendering`
+(or the same paths under an embedded `/system` mount). `storage/rendering` is
+the Media rendering editor — see [admin-media-rendering.md](admin-media-rendering.md);
+it carries the Settings gate (`sys.manage_settings | sys.groups`), which the
+section audience therefore includes. There are no record routes: buckets,
 backends, nested files, and files use `modal.detail`.
 
 ## Permissions

package/docs/auth-pages.md

@@ -13,6 +13,8 @@ import {
     // Fresh-auth (step-up) challenge surface
     REAUTH_STATUS, isReauthRequired, setFreshAuthHandler, requestFreshAuth,
     withFreshAuth, sessionIsPersistent,
+    // shared passkey error copy (LoginPage, MfaPanel, FreshAuthHost)
+    passkeyErrorMessage,
     type MfaChallenge, type FreshAuthHandler, type MfaCompletionOptions,
 } from 'portal-mojo/client';
 
@@ -80,6 +82,8 @@ answers with a full TokenGrant).
 - **Passkey**: `loginWithPasskey(username?, {remember})` behind `isPasskeySupported()`;
   no username → discoverable-credential prompt. The ceremony is fully built;
   REAL-authenticator verification is deferred (mock validates shape only).
+  Failures read through `passkeyErrorMessage()` (one copy for login, the MFA
+  passkey step and the fresh-auth modal).
   The remember choice is explicit because MFA and fresh-auth passkey paths
   must not promote a sessionStorage session into localStorage.
 
@@ -193,9 +197,10 @@ the first matching 440, retry success, and later normal calls reproducible.
   deployment-specific providers (`GET /api/auth/config` → `login.methods`),
   and no way to exercise the round-trip against the mock or without real
   provider credentials. Hosted pages cover OAuth deployments today.
-- **Passkey real-authenticator verification** — the ceremony is fully
-  built on auth.ts; verifying against a real authenticator + a live
-  django-mojo passkey registration is Ian's post-merge pass.
+- **Passkey real-authenticator verification** — login and registration
+  ceremonies are built on auth.ts (`loginWithPasskey`, `registerPasskey` —
+  the AccountModal's Add a passkey, see [account.md](account.md)).
+  Registration ceremony built; real-authenticator check pending.
 
 ## Pitfalls
 

package/docs/auth.md

@@ -7,6 +7,9 @@ import {
     sendMagicLink, loginWithMagicToken, handleMagicTokenFromURL,
     forgotPassword, resetPasswordWithCode, resetPasswordWithToken,
     loginWithPasskey, isPasskeySupported,
+    // self-service, signed in (the AccountModal's wire — see account.md)
+    registerPasskey, isPasskeyRegistrationSupported, suggestPasskeyName,
+    passkeyErrorMessage, confirmEmailChange, revokeOtherSessions,
 } from 'portal-mojo/client';
 ```
 
@@ -17,6 +20,7 @@ initAuth();                       // installs the pre-request gate + Authorizati
 void handleAuthCodeFromURL();     // returning from the hosted /auth pages (no-op otherwise)
 onAuth('login',  () => queryClient.invalidateQueries());   // identity changed →
 onAuth('logout', () => queryClient.invalidateQueries());   // every cached answer is suspect
+onAuth('rotated', () => queryClient.invalidateQueries());  // same user, re-issued session
 ```
 
 ## Session mechanics
@@ -27,8 +31,24 @@ onAuth('logout', () => queryClient.invalidateQueries());   // every cached answe
 - `useAuthSnapshot()` → `{authenticated, uid, email}` — live, cross-tab.
 - `logout()` is client-side (django-mojo has no logout endpoint) and emits
   `'logout'`.
-- Events for `onAuth`: `'login' | 'logout' | 'refreshed' | 'refresh-failed'
-  | 'unauthorized'`.
+- Every flow that answers with a login grant adopts it only when it carries
+  an `access_token` + `refresh_token` pair; anything else (e.g. django-mojo's
+  `forced_password_response` after `auth_key` rotated) rejects with
+  `GRANT_SIGN_IN_AGAIN` ("Sign in again to continue") and leaves storage
+  untouched. Adoption waits for an in-flight refresh, and a refresh that
+  completes after the stored session changed (new login, logout, another
+  tab) is discarded instead of written over it.
+- Events for `onAuth`: `'login' | 'rotated' | 'logout' | 'refreshed' |
+  'refresh-failed' | 'unauthorized'`.
+  - `'login'` — an explicit, completed sign-in (password, MFA step, passkey,
+    magic link, password reset, hosted-auth exchange).
+  - `'rotated'` — the SAME user's session re-issued by a credential change
+    (`revokeOtherSessions()`, `confirmEmailChange()`): new tokens in the same
+    storage, but NOT a login — never treat it as one (the packaged Admin
+    source session reopens a logout tombstone only on `'login'`). Invalidate
+    caches on it where you do on `'login'`.
+  - `'logout'` / `'unauthorized'` — the session ended; the toolkit modal
+    stack closes every open dialog on both.
 
 Both localStorage and sessionStorage keep the existing token keys. Refresh
 preserves the chosen storage, including sessions with only a valid refresh token
@@ -84,3 +104,26 @@ magic-link (`sendMagicLink` → `loginWithMagicToken`), password reset (code
 and token variants), passkeys (`loginWithPasskey`; ceremony fully ported,
 mock validates shape only). All reject with the server's message on
 failure.
+
+## Self-service credential changes (signed in)
+
+- `isPasskeyRegistrationSupported()` — `PublicKeyCredential` **and**
+  `navigator.credentials.create` (`isPasskeySupported()` only checks `get`).
+- `registerPasskey(name?)` — fresh-auth `POST /api/account/passkeys/register/begin`
+  → `navigator.credentials.create` → fresh-auth `…/register/complete
+  {challenge_id, credential, friendly_name}`. `transports` rides at the
+  credential's top level; `id === rawId`. Returns the saved row; callers
+  refresh `PasskeyModel` and `me`. Default name `suggestPasskeyName()`.
+- `passkeyErrorMessage(err)` — one copy for every passkey ceremony (login,
+  step-up, registration): NotAllowedError → "Passkey prompt was dismissed",
+  InvalidStateError → already registered, SecurityError → wrong domain/HTTPS,
+  AbortError → cancelled; anything else (server text) as written.
+- `confirmEmailChange(code)` — `POST /api/auth/email/change/confirm`; the
+  server rotates `auth_key` and answers a new login, adopted into the
+  storage this session already uses (`sessionIsPersistent()`).
+- `revokeOtherSessions()` — fresh-auth `POST /api/auth/sessions/revoke`;
+  every other session dies, the returned login is adopted so this one stays.
+
+Registration ceremony built; real-authenticator check pending. The rest of
+the account wire (TOTP, recovery codes, phone, verify, preferences) is in
+[account.md](account.md).

package/docs/calendar.md

@@ -101,7 +101,7 @@ Parse fns return `null` on invalid input, never throw; format fns return
 
 ## Styling
 
-`apps/portal/src/theme/calendar.css` — engine anatomy only
+`packages/portal-mojo/src/styles/components/calendar.css` — engine anatomy only
 (`mojo-calendar-*`: pane/head/nav/grid/weekday/cell + state classes), all
 colors via theme tokens; component tokens `--mojo-cal-anchor-fill`,
 `--mojo-cal-range-fill`, `--mojo-cal-range-fill-hover` (accent tints: