@pikku/skills 0.12.9 → 0.12.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.9",
+  "version": "0.12.10",
   "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",

package/skills/pikku-addon/SKILL.md

@@ -320,10 +320,10 @@ wireHTTPRoutes({ basePath: '/api', routes: { todos: todoRoutes } })
 ### Use in AI Agents
 
 ```typescript
-import { pikkuAIAgent } from '#pikku/agent/pikku-agent-types.gen.js'
+import { pikkuAgent } from '#pikku/agent/pikku-agent-types.gen.js'
 import { ref } from '#pikku'
 
-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 +337,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-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 { pikkuAgent } from '#pikku/agent/pikku-agent-types.gen.js'
 import { ref } from '#pikku/pikku-types.gen.js'
 
-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 { pikkuAgent } from '#pikku/agent/pikku-agent-types.gen.js'
 import { ref } from '#pikku/pikku-types.gen.js'
 
-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 { pikkuAgent } from '#pikku/agent/pikku-agent-types.gen.js'
 import { ref } from '#pikku/pikku-types.gen.js'
 
-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-concepts/SKILL.md

@@ -27,7 +27,7 @@ Pikku is a TypeScript framework that separates business logic from transport mec
 
 For deep-dive on each topic, see the dedicated skills:
 
-- **Wiring**: `pikku-http`, `pikku-websocket`, `pikku-rpc`, `pikku-mcp`, `pikku-queue`, `pikku-cron`, `pikku-trigger`, `pikku-cli`, `pikku-ai-agent`, `pikku-workflow`
+- **Wiring**: `pikku-http`, `pikku-websocket`, `pikku-rpc`, `pikku-mcp`, `pikku-queue`, `pikku-cron`, `pikku-trigger`, `pikku-cli`, `pikku-agent`, `pikku-workflow`
 - **Authorization**: `pikku-security` (authentication/sessions), `pikku-permissions` (permission checks, scopes), `pikku-middleware` (global/tag/route middleware)
 - **Infrastructure**: `pikku-services`, `pikku-config`
 - **Project introspection**: `pikku-info`
@@ -44,7 +44,7 @@ pikkuFunc (pure business logic)
     ├── wireMCPTool     → Model Context Protocol (AI tools)
     ├── wireCLI         → CLI commands
     ├── wireTrigger     → Event-driven (Redis pub/sub, PG LISTEN/NOTIFY)
-    ├── pikkuAIAgent    → AI agents / chatbots
+    ├── pikkuAgent    → AI agents / chatbots
     ├── pikkuWorkflow   → Multi-step durable workflows
     └── wire.rpc        → Internal function-to-function calls
 ```
