@pikku/skills 0.12.21 → 0.12.25

package/skills/pikku-scenario/references/persona-run.md

@@ -0,0 +1,148 @@
+# Running a persona as a virtual user
+
+`pikku persona run <environment> <persona>` signs a declared persona in over the
+app's real auth and works the API in character, driven by a model. A persona
+while running **is** the virtual user — there is no second declaration for it.
+
+**It is not a test runner.** It asserts nothing, and a green run proves nothing:
+what it produces is _findings_, and their absence is only ever "not this time,
+not with this seed". Findings set exit code 1, so a run can gate a pipeline;
+giving up on a goal does not, because that is a user being a user.
+
+Everything it needs is already in the project — the catalogue is the function
+meta, the intents are the scenarios' own prose, the identity is the persona
+signing in, the scopes come from their declared roles. The only new input is
+which person to be.
+
+Declaring personas — persona versus actor, `definePersonas`, materialised
+actors — is in the skill itself, under **Personas and actors**. This is the
+running half.
+
+## The shape of a run
+
+```bash
+SCENARIO_ACTOR_SECRET=… pikku persona run local shopper
+SCENARIO_ACTOR_SECRET=… pikku persona run local shopper -d careless --seed 42
+SCENARIO_ACTOR_SECRET=… pikku persona run staging auditor \
+  --goals "reconcile the order totals" --steps 80 --out runs/auditor.json
+```
+
+Both arguments are required positionals: the environment key from
+`environments`, then the persona id. A run needs a model — `--model`, or
+`scenarios.model` in `pikku.config.json` — and an AI provider in the
+environment (`OPENAI_BASE_URL` + `OPENAI_API_KEY`, or `LITELLM_PROXY_URL` +
+`LITELLM_API_KEY`).
+
+| Flag                   | Effect                                                                                                                                                |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--disposition` / `-d` | How they behave. Overrides the persona's own                                                                                                          |
+| `--goals`              | Comma-separated, in your words — run _alongside_ the persona's own and the ones derived from scenarios                                                |
+| `--steps`              | Model turns before it stops (default 40)                                                                                                              |
+| `--mutations`          | Non-read calls before it stops                                                                                                                        |
+| `--duration`           | Wall clock before it stops, e.g. `30m`                                                                                                                |
+| `--seed`               | Replay — the same seed schedules the same run                                                                                                         |
+| `--model`              | The model they think with                                                                                                                             |
+| `--allow-approval`     | Offer the endpoints the app marked as needing a human's approval. Off by default: those are the ones that spend money                                 |
+| `--skip-role-check`    | Start without verifying declared roles against the stage                                                                                              |
+| `--api-url`            | Override the environment's `apiUrl`, for a target that only exists at run time. It replaces the url, not the environment's classification — see below |
+| `--out`                | Write the whole run — every step, response and finding — as JSON                                                                                      |
+
+## The dispositions
+
+A disposition is a bundle of instructions and mechanical dials (move weights,
+temperature, repeat and re-read rates). `tuning` on the persona adjusts those
+dials without replacing the character — a tuned `careless` user is still
+careless. Passing `--disposition` drops the persona's `tuning`, because you
+asked to run them differently rather than to bend their dials into another
+shape.
+
+| Disposition   | Who that is                                                                                                                   |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `realistic`   | The default. A competent user reading schemas and entering plausible values                                                   |
+| `careless`    | Busy, interrupted, half-remembering; submits twice, enters odd-but-legal values. **Where most production bugs actually live** |
+| `newcomer`    | First time here, holds no ids in their head, must find a path from the lists that exist (`emptyMemory`)                       |
+| `stale`       | Working from old notes — reaches for ids that may no longer resolve, to see how the product says so                           |
+| `auditor`     | Reconciling, not achieving: reads one fact from every endpoint claiming to know it and reports disagreement. Read-only        |
+| `adversarial` | Probing whether the boundaries are enforced. Inverted oracle — a 2xx from something it should not reach is the finding        |
+| `accountable` | Doing the job for real. The **only** disposition production accepts                                                           |
+
+## Credentials, and which one wins
+
+Three variables, checked in this order. None of them belongs in
+`pikku.config.json`.
+
+1. **`FABRIC_OPERATOR_TOKEN`** — what a deployed stage accepts. Asymmetric, and
+   it needs no account the target would not otherwise have, so it wins over the
+   other two when both are present.
+2. **`PIKKU_PERSONA_SECRETS`** — `id=secret,id=secret`, already-derived
+   per-persona credentials. Hand a run only the personas it should be able to
+   be; asking for one outside the list is refused by name rather than falling
+   through to the root. Mint them with `pikku persona secret [personas...]` —
+   naming none mints all.
+3. **`SCENARIO_ACTOR_SECRET`** — the root secret, which derives every persona's
+   credential and is therefore entitled to all of them. Only `pikku dev` serves
+   the endpoint it opens.
+
+## Production is opt-in, twice
+
+A persona's `environments` omitted means every configured environment **except**
+those flagged `production: true` — nothing reaches production by being
+forgotten. Naming one requires `disposition: 'accountable'`.
+
+That rule is checked twice on purpose: the inspector checks the declaration at
+build time, and sign-in re-checks the **effective** disposition — the persona's
+own, or whatever `--disposition` replaced it with — before the run starts. So
+`--disposition adversarial` cannot point an accountable persona at production.
+The build check trusts the file; the run check does not trust which artifact got
+deployed.
+
+**That rule is keyed on the environment's name, not its url.** `production:
+true` is a label a person wrote in `pikku.config.json`; nothing can tell from a
+url whether real customers are behind it. `--api-url` replaces the url and keeps
+the classification, so a non-production environment repointed at a production
+host is still treated as non-production, and an adversarial persona will happily
+run against it. The flag is for a target that only exists at run time — a
+freshly provisioned sandbox. Point it anywhere else and the guard above is not
+protecting you.
+
+## The role check happens before the first step
+
+A run reads its own roles back from the stage and compares them to what the
+persona declared. It refuses on a mismatch, before anything runs — findings
+from a persona whose roles drifted are about the seed, and reading them as
+product bugs is how a whole run gets thrown away. A stage that reports no roles
+warns and runs unverified. `--skip-role-check` is for a target whose auth
+reports roles somewhere pikku cannot read; findings from such a run may be seed
+drift.
+
+## The other subcommands
+
+| Command                              | What it answers                                                                            |
+| ------------------------------------ | ------------------------------------------------------------------------------------------ |
+| `pikku persona list`                 | Who is declared — who each one is, what they may do, what they want                        |
+| `pikku persona sync <environment>`   | Which personas that environment will provision, with which roles, and why any were skipped |
+| `pikku persona secret [personas...]` | Mint per-persona credentials from the root secret                                          |
+
+`sync` **reports**; it does not provision. The CLI has no connection to a
+deployed environment's database, so the provisioning happens in the deployment —
+pass the generated personas to `pikkuFabric` from `@pikku/better-auth`.
+
+## What NOT to do
+
+- **Do not treat a clean run as a pass.** Nothing was asserted. Use scenarios
+  for the things that must hold.
+- **Do not run a persona declared `runnable: false`**, or one whose `account`
+  names a provider. The first is someone who exists to be acted upon — running
+  her races the scenario that bans her — and the second needs a human at a
+  consent screen. Both are refused before sign-in rather than partway through.
+- **Do not use `--api-url` to reach a production host from a non-production
+  environment.** The disposition guard reads the named environment's
+  `production` flag, not the url you pointed it at, so nothing will stop you.
+- **Do not put any of the three credentials in `pikku.config.json`.** They are
+  environment variables.
+- **Do not pass `--allow-approval` casually.** The endpoints behind it are the
+  ones the app marked as needing a human because they spend money.
+- **Do not read a finding from a run started with `--skip-role-check` as a
+  product bug** until the roles are confirmed some other way.
+- **Do not expect `--goals` to replace the persona's goals.** They are appended;
+  a run that replaces Susan's goals is not Susan.

package/skills/pikku-service-backends/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: pikku-service-backends
+description: >-
+  Use when picking or wiring a backend for one of Pikku's core service interfaces — ContentService
+  (S3, Backblaze B2), QueueService (SQS), SecretService (AWS Secrets Manager, Redis, MongoDB),
+  SchemaService (AJV, cfworker), ChannelStore, EventHubStore, WorkflowService, SessionStore or
+  AgentRunService (Redis, MongoDB). Covers which backend to choose, what each one silently does
+  differently, and the failures they swallow. TRIGGER when: code uses S3Content, B2Content,
+  SQSQueueService, AWSSecrets, RedisChannelStore, RedisSecretService, MongoDBChannelStore,
+  PikkuMongoDB, AjvSchemaService or CFWorkerSchemaService, or the user asks how to store files,
+  secrets, channel state or sessions. DO NOT TRIGGER when: defining service factories themselves
+  (use pikku-services), SQL via Kysely (use pikku-kysely), or the Lambda/Cloudflare runtimes
+  themselves (use pikku-deploy).
+installGroups: [core]
+---
+
+# Pikku Service Backends
+
+## Agent Operating Procedure
+
+Use this skill as an execution checklist, not reference material.
+
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
+3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
+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.
+
+Constructor shapes and method signatures come from `pikku doc` — run
+`pikku doc --ai` for the installed surface. This skill is the part the compiler
+cannot tell you: which backend implements which interface, and what changes when
+you swap one for another.
+
+`pikku-services` covers how to build and wire a service. This covers what to put
+behind the interface.
+
+## Pick a backend
+
+| Interface | Backends | Package |
+| --- | --- | --- |
+| `ContentService` | `S3Content`, `B2Content` | `@pikku/aws-services`, `@pikku/backblaze` |
+| `QueueService` | `SQSQueueService` | `@pikku/aws-services` |
+| `SecretService` | `AWSSecrets`, `RedisSecretService`, `MongoDBSecretService` | `@pikku/aws-services`, `@pikku/redis`, `@pikku/mongodb` |
+| `SchemaService` | `AjvSchemaService`, `CFWorkerSchemaService` | `@pikku/schema-ajv`, `@pikku/schema-cfworker` |
+| `ChannelStore`, `EventHubStore` | Redis, MongoDB | `@pikku/redis`, `@pikku/mongodb` |
+| `PikkuWorkflowService`, `WorkflowRunService` | Redis, MongoDB | `@pikku/redis`, `@pikku/mongodb` |
+| `SessionStore`, `AgentRunService`, `DeploymentService` | Redis, MongoDB | `@pikku/redis`, `@pikku/mongodb` |
+| `AgentStorageService`, `AgentRunStateService` | MongoDB **only** | `@pikku/mongodb` |
+
+SQL is the third option for every store interface in that table —
+`KyselyChannelStore`, `KyselyWorkflowService`, `KyselySecretService` and friends
+live in `@pikku/kysely` and are covered by `pikku-kysely`, because using them
+means writing queries.
+
+Per-package detail: `references/aws.md`, `references/backblaze.md`,
+`references/redis.md`, `references/mongodb.md`, `references/schema.md`.
+
+## What changes when you swap a backend
+
+### Redis and MongoDB are not interchangeable, in two ways
+
+They cover almost the same interface list, but:
+
+- **MongoDB has AI conversation storage and Redis does not.**
+  `MongoDBAgentStorageService` is the only implementation of
+  `AgentStorageService`/`AgentRunStateService`. A Redis-only deployment cannot
+  persist agent conversations.
+- **Every MongoDB service needs `await init()`; no Redis service does.** `init()`
+  is what creates the collections and indexes. Constructing a
+  `MongoDBChannelStore` and using it without awaiting `init()` compiles and then
+  behaves like an unindexed collection — slow first, wrong later.
+
+Redis services take the connection directly (an ioredis `Redis`, `RedisOptions`,
+or a URL string). MongoDB services take a `Db`, which means a `PikkuMongoDB`
+wrapper has to be constructed and initialised before any of them.
+
+### The two content backends share a design and a trap
+
+`S3Content` and `B2Content` are close enough to swap, and both:
+
+- treat `bucket` on every call as a **logical** bucket stored as a path prefix
+  (`${bucket}/${key}`) inside the one real bucket the config names. Do not
+  provision a bucket per logical bucket — the config takes exactly one.
+- **ignore `visibility` on `getUploadURL`**.
+- **swallow write failures**: `writeFile`, `copyFile` and `deleteFile` log and
+  return `false` rather than throwing, while the read paths throw. An ignored
+  return value is a silently lost file.
+
+Where they diverge:
+
+| | `S3Content` | `B2Content` |
+| --- | --- | --- |
+| Signing failure | **Fails open** — logs and returns the *unsigned* URL | Throws |
+| `writeFile` memory | Streams | **Buffers the whole stream** to compute a SHA-1 |
+| Client-side upload integrity | Presigned, expires at a fixed 3600s | `X-Bz-Content-Sha1: do_not_verify` — unverified |
+| Credential rotation | Picked up by the SDK provider chain | Auth is cached for the instance's lifetime — construct a new `B2Content` |
+
+The S3 fail-open is the one to design around: on a private CloudFront
+distribution the client gets a 403, and on a public one you have just handed out
+an unrestricted link. Validate `signConfig` at boot rather than trusting a throw.
+
+### Secret backends differ on whether the app can write
+
+- **`AWSSecrets` is read-only.** `setSecret` and `deleteSecret` throw. Secrets
+  are managed out of band; the app only reads them.
+- **Redis and MongoDB do envelope encryption** and can write, delete, and
+  `rotateKEK()`. Rotation requires `previousKey` to have been set — a service
+  constructed without it cannot rotate later without a redeploy.
+- **Only MongoDB has audit hooks** (`audit`, `auditReads`).
+
+`AWSSecrets` also collapses every failure — missing, denied, binary-only — into
+the same `FATAL: Error finding secret: <id>`, with the real reason on the error's
+`cause`. Read `cause` before concluding a secret is absent; `hasSecret` returns
+`false` for any error and cannot distinguish the two either.
+
+### AJV and cfworker are not drop-in equivalents
+
+Swapping them changes behaviour without changing types:
+
+- **`useDefaults`**: AJV fills schema defaults into the validated object in
+  place. cfworker does not, so a field you relied on being defaulted arrives
+  `undefined` on Workers.
+- **Recompilation**: AJV caches by name for the process lifetime — a second
+  `compileSchema` with the same name is a no-op. cfworker replaces the validator
+  when the schema value changes, which is what lets a dev hot-reload pick up
+  regenerated schemas. On AJV, restart the process instead.
+- **Coercion is neither one's job.** `coerceTypes` is off; a query-string `"1"`
+  becomes `1` in the wiring layer, not here.
+
+Both throw `UnprocessableContentError` (422) on a failed validation, and both
+throw a **bare string** — `Missing validator for <name>` — for a *missing*
+schema. It is not an `Error`, so `catch (e) { e.message }` reads `undefined`.
+That almost always means codegen did not run.
+
+Use cfworker on Cloudflare Workers: AJV compiles with `new Function`, which the
+Workers runtime forbids.
+
+### SQS gives you no result back
+
+`SQSQueueService` sets `supportsResults = false` and `getJob()` always throws —
+the transport is fire-and-forget. So is the Azure Storage Queue backend. Reach
+for BullMQ or PgBoss (see `pikku-wiring`) when a caller needs the job's result.
+
+## What NOT to do
+
+- Do not ignore the boolean from `writeFile`, `copyFile` or `deleteFile`. Both
+  content backends report failure that way and neither throws.
+- Do not rely on `S3Content.signURL` throwing. It fails open and hands back an
+  unsigned URL.
+- Do not construct a MongoDB-backed service without awaiting `init()`.
+- Do not assume AJV and cfworker validate identically — `useDefaults` alone
+  changes what your function receives.
+- Do not provision one real bucket per logical bucket; the prefix is the bucket.
+- Do not reach for SQS when a caller needs the result of the job.

package/skills/pikku-service-backends/references/aws.md

@@ -0,0 +1,106 @@
+# AWS (`@pikku/aws-services`)
+
+```bash
+yarn add @pikku/aws-services
+```
+
+AWS-backed implementations of the content, queue, and secret interfaces.
+
+## `S3Content` — ContentService
+
+```typescript
+import { S3Content } from '@pikku/aws-services'
+
+const content = new S3Content(
+  config: { bucketName: string; region: string; endpoint?: string },
+  logger: Logger,
+  signConfig: { keyPairId: string; privateKey: string }
+)
+```
+
+`endpoint` is what points the client at LocalStack or an S3-compatible store.
+
+Every method takes a single **args object**, matching the shared `ContentService`
+interface. None of them are positional:
+
+- `signURL({ url, dateLessThan, dateGreaterThan? }): Promise<string>` — CloudFront-sign an absolute URL
+- `signContentKey({ bucket, contentKey, dateLessThan, dateGreaterThan? }): Promise<string>`
+- `getUploadURL({ bucket, fileKey, contentType, visibility? }): Promise<{ uploadUrl, assetKey }>` — `visibility` is ignored
+- `readFile({ bucket, key }): Promise<ReadableStream | NodeJS.ReadableStream>`
+- `readFileAsBuffer({ bucket, key }): Promise<Buffer>`
+- `writeFile({ bucket, key, stream }): Promise<boolean>`
+- `copyFile({ bucket, key, fromAbsolutePath }): Promise<boolean>`
+- `deleteFile({ bucket, key }): Promise<boolean>`
+
+`signContentKey` builds `https://<bucketName>/<bucket>/<contentKey>` — it uses
+`bucketName` as the **host**. For signed content that value must therefore be
+your CloudFront domain, not a plain bucket name, which means the same config
+field is doing two jobs.
+
+Presigned upload URLs expire after a fixed **3600s**, not configurable through
+the service.
+
+```typescript
+const createSingletonServices = pikkuServices(async (config) => {
+  const logger = new PinoLogger()
+  const content = new S3Content(
+    { bucketName: config.s3Bucket, region: config.awsRegion },
+    logger,
+    { keyPairId: config.cfKeyPairId, privateKey: config.cfPrivateKey }
+  )
+  return { config, logger, content }
+})
+```
+
+## `SQSQueueService` — QueueService
+
+```typescript
+import { SQSQueueService } from '@pikku/aws-services'
+
+const queue = new SQSQueueService({
+  region: string,
+  queueUrlPrefix: string, // e.g. 'https://sqs.us-east-1.amazonaws.com/123456789/'
+  endpoint?: string,      // LocalStack or a custom SQS endpoint
+})
+```
+
+- `add<T>(queueName: string, data: T, options?: JobOptions): Promise<string>` — returns SQS's `MessageId`
+- `getJob()` — always **throws**
+
+The queue URL is `queueUrlPrefix + queueName`, so the name in `wireQueueWorker`
+has to match the SQS queue exactly.
+
+Constraints inherited from SQS, enforced in `add`:
+
+- `options.delay` is in **milliseconds**, floored to whole seconds. Over
+  900_000ms (15 minutes) or negative throws before the message is sent.
+- Standard queues only — no FIFO, so no `MessageGroupId` and no ordering
+  guarantee.
+- `data` is `JSON.stringify`d, which is where a `Date` or a `Map` quietly
+  degrades.
+
+```typescript
+const createSingletonServices = pikkuServices(async (config) => {
+  const queue = new SQSQueueService({
+    region: config.awsRegion,
+    queueUrlPrefix: config.sqsUrlPrefix,
+  })
+  return { config, queue }
+})
+```
+
+## `AWSSecrets` — SecretService
+
+```typescript
+import { AWSSecrets } from '@pikku/aws-services'
+
+const secrets = new AWSSecrets({ awsRegion: 'eu-west-2' })
+```
+
+`AWSConfig` has one field, `awsRegion` — there is no credentials option; the
+SDK's default provider chain (instance role, env, profile) supplies those.
+
+- `getSecret<T = string>(SecretId: string): Promise<SecretValue<T>>` — a JSON secret is parsed automatically, so pass a shape as `T` (a non-JSON value comes back as the raw string). The result is a branded `SecretValue`, not a bare value — reveal it where it is used rather than passing it through logs
+- `getSecrets<T>(SecretIds: (keyof T & string)[]): Promise<Partial<T>>` — missing keys are omitted rather than thrown
+- `hasSecret(SecretId: string): Promise<boolean>` — performs a full fetch
+- `setSecret` / `deleteSecret` — **not implemented**; they throw

