@pikku/skills 0.12.4 → 0.12.8

package/skills/pikku-rpc/SKILL.md

@@ -36,14 +36,24 @@ See `pikku-concepts` for the core mental model.
 
 ### RPC Methods (on `wire.rpc`)
 
-Four ways to call functions via RPC:
-
 | Method                           | Purpose                                   |
 | -------------------------------- | ----------------------------------------- |
 | `rpc.invoke(name, data)`         | Internal call to any wired function       |
 | `rpc.remote(name, data)`         | Remote call via DeploymentService         |
 | `rpc.exposed(name, data)`        | Call functions marked with `expose: true` |
-| `rpc.startWorkflow(name, input)` | Start a workflow                          |
+| `rpc.startWorkflow(name, input)` | Start a workflow (see `pikku-workflow`)   |
+| `rpc.agent.run/stream(...)`      | Run an AI agent (see `pikku-ai-agent`)    |
+| `rpc.agent.resume/approve(...)`  | Answer a tool-approval interrupt          |
+| `rpc.agent.interrupt(runId)`     | Stop an in-flight run                     |
+
+`rpc.invoke`, `rpc.remote` and `rpc.startWorkflow` are typed off the generated
+RPC map, so the name and the payload are checked. `rpc.exposed` is deliberately
+`(name: string, data: any) => Promise<any>` — it exists to dispatch a name that
+arrived from outside, which by definition cannot be checked at compile time.
+Reach for `rpc.invoke` whenever the name is known statically.
+
+`rpc` also carries `depth` (how deep the current RPC chain is, so runaway
+recursion is visible) and `global`.
 
 ### Exposed Functions
 
