@jskit-ai/agent-docs 0.1.246 → 0.1.248

package/skills/jskit/references/patterns/app/shell-foundation/example/package.json

@@ -34,7 +34,7 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.1.247",
+    "@jskit-ai/kernel": "0.2.0",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.8.5",
     "json-rest-schema": "^1.0.17",
@@ -42,15 +42,15 @@
     "vue": "^3.5.44",
     "vue-router": "^5.3.1",
     "vuetify": "^4.1.2",
-    "@jskit-ai/http-runtime": "0.1.245",
+    "@jskit-ai/http-runtime": "0.2.0",
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/shell-web": "0.1.254",
+    "@jskit-ai/shell-web": "0.2.0",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
     "@jskit-ai/config-eslint": "0.1.241",
-    "@jskit-ai/jskit-catalog": "0.1.299",
+    "@jskit-ai/jskit-catalog": "0.2.0",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/skills/jskit/references/patterns/app/shell-foundation/example/packages/main/package.json

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

package/skills/jskit/references/patterns/auth/accounts-hub/example/package.json

@@ -2,7 +2,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/database-runtime-mysql": "0.1.245",
-    "@jskit-ai/oidc-issuer-core": "0.1.3"
+    "@jskit-ai/database-runtime-mysql": "0.1.247",
+    "@jskit-ai/oidc-issuer-core": "0.1.5"
   }
 }

package/skills/jskit/references/patterns/auth/oidc-sign-in/example/package.json

@@ -2,7 +2,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/auth-provider-oidc-core": "0.1.4",
-    "@jskit-ai/auth-web": "0.1.250"
+    "@jskit-ai/auth-provider-oidc-core": "0.2.0",
+    "@jskit-ai/auth-web": "0.2.0"
   }
 }

package/skills/jskit/references/patterns/auth/supabase-auth/example/package.json

@@ -2,6 +2,6 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/auth-provider-supabase-core": "0.1.244"
+    "@jskit-ai/auth-provider-supabase-core": "0.2.0"
   }
 }

package/skills/jskit/references/patterns/connectors/calendar-cli/example/package.json

@@ -7,10 +7,10 @@
     "db:migrate:status": "knex --knexfile ./knexfile.js migrate:list"
   },
   "dependencies": {
-    "@jskit-ai/connectors-core": "0.1.64",
-    "@jskit-ai/connector-google-calendar": "0.1.64",
-    "@jskit-ai/database-runtime": "0.1.247",
-    "@jskit-ai/database-runtime-mysql": "0.1.245",
+    "@jskit-ai/connectors-core": "0.2.0",
+    "@jskit-ai/connector-google-calendar": "0.2.0",
+    "@jskit-ai/database-runtime": "0.1.249",
+    "@jskit-ai/database-runtime-mysql": "0.1.247",
     "knex": "^3.1.0"
   }
 }

package/skills/jskit/references/patterns/crud/json-api-resource-package/example/packages/books/package.json

@@ -8,8 +8,8 @@
     "./shared": "./src/shared/index.js"
   },
   "dependencies": {
-    "@jskit-ai/crud-core": "0.1.258",
-    "@jskit-ai/resource-crud-core": "0.1.189"
+    "@jskit-ai/crud-core": "0.2.0",
+    "@jskit-ai/resource-crud-core": "0.1.191"
   },
   "jskit": {
     "kind": "runtime",

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

@@ -8,6 +8,6 @@
     "db:migrate:status": "knex --knexfile ./knexfile.js migrate:list"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime-mysql": "0.1.245"
+    "@jskit-ai/database-runtime-mysql": "0.1.247"
   }
 }

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

@@ -8,6 +8,6 @@
     "db:migrate:status": "knex --knexfile ./knexfile.js migrate:list"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime-postgres": "0.1.244"
+    "@jskit-ai/database-runtime-postgres": "0.1.246"
   }
 }

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

