@pikku/skills 0.12.4 → 0.12.8

package/skills/pikku-permissions/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: pikku-permissions
 description: >-
-  Use when adding authorization checks to Pikku functions — pikkuPermission, pikkuAuth,
-  per-function permissions, global permissions, or understanding OR/AND permission logic.
-  TRIGGER when: user wants to restrict who can call a function, check resource ownership, add
-  role-based access, or understand where permission checks belong. DO NOT TRIGGER when: user asks
-  about middleware or request interception (use pikku-middleware), authentication strategies (use
+  Use when adding authorization checks to Pikku functions — pikkuPermission, pikkuAuth, scopes and
+  defineScope, per-function permissions, global permissions, or understanding the scope/OR/AND
+  gating logic. TRIGGER when: user wants to restrict who can call a function, check resource
+  ownership, add role-based or scope-based access, declares or grants scopes, hits
+  MissingScopeError, or asks where permission checks belong. DO NOT TRIGGER when: user asks about
+  middleware or request interception (use pikku-middleware), authentication strategies (use
   pikku-security), or session management.
 installGroups: [core]
 ---
@@ -16,7 +17,7 @@ installGroups: [core]
 
 **ALWAYS put authorization checks in the `permissions` field of `pikkuFunc` or `pikkuSessionlessFunc` — NEVER inside the `func` body.**
 
-This includes: org access checks, repo access checks, role checks, resource ownership, and any other authorization logic. The `permissions` field runs before `func`, is visible to the inspector, and is the only place Pikku enforces authorization.
+This includes: org access checks, repo access checks, role checks, resource ownership, and any other authorization logic. The `permissions` field runs before `func` and is visible to the inspector, so the gate is declared rather than buried — which is what lets `pikku info permissions` and an audit see it at all. Alongside it sits `scopes` (see below) for grant-based gating; between them they are where Pikku enforces authorization. The one sanctioned exception is `permissionsInBody`, covered at the end.
 
 ```typescript
 // CORRECT
@@ -104,11 +105,11 @@ export const hasBookAccess = pikkuPermission(
 
 ```typescript
 permissions: {
-  verified: isVerified,                        // OR: verified users can access
-  owner: isBookOwner,                          // OR: owners can access
-  reviewer: [isAuthenticated, hasBookAccess],  // AND: both must pass
+  verified: isVerified,                    // OR: verified users can access
+  owner: isBookOwner,                      // OR: owners can access
+  reviewer: [isVerified, hasBookAccess],   // AND: both must pass
 }
-// Logic: verified OR owner OR (isAuthenticated AND hasBookAccess)
+// Logic: verified OR owner OR (isVerified AND hasBookAccess)
 ```
 
 Groups are OR'd. Entries within a group array are AND'd.
@@ -134,23 +135,106 @@ export const deleteBook = pikkuFunc({
 A global permission is an app-wide baseline that **every** function must additionally pass. It is an independent AND gate: it can only ever *narrow* access — it never grants access a function's own `permissions` would deny.
 
 ```typescript
-import { addGlobalPermission } from '.pikku/pikku-types.gen.js'
+import { addGlobalPermission } from '#pikku'
 
-addGlobalPermission([signedInUser]) // every function now also requires a session
+addGlobalPermission([isEmployee]) // every function now also requires an employee session
 ```
 
 Multiple `addGlobalPermission` calls accumulate and are AND'd together.
 
 > Wire-, tag-, and HTTP-route-level permissions (`addHTTPPermission`, `addTagPermission`, and a `permissions` field on HTTP/channel/MCP wirings) were **removed in #972**. Permissions now live only on the function definition, plus the optional global gate. Tags are organizational only — use tag/HTTP *middleware* (`addTagMiddleware`, `addHTTPMiddleware`) for cross-cutting request handling, not authorization.
 
-## The Two Gates
+## Scopes — the AND Gate Above Permissions
 
-Authorization is two independent gates, both of which must pass:
+Scopes answer "what was this session granted?" before permissions ask "may this
+user do this to this resource?". They are AND-ed: every scope listed must be
+held. Because they are checked first and fail closed, a scope can only ever
+*narrow* access — it never grants what `permissions` would deny.
 
-1. **Global permissions** (`addGlobalPermission`) — AND'd together. A broad baseline that can only narrow access.
-2. **The function's own `permissions`** — OR'd groups (OR-of-ANDs), as above.
+Declare the scope tree once with `defineScope`. The body is a no-op that
+tree-shakes away; the CLI reads the call by AST and generates a `ScopeId` union,
+so a function naming an undeclared scope fails the build rather than silently
+gating on nothing.
 
-The gates are independent: a broad global (e.g. `signedInUser`) can **never** satisfy an admin-only function's own requirement. Each function still enforces its own `permissions` in full.
+```typescript
+// src/scopes.ts
+import { defineScope } from '#pikku'
+
+defineScope({
+  admin: {
+    displayName: 'Administration',
+    description: 'Administrative access',
+    scopes: {
+      invoices: {
+        description: 'Invoice management',
+        scopes: {
+          create: { description: 'Create invoices' },
+          void: { description: 'Void invoices' },
+        },
+      },
+    },
+  },
+  billing: {},
+})
+```
+
+Every node is grantable, keyed by segment: the above yields `admin`,
+`admin:invoices`, `admin:invoices:create`, `admin:invoices:void` and `billing`.
+Scopes may be declared across more than one file — the declarations merge.
+
+```typescript
+export const voidInvoice = pikkuFunc({
+  scopes: ['admin:invoices:void'],
+  permissions: { owner: isInvoiceOwner },
+  func: async ({ db }, { invoiceId }) => { ... },
+})
+```
+
+A grant satisfies a required scope if it is the scope itself, an ancestor of it,
+or a wildcard at any level — so a session holding `admin` satisfies
+`admin:invoices:void`, and `admin:*` does too. A missing scope throws
+`MissingScopeError` naming the first one that failed.
+
+`scopes` requires a session and so is unavailable on `pikkuSessionlessFunc`:
+scopes fail closed, an anonymous caller holds none, and a sessionless function
+with scopes would reject every caller it exists to serve. Gate those with
+`permissions`, which receive the optional session and may pass anonymous.
+
+## The Three Gates
+
+Authorization is three independent gates, evaluated in this order, all of which must pass:
+
+1. **Scopes** (`scopes`) — AND'd, checked before input validation. Fails closed.
+2. **Global permissions** (`addGlobalPermission`) — AND'd together. A broad baseline that can only narrow access.
+3. **The function's own `permissions`** — OR'd groups (OR-of-ANDs), as above.
+
+The gates are independent: a broad global (e.g. `isEmployee`) can **never** satisfy an admin-only function's own requirement. Each function still enforces its own `scopes` and `permissions` in full.
+
+## The Sanctioned Exception: `permissionsInBody`
+
+A few checks genuinely cannot be expressed as a permission — verifying a webhook
+signature, a signed token, or an invite code, where the "identity" arrives in the
+payload and there is no session to check. For those, declare
+`permissionsInBody: true` on the function and keep the check in the body.
+
+```typescript
+export const handleStripeWebhook = pikkuSessionlessFunc({
+  permissionsInBody: true,
+  auth: false,
+  func: async ({ stripe }, data, { http }) => {
+    stripe.webhooks.constructEvent(data.raw, http.request.header('stripe-signature'), secret)
+    // ...
+  },
+})
+```
+
+This is a last resort, and it is purely declarative — it grants nothing and
+enforces nothing. Its only job is to tell the auditor that this function's
+apparent openness is deliberate, so asserting it falsely disables the very check
+that would have caught the mistake. It requires `"allow": { "permissionsInBody": true }`
+in `pikku.config.json`, which keeps the decision visible at the project level.
+Prefer `permissions` whenever the check can be expressed as one — they are
+declared, inspectable, and reusable.
 
 ## Complete Example
 
@@ -158,10 +242,6 @@ The gates are independent: a broad global (e.g. `signedInUser`) can **never** sa
 // src/permissions.ts
 import { pikkuAuth, pikkuPermission } from '#pikku'
 
-export const isAuthenticated = pikkuAuth(
-  async (_services, session) => !!session
-)
-
 export const isVerified = pikkuAuth(
   async (_services, session) => !!session?.emailVerified
 )
@@ -179,7 +259,7 @@ export const deleteOrg = pikkuFunc({
   },
   permissions: {
     verified: isVerified,
-    owner: [isAuthenticated, isOrgMember],
+    owner: [isVerified, isOrgMember],
   },
 })
 ```

package/skills/pikku-pino/SKILL.md

@@ -46,10 +46,18 @@ No constructor parameters. Creates a Pino logger instance.
 **Methods:**
 
 - `setLevel(level: LogLevel): void` — Set minimum log level.
-- `info(messageOrObj: string | Record<string, any> | Error): void`
-- `warn(messageOrObj: string | Record<string, any> | Error): void`
-- `error(messageOrObj: string | Record<string, any> | Error): void`
-- `debug(messageOrObj: string | Record<string, any>): void`
+- `info(messageOrObj: string | Record<string, any> | Error, ...meta): void`
+- `warn(messageOrObj: string | Record<string, any> | Error, ...meta): void`
+- `error(messageOrObj: string | Record<string, any> | Error, ...meta): void`
+- `debug(message: string, ...meta): void` — string only; the object form is not accepted here
+
+Every argument, first and trailing, is `Safe<>`-guarded. A `SecretValue` nested
+anywhere in what you log collapses the call to `never` and it stops compiling.
+An unrevealed secret would print as `[secret]` regardless — the guard is what
+makes logging one a deliberate act rather than an accident.
+
+`setLevel` maps Pikku's `LogLevel` enum onto Pino's own level strings, so pass
+the enum (or its name) rather than a raw Pino level.
 
 ## Usage Patterns
 

package/skills/pikku-product-second-opinion/SKILL.md

@@ -120,12 +120,12 @@ Include this section **only if you are actually recommending a rebuild** onto it
 
 **TanStack Start (the web framework) — instead of the incumbent (Next.js).**
 - *Buys you:* modern, tidy developer experience; strong type-safety that catches whole classes of bugs before users see them; fast iteration; fine-grained control; deploys well to modern/edge hosting. The libraries underneath it — the TanStack ecosystem (Query, Router, Table) — are mature, battle-tested and everywhere in React.
-- *Costs you (the honest tradeoff — maturity of the framework itself):* separate the ecosystem from the framework. Query/Router/Table are mature; **TanStack Start, the framework that wraps them, has not shipped a stable 1.0** — its own maintainers describe it as a release candidate that is feature-complete with a stable API, and tell production users to lock to an exact version and follow the last-mile changes into 1.0. In practice that means pinning your version and budgeting for occasional upgrade work as it settles, rather than upgrading casually. On top of that it's newer than the incumbent (Next.js), which has the largest ecosystem — fewer ready-made templates and third-party examples, and a smaller (though growing) pool of developers who've used *this specific* framework, which can make hiring slightly slower.
-- *Usually:* a credible, modern choice on a mature foundation, but a **pre-1.0 one** — so it carries pinning and upgrade risk that the incumbent does not. Reasonable if the team wants the type-safety and is willing to track the framework to 1.0; harder to justify if nobody has capacity to own upgrades.
+- *Costs you (the honest tradeoff — maturity of the framework itself):* separate the ecosystem from the framework. Query/Router/Table are mature; the framework that wraps them is younger, and **you must check its release stage on tanstack.com/start at the moment you write** — do not infer it from the npm version. `@tanstack/react-start` has been on 1.x since early 2025 because its major tracks the **Router** version line, so "1.168.x" says nothing about whether Start itself has shipped a stable 1.0. If it is still pre-1.0, the cost is pinning an exact version and budgeting for upgrade work as it settles. Either way it is newer than the incumbent (Next.js), which has the largest ecosystem — fewer ready-made templates and third-party examples, and a smaller (though growing) pool of developers who've used *this specific* framework, which can make hiring slightly slower.
+- *Usually:* a credible, modern choice on a mature foundation. Whether it also carries pinning-and-upgrade risk depends on the release stage you just checked — say which you found, rather than repeating either verdict from here.
 
 **Pikku (the framework a rebuild would land on) — instead of staying where you are.**
 - *Buys you:* one way to write a capability and drive it from anywhere — web, background jobs, timers, realtime, AI assistants, the command line — so a feature is written once instead of five times. Type-safe clients and the API spec fall out of the code rather than being hand-maintained until they drift. The sprawl an organically-grown app accumulates collapses into one shape a small team can hold in its head.
-- *Costs you (the honest tradeoff — it is younger than anything it would replace):* Pikku has **not shipped a stable 1.0** — it's 0.12.x, and 0.13 is the first release that will promise backwards compatibility. Until then upgrades can break you. In practice: pin your version, budget for upgrade work, and know that the community, the ready-made examples, and the pool of developers who have used it are all far smaller than the incumbent's — smaller than TanStack Start's, let alone Next.js's. Being pre-1.0 is normal for a young framework, and survivable, but it is a real cost and it is the reader's to weigh, not yours to skip.
+- *Costs you (the honest tradeoff — it is younger than anything it would replace):* Pikku has **not shipped a stable 1.0** — at the time of writing it is 0.12.x, and 0.13 is the first release that promises backwards compatibility; check the published version rather than repeating this one. Until then upgrades can break you. In practice: pin your version, budget for upgrade work, and know that the community, the ready-made examples, and the pool of developers who have used it are all far smaller than the incumbent's — smaller than TanStack Start's, let alone Next.js's. Being pre-1.0 is normal for a young framework, and survivable, but it is a real cost and it is the reader's to weigh, not yours to skip.
 - *Usually:* worth it when the real problem is sprawl — many surfaces, hand-maintained glue, the same rule implemented three slightly different ways — and the team wants one shape instead of five. Harder to justify for an app that works and needs a few rewires: those are usually cheaper in place. If nobody has capacity to own upgrades, that's a real reason to wait.
 
 Check these statuses before you write them up rather than repeating them from here — a framework's release stage moves, and the point is the current fact, not this example.

package/skills/pikku-queue/SKILL.md

@@ -43,22 +43,48 @@ wireQueueWorker({
   name: string,            // Queue name (unique identifier)
   func: PikkuFunc,         // Worker function
   config?: {
-    batchSize?: number,    // Process N jobs at once
-    removeOnComplete?: number | boolean,  // Clean up completed jobs
+    batchSize?: number,           // Total worker concurrency
+    prefetch?: number,
+    pollInterval?: number,        // ms
+    visibilityTimeout?: number,   // seconds
+    lockDuration?: number,        // ms
+    drainDelay?: number,          // seconds
+    removeOnComplete?: number,    // how many completed jobs to RETAIN (a count, not an age)
+    removeOnFail?: number,        // how many failed jobs to RETAIN
+    maxStalledCount?: number,
+    autorun?: boolean,
+    groupConcurrency?: number | GroupConcurrencyConfig,  // must not exceed batchSize
   },
 })
 ```
 
+Not every adapter supports every option. Each adapter declares a
+`QueueConfigMapping`, and unsupported keys are dropped with a warning rather than
+silently ignored — so check the startup logs if a setting appears to have no
+effect.
+
+`groupConcurrency` limits how many jobs run concurrently *per group* (jobs
+carrying a `JobGroup` with an `id` and optional `tier`), so one noisy tenant
+cannot consume the whole worker:
+
+```typescript
+groupConcurrency: { default: 2, tiers: { enterprise: 10 } }
+```
+
 ### Wire Object (`wire.queue`)
 
 Inside queue worker functions:
 
 ```typescript
-wire.queue.updateProgress(percent: number)  // Report progress (0-100)
-wire.queue.discard(reason: string)          // Silently discard job
-wire.queue.fail(reason: string)             // Mark job as failed
+wire.queue.updateProgress(progress: number | string | object)  // Report progress
+wire.queue.discard(reason?: string)   // Silently discard job (throws QueueJobDiscardedError)
+wire.queue.fail(reason?: string)      // Mark job as failed
 ```
 
+`updateProgress` is not limited to a 0-100 percentage — a string or an object
+lets a long job report a stage ("rendering page 4/20") that a dashboard can show
+directly.
+
 ### Job Publishing
 
 ```typescript
@@ -69,13 +95,15 @@ Options:
 
 ```typescript
 {
-  priority?: number,       // Higher = processed first
-  delay?: number,          // Delay in ms before processing
-  attempts?: number,       // Max retry attempts
-  backoff?: {
-    type: 'exponential' | 'fixed',
-    delay: number,         // Base delay in ms
-  },
+  retryAttempts?: number,   // Max retry attempts
+  retryDelay?: number,      // Base delay in ms
+  retryBackoff?: 'linear' | 'exponential' | 'fixed',
+  deadLetterQueue?: string, // Where exhausted jobs land
+  messageRetention?: number,// Seconds
+  priority?: number,        // Higher numbers run first
+  fifo?: boolean,
+  timeout?: number,         // ms
+  delay?: number,           // ms before the job becomes eligible
 }
 ```
 
@@ -146,8 +174,9 @@ const jobId = await queue.add(
   {
     priority: 10,
     delay: 5000,
-    attempts: 3,
-    backoff: { type: 'exponential', delay: 1000 },
+    retryAttempts: 3,
+    retryBackoff: 'exponential',
+    retryDelay: 1000,
   }
 )
 ```
@@ -157,7 +186,7 @@ const jobId = await queue.add(
 After `npx pikku all`:
 
 ```typescript
-import { PikkuQueue } from '.pikku/pikku-queue.gen.js'
+import { PikkuQueue } from '#pikku/pikku-queue.gen.js'
 
 const queue = new PikkuQueue(queueService)
 
@@ -167,7 +196,7 @@ const jobId = await queue.add('todo-reminders', {
 })
 
 const job = await queue.getJob('todo-reminders', jobId)
-const status = await job.status() // 'waiting' | 'active' | 'completed' | 'failed'
+const status = await job.status() // 'waiting' | 'active' | 'completed' | 'failed' | 'delayed'
 const result = await job.waitForCompletion(30_000)
 ```
 

package/skills/pikku-react/SKILL.md

@@ -30,11 +30,16 @@ import {
   usePikkuFetch,
   usePikkuRPC,
   usePikkuRealtime,
+  usePikkuAgent,
+  usePikkuWorkflow,
+  asI18n,
 } from '@pikku/react'
 ```
 
-Five exports. `usePikkuRealtime` is only valid when you wired a
-`PikkuRealtime` class via `createPikku` — see step 3 below.
+`usePikkuRealtime` is only valid when you wired a `PikkuRealtime` class via
+`createPikku` — see the setup section. `usePikkuAgent` and `usePikkuWorkflow`
+are thin bindings over the RPC client that pin one agent/workflow name, so a
+component never repeats it. `asI18n` is the i18n brand (see **pikku-i18n**).
 
 ## Resolving the server URL
 
@@ -175,31 +180,53 @@ helpers live in **pikku-realtime**.
 | Paginate                            | **usePikkuInfiniteQuery** (react-query)       |
 | One-off call from an event handler  | `usePikkuRPC()` direct                        |
 | Hit a REST endpoint (not RPC)       | `usePikkuFetch()`                             |
-| Run a workflow                      | **pikku-workflows-client**                    |
+| Run one named workflow              | `usePikkuWorkflow('name')` → `.start/.run/.status` |
+| Talk to one named AI agent          | `usePikkuAgent('name')` → `.run/.stream/.approve`  |
+| Longer-running workflow UX          | **pikku-workflows-client**                    |
 | Subscribe to events / SSE / channel | `usePikkuRealtime()` (see **pikku-realtime**) |
 
 The first three live in your generated `api.gen.ts` (see the
-**pikku-react-query** skill). This skill covers the bottom four rows.
+**pikku-react-query** skill). This skill covers the rest.
+
+`usePikkuAgent` and `usePikkuWorkflow` bind the name once and hand back the
+call methods with it already applied:
+
+```tsx
+const agent = usePikkuAgent('todo-agent')
+const { text } = await agent.run({ message, threadId })
+
+const workflow = usePikkuWorkflow('onboardUser')
+const { runId } = await workflow.start({ email })
+const state = await workflow.status(runId)
+```
 
 ## Authentication
 