@@ -61,17 +71,18 @@ const greet = pikkuSessionlessFunc({
 
 ### HTTP RPC Endpoint
 
-Expose all `expose: true` functions over HTTP:
+The `POST /rpc/:rpcName` endpoint that dispatches every `expose: true` function
+is **generated, not hand-written**. Turn it on and let codegen own it:
 
-```typescript
-wireHTTP({
-  route: '/rpc/:rpcName',
-  method: 'post',
-  auth: false,
-  func: rpcCaller,
-})
+```bash
+pikku enable rpc            # sets scaffold.rpc = true (auth required)
+pikku enable rpc --noAuth   # sets scaffold.rpc = { auth: false } (public)
 ```
 
+This writes `rpc-public.gen.ts` with an `rpcCaller` function and its `wireHTTP`
+call already wired. Do not write that wiring yourself — a hand-rolled copy
+collides with the generated route on the same path.
+
 ## Usage Patterns
 
 ### Internal Function Composition
@@ -114,7 +125,7 @@ RPC calls go through Pikku's middleware and permission pipeline. Direct imports
 After `npx pikku all`:
 
 ```typescript
-import { pikkuRPC } from '.pikku/pikku-rpc.gen.js'
+import { pikkuRPC } from '#pikku/pikku-rpc.gen.js'
 
 pikkuRPC.setServerUrl('http://localhost:4002')
 

package/skills/pikku-rtl/SKILL.md

@@ -6,10 +6,11 @@ installGroups: [core]
 
 # Pikku RTL (Arabic + English)
 
-This skill sits **on top of** `pikku-i18n`. That skill maps a locale to `t()`
-tokens; this one adds the second axis: a locale also has a **direction**.
-Arabic is not special-cased — it is just another locale file (`ar.json`,
-registered `satisfies typeof en`) plus the document being told it is `rtl`.
+This skill sits **on top of** `pikku-i18n`. That skill compiles a locale's
+messages into typed `m.*()` functions; this one adds the second axis: a locale
+also has a **direction**. Arabic is not special-cased — it is just another
+`messages/ar.json` listed in `project.inlang/settings.json`, plus the document
+being told it is `rtl`.
 
 ## The one idea
 
@@ -21,9 +22,9 @@ things right and Arabic, Hebrew, Farsi and Urdu all work with zero per-component
 
 ## Agent Operating Procedure
 
-1. **Tokens first.** Every visible string is already a `t()` token via
-   `pikku-i18n`. Arabic copy goes in `i18n/ar.json`, mirroring `en.json`'s keys,
-   registered with `satisfies typeof en` so a missing key is a compile error.
+1. **Messages first.** Every visible string is already an `m.*()` message via
+   `pikku-i18n`. Arabic copy goes in `messages/ar.json`, mirroring `en.json`'s
+   keys with the `{param}` names kept identical.
 2. **Add the direction helper** to the i18n config (one home for locale→dir):
    ```ts
    const RTL_LOCALES = new Set(['ar', 'he', 'fa', 'ur'])
@@ -82,7 +83,7 @@ matching `dir` on `<html>`.
 
 ```tsx
 import { DirectionProvider, MantineProvider } from '@mantine/core'
-import i18n, { detectLocale, localeDir } from './i18n/config'
+import { detectLocale, localeDir } from './i18n/config'
 
 const locale =
   typeof window !== 'undefined' ? detectLocale(window.location.pathname) : 'en'
@@ -137,8 +138,9 @@ const html = `<!doctype html>
 </html>`
 ```
 
-i18next's active language must match: call `i18n.changeLanguage(locale)` before
-`renderToString` so the SSR'd text and `dir` agree.
+Paraglide's active locale must match: set it (via the i18n config's
+`setActiveLocale` / `overwriteGetLocale` bridge) before `renderToString`, so the
+SSR'd text and `dir` agree.
 
 ### Next.js app-router (test-harness next-ssr / next-static)
 
@@ -188,16 +190,17 @@ Prefer logical icon components if your icon set ships them.
   which is inconsistent. Add an Arabic-capable family (e.g. _Noto Sans Arabic_,
   _IBM Plex Sans Arabic_) to `font-family` so both scripts look intentional.
 - **Numerals:** don't hardcode digits. Format numbers/dates with
-  `Intl.NumberFormat`/`Intl.DateTimeFormat` (or i18next formatters) given the
-  active locale, so Western vs Arabic-Indic digits follow the locale choice.
+  `Intl.NumberFormat`/`Intl.DateTimeFormat` given the active locale, so Western
+  vs Arabic-Indic digits follow the locale choice.
 - **Line height:** Arabic diacritics sit tall — a slightly larger `line-height`
   on Arabic body text avoids clipping. Keep it locale-scoped, not global.
 
 ## Adding Arabic to an existing app — checklist
 
-1. `i18n/ar.json` mirroring `en.json`; register
-   `ar: { translation: ar satisfies typeof en }` and add `'ar'` to
-   `supportedLocales`. (Type-complete or it won't compile — the deploy blocks.)
+1. `messages/ar.json` mirroring `en.json`; add `"ar"` to `locales` in
+   `project.inlang/settings.json` and recompile. Keys missing from `ar.json`
+   fall back to the base locale per message rather than failing the build, so
+   diff the two files rather than trusting `tsc` to catch a gap here.
 2. Confirm the `localeDir` helper includes `ar` (it does by default).
 3. Confirm the root sets `dir` from the locale (recipe above).
 4. Sweep the app's styles: replace every `left/right`, `ml/mr`, `text-align:
@@ -215,5 +218,6 @@ left` with the flow-relative equivalent; revert any manual `row-reverse`.
   per-locale `if (rtl)` layout branches. Set `dir` once; let layout follow.
 - Don't set `dir` on individual components — it belongs on `<html>` so the whole
   document (and Mantine) agrees.
-- Don't translate Arabic copy outside the `t()` token system; an RTL language is
-  a normal locale, governed by `pikku-i18n`.
+- Don't translate Arabic copy outside the message system; an RTL language is a
+  normal locale, governed by `pikku-i18n`. There is no `t()` and no i18next in a
+  Pikku frontend — the string comes from `m.some__key()`.

package/skills/pikku-scenario/SKILL.md

@@ -5,7 +5,7 @@ description: >-
   test coverage. A scenario (pikkuScenario) drives the app the way users do — steps run as actors
   over the real transport against a running server — so a flow doubles as an e2e test and a
   staged/production health check. Covers scenario.do / expectEventually / expectError /
-  expectService, declared steps via pikkuScenarioStep (including browser steps driven by
+  expectService / expectScore, declared steps via pikkuScenarioStep (including browser steps driven by
   @pikku/playwright) written as intent rather than as clicks, with the actions factored into
   shared browser utilities, actors and environments in pikku.config.json, SCENARIO_ACTOR_SECRET, the
   `pikku scenario list|run` commands, live function coverage via `pikku dev --coverage`, and
@@ -36,7 +36,7 @@ A scenario is a `pikkuScenario` export that drives the app **as real actors over
 Consequences that matter, and bite if ignored:
 
 - **There is no state reset.** A scenario runs against a live server. Scope what you create (unique ids, your own rows) and never assume a clean database.
-- **Every effect runs as somebody, or as a declared step.** `scenario.do(...)` without `{ actor }` throws `Scenario tried to run '<rpc>' as an internal step…` — there is no bare internal-RPC step. The other way to do work is `scenario.step/given/when/then`, which runs a `pikkuScenarioStep`; its actor is optional (setup steps have none) unless it declares `browser: true`.
+- **Every effect runs as somebody, or as a declared step.** `scenario.do(...)` without `{ actor }` throws `Scenario tried to run '<rpc>' as an internal step…` — there is no bare internal-RPC step. The other way to do work is `scenario.given/when/then`, which runs a `pikkuScenarioStep`; its actor is optional (setup steps have none) unless it declares `browser: true`.
 - **Actors must be configured and signed in**, or the scenario cannot run.
 
 Scenarios live in `srcDirectories` like any other function — by convention `*.scenario.ts`.
@@ -85,18 +85,51 @@ A scenario takes the same config fields as a workflow (`title`, `description`, `
 
 ### The scenario API
 
-| Call                                                                                 | Purpose                                                                                                              |
-| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
-| `scenario.do(step, rpc, data, { actor })`                                            | Run an RPC as that actor. The step name is what appears in the run output.                                           |
-| `scenario.expectEventually(step, rpc, data, predicate, { actor, within, interval })` | Poll until `predicate(out)` passes or `within` elapses. For anything asynchronous — queues, workers, eventual state. |
-| `scenario.expectError(step, rpc, data, { actor, matches })`                          | Assert the call **fails**. For fault injection and negative paths.                                                   |
-| `scenario.expectService(step, 'service.method', { actor, calledWith })`              | Assert a stubbed service was called. Requires the server to run with `--test`.                                       |
-| `scenario.step(step, stepName, data, { actor })`                                     | Run a declared `pikkuScenarioStep`. `given`/`when`/`then` are the same call with a keyword in the rendered prose.    |
+| Call                                                                                 | Purpose                                                                                                                |
+| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| `scenario.do(step, rpc, data, { actor })`                                            | Run an RPC as that actor. The step name is what appears in the run output.                                             |
+| `scenario.expectEventually(step, rpc, data, predicate, { actor, within, interval })` | Poll until `predicate(out)` passes or `within` elapses. For anything asynchronous — queues, workers, eventual state.   |
+| `scenario.expectError(step, rpc, data, { actor, matches })`                          | Assert the call **fails**. For fault injection and negative paths.                                                     |
+| `scenario.expectService(step, 'service.method', { actor, calledWith })`              | Assert a stubbed service was called. Requires the server to run with `--test`.                                         |
+| `scenario.expectScore(step, runId, scorer, { atLeast, atMost, reference })`          | Grade a finished agent run with a declared scorer and assert the score. See below.                                     |
+| `scenario.given(stepName, step, data, { actor })`                                    | Run a declared `pikkuScenarioStep` as setup. `when` is the same call; `then` also makes the step's bindings witnesses. |
+| `scenario.runScheduledTask(name)`                                                    | Fire a wired scheduler on the target now, rather than waiting for its cron.                                            |
 
 `expectEventually` is **scenario-only**. Calling it from a `pikkuWorkflowFunc` is a critical inspector error (`PKU675`) pointing you at `pikkuScenario`.
 
 Prefer `expectEventually` over sleeping.
 
+### Asserting on an agent's answer (`expectScore`)
+
+An agent's output is not comparable to a fixed string, so it is graded rather
+than matched. Declare the rubric with `pikkuAIScorer` (grades in code) or
+`pikkuAIJudge` (grades with a model) in a `*.scorer.ts` file, name it on the
+agent's `scorers`, then assert on the run the scenario just triggered:
+
+```typescript
+const { runId } = await scenario.when('asks for a summary', 'runAssistant', {
+  prompt: data.prompt,
+}, { actor: actors.user })
+
+await scenario.expectScore('answered briefly', runId, 'brevity', { atLeast: 0.8 })
+```
+
+The default bound is `atLeast: 0.5`, so an unqualified `expectScore` still fails
+a run the scorer graded zero. `atMost` is for a rubric where high is the failure
+(sycophancy, verbosity). `reference` supplies the answer key a
+`requiresReference` judge grades against — live traffic has none, so such a
+judge is only ever reachable from a scenario.
+
+Grading goes through the `pikkuScenarioGradeRun` instrumentation RPC on the
+server under test, which grades from the snapshot the runtime kept at the end of
+the run. Two consequences: the run must have happened on **that** server and be
+recent, and the grade is returned to the scenario rather than recorded — a
+test's score never lands among the production figures. Sampling is ignored, so a
+scorer set to grade 1% of live traffic still grades every scenario run.
+
+Tag any scenario whose scorer is a judge `ai-live`: it costs a model call, and
+the default suite excludes it.
+
 ### Setup and teardown (`before` / `after`)
 
 A scenario config takes `before` and `after`. Both have the **same signature as `func`** — `(services, data, wire)` — with the return value discarded:
@@ -111,7 +144,9 @@ export const credentialScenario = pikkuScenario({
   tags: ['scenario', 'credential'],
   before: resetsCredentials,
   after: removesInstalledAddon,
-  func: async (services, data, { scenario, actors }) => { /* … */ },
+  func: async (services, data, { scenario, actors }) => {
+    /* … */
+  },
 })
 ```
 
@@ -124,7 +159,7 @@ export const credentialScenario = pikkuScenario({
 | Neither runs when the run is suspended or waiting — teardown only fires at a terminal outcome.           |
 | Hooks are **not** ladder rows. The runner records nothing for them; a failure is labelled by phase.      |
 
-A hook reaches the app the same way the body does: through `wire.actors`. If you want cleanup to be *visible* on the ladder, make it an ordinary `scenario.then(...)` instead.
+A hook reaches the app the same way the body does: through `wire.actors`. If you want cleanup to be _visible_ on the ladder, make it an ordinary `scenario.then(...)` instead.
 
 Hooks are scenario-only. A `before`/`after` on a `pikkuWorkflowFunc` never runs — a workflow is durable and resumable, so a callback that reran on every replay would have no honest meaning.
 
@@ -155,14 +190,14 @@ export const credentialFeature = pikkuFeature({
 })
 ```
 
-| Rule                                                                                                                                     |
-| ---------------------------------------------------------------------------------------------------------------------------------------- |
-| The **export identifier is the feature's id**; `name` is the human-readable label. Both must be exported or the build fails.              |
-| A `{ scenario, data }` entry is gherkin's `Examples:` — one run per entry. `data` is typed against that scenario's input.                 |
-| Feature hooks run **once around the whole group** (`before → a → b → c → after`), _not_ per scenario. `after` runs in a `finally`.         |
-| There is deliberately **no `Background:`**. Per-scenario setup is the scenario's own `before`, referencing a shared function.             |
-| A scenario's effective tags are its own **plus** the feature's, so `--tags credential` selects through the feature.                       |
-| A scenario need not belong to a feature — one with no input still runs standalone.                                                        |
+| Rule                                                                                                                                          |
+| --------------------------------------------------------------------------------------------------------------------------------------------- |
+| The **export identifier is the feature's id**; `name` is the human-readable label. Both must be exported or the build fails.                  |
+| A `{ scenario, data }` entry is gherkin's `Examples:` — one run per entry. `data` is typed against that scenario's input.                     |
+| Feature hooks run **once around the whole group** (`before → a → b → c → after`), _not_ per scenario. `after` runs in a `finally`.            |
+| There is deliberately **no `Background:`**. Per-scenario setup is the scenario's own `before`, referencing a shared function.                 |
+| A scenario's effective tags are its own **plus** the feature's, so `--tags credential` selects through the feature.                           |
+| A scenario need not belong to a feature — one with no input still runs standalone.                                                            |
 | Membership is resolved by **object identity** at runtime, which is why a loop works and why a scenario built inline in a feature is an error. |
 
 The **feature is the run unit**: `--flows` on a scenario whose every feature entry carries `data` errors and names the features containing it, because the feature is what supplies that data. Use `--features` for those. A scenario referenced bare anywhere, or in no feature at all, still runs standalone.
@@ -171,14 +206,14 @@ The **feature is the run unit**: `--flows` on a scenario whose every feature ent
 
 A scenario records what someone was **trying to do**, never the keystrokes they used to do it. This is the one decision that determines whether a suite survives its first redesign, and it applies to every step name you write.
 
-| Action ladder — wrong                  | Intent ladder — right                          |
-| -------------------------------------- | ---------------------------------------------- |
-| `Given opens /shop`                    | `Given the shopper is browsing the shop`       |
-| `When clicks the category filter`      | `When the shopper buys the £5 strawberry milkshake` |
-| `And clicks "Drinks"`                  | `Then it is in their basket`                   |
-| `And clicks the first product card`    |                                                |
-| `And clicks Add to basket`             |                                                |
-| `Then sees "1 item"`                   |                                                |
+| Action ladder — wrong               | Intent ladder — right                               |
+| ----------------------------------- | --------------------------------------------------- |
+| `Given opens /shop`                 | `Given the shopper is browsing the shop`            |
+| `When clicks the category filter`   | `When the shopper buys the £5 strawberry milkshake` |
+| `And clicks "Drinks"`               | `Then it is in their basket`                        |
+| `And clicks the first product card` |                                                     |
+| `And clicks Add to basket`          |                                                     |
+| `Then sees "1 item"`                |                                                     |
 
 Three things go wrong with the left-hand column, and all three are expensive:
 
@@ -188,11 +223,11 @@ Three things go wrong with the left-hand column, and all three are expensive:
 
 So there are three layers, and only two of them are named in the report:
 
-| Layer                          | What it is                                          | On the ladder |
-| ------------------------------ | --------------------------------------------------- | ------------- |
-| Scenario                       | The flow, written as intents                        | yes — the ladder |
-| Step (`pikkuScenarioStep`)     | One intent                                          | yes — one row |
-| Utility                        | An ordinary TS function over `browser`              | no            |
+| Layer                      | What it is                             | On the ladder    |
+| -------------------------- | -------------------------------------- | ---------------- |
+| Scenario                   | The flow, written as intents           | yes — the ladder |
+| Step (`pikkuScenarioStep`) | One intent                             | yes — one row    |
+| Utility                    | An ordinary TS function over `browser` | no               |
 
 Utilities are **not steps**. They are plain exported functions, they take the browser handle, and they hold the clicking:
 
@@ -262,7 +297,7 @@ export const buysTheItem = pikkuScenarioStep<
 })
 ```
 
-The two bindings are **alternatives**: `pikku scenario run --run browser` clicks through the shop, `--run default` (the fast suite) takes the server-side path, and both report the same sentence.
+The bindings are **alternatives**: `pikku scenario run --run browser` clicks through the shop, `--run cli` drives it over the websocket, `--run default` (the fast suite, and the default) takes the server-side path — and all of them report the same sentence.
 
 ```typescript
 await scenario.when(
@@ -274,9 +309,9 @@ await scenario.when(
 // reporter renders: When the shopper buys the £5 strawberry milkshake  ✓  1.2s
 ```
 
-**Every intent step begins by arriving.** `ensureOnShop` is not defensive noise — it is what lets a scenario start at any step, run alone, and be reordered without touching it. It checks first and navigates only if needed, so a scenario already on the shop pays nothing. This is about the *browser's* starting position, not the database: there is still no state reset (see above), and you still scope what you create.
+**Every intent step begins by arriving.** `ensureOnShop` is not defensive noise — it is what lets a scenario start at any step, run alone, and be reordered without touching it. It checks first and navigates only if needed, so a scenario already on the shop pays nothing. This is about the _browser's_ starting position, not the database: there is still no state reset (see above), and you still scope what you create.
 
-**The same utilities, a different intent.** A scenario about filtering has filtering as its subject, so there the filter *is* the intent — same helper, its own step:
+**The same utilities, a different intent.** A scenario about filtering has filtering as its subject, so there the filter _is_ the intent — same helper, its own step:
 
 ```typescript
 export const filtersTheShop = pikkuScenarioStep<
@@ -299,7 +334,7 @@ export const filtersTheShop = pikkuScenarioStep<
 })
 ```
 
-Two scenarios, two intents, one set of utilities. That is the shape to aim for: when a helper is reused by a step whose *subject* it is, promote it to a step there — never the reverse.
+Two scenarios, two intents, one set of utilities. That is the shape to aim for: when a helper is reused by a step whose _subject_ it is, promote it to a step there — never the reverse.
 
 **Non-browser steps need none of this.** Without a browser there is no navigation to absorb and no DOM to hide, so an intent maps to one RPC and `scenario.do` names it directly:
 
@@ -320,11 +355,11 @@ This is the one place the surface bindings do **not** behave like a switch, and
 
 On a `given` or `when`, the bindings are alternatives — clicking Buy and calling `createOrder` are two ways to cause one effect, so exactly one runs.
 
-On a `then`, they are not two implementations of one assertion. They are two *different claims*:
+On a `then`, they are not two implementations of one assertion. They are two _different claims_:
 
-| binding | what it actually proves |
-| ------- | ----------------------- |
-| `default` | the order row says `paid` — the system of record is right |
+| binding   | what it actually proves                                        |
+| --------- | -------------------------------------------------------------- |
+| `default` | the order row says `paid` — the system of record is right      |
 | `browser` | the confirmation panel says paid — the truth reached the human |
 
 The gap between them is the bug nobody catches: 200 OK, database correct, user still watching a spinner. So a `then` runs **every** binding it declares and fails if they disagree.
@@ -353,7 +388,7 @@ Three rules follow, and they are the ones that get broken:
 
 - **A browser witness must observe on the page.** One that quietly calls an RPC to check the result is worse than no binding at all — it reports a tick for a surface it never looked at.
 - **Return what you observed, don't just assert.** A witness returning a value lets the runner diff the two. A witness that only throws still works, but it can never disagree with anything, so it proves less. Read structured state with `where` on the test-id selector rather than parsing translated copy.
-- **A step with no binding for the run's surface is counted, not excused.** `--run browser` prints `n/m steps ran on browser` over *every* step, so an action that quietly fell back to the server lowers the number just as an assertion does. A `then` that fell back is additionally named — `--strict` fails on those, because a sentence saying the actor saw something nobody looked at is a different problem from a shortcut. Not being in the UI *is* the finding: do not add a browser binding that fakes it.
+- **A step with no binding for the run's surface is counted, not excused.** `--run browser` prints `n/m steps ran on browser` over _every_ step, so an action that quietly fell back to the server lowers the number just as an assertion does. A `then` that fell back is additionally named — `--strict` fails on those, because a sentence saying the actor saw something nobody looked at is a different problem from a shortcut. Not being in the UI _is_ the finding: do not add a browser binding that fakes it.
 
 **Always give a `then` a `default` witness.** It is the floor every run can fall back to, and an assertion with no witness the run can execute is fatal (`ScenarioNoWitness`) — not a coverage gap. The distinction is the point: a `then` checked server-side under `--run browser` did happen, it just wasn't seen where the prose claims; one checked nowhere never happened at all, and without the error it would return `undefined` and render as a tick. A browser-only `then` is therefore a step that fails the fast suite, which is rarely what you want.
 
@@ -376,12 +411,16 @@ export const buysAnApple = pikkuScenarioStep<
   name: 'buysAnApple',
   description: 'buys an apple',
   template: 'buys {qty} apples',
-  func: async (_services, { qty }, { scenarioStep }) => {
+  default: async (_services, { qty }, { scenarioStep }) => {
     return await requireActor(scenarioStep).invoke('placeOrder', { qty })
   },
 })
 ```
 
