@pikku/skills 0.12.2 → 0.12.6

package/skills/pikku-feature/SKILL.md

@@ -126,12 +126,12 @@ in-app features don't.
 - **Migrations are inline SQL files** in the project's migrations dir
   (typically `sql/`). Use a numbered prefix matching existing files.
 - **Secrets and env-vars: NEVER `process.env`.** Declare them with
-  `wireSecret` (sensitive) or `wireVariable` (non-sensitive) — both with a
-  zod schema for type-safe access. Read with
-  `services.secrets.getSecret('NAME')` or `services.variables.get('NAME')`.
-  See the **pikku-config** skill for the full pattern (including
-  OAuth2 credentials). This applies even in `config.ts` and singleton
-  service factories.
+  `defineSecret` (sensitive) or `defineVariable` (non-sensitive) — both with a
+  zod schema for type-safe access. Read variables with
+  `services.variables.get('NAME')`. Secrets are **not available in functions** —
+  read them in `services.ts` with `secrets.getSecret('NAME')` and pass the value
+  into the service the function uses. See the **pikku-config** skill for the full
+  pattern (including OAuth2 credentials). This applies even in `config.ts`.
 
 ### Conventions to copy from neighbours
 
@@ -218,10 +218,15 @@ branch.
 ## Stage 6 — Commit
 
 ```bash
-git add -A
+git add <the files you changed>
 git commit -m "feat: <short title>"
 ```
 
+Stage the files you actually touched, by path. `git add -A` / `git add .` also
+sweeps up regenerated artifacts you didn't mean to commit and, where more than
+one agent shares the checkout, another agent's in-progress work — which lands in
+your branch and silently breaks theirs.
+
 ## Stage 7 — Hand off
 
 Tell the user the branch name and how to review. Two options:

package/skills/pikku-gateway-slack/SKILL.md

@@ -35,24 +35,67 @@ yarn add @pikku/gateway-slack @slack/web-api
 ```typescript
 import { SlackGatewayAdapter } from '@pikku/gateway-slack'
 
-const adapter = new SlackGatewayAdapter(options: SlackGatewayAdapterOptions)
+const adapter = new SlackGatewayAdapter({
+  signingSecret: string,
+  tokenResolver: (teamId: string) => Promise<string | null>,
+})
 ```
 
 Bridges Slack Events API webhooks with Pikku's gateway system for processing Slack events as Pikku functions.
 
+**There is no `botToken` option.** One adapter serves every workspace, and the
+bot token is resolved per `team_id` through `tokenResolver` — normally a lookup
+against the row `exchangeSlackOAuthCode` wrote at install time. Returning `null`
+throws for that event. `WebClient`s are cached per team, so call
+`invalidateClient(teamId)` after a token rotation.
+
+**Methods:**
+
+- `verifyWebhook(data, request?)` — asserts the signature, then answers the `url_verification` challenge. It **fails closed**: no request access, missing headers, a stale timestamp, or an HMAC mismatch all throw `UnauthorizedError` before parse or the handler runs
+- `parse(data)` — normalizes an `event_callback` into a `GatewayInboundMessage`, or returns `null` for anything to ignore
+- `createBoundSend(teamId, channelId, threadTs?)` — the real send path
+- `send(senderId, message)` — **a deliberate no-op.** The generic signature carries no channel context, and the gateway runner calls it for auto-send, so it swallows rather than throws. A reply written through it silently never reaches Slack
+- `getClientForTeam(teamId)` / `invalidateClient(teamId)` / `close()`
+
+`parse` returns `null` — meaning the event is dropped — for anything that isn't a
+`message` or `app_mention`, for bot messages (loop prevention), for any subtype
+other than `thread_broadcast`, and for events with no `user` or no `text`.
+`metadata` carries `{ teamId, channelId, threadTs, messageTs, eventType }`, with
+`threadTs` falling back to the message's own `ts` so replies always land
+in-thread.
+
 ### `SlackGatewayHelper`
 
