@pikku/cli 0.12.55 → 0.12.56

package/skills/pikku-concepts/SKILL.md

@@ -53,42 +53,32 @@ The function never imports Express, never reads `req.body`, never touches `ws.se
 
 ## Concept Mapping: Generic Backend → Pikku
 
-| Generic Backend Concept                 | Pikku Equivalent                                                | Skill             |
-| --------------------------------------- | --------------------------------------------------------------- | ----------------- |
-| **Controller / Route Handler**          | `pikkuFunc` / `pikkuSessionlessFunc`                            | (this skill)      |
-| **Route definition** (`GET /users/:id`) | `wireHTTP({ route, method, func })`                             | `pikku-http`      |
-| **Middleware** (Express/Koa-style)      | `pikkuMiddleware`                                               | `pikku-security`  |
-| **Auth Guard / Auth Middleware**        | `authBearer()` / `authCookie()` / `authApiKey()`                | `pikku-security`  |
-| **Authorization / Permissions**         | `pikkuPermission` / `pikkuAuth`                                 | `pikku-security`  |
-| **DTO / Request Validation**            | Standard Schema (Zod, Valibot, ArkType)                         | (this skill)      |
-| **Dependency Injection**                | `pikkuServices` (singleton) + `pikkuWireServices` (per-request) | `pikku-services`  |
-| **WebSocket handlers**                  | `wireChannel`                                                   | `pikku-websocket` |
-| **Job Queue workers**                   | `wireQueueWorker`                                               | `pikku-queue`     |
-| **Cron / Scheduled tasks**              | `wireScheduler`                                                 | `pikku-cron`      |
-| **Module / Feature grouping**           | Tags + wiring files                                             | (this skill)      |
-| **Error handling**                      | Throw typed errors (`NotFoundError`, `ForbiddenError`)          | (this skill)      |
-| **Type-safe API client**                | `npx pikku prebuild` generates clients                          | (this skill)      |
-| **Secrets / Config**                    | `wireSecret`, `wireVariable`, `services.variables`              | `pikku-config`    |
+Controllers/routes → `pikkuFunc`; middleware/auth/permissions → `pikku-security`; DI → `pikku-services`; transports (HTTP/WS/queue/cron) → their `wire*` + skill. For the full Generic Backend → Pikku mapping table (with side-by-side code examples), read `references/concept-mapping.md`.
 
 ## Functions
 
 Three main function types:
 
 ```typescript
-// Requires authentication — receives session in wire context
-const updateTodo = pikkuFunc<UpdateInput, TodoOutput>(
-  async (services, data, wire) => {
+// Requires authentication — receives session in wire context.
+// input/output are Zod schemas; the data + return types are inferred from them.
+const updateTodo = pikkuFunc({
+  input: UpdateTodoInput,
+  output: TodoOutput,
+  func: async (services, data, wire) => {
     const session = await wire.session.get()
     return services.todoStore.update(data.id, data)
-  }
-)
+  },
+})
 
 // No authentication required
