@pikku/skills 0.12.4 → 0.12.6

package/skills/pikku-cli/SKILL.md

@@ -36,19 +36,23 @@ See `pikku-concepts` for the core mental model.
 
 ### `wireCLI(config)`
 
+All three factories come from `#pikku` (the generated types re-export
+`cli/pikku-cli-types.gen.js`). Importing them from `@pikku/core/cli` compiles but
+loses your project's service and middleware types.
+
 ```typescript
-import { wireCLI } from '@pikku/core/cli'
+import { wireCLI } from '#pikku'
 
 wireCLI({
   program: string,              // Program name (e.g. 'todos')
-  options?: {                   // Global options
-    [key: string]: {
-      description: string,
-      short?: string,           // Single char alias (e.g. 'v')
-      default?: any,
-    }
-  },
+  description?: string,
+  summary?: string,
+  options?: CLIOptions,         // Global options — see below
   render?: PikkuCLIRender,      // Default renderer for all commands
+  middleware?: PikkuMiddleware[],
+  tags?: string[],              // Targets tag middleware
+  errors?: string[],
+  auth?: boolean,               // Only affects the websocket backend, not local runs
   commands: {
     [name: string]: PikkuCLICommand | {
       description: string,
@@ -65,24 +69,49 @@ import { pikkuCLICommand } from '#pikku'
 
 pikkuCLICommand({
   parameters?: string,          // Positional args (e.g. '<text>', '<username> <email>')
-  func: PikkuFunc,              // Business logic function
+  func?: PikkuFunc,             // Business logic function — omit on a pure command group
+  title?: string,
   description?: string,
   render?: PikkuCLIRender,      // Custom output renderer
-  options?: {
-    [key: string]: {
-      description: string,
-      short?: string,
-      default?: any,
-      choices?: string[],       // Restrict to values
-    }
-  },
+  options?: CLIOptions,
+  subcommands?: { [name: string]: PikkuCLICommand },  // nests to any depth
+  middleware?: PikkuMiddleware[],
+  permissions?: PermissionGroup,
+  auth?: boolean,
+  isDefault?: boolean,          // Runs when the group is invoked with no subcommand
 })
 ```
 
+`parameters` is checked against the func's input at compile time — a name that is
+not a key of the input makes the type `never`, so a typo'd positional fails to
+build rather than arriving as `undefined`.
+
+### Options
+
+```typescript
+{
+  description: string,
+  short?: string,        // Single char alias (e.g. 'v')
+  default?: any,
+  choices?: any[],       // Restrict to these values
+  array?: boolean,       // Collect every value up to the next flag
+  required?: boolean,
+}
+```
+
+How the parser reads them, which is worth knowing before you name one:
+
+- **Flag names are camel-cased**, so `--api-url` and `--apiUrl` both fill `apiUrl`.
+- **`--no-x` negation only works when `x` has a boolean `default`.** Without one,
+  `--no-x` parses as an option literally named `noX` — which is why boolean flags
+  should always declare their default.
+- Short flags cluster (`-abc`), and only the last in a cluster may take a value.
+- An unknown `--flag` warns rather than throwing.
+
 ### `pikkuCLIRender(fn)`
 
 ```typescript
-import { pikkuCLIRender } from '@pikku/core/cli'
+import { pikkuCLIRender } from '#pikku'
 
 const renderer = pikkuCLIRender<OutputType>((services, data) => {
   // Format and print output to terminal
@@ -90,6 +119,15 @@ const renderer = pikkuCLIRender<OutputType>((services, data) => {
 })
 ```
 
+### Wire object (`wire.cli`)
+
+```typescript
+wire.cli.program   // program name
+wire.cli.command   // string[] — the resolved command path
+wire.cli.data      // all positionals and options, merged
+wire.cli.channel   // the channel when served remotely (see below)
+```
+
 ## Usage Patterns
 
 ### Basic Commands