-Helper for handling Slack messages and metadata within gateway functions.
+Wraps a parsed message plus the adapter and binds the channel/thread for you:
+
+```typescript
+const slack = new SlackGatewayHelper(data, adapter)
+await slack.sendText('Thinking…') // sends now
+return slack.reply('Here is the answer') // auto-sent by the runner
+```
+
+Also: `send(message)`, `replyBlocks(blocks)`, and the `channelId` / `threadTs` /
+`teamId` getters.
 
 ### Slash Commands
 
 ```typescript
 import { parseSlashCommand, respondToSlashCommand } from '@pikku/gateway-slack'
 
-const command = parseSlashCommand(request)
-await respondToSlashCommand(responseUrl, { text: 'Done!' })
+const command = parseSlashCommand(data)
+// { raw, subcommand, args, argsList, teamId, userId, channelId, triggerId, responseUrl }
+await respondToSlashCommand(command.responseUrl, { text: 'Done!' })
 ```
 
+The parsed result is camelCase — reach for `command.responseUrl`, not
+`command.response_url`; the underlying snake_case payload is on `command.raw`.
+`text` is split on whitespace: the first word becomes `subcommand`, the rest
+`args`/`argsList`.
+
+`respondToSlashCommand` posts to the `response_url` and **ignores the result** —
+a rejected response is invisible. Use it for the delayed reply when work exceeds
+Slack's 3-second acknowledgement window.
+
 ### OAuth Flow
 
 ```typescript
@@ -81,9 +124,19 @@ const tokens = await exchangeSlackOAuthCode({
 ```typescript
 import { verifySlackSignature } from '@pikku/gateway-slack'
 
-verifySlackSignature(signingSecret, timestamp, body, signature)
+verifySlackSignature(signingSecret, signature, timestamp, body): boolean
 ```
 
+**Signature before timestamp** — the two middle arguments are both strings, so
+swapping them compiles and simply never verifies. `signature` is the raw
+`x-slack-signature` header (`v0=…`), `timestamp` is `x-slack-request-timestamp`
+in Unix seconds, and `body` must be the **raw** request body: any re-serialization
+changes the HMAC.
+
+It returns `false` rather than throwing, including for a timestamp more than 5
+minutes off (replay protection). The adapter already calls this for you — reach
+for it directly only outside the gateway path, e.g. in a slash-command route.
+
 ## Usage Patterns
 
 ### Slack Bot Gateway
@@ -93,22 +146,30 @@ import { SlackGatewayAdapter } from '@pikku/gateway-slack'
 
 const slackGateway = new SlackGatewayAdapter({
   signingSecret: config.slackSigningSecret,
-  botToken: config.slackBotToken,
+  tokenResolver: async (teamId) => {
+    const row = await kysely
+      .selectFrom('slackInstall')
+      .select('botToken')
+      .where('teamId', '=', teamId)
+      .executeTakeFirst()
+    return row?.botToken ?? null
+  },
 })
-
-// Register with your HTTP runner to handle /slack/events endpoint
 ```
 
 ### Slash Command Handler
 
+Slack gives you 3 seconds to acknowledge, so anything slower answers immediately
+and posts the real result to `responseUrl` afterwards:
+
 ```typescript
 const handleSlashCommand = pikkuSessionlessFunc({
   title: 'Handle Slack Command',
   func: async ({ db }, data) => {
     const command = parseSlashCommand(data)
-    // Process command...
-    await respondToSlashCommand(command.response_url, {
-      text: `Processed: ${command.text}`,
+    await respondToSlashCommand(command.responseUrl, {
+      text: `Processed: ${command.args}`,
+      response_type: 'ephemeral',
     })
   },
 })

package/skills/pikku-http/SKILL.md

@@ -38,8 +38,13 @@ Follow existing patterns you find (naming, tag usage, file organization). See `p
 
 ## API Reference
 
-- `wireHTTP(config)` (from `@pikku/core/http`) — wire one function to one endpoint.
-- `defineHTTPRoutes(config)` + `wireHTTPRoutes(config)` (from `.pikku/pikku-types.gen.js`) — group routes with shared config; composable/nestable.
+All three come from `#pikku` (the generated `.pikku/pikku-types.gen.js`), 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.
+
+- `wireHTTP(config)` — wire one function to one endpoint.
+- `defineHTTPRoutes(config)` + `wireHTTPRoutes(config)` — group routes with shared config; composable/nestable.
 
 Function input/output types come from the function's own `input:`/`output:` zod schemas — never declared in the wiring. Route `:params`, query params, and body are merged into the function's `data` arg (see Data Flow).
 
