@pikku/skills 0.12.4 → 0.12.6

package/skills/pikku-kysely/SKILL.md

@@ -28,7 +28,7 @@ Use this skill as an execution checklist, not reference material.
 
 ## Writing Queries — the Kysely query builder
 
-In a Pikku function body the injected `kysely` IS the `Kysely<DB>` instance — query it directly. Pikku wires the **CamelCasePlugin**, so you write **camelCase everywhere in TS** (columns, aliases) and raw **snake_case ONLY inside a `` sql`` `` literal**. Kysely is a query builder, NOT an ORM — there are no relations; shape nested data with the JSON helpers below. Never hand-roll SQL strings; never annotate the return type (in Pikku the output zod schema IS the type).
+In a Pikku function body the injected `kysely` IS the `Kysely<DB>` instance — query it directly. Every connection factory below wires the **CamelCasePlugin** by default, so you write **camelCase everywhere in TS** (columns, aliases) and raw **snake_case ONLY inside a `` sql`` `` literal**. If a project opted out (`createNodeSqliteKysely({ camelCase: false })`), that inverts — check how the instance was built before assuming. Kysely is a query builder, NOT an ORM — there are no relations; shape nested data with the JSON helpers below. Never hand-roll SQL strings; never annotate the return type (in Pikku the output zod schema IS the type).
 
 ```typescript
 import { sql } from 'kysely'
@@ -92,12 +92,19 @@ await kysely.transaction().execute(async (trx) => {
 })
 ```
 
-Pikku provides SQL database services through four packages:
+Pikku provides SQL database services through six packages:
 
-- `@pikku/kysely` — Base service implementations (database-agnostic)
-- `@pikku/kysely-postgres` — PostgreSQL-specific implementations + `PikkuKysely` connection wrapper
+- `@pikku/kysely` — Base service implementations (database-agnostic), the serialize plugins, `createAuditedKysely` and the `pikkuSchemas` helpers
+- `@pikku/kysely-postgres` — PostgreSQL-specific implementations + the `PikkuKysely` connection wrapper and `PgEventHubService` (LISTEN/NOTIFY-backed)
 - `@pikku/kysely-mysql` — MySQL-specific implementations
-- `@pikku/kysely-sqlite` — SQLite-specific implementations + `createSQLiteKysely` factory
+- `@pikku/kysely-sqlite` — SQLite-specific implementations, `createSQLiteKysely`, and the `LibsqlWebDialect`
+- `@pikku/kysely-node-sqlite` — `createNodeSqliteKysely` over `node:sqlite`, plus user-defined SQL functions and the coercion plugin
+- `@pikku/kysely-bun-sqlite` — the same over `bun:sqlite`
+
+The last two are runtime adapters rather than service sets: they build the
+`Kysely<DB>` you inject into functions, while the dialect packages above supply
+Pikku's own stores. They differ in one place — `bun:sqlite` cannot register
+scalar functions, so `createBunSqliteKysely` throws if you pass `functions`.
 
 All implement standard Pikku interfaces from `@pikku/core`.
 
@@ -105,9 +112,11 @@ All implement standard Pikku interfaces from `@pikku/core`.
 
 ```bash
 # Pick your database
-yarn add @pikku/kysely @pikku/kysely-postgres   # PostgreSQL
-yarn add @pikku/kysely @pikku/kysely-mysql      # MySQL
-yarn add @pikku/kysely @pikku/kysely-sqlite     # SQLite
+yarn add @pikku/kysely @pikku/kysely-postgres     # PostgreSQL
+yarn add @pikku/kysely @pikku/kysely-mysql        # MySQL
+yarn add @pikku/kysely @pikku/kysely-sqlite       # SQLite (stores)
+yarn add @pikku/kysely-node-sqlite                # SQLite on Node
+yarn add @pikku/kysely-bun-sqlite                 # SQLite on Bun
 ```
 
 ## API Reference
