@pikku/skills 0.12.9 → 0.12.11

package/skills/pikku-http/SKILL.md

@@ -38,7 +38,7 @@ Follow existing patterns you find (naming, tag usage, file organization). See `p
 
 ## API Reference
 
-All three come from `#pikku` (the generated `.pikku/pikku-types.gen.js`), which
+All three come from `#pikku/http` (the generated `.pikku/http/index.ts`), which
 binds them to your project's service, session and middleware types. The
 `@pikku/core/http` versions are the unbound generics — they compile, but you
 lose the typing that makes the wiring worth having.
@@ -59,7 +59,7 @@ addHTTPMiddleware('*', [authBearer()]) // All routes
 addHTTPMiddleware('/api/*', [rateLimit()]) // Pattern match
 ```
 
-> HTTP-route-level permissions (`addHTTPPermission`, a `permissions` field on the wiring) were removed in #972. Declare authorization on the function definition (`pikkuFunc({ permissions })`, see `pikku-permissions`), or app-wide via `addGlobalPermission`. Tags/patterns are for *middleware* only now.
+> HTTP-route-level permissions (`addHTTPPermission`, a `permissions` field on the wiring) were removed in #972. Declare authorization on the function definition (`pikkuFunc({ permissions })`, see `pikku-permissions`), or app-wide via `addGlobalPermission`. Tags/patterns are for _middleware_ only now.
 
 ## Data Flow
 
@@ -211,7 +211,7 @@ Functions live in their own files (one per file) and supply behavior + `permissi
 
 ```typescript
 // functions/books.functions.ts
-import { pikkuFunc, pikkuSessionlessFunc } from '#pikku'
+import { pikkuFunc, pikkuSessionlessFunc } from '#pikku/function'
 
 export const listBooks = pikkuSessionlessFunc({
   title: 'List Books',
@@ -226,7 +226,7 @@ export const getBook = pikkuFunc({
 })
 
 // wirings/books.http.ts — same defineHTTPRoutes/wireHTTPRoutes shape as the Route Groups example above
-import { addHTTPMiddleware } from '#pikku'
+import { addHTTPMiddleware } from '#pikku/http'
 import { cors, authBearer } from '@pikku/core/middleware'
 
 addHTTPMiddleware('*', [cors(), authBearer()])

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

@@ -4,19 +4,19 @@
 
 Wire a single function to an HTTP endpoint. Import from `#pikku`.
 
-| Option | Type | Notes |
-| --- | --- | --- |
-| `method` | `'get' \| 'post' \| 'put' \| 'patch' \| 'delete' \| 'head' \| 'options'` | 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 |
-| `middleware?` | `PikkuMiddleware[]` | Per-route middleware |
-| `sse?` | `boolean` | Enable Server-Sent Events — **`method: 'get'` only** |
-| `query?` | `Array<keyof In>` | **`method: 'post'` only** — input fields also read from the query string |
-| `contentType?` | `'xml' \| 'json'` | Response content type |
-| `timeout?` | `number` | Request timeout in ms |
-| `headers?` | `HTTPHeadersSchema` | Expected headers schema |
+| Option         | Type                                                                     | Notes                                                                    |
+| -------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
+| `method`       | `'get' \| 'post' \| 'put' \| 'patch' \| 'delete' \| 'head' \| 'options'` | 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                                       |
+| `middleware?`  | `PikkuMiddleware[]`                                                      | Per-route middleware                                                     |
+| `sse?`         | `boolean`                                                                | Enable Server-Sent Events — **`method: 'get'` only**                     |
+| `query?`       | `Array<keyof In>`                                                        | **`method: 'post'` only** — input fields also read from the query string |
+| `contentType?` | `'xml' \| 'json'`                                                        | Response content type                                                    |
+| `timeout?`     | `number`                                                                 | Request timeout in ms                                                    |
+| `headers?`     | `HTTPHeadersSchema`                                                      | Expected headers schema                                                  |
 
 `sse` and `query` are constrained by the config union rather than by a runtime
 check, so a `sse: true` on a `post` fails to typecheck rather than silently

