@pikku/cli 0.12.54 → 0.12.56

package/skills/pikku-testing/references/cucumber-bdd-testing.md

@@ -0,0 +1,176 @@
+# Cucumber / BDD Testing with `@pikku/cucumber`
+
+## Personas and Named Data — Never Inline JSON
+
+**Never put JSON, inline tables, or raw values inside `.feature` files.** Feature files are for human-readable scenarios; all test data belongs in typed maps that step definitions look up by name.
+
+`@pikku/cucumber` exports `PersonaData<T>` — a typed map that throws a clear error when a name is missing.
+
+### Personas
+
+A **persona** is a named user: login credentials plus the session held after authenticating. Define all personas in one file:
+
+```ts
+// tests/tests/support/personas.ts
+import { PersonaData } from '@pikku/cucumber'
+
+export const logins = new PersonaData({
+  yasser: { email: 'yasser@example.com', password: 'hunter2' },
+  guest:  { email: 'guest@example.com',  password: 'guest123' },
+})
+```
+
+A persona step logs in and stores the session in the world so every subsequent call by that persona carries it automatically:
+
+```ts
+// tests/tests/support/steps/auth.steps.ts
+import { Given } from '@cucumber/cucumber'
+import { logins } from '../personas.js'
+
+Given('{string} logs in', async function (name: string) {
+  await this.call(name, 'auth:login', logins.get(name))
+  const { token } = this.lastResult as { token: string }
+  this.setSession(name, { token })
+})
+```
+
+### Named Domain Data
+
+Use a separate `PersonaData` map per domain concept. Name entries after real-world meaning, not technical fields:
+
+```ts
+// tests/tests/support/data/cards.ts
+import { PersonaData } from '@pikku/cucumber'
+
+export const cards = new PersonaData({
+  'writing a blog post': { title: 'Writing a blog post', columnId: 'backlog' },
+  'fix the login bug':   { title: 'Fix the login bug',   columnId: 'in-progress' },
+})
+```
+
+Steps resolve the name and make the call — the feature file never sees raw data:
+
+```ts
+// tests/tests/support/steps/card.steps.ts
+import { When, Then } from '@cucumber/cucumber'
+import assert from 'node:assert/strict'
+import { cards } from '../data/cards.js'
+
+When('{string} creates a card for {string}', async function (persona: string, cardName: string) {
+  await this.call(persona, 'kanban:createCard', cards.get(cardName))
+})
+
+When('{string} gets the card {string}', async function (persona: string, cardName: string) {
+  const { title } = cards.get(cardName)
+  await this.call(persona, 'kanban:getCard', { title })
+})
+
+// "the newly created card" — checks the live result against the data map entry
+// AND any server-assigned fields (id, createdAt) are present
+Then('the result is the newly created card {string}', function (cardName: string) {
+  const expected = cards.get(cardName)
+  const result = this.lastResult as typeof expected & { id: string; createdAt: string }
+  assert.equal(result.title, expected.title)
+  assert.equal(result.columnId, expected.columnId)
+  assert.ok(result.id, 'expected server-assigned id')
+  assert.ok(result.createdAt, 'expected server-assigned createdAt')
+})
+```
+
+The feature file reads naturally:
+
+```gherkin
+Feature: Card management
+
+  Scenario: Create and retrieve a card
+    Given 'yasser' logs in
+    When 'yasser' creates a card for 'writing a blog post'
+    And 'yasser' gets the card 'writing a blog post'
+    Then the result is the newly created card 'writing a blog post'
+```
+
+### File layout
+
+```
+tests/tests/support/
+  personas.ts          ← logins PersonaData (one per project)
+  data/
+    cards.ts           ← cards PersonaData
+    users.ts           ← users PersonaData
+  steps/
+    auth.steps.ts      ← login / logout steps
+    card.steps.ts      ← card CRUD steps
+```
+
+Keep one `PersonaData` instance per domain concept. Steps import only what they need — no cross-domain coupling.
+
+## Anti-Patterns
+
+### Inline data in feature files
+
+Raw values/JSON in `.feature` files make scenarios brittle and unreadable. Use named references resolved by step definitions instead.
+
+```gherkin
+# Wrong
+When I call 'kanban:createCard' with {"title": "My card", "columnId": "backlog"}
+Then the result title is "My card"
+
+# Right
+When 'yasser' creates a card for 'writing a blog post'
+Then the result is the newly created card 'writing a blog post'
+```
+
+### Feature-coupled step definitions
+
+Steps tied to one feature can't be reused and cause duplication. Organise by **domain concept**, not by feature. Name step files after the domain they cover — a login step belongs in `auth.steps.ts` regardless of which feature needs it.
+
+```
+Wrong:                          Right:
+steps/                          steps/
+  edit_work_experience.ts         auth.steps.ts
+  edit_languages.ts               profile.steps.ts
+  edit_education.ts               card.steps.ts
+```
+
+### Conjunction steps
+
+Don't combine multiple actions into a single step — it makes reuse impossible. Use `And` / `But`: each step does exactly one thing.
+
+```gherkin
+# Wrong — two actions in one step
+Given 'yasser' is logged in and has created a card
+
+# Right — atomic, composable
+Given 'yasser' logs in
+And 'yasser' creates a card for 'writing a blog post'
+```
+
+### Asserting in When steps
+
+`When` steps perform actions; `Then` steps assert outcomes. Mixing them hides intent.
+
+```gherkin
+# Wrong
+When 'yasser' creates a card and the title is 'writing a blog post'
+
+# Right
+When 'yasser' creates a card for 'writing a blog post'
+Then the call succeeds
+```
+
+### Hard-coding persona data in step definitions
+
+Credentials/test inputs embedded in step code can't be reused and break when data changes — look them up from `PersonaData`.
+
+```ts
+// Wrong
+Given('{string} logs in', async function (name: string) {
+  await this.call(name, 'auth:login', { email: 'yasser@example.com', password: 'hunter2' })
+})
+
+// Right
+Given('{string} logs in', async function (name: string) {
+  await this.call(name, 'auth:login', logins.get(name))
+  this.setSession(name, (this.lastResult as { token: string }))
+})
+```