@@ -193,6 +231,17 @@ wireCLI({
 
 The func's input is the positional `parameters` plus `options`, merged (e.g. `parameters: '<username> <email>'` + an `admin` option → func input `{ username, email, admin }`).
 
+A renderer's full signature is `(services, data, session?)`. It returns nothing —
+printing is its job.
+
+### Running the program over a websocket
+
+Codegen emits a `<program>-channel.gen.ts` beside your wiring: a `wireChannel`
+that serves the same commands remotely, so a local binary and a hosted session
+run identical code. `auth` on `wireCLI` guards **that channel only** — a locally
+executed CLI has no connection to authenticate, so it is not a way to require a
+session for local runs. Don't hand-write or edit the generated channel file.
+
 ## Complete Example
 
 For a full functions + renderers + nested-subcommand wiring walkthrough, see `references/complete-example.md`.

package/skills/pikku-cli/references/complete-example.md

@@ -32,6 +32,8 @@ export const deleteUser = pikkuFunc({
 })
 
 // wirings/cli.wiring.ts
+import { wireCLI, pikkuCLICommand, pikkuCLIRender } from '#pikku'
+
 const userRenderer = pikkuCLIRender<{ user: User }>((_services, { user }) => {
   console.log(`Created user: ${user.username} (${user.email}) [${user.role}]`)
 })

package/skills/pikku-concepts/SKILL.md

@@ -28,7 +28,8 @@ Pikku is a TypeScript framework that separates business logic from transport mec
 For deep-dive on each topic, see the dedicated skills:
 
 - **Wiring**: `pikku-http`, `pikku-websocket`, `pikku-rpc`, `pikku-mcp`, `pikku-queue`, `pikku-cron`, `pikku-trigger`, `pikku-cli`, `pikku-ai-agent`, `pikku-workflow`
-- **Infrastructure**: `pikku-services`, `pikku-security`, `pikku-config`
+- **Authorization**: `pikku-security` (authentication/sessions), `pikku-permissions` (permission checks, scopes), `pikku-middleware` (global/tag/route middleware)
+- **Infrastructure**: `pikku-services`, `pikku-config`
 - **Project introspection**: `pikku-info`
 
 ## Core Mental Model
@@ -58,7 +59,7 @@ The function never imports Express, never reads `req.body`, never touches `ws.se
 
 ## Concept Mapping: Generic Backend → Pikku
 
-Controllers/routes → `pikkuFunc`; middleware/auth/permissions → `pikku-security`; DI → `pikku-services`; transports (HTTP/WS/queue/cron) → their `wire*` + skill. For the full Generic Backend → Pikku mapping table (with side-by-side code examples), read `references/concept-mapping.md`.
+Controllers/routes → `pikkuFunc`; auth/sessions → `pikku-security`; authorization checks → `pikku-permissions`; request interception → `pikku-middleware`; DI → `pikku-services`; transports (HTTP/WS/queue/cron) → their `wire*` + skill. For the full Generic Backend → Pikku mapping table (with side-by-side code examples), read `references/concept-mapping.md`.
 
 ## Functions
 
@@ -95,22 +96,53 @@ Services can be destructured inline in the `func` signature (e.g. `async ({ logg
 
 ```typescript
 pikkuFunc({
+  // Identity and documentation
   title?: string,           // Human-readable name
   description?: string,     // What the function does
-  version?: number,         // Contract version (see pikku-config for versioning)
+  version?: number,         // Contract version (see pikku-versioning)
+  override?: string,        // Logical name override, so several exports share a versioned base
   tags?: string[],          // For grouping and middleware targeting
+
+  // Contract
+  input?: ZodSchema,        // Input validation schema
+  output?: ZodSchema,       // Output validation schema
+  errors?: Array<typeof PikkuError>,  // Errors this function may throw
+
+  // Reachability
   expose?: boolean,         // Allow external RPC calls (see pikku-rpc)
   remote?: boolean,         // Allow remote RPC calls
   mcp?: boolean,            // Expose as MCP tool (see pikku-mcp)
+  readonly?: boolean,       // Declares the function performs no writes
+  deploy?: 'serverless' | 'server' | 'auto',
+
+  // Authorization — see pikku-permissions
   auth?: boolean,           // Override default auth requirement
-  input?: ZodSchema,        // Input validation schema
-  output?: ZodSchema,       // Output validation schema
-  permissions?: PermissionGroup,  // See pikku-security
-  middleware?: PikkuMiddleware[], // See pikku-security
+  scopes?: ScopeId[],       // AND-ed, checked before permissions; session required
+  permissions?: PermissionGroup,  // OR-ed pool
+  permissionsInBody?: boolean,    // Last resort; needs allow.permissionsInBody in config
+  middleware?: PikkuMiddleware[], // See pikku-middleware
+
+  // Agent tooling — see pikku-ai-agent
+  approvalRequired?: boolean,
+  approvalDescription?: (services, data) => Promise<string>,
+
+  // Workflow step behavior — see pikku-workflow
+  workflowQueued?: boolean, // Dispatch via queue instead of inline
+  workflowRetries?: number,
+  workflowTimeout?: string, // e.g. '30s', '5m'
+
+  audit?: boolean | { durability?: 'best-effort' | 'transactional' },
+
   func: async (services, data, wire) => { ... },
 })
 ```
 
+`scopes` is the one option `pikkuSessionlessFunc` does not accept, and the
+omission is deliberate: scopes are AND-ed and fail closed, so an anonymous
+caller holds none and satisfies none — a sessionless function with scopes would
+reject every caller it exists to serve. Gate those with `permissions`, which
+receive the optional session and may pass anonymous.
+
 **Generics XOR `input`/`output` — never both.** A function's data and return
 types come from *one* source: either the `input`/`output` schemas (preferred —
 they double as runtime validation and OpenAPI) or type generics
@@ -145,7 +177,35 @@ Schemas serve triple duty: runtime validation, TypeScript types, and OpenAPI doc
 
 ## Server Bootstrap
 
-Every Pikku app follows the same bootstrap pattern regardless of runtime:
+There are two ways to start a Pikku app. Pick based on whether you need to own the HTTP server.
+
+**1. Let Pikku own the server (preferred when you don't need a specific runtime)**
+
+`pikku dev` and `pikku serve` create the config and singleton services, start the server, and shut it down cleanly. You write no bootstrap code at all — startup and shutdown work goes in lifecycle hooks:
+
+```typescript
+// src/lifecycle.ts
+import { pikkuServerLifecycle } from '@pikku/core'
+import type { SingletonServices } from '../types/application-types.js'
+
+export const lifecycle = pikkuServerLifecycle<SingletonServices>({
+  beforeStart: async ({ kysely }) => {
+    await runMigrations(kysely)
+  },
+  afterStart: async ({ logger }) => {
+    logger.info('accepting traffic')
+  },
+  beforeStop: async ({ queueService }) => {
+    await queueService.drain()
+  },
+})
+```
+
+Export exactly one `pikkuServerLifecycle` from anywhere in `srcDirectories` — the inspector finds it by the wrapper call. Every hook is optional and receives the already-created singleton services. See pikku-services for the ordering and the `afterStop` caveat.
+
+**2. Bootstrap it yourself (required for a specific runtime)**
+
+Express, Fastify, uWS, Lambda, Cloudflare and Next.js need their own entrypoint, because Pikku is embedded in a server you own:
 
 ```typescript
 import '../../functions/.pikku/pikku-bootstrap.gen.js' // Generated — registers all wirings
@@ -168,6 +228,10 @@ await server.init()
 await server.start()
 ```
 
+**Lifecycle hooks do not run on this path** — only `pikku dev` and `pikku serve` invoke them. Do your startup work directly in the entrypoint instead.
+
+`pikku workspace validate` warns when a project starts a server by hand *and* depends on no runtime adapter, since that combination means path 1 was available and unused. Silence it with `"lint": { "customServerBootstrap": "off" }` in `pikku.config.json`.
+
 ## Code Generation
 
 Run `npx pikku all` to generate:
@@ -175,7 +239,7 @@ Run `npx pikku all` to generate:
 - `pikku-types.gen.ts` — Typed function factories and wiring functions
 - `pikku-fetch.gen.ts` — Type-safe HTTP client
 - `pikku-websocket.gen.ts` — Type-safe WebSocket client
-- `pikku-bootstrap.gen.js` — Runtime initialization (auto-imports all wirings)
+- `pikku-bootstrap.gen.ts` — Runtime initialization (auto-imports all wirings)
 - `pikku-services.gen.ts` — Service factory types
 
 Config lives in `pikku.config.json`:
@@ -203,12 +267,13 @@ src/
 │   └── queue.wiring.ts
 ├── schemas.ts           # Zod/Valibot schemas
 ├── services.ts          # Service factories (see pikku-services)
+├── lifecycle.ts         # Server lifecycle hooks (pikku dev/serve only)
 ├── middleware.ts         # Middleware definitions (see pikku-security)
 ├── permissions.ts       # Permission definitions (see pikku-security)
 └── .pikku/              # Generated (gitignored)
     ├── pikku-types.gen.ts
     ├── pikku-fetch.gen.ts
-    └── pikku-bootstrap.gen.js
+    └── pikku-bootstrap.gen.ts
 ```
 
 ## Environment Variables

package/skills/pikku-config/SKILL.md

@@ -4,9 +4,10 @@ description: >-
   Use when managing secrets, environment variables, config, or OAuth2 credentials in a Pikku app.
   Covers defineSecret, defineVariable, defineCredential, and typed config access. TRIGGER when:
   code uses defineSecret/defineVariable/defineCredential, user asks about env vars, secrets,
-  config, OAuth2, or "how do I access environment variables". DO NOT TRIGGER when: user asks about
-  API versioning/breaking changes (use pikku-versioning), service factories (use pikku-services),
-  or auth middleware (use pikku-security).
+  config, OAuth2, SecretValue/.reveal(), SecretCoercionError, or "how do I access environment
+  variables". DO NOT TRIGGER when: user asks about API versioning/breaking changes (use
+  pikku-versioning), service factories (use pikku-services), middleware (use pikku-middleware), or
+  auth strategies and sessions (use pikku-security).
 installGroups: [core]
 ---
 
@@ -64,10 +65,17 @@ or any wire** — it is removed from their services type and throws at runtime i
 reached through a cast. Read it where you wire the app and hand the value to a
 service:
 
+`getSecret` returns a `SecretValue<T>`, not the bare value. It is nominal — not
+assignable to `string`, so every concretely-typed sink rejects it — it serializes
+to `[secret]` in logs and audits, and coercing it to a string (a template
+literal, a concatenation) throws `SecretCoercionError`, because that is always a
+leak. `.reveal()` is the one way out, which makes every disclosure deliberate and
+greppable. Call it at the point the value reaches the thing that needs it:
+
 ```typescript
 // services.ts — allowed
 const createSingletonServices = pikkuServices(async (config, { secrets }) => ({
-  stripe: new StripeService(await secrets.getSecret('STRIPE_CONFIG')),
+  stripe: new StripeService((await secrets.getSecret('STRIPE_CONFIG')).reveal()),
 }))
 
 // functions/*.ts — ask the service, never the secret store
@@ -113,7 +121,7 @@ defineSecret({
 })
 
 // In your services factory — fully typed
-const config = await secrets.getSecret('STRIPE_CONFIG')
+const config = (await secrets.getSecret('STRIPE_CONFIG')).reveal()
 // config.apiKey       → string (autocompleted)
 // config.webhookSecret → string (autocompleted)
 
@@ -178,17 +186,34 @@ defineCredential({
   },
 })
 
-// In your function — tokens refresh automatically
-const response = await slackOAuth.request(
-  'https://slack.com/api/chat.postMessage',
-  {
-    method: 'POST',
-    body: JSON.stringify({ channel, text }),
+### Reading a Credential
+
+A declared credential is resolved per invocation through `wire.getCredential(name)`,
+so the natural place to read it is a wire service factory: build the client there
+once and let functions ask the client, the same way they ask a service for a
+secret-derived value. Tokens refresh automatically, so what arrives is already
+valid.
+
+```typescript
+export const createWireServices = pikkuWireServices(async (_services, wire) => {
+  const cred = await wire.getCredential?.<{ accessToken: string }>('slack')
+  if (!cred?.accessToken) {
+    // Tells the caller which credential to connect, and where.
+    throw new MissingCredentialError('slack', 'oauth2', '/credentials/slack/connect')
   }
-)
-const data = await response.json()
+  return { slack: new SlackClient(cred.accessToken) }
+})
+
+// functions/*.ts — ask the client, never the credential store
+export const postMessage = pikkuFunc({
+  func: async ({ slack }, { channel, text }) => slack.postMessage(channel, text),
+})
 ```
 
+A `wire` credential resolves per user, so an unconnected user hits
+`MissingCredentialError` rather than silently acting as someone else; a
+`singleton` credential is platform-level and identical for every caller.
+
 ## Key Rule
 
 **Never use `process.env` inside Pikku functions.** Use the `variables` or `secrets` service:
@@ -201,7 +226,24 @@ const apiKey = process.env.API_KEY
 const apiKey = services.variables.get('API_KEY')
 ```
 
-`process.env` belongs only in server bootstrap code (`start.ts`).
+`process.env` belongs only in server bootstrap code (`start.ts`). Under `pikku dev` / `pikku serve` there is no `start.ts` — startup work goes in a `pikkuServerLifecycle` export, and the hooks receive the singleton services, so read configuration through `variables` there too (see pikku-services).
+
+### Lint rules
+
+`pikku.config.json` can set the severity of individual checks:
+
+```json
+{
+  "lint": {
+    "servicesNotDestructured": "error",
+    "wiresNotDestructured": "error",
+    "functionDynamicImport": "warn",
+    "customServerBootstrap": "warn"
+  }
+}
+```
+
+`customServerBootstrap` is the one evaluated by `pikku workspace validate` rather than codegen: it warns when the root `start`/`dev` script boots a server without `pikku dev` / `pikku serve` and no runtime adapter is installed. Set it to `"off"` to keep a hand-rolled entrypoint, or `"error"` to enforce the hooks.
 
 ## Complete Example
 

package/skills/pikku-cron/SKILL.md

@@ -6,6 +6,7 @@ description: >-
   when: code uses wireScheduler, user asks about cron, scheduled tasks, recurring jobs, or "run
   every X minutes/hours". DO NOT TRIGGER when: user asks about background jobs with retries (use
   pikku-queue) or event-driven triggers (use pikku-trigger).
+installGroups: [core]
 ---
 
 # Pikku Cron/Scheduler Wiring
@@ -42,6 +43,7 @@ wireScheduler({
   name: string,            // Unique scheduler name
   schedule: string,        // Cron expression
   func: PikkuVoidFunc,     // Must be pikkuVoidFunc (no input/output)
+  tags?: string[],         // Targets tag middleware — see pikku-middleware
   middleware?: PikkuMiddleware[],
 })
 ```
@@ -53,10 +55,17 @@ Inside scheduled functions:
 ```typescript
 wire.scheduledTask.name // Scheduler name
 wire.scheduledTask.schedule // Cron expression string
-wire.scheduledTask.executionTime // When this execution was triggered
-wire.scheduledTask.skip(reason) // Skip this execution (no error)
+wire.scheduledTask.executionTime // Date this execution was triggered
+wire.scheduledTask.skip(reason?) // Abort this execution — THROWS, never returns
 ```
 
+**`skip()` aborts by throwing.** It reads like an early return but it is not:
+nothing after the call runs, so there is no need to `return` afterwards. The
+consequence that bites is in middleware — a `try/catch` around `await next()`
+will catch a skip and report it as a failure. If your middleware distinguishes
+success from failure, let the skip pass through rather than logging it as an
+error.
+
 ### Cron Expression Reference
 
 ```
@@ -113,8 +122,7 @@ const weeklyCleanup = pikkuVoidFunc({
 
     const staleCount = await db.countStaleTodos()
     if (staleCount === 0) {
-      wire.scheduledTask.skip('No stale todos found')
-      return
+      wire.scheduledTask.skip('No stale todos found') // throws — nothing below runs
     }
 
     await db.deleteCompletedTodos({ olderThan: '30d' })
@@ -178,8 +186,7 @@ export const cleanupExpired = pikkuVoidFunc({
   func: async ({ db, logger }, _input, wire) => {
     const count = await db.countExpiredSessions()
     if (count === 0) {
-      wire.scheduledTask.skip('No expired sessions')
-      return
+      wire.scheduledTask.skip('No expired sessions') // throws — nothing below runs
     }
     await db.deleteExpiredSessions()
     logger.info(`Cleaned ${count} expired sessions`)

package/skills/pikku-deploy-azure/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: pikku-deploy-azure
 description: >-
-  Use when deploying a Pikku app to Azure Functions. Covers PikkuAzFunctionsLogger and
-  PikkuAzTimerRequest for Azure Functions runtime. TRIGGER when: user asks about Azure Functions,
-  Azure deployment, or @pikku/azure-functions. DO NOT TRIGGER when: user asks about AWS Lambda
-  (use pikku-deploy-lambda) or Cloudflare Workers (use pikku-deploy-cloudflare).
+  Use when deploying a Pikku app to Azure Functions. Covers createAzureHandler for HTTP, storage
+  queue and timer triggers, plus AzInvocationLogger and PikkuAZTimerRequest. TRIGGER when: user
+  asks about Azure Functions, Azure deployment, or @pikku/azure-functions. DO NOT TRIGGER when:
+  user asks about AWS Lambda (use pikku-deploy-lambda) or Cloudflare Workers (use
+  pikku-deploy-cloudflare).
 ---
 
 # Pikku Azure Functions Deployment
@@ -29,43 +30,97 @@ yarn add @pikku/azure-functions @azure/functions
 
 ## API Reference
 
-### `PikkuAzFunctionsLogger`
-
-Logger implementation that integrates with Azure Functions' built-in logging context.
-
-### `PikkuAzTimerRequest`
-
-Timer trigger request handler for running Pikku scheduled functions as Azure Timer Triggers.
+Exported from `@pikku/azure-functions`:
+
+- `createAzureHandler(factories, handlerTypes)` — the entry point. Returns
+  `{ http?, queue?, timer? }` for the handler types you ask for.
+- `createAzureWorkerHandler(factories)` — `createAzureHandler(factories, ['fetch'])`.
+- `createAzureWebSocketHandler(factories)` — **a stub**: its `negotiate` always
+  answers `501 WebSocket via Azure Web PubSub not yet implemented`. Channels do
+  not work on Azure yet; do not plan a deployment around it.
+- `AzInvocationLogger` — the logger. Note the name: there is no
+  `PikkuAzFunctionsLogger`.
+- `PikkuAZTimerRequest` — `new PikkuAZTimerRequest(context, data)`, a
+  `PikkuRequest` carrying the data. The context argument is accepted and
+  ignored.
+- `AzureQueueService`, `AzureDeploymentService`.
+
+`factories` is `{ createConfig, createSingletonServices, createPlatformServices? }`.
+Services are built from `process.env` and cached in module scope across
+invocations of the same instance.
 
 ## Usage Patterns
 
-### HTTP Function
+### Registering handlers
 
 ```typescript
 import { app } from '@azure/functions'
-import { PikkuAzFunctionsLogger } from '@pikku/azure-functions'
+import { createAzureHandler } from '@pikku/azure-functions'
+import { createConfig, createSingletonServices } from './services.js'
+import './.pikku/pikku-bootstrap.gen.js'
+
+const handlers = createAzureHandler(
+  { createConfig, createSingletonServices },
+  ['fetch', 'queue', 'scheduled']
+)
 
 app.http('api', {
-  methods: ['GET', 'POST', 'PUT', 'DELETE'],
+  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
   route: '{*path}',
-  handler: async (request, context) => {
-    const logger = new PikkuAzFunctionsLogger(context)
-    // Wire Pikku HTTP runner with Azure request/response
-  },
+  handler: handlers.http as any,
 })
-```
 
-### Timer Trigger
-
-```typescript
-import { app } from '@azure/functions'
-import { PikkuAzTimerRequest } from '@pikku/azure-functions'
+app.storageQueue('queue', {
+  queueName: 'my-queue',
+  connection: 'AzureWebJobsStorage',
+  handler: handlers.queue as any,
+})
 
 app.timer('scheduler', {
   schedule: '0 */5 * * * *',
-  handler: async (timer, context) => {
-    const request = new PikkuAzTimerRequest(timer)
-    // Process scheduled Pikku functions
-  },
+  handler: handlers.timer as any,
 })
 ```
+
+Note the key names: `handlerTypes` uses **`scheduled`**, but the handler it
+returns is **`timer`**.
+
+### HTTP
+
+The handler buffers the whole body, converts to a standard `Request`, and
+returns the response body as **text** — a streaming or binary response is
+flattened. It takes no `RunHTTPWiringOptions`, so there is no `maxBodySize` or
+`respondWith404` here; Azure's own request limits are the bound. A thrown error
+is logged to `console.error` and whatever the response already holds is
+returned.
+
+### Queue
+
+The queue name comes from the message's own `queueName`, falling back to
+`context.triggerMetadata.queueTrigger` and then `'unknown'` — a name that does
+not match a wired queue means the job has no handler. `attemptsMade` is read
+from `dequeueCount`, and `waitForCompletion` throws: Azure Storage Queues are
+fire-and-forget. A failing job throws out of the handler, so retries and the
+poison queue are governed by `host.json`, not by Pikku.
+
+Producer side, `AzureQueueService(connectionString?)` falls back to
+`AzureWebJobsStorage` and throws at construction if neither is set. Messages are
+base64-encoded (Azure requires it), `delay` is milliseconds mapped to
+`visibilityTimeout` in whole seconds capped at 7 days, `supportsResults` is
+`false` and `getJob()` always throws. The queue name is remapped through
+`AZURE_QUEUE_NAME_<SCREAMING_SNAKE>` when that variable exists, otherwise used
+as-is.
+
+### Timer
+
+The timer handler runs **every** scheduled task registered in the bundle,
+ignoring both the `Timer` argument and each task's own cron expression. Unlike
+the Lambda equivalent it does not catch per-task failures, so the first task
+that throws aborts the ones after it — keep one schedule per function app, or
+guard the task bodies yourself.
+
+### Logging
+
+`new AzInvocationLogger(context)` forwards to the invocation context's
+`info`/`warn`/`error`/`debug`/`trace`. `setLevel()` is a **no-op**: every level
+is emitted and filtering has to be done in Azure's own logging configuration.