@pikku/skills 0.12.1 → 0.12.4

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
@@ -166,6 +167,200 @@ export const credentialFeature = pikkuFeature({
 
 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 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.
+
+```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.
@@ -210,8 +405,12 @@ 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.
+
 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`).
 
+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 },
@@ -290,7 +489,7 @@ SCENARIO_ACTOR_SECRET=… pikku scenario run local --features credentialFeature
 SCENARIO_ACTOR_SECRET=… pikku scenario run local --tags smoke,scenario
 ```
 
-`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`. `--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.
 
 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>`.
 
@@ -300,13 +499,13 @@ Output is `PASS <name> (<ms>) → <output>` / `FAIL <name> (<ms>): <error>`, the
 
 Coverage is attributed by running scenarios against a server that is collecting it. It is **not** derived from unit tests.
 
-Prerequisites in `pikku.config.json`:
+Prerequisite in `pikku.config.json`:
 
 ```json
-{ "scaffold": { "scenarios": "auth" }, "verboseMeta": true }
+{ "scaffold": { "scenarios": "auth" } }
 ```
 
-`scaffold.scenarios` generates the coverage and stub RPCs into your project (`pikkuScenarioTakeLiveCoverage`, `pikkuScenarioResetLiveCoverage`, `pikkuScenarioResetStubs`, `pikkuScenarioGetStubCalls`), so scenario runs work against any server. `verboseMeta` is required — the coverage RPC reads the verbose functions meta and returns `null` without it.
+`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
 pikku dev --coverage                                   # V8 precise coverage, in-process
@@ -374,8 +573,11 @@ Services are plain objects — a Pikku function is pure business logic, so a moc
 | 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`, `verboseMeta` off, `scaffold.scenarios` unset, or no actors configured. |
+| 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

@@ -15,7 +15,7 @@ installGroups: [core]
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
 4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.

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

@@ -14,7 +14,7 @@ installGroups: [core]
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
 4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.

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

@@ -15,7 +15,7 @@ installGroups: [core, fabric]
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
 4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.

package/skills/pikku-services/SKILL.md

@@ -16,7 +16,7 @@ installGroups: [core]
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
 4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.

package/skills/pikku-software-archaeology/README.md

@@ -6,7 +6,7 @@ Reverse-engineers an existing repository into a **Product Blueprint**: the produ
 Existing Repository → pikku-software-archaeology → .knowledge/ blueprint → new Pikku application
 ```
 
-This is **not** a code indexer or doc generator. It extracts *intent over implementation*: `POST /api/users/:id/status` becomes the command `ActivateUser`; three scattered `if (inv.user_id !== req.user.id)` checks become one `InvoiceOwnerOnly` policy with three `enforcedAt` citations.
+This is **not** a code indexer or doc generator. It extracts _intent over implementation_: `POST /api/users/:id/status` becomes the command `ActivateUser`; three scattered `if (inv.user_id !== req.user.id)` checks become one `InvoiceOwnerOnly` policy with three `enforcedAt` citations.
 
 ## Design decision: the AI is the parser
 
@@ -19,8 +19,9 @@ In Claude Code, from (or pointing at) the target repo:
 > Use the pikku-software-archaeology skill to extract a product blueprint from /path/to/repo
 
 The agent then:
+
 1. **Surveys** the repo (manifests, entry points, routes, jobs, webhooks, schema, config, TODO/HACK markers) — facts only.