package/skills/pikku-workflow/SKILL.md

@@ -12,247 +12,129 @@ 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.
-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.
-5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
-
-Build durable, multi-step workflows with automatic retry, sleep, suspend/resume, and parallel execution. Steps are cached for replay safety.
-
-## Before You Start
-
-```bash
-pikku info functions --verbose   # See existing functions that can be workflow steps
-pikku info tags --verbose        # Understand project organization
-```
+1. Capture baseline. Run `pikku-verify` (or `pikku all`) BEFORE writing code; note existing errors — only NEW errors are yours to fix.
+2. Discover before editing. Prefer `pikku-meta` / `pikku info functions --verbose` and `pikku info tags --verbose` to see functions usable as steps and project organization; inspect only the focused output you need.
+3. Identify the source files that own the behavior. Do not start from generated output, `.pikku`, `node_modules`, vendored packages, or build artifacts.
+4. Make the smallest source change. Keep generated files generated — never hand-edit SDKs, schema output, or typegen to paper over errors; fix the source cause.
+5. Validate with the narrowest relevant command, then re-run `pikku-verify`. If only files you did not touch still error, those are pre-existing — leave them unless asked.
+6. Call `pikku-workflow-view` only when `pikku-verify` fully passes (codegen AND type check both green) — never after a partial pass.
 
 See `pikku-concepts` for the core mental model.
 
-## API Reference
+Build durable, multi-step workflows with automatic retry, sleep, suspend/resume, and parallel execution. Steps are cached for replay safety.
 
-### `pikkuWorkflowFunc<TInput, TOutput>(fn)`
+## Choosing the right factory
 
-```typescript
-import { pikkuWorkflowFunc } from '#pikku'
+| Factory | When to use | Step-graph view? |
+|---|---|---|
+| `pikkuWorkflowFunc` | **Default for all new workflows.** Sequential + conditional logic; DSL mode (serialisable, replay-safe). ALL `const`/`let` declarations must be at the top level of the function body (not inside blocks). | ✅ Yes |
+| `pikkuWorkflowGraph` | DAG / fan-out with nodes and typed refs between them. | ✅ Yes |
+| `pikkuWorkflowComplexFunc` | Escape hatch only — arbitrary TypeScript, no top-level restriction (e.g. dynamic inline functions the DSL extractor cannot handle). | ❌ No (loses step-graph view) |
 
-const myWorkflow = pikkuWorkflowFunc<InputType, OutputType>(
-  async (services, data, { workflow }) => {
-    // workflow.do(), workflow.sleep(), workflow.suspend()
-    return result
-  }
-)
-```
+**Default to `pikkuWorkflowFunc`.** Use `pikkuWorkflowGraph` ONLY with explicit user approval AND only for a genuine cyclic dependency or Node.js-only import DSL cannot express. Use `pikkuWorkflowComplexFunc` ONLY with explicit user approval — a last-resort escape hatch. Never switch to either just to dodge a PKU641 error; restructure the code instead.
+
+### PKU641 — DSL static analysis error
 
