@pikku/skills 0.12.4 → 0.12.8

package/skills/pikku-deploy-azure/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: pikku-deploy-azure
 description: >-
-  Use when deploying a Pikku app to Azure Functions. Covers PikkuAzFunctionsLogger and
-  PikkuAzTimerRequest for Azure Functions runtime. 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).
+  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
@@ -29,43 +30,97 @@ yarn add @pikku/azure-functions @azure/functions
 
 ## API Reference
 
-### `PikkuAzFunctionsLogger`
-
-Logger implementation that integrates with Azure Functions' built-in logging context.
-
-### `PikkuAzTimerRequest`
-
-Timer trigger request handler for running Pikku scheduled functions as Azure Timer Triggers.
+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`.
+
+`factories` is `{ createConfig, createSingletonServices, createPlatformServices? }`.
+Services are built from `process.env` and cached in module scope across
+invocations of the same instance.
 
 ## Usage Patterns
 
-### HTTP Function
+### Registering handlers
 
 ```typescript
 import { app } from '@azure/functions'
-import { PikkuAzFunctionsLogger } from '@pikku/azure-functions'
+import { createAzureHandler } from '@pikku/azure-functions'
+import { createConfig, createSingletonServices } from './services.js'
+import './.pikku/pikku-bootstrap.gen.js'
+
+const handlers = createAzureHandler(
+  { createConfig, createSingletonServices },
+  ['fetch', 'queue', 'scheduled']
+)
 
 app.http('api', {
-  methods: ['GET', 'POST', 'PUT', 'DELETE'],
+  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
   route: '{*path}',
-  handler: async (request, context) => {
-    const logger = new PikkuAzFunctionsLogger(context)
-    // Wire Pikku HTTP runner with Azure request/response
-  },
+  handler: handlers.http as any,
 })
-```
 
-### Timer Trigger
-
-```typescript
-import { app } from '@azure/functions'
-import { PikkuAzTimerRequest } from '@pikku/azure-functions'
+app.storageQueue('queue', {
+  queueName: 'my-queue',
+  connection: 'AzureWebJobsStorage',
+  handler: handlers.queue as any,
+})
 
 app.timer('scheduler', {
   schedule: '0 */5 * * * *',
-  handler: async (timer, context) => {
-    const request = new PikkuAzTimerRequest(timer)
-    // Process scheduled Pikku functions
-  },
+  handler: handlers.timer as any,
 })
 ```
+
+Note the key names: `handlerTypes` uses **`scheduled`**, but the handler it
+returns is **`timer`**.
+
+### 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
+flattened. It takes no `RunHTTPWiringOptions`, so there is no `maxBodySize` or
+`respondWith404` here; Azure's own request limits are the bound. A thrown error
+is logged to `console.error` and whatever the response already holds is
+returned.
+
+### Queue
+
+The queue name comes from the message's own `queueName`, falling back to
+`context.triggerMetadata.queueTrigger` and then `'unknown'` — a name that does
+not match a wired queue means the job has no handler. `attemptsMade` is read
+from `dequeueCount`, and `waitForCompletion` throws: Azure Storage Queues are
+fire-and-forget. A failing job throws out of the handler, so retries and the
+poison queue are governed by `host.json`, not by Pikku.
+
+Producer side, `AzureQueueService(connectionString?)` falls back to
+`AzureWebJobsStorage` and throws at construction if neither is set. Messages are
+base64-encoded (Azure requires it), `delay` is milliseconds mapped to
+`visibilityTimeout` in whole seconds capped at 7 days, `supportsResults` is
+`false` and `getJob()` always throws. The queue name is remapped through
+`AZURE_QUEUE_NAME_<SCREAMING_SNAKE>` when that variable exists, otherwise used
+as-is.
+
+### 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
+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
+
+`new AzInvocationLogger(context)` forwards to the invocation context's
+`info`/`warn`/`error`/`debug`/`trace`. `setLevel()` is a **no-op**: every level
+is emitted and filtering has to be done in Azure's own logging configuration.

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

@@ -26,57 +26,99 @@ 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 { runFetch, runScheduled } from '@pikku/cloudflare'
-import { setupServices } from './setup-services.js'
+import { createCloudflareHandler } from '@pikku/cloudflare'
+import { createConfig, createSingletonServices } from './services.js'
 import './.pikku/pikku-bootstrap.gen.js'
 
-export default {
-  async scheduled(controller, env) {
-    await setupServices(env)
-    await runScheduled(controller)
-  },
-
-  async fetch(request, env): Promise<Response> {
-    await setupServices(env)
-    return await runFetch(request as unknown as Request)
-  },
-} satisfies ExportedHandler<Record<string, string>>
+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
 
-Cloudflare passes env variables per-request — wrap them with Pikku services:
+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
-// setup-services.ts
-import { LocalVariablesService, LocalSecretService } from '@pikku/core/services'
-import { createConfig, createSingletonServices } from './services.js'
+import { setupServices } from '@pikku/cloudflare'
 
-export const setupServices = async (
-  env: Record<string, string | undefined>
-) => {
-  const localVariables = new LocalVariablesService(env)
-  const config = await createConfig(localVariables)
-  const localSecrets = new LocalSecretService(localVariables)
-  return await createSingletonServices(config, {
-    variables: localVariables,
-    secrets: localSecrets,
-  })
-}
+const services = await setupServices(env, {
+  createConfig,
+  createSingletonServices,
+})
 ```
 