-2. **Excavates the test suite** — `describe`/`it` names become workflow scenarios; assertions confirm policies and upgrade confidence; rules that exist *only* in tests are captured.
+2. **Excavates the test suite** — `describe`/`it` names become workflow scenarios; assertions confirm policies and upgrade confidence; rules that exist _only_ in tests are captured.
 3. **Extracts** through twelve lenses (domains, entities, commands, …) per the pipeline in `SKILL.md`. Large repos fan out subagents per lens and merge.
 4. **Cross-checks and validates**:
    ```bash
@@ -37,15 +38,23 @@ Concept names are the stable IDs. On re-run after code changes, re-extract only
 
 ## How Pikku consumes the blueprint
 
-Full mapping table in `references/pikku-mapping.md`. Summary: entities → Kysely migrations + Zod schemas; commands/queries → `pikkuFunc`s; api surfaces → `wireHTTP`; policies → shared permission functions (collapsing duplicated legacy checks); system workflows → `wireScheduler`/`wireQueueWorker`/`pikkuWorkflowFunc`; integrations → injected services with `wireSecret`/`wireCredential`; test-derived scenarios → `pikkuUserFlow` stories / e2e tests. Humans resolve `migration.json.decisionsNeeded` before any generation starts.
+Full mapping table in `references/pikku-mapping.md`. Summary: entities → Kysely migrations + Zod schemas; commands/queries → `pikkuFunc`s; api surfaces → `wireHTTP`; policies → shared permission functions (collapsing duplicated legacy checks); system workflows → `wireScheduler`/`wireQueueWorker`/`pikkuWorkflowFunc`; integrations → injected services with `defineSecret`/`defineCredential`; test-derived scenarios → `pikkuUserFlow` stories / e2e tests. Humans resolve `migration.json.decisionsNeeded` before any generation starts.
 
 ## How uncertainty is represented
 
 Every extracted concept carries:
 
 ```json