package/skills/pikku-i18n/SKILL.md

@@ -142,7 +142,8 @@ The wrapper alternative — a module that walks the namespace and pipes each mes
 
   `packages/console` is the one place in this repo that still wraps it, in `src/i18n/messages.ts`, to keep the debug mask (`█`) it carried over from i18next. That wrapper is a leftover, not a pattern — the generated-locale approach above is how a new app gets the same masking without touching every export. Don't copy it.
 
-  The `mKey`/`mList` runtime resolvers that used to live beside it are **gone**, and must not come back. `mList` resolved indexed `prefix.0` keys that no longer exist; `mKey` took a computed string, which is exactly the type safety Paraglide exists to provide. Where a key really is dynamic, map the discriminant to a message *function* and call it — the map is type-checked, a string is not.
+  The `mKey`/`mList` runtime resolvers that used to live beside it are **gone**, and must not come back. `mList` resolved indexed `prefix.0` keys that no longer exist; `mKey` took a computed string, which is exactly the type safety Paraglide exists to provide. Where a key really is dynamic, map the discriminant to a message _function_ and call it — the map is type-checked, a string is not.
+
 - Don't re-resolve messages by string key or re-implement `{param}` interpolation. A key-string resolver turns a missing key back into silent runtime text, surrendering the type safety that is the entire reason to use Paraglide.
 - Don't reach for i18next/react-i18next or a runtime-fetch translation loader — Paraglide's compiled functions are the whole delivery mechanism.
 - Don't tokenize backend error messages or logs here — those are not frontend display strings.

package/skills/pikku-info/SKILL.md

@@ -29,7 +29,7 @@ Use the `pikku info` CLI commands to inspect this Pikku project. Run the command
 
 There are exactly four subcommands — `functions`, `tags`, `middleware`,
 `permissions`. Routes, channels, schedulers and queues are not separate
-subcommands; they show up as the *transport* column of `info functions --verbose`.
+subcommands; they show up as the _transport_ column of `info functions --verbose`.
 
 ## Available Commands
 

package/skills/pikku-knowledge/SKILL.md

@@ -66,7 +66,7 @@ Frontmatter fields:
 
 | Field         | Meaning                                                                                                                 |
 | ------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `type`        | **The only required field.** `slice`, `entity`, `decision`, `note`, `overview`. Lowercase — gates compare it literally. |
+| `type`        | **The only required field.** `slice` — or `milestone`, when the project's own `knowledge/index.md` names the section that way; `validate` accepts both, so follow the scaffold rather than this list. Then `entity`, `decision`, `note`, `overview`. Lowercase — gates compare it literally. |
 | `title`       | What to call the note in a listing. Falls back to the first heading, then the filename.                                 |
 | `description` | One line, used as the note's subtitle in a section index.                                                               |
 | `resource`    | Comma-separated `<kind>:<id>` URIs — the code this note is about. See below.                                            |
@@ -193,19 +193,19 @@ It is a **summary, not the note** — the argument continues in prose underneath
 
 **Every kind resolves.** That is the whole design: a kind that cannot be checked lets notes accumulate references nothing validates, and the graph rots into fiction exactly where it looks most authoritative.
 
