@pikku/skills 0.12.9 → 0.12.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.9",
+  "version": "0.12.11",
   "description": "The Pikku agent skills — the instruction set coding agents read to build, wire and deploy Pikku projects",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
@@ -26,11 +26,11 @@
     "skills"
   ],
   "devDependencies": {
-    "@types/node": "^24.11.0",
+    "@types/node": "^24.13.3",
     "typescript": "^6.0.3",
-    "yaml": "^2.8.2"
+    "yaml": "^2.9.0"
   },
   "engines": {
     "node": ">=24"
   }
-}
+}

package/skills/pikku-addon/SKILL.md

@@ -40,7 +40,7 @@ See `pikku-concepts` for the core mental model.
 Register an addon in the consuming project:
 
 ```typescript
-import { wireAddon } from '#pikku'
+import { wireAddon } from '#pikku/addon'
 
 wireAddon({
   name: string,                    // Namespace for addon functions (e.g. 'todos')
@@ -123,7 +123,7 @@ Type-safe reference to a function — local or addon — for use in any wiring.
 returns a function config that proxies the call via RPC at runtime:
 
 ```typescript
-import { ref } from '#pikku'
+import { ref } from '#pikku/function'
 
 ref('todos:addTodo') // namespace:functionName for an addon function
 ref('myLocalFunc') // a local function by name
@@ -134,7 +134,7 @@ There is no `addon()` helper; `ref()` covers both. For an addon that publishes
 `refChannel` and `refCLI`, which carry the addon's own route/config metadata:
 
 ```typescript
-import { refHTTP } from '#pikku'
+import { refHTTP } from '#pikku/function'
 
 wireHTTP(refHTTP('todos:listTodos', { basePath: '/api' }))
 ```
@@ -146,7 +146,7 @@ second argument is always present — an addon never falls back to its own logge
 variables or secrets; the consuming app supplies them:
 
 ```typescript
-import { pikkuAddonServices } from '#pikku'
+import { pikkuAddonServices } from '#pikku/addon/setup'
 
 export const createSingletonServices = pikkuAddonServices(
   async (config, { secrets, logger }) => {
@@ -167,7 +167,7 @@ config object.
 Define per-request services for an addon package (created fresh per HTTP request, queue job, etc.):
 
 ```typescript
