@jskit-ai/agent-docs 0.1.292 → 0.1.293

package/guide/agent/app-setup/authentication.md

@@ -161,8 +161,15 @@ The login page shows either refusal, translated, with the wait.
 
 Local auth confirms the email address of each account it registers by
 password, in every environment, unless `AUTH_LOCAL_EMAIL_CONFIRMATION=false`.
-Registering keeps the registration waiting, with no account, profile or
-session, and answers `requiresEmailConfirmation: true`; the sign-in page then
+Two registrations whose email is already proven sign in at once instead: one
+through an invitation that a feature's invitation context resolver (such as
+workspace invites) resolves, still pending, for the registering email (letter
+case aside) and before its `expiresAt`, since its link reached that address;
+and the first account a production server's setup code admits (see below). An
+invitation passed through as given, with no resolver installed, or whose
+context names no email, proves nothing. Any other registration keeps waiting,
+with no account, profile or session, and answers
+`requiresEmailConfirmation: true`; the sign-in page then
 shows "Confirm your email", with a button to send a new link and a field for
 the link or its code. Confirming takes the link's code and the password the
 registration was made with (`POST /api/register/confirm` with
@@ -174,7 +181,9 @@ wrong password creates nothing and keeps the registration and its link, with
 status 400 and `auth.local.register.confirmationPasswordInvalid`. Signing in
 with the right password while the registration waits is refused with status
 403 and `auth.login.emailUnconfirmed`, and the sign-in page shows how to
-confirm; a wrong password is an ordinary failed sign-in.
+confirm; a wrong password is an ordinary failed sign-in. The refusal holds
+even after `AUTH_LOCAL_EMAIL_CONFIRMATION=false`, which offers no
+confirming: the person registers again.
 
 A link's code is random, kept only as a hash, works once and expires after a
 day. Registering the same email again replaces the waiting registration whole
@@ -210,9 +219,10 @@ Confirmation guards self-registration. An app whose accounts are only invited,
 or created through the first account, sets `AUTH_LOCAL_SELF_REGISTRATION=false`
 and needs no confirmation sender: an invitation counts when a feature's
 invitation context resolver (such as workspace invites) resolves it for that
-email, and the first account is admitted by its setup code. In production
-without a sender, those registrations sign in at once; with one, they confirm
-as usual. An app that refused the register routes itself, with a 404 hook,
+email, and the first account is admitted by its setup code. Those
+registrations sign in at once, with or without a sender, except an invitation
+whose resolver names no email, which confirms when a sender is installed. An
+app that refused the register routes itself, with a 404 hook,
 can drop the hook for this setting. The sign-in page then shows its Register
 tab only to an invited person (an `invitationToken` in its address) and, while
 the app has no account, to the first one: local auth reports
@@ -289,8 +299,9 @@ field (capability `features.firstAccountSetupCode`), and the register body
 takes `setupCode`; letter case, spaces and dashes do not matter. A missing code
 is refused with 403 `auth.local.setup.codeRequired`, a wrong one with 403
 `auth.local.setup.codeInvalid`. An OAuth sign-in cannot create that first
-account. The registration then follows the ordinary rules, email confirmation
-included, and confirming it signs the owner in. The code admits registrations
+account. The registration then follows the ordinary rules, except that it
+needs no email confirmation: only the operator can read the code, so it signs
+the owner in at once. The code admits registrations
 until an account exists; then it stops working and its file is deleted, and
 registration needs no code again. Restarting before then makes a new code and
 the old one stops working: the latest log line and the file always agree, and

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

@@ -336,6 +336,7 @@ authorization and role checks. Do not pass arbitrary HTTP input as options.
 | `workspaces.services.members.sendInvite(workspace, actor, prepared, options)` | Refuses to run inside a transaction: it delivers after the preparation's transaction commits. 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`, and answers with `sendInvite`'s result as JSON:API data (`returnJsonApiData`, read it from `.value`), as the invite action sends it. Refuses to run inside a transaction. |
 | `workspaces.invite-acceptance-participant` (optional capability) | One application function receiving `({ invite, user }, options)` inside the acceptance transaction. Without it, acceptance activates the membership only. |
+| `workspaces.workspace-created-participant` (optional capability) | One application function receiving `({ workspace, owner }, options)` inside a new workspace's creation transaction. Without it, creation writes the workspace, its owner's membership and its settings only. |
 
 `sendInvite` accepts `{ createdInviteId, inviteTokenPreview }` from preparation or
 only `{ createdInviteId }` for a later attempt. The latter uses JSKIT's existing
@@ -471,6 +472,24 @@ Replacement can create a new pending invitation after acceptance while retaining
 the accepted invitation. Keep callbacks short: invitation changes in one workspace
 serialize. Deadlocks/serialization failures propagate without replaying callbacks.
 
+### Workspace creation participation
+
+Provide the optional `workspaces.workspace-created-participant` capability the
+same way, from a small application feature, to write application records for
+every new workspace in the same transaction. Both creation paths call
+`fn({ workspace, owner }, txOptions)`: the `workspace.workspaces.create` action
+(`createWorkspaceForAuthenticatedUser`) and a personal workspace's provisioning
+(`ensurePersonalWorkspaceForUser`, which joins its caller's transaction, such as
+a first sign-in's profile sync). It runs after the workspace, its owner's
+membership and its settings are written, so it can read them with `txOptions`.
+`workspace` and `owner` are shallow frozen. Pass `txOptions` to every write and
+let failures propagate: a failure rolls back the whole creation, workspace,
+membership, settings and the participant's own writes, and the caller receives
+the failure itself (an `AppError` answers as that refusal). Keep external effects
+out of it. An existing personal workspace is not created again and does not call
+it, and a create that loses its slug to the same owner's identical create answers
+that workspace without calling it a second time.
+
 ### Compatibility and verification
 
 Since `@jskit-ai/workspaces-core@0.1.198`, transactional `createInvite` callers

package/guide/agent/app-setup/upgrading-jskit.md

@@ -178,6 +178,10 @@ The check fails when:
 - installed package versions or root/workspace declarations disagree with the lockfile.
 - a package script runs tests outside the machine's test budget (`test/*`, see
   [Test files run in parallel](/guide/framework/typed-features#test-files-run-in-parallel)).
+- an application package's manifest (`jskit.capabilities`) misses a capability
+  its features provide or require, or provides one none of them does
+  (`manifest/capabilities`, see
+  [Package manifest](/guide/framework/typed-features#package-manifest)).
 
 Shared client owners such as the kernel, HTTP runtime, shell, auth web runtime,
 realtime runtime, and assistant runtime use exact peer dependencies where they

package/guide/agent/framework/client-features.md

@@ -389,6 +389,29 @@ const emit = defineEmits(["close"]);
 emit("closed");
 ```
 
+### Selection fields
+
+**A select, autocomplete or combobox whose options load from the server, or
+whose value is a record id, is `SelectField` from
+`@jskit-ai/http-web/client/components/SelectField`, with `loading` bound while
+the options load.** A raw `v-select`, `v-autocomplete` or `v-combobox` takes
+fixed options only: a list written out in the template, a top-level `const`
+holding one (as written, frozen, or `computed()` over one written out), or an
+import from a `shared` module. The model's name decides nothing.
+
+Why: Vuetify titles a value missing from `items` with the value itself, so a
+stored id such as `53` shows until the options arrive; `SelectField` hides it
+while `loading` is true.
+
+```vue
+<!-- good -->
+<SelectField v-model="form.serviceId" :items="services.items" :loading="services.loading" />
+<v-select v-model="form.size" :items="SIZE_OPTIONS" />
+
+<!-- bad: a stored id shows while the services load -->
+<v-select v-model="form.serviceId" :items="services.items" />
+```
+
 ### Presenting scripts
 
 **A component's `<script>` presents: props, emits, element refs, display
@@ -563,6 +586,7 @@ client-only rules below. The server's action and error rules do not apply.
 | `jskit/no-frozen-vue-state` | `Object.freeze` over refs, computeds or reactive state | [Fixed result shape](#fixed-result-shape) |
 | `jskit/released-listeners` | a listener, interval, observer or subscription the file starts and never releases | [Released listeners](#released-listeners) |
 | `jskit/no-module-state` | a module-level `let`, `ref()` or `reactive()` | [Module state](#module-state) |
+| `jskit/selection-field` | a `v-select`, `v-autocomplete` or `v-combobox` whose items are not fixed, and a `SelectField` whose items are not fixed that binds no `loading` | [Selection fields](#selection-fields) |
 | `vue/require-prop-types`, `vue/require-default-prop`, `vue/require-valid-default-prop`, `vue/no-required-prop-with-default` | a prop without a type, optional without a default, or both | [Collaborator props](#collaborator-props) |
 | `vue/require-explicit-emits` | an emitted event the component does not declare | [Declared emits](#declared-emits) |
 
@@ -583,10 +607,11 @@ Simplicity, effect order and presenting scripts are checked by reading.
 Client exceptions use the
 [typed features exceptions](/guide/framework/typed-features#exceptions): a
 comment on the line before the finding, naming the rule or the finding, with a
-reason prefix. Client code adds three placements:
+reason prefix. Client code adds four placements:
 
 | Placement | The exception |
 | --- | --- |
 | `// readable-check: allow module-state - shared resource: <what the page shares>` | module state every instance on the page shares on purpose |
 | `<!-- readable-check: allow optional-call - optional operation: <what lacks it> -->` above an element | that element's bindings call an optional operation |
+| `<!-- readable-check: allow selection-field - data: <where the options come from> -->` above an element | a selection whose options are in memory and whose value is no record id |
 | `// readable-check: allow method-probe - input validation: <the shapes>` above a function | the probes of a function whose one job is normalizing an external value of several shapes |

package/guide/agent/framework/typed-features.md

@@ -81,6 +81,31 @@ setup: ({ resources }) => ({ invoices: { list: (options) => resources.invoices.q
 actions: ({ invoices }) => [{ id: "invoices.list", execute: () => invoices.list() }]
 ```
 
+### Package manifest
+
+**A package's manifest, `jskit.capabilities` in its `package.json`, lists
+exactly what its features provide, and every capability they require beyond
+the kernel's own (`runtime.actions`, `runtime.events`, `runtime.http`,
+`runtime.bootstrap`) and those the package provides itself.** Optional
+capabilities are not required. A requirement no feature has stays only when
+the package needs it at install time, such as the database its migrations
+need.
+
+Why: start-up resolves every package's requirements from the manifests, and
+refuses a manifest that disagrees with the package's features. Plain
+`jskit check` loads each application package's features (the server providers
+`jskit.runtime.server.providers` declares) and reports the drift before that
+(`manifest/capabilities`), each capability to add or remove; it lists the
+requirements no feature has for review.
+
+```jsonc
+// good: BooksFeature provides app.books and requires crud.contracts and runtime.actions
+"capabilities": { "provides": ["app.books"], "requires": ["crud.contracts"] }
+
+// bad: app.books missing from provides, crud.contracts from requires
+"capabilities": { "provides": ["app.book"], "requires": [] }
+```
+
 ### Capability types
 
 **Each provided token has one `@typedef` in its package's `src/server/types.js`,
@@ -696,6 +721,11 @@ way (is this user an operator) is a member of its owner's capability.**
   meaning of 0 and false before replacing a copy.
 - A helper two packages of an application use lives in its shared package,
   never inside one of them.
+- A component's closure over its own state is not a helper: a function of at
+  most two statements in `<script setup>` whose every outside name is a
+  binding `<script setup>` declares (not an import or a global). Two pages
+  that reload their own resources the same way keep their own `reload()`;
+  sharing it would take a module that receives each page's state.
 
 Why: the kernel's helpers fix one meaning of empty, and a copy brings its own.
 
@@ -1175,8 +1205,9 @@ Why: a comment that narrates history is wrong the day after it is written.
 
 `npm run lint` runs ESLint with `@jskit-ai/config-eslint`, and `npm run
 verify` runs `jskit check` (the package graph, navigation, [data
-access](/guide/framework/data-access#exceptions) and [test
-runs](#test-run-rules)), lint, the tests and the build. The foundations'
+access](/guide/framework/data-access#exceptions), [test
+runs](#test-run-rules) and [package manifests](#package-manifest)), lint, the
+tests and the build. The foundations'
 `eslint.config.mjs` already holds a new
 application's code to every check:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.292",
+  "version": "0.1.293",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [

package/patterns/feature-package/example/booking-engine/package.json

@@ -5,8 +5,8 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/kernel": "0.2.17",
-    "json-rest-schema": "^1.0.17"
+    "@jskit-ai/kernel": "0.2.18",
+    "json-rest-schema": "^1.0.20"
   },
   "exports": {
     "./server/actions": "./src/server/bookingEngineActions.js",

package/patterns/minimal-foundation/example/AGENTS.md

@@ -74,7 +74,11 @@ Selection fields never show a stored id as text. A select, autocomplete or
 combobox whose options load from the server, or whose value is a record id,
 uses `SelectField` from `@jskit-ai/http-web/client/components/SelectField` with
 `loading` while the options load, not a raw `v-select`, `v-autocomplete` or
-`v-combobox`.
+`v-combobox`. The lint rule `jskit/selection-field` reports a raw one whose
+items are not fixed (a list written out, a top-level `const` holding one, or an
+import from a `shared` module) and a `SelectField` over loaded items without
+`loading`; a justified case says why in
+`<!-- readable-check: allow selection-field - data: <reason> -->` above it.
 
 Copied pattern source is ordinary application source. Do not add generator
 provenance, receipts, completion ledgers, or tooling-operation history. Keep

package/patterns/minimal-foundation/example/package.json

@@ -34,23 +34,23 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.2.17",
+    "@jskit-ai/kernel": "0.2.18",
     "@jskit-ai/material-web": "0.1.5",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.12.7",
     "pino": "^10.3.1",
-    "json-rest-schema": "^1.0.17",
+    "json-rest-schema": "^1.0.20",
     "pinia": "^4.0.3",
     "vue": "^3.5.44",
     "vue-router": "^5.3.1",
     "vuetify": "^4.3.0",
-    "@jskit-ai/http-runtime": "0.2.17",
+    "@jskit-ai/http-runtime": "0.2.18",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.248",
-    "@jskit-ai/jskit-catalog": "0.2.44",
+    "@jskit-ai/config-eslint": "0.1.249",
+    "@jskit-ai/jskit-catalog": "0.2.45",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/patterns/shell-foundation/example/AGENTS.md

@@ -74,7 +74,11 @@ Selection fields never show a stored id as text. A select, autocomplete or
 combobox whose options load from the server, or whose value is a record id,
 uses `SelectField` from `@jskit-ai/http-web/client/components/SelectField` with
 `loading` while the options load, not a raw `v-select`, `v-autocomplete` or
-`v-combobox`.
+`v-combobox`. The lint rule `jskit/selection-field` reports a raw one whose
+items are not fixed (a list written out, a top-level `const` holding one, or an
+import from a `shared` module) and a `SelectField` over loaded items without
+`loading`; a justified case says why in
+`<!-- readable-check: allow selection-field - data: <reason> -->` above it.
 
 Copied pattern source is ordinary application source. Do not add generator
 provenance, receipts, completion ledgers, or tooling-operation history. Keep

package/patterns/shell-foundation/example/package.json

@@ -34,24 +34,24 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.2.17",
+    "@jskit-ai/kernel": "0.2.18",
     "@jskit-ai/material-web": "0.1.5",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.12.7",
     "pino": "^10.3.1",
-    "json-rest-schema": "^1.0.17",
+    "json-rest-schema": "^1.0.20",
     "pinia": "^4.0.3",
     "vue": "^3.5.44",
     "vue-router": "^5.3.1",
     "vuetify": "^4.3.0",
-    "@jskit-ai/http-runtime": "0.2.17",
-    "@jskit-ai/shell-web": "0.2.21",
+    "@jskit-ai/http-runtime": "0.2.18",
+    "@jskit-ai/shell-web": "0.2.22",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.248",
-    "@jskit-ai/jskit-catalog": "0.2.44",
+    "@jskit-ai/config-eslint": "0.1.249",
+    "@jskit-ai/jskit-catalog": "0.2.45",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/patterns/shell-foundation/example/packages/main/package.json

@@ -9,7 +9,7 @@
   },
   "description": "App-local runtime composition and lightweight glue.",
   "dependencies": {
-    "@jskit-ai/kernel": "0.2.17"
+    "@jskit-ai/kernel": "0.2.18"
   },
   "jskit": {
     "kind": "runtime",