+A step's body always lives under a **surface binding** — `default`, `browser` or
+`cli` — never under a `func`. Declaring none throws at load time: at minimum give
+it a `default`.
+
 ```typescript
 await scenario.given(
   'buys an apple',
@@ -396,7 +435,7 @@ Rules that bite:
 
 - **The step is referenced by its typed string name, not by importing the const** — exactly like `workflow.do`. The name is the step's `pikkuFuncId` and is checked against the generated step map. A non-literal target is a critical error (`PKU678`).
 - **Steps are not RPCs.** They are deliberately never network-callable — a browser-driving step must not be.
-- **`actor.invoke` is typed over the exposed RPC map**, so the name and the payload are checked and the result comes back narrowed — no cast. `actor.invokeRaw(name, data, { headers })` is the same call reporting `{ status, ok, body }` instead of throwing; use it whenever the refusal *is* the assertion.
+- **`actor.invoke` is typed over the exposed RPC map**, so the name and the payload are checked and the result comes back narrowed — no cast. `actor.invokeRaw(name, data, { headers })` is the same call reporting `{ status, ok, body }` instead of throwing; use it whenever the refusal _is_ the assertion.
 - **`actor` and `env` are optional on the wire**, because a pure assertion step needs neither. Narrow them with `requireActor(scenarioStep)` and `requireScenarioEnv(scenarioStep)` from `@pikku/core/workflow` rather than a local guard — both name the step and say what to pass. `env` is `{ apiUrl, appUrl? }` from the environment the run targets, and is how a raw-HTTP step learns the target's URL: a step runs in the CLI process, where there is no `variables` service and `process.env` is not the answer.
 - **Steps default to `retries: 0`**, unlike ordinary workflow steps. Retrying a failed assertion is wrong; pass `retries` explicitly if a step is genuinely flaky-by-nature.
 - **Step results are persisted**, so return JSON-serialisable data — never a `Locator` or a client object.
@@ -405,26 +444,24 @@ Rules that bite:
 
 ### Browser steps
 
-`browser` is a boolean on the step, and it is the whole switch: `browser: true` and a browser is guaranteed present on the wire, `browser: false` (the default) and there is none. There is no third state and nothing to null-check — `wire.browser` is optional in the type only for the steps that did not ask for one.
+Declaring a `browser` binding is the whole switch: inside that binding `wire.browser` is guaranteed present and non-optional, and a step without one never sees a browser at all. There is nothing to null-check.
 
-A step declaring `browser: true` gets `wire.browser` — a session bound to **its actor**, signed in through the same `signInPath` + `SCENARIO_ACTOR_SECRET` path the HTTP actors use, so the browser and the RPC calls are one identity. Calling such a step without an actor is a critical error (`PKU677`).
+A `browser` binding gets a session bound to **its actor**, signed in through the same `signInPath` + `SCENARIO_ACTOR_SECRET` path the HTTP actors use, so the browser and the RPC calls are one identity. Calling such a step without an actor is a critical error (`PKU677`).
 
 Browser steps are where **intent, not actions** earns its keep: the step is one intent, the clicking lives in shared utilities, and the step arrives before it acts. Write the mechanics below into utilities and keep the step body to three or four calls that read as a sentence.
 
 ```typescript
