@pikku/cli 0.12.91 → 0.12.92

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

@@ -1,231 +0,0 @@
----
-name: pikku-ai-agent
-description: >-
-  Use when building AI agents, chatbots, or LLM-powered assistants with Pikku. Covers
-  pikkuAIAgent, tool registration, memory, streaming, and agent invocation. TRIGGER when: code
-  uses pikkuAIAgent/runAIAgent/streamAIAgent, user asks about AI agents, chatbots, LLM assistants,
-  tool-calling agents, or agent memory/streaming. DO NOT TRIGGER when: user asks about MCP tool
-  exposure (use pikku-mcp) or general function definitions (use pikku-concepts).
-installGroups: [core]
----
-
-# Pikku AI Agent Wiring
-
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise 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.
-
-Build AI agents that use Pikku functions as tools. Agents support conversation memory, streaming, and multi-step tool execution.
-
-## Before You Start
-
-```bash
-pikku info functions --verbose   # See existing functions that can be used as agent tools
-pikku info tags --verbose        # Understand project organization
-```
-
-See `pikku-concepts` for the core mental model.
-
-## API Reference
-
-### `pikkuAIAgent(config)`
-
-```typescript
-import { pikkuAIAgent } from '#pikku'
-
-pikkuAIAgent({
-  name: string,                  // Unique agent identifier
-  description: string,           // What the agent does
-  instructions: string | string[],  // System prompt / behavior instructions
-  model: string,                 // LLM model (e.g. 'openai/gpt-5-mini')
-  tools?: PikkuFunc[],           // Pikku functions the agent can call
-  agents?: AIAgentConfig[],      // Sub-agents this agent can delegate to
-  memory?: {
-    storage?: string,            // Service name for persistence (e.g. 'aiStorage')
-    vector?: string,             // Vector store service name
-    embedder?: string,           // Embedding service name
-    lastMessages?: number,       // How many messages to retain in context
-    workingMemory?: ZodSchema,   // Schema for structured working memory
-  },
-  maxSteps?: number,             // Max tool-call rounds per invocation
-  temperature?: number,          // LLM temperature (0-1)
-  toolChoice?: 'auto' | 'required' | 'none',
-  input?: ZodSchema,             // Input validation schema
-  output?: ZodSchema,            // Output validation schema
-  tags?: string[],               // For grouping and middleware targeting
-  aiMiddleware?: PikkuAIMiddlewareHooks[],  // AI-specific middleware
-  middleware?: PikkuMiddleware[],
-  permissions?: PermissionGroup,
-})
-```
-
-### `runAIAgent(name, input, options)` — Non-streaming
-
-```typescript
-const result = await runAIAgent(
-  agentName,
-  {
-    message: string, // User message
-    threadId: string, // Conversation thread ID
-    resourceId: string, // User/resource identifier
-  },
-  { singletonServices }
-)
-
-result.text // Agent's text response
-result.steps // Array of tool calls made
-result.usage // Token usage { inputTokens, outputTokens }
-```
-
-### `streamAIAgent(name, input, channel, options)` — Streaming
-
-```typescript
-await streamAIAgent(
-  agentName,
-  {
-    message: string,
-    threadId: string,
-    resourceId: string,
-  },
-  channel,
-  { singletonServices }
-)
-
-// Channel receives events:
-// { type: 'step-start', stepNumber: 1 }
-// { type: 'text-delta', text: '...' }
-// { type: 'reasoning-delta', text: '...' }
-// { type: 'tool-call', toolCallId, toolName, args }
-// { type: 'tool-result', toolCallId, toolName, result }
-// { type: 'agent-call', agentName, session, input }
-// { type: 'agent-result', agentName, session, result }
-// { type: 'approval-request', toolCallId, toolName, args, reason? }
-// { type: 'usage', tokens: { input, output }, model }
-// { type: 'error', message }
-// { type: 'done' }
-```
-
-## Usage Patterns
-
-### Define an Agent
-
-```typescript
-const todoAssistant = pikkuAIAgent({
-  name: 'todo-assistant',
-  description: 'A helpful assistant that manages todos',
-  instructions:
-    'You help users manage their todo lists. Be concise and helpful.',
-  model: 'openai/gpt-5-mini',
-  tools: [listTodos, createTodo, completeTodo],
-  memory: {
-    storage: 'aiStorage',
-    lastMessages: 20,
-  },
-  maxSteps: 5,
-  temperature: 0.7,
-})
-```
-
-### Invoke Non-Streaming
-
-```typescript
-const result = await runAIAgent(
-  'todo-assistant',
-  {
-    message: 'Create a task for tomorrow: buy groceries',
-    threadId: 'thread-123',
-    resourceId: 'user-456',
-  },
-  { singletonServices }
-)
-
-console.log(result.text) // "I've created a task 'buy groceries' for tomorrow."
-console.log(result.steps) // [{ tool: 'createTodo', args: {...}, result: {...} }]
-console.log(result.usage) // { inputTokens: 150, outputTokens: 42 }
-```
-
-### Stream Responses
-
-```typescript
-await streamAIAgent(
-  'todo-assistant',
-  {
-    message: 'Create a task for tomorrow',
-    threadId: 'thread-123',
-    resourceId: 'user-456',
-  },
-  channel,
-  { singletonServices }
-)
-```
-
-## Complete Example
-
-```typescript
-// functions/todos.functions.ts
-export const listTodos = pikkuSessionlessFunc({
-  description: 'List all todo items',
-  func: async ({ db }, { status }) => {
-    return { todos: await db.listTodos(status) }
-  },
-})
-
-export const createTodo = pikkuFunc({
-  description: 'Create a new todo item',
-  func: async ({ db }, { text, priority, dueDate }) => {
-    return await db.createTodo({ text, priority, dueDate })
-  },
-})
-
-export const completeTodo = pikkuFunc({
-  description: 'Mark a todo as complete',
-  func: async ({ db }, { todoId }) => {
-    return await db.completeTodo(todoId)
-  },
-})
-
-// agents/todo-assistant.ts
-const todoAssistant = pikkuAIAgent({
-  name: 'todo-assistant',
-  description: 'A helpful assistant that manages todos',
-  instructions: `You help users manage their todo lists.
-    - Be concise and helpful
-    - When creating todos, infer priority if not specified
-    - When listing todos, summarize the results`,
-  model: 'openai/gpt-5-mini',
-  tools: [listTodos, createTodo, completeTodo],
-  memory: {
-    storage: 'aiStorage',
-    lastMessages: 20,
-  },
-  maxSteps: 5,
-  temperature: 0.7,
-})
-
-// Wire to HTTP for chat endpoint
-wireHTTP({
-  method: 'post',
-  route: '/chat',
-  func: pikkuFunc({
-    title: 'Chat',
-    func: async (services, { message, threadId }, wire) => {
-      const { session } = wire
-      return await runAIAgent(
-        'todo-assistant',
-        {
-          message,
-          threadId,
-          resourceId: session.userId,
-        },
-        { singletonServices: services }
-      )
-    },
-  }),
-})
-```

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

