@pikku/skills 0.12.22 → 0.12.25

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

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

@@ -0,0 +1,72 @@
+# uWebSockets.js
+
+Highest-throughput option among Pikku's runtimes. Handles both HTTP and
+WebSocket automatically.
+
+```bash
+yarn add @pikku/uws
+```
+
+```typescript
+import { PikkuUWSServer } from '@pikku/uws'
+import './.pikku/pikku-bootstrap.gen.js'
+import { createConfig, createSingletonServices } from './services.js'
+
+const config = await createConfig()
+const singletonServices = await createSingletonServices(config)
+
+const appServer = new PikkuUWSServer(
+  { ...config, hostname: 'localhost', port: 4002 },
+  singletonServices.logger
+)
+appServer.enableExitOnSigInt()
+await appServer.init()
+await appServer.start()
+```
+
+The config extends `CoreConfig` with `port`, `hostname` and an optional
+`healthCheckPath`. `app: uWS.App` is exposed for direct access.
+
+## What the server does and does not give you
+
+`init()` registers three things in order: the health check (`healthCheckPath`,
+default `/health-check`), a catch-all `app.any('/*')` HTTP handler, and a
+catch-all `app.ws('/*')` websocket handler. Nothing is registered by the
+constructor, so nothing answers before `init` runs.
+
+**There is no `enableCors`, no static assets and no `content` support** — unlike
+the Express server. The class is explicitly a prototyping convenience; for
+anything that needs extra handlers, use `@pikku/uws-handler` directly and treat
+`pikku-uws-server.ts` as the template (that is what its own JSDoc says).
+
+`httpOptions` reaches the HTTP handler only. The websocket handler is
+constructed with a fixed `{ logger, logRoutes: true }`, so per-request options
+do not apply to the upgrade path. `loadSchemas` is also never passed by the
+server, so schemas compile lazily on first use rather than at startup — pass
+`loadSchemas: true` in `httpOptions` if you want the startup cost paid up front.
+
+`stop()` closes the listen socket and then waits a fixed 2 seconds for
+connections to drain. Called before `start()`, it throws a bare **string**, not
+an `Error`, so `catch (e) { e.message }` reads `undefined`.
+
+## Body limits
+
+uWS hands over raw chunks with no limit of its own, so the handler counts the
+bytes itself. A request over `maxBodySize` (default `DEFAULT_MAX_BODY_SIZE`) is
+answered `413` with a `PayloadTooLargeError` body, and the chunks are dropped
+rather than concatenated — an oversized request never accumulates in memory. A
+`content-length` header that already exceeds the limit short-circuits before any
+data arrives.
+
+## Handlers directly (own uWS app)
+
+```typescript
+import { pikkuHTTPHandler, pikkuWebsocketHandler } from '@pikku/uws-handler'
+
+app.any('/*', pikkuHTTPHandler({ logger, logRoutes: true, loadSchemas: true }))
+app.ws('/*', pikkuWebsocketHandler({ logger, logRoutes: true }))
+```
+
+Both take `{ logger, logRoutes?, loadSchemas? } & RunHTTPWiringOptions`.
+
+For a WebSocket-only server on the `ws` library instead, see `ws.md`.

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

@@ -0,0 +1,75 @@
+# ws (WebSocket only)
+
+`@pikku/ws` connects Pikku's channel system to a Node.js WebSocket server built
+on the [ws](https://github.com/websockets/ws) library. Use it for a
+WebSocket-only server; for HTTP and WebSocket on one port see `uws.md`, and when
+the WebSocket server shares a port with an existing HTTP app see `express.md` or
+`fastify.md`.
+
+```bash
+yarn add @pikku/ws ws
+```
+
+The package exports one function, `pikkuWebsocketHandler` — there is no server
+class. You own the `http.Server` and the `WebSocketServer`; the handler attaches
+the upgrade and message plumbing to them.
+
+```typescript
+import { DEFAULT_WS_MAX_PAYLOAD, pikkuWebsocketHandler } from '@pikku/ws'
+import { stopSingletonServices } from '@pikku/core'
+import { Server } from 'http'
+import { WebSocketServer } from 'ws'
+
+import './.pikku/pikku-bootstrap.gen.js'
+import { createConfig, createSingletonServices } from './services.js'
+
+const config = await createConfig()
+const singletonServices = await createSingletonServices(config)
+
+const server = new Server()
+const wss = new WebSocketServer({
+  noServer: true,
+  maxPayload: DEFAULT_WS_MAX_PAYLOAD,
+})
+
+pikkuWebsocketHandler({
+  server,
+  wss,
+  logger: singletonServices.logger,
+  logRoutes: true, // print the wired channels at startup
+  loadSchemas: true, // compile input schemas up front
+})
+
+server.listen(4002, 'localhost')
+
+process.on('SIGINT', async () => {
+  await stopSingletonServices()
+  wss.close()
+  server.close()
+  process.exit(0)
+})
+```
+
+## `noServer: true` is required, not stylistic
+
+The handler listens for the HTTP server's own `upgrade` event, opens the channel
+— running Pikku's middleware chain, auth and CORS against the upgrade request
+first — and only then calls `wss.handleUpgrade`. A `WebSocketServer` bound to the
+server directly would take the socket before any of that ran.
+
+An upgrade the channel rejects gets the socket destroyed, and an auth failure is
+written as a real HTTP response on the raw socket rather than a silent drop.
+
+## Services and the event hub
+
+Services come from the bootstrap import and the global singleton registry, which
+is why nothing is passed in. The event hub is taken from
+`singletonServices.eventHub` when it is a `LocalEventHubService`, and a local one
+is created otherwise — so a single-process app gets pub/sub for free, while a
+multi-instance deployment must register a distributed hub.
+
+The options type also extends `RunHTTPWiringOptions`, so per-request settings
+such as `respondWith404`, `coerceDataFromSchema` and `bubbleErrors` are accepted
+here too.
+
+On shutdown, call `stopSingletonServices()` then close `wss` and `server`.