@jskit-ai/agent-docs 0.1.257 → 0.1.259

package/skills/jskit/references/heuristics/INDEX.md

@@ -1,4 +1,4 @@
-<!-- Generated from `packages/agent-docs/heuristics/INDEX.md` by `npm run agent-docs:build`. -->
+<!-- Generated from `packages/agent-docs/heuristics/INDEX.md`. -->
 
 # JSKIT Heuristics Index
 
@@ -44,3 +44,7 @@ How to use it:
   - [crud-repository-mapping.md](./crud-repository-mapping.md)
 - row policy, permission filtering, visibility before pagination, recursive CTE, descendants, package cycle, `RowPolicyPlugin`
   - [row-policies.md](./row-policies.md)
+- typed features, server feature, provider, service, repository, collaborator, `typeof`, `= null`, `setProvider`, `register`, `input || {}`, `payload = {}`, `async execute`, `Object.freeze`, `requires`, `optional`, `types.js`, `RuntimeKnex`, `silentLogger`, `create<Name>Actions`, `ActionSpecifications`, request context, `jskit/*` lint findings, `readable-check: allow`, `optional operation:`, `process.env`, `AppError` code, `Object.assign(new Error`, `idempotency`, `…ForTests` export, file or function size
+  - [typed-features.md](./typed-features.md)
+- client features, composable, `use<Name>`, Vue component, client provider, props, emits, `inject`, `provide`, `ref`, `reactive`, `watch`, `addEventListener`, `setInterval`, module state, `Object.freeze` on a composable, `?.()` in a template, `jskit/typed-inject`, `jskit/collaborator-props`, `jskit/fixed-result-shape`, `jskit/released-listeners`, `jskit/no-module-state`, `jskit/no-frozen-vue-state`, `clientFeaturesConfig`, `shared resource:`
+  - [client-features.md](./client-features.md)

package/skills/jskit/references/heuristics/child-cruds.md

@@ -1,4 +1,4 @@
-<!-- Generated from `packages/agent-docs/heuristics/child-cruds.md` by `npm run agent-docs:build`. -->
+<!-- Generated from `packages/agent-docs/heuristics/child-cruds.md`. -->
 
 # Child CRUD Layout Patterns
 

package/skills/jskit/references/heuristics/client-features.md