-const listTodos = pikkuSessionlessFunc<ListInput, TodoListOutput>(
-  async (services, data) => {
+const listTodos = pikkuSessionlessFunc({
+  input: ListTodosInput,
+  output: TodoListOutput,
+  func: async (services, data) => {
     return { todos: services.todoStore.list(data.filters) }
-  }
-)
+  },
+})
 
 // No input or output (for scheduled tasks, lifecycle hooks)
 const cleanup = pikkuVoidFunc(async (services) => {
@@ -96,23 +86,7 @@ const cleanup = pikkuVoidFunc(async (services) => {
 })
 ```
 
-Config object form (recommended):
-
-```typescript
-const createTodo = pikkuSessionlessFunc({
-  title: 'Create Todo',
-  description: 'Create a new todo item',
-  input: CreateTodoInputSchema,
-  output: CreateTodoOutputSchema,
-  func: async ({ logger, todoStore }, { title, priority }) => {
-    const todo = todoStore.createTodo(title, priority)
-    logger.info(`Created todo: ${todo.id}`)
-    return { todo }
-  },
-})
-```
-
-Full config options:
+Services can be destructured inline in the `func` signature (e.g. `async ({ logger, todoStore }, { title }) => ...`). Full config options:
 
 ```typescript
 pikkuFunc({
@@ -243,33 +217,7 @@ expect(result.todos).toHaveLength(3)
 
 ## Available Packages
 
-### Runtime Adapters
-
-| Package                       | Use Case                              |
-| ----------------------------- | ------------------------------------- |
-| `@pikku/express-server`       | Express standalone server             |
-| `@pikku/express-middleware`   | Express as middleware in existing app |
-| `@pikku/fastify-server`       | Fastify standalone                    |
-| `@pikku/fastify-plugin`       | Fastify plugin                        |
-| `@pikku/next`                 | Next.js API routes                    |
-| `@pikku/aws-lambda`           | AWS Lambda handlers                   |
-| `@pikku/cloudflare`           | Cloudflare Workers                    |
-| `@pikku/uws-server`           | uWebSockets.js (high perf)            |
-| `@pikku/modelcontextprotocol` | MCP server                            |
-
-### Service Packages
-
-| Package                  | Provides                                             |
-| ------------------------ | ---------------------------------------------------- |
-| `@pikku/jose`            | JWT (sign/verify) via jose library                   |
-| `@pikku/schema-ajv`      | Schema validation via AJV                            |
-| `@pikku/schema-cfworker` | Schema validation for Cloudflare                     |
-| `@pikku/pino`            | Structured logging via Pino                          |
-| `@pikku/kysely`          | Type-safe SQL via Kysely (PostgreSQL, SQLite, MySQL) |
-| `@pikku/redis`           | Redis client                                         |
-| `@pikku/queue-bullmq`    | Job queues via BullMQ                                |
-| `@pikku/queue-pg-boss`   | Job queues via PgBoss                                |
-| `@pikku/aws-services`    | AWS SDK (SQS, DynamoDB, etc.)                        |
+Pikku ships runtime adapters (`@pikku/express-server`, `@pikku/fastify-server`, `@pikku/next`, `@pikku/aws-lambda`, `@pikku/cloudflare`, `@pikku/uws-server`, `@pikku/modelcontextprotocol`, ...) and service packages (`@pikku/jose`, `@pikku/schema-ajv`, `@pikku/pino`, `@pikku/kysely`, `@pikku/redis`, `@pikku/queue-bullmq`, `@pikku/queue-pg-boss`, ...). For the full list with use cases, read `references/packages.md`.
 
 ## Key Differences from Traditional Frameworks
 

package/skills/pikku-concepts/references/concept-mapping.md

@@ -1,6 +1,25 @@
 # Concept Mapping: Generic Backend → Pikku
 
-Side-by-side code examples showing how common backend patterns translate to Pikku.
+Authoritative mapping table plus side-by-side code examples showing how common backend patterns translate to Pikku.
+
+## Quick Reference Table
+
+| Generic Backend Concept                 | Pikku Equivalent                                                | Skill             |
+| --------------------------------------- | --------------------------------------------------------------- | ----------------- |
+| **Controller / Route Handler**          | `pikkuFunc` / `pikkuSessionlessFunc`                            | `pikku-concepts`  |
+| **Route definition** (`GET /users/:id`) | `wireHTTP({ route, method, func })`                             | `pikku-http`      |
+| **Middleware** (Express/Koa-style)      | `pikkuMiddleware`                                               | `pikku-security`  |
+| **Auth Guard / Auth Middleware**        | `authBearer()` / `authCookie()` / `authApiKey()`                | `pikku-security`  |
+| **Authorization / Permissions**         | `pikkuPermission` / `pikkuAuth`                                 | `pikku-security`  |
+| **DTO / Request Validation**            | Standard Schema (Zod, Valibot, ArkType)                         | `pikku-concepts`  |
+| **Dependency Injection**                | `pikkuServices` (singleton) + `pikkuWireServices` (per-request) | `pikku-services`  |
+| **WebSocket handlers**                  | `wireChannel`                                                   | `pikku-websocket` |
+| **Job Queue workers**                   | `wireQueueWorker`                                               | `pikku-queue`     |
+| **Cron / Scheduled tasks**              | `wireScheduler`                                                 | `pikku-cron`      |
+| **Module / Feature grouping**           | Tags + wiring files                                             | `pikku-concepts`  |
+| **Error handling**                      | Throw typed errors (`NotFoundError`, `ForbiddenError`)          | `pikku-concepts`  |
+| **Type-safe API client**                | `npx pikku prebuild` generates clients                          | `pikku-concepts`  |
+| **Secrets / Config**                    | `wireSecret`, `wireVariable`, `services.variables`              | `pikku-config`    |
 
 ## Route Handler / Controller → pikkuFunc
 
@@ -21,14 +40,17 @@ class TodoController {
 **Pikku:**
 
 ```typescript
-// Function knows nothing about HTTP
-const createTodo = pikkuSessionlessFunc<CreateTodoInput, TodoOutput>(
-  async ({ todoStore, logger }, { title, priority }) => {
+// Function knows nothing about HTTP.
+// input/output are Zod schemas; the data + return types are inferred from them.
+const createTodo = pikkuSessionlessFunc({
+  input: CreateTodoInput,
+  output: TodoOutput,
+  func: async ({ todoStore, logger }, { title, priority }) => {
     const todo = todoStore.createTodo(title, priority)
     logger.info(`Created todo: ${todo.id}`)
     return { todo }
-  }
-)
+  },
+})
 
 // Wiring (separate file) - grouped with defineHTTPRoutes
 export const todoRoutes = defineHTTPRoutes({
@@ -68,13 +90,15 @@ async getUser(req: Request, res: Response) {
 **Pikku:**
 
 ```typescript
-// All sources merged into a single typed `data` object
-const getUser = pikkuSessionlessFunc<
-  { id: string; fields?: string },
-  UserOutput
->(async (services, { id, fields }) => {
-  // id comes from route param, fields from query - function doesn't care
-  return { user: await services.db.getUser(id, fields) }
+// All sources merged into a single typed `data` object.
+// input/output are Zod schemas; the data + return types are inferred from them.
+const getUser = pikkuSessionlessFunc({
+  input: z.object({ id: z.string(), fields: z.string().optional() }),
+  output: UserOutput,
+  func: async (services, { id, fields }) => {
+    // id comes from route param, fields from query - function doesn't care
+    return { user: await services.db.getUser(id, fields) }
+  },
 })
 
 wireHTTP({ method: 'get', route: '/users/:id', func: getUser, auth: false })

package/skills/pikku-concepts/references/packages.md

@@ -0,0 +1,29 @@
+# Available Pikku Packages
+
+## Runtime Adapters
+
+| Package                       | Use Case                              |
+| ----------------------------- | ------------------------------------- |
+| `@pikku/express-server`       | Express standalone server             |
+| `@pikku/express-middleware`   | Express as middleware in existing app |
+| `@pikku/fastify-server`       | Fastify standalone                    |
+| `@pikku/fastify-plugin`       | Fastify plugin                        |
+| `@pikku/next`                 | Next.js API routes                    |
+| `@pikku/aws-lambda`           | AWS Lambda handlers                   |
+| `@pikku/cloudflare`           | Cloudflare Workers                    |
+| `@pikku/uws-server`           | uWebSockets.js (high perf)            |
+| `@pikku/modelcontextprotocol` | MCP server                            |
+
+## Service Packages
+
+| Package                  | Provides                                             |
+| ------------------------ | ---------------------------------------------------- |
+| `@pikku/jose`            | JWT (sign/verify) via jose library                   |
+| `@pikku/schema-ajv`      | Schema validation via AJV                            |
+| `@pikku/schema-cfworker` | Schema validation for Cloudflare                     |
+| `@pikku/pino`            | Structured logging via Pino                          |
+| `@pikku/kysely`          | Type-safe SQL via Kysely (PostgreSQL, SQLite, MySQL) |
+| `@pikku/redis`           | Redis client                                         |
+| `@pikku/queue-bullmq`    | Job queues via BullMQ                                |
+| `@pikku/queue-pg-boss`   | Job queues via PgBoss                                |
+| `@pikku/aws-services`    | AWS SDK (SQS, DynamoDB, etc.)                        |

package/skills/pikku-http/SKILL.md

@@ -34,67 +34,14 @@ Follow existing patterns you find (naming, tag usage, file organization). See `p
 
 ## API Reference
 
-### `wireHTTP(config)`
+- `wireHTTP(config)` (from `@pikku/core/http`) — wire one function to one endpoint.
+- `defineHTTPRoutes(config)` + `wireHTTPRoutes(config)` (from `.pikku/pikku-types.gen.js`) — group routes with shared config; composable/nestable.
 
-Wire a single function to an HTTP endpoint.
+Function input/output types come from the function's own `input:`/`output:` zod schemas — never declared in the wiring. Route `:params`, query params, and body are merged into the function's `data` arg (see Data Flow).
 
-```typescript
-import { wireHTTP } from '@pikku/core/http'
-
-wireHTTP({
-  method: 'get' | 'post' | 'put' | 'patch' | 'delete' | 'head',
-  route: string,          // e.g. '/books/:bookId' — :params become data fields
-  func: PikkuFunc,        // The function to call
-  auth?: boolean,         // Override default auth (true = require session)
-  tags?: string[],        // For grouping, middleware targeting
-  permissions?: Record<string, PikkuPermission | PikkuPermission[]>,
-  middleware?: PikkuMiddleware[],
-  sse?: boolean,          // Enable Server-Sent Events
-  contentType?: 'xml' | 'json',  // Response content type
-  timeout?: number,       // Request timeout in ms
-  headers?: HTTPHeadersSchema,   // Expected headers schema
-  docs?: HTTPRouteDocsConfig,    // OpenAPI docs config
-})
-```
-
-### `defineHTTPRoutes(config)` + `wireHTTPRoutes(config)`
+Config cascading across groups: `basePath` concatenates down the chain, `tags` merge (union), `auth` child overrides parent.
 
-Group routes with shared configuration. Groups are composable and nestable.
-
-```typescript
-import { defineHTTPRoutes, wireHTTPRoutes } from '.pikku/pikku-types.gen.js'
-
-const routes = defineHTTPRoutes({
-  basePath?: string,       // Prepended to all route paths
-  tags?: string[],         // Applied to all routes in group
-  auth?: boolean,          // Default auth for all routes (overridable per-route)
-  middleware?: PikkuMiddleware[],
-  routes: {
-    [key: string]: {
-      method: string,
-      route: string,
-      func: PikkuFunc,
-      auth?: boolean,      // Override group auth
-      permissions?: Record<string, PikkuPermission | PikkuPermission[]>,
-      middleware?: PikkuMiddleware[],
-    }
-  }
-})
-
-wireHTTPRoutes({
-  basePath?: string,       // Top-level prefix (e.g. '/api/v1')
-  middleware?: PikkuMiddleware[],
-  routes: {
-    [key: string]: ReturnType<typeof defineHTTPRoutes>,
-  }
-})
-```
-
-Config cascading rules:
-
-- `basePath` — concatenates down the chain
-- `tags` — merge (union)
-- `auth` — child overrides parent
+For the full option tables (every `wireHTTP` field, the `defineHTTPRoutes`/`wireHTTPRoutes` config shape), read `references/http-options.md`.
 
 ### `addHTTPMiddleware(pattern, middlewares)`
 
@@ -137,7 +84,7 @@ wireHTTP({
 const booksRoutes = defineHTTPRoutes({
   tags: ['books'],
   routes: {
-    list: { method: 'get', route: '/books', func: listBooks, auth: false },
+    list: { method: 'get', route: '/books', func: listBooks, auth: false }, // per-route override
     get: { method: 'get', route: '/books/:bookId', func: getBook },
     create: { method: 'post', route: '/books', func: createBook },
     delete: { method: 'delete', route: '/books/:bookId', func: deleteBook },
@@ -145,24 +92,19 @@ const booksRoutes = defineHTTPRoutes({
 })
 
 const todosRoutes = defineHTTPRoutes({
-  auth: false,
+  auth: false, // group-level default, overridable per-route
   tags: ['todos'],
   routes: {
     list: { method: 'get', route: '/todos', func: listTodos },
-    create: { method: 'post', route: '/todos', func: createTodo },
-    get: { method: 'get', route: '/todos/:id', func: getTodo },
   },
 })
 
 wireHTTPRoutes({
   basePath: '/api/v1',
   middleware: [cors()],
-  routes: {
-    books: booksRoutes,
-    todos: todosRoutes,
-  },
+  routes: { books: booksRoutes, todos: todosRoutes },
 })
-// Results in: GET /api/v1/books, POST /api/v1/books, etc.
+// Results in: GET /api/v1/books, POST /api/v1/books, GET /api/v1/todos, etc.
 ```
 
 ### Auth & Permissions
@@ -258,60 +200,27 @@ const deleted = await pikkuFetch.delete('/api/v1/books/:bookId', {
 
 ## Complete Example
 
+Functions live in their own files (one per file) and supply behavior + `permissions`; the wiring file imports them and wires routes. Sessionless funcs need no session; `pikkuFunc` does.
+
 ```typescript
 // functions/books.functions.ts
 import { pikkuFunc, pikkuSessionlessFunc } from '#pikku'
 
 export const listBooks = pikkuSessionlessFunc({
   title: 'List Books',
-  func: async ({ db }, { limit }) => {
-    return { books: await db.listBooks(limit) }
-  },
+  func: async ({ db }, { limit }) => ({ books: await db.listBooks(limit) }),
 })
 
 export const getBook = pikkuFunc({
   title: 'Get Book',
   description: 'Retrieve a book by ID',
-  func: async ({ db }, { bookId }) => {
-    return await db.getBook(bookId)
-  },
+  func: async ({ db }, { bookId }) => await db.getBook(bookId),
   permissions: { user: isAuthenticated },
 })
 
-export const createBook = pikkuFunc({
-  title: 'Create Book',
-  func: async ({ db }, { title, author }) => {
-    return await db.createBook({ title, author })
-  },
-})
-
-export const deleteBook = pikkuFunc({
-  title: 'Delete Book',
-  func: async ({ db }, { bookId }) => {
-    await db.deleteBook(bookId)
-    return { deleted: true }
-  },
-})
-
-// wirings/books.http.ts
-import { defineHTTPRoutes, wireHTTPRoutes } from '.pikku/pikku-types.gen.js'
+// wirings/books.http.ts — same defineHTTPRoutes/wireHTTPRoutes shape as the Route Groups example above
 import { addHTTPMiddleware } from '@pikku/core/http'
 import { cors, authBearer } from '@pikku/core/middleware'
 
-const booksRoutes = defineHTTPRoutes({
-  tags: ['books'],
-  routes: {
-    list: { method: 'get', route: '/books', func: listBooks, auth: false },
-    get: { method: 'get', route: '/books/:bookId', func: getBook },
-    create: { method: 'post', route: '/books', func: createBook },
-    delete: { method: 'delete', route: '/books/:bookId', func: deleteBook },
-  },
-})
-
-wireHTTPRoutes({
-  basePath: '/api',
-  routes: { books: booksRoutes },
-})
-
 addHTTPMiddleware('*', [cors(), authBearer()])
 ```

package/skills/pikku-http/references/http-options.md

@@ -0,0 +1,57 @@
+# wireHTTP / defineHTTPRoutes / wireHTTPRoutes — full option reference
+
+## `wireHTTP(config)`
+
+Wire a single function to an HTTP endpoint. Import from `@pikku/core/http`.
+
+| Option | Type | Notes |
+| --- | --- | --- |
+| `method` | `'get' \| 'post' \| 'put' \| 'patch' \| 'delete' \| 'head'` | HTTP verb |
+| `route` | `string` | e.g. `/books/:bookId` — `:params` become `data` fields |
+| `func` | `PikkuFunc` | The function to call |
+| `auth?` | `boolean` | Override default auth (`true` = require session) |
+| `tags?` | `string[]` | For grouping, middleware targeting |
+| `permissions?` | `Record<string, PikkuPermission \| PikkuPermission[]>` | Permission checks |
+| `middleware?` | `PikkuMiddleware[]` | Per-route middleware |
+| `sse?` | `boolean` | Enable Server-Sent Events |
+| `contentType?` | `'xml' \| 'json'` | Response content type |
+| `timeout?` | `number` | Request timeout in ms |
+| `headers?` | `HTTPHeadersSchema` | Expected headers schema |
+| `docs?` | `HTTPRouteDocsConfig` | OpenAPI docs config |
+
+## `defineHTTPRoutes(config)` + `wireHTTPRoutes(config)`
+
+Group routes with shared configuration. Groups are composable and nestable. Import from `.pikku/pikku-types.gen.js`.
+
+```typescript
+const routes = defineHTTPRoutes({
+  basePath?: string,       // Prepended to all route paths
+  tags?: string[],         // Applied to all routes in group
+  auth?: boolean,          // Default auth for all routes (overridable per-route)
+  middleware?: PikkuMiddleware[],
+  routes: {
+    [key: string]: {
+      method: string,
+      route: string,
+      func: PikkuFunc,
+      auth?: boolean,      // Override group auth
+      permissions?: Record<string, PikkuPermission | PikkuPermission[]>,
+      middleware?: PikkuMiddleware[],
+    }
+  }
+})
+
+wireHTTPRoutes({
+  basePath?: string,       // Top-level prefix (e.g. '/api/v1')
+  middleware?: PikkuMiddleware[],
+  routes: {
+    [key: string]: ReturnType<typeof defineHTTPRoutes>,
+  }
+})
+```
+
+Config cascading rules:
+
+- `basePath` — concatenates down the chain
+- `tags` — merge (union)
+- `auth` — child overrides parent

package/skills/pikku-middleware/SKILL.md

@@ -77,20 +77,17 @@ wireHTTP({
 
 ## Global Middleware (`addGlobalMiddleware`)
 
-`addGlobalMiddleware` registers middleware that runs before everything else — across every wire type: HTTP, Queue, Channel, Trigger, Scheduler, Workflow, Agent, CLI, MCP. Use it for cross-cutting concerns like telemetry that must wrap every invocation regardless of transport.
+Runs before everything else, across every wire type: HTTP, Queue, Channel, Trigger, Scheduler, Workflow, Agent, CLI, MCP. Use it for cross-cutting concerns (e.g. telemetry) that must wrap every invocation regardless of transport.
 
 ```typescript
 import { addGlobalMiddleware } from '@pikku/core'
 import { telemetryOuter, telemetryInner } from '@pikku/core/middleware'
 
-// Outer telemetry: wraps the full call (highest priority)
-addGlobalMiddleware([telemetryOuter({ environmentId: env.STAGE_ID })])
-
-// Inner telemetry: closest to the function body (lowest priority)
-addGlobalMiddleware([telemetryInner({ environmentId: env.STAGE_ID })])
+addGlobalMiddleware([telemetryOuter({ environmentId: env.STAGE_ID })])  // wraps the full call
+addGlobalMiddleware([telemetryInner({ environmentId: env.STAGE_ID })])  // closest to the function body
 ```
 
-`telemetryOuter` ships with `priority: 'highest'` and `telemetryInner` with `priority: 'lowest'` — so even if both are added in the same call, priority sorting places outer first regardless of array order.
+`telemetryOuter` ships with `priority: 'highest'`, `telemetryInner` with `priority: 'lowest'` — so priority sorting places outer first regardless of array/call order.
 
 ## HTTP & Prefix Middleware (`addHTTPMiddleware`)
 
@@ -165,15 +162,13 @@ const earlyMiddleware = pikkuMiddleware({
 })
 ```
 
-Within the same priority level, registration order is preserved. Priority is the primary sort key — use it when a middleware must run before or after others regardless of registration order (e.g. telemetry wrapping everything, session extraction before auth checks).
-
-## Common Patterns
+Priority is the primary sort key; within the same level, registration order is preserved. Use priority when a middleware must run before/after others regardless of registration order (e.g. telemetry wrapping everything, session extraction before auth checks).
 
-### Service-to-Service Bearer Auth
+## Service-to-Service Bearer Auth (canonical pattern)
 
-The canonical pattern for a server that exposes RPCs only to a trusted caller (e.g. an API calling a machine-agent):
+A server that exposes RPCs only to a trusted caller (e.g. an API calling a machine-agent). Auth lives in a tag middleware — NOT in the function body. Authorization/permission checks belong in the `permissions` field (see `pikku-permissions`), never inside `func`.
 
-**On the server (the service being called):**
+**On the server (the service being called):** tag the function, register a `pikkuMiddleware` that reads the `Authorization` header on that tag.
 
 ```typescript
 // lib/host-token.ts
@@ -217,63 +212,11 @@ export const myFunc = pikkuSessionlessFunc({
 })
 ```
 
-**On the client (the caller):**
-
-Use the generated `RPCInvoke` type from `.pikku/rpc/pikku-rpc-wirings-map.gen.d.ts` — never hand-write the input/output types:
-
-```typescript
-import type { RPCInvoke } from '../../backends/my-service/.pikku/rpc/pikku-rpc-wirings-map.gen.d.js'
-
-export function getServiceRPC(baseUrl: string, token: string): RPCInvoke {
-  return async (name: string, data?: unknown) => {
-    const res = await fetch(`${baseUrl}/rpc/${String(name)}`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${token}`,
-      },
-      body: JSON.stringify({ data: data ?? {} }),
-    })
-    if (!res.ok) {
-      const text = await res.text().catch(() => '')
-      throw new Error(`rpc ${String(name)} failed: ${res.status} ${text}`)
-    }
-    return res.json()
-  } as RPCInvoke
-}
-```
-
-### Session-Setting Middleware
-
-```typescript
-const apiKeyAuth = pikkuMiddleware(async ({ kysely }, { http, setSession, session }, next) => {
-  if (session) return next()  // already authenticated
-
-  const header = http?.request?.header?.('x-api-key')
-  if (!header) return next()
-
-  const row = await kysely.selectFrom('apiKey').select('userId').where('key', '=', header).executeTakeFirst()
-  if (row) setSession?.({ userId: row.userId })
-
-  return next()
-})
-
-addTagMiddleware('api-key-auth', [apiKeyAuth])
-```
-
-Functions tagged `'api-key-auth'` with `auth: true` reject requests without a valid key; those with `auth: false` can inspect the session but won't reject.
+**On the client (the caller):** use the generated `RPCInvoke` type — never hand-write a `fetch` wrapper's types. See `references/middleware-patterns.md`.
 
-### Request Logging / Audit
+## More patterns
 
-```typescript
-const auditLog = pikkuMiddleware(async ({ logger, db }, wire, next) => {
-  const start = Date.now()
-  await next()
-  await db.createAuditLog({ duration: Date.now() - start })
-})
-
-addHTTPMiddleware('/admin/*', [auditLog])
-```
+`references/middleware-patterns.md` covers the client-side `RPCInvoke` caller, session-setting middleware (set a session from an API key), and request logging / audit middleware.
 
 ## After Changes
 

package/skills/pikku-middleware/references/middleware-patterns.md

@@ -0,0 +1,61 @@
+# Middleware Patterns (extended)
+
+Detailed, less-common middleware recipes. The common-path bearer-auth pattern lives inline in SKILL.md; this file holds the client-side caller, session-setting, and audit recipes.
+
+## Service-to-Service: the client (caller) side
+
+Use the generated `RPCInvoke` type from `.pikku/rpc/pikku-rpc-wirings-map.gen.d.ts` — never hand-write the input/output types:
+
+```typescript
+import type { RPCInvoke } from '../../backends/my-service/.pikku/rpc/pikku-rpc-wirings-map.gen.d.js'
+
+export function getServiceRPC(baseUrl: string, token: string): RPCInvoke {
+  return async (name: string, data?: unknown) => {
+    const res = await fetch(`${baseUrl}/rpc/${String(name)}`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${token}`,
+      },
+      body: JSON.stringify({ data: data ?? {} }),
+    })
+    if (!res.ok) {
+      const text = await res.text().catch(() => '')
+      throw new Error(`rpc ${String(name)} failed: ${res.status} ${text}`)
+    }
+    return res.json()
+  } as RPCInvoke
+}
+```
+
+## Session-Setting Middleware
+
+```typescript
+const apiKeyAuth = pikkuMiddleware(async ({ kysely }, { http, setSession, session }, next) => {
+  if (session) return next()  // already authenticated
+
+  const header = http?.request?.header?.('x-api-key')
+  if (!header) return next()
+
+  const row = await kysely.selectFrom('apiKey').select('userId').where('key', '=', header).executeTakeFirst()
+  if (row) setSession?.({ userId: row.userId })
+
+  return next()
+})
+
+addTagMiddleware('api-key-auth', [apiKeyAuth])
+```
+
+Functions tagged `'api-key-auth'` with `auth: true` reject requests without a valid key; those with `auth: false` can inspect the session but won't reject.
+
+## Request Logging / Audit
+
+```typescript
+const auditLog = pikkuMiddleware(async ({ logger, db }, wire, next) => {
+  const start = Date.now()
+  await next()
+  await db.createAuditLog({ duration: Date.now() - start })
+})
+
+addHTTPMiddleware('/admin/*', [auditLog])
+```