@pikku/skills 0.12.21 → 0.12.25

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()`.

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

@@ -1,31 +1,11 @@
----
-name: pikku-deploy-fastify
-description: >-
-  Use when deploying a Pikku app with Fastify. Covers PikkuFastifyServer standalone and
-  pikkuFastifyPlugin for existing Fastify apps. TRIGGER when: code imports @pikku/fastify or
-  @pikku/fastify-plugin, user mentions Fastify deployment, or start.ts creates a
-  PikkuFastifyServer. DO NOT TRIGGER when: just defining functions/wirings without
-  Fastify-specific code.
----
-
-# Pikku Fastify 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.
-
-## Standalone Server
+# Fastify
 
 ```bash
 yarn add @pikku/fastify
 ```
 
+## Standalone server
+
 ```typescript
 import { PikkuFastifyServer } from '@pikku/fastify'
 import './.pikku/pikku-bootstrap.gen.js'
@@ -43,16 +23,12 @@ await appServer.init()
 await appServer.start()
 ```
 
-**Constructor:** `new PikkuFastifyServer(config, logger)`
-
-**Config extends CoreConfig with:** `port`, `hostname`, `healthCheckPath?`
-
-**Methods:** `init(httpOptions?: RunHTTPWiringOptions)`, `start()`, `stop()`, `enableExitOnSigInt()`
-
-**Property:** `app: FastifyInstance` — Direct access to Fastify instance.
+The config extends `CoreConfig` with `port`, `hostname` and an optional
+`healthCheckPath`. `app: FastifyInstance` is exposed for direct access.
 
-`enableCors` exists on the class but **throws `Method not implemented.`** — unlike
-the Express server. Register `@fastify/cors` on `app` yourself before `init()`.
+`enableCors` exists on the class but **throws `Method not implemented.`** —
+unlike the Express server. Register `@fastify/cors` on `app` yourself before
+`init()`.
 
 Unlike the Express server, the health check is registered by `init()`, not the
 constructor, so nothing answers before `init` runs. `init` also passes

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

@@ -1,30 +1,10 @@
----
-name: pikku-deploy-lambda
-description: >-
-  Use when deploying a Pikku app to AWS Lambda. Covers HTTP handlers, scheduled tasks, SQS queue
-  workers, WebSocket via API Gateway, and cold start caching. TRIGGER when: code imports
-  @pikku/lambda, user mentions Lambda/serverless/AWS deployment, or handler files export
-  Lambda-typed functions. DO NOT TRIGGER when: just defining functions/wirings without
-  Lambda-specific code.
----
-
-# Pikku AWS Lambda 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.
+# AWS Lambda
 
 ```bash
 yarn add @pikku/lambda
 ```
 
-## Cold Start Pattern
+## Cold start pattern
 
 Cache singleton services across Lambda invocations:
 
@@ -53,7 +33,7 @@ named exports (`handler`, `queue`, `scheduled`, or `connect`/`disconnect`/
 `default`) that `serverless.yml` references. Hand-written handlers are for cases
 the codegen does not cover.
 
-## HTTP Handler
+## HTTP handler
 
 Pick the entry point that matches the API Gateway payload version — they take
 different event types and are not interchangeable:
@@ -91,7 +71,7 @@ carried.
 Neither takes `RunHTTPWiringOptions` — there is no `maxBodySize` or
 `respondWith404` knob here; API Gateway's own payload limit is the bound.
 
-## Scheduled Tasks
+## Scheduled tasks
 
 ```typescript
 import type { ScheduledHandler } from 'aws-lambda'
@@ -113,7 +93,7 @@ Reach for `runScheduledTask({ name })` from `@pikku/core/scheduler` directly
 only when one Lambda genuinely bundles several tasks that must fire on separate
 schedules.
 