-Auth is handled at the `PikkuFetch` layer — pass options to `createPikku`
-or set headers on the fetch instance after creation. Common pattern:
+Auth is handled at the `PikkuFetch` layer, and `createPikku`'s options object
+*is* `CorePikkuFetchOptions` plus `serverUrl` — flat, not nested under a
+`fetchOptions` key:
 
 ```tsx
 const pikku = createPikku(PikkuFetch, PikkuRPC, {
   serverUrl: apiUrl(),
-  fetchOptions: {
-    onRequest: (req) => {
-      const token = localStorage.getItem('token')
-      if (token) req.headers.set('Authorization', `Bearer ${token}`)
-    },
-  },
+  credentials: 'include', // cookie sessions
+  authHeaders: { jwt: token }, // or { apiKey }
+  transformDate: true,
 })
 ```
 
-Exact option names depend on the `@pikku/fetch` version — read
-`PikkuFetch`'s constructor type if unsure.
+There is no request-interceptor hook. For a token that changes after startup,
+call the setter on the shared instance — RPC and realtime pick it up because
+they hold the same fetch:
+
+```tsx
+pikku.fetch.setAuthorizationJWT(token) // null clears it
+pikku.fetch.setAPIKey(key)
+pikku.fetch.setHeader('x-tenant', tenantId)
+```
+
+`authHeaders.jwt` becomes `Authorization: Bearer …` and `authHeaders.apiKey`
+becomes `X-API-KEY`; setting a JWT takes precedence over an API key.
 
 ## What NOT to do
 

