@pikku/skills 0.12.15 → 0.12.17

package/skills/pikku-i18n/SKILL.md

@@ -11,10 +11,81 @@ installGroups: [client, fabric]
 Use this skill as an execution checklist, not reference material.
 
 1. Every user-facing string in a frontend is a message. Never hardcode display text — add a key to `messages/en.json` and render `m.the__key()`. This holds even when the app ships only English; the messages are the seam a second language slots into later.
-2. One `messages/<locale>.json` per language at the app root (NOT under `src/`), declared in `project.inlang/settings.json`. English (`en`) is `baseLocale` and the only locale until someone adds another.
+2. One `messages/<locale>.json` per language at the app root (NOT under `src/`), declared in `project.inlang/settings.json`. English (`en`) is `baseLocale` and the only locale until someone adds another. **`baseLocale` stays `en` whatever language the product speaks** — see [The product's language is not the code's language](#the-products-language-is-not-the-codes-language), which is the first thing to read if the brief says the app is not in English.
 3. Messages compile to typed ESM functions in `src/paraglide/` (generated, self-gitignored — never edit or commit it). The Vite plugin compiles during `dev`/`build` with HMR on message edits; run the CLI compile only when you need `tsc` before Vite has ever run.
 4. Validate with the app's own `tsc` then its `build`. The deploy pipeline compiles Paraglide and runs each frontend's `tsc` before building it — an i18n mistake blocks the deploy.
 
+## The product's language is not the code's language
+
+A brief that says "the entire UI is German, no English strings visible anywhere"
+is a statement about **one** of three separate things, and reading it as a
+statement about the codebase is the single most expensive mistake available in
+this skill. Three axes:
+
+| Axis            | What it covers                                                                                          | What sets it                                                    |
+| --------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| **Identifiers** | Function, component, type and file names; database tables and columns                                   | Nothing — always English, no setting                            |
+| **Meta**        | `description` / `name` / `title` / `template` authored inside the code, which the Pikku Console renders | `locale` in `pikku.config.json`, default `en`                   |
+| **Product UI**  | Every string the app shows a user                                                                       | `messages/<locale>.json` + `defaultLocale` — **this axis only** |
+
+A non-English product moves the third row and nothing else.
+
+### `baseLocale` stays `en`
+
+`baseLocale` in `project.inlang/settings.json` does not mean "the language the
+app is in". It names the message **source** — the catalogue every other locale is
+cloned from and translated against. Setting it to the product's language looks
+like it works, because the app does come up in that language, and then:
+
+- there is no `en.json`, so `--add-locale` has no catalogue to translate from
+- the app can never gain a second language without re-authoring every key
+- a message missing from a locale falls back to a catalogue nobody wrote
+
+The setting that actually decides what a first-time visitor sees is
+`defaultLocale`, held in `apps/app/src/i18n/active.json` in the Fabric app
+template and read by `src/i18n/config.ts`. It is deliberately a separate file
+from `settings.json` for exactly this reason — the source language and the
+served language are different questions.
+
+So a German medical portal is **three** settings, not one:
+
+```jsonc
+// project.inlang/settings.json — the source catalogue is English
+{ "baseLocale": "en", "locales": ["en", "de"] }
+
+// apps/app/src/i18n/active.json — what a visitor opens in
+{ "defaultLocale": "de" }
+
+// pikku.config.json — the language the team reads their Console in
+{ "locale": "de" }
+```
+
+In the Fabric template both of the first two have a command, so you rarely edit
+them by hand:
+
+```sh
+fabric i18n --add-locale de       # adds "de" to locales, seeds messages/de.json from en.json
+fabric i18n --default-locale de   # writes active.json — the app now OPENS in German
+```
+
+### The failure this is written from
+
+A real build, from this template. The brief said the UI was German; the agent
+set `baseLocale: "de"` with `locales: ["de"]` and no `en.json`, then carried the
+same reading into the code — RPC functions `getUebersicht` and
+`getPatientendetail`, components `Zeitstrahl` and `AufmerksamkeitStreifen`,
+helpers `datumDeutsch` and `voraussichtlichFertig`, database tables `vorgang`
+and `ereignis` with German columns.
+
+The German UI it was asked for needed none of that. It needed German **values**
+in a catalogue whose keys and source stayed English. What it got instead was a
+project that cannot add a second language and cannot be picked up by anyone who
+does not read German.
+
+If you find a project in this state, say so plainly rather than working around
+it: `baseLocale` cannot be repointed without re-keying every message, so it is a
+migration someone has to agree to, not a fix to slip in.
+
 ## The moving parts (starter-template layout)
 
 - `messages/en.json` — flat keys, `{param}` interpolation, inlang message-format:
@@ -109,9 +180,10 @@ The gate catches _invalid_ messages but not _inlined_ strings. The `@pikku/manti
 ## Adding a second language
 
 1. `messages/fr.json` mirroring `en.json`'s keys (translate the values, keep `{param}` names identical).
-2. Add `"fr"` to `locales` in `project.inlang/settings.json`.
+2. Add `"fr"` to `locales` in `project.inlang/settings.json`. **Leave `baseLocale` at `en`** — step 1 only works because there is an English catalogue to mirror.
 3. Recompile (restart/`vite dev` or the CLI compile). A locale file missing keys falls back to the base locale per message.
 4. Content is reachable via the `/<lang>` URL prefix (`detectLocale` already resolves it); the base locale needs no prefix. Expose the switcher via `useLocale().setLocale`.
+5. Only if the app should **open** in the new language rather than merely offer it: set `defaultLocale` (`active.json` / `fabric i18n --default-locale fr`). Adding a locale and changing the default are different asks — do the second only when asked.
 
 ## i18n debug mode (find inlined strings)
 
@@ -137,6 +209,9 @@ The wrapper alternative — a module that walks the namespace and pipes each mes
 ## What NOT to do
 
 - Don't hardcode display strings "just for now" — the message is the work.
+- Don't set `baseLocale` to anything but `en`, whatever language the product speaks. It names the source catalogue, and a project without one can never add a language. Set `defaultLocale` instead.
+- Don't let a non-English UI reach the identifiers. Functions, components, types, files, tables and columns are English in every project; the product's language lives in `messages/*.json` and nowhere else.
+- Don't translate message **keys**. `auth__login__title` stays English in `de.json`; only the value changes.
 - Don't edit or commit anything under `src/paraglide/` — it's regenerated; change `messages/*.json` instead.
 - **Don't wrap `m`.** No re-export module, no branding layer, no resolver. Components import `m` from `../paraglide/messages.js` and call it. `@pikku/react`'s `I18nString` is declared as `string & { readonly __brand: 'LocalizedString' }` — deliberately identical to Paraglide's own `LocalizedString` — so `m.some__key()` satisfies the `@pikku/mantine` `I18nNode` gate natively. A wrapper adds nothing and costs per-message tree-shaking.
 

package/skills/pikku-middleware/SKILL.md

@@ -184,7 +184,82 @@ const earlyMiddleware = pikkuMiddleware({
 
 Within the same priority level, the collection order above is preserved. Use priority when a middleware must run before/after others regardless of where it was registered (e.g. telemetry wrapping everything, session extraction before auth checks).
 
-## Service-to-Service Bearer Auth (canonical pattern)
+## ⛔ MACHINE AUTH: THE TOKEN BECOMES A SESSION. ⛔
+
+**A caller that has an identity — a sandbox, a deployed stage, a pool host, a device — is authenticated ONCE, in middleware, which calls `setSession`. The function is then an ordinary `pikkuFunc` gated with `scopes`. It reads `session`. It NEVER re-derives who the caller is.**
+
+Either a function is sessionless (genuinely public) or it has a session. Anything in between — a token verified inside `func`, a token verified in a `permissions` check that returns `true`, an identity passed in the input schema, the same resolver memoised per request so N functions can each call it — is the anti-pattern this section exists to kill.
+
+```typescript
+// middleware.ts — resolve the bearer ONCE, for every route
+const sandboxBearerAuth = pikkuMiddleware<SingletonServices>(
+  async ({ kysely, auth }, { http, getSession, setSession }, next) => {
+    if (await getSession?.()) return next()
+    const header = http?.request?.header?.('authorization')
+    if (!header?.startsWith('Bearer ')) return next()
+    const sandbox = await resolveSandboxSession(kysely, auth, header.slice(7).trim())
+    if (sandbox) {
+      setSession?.({ userId: sandbox.createdByUserId ?? sandbox.sandboxInstanceId,
+        orgId: sandbox.organizationId, scopes: ['machine:sandbox'], sandbox } as UserSession)
+    }
+    return next()
+  },
+)
+
+addHTTPMiddleware('*', [cors(...), betterAuthSession(), apiBearerAuth, sandboxBearerAuth as any])
+```
+
+```typescript
+// functions/report-something.function.ts
+export const reportSomething = pikkuFunc({
+  expose: true,
+  scopes: ['machine:sandbox'],          // ← the gate. Enforced by the runner, seen by the inspector.
+  input: ReportSomethingInput,
+  output: ReportSomethingOutput,
+  func: async ({ kysely }, input, { session }) => {
+    const sandbox = sandboxOf(session)   // ← narrowing only, no verification
+    ...
+  },
+})
+```
+
+An unresolved token leaves the session unset and the function throws `MissingSessionError` — 401, for free. Declare the scope tree once with `defineScope` (see `pikku-permissions`).
+
+### It MUST be `addHTTPMiddleware`, never `addTagMiddleware`
+
+**A session set in tag middleware is invisible to the function when the call arrives over `POST /rpc/:rpcName`.** Tag middleware runs inside `runPikkuFunc`, and the RPC dispatch calls it without a `sessionService`, so `invocationWire.session` is never re-read after your `setSession` — the function sees the session the OUTER wire had, which is none. `addHTTPMiddleware('*')` runs on the `/rpc` route itself, before its handler, and that session is the one the dispatched function inherits. Tag middleware is still right for a gate that only says yes/no.
+
+### A cron is a machine identity too — set it in the task's own middleware
+
+A scheduled task has no caller and no header, but it is still a machine principal, and without a session it cannot invoke a gated RPC or be attributed in anything it writes. Give it one the same way, in the task's own `middleware`:
+
+```typescript
+const cronSession = pikkuMiddleware(async (_services, { scheduledTask, setSession }, next) => {
+  setSession?.({ userId: `cron:${scheduledTask?.name}`, scopes: ['machine:cron'] } as UserSession)
+  return next()
+})
+
+wireScheduler({
+  name: 'tickVirtualUserSchedules',
+  schedule: '*/15 * * * *',
+  middleware: [cronSession],
+  func: tickVirtualUserSchedules,
+})
+```
+
+One `const`, not a `machineSession(name)` factory: the inspector rejects a bare `pikkuMiddleware()` that is not assigned to a variable or object property, and the task name is on the wire anyway. Parameterised middleware goes through `pikkuMiddlewareFactory`.
+
+The task can then be a thin `rpc.invoke('someGatedRpc')` against the same entry point a person calls, instead of factoring the logic into a `lib/` helper purely to route around the missing identity.
+
+Unlike tag middleware over `/rpc`, this works: `runScheduledTask` builds its wire with a `sessionService`, so the session set here is the one the function is frozen with. And unlike a person, a cron is **not** a user row — inventing a seeded account for it buys a phantom member in every list, seat count and bill, and a per-org membership that a cross-org sweep has to ignore anyway. Platform-wide authority is a scope, not a membership.
+
+### The one sessionless exception: bootstrap
+
+An endpoint that runs BEFORE the caller has an identity — registering a new host with a shared bootstrap key, a login, a device-code request — has no session to set. That one stays `pikkuSessionlessFunc` and declares its gate in `permissions` (see `pikku-permissions`).
+
+## Service-to-Service Bearer Auth (gate-only pattern)
+
+Use this when the callee needs to know only THAT the caller is trusted, not WHICH caller it is. If it needs to know which, use the session pattern above.
 
 A server that exposes RPCs only to a trusted caller (e.g. an API calling a machine-agent). Auth lives in a tag middleware — NOT in the function body. Authorization/permission checks belong in the `permissions` field (see `pikku-permissions`), never inside `func`.
 

package/skills/pikku-permissions/SKILL.md

@@ -13,6 +13,10 @@ installGroups: [core]
 
 # Pikku Permissions
 
+## ⛔ FIRST: is the caller a machine with a token? ⛔
+
+**Then this is NOT a permissions problem.** Resolve the token in `addHTTPMiddleware('*')` middleware that calls `setSession`, make the function a `pikkuFunc`, and gate it with `scopes`. A `permissions` check that verifies a bearer token and returns `true` is authentication wearing an authorization hat — and it leaves the function sessionless, so every body still has to work out who called it. See the machine-auth section of `pikku-middleware`. The only exception is a bootstrap endpoint whose caller has no identity yet (a shared-secret registration, a login): that one is sessionless and declares its gate here.
+
 ## The Rule
 
 **ALWAYS put authorization checks in the `permissions` field of `pikkuFunc` or `pikkuSessionlessFunc` — NEVER inside the `func` body.**

package/skills/pikku-scenario/SKILL.md

@@ -356,6 +356,56 @@ const order = await scenario.do(
 
 Reach for a `pikkuScenarioStep` on the non-browser side only when one intent genuinely spans several RPCs, or when the step asserts something the RPC result alone does not say.
 
+### What language the prose is in
+
+A scenario carries two kinds of text, and they do not share a language.
+
+**Identifiers are English.** The exported const (`buysAnApple`,
+`credentialFeature`), the step's `name` — which is its `pikkuFuncId`, the typed
+string the generated step map is keyed by — the file name, and every helper in
+`*.browser.ts`. These bind to generated code and to `pikku scenario list`; they
+are English in every project regardless of who the product is for or what
+language the team speaks. There is no setting that changes this.
+
+**Prose follows `locale` in `pikku.config.json`** (default `en`). That is a
+step's `description` and `template`, a feature's `name` and `description`, a
+scenario's `title`, and the positional step names passed to
+`scenario.given/when/then`. Read the field before you write any of them.
+
+This split is the same one the feature table already states — _the export
+identifier is the feature's id; `name` is the human-readable label_ — applied to
+language. The report is the deliverable, and it is read by the team; the
+identifier is an API, and it is read by the toolchain.
+
+```typescript
+// pikku.config.json: { "locale": "de" }
+export const buysAnApple = pikkuScenarioStep<{ qty: number }, { orderId: string }>({
+  name: 'buysAnApple',          // identifier — English, always
+  description: 'kauft einen Apfel',  // prose — follows locale
+  template: 'kauft {qty} Äpfel',     // prose — follows locale
+  actor: true,
+  default: async (_services, { qty }, { actor }) =>
+    await actor.invoke('placeOrder', { qty }),
+})
+```
+
+Note what does **not** change: `placeOrder` is still `placeOrder`, and the file
+is still `apple.scenario.ts`.
+
+A product with a non-English UI is not on its own a reason to set `locale` — that
+is the app's language, not the team's. Ask, or leave it `en`.
+
+**Where a non-`en` `locale` still shows English, today.** The reporter composes a
+sentence as `<Keyword> the <actor> <template>` (`composeStepProse`), and both the
+keyword and the article `the` are English literals. The Console translates the
+Given/When/Then keywords into its own UI language; the CLI reporter does not, and
+nothing translates `the`. So `locale: "de"` gives you German step prose inside an
+English frame — `Given the shopper kauft 1 Äpfel`. Write templates that read
+acceptably in that frame rather than trying to defeat it. A second gap: where a
+function or scenario declares no `title`, the Console falls back to splitting the
+**identifier** into an English-looking label (`toEnglishName`), so under a
+non-`en` `locale` meta is worth authoring rather than leaving to the fallback.
+
 ### `then` bindings are witnesses, not alternatives
 
 This is the one place the surface bindings do **not** behave like a switch, and it is the part worth reading twice.
@@ -783,6 +833,7 @@ Services are plain objects — a Pikku function is pure business logic, so a moc
 | Assuming a clean database                           | There is no state reset — it may be a staging server. Scope what you create.                                                |
 | `sleep()` before asserting                          | Use `expectEventually`.                                                                                                     |
 | A step named `clicksAddToBasket` / `opensThePage`   | That is an action, not an intent. Name the step for what the actor wanted; put the clicking in a utility.                   |
+| A step named `kauftEinenApfel` / a `vorgang` table   | Identifiers are English in every project. The German belongs in `description` / `template`, and only when `pikku.config.json` sets `locale`.  |
 | A browser step that assumes it is already on a page | It can then only run mid-flow. Arrive first — check the URL, navigate if needed.                                            |
 | `getByLabel('Full Name')` in a translated app        | Passes only in the base locale, and a copy edit breaks it as an unexplained timeout. Locate by message key.                 |
 | A `browser` binding guarding `if (!browser)`        | The binding guarantees it. The guard hides the real error, which is a missing actor (`PKU677`).                             |

package/skills/pikku-schedule/SKILL.md

@@ -50,6 +50,29 @@ wireScheduler({
 })
 ```
 
+### Giving a cron an identity
+
+A cron has no caller, so it runs with **no session at all**: it cannot invoke a
+permission- or scope-gated RPC, and nothing it writes can be attributed. A
+scheduled task is a machine principal — give it a session in the task's own
+`middleware`, exactly as a bearer-authenticated caller gets one:
+
+```typescript
+wireScheduler({
+  name: 'bookingLifecycleDaily',
+  schedule: '0 3 * * *',
+  middleware: [cronSession],
+  func: bookingLifecycleDaily,
+})
+```
+
+`runScheduledTask` builds its wire with a `sessionService`, so a `setSession`
+here is the session the function is frozen with. See the machine-auth section of
+`pikku-middleware` for the factory and for why a cron is not a user row.
+
+A scheduler service running a task on someone's behalf can pass a session
+directly instead: `runScheduledTask({ name, session })`.
+
 ### Wire Object (`wire.scheduledTask`)
 
 Inside scheduled functions: