@pikku/skills 0.12.21 → 0.12.25

package/skills/{pikku-build-app/SKILL.md → pikku-build/references/app.md}

@@ -1,17 +1,3 @@
----
-name: pikku-build-app
-description: >-
-  Build a real product on open-source Pikku using the full Fabric workflow, run locally — knowledge
-  base first, personas and roles, milestones planned then built one at a time, each proven by a
-  scenario, with a design pass. The default build mode, and the one that stays importable into
-  Fabric later. TRIGGER when: the user asked for an app to be built on Pikku and picked "App" (or
-  did not pick), a freshly scaffolded pikku project needs turning into a product, or the user says
-  "build this properly / so someone can pick it up". DO NOT TRIGGER when: the user asked for
-  something quick or throwaway (use pikku-build-quick), wants every platform surface demonstrated
-  (use pikku-build-platform), or is adding one feature to an app that already has its knowledge
-  base and milestones (use pikku-feature).
----
-
 # Build a product on open-source Pikku
 
 You have a scaffolded project with skills installed. This skill owns everything
@@ -210,7 +196,7 @@ people the user named, and the roles they imply.
 
 ```typescript
 import { definePersonas } from '#pikku/scopes/pikku-personas.gen.js'
-import { defineSystemRole } from '#pikku'
+import { defineSystemRole } from '#pikku/scopes'
 
 defineSystemRole({
   owner: {
@@ -272,7 +258,7 @@ definePersonas({
   live with them.
 - **Roles are what a permission check reads, not where it lives.** The check goes
   in the function's `permissions` field (§6), never in the body. Read the
-  `pikku-permissions` skill.
+  `pikku-auth` skill.
 
 `pikku persona list` shows who is declared and `pikku roles audit` reports roles
 the database still holds that code no longer declares — both need §0's bootstrap
@@ -365,17 +351,45 @@ Number the files (`01-…`, `02-…`) so the order is visible in the tree. Then
 **Show the user the list before building.** This is the last cheap moment to
 reorder — after §6 the migrations are numbered and the order is concrete.
 
+## 5a. The technical plan — one milestone at a time, before you build it
+
+The milestone note says what the app must DO. The **plan** says what has to
+exist for it: the tables, functions, wires, roles, scopes, screens and
+scenarios, split into passes. It is JSON, it lives beside the note, and
+`pikku knowledge plan progress` measures the finished build against it.
+
+**Read `pikku-architect` and follow it.** The plan is the denominator the
+completion check divides by, so a builder who writes their own plan can build a
+fraction, plan only that fraction, and certify itself complete. Fabric answers
+that by giving the plan its own seat; here the defence is the ORDER, and it only
+holds if you keep it: the plan is written against the note in its own turn,
+before any of the code it measures exists, and is never edited afterwards to
+match what you ended up building. An item that will not land is deferred with
+its reason — `plan defer` — not quietly rewritten. Write it before you open a
+migration:
+
+```sh
+pikku knowledge plan schema                        # the only spec there is
+pikku knowledge plan set <milestone> /tmp/plan.json
+pikku knowledge plan show <milestone> --for-build  # what you then build
+```
+
+**Plan one milestone at a time, at the moment you are about to build it** — not
+all of them here. A plan written against a note that later moves is worse than
+no plan, and everything after the current milestone is still allowed to move.
+
 ---
 
 ## PHASE 4 — Build
 
 ## 6. Implement milestones, one at a time
 
-**Per milestone** — set its note to `status: dispatched`, do the six steps,
-set it to `built`. Do not start the next one until §7 is green for this one *and
-§7a shows its functions covered*. A stack of half-milestones cannot be reviewed
-and cannot be handed over, and an uncovered function is a half-milestone whether
-or not the note says `built`.
+**Per milestone** — plan it (§5a), set its note to `status: dispatched`, do the
+six steps, close it out (§6a), set it to `built`. Do not start the next one
+until §6a passes, §7 is green for this one *and §7a shows its functions
+covered*. A stack of half-milestones cannot be reviewed and cannot be handed
+over, and an uncovered function is a half-milestone whether or not the note says
+`built`.
 
 1. **Migration.** SQL in `db/sqlite/` at the project root, numbered on from the
    ones already there. Apply with `bunx --bun pikku db migrate`, which also
@@ -475,6 +489,44 @@ it is worth writing as a browser step on §7's scenario and running
 `pikku scenario run local --spawn --run browser`: same clicks, same assertions,
 in the repo, green or red on every future run.
 
+## 6a. Close the milestone against its plan, not against your memory
+
+```sh
+pikku knowledge plan progress <milestone>
+```
+
+It reads §5a's plan and reconciles it against the generated meta under
+`.pikku/` — the function exists or it does not, the route is wired or it is not,
+the `pikkuScenario` export is there or it is not. Nothing it reports comes from
+what anyone claimed, which is the whole reason it replaced a todo list. It exits
+non-zero while anything in the first pass is missing.
+
+Three things it says, and what each one asks of you:
+
+- **MISSING** — the first pass owes it and the meta cannot see it. Either build
+  it, or, if it genuinely belongs to later work, move it out with a reason on
+  the record:
+
+  ```sh
+  pikku knowledge plan defer <milestone> function:sendReminder \
+    -r "The email service it needs is the next milestone."
+  ```
+
+  **A deferral is capped at two per plan.** Past that, the plan was wrong and the
+  milestone is two milestones — say so to the user rather than deferring again.
+  What you may never do is drop the item silently: the plan is what the next
+  person reads to know what this milestone was for.
+- **PROBLEMS** — something exists but does not do what was planned. A function
+  planned as restricted whose meta says `auth: false`; a `cascade` no migration
+  declares; a browser scenario that opens a page and asserts it is still on it.
+  These are never deferred. Fix the app.
+- **DEFERRED to a later pass** — already accounted for. Reported so it is
+  visible, never blocking.
+
+**Do not set the note to `built` while this exits non-zero**, and do not edit the
+plan to match what you built — `plan set` is the architect's seat, and a builder
+rewriting its own denominator is exactly what the split exists to stop.
+
 ## 7. Prove it — scenarios
 
 A scenario is a user journey run as one of your personas, over the real
@@ -484,7 +536,7 @@ experiences it. Three ship in `packages/functions/test/scenarios/` — keep them
 green — and every milestone's gherkin block from §5 becomes one more.
 
 ```typescript