package/skills/pikku-react-query/SKILL.md

@@ -17,7 +17,7 @@ Use this skill as an execution checklist, not reference material.
 5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
 
 Pikku generates a typed React Query layer from your backend `expose: true`
-functions. You don''t write `useQuery`/`useMutation` against `fetch`
+functions. You don't write `useQuery`/`useMutation` against `fetch`
 yourself — you call hooks named after RPCs and get full type inference for
 input + output.
 
@@ -184,25 +184,29 @@ refetch.
 
 ### `usePikkuInfiniteQuery(name, data, options?)`
 
-Only available for RPCs whose output has a `nextCursor?: string | null`
-field — typically a list endpoint with pagination. The hook auto-feeds
-`nextCursor` into the next page's request.
+The hook's `name` parameter is narrowed to RPCs whose **output** has a
+`nextCursor?: string | null` field, so calling it with anything else is a type
+error rather than a missing hook. That output field is read after each page and
+sent back as the **input** field `cursor` — which is why the `data` you pass is
+`Omit<input, 'cursor'>`: the hook owns that key.
 
 ```tsx
 const { data, fetchNextPage, hasNextPage, isFetchingNextPage } =
   usePikkuInfiniteQuery('listTodos', { limit: 20 })
 
-const todos = data?.pages.flatMap((p) => p.rows) ?? []
+const todos = data?.pages.flatMap((p) => p.todos) ?? []
 ```
 
