@pikku/skills 0.12.2 → 0.12.6

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

@@ -2,10 +2,11 @@
 name: pikku-ai-voice
 description: >-
   Use when adding voice input (speech-to-text) or voice output (text-to-speech) to AI agents in a
-  Pikku app. Covers voiceInput/voiceOutput middleware hooks and STT/TTS service interfaces.
-  TRIGGER when: code uses voiceInput, voiceOutput, STTService, TTSService, or user asks about
-  voice, speech-to-text, text-to-speech, or @pikku/ai-voice. DO NOT TRIGGER when: user asks about
-  AI agent wiring (use pikku-ai-agent) or Vercel AI SDK (use pikku-ai-vercel).
+  Pikku app. Covers the voiceInput/voiceOutput AI middleware from @pikku/core/ai-agent, per-script
+  voices, and barge-in. TRIGGER when: code uses voiceInput, voiceOutput, or user asks about voice
+  agents, speech-to-text, text-to-speech, transcription, or @pikku/ai-voice. DO NOT TRIGGER when:
+  user asks about AI agent wiring generally (use pikku-ai-agent) or the runner itself (use
+  pikku-ai-vercel).
 ---
 
 # Pikku AI Voice (Speech I/O)
@@ -20,69 +21,142 @@ Use this skill as an execution checklist, not reference material.
 4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
 5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
 
-`@pikku/ai-voice` provides speech-to-text and text-to-speech middleware hooks for Pikku AI agents.
+## `@pikku/ai-voice` is deprecated and empty
 
-## Installation
+The package still publishes, but its entire source is `export {}` — there are no
+`STTService`/`TTSService` interfaces and nothing to import. Do not add it as a
+dependency.
 
-```bash
-yarn add @pikku/ai-voice
-```
+Voice now lives in **`@pikku/core/ai-agent`** as two AI middlewares, and the
+speech models are reached through the `aiAgentRunner` (`transcribe` /
+`generateSpeech`) rather than through separate services. See `pikku-ai-vercel`.
 
 ## API Reference
 
-### Service Interfaces
-
 ```typescript
-interface STTService {
-  transcribe(
-    audio: Uint8Array,
-    options?: { language?: string; format?: string }
-  ): Promise<string>
-}
-
-interface TTSService {
-  synthesize(
-    text: string,
-    options?: { voice?: string; format?: string }
-  ): Promise<Uint8Array>
-  synthesizeStream?(
-    text: string,
-    options?: { voice?: string; format?: string }
-  ): AsyncIterable<Uint8Array>
-}
-```
+import { voiceInput, voiceOutput } from '@pikku/core/ai-agent'
 
-### Middleware Hooks
-
-```typescript
-import { voiceInput, voiceOutput } from '@pikku/ai-voice'
+voiceInput(config?: {
+  model?: string               // transcription model — required in practice
+  language?: string            // forwarded as openai providerOptions.language
+  allowedAudioHosts?: string[] // allowlist for audio parts given as a URL
+})
 
-voiceInput(config?: { language?: string }): PikkuAIMiddlewareHooks
-voiceOutput(config?: { format?: string; voice?: string }): PikkuAIMiddlewareHooks
+voiceOutput(config?: {
+  model?: string               // speech model — required in practice
+  voice?: string
+  format?: string
+  instructions?: string
+  speed?: number
+  language?: string
+  speakableScripts?: string[] | Record<string, string>
+  always?: boolean
+})
 ```
 