@@ -120,7 +129,8 @@ import { PikkuKysely } from '@pikku/kysely-postgres'
 const db = new PikkuKysely<DB>(
   logger: Logger,
   connectionOrConfig: postgres.Sql | postgres.Options | string,
-  defaultSchemaName?: string
+  defaultSchemaName?: string,
+  poolConfig?: PostgresConfig   // maxPool, connectTimeout, idleTimeout, maxLifetime, prepare, statementTimeout
 )
 
 await db.init()
@@ -128,14 +138,39 @@ db.kysely  // Kysely<DB> instance for queries
 await db.close()
 ```
 
-### SQLite Factory — `createSQLiteKysely`
+It builds a postgres.js-backed Kysely with the CamelCasePlugin. Pass an existing
+`postgres.Sql` when something else owns the pool — the wrapper then leaves it
+open on `close()`. `poolConfig` keys are only forwarded when set, so postgres.js
+keeps its own defaults for the rest, and it is ignored entirely when you hand in
+an already-constructed connection.
+
+### SQLite factories
+
+```typescript
+import { createNodeSqliteKysely } from '@pikku/kysely-node-sqlite'
+
+// Your application DB — CamelCasePlugin on by default
+const kysely = createNodeSqliteKysely<DB>({
+  filename: 'app.db',       // or ':memory:'
+  camelCase: true,
+  plugins: [],              // layered on top
+  functions: {},            // scalar UDFs, registered as deterministic (Node only)
+})
+```
 
 ```typescript
 import { createSQLiteKysely } from '@pikku/kysely-sqlite'
 
-const kysely = createSQLiteKysely(database: SqliteDatabase | (() => Promise<SqliteDatabase>))
+// Pikku's own tables — returns Kysely<KyselyPikkuDB>, not your DB
+const pikkuDb = createSQLiteKysely(database: SqliteDatabase | (() => Promise<SqliteDatabase>))
 ```
 
+These two are not interchangeable. `createSQLiteKysely` is typed to
+`KyselyPikkuDB` and wires the `SerializePlugin` (JSON columns in and out) rather
+than the CamelCasePlugin, because it exists to back the stores below. Reach for
+`createNodeSqliteKysely` / `createBunSqliteKysely` for the instance your
+functions query.
+
 ### Available Services
 
 Each database variant exports these services with a prefix (`Pg`, `MySQL`, `SQLite`, or base `Kysely`):
@@ -151,24 +186,52 @@ Each database variant exports these services with a prefix (`Pg`, `MySQL`, `SQLi
 | `*AgentRunService`    | `AgentRunService`                     | Agent execution tracking                       |
 | `*SecretService`      | `SecretService`                       | Encrypted secret storage (envelope encryption) |
 
+A handful more live only on the base package — there is no `Pg`/`MySQL`/`SQLite`
+variant to reach for, you import them from `@pikku/kysely` whatever the engine:
+
+| Service                    | Purpose                                       |
+| -------------------------- | --------------------------------------------- |
+| `KyselySessionStore`        | Persisted user sessions                       |
+| `KyselyScopeService`        | Scope and role storage                        |
+| `KyselyWebhookService`      | Webhook registrations and deliveries          |
+| `KyselyCredentialService`   | Encrypted third-party credentials             |
+| `KyselyAIRunStateService`   | AI run state (also implemented by AIStorage)  |
+| `KyselyWorkflowMirror`      | Mirrors workflow runs into queryable tables   |
+| `KyselyAuditService`        | Durable audit sink (see `pikku-audit`)        |
+
 All services take a `Kysely<KyselyPikkuDB>` instance in their constructor and have an `init()` method that creates tables if needed.
 
 ### Secret Service
 