-export const opensTheCart = pikkuScenarioStep<
-  { path: string },
-  { url: string },
-  true
->({
-  name: 'opensTheCart',
-  description: 'opens the cart',
-  browser: true,
-  func: async (_services, { path }, { browser }) => {
-    await browser.goto(path)
-    return { url: browser.page.url() }
-  },
-})
+export const opensTheCart = pikkuScenarioStep<{ path: string }, { url: string }>(
+  {
+    name: 'opensTheCart',
+    description: 'opens the cart',
+    browser: async (_services, { path }, { browser }) => {
+      await browser.goto(path)
+      return { url: browser.page.url() }
+    },
+    default: async ({ rpc }) => ({ url: (await rpc.invoke('getCart', {})).url }),
+  }
+)
 ```
 
 - Install `@pikku/playwright` and `@playwright/test`, and import `@pikku/playwright` once (`import type {} from '@pikku/playwright'`) so `browser.page` is a typed Playwright `Page`. Without it you still get the structural `goto`/`screenshot` handle.
@@ -441,8 +478,14 @@ Personas, actors and environments live in `pikku.config.json`:
   "scenarios": {
     "personas": {
       "shopper": { "description": "Buys things here", "primary": true },
-      "support": { "description": "Answers for the shop", "proficiency": "power" },
-      "reminders": { "description": "The shop chasing abandoned carts", "kind": "system" }
+      "support": {
+        "description": "Answers for the shop",
+        "proficiency": "power"
+      },
+      "reminders": {
+        "description": "The shop chasing abandoned carts",
+        "kind": "system"
+      }
     },
     "actors": {
       "shopper": {
@@ -487,9 +530,24 @@ SCENARIO_ACTOR_SECRET=… pikku scenario run local
 SCENARIO_ACTOR_SECRET=… pikku scenario run local --flows orderSupportScenario
 SCENARIO_ACTOR_SECRET=… pikku scenario run local --features credentialFeature
 SCENARIO_ACTOR_SECRET=… pikku scenario run local --tags smoke,scenario
+SCENARIO_ACTOR_SECRET=… pikku scenario run local --spawn --no-browser --exclude-tags ai-live
 ```
 