-These return middleware hooks that can be attached to AI agent wirings to automatically transcribe audio input and synthesize audio output.
-
-## Usage Patterns
-
-### Voice-Enabled Agent
+Both attach through the agent's **`aiMiddleware`** array, not a
+`middlewareHooks` option, and the agent is declared with `pikkuAIAgent` — there
+is no `wireAIAgent`.
+
+### `voiceInput` — audio in, text in its place
+
+It rewrites the last user message, replacing each `audio/*` file part with a
+text part holding the transcript. Downstream nothing can tell the turn was
+spoken, which is why it records two shared-notes keys on the way past:
+
+- `SPOKEN_TURN` (`'voice:spokenTurn'`) — `true`/`false` on every turn it sees.
+  **Absent** when the middleware isn't wired at all, which is what lets
+  `voiceOutput` still speak for a caller that has no voice input.
+- `SPOKEN_TRANSCRIPT` (`'voice:transcript'`) — what the user was heard to say,
+  only when something was heard. The stream wiring forwards it to the client as
+  a `transcript` event; a voice client has no other way to know what its own
+  audio said, and without it the user's turn renders as an empty bubble.
+
+Behaviours that decide how a voice loop should be written:
+
+- **It is a no-op without `aiAgentRunner.transcribe`** — no error, the audio
+  simply passes through untouched.
+- **`config.model` is required once audio actually arrives**, and throws then
+  rather than at wiring time.
+- **A turn that was entirely non-speech throws `NoSpeechDetectedError`.** Catch
+  it and go back to listening without running the agent — answering a
+  hallucinated sentence is worse than answering nothing. It is deliberately
+  distinct from a transcription failure, which is worth reporting.
+- **Non-speech means an empty transcript, and nothing cleverer.** There was a
+  per-segment confidence gate here and it was removed: Whisper is
+  subtitle-trained, so it is *confident* when it invents ("Thank you." scored
+  better than the real sentence beside it). Pick an ASR that returns an empty
+  string on silence rather than trying to filter one that doesn't.
+- Audio arrives either inline (base64 `data`) or as a `url` fetched through
+  `safeFetch`; either way 50MB is the ceiling.
+
+### `voiceOutput` — sentence-at-a-time synthesis
+
+It intercepts the output stream, buffers `text-delta`s to a sentence boundary,
+and synthesizes each finished sentence immediately, so the first is playing while
+the rest is still being written. Emissions are chained even though generation
+overlaps, so the client hears them in order; on `done` it flushes the tail,
+awaits the chain, and emits `audio-done` before the `done` event.
+
+- **It speaks only in reply to speech** unless `always: true`. Only an explicit
+  `SPOKEN_TURN === false` silences it — the key being absent (no `voiceInput`
+  wired) still speaks. Set `always` for a read-aloud mode or a kiosk, where the
+  whole output is meant to be heard; leave it off for an agent serving both typed
+  and spoken callers, since synthesizing replies nobody is listening to costs
+  real money per sentence.
+- **A failed sentence is logged and skipped**, not thrown — one silent sentence
+  beats the rest of the reply never arriving.
+- **Barge-in aborts synthesis, not just playback**: the stream's `signal` is
+  passed to the speech model, so sentences in flight stop being billed.
+
+### `speakableScripts` — declare what the model can pronounce
+
+Handed a script it has no voice for, a speech model typically neither fails nor
+stays quiet: Kokoro reads out the *letter names* — 24 seconds of "Arabic meem,
+Arabic ra" for a one-line sentence. Declaring the range leaves anything outside
+it unspoken and reports it once per reply as a `voice-unsupported` data event.
+
+The record form maps script → voice, because a multilingual model usually needs
+the matching voice too: asked for Chinese in a default American-English voice,
+Kokoro spells the characters out in 9.9s where `zf_xiaobei` says it in 3.5.
+
+Known scripts: `latin`, `devanagari`, `han`, `kana`, `arabic`, `cyrillic`,
+`hangul`, `hebrew`, `greek`, `thai`. A sentence in several is settled by
+precedence, not config order — `kana` first (it appears only in Japanese, so it
+decides; `han` alone cannot), `latin` last (it turns up inside sentences in every
+other script). Omitting the option means no check at all, which is right for a
+genuinely multilingual provider.
+
+`unspeakableScripts(text, speakable)` and `voiceForText(text, speakable,
+fallback)` are exported if you need the same decision outside the middleware.
+
+## Usage Pattern
 
 ```typescript
-import { voiceInput, voiceOutput } from '@pikku/ai-voice'
-import { wireAIAgent } from '@pikku/core/ai-agent'
+import { pikkuAIAgent } from '#pikku/agent/pikku-agent-types.gen.js'
+import { voiceInput, voiceOutput } from '@pikku/core/ai-agent'
 
-wireAIAgent({
+export const voiceAssistant = pikkuAIAgent({
   name: 'voice-assistant',
-  model: 'openai:gpt-4o',
-  systemPrompt: 'You are a voice assistant.',
-  middlewareHooks: [
-    voiceInput({ language: 'en' }),
-    voiceOutput({ voice: 'alloy', format: 'mp3' }),
+  description: 'Holds a spoken conversation',
+  goal: 'You are a voice assistant. You are being listened to, not read.',
+  model: 'openai/gpt-5-mini',
+  aiMiddleware: [
+    voiceInput({ model: 'deepinfra/openai/whisper-large-v3-turbo' }),
+    voiceOutput({
+      model: 'deepinfra/hexgrad/Kokoro-82M',
+      speakableScripts: {
+        han: 'zf_xiaobei',
+        kana: 'jf_alpha',
+        devanagari: 'hf_alpha',
+        latin: 'af_bella',
+      },
+    }),
   ],
-  func: myAgentFunc,
 })
 ```
 