-| Kind        | An id is                                           | Where it resolves                                                                 |
-| ----------- | -------------------------------------------------- | --------------------------------------------------------------------------------- |
-| `func:`     | a function id                                      | generated function meta                                                           |
-| `workflow:` | a workflow name                                    | generated workflow meta                                                           |
-| `schema:`   | a schema name                                      | generated schemas                                                                 |
-| `http:`     | a route, `method:route`, or the function behind it | generated http wirings                                                            |
-| `queue:`    | a queue name                                       | generated queue wirings                                                           |
-| `cron:`     | a scheduled task name                              | generated scheduler wirings                                                       |
-| `channel:`  | a channel name                                     | generated channel meta                                                            |
-| `table:`    | a table name                                       | the generated db schema                                                           |
-| `addon:`    | `@pikku/addon-x` or bare `x`                       | the manifests that declare the dependency                                         |
+| Kind        | An id is                                           | Where it resolves                                                                          |
+| ----------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `func:`     | a function id                                      | generated function meta                                                                    |
+| `workflow:` | a workflow name                                    | generated workflow meta                                                                    |
+| `schema:`   | a schema name                                      | generated schemas                                                                          |
+| `http:`     | a route, `method:route`, or the function behind it | generated http wirings                                                                     |
+| `queue:`    | a queue name                                       | generated queue wirings                                                                    |
+| `cron:`     | a scheduled task name                              | generated scheduler wirings                                                                |
+| `channel:`  | a channel name                                     | generated channel meta                                                                     |
+| `table:`    | a table name                                       | the generated db schema                                                                    |
+| `addon:`    | `@pikku/addon-x` or bare `x`                       | the manifests that declare the dependency                                                  |
 | `scope:`    | a scope name                                       | the `scopes:` a function gates itself with, plus the scopes a `defineSystemRole()` confers |
-| `persona:`  | a persona name                                     | `definePersonas()`                                                                |
+| `persona:`  | a persona name                                     | `definePersonas()`                                                                         |
 
 Ids are case-sensitive: `createEntry` is not `createentry`.
 

package/skills/pikku-kysely/SKILL.md

@@ -28,25 +28,29 @@ 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. 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).
+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'
 // Relation helpers are ENGINE-SPECIFIC — import the matching path:
-import { jsonArrayFrom, jsonObjectFrom } from 'kysely/helpers/sqlite'   // SQLite / libSQL
+import { jsonArrayFrom, jsonObjectFrom } from 'kysely/helpers/sqlite' // SQLite / libSQL
 // import { jsonArrayFrom, jsonObjectFrom } from 'kysely/helpers/postgres' // Postgres
 ```
 
 ```typescript
 // SELECT + where/orderBy/limit/offset. Terminals: .execute() | .executeTakeFirst()
 // | .executeTakeFirstOrThrow(() => new NotFoundError()) — pass an error factory.
-const rows = await kysely.selectFrom('item')
+const rows = await kysely
+  .selectFrom('item')
   .select(['id', 'name', 'quantity'])
   .where('warehouseId', '=', warehouseId)
-  .orderBy('name').limit(50).execute()
+  .orderBy('name')
+  .limit(50)
+  .execute()
 
 // JOINS + aliased selects (qualify columns once a join exists)
-await kysely.selectFrom('stock')
+await kysely
+  .selectFrom('stock')
   .innerJoin('item', 'item.id', 'stock.itemId')
   .leftJoin('bin as b', 'b.id', 'stock.binId')
   .select(['stock.id', 'item.name as itemName', 'b.code as binCode'])
@@ -54,41 +58,64 @@ await kysely.selectFrom('stock')
 
 // AGGREGATES via the fn helper + groupBy/having. eb.fn.count returns string|number —
 // cast if you need a JS number (SQLite: CAST(... AS INTEGER)).
-await kysely.selectFrom('stock')
+await kysely
+  .selectFrom('stock')
   .select((eb) => ['itemId', eb.fn.sum<number>('quantity').as('onHand')])
   .groupBy('itemId')
-  .having((eb) => eb.fn.sum('quantity'), '<', 10)   // low-stock
+  .having((eb) => eb.fn.sum('quantity'), '<', 10) // low-stock
   .execute()
 
 // INSERT + RETURNING (one round-trip; works on SQLite & Postgres)
-const created = await kysely.insertInto('item')
+const created = await kysely
+  .insertInto('item')
   .values({ name: input.name, warehouseId })