-## SQS Queue Worker
+## SQS queue worker
 
 ```typescript
 import type { SQSHandler } from 'aws-lambda'
@@ -181,8 +161,7 @@ is a separate invocation, so nothing survives in memory between `$connect` and
 `LambdaEventHubService` handles cross-connection messaging and takes
 `(logger, event, channelStore, eventHubStore)` — the `event` is needed to derive
 the API Gateway Management endpoint, so it is constructed per invocation, not
-once at cold start. It also needs an `EventHubStore` alongside the channel
-store.
+once at cold start. It also needs an `EventHubStore` alongside the channel store.
 
 Two behaviours to design around: **binary payloads throw** (`Binary data is not
 supported on serverless lambdas`), and any `PostToConnection` failure removes

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

@@ -1,29 +1,10 @@
----
-name: pikku-deploy-nextjs
-description: >-
-  Use when deploying a Pikku app with Next.js. Covers API route handlers, server-side data
-  fetching, and RPC calls from Server Components. TRIGGER when: code imports @pikku/next, user
-  mentions Next.js integration, or app/api route files use pikkuAPIRequest. DO NOT TRIGGER when:
-  just defining functions/wirings without Next.js-specific code.
----
-
-# Pikku Next.js 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.
+# Next.js
 
 ```bash
 yarn add @pikku/next
 ```
 
-## API Route Handler
+## API route handler
 
 The CLI generates a typed wrapper. Use it in a catch-all route:
 
@@ -49,7 +30,7 @@ choose. It also passes no `RunHTTPWiringOptions`: to set `maxBodySize` or
 `respondWith404` you need your own handler over `new PikkuNextJS(...)` calling
 `apiRequest(req, options)`.
 
-## Server-Side Data Fetching
+## Server-side data fetching
 
 Use the generated `pikku()` helper in Server Components or Server Actions:
 
@@ -69,12 +50,9 @@ const config = await staticGet('/config')
 const result = await rpc('calculateTax', { amount: 100, region: 'US' })
 ```
 
-**Dynamic vs Static:**
-
-- `get`, `post`, `patch`, `del`, `rpc` — read `next/headers` cookies and headers,
-  so they force the component dynamic
-- `staticGet`, `staticPost`, `staticRPC` — no request context, safe for
-  precompile/ISR
+`get`, `post`, `patch`, `del` and `rpc` read `next/headers` cookies and headers,
+so they force the component dynamic. `staticGet`, `staticPost` and `staticRPC`
+have no request context and are safe for precompile/ISR.
 
 The static variants pass `skipUserSession: true`, so a wiring that expects a
 session sees none. That is the real difference — not just where they can run.
@@ -85,7 +63,7 @@ Both paths run with `bubbleErrors: true`, so a failing wiring **throws** in your
 Server Component rather than resolving to an error status. Wrap the call, or let
 the Next.js error boundary take it.
 
-## How It Works
+## How it works
 
 `PikkuNextJS` lazy-initializes on first request:
 
@@ -95,8 +73,6 @@ import { PikkuNextJS } from '@pikku/next'
 const pikku = new PikkuNextJS(createConfig, createSingletonServices)
 ```
 
-**Constructor:** `new PikkuNextJS(createConfig | undefined, createSingletonServices)`
-
 Both arguments are positional and `createConfig` is only optional in the sense
 that passing `undefined` substitutes an empty config —
 `createSingletonServices` is required.
@@ -113,8 +89,8 @@ route definitions.
 - **`PikkuNextJSWorkerRPC({ fetcher })`** — same surface as `PikkuNextJS`, but
   every call is dispatched through a `Fetcher` (a Cloudflare service binding, a
   local HTTP client, a fabric dispatcher) instead of loading function code
-  in-process. Use it to keep functions out of the SSR bundle. A non-2xx
-  response throws with the status and body text.
+  in-process. Use it to keep functions out of the SSR bundle. A non-2xx response
+  throws with the status and body text.
 - **`toNextJsAuthHandler(auth)`** — wraps a better-auth instance or handler
   function for an auth route. The three-argument form
   `(pikkuAuthFactory, createConfig, createSingletonServices)` resolves a Pikku