-If the hook isn't generated for an RPC, the RPC's output doesn't include
-`nextCursor` — paginate it on the backend or use `usePikkuQuery` with
-manual cursor state.
+So the backend contract is a pair: output `nextCursor`, input `cursor`. An RPC
+missing either one paginates with `usePikkuQuery` and manual cursor state
+instead.
 
 ## Workflow hooks
 
-When the project has workflows (`capabilities.workflow: true`), three
-extra hooks are generated. See the **pikku-workflows-client** skill.
+When the project defines any workflow, the same file also gains
+`useStartWorkflow(name)` (mutation → `{ runId }`), `useRunWorkflow(name)`
+(mutation → the workflow's output) and `useWorkflowStatus(name, runId?)` (query,
+disabled until `runId` is set). See the **pikku-workflows-client** skill.
 
 ## Calling RPCs without React Query
 

package/skills/pikku-realtime/SKILL.md

@@ -46,7 +46,9 @@ import type { EventHubService } from '@pikku/core/channel'
 import type { EventHubTopics } from './eventhub-topics.js'
 
 export interface SingletonServices extends CoreSingletonServices<Config> {
-  eventHub?: EventHubService<EventHubTopics>
+  // `CoreSingletonServices` declares eventHub optional; re-declare it required
+  // so functions can use it without a `if (eventHub)` guard on every publish.
+  eventHub: EventHubService<EventHubTopics>
 }
 
 // services.ts
