@pikku/skills 0.12.38 → 0.12.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.38",
+  "version": "0.12.40",
   "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-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/multi-app.md

@@ -63,86 +63,61 @@ Worth a scenario each, because they are two different claims: that a mechanic ca
 *see* the invoices nav item, and that their call to an invoices RPC is *refused*. The
 second is the one that catches a `permissions` field nobody wired.
 
-## The clone
+## The second app
 
 ```bash
-cp -R apps/app apps/admin
-rm -rf apps/admin/node_modules apps/admin/src/paraglide
+pikku new app admin --serves staff --personas manager,mechanic
 ```
 
-`src/paraglide` is compiled from `messages/` by the Vite plugin on first run;
-copying it forward ships one app's compiled strings inside another.
-
-Then, in order:
-
-### 1. `apps/admin/package.json`
-
-- `name` → `@project/admin`
-- `dev` and `preview` ports → `7105`. Every frontend needs its own, or the second
-  one fails to bind and the dev runner looks like it hung.
-- the `--tsBuildInfoFile` path inside the **`tsc` script** → `admin-tsc.tsbuildinfo`.
-  In this template it is a CLI flag on that script (`tsc --noEmit --incremental
-  --tsBuildInfoFile node_modules/.cache/app-tsc.tsbuildinfo`), not a
-  `compilerOptions` entry — `tsconfig.json` needs no change. Left alone, the two
-  apps fight over one incremental cache and you get type errors that vanish on a
-  clean build: an hour of debugging for a one-word edit.
-
-### 2. `pikkufabric.config.json`
-
-This file is the source of truth for what apps exist, and it is read whether or
-not you ever deploy to Fabric.
-
-```json
-{
-  "projectId": "__PROJECT_ID__",
-  "frontends": {
-    "app": {
-      "cwd": "apps/app", "primary": true, "deploy": true, "kind": "ssr",
-      "dev": { "command": ["bun", "run", "dev"], "port": 7104, "healthPath": "/" },
-      "serves": "tenant",
-      "personas": ["visitor", "chidi"]
-    },
-    "admin": {
-      "cwd": "apps/admin", "primary": false, "deploy": true, "kind": "ssr",
-      "dev": { "command": ["bun", "run", "dev"], "port": 7105, "healthPath": "/" },
-      "serves": "owner",
-      "personas": ["amina", "bilal"]
-    }
-  }
-}
-```
-
-Two things to fix while you are in here, not just add:
-
-- **The shipped `app` entry may say `["yarn", "dev"]`** while the rest of the
-  project is driven with bun. Correct it. A frontend that starts under a package
-  manager the project does not use is a failure that only appears on someone
-  else's machine.
-- **`serves` and `personas` name real personas.** Every persona should appear
-  under exactly one frontend. A persona listed nowhere is a person with no way
-  in, and that is a design bug worth seeing now rather than at review.
-
-### 3. The dev runner
-
-`dev.mjs`, under the project's scripts directory, spawns `@project/app` **by
-name** and will silently never start your second app — the frontend simply is not
-there, with no error to explain it.
-
-Make it read the `frontends` map and spawn one child per entry, rather than
-adding a second hardcoded line. Two sources of truth for "which apps exist" is
-the drift this whole file is trying to avoid.
-
-### 4. `pikku.config.json` → `environments`
-
-`local.appUrl` points at one app. Add an environment per frontend (`local`,
-`local-admin`) so the browser scenario pass can drive either one. A browser
-scenario run against the wrong `appUrl` fails on a missing element and reads like
-a UI bug rather than a config one.
-
-### 5. Re-run `bun install`
-
-`apps/*` is already globbed in the root workspaces, so this just links the new
-one.
+One command does every step this section used to list by hand: it fetches
+`pikkujs/starter-template`'s `apps/app`, re-points its `package.json` at the
+new name, its own dev/preview port and its own `--tsBuildInfoFile`, stamps
+`app: '<slug>'` onto each named persona in `definePersonas({…})`, adds the
+`frontends` entry, and re-runs `bun install`.
+
+**It scaffolds from the starter template, not from the app you already have.**
+Copying the working app drags its screens, routes and nav into an audience that
+never asked for them, and the first hour in the new app goes on deleting
+someone else's product.
+
+`--template <source>` scaffolds from something else — any giget source, or a
+path inside the repo for an offline or vendored copy. `--install false` skips
+the install when you are batching several.
+
+**The `--tsBuildInfoFile` edit is the one that used to bite.** Two apps sharing
+one incremental cache produce type errors that vanish on a clean build: an hour
+of debugging for a one-word edit. It is handled now, but it is why you should
+not copy by hand.
+
+### What it refuses, and why that is the valuable part
+
+The scaffolding is five file edits. Getting the audience wrong is a whole
+second app nobody needed, so the command will not create one when:
+
+- **`--serves` names a surface.** `dashboard`, `portal`, `admin`, `console`,
+  `ui` and friends say nothing — every frontend is an app. Name the people in
+  their own word: staff, customer, supplier, patient.
+- **An existing app already serves that audience.** People sharing an audience
+  share ONE app and differ by nav and permitted actions. A new app is for a
+  group the first app is not for.
+- **A named persona already signs into another app.** A person signs into one
+  app; move them out first if they really belong here.
+- **The slug is what the plan calls an app that already exists.** The plan's
+  FIRST app is the one the project starts with — only the apps after it get
+  created.
+- **A persona is not in `definePersonas({…})`.** The app is built around who
+  signs into it, so it is not created for people who do not exist yet.
+
+It also repairs its own half-states: a run that died between writing the
+directory and writing the config entry leaves one without the other, and
+neither survives alone, so the next run clears the remains and carries on
+rather than sending you in to do the surgery by hand.
+
+### What it does NOT do
+
+It stops after `bun install`. Serving the new app — a reverse proxy, a
+supervisor, a dev runner, a deploy target — belongs to whatever is hosting it.
+On a plain checkout, `bun --filter @project/<slug> dev` is enough.
 
 ## Sessions across two origins
 

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-knowledge/SKILL.md

