@pikku/skills 0.12.39 → 0.12.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.39",
+  "version": "0.12.41",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",

package/skills/pikku-agent/references/agents.md

@@ -102,6 +102,13 @@ await rpc.agent.resume(runId, { toolCallId, approved })
 await rpc.agent.interrupt(runId, 'user' | 'speech' | 'timeout')
 ```
 
+`rpc.agent` is built from a factory that `@pikku/core/agent` registers when it
+is imported, so the agent runtime lands only in a deployment unit that actually
+holds an agent. A unit that declares one imports it through its own agent file
+and needs nothing extra; a unit that reaches `rpc.agent` while holding no agent
+throws `Agent runtime not available` rather than silently paying ~52 KB for a
+runtime it never uses.
+
 `context` is a string injected into the system prompt for this request only —
 use it for upfront state (current org, project, deployment) so the agent stops
 asking the user for identifiers it could have been handed.

package/skills/pikku-blueprint-to-fabric/SKILL.md

@@ -313,7 +313,7 @@ Then run the slice's scenarios. All four green — validate, codegen, `tsc`, sce
 
 Never batch. A rebuild verified only at the end gives you an undifferentiated pile of failures with no bisect point, and the whole reason for slicing is that each slice is a checkpoint you can trust.
 
-New functions with `expose: true` are versioned from the start — `pikku versions` / `pikku semver` (**pikku-meta**); you're establishing v1 contracts, not migrating them.
+New functions with `expose: true` are versioned from the start — `pikku versions` / `pikku release` (**pikku-meta**); you're establishing v1 contracts, not migrating them.
 
 ## Stage 9 — The parity report (the deliverable)
 

package/skills/pikku-build/SKILL.md

@@ -115,21 +115,17 @@ generated functions through `ref()`.
 
   A person who has to go hunting for the port assumes the app did not start.
 
-## Keep a BUILD-REPORT.md
+## Report what pikku got wrong, as it happens
 
 Whenever pikku or a skill costs you time — a command that failed on a fresh
 tree, a skill that described a flag the CLI does not have, generated code you
-had to fix by hand — add an entry to `BUILD-REPORT.md` at the repo root as it
-happens: what you ran, what you expected, what happened, and the workaround.
-Leave out secrets, tokens and customer data.
-
-At hand-over, show the file and ask the user whether to send it. Only with
-their okay, send each entry with `pikku fabric report --stdin` (JSON on stdin;
-`"kind": "product"` when pikku behaved wrongly, `"kind": "harness"` with
-`"skill"` and `"passage"` when a skill misled you). The `pikku-report` skill
-has the fields. When the CLI is not signed in to Fabric, the report is queued
-locally rather than sent: say so, and that `pikku fabric findings flush` sends
-the queue once they sign in. Do not retry or file it twice.
+had to fix by hand — file it then with `pikku fabric report --stdin`. The
+`pikku-report` skill has the fields. Leave out secrets, tokens and customer data.
+
+Findings are held until hand-over. The last thing in the hand-over, after the
+app runs (and is deployed, if they chose to), is `pikku fabric report`: if it
+lists findings and asks, ask the user — Yes, No, Always or Never — and run it
+again with `--consent <answer>`. If it says reporting is off, do not ask.
 
 ## Who you are talking to
 

package/skills/pikku-build/references/app.md

@@ -515,9 +515,11 @@ Rules that are not optional:
 - Surface errors. No empty catch, no swallowed promise. If a mutation can fail,
   render the failure inline next to the control that triggered it — not a toast.
 - An exposed function with no session and no permission is reachable by anyone
-  over `POST /rpc/:rpcName` (PKU574). Either gate it or drop `expose: true`.
+  over `POST /rpc/:rpcName` (PKU574). Either gate it, drop `expose: true`, or —
+  when public is the point — write `auth: false` on it to say so.
 - A public, signed-out read (a homepage's programme, a price list) is a
-  `pikkuSessionlessFunc`. `pikkuFunc` with `auth: false` still answers
+  `pikkuSessionlessFunc` with `auth: false` written out, which is what keeps
+  PKU574 quiet for it. `pikkuFunc` with `auth: false` still answers
   `MissingSessionError` over `/rpc` to a caller with no session.
 - Better Auth already owns the `user`, `session`, `account` and `verification`
   tables. A domain table with one of those names — a class _session_, a drop-in

package/skills/pikku-build/references/feature.md

@@ -259,14 +259,14 @@ Do not push without explicit confirmation. Do not merge.
 When pikku itself is what cost you time — a wrong generated type, a check that
 passed when it should not, a skill that misled you — file it with `pikku fabric
 report`. The `pikku-report` skill owns the ladder, the two kinds, the JSON-on-
-stdin form and the local spool; read it before filing.
+stdin form and asking the user at hand-over; read it before filing.
 
-Reporting at all is permitted here (see **Hard constraints**) and is the one
-network call a build may make. Nothing is written to the repo. Never patch pikku
+Filing is permitted here (see **Hard constraints**), and sending what was filed
+is the one network call a build may make, once the user agrees. Nothing is
+written to the repo. Never patch pikku
 itself — not `node_modules`, not a linked checkout — work around it in the app,
 report it, and let the fix happen once.
 
-
 ## Hard constraints
 
 The skill's `allowed-tools` does **not** permit:

package/skills/pikku-build/references/platform.md

@@ -167,8 +167,8 @@ bunx --bun pikku versions init
 
 The CLI suggests this on every run of a project without it. Versioning a function
 contract, then changing it, is a short milestone that shows something no
-scaffold demonstrates on its own. `pikku semver` derives the release version by
-comparing this build's surface against a deployed one.
+scaffold demonstrates on its own. `pikku release` derives the release version by
+comparing this build's surface against the last release, then ships it.
 
 ### Addons — `pikku-addon`
 

package/skills/pikku-build/references/quick.md

@@ -135,7 +135,7 @@ than they save:
   type params, never an inline return type. The schema is the type.
 - Permission checks go in the `permissions` field, never the function body. An
   exposed function with no session and no permission is reachable by anyone over
-  `POST /rpc/:rpcName` (PKU574).
+  `POST /rpc/:rpcName` (PKU574). If that is the point, write `auth: false` on it.
 - No `process.env` inside a function — use the injected `variables` / `secrets`
   services.
 - A `z.date()` **input** arrives over RPC as an ISO string, not a `Date`.

package/skills/pikku-concepts/SKILL.md

@@ -115,7 +115,7 @@ flags; the "Read" column is the skill that teaches the thing, where one does.
 | `doc`                 | The installed API surface                                               | this skill                   |
 | `meta` / `info`       | What the project declares, machine- and human-readable                  | `pikku-meta`                 |
 | `validate`            | Every check that applies — app structure, an addon's published file set | `pikku-build`, `pikku-addon` |
-| `versions` / `semver` | Contract hashes, breaking-change detection, the release semver          | `pikku-meta`                 |
+| `versions` / `release` | Contract hashes, breaking-change detection, versioned releases        | `pikku-meta`                 |
 | `audit` / `update`    | Advisories; which `@pikku/*` can move and what peers that needs         | `pikku-meta`                 |
 | `scopes` / `roles`    | Declared authorization scopes; roles from `defineSystemRole`            | `pikku-auth`                 |
 | `knowledge`           | The knowledge base — what this app is, in its users' language           | `pikku-knowledge`            |

package/skills/pikku-kysely/SKILL.md

@@ -293,7 +293,10 @@ const kysely = createNodeSqliteKysely<DB>({
 import { createSQLiteKysely } from '@pikku/kysely-sqlite'
 
 // Pikku's own tables — returns Kysely<KyselyPikkuDB>, not your DB
-const pikkuDb = createSQLiteKysely(database: SqliteDatabase | (() => Promise<SqliteDatabase>))
+const pikkuDb = createSQLiteKysely(
+  database: SqliteDatabase | (() => Promise<SqliteDatabase>),
+  { plugins: [] } // layered ahead of the always-last SerializePlugin
+)
 ```
 
 These two are not interchangeable. `createSQLiteKysely` is typed to

package/skills/pikku-meta/SKILL.md

@@ -3,8 +3,8 @@ name: pikku-meta
 description: >-
   Use to inspect or evolve a project you did not just write — `pikku meta` and `pikku info` for
   what the project declares (functions, schemas, wires, workflows, middleware, permissions) and
-  `pikku meta apply` to change it, `pikku versions` / `pikku semver` for contract hashes,
-  breaking-change detection and the semver a release should get, and `pikku audit` / `pikku
+  `pikku meta apply` to change it, `pikku versions` / `pikku release` for contract hashes,
+  breaking-change detection, the semver a release should get and shipping it, and `pikku audit` / `pikku
   update` for dependency advisories and moving Pikku forward. TRIGGER when: user asks what
   functions or routes exist, wants a function's input/output shape, wants to retag a function or
   set config on a declaration, asks about API versioning, breaking changes, what semver a release
@@ -13,7 +13,7 @@ description: >-
   Pikku concepts (use pikku-concepts).
 installGroups: [core]
 allowed-tools: Bash(yarn pikku meta *), Bash(yarn pikku info *)
-argument-hint: '[context|functions|schemas|workflows|middleware|permissions|wires|apply|versions|semver|audit|update]'
+argument-hint: '[context|functions|schemas|workflows|middleware|permissions|wires|apply|versions|release|audit|update]'
 ---
 
 # Pikku Project Metadata
@@ -26,7 +26,7 @@ and change it through the write path rather than by hand.
 | You are… | Read |
 | --- | --- |
 | Asking what exists, or setting config on a declaration | `references/meta.md` |
-| Versioning a contract, or deciding a release's semver | `references/versioning.md` |
+| Versioning a contract, or versioning and shipping a release | `references/versioning.md` |
 | Chasing a dependency advisory, or upgrading Pikku | `references/audit.md` |
 
 ## Start with `pikku meta context`
@@ -41,7 +41,7 @@ they are the same ground in two shapes.
 An input is contravariant (the caller writes it) and an output is covariant (the
 caller reads it), so the same edit is not the same event on both. Adding a
 required field breaks an input and is compatible on an output; making a field
-optional is the reverse. `pikku semver` reads the generated JSON Schemas with
+optional is the reverse. `pikku release diff` reads the generated JSON Schemas with
 that asymmetry built in, so let it decide rather than eyeballing a diff.
 
 ## What NOT to do

package/skills/pikku-meta/references/versioning.md

@@ -1,6 +1,5 @@
 # Pikku Function Versioning
 
-
 ## Before You Start
 
 ```bash
@@ -122,28 +121,86 @@ the manifest alone. Fix the contract or bump the version, then run it again.
 4. If intentional: pin the old contract as `…V1` with `version: 1`, bump the
    live function to `version: 2`, then `pikku versions update`
 
-## The `pikku semver` command
+## The `pikku release` command
 
-`versions check` and `semver` answer different questions and share no state.
+`versions check` and `release` answer different questions and share no state.
 `check` is a within-repo gate — "you changed a contract without bumping
-`version:`". `semver` is a release question — "what does this build owe the
-clients of the one already deployed?" — and needs an **external baseline**,
-which is why the answer is always relative to an environment rather than to
-the previous commit.
+`version:`". `release` is a release question — "what does this build owe the
+clients of the last release, and how do we ship it?". The baseline is
+`surface.pikku.json`, the snapshot committed by the previous release.
 
 ```bash
-npx pikku semver --against https://api.acme.com/surface.json  # vs production
-npx pikku semver --against ../other-app/.pikku                # vs a checkout
-npx pikku semver --emit --out surface.json                    # publish a baseline
-npx pikku semver --against ... --fail-on major                # CI gate
+npx pikku release init                                   # first run: snapshot + CHANGELOG.md
+npx pikku release diff                                   # vs surface.pikku.json
+npx pikku release diff --against https://api.acme.com/surface.json  # vs any baseline
+npx pikku release diff --fail-on major                   # PR gate
+npx pikku release snapshot --out surface.json            # write a snapshot
+npx pikku release prepare                                # bump package.json, write changelog + snapshot
 ```
 
 `--against` takes three things and tells them apart itself: a directory is read
 as a `.pikku` tree, an `http(s)` URL is fetched as a published snapshot, and any
-other file is read as a snapshot. `--emit` produces the snapshot; **use `--out`**
-— plain `--emit` writes to stdout _after_ the CLI banner, so a bare `> file.json`
-captures the banner too. Publish the snapshot from CI on deploy and it becomes
-the baseline everyone else compares against.
+other file is read as a snapshot. `snapshot` without `--out` writes to stdout
+_after_ the CLI banner, so a bare `> file.json` captures the banner too.
+`pikku semver` is a deprecated alias for `release diff` / `release snapshot`.
+
+### Shipping a release
+
+Work lands on the trunk branch (default `staging`); production (default `main`)
+only ever fast-forwards to a release commit. pikku works the release out and
+writes it; it never commits, tags or pushes. Who does that is your call — you
+with plain git, or a platform with its own credentials.
+
+`prepare` runs on a checkout of `origin/staging` after `pikku all`. It diffs the
+surface against `surface.pikku.json`, reads the commits production does not have
+yet, bumps `package.json`, prepends a `CHANGELOG.md` section and rewrites the
+snapshot. No commits since the last release means nothing to release. It
+refuses when `main` has commits `staging` lacks (merge `main` into `staging`
+with a merge commit first). `.pikku/release.gen.json` records the version, the
+changelog section, the trunk sha it was prepared on and the files it wrote,
+named from the repository root.
+
+Shipping is then one commit on top of that trunk sha:
+
+```bash
+npx pikku release prepare
+git add package.json CHANGELOG.md surface.pikku.json
+git commit -m "release: v0.4.0"
+git tag v0.4.0
+git push --atomic origin HEAD:staging HEAD:main v0.4.0
+```
+
+The push only fast-forwards, so if `staging` moved since prepare it is rejected
+and you prepare again.
+
+The bump comes from the surface diff alone — there is no manual override. A
+release whose surface did not move is a patch. Below 1.0 a breaking change
+is a minor, like any other surface change; from 1.0 it is a major. 1.0.0 is
+never reached by a diff: `pikku release prepare --go-live` releases it once,
+when the app is live. The changelog lists the surface changes and nothing
+else from the code; a behaviour change behind an unchanged API only shows up
+if a commit carries a `Release-Note: …` trailer, which adds a line to Notes.
+A release with neither says it holds internal changes only. Branch names are configurable in `pikku.config.json`:
+
+```json
+{
+  "release": {
+    "trunk": "staging",
+    "production": "main",
+    "branch": "release/next",
+    "remote": "origin"
+  }
+}
+```
+
+`branch` is not used by pikku itself; it is passed through in
+`release.gen.json` as the name a platform gives the prepared release commit
+while it waits to ship.
+
+Functions and wirings defined under a `scaffold/` directory or in a generated
+`*.gen.*` file are platform plumbing (auth, console, a host's injected shims)
+and are left out of the surface, so the same app diffs the same locally and in
+a platform's build.
 
 The verdict, in order:
 
@@ -179,7 +236,7 @@ the wiring level only `auth` going from absent/false to true is classified as
 breaking; every other metadata change is reported as compatible, because there
 is no general way to tell a cosmetic wiring edit from a restricting one.
 
-Output is `.pikku/changes.gen.json` (override with `--out`), so it rides the
+`release diff` writes `.pikku/changes.gen.json` (override with `--out`), so it rides the
 same meta pipeline as `audit.json`:
 
 ```json
@@ -215,7 +272,7 @@ jobs:
       - run: npm ci
       - run: npx pikku versions check
       # Refuse to ship a breaking change to production unintentionally.
-      - run: npx pikku semver --against https://api.acme.com/surface.json --fail-on major
+      - run: npx pikku release diff --fail-on major
 ```
 
 ## Complete Example

package/skills/pikku-report/SKILL.md

@@ -3,12 +3,11 @@ name: pikku-report
 description: >-
   Use when pikku itself cost you time — wrong generated types, a check that passes when it
   should not, output that is quietly wrong, a skill that misled you — or when the user asks you
-  to report a framework bug, file a finding, or look at what is queued. Owns `pikku fabric
-  report` (a finding is about pikku, not the app), the product-vs-harness kinds, the
-  workaround-first ladder, and the local findings spool. TRIGGER when: the framework fought you,
+  to report a framework bug or file a finding. Owns `pikku fabric report` (a finding is about
+  pikku, not the app), the product-vs-harness kinds, the workaround-first ladder, and asking the
+  user at hand-over whether to send what was filed. TRIGGER when: the framework fought you,
   codegen produced something broken, a skill told you to run something that does not exist, the
-  user says "report this to pikku" / "file a finding" / "check the findings queue", or a finding
-  was queued and never sent. DO NOT TRIGGER when: the bug is in the app you are building (fix it
+  user says "report this to pikku" / "file a finding", or you are handing over a build. DO NOT TRIGGER when: the bug is in the app you are building (fix it
   there), or you are tempted to patch pikku's source (never do that from an app).
 installGroups: [core]
 ---
@@ -19,9 +18,9 @@ A finding is about **pikku**, not about the app you are building. It is how the
 framework learns what cost its users time — the bug, the misleading skill, the
 silence where a check should have complained.
 
-Nothing is written to the repository. The terminal receipt shows exactly what
-left your machine, and the command is spelled `pikku fabric report` — there is
-no top-level report command.
+File each one the moment it happens. Nothing leaves the machine until the user
+says so at hand-over, and nothing is written to the repository. The command is
+spelled `pikku fabric report` — there is no top-level report command.
 
 ## Report at the moment it happens
 
@@ -62,7 +61,7 @@ baseline noise that was already failing before you started.
 - `--kind harness` — a skill misled you: it told you to run something that does
   not exist, described a flag that is spelled differently, or contradicted what
   the CLI actually did. Pass `--skill <name>` and `--passage "<the line or
-  section>"`. This is the most useful kind to file, because it is fixable
+section>"`. This is the most useful kind to file, because it is fixable
   immediately — so file it even when the cost was small.
 
 ## The command
@@ -102,24 +101,44 @@ before anything is sent:
 Add whichever of these you actually have: `error` (the error's message line,
 verbatim), `repro` (the shortest way to reach it again), `proposal`, `area`,
 `surface`, `cost` (measured if you measured it — "98s vs 20s steady" ranks;
-"slow" does not), `run` (an id shared by every finding from this build),
-`deployTarget`.
+"slow" does not), `deployTarget`.
 
 Versions, platform and package manager are read off the installed tree for you.
 Do not pass them and do not ask the user for them.
 
-## When it cannot send
+## At hand-over
 
-Reporting never fails a build. A finding that cannot be sent — logged out, or
-fabric unreachable — is held on the machine and goes out with the next report
-that succeeds, so nothing you file is lost:
+Filing holds the finding on the machine, tied to this build by a run id the CLI
+makes for the checkout. The terminal says `held until hand-over`; carry on.
 
-- `pikku fabric findings list` shows what is queued.
-- `pikku fabric findings flush` sends everything queued.
-- `pikku fabric findings clear` discards it.
+The last thing in the hand-over — after the app runs, and is deployed if they
+chose to — is:
 
-If the terminal says the finding was queued, carry on with what you were doing.
-Do not try to fix the send, and do not file the same thing again.
+```bash
+pikku fabric report
+```
+
+With no finding, it lists what this build filed. What happens next depends on
+what the user said before, which the CLI keeps on their machine:
+
+- **Always** — every finding was sent the moment you filed it. Tell the user in
+  one line.
+- **Never** — nothing was kept. Do not ask and do not mention it.
+- **Nothing saved** — show the user the titles and ask once: _"Send these to the
+  Pikku team so they can fix them?"_ — **Yes**, **No**, **Always** or
+  **Never**. Then run it again with their answer:
+
+  ```bash
+  pikku fabric report --consent yes|no|always|never
+  ```
+
+  Yes sends and No discards what is held now; Always and Never are saved and the
+  question is not asked again. If nobody answers, leave them held and say that
+  `pikku fabric report` sends them later.
+
+Findings are anonymous: no account, no project. The receipt printed when you
+filed each one is exactly what leaves the machine. A send that fails keeps what
+was not sent; do not retry or file it twice.
 
 ## Never fix pikku itself
 

package/skills/pikku-wiring/references/trigger.md

@@ -94,6 +94,60 @@ generated by the inspector, and it warns rather than throwing; the usual fix is
 the one the warning suggests — move the wiring into its own file so codegen
 picks it up.
 
+## Webhook sources
+
+When the outside world pushes to you (Stripe, GitHub, Slack), the source is an
+HTTP route, not a listener. `wireTriggerWebhookSource` declares it; triggers
+subscribe to its events as `<source>:<event>`:
+
+```ts snippet:wireTriggerWebhookSource
+
+```
+
+- The route is `POST /webhooks/<name>` unless `method`/`route` say otherwise.
+  It needs no session.
+- `events` maps each event name to a schema. An event that fails its schema is
+  logged and dropped; so is one no `wireTrigger` listens for. Both still get a
+  `200`, so the provider does not retry forever.
+- `receive(services, { body, headers, method, url, query })` gets the **raw
+  bytes** — verify the signature over those — and returns `{ events: [{ name,
+id?, data }] }`, or `{ respond: { status, body } }` for a handshake. Throwing
+  rejects the request with the error's status (`UnauthorizedError` → 401).
+  Omitted, the JSON body becomes one event dispatched to a trigger named just
+  `<source>`.
+- Every accepted event is queued on `pikku-incoming-webhooks` and run by a
+  generated worker, so the provider is answered quickly and a failing trigger is
+  retried by the queue. This needs a `queueService` and an
+  `incomingWebhookService: new IncomingWebhookService(queueService)` in your
+  singleton services. The event `id` becomes the job id.
+- With a database, use `KyselyIncomingWebhookService(queueService, db)` from
+  `@pikku/kysely` instead (and `await service.init()`). It keeps a receipt per
+  event, so a provider's redelivery of an event already accepted is dropped
+  even on queues that ignore job ids, and records each attempt and its last
+  error. Its `webhookReceipt` table comes from `pikku db generate`; `pikku dev`
+  and `pikku serve` use it when a Kysely database is configured.
+- `receive` sees singleton services without `secrets`: read the signing secret
+  in a service method, and declare it with `defineSecret`. Name it in `secret`
+  so deploy knows where `setup` should store it.
+
+`check`, `setup` and `teardown` register the route with the provider. Each gets
+`{ url, label, events, previous? }`, where `events` are only the ones some
+trigger subscribes to. The CLI runs them:
+
+```bash
+pikku webhooks status   --url https://api.example.com --labelPrefix shop:prod
+pikku webhooks setup    --url https://api.example.com --labelPrefix shop:prod
+pikku webhooks teardown --url https://api.example.com --labelPrefix shop:prod --previous state.json
+```
+
+Each prints one JSON line per source (`ok`, `missing`, `drifted`, `created`,
+`updated`, `unchanged`, `manual`, `deleted`, `absent`, `skipped`, `failed`). `setup` only
+runs where `check` does not report `ok`, and a `setup` that returns a new signing
+secret prints it with the `secret` name to store it under. In CI pass
+`--secretsOut <file>`: secrets are written there (mode 600) as
+`{ secretName: secret }` and left out of stdout. Any step can be
+`ref('<addon>:<fn>')` to use an addon's implementation.
+
 ## Usage Patterns
 
 ### Redis Pub/Sub Source
@@ -139,7 +193,6 @@ wireTriggerSource({
 })
 ```
 
-
 ## Complete Example
 
 ```typescript

package/skills/pikku-workflow/SKILL.md

@@ -159,6 +159,9 @@ export const processOrder = pikkuWorkflowFunc({
 // 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' })
 
+// Sub-workflow step — name another workflow instead of an RPC (see "Sub-workflows")
+const onboarded = await workflow.do('Onboard', 'onboardUserWorkflow', { userId })
+
 // Inline closure step — immediate execution, cached for replay
 const msg = await workflow.do('Generate', async () => `Welcome, ${data.email}!`)
 
@@ -277,9 +280,59 @@ const users = await Promise.all(
 )
 ```
 
+### Sub-workflows
+
+A step whose second argument names a **workflow** rather than an RPC starts that
+workflow as a child run and resolves to its output. There is no separate API —
+it is the same `workflow.do`, and the generated `TypedWorkflow` has an overload
+keyed on `FlattenedWorkflowMap`, so the child's input and output are type-checked
+exactly like an RPC step's.
+
+```typescript
+export const signupWorkflow = pikkuWorkflowFunc<
+  { email: string },
+  { userId: string }
+>({
+  func: async (_services, data, { workflow }) => {
+    const user = await workflow.do('Create user', 'createUser', data)
+    // runs onboardUserWorkflow as a child run; awaits its output
+    await workflow.do('Onboard', 'onboardUserWorkflow', { userId: user.id })
+    await workflow.do('Send welcome', 'sendWelcomeEmail', { userId: user.id })
+    return { userId: user.id }
+  },
+})
+```
+
+How the child runs:
+
+- **It is its own run.** It gets its own `runId`, its own steps and its own
+  history; the parent step records it as `childRunId` and the child's wire
+  carries `parentRunId`/`parentStepId`. Inspect the child's steps on the child
+  run, not the parent.
+- **Identity is inherited.** The child's wire copies the parent's
+  `pikkuUserId`, so the child runs as whoever started the parent.
+- **Inline vs queued follows the deployment.** Without a `queueService` the
+  child runs inline and the parent step returns its output directly. With one,
+  the child is queued, the parent parks on that step, and the child's
+  completion writes the parent step's result and resumes the parent.
+- **Failure propagates.** A child that fails or is cancelled fails the parent
+  step (`'Sub-workflow failed'` / `'Sub-workflow was cancelled'` when the child
+  left no message). Inline, the step's `retries` start a fresh child run per
+  attempt; queued, the child's failure lands on the parent step once and is
+  not retried — put retries on the child's own steps instead.
+
+Use a sub-workflow when the child is a real orchestration you also start on
+its own, or reuse from several parents. A child that would be a single
+`workflow.do` is a function — call the RPC directly (see the single-RPC rule
+above).
+
+To start a workflow **without waiting** for it, that is not a sub-workflow:
+have an RPC step call `rpc.startWorkflow(name, input)`, which returns
+`{ runId }` immediately, and the new run has no parent link.
+
 ### Graph workflow (DAG)
 
-`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.
+`pikkuWorkflowGraph` derives types from the RPC map — no explicit `input`/`output`. Nodes map `nodeName → Pikku function name` — or a workflow name, which runs that workflow as a sub-workflow node; `config.<node>.next` lists nodes to run after it (in parallel); `config.<node>.input: (ref) => ...` transforms input using refs to prior node outputs.
 
 ```typescript
 import { pikkuWorkflowGraph } from '#pikku/workflow/pikku-workflow-types.gen.js'