@pikku/skills 0.12.16 → 0.12.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.16",
+  "version": "0.12.18",
   "description": "The Pikku agent skills — the instruction set coding agents read to build, wire and deploy Pikku projects",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/skills/pikku-build-app/SKILL.md

@@ -28,7 +28,10 @@ project shaped so `pikku fabric init` later adopts it with zero rework.
 ## Agent Operating Procedure
 
 1. Discover before editing. Run `pikku info functions --verbose --silent` and
-   read `AGENTS.md` before your first change.
+   read `AGENTS.md` before your first change. Read `locale` in
+   `pikku.config.json` too: it is the language every `description`, `title` and
+   step `template` you write must be in (§1a). Identifiers stay English whatever
+   it says.
 2. Make the smallest source change that satisfies the task. Keep generated files
    generated — never hand-edit `.pikku/`, `*.gen.*`, or the SDK.
 3. Validate with the narrowest relevant command, then `pikku all` when functions,
@@ -72,10 +75,68 @@ in one message. Then stop; do not interview the user.
   Neutral (fine for an internal tool, but say so out loud); a direction in words;
   a reference (brand guide, screenshots, a site whose register they want); or
   their own design agent/prompt, whose output you take as the direction.
+- **What language should the app speak, and what language does the team work
+  in?** Two answers, not one — see §1a, which is where they go. Ask only if the
+  request is not obviously English; a brief written in English about an English
+  product answers both.
 
 Skip anything you can decide yourself. If nobody answers, assume one app with
 paths, the roles implied by the request, Neutral, English — and say so.
 
+## 1a. Three languages, and you must not collapse them
+
+A brief saying "the entire UI is German" is about **one** of these. Getting this
+wrong has already shipped a project that can never add a second language, so
+settle all three explicitly before you write code.
+
+| Axis            | What it covers                                                                                                                       | Where it goes                                                                     |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| **Identifiers** | Function, component, type, variable and file names. Database tables and columns. Commit messages.                                    | Nowhere — **always English**, no setting, not negotiable                          |
+| **Meta**        | `description` on functions and steps, `name`/`title` on features and scenarios, step `template`, role and persona descriptions        | `locale` in `pikku.config.json`, default `en`                                     |
+| **Product UI**  | Every string the app shows a user                                                                                                    | `messages/<locale>.json`, and `defaultLocale` for what a first-time visitor opens in |
+
+**Identifiers are English.** The product's market does not change this and
+neither does `locale`. Identifiers are the surface the generated `#pikku/*`
+clients, `pikku info`, the typed RPC map and the Kysely types all bind to, and
+unlike a string an identifier cannot be translated later — renaming one is a
+migration. A German practice management tool gets `getWorklist`, `case`,
+`event`, not `getUebersicht`, `vorgang`, `ereignis`.
+
+**Meta follows `locale`.** Write the team's answer into `pikku.config.json` in
+this phase, before there is any meta to be wrong:
+
+```json
+{ "locale": "de" }
+```
+
+It exists for the Pikku Console. Meta is the one part of a project the Console
+renders back to a human, so a team working in German reads their own functions,
+features and scenario reports in German. Default `en` and do not ask when the
+project is obviously English. **On every later run, read this field first and
+author descriptions, titles and step templates in it** — a project whose
+`locale` you ignored reports half in one language and half in another.
+
+**Product UI is the message catalogue.** `messages/<locale>.json` via
+`pikku-i18n`, with `defaultLocale` deciding what a visitor opens in.
+`baseLocale` in `project.inlang/settings.json` **stays `en`**: it names the
+message source, the catalogue every other language is cloned from, so a project
+that repoints it has nothing to translate from and `--add-locale` is broken
+forever.
+
+A German medical portal, correctly:
+
+```jsonc
+// project.inlang/settings.json
+{ "baseLocale": "en", "locales": ["en", "de"] }
+// apps/app/src/i18n/active.json   (or: fabric i18n --default-locale de)
+{ "defaultLocale": "de" }
+// pikku.config.json
+{ "locale": "de" }
+```
+
+Record the two non-obvious answers as a `decisions/` note in §2 — neither is
+discoverable from code, and the next agent will otherwise re-derive them wrong.
+
 ---
 
 ## PHASE 1 — What the app is

package/skills/pikku-build-platform/SKILL.md

@@ -154,6 +154,13 @@ icons, hardcoded `marginLeft`, a nav that opens on the wrong side.
 Adding a language means adding a locale file. If it means touching components,
 that is the finding.
 
+`baseLocale` stays `en` through all of this — it names the message source that
+every added locale is cloned from, so three locales is `locales: ["en", …]` and
+never a repointed base. Shipping locales is also not a reason for anything in
+the code to stop being English: identifiers are English in every project, and
+the language of `description`/`title`/`template` is `locale` in
+`pikku.config.json`. See `pikku-build-app` §1a.
+
 ### Emails — `pikku-emails`
 
 Templates in `emails/`, rendered and sent through the injected `email` service,