@@ -57,6 +59,10 @@ const eventHub = new LocalEventHubService<EventHubTopics>()
 For multi-instance deployments use `CloudflareEventHubService` /
 `LambdaEventHubService` / `UWSEventHubService` instead — same interface.
 
+If a deployment genuinely has no eventHub, that belongs in `services.ts` (don't
+create the service there), not as an optional type every function has to guard —
+see `pikku-services`.
+
 ## 2. Enable the server side
 
 ```bash
@@ -85,20 +91,28 @@ Add to `pikku.config.json`:
 }
 ```
 
-Run `pikku all` (or `pikku realtime` to regenerate just this file). The generated
-file exports two surfaces:
+Run `pikku all` (or `pikku realtime` to regenerate just this file). Everything is
+on one class — both transports are methods, so switching from WebSocket to SSE is
+a one-word change, not a different import:
 
 ```ts
 export class PikkuRealtime {
-  constructor(options: { url: string; reconnect?: boolean; ... })
+  constructor(options?: { reconnect?: boolean; reconnectDelayMs?: number; reconnectMaxDelayMs?: number })
+  setPikkuFetch(fetch: PikkuFetch): void   // server URL + auth come from here, not the constructor
+
+  // WebSocket at /events — many topics on one connection
   subscribe<K extends keyof EventHubTopics>(topic: K, handler: (data: EventHubTopics[K]) => void): () => void
-  unsubscribe<K extends keyof EventHubTopics>(topic: K, handler?: ...): void
+  unsubscribe<K extends keyof EventHubTopics>(topic: K, handler?: (data: EventHubTopics[K]) => void): void
+
+  // SSE at GET /events/:topic — one EventSource per topic
+  subscribeToTopic<K extends keyof EventHubTopics>(topic: K, handler: (data: EventHubTopics[K]) => void): { close: () => void }
+
+  // generic escape hatches — see references/other-routes.md
+  subscribeToSSE<T>(path: string, handler: (data: T) => void): { close: () => void }
+  connectToChannel(channelRoute: string, protocols?: string | string[]): WebSocket
+
   close(): void
 }
-
-export function subscribeToTopicViaSSE<K extends keyof EventHubTopics>(
-  baseUrl: string, topic: K, handler: (data: EventHubTopics[K]) => void
-): { close: () => void }
 ```
 
 Without `realtimeEventHubTopicsImport`, the client falls back to