@@ -3,16 +3,15 @@ name: pikku-knowledge
 description: >-
   Use when writing, reading, reorganising or validating a project's knowledge/ directory — the
   notes that say what the app is, in the language its users use. Covers the Open Knowledge Format
-  note (path-as-identity markdown, YAML frontmatter, only `type` required), the sections of the
-  app-project profile (slices, entities, decisions, questions, wishlist) and the one question each
-  answers, slice status/entities/gherkin rules, the `resource:` URI scheme tying a note to the
-  code it is about, the shapes that are NOT a knowledge base, and the `pikku knowledge
-  validate|index` commands. TRIGGER when: user asks to write down a decision, requirement, entity
-  or open question; asks what the app does or is; asks about knowledge/, notes, slices,
-  an index.md, or a diagram, callout or decision block; or hands over a product
-  brief to record. DO NOT TRIGGER when: user asks what
-  functions, routes, tables or permissions exist (that is `pikku meta` / `pikku info`, never a
-  note), or to write a scenario test (use pikku-scenario).
+  note (path-as-identity markdown, YAML frontmatter, only `type` required), the app-project
+  profile's sections (milestones, entities, decisions, questions, wishlist) and what each answers,
+  milestone status/entities/gherkin rules, the `resource:` URI scheme tying a note to its code,
+  what is NOT a knowledge base, and `pikku knowledge validate|index`. TRIGGER when: user asks to
+  write down a decision, requirement, entity or open question; asks what the app does or is; asks
+  about knowledge/, notes, milestones, an index.md, or a diagram, callout or decision block; or
+  hands over a product brief to record. DO NOT TRIGGER when: user asks what functions, routes,
+  tables or permissions exist (that is `pikku meta` / `pikku info`, never a note), or to write a
+  scenario test (use pikku-scenario).
 installGroups: [core]
 agent:
   tools: read, write, edit, bash, grep
@@ -76,7 +75,7 @@ Frontmatter fields:
 
 | Field         | Meaning                                                                                                                 |
 | ------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `type`        | **The only required field.** `slice` — or `milestone`, when the project's own `knowledge/index.md` names the section that way; `validate` accepts both, so follow the scaffold rather than this list. Then `entity`, `decision`, `note`, `overview`. Lowercase — gates compare it literally. |
+| `type`        | **The only required field.** One of `milestone`, `entity`, `decision`, `note`, `overview`. Lowercase — every gate compares it literally, and `milestone` is the exact string `readMilestones` filters on, so a near-miss is a note no command can see. |
 | `title`       | What to call the note in a listing. Falls back to the first heading, then the filename.                                 |
 | `description` | One line, used as the note's subtitle in a section index.                                                               |
 | `resource`    | Comma-separated `<kind>:<id>` URIs — the code this note is about. See below.                                            |
@@ -92,9 +91,9 @@ Plain markdown links between notes — `[revocation](../decisions/revocation-end
 ```
 knowledge/
   index.md                                  # type: overview — the map
-  slices/
+  milestones/
     index.md
-    01-the-daily-entry.md                   # type: slice
+    01-the-daily-entry.md                   # type: milestone
   entities/
     index.md
     entry.md                                # type: entity
@@ -116,7 +115,7 @@ Each section answers exactly one question, which is what lets a reader find a no
 
 | Section               | The question it answers                                            |
 | --------------------- | ------------------------------------------------------------------ |
-| `slices/`             | What is one buildable piece of this app, and what proves it works? |
+| `milestones/`         | What is one buildable piece of this app, and what proves it works? |
 | `entities/`           | What is this thing, in the words users use for it?                 |
 | `decisions/`          | What was chosen, and what does that rule out?                      |
 | `decisions/security/` | Who may do what?                                                   |
@@ -125,13 +124,13 @@ Each section answers exactly one question, which is what lets a reader find a no
 
 **Create a section the turn you have a note for it** — never a scaffold of empty directories, and never a section without its own `index.md`. A section index says in one line what belongs in it; that sentence is the reason the file exists, so `pikku knowledge index` writes only the note listing and leaves your prose alone.
 
-## Slices
+## Milestones
 