-`run` takes the environment as a **required positional** — the key from `environments`. `--flows`/`-f` filters by scenario name, `--features` by feature id, `--tags`/`-t` by tag (match-any). Every filter narrows the same plan, so narrowing a feature to two of its five scenarios still runs the feature's hooks exactly once around those two.
+`run` takes the environment as a **required positional** — the key from `environments`. Every filter narrows the same plan, so narrowing a feature to two of its five scenarios still runs the feature's hooks exactly once around those two.
+
+| Flag                    | Effect                                                                                  |
+| ----------------------- | --------------------------------------------------------------------------------------- |
+| `--flows` / `-f`        | Comma-separated scenario names                                                          |
+| `--features`            | Comma-separated feature ids                                                             |
+| `--tags` / `-t`         | Match-any tag filter                                                                    |
+| `--exclude-tags`        | Hold tags back — unless the flow is named directly with `--flows`                       |
+| `--run <surface>`       | `default` (the default), `browser`, or `cli`                                            |
+| `--no-browser`          | Shorthand for `--run default`; scenarios with browser steps report as **skipped**       |
+| `--strict`              | Fail, rather than pass, a `then` with no witness on the run's surface                   |
+| `--spawn` / `--keep-alive` | Start `pikku dev` on the environment's apiUrl for the run; optionally leave it up     |
+| `--api-url` / `--app-url` | Override the environment's URLs — for a target that only exists at run time            |
+| `--trace`               | Keep every stack frame on failure (default shows only the project's own)                |
+| `--coverage`            | Reset/snapshot server coverage per scenario                                             |
 
 Output is `PASS <name> (<ms>) → <output>` / `FAIL <name> (<ms>): <error>`, then `N/M scenarios passed against '<env>'`. A scenario inside a feature is named `<Feature> › <scenario> <data>`.
 
@@ -501,10 +559,16 @@ Coverage is attributed by running scenarios against a server that is collecting
 
 Prerequisite in `pikku.config.json`:
 
-```json
-{ "scaffold": { "scenarios": "auth" } }
+```bash
+pikku enable scenarios            # sets scaffold.scenarios = true (session required)
+pikku enable scenarios --noAuth   # sets scaffold.scenarios = { "auth": false }
 ```
 
+`scaffold.scenarios` is a boolean or `{ auth?, path? }`. The legacy string forms
+(`"auth"` / `"no-auth"`) are **rejected by the config loader**, not reinterpreted —
+under a shape where a string could be a path, silently reading one as a flag
+would be worse than failing.
+
 `scaffold.scenarios` generates the coverage and stub RPCs into your project (`pikkuScenarioTakeLiveCoverage`, `pikkuScenarioResetLiveCoverage`, `pikkuScenarioResetStubs`, `pikkuScenarioGetStubCalls`), so scenario runs work against any server. The coverage RPC reads `<outDir>/function/pikku-functions-meta-verbose.gen.json` off disk at request time — codegen always writes it, but it has to be deployed alongside the app or the RPC returns `null`.
 
 ```bash
@@ -565,19 +629,20 @@ Services are plain objects — a Pikku function is pure business logic, so a moc
 
 ## Red flags
 
-| Smell                                         | Why it's wrong                                                                                            |
-| --------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| `pikku tests …`                               | Removed in #865. Use `pikku scenario`.                                                                    |
-| `.feature` files / Gherkin for function tests | Scenarios are TypeScript, not Gherkin. The in-process cucumber function world was deleted.                |
-| `scenario.do(...)` with no `{ actor }`        | Throws. Every step runs as somebody.                                                                      |
-| A scenario per function                       | Scenarios are user flows. One flow covers many functions; that is the point.                              |
-| 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 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.                       |
-| A `browser: true` step guarding `if (!browser)` | `browser: true` guarantees it. The guard hides the real error, which is a missing actor (`PKU677`).      |
-| `expectEventually` in a `pikkuWorkflowFunc`   | `PKU675` — scenario-only.                                                                                 |
-| Coverage silently 0                           | Server not run with `--coverage`, verbose functions meta not deployed, `scaffold.scenarios` unset, or no actors configured. |
+| Smell                                               | Why it's wrong                                                                                                              |
+| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `pikku tests …`                                     | Removed in #865. Use `pikku scenario`.                                                                                      |
+| `.feature` files / Gherkin for function tests       | Scenarios are TypeScript, not Gherkin. The in-process cucumber function world was deleted.                                  |
+| `scenario.do(...)` with no `{ actor }`              | Throws. Every step runs as somebody.                                                                                        |
+| A scenario per function                             | Scenarios are user flows. One flow covers many functions; that is the point.                                                |
+| 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 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.                                            |
+| A `browser` binding guarding `if (!browser)`        | The binding guarantees it. The guard hides the real error, which is a missing actor (`PKU677`).                             |
+| A step with a `func:` instead of a surface binding   | There is no `func` on a step. Bodies live under `default` / `browser` / `cli`; a step with none throws at load.             |
+| `expectEventually` in a `pikkuWorkflowFunc`         | `PKU675` — scenario-only.                                                                                                   |
+| Coverage silently 0                                 | Server not run with `--coverage`, verbose functions meta not deployed, `scaffold.scenarios` unset, or no actors configured. |
 
 `@pikku/cucumber` is a **browser/e2e** harness (`Actor`, `BrowserWorld`, `PersonaData`, `DbUtils`) — out of scope here.
 

package/skills/pikku-schedule/SKILL.md

@@ -36,22 +36,55 @@ yarn add @pikku/schedule
 ```typescript
 import { InMemorySchedulerService } from '@pikku/schedule'
 
-const scheduler = new InMemorySchedulerService()
+const schedulerService = new InMemorySchedulerService()
+await schedulerService.start() // registers a CronJob per wired scheduled task
 ```
 
-Implements the scheduler service interface. Schedules are held in memory — they do not survive process restarts. Suitable for development and single-instance deployments.
+It implements core's `SchedulerService` on two mechanisms: `cron` for the
+recurring tasks you declared with `wireScheduler` (see `pikku-cron`), and
+`setTimeout` for one-off delayed RPCs. Both live in process memory, so nothing
+survives a restart and nothing is shared between instances — fine for
+development and a single-instance deployment, wrong for anything else.
+
+`PikkuTaskScheduler` is a deprecated alias for the same class.
+
+### Scheduling a one-off RPC
+
+```typescript
+const taskId = await schedulerService.scheduleRPC('5m', 'sendReminder', data, session)
+await schedulerService.getTask(taskId) // { rpcName, scheduledFor, status, … } | null
+await schedulerService.getAllTasks() // pending one-offs only
+await schedulerService.unschedule(taskId) // true when it was still pending
+```
+
+The delay is milliseconds or a duration string (`'30s'`, `'5m'`, `'2h'`). This is
+also the mechanism a workflow's delayed steps use, which is why a workflow that
+sleeps needs a `schedulerService` registered.
 
 ## Usage Patterns
 
 ### Basic Setup
 
+The scheduler is a singleton service under the name **`schedulerService`**, and
+it is started in your server bootstrap — declaring it without calling `start()`
+registers no cron jobs, so nothing ever fires:
+
 ```typescript
+// start.ts
 import { InMemorySchedulerService } from '@pikku/schedule'
 
-const createSingletonServices = pikkuServices(async (config) => {
-  const scheduler = new InMemorySchedulerService()
-  return { config, scheduler }
+const schedulerService = new InMemorySchedulerService()
+const singletonServices = await createSingletonServices(config, {
+  schedulerService,
 })
+
+await appServer.start()
+await schedulerService.start()
 ```
 
-For distributed or persistent scheduling, use BullMQ (`BullSchedulerService`) or PgBoss (`PgBossSchedulerService`) from the queue packages instead. See `pikku-queue` for details.
+Call `close()` on shutdown — it stops every cron job and clears pending timers.
+
+For distributed or persistent scheduling, take the scheduler service off the
+queue factory instead (`bullFactory.getSchedulerService()`,
+`pgBossFactory.getSchedulerService()`) and register it under the same name. See
+`pikku-queue`.