-import { pikkuScenario } from '#pikku/workflow/pikku-workflow-types.gen.js'
+import { pikkuScenario } from '#pikku/scenarios'
 
 export const tenantReportsAFaultScenario = pikkuScenario<void, { id: string }>({
   title: 'A tenant reports a fault and the owner sees it',
@@ -685,7 +737,7 @@ cheaper to honour than to retrofit:
   that needs it
 - `references/theming.md` — authoring the theme (§8a)
 - `references/ship.md` — deploying, and the Fabric-readiness contract (§9)
-- Sibling skills: `pikku-knowledge` (§2), `pikku-permissions` (§3),
-  `pikku-scenario` (§7, §7a), `pikku-deploy-cloudflare` and `pikku-fabric` (§9)
+- Sibling skills: `pikku-knowledge` (§2), `pikku-auth` (§3),
+  `pikku-scenario` (§7, §7a), `pikku-deploy` and `pikku-fabric` (§9)
 - Project conventions written by the template: `AGENTS.md`
-- Doing less than this: `pikku-build-quick`. Doing more: `pikku-build-platform`.
+- Doing less than this: `references/quick.md``. Doing more: `references/platform.md``.

package/skills/{pikku-feature/SKILL.md → pikku-build/references/feature.md}

@@ -1,10 +1,3 @@
----
-name: pikku-feature
-description: 'Drive create-a-feature work inside a Pikku project that already exists: discover project context, work on a feature branch, implement + verify + commit, and ask the user to review via the diff. TRIGGER when: the user asks to "create a feature", "add X to my Pikku project", "wire up a new endpoint", or anything that implies turning a natural-language request into Pikku functions/wirings/migrations within a working app. DO NOT TRIGGER when: the user asks for a one-off code edit in an existing function, asks about Pikku concepts (use pikku-concepts), or is building a whole app from a fresh scaffold rather than extending one (use pikku-build-app, or pikku-build-quick / pikku-build-platform).'
-allowed-tools: Bash(yarn pikku meta *), Bash(yarn pikku all *), Bash(yarn tsc), Bash(git status *), Bash(git diff *), Bash(git switch *), Bash(git checkout *), Bash(git checkout -b *), Bash(git add *), Bash(git commit *), Bash(git log *), Bash(git branch *), Bash(yarn pikku fabric report *), Bash(npx --no pikku fabric report *)
-argument-hint: '<feature description>'
----
-
 # Pikku Create-a-Feature
 
 ## Agent Operating Procedure
@@ -137,7 +130,7 @@ in-app features don't.
   zod schema for type-safe access. Read variables with
   `services.variables.get('NAME')`. Secrets are **not available in functions** —
   read them in `services.ts` with `secrets.getSecret('NAME')` and pass the value
-  into the service the function uses. See the **pikku-config** skill for the full
+  into the service the function uses. See the **pikku-services** skill for the full
   pattern (including OAuth2 credentials). This applies even in `config.ts`.
 
 ### Conventions to copy from neighbours

package/skills/{pikku-build-app → pikku-build}/references/multi-app.md

@@ -102,7 +102,7 @@ rewritten to the pikku dev server).
   the permission check exists. The refusal scenario is the evidence.
 - **In production on two subdomains**, the session cookie needs a parent domain
   (`.example.com`) or each app gets its own login. Decide which, set it per the
-  `pikku-better-auth` skill, and record it in `knowledge/decisions/security/`.
+  `pikku-auth` skill, and record it in `knowledge/decisions/security/`.
 - **Never hardcode a host or port.** The API base resolves to same-origin `/api`.
 
 ## Building the second app's screens

package/skills/{pikku-build-platform/SKILL.md → pikku-build/references/platform.md}

@@ -1,25 +1,12 @@
----
-name: pikku-build-platform
-description: >-
-  Build an app that exercises every Pikku surface — workflows, schedules, queues, an AI agent,
-  realtime, MCP, multiple locales, contract versioning and scenario coverage — on top of the full
-  pikku-build-app workflow. For proving what the platform does, not for shipping the smallest
-  thing that works. TRIGGER when: the user picked "Platform", asked for a showcase or reference
-  app, or asked to demonstrate what Pikku can do. DO NOT TRIGGER when: the user wants a product
-  built (use pikku-build-app), something quick (use pikku-build-quick), or one specific surface
-  wired into an existing app — a single workflow, cron job or agent (use that surface's own skill,
-  e.g. pikku-workflow, pikku-schedule, pikku-agent).
----
-
 # Build a platform showcase on Pikku
 
-**This skill is a delta. `pikku-build-app` is the base — read it and follow it in
+**This skill is a delta. `references/app.md` is the base — read it and follow it in
 full.** Everything there applies: knowledge base first, personas and roles,
 milestones planned then built one at a time, scenarios, design pass, deploy
 gates, Fabric-readiness. This file adds the surfaces that turn an app into a
 demonstration of the platform, and says where each one slots into that workflow.
 
-Read `pikku-build-app` now, then come back. Do not blend the two into one plan —
+Read `references/app.md` now, then come back. Do not blend the two into one plan —
 the phases below hang off its phases by number.
 
 ## What "platform" means here
@@ -32,7 +19,7 @@ proves it.** A cron job that logs "tick" is not a schedule — it is a comment.
 Budget the extra surfaces at one milestone each. They are not free, and a
 half-wired workflow engine is worse than no workflow engine.
 
-## Choosing surfaces — during `pikku-build-app` §5 (planning)
+## Choosing surfaces — during `references/app.md` §5 (planning)
 
 When you plan milestones, each surface below becomes its own milestone note in
 `knowledge/milestones/`, ordered after the spine it depends on.
@@ -85,11 +72,11 @@ on a human or a timer and must survive a restart.
   gap in the middle? If every operation completes in one request, you do not need
   workflows and forcing one is noise.
 - **Prove it:** a scenario that starts the workflow, advances it as a second
-  persona, and asserts the end state. `pikku-workflows-client` covers driving it
+  persona, and asserts the end state. `pikku-react` covers driving it
   from the UI.
 - Three workflows ship with the template. Read them before writing yours.
 
-### Schedules — `pikku-schedule`
+### Schedules — `pikku-wiring`
 
 Recurring work: a nightly rollup, a reminder sweep, an expiry pass.
 
@@ -99,7 +86,7 @@ Recurring work: a nightly rollup, a reminder sweep, an expiry pass.
 - **Prove it:** invoke the scheduled function directly in a scenario and assert
   its effect. Do not test by waiting.
 
-### Queues — `pikku-queue`
+### Queues — `pikku-wiring`
 
 Work that must happen but not now, and may retry: email fan-out, image
 processing, third-party calls that fail.
@@ -108,7 +95,7 @@ processing, third-party calls that fail.
   fails in ways worth retrying.
 - **Prove it:** enqueue in one scenario step, assert the effect in a `then`.
 
-### An AI agent — `pikku-agent`, `pikku-ai-vercel`
+### An AI agent — `pikku-agent`
 
 The template ships agent wiring and `@ai-sdk/openai`. An agent that answers
 questions over the app's own data is the showcase; a general chatbot is not.
@@ -124,7 +111,7 @@ questions over the app's own data is the showcase; a general chatbot is not.
   matching `defineSecret`, never `process.env`, or deploy has nothing to
   provision (PKU951).
 
-### Realtime and events — `pikku-realtime`, `pikku-websocket`
+### Realtime and events — `pikku-wiring`
 
 `pikku enable events` gives a realtime channel plus an SSE stream, and the
 generated typed client.
@@ -134,20 +121,20 @@ generated typed client.
 - **Prove it:** a browser scenario is the only honest proof — assert the second
   persona's screen changed without a reload.
 
-### MCP — `pikku-mcp`
+### MCP — `pikku-wiring`
 
 Exposes functions as Model Context Protocol tools, so an outside agent can drive
 the app. Cheap once functions exist, and a genuine differentiator to show.
 
-### Triggers and webhooks — `pikku-trigger`, `pikku enable webhook`
+### Triggers and webhooks — `pikku-wiring`, `pikku enable webhook`
 
 Inbound triggers and outgoing webhook delivery. This is where `wireHTTP` is
 correct rather than a smell: a third-party caller needs a real REST shape.
 
-### Locales — `pikku-i18n`, `pikku-paraglide`
+### Locales — `pikku-i18n`
 
-`pikku-build-app` already requires every string to be a key. **Here, ship three
-locales, and make one of them RTL** (`pikku-rtl`). Two LTR locales prove the
+`references/app.md` already requires every string to be a key. **Here, ship three
+locales, and make one of them RTL** (`pikku-i18n`). Two LTR locales prove the
 plumbing; an RTL one proves the layout, and it will find real bugs — mirrored
 icons, hardcoded `marginLeft`, a nav that opens on the wrong side.
 
@@ -159,7 +146,7 @@ every added locale is cloned from, so three locales is `locales: ["en", …]` an
 never a repointed base. Shipping locales is also not a reason for anything in
 the code to stop being English: identifiers are English in every project, and
 the language of `description`/`title`/`template` is `metaLocale` in
-`pikku.config.json`. See `pikku-build-app` §1a.
+`pikku.config.json`. See `references/app.md` §1a.
 
 ### Emails — `pikku-emails`
 
@@ -168,7 +155,7 @@ localised like every other string. The base workflow asks for one; **a showcase
 sends three** — a welcome, a transactional confirmation, and one sent from a
 schedule or queue rather than a request, because that is the interesting path.
 
-### Contract versioning — `pikku-versioning`
+### Contract versioning — `pikku-meta`
 
 ```sh
 bunx --bun pikku versions init
@@ -186,7 +173,7 @@ the domain has a piece that genuinely belongs to no single app.
 
 ## Coverage — where the bar is higher than the base workflow
 
-`pikku-build-app` §7a already has the mechanics and the per-milestone habit:
+`references/app.md` §7a already has the mechanics and the per-milestone habit:
 run the server instrumented, run the scenarios against it, read
 `coverage/scenario-coverage.json`, and triage every gap as a missing scenario, a
 function that should not exist, or a documented deferral. Do all of that here.
@@ -205,7 +192,7 @@ Two things change in a showcase:
 
 ## The full gate
 
-Everything in `pikku-build-app` §9, plus the checks a showcase should be able to
+Everything in `references/app.md` §9, plus the checks a showcase should be able to
 survive:
 
 ```sh
@@ -227,7 +214,7 @@ bunx --bun pikku scenario run local --spawn --run browser
 
 ## Deploy
 
-`pikku-build-app` §9 covers the open-source paths (`--provider standalone`,
+`references/app.md` §9 covers the open-source paths (`--provider standalone`,
 `cloudflare`, `aws`). One thing specific to this mode: **the extra surfaces are
 extra deploy units.** Workflow workers, queue workers, schedules and the events
 channel each appear in `pikku deploy plan` as their own entries. Read the plan
@@ -236,10 +223,8 @@ built.
 
 ## Reference
 
-- Base workflow: `pikku-build-app` — read it first, follow it in full
-- Per-surface skills: `pikku-workflow`, `pikku-schedule`,
-  `pikku-queue`, `pikku-agent`, `pikku-ai-vercel`, `pikku-realtime`,
-  `pikku-websocket`, `pikku-mcp`, `pikku-trigger`, `pikku-i18n`, `pikku-rtl`,
-  `pikku-emails`, `pikku-versioning`, `pikku-addon`, `pikku-security`,
-  `pikku-audit`
+- Base workflow: `references/app.md` — read it first, follow it in full
+- Per-surface skills: `pikku-workflow`, `pikku-wiring`, `pikku-agent`,
+  `pikku-i18n`, `pikku-emails`,
+  `pikku-meta`, `pikku-addon`, `pikku-auth`, `pikku-services`
 - Every feature, end to end: https://pikkufabric.com/llm-all-features.txt

package/skills/{pikku-template-clone/SKILL.md → pikku-build/references/post-clone.md}

@@ -1,9 +1,3 @@
----
-name: pikku-template-clone
-description: 'Standard cleanup to run right after a Pikku template is cloned or scaffolded into a new project. TRIGGER when: a Pikku template was just cloned/scaffolded (via `npm create pikku`, `git clone <template>`, or the user says "I cloned the kanban template / starter / template"), or the working tree still looks like an untouched template (template README, placeholder `@project/*` name in package.json). DO NOT TRIGGER when: working in an established project mid-feature, or editing the template repo itself.'
-allowed-tools: Bash(git status *), Bash(git add *), Bash(git commit *), Bash(git rm *), Bash(git mv *), Bash(git log *)
----
-
 # Pikku Template Post-Clone Cleanup
 
 ## Agent Operating Procedure

package/skills/{pikku-build-quick/SKILL.md → pikku-build/references/quick.md}

@@ -1,19 +1,3 @@
----
-name: pikku-build-quick
-description: >-
-  Build a working app on open-source Pikku fast — scaffold to running screens, skipping the
-  knowledge base and the milestone ladder. For spikes, throwaway demos, and ideas nobody has
-  committed to yet. TRIGGER when: the user asked for something quick, a prototype, a spike, a
-  demo of an idea, or "just get it running", or picked "Quick" from the build-mode question. DO
-  NOT TRIGGER when: the request is an unqualified "build me an X on Pikku" with no signal of
-  speed or throwaway-ness — App is the default and small or toy-sounding apps do not change that
-  (use pikku-build-app); the user wants a real product someone else will pick up (use
-  pikku-build-app); the user wants a demo of Pikku itself — one that shows off surfaces like
-  workflows, queues, realtime or i18n (use pikku-build-platform); or the user is adding a feature
-  to an app that already exists rather than building one from a fresh scaffold (use
-  pikku-feature).
----
-
 # Build an app on Pikku, fast
 
 You have a scaffolded project with skills installed. Get it to working, seeded,
@@ -58,7 +42,7 @@ Identifiers are English in every project, whatever the product's market;
 `template`, which the Console renders) stays `en` unless the user already told
 you otherwise. If the request says the app's UI is not English, that is the
 message catalogue only: add the locale and set `defaultLocale`, and leave
-`baseLocale` at `en`. `pikku-build-app` §1a has the three axes in full; getting
+`baseLocale` at `en`. `references/app.md` §1a has the three axes in full; getting
 them confused is how a project ends up unable to add a second language.
 
 ## 2. Personas — 60 seconds, not optional
@@ -85,7 +69,7 @@ named:
 
 ```typescript
 import { definePersonas } from '#pikku/scopes/pikku-personas.gen.js'
-import { defineSystemRole } from '#pikku'
+import { defineSystemRole } from '#pikku/scopes'
 
 defineSystemRole({
   owner: { displayName: 'Owner', description: 'Sees only their own rows', scopes: [] },
@@ -191,7 +175,7 @@ taller than the viewport. It is the most likely width your demo gets opened at.
 If you have five spare minutes, `npx impeccable install` (Node 22.18+) scores
 each screen against interaction heuristics and names what is wrong. Feed it
 screenshots, not source. It will polish the default look; it will not give the
-app a look — that is `pikku-build-app` §8a.
+app a look — that is `references/app.md` §8a.
 
 ## 5. One smoke scenario
 
@@ -199,7 +183,7 @@ Not the full ladder — one journey, end to end, as a real persona, so the app h
 at least one thing that stays true.
 
 ```typescript
-import { pikkuScenario } from '#pikku/workflow/pikku-workflow-types.gen.js'
+import { pikkuScenario } from '#pikku/scenarios'
 
 export const ownerCreatesAndSeesItScenario = pikkuScenario<void, { id: string }>({
   title: 'An owner creates a thing and sees it',
@@ -235,7 +219,7 @@ that this is a quick build — no knowledge base, no milestones, no design pass,
 access control clicked-through rather than proven.
 
 **Upgrading to a real build is additive, not a rewrite.** If they want it, switch
-to `pikku-build-app` and do this, in order:
+to `references/app.md` and do this, in order:
 
 1. Write `knowledge/` for what already exists — `entities/` for what you built,
    `decisions/` for what you chose silently, `questions/` for what you guessed
@@ -244,7 +228,7 @@ to `pikku-build-app` and do this, in order:
    its gherkin block.
 3. Write the refusal scenarios — the ones proving one persona cannot reach
    another's rows. This is the gap that matters most.
-4. Then pick up `pikku-build-app` at its §4 (apps) or §5 (milestones) for
+4. Then pick up `references/app.md` at its §4 (apps) or §5 (milestones) for
    anything new.
 
 Nothing built here has to be thrown away to do that — which is the whole reason

package/skills/{pikku-build-app → pikku-build}/references/ship.md

@@ -16,7 +16,7 @@ bunx --bun pikku deploy apply --provider standalone --runtime bun
 bundles the project into a single unit and emits either a `bundle.js` you run
 with Node, or a self-contained executable compiled with `bun build --compile`.
 `cloudflare` (the default) and `aws` are the other providers — read the
-`pikku-deploy-cloudflare` skill before using it, as it ships the handler
+`pikku-deploy` skill before using it, as it ships the handler
 factories the deploy codegen expects, and hand-rolling an `ExportedHandler` is
 how a worker deploy fails at runtime instead of at build.
 
@@ -81,6 +81,12 @@ Everything above is open source. This is the contract that keeps
   serves imports as a person with no way in.
 - **`knowledge/` passes `validate`, with every milestone at `built`.** This is
   the part Fabric itself reads and continues from.
+- **Every `built` milestone passes `pikku knowledge plan progress`.** A note that
+  says `built` is a claim; the plan reconciled against the generated meta is the
+  check. Anything the first pass still owes is either built now or deferred with
+  its reason on the record; anything the check calls a problem — something that
+  exists and does not do what was planned — is fixed, whatever pass it came from,
+  because deferring it defers a hole rather than the work.
 - **Every milestone has a passing scenario**, including its refusals.
 - **Permissions live in the `permissions` field**, not in function bodies and not
   in the frontends. A check hidden in a component does not survive a new client.

package/skills/pikku-concepts/SKILL.md

@@ -74,6 +74,71 @@ which is what decides whether a thrown error becomes a 409 or a 500.
 `pikku doc` needs `@pikku/cli` 0.12.115 or newer. On an older pin, fall back to the door's
 skill and `pikku meta --json`, and do not guess at names the doc would have given you.
 
+## The CLI commands
+
+`pikku doc` is the API surface — the `#pikku/*` exports. It does **not** list
+commands, so this table is where they exist. `pikku <command> --help` has the
+flags; the "Read" column is the skill that teaches the thing, where one does.
+
+**Generating**
+
+| Command                                    | What it does                                         | Read                          |
+| ------------------------------------------ | ---------------------------------------------------- | ----------------------------- |
+| `all`                                      | Everything: types, schemas, wirings, clients         | this skill                    |
+| `bootstrap`                                | Type files only (the setup phase)                    | this skill                    |
+| `schemas`                                  | JSON Schemas for function input/output types         | this skill                    |
+| `fetch` / `websocket` / `rpc` / `realtime` | One client each, when you do not want `all`          | `pikku-wiring`, `pikku-react` |
+| `react-query` / `tanstack-start`           | React Query hooks; the TanStack Start `makeApi` shim | `pikku-react`                 |
+| `queue-service`                            | The queue service wrapper                            | `pikku-wiring`                |
+| `openapi`                                  | An OpenAPI spec from the HTTP routes                 | —                             |
+| `nextjs`                                   | Next.js backend and HTTP wrappers                    | `pikku-deploy`                |
+| `new`                                      | Scaffold a function or wiring                        | `pikku-wiring`                |
+| `enable`                                   | Turn a Pikku feature on                              | `pikku-build`                 |
+| `import`                                   | Import workflows from another system                 | `pikku-n8n-import`            |
+
+**Running**
+
+| Command                      | What it does                                                                   | Read                                    |
+| ---------------------------- | ------------------------------------------------------------------------------ | --------------------------------------- |
+| `dev`                        | Local dev server, all services wired, watch + HMR                              | `pikku-build`                           |
+| `serve`                      | Bundled bun/node runner — no watch, no codegen                                 | `pikku-deploy`                          |
+| `watch`                      | Regenerate on file change, without a server                                    | —                                       |
+| `scenario list\|run`         | Scenarios as e2e tests and health checks                                       | `pikku-scenario`                        |
+| `persona run`                | A declared persona as a model-driven virtual user against a stage              | `pikku-scenario`, persona-run reference |
+| `persona list\|sync\|secret` | Who is declared; what an environment will provision; minting their credentials | `pikku-scenario`, persona-run reference |
+| `db`                         | Local development database                                                     | `pikku-kysely`                          |
+
+**Inspecting and evolving**
+
+| Command               | What it does                                                            | Read                         |
+| --------------------- | ----------------------------------------------------------------------- | ---------------------------- |
+| `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`                 |
+| `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`            |
+| `emails`              | Email template generation                                               | `pikku-emails`               |
+
+**Shipping, and the CLI itself**
+
+| Command                       | What it does                                                                                                                                   | Read           |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
+| `deploy`                      | Deploy to cloud infrastructure                                                                                                                 | `pikku-deploy` |
+| `fabric`                      | PikkuFabric: login, link, deploy, domains, secrets, logs                                                                                       | `pikku-fabric` |
+| `binary`                      | Compile an entrypoint to a native binary (`bun build --compile`)                                                                               | —              |
+| `dist`                        | Copy what `tsc` cannot emit — `.gen.json` meta, hand-authored `.d.ts` — into the build output. Run it after `tsc`, as a package's build script | —              |
+| `login` / `logout` / `whoami` | The CLI's session against a pikku server                                                                                                       | —              |
+| `skills`                      | Install these skills into an agent (Claude Code, opencode, pi)                                                                                 | —              |
+
+`-c/--config`, `--log-level`, `--json` and the filter flags are **global
+options**, not commands — they attach to the generating commands above.
+
+A dash means no skill covers it beyond this line. `--help` is then the whole of
+it — which is a reason to read `--help` rather than to assume the command does
+what its name suggests.
+
 ## Core Mental Model
 
 ```text
@@ -101,7 +166,7 @@ The function never imports Express, never reads `req.body`, never touches `ws.se
 
 ## Concept Mapping: Generic Backend → Pikku
 
-Controllers/routes → `pikkuFunc`; auth/sessions → `pikku-security`, a separate install; authorization checks → `pikku-permissions`; request interception → `pikku-middleware`; DI → `pikku-services`; transports (HTTP/WS/queue/cron) → their `wire*` + skill. For the full Generic Backend → Pikku mapping table (with side-by-side code examples), read `references/concept-mapping.md`.
+Controllers/routes → `pikkuFunc`; auth/sessions and authorization checks → `pikku-auth`, a separate install; request interception → `pikku-middleware`; DI → `pikku-services`; transports (HTTP/WS/queue/cron) → their `wire*` + skill. For the full Generic Backend → Pikku mapping table (with side-by-side code examples), read `references/concept-mapping.md`.
 
 ## Functions
 
@@ -143,7 +208,7 @@ pikkuFunc({
   // "What Language You Write In".
   title?: string,           // Human-readable name
   description?: string,     // What the function does
-  version?: number,         // Contract version (see pikku-versioning)
+  version?: number,         // Contract version (see pikku-meta)
   override?: string,        // Logical name override, so several exports share a versioned base
   tags?: string[],          // For grouping and middleware targeting
 
@@ -153,13 +218,13 @@ pikkuFunc({
   errors?: Array<typeof PikkuError>,  // Errors this function may throw
 
   // Reachability
-  expose?: boolean,         // Allow external RPC calls (see pikku-rpc)
+  expose?: boolean,         // Allow external RPC calls (see pikku-wiring)
   remote?: boolean,         // Allow remote RPC calls
-  mcp?: boolean,            // Expose as MCP tool (see pikku-mcp)
+  mcp?: boolean,            // Expose as MCP tool (see pikku-wiring)
   readonly?: boolean,       // Declares the function performs no writes
   deploy?: 'serverless' | 'server' | 'auto',
 
-  // Authorization — see pikku-permissions
+  // Authorization — see pikku-auth
   auth?: boolean,           // Override default auth requirement
   scopes?: ScopeId[],       // AND-ed, checked before permissions; session required
   permissions?: PermissionGroup,  // OR-ed pool
@@ -247,6 +312,8 @@ export const lifecycle = pikkuServerLifecycle<SingletonServices>({
 
 Export exactly one `pikkuServerLifecycle` from anywhere in `srcDirectories` — the inspector finds it by the wrapper call. Every hook is optional and receives the already-created singleton services. See pikku-services for the ordering and the `afterStop` caveat.
 
+**Only `pikku dev` and `pikku serve` invoke these hooks.** No deploy runtime does, so anything a Workers or serverless stage needs done cannot live here — put it on the request path that needs it, guarded by a cheap check.
+
 **2. Bootstrap it yourself (required for a specific runtime)**
 
 Express, Fastify, uWS, Lambda, Cloudflare and Next.js need their own entrypoint, because Pikku is embedded in a server you own:
@@ -315,7 +382,7 @@ src/
 ├── services.ts          # Service factories (see pikku-services)
 ├── lifecycle.ts         # Server lifecycle hooks (pikku dev/serve only)
 ├── middleware.ts         # Middleware definitions (see pikku-middleware)
-├── permissions.ts       # Permission definitions (see pikku-permissions)
+├── permissions.ts       # Permission definitions (see pikku-auth)
 └── .pikku/              # Generated (gitignored)
     ├── function/        # #pikku/function
     ├── http/            # #pikku/http
@@ -333,7 +400,7 @@ bottom.
 | Axis            | What it covers                                                                                                                                                    | What decides it                                                                                             |
 | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
 | **Identifiers** | Function, component, type, variable and file names. Database tables and columns. Branch names and commit messages.                                                | Nothing. **Always English.** There is no setting.                                                           |
-| **Meta**        | The prose authored _inside_ the code: `description` on functions and steps, `name`/`title` on features and scenarios, step `template`, role/persona descriptions. | `metaLocale` in `pikku.config.json`. Defaults to `en`.                                                          |
+| **Meta**        | The prose authored _inside_ the code: `description` on functions and steps, `name`/`title` on features and scenarios, step `template`, role/persona descriptions. | `metaLocale` in `pikku.config.json`. Defaults to `en`.                                                      |
 | **Product UI**  | Every string the app shows a user.                                                                                                                                | `messages/<locale>.json`, with `active.json`'s `defaultLocale` choosing what a first-time visitor opens in. |
 
 ### Identifiers are English, and nothing changes that
@@ -413,7 +480,7 @@ language, it is telling you about axis three and nothing else.
 
 ## Environment Variables
 
-Never use `process.env` inside Pikku functions. Use the `variables` service (see `pikku-config`):
+Never use `process.env` inside Pikku functions. Use the `variables` service (see `pikku-services`):
 
 ```typescript
 const apiKey = services.variables.get('API_KEY')

package/skills/pikku-concepts/references/concept-mapping.md

@@ -7,19 +7,19 @@ Authoritative mapping table plus side-by-side code examples showing how common b
 | Generic Backend Concept                 | Pikku Equivalent                                                | Skill             |
 | --------------------------------------- | --------------------------------------------------------------- | ----------------- |
 | **Controller / Route Handler**          | `pikkuFunc` / `pikkuSessionlessFunc`                            | `pikku-concepts`  |
-| **Route definition** (`GET /users/:id`) | `wireHTTP({ route, method, func })`                             | `pikku-http`      |
-| **Middleware** (Express/Koa-style)      | `pikkuMiddleware`                                               | `pikku-security`  |
-| **Auth Guard / Auth Middleware**        | `authBearer()` / `authCookie()` / `authApiKey()`                | `pikku-security`  |
-| **Authorization / Permissions**         | `pikkuPermission` / `pikkuAuth`                                 | `pikku-security`  |
+| **Route definition** (`GET /users/:id`) | `wireHTTP({ route, method, func })`                             | `pikku-wiring`      |
+| **Middleware** (Express/Koa-style)      | `pikkuMiddleware`                                               | `pikku-middleware` |
+| **Auth Guard / Auth Middleware**        | `authBearer()` / `authCookie()` / `authApiKey()`                | `pikku-auth`  |
+| **Authorization / Permissions**         | `pikkuPermission` / `pikkuAuth`                                 | `pikku-auth`  |
 | **DTO / Request Validation**            | Standard Schema (Zod, Valibot, ArkType)                         | `pikku-concepts`  |
 | **Dependency Injection**                | `pikkuServices` (singleton) + `pikkuWireServices` (per-request) | `pikku-services`  |
-| **WebSocket handlers**                  | `wireChannel`                                                   | `pikku-websocket` |
-| **Job Queue workers**                   | `wireQueueWorker`                                               | `pikku-queue`     |
-| **Cron / Scheduled tasks**              | `wireScheduler`                                                 | `pikku-schedule`      |
+| **WebSocket handlers**                  | `wireChannel`                                                   | `pikku-wiring` |
+| **Job Queue workers**                   | `wireQueueWorker`                                               | `pikku-wiring`     |
+| **Cron / Scheduled tasks**              | `wireScheduler`                                                 | `pikku-wiring`      |
 | **Module / Feature grouping**           | Tags + wiring files                                             | `pikku-concepts`  |
 | **Error handling**                      | Throw typed errors (`NotFoundError`, `ForbiddenError`)          | `pikku-concepts`  |
 | **Type-safe API client**                | `npx pikku all` generates clients                               | `pikku-concepts`  |
-| **Secrets / Config**                    | `defineSecret`, `defineVariable`, `services.variables`          | `pikku-config`    |
+| **Secrets / Config**                    | `defineSecret`, `defineVariable`, `services.variables`          | `pikku-services`    |
 
 ## Route Handler / Controller → pikkuFunc