-A slice is the one note type that is a piece of _work_ rather than a fact, so it alone carries state and size:
+A milestone is the one note type that is a piece of _work_ rather than a fact, so it alone carries state and size. It lives in `knowledge/milestones/` and nowhere else: `readMilestones` matches on that directory literally, so the same note under another section is invisible to every gate and command below.
 
 ````markdown
 ---
-type: slice
+type: milestone
 title: The daily entry
 description: An owner writes one entry per day, and sees it on the day.
 status: proposed
@@ -151,9 +150,9 @@ And writing again replaces it rather than adding a second
 ```
 ````
 
-- **`status`** is `designing` → `proposed` → `dispatched` → `built`. Nothing else. Every gate compares it literally. `designing` sits BEFORE `proposed`: the slice is written down but must not be built yet, because whoever is being shown its looks has not picked one. Only `proposed` is dispatchable, so the two cannot be one status without a slice being built out from under the person still choosing.
+- **`status`** is `proposed` → `dispatched` → `built`. Nothing else — `MILESTONE_STATUSES` is those three, and every gate compares them literally, so an invented status fails `validate` rather than degrading. Only `proposed` is dispatchable. A profile may add one of its own ahead of `proposed` for work that is written down but must not be built yet; that is the profile's to define and validate, not core's.
 - **`statusAt:` and `attempts:` are bookkeeping, not content — never hand-edit them.** A loop driving this base writes both. `statusAt:` is stamped by whatever moved the status, and is what makes "how long has this been building?" answerable; the file's mtime is not the transition time, because a note is edited after dispatch for all sorts of reasons. `attempts:` is `seat@hash` entries recording which seat has already tried to move this note forward, against the content it was trying to move — it is the loop's only brake, and clearing it by hand hands back a budget that exists to stop a note nothing can satisfy being rewritten forever. Rewriting the note's real content refunds that budget on its own, which is the point: an answer that changes the note is what unsticks it.
-- **`entities`** lists what the slice touches, **at most three**. Past three it is not one buildable piece — split it.
+- **`entities`** lists what the milestone touches, **at most three**. Past three it is not one buildable piece — split it.
 - **The scenario is a fenced `gherkin` block, in the third person.** `Given 'owner' has no entry` — never `Given I have no entry`. A quoted word _means a persona_, which is what lets a reader (and a test) tell who is acting. First person hides that, so it is rejected. The console draws the keywords as a column and each quoted persona as a chip, so a first-person scenario is visibly a block with no personas in it.
 
 ## Showing it
@@ -231,7 +230,7 @@ These are all things that exist somewhere better, so a note is always the copy t
 | Do not write                        | Because it lives in                                        |
 | ----------------------------------- | ---------------------------------------------------------- |
 | a `personas/` section               | `definePersonas()` in the project's own code               |
-| a `scenarios/` section              | the gherkin block inside the slice it belongs to           |
+| a `scenarios/` section              | the gherkin block inside the milestone it belongs to       |
 | a `permissions/` section            | a decision note under `decisions/security/`                |
 | a list of tables, columns or routes | `pikku meta` — the generated schema _is_ the schema        |
 | a changelog                         | `CHANGELOG.md` at the repo root                            |
@@ -250,7 +249,7 @@ pikku knowledge index           # refresh every index.md
 pikku knowledge index --check   # report stale indexes without writing (CI gate)
 ```
 
-`validate` reports: notes with no `type`, a missing `knowledge/index.md`, a section with no `index.md`, notes flat at the root, sections that duplicate what the project already declares, slices with a bad or missing `status`, slices over three entities, slices with no gherkin block or a first-person one, `decision` fences that state no `chosen:` or rule nothing out, and every `resource:` that no longer resolves. Errors fail the command; warnings do not.
+`validate` reports: notes with no `type`, a missing `knowledge/index.md`, a section with no `index.md`, notes flat at the root, sections that duplicate what the project already declares, milestones with a bad or missing `status`, milestones over three entities, milestones with no gherkin block or a first-person one, `decision` fences that state no `chosen:` or rule nothing out, and every `resource:` that no longer resolves. Errors fail the command; warnings do not.
 
 `index` rewrites only the block between `<!-- pikku:knowledge-index -->` markers, creating a scaffolded `index.md` for a section that has none. It is idempotent — running it twice changes nothing.
 
@@ -312,4 +311,4 @@ The exception, and it is narrow: bookkeeping the loop owns. `statusAt:` and `att
 
 OKF permits frontmatter fields a reader does not know, and the parser ignores them rather than failing. That is the extension point: a tool layered on Pikku can add its own sections and fields on top of everything above without forking the format.
 
-Fabric is the one that exists. It adds `decisions/design/` — rules about how the app looks and behaves — and a `design:` field on a slice pointing at the design options it was built from. Both are Fabric's to validate; `pikku knowledge validate` passes them through untouched. Everything else in this skill is the same in both.
+Fabric is the one that exists. It adds `decisions/design/` — rules about how the app looks and behaves — a `screens/` section, and a `design:` field on a milestone pointing at the design options it was built from. Both are Fabric's to validate; `pikku knowledge validate` passes them through untouched. Everything else in this skill is the same in both.

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-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'