@@ -144,6 +149,9 @@ wireHTTP({
 
 ### SSE (Server-Sent Events)
 
+`sse: true` is only accepted on `method: 'get'` — the wiring union offers it on
+no other verb.
+
 ```typescript
 wireHTTP({
   method: 'get',
@@ -154,7 +162,7 @@ wireHTTP({
 
 const getTodos = pikkuFunc({
   title: 'Get Todos',
-  func: async ({ db, channel }, {}) => {
+  func: async ({ db }, {}, { channel }) => {
     const todos = await db.getTodos()
 
     if (channel) {
@@ -170,12 +178,17 @@ const getTodos = pikkuFunc({
 })
 ```
 
+`channel` is on the **wire** — the func's third argument — not on services, and
+it is optional because the same function can be reached over plain HTTP or RPC,
+where there is no stream to send on. The `if (channel)` guard is what lets one
+function serve both; the return value is the non-streaming answer.
+
 ### Generated Fetch Client
 
 After `npx pikku all`, a type-safe client is generated:
 
 ```typescript
-import { pikkuFetch } from '.pikku/pikku-fetch.gen.js'
+import { pikkuFetch } from '#pikku/pikku-fetch.gen.js'
 
 pikkuFetch.setServerUrl('http://localhost:4002')
 
@@ -213,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/core/http'
+import { addHTTPMiddleware } from '#pikku'
 import { cors, authBearer } from '@pikku/core/middleware'
 
 addHTTPMiddleware('*', [cors(), authBearer()])

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

@@ -2,25 +2,30 @@
 
 ## `wireHTTP(config)`
 
-Wire a single function to an HTTP endpoint. Import from `@pikku/core/http`.
+Wire a single function to an HTTP endpoint. Import from `#pikku`.
 
 | Option | Type | Notes |
 | --- | --- | --- |
-| `method` | `'get' \| 'post' \| 'put' \| 'patch' \| 'delete' \| 'head'` | HTTP verb |
+| `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 |
+| `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 |
-| `docs?` | `HTTPRouteDocsConfig` | OpenAPI docs config |
+
+`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
+serving a normal response. OpenAPI metadata is not declared here — it is derived
+from the function's `description`/`summary` and its input/output schemas.
 
 ## `defineHTTPRoutes(config)` + `wireHTTPRoutes(config)`
 
-Group routes with shared configuration. Groups are composable and nestable. Import from `.pikku/pikku-types.gen.js`.
+Group routes with shared configuration. Groups are composable and nestable. Import from `#pikku`.
 
 ```typescript
 const routes = defineHTTPRoutes({

package/skills/pikku-i18n/SKILL.md

@@ -56,18 +56,18 @@ function LoginPage() {
 
 ## Keys only known at runtime (enum labels, status maps)
 
-A DB value picking a label (`enums__document_status__${status}`) is the one case a
-generated message can't express. Paraglide's README (§ "What about dynamic or
-CMS-driven keys?") is explicit: use an **explicit mapping from value to message
-function**. Key it on the enum type, never `string`:
+A DB value picking a label is the one case a generated message can't express.
+Paraglide's README (§ "What about dynamic or CMS-driven keys?") is explicit: use
+an **explicit mapping from value to message function**. Key it on the enum type,
+never `string`:
 
 ```ts
 import { m } from '../paraglide/messages.js'
 
 const DOCUMENT_STATUS_LABEL: Record<DocumentStatus, () => string> = {
-  completed: m.enums__document_status__completed,
-  in_progress: m.enums__document_status__in_progress,
-  required: m.enums__document_status__required,
+  completed: m.enum__document_status__completed,
+  in_progress: m.enum__document_status__in_progress,
+  required: m.enum__document_status__required,
 }
 
 // call site — no fallback, because there is no missing case
@@ -77,6 +77,13 @@ DOCUMENT_STATUS_LABEL[status]()
 `Record<DocumentStatus, …>` is exhaustive: add a value to the enum without a
 label and the build fails. That is the entire point.
 
+**Don't write these maps by hand.** `@pikku/paraglide` generates them from the
+`enum__<group>__<member>` keys in the catalog and types each one against the DB
+enum it mirrors, so a migration adding a status is a compile error rather than a
+map someone forgot. Use the namespace above (singular `enum`, `__` between
+segments) so the generator picks the group up, and read `pikku-paraglide` before
+adding one.
+
 Do NOT write `Record<string, () => string>` with a `?? status` fallback, and do
 NOT index the namespace with a computed key (`m[\`enums__${name}__${value}\`]`).
 Both compile, both render the raw identifier to users when a label is missing,
@@ -132,6 +139,10 @@ The wrapper alternative — a module that walks the namespace and pipes each mes
 - Don't hardcode display strings "just for now" — the message is the work.
 - Don't edit or commit anything under `src/paraglide/` — it's regenerated; change `messages/*.json` instead.
 - **Don't wrap `m`.** No re-export module, no branding layer, no resolver. Components import `m` from `../paraglide/messages.js` and call it. `@pikku/react`'s `I18nString` is declared as `string & { readonly __brand: 'LocalizedString' }` — deliberately identical to Paraglide's own `LocalizedString` — so `m.some__key()` satisfies the `@pikku/mantine` `I18nNode` gate natively. A wrapper adds nothing and costs per-message tree-shaking.
+
+  `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.
 - 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

@@ -1,10 +1,10 @@
 ---
 name: pikku-info
 description: >-
-  Discover what exists in a Pikku project — functions, tags, middleware, permissions, HTTP routes,
-  channels, schedulers, queues, and more. Use when you need to understand the project structure,
-  find existing functions, or check what middleware and permissions are defined. TRIGGER when:
-  user asks "what functions exist?", "show me the project structure", "list
+  Discover what exists in a Pikku project — functions (with their transport, middleware and
+  permissions), tags, middleware and permission definitions. Use when you need to understand the
+  project structure, find existing functions, or check what middleware and permissions are
+  defined. TRIGGER when: user asks "what functions exist?", "show me the project structure", "list
   routes/middleware/permissions", or needs to understand an existing Pikku codebase. DO NOT
   TRIGGER when: user is writing new code (use the specific wiring skill) or asking about Pikku
   concepts (use pikku-concepts).
@@ -27,9 +27,19 @@ Use this skill as an execution checklist, not reference material.
 
 Use the `pikku info` CLI commands to inspect this Pikku project. Run the commands below and present the results to the user in a clear summary.
 
+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`.
+
 ## Available Commands
 
-Always use `--silent` to suppress the banner and inspector logs.
+`--silent` suppresses the banner and the inspector's diagnostics, which is what
+you want when parsing the table. It is read by the CLI but not declared as an
+option, so every run also prints `Warning: Unknown option: --silent (ignored)` —
+the warning is wrong, the flag works. Ignore that one line.
+
+For anything you intend to parse rather than read, prefer `--json` (alias
+`-j`, or `--output json`), which emits NDJSON instead of a formatted table.
 
 ### Functions
 
@@ -91,9 +101,9 @@ yarn pikku info permissions --verbose --silent
 
 1. If the user specifies a subcommand (e.g., `/pikku-info functions`), run only that command.
 2. If no subcommand is specified, run all four commands to give a complete project overview.
-3. Always use `--silent` to suppress the Pikku banner and inspector logs.
-4. Use `--verbose` when the user asks for details, file paths, or "more info".
-5. Use `--limit N` to control output size (default is 50 rows).
+3. Always use `--silent` to suppress the Pikku banner and inspector logs, and disregard the spurious "Unknown option" warning it prints.
+4. Use `--verbose` when the user asks for details, file paths, or "more info". On `tags` it swaps counts for names; elsewhere it adds columns.
+5. Use `--limit N` to control output size (default is 50 rows) — the footer tells you how many were withheld.
 6. After running the commands, summarize the findings concisely:
    - Total count of functions, tags, middleware, and permissions
    - Notable patterns (e.g., which transport types are in use, which tags group the most functions)

package/skills/pikku-jose/SKILL.md

@@ -45,15 +45,28 @@ await jwt.init()
 
 **Constructor Parameters:**
 
-- `getSecrets` — Async function returning an array of `{ id, value }` key pairs. First key is used for signing; all keys are tried for verification (supports rotation).
+- `getSecrets` — Async function returning an array of `{ id, value }` key pairs. The **first** entry signs; every entry can verify.
 - `logger` — Optional logger instance.
 
 **Methods:**
 
 - `init(): Promise<void>` — Fetch and cache secrets. Call at startup.
-- `encode<T>(expiresIn: RelativeTimeInput, payload: T): Promise<string>` — Create a signed JWT.
-- `decode<T>(token: string): Promise<T>` — Decode a JWT payload without verification.
-- `verify(token: string): Promise<void>` — Verify a JWT signature and expiry.
+- `encode<T>(expiresIn: RelativeTimeInput, payload: T): Promise<string>` — Create a signed JWT, stamping the signing key's `id` as the token's `kid` header.
+- `decode<T>(token: string): Promise<T>` — **Verifies** the signature and expiry, then returns the payload.
+- `verify(token: string): Promise<void>` — The same check, discarding the payload.
+
+`decode` is not an unchecked read: both methods run `jose.jwtVerify` and both
+throw on a bad signature or an expired token. There is no way to inspect an
+untrusted payload through this service — reach for `jose.decodeJwt` directly if
+you genuinely need that, and treat the result as unauthenticated input.
+
+Tokens are signed **HS256** with a symmetric secret. The algorithm is fixed and
+pinned on verification, so a token arriving with any other `alg` is rejected —
+but it also means this service has no asymmetric (RS256/ES256) mode.
+
+`init()` is not strictly required: `encode` calls it lazily on first use. Call it
+at startup anyway so a missing or unreachable secret fails at boot rather than
+on the first request that needs a token.
 
 ## Usage Patterns
 
@@ -63,15 +76,20 @@ await jwt.init()
 import { JoseJWTService } from '@pikku/jose'
 
 const jwt = new JoseJWTService(
-  async () => [{ id: 'key-1', value: process.env.JWT_SECRET! }],
+  async () => [{ id: 'key-1', value: await secrets.getSecret('JWT_SECRET') }],
   logger
 )
 await jwt.init()
 ```
 
+A signing key is a secret, so it comes from the secrets service rather than
+`process.env` — and because `getSecrets` is a function called on demand, reading
+it there (not once at construction) is what makes the re-init-on-unknown-kid path
+above actually see a rotated key. See `pikku-config`.
+
 ### Secret Rotation
 
-Supply multiple keys. The first is used for signing; all are tried for verification:
+Supply multiple keys. The first signs; the rest stay available for verification:
 
 ```typescript
 const jwt = new JoseJWTService(async () => [
@@ -80,6 +98,17 @@ const jwt = new JoseJWTService(async () => [
 ])
 ```
 
+Verification resolves the key by the token's `kid` header rather than trying each
+secret in turn — which is why `encode` stamps the signing key's `id` there, and
+why the ids must stay stable across a rotation. Keep an id in the list for as
+long as tokens bearing it can still be in flight.
+
+When a `kid` isn't in the cache, the service re-runs `getSecrets()` once before
+giving up with `Missing secret for id: <kid>`. That is what lets a running server
+pick up a newly added key without a restart, provided `getSecrets` reads from
+something live (a secret store) rather than a value captured at boot. A token
+with no `kid` at all falls back to the current signing key.
+
 ### With Pikku Services
 
 ```typescript

package/skills/pikku-knowledge/SKILL.md

@@ -161,8 +161,8 @@ And writing again replaces it rather than adding a second
 | `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 grants in `scenarios.actors` |
-| `persona:`  | a persona name                                     | `scenarios.personas` in `pikku.config.json`                                       |
+| `scope:`    | a scope name                                       | the `scopes:` a function gates itself with, plus the scopes a `defineSystemRole()` confers |
+| `persona:`  | a persona name                                     | `definePersonas()`                                                                |
 
 Ids are case-sensitive: `createEntry` is not `createentry`.
 
@@ -176,7 +176,7 @@ These are all things that exist somewhere better, so a note is always the copy t
 
 | Do not write                        | Because it lives in                                        |
 | ----------------------------------- | ---------------------------------------------------------- |
-| a `personas/` section               | `scenarios.personas` in `pikku.config.json`                |
+| a `personas/` section               | `definePersonas()` in the project's own code               |
 | a `scenarios/` section              | the gherkin block inside the slice it belongs to           |
 | a `permissions/` section            | a decision note under `decisions/security/`                |
 | a list of tables, columns or routes | `pikku meta` — the generated schema _is_ the schema        |

package/skills/pikku-kysely/SKILL.md

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