@jskit-ai/agent-docs 0.1.283 → 0.1.285

package/skills/jskit/references/patterns/crud/crud-screen-set/example/books/BookViewPage.vue

@@ -3,13 +3,13 @@ import CrudDeleteAction from "@jskit-ai/http-web/client/components/CrudDeleteAct
 import CrudViewScreen from "@jskit-ai/http-web/client/components/CrudViewScreen";
 import { useCrudDeleteAction } from "@jskit-ai/http-web/client/composables/useCrudDeleteAction";
 import { useCrudViewScreen } from "@jskit-ai/http-web/client/composables/useCrudViewScreen";
-import { bookResource } from "@local/books/shared";
+import { bookCrud } from "@local/books/shared";
 
 // Up returns to the page the book was opened from, or else to the list.
 definePage({ meta: { jskit: { title: "Book", parent: "/books" } } });
 
 const screen = useCrudViewScreen({
-  resource: bookResource,
+  resource: bookCrud,
   resourceNamespace: "books",
   apiUrlTemplate: "/books/:bookId",
   recordIdParam: "bookId",
@@ -22,7 +22,7 @@ const screen = useCrudViewScreen({
 
 const deleteAction = useCrudDeleteAction({
   screen,
-  resource: bookResource,
+  resource: bookCrud,
   resourceNamespace: "books",
   apiUrlTemplate: "/books/:bookId"
 });

package/skills/jskit/references/patterns/database/mysql-application/PATTERN.md

@@ -11,8 +11,10 @@ requires: @jskit-ai/database-runtime-mysql
 ## Use when
 
 Use this pattern when an application deliberately chooses MySQL or MariaDB.
-Install `@jskit-ai/database-runtime-mysql`; its normal npm dependencies provide
-the database runtime, Knex, and `mysql2` without a package-setup wizard.
+Install `@jskit-ai/database-runtime` and `@jskit-ai/database-runtime-mysql`
+without a package-setup wizard: the runtime brings Knex and the driver brings
+`mysql2`. The driver takes the runtime as a peer, so the application holds its
+one copy.
 
 ## Do not use when
 
@@ -50,8 +52,11 @@ Knex discovers package-owned migrations from the installed dependency graph.
 `example/package.json` contains the runtime dependency and database scripts.
 `example/knexfile.js` loads an optional local `.env` and fixes the MySQL dialect.
 `example/scripts/prepare-database.js` is the portable migrate-then-seed
-entrypoint for managed sessions and deployments. `example/.env.example` names
-the connection values and separate test databases without a secret.
+entrypoint for managed sessions and deployments. It loads the optional `.env`
+as the knexfile does, and migrates the database `DB_NAME` names without
+creating it: the hosting environment or a database administrator creates it
+first. `example/.env.example` names the connection values and separate test
+databases without a secret.
 
 `example/.github/workflows/verify.yml` is a normal app-owned CI workflow with
 exactly one database service: `mariadb` (`mariadb:11.4`, `MARIADB_*`

package/skills/jskit/references/patterns/database/mysql-application/example/package.json

@@ -9,6 +9,7 @@
     "test": "jskit test --databases"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime-mysql": "0.1.260"
+    "@jskit-ai/database-runtime": "0.1.264",
+    "@jskit-ai/database-runtime-mysql": "0.1.262"
   }
 }

package/skills/jskit/references/patterns/database/mysql-application/example/scripts/prepare-database.js

@@ -1,3 +1,11 @@
 import { prepareDatabaseFromApp } from "@jskit-ai/database-runtime/server/databaseSetup";
 
+try {
+  process.loadEnvFile(".env");
+} catch (error) {
+  if (error?.code !== "ENOENT") {
+    throw error;
+  }
+}
+
 await prepareDatabaseFromApp({ client: "mysql2", environment: process.env });

package/skills/jskit/references/patterns/database/postgres-application/PATTERN.md

@@ -11,8 +11,9 @@ requires: @jskit-ai/database-runtime-postgres
 ## Use when
 
 Use this pattern when an application deliberately chooses PostgreSQL. Install
-`@jskit-ai/database-runtime-postgres`; its normal npm dependencies provide the
-database runtime, Knex, and `pg` without a package-setup wizard.
+`@jskit-ai/database-runtime` and `@jskit-ai/database-runtime-postgres` without
+a package-setup wizard: the runtime brings Knex and the driver brings `pg`. The
+driver takes the runtime as a peer, so the application holds its one copy.
 
 ## Do not use when
 
@@ -50,8 +51,11 @@ Knex discovers package-owned migrations from the installed dependency graph.
 `example/package.json` contains the runtime dependency and database scripts.
 `example/knexfile.js` loads an optional local `.env` and fixes the PostgreSQL
 dialect. `example/scripts/prepare-database.js` is the portable
-migrate-then-seed entrypoint for managed sessions and deployments.
-`example/.env.example` names the five connection values without a secret.
+migrate-then-seed entrypoint for managed sessions and deployments. It loads
+the optional `.env` as the knexfile does, and migrates the database `DB_NAME`
+names without creating it: the hosting environment or a database
+administrator creates it first. `example/.env.example` names the five
+connection values without a secret.
 
 Tests get their own databases from
 `@jskit-ai/database-runtime/server/testDatabases`. The `test` script runs

package/skills/jskit/references/patterns/database/postgres-application/example/package.json

@@ -9,6 +9,7 @@
     "test": "jskit test --databases"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime-postgres": "0.1.259"
+    "@jskit-ai/database-runtime": "0.1.264",
+    "@jskit-ai/database-runtime-postgres": "0.1.261"
   }
 }

package/skills/jskit/references/patterns/database/postgres-application/example/scripts/prepare-database.js

@@ -1,3 +1,11 @@
 import { prepareDatabaseFromApp } from "@jskit-ai/database-runtime/server/databaseSetup";
 
+try {
+  process.loadEnvFile(".env");
+} catch (error) {
+  if (error?.code !== "ENOENT") {
+    throw error;
+  }
+}
+
 await prepareDatabaseFromApp({ client: "pg", environment: process.env });

package/skills/jskit/references/patterns/database/table-resource/PATTERN.md

@@ -0,0 +1,120 @@
+---
+id: database/table-resource
+title: Table resource
+summary: Describe one database table once (its fields, columns, ownership, search and sort) so its owner feature reads and writes it through a scoped handle.
+keywords: database, defaultTo, defineTableResource, lockVersionField, lookup, owns, ownership, resource, system, table, workspace_or_shared
+requires: @jskit-ai/resource-core
+---
+
+# Table resource
+
+## Use when
+
+Use this pattern for every table an application owns, whether or not it is
+served over HTTP. The table resource is the table's one description; the
+feature that owns the table lists it in `owns`, and every read and write goes
+through the handle setup receives
+([data access](https://mobily-enterprises.github.io/jskit-ai/guide/framework/data-access)).
+
+## Do not use when
+
+Do not describe a table twice, and do not describe another feature's table:
+ask its owner. A table with standard screens over HTTP adds a CRUD contract on
+this resource (`crud/crud-contract`), not a second resource.
+
+## Product decisions
+
+- who owns a row, always stated: nobody (`public`), a workspace, a user, a
+  user inside a workspace, a workspace with rows shared with every
+  workspace, or no one any request may reach (`system`)
+- the fields, which are required, searchable or hidden, and their defaults
+- whether people edit records from forms read earlier (a version number)
+- the default order of lists
+
+## Invariants
+
+- One table, one table resource, one owner feature.
+- `ownership` matches the owner columns: `workspace` filters on the hidden
+  `workspaceId` field, `user` on `userId`, `workspace_user` on both, and
+  `workspace_or_shared` reads a workspace's rows plus the rows whose
+  `workspaceId` is null. The handle adds that predicate to every statement and
+  stamps new rows from the caller's context. A `system` table has no owner
+  columns, and its handle refuses every call whose context is not a system
+  context, before any statement: it is for rows that only the owner's
+  background work keeps (queues, leases, run state), never served to a request.
+- A field's default value is `defaultTo`; `default` is refused, since
+  json-rest-api never read it.
+- A field with `defaultTo` is not `required`: a create is checked for
+  required fields before defaults apply, so `defineTableResource` refuses the
+  two together.
+- `lockVersionField` names an integer field over a non-null integer column
+  with a starting value; `patch(id, changes, { ...options, lockVersion })` then refuses
+  stale edits with a 409.
+- The definition is shared with the client, so it holds no server-only keys:
+  the row policy, hooks, server-only search entries and computed query fields
+  go in the owner's `owns` entry.
+- The source-controlled migration and the resource describe the same table.
+
+## Framework APIs
+
+`defineTableResource()` from `@jskit-ai/resource-core/shared/tableResource`
+freezes the description and refuses the CRUD contract's keys (`namespace`,
+`apiAccess`, `operations`, `messages`), `autofilter` and the server-only keys,
+each with an error naming where it belongs.
+
+A field that looks up a record of another resource names that resource's
+namespace with `lookup`:
+
+```js
+customerId: { type: "id", required: true, search: true, lookup: "customers" }
+```
+
+`defineTableResource()` expands it, where `lookup` stood, to:
+
+```js
+relation: { kind: "lookup", namespace: "customers", valueKey: "id" },
+belongsTo: "customers",  // the table resource named by the namespace, camel-cased
+as: "customer",          // the field key without its Id suffix
+ui: { formControl: "autocomplete" }
+```
+
+Keys you write beside `lookup` win: `belongsTo` and `as` replace the
+filled-in values, and `relation` and `ui` are merged over them. A field whose
+key has no `Id` suffix must write `as`.
+
+The owner, on the server:
+
+```js
+const OrdersFeature = defineFeature({
+  id: "orders",
+  owns: [{ resource: orderResource, rowPolicy: ordersTheActorMayHandle }],
+  provides: { orders: "orders" },
+  setup: ({ resources }) => ({ orders: createOrdersRepository({ orders: resources.orders }) })
+});
+```
+
+## Example files
+
+- `example/orderResource.js` is a workspace-owned orders table with a lookup,
+  defaults, a version number, a text search and a default sort.
+
+## Variation points
+
+Rename the table and fields, pick the ownership kind the product's owner
+columns support, add search entries and sorts. A computed output field is
+`storage: { virtual: true }` here and a `queryFields` entry in `owns`.
+
+## Verification
+
+- Import the resource and check its ownership, fields and lookups.
+- Rebuild the table from source-controlled migrations in a disposable database.
+- Give each repository path a scope test (`expectScoped`) and a flat-query
+  test (`expectFlatQueries`) from `@jskit-ai/resource-runtime/test`.
+
+## Avoid
+
+- a second table resource for the same table
+- `where workspace_id = ?` written by hand: ownership adds it
+- a row policy, hooks or SQL in the shared definition
+- `default:` instead of `defaultTo:`
+- `required: true` beside `defaultTo`

package/skills/jskit/references/patterns/database/table-resource/example/orderResource.js

@@ -0,0 +1,25 @@
+import { defineTableResource } from "@jskit-ai/resource-core/shared/tableResource";
+
+// The orders table: one workspace owns each row. Shared with the client; the
+// owner feature lists it in `owns` on the server.
+const orderResource = defineTableResource({
+  name: "orders",
+  tableName: "orders",
+  ownership: "workspace",
+  lockVersionField: "lockVersion",
+  schema: {
+    workspaceId: { type: "id", required: true, hidden: true },
+    customerId: { type: "id", required: true, search: true, lookup: "customers" },
+    reference: { type: "string", maxLength: 64, required: true, search: true },
+    status: { type: "string", maxLength: 32, search: true, defaultTo: "open" },
+    total: { type: "number", defaultTo: 0 },
+    lockVersion: { type: "integer", min: 0, readOnly: true, defaultTo: 0 },
+    createdAt: { type: "dateTime", temporalPrecision: 0, readOnly: true }
+  },
+  searchSchema: {
+    q: { type: "string", oneOf: ["reference"], filterOperator: "like" }
+  },
+  defaultSort: ["-createdAt"]
+});
+
+export { orderResource };

package/skills/jskit/references/patterns/realtime/realtime-application/PATTERN.md

@@ -43,6 +43,13 @@ name and audience. Client features use `RealtimeClientProvider` and the public
 listener registration helpers from `@jskit-ai/realtime`. Use the normal shell
 placement registry for the optional status component.
 
+An audience's `audienceUsers({ event, options })` reads in a context scoped to
+the event's workspace, user or workspace user. An application whose action
+events declare such an audience registers `RealtimeAudienceScopeFeature` from
+`@jskit-ai/realtime/server/RealtimeAudienceScopeFeature`, which provides those
+contexts, or realtime refuses to boot. An audience that reads only public
+tables marks itself `publicTablesOnly: true` and reads with no context.
+
 ## Example files
 
 `example/package.json` declares realtime and shell runtime packages.

package/skills/jskit/references/patterns/realtime/realtime-application/example/package.json

@@ -2,7 +2,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/realtime": "0.2.19",
-    "@jskit-ai/shell-web": "0.2.16"
+    "@jskit-ai/realtime": "0.2.21",
+    "@jskit-ai/shell-web": "0.2.18"
   }
 }