package/skills/pikku-build-quick/SKILL.md

@@ -52,6 +52,15 @@ it — one kind of person, or several?** Everything else you decide yourself.
 Do not ask about design, deployment, or scope. This is the quick mode; the
 defaults are the point.
 
+Do not ask about language either — take the defaults and note them in §6.
+Identifiers are English in every project, whatever the product's market;
+`locale` in `pikku.config.json` (the language of `description`/`title`/step
+`template`, which the Console renders) stays `en` unless the user already told
+you otherwise. If the request says the app's UI is not English, that is the
+message catalogue only: add the locale and set `defaultLocale`, and leave
+`baseLocale` at `en`. `pikku-build-app` §1a has the three axes in full; getting
+them confused is how a project ends up unable to add a second language.
+
 ## 2. Personas — 60 seconds, not optional
 
 `packages/functions/src/personas.ts` ships with a `visitor`. Add one persona per

package/skills/pikku-concepts/SKILL.md

@@ -138,7 +138,9 @@ Services can be destructured inline in the `func` signature (e.g. `async ({ logg
 
 ```typescript
 pikkuFunc({
-  // Identity and documentation
+  // Identity and documentation — prose, so it follows `locale` in
+  // pikku.config.json (default `en`). The identifier does not; see
+  // "What Language You Write In".
   title?: string,           // Human-readable name
   description?: string,     // What the function does
   version?: number,         // Contract version (see pikku-versioning)
@@ -321,6 +323,94 @@ src/
     └── pikku-bootstrap.gen.ts
 ```
 
+## What Language You Write In
+
+Three different things in a Pikku project have a human language, and they are
+**not** the same language. Collapsing them is the mistake this section exists to
+prevent, and it has already shipped in a real product — the failure is at the
+bottom.
+
+| Axis            | What it covers                                                                                                                                                    | What decides it                                                                                             |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| **Identifiers** | Function, component, type, variable and file names. Database tables and columns. Branch names and commit messages.                                                | Nothing. **Always English.** There is no setting.                                                           |
+| **Meta**        | The prose authored _inside_ the code: `description` on functions and steps, `name`/`title` on features and scenarios, step `template`, role/persona descriptions. | `locale` in `pikku.config.json`. Defaults to `en`.                                                          |
+| **Product UI**  | Every string the app shows a user.                                                                                                                                | `messages/<locale>.json`, with `active.json`'s `defaultLocale` choosing what a first-time visitor opens in. |
+
+### Identifiers are English, and nothing changes that
+
+Not the product's market, not the team's working language, and **not `locale`**.
+A German medical practice, an Arabic marketplace and a Japanese logistics tool
+all get `getOverview`, `AttentionStripe`, `case`, `event`.
+
+This is not linguistic preference, it is mechanics. Identifiers are the surface
+every other tool binds to: the generated `#pikku/*` clients, `pikku info` and
+`pikku meta`, the RPC map a scenario's `actor.invoke` is typed over, the
+generated SQL types, every skill and every agent that ever picks the project up.
+A `vorgang` table types as `Vorgang` in Kysely and reads as noise to everyone who
+did not name it, and unlike a string it cannot be translated later — renaming an
+identifier is a migration, not an edit.
+
+### Meta follows `locale`, and that is what the field is for
+
+```json
+{ "locale": "de" }
+```
+
+Meta is the one part of a project the **Pikku Console** renders back to a human.
+A team reviewing their own functions, features and scenario reports in the
+Console is reading meta and nothing else, so a team whose working language is
+German should be able to read their Console in German. That is the entire reason
+the field exists.
+
+Read it before you author meta, and write descriptions, titles and templates in
+it. Absent, it is `en`. It is a BCP-47 tag (`en`, `de`, `pt-BR` — a hyphen, not
+an underscore), and the CLI rejects anything else by name.
+
+`locale` is **not** licence to rename anything. `locale: "de"` buys a German
+`description: 'Zeigt die Arbeitsliste'` on a function still called
+`getWorklist`.
+
+### Product UI language lives in the catalogue, and only there
+
+What the app says to its users is a translation concern, not a code concern. It
+belongs in `messages/<locale>.json`; `pikku-i18n` owns the details. The one rule
+worth repeating here: **`baseLocale` in `project.inlang/settings.json` stays
+`en`.** It names the message _source_ — the catalogue every other language is
+cloned from and translated against — so a project that sets it to anything else
+has no English catalogue to translate from and can never gain a second language
+without re-authoring every key.
+
+### The failure this comes from
+
+An agent was asked to build a doctor's portal for a German practice. The brief
+said "the entire UI is German, no English strings visible anywhere". The agent
+read one sentence about the product's users as an instruction about the
+codebase, and produced:
+
+- `project.inlang/settings.json` with `baseLocale: "de"` and `locales: ["de"]`,
+  no `en.json` at all — which silently broke `--add-locale` forever
+- RPC functions `getUebersicht` and `getPatientendetail`
+- React components `Zeitstrahl` and `AufmerksamkeitStreifen`
+- database tables `vorgang` and `ereignis`, with German columns
+
+Every one of those is wrong, and the brief was satisfied by none of them: a
+German UI needs German _messages_. What that project actually wanted was three
+settings, each on its own axis:
+
+```jsonc
+// project.inlang/settings.json — the message source stays English
+{ "baseLocale": "en", "locales": ["en", "de"] }
+
+// apps/app/src/i18n/active.json — what a first-time visitor opens in
+{ "defaultLocale": "de" }
+
+// pikku.config.json — the language the team reads their Console in
+{ "locale": "de" }
+```
+
+Identifiers stay English throughout. When a brief tells you the product speaks a
+language, it is telling you about axis three and nothing else.
+
 ## Environment Variables
 
 Never use `process.env` inside Pikku functions. Use the `variables` service (see `pikku-config`):

package/skills/pikku-fabric/SKILL.md

@@ -322,7 +322,12 @@ Why it parked is the whole story, and it is `statusReason`, not `status`:
   accepts them for that deploy.
 - `needs_config` — a declared secret or variable has no value covering the
   stage. The CLI names them. `--auto-approve` will **not** force this through;
-  set the values (`pikku fabric secrets set <name>`) and re-attach.
+  set the values and re-attach — `pikku fabric secrets set <name>` for a
+  declared secret, `pikku fabric variables set <name> --value <v>` for a declared
+  variable. They are separate stores: a secret is sealed to the stage and cannot
+  be read back, a variable is stored plainly and can (`variables get`). `set`
+  reads the value as JSON when it parses, so `--value true` is the boolean on a
+  stage exactly as it is from `.env`, and `--value '"true"'` is the string.
 - `needs_attention` — the plan is red. Nothing to approve.
 
 `--sync` defaults to a 900s ceiling; `--timeout <seconds>` moves it. On timeout
@@ -411,6 +416,7 @@ These apply in every Fabric app:
 - **No hand-editing `.pikku/db/schema.gen.ts`** — write a migration and re-run `pikku db migrate`.
 - **One runtime unit per file** — never define multiple functions/workflows in a single source file.
 - **Workflow steps don't need manual wiring** — `pikkuSessionlessFunc` step functions in `*.steps.ts` files are auto-discovered by codegen.
+- **Identifiers are English** — functions, components, types, files, database tables and columns, in every app whatever market it serves. The team's language is `locale` in `pikku.config.json` and reaches `description`/`title`/`template` only; the app's language is the message catalogue, where `baseLocale` stays `en` and `defaultLocale` decides what a visitor opens in. `pikku fabric validate` warns (`app-base-locale-not-english-<app>`) when an app repoints its base.
 
 ## Converting an existing app to Fabric format
 
@@ -426,7 +432,7 @@ Fix every `error` and `warn` in the output before continuing. Then:
 2. **Replace route handlers with pikkuFuncs**: extract business logic into `pikkuFunc`/`pikkuSessionlessFunc`, add `wireHTTP` or `expose: true` for transport.
 3. **Replace DI/IoC with pikkuServices**: move service construction to `createSingletonServices` in `services.ts`.
 4. **Replace `process.env` calls**: plain config becomes `defineVariable` + `variables.get()`, anything sensitive becomes `defineSecret` + `secrets.getSecret()`.
-5. **Add `pikku.config.json`** at project root with `srcDirectories`, `outDir`, and `clientFiles`.
+5. **Add `pikku.config.json`** at project root with `srcDirectories`, `outDir`, and `clientFiles` — plus `locale` if the team does not work in English, which is the language every `description`, `title` and step `template` is then authored in.
 6. **Add `pikkufabric.config.json`** at project root with `projectId`, `production.domain`, and `frontends` (production is always `main`, so there is no `production.branch`).
 7. **Run `pikku all`** — verify codegen succeeds and there are no type errors.
 8. **Run `pikku fabric validate`** once more to confirm no structural issues remain.

package/skills/pikku-feature/SKILL.md

@@ -41,6 +41,13 @@ schemas (`yarn pikku meta functions get <id>`) or workflow steps
 **Capability rule:** do not introduce new wires of a type whose
 `capabilities.<type>` is `false` unless the user explicitly asked for it.
 
+**Language rule:** read `locale` in `pikku.config.json` (default `en`). It is
+the language of every `description`, `title` and step `template` you author —
+the meta the Pikku Console renders back to the team. It renames nothing:
+functions, components, types, files, tables and columns are English in every
+project, and what the app says to its users is the message catalogue. See
+`pikku-concepts` → _What Language You Write In_.
+
 ## Stage 2 — State intent in plain English (BEFORE writing code)
 
 Before touching any files, give the user one paragraph stating exactly what

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: