@pikku/skills 0.12.2 → 0.12.6

package/skills/pikku-config/SKILL.md

@@ -2,11 +2,12 @@
 name: pikku-config
 description: >-
   Use when managing secrets, environment variables, config, or OAuth2 credentials in a Pikku app.
-  Covers wireSecret, wireVariable, wireOAuth2Credential, and typed config access. TRIGGER when:
-  code uses wireSecret/wireVariable/wireOAuth2Credential, user asks about env vars, secrets,
-  config, OAuth2, or "how do I access environment variables". DO NOT TRIGGER when: user asks about
-  API versioning/breaking changes (use pikku-versioning), service factories (use pikku-services),
-  or auth middleware (use pikku-security).
+  Covers defineSecret, defineVariable, defineCredential, and typed config access. TRIGGER when:
+  code uses defineSecret/defineVariable/defineCredential, user asks about env vars, secrets,
+  config, OAuth2, SecretValue/.reveal(), SecretCoercionError, or "how do I access environment
+  variables". DO NOT TRIGGER when: user asks about API versioning/breaking changes (use
+  pikku-versioning), service factories (use pikku-services), middleware (use pikku-middleware), or
+  auth strategies and sessions (use pikku-security).
 installGroups: [core]
 ---
 
@@ -35,34 +36,60 @@ See `pikku-concepts` for the core mental model.
 
 ## Secrets & Variables
 
-### `wireSecret(config)`
+### `defineSecret(config)`
 
 Declare a secret with a Zod schema for type-safe access:
 
 ```typescript
-wireSecret({
+defineSecret({
   name: string, // Secret identifier
   schema: ZodSchema, // Shape and validation
 })
 ```
 
-### `wireVariable(config)`
+### `defineVariable(config)`
 
 Declare a variable (non-sensitive config) with a Zod schema:
 
 ```typescript
-wireVariable({
+defineVariable({
   name: string,
   schema: ZodSchema,
 })
 ```
 
-### Accessing in Functions
+### Accessing Secrets
+
+`secrets` is **not available inside functions, AI agents, workflows, permissions
+or any wire** — it is removed from their services type and throws at runtime if
+reached through a cast. Read it where you wire the app and hand the value to a
+service:
+
+`getSecret` returns a `SecretValue<T>`, not the bare value. It is nominal — not
+assignable to `string`, so every concretely-typed sink rejects it — it serializes
+to `[secret]` in logs and audits, and coercing it to a string (a template
+literal, a concatenation) throws `SecretCoercionError`, because that is always a
+leak. `.reveal()` is the one way out, which makes every disclosure deliberate and
+greppable. Call it at the point the value reaches the thing that needs it:
 
 ```typescript
-// Secrets — encrypted, sensitive values
-const config = await services.secrets.getSecret('SECRET_NAME')
+// services.ts — allowed
+const createSingletonServices = pikkuServices(async (config, { secrets }) => ({
+  stripe: new StripeService((await secrets.getSecret('STRIPE_CONFIG')).reveal()),
+}))
+
+// functions/*.ts — ask the service, never the secret store
+export const charge = pikkuFunc({
+  func: async ({ stripe }, data) => stripe.charge(data.amount),
+})
+```
+
+Allowed: `pikkuServices`, `pikkuWireServices`, addon service factories,
+middleware. Everywhere else, the service you constructed is the interface.
 
+### Accessing Variables in Functions
+
+```typescript
 // Variables — plain-text configuration
 const flags = await services.variables.getVariableJSON('VARIABLE_NAME')
 
@@ -85,7 +112,7 @@ const createSingletonServices = pikkuServices(async (config) => ({
 
 ```typescript
 // Declare secrets with typed schemas