package/skills/jskit/references/patterns/rewards/google-rewarded/PATTERN.md

@@ -38,7 +38,7 @@ capability composition beside `RewardedClientProvider` from
 `client.rewarded-delivery`; the generic UI supplies `client.rewarded`.
 Use `useRewardedRuntime().requireUnlock({ gateKey, workspaceSlug })` for gates.
 Separately supply server capability `rewarded.grant-policy` with
-`authorizeGrant({ session, context, trx })`; only `true` permits a grant.
+`authorizeGrant({ session, context, options })`; only `true` permits a grant.
 This delivery example does not provide or choose the server policy.
 
 ## Example files

package/skills/jskit/references/patterns/server/feature-package/PATTERN.md

@@ -2,7 +2,7 @@
 id: server/feature-package
 title: App-local server feature package
 summary: Define a server feature through explicit capabilities and first-class actions, adding services or repositories only when its domain earns them.
-keywords: actions, feature, json-rest, knex, orchestration, package, provider, repository, routes, server
+keywords: actions, aggregate, feature, handle, orchestration, owns, package, provider, repository, routes, server, table resource
 requires: @jskit-ai/kernel
 ---
 
@@ -17,16 +17,18 @@ actions whose implementations capture those exact dependencies.
 
 The concrete `booking-engine` example is intentionally repository-free. The
 `variations/` directory preserves the two important escalations: a meaningful
