@pikku/skills 0.12.9 → 0.12.11

package/skills/pikku-realtime/SKILL.md

@@ -97,19 +97,38 @@ a one-word change, not a different import:
 
 ```ts
 export class PikkuRealtime {
-  constructor(options?: { reconnect?: boolean; reconnectDelayMs?: number; reconnectMaxDelayMs?: number })
-  setPikkuFetch(fetch: PikkuFetch): void   // server URL + auth come from here, not the constructor
+  constructor(options?: {
+    reconnect?: boolean
+    reconnectDelayMs?: number
+    reconnectMaxDelayMs?: number
+  })
+  setPikkuFetch(fetch: PikkuFetch): void // server URL + auth come from here, not the constructor
 
   // WebSocket at /events — many topics on one connection
-  subscribe<K extends keyof EventHubTopics>(topic: K, handler: (data: EventHubTopics[K]) => void): () => void
-  unsubscribe<K extends keyof EventHubTopics>(topic: K, handler?: (data: EventHubTopics[K]) => void): void
+  subscribe<K extends keyof EventHubTopics>(
+    topic: K,
+    handler: (data: EventHubTopics[K]) => void
+  ): () => void
+  unsubscribe<K extends keyof EventHubTopics>(
+    topic: K,
+    handler?: (data: EventHubTopics[K]) => void
+  ): void
 
   // SSE at GET /events/:topic — one EventSource per topic
-  subscribeToTopic<K extends keyof EventHubTopics>(topic: K, handler: (data: EventHubTopics[K]) => void): { close: () => void }
+  subscribeToTopic<K extends keyof EventHubTopics>(
+    topic: K,
+    handler: (data: EventHubTopics[K]) => void
+  ): { close: () => void }
 
   // generic escape hatches — see references/other-routes.md
-  subscribeToSSE<T>(path: string, handler: (data: T) => void): { close: () => void }
-  connectToChannel(channelRoute: string, protocols?: string | string[]): WebSocket
+  subscribeToSSE<T>(
+    path: string,
+    handler: (data: T) => void
+  ): { close: () => void }
+  connectToChannel(
+    channelRoute: string,
+    protocols?: string | string[]
+  ): WebSocket
 
   close(): void
 }
@@ -137,14 +156,16 @@ Envelope the payload as `{ topic, data }`: the generated client dispatches on th
 `topic` field, so a bare payload arrives but no handler fires.
 
 ```ts