-  .returning(['id', 'name']).executeTakeFirstOrThrow()
+  .returning(['id', 'name'])
+  .executeTakeFirstOrThrow()
 
 // UPDATE + RETURNING, DELETE
-await kysely.updateTable('item').set({ quantity: input.quantity })
-  .where('id', '=', input.id).returning(['id', 'quantity']).executeTakeFirstOrThrow()
+await kysely
+  .updateTable('item')
+  .set({ quantity: input.quantity })
+  .where('id', '=', input.id)
+  .returning(['id', 'quantity'])
+  .executeTakeFirstOrThrow()
 await kysely.deleteFrom('item').where('id', '=', input.id).execute()
 
 // EXPRESSION BUILDER for and/or; $if for conditional building; sql for raw fragments
-await kysely.selectFrom('item')
+await kysely
+  .selectFrom('item')
   .selectAll()
   .where((eb) => eb.or([eb('quantity', '=', 0), eb('discontinued', '=', true)]))
   .$if(!!input.search, (qb) => qb.where('name', 'like', `%${input.search}%`))
-  .select(sql<number>`quantity * unit_cost`.as('value'))   // snake_case ok inside sql``
+  .select(sql<number>`quantity * unit_cost`.as('value')) // snake_case ok inside sql``
   .execute()
 
 // NESTED DATA (no relations) — jsonObjectFrom (one) / jsonArrayFrom (many)
-await kysely.selectFrom('warehouse')
-  .select((eb) => ['warehouse.id', 'warehouse.name',
-    jsonArrayFrom(eb.selectFrom('bin').select(['bin.id', 'bin.code'])
-      .whereRef('bin.warehouseId', '=', 'warehouse.id')).as('bins')])
+await kysely
+  .selectFrom('warehouse')
+  .select((eb) => [
+    'warehouse.id',
+    'warehouse.name',
+    jsonArrayFrom(
+      eb
+        .selectFrom('bin')
+        .select(['bin.id', 'bin.code'])
+        .whereRef('bin.warehouseId', '=', 'warehouse.id')
+    ).as('bins'),
+  ])
   .execute()
 
 // TRANSACTION — multi-write atomicity. Use trx (not kysely) inside.
 await kysely.transaction().execute(async (trx) => {
-  await trx.updateTable('stock').set({ quantity: 0 }).where('itemId', '=', id).execute()
-  await trx.insertInto('stockMove').values({ itemId: id, delta: -qty }).execute()
+  await trx
+    .updateTable('stock')
+    .set({ quantity: 0 })
+    .where('itemId', '=', id)
+    .execute()
+  await trx
+    .insertInto('stockMove')
+    .values({ itemId: id, delta: -qty })
+    .execute()
 })
 ```
 
@@ -151,10 +178,10 @@ import { createNodeSqliteKysely } from '@pikku/kysely-node-sqlite'
 
 // Your application DB — CamelCasePlugin on by default
 const kysely = createNodeSqliteKysely<DB>({
-  filename: 'app.db',       // or ':memory:'
+  filename: 'app.db', // or ':memory:'
   camelCase: true,
-  plugins: [],              // layered on top
-  functions: {},            // scalar UDFs, registered as deterministic (Node only)
+  plugins: [], // layered on top
+  functions: {}, // scalar UDFs, registered as deterministic (Node only)
 })
 ```
 
@@ -175,29 +202,29 @@ functions query.
 
 Each database variant exports these services with a prefix (`Pg`, `MySQL`, `SQLite`, or base `Kysely`):
 
