@jskit-ai/agent-docs 0.1.257 → 0.1.258

package/guide/agent/app-setup/existing-application-migration.md

@@ -66,7 +66,9 @@ Model product domains through `defineFeature()` when they own a real capability
 or operation boundary. A Feature declares stable named `requires`, optional
 inputs, and `provides`; `setup()` receives those values directly and returns
 only the promised outputs. Named actions capture the exact feature APIs they
-need. Register structural catalogue entries during `setup()` and reserve
+need. Write Features and providers as [typed features](/guide/framework/typed-features):
+each collaborator is declared, typed where it is received, and never probed.
+Register structural catalogue entries during `setup()` and reserve
 `boot()` for long-lived work that starts after composition. `shutdown()` stops
 that work. The runtime shuts Features down in reverse order and keeps going
 after one fails; it then rejects with an `AggregateError` holding one error per
@@ -235,8 +237,8 @@ Invitation creation, acceptance and refusal now own their managed transactions:
 - Replace `members.createInvite(..., { trx })` with
   `members.prepareInvite(..., { trx })`, save the application association/receipt,
   commit, then call `members.sendInvite(...)` without `trx`.
-- Move related acceptance writes into
-  `pendingInvitations.registerAcceptanceParticipant(fn)` during feature setup.
+- Move related acceptance writes into a function provided as the
+  `workspaces.invite-acceptance-participant` capability.
   Acceptance/refusal reject borrowed transactions; revocation can still join one.
 - Terminal repository transitions reject accepted/revoked invitations. Mailer
   exceptions return a fixed message to keep tokens out of provider diagnostics.
@@ -262,11 +264,13 @@ historical migration when moving it so the existing Knex ledger continues to
 recognize it. Basenames must be unique across the effective graph.
 
 Keep cross-package foreign keys and other dependency-sensitive constraints in
