@pikku/skills 0.12.22 → 0.12.25

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
@@ -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
 
@@ -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
@@ -317,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
@@ -415,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
 

package/skills/pikku-deploy/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: pikku-deploy
+description: >-
+  Use when deploying a Pikku app to a runtime — Express, Fastify, uWebSockets.js, the `ws` library,
+  Next.js, AWS Lambda, Cloudflare Workers or Azure Functions. Covers the bootstrap every runtime
+  shares, choosing between them, and the behaviour that differs: which accept
+  `RunHTTPWiringOptions`, how each one runs scheduled tasks, and where CORS and health checks live.
+  TRIGGER when: writing or debugging `start.ts` / a worker entry / a Lambda handler, code imports
+  `@pikku/express`, `@pikku/fastify`, `@pikku/uws`, `@pikku/ws`, `@pikku/next`, `@pikku/lambda`,
+  `@pikku/cloudflare` or `@pikku/azure-functions`, or the user asks how to serve, host or deploy a
+  Pikku app. DO NOT TRIGGER when: defining functions or wirings with no runtime-specific code.
+installGroups: [core]
+---
+
+# Pikku Deployment
+
+## Agent Operating Procedure
+
+Use this skill as an execution checklist, not reference material.
+
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
+3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
+4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
+5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
+
+Signatures and option keys come from `pikku doc` — run `pikku doc --ai` for the
+installed surface. This skill is the part the compiler cannot tell you: which
+runtime to pick, and what each one does differently once you have.
+
+## Pick a runtime
+
+Two families, and the difference decides how you write the entry file.
+
+**Long-running servers** own a process. Services are built once at startup and
+live in module scope for the life of the server.
+
+| Runtime | Package | Reach for it when |
+| --- | --- | --- |
+| Express | `@pikku/express` | An existing Express app, or you want static assets and upload handling |
+| Fastify | `@pikku/fastify` | An existing Fastify app, or you want its stricter defaults |
+| uWebSockets.js | `@pikku/uws` | Highest throughput, HTTP and WebSocket on one port |
+| ws | `@pikku/ws` | WebSocket only, attached to an `http.Server` you own |
+
+**Per-invocation runtimes** are handed a request and torn down. Services are
+cached in module scope across warm invocations, and the deploy codegen writes
+that caching for you.
+
+| Runtime | Package | Reach for it when |
+| --- | --- | --- |
+| AWS Lambda | `@pikku/lambda` | API Gateway, EventBridge, SQS |
+| Cloudflare Workers | `@pikku/cloudflare` | Edge, Durable Objects for channels |
+| Azure Functions | `@pikku/azure-functions` | Azure hosting — note channels are not implemented |
+| Next.js | `@pikku/next` | Pikku behind Next routes, or RPC from Server Components |
+
+Then read the reference for the one you picked: `references/express.md`,
+`references/fastify.md`, `references/uws.md`, `references/ws.md`,
+`references/nextjs.md`, `references/lambda.md`, `references/cloudflare.md`,
+`references/azure.md`.
+
+## The bootstrap every runtime shares
+
+Importing the generated bootstrap registers your wirings; nothing routes without
+it. `createConfig` and `createSingletonServices` come from your own
+`services.ts`.
+
+```typescript
+import './.pikku/pikku-bootstrap.gen.js'
+import { createConfig, createSingletonServices } from './services.js'
+
+const config = await createConfig()
+const singletonServices = await createSingletonServices(config)
+```
+
+A long-running server takes it from there. A per-invocation runtime wraps the
+same two calls in a memoised factory, because the module may be reused across
+invocations — every `@pikku/*` serverless package ships those factories, and
+hand-written handlers are for the cases the deploy codegen does not cover.
+
+## What differs, and where it bites
+
+### `RunHTTPWiringOptions` is not accepted everywhere
+
+`maxBodySize`, `respondWith404`, `coerceDataFromSchema` and `bubbleErrors` reach
+the request only on the runtimes that thread them through.
+
+| Runtime | Accepts options | Where an oversized body is actually stopped |
+| --- | --- | --- |
+| Express | `init(httpOptions)` | The `express.json` parser limit, fed by `maxBodySize` |
+| Fastify | `init(httpOptions)` | Fastify's own `bodyLimit`, set from `maxBodySize` |
+| uWS | HTTP handler only | The handler counts bytes itself and answers `413` |
+| ws | Yes, on the handler | `maxPayload` on the `WebSocketServer` |
+| Next.js | Only via your own `PikkuNextJS` handler | Next's own limits |
+| Lambda | **No** | API Gateway's payload limit |
+| Cloudflare | Partially — `runFetch(request, hibernation, options)` | The platform's limit |
+| Azure | **No** | Azure's request limits |
+
+On Fastify, leaving `maxBodySize` unset keeps Fastify's stricter 1MB default
+rather than loosening it to Pikku's 10MB fallback. On uWS the chunks are dropped
+rather than concatenated, so an oversized request never accumulates in memory.
+
+### Scheduled tasks run differently on all three serverless runtimes
+
+Same `wireScheduler` declaration, three behaviours. This is the one most likely
+to produce a silent production bug.
+
+- **Cloudflare** matches `controller.cron` and **returns after the first match**.
+  Two tasks sharing a cron expression means only one ever runs.
+- **Lambda** runs **every** task in the bundle, ignores the event, and logs
+  rather than rethrows a failure — one bad task cannot stop the others.
+- **Azure** runs **every** task in the bundle, ignores both the timer argument
+  and each task's own cron, and does **not** catch per-task failures — the first
+  throw aborts the rest.
+
+Where a runtime runs everything in the bundle, the deployment unit is what
+decides which tasks fire, not the schedule you wrote. Reach for
+`runScheduledTask({ name })` when one deployment genuinely bundles several tasks
+that must fire separately.
+
+### CORS and health checks are not uniform
+
+- **Express** registers the health check in the **constructor**, so it answers
+  before any middleware and cannot be wrapped in auth. `enableCors` must be
+  called before `init()`.
+- **Fastify** registers it in `init()`, so nothing answers before that runs. Its
+  `enableCors` exists but **throws `Method not implemented.`** — register
+  `@fastify/cors` yourself.
+- **uWS** registers it in `init()` and has **no** `enableCors`, no static assets
+  and no `content` support at all.
+- Serverless runtimes have neither; the platform in front of them owns both.
+  On Lambda, only `runFetchV2` echoes the request `Origin`, so v1 preflights
+  fail in the browser unless API Gateway or CloudFront adds the header.
+
+### Channels need a shared store off a single process
+
+A long-running server can hold channel state in memory. Every per-invocation
+runtime cannot: `$connect` and `$default` are separate invocations, so
+`channelStore` must be a real shared store (`PgChannelStore` and friends).
+Cloudflare instead keeps state in a Durable Object, and **Azure has no channel
+support** — `createAzureWebSocketHandler` is a stub that answers `501`.
+
+## What NOT to do
+
+- Do not hand-roll Cloudflare's `setupServices`. It calls
+  `setSingletonServices()`, and the core runners resolve through that global
+  slot rather than the value you were returned — a setup that only returns
+  services leaves every request throwing "Singleton services not initialized" as
+  a CF `1101`.
+- Do not discard what a Lambda WebSocket handler returns.
+  `connectWebsocket` returns a complete `APIGatewayProxyResult`; answering a
+  hardcoded `200` instead accepts every connection, including the ones your
+  channel's auth rejected.
+- Do not bind a `WebSocketServer` to the HTTP server on `ws` or uWS.
+  `noServer: true` is required, not stylistic — the handler performs the upgrade
+  itself so middleware and auth run against the upgrade request first.
+- Do not assume a runtime rethrows. Express, Azure and Lambda's `runFetch` each
+  swallow or flatten errors differently; the reference for your runtime says
+  which.