-| Service               | Interface                             | Purpose                                        |
-| --------------------- | ------------------------------------- | ---------------------------------------------- |
-| `*ChannelStore`       | `ChannelStore`                        | WebSocket channel state persistence            |
-| `*EventHubStore`      | `EventHubStore`                       | Event hub state persistence                    |
-| `*WorkflowService`    | `PikkuWorkflowService`                | Workflow definition storage                    |
-| `*WorkflowRunService` | `WorkflowRunService`                  | Workflow execution tracking                    |
-| `*DeploymentService`  | `DeploymentService`                   | Deployment state management                    |
-| `*AIStorageService`   | `AIStorageService, AIRunStateService` | AI conversation/run storage                    |
-| `*AgentRunService`    | `AgentRunService`                     | Agent execution tracking                       |
-| `*SecretService`      | `SecretService`                       | Encrypted secret storage (envelope encryption) |
+| Service                | Interface                                   | Purpose                                        |
+| ---------------------- | ------------------------------------------- | ---------------------------------------------- |
+| `*ChannelStore`        | `ChannelStore`                              | WebSocket channel state persistence            |
+| `*EventHubStore`       | `EventHubStore`                             | Event hub state persistence                    |
+| `*WorkflowService`     | `PikkuWorkflowService`                      | Workflow definition storage                    |
+| `*WorkflowRunService`  | `WorkflowRunService`                        | Workflow execution tracking                    |
+| `*DeploymentService`   | `DeploymentService`                         | Deployment state management                    |
+| `*AgentStorageService` | `AgentStorageService, AgentRunStateService` | AI conversation/run storage                    |
+| `*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`)        |
+| Service                      | Purpose                                      |
+| ---------------------------- | -------------------------------------------- |
+| `KyselySessionStore`         | Persisted user sessions                      |
+| `KyselyScopeService`         | Scope and role storage                       |
+| `KyselyWebhookService`       | Webhook registrations and deliveries         |
+| `KyselyCredentialService`    | Encrypted third-party credentials            |
+| `KyselyAgentRunStateService` | 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.
 

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

@@ -16,10 +16,10 @@ description: >-
 Unified authentication for humans **and** machines against a Pikku + better-auth
 server. Two paths, two headers, one resolver:
 
-| Caller | Credential | Header | Obtained by |
-|---|---|---|---|
-| **Human** (CLI, dev) | better-auth session token | `Authorization: Bearer <token>` | `pikku login` (device flow) → `~/.pikku/session.json` |
-| **Machine** (agent, sandbox, worker) | scoped API key | `x-api-key: <key>` | `createApiKey` (server-side, at provision/spawn) |
+| Caller                               | Credential                | Header                          | Obtained by                                           |
+| ------------------------------------ | ------------------------- | ------------------------------- | ----------------------------------------------------- |
+| **Human** (CLI, dev)                 | better-auth session token | `Authorization: Bearer <token>` | `pikku login` (device flow) → `~/.pikku/session.json` |
+| **Machine** (agent, sandbox, worker) | scoped API key            | `x-api-key: <key>`              | `createApiKey` (server-side, at provision/spawn)      |
 
 Both resolve to a Pikku `UserSession` through one middleware:
 `betterAuthSession({ mapSession, apiKey: { mapKey } })`.
@@ -83,7 +83,7 @@ import { apiKey } from '@better-auth/api-key'
 betterAuth({
   plugins: [
     apiKey({
-      enableMetadata: true,          // REQUIRED to store scope on the key
+      enableMetadata: true, // REQUIRED to store scope on the key
       enableSessionForAPIKeys: true, // lets a key resolve via getSession too
     }),
   ],
@@ -104,10 +104,10 @@ one for a non-existent `userId` is created but will not resolve.
 // `auth` is the better-auth instance (injected service)
 const { key } = await auth.api.createApiKey({
   body: {
-    userId: sandboxRuntimeUserId,        // a stable service user
+    userId: sandboxRuntimeUserId, // a stable service user
     name: `sandbox:${sandboxId}`,
-    expiresIn: 60 * 60,                   // seconds
-    metadata: { sandboxId },             // keep only STABLE ids here
+    expiresIn: 60 * 60, // seconds
+    metadata: { sandboxId }, // keep only STABLE ids here
     permissions: { sandbox: ['read', 'write'] },
   },
 })
@@ -159,7 +159,7 @@ 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. 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
+_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
@@ -182,7 +182,7 @@ 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*
+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.

package/skills/pikku-mcp/SKILL.md

@@ -6,7 +6,7 @@ description: >-
   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).
+  pikku-agent) or general function definitions (use pikku-concepts).
 installGroups: [core]
 ---
 