@@ -2,7 +2,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/realtime": "0.1.247",
-    "@jskit-ai/shell-web": "0.1.254"
+    "@jskit-ai/realtime": "0.2.0",
+    "@jskit-ai/shell-web": "0.2.0"
   }
 }

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.1.247",
+    "@jskit-ai/kernel": "0.2.0",
     "json-rest-schema": "^1.0.17"
   },
   "exports": {

package/skills/jskit/references/patterns/users/account-settings/PATTERN.md

@@ -28,6 +28,16 @@ section order, and which account operations require reauthentication.
 Use account settings elements and composables from `@jskit-ai/users-web`,
 ordinary `useCommand()` mutation behavior, and JSKIT shell placements.
 
+The runtime's `preferences.options.locale` lists the app's `config.languages`
+(`[{ code, name }]` in the public app config), or a built-in list when the app
+configures none; theme, date and number format options arrive translated. The
+saved locale is a canonical BCP 47 code. `useAccountLocale()` from
+`@jskit-ai/users-web/client` returns it as a read-only ref (`""` when signed
+out), updated at bootstrap and after preferences save. JSKIT does not switch the
+app's language; the app does, for example
+`watch(useAccountLocale(), (code) => { if (code) i18n.global.locale.value = code; }, { immediate: true })`.
+Section titles may be plain text, a message key or `{ key, fallback }`.
+
 ## Invariants
 
 - Sections use JSKIT account settings APIs rather than direct HTTP helpers.

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users/package.json

@@ -9,8 +9,8 @@
     "./shared": "./src/shared/index.js"
   },
   "dependencies": {
-    "@jskit-ai/crud-core": "0.1.258",
-    "@jskit-ai/resource-crud-core": "0.1.189"
+    "@jskit-ai/crud-core": "0.2.0",
+    "@jskit-ai/resource-crud-core": "0.1.191"
   },
   "jskit": {
     "kind": "runtime",

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users-workspace/package.json

@@ -9,9 +9,9 @@
     "./shared": "./src/shared/index.js"
   },
   "dependencies": {
-    "@jskit-ai/crud-core": "0.1.258",
-    "@jskit-ai/resource-crud-core": "0.1.189",
-    "@jskit-ai/workspaces-core": "0.1.225"
+    "@jskit-ai/crud-core": "0.2.0",
+    "@jskit-ai/resource-crud-core": "0.1.191",
+    "@jskit-ai/workspaces-core": "0.2.0"
   },
   "jskit": {
     "kind": "runtime",

package/skills/jskit/references/patterns/workspaces/workspace-server/PATTERN.md

@@ -49,6 +49,13 @@ responses expose optional `roleLabel` alongside the unchanged `roleSid`.
 Applications with their own invitation renderer may use its optional
 `roleLabel` input; `roleSid` remains the stored role id.
 
+Invitation emails use the recipient's language: `locale` is the saved
+`user_settings.locale` of an existing account with the invited email, else `en`.
+Renderers receive `locale` and `t(key, params)`, which renders a
+`jskit.workspaces.inviteEmail.*` message from the app's
+`src/locales/<code>/jskit.json` (exact locale, then language, then English); the
+mailer's `sendWorkspaceInvite` receives `locale` too.
+
 Keep existing permissions, inheritance, assignability and
 `workspace.defaultInviteRole` when adding a label. `owner` remains
 nonassignable. Custom roles, including specialised Training roles, are ordinary

package/skills/jskit/references/translation.md

@@ -0,0 +1,227 @@
+<!-- Generated from `packages/agent-docs/site/guide/framework/translation.md` by `npm run agent-docs:build`. -->
+
+# Translating a JSKIT app
+
+JSKIT ships every screen, message and error in English and can show all of them
+in another language. An app supplies translation files only: it never copies or
+overrides JSKIT components to translate them. An app that supplies no
+translations looks and behaves exactly as an English-only app.
+
+## How it fits together
+
+- Every JSKIT package with user-visible text ships `locales/en.json`, a nested
+  catalog under its own namespace: `jskit.auth.*`, `jskit.users.*`,
+  `jskit.shell.*`, `jskit.http.*`, and so on.
+- JSKIT components translate through the app's
+  [vue-i18n](https://vue-i18n.intlify.dev/) instance when the app supplies one,
+  and through the bundled English otherwise. `vue-i18n` is an optional peer
+  dependency; install it only when the app is translated.
+- The server never decides the language of an error. Every error response
+  carries a stable `code`, its `params` and the English `message`; the client
+  renders the code in the user's language.
+- Choosing and switching the language is the app's job. JSKIT components follow
+  vue-i18n's active locale.
+
+## Pass the app's vue-i18n instance
+
+Create the instance in composition mode and give it to the client bootstrap:
+
+```js
+import { createI18n } from "vue-i18n";
+import { bootstrapClientShellApp } from "@jskit-ai/kernel/client";
+import it from "./locales/it/jskit.json" with { type: "json" };
+
+const i18n = createI18n({
+  legacy: false,
+  locale: "en",
+  fallbackLocale: "en",
+  messages: { it }
+});
+
+await bootstrapClientShellApp({ /* existing options */, i18n });
+```
+
+The bootstrap installs the instance (unless `appPlugins` already does) and
+merges every installed package's English into its `en` messages. The app's own
+`en` messages win, so an app can reword a JSKIT text by defining the same key.
+JSKIT refuses a legacy-mode instance (`createI18n({ legacy: true })`).
+
+## Add a language
+
+1. Write the merged English of the app's installed JSKIT packages to a file for
+   translators:
+
+   ```bash
+   npx jskit i18n export it
+   ```
+
+   This creates `src/locales/it/jskit.json`. Running it again after upgrading
+   JSKIT adds new keys in English and keeps every existing translation.
+2. Translate the values. Keep every `{placeholder}` exactly; plural messages
+   keep the same number of `|`-separated choices as the English.
+3. Check the file against the installed packages:
+
+   ```bash
+   npx jskit i18n check it
+   ```
+
+   It reports missing and extra keys, invalid messages, placeholder and plural
+   mismatches, and (as warnings) values still identical to the English. It exits
+   non-zero when keys are missing, a message is invalid or placeholders differ,
+   so it can run in CI.
+4. Load the file into the vue-i18n instance under its locale code, as above.
+
+Missing keys fall back to English, so a partly translated language still works.
+
+### Message syntax
+
+JSKIT catalogs use a subset of vue-i18n's syntax, and translations must too:
+
+- named placeholders: `Use at least {min} characters.`
+- literal text in quotes for the characters `{ } @ $ |`: `support{'@'}example.com`
+- plural choices separated by `|`, chosen by `count`:
+  `{count} file | {count} files` (one | other) or
+  `no files | one file | {count} files` (zero | one | other)
+
+Linked messages (`@:key`), list placeholders (`{0}`) and HTML are not used.
+
+## Use the user's saved language
+
+Account preferences store the user's language in `user_settings.locale` as a
+BCP 47 code (for example `it-IT`). The "Language / locale" select offers the
+app's configured languages:
+
+```js
+// config/public.js
+config.languages = [
+  { code: "en-US", name: "English (US)" },
+  { code: "it-IT", name: "Italiano" }
+];
+```
+
+Each `name` may also be a message key. A saved locale that is not among the
+configured languages stays selectable under its language name. Without
+`config.languages` the select keeps JSKIT's built-in list, unchanged.
+
+JSKIT never switches the app's language itself. `useAccountLocale()` from
+`@jskit-ai/users-web/client` is a read-only ref holding the signed-in user's
+saved locale (`""` when nobody is signed in); it updates after sign-in and after
+the preferences are saved. Follow it in the app:
+
+```js
+import { watch } from "vue";
+import { useAccountLocale } from "@jskit-ai/users-web/client";
+
+watch(useAccountLocale(), (locale) => {
+  if (locale) i18n.global.locale.value = pickSupportedLocale(locale);
+}, { immediate: true });
+```
+
+`pickSupportedLocale` is the app's own choice, for example `it-IT` → `it` when
+the app ships only `src/locales/it/jskit.json`.
+
+## How errors are shown
+
+Every error response from a JSKIT HTTP API has a `code` and `params` next to
+the English `message`:
+
+```json
+{ "error": "Invalid email or password.", "code": "auth.login.invalidCredentials", "params": {} }
+```
+
+- Codes added for translation are dotted (`<namespace>.<area>.<name>`) and
+  render from the key `jskit.<code>`.
+- Older codes such as `ACTION_PERMISSION_DENIED` or `not_found` keep their
+  values and render from `jskit.errors.<code>`.
+- Validation errors keep `details.fieldErrors` (English) and add
+  `details.fieldErrorCodes: { field: { code, params } }`.
+- Where one code covers several different sentences (for example
+  `connector_input_invalid`), the response also has `messageCode` and
+  `messageParams` for the exact sentence.
+
+The client translates a code only when the English the server sent is JSKIT's
+English for that code. An app's own sentence under a shared code (for example
+`throw new NotFoundError("Contact not found.")`) is shown exactly as written, and
+so is any text whose code has no catalog entry.
+
+App code that shows errors uses the same helper JSKIT's components use:
+
+```js
+import { useJskitText } from "@jskit-ai/kernel/client";
+
+const { serverMessage, fieldErrorMessages } = useJskitText();
+const message = serverMessage(error);          // translated, or the English sent
+const fieldMessages = fieldErrorMessages(error); // { field: text }
+```
+
+To give the app's own errors codes, throw them with a code and params and add
+the app's English and translations to its vue-i18n messages under the key the
+code maps to:
+
+```js
+throw new AppError(409, "That slug is taken.", { code: "app.project.slugTaken" });
+// en: { jskit: { app: { project: { slugTaken: "That slug is taken." } } } }
+```
+
+## Placement labels
+
+A placement `label` or `title` may be a message key, `{ key, fallback, params }`
+or plain text. JSKIT's menus, tabs, profile menu and account-settings sections
+translate a key and show any other string as written:
+
+```js
+{ label: "jskit.users.accountSettings.menuLabel" }
+{ label: { key: "app.menu.reports", fallback: "Reports" } }
+{ label: "Reports" }
+```
+
+## Dates and numbers
+
+JSKIT formats dates, times, numbers and relative times with `Intl` in the
+active vue-i18n locale. Without an instance, each text keeps the format it had
+before translation support (usually the browser's default).
+App code can use the same helpers from `useJskitText()`: `formatDate`,
+`formatTime`, `formatDateTime`, `formatNumber` and `formatRelativeTime`.
+
+## Emails
+
+The workspace invitation email is rendered in the recipient's saved
+`user_settings.locale` when the recipient already has an account, and in English
+otherwise. The server reads the same `src/locales/<code>/jskit.json` files the
+client uses, so translating `jskit.workspaces.inviteEmail.*` there translates
+the email too. It looks for the exact locale (`it-IT`), then the language
+(`it`), then English. The app's invite mailer also receives the chosen `locale`.
+
+Server code that renders JSKIT-style messages itself uses the same lookup:
+
+```js
+import { createServerI18n } from "@jskit-ai/kernel/server/i18n";
+
+const i18n = createServerI18n({ appRoot, catalogs: [english] });
+i18n.t("it-IT", "jskit.workspaces.inviteEmail.subject", { workspace: "Acme" });
+```
+
+Password-reset emails are sent by the app's own recovery sender (local
+accounts) or by the identity provider (Supabase, OIDC), so their language is
+the app's or the provider's choice.
+
+## What the app translates itself
+
+JSKIT's catalogs cover JSKIT's own code. These texts belong to the app:
+
+- Vuetify's built-in texts (close buttons, pagination, "No data available").
+  Translate them through Vuetify's locale options, or let Vuetify share the
+  vue-i18n instance with its `createVueI18nAdapter`.
+- Files the app copied from a JSKIT starter or pattern, such as its
+  account-settings sections, placement entries and pages. Once copied they are
+  app code: give their texts the app's own keys.
+- The startup HTML in `index.html` (for example "Loading application…"), shown
+  before any JavaScript runs.
+
+## Checks inside JSKIT
+
+Each JSKIT package with a catalog has a test that compiles every message with
+vue-i18n, requires every key and dotted code its source uses to exist, rejects
+unused keys and refuses a key another package already defines. ESLint's
+`@intlify/vue-i18n/no-raw-text` rule rejects untranslated template text in JSKIT
+client code.