@@ -0,0 +1,66 @@
+<!-- Generated from `packages/agent-docs/heuristics/client-features.md`. -->
+
+# Client Feature Heuristics
+
+Use when:
+
+- writing or reviewing a composable, Vue component, client factory or client provider
+- a `jskit/*` or `vue/*` finding from `clientFeaturesConfig` is reported
+- a prop, injected value or option is probed, defaulted to nothing, or patched on after construction
+
+[Client features](../client-features.md) is the one guide
+for client code: each rule says what to do, why, and shows good and bad code.
+Server code follows [typed features](../typed-features.md).
+
+Simple to reason about comes first. Write plain functions and direct calls. If
+a rule seems to need a layer, a registry, a wrapper, a computed API or a split
+into tiny modules, the reading is wrong: take the direct form that meets the
+rule's intent, and report the case.
+
+## Keyword map
+
+- a layer, wrapper, `Proxy`, `Object.fromEntries` API, one-use factory, `utils2`, `part1`, a file split only to fit a size limit
+  - [Simple to reason about](../client-features.md#simple-to-reason-about)
+- `ReturnType<typeof useX>` repeated, an adapter shape nobody wrote down, `./client/types`, `@jskit-ai/kernel/client/types`
+  - [Client types](../client-features.md#client-types)
+- `useX(options)` read in the body, an untyped composable option (`jskit/typed-dependencies`)
+  - [Typed options](../client-features.md#typed-options)
+- `= null`, `= {}`, `typeof x === "function"`, `x?.()` on an option every caller passes (`jskit/required-collaborators`)
+  - [Required options](../client-features.md#required-options)
+- `onX = () => {}`, `optional operation:`, a getter-backed binding, `?.()` in a template, `typeof source === "function" ? source() : source.value`, an upload result of several shapes
+  - [Absent options](../client-features.md#absent-options)
+- `typeof window`, `matchMedia`, `requestAnimationFrame`, `hasWindowFunction`, `platform object:`
+  - [Platform probes](../client-features.md#platform-probes)
+- `defineProvider` on the client, a module `Map` of components, `register<Name>()`
+  - [Client providers](../client-features.md#client-providers)
+- `inject("key")`, `inject(KEY, null)`, `inject(KEY, {})` (`jskit/typed-inject`)
+  - [Injected values](../client-features.md#injected-values)
+- `type: Object, default: null` on a prop the component calls, `adapter: Object` (`jskit/collaborator-props`, `vue/require-default-prop`)
+  - [Collaborator props](../client-features.md#collaborator-props)
+- an event emitted but not declared (`vue/require-explicit-emits`)
+  - [Declared emits](../client-features.md#declared-emits)
+- a long `<script setup>`, requests or timers in a component, `<style scoped src>`
+  - [Presenting scripts](../client-features.md#presenting-scripts)
+- `runtime.x = …` after `useX()`, `Object.assign` onto a result, `...useX()` in a result, `Object.freeze` on a composable (`jskit/fixed-result-shape`, `jskit/no-frozen-vue-state`, `jskit/no-factory-spread`)
+  - [Fixed result shape](../client-features.md#fixed-result-shape)
+- `watch()` moved into a helper composable while splitting
+  - [Effect order](../client-features.md#effect-order)
+- `addEventListener` without `removeEventListener`, `setInterval`, `ResizeObserver`, `.on()` without `.off()` (`jskit/released-listeners`)
+  - [Released listeners](../client-features.md#released-listeners)
+- a module-level `let`, `ref()` or `reactive()`, `shared resource:` (`jskit/no-module-state`)
+  - [Module state](../client-features.md#module-state)
+- a copied `isRecord` or `normalizeText` in client code, a client copy of a server helper (`jskit/no-duplicate-helper`)
+  - [One helper per package](../client-features.md#one-helper-per-package)
+- a `.vue` file over 750 lines (`max-lines`)
+  - [Size limits](../client-features.md#size-limits)
+- `clientFeaturesConfig`, which globs to list, an existing application's client tree
+  - [Running the checks](../client-features.md#running-the-checks)
+
+Avoid:
+
+- probing a prop, option or injected value before calling it
+- freezing a composable's result or anything holding refs
+- patching members onto a result after it is built
+- listeners, intervals and observers that outlive their component
+- module-level state that is not one per page on purpose
+- abstractions added only to satisfy a rule

package/skills/jskit/references/heuristics/client-requests.md

@@ -1,4 +1,4 @@
-<!-- Generated from `packages/agent-docs/heuristics/client-requests.md` by `npm run agent-docs:build`. -->
+<!-- Generated from `packages/agent-docs/heuristics/client-requests.md`. -->
 
 # Client Request Patterns
 

package/skills/jskit/references/heuristics/crud-authoring.md

@@ -1,4 +1,4 @@
-<!-- Generated from `packages/agent-docs/heuristics/crud-authoring.md` by `npm run agent-docs:build`. -->
+<!-- Generated from `packages/agent-docs/heuristics/crud-authoring.md`. -->
 
 # CRUD authoring
 
@@ -33,13 +33,19 @@ Read these package-owned source patterns:
 The migration and resource are both authored contracts. A live schema is useful
 for understanding an imported system, but it is never the sole source of truth.
 
+Write a field's `operations` only where it differs from the default (output,
+create required as the field is, patch; none for `primary: true` or
+`hidden: true`; output only for `readOnly: true`), and write a lookup field as `lookup: "<namespace>"`.
+The `crud/resource-contract` pattern lists what each expands to.
+
 ## Ownership and access
 
 - `public` means every record is intentionally public. It cannot be combined
   with user or workspace ownership.
 - `user` requires a real user ownership column and negative cross-user tests.
 - `workspace` and `workspace_user` require an explicit workspace route/action
-  scope plus named permission policy.
+  scope plus named permission policy. The scope is workspaces-core's
+  `WORKSPACE_CRUD_SCOPE`; never copy its literal into a feature.
 - Domain relationships such as `recipient_user_id` are not ownership merely
   because they point to a user.
 
@@ -68,6 +74,10 @@ or rewrite a historical baseline.
 - `actions` exposes non-CRUD service methods through normal validated,
   permissioned, audited JSKIT actions and optional explicit HTTP routes.
 
+A resource whose records carry a version number names it `lockVersionField`
+and patches through the repository's `patchDocumentIfLockVersion`; see the
+database layer guide's Optimistic locking.
+
 Keep database reads and writes in repositories. Services and lifecycle hooks
 orchestrate repositories; they do not issue raw database queries. Put external
 side effects after commit, or write a durable outbox record inside the

package/skills/jskit/references/heuristics/crud-links.md

@@ -1,4 +1,4 @@
-<!-- Generated from `packages/agent-docs/heuristics/crud-links.md` by `npm run agent-docs:build`. -->
+<!-- Generated from `packages/agent-docs/heuristics/crud-links.md`. -->
 
 # CRUD Link Resolution Patterns
 

package/skills/jskit/references/heuristics/crud-repository-mapping.md

@@ -1,4 +1,4 @@
-<!-- Generated from `packages/agent-docs/heuristics/crud-repository-mapping.md` by `npm run agent-docs:build`. -->
+<!-- Generated from `packages/agent-docs/heuristics/crud-repository-mapping.md`. -->
 
 # CRUD Repository Mapping
 
@@ -61,7 +61,7 @@ remainingBatchWeight: {
 - `storage: { virtual: true }` fields must not appear in create/patch write schemas
 
 Repository pattern:
-- build the runtime with `createCrudResourceRuntime(resource, { ... })`
+- build the runtime with `createCrudResourceRuntime(resource, knex, { ... })`, passing the application's Knex instance
 - register computed projections in `virtualFields`
 - keep SQL in the repository, not in shared metadata
 - let generic CRUD runtime apply `storage.writeSerializer` during create/update writes
@@ -69,7 +69,7 @@ Repository pattern:
 Example:
 
 ```js
-const repositoryRuntime = createCrudResourceRuntime(resource, {
+const repositoryRuntime = createCrudResourceRuntime(resource, knex, {
   context: "receivals repository",
   list: LIST_CONFIG,
   virtualFields: {

package/skills/jskit/references/heuristics/filters.md

@@ -1,4 +1,4 @@
-<!-- Generated from `packages/agent-docs/heuristics/filters.md` by `npm run agent-docs:build`. -->
+<!-- Generated from `packages/agent-docs/heuristics/filters.md`. -->
 
 # Structured Filters
 

package/skills/jskit/references/heuristics/live-actions.md

@@ -1,4 +1,4 @@
-<!-- Generated from `packages/agent-docs/heuristics/live-actions.md` by `npm run agent-docs:build`. -->
+<!-- Generated from `packages/agent-docs/heuristics/live-actions.md`. -->
 
 # Live Action Patterns
 

package/skills/jskit/references/heuristics/page-redirects.md

@@ -1,4 +1,4 @@
-<!-- Generated from `packages/agent-docs/heuristics/page-redirects.md` by `npm run agent-docs:build`. -->
+<!-- Generated from `packages/agent-docs/heuristics/page-redirects.md`. -->
 
 # Page Redirect Patterns
 

package/skills/jskit/references/heuristics/page-scaffolding.md

@@ -1,4 +1,4 @@
-<!-- Generated from `packages/agent-docs/heuristics/page-scaffolding.md` by `npm run agent-docs:build`. -->
+<!-- Generated from `packages/agent-docs/heuristics/page-scaffolding.md`. -->
 
 # Page Scaffolding Patterns
 

package/skills/jskit/references/heuristics/placements.md

@@ -1,4 +1,4 @@
-<!-- Generated from `packages/agent-docs/heuristics/placements.md` by `npm run agent-docs:build`. -->
+<!-- Generated from `packages/agent-docs/heuristics/placements.md`. -->
 
 # Placement Patterns
 

package/skills/jskit/references/heuristics/row-policies.md

@@ -1,4 +1,4 @@
-<!-- Generated from `packages/agent-docs/heuristics/row-policies.md` by `npm run agent-docs:build`. -->
+<!-- Generated from `packages/agent-docs/heuristics/row-policies.md`. -->
 
 # Row Policies
 

package/skills/jskit/references/heuristics/server-search.md

@@ -1,4 +1,4 @@
-<!-- Generated from `packages/agent-docs/heuristics/server-search.md` by `npm run agent-docs:build`. -->
+<!-- Generated from `packages/agent-docs/heuristics/server-search.md`. -->
 
 # Server Search
 

package/skills/jskit/references/heuristics/surfaces.md

@@ -1,4 +1,4 @@
-<!-- Generated from `packages/agent-docs/heuristics/surfaces.md` by `npm run agent-docs:build`. -->
+<!-- Generated from `packages/agent-docs/heuristics/surfaces.md`. -->
 
 # Surface Patterns
 

package/skills/jskit/references/heuristics/typed-features.md

@@ -0,0 +1,100 @@
+<!-- Generated from `packages/agent-docs/heuristics/typed-features.md`. -->
+
+# Typed Feature Heuristics
+
+Use when:
+
+- writing or reviewing a server feature, provider, action, service, repository, route, error or test
+- a `jskit/*` lint rule from `@jskit-ai/config-eslint` reports a finding
+- a collaborator is probed, defaulted to nothing, or filled in after construction
+
+[Typed features](../typed-features.md) is the one guide:
+each rule there says what to do, why, and shows good and bad code. This map
+only sends a keyword or a finding to its section. Every lint message already
+ends with the same link.
+
+## Keyword map
+
+- `typeof x === "function"`, `x?.method?.()`, `received?.()`, `= null`, `= {}` or `= () => {}` on a collaborator, "x is required" guard (`jskit/required-collaborators`)
+  - [Required collaborators](../typed-features.md#required-collaborators)
+- `optional operation:` on a method every implementer has, a feature-gated operation
+  - [Required collaborators](../typed-features.md#required-collaborators)
+- `create<Name>(dependencies)` with `dependencies.x` in the body, no `@param` type, a pure helper passed in (`jskit/typed-dependencies`)
+  - [Typed collaborators](../typed-features.md#typed-collaborators)
+- `(...args: any[]) => Promise<any>`, `ReturnType<…>` or `X["service"]` repeated, a missing `types.js` (`jskit/named-repeated-type`)
+  - [Capability types](../typed-features.md#capability-types)
+- `capability.service || capability`, `x?.value ?? x`, "tests pass the bare service" (`jskit/no-dual-shape`)
+  - [One shape per value](../typed-features.md#one-shape-per-value)
+- `env = process.env`, `env || process.env`, `.env` loaded twice (`jskit/no-env-default`)
+  - [Environment from the caller](../typed-features.md#environment-from-the-caller)
+- `setProvider`, `attach*`, any `set<Name>()` that fills a slot, `X | null` below the hook, `deferred until boot: <reason>` (`jskit/no-slot-setter`)
+  - [Optional tokens](../typed-features.md#optional-tokens)
+- a module-level `register<Name>()`, `let x` or a `WeakMap` filled in `boot()` (`jskit/no-module-registry`)
+  - [Owned state](../typed-features.md#owned-state)
+- `shutdown()` with `?.()` or `?? []`
+  - [Shutdown mirrors setup](../typed-features.md#shutdown-mirrors-setup)
+- `logger = null`, `if (!logger) return`, `logger = console`, `logger?.warn`, a log line built from `error.message`
+  - [Loggers](../typed-features.md#loggers)
+- a value built inline in `setup()`, inline `actions() { return [{ … }] }`, a `defineFeature` in `*Provider.js`
+  - [Feature files](../typed-features.md#feature-files)
+- an action outside `create<Name>Actions`, `ActionSpecifications`, `run(service, input, context)`, positional `create<Name>Actions(service)` (`jskit/action-creator`)
+  - [Action creators](../typed-features.md#action-creators)
+- `async execute`, `execute(input) { … }`, `await` or an envelope in an action, `input || {}`, `input?.` (`jskit/one-line-action`, `jskit/action-execute-shape`)
+  - [One-line execute](../typed-features.md#one-line-execute)
+- `actionDefaults`, `channels` and `surfaces` repeated in every literal
+  - [Shared action fields](../typed-features.md#shared-action-fields)
+- `mode: "patch"` on a command, a service guard that repeats `required`
+  - [Strict action inputs](../typed-features.md#strict-action-inputs)
+- `idempotency:` (`jskit/no-idempotency`)
+  - [No idempotency](../typed-features.md#no-idempotency)
+- a `with<Rule>(definition)` wrapper around every action
+  - [The action policy](../typed-features.md#the-action-policy)
+- `context?.actor`, `options.context.actor`, `requireRequestContext`, `{ request, context }` beside `{ context }`
+  - [Request context](../typed-features.md#request-context)
+- `payload = {}`, `query = {}`, `input?.x` in a service, a second parse of validated input
+  - [Validated input as is](../typed-features.md#validated-input-as-is)
+- `options?.` or `options || {}` after `options = {}`, `fetchImpl = null` below the feature, `skip*` flags, a boolean mode parameter (`jskit/no-optional-after-default`)
+  - [Options and defaults](../typed-features.md#options-and-defaults)
+- `return { method() { … } }` from a `create*`, an unfrozen list (`jskit/frozen-factory-result`)
+  - [Frozen results](../typed-features.md#frozen-results)
+- `...factory(…)` in a token value or a returned API (`jskit/no-factory-spread`)
+  - [Named members](../typed-features.md#named-members)
+- a copied helper, function or arrow, a local `normalizeText` (`jskit/no-duplicate-helper`)
+  - [One helper per package](../typed-features.md#one-helper-per-package)
+- `options?.trx || options?.transaction`, a hand-read actor, cursor or created id
+  - [One reader per fact](../typed-features.md#one-reader-per-fact)
+- a route that queries storage, `boot*.js` holding routes
+  - [Routes](../typed-features.md#routes)
+- `new AppError(status, message)` with no code, `new NotFoundError("…")`, one code for two sentences (`jskit/app-error-code`)
+  - [Refusals carry their own code](../typed-features.md#refusals-carry-their-own-code)
+- `AppError(500, …)` for an internal invariant
+  - [Internal failures are plain errors](../typed-features.md#internal-failures-are-plain-errors)
+- `Object.assign(new Error(…), { statusCode })`, `error.status = 404` (`jskit/no-patched-error`)
+  - [One construction per error](../typed-features.md#one-construction-per-error)
+- `.catch(() => {})` around a collaborator call
+  - [Failures are logged, not swallowed](../typed-features.md#failures-are-logged-not-swallowed)
+- a double that copies an id format or a stream frame, production code shaped around a double
+  - [Doubles use documented seams](../typed-features.md#doubles-use-documented-seams)
+- a parameter, option or default only tests pass
+  - [Tests are not callers](../typed-features.md#tests-are-not-callers)
+- `…ForTests`, `__reset…`, `testOnly…` exports (`jskit/no-test-only-export`)
+  - [No test-only exports](../typed-features.md#no-test-only-exports)
+- a file over 750 lines, a function over 600 (`max-lines`, `max-lines-per-function`), a data module
+  - [Size limits](../typed-features.md#size-limits), [Data modules](../typed-features.md#data-modules)
+- two properties on one line in `Object.freeze({ … })` or a token map (`jskit/one-property-per-line`)
+  - [Formatter](../typed-features.md#formatter)
+- `build*` factories, `create*` pure builders, files not named for what they hold
+  - [Names](../typed-features.md#names)
+- a `//` description before a `/** */` block, a comment that says "was", "now", "until" or "tests" (`jskit/jsdoc-description-inside`)
+  - [Comments](../typed-features.md#comments)
+- `readable-check: allow` without a reason prefix, a reason that cites tests (`jskit/allow-comment-form`)
+  - [Exceptions](../typed-features.md#exceptions)
+
+Avoid:
+
+- probing a collaborator before calling it
+- defaulting a collaborator to `null`, `{}` or a no-op
+- setters that fill a slot after construction
+- module-level registries
+- refusals without their own code
+- excusing a finding without a reason in its `readable-check: allow` comment

package/skills/jskit/references/heuristics/ui-contract.md

@@ -1,4 +1,4 @@
-<!-- Generated from `packages/agent-docs/heuristics/ui-contract.md` by `npm run agent-docs:build`. -->
+<!-- Generated from `packages/agent-docs/heuristics/ui-contract.md`. -->
 
 # JSKIT UI contract
 

package/skills/jskit/references/heuristics/ui-testing.md

@@ -1,4 +1,4 @@
-<!-- Generated from `packages/agent-docs/heuristics/ui-testing.md` by `npm run agent-docs:build`. -->
+<!-- Generated from `packages/agent-docs/heuristics/ui-testing.md`. -->
 
 # UI Testing Pattern
 
@@ -26,7 +26,7 @@ Rules:
   reach the form before reload, then assert the original list URL; direct entry
   checks the configured fallback separately. Do not replace this wait with sleeps.
 - A managed runner supplies `PLAYWRIGHT_BASE_URL`. When it is set, JSKIT does not start another app server.
-- Vibe64 supplies an authenticated context through `VIBE64_PLAYWRIGHT_STORAGE_STATE`. Treat that file as a temporary secret: do not commit it, print it, or retain it after the run.
+- A managed runner may supply an authenticated context through `PLAYWRIGHT_STORAGE_STATE`. Treat that file as a temporary secret: do not commit it, print it, or retain it after the run.
 - Do not install a browser when the environment provides a managed browser runner.
 - Shared CRUD lists retain both card and table markup and hide the inactive
   layout with CSS. Select visible record text with
@@ -134,7 +134,7 @@ A managed preview must not expose `AUTH_DEV_BYPASS_SECRET` to project code or fo
 
 ```bash
 PLAYWRIGHT_BASE_URL=https://managed-preview.example.test \
-VIBE64_PLAYWRIGHT_STORAGE_STATE=/secure/temp/playwright-state.json \
+PLAYWRIGHT_STORAGE_STATE=/secure/temp/playwright-state.json \
 playwright test tests/e2e/contacts.spec.ts
 ```
 
@@ -152,7 +152,7 @@ test into a successful command. For an unmanaged project, for example:
 npx playwright test tests/e2e/contacts.spec.ts -g filters --reporter=dot > /tmp/contacts-test.log 2>&1
 ```
 
-On Vibe64, use `vibe64-playwright --target <declared-test-target> test ...`
+On a managed host, run the host's launcher for the declared test target
 with the same file/case selection and output redirection. Do not replace the
 managed launcher with the unmanaged example.
 

package/skills/jskit/references/material-3.md

@@ -1,4 +1,4 @@
-<!-- Generated from `packages/agent-docs/site/guide/framework/material-3.md` by `npm run agent-docs:build`. -->
+<!-- Generated from `packages/agent-docs/site/guide/framework/material-3.md`. -->
 
 # Material 3
 
@@ -97,7 +97,7 @@ Run this behavior-preserving audit over every affected screen:
 3. Check hierarchy, token use, component purpose, responsive presentation,
    interaction states, keyboard/focus behavior, labels, targets, contrast, and
    reduced motion.
-4. Audit Back on every affected page using [Back navigation](./ui-operations.md#back-navigation):
+4. Audit Back on every affected page using [Back navigation](ui-operations.md#back-navigation):
    verify its presence or justified omission, actual previous-page destination,
    safe direct-entry fallback, and retained origin context. Inspect handlers and
    route bindings; a hardcoded parent/list link is an explicit exception, not

package/skills/jskit/references/multi-homing.md

@@ -1,4 +1,4 @@
-<!-- Generated from `packages/agent-docs/site/guide/app-setup/multi-homing.md` by `npm run agent-docs:build`. -->
+<!-- Generated from `packages/agent-docs/site/guide/app-setup/multi-homing.md`. -->
 
 # Workspace tenancy
 
@@ -58,13 +58,32 @@ config.tenancyPolicy = {
 Provisioning runs in the users profile-sync lifecycle after registration and
 sign-in. The first run creates the personal workspace, its owner membership and
 its settings; later runs reuse it. The default name is the user's display name,
-or email, followed by "'s Workspace". Set `personalWorkspaceName` in
-`config/server.js` to choose another; it receives the synchronized profile
-(`id`, `displayName`, `email`, `username`), and an empty result keeps the default:
+or email, followed by "'s Workspace". To choose another, provide the
+`workspaces.personal-workspace-name` capability from an application feature. It
+receives the synchronized profile (`id`, `displayName`, `email`, `username`), and
+an empty result keeps the default:
 
 ```js
-// config/server.js
-config.personalWorkspaceName = (user) => `${user.displayName || user.email}'s home`;
+import { defineFeature } from "@jskit-ai/kernel/server/features";
+import { homeWorkspaceName } from "./homeWorkspaceName.js";
+
+const AppPersonalWorkspaceNameFeature = defineFeature({
+  id: "app.personal-workspace-name",
+  provides: {
+    personalWorkspaceName: "workspaces.personal-workspace-name"
+  },
+  setup: () => ({ personalWorkspaceName: homeWorkspaceName })
+});
+```
+
+```js
+// homeWorkspaceName.js
+/** @type {import("@jskit-ai/workspaces-core/server/types").PersonalWorkspaceName} */
+function homeWorkspaceName(user) {
+  return `${user.displayName || user.email}'s home`;
+}
+
+export { homeWorkspaceName };
 ```
 
 ### Development sign-in
@@ -103,8 +122,13 @@ before an operation discloses records or record existence.
 
 For a standard CRUD resource owned by a workspace, give its table the
 `workspace_id` column, set the resource's `autofilter: "workspace"`, and bind
-`defineCrudJsonApiFeature()` with `ownershipFilter: "workspace"` on a workspace
-surface. JSKIT then filters `workspaceId` by the workspace in the route.
+`defineCrudJsonApiFeature()` with `ownershipFilter: "workspace"` and `scope:
+WORKSPACE_CRUD_SCOPE` (from `@jskit-ai/workspaces-core/server/support/workspaceCrud`)
+on a workspace surface. JSKIT then filters `workspaceId` by the workspace in the
+route. A repository method you add reads the workspace id with
+`resolveWorkspaceScopeValue(options.context)`
+(`@jskit-ai/json-rest-api-core/server/jsonRestApiHost`), which throws when the
+context names two workspaces.
 `workspace_user` also filters by the signed-in user. See the CRUD operations
 guide.
 
@@ -152,14 +176,31 @@ capability provides:
 
 ### Invitation email
 
-To send invitation email, set a mailer in `config/server.js`. Without one,
-invitations are still created and delivery reports `mailer_unconfigured`.
-`workspaceInviteMailer` is an object whose `sendWorkspaceInvite(message,
-options)` receives `{ email, inviteUrl, workspace, inviter, roleSid, expiresAt,
-message }`, where the inner `message` is the rendered `{ subject, text, html }`.
-`workspaceInviteEmailTemplate` is an optional function that renders that inner
-message; it receives `{ email, inviteUrl, workspace, inviter, roleSid,
-roleLabel, expiresAt }` (`roleLabel` only when configured). Invitation links use `/invite/:token` unless
+To send invitation email, provide the optional `workspaces.invite-mailer`
+capability from one of the application's providers. Without one, invitations
+are still created and delivery reports `mailer_unconfigured`. The mailer, typed
+`WorkspaceInviteMailer` in `@jskit-ai/workspaces-core/server/types`, is an
+object whose `sendWorkspaceInvite(message, options)` receives `{ email,
+inviteUrl, workspace, inviter, roleSid, expiresAt, message }`, where the inner
+`message` is the rendered `{ subject, text, html }`:
+
+```js
+const InviteMailerProvider = defineProvider({
+  id: "app.invite-mailer",
+  provides: {
+    inviteMailer: "workspaces.invite-mailer"
+  },
+  setup() {
+    return { inviteMailer: createAppInviteMailer() };
+  }
+});
+```
+
+The optional `workspaces.invite-email-template` capability is a function that
+renders that inner message; it receives `{ email, inviteUrl, workspace, inviter,
+roleSid, roleLabel, expiresAt, locale, t }` (`roleLabel` only when configured).
+Provide it from an application feature, as for the mailer; without it the
+built-in template renders the message. Invitation links use `/invite/:token` unless
 `workspaceInvitations.invitePath` names another path. The
 `workspaces/workspace-server` pattern includes an example renderer.
 
@@ -252,8 +293,8 @@ authorization and role checks. Do not pass arbitrary HTTP input as options.
 | `workspaces.repositories.workspaceInvites.lockWorkspaceForInvitations(workspaceId, { trx })` | Locks the workspace before application receipt/draft rows when composing preparation. Requires an active transaction. |
 | `workspaces.services.members.prepareInvite(workspace, actor, payload, options)` | Requires a managed `options.trx`. Validates the invitation role, replaces pending invitations for that workspace/email, and returns `{ createdInviteId, inviteTokenPreview }`. Never sends. |
 | `workspaces.services.members.sendInvite(workspace, actor, prepared, options)` | Requires no `options.trx`. Reloads the committed pending invitation and workspace display data, validates expiry and token correspondence, and sends that invitation without replacement. |
-| `workspaces.services.members.createInvite(workspace, actor, payload, options)` | Owns preparation and commit, then calls `sendInvite`; retains the ordinary response shape. Rejects `options.trx`. |
-| `workspaces.services.pendingInvitations.registerAcceptanceParticipant(fn)` | Registers one application callback receiving `({ invite, user }, options)`. Invalid, duplicate and late registration reject. |
+| `workspaces.services.members.createInvite(workspace, actor, payload, options)` | Owns preparation and commit, then calls `sendInvite`, and answers with `sendInvite`'s result as JSON:API data (`returnJsonApiData`, read it from `.value`), as the invite action sends it. Rejects `options.trx`. |
+| `workspaces.invite-acceptance-participant` (optional capability) | One application function receiving `({ invite, user }, options)` inside the acceptance transaction. Without it, acceptance activates the membership only. |
 
 `sendInvite` accepts `{ createdInviteId, inviteTokenPreview }` from preparation or
 only `{ createdInviteId }` for a later attempt. The latter uses JSKIT's existing
@@ -266,30 +307,34 @@ diagnostics and administrative receipts; save the invitation ID in the receipt.
 
 ### Preparation, association, commit and controlled delivery
 
-Declare `workspaces: "workspaces.core"` in the application's feature `requires`.
-In this example, `reviewedPeople`, `people`, `scopes` and `audit` are application
-services. Each forwards the supplied transaction to its repositories.
+The acceptance participant comes from a small application feature that provides
+`workspaces.invite-acceptance-participant` and requires only what its writes need.
+It cannot require `workspaces.core`, which receives it. In this example,
+`reviewedPeople`, `people`, `scopes` and `audit` are application services. Each
+forwards the supplied transaction to its repositories.
 
 ```js
-// During application Feature.setup, before serving requests:
-const { members, pendingInvitations } = workspaces.services;
-const invites = workspaces.repositories.workspaceInvites;
-
-pendingInvitations.registerAcceptanceParticipant(async ({ invite, user }, options) => {
-  // Resolve from the exact validated invitation, never a client person ID.
-  const association = await reviewedPeople.resolveInvitation(invite.id, options);
-  if (association.kind === "ordinary") return;
-  await reviewedPeople.requireCurrentReview(association, {
-    workspaceId: invite.workspaceId,
-    user,
-    roleSid: invite.roleSid
-  }, options);
-  await people.linkAccountAndTraining(association.personId, user.id, options);
-  await scopes.applyReviewedAccess(association, user.id, options);
-  await audit.recordInvitationAcceptance(association, user.id, options);
-});
+// An application feature providing "workspaces.invite-acceptance-participant":
+setup: ({ reviewedPeople, people, scopes, audit }) => ({
+  inviteAcceptanceParticipant: async ({ invite, user }, options) => {
+    // Resolve from the exact validated invitation, never a client person ID.
+    const association = await reviewedPeople.resolveInvitation(invite.id, options);
+    if (association.kind === "ordinary") return;
+    await reviewedPeople.requireCurrentReview(association, {
+      workspaceId: invite.workspaceId,
+      user,
+      roleSid: invite.roleSid
+    }, options);
+    await people.linkAccountAndTraining(association.personId, user.id, options);
+    await scopes.applyReviewedAccess(association, user.id, options);
+    await audit.recordInvitationAcceptance(association, user.id, options);
+  }
+})
 
-// Inside an authorized application command:
+// Inside an authorized application command, in a feature that requires
+// workspaces: "workspaces.core":
+const { members } = workspaces.services;
+const invites = workspaces.repositories.workspaceInvites;
 const prepared = await invites.withTransaction(async (trx) => {
   const options = { trx, context };
   // Match acceptance's order: workspace, then application draft/receipt rows.
@@ -316,23 +361,24 @@ invitation. Association failure rolls back the new invitation, replacement of
 the previous invitation, receipt and application writes. Send only after the
 transaction resolves successfully.
 
-With no `workspaceInviteMailer`, delivery returns `status: "mailer_unconfigured"`,
-an explanatory `message` and an empty `providerMessageId`; the invitation remains
-committed. Use a controlled mailer in tests; SMTP is unnecessary:
+With no provider of `workspaces.invite-mailer`, delivery returns
+`status: "mailer_unconfigured"`, an explanatory `message` and an empty
+`providerMessageId`; the invitation remains committed. Provide a controlled
+mailer in tests; SMTP is unnecessary:
 
 ```js
-workspaceInviteMailer: {
+const inviteMailer = {
   async sendWorkspaceInvite(message) {
     capturedInvites.push(message); // Test-local memory; contains the secret link.
     return { status: "sent", message: "Captured by test mailer.", providerMessageId: "fixture-1" };
   }
-}
+};
 ```
 
 Renderer/mailer exceptions return `inviteDelivery.status: "failed"` with a fixed
 message to keep provider errors from exposing tokens. Persistence is unchanged.
-Successful mailer results retain their normalized status, message and provider
-message ID; the default status is `sent`.
+Successful mailer results retain their normalized status, message, message
+code and provider message ID; the default status is `sent`.
 
 A provider may accept a message before throwing or losing its response. The
 application must track delivery attempts and decide when to retry; email is not
@@ -377,7 +423,7 @@ Preserve `error.transactionOutcome` and `error.cause`: `rolledBack` confirms
 rollback, `committed` can accompany a failed completion hook, and `unknown`
 requires resolving the outcome before retrying. Errors after commit cannot undo
 persistence. See
-[managed transaction guidance](./existing-application-migration.md#json-rest-v2-integration).
+[managed transaction guidance](existing-application-migration.md#json-rest-v2-integration).
 
 Invitation mutations lock workspace before invitation rows. A losing acceptance,
 refusal, revocation or replacement cannot overwrite accepted/revoked state.
@@ -411,9 +457,9 @@ npm run verify
 ```
 
 Run the application's `npm run jskit:update`, restart its backend and verify that
-`members.prepareInvite`, `members.sendInvite` and
-`pendingInvitations.registerAcceptanceParticipant` are functions on the installed
-`workspaces.core` capability. The first release containing this contract pairs
+`members.prepareInvite` and `members.sendInvite` are functions on the installed
+`workspaces.core` capability, and that the application feature providing
+`workspaces.invite-acceptance-participant` is installed. The first release containing this contract pairs
 `@jskit-ai/workspaces-core@0.1.198`, `@jskit-ai/jskit-catalog@0.1.245` and
 `@jskit-ai/agent-docs@0.1.192`. Upgrade the coordinated dependency graph, then run
 the application's identity, training, permission, privacy and browser tests.