-wireSecret({
+defineSecret({
   name: 'STRIPE_CONFIG',
   schema: z.object({
     apiKey: z.string().startsWith('sk_'),
@@ -93,13 +120,13 @@ wireSecret({
   }),
 })
 
-// In your function — fully typed
-const config = await secrets.getSecret('STRIPE_CONFIG')
+// In your services factory — fully typed
+const config = (await secrets.getSecret('STRIPE_CONFIG')).reveal()
 // config.apiKey       → string (autocompleted)
 // config.webhookSecret → string (autocompleted)
 
 // Declare variables
-wireVariable({
+defineVariable({
   name: 'FEATURE_FLAGS',
   schema: z.object({
     darkMode: z.boolean(),
@@ -113,46 +140,80 @@ const flags = await variables.getVariableJSON('FEATURE_FLAGS')
 // flags.maxUploadMB → number
 ```
 
-## OAuth2 Credentials
+## Credentials
 
-### `wireOAuth2Credential(config)`
+### `defineCredential(config)`
 
 ```typescript
-wireOAuth2Credential({
-  name: string,              // Credential identifier
-  displayName: string,       // Human-readable name
-  secretId: string,          // Secret holding { clientId, clientSecret }
-  tokenSecretId: string,     // Secret for token storage (auto-refreshed)
-  authorizationUrl: string,  // OAuth2 authorization endpoint
-  tokenUrl: string,          // OAuth2 token endpoint
-  scopes: string[],          // Required OAuth2 scopes
+defineCredential({
+  name: string,                  // Credential identifier
+  displayName: string,           // Human-readable name
+  type: 'wire' | 'singleton',    // Per-user ('wire') or platform-level ('singleton')
+  schema: ZodSchema,             // Shape of the stored credential
+  oauth2?: {                     // Omit entirely for a plain API key
+    appCredentialSecretId: string, // Secret holding { clientId, clientSecret }
+    tokenSecretId: string,         // Secret for token storage (auto-refreshed)
+    authorizationUrl: string,      // OAuth2 authorization endpoint
+    tokenUrl: string,              // OAuth2 token endpoint
+    scopes: string[],              // Required OAuth2 scopes
+  },
 })
 ```
 
 ### Usage
 
 ```typescript
-wireOAuth2Credential({
-  name: 'slackOAuth',
-  displayName: 'Slack OAuth',
-  secretId: 'SLACK_OAUTH_APP',
-  tokenSecretId: 'SLACK_OAUTH_TOKENS',
-  authorizationUrl: 'https://slack.com/oauth/v2/authorize',
-  tokenUrl: 'https://slack.com/api/oauth.v2.access',
-  scopes: ['chat:write', 'channels:read'],
+// Per-user API key — no oauth2 block
+defineCredential({
+  name: 'stripe',
+  displayName: 'Stripe API Key',
+  type: 'wire',
+  schema: z.object({ apiKey: z.string() }),
 })
 
-// In your function — tokens refresh automatically
-const response = await slackOAuth.request(
-  'https://slack.com/api/chat.postMessage',
-  {
-    method: 'POST',
-    body: JSON.stringify({ channel, text }),
+// Platform-level OAuth (singleton)
+defineCredential({
+  name: 'slack',
+  displayName: 'Slack',
+  type: 'singleton',
+  schema: z.object({ accessToken: z.string(), refreshToken: z.string() }),
+  oauth2: {
+    appCredentialSecretId: 'SLACK_OAUTH_APP',
+    tokenSecretId: 'SLACK_OAUTH_TOKENS',
+    authorizationUrl: 'https://slack.com/oauth/v2/authorize',
+    tokenUrl: 'https://slack.com/api/oauth.v2.access',
+    scopes: ['chat:write', 'channels:read'],
+  },
+})
+
+### Reading a Credential
+
+A declared credential is resolved per invocation through `wire.getCredential(name)`,
+so the natural place to read it is a wire service factory: build the client there
+once and let functions ask the client, the same way they ask a service for a
+secret-derived value. Tokens refresh automatically, so what arrives is already
+valid.
+
+```typescript
+export const createWireServices = pikkuWireServices(async (_services, wire) => {
+  const cred = await wire.getCredential?.<{ accessToken: string }>('slack')
+  if (!cred?.accessToken) {
+    // Tells the caller which credential to connect, and where.
+    throw new MissingCredentialError('slack', 'oauth2', '/credentials/slack/connect')
   }
-)
-const data = await response.json()
+  return { slack: new SlackClient(cred.accessToken) }
+})
+
+// functions/*.ts — ask the client, never the credential store
+export const postMessage = pikkuFunc({
+  func: async ({ slack }, { channel, text }) => slack.postMessage(channel, text),
+})
 ```
 
+A `wire` credential resolves per user, so an unconnected user hits
+`MissingCredentialError` rather than silently acting as someone else; a
+`singleton` credential is platform-level and identical for every caller.
+
 ## Key Rule
 
 **Never use `process.env` inside Pikku functions.** Use the `variables` or `secrets` service:
@@ -165,13 +226,30 @@ const apiKey = process.env.API_KEY
 const apiKey = services.variables.get('API_KEY')
 ```
 
-`process.env` belongs only in server bootstrap code (`start.ts`).
+`process.env` belongs only in server bootstrap code (`start.ts`). Under `pikku dev` / `pikku serve` there is no `start.ts` — startup work goes in a `pikkuServerLifecycle` export, and the hooks receive the singleton services, so read configuration through `variables` there too (see pikku-services).
+
+### Lint rules
+
+`pikku.config.json` can set the severity of individual checks:
+
+```json
+{
+  "lint": {
+    "servicesNotDestructured": "error",
+    "wiresNotDestructured": "error",
+    "functionDynamicImport": "warn",
+    "customServerBootstrap": "warn"
+  }
+}
+```
+
+`customServerBootstrap` is the one evaluated by `pikku workspace validate` rather than codegen: it warns when the root `start`/`dev` script boots a server without `pikku dev` / `pikku serve` and no runtime adapter is installed. Set it to `"off"` to keep a hand-rolled entrypoint, or `"error"` to enforce the hooks.
 
 ## Complete Example
 
 ```typescript
 // schemas/config.ts
-wireSecret({
+defineSecret({
   name: 'DATABASE_CONFIG',
   schema: z.object({
     connectionString: z.string().url(),
@@ -179,7 +257,7 @@ wireSecret({
   }),
 })
 
-wireVariable({
+defineVariable({
   name: 'APP_CONFIG',
   schema: z.object({
     appName: z.string(),
@@ -188,20 +266,24 @@ wireVariable({
   }),
 })
 
-wireOAuth2Credential({
+defineCredential({
   name: 'githubOAuth',
   displayName: 'GitHub OAuth',
-  secretId: 'GITHUB_OAUTH_APP',
-  tokenSecretId: 'GITHUB_OAUTH_TOKENS',
-  authorizationUrl: 'https://github.com/login/oauth/authorize',
-  tokenUrl: 'https://github.com/login/oauth/access_token',
-  scopes: ['read:user', 'repo'],
+  type: 'wire',
+  schema: z.object({ accessToken: z.string(), refreshToken: z.string() }),
+  oauth2: {
+    appCredentialSecretId: 'GITHUB_OAUTH_APP',
+    tokenSecretId: 'GITHUB_OAUTH_TOKENS',
+    authorizationUrl: 'https://github.com/login/oauth/authorize',
+    tokenUrl: 'https://github.com/login/oauth/access_token',
+    scopes: ['read:user', 'repo'],
+  },
 })
 
 // functions/admin.functions.ts
 export const getAppStatus = pikkuSessionlessFunc({
   title: 'Get App Status',
-  func: async ({ variables, secrets }) => {
+  func: async ({ variables }) => {
     const appConfig = await variables.getVariableJSON('APP_CONFIG')
     return {
       appName: appConfig.appName,

package/skills/pikku-cron/SKILL.md

@@ -6,6 +6,7 @@ description: >-
   when: code uses wireScheduler, user asks about cron, scheduled tasks, recurring jobs, or "run
   every X minutes/hours". DO NOT TRIGGER when: user asks about background jobs with retries (use
   pikku-queue) or event-driven triggers (use pikku-trigger).
+installGroups: [core]
 ---
 
 # Pikku Cron/Scheduler Wiring
@@ -42,6 +43,7 @@ wireScheduler({
   name: string,            // Unique scheduler name
   schedule: string,        // Cron expression
   func: PikkuVoidFunc,     // Must be pikkuVoidFunc (no input/output)
+  tags?: string[],         // Targets tag middleware — see pikku-middleware
   middleware?: PikkuMiddleware[],
 })
 ```
@@ -53,10 +55,17 @@ Inside scheduled functions:
 ```typescript
 wire.scheduledTask.name // Scheduler name
 wire.scheduledTask.schedule // Cron expression string
-wire.scheduledTask.executionTime // When this execution was triggered
-wire.scheduledTask.skip(reason) // Skip this execution (no error)
+wire.scheduledTask.executionTime // Date this execution was triggered
+wire.scheduledTask.skip(reason?) // Abort this execution — THROWS, never returns
 ```
 
+**`skip()` aborts by throwing.** It reads like an early return but it is not:
+nothing after the call runs, so there is no need to `return` afterwards. The
+consequence that bites is in middleware — a `try/catch` around `await next()`
+will catch a skip and report it as a failure. If your middleware distinguishes
+success from failure, let the skip pass through rather than logging it as an
+error.
+
 ### Cron Expression Reference
 
 ```
@@ -113,8 +122,7 @@ const weeklyCleanup = pikkuVoidFunc({
 
     const staleCount = await db.countStaleTodos()
     if (staleCount === 0) {
-      wire.scheduledTask.skip('No stale todos found')
-      return
+      wire.scheduledTask.skip('No stale todos found') // throws — nothing below runs
     }
 
     await db.deleteCompletedTodos({ olderThan: '30d' })
@@ -178,8 +186,7 @@ export const cleanupExpired = pikkuVoidFunc({
   func: async ({ db, logger }, _input, wire) => {
     const count = await db.countExpiredSessions()
     if (count === 0) {
-      wire.scheduledTask.skip('No expired sessions')
-      return
+      wire.scheduledTask.skip('No expired sessions') // throws — nothing below runs
     }
     await db.deleteExpiredSessions()
     logger.info(`Cleaned ${count} expired sessions`)

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.