@@ -1,82 +0,0 @@
----
-name: pikku-ai-vercel
-description: >-
-  Use when setting up AI agent execution with the Vercel AI SDK in a Pikku app. Covers
-  VercelAIAgentRunner for streaming and non-streaming AI agent steps. TRIGGER when: code uses
-  VercelAIAgentRunner, user asks about Vercel AI SDK integration, AI agent runners, or
-  @pikku/ai-vercel. DO NOT TRIGGER when: user asks about AI agent wiring (use pikku-ai-agent) or
-  voice I/O (use pikku-ai-voice).
-installGroups: [core]
----
-
-# Pikku AI Vercel (Agent Runner)
-
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise 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.
-
-`@pikku/ai-vercel` provides an AI agent runner backed by the [Vercel AI SDK](https://sdk.vercel.ai/). Implements `AIAgentRunnerService` from `@pikku/core`.
-
-## Installation
-
-```bash
-yarn add @pikku/ai-vercel ai @ai-sdk/openai  # or any AI SDK provider
-```
-
-## API Reference
-
-### `VercelAIAgentRunner`
-
-```typescript
-import { VercelAIAgentRunner } from '@pikku/ai-vercel'
-
-const runner = new VercelAIAgentRunner(
-  providers: Record<string, any>  // Map of provider name → Vercel AI SDK provider instance
-)
-```
-
-**Methods:**
-
-- `stream(params: AIAgentRunnerParams, channel: AIStreamChannel): Promise<AIAgentStepResult>` — Stream AI responses with tool calls
-- `run(params: AIAgentRunnerParams): Promise<AIAgentStepResult>` — Execute a single AI step (non-streaming)
-
-The `providers` map lets you register multiple AI providers. Model strings use `provider:model` format (e.g., `"openai:gpt-4o"`).
-
-## Usage Patterns
-
-### Basic Setup
-
-```typescript
-import { VercelAIAgentRunner } from '@pikku/ai-vercel'
-import { openai } from '@ai-sdk/openai'
-import { anthropic } from '@ai-sdk/anthropic'
-
-const createSingletonServices = pikkuServices(async (config) => {
-  const aiRunner = new VercelAIAgentRunner({
-    openai: openai,
-    anthropic: anthropic,
-  })
-  return { config, aiRunner }
-})
-```
-
-### With AI Agent Wiring
-
-```typescript
-import { wireAIAgent } from '@pikku/core/ai-agent'
-
-wireAIAgent({
-  name: 'assistant',
-  model: 'openai:gpt-4o',
-  systemPrompt: 'You are a helpful assistant.',
-  func: myAgentFunc,
-})
-```
-
-The `VercelAIAgentRunner` is used internally by Pikku's AI agent wiring to execute model calls. See `pikku-ai-agent` for wiring details.

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

@@ -1,88 +0,0 @@
----
-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 AI Voice (Speech I/O)
-
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise 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.
-
-`@pikku/ai-voice` provides speech-to-text and text-to-speech middleware hooks for Pikku AI agents.
-
-## Installation
-
-```bash
-yarn add @pikku/ai-voice
-```
-
-## 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>
-}
-```
-
-### Middleware Hooks
-
-```typescript
-import { voiceInput, voiceOutput } from '@pikku/ai-voice'
-
-voiceInput(config?: { language?: string }): PikkuAIMiddlewareHooks
-voiceOutput(config?: { format?: string; voice?: string }): PikkuAIMiddlewareHooks
-```
-
-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
-
-```typescript
-import { voiceInput, voiceOutput } from '@pikku/ai-voice'
-import { wireAIAgent } from '@pikku/core/ai-agent'
-
-wireAIAgent({
-  name: 'voice-assistant',
-  model: 'openai:gpt-4o',
-  systemPrompt: 'You are a voice assistant.',
-  middlewareHooks: [
-    voiceInput({ language: 'en' }),
-    voiceOutput({ voice: 'alloy', format: 'mp3' }),
-  ],
-  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.

package/skills/pikku-audit/SKILL.md

@@ -1,175 +0,0 @@
----
-name: pikku-audit
-description: >-
-  Use when adding audit / activity-history / change-tracking to a Pikku app, or when a function
-  needs to record who changed what. Covers the built-in AuditService sink, the per-invocation
-  auditLog buffer (createInvocationAudit / pikkuWireServices), the `audit: true` function flag,
-  explicit `auditLog.write()` domain events, automatic query-level capture via
-  createAuditedKysely, and the durable KyselyAuditService sink. TRIGGER when: user asks for an
-  audit log, change history, activity feed, "who did this", or a custom audit/history table; code
-  uses auditLog, createInvocationAudit, createAuditedKysely, or AuditService. DO NOT TRIGGER when:
-  user wants app logging/telemetry (use the logger) or DB migrations in general (use
-  pikku-kysely).
-installGroups: [core]
----
-
-# Pikku Audit
-
-## Agent Operating Procedure
-
-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.
-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.
-
-An event only persists when the function opts in with **`audit: true`** — otherwise `auditLog` is a no-op that warns.
-
-## Wiring (services.ts)
-
-```typescript
-import { NoopAuditService, createInvocationAudit } from '@pikku/core/services'
-
-export const createSingletonServices = pikkuServices(async (config, existing) => {
-  // Prod platforms may inject a queue-backed sink as existing.audit.
-  const audit = existing?.audit ?? new NoopAuditService()
-  return { ...existing, config, /* ... */ audit }
-})
-
-// auditLog is created per invocation from the sink. Returned unconditionally so
-// 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) }
-})
-```
-
-`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.
-
-```typescript
-export const cancelInvoice = pikkuFunc({
-  audit: true,                       // REQUIRED — else write() is a no-op
-  input: CancelInvoiceInput,
-  output: CancelInvoiceOutput,
-  func: async ({ kysely, auditLog }, { invoiceId }, { session }) => {
-    const inv = await kysely.selectFrom('invoice')/* ... */.executeTakeFirstOrThrow()
-    await kysely.updateTable('invoice').set({ status: 'cancelled' })/* ... */.execute()
-
-    await auditLog?.write({
-      type: 'invoice.update',
-      source: 'explicit',
-      metadata: {
-        entity: 'invoice',
-        entityId: invoiceId,
-        action: 'update',
-        field: 'status',
-        before: inv.status,
-        after: 'cancelled',
-      },
-    })
-    return { ok: true }
-  },
-})
-```
-
-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`.
-
-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.
-
-## 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.
-
-```typescript
-import { createAuditedKysely } from '@pikku/kysely'
-export const createWireServices = pikkuWireServices(async (services, wire) => {
-  if (!services.audit) return {}
-  const auditLog = createInvocationAudit(services.audit, wire)
-  return { auditLog, kysely: createAuditedKysely(services.kysely, { audit: auditLog }) }
-})
-```
-
-## Sinks
-
-- **`NoopAuditService`** (`@pikku/core/services`) — default; discards events. Fine when audit isn't needed.
-- **`KyselyAuditService`** (`@pikku/kysely`) — durable: persists events to an `audit` table via kysely. Use as the local/dev sink so events are queryable without a platform queue: `new KyselyAuditService(kysely)`.
-- **Platform-injected sink** — a deploy platform may inject its own queue-backed `audit` (hence the `existing?.audit ??` fallback above). Its rows land in the same `audit` table shape.
-
-### The `audit` table (add this migration if you persist audit)
-
-```sql
-CREATE TABLE IF NOT EXISTS audit (
-  audit_id       TEXT NOT NULL PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
-  occurred_at    TEXT NOT NULL DEFAULT (datetime('now')),
-  type           TEXT NOT NULL,
-  source         TEXT NOT NULL DEFAULT 'auto',
-  outcome        TEXT,
-  function_id    TEXT,
-  wire_type      TEXT,
-  trace_id       TEXT,
-  transaction_id TEXT,
-  query_id       TEXT,
-  actor_user_id  TEXT,
-  actor_org_id   TEXT,
-  tables         TEXT,  -- JSON: table names touched (auto capture)
-  changed_cols   TEXT,  -- JSON: changed column names (auto capture)
-  event          TEXT,  -- custom event label
-  old            TEXT,  -- JSON: previous values
-  data           TEXT   -- JSON: metadata / new values / event payload
-);
-```
-
-`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')
-  .where(sql<boolean>`json_extract(audit.data, '$.entity') = 'invoice'`)
-  .where(sql<boolean>`json_extract(audit.data, '$.entityId') = ${invoiceId}`)
-  .orderBy('audit.occurredAt', 'desc')
-  .select([
-    'audit.auditId',
-    sql<string>`json_extract(audit.data, '$.action')`.as('action'),
-    'audit.occurredAt as at',
-    'user.name as userName',
-  ])
-  .execute()
-```
-
-## AuditEvent shape
-
-```typescript
-type AuditEvent = {
-  type: string                          // e.g. 'invoice.update'
-  source: 'auto' | 'explicit'
-  occurredAt: string                    // auto-filled by auditLog
-  outcome?: string
-  functionId?; wireType?; wireId?; traceId?; transactionId?; queryId?  // auto
-  actor?: { userId?; orgId? }           // 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).
-
-## 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.
-- 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

@@ -1,111 +0,0 @@
----
-name: pikku-aws
-description: >-
-  Use when setting up AWS services (S3, SQS, Secrets Manager) in a Pikku app. Covers S3Content for
-  file storage, SQSQueueService for queues, and AWSSecrets for secret management. TRIGGER when:
-  code uses S3Content, SQSQueueService, AWSSecrets, or user asks about AWS integration, S3
-  uploads, SQS queues, or AWS Secrets Manager with Pikku. DO NOT TRIGGER when: user asks about AWS
-  Lambda runtime (use pikku-deploy-lambda).
----
-
-# Pikku AWS Services
-
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise 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.
-
-`@pikku/aws-services` provides AWS-backed implementations of Pikku's content, queue, and secret service interfaces.
-
-## Installation
-
-```bash
-yarn add @pikku/aws-services
-```
-
-## API Reference
-
-### `S3Content` (File Storage)
-
-```typescript
-import { S3Content } from '@pikku/aws-services'
-
-const content = new S3Content(
-  config: S3ContentConfig,
-  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
-
-### `SQSQueueService` (Queue)
-
-```typescript
-import { SQSQueueService } from '@pikku/aws-services'
-
-const queue = new SQSQueueService(config: SQSQueueServiceConfig)
-```
-
-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
-
-### `AWSSecrets` (Secrets Manager)
-
-```typescript
-import { AWSSecrets } from '@pikku/aws-services'
-
-const secrets = new AWSSecrets(config: AWSConfig)
-```
-
-**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)
-- `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.
-
-## Usage Patterns
-
-### S3 Content Service
-
-```typescript
-const createSingletonServices = pikkuServices(async (config) => {
-  const logger = new PinoLogger()
-  const content = new S3Content(
-    { bucket: config.s3Bucket, region: config.awsRegion },
-    logger,
-    { keyPairId: config.cfKeyPairId, privateKey: config.cfPrivateKey }
-  )
-  return { config, logger, content }
-})
-```
-
-### SQS Queue
-
-```typescript
-const createSingletonServices = pikkuServices(async (config) => {
-  const queue = new SQSQueueService({
-    region: config.awsRegion,
-    queueUrlPrefix: config.sqsUrlPrefix,
-  })
-  return { config, queue }
-})
-```