package/skills/pikku-service-backends/references/backblaze.md

@@ -0,0 +1,57 @@
+# Backblaze B2 (`@pikku/backblaze`)
+
+```bash
+yarn add @pikku/backblaze
+```
+
+`B2Content` implements `ContentService` over Backblaze B2.
+
+```typescript
+import { B2Content } from '@pikku/backblaze'
+
+const content = new B2Content(config: B2ContentConfig, logger: Logger)
+```
+
+`B2ContentConfig` has exactly three fields — `applicationKeyId`, `applicationKey`
+and `bucketId`. There is no `cdnUrl`: downloads are served from the `downloadUrl`
+B2 returns at authorization.
+
+Every method takes a single **args object**, matching the shared `ContentService`
+interface. None of them are positional:
+
+- `signContentKey({ bucket, contentKey, dateLessThan }): Promise<string>` — a full download URL with an `Authorization` query param
+- `signURL({ url, dateLessThan }): Promise<string>` — re-signs an existing `/file/` URL; a URL with no `/file/` segment is returned untouched
+- `getUploadURL({ bucket, fileKey, contentType, visibility? }): Promise<UploadURLResult>` — `visibility` is ignored
+- `writeFile({ bucket, key, stream }): Promise<boolean>`
+- `copyFile({ bucket, key, fromAbsolutePath }): Promise<boolean>`
+- `readFile({ bucket, key }): Promise<ReadableStream | NodeJS.ReadableStream>`
+- `readFileAsBuffer({ bucket, key }): Promise<Buffer>`
+- `deleteFile({ bucket, key }): Promise<boolean>`
+
+Because `writeFile` drains the whole stream into a `Buffer` before uploading
+(B2's upload endpoint needs a SHA-1 and a content length up front), large uploads
+should go through `getUploadURL` and be sent by the client directly.
+
+```typescript
+const createSingletonServices = pikkuServices(async (config) => {
+  const logger = new PinoLogger()
+  const content = new B2Content(
+    {
+      applicationKeyId: config.b2KeyId,
+      applicationKey: config.b2AppKey,
+      bucketId: config.b2BucketId,
+    },
+    logger
+  )
+  return { config, logger, content }
+})
+```
+
+```typescript
+await content.writeFile({ bucket: 'avatars', key: `${userId}.png`, stream })
+const url = await content.signContentKey({
+  bucket: 'avatars',
+  contentKey: `${userId}.png`,
+  dateLessThan: new Date(Date.now() + 60_000),
+})
+```

package/skills/pikku-service-backends/references/mongodb.md

@@ -0,0 +1,90 @@
+# MongoDB (`@pikku/mongodb`)
+
+```bash
+yarn add @pikku/mongodb
+```
+
+## `PikkuMongoDB` — connection wrapper
+
+Every service below takes a `Db`, so the wrapper is constructed and initialised
+first.
+
+```typescript
+import { PikkuMongoDB } from '@pikku/mongodb'
+
+const mongo = new PikkuMongoDB(
+  logger: Logger,
+  clientOrUri: MongoClient | string,
+  dbName: string,
+  options?: MongoClientOptions
+)
+
+await mongo.init()
+mongo.db  // Db instance for queries
+await mongo.close()
+```
+
+## Available services
+
+| Service | Interface | Purpose |
+| --- | --- | --- |
+| `MongoDBChannelStore` | `ChannelStore` | WebSocket channel state persistence |
+| `MongoDBEventHubStore` | `EventHubStore` | Event hub state persistence |
+| `MongoDBWorkflowService` | `PikkuWorkflowService` | Workflow definition storage |
+| `MongoDBWorkflowRunService` | `WorkflowRunService` | Workflow execution tracking |
+| `MongoDBDeploymentService` | `DeploymentService` | Deployment state management |
+| `MongoDBAgentStorageService` | `AgentStorageService`, `AgentRunStateService` | AI conversation/run storage |
+| `MongoDBAgentRunService` | `AgentRunService` | Agent execution tracking |
+| `MongoDBSecretService` | `SecretService` | Encrypted secret storage (envelope encryption) |
+| `MongoDBSessionStore` | `SessionStore` | Persisted user sessions |
+
+All of them take a `Db` in the constructor and have an `init()` method that
+creates the collections and indexes. **Await it** — a service used without it
+behaves like an unindexed collection.
+
+## `MongoDBSecretService`
+
+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 { MongoDBSecretService } from '@pikku/mongodb'
+
+const secrets = new MongoDBSecretService(mongo.db, {
+  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()
+```
+
+## Full setup
+
+```typescript
+import {
+  PikkuMongoDB,
+  MongoDBChannelStore,
+  MongoDBWorkflowService,
+} from '@pikku/mongodb'
+
+const createSingletonServices = pikkuServices(async (config) => {
+  const logger = new PinoLogger()
+  const mongo = new PikkuMongoDB(logger, config.mongoUri, 'myapp')
+  await mongo.init()
+
+  const channelStore = new MongoDBChannelStore(mongo.db)
+  await channelStore.init()
+
+  const workflowService = new MongoDBWorkflowService(mongo.db)
+  await workflowService.init()
+
+  return { config, logger, database: mongo, channelStore, workflowService }
+})
+```

package/skills/pikku-service-backends/references/redis.md

@@ -0,0 +1,75 @@
+# Redis (`@pikku/redis`)
+
+```bash
+yarn add @pikku/redis
+```
+
+Redis-backed implementations of Pikku's core service interfaces, using
+[ioredis](https://github.com/redis/ioredis). Every service accepts a Redis
+connection — an ioredis `Redis` instance, `RedisOptions`, or a connection
+string — in its constructor. None of them need an `init()` call.
+
+| Service | Interface | Purpose |
+| --- | --- | --- |
+| `RedisChannelStore` | `ChannelStore` | WebSocket channel state persistence |
+| `RedisEventHubStore` | `EventHubStore` | Event hub state persistence |
+| `RedisWorkflowService` | `PikkuWorkflowService` | Workflow definition storage |
+| `RedisWorkflowRunService` | `WorkflowRunService` | Workflow execution tracking |
+| `RedisDeploymentService` | `DeploymentService` | Deployment state management |
+| `RedisAgentRunService` | `AgentRunService` | Agent execution tracking |
+| `RedisSecretService` | `SecretService` | Encrypted secret storage (envelope encryption) |
+| `RedisSessionStore` | `SessionStore` | Persisted user sessions |
+
+There is no Redis implementation of `AgentStorageService` — AI conversation
+storage is MongoDB-only.
+
+## `RedisSecretService`
+
+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: {
+    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>
+await secrets.getSecrets<T>(keys: (keyof T & string)[]): Promise<Partial<T>>
+await secrets.hasSecret(key: string): Promise<boolean>
+await secrets.setSecret(key: string, value: unknown): Promise<void>
+await secrets.deleteSecret(key: string): Promise<void>
+await secrets.rotateKEK(): Promise<number>
+await secrets.close(): Promise<void>
+```
+
+## Full setup
+
+```typescript
+import {
+  RedisChannelStore,
+  RedisWorkflowService,
+  RedisSecretService,
+} from '@pikku/redis'
+
+const createSingletonServices = pikkuServices(async (config) => {
+  const logger = new PinoLogger()
+
+  const channelStore = new RedisChannelStore(config.redisUrl)
+  const workflowService = new RedisWorkflowService(config.redisUrl)
+
+  const secrets = new RedisSecretService(config.redisUrl, {
+    key: config.kekPassphrase,
+  })
+
+  return { config, logger, channelStore, workflowService, secrets }
+})
+```