@uniweb/api 0.7.0 → 0.8.0

package/README.md

@@ -52,11 +52,13 @@ function Account() {
 ```
 
 `viewer` is flat — `viewer.uuid`, `viewer.username`, `viewer.handle`, and `viewer.roles`,
-a list of `{ role, scope_unit_id }`. A member holds no roles (`[]`); the site's operator
-holds `system_admin`. ⚠️ `viewer.workspace` — the site service's home org,
-`{ handle: 'home', … }` — is the same for every member, so it cannot tell an operator
-from a member. To decide whether to show an edit control for
-a particular record, read that record: `entity.can_edit` is the backend's own answer.
+a list of `{ role, scope_unit_id }`. ⭐ **Roles describe the session, and a session
+signed in on a site holds a member's rights — the operator's too.** A site runs your
+foundation's code with the signed-in member's session, so no administrator's role
+rides with it: `viewer.roles` never names one there, and an ordinary member holds none
+(`[]`). `viewer.workspace` — the site service's home org, `{ handle: 'home', … }` — is
+the same for everyone. To decide whether to show an edit control for a particular
+record, read that record: `entity.can_edit` is the backend's own answer.
 
 **Signing up** — `useSignUp().signUp({ username, email, password })` answers
 `{ status: 'verification_required', email }`, the same answer for an address already in
@@ -69,6 +71,23 @@ already taken fails with status `409`.
 second factor is enrolled). **Second factor** — when `signIn` answers
 `{ ok: false, challenge: { kind: 'totp' } }`, finish with `completeChallenge(code)`.
 
+**The Admin link** — some of the site's members administer its backend, the operator
+among them. For them, `adminHref` is the address that takes them to the backend's
+administration, already signed in; for everyone else it is `null`, so draw the link
+only when it is set:
+
+```jsx
+const { adminHref } = useSession()
+
+{adminHref && <a href={adminHref}>Admin</a>}
+```
+
+⛔ **Navigate to it — a link, or `location.assign(adminHref)` — never `fetch` it.** It
+answers with a redirect carrying a one-time credential that no script on the site is
+to hold. The link decides what to offer, not what is allowed: on the site, an
+administrator's session acts as a member's, and administering happens at the other
+end of the link.
+
 ## Reading
 
 ```jsx
@@ -84,9 +103,9 @@ live source — no `backend` service, or nobody signed in — so render your sit
 Showing "nothing yet" for the first case tells a visitor their content is missing
 when it is simply not being asked for.
 
-**Whose records.** A member reads their own entities and what was shared with them;
-other members' are private unless the site's service was set up to let members read
-each other's. The site's operator reads everything. `scope: 'mine'` lists only the
+**Whose records.** Everyone signed in on the site — its operator too — reads their own
+entities and what was shared with them; other members' are private unless the site's
+service was set up to let members read each other's. `scope: 'mine'` lists only the
 viewer's own.
 
 A record is a summary: `record.brief` holds the fields of the Model's brief section. It
@@ -182,7 +201,7 @@ import { createMockBackend } from '@uniweb/api/mock'
 export default createMockBackend({
   seed: {
     accounts: [
-      { username: 'me', password: 'me', operator: true },   // the site's operator
+      { username: 'me', password: 'me', operator: true },   // runs the site, and gets the Admin link
       { username: 'member', password: 'member' },
     ],
     schemas: {
@@ -210,15 +229,16 @@ production, and nothing in your site's configuration changes between the two.
 
 ⭐ **The mock answers what the backend answers** — the same statuses, bodies and
 refusals, for every route this package uses. It enforces what your schemas declare —
-who may create entries, which sections are insert-only, the fields a section takes —
-and it is as strict as the backend about requests, so a mistake fails here rather
-than in front of a user. Members read and write their own entities and nothing of each
-other's; the operator reads and writes everything (`memberFloor: 'read'` in the seed
-models a service set up to let members read each other's — or per Model,
+which sections are insert-only, the fields a section takes — and it is as strict as
+the backend about requests, so a mistake fails here rather than in front of a user.
+Everyone signed in — the operator too, as on a real site — reads and writes their own
+entities and nothing of anyone else's (`memberFloor: 'read'` in the seed models a
+service set up to let members read each other's — or per Model,
 `memberFloor: { '@acme/course': 'read' }`, so the operator's content is shared while
 each member's own records stay private). A new sign-up must be
-verified: the link is in `mock.outbox` (the standalone server prints it). State is in
-memory: restart to reset.
+verified: the link is in `mock.outbox` (the standalone server prints it). The
+operator's Admin link answers too, landing on a page of the mock's own — the backend's
+administration is not part of it. State is in memory: restart to reset.
 
 There is also a standalone server, for a frontend that is not a Uniweb site:
 
@@ -230,7 +250,7 @@ npx uniweb-api-mock --port 8787
 
 `@uniweb/api/client` carries the same operations as plain functions and imports no
 React: `probeSession`, `signIn`, `listEntities`, `readEntity`, `writeItems`,
-`createEntity`, `deleteEntity`.
+`createEntity`, `deleteEntity`, `adminHref`.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/api",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "The client for a Uniweb site's own backend — session, records, entities — imported by a foundation the way it imports @uniweb/kit.",
   "type": "module",
   "exports": {
@@ -34,7 +34,7 @@
     "node": ">=20.19"
   },
   "dependencies": {
-    "@uniweb/core": "^0.38.0"
+    "@uniweb/core": "^0.38.1"
   },
   "peerDependencies": {
     "react": "^19.0.0"

package/src/client.js

@@ -15,7 +15,7 @@ import { getUniweb, deriveCacheKey } from '@uniweb/core'
 import { resolveService } from '@uniweb/core'
 import { ApiError } from './errors.js'
 import { composeUrl, isCrossOrigin, readBody, UNSAFE } from './http.js'
-import { AUTH, ROUTES, PARAM, FIELD, LIST, OP, GUARDED_OPS, CREATE, READ, SCHEMA, PAGE, TOTP } from './wire.js'
+import { AUTH, ROUTES, PARAM, FIELD, LIST, OP, GUARDED_OPS, CREATE, READ, SCHEMA, PAGE, TOTP, VIEWER } from './wire.js'
 import { Ledger } from './ledger.js'
 
 /**
@@ -353,6 +353,7 @@ export class ApiClient {
       ...account,
       roles: Array.isArray(me?.roles) ? me.roles : [],
       workspace: viewerWorkspace(me?.workspace),
+      adminApp: me?.[VIEWER.capabilities]?.[VIEWER.adminApp] === true,
     })
     if (this._session.viewer && this._session.viewer.uuid !== viewer.uuid) this.forgetViewer()
     return this.setSession({ status: 'authenticated', viewer, error: null })
@@ -627,8 +628,9 @@ export class ApiClient {
    * a `401` too, never an empty list (so `records: []` means empty).
    *
    * `scope` decides whose: the default, `accessible`, is everything the viewer may
-   * read — for a member of a site, their own entities and what was shared with them;
-   * for the operator, everything. `mine` is only what the viewer owns.
+   * read — signed in on a site, their own entities and what was shared with them, the
+   * operator's session included (`VIEWER` in `./wire.js`). `mine` is only what the
+   * viewer owns.
    *
    * ## Paging, as far as it can honestly be absorbed
    *
@@ -921,6 +923,28 @@ export function getClient() {
   return client
 }
 
+/**
+ * The Admin link — the address that takes the viewer to the backend's administration,
+ * signed in — or `null` when there is none to offer: no backend, nobody signed in, or
+ * an account the administration does not admit (`viewer.adminApp`).
+ *
+ * ⛔ **For a navigation — an `<a href>`, `location.assign` — never a `fetch`.** It
+ * answers with a redirect carrying a one-time credential that no script on a site is to
+ * hold, and a fetch that follows it spends the code (`AUTH.memberHandoff`).
+ *
+ * A function of the client's base and a session snapshot, not a method: an instance an
+ * older copy of this package created has neither, and works here all the same.
+ *
+ * @param {ApiClient|null} client
+ * @param {object} [session] - a snapshot; the client's current one by default
+ * @returns {string|null}
+ */
+export function adminHrefOf(client, session = client?.session) {
+  const base = client?.base ?? null
+  if (base === null || session?.status !== 'authenticated' || session.viewer?.adminApp !== true) return null
+  return composeUrl(base, AUTH.memberHandoff)
+}
+
 // ── The functions — the same client, outside React ───────────────────────────
 
 function required() {
@@ -953,6 +977,8 @@ export const writeItems = (args) => required().writeItems(args)
 export const createEntity = (args) => required().createEntity(args)
 /** @see ApiClient#deleteEntity */
 export const deleteEntity = (args) => required().deleteEntity(args)
+/** The Admin link for the current viewer, or `null` — never throws; see `adminHrefOf`. */
+export const adminHref = () => adminHrefOf(getClient())
 
 export { ApiError, kindOf } from './errors.js'
 export { Ledger } from './ledger.js'

package/src/hooks/useRecords.js

@@ -34,8 +34,8 @@ const DISABLED = Object.freeze({ status: 'absent', records: NONE, matched: 0, ha
  * entity for those. ⚠️ `matched` counts the records in this answer, not a total:
  * `hasMore` is true when the page came back full.
  *
- * The default scope is everything the viewer may read — for a member, their own
- * entities and what was shared with them; for the operator, everything.
+ * The default scope is everything the viewer may read — signed in on a site, their
+ * own entities and what was shared with them, the operator included.
  * `scope: 'mine'` is only the viewer's own.
  *
  * Cached under a key scoped to the viewer, so a sign-in re-reads the list for who

package/src/hooks/useSession.js

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useSyncExternalStore } from 'react'
-import { getClient } from '../client.js'
+import { getClient, adminHrefOf } from '../client.js'
 
 const NONE = Object.freeze({ status: 'anonymous', viewer: null, error: null })
 const noSubscribe = () => () => {}
@@ -15,6 +15,10 @@ const noop = async () => NONE
  * affordance on false. `error` is set when the backend could not be asked;
  * `refresh()` asks again.
  *
+ * `adminHref` is the Admin link — set only for a signed-in account the backend's
+ * administration admits, `null` for everyone else, so draw the link only when it is
+ * set. ⛔ Navigate to it, never `fetch` it (`adminHrefOf` in `../client.js`).
+ *
  * Reads the shared snapshot through `useSyncExternalStore`, so every copy of
  * this package on the page sees one session, and the first render on the
  * server matches the first render in the browser.
@@ -24,6 +28,7 @@ const noop = async () => NONE
  *   viewer: object | null,
  *   error: Error | null,
  *   canSignIn: boolean,
+ *   adminHref: string | null,
  *   signOut: () => Promise<void>,
  *   refresh: () => Promise<object>,
  * }}
@@ -48,6 +53,7 @@ export function useSession() {
     viewer: session.viewer,
     error: session.error,
     canSignIn: !!(client && client.enabled),
+    adminHref: adminHrefOf(client, session),
     signOut,
     refresh,
   }

package/src/index.js

@@ -26,6 +26,7 @@ export {
   writeItems,
   createEntity,
   deleteEntity,
+  adminHref,
   ApiError,
   Ledger,
 } from './client.js'

package/src/mock/index.js

@@ -1,7 +1,24 @@
-import { AUTH, ENTITIES, MODELS, PARAM, OP, FIELD, CREATE, PAGE, SCOPE, PROBLEM, GUARDED_OPS } from '../wire.js'
+import { AUTH, ENTITIES, MODELS, PARAM, OP, FIELD, CREATE, PAGE, SCOPE, PROBLEM, GUARDED_OPS, HANDOFF_REFUSAL } from '../wire.js'
 import { MockStore, isUuid, refuse } from './store.js'
 import { DEFAULT_SEED } from './seed.js'
 
+/**
+ * Where the mock's Admin link lands. The backend's administration lives on its own
+ * origin, outside the API, and the mock models none of it: the handoff's redirect
+ * comes here instead, to a page that says so. A path of the mock's, not the backend's.
+ */
+const ADMIN_PAGE = '/admin'
+
+const escapeHtml = (value) =>
+  String(value).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c])
+
+function adminPage(account) {
+  const who = account ? `Signed in as <b>${escapeHtml(account.handle)}</b>. ` : ''
+  return `<!doctype html><meta charset="utf-8"><title>Administration</title>
+<p>${who}On a live site, the Admin link opens the backend's administration here, signed in. The local mock has none to open.</p>
+`
+}
+
 /**
  * A mock of a site's `backend` service, for local development.
  *
@@ -36,12 +53,15 @@ import { DEFAULT_SEED } from './seed.js'
  *
  * ## What it models, and what it does not
  *
- * One operator (`operator: true` on a seeded account) and members; a member reads
- * and writes their own entities and nothing of another's (unless the seed's
- * `memberFloor` says the service lets them), the operator reads and writes all;
+ * One operator (`operator: true` on a seeded account) and members; everyone signed
+ * in — the operator too, as on a real site — reads and writes their own entities and
+ * nothing of another's (unless the seed's `memberFloor` says the service lets them);
  * anyone signed in may create entries of any Model (Models are open); sign-up
- * leaves an account unverified until the link in `mock.outbox` is followed. It
- * does not model entitlements behind `via`, nested sections, or second factors.
+ * leaves an account unverified until the link in `mock.outbox` is followed. The
+ * operator is the account the backend's administration admits, so its Admin link
+ * answers — with a redirect to a page of the mock's own, since the administration
+ * itself is not modelled. It does not model entitlements behind `via`, nested
+ * sections, or second factors.
  *
  * @param {object} [options]
  * @param {object} [options.seed] - accounts, schemas and entities to start from (see `MockStore`)
@@ -199,6 +219,14 @@ export function createMockBackend({ seed = DEFAULT_SEED, prefix = '/_api', signe
         const viewer = store.viewer()
         return viewer ? json(200, viewer) : unauthorized()
       }
+      if (path === AUTH.memberHandoff && method === 'GET') {
+        if (!store.account) return unauthorized()
+        if (!store.account.operator) return problem(HANDOFF_REFUSAL)
+        // The backend redirects to its administration on its own origin. The mock has
+        // none, so the redirect lands on a page of its own that says so (`ADMIN_PAGE`).
+        // Relative, so it lands under whatever path the mock is mounted at.
+        return new Response(null, { status: 302, headers: { location: `..${ADMIN_PAGE}` } })
+      }
       if (path === AUTH.login && method === 'POST') {
         const b = await body(request)
         return fields(b, ['username', 'password'], '{"username": ..., "password": ...}') ?? answer(store.signIn(b))
@@ -391,6 +419,11 @@ export function createMockBackend({ seed = DEFAULT_SEED, prefix = '/_api', signe
       }
     }
 
+    // ── Where the Admin link lands ──────────────────────────────────────────
+    if (path === ADMIN_PAGE && method === 'GET') {
+      return new Response(adminPage(store.account), { status: 200, headers: { 'content-type': 'text/html; charset=utf-8' } })
+    }
+
     return problem({ status: 404, title: 'Not Found', detail: `no route for ${method} ${path}` })
   }
 

package/src/mock/store.js

@@ -19,10 +19,12 @@ import { checkItemWrite, OUTCOME } from './schema-shape.js'
  *   unless shared. A service can be set up to let members read (or edit) each
  *   other's — the seed's `memberFloor` models that choice. *(Until 2026-09-18 the
  *   backend gave every member read access to every other member's entities.)*
- * - **The operator** — the account that runs the site's service — holds
- *   `system_admin`, creates the Models only the operator may, and may write
- *   anything. It is a member of the site's unit like everyone else, so what it
- *   makes is its own. A seeded account is the operator with `operator: true`.
+ * - **The operator** — the account that runs the site's service — owns what the
+ *   seed gives it. ⛔ **Signed in on the site it holds a member's rights**, like
+ *   everyone: no `system_admin` in `roles`, and nothing of another member's unless
+ *   shared — a site runs third-party code with its member's session. *(Until
+ *   2026-10-10 the operator's session held `system_admin` and read and wrote
+ *   everything.)* A seeded account is the operator with `operator: true`.
  *
  * ⛔ **Seeded fixtures plus in-memory mutation, and deliberately not a database.**
  * A mock that grows a schema and migrations becomes a second implementation that
@@ -207,15 +209,21 @@ export class MockStore {
     return this.session?.account ?? null
   }
 
-  /** The viewer, in the shape `/auth/me` answers. */
+  /**
+   * The viewer, in the shape `/auth/me` answers. `roles` are the session's, and a
+   * session on a site holds no administrator's — the operator's neither. Whether the
+   * backend's administration admits the ACCOUNT is `capabilities.admin_app`: the
+   * operator's yes, a member's no.
+   */
   viewer(account = this.account) {
     if (!account) return null
     return {
       account: this.identity(account),
-      roles: account.operator ? [{ role: 'system_admin', scope_unit_id: null }] : [],
+      roles: [],
       // A request that names no workspace — as this package's never do — lands in the
       // home org, which every account belongs to. Both null would mean a non-member.
       workspace: { ...HOME_ORG },
+      capabilities: { admin_app: account.operator === true },
     }
   }
 
@@ -229,7 +237,8 @@ export class MockStore {
     if (!account.verified) return refuse(403, PROBLEM.notVerified, 'verify your email address before signing in')
     this.session = { account }
     const expires = new Date(Date.now() + 30 * 24 * 3600 * 1000).toISOString()
-    return { body: { token: `mock-${account.uuid}`, expires_at: expires, account: this.identity(account) } }
+    // No `token`: a site's backend answers a sign-in with the session cookie alone.
+    return { body: { expires_at: expires, account: this.identity(account) } }
   }
 
   signOut() {
@@ -468,28 +477,31 @@ export class MockStore {
     return floor[entity.model] ?? null
   }
 
-  /** The operator, the owner — or any member, when the service lets members read each other's. */
+  /**
+   * The owner — or any member, when the service lets members read each other's. The
+   * operator is a member here like everyone: a session on a site holds no
+   * administrator's rights.
+   */
   mayRead(entity) {
     const me = this.account
-    return !!me && (me.operator || entity.owner_id === me.id || this.floorFor(entity) != null)
+    return !!me && (entity.owner_id === me.id || this.floorFor(entity) != null)
   }
 
   mayEdit(entity) {
     const me = this.account
-    return !!me && (me.operator || entity.owner_id === me.id || this.floorFor(entity) === 'edit')
+    return !!me && (entity.owner_id === me.id || this.floorFor(entity) === 'edit')
   }
 
   /**
    * Which branch lets the viewer read a row, as the backend names it — the first to
-   * answer in its order: `owner`, `grant`, `rbac`, `unit_member`. The operator's own rows
-   * are `owner` like anyone's, and the rest it reads as `system_admin`. *(Until
-   * 2026-09-18 the operator was not a member of the site's unit, and ownership speaks
-   * only for a member — so its own rows answered `rbac` too.)*
+   * answer in its order: `owner`, `grant`, `rbac`, `unit_member`. A session's own rows
+   * are `owner`, the operator's too, and the rest it reads by the service's floor.
+   * *(Until 2026-10-10 the operator's session read the rest as `rbac`, through
+   * `system_admin`.)*
    */
   via(entity) {
     const me = this.account
     if (entity.owner_id === me?.id) return 'owner'
-    if (me?.operator) return 'rbac'
     return 'unit_member'
   }
 

package/src/wire.js

@@ -99,8 +99,32 @@ export const AUTH = {
   verify: '/auth/verify',
   resetRequest: '/auth/reset/request',
   resetConfirm: '/auth/reset/confirm',
+  /**
+   * `GET /auth/member-handoff` — the Admin link (`adminHref` in `./client.js`).
+   * ⛔ **A navigation, never a fetch.** For an account the backend's administration
+   * admits (`VIEWER`'s `admin_app`), it answers `302` toward that administration, on
+   * the backend's own origin, carrying a one-time credential no script on a site is to
+   * hold — a fetch learns nothing from the redirect, and one that follows it spends
+   * the code. `401` no session · `403` an account it does not admit
+   * (`HANDOFF_REFUSAL`) · `404` a backend no site reaches · `503` a backend never told
+   * its own origin — each problem JSON, branched on by `title` or `reason`, never
+   * `detail`. **MEASURED** by backend, 2026-10-10.
+   */
+  memberHandoff: '/auth/member-handoff',
 }
 
+/**
+ * The handoff's `403`, as sent — an account the administration does not admit.
+ * **MEASURED** by backend, 2026-10-10. This package never reads it: the handoff is a
+ * navigation, so the browser shows it. The mock answers it.
+ */
+export const HANDOFF_REFUSAL = Object.freeze({
+  status: 403,
+  title: 'Admin Role Required',
+  detail: "the admin app admits a system_admin or an administrator of this deployment's home org",
+  reason: 'admin_role_required',
+})
+
 /**
  * The bodies of the auth routes. **MEASURED.** This package hands a caller's
  * fields to the backend unchanged, so these are the names a caller must use — a
@@ -108,13 +132,18 @@ export const AUTH = {
  *
  * | route | body | answer |
  * |---|---|---|
- * | login | `{ username, password }` | `200 { token, expires_at, account }` + the session cookie · `200 { status: 'totp_required', challenge_token }` · `401` wrong credential · `403 Email Not Verified` |
+ * | login | `{ username, password }` | `200 { expires_at, account }` + the session cookie · `200 { status: 'totp_required', challenge_token }` · `401` wrong credential · `403 Email Not Verified` |
  * | challenge | `{ challenge_token, code }` | as login's `200`; a bad token or code is `401` |
  * | register | `{ username, email, password }` | `202 { status: 'verification_required', email }` — the same answer for an address already taken; a taken **username** is `409` |
  * | reset request | `{ email }` | `202 { status: 'reset_requested' }` whether or not the address is known |
  * | reset confirm | `{ token, new_password, code? }` | `200 { reset: true }`; a bad token is `400 Validation`; `code` is required when a second factor is enrolled |
  * | logout | none | `204`; with no session to end, `401` |
- * | me | none | `200 { account: { uuid, username, handle }, roles, workspace: { unit_uuid, handle } }` · `401` |
+ * | me | none | `200 { account: { uuid, username, handle }, roles, workspace: { unit_uuid, handle }, capabilities: { admin_app } }` · `401` |
+ *
+ * ⭐ **The session is the cookie, and only the cookie.** A site's backend answers a
+ * sign-in with no `token` (since 2026-10-10, MEASURED by backend; `token` was in the
+ * reply until then), and this package never read one: it signs in, then asks
+ * `/auth/me` who the viewer is.
  */
 export const AUTH_BODY = {
   login: ['username', 'password'],
@@ -135,7 +164,13 @@ export const TOTP = {
  * The viewer, as `/auth/me` answers. **MEASURED.**
  *
  * `roles` is a list of `{ role, scope_unit_id }` — `role` one of `system_admin`,
- * `unit_admin`, `content_editor`, `user`. An ordinary member holds none: `[]`.
+ * `unit_admin`, `content_editor`, `user`. ⭐ **They describe the session, not the
+ * account.** On a site's `backend` service a session signed in on the site holds no
+ * `system_admin` and no `unit_admin` of the home org — the operator's neither — so
+ * `roles` never name an administrator there: a site runs third-party code with its
+ * member's session, and a bug in that code must not act as one. An ordinary member
+ * holds none: `[]`. *(Since 2026-10-10, MEASURED by backend; until then the operator's
+ * session on a site held `system_admin`.)*
  *
  * `workspace` is `{ unit_uuid, handle }` — **the workspace the request works in**. This
  * package's requests name none, and on a site's `backend` service such a request lands in
@@ -147,14 +182,26 @@ export const TOTP = {
  * function the route serializes, 2026-09-23.)*
  *
  * ⛔ **Neither is an operator signal.** Every member of a site's service works in the
- * same home org, so it reads the same for the operator and for someone who signed up a
- * minute ago. The operator holds `system_admin`. Better than either: ask about the
- * thing — a single-entity read carries `can_edit`, the write gate's own answer.
+ * same home org, so `workspace` reads the same for the operator and for someone who
+ * signed up a minute ago, and on a site `roles` name no administrator. Ask about the
+ * thing instead — a single-entity read carries `can_edit`, the write gate's own answer
+ * for this session.
+ *
+ * `capabilities.admin_app` is the one fact here about the ACCOUNT rather than the
+ * session: `true` when the backend's administration admits it — the operator, and
+ * whoever else administers the service. The viewer carries it as `adminApp`, and the
+ * package then offers the Admin link (`AUTH.memberHandoff`). It decides what to OFFER,
+ * never what is allowed on the site, where the session acts as a member whatever the
+ * account holds. `true` or `false` for every signed-in caller, at the same path as on
+ * `/session/bootstrap` (MEASURED by backend, 2026-10-10); anything else reads as
+ * `false`.
  */
 export const VIEWER = {
   account: 'account',
   roles: 'roles',
   workspace: 'workspace',
+  capabilities: 'capabilities',
+  adminApp: 'admin_app',
 }
 
 /**
@@ -224,11 +271,12 @@ export const PARAM = {
  * The list's `scope`. Default `accessible` — everything the viewer may read; `mine`
  * — only what the viewer owns.
  *
- * What a member of a site may read: their own entities, and what was shared with
- * them. Other members' entities are private to their owners unless the site's
- * service was set up to let members read each other's. The operator reads
- * everything. *(A site's service let every member read every other member's
- * entities until 2026-09-18 — measured, and changed on the backend.)*
+ * What a session signed in on a site may read — any member's, the operator's
+ * included (`VIEWER`): its own entities, and what was shared with it. Other members'
+ * entities are private to their owners unless the site's service was set up to let
+ * members read each other's. *(A site's service let every member read every other
+ * member's entities until 2026-09-18, and the operator's session read everything until
+ * 2026-10-10 — both measured, and changed on the backend.)*
  */
 export const SCOPE = {
   mine: 'mine',
@@ -342,9 +390,9 @@ export const CREATE = {
  * paging; a page that came back full is the only sign there may be more.
  *
  * `via` names why the viewer can read the row — `owner`, `grant`, `rbac`,
- * `unit_member`, `entitlement`; treat an unknown value as "no opinion". The
- * operator's own rows are `owner` and the rest `rbac` — since 2026-09-18; an older
- * backend answers `rbac` on the operator's own rows too. ⚠️ An empty list means
+ * `unit_member`, `entitlement`; treat an unknown value as "no opinion". A session's
+ * own rows are `owner` — the operator's too. *(Until 2026-10-10 the operator's session
+ * on a site read the rest as `rbac`, through `system_admin`.)* ⚠️ An empty list means
  * empty: a lapsed session is a `401`, never `200 []`.
  */
 export const LIST = {