+**Do not hand-roll this.** 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
-import { CloudflareWebSocketHibernationServer } from '@pikku/cloudflare'
-
-export class WebSocketHibernationServer extends CloudflareWebSocketHibernationServer {
-  protected async getParams() {
-    const singletonServices = await setupServices(this.env)
-    return { singletonServices }
-  }
-}
+export { PikkuWebSocketHibernationServer as WebSocketHibernationServer } from '@pikku/cloudflare'
+export default createCloudflareWebSocketHandler({
+  createConfig,
+  createSingletonServices,
+})
 ```
 
-Register the Durable Object in `wrangler.toml` and export from the worker entry.
+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-express/SKILL.md

@@ -55,15 +55,37 @@ await appServer.start()
 
 **Methods:**
 
-- `init(httpOptions?): Promise<void>` — Register middleware and routes
+- `init(httpOptions?: RunHTTPWiringOptions): Promise<void>` — installs the body parsers, the cookie parser and the Pikku middleware
 - `start(): Promise<void>` — Start listening
-- `stop(): Promise<void>` — Graceful shutdown
-- `enableExitOnSigInt(): Promise<void>` — SIGINT handler
+- `stop(): Promise<void>` — Graceful shutdown; throws if the server was never started
+- `enableExitOnSigInt(): Promise<void>` — SIGINT handler: stops the singleton services, then the server, then exits 0
 - `enableCors(options): void` — Enable CORS
-- `enableStaticAssets(): void` — Serve static files (requires `content` config)
+- `enableStaticAssets(): void` — serve `content.localFileUploadPath` under `content.assetUrlPrefix`
+- `enableReaper(): void` — a `PUT /reaper/*path` upload sink for local development, path-traversal checked and bounded by `content.sizeLimit` (default `1mb`)
+- `getHttpServer(): Server` — the underlying `http.Server`, e.g. to attach a WebSocket server; throws before `start()`
+
+`enableStaticAssets` and `enableReaper` both throw when `content` is unset.
 
 **Property:** `app: Express` — Direct access to Express instance for custom middleware.
 
+### 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.
+
 ## Middleware (existing Express app)
 
 ```bash
@@ -76,11 +98,25 @@ 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

@@ -47,10 +47,19 @@ await appServer.start()
 
 **Config extends CoreConfig with:** `port`, `hostname`, `healthCheckPath?`
 
-**Methods:** `init(httpOptions?)`, `start()`, `stop()`, `enableExitOnSigInt()`
+**Methods:** `init(httpOptions?: RunHTTPWiringOptions)`, `start()`, `stop()`, `enableExitOnSigInt()`
 
 **Property:** `app: FastifyInstance` — Direct access to Fastify instance.
 
+`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
+`logRoutes: true` and `loadSchemas: true`, which your `httpOptions` can override.
+The Fastify instance is constructed with no options; reach for the plugin package
+if you need `Fastify({ … })` of your own.
+
 ## Plugin (existing Fastify app)
 
 ```bash
@@ -68,6 +77,18 @@ app.register(pikkuFastifyPlugin, {
     logger: singletonServices.logger,
     logRoutes: true,
     loadSchemas: true,
+    // plus any RunHTTPWiringOptions: maxBodySize, respondWith404, …
   },
 })
 ```
+
+Every option other than `logger` is optional, and the rest of the `pikku` object
+is `RunHTTPWiringOptions` passed straight through.
+
+The plugin registers a catch-all `fastify.all('/*')`, so mount it on a
+[Fastify prefix](https://fastify.dev/docs/latest/Reference/Plugins/) if the app
+has routes of its own to keep.
+
+Fastify buffers the body itself, so its `bodyLimit` is where an oversized request
+is stopped. `maxBodySize` sets it — and left unset, Fastify's stricter 1MB default
+stands rather than being loosened to Pikku's 10MB fallback.

package/skills/pikku-deploy-lambda/SKILL.md

@@ -44,30 +44,75 @@ export const coldStart = async () => {
 }
 ```
 
+If the deploy codegen generated your handlers, this caching is already done for
+you by the factories in `@pikku/lambda` — `createLambdaHandler(factories,
+handlerTypes)`, `createLambdaWorkerHandler(factories)` and
+`createLambdaWebSocketHandler(factories)`. They build `variables`/`secrets` from
+`process.env`, cache the singleton services in module scope, and return the
+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
 
+Pick the entry point that matches the API Gateway payload version — they take
+different event types and are not interchangeable:
+
 ```typescript
-import type { APIGatewayProxyEvent } from 'aws-lambda'
-import { runFetch } from '@pikku/lambda/http'
+import type { APIGatewayEvent } from 'aws-lambda'
+import { runFetch } from '@pikku/lambda/http' // REST API / payload v1
 
-export const httpRoute = async (event: APIGatewayProxyEvent) => {
+export const httpRoute = async (event: APIGatewayEvent) => {
   await coldStart()
   return await runFetch(event)
 }
 ```
 
+```typescript
+import type { APIGatewayProxyEventV2 } from 'aws-lambda'
+import { runFetchV2 } from '@pikku/lambda/http' // HTTP API / payload v2
+
+export const httpRoute = async (event: APIGatewayProxyEventV2) => {
+  await coldStart()
+  return await runFetchV2(event)
+}
+```
+
+Both answer `OPTIONS` themselves before Pikku's wirings run, so a preflight
+never reaches your middleware. Only `runFetchV2` echoes the request `Origin`
+into `Access-Control-Allow-Origin`; `runFetch` sets allowed headers and methods
+but **no origin header at all**, so v1 preflights fail in the browser unless
+API Gateway or a CloudFront layer adds one.
+
+They also differ on failure: `runFetchV2` logs and returns a JSON `500`, while
+`runFetch` swallows the error and returns whatever status the response already
+carried.
+
+Neither takes `RunHTTPWiringOptions` — there is no `maxBodySize` or
+`respondWith404` knob here; API Gateway's own payload limit is the bound.
+
 ## Scheduled Tasks
 
 ```typescript
 import type { ScheduledHandler } from 'aws-lambda'
-import { runScheduledTask } from '@pikku/core/scheduler'
+import { runLambdaScheduled } from '@pikku/lambda/scheduled'
 
-export const myScheduledTask: ScheduledHandler = async () => {
+export const scheduled: ScheduledHandler = async (event) => {
   await coldStart()
-  await runScheduledTask({ name: 'myScheduledTask' })
+  await runLambdaScheduled(event)
 }
 ```
 
+`runLambdaScheduled` runs **every** scheduled task registered in the bundle,
+each with its own `cron-<uuid>` traceId, and logs rather than rethrows a task
+failure — so one bad task cannot fail the invocation or stop the others. The
+event itself is ignored; which tasks run is decided by what the unit bundled,
+not by which EventBridge rule fired.
+
+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
 
 ```typescript
@@ -80,6 +125,25 @@ export const mySQSWorker: SQSHandler = async (event) => {
 }
 ```
 
+The worker returns an `SQSBatchResponse` listing the failed messages in
+`batchItemFailures`, which SQS only honours when the event source mapping has
+**`ReportBatchItemFailures`** enabled. Without it the whole batch is retried
+when any one message fails, so successfully processed jobs run twice.
+
+Records are processed in parallel, and the queue name is taken from the last
+segment of `eventSourceARN` — it must match the name the worker was wired under.
+A `QueueJobDiscardedError` counts as success (no retry); anything else is
+reported as a failed item.
+
+`waitForCompletion` throws on an SQS job: the transport is fire-and-forget.
+
+On the producer side, `SQSQueueService` resolves each queue URL from the
+constructor's `queueUrlMap` first, then from
+`SQS_QUEUE_URL_<SCREAMING_SNAKE_NAME>`, and throws naming the missing variable
+if neither has it. `supportsResults` is `false` and `getJob()` always throws —
+use BullMQ or PgBoss if you need results. `delay` is milliseconds, rounded up to
+whole seconds and capped at SQS's 900s ceiling.
+
 ## WebSocket (API Gateway v2)
 
 ```typescript
@@ -90,21 +154,37 @@ import {
   LambdaEventHubService,
 } from '@pikku/lambda/websocket'
 
-export const connectHandler = async (event) => {
-  const params = await getParams(event)
-  await connectWebsocket(event, params)
-  return { statusCode: 200, body: '' }
+const params = async (event) => {
+  const { channelStore } = await coldStart()
+  return { channelStore }
 }
 
-export const disconnectHandler = async (event) => {
-  const params = await getParams(event)
-  return await disconnectWebsocket(event, params)
-}
+export const connectHandler = async (event) =>
+  await connectWebsocket(event, await params(event))
 
-export const defaultHandler = async (event) => {
-  const params = await getParams(event)
-  return await processWebsocketMessage(event, params)
-}
+export const disconnectHandler = async (event) =>
+  await disconnectWebsocket(event, await params(event))
+
+export const defaultHandler = async (event) =>
+  await processWebsocketMessage(event, await params(event))
 ```
 
-WebSocket requires a `ChannelStore` (e.g., `PgChannelStore`) and `LambdaEventHubService` for cross-connection messaging.
+All three take the same `{ channelStore }` and **return a complete
+`APIGatewayProxyResult`** — return it. Discarding `connectWebsocket`'s result
+and answering a hardcoded `200` accepts every connection, including the ones
+your channel's auth rejected.
+
+`channelStore` (e.g. `PgChannelStore`) must be a real shared store: each route
+is a separate invocation, so nothing survives in memory between `$connect` and
+`$default`.
+
+`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.
+
+Two behaviours to design around: **binary payloads throw** (`Binary data is not
+supported on serverless lambdas`), and any `PostToConnection` failure removes
+the connection from the channel store — a transient error drops a live client,
+not just a stale one.

package/skills/pikku-deploy-nextjs/SKILL.md

@@ -38,6 +38,17 @@ export const PATCH = pikkuAPIRequest
 export const DELETE = pikkuAPIRequest
 ```
 
+`pikkuAPIRequest` strips a leading `/api` from the pathname before routing, so
+wirings are declared as `/todos`, not `/api/todos`, even though the route file
+lives under `app/api`. Turn that off with `removeAPIPrefix(false)` from the same
+generated file if your wirings really do carry the prefix.
+
+It takes `(req, context)` to match Next's handler signature but ignores the
+context — Pikku routes from the URL, so the catch-all segment name is yours to
+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
 
 Use the generated `pikku()` helper in Server Components or Server Actions:
@@ -45,7 +56,7 @@ Use the generated `pikku()` helper in Server Components or Server Actions:
 ```typescript
 import { pikku } from '@/pikku-nextjs.gen.js'
 
-const { get, post, del, rpc, staticGet, staticPost, staticRPC } = pikku()
+const { get, post, patch, del, rpc, staticGet, staticPost, staticRPC } = pikku()
 
 // Dynamic (reads headers/cookies — requires request context)
 const todos = await get('/todos')
@@ -60,8 +71,19 @@ const result = await rpc('calculateTax', { amount: 100, region: 'US' })
 
 **Dynamic vs Static:**
 
-- `get`, `post`, `del`, `rpc` — access headers/cookies, use in dynamic Server Components
-- `staticGet`, `staticPost`, `staticRPC` — no request context, safe for precompile/ISR
+- `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
+
+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.
+There is no `staticPatch` or `staticDel`; a mutation at build time is not a
+thing the generated client offers.
+
+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
 
@@ -73,6 +95,28 @@ import { PikkuNextJS } from '@pikku/next'
 const pikku = new PikkuNextJS(createConfig, createSingletonServices)
 ```
 
-**Constructor:** `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.
+
+Initialization is memoized on a promise, so concurrent first requests share one
+setup; a failed setup clears the promise, so the next request retries rather
+than caching the failure forever.
+
+The generated `pikku-nextjs.gen.ts` wraps this with full type safety from your
+route definitions.
+
+## Related exports
 
-The generated `pikku-nextjs.gen.ts` wraps this with full type safety from your 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.
+- **`toNextJsAuthHandler(auth)`** — wraps a better-auth instance or handler
+  function for an auth route. The three-argument form
+  `(pikkuAuthFactory, createConfig, createSingletonServices)` resolves a Pikku
+  better-auth factory lazily; it throws if you pass `createConfig` without
+  `createSingletonServices`. `nextCookies` is re-exported alongside it.