-application `migrations/constraints/`, the final phase of
-`createKnexMigrationConfigFromApp()`. It uses `sortDirsSeparately: true`: root
-`migrations/` runs before the sorted package directories, and filenames only
-order work within their own directory. A later timestamp in a package does not
-defer its foreign key until another package has created the parent table.
+a constraints phase of `createKnexMigrationConfigFromApp()`: the referencing
+package's own `constraints/` subdirectory, which runs after root `migrations/`,
+or application `migrations/constraints/`, which runs last. It uses
+`sortDirsSeparately: true`: the sorted package directories run before root
+`migrations/`, and filenames only order work within their own directory. A later
+timestamp in a package does not defer its foreign key until another package has
+created the parent table.
 Follow the [database ordering and partial-failure recovery rules](https://mobily-enterprises.github.io/jskit-ai/guide/app-setup/database-layer#directory-order-comes-before-filenames),
 including independent checks for columns and constraints after MySQL or MariaDB
 DDL fails. Seeds are not migrations: run one explicit application-owned,
@@ -317,17 +321,16 @@ Do not conflate these identities:
 
 An application with accounts has the standard managed-preview login: retain
 the app-owned `tools/preview-identity` executable, or add it from
-`auth/auth-surface` when it is missing, and declare it under
-`#### Preview identity` in the web-presented Vibe64 `Outputs` target exactly as
-that pattern shows. JSKIT owns the executable/library pattern, Vibe64 owns
-the declaration's grammar and runtime behavior, and Genesis transports the
-consumer-owned section without interpreting it. The executable calls the
+`auth/auth-surface` when it is missing, pass it the preview host's protocol id
+and hostnames, and declare it to the host as that pattern shows. JSKIT owns
+the executable/library pattern; the host owns the declaration's grammar, its
+protocol id and its runtime behavior. The executable calls the
 `@jskit-ai/auth-web` server-side managed-preview library; it does not need a
 framework CLI. Never expose the exchange secret in browser code, a URL, client
 environment, logs, or source.
 
 Managed Playwright uses the host-provided
-`VIBE64_PLAYWRIGHT_STORAGE_STATE`, relative URLs, and the existing managed
+`PLAYWRIGHT_STORAGE_STATE`, relative URLs, and the existing managed
 server. Direct-local tests may instead use `loginAsExistingUser()` from
 `@jskit-ai/auth-web/test/playwright` with a server-only development secret.
 Do not mix those two authentication modes or start a duplicate server against
@@ -353,10 +356,11 @@ do not accept a visually similar screen as behavioral equivalence.
 
 ## 7. Reconcile, then Deslop as a distinct pass
 
-When the project uses Genesis, run an explicit reconciliation after the port is
-functionally green. Compare the implemented source with the current Blueprint,
-selected Stack, Program, resources, managed skills, and effective workspace and
-Outputs recipes. Update stale citations and declarations to describe what now
+When the project keeps authoritative project documentation, run an explicit
+reconciliation after the port is functionally green. Compare the implemented
+source with its current product description, selected stack, subsystem notes,
+resources, managed skills, and effective workspace and output recipes. Update
+stale citations and declarations to describe what now
 exists. Do not duplicate an inherited setup recipe merely to make the project
 look self-contained.
 
@@ -381,10 +385,10 @@ evidence in ordinary source, configuration, command output, and tests:
 1. **Behavior:** focused tests and the full managed browser suite are green
    against an isolated disposable database. Use the managed host and server
    when supplied.
-2. **Reconciliation:** a dedicated Genesis reconciliation confirms the
-   Blueprint, Stack, Program, resources, managed skills, and effective setup and
-   Outputs recipes match the implementation. For a project without Genesis,
-   reconcile its equivalent authoritative product and host documentation.
+2. **Reconciliation:** a dedicated reconciliation confirms the project's
+   authoritative product and host documentation (product description, selected
+   stack, subsystem notes, resources, managed skills, and effective setup and
+   output recipes) matches the implementation.
 3. **Deslop:** a distinct JSKIT Deslop pass, including the selected Material 3
    audit where UI is affected, removes obsolete framework residue without
    changing legitimate behavior.
@@ -400,9 +404,9 @@ Do not satisfy a gate by adding a completion ledger or generated conformance
 state. If a command cannot run, report the missing evidence rather than marking
 the port complete.
 
-## Downstream proof: DogAndGroom
+## Downstream proof: a production port
 
-DogAndGroom validated this procedure on a substantial existing product rather
+A production application validated this procedure on a substantial existing product rather
 than a sample. The port redistributed 66 historical migrations among 43 owning
 packages while retaining globally unique basenames and putting cross-package
 constraints last. Its imported database ledger remained read-only and
@@ -416,7 +420,7 @@ and safety behavior. Obsolete framework generators, provenance markers,
 service-location wiring, and empty extension modules were removed without
 flattening those workflows.
 
-After a separate Genesis reconciliation and JSKIT/Material Deslop, its focused
+After a separate reconciliation and JSKIT/Material Deslop, its focused
 checks, 339 server tests, client tests, production build, database proofs, and
 all 105 managed Playwright cases passed. These numbers are downstream evidence
 that the method scales; they are not template targets or state that another

package/guide/agent/app-setup/multi-homing.md

@@ -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
@@ -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.

package/guide/agent/app-setup/run-an-accounts-hub.md

@@ -129,10 +129,12 @@ npx jskit-oidc-issuer import-accounts --in accounts.jsonl --apply
   password they already had. Emails start unconfirmed: each person confirms
   theirs once, at their first app sign-in. Rows that clash with a
   different hub account are refused and listed. A dry run prints only counts.
-- `preview-identity` implements `vibe64.preview-identity.command.v1` for the
-  hub, so an editor's preview can sign in as an existing hub account. It works
-  only outside production, from loopback, with `AUTH_DEV_BYPASS_ENABLED` and
-  `AUTH_DEV_BYPASS_SECRET`.
+- `preview-identity` answers the preview identity exchange for the hub, so an
+  editor's preview can sign in as an existing hub account. Pass the preview
+  host's protocol id with `--protocol` and each hostname pattern, besides
+  loopback, that the host serves the hub on with `--local-hostname`. It works
+  only outside production, from loopback, with
+  `AUTH_DEV_BYPASS_ENABLED` and `AUTH_DEV_BYPASS_SECRET`.
 
 ## Connecting an app