@@ -108,9 +122,19 @@ subscribe/unsubscribe.
 ## 4. Publish events from a function
 
 The `/events` channel listens for client subscriptions; the eventHub fans out
-publishes. Envelope the payload with `topic` so the client dispatcher works; the
-`null` channelId means "broadcast to all subscribers" (pass a specific channel id
-to exclude/include a single connection):
+publishes:
+
+```ts
+publish(topic, channelId: string | null, data, isBinary?)
+```
+
+The middle argument is the channel to **skip**, not the one to send to — pass
+`null` to reach every subscriber, or the current `channel.channelId` when the
+originating connection has already applied the change locally and would otherwise
+render it twice.
+
+Envelope the payload as `{ topic, data }`: the generated client dispatches on the
+`topic` field, so a bare payload arrives but no handler fires.
 
 ```ts
 import { pikkuFunc } from '#pikku'
@@ -123,12 +147,10 @@ export const createTodo = pikkuFunc({
       .insertInto('todos').values(data).returningAll()
       .executeTakeFirstOrThrow()
 
-    if (eventHub) {
-      await eventHub.publish('todo-created', null, {
-        topic: 'todo-created',
-        data: { todo },
-      })
-    }
+    await eventHub.publish('todo-created', null, {
+      topic: 'todo-created',
+      data: { todo },
+    })
     return { id: todo.id }
   },
 })
@@ -215,10 +237,10 @@ sockets (`subscribeToSSE`, `connectToChannel`). See
 
 | Need                                       | Use                           |
 | ------------------------------------------ | ----------------------------- |
-| Many topics in one connection              | **PikkuRealtime** (WebSocket) |
-| Single live stream, simple cleanup         | **subscribeToTopicViaSSE**    |
-| Bidirectional (client also sends messages) | **PikkuRealtime**             |
-| WebSockets blocked by infra                | **subscribeToTopicViaSSE**    |
+| Many topics in one connection              | `realtime.subscribe`          |
+| Single live stream, simple cleanup         | `realtime.subscribeToTopic`   |
+| Bidirectional (client also sends messages) | `realtime.subscribe`          |
+| WebSockets blocked by infra                | `realtime.subscribeToTopic`   |
 
 Both auto-clean on the server (the eventHub's `onChannelClosed` hook unsubscribes
 all topics for the dead channel id). Don't write manual cleanup unless you're

package/skills/pikku-redis/SKILL.md

@@ -43,15 +43,25 @@ All services accept a Redis connection (ioredis `Redis` instance, `RedisOptions`
 | `RedisDeploymentService`  | `DeploymentService`    | Deployment state management                    |
 | `RedisAgentRunService`    | `AgentRunService`      | Agent execution tracking                       |
 | `RedisSecretService`      | `SecretService`        | Encrypted secret storage (envelope encryption) |
+| `RedisSessionStore`       | `SessionStore`         | Persisted user sessions                        |
 
 ### Secret Service
 
+Envelope encryption: `key` derives the KEK that wraps each secret's own DEK.
+Keeping `previousKey` set is what makes `rotateKEK()` possible — it re-wraps
+every secret onto the current key and returns the new version.
+
 ```typescript
 import { RedisSecretService } from '@pikku/redis'
 
 const secrets = new RedisSecretService(
   connectionOrConfig: Redis | RedisOptions | string,
-  config: { kekSecret: string; salt: string }
+  config: {
+    key: string          // the KEK passphrase
+    keyVersion?: number  // defaults to 1
+    previousKey?: string // required to rotate
+    keyPrefix?: string   // namespaces the redis keys
+  }
 )
 
 await secrets.getSecret<T = string>(key: string): Promise<T>
@@ -81,8 +91,7 @@ const createSingletonServices = pikkuServices(async (config) => {
   const workflowService = new RedisWorkflowService(config.redisUrl)
 
   const secrets = new RedisSecretService(config.redisUrl, {
-    kekSecret: config.kekSecret,
-    salt: config.salt,
+    key: config.kekPassphrase,
   })
 
   return { config, logger, channelStore, workflowService, secrets }