-import { pikkuFunc } from '#pikku'
+import { pikkuFunc } from '#pikku/function'
 
 export const createTodo = pikkuFunc({
   input: CreateTodoInput,
   output: CreateTodoOutput,
   func: async ({ kysely, eventHub }, data) => {
     const todo = await kysely
-      .insertInto('todos').values(data).returningAll()
+      .insertInto('todos')
+      .values(data)
+      .returningAll()
       .executeTakeFirstOrThrow()
 
     await eventHub.publish('todo-created', null, {
@@ -160,7 +181,9 @@ A thin helper removes the duplication:
 
 ```ts
 async function publishEvent<K extends keyof EventHubTopics>(
-  hub: EventHubService<EventHubTopics>, topic: K, data: EventHubTopics[K]
+  hub: EventHubService<EventHubTopics>,
+  topic: K,
+  data: EventHubTopics[K]
 ) {
   return hub.publish(topic, null, { topic, data })
 }
@@ -187,7 +210,9 @@ const pikku = createPikku(
 // pikku.fetch / pikku.rpc / pikku.realtime — all share the same fetch.
 
 createRoot(document.getElementById('root')!).render(
-  <PikkuProvider pikku={pikku}><App /></PikkuProvider>
+  <PikkuProvider pikku={pikku}>
+    <App />
+  </PikkuProvider>
 )
 ```
 
@@ -214,7 +239,8 @@ function TodoList() {
   useEffect(() => {
     // WebSocket multi-topic:
     const off = realtime.subscribe('todo-created', ({ todo }) =>
-      setTodos((prev) => [...prev, todo]))
+      setTodos((prev) => [...prev, todo])
+    )
     return off
 
     // Single-topic SSE (auto-cleanup on close) instead:
@@ -223,7 +249,13 @@ function TodoList() {
     // return () => sub.close()
   }, [realtime])
 
-  return <ul>{todos.map((t) => <li key={t.id}>{t.title}</li>)}</ul>
+  return (
+    <ul>
+      {todos.map((t) => (
+        <li key={t.id}>{t.title}</li>
+      ))}
+    </ul>
+  )
 }
 ```
 
@@ -235,12 +267,12 @@ sockets (`subscribeToSSE`, `connectToChannel`). See
 
 ## When to pick which transport
 
-| Need                                       | Use                           |
-| ------------------------------------------ | ----------------------------- |
-| Many topics in one connection              | `realtime.subscribe`          |
-| Single live stream, simple cleanup         | `realtime.subscribeToTopic`   |
-| Bidirectional (client also sends messages) | `realtime.subscribe`          |
-| WebSockets blocked by infra                | `realtime.subscribeToTopic`   |
+| Need                                       | Use                         |
+| ------------------------------------------ | --------------------------- |
+| Many topics in one connection              | `realtime.subscribe`        |
+| Single live stream, simple cleanup         | `realtime.subscribeToTopic` |
+| Bidirectional (client also sends messages) | `realtime.subscribe`        |
+| WebSockets blocked by infra                | `realtime.subscribeToTopic` |
 
 Both auto-clean on the server (the eventHub's `onChannelClosed` hook unsubscribes
 all topics for the dead channel id). Don't write manual cleanup unless you're

package/skills/pikku-rpc/SKILL.md

@@ -42,7 +42,7 @@ See `pikku-concepts` for the core mental model.
 | `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 (see `pikku-workflow`)   |
-| `rpc.agent.run/stream(...)`      | Run an AI agent (see `pikku-ai-agent`)    |
+| `rpc.agent.run/stream(...)`      | Run an AI agent (see `pikku-agent`)       |
 | `rpc.agent.resume/approve(...)`  | Answer a tool-approval interrupt          |
 | `rpc.agent.interrupt(runId)`     | Stop an in-flight run                     |
 

package/skills/pikku-rtl/SKILL.md

@@ -18,7 +18,7 @@ Set `dir` **once at the document root** from the active locale, then let the
 browser and Mantine mirror everything — _provided_ every custom style is written
 **flow-relative** (start/end), never **physical** (left/right). Get those two
 things right and Arabic, Hebrew, Farsi and Urdu all work with zero per-component
-*layout* code — directional icons still need one manual step, covered below.
+_layout_ code — directional icons still need one manual step, covered below.
 
 ## Agent Operating Procedure
 

package/skills/pikku-scenario/SKILL.md

@@ -46,7 +46,7 @@ Scenarios live in `srcDirectories` like any other function — by convention `*.
 `pikkuScenario` comes from the **generated** workflow types, not `@pikku/core`:
 
 ```typescript
-import { pikkuScenario } from '#pikku/workflow/pikku-workflow-types.gen.js'
+import { pikkuScenario } from '#pikku/scenario'
 
 export const orderSupportScenario = pikkuScenario<
   { value?: number },
@@ -102,16 +102,23 @@ 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
+than matched. Declare the rubric with `pikkuAgentScorer` (grades in code) or
+`pikkuAgentJudge` (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 })
+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 })
+await scenario.expectScore('answered briefly', runId, 'brevity', {
+  atLeast: 0.8,
+})
 ```
 
 The default bound is `atLeast: 0.5`, so an unqualified `expectScore` still fails
@@ -168,7 +175,7 @@ Hooks are scenario-only. A `before`/`after` on a `pikkuWorkflowFunc` never runs
 `pikkuFeature` groups scenarios the way gherkin's `Feature:` groups `Scenario:`. Scenarios are referenced by **imported identifier**, so a renamed or deleted scenario is a compile error rather than a silent skip:
 
 ```typescript
-import { pikkuFeature } from '#pikku/workflow/pikku-workflow-types.gen.js'
+import { pikkuFeature } from '#pikku/scenario'
 import {
   credentialLazyLoadScenario,
   credentialRoundTripScenario,
@@ -233,7 +240,7 @@ Utilities are **not steps**. They are plain exported functions, they take the br
 
 ```typescript
 // shop.browser.ts — shared actions. Not steps: nothing here is an intent.
-import type { PikkuBrowserWire } from '@pikku/core/workflow'
+import type { PikkuBrowserWire } from '#pikku/scenario'
 import type {} from '@pikku/playwright'
 
 /** Arrive on the shop, from wherever the browser happens to be. */
@@ -370,6 +377,9 @@ export const seesTheOrderConfirmed = pikkuScenarioStep<
   { status: string }
 >({
   name: 'seesTheOrderConfirmed',
+  // Both bindings run as the persona, so the step declares one and the runner
+  // injects `wire.actor` — non-optional in every binding.
+  actor: true,
   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.
@@ -378,8 +388,9 @@ export const seesTheOrderConfirmed = pikkuScenarioStep<
       .locate({ testId: 'order-status', where: { 'data-order': orderId } })
       .getAttribute('data-status'),
   }),
-  default: async ({ rpc }, { orderId }) => ({
-    status: (await rpc.invoke('getOrder', { orderId })).status,
+  // Through the actor, not through a `rpc` service — see "What a step is given".
+  default: async (_services, { orderId }, { actor }) => ({
+    status: (await actor.invoke('getOrder', { orderId })).status,
   }),
 })
 ```
@@ -401,8 +412,7 @@ Assertions with no possible browser witness are a different thing and should not
 `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.
 
 ```typescript
-import { pikkuScenarioStep } from '#pikku/workflow/pikku-workflow-types.gen.js'
-import { requireActor } from '@pikku/core/workflow'
+import { pikkuScenarioStep } from '#pikku/scenario'
 
 export const buysAnApple = pikkuScenarioStep<
   { qty: number },
@@ -411,8 +421,9 @@ export const buysAnApple = pikkuScenarioStep<
   name: 'buysAnApple',
   description: 'buys an apple',
   template: 'buys {qty} apples',
-  default: async (_services, { qty }, { scenarioStep }) => {
-    return await requireActor(scenarioStep).invoke('placeOrder', { qty })
+  actor: true,
+  default: async (_services, { qty }, { actor }) => {
+    return await actor.invoke('placeOrder', { qty })
   },
 })
 ```
@@ -436,12 +447,63 @@ 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` 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.
+- **A step that runs as somebody declares `actor: true`**, and the runner injects `wire.actor` — non-optional inside every binding, with no guard to write and nothing to unwrap. A `browser` binding implies it, because a window is opened as somebody. Leave it off for a step with no persona to be: an assertion over what an earlier step returned, or one that posts credentials precisely because it must not reuse an actor's session. Dispatching a step that declared it without `{ actor: actors.x }` fails before the body runs (`ScenarioActorRequired`); a step that did not declare it has no `actor` on its wire at all.
+- **`env` is optional on the wire**, because most steps need nothing from it. Narrow it with `requireScenarioEnv(scenarioStep)` from `#pikku/scenario` rather than a local guard — it names the step and says 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.
 - **`description` documents the step; `template` is what the report renders.** `template`'s `{placeholders}` are filled from the input the step was called with, so one step reads differently for each call — `sees {state} addon {packageName}` reports as "sees available addon @pikku/addon-stripe". Reflect every input field in the template, and type the values so they read as words (`state?: 'installed' | 'available'`, not `installed?: boolean`). A placeholder with no value renders as nothing and the whitespace collapses.
 - Prose precedence is `options.description` → the step's `template` → the step's own `description` → the positional step name. Repeated names get `#1`, `#2` ordinals, so a `for` loop over a data set is how you write a Scenario Outline. A loop-generated step name is not statically known, so it is matched back to its declaration by step function instead — which works as long as that function's call sites agree on their phase, actor and prose. Two call sites that disagree make the loop step report under its bare runtime name.
 
+#### What a step is given
+
+A step has the signature of an ordinary pikku function, which makes it look as
+though it runs where the application runs. It does not — **it runs in the CLI
+process**, and the services object is built there, by hand:
+
+```typescript
+{ logger, workflowService, workflowRunService, agentRunner? }
+```
+
+That is the whole list. There is no `kysely`, no `variables`, no `secrets`, and
+none of the project's own singleton or wire services. A step that destructures
+one gets `undefined` and fails on first use — `Cannot read properties of
+undefined (reading 'selectFrom')` — which reads like a broken container and is
+not.
+
+`rpc` is the trap worth naming, because it is present and it throws. It is a
+`guardRpc` whose every member refuses:
+
+> Scenario tried to run 'getOrder' as an internal step. Every workflow.do in a
+> scenario must carry { actor: actors.x } so it executes against 'local'.
+
+The same guard covers `rpc.agent.run/stream/resume/approve/interrupt` and
+`startWorkflow`.
+
+This is the design, not a gap: **everything a step touches of the application
+goes over the wire as somebody.** A test that could reach into the database
+would be testing a different program from the one a person uses. So there are
+exactly three ways in, and they are all through the actor:
+
+- `actor.invoke(name, data)` — typed over the exposed RPC map, carrying the
+  actor's session. Declare `actor: true` and destructure it off the wire.
+- `.invokeRaw(name, data, { headers })` — same call, reporting
+  `{ status, ok, body }`, for when the refusal is the assertion.
+- a plain `fetch` against `requireScenarioEnv(scenarioStep).apiUrl`, for
+  anything not an RPC — a websocket, a file upload, a webhook.
+
+Two consequences follow, and both shape how steps get written:
+
+- **A step cannot observe anything the app does not publish.** If a test needs a
+  fact the client never sees, the fix is to emit it on the stream or expose it
+  as an RPC — which usually improves the product, since a client debugging the
+  same problem needed it too.
+- **`agentRunner` is conditional.** It is built only when the project declares
+  agents, and `createDevAgentRunner` needs a base URL *and* a key together
+  (`OPENAI_BASE_URL` + `OPENAI_API_KEY`, or the LiteLLM pair). With a key alone
+  it returns nothing and `agentRunner` is `undefined`, so `actor.converse`
+  fails before the persona says anything. A suite that would rather own its own
+  model can pass an `llm` to `runConversation` instead of relying on this one.
+
 ### Browser steps
 
 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.
@@ -451,17 +513,20 @@ A `browser` binding gets a session bound to **its actor**, signed in through the
 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 }>(
-  {
-    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 }),
-  }
-)
+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 (_services, _data, { actor }) => ({
+    url: (await actor.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.
@@ -517,11 +582,68 @@ A persona holds only what is true of that kind of person for the app's whole lif
 
 `kind: "system"` is the app acting on its own — a schedule, a cleanup, a send. It gets **no actor**: there is nobody to sign in. Give it one by hand only if it genuinely has a service account.
 
+#### Declaring personas in TypeScript
+
+`definePersonas({ … })` is the code form of the block above, and there may be
+**one call in the whole codebase** — one place to read the set from, one place
+to add to it. A second anywhere, including in the same file, is a critical.
+Generated files are exempt and never claim the slot.
+
+> [!WARNING]
+> The declaration is **read from source, never evaluated** — the CLI writes it
+> to JSON that a deployed stage carries without the app. So every value has to
+> be statically knowable, and a value that is not comes out as `undefined`
+> rather than as an error. Only `name` is checked, so a computed `personality`,
+> `jobTitle` or `description` is dropped in silence and the persona runs with a
+> blank temperament.
+
+What that admits and what it does not:
+
+```typescript
+personality: 'Wound up and short with it.'      // read
+personality: `Wound up and short with it.
+  Says what she wants in a few blunt words.`    // read — no ${} in it
+personality: 'Wound up. ' + 'Short with it.'    // dropped, silently
+personality: TEMPERAMENTS.impatient             // dropped, silently
+```
+
+A no-substitution template literal is a string literal as far as the reader is
+concerned, so it is the way to write a long personality across several lines —
+not a concatenation, and not a `prettier-ignore`d single line. Its newlines and
+leading indentation are kept verbatim and reach the model that way, which is
+harmless but worth knowing before you align it to the surrounding code.
+
+One more thing worth knowing before writing a rich persona: **`actor.converse`
+builds its prompt from `name`, `jobTitle`, `personality` and the scenario's
+`task` only.** Fields like `disposition`, `goals` and `roles` are read and
+stored, and the console shows them, but they do not reach the conversing
+persona's instructions. Anything that must shape how someone talks belongs in
+`personality` or in the task.
+
 An actor with no `persona` is its own persona, so a project that never declares any keeps working unchanged.
 
 - `environments.<name>.apiUrl` is required. `signInPath` defaults to `/auth/sign-in/actor`, `rpcPath` to `/rpc`.
 - **`SCENARIO_ACTOR_SECRET` is an environment variable and never goes in `pikku.config.json`.** It signs actors in. `pikku scenario run` throws without it; a server auto-building actors warns and runs without them.
 
+### The same actors sign a human in
+
+Declared actors are not only for automated runs. `signInPath` is Better Auth's
+`actor` plugin (see `pikku-better-auth`), which any caller can post to — so the
+frontend gets a one-click "Sign in as …" switcher over the **same** list, and an
+app can be reviewed as each kind of user without anyone knowing a seed password.
+
+The sandbox dev server bakes both halves into the frontend from the declared
+personas: `VITE_DEV_ACTORS` (the JSON actor list) and
+`VITE_SCENARIO_ACTOR_SECRET`. Neither is set in a production build, so the
+control renders nothing there — but gate the reads on your bundler's dev flag
+anyway (`import.meta.env.DEV ? … : undefined`) so the secret never reaches a
+production bundle in the first place.
+
+Do not hand-roll the switcher: `useDevActors()` (`pikku-react`) is the logic and
+`<DevActorSwitcher />` from `@pikku/mantine/dev` is a ready rendering of it.
+`pikku fabric validate` **requires** any frontend with a login screen to ship
+one — without it a reviewer is locked out of their own sandbox.
+
 ## Running
 
 ```bash
@@ -535,19 +657,19 @@ SCENARIO_ACTOR_SECRET=… pikku scenario run local --spawn --no-browser --exclud
 
 `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                                             |
+| 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>`.
 
@@ -584,9 +706,7 @@ The run resets coverage before each scenario and snapshots after, writing **`<ou
   "generatedAt": "…",
   "environment": "local",
   "scenarios": {
-    "<name>": {
-      /* FunctionCoverageReport */
-    },
+    "<name>": {/* FunctionCoverageReport */},
   },
 }
 ```
@@ -640,7 +760,7 @@ Services are plain objects — a Pikku function is pure business logic, so a moc
 | 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.             |
+| 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. |
 

package/skills/pikku-schedule/SKILL.md

@@ -51,7 +51,12 @@ development and a single-instance deployment, wrong for anything else.
 ### Scheduling a one-off RPC
 
 ```typescript
-const taskId = await schedulerService.scheduleRPC('5m', 'sendReminder', data, session)
+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

package/skills/pikku-schema-ajv/SKILL.md

@@ -52,7 +52,7 @@ called `schema` in the source, which reads backwards.
 
 - **Registration is name-keyed and never re-compiles.** A second
   `compileSchema('X', …)` with a different schema is a no-op; the first one wins
-  for the process lifetime. `@pikku/schema-cfworker` *does* recompile on a
+  for the process lifetime. `@pikku/schema-cfworker` _does_ recompile on a
   changed value, so a dev hot-reload after codegen picks up a changed schema
   there but not here — restart the process instead.
 - **AJV is a module-level singleton**, shared by every `AjvSchemaService` you
@@ -62,7 +62,7 @@ called `schema` in the source, which reads backwards.
   become `1` — the wiring layer is what coerces, not this service.
 - `ajv-formats` is registered, so `format` keywords (`email`, `uuid`, `date-time`)
   are enforced.
-- A failed validation throws `UnprocessableContentError` (a 422). A *missing*
+- A failed validation throws `UnprocessableContentError` (a 422). A _missing_
   schema throws a bare string, `Missing validator for <name>` — not an `Error`,
   so `catch (e) { e.message }` reads `undefined`. That normally means codegen
   didn't run.

package/skills/pikku-schema-cfworker/SKILL.md

@@ -63,7 +63,7 @@ surface as behaviour changes rather than compile errors:
   underlying cause swallowed — check the schema by hand when you see it.
 
 A failed validation throws `UnprocessableContentError` (422) with the validator
-errors joined; a *missing* schema throws a bare string, `Missing validator for
+errors joined; a _missing_ schema throws a bare string, `Missing validator for
 <name>`, not an `Error`.
 
 ## Usage Patterns

package/skills/pikku-security/SKILL.md

@@ -62,7 +62,7 @@ Apply these via `addHTTPMiddleware` in a wirings file:
 
 ```typescript
 import { authBearer, authCookie, authAPIKey } from '@pikku/core/middleware'
-import { addHTTPMiddleware } from '#pikku'
+import { addHTTPMiddleware } from '#pikku/http'
 
 // JWT bearer token — reads Authorization header
 addHTTPMiddleware('*', [authBearer()])
@@ -118,14 +118,18 @@ response.
 
 ```typescript
 // permissions.ts
-import { pikkuAuth, pikkuPermission } from '#pikku'
+import { pikkuAuth, pikkuPermission } from '#pikku/function'
 
-export const isAuthenticated = pikkuAuth(async (_services, session) => !!session)
-export const isVerified = pikkuAuth(async (_services, session) => !!session?.emailVerified)
+export const isAuthenticated = pikkuAuth(
+  async (_services, session) => !!session
+)
+export const isVerified = pikkuAuth(
+  async (_services, session) => !!session?.emailVerified
+)
 
 // wirings/auth.wiring.ts
 import { authCookie } from '@pikku/core/middleware'
-import { addHTTPMiddleware } from '#pikku'
+import { addHTTPMiddleware } from '#pikku/http'
 
 addHTTPMiddleware('*', [
   authCookie({

package/skills/pikku-services/SKILL.md

@@ -38,7 +38,7 @@ pikku info tags --verbose        # Understand project organization
 ### `pikkuServices(factory)` — singleton services (created once at startup)
 
 ```typescript
-import { pikkuServices } from '#pikku'
+import { pikkuServices } from '#pikku/function'
 import { ConsoleLogger } from '@pikku/core/services'
 import { JoseJWTService } from '@pikku/jose'
 
@@ -61,7 +61,7 @@ export const createSingletonServices = pikkuServices(
 ### `pikkuWireServices(factory)` — per-request services (fresh per HTTP request, queue job, CLI command, etc.)
 
 ```typescript
-import { pikkuWireServices } from '#pikku'
+import { pikkuWireServices } from '#pikku/function'
 
 export const createWireServices = pikkuWireServices(
   async (singletonServices, wire) => {
@@ -157,13 +157,16 @@ const getUser = pikkuFunc({
 
 **Never write a `if (!service) throw ...` existence guard in a function body.** It is dead code, and it defeats the platform.
 
-Optionality lives in exactly one place — `services.ts` / the `SingletonServices` declaration — and it means *"this may not be created"*, not *"this may be missing at call time"*. A service is optional precisely because **nothing destructures it**, and the generated `requiredSingletonServices` manifest therefore never marks it for creation. The moment any wired function destructures it, Pikku creates it and guarantees it is there.
+Optionality lives in exactly one place — `services.ts` / the `SingletonServices` declaration — and it means _"this may not be created"_, not _"this may be missing at call time"_. A service is optional precisely because **nothing destructures it**, and the generated `requiredSingletonServices` manifest therefore never marks it for creation. The moment any wired function destructures it, Pikku creates it and guarantees it is there.
 
 The types enforce this rather than merely documenting it. The inspector records the services destructured by every wired `func`, `permissions` **and** `middleware`, and emits them as `RequiredSingletonServices`. The generated function types then default their service parameter to:
 
 ```typescript
-export type WiredSingletonServices = RequiredSingletonServices & SingletonServices
-export type WiredServices = SecretlessServices<RequiredSingletonServices & Services>
+export type WiredSingletonServices = RequiredSingletonServices &
+  SingletonServices
+export type WiredServices = SecretlessServices<
+  RequiredSingletonServices & Services
+>
 ```
 
 The `SecretlessServices<...>` wrapper is why `secrets` never appears in a
@@ -223,21 +226,21 @@ const createSingletonServices = pikkuServices(async (config) => {
 
 ### Built-in Services
 
-| Service                    | Package                | Purpose                          |
-| -------------------------- | ---------------------- | -------------------------------- |
-| `ConsoleLogger`            | `@pikku/core/services` | Console-based logging            |
-| `JoseJWTService`           | `@pikku/jose`          | JWT sign/verify via jose         |
-| `LocalSecretService`       | `@pikku/core/services` | Local development secrets        |
-| `LocalVariablesService`    | `@pikku/core/services` | Local environment variables      |
-| `PinoLogger`               | `@pikku/pino`          | Structured logging via Pino      |
-| `createInvocationAudit`    | `@pikku/core/services` | Per-request audit buffer         |
-| `createAuditedKysely`      | `@pikku/kysely`        | Auto-capture DB queries as audit events |
+| Service                 | Package                | Purpose                                 |
+| ----------------------- | ---------------------- | --------------------------------------- |
+| `ConsoleLogger`         | `@pikku/core/services` | Console-based logging                   |
+| `JoseJWTService`        | `@pikku/jose`          | JWT sign/verify via jose                |
+| `LocalSecretService`    | `@pikku/core/services` | Local development secrets               |
+| `LocalVariablesService` | `@pikku/core/services` | Local environment variables             |
+| `PinoLogger`            | `@pikku/pino`          | Structured logging via Pino             |
+| `createInvocationAudit` | `@pikku/core/services` | Per-request audit buffer                |
+| `createAuditedKysely`   | `@pikku/kysely`        | Auto-capture DB queries as audit events |
 
 ## Complete Example
 
 ```typescript
 // services.ts
-import { pikkuServices, pikkuWireServices } from '#pikku'
+import { pikkuServices, pikkuWireServices } from '#pikku/function'
 import { ConsoleLogger } from '@pikku/core/services'
 import { JoseJWTService } from '@pikku/jose'
 
@@ -249,9 +252,15 @@ class TodoStore {
     this.todos.set(todo.id, todo)
     return todo
   }
-  async get(id: string) { return this.todos.get(id) }
-  async list() { return [...this.todos.values()] }
-  async delete(id: string) { this.todos.delete(id) }
+  async get(id: string) {
+    return this.todos.get(id)
+  }
+  async list() {
+    return [...this.todos.values()]
+  }
+  async delete(id: string) {
+    this.todos.delete(id)
+  }
 }
 
 export const createSingletonServices = pikkuServices(async (config) => {