-import { pikkuAddonWireServices } from '#pikku'
+import { pikkuAddonWireServices } from '#pikku/addon/setup'
 
 export const createWireServices = pikkuAddonWireServices(
   async (singletonServices, wire) => {
@@ -195,7 +195,7 @@ This generates `package.json` (exports `.pikku/*` + `dist/`), `pikku.config.json
 
 ```typescript
 // src/services.ts
-import { pikkuAddonServices, pikkuAddonWireServices } from '#pikku'
+import { pikkuAddonServices, pikkuAddonWireServices } from '#pikku/addon/setup'
 import { TodoStore } from './todo-store.service.js'
 
 export const createSingletonServices = pikkuAddonServices(async () => {
@@ -213,10 +213,14 @@ export const createWireServices = pikkuAddonWireServices(
 
 ### Functions
 
+An addon generates its whole tree under `#pikku/addon/*`, so it authors against
+`#pikku/addon/function`, `#pikku/addon/http` and so on. An application's leaves
+stay flat, which is what stops a linked addon resolving against its host.
+
 ```typescript
 // src/functions/addTodo.function.ts
 import { z } from 'zod'
-import { pikkuSessionlessFunc } from '#pikku'
+import { pikkuSessionlessFunc } from '#pikku/addon/function'
 
 const AddTodoInput = z.object({ title: z.string() })
 const AddTodoOutput = z.object({ id: z.string(), title: z.string() })
@@ -269,7 +273,7 @@ yarn add @my-org/addon-todos
 
 ```typescript
 // wirings/todos.wirings.ts
-import { wireAddon } from '#pikku'
+import { wireAddon } from '#pikku/addon'
 
 wireAddon({ name: 'todos', package: '@my-org/addon-todos' })
 ```
@@ -290,7 +294,8 @@ export const myFunc = pikkuFunc({
 ### Wire to HTTP
 
 ```typescript
-import { wireHTTP, ref } from '#pikku'
+import { wireHTTP } from '#pikku/http'
+import { ref } from '#pikku/function'
 
 wireHTTP({
   method: 'get',
@@ -303,7 +308,8 @@ wireHTTP({
 Or batch multiple addon routes with `defineHTTPRoutes` + `wireHTTPRoutes`:
 
 ```typescript
-import { wireHTTPRoutes, defineHTTPRoutes, ref } from '#pikku'
+import { wireHTTPRoutes, defineHTTPRoutes } from '#pikku/http'
+import { ref } from '#pikku/function'
 
 const todoRoutes = defineHTTPRoutes({
   tags: ['todos'],
@@ -320,10 +326,10 @@ wireHTTPRoutes({ basePath: '/api', routes: { todos: todoRoutes } })
 ### Use in AI Agents
 
 ```typescript
-import { pikkuAIAgent } from '#pikku/agent/pikku-agent-types.gen.js'
-import { ref } from '#pikku'
+import { pikkuAgent } from '#pikku/agent/pikku-agent-types.gen.js'
+import { ref } from '#pikku/function'
 
-export const todoAgent = pikkuAIAgent({
+export const todoAgent = pikkuAgent({
   name: 'todo-agent',
   description: 'Manages a todo list',
   goal: 'You help users manage their todos.',
@@ -337,4 +343,4 @@ export const todoAgent = pikkuAIAgent({
 })
 ```
 
-See `pikku-ai-agent` — an addon function is just another `ref()` in `tools`.
+See `pikku-agent` — an addon function is just another `ref()` in `tools`.

package/skills/pikku-addon/references/addon-package-manifest.md

@@ -40,8 +40,8 @@ my-addon/
 {
   "name": "@my-org/addon-todos",
   "imports": {
-    "#pikku": "./.pikku/pikku-types.gen.ts",
-    "#pikku/*": "./.pikku/*"
+    "#pikku/*.js": "./.pikku/*.ts",
+    "#pikku/*": "./.pikku/*/index.ts"
   },
   "exports": {
     ".": { "types": "./dist/src/index.d.ts", "import": "./dist/src/index.js" },

package/skills/{pikku-ai-agent → pikku-agent}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: pikku-ai-agent
+name: pikku-agent
 description: >-
   Use when building AI agents, chatbots, or LLM-powered assistants with Pikku. Covers
-  pikkuAIAgent, ref() tool registration, memory, streaming, tool approval, thread ownership, and
-  invocation via rpc.agent. TRIGGER when: code uses pikkuAIAgent/rpc.agent/runAIAgent/
-  streamAIAgent, user asks about AI agents, chatbots, LLM assistants, tool-calling agents, agent
+  pikkuAgent, ref() tool registration, memory, streaming, tool approval, thread ownership, and
+  invocation via rpc.agent. TRIGGER when: code uses pikkuAgent/rpc.agent/runAgent/
+  streamAgent, user asks about AI agents, chatbots, LLM assistants, tool-calling agents, agent
   memory/streaming, or `pikku enable agent`. DO NOT TRIGGER when: user asks about MCP tool
   exposure (use pikku-mcp) or general function definitions (use pikku-concepts).
 installGroups: [core]
@@ -35,15 +35,15 @@ See `pikku-concepts` for the core mental model.
 
 ## API Reference
 
-### `pikkuAIAgent(config)`
+### `pikkuAgent(config)`
 
 Import it from the generated agent types file — `#pikku` does not re-export it:
 
 ```typescript
-import { pikkuAIAgent } from '#pikku/agent/pikku-agent-types.gen.js'
-import { ref } from '#pikku/pikku-types.gen.js'
+import { pikkuAgent } from '#pikku/agent/pikku-agent-types.gen.js'
+import { ref } from '#pikku/function'
 
-pikkuAIAgent({
+pikkuAgent({
   name: string,                  // Unique agent identifier
   description: string,           // What the agent does (shown in agent listings)
   summary?: string,
@@ -67,7 +67,7 @@ pikkuAIAgent({
   agentMode?: 'delegate' | 'supervise',
 
   memory?: {
-    storage?: string,            // Service name for persistence (e.g. 'aiStorage')
+    storage?: string,            // Service name for persistence (e.g. 'agentStorage')
     vector?: string,             // Vector store service name
     embedder?: string,           // Embedding service name
     lastMessages?: number,       // How many messages to retain in context
@@ -88,7 +88,7 @@ pikkuAIAgent({
 
   middleware?: PikkuMiddleware[],
   channelMiddleware?: PikkuChannelMiddleware[],
-  aiMiddleware?: PikkuAIMiddlewareHooks[],
+  agentMiddleware?: PikkuAgentMiddlewareHooks[],
 })
 ```
 
@@ -140,15 +140,15 @@ asking the user for identifiers it could have been handed.
 }
 ```
 
-`runAIAgent` / `streamAIAgent` from `@pikku/core/ai-agent` are the layer beneath
-this. Their third argument is `RunAIAgentParams` (`{ sessionService?,
+`runAgent` / `streamAgent` from `@pikku/core/agent` are the layer beneath
+this. Their third argument is `RunAgentParams` (`{ sessionService?,
 getCredential?, anonymousOwnerResourceId? }`) — **not** `{ singletonServices }`.
 Reach for them only outside a wired function; inside one, `rpc.agent` is the
 supported path.
 
 ### Stream events
 
-`rpc.agent.stream` pushes `AIStreamEvent`s onto the channel:
+`rpc.agent.stream` pushes `AgentStreamEvent`s onto the channel:
 
 ```typescript
 // { type: 'step-start', stepNumber }
@@ -178,10 +178,10 @@ than folding it into the parent's transcript.
 ### Define an Agent
 
 ```typescript
-import { pikkuAIAgent } from '#pikku/agent/pikku-agent-types.gen.js'
-import { ref } from '#pikku/pikku-types.gen.js'
+import { pikkuAgent } from '#pikku/agent/pikku-agent-types.gen.js'
+import { ref } from '#pikku/function'
 
-export const todoAgent = pikkuAIAgent({
+export const todoAgent = pikkuAgent({
   name: 'todo-agent',
   description: 'Manages a todo list',
   goal: 'You help users manage their todos. You can list, add, complete and delete them.',
@@ -192,7 +192,7 @@ export const todoAgent = pikkuAIAgent({
     ref('todos:completeTodo'),
     ref('graph:sleep'),
   ],
-  memory: { storage: 'aiStorage', lastMessages: 20 },
+  memory: { storage: 'agentStorage', lastMessages: 20 },
   maxSteps: 10,
   toolChoice: 'auto',
 })
@@ -216,7 +216,7 @@ tools** — with a tool present the runner falls back to free text, silently. If
 you need both, split the classification into its own tool-free agent.
 
 ```typescript
-export const structuredAgent = pikkuAIAgent({
+export const structuredAgent = pikkuAgent({
   name: 'structured-agent',
   description: 'Classifies a message and returns a structured verdict',
   goal: 'You classify the sentiment of the user message.',
@@ -234,14 +234,14 @@ rather than signalling that it was short-circuited.
 
 ```typescript
 prepareStep: ({ stepNumber, tools }) => {
-  if (stepNumber >= 1) tools.length = 0   // withdraw tools after the first step
+  if (stepNumber >= 1) tools.length = 0 // withdraw tools after the first step
 }
 ```
 
 ### Tool approval
 
 A tool that should pause for a human sets `approvalRequired: true` (with an
-optional `approvalDescription`) on the *function*, not on the agent. The run then
+optional `approvalDescription`) on the _function_, not on the agent. The run then
 resolves with `status: 'suspended'` and `pendingApprovals`, and streaming emits
 `approval-request`. Answer with `rpc.agent.approve(runId, approvals)`.
 
@@ -282,10 +282,10 @@ export const completeTodo = pikkuFunc({
 })
 
 // agents/todo-assistant.agent.ts
-import { pikkuAIAgent } from '#pikku/agent/pikku-agent-types.gen.js'
-import { ref } from '#pikku/pikku-types.gen.js'
+import { pikkuAgent } from '#pikku/agent/pikku-agent-types.gen.js'
+import { ref } from '#pikku/function'
 
-export const todoAssistant = pikkuAIAgent({
+export const todoAssistant = pikkuAgent({
   name: 'todo-assistant',
   description: 'A helpful assistant that manages todos',
   role: 'You are an assistant that manages a user’s todo list.',
@@ -299,7 +299,7 @@ export const todoAssistant = pikkuAIAgent({
     ref('todos:createTodo'),
     ref('todos:completeTodo'),
   ],
-  memory: { storage: 'aiStorage', lastMessages: 20 },
+  memory: { storage: 'agentStorage', lastMessages: 20 },
   maxSteps: 5,
   temperature: 0.7,
 })

package/skills/pikku-ai-vercel/SKILL.md

@@ -2,9 +2,9 @@
 name: pikku-ai-vercel
 description: >-
   Use when setting up AI agent execution with the Vercel AI SDK in a Pikku app. Covers
-  VercelAIAgentRunner for streaming and non-streaming AI agent steps. TRIGGER when: code uses
-  VercelAIAgentRunner, user asks about Vercel AI SDK integration, AI agent runners, or
-  @pikku/ai-vercel. DO NOT TRIGGER when: user asks about AI agent wiring (use pikku-ai-agent) or
+  VercelAgentRunner for streaming and non-streaming AI agent steps. TRIGGER when: code uses
+  VercelAgentRunner, user asks about Vercel AI SDK integration, AI agent runners, or
+  @pikku/ai-vercel. DO NOT TRIGGER when: user asks about AI agent wiring (use pikku-agent) or
   voice I/O (use pikku-ai-voice).
 installGroups: [core]
 ---
@@ -21,7 +21,7 @@ Use this skill as an execution checklist, not reference material.
 4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
 5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
 
-`@pikku/ai-vercel` provides an AI agent runner backed by the [Vercel AI SDK](https://sdk.vercel.ai/). Implements `AIAgentRunnerService` from `@pikku/core`.
+`@pikku/ai-vercel` provides an AI agent runner backed by the [Vercel AI SDK](https://sdk.vercel.ai/). Implements `AgentRunnerService` from `@pikku/core`.
 
 ## Installation
 
@@ -31,12 +31,12 @@ yarn add @pikku/ai-vercel ai @ai-sdk/openai  # or any AI SDK provider
 
 ## API Reference
 
-### `VercelAIAgentRunner`
+### `VercelAgentRunner`
 
 ```typescript
-import { VercelAIAgentRunner } from '@pikku/ai-vercel'
+import { VercelAgentRunner } from '@pikku/ai-vercel'
 
-const runner = new VercelAIAgentRunner(
+const runner = new VercelAgentRunner(
   providers: Record<string, any>,                    // provider name → AI SDK provider
   providerFactory?: (apiKey: string) => Record<string, any>,
   allowedAttachmentHosts?: string[]
@@ -45,8 +45,8 @@ const runner = new VercelAIAgentRunner(
 
 **Methods:**
 
-- `stream(params: AIAgentRunnerParams, channel: AIStreamChannel): Promise<AIAgentStepResult>` — Stream AI responses with tool calls
-- `run(params: AIAgentRunnerParams): Promise<AIAgentStepResult>` — Execute a single AI step (non-streaming)
+- `stream(params: AgentRunnerParams, channel: AgentStreamChannel): Promise<AgentStepResult>` — Stream AI responses with tool calls
+- `run(params: AgentRunnerParams): Promise<AgentStepResult>` — Execute a single AI step (non-streaming)
 - `transcribe({ model, audio, … })` / `generateSpeech({ model, text, voice, … })` — what `voiceInput`/`voiceOutput` call; see `pikku-ai-voice`
 - `generateImage`, `embed`, `embedMany`, `rerank` — the remaining AI SDK surfaces
 - `withApiKey(apiKey)` — returns a **new** runner built from `providerFactory`; returns `this` unchanged when no factory was supplied or the key is blank. This is the per-user-credential path
@@ -75,7 +75,7 @@ gateway-routed providers after construction.
 ### Basic Setup
 
 ```typescript
-import { VercelAIAgentRunner } from '@pikku/ai-vercel'
+import { VercelAgentRunner } from '@pikku/ai-vercel'
 import { createOpenAI } from '@ai-sdk/openai'
 import { createAnthropic } from '@ai-sdk/anthropic'
 
@@ -86,19 +86,19 @@ const createSingletonServices = pikkuServices(async (config, { secrets }) => {
       apiKey: (await secrets.getSecret('OPENAI_API_KEY')).reveal(),
     })
   }
-  return { config, aiAgentRunner: new VercelAIAgentRunner(providers) }
+  return { config, agentRunner: new VercelAgentRunner(providers) }
 })
 ```
 
-The service key is **`aiAgentRunner`** — that is the name the agent wiring looks
+The service key is **`agentRunner`** — that is the name the agent wiring looks
 up. Registering it as `aiRunner` leaves every agent unable to call a model.
 
 ### With an agent
 
 ```typescript
-import { pikkuAIAgent } from '#pikku/agent/pikku-agent-types.gen.js'
+import { pikkuAgent } from '#pikku/agent/pikku-agent-types.gen.js'
 
-export const assistant = pikkuAIAgent({
+export const assistant = pikkuAgent({
   name: 'assistant',
   description: 'Answers questions',
   goal: 'You are a helpful assistant.',
@@ -106,16 +106,16 @@ export const assistant = pikkuAIAgent({
 })
 ```
 
-There is no `wireAIAgent` — agents are declared with `pikkuAIAgent` from the
-generated agent types. See `pikku-ai-agent` for the full config.
+There is no `wireAgent` — agents are declared with `pikkuAgent` from the
+generated agent types. See `pikku-agent` for the full config.
 
 ### Testing without a real provider
 
-Replacing the *provider* rather than the runner keeps every code path under test
+Replacing the _provider_ rather than the runner keeps every code path under test
 real — tool loop, streaming, memory, approvals — and only scripts the replies.
 Sealing it with `'*'` means no model string, including ones added later, can
 reach a live endpoint:
 
 ```typescript
-new VercelAIAgentRunner({ '*': createMockLlmProvider() })
+new VercelAgentRunner({ '*': createMockLlmProvider() })
 ```

package/skills/pikku-ai-voice/SKILL.md

@@ -2,10 +2,10 @@
 name: pikku-ai-voice
 description: >-
   Use when adding voice input (speech-to-text) or voice output (text-to-speech) to AI agents in a
-  Pikku app. Covers the voiceInput/voiceOutput AI middleware from @pikku/core/ai-agent, per-script
+  Pikku app. Covers the voiceInput/voiceOutput AI middleware from @pikku/core/agent, per-script
   voices, and barge-in. TRIGGER when: code uses voiceInput, voiceOutput, or user asks about voice
   agents, speech-to-text, text-to-speech, transcription, or @pikku/ai-voice. DO NOT TRIGGER when:
-  user asks about AI agent wiring generally (use pikku-ai-agent) or the runner itself (use
+  user asks about AI agent wiring generally (use pikku-agent) or the runner itself (use
   pikku-ai-vercel).
 ---
 
@@ -27,14 +27,14 @@ The package still publishes, but its entire source is `export {}` — there are
 `STTService`/`TTSService` interfaces and nothing to import. Do not add it as a
 dependency.
 
-Voice now lives in **`@pikku/core/ai-agent`** as two AI middlewares, and the
-speech models are reached through the `aiAgentRunner` (`transcribe` /
+Voice now lives in **`@pikku/core/agent`** as two AI middlewares, and the
+speech models are reached through the `agentRunner` (`transcribe` /
 `generateSpeech`) rather than through separate services. See `pikku-ai-vercel`.
 
 ## API Reference
 
 ```typescript
-import { voiceInput, voiceOutput } from '@pikku/core/ai-agent'
+import { voiceInput, voiceOutput } from '@pikku/core/agent'
 
 voiceInput(config?: {
   model?: string               // transcription model — required in practice
@@ -54,9 +54,9 @@ voiceOutput(config?: {
 })
 ```
 
-Both attach through the agent's **`aiMiddleware`** array, not a
-`middlewareHooks` option, and the agent is declared with `pikkuAIAgent` — there
-is no `wireAIAgent`.
+Both attach through the agent's **`agentMiddleware`** array, not a
+`middlewareHooks` option, and the agent is declared with `pikkuAgent` — there
+is no `wireAgent`.
 
 ### `voiceInput` — audio in, text in its place
 
@@ -74,7 +74,7 @@ spoken, which is why it records two shared-notes keys on the way past:
 
 Behaviours that decide how a voice loop should be written:
 
-- **It is a no-op without `aiAgentRunner.transcribe`** — no error, the audio
+- **It is a no-op without `agentRunner.transcribe`** — no error, the audio
   simply passes through untouched.
 - **`config.model` is required once audio actually arrives**, and throws then
   rather than at wiring time.
@@ -84,7 +84,7 @@ Behaviours that decide how a voice loop should be written:
   distinct from a transcription failure, which is worth reporting.
 - **Non-speech means an empty transcript, and nothing cleverer.** There was a
   per-segment confidence gate here and it was removed: Whisper is
-  subtitle-trained, so it is *confident* when it invents ("Thank you." scored
+  subtitle-trained, so it is _confident_ when it invents ("Thank you." scored
   better than the real sentence beside it). Pick an ASR that returns an empty
   string on silence rather than trying to filter one that doesn't.
 - Audio arrives either inline (base64 `data`) or as a `url` fetched through
@@ -112,7 +112,7 @@ awaits the chain, and emits `audio-done` before the `done` event.
 ### `speakableScripts` — declare what the model can pronounce
 
 Handed a script it has no voice for, a speech model typically neither fails nor
-stays quiet: Kokoro reads out the *letter names* — 24 seconds of "Arabic meem,
+stays quiet: Kokoro reads out the _letter names_ — 24 seconds of "Arabic meem,
 Arabic ra" for a one-line sentence. Declaring the range leaves anything outside
 it unspoken and reports it once per reply as a `voice-unsupported` data event.
 
@@ -133,15 +133,15 @@ fallback)` are exported if you need the same decision outside the middleware.
 ## Usage Pattern
 
 ```typescript
-import { pikkuAIAgent } from '#pikku/agent/pikku-agent-types.gen.js'
-import { voiceInput, voiceOutput } from '@pikku/core/ai-agent'
+import { pikkuAgent } from '#pikku/agent/pikku-agent-types.gen.js'
+import { voiceInput, voiceOutput } from '@pikku/core/agent'
 
-export const voiceAssistant = pikkuAIAgent({
+export const voiceAssistant = pikkuAgent({
   name: 'voice-assistant',
   description: 'Holds a spoken conversation',
   goal: 'You are a voice assistant. You are being listened to, not read.',
   model: 'openai/gpt-5-mini',
-  aiMiddleware: [
+  agentMiddleware: [
     voiceInput({ model: 'deepinfra/openai/whisper-large-v3-turbo' }),
     voiceOutput({
       model: 'deepinfra/hexgrad/Kokoro-82M',

package/skills/pikku-audit/SKILL.md

@@ -38,11 +38,13 @@ An event only persists when the function opts in with **`audit: true`** — othe
 ```typescript
 import { NoopAuditService, createInvocationAudit } from '@pikku/core/services'
 
-export const createSingletonServices = pikkuServices(async (config, existing) => {
-  // Prod platforms may inject a queue-backed sink as existing.audit.
-  const audit = existing?.audit ?? new NoopAuditService()
-  return { ...existing, config, /* ... */ audit }
-})
+export const createSingletonServices = pikkuServices(
+  async (config, existing) => {
+    // Prod platforms may inject a queue-backed sink as existing.audit.
+    const audit = existing?.audit ?? new NoopAuditService()
+    return { ...existing, config, /* ... */ audit }
+  }
+)
 
 // auditLog is created per invocation from the sink. Returned unconditionally so
 // a write from a function that forgot `audit: true` warns instead of vanishing.
@@ -67,12 +69,17 @@ Mark the function `audit: true` and call `auditLog?.write(...)`. Domain history
 
 ```typescript
 export const cancelInvoice = pikkuFunc({
-  audit: true,                       // REQUIRED — else write() is a no-op
+  audit: true, // REQUIRED — else write() is a no-op
   input: CancelInvoiceInput,
   output: CancelInvoiceOutput,
   func: async ({ kysely, auditLog }, { invoiceId }, { session }) => {
-    const inv = await kysely.selectFrom('invoice')/* ... */.executeTakeFirstOrThrow()
-    await kysely.updateTable('invoice').set({ status: 'cancelled' })/* ... */.execute()
+    const inv = await kysely
+      .selectFrom('invoice') /* ... */
+      .executeTakeFirstOrThrow()
+    await kysely
+      .updateTable('invoice')
+      .set({ status: 'cancelled' }) /* ... */
+      .execute()
 
     await auditLog?.write({
       type: 'invoice.update',
@@ -108,7 +115,10 @@ import { createAuditedKysely } from '@pikku/kysely'
 export const createWireServices = pikkuWireServices(async (services, wire) => {
   if (!services.audit) return {}
   const auditLog = createInvocationAudit(services.audit, wire)
-  return { auditLog, kysely: createAuditedKysely(services.kysely, { audit: auditLog }) }
+  return {
+    auditLog,
+    kysely: createAuditedKysely(services.kysely, { audit: auditLog }),
+  }
 })
 ```
 
@@ -172,15 +182,20 @@ const rows = await kysely
 
 ```typescript
 type AuditEvent = {
-  type: string                          // e.g. 'invoice.update'
+  type: string // e.g. 'invoice.update'
   source: 'auto' | 'explicit'
-  occurredAt: string                    // auto-filled by auditLog
+  occurredAt: string // auto-filled by auditLog
   eventId?: string
   outcome?: 'success' | 'failed' | 'denied'
-  functionId?; wireType?; wireId?; traceId?; transactionId?; queryId?  // auto
+  functionId?
+  wireType?
+  wireId?
+  traceId?
+  transactionId?
+  queryId? // auto
   userIdentity?: { userId?; orgId?; pikkuUserId? } // auto from wire session
   input?: unknown
-  metadata?: Record<string, unknown>    // your domain payload
+  metadata?: Record<string, unknown> // your domain payload
 }
 ```
 

package/skills/pikku-aws/SKILL.md

@@ -64,12 +64,12 @@ provision an S3 bucket per logical bucket — the config takes only one.
 
 ### Behaviours worth knowing before you rely on them
 
-- **`signURL` fails open.** A signing error is logged and the *unsigned* URL is
+- **`signURL` fails open.** A signing error is logged and the _unsigned_ URL is
   returned rather than thrown. If your CloudFront distribution is private the
   client then gets a 403; if it isn't, you have just handed out an unrestricted
   link. Check that `signConfig` is a valid CloudFront key pair at boot.
 - **`signContentKey` builds `https://<bucketName>/<bucket>/<contentKey>`** — it
-  uses `bucketName` as the *host*. For signed content the value must therefore be
+  uses `bucketName` as the _host_. For signed content the value must therefore be
   your CloudFront domain, not a plain bucket name, which also means the same
   config field is doing two jobs.
 - **Presigned upload URLs expire after a fixed 3600s.** It is not configurable