-### Custom STT/TTS Services
-
-Implement the `STTService` and `TTSService` interfaces with your provider (OpenAI Whisper, ElevenLabs, etc.) and register them as singleton services.
+Write the goal for the ear: no lists, no markdown, no IDs read digit by digit.
+The one thing worth spelling out is approvals — spoken aloud, the confirmation
+sentence is all the user gets, so let `approvalDescription` on the tool produce
+it and forbid the model from asking for permission in its own words.

package/skills/pikku-audit/SKILL.md

@@ -20,16 +20,18 @@ installGroups: [core]
 Use this skill as an execution checklist, not reference material.
 
 1. Discover before editing. Check how services are wired (`services.ts`) and whether an `audit` table migration exists before adding audit calls.
-2. NEVER hand-roll a custom `audit_log` / history table with direct `insertInto('audit_log')` calls. The framework owns audit. A bespoke table drifts from the runtime (missing actor/trace/wire context, hand-written CHECK constraints that reject valid events, no prod sink). Use the built-in path below.
+2. NEVER hand-roll a custom `audit_log` / history table with direct `insertInto('audit_log')` calls. The framework owns audit. A bespoke table drifts from the runtime (missing user/trace/wire context, hand-written CHECK constraints that reject valid events, no prod sink). Use the built-in path below.
 3. Make the smallest source change: mark the function `audit: true`, inject `auditLog`, call `auditLog.write(...)`. Do not invent a new service.
 4. Validate with `pikku all` (regenerates the service flags) then run the app / e2e.
 
 ## Mental model — two layers
 
 - **`audit` (singleton `AuditService`)** — the durable **sink**. Write-only: `audit(event)` + optional `write(batch)`. Defaults to `NoopAuditService` (discards). Swap in a real sink to persist (see Sinks).
-- **`auditLog` (wire service `AuditLog`)** — a per-invocation **buffer** built from the sink via `createInvocationAudit(audit, wire)`. `auditLog.write(input)` enriches each event with `functionId`, `wireType`, `traceId`, `occurredAt`, and `actor` (from the wire session) automatically, then flushes to the sink when the invocation ends.
+- **`auditLog` (wire service `AuditLog`)** — a per-invocation **buffer** built from the sink via `createInvocationAudit(audit, wire)`. `auditLog.write(input)` enriches each event with `functionId`, `wireType`, `traceId`, `occurredAt`, and `userIdentity` (from the wire session) automatically, then flushes to the sink when the invocation ends.
 
-An event only persists when the function opts in with **`audit: true`** — otherwise `auditLog` is a no-op that warns.
+An event only persists when the function opts in with **`audit: true`** — otherwise `auditLog` is a no-op that warns once per invocation, naming the function that dropped the write.
+
+`audit` also takes a config object, `{ durability: 'best-effort' | 'transactional' }`, and `audit: true` is shorthand for `'best-effort'`. Best-effort buffers events and flushes them when the invocation closes, swallowing sink failures with a warning — the function's result is never held hostage to the audit sink. `'transactional'` awaits the sink on every `write()` instead, so a sink failure fails the invocation. Reach for it only when losing the record is worse than failing the call.
 
 ## Wiring (services.ts)
 