+Envelope encryption: each secret gets its own DEK, wrapped by a KEK derived from
+`key` plus a stored per-version salt. Keeping `previousKey` around is what makes
+rotation possible — `rotateKEK` re-wraps every secret from the old key to the
+current one and returns the new version, and it throws if no `previousKey` is
+configured.
+
 ```typescript
 import { PgKyselySecretService } from '@pikku/kysely-postgres'
 
 const secrets = new PgKyselySecretService(db.kysely, {
-  kekSecret: 'your-key-encryption-key',
-  salt: 'your-salt',
+  key: 'your-key-encryption-passphrase',
+  keyVersion: 2, // defaults to 1
+  previousKey: 'the-passphrase-you-are-rotating-away-from',
+  audit: true, // log write/delete/rotate through the audit sink
+  auditReads: false, // reads too — noisy, off by default
 })
 await secrets.init()
 
 await secrets.setSecret('api-key', { key: 'sk-...' })
-const value = await secrets.getSecret<{ key: string }>('api-key')
-await secrets.rotateKEK() // Re-encrypt all secrets with new KEK
+const secret = await secrets.getSecret<{ key: string }>('api-key')
+await secrets.hasSecret('api-key')
+await secrets.deleteSecret('api-key')
+const newVersion = await secrets.rotateKEK()
 ```
 
+`getSecret` hands back a `SecretValue<T>`, not the bare value — it serializes as
+`[secret]` until something reveals it, which is what stops a secret drifting into
+a log line or an audit row. See `pikku-config` for the reveal rules.
+
 ## Usage Patterns
 
 ### PostgreSQL Setup

package/skills/pikku-machine-auth/SKILL.md

