@pikku/skills 0.12.2 → 0.12.6

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

@@ -6,7 +6,8 @@ description: >-
   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
-  @pikku/playwright), actors and environments in pikku.config.json, SCENARIO_ACTOR_SECRET, the
+  @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
   plain unit tests for pure function logic. TRIGGER when: user asks about scenarios, testing a
   Pikku function, test coverage, end-to-end flows, browser/UI e2e, or health checks. DO NOT
@@ -35,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`.
@@ -84,13 +85,14 @@ 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.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`.
 
@@ -110,7 +112,9 @@ export const credentialScenario = pikkuScenario({
   tags: ['scenario', 'credential'],
   before: resetsCredentials,
   after: removesInstalledAddon,
-  func: async (services, data, { scenario, actors }) => { /* … */ },
+  func: async (services, data, { scenario, actors }) => {
+    /* … */
+  },
 })
 ```
 
@@ -123,7 +127,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.
 
@@ -154,18 +158,212 @@ 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.
 
+### Steps describe intent, not actions
+
+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"`                |                                                     |
+
+Three things go wrong with the left-hand column, and all three are expensive:
+
+- **A layout change rewrites every scenario that touched that screen.** In the right-hand column it rewrites one function.
+- **The report is the deliverable.** `buys the £5 strawberry milkshake` is readable by someone who has never seen the app; `clicks [data-testid=add]` tells them nothing about whether the product works.
+- **An action step cannot arrive on its own.** It assumes the previous click left the browser somewhere, so the scenario only runs front-to-back, as a whole, in one order.
+
+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               |
+
+Utilities are **not steps**. They are plain exported functions, they take the browser handle, and they hold the clicking:
+
+```typescript
+// shop.browser.ts — shared actions. Not steps: nothing here is an intent.
+import type { PikkuBrowserWire } from '@pikku/core/workflow'
+import type {} from '@pikku/playwright'
+
+/** Arrive on the shop, from wherever the browser happens to be. */
+export const ensureOnShop = async (browser: PikkuBrowserWire) => {
+  if (!new URL(browser.page.url()).pathname.startsWith('/shop')) {
+    await browser.goto('/shop')
+  }
+  await browser
+    .locate({ testId: 'product-grid' })
+    .first()
+    .waitFor({ state: 'visible' })
+}
+
+export const searchFor = async (browser: PikkuBrowserWire, query: string) => {
+  await browser.locate({ testId: 'shop-search' }).first().fill(query)
+  await browser.page.keyboard.press('Enter')
+}
+
+export const filterByCategory = async (
+  browser: PikkuBrowserWire,
+  category: string
+) => {
+  await browser.locate({ testId: 'category-filter' }).first().click()
+  await browser
+    .locate({ testId: 'category-option', where: { 'data-category': category } })
+    .first()
+    .click()
+}
+
+export const addToBasket = async (browser: PikkuBrowserWire, name: string) => {
+  const card = browser
+    .locate({ testId: 'product-card', containing: name })
+    .first()
+  await card.waitFor({ state: 'visible' })
+  await card.locate('[data-testid=add-to-basket]').click()
+}
+```
+
+The step composes them, and it is the step — one row — that the report shows:
+
+```typescript
+export const buysTheItem = pikkuScenarioStep<
+  { name: string },
+  { name: string }
+>({
+  name: 'buysTheItem',
+  description: 'finds one item in the shop and puts it in the basket',
+  template: 'buys the {name}',
+  // One intent, one implementation per surface an actor can drive it through.
+  browser: async (_services, { name }, { browser }) => {
+    await ensureOnShop(browser)
+    await searchFor(browser, name)
+    await addToBasket(browser, name)
+    return { name }
+  },
+  default: async ({ rpc }, { name }) => {
+    const item = await rpc.invoke('findItemByName', { name })
+    await rpc.invoke('addToBasket', { itemId: item.id })
+    return { name }
+  },
+})
+```
+
+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(
+  'buys a milkshake',
+  'buysTheItem',
+  { name: '£5 strawberry milkshake' },
+  { actor: actors.shopper }
+)
+// 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.
+
+**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<
+  { category: string },
+  { shown: number }
+>({
+  name: 'filtersTheShop',
+  description: 'narrows the catalogue to one category',
+  template: 'filters the shop by {category}',
+  browser: async (_services, { category }, { browser }) => {
+    await ensureOnShop(browser)
+    await filterByCategory(browser, category)
+    return {
+      shown: await browser.locate({ testId: 'product-card' }).count(),
+    }
+  },
+  default: async ({ rpc }, { category }) => ({
+    shown: (await rpc.invoke('listItems', { categorySlug: category })).length,
+  }),
+})
+```
+
+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:
+
+```typescript
+const order = await scenario.do(
+  'Shopper checks out',
+  'createOrder',
+  { basketId, shippingAddress },
+  { actor: actors.shopper }
+)
+```
+
+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.
+
+### `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.
+
+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_:
+
+| 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.
+
+```typescript
+export const seesTheOrderConfirmed = pikkuScenarioStep<
+  { orderId: string },
+  { status: string }
+>({
+  name: 'seesTheOrderConfirmed',
+  template: 'sees order {orderId} confirmed',
+  // Both run on `--run browser`. Each returns what it observed, and the runner
+  // compares them — so this fails when the page disagrees with the database.
+  browser: async (_services, { orderId }, { browser }) => ({
+    status: await browser
+      .locate({ testId: 'order-status', where: { 'data-order': orderId } })
+      .getAttribute('data-status'),
+  }),
+  default: async ({ rpc }, { orderId }) => ({
+    status: (await rpc.invoke('getOrder', { orderId })).status,
+  }),
+})
+```
+
+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.
+
+**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.
+
+**Every scenario must assert.** A flow of only `given`/`when` is a PKU680 critical — it proves nothing threw. Since coverage counts every step, an assertion-free ladder of browser-bound actions would score a perfect `3/3` while checking nothing, so clicking through the UI and never looking at the result is the cheapest way to fake the number. The rule closes that.
+
+Assertions with no possible browser witness are a different thing and should not be written as a `then`: "the audit log recorded it" is a system check, and "the receipt email arrives" is `expectEventually`, which is always out-of-band and always server-side.
+
 ### Declared steps (`pikkuScenarioStep`)
 
 `scenario.do` can only name an RPC. A **step** is a named, typed unit of scenario behaviour whose body is an ordinary pikku function — so it can call several RPCs as its actor, assert, or drive a browser.
@@ -181,12 +379,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',
@@ -201,7 +403,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.
@@ -210,22 +412,24 @@ Rules that bite:
 
 ### Browser steps
 
-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`).
+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 `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.
@@ -242,8 +446,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": {
@@ -288,9 +498,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 `scenarios.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>`.
 
@@ -302,10 +527,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
@@ -366,16 +597,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`.                                                                                   |
-| `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.