@@ -122,7 +122,7 @@ pikkuFunc({
   permissionsInBody?: boolean,    // Last resort; needs allow.permissionsInBody in config
   middleware?: PikkuMiddleware[], // See pikku-middleware
 
-  // Agent tooling — see pikku-ai-agent
+  // Agent tooling — see pikku-agent
   approvalRequired?: boolean,
   approvalDescription?: (services, data) => Promise<string>,
 
@@ -144,7 +144,7 @@ reject every caller it exists to serve. Gate those with `permissions`, which
 receive the optional session and may pass anonymous.
 
 **Generics XOR `input`/`output` — never both.** A function's data and return
-types come from *one* source: either the `input`/`output` schemas (preferred —
+types come from _one_ source: either the `input`/`output` schemas (preferred —
 they double as runtime validation and OpenAPI) or type generics
 (`pikkuFunc<In, Out>({ ... })`). Passing both makes the two disagree and forces
 `as any` casts. Do not annotate the `func` return type inline either — let the
@@ -230,7 +230,7 @@ await server.start()
 
 **Lifecycle hooks do not run on this path** — only `pikku dev` and `pikku serve` invoke them. Do your startup work directly in the entrypoint instead.
 
-`pikku validate` warns when a project starts a server by hand *and* depends on no runtime adapter, since that combination means path 1 was available and unused. Silence it with `"lint": { "customServerBootstrap": "off" }` in `pikku.config.json`.
+`pikku validate` warns when a project starts a server by hand _and_ depends on no runtime adapter, since that combination means path 1 was available and unused. Silence it with `"lint": { "customServerBootstrap": "off" }` in `pikku.config.json`.
 
 ## Code Generation
 

package/skills/pikku-deploy-cloudflare/SKILL.md

@@ -42,14 +42,14 @@ export default createCloudflareHandler(
 )
 ```
 
-| Factory | For |
-| --- | --- |
-| `createCloudflareHandler(factories, handlerTypes)` | combined `fetch`/`queue`/`scheduled` |
-| `createCloudflareWorkerHandler(factories)` | HTTP / agent / RPC / workflow-orchestrator units |
-| `createCloudflareCronHandler(factories)` | cron units |
-| `createCloudflareQueueHandler(factories)` | queue-consumer and workflow-step units |
-| `createCloudflareMCPHandler(factories)` | MCP units (same HTTP transport) |
-| `createCloudflareWebSocketHandler(factories)` | channel units, delegating to the DO |
+| Factory                                            | For                                              |
+| -------------------------------------------------- | ------------------------------------------------ |
+| `createCloudflareHandler(factories, handlerTypes)` | combined `fetch`/`queue`/`scheduled`             |
+| `createCloudflareWorkerHandler(factories)`         | HTTP / agent / RPC / workflow-orchestrator units |
+| `createCloudflareCronHandler(factories)`           | cron units                                       |
+| `createCloudflareQueueHandler(factories)`          | queue-consumer and workflow-step units           |
+| `createCloudflareMCPHandler(factories)`            | MCP units (same HTTP transport)                  |
+| `createCloudflareWebSocketHandler(factories)`      | channel units, delegating to the DO              |
 
 `factories` is `{ createConfig, createSingletonServices, createPlatformServices? }`.
 
@@ -71,7 +71,7 @@ const services = await setupServices(env, {
 **Do not hand-roll this.** Beyond building `LocalVariablesService` /
 `LocalSecretService` and caching the result, it calls `setSingletonServices()` —
 and the core runners (`fetchData`, `runQueueJob`, `runScheduled`) resolve
-services through that global slot, *not* through the value you were returned. A
+services through that global slot, _not_ through the value you were returned. A
 setup function that only returns the services leaves every request throwing
 "Singleton services not initialized" as a CF `1101`. It also stashes the env via
 `setCloudflareEnv`, which `getCloudflareEnv()` reads for bindings.

package/skills/pikku-deploy-uws/SKILL.md

@@ -102,14 +102,17 @@ yarn add @pikku/ws
 ```
 
 ```typescript
-import { pikkuWebsocketHandler } from '@pikku/ws'
+import { DEFAULT_WS_MAX_PAYLOAD, pikkuWebsocketHandler } from '@pikku/ws'
 import { stopSingletonServices } from '@pikku/core'
 import { Server } from 'http'
 import { WebSocketServer } from 'ws'
 import './.pikku/pikku-bootstrap.gen.js'
 
 const server = new Server()
-const wss = new WebSocketServer({ noServer: true })
+const wss = new WebSocketServer({
+  noServer: true,
+  maxPayload: DEFAULT_WS_MAX_PAYLOAD,
+})
 
 pikkuWebsocketHandler({
   server,

package/skills/pikku-deps/SKILL.md

@@ -4,8 +4,11 @@ description: >-
   Use for the Pikku dependency security audit: the `pikku audit` CLI command, the
   `.pikku/audit.json` artifact, the `SecurityAuditReport` type in @pikku/core, and the console
   Security screen (getSecurityAudit / runSecurityAudit / updateDependency + SecurityAuditView).
-  TRIGGER when: user asks about `pikku audit`, dependency vulnerabilities/advisories, outdated
-  dependencies, the Security screen/page in the console, updating a vulnerable dependency, or
+  Also covers `pikku update`, which moves the @pikku/* dependency set forward and reports the
+  peers those versions need.
+  TRIGGER when: user asks about `pikku audit` or `pikku update`, dependency
+  vulnerabilities/advisories, outdated dependencies, upgrading Pikku itself, peer dependency
+  conflicts, the Security screen/page in the console, updating a vulnerable dependency, or
   reading/rendering audit.json. DO NOT TRIGGER when: user asks about authentication/sessions/JWT
   (use pikku-security), permissions (use pikku-permissions), or secrets/env vars (use
   pikku-config).
@@ -43,11 +46,47 @@ installGroups: [core]
   `bun outdated`, normalised into one `SecurityAuditReport` with per-severity /
   per-update-level counts). Other PMs are detected but **stubbed** with a `note`
   field until their shapes are normalised — issues/updates come back empty.
-- `bun audit` exits non-zero when it *finds* advisories but still writes the
+- `bun audit` exits non-zero when it _finds_ advisories but still writes the
   payload to stdout, so a non-zero exit **with output** is data. A non-zero exit
   with **no** output — or a launch failure, timeout, or a blown 32MB buffer —
   throws, precisely so a failed run can't masquerade as "0 advisories".
 
+## The `pikku update` command
+
+Narrower than `audit --outdated`, and the only one that writes: it moves the
+**@pikku/\* set** forward and reports the peers those versions need. Use `audit`
+to learn a dependency is vulnerable; use `update` to move Pikku itself.
+
+- `pikku update` — reports only. Nothing is written without `--update`.
+- `pikku update --update` — writes the new ranges into every covered
+  package.json, then runs an install. `--no-install` writes and stops.
+- `pikku update --update-peers` — implies `--update` and additionally writes the
+  ranges unsatisfied peers require, **for peers the project already declares**.
+  A peer it does not declare is reported and never added — adding a dependency
+  is not an update. Separate from `--update` because a peer bump can cross a
+  **major** of a third-party package (`ai` 5 → 6), which is not a call to make
+  on the user's behalf.
+- `--tag <dist-tag>` (default `latest`) reads each package's own dist-tag, so
+  `--tag next` moves the whole set onto prereleases. `--registry <url>` defaults
+  to `npm_config_registry`.
+- Coverage is the nearest package.json walking up from the project root, plus
+  every workspace it declares — a monorepo updates in one pass. All four
+  dependency fields are read, `peerDependencies` included, so an addon's own
+  declared peer range moves with it.
+
+Statuses, per dependency: `outdated` (the range floor is behind latest — this is
+what `--update` writes), `stale-install` (the range already admits latest but
+node_modules is behind — an install fixes it, no edit needed), `linked` (a
+`workspace:`/`file:`/`link:`/`portal:` range — a deliberate local checkout,
+counted but never listed), `manual` (a registry range we refuse to substitute
+into: a union, an x-range, a `*`), `unresolved` (the registry had no such tag —
+this must **never** read as "current", the same rule as a failed audit).
+
+Peers are read off the version the run **lands on**, not the one installed —
+the point is what the target needs. An @pikku peer the same run already brings
+forward is not reported, and an unsatisfied _optional_ peer the project never
+declared is skipped.
+
 ## Console integration (@pikku/addon-console)
 
 Three RPCs, all reading/writing the same artifact via the meta service. Shared