-orchestration service and an explicit custom Knex repository for a domain that
-cannot fit the normal resource APIs.
+orchestration service and a repository over a table the feature owns, for a
+domain whose operations are not CRUD screens.
 
 ## Do not use when
 
 Do not create a package for a tiny composition callback or one route with no
-domain behavior. Use the CRUD resource patterns when ordinary resource
-operations fit. Do not select custom Knex merely because SQL is familiar; it
-is an explicit exception for persistence behavior the higher-level APIs cannot
-express.
+domain behavior. Use the CRUD feature pattern when the table's operations are
+screens over HTTP. Do not reach for Knex because SQL is familiar: a table's
+reads and writes go through its handle, and a report the handle cannot express
+is one `scopedQuery()` method, as the
+[data access guide](https://mobily-enterprises.github.io/jskit-ai/guide/framework/data-access)
+says.
 
 ## Product decisions
 
@@ -50,7 +52,7 @@ questionnaire.
 - Every factory, action creator and hook that receives a collaborator names its
   type in a JSDoc `@param`: `import("./types.js").<Name>` or
   `ReturnType<typeof createX>` inside the package, the owner's `./server/types`
-  across packages; a Knex client is database-runtime's `RuntimeKnex`.
+  across packages; a table's handle is resource-runtime's `ResourceHandle`.
 - Collaborators are required. There is no `= null`, `= {}` or no-op default,
   no `typeof` probe, no optional call and no "requires x" guard: the capability
   runtime refuses to start without a required token.
@@ -80,9 +82,11 @@ questionnaire.
 - One copy of each pure helper per package, imported directly. Files stay under
   750 lines and functions under 600, one concern per factory.
 - The service orchestrates the feature and does not issue SQL directly.
-- A repository owns persistence and accepts transaction/context options.
-- The normal persistence lane uses a public or documented high-level resource
-  API; custom Knex is an explicit, reviewed exception.
+- A feature that owns a table lists its table resource in `owns`; setup
+  receives the table's handle, and only its repository uses it. One table has
+  one owner.
+- A repository holds the owner's queries on its handles and passes each call's
+  options (context and transaction) on.
 - Ordinary HTTP and assistant exposure is projected from actions. Explicit
   route code exists only for a genuinely custom transport.
 - Register routes, actions, contributors, and other catalogue entries during
@@ -97,8 +101,8 @@ questionnaire.
 The provider uses `defineFeature()` from
 `@jskit-ai/kernel/server/features`. The runtime supplies named capabilities
 and the feature publishes its actions through the dedicated action catalogue.
-The custom persistence variation uses `createWithTransaction()` from
-`@jskit-ai/database-runtime/shared`.
+The persistence variation owns its table with `defineFeature({ owns })` and
+reads totals with the handle's `aggregate()`.
 
 ## Example files
 
@@ -147,9 +151,11 @@ const SeasonalAvailabilityFeature = defineFeature({
 `example/variations/availabilityEngineActions.js` and
 `example/variations/orchestratorService.js` show the repository-free lane.
 `example/variations/InvoiceRollupFeature.js`,
-`example/variations/invoiceRollupActions.js` and
-`example/variations/customKnexRepository.js` show the explicit custom
-persistence lane. `example/variations/types.js` declares the
+`example/variations/invoiceRollupActions.js`,
+`example/variations/invoiceResource.js` and
+`example/variations/ownedTableRepository.js` show the persistence lane: the
+feature owns the invoices table, and its repository reads monthly totals with
+`aggregate()`, scoped to the caller's workspace by the handle. `example/variations/types.js` declares the
 `AvailabilityEngine` and `InvoiceRollup` types.
 
 The [typed features guide](https://mobily-enterprises.github.io/jskit-ai/guide/framework/typed-features)
@@ -172,7 +178,9 @@ illustrative status query with narrow product language before shipping.
   denied access.
 - Exercise HTTP routes only when the package owns them.
 - Test service orchestration independently from persistence.
-- Test repository transaction and context forwarding.
+- Test each repository path against a second workspace's rows
+  (`expectScoped`) and at two sizes (`expectFlatQueries`), from
+  `@jskit-ai/resource-runtime/test`.
 - Rebuild any schema from immutable migrations in a disposable database.
 - Run the app's package, server, and integration verification.
 

package/skills/jskit/references/patterns/server/feature-package/example/booking-engine/package.json

@@ -5,7 +5,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/kernel": "0.2.13",
+    "@jskit-ai/kernel": "0.2.15",
     "json-rest-schema": "^1.0.17"
   },
   "exports": {

package/skills/jskit/references/patterns/server/feature-package/example/variations/InvoiceRollupFeature.js

@@ -1,19 +1,18 @@
 import { defineFeature } from "@jskit-ai/kernel/server/features";
-import { createInvoiceRollup } from "./customKnexRepository.js";
+import { invoiceResource } from "./invoiceResource.js";
+import { createInvoiceRollup } from "./ownedTableRepository.js";
 import { createInvoiceRollupActions } from "./invoiceRollupActions.js";
 
 const InvoiceRollupFeature = defineFeature({
   id: "feature.invoice-rollup",
   domain: "invoices",
-  requires: {
-    database: "runtime.database"
-  },
+  owns: [invoiceResource],
   provides: {
     invoiceRollup: "feature.invoice-rollup"
   },
-  /** @param {{ database: import("@jskit-ai/database-runtime/server/types").RuntimeDatabase }} capabilities */
-  setup({ database }) {
-    return { invoiceRollup: createInvoiceRollup({ knex: database.knex }) };
+  /** @param {{ resources: { invoices: import("@jskit-ai/resource-runtime/server/types").ResourceHandle } }} capabilities */
+  setup({ resources }) {
+    return { invoiceRollup: createInvoiceRollup({ invoices: resources.invoices }) };
   },
   actions({ invoiceRollup }) {
     return createInvoiceRollupActions({ invoiceRollup });

package/skills/jskit/references/patterns/server/feature-package/example/variations/invoiceResource.js

@@ -0,0 +1,15 @@
+import { defineTableResource } from "@jskit-ai/resource-core/shared/tableResource";
+
+/** The invoices table: its fields, and the workspace that owns each row. Shared with the client. */
+const invoiceResource = defineTableResource({
+  name: "invoices",
+  tableName: "invoices",
+  ownership: "workspace",
+  schema: {
+    status: { type: "string", required: true, search: true },
+    amount: { type: "number", required: true },
+    issuedAt: { type: "dateTime", required: true }
+  }
+});
+
+export { invoiceResource };

package/skills/jskit/references/patterns/server/feature-package/example/variations/invoiceRollupActions.js

@@ -1,6 +1,6 @@
 import { emptyInputValidator } from "@jskit-ai/kernel/server/actions/actionContributorHelpers";
 
-const ACTION_GET_ROLLUP_STATUS = "invoices.rollup.status.read";
+const ACTION_READ_MONTHLY_TOTALS = "invoices.rollup.monthly-totals.read";
 
 /** The fields every invoice rollup query shares, spread first into each definition: they run on the admin surface. */
 const ROLLUP_QUERY = Object.freeze({
@@ -15,12 +15,12 @@ function createInvoiceRollupActions({ invoiceRollup }) {
   return Object.freeze([
     Object.freeze({
       ...ROLLUP_QUERY,
-      id: ACTION_GET_ROLLUP_STATUS,
+      id: ACTION_READ_MONTHLY_TOTALS,
       input: emptyInputValidator,
       output: null,
-      execute: (input, context) => invoiceRollup.getStatus(input, { context })
+      execute: (input, context) => invoiceRollup.totalsByMonth(input, { context })
     })
   ]);
 }
 
-export { ACTION_GET_ROLLUP_STATUS, createInvoiceRollupActions };
+export { ACTION_READ_MONTHLY_TOTALS, createInvoiceRollupActions };

package/skills/jskit/references/patterns/server/feature-package/example/variations/ownedTableRepository.js

@@ -0,0 +1,27 @@
+/**
+ * The invoice rollup's persistence: the queries of the invoices table its
+ * feature owns, on that table's handle. The handle adds the workspace to every
+ * statement, so no query names it.
+ * @param {{ invoices: import("@jskit-ai/resource-runtime/server/types").ResourceHandle }} dependencies
+ */
+function createInvoiceRollup({ invoices }) {
+  /**
+   * How many invoices of each status the workspace issued each month, and their total.
+   * @param {Record<string, never>} input
+   * @param {import("@jskit-ai/resource-runtime/server/types").ResourceCallOptions} options
+   */
+  function totalsByMonth(input, options) {
+    return invoices.aggregate({
+      groupBy: ["status", { field: "issuedAt", bucket: "month", as: "month" }],
+      measures: { invoices: { count: "*" }, amount: { sum: "amount" } },
+      sort: ["month"]
+    }, options);
+  }
+
+  return Object.freeze({
+    withTransaction: invoices.withTransaction,
+    totalsByMonth
+  });
+}
+
+export { createInvoiceRollup };

package/skills/jskit/references/patterns/server/feature-package/example/variations/types.js

@@ -2,6 +2,6 @@
 // capabilities, for features that require them.
 
 /** @typedef {ReturnType<typeof import("./orchestratorService.js").createAvailabilityEngine>} AvailabilityEngine */
-/** @typedef {ReturnType<typeof import("./customKnexRepository.js").createInvoiceRollup>} InvoiceRollup */
+/** @typedef {ReturnType<typeof import("./ownedTableRepository.js").createInvoiceRollup>} InvoiceRollup */
 
 export {};

package/skills/jskit/references/patterns/users/user-administration-server/PATTERN.md

@@ -22,21 +22,70 @@ credentials, or an application that needs no administrative user listing.
 
 Choose global versus workspace scope, visible and editable fields, permission
 policy, route surface, filters, and whether account deletion is part of the
-product. Do not expose password/session data through the resource.
+product. Do not expose password, session or sign-in identity data through the
+CRUD contract.
 
 ## Framework APIs
 
 Use `@jskit-ai/users-core` for profile persistence and policies,
-`defineCrudJsonApiFeature()` from `@jskit-ai/crud-core` for standard mechanics,
-and the resource contracts from `@jskit-ai/resource-crud-core`.
+`defineCrudFeature()` from `@jskit-ai/crud-core` for standard mechanics,
+and `defineCrudContract()` from `@jskit-ai/resource-crud-core`.
+
+users-core is the `users` table's one owner, so an administration feature does
+not own it: `defineCrudFeature({ crud: userCrud, ownerRepository: "users.profiles", ... })`
+serves the CRUD contract through users-core's repository. The workspace
+variant also names `visibility: "workspace"`: its routes are a workspace's,
+so they resolve the caller's workspace and check its `crud.users.*`
+permissions. The `users` table is public, every user's, so the variant also
+narrows the repository to the workspace's members with `decorateRepository`
+(`src/server/workspaceMembersOnly.js`): a list reads only the active members
+from `workspaces.memberships`' `activeMemberIds`, and anyone else is a missing
+record, so a workspace admin never learns who else has an account. The narrowed
+repository answers only `query`, `get` and `pageLimits`: users.profiles' other
+methods (`findByEmail`, `countUsers`, the writes) read or write every user, so
+they never pass through it.
+
+The `users` table has one table resource, users-core's `userProfileTableResource`
+(`@jskit-ai/users-core/shared/resources/userProfileResource`). An
+administration package never defines a second one; `jskit check` fails a table
+with two. It builds its CRUD contract on that resource,
+`defineCrudContract(userProfileTableResource, { namespace, operations, fields })`,
+which chooses the operations, their namespace and the fields each returns; a
+field it does not name, such as the sign-in identity, is never shown. The
+list searches with the resource's `q` filter: every word in the display name,
+email or username.
+
+Other code that reads or writes the users' records (a decorated service, a
+hook, a job) requires their owners' capabilities, never the `users` or
+`user_settings` tables:
+
+- `users.profiles`: `findById`, `findByEmail`, `findByIdentity`,
+  `listByEmails(emails, options)` (one read),
+  `listByIds(ids, options)` (every profile of the ids, sorted by id, one read
+  per 1,000 ids), `upsert`,
+  `createWithSettings({ profile, settings }, options)` (the profile and its
+  settings in one transaction; settings start from the defaults),
+  `createWithId(profile, options)` (a profile keeping an earlier table's id),
+  `createManyIgnoringExisting(profiles, options)` (a re-runnable bulk import,
+  system context only), `changeUsername(userId, username, options)` and
+  `countUsers({ excludeIds, createdSince, authProvider }, options)`.
+- `users.settings`: `findByUserId`, `listByUserIds(userIds, options)` (the
+  settings of every listed user who has them, sorted by user id, one read per
+  1,000 ids), `ensureForUserId` and the settings updates.
+
+Their types are `UsersProfiles` and `UsersSettings` in
+`@jskit-ai/users-core/server/types`. Every method takes `options` last and
+joins the caller's transaction: inside `withTransaction(options, async
+(txOptions) => …)`, pass `txOptions` to every call.
 
 ## Invariants
 
 - The public user id is the resource identity.
 - Workspace operations are scoped before repository access.
 - Permission checks happen before records or record existence are disclosed.
-- Shared profile persistence remains owned by `@jskit-ai/users-core`.
-- The resource is the field contract; the feature projects its repository,
+- Shared profile persistence remains owned by `@jskit-ai/users-core`, and so
+  does the `users` table's one table resource.
+- The CRUD contract is the field contract; the feature projects its repository,
   service, actions, and routes without app-local ceremony.
 - Each package exports the type of the capability it provides:
   `src/server/types.js` declares `AppUsers` (for `app.users`) or
@@ -54,9 +103,12 @@ and the resource contracts from `@jskit-ai/resource-crud-core`.
 
 `example/packages/users/` is a global administration package.
 `example/packages/users-workspace/` demonstrates the workspace route/action
-boundary, with workspaces-core's `WORKSPACE_CRUD_SCOPE`, while reusing the same
-service contract. Each package's
-`src/server/types.js` declares the type of the capability it provides. Copy only the composition
+boundary, with workspaces-core's `WORKSPACE_CRUD_SCOPE`, and lists only the
+workspace's members through the same service contract. Each package's `src/shared/userCrud.js` builds its CRUD
+contract on users-core's `userProfileTableResource`, its `package.json` requires
+`users.profiles` (users-core, which owns the table, must be installed), and its
+`src/server/types.js` declares the type of the capability it provides; the
+workspace variant also requires `workspaces.memberships`. Copy only the composition
 that matches the product and adapt it as ordinary application source.
 
 ## Variation points
@@ -71,9 +123,10 @@ isolation, missing records, null/cleared fields, filtering, and pagination.
 
 ## Avoid
 
-- copying authentication credential tables into the user resource
+- a second table resource on `users` or `user_settings`
+- copying authentication credential tables into the CRUD contract
 - trusting route scope without repository scope
-- adding app-local mechanics already provided by `defineCrudJsonApiFeature()`
+- adding app-local mechanics already provided by `defineCrudFeature()`
 - generator metadata or field questionnaires
 - probing a collaborator, defaulting one to `null`, `{}` or a no-op, setters
   that fill a slot after construction, and module-level registries