@@ -46,15 +48,22 @@ export const createSingletonServices = pikkuServices(async (config, existing) =>
 // a write from a function that forgot `audit: true` warns instead of vanishing.
 export const createWireServices = pikkuWireServices(async (services, wire) => {
   if (!services.audit) return {}
-  return { auditLog: createInvocationAudit(services.audit, wire) }
+  return {
+    auditLog: createInvocationAudit(services.audit, wire, services.logger),
+  }
 })
 ```
 
+The optional third argument is the fallback logger for the dropped-write warning
+and for best-effort flush failures. Without it those messages only surface when
+the wire happens to carry a logger, which is how a missing `audit: true` goes
+unnoticed.
+
 `audit` and `auditLog` are already declared on `CoreSingletonServices` / `CoreServices`, so no type change is needed to inject them.
 
 ## Recording events — explicit domain events (default)
 
-Mark the function `audit: true` and call `auditLog?.write(...)`. Domain history goes in `metadata`; the actor is derived from the session, so do NOT pass it manually.
+Mark the function `audit: true` and call `auditLog?.write(...)`. Domain history goes in `metadata`; the user identity is derived from the session, so do NOT pass it manually.
 
 ```typescript
 export const cancelInvoice = pikkuFunc({
@@ -82,12 +91,14 @@ export const cancelInvoice = pikkuFunc({
 })
 ```
 
-For a **system/cron** function there is no session, so `actor` is simply absent (nulls out `actor_user_id`). Use `pikkuVoidFunc({ audit: true, func: async ({ auditLog }) => { ... } })` — the void/config form accepts `audit`.
+For a **system/cron** function there is no session, so `userIdentity` is simply absent (nulls out `user_id`). Use `pikkuVoidFunc({ audit: true, func: async ({ auditLog }) => { ... } })` — the void/config form accepts `audit`.
 
 Helper functions (in `lib/`) that record audit take `auditLog?: AuditLog` in their services arg and are passed it from a `audit: true` caller — never import a service.
 
 Note: events buffer and flush on invocation close. For a write inside a DB transaction, call `auditLog.write()` **after** the transaction commits — the sink is not part of your `trx`, so only record committed state.
 
+`write` is `Safe<>`-guarded the way the logger is: `input` and `metadata` are `unknown`, so a `SecretValue` nested anywhere in the event collapses the call to `never` and it stops compiling. An unrevealed secret would serialize as `[secret]` regardless — the guard just makes putting one in an audit row a decision rather than an accident. Reveal it explicitly if you genuinely mean to record it.
+
 ## Recording events — automatic query capture (optional)
 
 To audit every DB mutation without explicit calls, wrap kysely so each query emits an event. Note this captures table/column changes only — it cannot see semantic events that do no DB write (e.g. "email sent"), so combine with explicit writes when you need those.
@@ -101,6 +112,11 @@ export const createWireServices = pikkuWireServices(async (services, wire) => {
 })
 ```
 
+It is a Kysely plugin, so it wraps the instance rather than replacing it. Only
+mutations are captured by default; `auditReads: true` adds selects, which is
+usually far more volume than it is worth. `eventType`, `transactionId` and
+`queryIdPrefix` are also accepted for labelling the emitted events.
+
 ## Sinks
 
 - **`NoopAuditService`** (`@pikku/core/services`) — default; discards events. Fine when audit isn't needed.
@@ -121,8 +137,9 @@ CREATE TABLE IF NOT EXISTS audit (
   trace_id       TEXT,
   transaction_id TEXT,
   query_id       TEXT,
-  actor_user_id  TEXT,
-  actor_org_id   TEXT,
+  user_id        TEXT,
+  org_id         TEXT,
+  pikku_user_id  TEXT,
   tables         TEXT,  -- JSON: table names touched (auto capture)
   changed_cols   TEXT,  -- JSON: changed column names (auto capture)
   event          TEXT,  -- custom event label
@@ -131,12 +148,14 @@ CREATE TABLE IF NOT EXISTS audit (
 );
 ```
 
+The defaults above are SQLite; on Postgres swap them for `gen_random_uuid()::text` and `now()::text`. Every column stays TEXT on every engine so a locally-run project and a deployed stage write identical rows, and the sink inserts with `ON CONFLICT DO NOTHING` so a retried flush is idempotent.
+
 `auditLog.write({ metadata })` lands in the `data` column. Read history back by filtering it (SQLite `json_extract`, Postgres `->>`):
 
 ```typescript
 const rows = await kysely
   .selectFrom('audit')
-  .leftJoin('user', 'user.id', 'audit.actorUserId')
+  .leftJoin('user', 'user.id', 'audit.userId')
   .where(sql<boolean>`json_extract(audit.data, '$.entity') = 'invoice'`)
   .where(sql<boolean>`json_extract(audit.data, '$.entityId') = ${invoiceId}`)
   .orderBy('audit.occurredAt', 'desc')
@@ -156,20 +175,23 @@ type AuditEvent = {
   type: string                          // e.g. 'invoice.update'
   source: 'auto' | 'explicit'
   occurredAt: string                    // auto-filled by auditLog
-  outcome?: string
+  eventId?: string
+  outcome?: 'success' | 'failed' | 'denied'
   functionId?; wireType?; wireId?; traceId?; transactionId?; queryId?  // auto
-  actor?: { userId?; orgId? }           // auto from wire session
+  userIdentity?: { userId?; orgId?; pikkuUserId? } // auto from wire session
   input?: unknown
   metadata?: Record<string, unknown>    // your domain payload
 }
 ```
 
-`auditLog.write()` takes `Omit<AuditEvent, 'occurredAt'>` — you only supply `type`, `source`, and `metadata` (and `actor` if overriding the session default).
+`auditLog.write()` takes `Omit<AuditEvent, 'occurredAt'>` — you only supply `type`, `source`, and `metadata` (and `userIdentity` if overriding the session default).
+
+`userIdentity` is filled from the wire's session plus its `pikkuUserId`, and is left off entirely when all three are absent — which is what makes a cron or system invocation land with a null actor rather than an empty object.
 
 ## Do / Don't
 
 - DO mark recording functions `audit: true`, inject `auditLog`, and call `auditLog.write({ type, source: 'explicit', metadata })`.
-- DO let the actor come from the session — don't thread `userId` into metadata for the actor.
+- DO let the user identity come from the session — don't thread `userId` into metadata for it.
 - DON'T create a custom `audit_log`/history table or `insertInto('audit_log')` by hand.
 - DON'T annotate the function's I/O from audit; audit is a side channel, not part of `input`/`output`.
 - DON'T write audit inside a DB transaction expecting rollback — record after commit.

package/skills/pikku-aws/SKILL.md

@@ -36,52 +36,102 @@ yarn add @pikku/aws-services
 import { S3Content } from '@pikku/aws-services'
 
 const content = new S3Content(
-  config: S3ContentConfig,
+  config: { bucketName: string; region: string; endpoint?: string },
   logger: Logger,
   signConfig: { keyPairId: string; privateKey: string }
 )
 ```
 
-**Methods:**
-
-- `signURL(url: string, dateLessThan: Date, dateGreaterThan?: Date): Promise<string>` — Sign a CloudFront URL
-- `signContentKey(key: string, dateLessThan: Date, dateGreaterThan?: Date): Promise<string>` — Sign a content key
-- `getUploadURL(Key: string, ContentType: string): Promise<{ uploadUrl, assetKey }>` — Get presigned upload URL
-- `readFile(Key: string): Promise<ReadableStream>` — Read file as stream
-- `readFileAsBuffer(Key: string): Promise<Buffer>` — Read file as buffer
-- `writeFile(Key: string, stream: ReadableStream): Promise<boolean>` — Write file from stream
-- `copyFile(Key: string, fromAbsolutePath: string): Promise<boolean>` — Copy local file to S3
-- `deleteFile(Key: string): Promise<boolean>` — Delete file
+`endpoint` is what points the client at LocalStack or an S3-compatible store.
+
+**Methods** — every one 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>`
+
+### One real bucket, logical buckets as prefixes
+
+The `bucket` on every call is a **logical** bucket stored as a path prefix
+(`${bucket}/${key}`) inside the single S3 bucket named by `bucketName`. Don't
+provision an S3 bucket per logical bucket — the config takes only one.
+
+### Behaviours worth knowing before you rely on them
+
+- **`signURL` fails open.** A signing error is logged and the *unsigned* URL is
+  returned rather than thrown. If your CloudFront distribution is private the
+  client then gets a 403; if it isn't, you have just handed out an unrestricted
+  link. Check that `signConfig` is a valid CloudFront key pair at boot.
+- **`signContentKey` builds `https://<bucketName>/<bucket>/<contentKey>`** — it
+  uses `bucketName` as the *host*. For signed content the value must therefore be
+  your CloudFront domain, not a plain bucket name, which also means the same
+  config field is doing two jobs.
+- **Presigned upload URLs expire after a fixed 3600s.** It is not configurable
+  through the service.
+- **Write paths swallow failures.** `writeFile`, `copyFile` and `deleteFile` log
+  and return `false` rather than throwing; the read paths throw. Check the
+  boolean.
 
 ### `SQSQueueService` (Queue)
 
 ```typescript
 import { SQSQueueService } from '@pikku/aws-services'
 
-const queue = new SQSQueueService(config: SQSQueueServiceConfig)
+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
+})
 ```
 
 Implements `QueueService`. Note: `supportsResults = false` — job status tracking is not supported.
 
 **Methods:**
 
-- `add<T>(queueName: string, data: T, options?: JobOptions): Promise<string>` — Enqueue a message
+- `add<T>(queueName: string, data: T, options?: JobOptions): Promise<string>` — Enqueue a message; returns SQS's `MessageId`
+- `getJob()` — always **throws**. SQS is fire-and-forget; reach for BullMQ or PgBoss when you need the result back.
+
+The queue URL is `queueUrlPrefix + queueName`, so the queue name in `wireQueueWorker` has to match the SQS queue exactly.
+
+Constraints inherited from SQS, enforced in `add`:
+
+- `options.delay` is in **milliseconds** and is 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.
 
 ### `AWSSecrets` (Secrets Manager)
 
 ```typescript
 import { AWSSecrets } from '@pikku/aws-services'
 
-const secrets = new AWSSecrets(config: AWSConfig)
+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.
+
 **Methods:**
 
-- `getSecret<T = string>(SecretId: string): Promise<T>` — Get a secret value; a JSON secret is parsed automatically, so pass a shape as `T` (a non-JSON value comes back as the raw string)
+- `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>>` — Batch fetch; missing keys are omitted rather than thrown
 - `hasSecret(SecretId: string): Promise<boolean>` — Check if secret exists
 - `setSecret` / `deleteSecret` — **not implemented** for `AWSSecrets`; it throws. Manage AWS secrets out of band.
 
+Every `getSecret` failure — missing secret, denied permission, a secret holding
+only binary — surfaces as the same `FATAL: Error finding secret: <id>`, with the
+real reason on the error's `cause`. Read `cause` before concluding the secret
+doesn't exist. `hasSecret` performs a full fetch and returns `false` for any
+error, so it can't distinguish "absent" from "not allowed" either.
+
 ## Usage Patterns
 
 ### S3 Content Service
@@ -90,7 +140,7 @@ const secrets = new AWSSecrets(config: AWSConfig)
 const createSingletonServices = pikkuServices(async (config) => {
   const logger = new PinoLogger()
   const content = new S3Content(
-    { bucket: config.s3Bucket, region: config.awsRegion },
+    { bucketName: config.s3Bucket, region: config.awsRegion },
     logger,
     { keyPairId: config.cfKeyPairId, privateKey: config.cfPrivateKey }
   )

package/skills/pikku-backblaze/SKILL.md

@@ -39,16 +39,41 @@ const content = new B2Content(
 )
 ```
 
-**Methods:**
-
-- `signContentKey(key: string, dateLessThan: Date): Promise<string>` — Sign a content key
-- `signURL(url: string, dateLessThan: Date): Promise<string>` — Sign a URL
-- `getUploadURL(fileKey: string, contentType: string): Promise<{ uploadUrl, assetKey, uploadMethod?, uploadHeaders? }>` — Get upload URL
-- `writeFile(assetKey: string, stream: ReadableStream): Promise<boolean>` — Write file
-- `copyFile(assetKey: string, fromAbsolutePath: string): Promise<boolean>` — Copy local file to B2
-- `readFile(assetKey: string): Promise<ReadableStream>` — Read file as stream
-- `readFileAsBuffer(assetKey: string): Promise<Buffer>` — Read file as buffer
-- `deleteFile(fileName: string): Promise<boolean>` — Delete file
+`B2ContentConfig` has exactly three fields — `applicationKeyId`, `applicationKey`
+and `bucketId`. There is no `cdnUrl`: downloads are served from the `downloadUrl`
+B2 returns at authorization.
+
+**Methods** — every one 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 by this backend
+- `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>`
+
+### One real bucket, logical buckets as prefixes
+
+The `bucket` on every call is a **logical** bucket stored as a path prefix
+(`${bucket}/${key}`) inside the single B2 bucket named by `bucketId`. Don't
+provision a B2 bucket per logical bucket — the config takes only one.
+
+### Behaviours worth knowing before you rely on them
+
+- **Writes are buffered in memory.** `writeFile` drains the whole stream into a
+  `Buffer` before uploading, because 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.
+- **`getUploadURL` sets `X-Bz-Content-Sha1: do_not_verify`**, since the server
+  can't hash a body it never sees. The client-side upload is unverified.
+- **Write paths swallow failures.** `writeFile`, `copyFile` and `deleteFile` log
+  and return `false` rather than throwing; the read paths and the signing paths
+  throw. Check the boolean — an ignored return is a silently lost file.
+- Authorization and the bucket-name lookup are cached on the instance for its
+  lifetime, so a rotated application key needs a new `B2Content`.
 
 ## Usage Patterns
 
@@ -62,10 +87,18 @@ const createSingletonServices = pikkuServices(async (config) => {
       applicationKeyId: config.b2KeyId,
       applicationKey: config.b2AppKey,
       bucketId: config.b2BucketId,
-      cdnUrl: config.b2CdnUrl,
     },
     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),
+})
+```