@pikku/skills 0.12.22 → 0.12.26

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.

package/skills/{pikku-deploy-azure/SKILL.md → pikku-deploy/references/azure.md}

@@ -1,57 +1,25 @@
----
-name: pikku-deploy-azure
-description: >-
-  Use when deploying a Pikku app to Azure Functions. Covers createAzureHandler for HTTP, storage
-  queue and timer triggers, plus AzInvocationLogger and PikkuAZTimerRequest. TRIGGER when: user
-  asks about Azure Functions, Azure deployment, or @pikku/azure-functions. DO NOT TRIGGER when:
-  user asks about AWS Lambda (use pikku-deploy-lambda) or Cloudflare Workers (use
-  pikku-deploy-cloudflare).
----
-
-# Pikku Azure Functions 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.
-
-`@pikku/azure-functions` provides Azure Functions runtime adapters for Pikku.
-
-## Installation
+# Azure Functions
 
 ```bash
 yarn add @pikku/azure-functions @azure/functions
 ```
 
-## API Reference
-
-Exported from `@pikku/azure-functions`:
-
-- `createAzureHandler(factories, handlerTypes)` — the entry point. Returns
-  `{ http?, queue?, timer? }` for the handler types you ask for.
-- `createAzureWorkerHandler(factories)` — `createAzureHandler(factories, ['fetch'])`.
-- `createAzureWebSocketHandler(factories)` — **a stub**: its `negotiate` always
-  answers `501 WebSocket via Azure Web PubSub not yet implemented`. Channels do
-  not work on Azure yet; do not plan a deployment around it.
-- `AzInvocationLogger` — the logger. Note the name: there is no
-  `PikkuAzFunctionsLogger`.
-- `PikkuAZTimerRequest` — `new PikkuAZTimerRequest(context, data)`, a
-  `PikkuRequest` carrying the data. The context argument is accepted and
-  ignored.
-- `AzureQueueService`, `AzureDeploymentService`.
+`createAzureHandler(factories, handlerTypes)` is the entry point, returning
+`{ http?, queue?, timer? }` for the handler types you ask for.
+`createAzureWorkerHandler(factories)` is `createAzureHandler(factories,
+['fetch'])`. `factories` is `{ createConfig, createSingletonServices,
+createPlatformServices? }`; services are built from `process.env` and cached in
+module scope across invocations of the same instance.
 
-`factories` is `{ createConfig, createSingletonServices, createPlatformServices? }`.
-Services are built from `process.env` and cached in module scope across
-invocations of the same instance.
+**Channels do not work on Azure.** `createAzureWebSocketHandler` is a stub whose
+`negotiate` always answers `501 WebSocket via Azure Web PubSub not yet
+implemented` — do not plan a deployment around it.
 
-## Usage Patterns
+Two naming traps: the logger is `AzInvocationLogger`, not
+`PikkuAzFunctionsLogger`; and `PikkuAZTimerRequest(context, data)` accepts the
+context argument and ignores it.
 