-{ "evidence": [{ "file": "controllers/invoices.js", "lines": "52", "note": "guard: only drafts editable" }],
-  "confidence": "high" }
+{
+  "evidence": [
+    {
+      "file": "controllers/invoices.js",
+      "lines": "52",
+      "note": "guard: only drafts editable"
+    }
+  ],
+  "confidence": "high"
+}
 ```
 
 - **high** — the behavior itself is in the cited code/schema/test. Generates directly.
@@ -53,7 +62,8 @@ Every extracted concept carries:
 - **low** — plausible reconstruction. Never auto-generated; surfaced for human review.
 
 Two further distinctions keep facts and guesses separate:
-- `events[].explicit: false` — the event was *reconstructed* from side-effect clusters (email + status flip), not emitted by the code.
+
+- `events[].explicit: false` — the event was _reconstructed_ from side-effect clusters (email + status flip), not emitted by the code.
 - Comments/docs vs code: comments describe intent, code describes behavior. Disagreements are recorded as the code's behavior plus a `gaps.json` entry.
 
 ## Repo layout

package/skills/pikku-software-archaeology/references/pikku-mapping.md

@@ -2,36 +2,36 @@
 
 The `.knowledge/` blueprint is designed so each concept maps onto exactly one Pikku primitive. A generator (or an agent following `pikku-feature`) walks the JSON files in this order:
 
-| Blueprint source | Pikku target |
-|---|---|
-| `entities.json` attributes + relationships + constraints | Kysely migrations + generated `DB` types; Zod schemas per entity |
-| `entities.json` states/transitions | a `status` column + transition guards inside the owning commands (or a state-machine helper) |
-| `commands.json` | `pikkuFunc` / `pikkuSessionlessFunc` with `input:` Zod schema built from `input[]`; `preconditions` become guard clauses; name is the camelCased command name (`SendInvoice` → `sendInvoice`) |
-| `queries.json` | `pikkuFunc` reads; `scoping` becomes the mandatory `WHERE` / session filter |
-| `events.json` | EventHub topics (realtime) or queue messages; `consumedBy` become `wireQueueWorker` handlers — implicit events (`explicit: false`) get promoted to real emissions |
-| `policies.json` (authorization) | Pikku `permissions` / middleware; one policy = one named permission function, wired everywhere `enforcedAt` listed — this collapses duplicated legacy checks into a single definition |
-| `policies.json` (validation) | Zod schema refinements on the command's `input` |
-| `workflows.json` kind=user | frontend flows + the commands they chain |
-| `workflows.json` kind=system, with `schedule` | `wireScheduler` entries |
-| `workflows.json` multi-step / checkpointing | `pikkuWorkflowFunc` with one `workflow.do(...)` step per blueprint step |
-| `workflows.json` `scenarios[]` | **`pikkuUserFlow` stories — this is the canonical target.** Each scenario's given/when/outcome maps 1:1 onto a user-flow step sequence; group scenarios by their workflow into one flow per journey. Only scenarios with no user-facing surface (pure system workflows: cron sweeps, webhook ingest) fall back to API/e2e tests |
-| `api.json` | `wireHTTP` routes: keep `path`+`method` for compatibility, point at the mapped command/query func; `auth: none`/capability-URL surfaces get `auth: false` |
-| `api.json` kind=webhook-in | `wireHTTP` with `auth: false` + signature-verification middleware from the integration |
-| `integrations.json` | services in `services.ts` (constructor-injected classes); `configVia` env vars become `wireSecret` / config; per-user credentials become `wireCredential` |
-| `architecture.json` notes | deployment config (ports, raw-body routes, proxy expectations) |
-| `invariants.json` enforcedBy=db-constraint | migration constraints (UNIQUE, CHECK, FK) |
-| `invariants.json` enforcedBy=code-guard/nothing | guard clauses + a test each; `atRiskBecause` entries get a hardening task |
-| `gaps.json` | excluded from generation; `open-product-decision` + `migration.json.decisionsNeeded` go to a human BEFORE generation starts |
-| `migration.json.mappings` | the work plan: one mapping = one migration slice |
-| `interfaces.json` kind=cli | `wireCLI` entrypoints — the CLI commands are the same funcs the routes expose |
-| `interfaces.json` kind=mcp | `wireMCP` — each MCP tool IS a `pikkuFunc` (reuse the command/query funcs; don't author tool duplicates) |
-| `interfaces.json` kind=openapi-rest / sdk | generated, not hand-written: the OpenAPI spec + typed client SDK fall out of the `wireHTTP` routes + codegen |
-| `interfaces.json` kind=websocket-realtime | `pikku-realtime` EventHub topics / channels |
-| `frontend.json` | `apps/app` (TanStack Start) shell: router, `@pikku/mantine` theme, `pikku-react-query` data layer, `better-auth` client — the target stack the legacy UI is rebuilt onto |
-| `frontend-routes.json` | TanStack Router routes under `apps/app/src/routes/**` (thin data containers calling `usePikkuQuery`); `dataFrom` names become the generated hooks; subpath routes for rich detail views |
-| `frontend-components.json` rebuild=`mantine-standard`/`mantine-composition` | components in `packages/components` composed from `@pikku/mantine` — the trivial/straightforward bulk |
-| `frontend-components.json` rebuild=`custom-logic` | the PORT list — each becomes a `packages/components` component that reimplements the bespoke behavior (chart/table/editor); its `dependencies` inform whether the lib is kept or replaced. These are the frontend's real work items |
-| `frontend-components.json` rebuild=`custom-style` | normalize to Mantine/theme tokens; usually deleted-and-recomposed, not ported |
+| Blueprint source                                                            | Pikku target                                                                                                                                                                                                                                                                                                                    |
+| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `entities.json` attributes + relationships + constraints                    | Kysely migrations + generated `DB` types; Zod schemas per entity                                                                                                                                                                                                                                                                |
+| `entities.json` states/transitions                                          | a `status` column + transition guards inside the owning commands (or a state-machine helper)                                                                                                                                                                                                                                    |
+| `commands.json`                                                             | `pikkuFunc` / `pikkuSessionlessFunc` with `input:` Zod schema built from `input[]`; `preconditions` become guard clauses; name is the camelCased command name (`SendInvoice` → `sendInvoice`)                                                                                                                                   |
+| `queries.json`                                                              | `pikkuFunc` reads; `scoping` becomes the mandatory `WHERE` / session filter                                                                                                                                                                                                                                                     |
+| `events.json`                                                               | EventHub topics (realtime) or queue messages; `consumedBy` become `wireQueueWorker` handlers — implicit events (`explicit: false`) get promoted to real emissions                                                                                                                                                               |
+| `policies.json` (authorization)                                             | Pikku `permissions` / middleware; one policy = one named permission function, wired everywhere `enforcedAt` listed — this collapses duplicated legacy checks into a single definition                                                                                                                                           |
+| `policies.json` (validation)                                                | Zod schema refinements on the command's `input`                                                                                                                                                                                                                                                                                 |
+| `workflows.json` kind=user                                                  | frontend flows + the commands they chain                                                                                                                                                                                                                                                                                        |
+| `workflows.json` kind=system, with `schedule`                               | `wireScheduler` entries                                                                                                                                                                                                                                                                                                         |
+| `workflows.json` multi-step / checkpointing                                 | `pikkuWorkflowFunc` with one `workflow.do(...)` step per blueprint step                                                                                                                                                                                                                                                         |
+| `workflows.json` `scenarios[]`                                              | **`pikkuUserFlow` stories — this is the canonical target.** Each scenario's given/when/outcome maps 1:1 onto a user-flow step sequence; group scenarios by their workflow into one flow per journey. Only scenarios with no user-facing surface (pure system workflows: cron sweeps, webhook ingest) fall back to API/e2e tests |
+| `api.json`                                                                  | `wireHTTP` routes: keep `path`+`method` for compatibility, point at the mapped command/query func; `auth: none`/capability-URL surfaces get `auth: false`                                                                                                                                                                       |
+| `api.json` kind=webhook-in                                                  | `wireHTTP` with `auth: false` + signature-verification middleware from the integration                                                                                                                                                                                                                                          |
+| `integrations.json`                                                         | services in `services.ts` (constructor-injected classes); `configVia` env vars become `defineSecret` / config; per-user credentials become `defineCredential`                                                                                                                                                                   |
+| `architecture.json` notes                                                   | deployment config (ports, raw-body routes, proxy expectations)                                                                                                                                                                                                                                                                  |
+| `invariants.json` enforcedBy=db-constraint                                  | migration constraints (UNIQUE, CHECK, FK)                                                                                                                                                                                                                                                                                       |
+| `invariants.json` enforcedBy=code-guard/nothing                             | guard clauses + a test each; `atRiskBecause` entries get a hardening task                                                                                                                                                                                                                                                       |
+| `gaps.json`                                                                 | excluded from generation; `open-product-decision` + `migration.json.decisionsNeeded` go to a human BEFORE generation starts                                                                                                                                                                                                     |
+| `migration.json.mappings`                                                   | the work plan: one mapping = one migration slice                                                                                                                                                                                                                                                                                |
+| `interfaces.json` kind=cli                                                  | `wireCLI` entrypoints — the CLI commands are the same funcs the routes expose                                                                                                                                                                                                                                                   |
+| `interfaces.json` kind=mcp                                                  | `wireMCP` — each MCP tool IS a `pikkuFunc` (reuse the command/query funcs; don't author tool duplicates)                                                                                                                                                                                                                        |
+| `interfaces.json` kind=openapi-rest / sdk                                   | generated, not hand-written: the OpenAPI spec + typed client SDK fall out of the `wireHTTP` routes + codegen                                                                                                                                                                                                                    |
+| `interfaces.json` kind=websocket-realtime                                   | `pikku-realtime` EventHub topics / channels                                                                                                                                                                                                                                                                                     |
+| `frontend.json`                                                             | `apps/app` (TanStack Start) shell: router, `@pikku/mantine` theme, `pikku-react-query` data layer, `better-auth` client — the target stack the legacy UI is rebuilt onto                                                                                                                                                        |
+| `frontend-routes.json`                                                      | TanStack Router routes under `apps/app/src/routes/**` (thin data containers calling `usePikkuQuery`); `dataFrom` names become the generated hooks; subpath routes for rich detail views                                                                                                                                         |
+| `frontend-components.json` rebuild=`mantine-standard`/`mantine-composition` | components in `packages/components` composed from `@pikku/mantine` — the trivial/straightforward bulk                                                                                                                                                                                                                           |
+| `frontend-components.json` rebuild=`custom-logic`                           | the PORT list — each becomes a `packages/components` component that reimplements the bespoke behavior (chart/table/editor); its `dependencies` inform whether the lib is kept or replaced. These are the frontend's real work items                                                                                             |
+| `frontend-components.json` rebuild=`custom-style`                           | normalize to Mantine/theme tokens; usually deleted-and-recomposed, not ported                                                                                                                                                                                                                                                   |
 
 ## Order of generation
 

package/skills/pikku-trigger/SKILL.md

@@ -16,7 +16,7 @@ installGroups: [core]
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
 4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.

package/skills/pikku-versioning/SKILL.md

@@ -16,7 +16,7 @@ installGroups: [core]
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
 4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.

package/skills/pikku-websocket/SKILL.md

@@ -15,7 +15,7 @@ description: >-
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
 4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.

package/skills/pikku-workflows-client/SKILL.md

@@ -10,7 +10,7 @@ installGroups: [core]
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
 4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.

package/skills/pikku-ws/SKILL.md

@@ -13,7 +13,7 @@ description: >-
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
 4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.