-### Workflow Step Types
+`pikkuWorkflowFunc` statically analyzes the body: **every `const`/`let` must be top-level, not inside any block (`if`, `for`, `while`, …).** Assignments inside blocks are fine — only declarations trigger it.
 
 ```typescript
-// RPC step — run a named Pikku function as a step
-// workflow.do(stepName, funcName, data, options?)
-const result = await workflow.do(
-  'Create profile',
-  'createUserProfile',
-  {
-    email: data.email,
-  },
-  { retries: 3, retryDelay: '1s' }
-)
+// ❌ PKU641 — declaration inside block
+if (priority === 'high') {
+  const bugCard = await workflow.do(...)
+}
 
-// Inline closure step — immediate execution, cached for replay
-// workflow.do(stepName, asyncFn)
-const result = await workflow.do('Generate message', async () => {
-  return `Welcome, ${data.email}!`
-})
+// ✅ hoist the declaration, assign inside the block
+let bugCard: Awaited<ReturnType<typeof workflow.do>>
+if (priority === 'high') {
+  bugCard = await workflow.do(...)
+}
 ```
 
-### Step execution: inline vs queue dispatch
-
-Whether a step runs **inline** (same process/session, no queue round-trip) or is **dispatched to the queue** is decided **purely by the step's function** — there is no workflow-level or per-call `inline` flag.
-
-- **Steps default to inline.** Most steps don't need their own worker; running them inline avoids a queue round-trip per step, so a normally-started workflow executes its whole chain in one orchestrator pass.
-- **`inline: false` opts a function out.** Set `inline: false` on the **function config** (`pikkuFunc` / `pikkuSessionlessFunc`, same level as `auth`/`expose`) to dispatch that step via the queue — for expensive/long-running steps that deserve their own worker, retry isolation, and concurrency limits. It is **not** a `workflow.do(...)` option (those are only `retries`/`retryDelay`/`description`).
-
-The rule (`dispatchStep`):
-
-| Function `inline` | `queueService` present? | Result |
-|---|---|---|
-| default / `true` | any | **inline** |
-| `false` | yes | **queued** (own worker) |
-| `false` | no | **inline + a `logger.warn`** (misconfiguration: can't dispatch) |
+## Import path
 
 ```typescript
-// Push this one expensive step onto the queue; every other step stays inline:
-export const renderLargeReport = pikkuSessionlessFunc({
-  inline: false, // dispatch via queue instead of running inline
-  input: ReportInput,
-  output: ReportOutput,
-  func: async (services, data) => { /* ... */ },
-})
-```
+// CORRECT — workflow factories come from the generated types file
+import { pikkuWorkflowFunc, pikkuWorkflowGraph, pikkuWorkflowComplexFunc } from '#pikku/workflow/pikku-workflow-types.gen.js'
 
-- **Run-level `inline` is separate** and only controls whether the *whole run* executes in-process without queue infrastructure (it's set automatically when there is no `queueService`, or via `startWorkflow(..., { inline: true })`). It governs sleep handling, **not** per-step dispatch — step dispatch is always per-function.
-- `inline: false` requires a `queueService`; without one the step still runs (so the workflow progresses) but emits a `logger.warn` so the misconfiguration is visible.
-
-// Sleep — durable pause (duration: '5min', '1h', '30s', '1d')
-await workflow.sleep('Wait 5 minutes', '5min')
-
-// Suspend — pause until externally resumed
-await workflow.suspend('Awaiting approval')
+// WRONG — '#pikku' does not re-export them (TS2305)
+import { pikkuWorkflowFunc } from '#pikku'
 ```
 
-### Choosing the right wrapper
+## Defining a workflow
 
-| Wrapper | When to use |
-|---|---|
-| `pikkuWorkflowFunc` | **Default.** Use for all new workflows. DSL mode — serialisable, replay-safe. |
-| `pikkuWorkflowComplexFunc` | **Only with explicit user approval.** For workflows with patterns the DSL extractor cannot handle (e.g. dynamic inline functions). Not a general escape hatch — restructure first. |
-| `pikkuWorkflowGraph` | **Only with explicit user approval.** For genuine DAGs where there is a cyclic dependency between nodes or a Node.js-only import DSL cannot express. |
-
-**Conditional results** — the correct DSL pattern when a step only runs under some condition:
+Declare input/output as Zod schemas (like any function) — never TypeScript generic params (no `pikkuWorkflowFunc<In, Out>(...)`; that skips runtime validation). `data` is typed from the input schema.
 
 ```typescript
-// ✅ Declare at top level, assign inside block
-let result: { id: string } | null = null
-if (input.createFoo) {
-  result = await workflow.do('Create foo', 'createFoo', { ... })
-}
-// Use result?.id downstream
-
-// ❌ Do NOT declare const inside a block — DSL forbids block-scoped declarations
-// ❌ Do NOT switch to pikkuWorkflowComplexFunc to avoid the restriction
-```
-
-### `pikkuWorkflowGraph(config)` — DAG Workflows
+import { z } from 'zod'
+import { pikkuWorkflowFunc } from '#pikku/workflow/pikku-workflow-types.gen.js'
+
+const ProcessOrderInput = z.object({ orderId: z.string(), amount: z.number() })
+const ProcessOrderOutput = z.object({ status: z.string(), discount: z.number().optional() })
+
+export const processOrder = pikkuWorkflowFunc({
+  description: 'Process an order through payment and fulfillment',
+  tags: ['orders'],
+  input: ProcessOrderInput,
+  output: ProcessOrderOutput,
+  func: async (services, data, { workflow }) => {
+    // Declare ALL variables at top level — even those only assigned in branches (PKU641)
+    let discount: number | undefined
+    let status: string
+
+    if (data.amount > 1000) {
+      const d = await workflow.do('Apply bulk discount', 'calcDiscount', { amount: data.amount })
+      discount = d.discountPercent
+    }
+
+    const payment = await workflow.do('Charge', 'chargePayment', {
+      orderId: data.orderId,
+      amount: discount ? data.amount * (1 - discount / 100) : data.amount,
+    })
 
-```typescript
-import { pikkuWorkflowGraph } from '#pikku'
+    if (payment.success) {
+      await workflow.do('Fulfill', 'fulfillOrder', { orderId: data.orderId })
+      status = 'fulfilled'
+    } else {
+      status = 'payment-failed'
+    }
 
-pikkuWorkflowGraph({
-  description: 'Onboard a new user',
-  nodes: {
-    createProfile: 'createUserProfile', // nodeName → Pikku function name
-    sendWelcome: 'sendEmail',
-  },
-  config: {
-    createProfile: {
-      next: ['sendWelcome'], // Nodes to run after this one (parallel)
-    },
-    sendWelcome: {
-      input: (ref) => ({
-        // Transform input using refs to prior node outputs
-        to: ref('createProfile', 'email'),
-        subject: 'Welcome!',
-      }),
-    },
+    return { status, discount }
   },
 })
 ```
 
-### HTTP Workflow Wiring
+### Workflow step types
 
 ```typescript
-// Start a workflow
-wireHTTP({
-  method: 'post',
-  route: '/workflow/onboard',
-  func: workflowStart('workflowName'),
-})
-
-// Execute workflow steps (called by orchestrator)
-wireHTTP({
-  method: 'post',
-  route: '/workflow/onboard/run',
-  func: workflow('workflowName'),
-})
-
-// Check workflow status
-wireHTTP({
-  method: 'get',
-  route: '/workflow/status/:runId',
-  func: workflowStatus('workflowName'),
-})
-```
+// RPC step — run a registered Pikku function as a step (opts: retries, retryDelay, description)
+const result = await workflow.do('Step name', 'rpcFunctionName', { ...data }, { retries: 3, retryDelay: '1s' })
 
-## Usage Patterns
+// Inline closure step — immediate execution, cached for replay
+const msg = await workflow.do('Generate', async () => `Welcome, ${data.email}!`)
 
-### Sequential Workflow
+// Sleep — durable pause (duration: '30s', '5min', '1h', '1d')
+await workflow.sleep('Wait 5 minutes', '5min')
 
-```typescript
-const onboardUser = pikkuWorkflowFunc<
-  { email: string; userId: string },
-  { success: boolean }
->(async ({}, data, { workflow }) => {
-  const user = await workflow.do('Create profile', 'createUserProfile', {
-    email: data.email,
-    userId: data.userId,
-  })
-
-  const message = await workflow.do(
-    'Generate welcome',
-    async () => `Welcome, ${data.email}!`
-  )
-
-  await workflow.sleep('Wait 5 minutes', '5min')
-
-  await workflow.do('Send email', 'sendEmail', {
-    to: data.email,
-    subject: 'Welcome!',
-    body: message,
-  })
-
-  return { success: true }
-})
+// Suspend — pause until externally resumed (e.g. awaiting approval), then continue
+await workflow.suspend('Awaiting approval')
 ```
 
-### Parallel Execution (Fan-out)
+### Parallel fan-out
 
 ```typescript
 const users = await Promise.all(
-  data.userIds.map(
-    async (userId) =>
-      await workflow.do(`Get user ${userId}`, 'userGet', { userId })
-  )
-)
-```
-
-### Retry with Backoff
-
-```typescript
-const payment = await workflow.do(
-  'Process payment',
-  'processPayment',
-  { amount: 100 },
-  { retries: 3, retryDelay: '1s' }
+  data.userIds.map((userId) => workflow.do(`Fetch user ${userId}`, 'getUser', { userId }))
 )
 ```
 
-### Conditional Branching
-
-```typescript
-if (user.plan === 'pro') {
-  await workflow.do('Apply discount', 'applyDiscount', { userId })
-}
-```
+### Graph workflow (DAG)
 
-### Suspend and Resume
+`pikkuWorkflowGraph` derives types from the RPC map — no explicit `input`/`output`. Nodes map `nodeName → Pikku function name`; `config.<node>.next` lists nodes to run after it (in parallel); `config.<node>.input: (ref) => ...` transforms input using refs to prior node outputs.
 
 ```typescript
-const approval = pikkuWorkflowFunc<
-  { requestId: string },
-  { approved: boolean }
->(async ({}, data, { workflow }) => {
-  await workflow.do('Submit request', 'submitRequest', data)
-  await workflow.suspend('Awaiting approval')
-  // Workflow pauses here until externally resumed
-  const result = await workflow.do('Check result', 'getApprovalResult', data)
-  return { approved: result.approved }
-})
-```
-
-### Graph Workflow (DAG)
+import { pikkuWorkflowGraph } from '#pikku/workflow/pikku-workflow-types.gen.js'
 
-```typescript
-const userOnboarding = pikkuWorkflowGraph({
+export const userOnboarding = pikkuWorkflowGraph({
   description: 'Onboard a new user',
   nodes: {
     createProfile: 'createUserProfile',
@@ -260,75 +142,27 @@ const userOnboarding = pikkuWorkflowGraph({
     setupDefaults: 'createDefaultTodos',
   },
   config: {
-    createProfile: {
-      next: ['sendWelcome', 'setupDefaults'], // Run in parallel
-    },
+    createProfile: { next: ['sendWelcome', 'setupDefaults'] }, // run in parallel
     sendWelcome: {
-      input: (ref) => ({
-        to: ref('createProfile', 'email'),
-        subject: 'Welcome!',
-      }),
+      input: (ref) => ({ to: ref('createProfile', 'email'), subject: 'Welcome!' }),
     },
   },
 })
 ```
 
-## Complete Example
+## File conventions
 
-```typescript
-// functions/onboarding.workflow.ts
-export const onboardUser = pikkuWorkflowFunc<
-  { email: string; userId: string; plan: string },
-  { success: boolean }
->(async ({}, data, { workflow }) => {
-  // Step 1: Create user profile
-  const user = await workflow.do('Create profile', 'createUserProfile', {
-    email: data.email,
-    userId: data.userId,
-  })
-
-  // Step 2: Set up defaults based on plan
-  if (data.plan === 'pro') {
-    await workflow.do('Apply pro features', 'enableProFeatures', {
-      userId: data.userId,
-    })
-  }
-
-  // Step 3: Send welcome email
-  await workflow.do('Send welcome', 'sendEmail', {
-    to: data.email,
-    subject: 'Welcome!',
-    body: `Welcome to our platform, ${user.name}!`,
-  })
-
-  // Step 4: Wait then send follow-up
-  await workflow.sleep('Wait 1 day', '1d')
-
-  await workflow.do('Send follow-up', 'sendEmail', {
-    to: data.email,
-    subject: 'Getting started',
-    body: 'Here are some tips to get started...',
-  })
+- Place workflows in `packages/functions/src/wirings/*.workflow.ts`; export the variable so the inspector discovers it (no manual registration).
+- HTTP start/run/status routes are auto-scaffolded via `scaffold.workflow` in `pikku.config.json`.
 
-  return { success: true }
-})
+## Step dispatch & HTTP wiring
 
-// wirings/workflow.wiring.ts
-wireHTTP({
-  method: 'post',
-  route: '/onboard',
-  func: workflowStart('onboardUser'),
-})
+For per-step inline-vs-queue dispatch (`inline: false` and the `dispatchStep` rules), the manual `workflowStart`/`workflow`/`workflowStatus` HTTP wirings, and a suspend/resume example, read `references/workflow-reference.md`.
 
-wireHTTP({
-  method: 'post',
-  route: '/onboard/run',
-  func: workflow('onboardUser'),
-})
+## After writing
 
-wireHTTP({
-  method: 'get',
-  route: '/onboard/status/:runId',
-  func: workflowStatus('onboardUser'),
-})
-```
+1. `pikku-verify` (codegen + tsc).
+2. PKU641 → a `const`/`let` is inside a block; hoist it to the top of the function body.
+3. Import errors → use `#pikku/workflow/pikku-workflow-types.gen.js`, not `#pikku`.
+4. Type errors only in files you did not touch → pre-existing template errors; safe to ignore.
+5. Both green → call `pikku-workflow-view` with the workflow name.

package/skills/pikku-workflow/references/workflow-reference.md

@@ -0,0 +1,63 @@
+# Pikku Workflow Reference
+
+## Step execution: inline vs queue dispatch
+
+Whether a step runs **inline** (same process/session, no queue round-trip) or is **dispatched to the queue** is decided **purely by the step's function** — there is no workflow-level or per-call `inline` flag. `workflow.do(...)` options are only `retries`/`retryDelay`/`description`.
+
+- **Steps default to inline.** Most steps don't need their own worker; running them inline avoids a queue round-trip per step, so a normally-started workflow executes its whole chain in one orchestrator pass.
+- **`inline: false` opts a function out.** Set `inline: false` on the **function config** (`pikkuFunc` / `pikkuSessionlessFunc`, same level as `auth`/`expose`) to dispatch that step via the queue — for expensive/long-running steps that deserve their own worker, retry isolation, and concurrency limits.
+- **Run-level `inline` is separate** and only controls whether the *whole run* executes in-process without queue infrastructure (set automatically when there is no `queueService`, or via `startWorkflow(..., { inline: true })`). It governs sleep handling, not per-step dispatch.
+
+The rule (`dispatchStep`):
+
+| Function `inline` | `queueService` present? | Result |
+|---|---|---|
+| default / `true` | any | **inline** |
+| `false` | yes | **queued** (own worker) |
+| `false` | no | **inline + a `logger.warn`** (misconfiguration: can't dispatch) |
+
+```typescript
+// Push this one expensive step onto the queue; every other step stays inline:
+export const renderLargeReport = pikkuSessionlessFunc({
+  inline: false, // dispatch via queue instead of running inline
+  input: ReportInput,
+  output: ReportOutput,
+  func: async (services, data) => { /* ... */ },
+})
+```
+
+`inline: false` requires a `queueService`; without one the step still runs (so the workflow progresses) but emits a `logger.warn` so the misconfiguration is visible.
+
+## HTTP workflow wiring (manual)
+
+Usually auto-scaffolded via `scaffold.workflow`. To wire by hand:
+
+```typescript
+// Start a workflow
+wireHTTP({ method: 'post', route: '/onboard', func: workflowStart('onboardUser') })
+
+// Execute workflow steps (called by the orchestrator)
+wireHTTP({ method: 'post', route: '/onboard/run', func: workflow('onboardUser') })
+
+// Check workflow status
+wireHTTP({ method: 'get', route: '/onboard/status/:runId', func: workflowStatus('onboardUser') })
+```
+
+## Suspend / resume example
+
+```typescript
+import { z } from 'zod'
+import { pikkuWorkflowFunc } from '#pikku/workflow/pikku-workflow-types.gen.js'
+
+export const approval = pikkuWorkflowFunc({
+  description: 'Submit a request and wait for approval',
+  input: z.object({ requestId: z.string() }),
+  output: z.object({ approved: z.boolean() }),
+  func: async (services, data, { workflow }) => {
+    await workflow.do('Submit request', 'submitRequest', data)
+    await workflow.suspend('Awaiting approval') // pauses here until externally resumed
+    const result = await workflow.do('Check result', 'getApprovalResult', data)
+    return { approved: result.approved }
+  },
+})
+```