-### Registering handlers
+## Registering handlers
 
 ```typescript
 import { app } from '@azure/functions'
@@ -86,7 +54,7 @@ app.timer('scheduler', {
 Note the key names: `handlerTypes` uses **`scheduled`**, but the handler it
 returns is **`timer`**.
 
-### HTTP
+## HTTP
 
 The handler buffers the whole body, converts to a standard `Request`, and
 returns the response body as **text** — a streaming or binary response is
@@ -95,7 +63,7 @@ flattened. It takes no `RunHTTPWiringOptions`, so there is no `maxBodySize` or
 is logged to `console.error` and whatever the response already holds is
 returned.
 
-### Queue
+## Queue
 
 The queue name comes from the message's own `queueName`, falling back to
 `context.triggerMetadata.queueTrigger` and then `'unknown'` — a name that does
@@ -112,7 +80,7 @@ base64-encoded (Azure requires it), `delay` is milliseconds mapped to
 `AZURE_QUEUE_NAME_<SCREAMING_SNAKE>` when that variable exists, otherwise used
 as-is.
 
-### Timer
+## Timer
 
 The timer handler runs **every** scheduled task registered in the bundle,
 ignoring both the `Timer` argument and each task's own cron expression. Unlike
@@ -120,7 +88,7 @@ the Lambda equivalent it does not catch per-task failures, so the first task
 that throws aborts the ones after it — keep one schedule per function app, or
 guard the task bodies yourself.
 
-### Logging
+## Logging
 
 `new AzInvocationLogger(context)` forwards to the invocation context's
 `info`/`warn`/`error`/`debug`/`trace`. `setLevel()` is a **no-op**: every level

package/skills/pikku-deploy/references/cloudflare.md

@@ -0,0 +1,104 @@
+# Cloudflare Workers
+
+```bash
+yarn add @pikku/cloudflare
+```
+
+## Worker entry
+
+`@pikku/cloudflare` ships the handler factories the deploy codegen emits — use
+them rather than hand-rolling an `ExportedHandler`. Each returns a
+`WorkerEntrypoint` class that sets services up on every invocation (cached after
+the first) and adds an RPC-callable `runRpc(name, args)`:
+
+```typescript
+import { createCloudflareHandler } from '@pikku/cloudflare'
+import { createConfig, createSingletonServices } from './services.js'
+import './.pikku/pikku-bootstrap.gen.js'
+
+export default createCloudflareHandler(
+  { createConfig, createSingletonServices },
+  ['fetch', 'scheduled']
+)
+```
+
+| Factory | For |
+| --- | --- |
+| `createCloudflareHandler(factories, handlerTypes)` | combined `fetch`/`queue`/`scheduled` |
+| `createCloudflareWorkerHandler(factories)` | HTTP / agent / RPC / workflow-orchestrator units |
+| `createCloudflareCronHandler(factories)` | cron units |
+| `createCloudflareQueueHandler(factories)` | queue-consumer and workflow-step units |
+| `createCloudflareMCPHandler(factories)` | MCP units (same HTTP transport) |
+| `createCloudflareWebSocketHandler(factories)` | channel units, delegating to the DO |
+
+`factories` is `{ createConfig, createSingletonServices, createPlatformServices? }`.
+
+## Service setup — do not hand-roll this
+
+Cloudflare passes env bindings per-request, so services are built from `env`
+rather than at module load. `setupServices(env, factories)` is exported from
+`@pikku/cloudflare` and is what the factories call:
+
+```typescript
+import { setupServices } from '@pikku/cloudflare'
+
+const services = await setupServices(env, {
+  createConfig,
+  createSingletonServices,
+})
+```
+
+Beyond building `LocalVariablesService` / `LocalSecretService` and caching the
+result, it calls `setSingletonServices()` — and the core runners (`fetchData`,
+`runQueueJob`, `runScheduled`) resolve services through that global slot, _not_
+through the value you were returned. A setup function that only returns the
+services leaves every request throwing "Singleton services not initialized" as a
+CF `1101`. It also stashes the env via `setCloudflareEnv`, which
+`getCloudflareEnv()` reads for bindings.
+
+## HTTP
+
+`runFetch(request, websocketHibernationServer?, options?)`:
+
+- A `GET` with `Upgrade: websocket` is routed to the hibernation server. Without
+  one passed in it answers **426**, so a channel worker that forgets the second
+  argument fails every upgrade while plain HTTP keeps working.
+- `CF-Ray` becomes the traceId when present, so a Cloudflare trace and a Pikku
+  trace line up without extra wiring.
+- `options.exposeErrors` defaults to **`false`** — error detail is withheld from
+  responses unless you opt in.
+
+## Scheduled tasks
+
+`runScheduled(controller)` matches registered tasks against `controller.cron`
+and **returns after the first match**. Two tasks sharing one cron expression
+means only one of them ever runs — give each its own expression, or invoke
+`runScheduledTask({ name })` per task yourself.
+
+## WebSocket (Durable Objects)
+
+The ready-made DO class is exported; re-export it under the binding name and
+point the worker at it:
+
+```typescript
+export { PikkuWebSocketHibernationServer as WebSocketHibernationServer } from '@pikku/cloudflare'
+export default createCloudflareWebSocketHandler({
+  createConfig,
+  createSingletonServices,
+})
+```
+
+Subclass `CloudflareWebSocketHibernationServer` only when you need something
+`getParams()` cannot express — it is abstract with one method returning
+`{ singletonServices, createWireServices? }`. The channel store
+(`CloudflareWebsocketStore` over the DO's own storage), the event hub and the
+channel handler factory are all built by the base class; do not supply them.
+
+The router looks up the DO through the **`WEBSOCKET_HIBERNATION_SERVER`**
+binding and answers `503` naming it if the binding is missing, so declare it in
+`wrangler.toml` under exactly that name.
+
+A throw during `onConnect` closes the socket with `1008` and answers `403
+Forbidden` with a deliberately generic body — an auth denial and a genuine fault
+look identical to the client. The real reason is on the logger, so read the
+worker logs rather than the status code.

package/skills/pikku-deploy/references/express.md

@@ -0,0 +1,92 @@
+# Express
+
+```bash
+yarn add @pikku/express
+```
+
+## Standalone server
+
+```typescript
+import { PikkuExpressServer } from '@pikku/express'
+import './.pikku/pikku-bootstrap.gen.js'
+import { createConfig, createSingletonServices } from './services.js'
+
+const config = await createConfig()
+const singletonServices = await createSingletonServices(config)
+
+const appServer = new PikkuExpressServer(
+  { ...config, port: 4002, hostname: 'localhost' },
+  singletonServices.logger
+)
+appServer.enableExitOnSigInt()
+await appServer.init()
+await appServer.start()
+```
+
+The config extends `CoreConfig` with `port`, `hostname`, an optional
+`healthCheckPath`, an optional `limits` map and an optional `content`
+(`LocalContentConfig`) for static assets and file uploads. `app: Express` is
+exposed for custom middleware, and `getHttpServer()` returns the underlying
+`http.Server` — to attach a WebSocket server, say — but throws before `start()`.
+
+`enableStaticAssets()` serves `content.localFileUploadPath` under
+`content.assetUrlPrefix`, and `enableReaper()` adds a `PUT /reaper/*path` upload
+sink for local development, path-traversal checked and bounded by
+`content.sizeLimit` (default `1mb`). Both throw when `content` is unset.
+
+## Ordering, and what `init` installs for you
+
+The health check is registered in the **constructor**, so it answers before any
+middleware you add and cannot be wrapped in auth. It defaults to
+`/health-check`; override with `healthCheckPath`.
+
+Everything else is installed by `init()`: `express.json`, `express.text` (for
+`text/xml`), `express.urlencoded`, `cookie-parser`, then the Pikku middleware.
+Call `enableCors` **before** `init` if you want CORS applied to Pikku's routes.
+
+Express buffers the body before Pikku sees it, so the parser limit is the only
+place an oversized request can actually be stopped. `httpOptions.maxBodySize`
+therefore feeds those parser limits, with an explicit `config.limits` entry
+(`json` / `xml` / `urlencoded`) still winning. Everything defaults to `1mb`.
+
+`init` passes `logRoutes: true` and `loadSchemas: true` by default; your
+`httpOptions` spread over them, so you can turn either off.
+
+`stop()` throws if the server was never started. `enableExitOnSigInt()`
+installs a SIGINT handler that stops the singleton services, then the server,
+then exits 0.
+
+## Middleware (existing Express app)
+
+```bash
+yarn add @pikku/express-middleware
+```
+
+```typescript
+import express from 'express'
+import { pikkuExpressMiddleware } from '@pikku/express-middleware'
+import './.pikku/pikku-bootstrap.gen.js'
+
+const app = express()
+app.use(express.json())
+app.use(cookieParser())
+app.use(
+  pikkuExpressMiddleware({
+    logger: singletonServices.logger,
+    logRoutes: true,
+    loadSchemas: true,
+    // plus any RunHTTPWiringOptions: maxBodySize, respondWith404, coerceDataFromSchema
+  })
+)
+```
+
+Options beyond `logger` are all optional: `logRoutes` logs the wiring table once
+at startup, `loadSchemas` compiles every schema up front, and the rest are
+`RunHTTPWiringOptions` passed through per request.
+
+On your own app **you** own the parser stack — the middleware reads `req.body`,
+so a body parser and `cookie-parser` must be registered before it, and
+`maxBodySize` alone will not stop an oversized request that your parser already
+accepted. Unmatched requests fall through to `next()` (unless `respondWith404`
+is set), so Pikku's routes coexist with your existing ones; a streaming response
+is the exception and does not call `next()`.