@@ -157,7 +157,42 @@ addHTTPMiddleware([
 
 When the api-key header is present it is authoritative — the middleware never
 falls through to `getSession` (a bare mock session would shadow the scoped one).
-When it is absent, the human `getSession` path runs as normal.
+When it is absent, the human `getSession` path runs as normal. Either way the
+middleware bails out entirely if a session is already set, and it checks the
+*live* session rather than the wire's construction-time snapshot, so it can't
+clobber one an earlier middleware resolved.
+
+### Restricting a key below its owner
+
+Set `scopes` on the session `mapKey` returns and that set is **authoritative** —
+including an empty one. It is never widened back out to everything the owning
+service user holds:
+
+```typescript
+mapKey: async (key) => ({
+  userId: 'sandbox-runtime',
+  scopes: ['sandbox:read'], // this key can do only this
+})
+```
+
+Leave `scopes` unset for a key that acts with its owner's full rights. This is
+what makes one stable service user safely able to own keys of very different
+power — the restriction lives on the key, not on a proliferation of identities.
+
+### Failure handling is deliberately split
+
+A key that fails to verify is logged and treated as an ordinary "not
+authenticated" — an unusable credential is not an outage. A failure *inside*
+`mapKey` (your scope store is down) propagates as a real error instead. That
+asymmetry is on purpose: a scope lookup that silently failed would serve the
+request anonymously, which is exactly the wrong direction to fail in.
+
+### `betterAuthStatelessSession` has no machine path
+
+The lean cookie-cache middleware (`betterAuthStatelessSession` — no
+`services.auth()`, no DB) handles only the human path. Machine auth needs
+`betterAuthSession`, because `verifyApiKey` is a server call there is no
+stateless equivalent of. Both accept an `impersonation` option.
 
 ### WebSocket channels authenticate on the upgrade handshake
 

package/skills/pikku-mcp/SKILL.md

@@ -2,11 +2,11 @@
 name: pikku-mcp
 description: >-
   Use when exposing Pikku functions as MCP tools, resources, or prompts for AI assistants. Covers
-  mcp: true flag, pikkuMCPResourceFunc, pikkuMCPPromptFunc, and MCP wire object. TRIGGER when:
-  code uses mcp: true or pikkuMCPResourceFunc/pikkuMCPPromptFunc, user asks about MCP, Model
-  Context Protocol, AI tool integration, or exposing functions to Claude/ChatGPT. DO NOT TRIGGER
-  when: user asks about AI agents (use pikku-ai-agent) or general function definitions (use
-  pikku-concepts).
+  mcp: true, pikkuMCPToolFunc, pikkuMCPResourceFunc, pikkuMCPPromptFunc, wireMCPResource,
+  wireMCPPrompt, the MCP wire object and PikkuMCPServer. TRIGGER when: code uses mcp: true or any
+  pikkuMCP*Func/wireMCP* helper, user asks about MCP, Model Context Protocol, AI tool integration,
+  or exposing functions to Claude/ChatGPT. DO NOT TRIGGER when: user asks about AI agents (use
+  pikku-ai-agent) or general function definitions (use pikku-concepts).
 installGroups: [core]
 ---
 
@@ -33,209 +33,219 @@ pikku info tags --verbose        # Understand project organization
 
 See `pikku-concepts` for the core mental model.
 
+## The shape of MCP in Pikku
+
+MCP has three surfaces, and Pikku wires them differently:
+
+| Surface | Function factory | Wiring | Return type |
+| --- | --- | --- | --- |
+| **Tool** | `mcp: true` on a `pikkuFunc`, or `pikkuMCPToolFunc` | none — the function *is* the registration | the func's own output, or MCP content blocks |
+| **Resource** | `pikkuMCPResourceFunc` | `wireMCPResource({ uri, title, … })` | `Array<{ uri, text }>` |
+| **Prompt** | `pikkuMCPPromptFunc` | `wireMCPPrompt({ name, description, … })` | `Array<MCPPromptMessage>` |
+
+Tools are the odd one out — there is no `wireMCPTool`. Resources and prompts
+carry protocol metadata (a URI template, a prompt name) that belongs to the
+endpoint rather than the implementation, so that metadata lives on the wiring and
+the `pikkuMCP*Func` factory stays a plain function.
+
+Import every factory and wiring from `#pikku`.
+
 ## API Reference
 
-### MCP Tools (simplest approach)
+### Tools
 
-Add `mcp: true` to any existing `pikkuFunc` to expose it as an MCP tool:
+Add `mcp: true` to any existing function:
 
 ```typescript
-const myFunc = pikkuFunc({
-  description: string,      // Used as MCP tool description
-  input: ZodSchema,         // Becomes MCP tool input schema
-  output: ZodSchema,        // Return type
-  mcp: true,                // ← Expose as MCP tool
-  func: async (services, data) => { ... },
+export const createTodo = pikkuFunc({
+  description: 'Create a new todo item',   // becomes the MCP tool description
+  input: CreateTodoInput,                  // becomes the MCP tool input schema
+  output: CreateTodoOutput,
+  mcp: true,
+  func: async ({ db }, { text, priority }) => db.createTodo({ text, priority }),
 })
 ```
 
-### MCP Resources (`pikkuMCPResourceFunc`)
+A missing `description` is all an assistant has to go on, so codegen warns about
+it rather than failing — treat the warning as a bug.
+
+Use `pikkuMCPToolFunc` when the tool should control its own presentation. It
+returns MCP content blocks (`{ type: 'text', text }` or `{ type: 'image', data }`
+with base64), so the assistant reads prose rather than raw JSON:
 
 ```typescript
-import { pikkuMCPResourceFunc } from '#pikku'
+import { pikkuMCPToolFunc } from '#pikku'
 
-const resource = pikkuMCPResourceFunc({
-  uri: string,              // URI template, e.g. 'todos/{id}'
-  title: string,            // Human-readable title
-  description?: string,
-  func: async (services, data, { mcp }) => {
-    // Must return array of { uri, text } or { uri, blob, mimeType }
-    return [{ uri: mcp.uri!, text: JSON.stringify(result) }]
+export const createTodoTool = pikkuMCPToolFunc({
+  description: 'Create a todo item with title, priority, due date and tags',
+  input: CreateTodoWithUserInputSchema,
+  func: async (_services, input, { rpc }) => {
+    const { todo } = await rpc.invoke('createTodo', input)
+    return [
+      { type: 'text' as const, text: `Created "${todo.title}" (${todo.id})` },
+    ]
   },
 })
 ```
 
-### MCP Prompts (`pikkuMCPPromptFunc`)
+It also accepts `name`, `title`, `summary`, `tags`, `middleware` and
+`permissions`. The function is sessionless and gets `mcp` and `rpc` on its wire —
+calling existing business functions through `rpc.invoke` keeps the tool a thin
+presentation layer over logic that is already tested and reachable over HTTP.
+
+### Resources
 
 ```typescript
-import { pikkuMCPPromptFunc } from '#pikku'
+import { pikkuMCPResourceFunc } from '#pikku'
 
-const prompt = pikkuMCPPromptFunc({
-  name: string,
-  description: string,
-  func: async (services, data) => {
-    // Must return array of MCP messages
+export const getTodoResource = pikkuMCPResourceFunc<{ id: string }>(
+  async (_services, { id }, { rpc, mcp }) => {
+    const { todo } = await rpc.invoke('getTodo', { id })
     return [
       {
-        role: 'user',
-        content: { type: 'text', text: '...' },
+        uri: mcp.uri!,
+        text: todo ? formatTodo(todo) : `Todo "${id}" not found.`,
       },
     ]
-  },
-})
-```
-
-### MCP Wire Object
-
-Inside MCP-enabled functions, `wire.mcp` provides:
-
-```typescript
-mcp.uri // Current resource URI (for resources)
-mcp.sendResourceUpdated(uri) // Notify clients a resource changed
-mcp.enableTools({ toolName: true }) // Dynamically enable/disable tools
+  }
+)
 ```
 
-## Usage Patterns
-
-### Expose Existing Functions as MCP Tools
-
-The simplest path — add `mcp: true` to any function:
+The factory takes either a bare function (as above) or a config object — `{ func, name }`,
+or `{ func, input }` with a schema. A resource returns `Array<{ uri, text }>`;
+it is text only, with no blob variant. `mcp.uri` is the concrete URI the client
+asked for, which is why each entry echoes it back.
 
 ```typescript
-export const createTodo = pikkuFunc({
-  description: 'Create a new todo item',
-  input: CreateTodoInput,
-  output: CreateTodoOutput,
-  mcp: true,
-  func: async ({ db }, { text, priority }) => {
-    return await db.createTodo({ text, priority })
-  },
-})
-```
+import { wireMCPResource } from '#pikku'
 
-### MCP Resources with URI Templates
-
-```typescript
-export const getTodo = pikkuMCPResourceFunc({
-  uri: 'todos/{id}',
+wireMCPResource({
+  uri: 'todos/{id}', // URI template
   title: 'Todo Details',
-  description: 'Get a todo by ID',
-  func: async ({ db }, { id }, { mcp }) => {
-    const todo = await db.getTodo(id)
-    return [{ uri: mcp.uri!, text: JSON.stringify(todo) }]
-  },
+  description: 'Get details of a specific todo by ID',
+  func: getTodoResource,
+  tags: ['todos'],
+  // also: summary?, mimeType?, size?, streaming?, errors?, middleware?
 })
 ```
 
-### MCP Prompts
+Every `{param}` in `uri` is checked against the function's input at compile time,
+so `todos/{id}` wired to a function whose input has no `id` fails to build rather
+than handing the function an `undefined`.
+
+### Prompts
 
 ```typescript
-export const codeReview = pikkuMCPPromptFunc({
-  name: 'codeReview',
-  description: 'Generate a code review prompt',
-  func: async ({}, { filePath, context }) => {
+import { pikkuMCPPromptFunc, wireMCPPrompt } from '#pikku'
+
+export const planDayPrompt = pikkuMCPPromptFunc({
+  input: UserIdInputSchema,
+  func: async (_services, { userId }, { rpc }) => {
+    const { todos } = await rpc.invoke('listTodos', { userId, completed: false })
     return [
       {
-        role: 'user',
+        role: 'user' as const,
         content: {
-          type: 'text',
-          text: `Review ${filePath}. Context: ${context}`,
+          type: 'text' as const,
+          text: `Plan my day:\n${todos.map(formatTodo).join('\n')}`,
         },
       },
     ]
   },
 })
+
+wireMCPPrompt({
+  name: 'planDay',
+  description: 'Generate a daily plan based on pending todos',
+  func: planDayPrompt,
+  tags: ['productivity'],
+})
 ```
 
-### Dynamic Tool Control
+A message's `role` is `'user' | 'assistant' | 'system'` and its `content.type` is
+`'text' | 'image'`. The prompt arguments the client sees are derived from the
+input schema at codegen time: each property becomes a named argument, and
+schema-required properties become required arguments.
+
+### MCP Wire Object
+
+Available as `wire.mcp` inside any MCP function:
+
+```typescript
+mcp.uri // the resolved resource URI (resources only)
+mcp.sendResourceUpdated(uri) // notify clients a resource changed
+await mcp.enableTools({ archiveTodos: true })
+await mcp.enableResources({ todoDetails: false })
+await mcp.enablePrompts({ planDay: true })
+```
+
+The `enable*` calls are how a server presents a changing surface — hiding tools
+that are meaningless in the current state beats letting the assistant call them
+and fail. Each returns a boolean, and each name is typechecked against your
+generated endpoint names.
 
 ```typescript
-export const manageTodos = pikkuFunc({
-  description: 'Manage todo items',
-  input: ManageTodosInput,
-  output: ManageTodosOutput,
+export const deleteTodo = pikkuFunc({
+  description: 'Delete a todo item',
   mcp: true,
-  func: async ({ db }, { action, id }, { mcp }) => {
-    if (action === 'delete') {
-      await db.deleteTodo(id)
-      mcp.sendResourceUpdated(`todos/${id}`)
-      await mcp.enableTools({ archiveTodos: true })
-      return { deleted: true }
-    }
+  func: async ({ db }, { id }, { mcp }) => {
+    await db.deleteTodo(id)
+    mcp.sendResourceUpdated(`todos/${id}`)
+    return { deleted: true }
   },
 })
 ```
 
-### MCP Server Setup
+## MCP Server Setup
+
+`PikkuMCPServer` takes the server config and a logger — not your services. It
+loads the generated `mcp.gen.json`, and the bootstrap import is what registers
+your functions.
 
 ```typescript
 // start.ts
 import { PikkuMCPServer } from '@pikku/modelcontextprotocol'
+import { createConfig, createSingletonServices } from './services.js'
+import mcpJSON from '../.pikku/mcp/mcp.gen.json' with { type: 'json' }
+import '../.pikku/pikku-bootstrap.gen.js'
+
+const config = await createConfig()
+const singletonServices = await createSingletonServices(config)
+
+const server = new PikkuMCPServer(
+  {
+    name: 'pikku-mcp-server',
+    version: '1.0.0',
+    mcpJSON,
+    capabilities: { logging: {}, tools: {}, resources: {}, prompts: {} },
+  },
+  singletonServices.logger
+)
 
-const server = new PikkuMCPServer(config, singletonServices, createWireServices)
 await server.init()
-await server.start()
-```
 
-## Complete Example
+// stdio — the transport desktop MCP clients spawn
+await server.connectStdio()
+singletonServices.logger = server.createMCPLogger()
 
-```typescript
-// functions/todos.functions.ts
-export const listTodos = pikkuSessionlessFunc({
-  description: 'List all todo items',
-  input: ListTodosInput,
-  output: ListTodosOutput,
-  mcp: true,
-  func: async ({ db }, { status }) => {
-    return { todos: await db.listTodos(status) }
-  },
-})
+// …or streamable HTTP, for a hosted server
+const { close } = await server.connectHTTP({ port: 3000, host: '127.0.0.1' })
+```
 
-export const createTodo = pikkuFunc({
-  description: 'Create a new todo item',
-  input: CreateTodoInput,
-  output: CreateTodoOutput,
-  mcp: true,
-  func: async ({ db }, { text, priority }) => {
-    return await db.createTodo({ text, priority })
-  },
-})
+`capabilities` is a filter, not documentation: a surface you leave out is not
+advertised and its endpoints are never loaded, which is how you ship a tools-only
+server.
 
-export const completeTodo = pikkuFunc({
-  description: 'Mark a todo as complete',
-  input: CompleteTodoInput,
-  output: CompleteTodoOutput,
-  mcp: true,
-  func: async ({ db }, { todoId }) => {
-    return await db.completeTodo(todoId)
-  },
-})
+Over stdio the protocol owns stdout, so an ordinary console logger corrupts the
+frames — that is what `createMCPLogger()` is for. Swap the logger before
+anything logs.
 
-// functions/todos.mcp.ts
-export const getTodoResource = pikkuMCPResourceFunc({
-  uri: 'todos/{id}',
-  title: 'Todo Details',
-  description: 'Get details of a specific todo',
-  func: async ({ db }, { id }, { mcp }) => {
-    const todo = await db.getTodo(id)
-    return [{ uri: mcp.uri!, text: JSON.stringify(todo) }]
-  },
-})
+## Red flags
 
-export const planDayPrompt = pikkuMCPPromptFunc({
-  name: 'planDay',
-  description: 'Create a daily plan based on pending todos',
-  func: async ({ db }, {}) => {
-    const { todos } = await db.listTodos('pending')
-    return [
-      {
-        role: 'user',
-        content: {
-          type: 'text',
-          text: `Plan my day. Here are my pending todos:\n${todos.map((t) => `- ${t.text} (${t.priority})`).join('\n')}`,
-        },
-      },
-    ]
-  },
-})
-```
+| Symptom | Cause |
+| --- | --- |
+| `wireMCPTool` is not exported | There is no tool wiring — use `mcp: true` or `pikkuMCPToolFunc` |
+| `uri`/`title` rejected on `pikkuMCPResourceFunc` | Those belong on `wireMCPResource` |
+| Resource returning `{ uri, blob, mimeType }` | Resources are text only: `{ uri, text }` |
+| Client sees a tool with no description | `mcp: true` without a `description` — check the codegen warning |
+| stdio client disconnects on the first log line | Logger still writing to stdout; use `createMCPLogger()` |

package/skills/pikku-middleware/SKILL.md

@@ -136,7 +136,7 @@ Tags from the function definition and the wire object are merged — middleware
 ### Registering Tag Middleware
 
 ```typescript
-import { addTagMiddleware } from '.pikku/pikku-types.gen.js'
+import { addTagMiddleware } from '#pikku'
 
 addTagMiddleware('machine-agent', [machineAgentBearerAuth])
 ```
@@ -145,18 +145,30 @@ Call at module load time — typically in the same `wirings/*.ts` file as the `w
 
 ## Middleware Execution Order
 
-**Scope resolution order (broadest → narrowest):**
+Resolution happens in two steps, and the order matters more than it looks.
+
+**Step 1 — collect, broadest → narrowest:**
 
 ```text
 global → httpGroup/* → httpGroup/prefix → wiringTags → wiringMiddleware → funcTags → funcMiddleware → function body
 ```
 
-**Within each scope, sorted by priority:**
+**Step 2 — sort that whole flat list by priority:**
 
 ```text
 highest → high → medium (default) → low → lowest
 ```
 
+**Priority is the primary key across every scope, not within one.** The collected
+list is flattened first and sorted once, so a `priority: 'lowest'` global
+middleware runs *after* an inline per-route middleware of default priority — the
+narrower scope does not win. Scope order survives only as the tiebreaker between
+middleware of equal priority, because the sort is stable.
+
+This is what makes `telemetryOuter`/`telemetryInner` work: they pin themselves to
+`highest`/`lowest` so they bracket every other middleware no matter where those
+were registered.
+
 Set priority using the config-object form of `pikkuMiddleware`:
 
 ```typescript
@@ -167,7 +179,7 @@ const earlyMiddleware = pikkuMiddleware({
 })
 ```
 
-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).
+Within the same priority level, the collection order above is preserved. Use priority when a middleware must run before/after others regardless of where it was registered (e.g. telemetry wrapping everything, session extraction before auth checks).
 
 ## Service-to-Service Bearer Auth (canonical pattern)
 
@@ -185,7 +197,7 @@ export const getToken = () => _token
 ```typescript
 // wirings/http.wiring.ts
 import { timingSafeEqual } from 'node:crypto'
-import { addTagMiddleware, pikkuMiddleware } from '../../.pikku/pikku-types.gen.js'
+import { addTagMiddleware, pikkuMiddleware } from '#pikku'
 import { UnauthorizedError } from '@pikku/core/errors'
 import { getToken } from '../lib/host-token.js'