@@ -37,11 +37,11 @@ See `pikku-concepts` for the core mental model.
 
 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>` |
+| 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
@@ -58,8 +58,8 @@ Add `mcp: true` to any existing function:
 
 ```typescript
 export const createTodo = pikkuFunc({
-  description: 'Create a new todo item',   // becomes the MCP tool description
-  input: CreateTodoInput,                  // becomes the MCP tool input schema
+  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 }),
@@ -74,7 +74,7 @@ returns MCP content blocks (`{ type: 'text', text }` or `{ type: 'image', data }
 with base64), so the assistant reads prose rather than raw JSON:
 
 ```typescript
-import { pikkuMCPToolFunc } from '#pikku'
+import { pikkuMCPToolFunc } from '#pikku/mcp'
 
 export const createTodoTool = pikkuMCPToolFunc({
   description: 'Create a todo item with title, priority, due date and tags',
@@ -96,7 +96,7 @@ presentation layer over logic that is already tested and reachable over HTTP.
 ### Resources
 
 ```typescript
-import { pikkuMCPResourceFunc } from '#pikku'
+import { pikkuMCPResourceFunc } from '#pikku/mcp'
 
 export const getTodoResource = pikkuMCPResourceFunc<{ id: string }>(
   async (_services, { id }, { rpc, mcp }) => {
@@ -117,7 +117,7 @@ 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
-import { wireMCPResource } from '#pikku'
+import { wireMCPResource } from '#pikku/mcp'
 
 wireMCPResource({
   uri: 'todos/{id}', // URI template
@@ -136,12 +136,15 @@ than handing the function an `undefined`.
 ### Prompts
 
 ```typescript
-import { pikkuMCPPromptFunc, wireMCPPrompt } from '#pikku'
+import { pikkuMCPPromptFunc, wireMCPPrompt } from '#pikku/mcp'
 
 export const planDayPrompt = pikkuMCPPromptFunc({
   input: UserIdInputSchema,
   func: async (_services, { userId }, { rpc }) => {
-    const { todos } = await rpc.invoke('listTodos', { userId, completed: false })
+    const { todos } = await rpc.invoke('listTodos', {
+      userId,
+      completed: false,
+    })
     return [
       {
         role: 'user' as const,
@@ -242,10 +245,10 @@ anything logs.
 
 ## Red flags
 
-| 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()` |
+| 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

@@ -23,7 +23,7 @@ installGroups: [core]
 ## The `pikkuMiddleware` Factory
 
 ```typescript
-import { pikkuMiddleware } from '#pikku'
+import { pikkuMiddleware } from '#pikku/function'
 
 // Simple: just a function
 const myMiddleware = pikkuMiddleware(async (services, wire, next) => {
@@ -48,12 +48,13 @@ const telemetryMiddleware = pikkuMiddleware({
 ```
 
 The `wire` object gives you:
+
 - `wire.http` — inbound HTTP context (headers, URL, cookies)
 - `wire.setSession(session)` — set the session for this request
 - `wire.getSession()` — read the current session
 - `wire.session` — the session set so far (may be undefined)
 
-Throw a typed error to abort: `UnauthorizedError`, `ForbiddenError`, etc. from `@pikku/core/errors`.
+Throw a typed error to abort: `UnauthorizedError`, `ForbiddenError`, etc. from `#pikku/error`.
 
 ## Scoping: Five Levels
 
@@ -70,7 +71,7 @@ addHTTPMiddleware('*', [cors(), authBearer()])
 addHTTPMiddleware('/admin/*', [auditLog])
 
 // 4. Tag-based: any wiring with matching tag
-addTagMiddleware('machine-agent', [bearerAuth])  // tag on function or wire
+addTagMiddleware('machine-agent', [bearerAuth]) // tag on function or wire
 
 // 5. Inline: per-wiring
 wireHTTP({
@@ -88,8 +89,8 @@ Runs before everything else, across every wire type: HTTP, Queue, Channel, Trigg
 import { addGlobalMiddleware } from '@pikku/core'
 import { telemetryOuter, telemetryInner } from '@pikku/core/middleware'
 
-addGlobalMiddleware([telemetryOuter({ environmentId: env.STAGE_ID })])  // wraps the full call
-addGlobalMiddleware([telemetryInner({ environmentId: env.STAGE_ID })])  // closest to the function body
+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'`, `telemetryInner` with `priority: 'lowest'` — so priority sorting places outer first regardless of array/call order.
@@ -101,7 +102,9 @@ import { addHTTPMiddleware } from '@pikku/core/http'
 import { cors, authBearer } from '@pikku/core/middleware'
 
 // All routes
-addHTTPMiddleware('*', [cors({ origin: 'https://app.example.com', credentials: true })])
+addHTTPMiddleware('*', [
+  cors({ origin: 'https://app.example.com', credentials: true }),
+])
 
 // Scoped to /api/* prefix
 addHTTPMiddleware('/api/*', [rateLimit({ maxRequests: 100, windowMs: 60_000 })])
@@ -136,7 +139,7 @@ Tags from the function definition and the wire object are merged — middleware
 ### Registering Tag Middleware
 
 ```typescript
-import { addTagMiddleware } from '#pikku'
+import { addTagMiddleware } from '#pikku/function'
 
 addTagMiddleware('machine-agent', [machineAgentBearerAuth])
 ```
@@ -161,7 +164,7 @@ 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
+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.
 
@@ -190,19 +193,23 @@ A server that exposes RPCs only to a trusted caller (e.g. an API calling a machi
 ```typescript
 // lib/host-token.ts
 let _token: string | null = null
-export const setToken = (t: string) => { _token = t }
+export const setToken = (t: string) => {
+  _token = t
+}
 export const getToken = () => _token
 ```
 
 ```typescript
 // wirings/http.wiring.ts
 import { timingSafeEqual } from 'node:crypto'
-import { addTagMiddleware, pikkuMiddleware } from '#pikku'
-import { UnauthorizedError } from '@pikku/core/errors'
+import { addTagMiddleware, pikkuMiddleware } from '#pikku/function'
+import { UnauthorizedError } from '#pikku/error'
 import { getToken } from '../lib/host-token.js'
 
 const bearerAuth = pikkuMiddleware(async (_services, { http }, next) => {
-  const authHeader = http?.request?.header?.('authorization') || http?.request?.header?.('Authorization')
+  const authHeader =
+    http?.request?.header?.('authorization') ||
+    http?.request?.header?.('Authorization')
   const token = getToken()
   const expected = token ? `Bearer ${token}` : null
   if (

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

@@ -31,17 +31,23 @@ export function getServiceRPC(baseUrl: string, token: string): RPCInvoke {
 ## Session-Setting Middleware
 
 ```typescript
-const apiKeyAuth = pikkuMiddleware(async ({ kysely }, { http, setSession, session }, next) => {
-  if (session) return next()  // already authenticated
+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 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 })
+    const row = await kysely
+      .selectFrom('apiKey')
+      .select('userId')
+      .where('key', '=', header)
+      .executeTakeFirst()
+    if (row) setSession?.({ userId: row.userId })
 
-  return next()
-})
+    return next()
+  }
+)
 
 addTagMiddleware('api-key-auth', [apiKeyAuth])
 ```