@voltro/cli 0.30.1 → 0.31.0

package/templates/agent-docs/plugins/ai-flows.md

@@ -0,0 +1,148 @@
+# AI Flows
+
+> Durable multi-step AI pipelines — deterministic or agentic, with human-in-the-loop, chaining, and cadence. Author flows in code (defineFlow) or as data (visual-editor rows); one engine runs both.
+
+
+
+---
+
+<!-- source: en/plugins/ai-flows.md -->
+## AI Flows
+
+_Durable multi-step AI pipelines — deterministic or agentic, with human-in-the-loop, chaining, and cadence. Author flows in code (defineFlow) or as data (visual-editor rows); one engine runs both._
+
+`@voltro/plugin-ai-flows` turns a multi-step AI pipeline into a **durable,
+resumable run**: an orchestrator that chains sub-agents and generation tools
+(text / image / video / audio) into a bundled result, with **human-in-the-loop**
+review, **chaining** (flow A feeds flow B), and **cadence** (scheduling). It's the
+layer above `@voltro/ai` agents — an agent is code; a **flow is data** a
+non-technical user can author in a visual editor and the framework interprets.
+
+Two execution modes:
+
+- **Deterministic** (`mode: 'deterministic'`) — run the plan steps in order,
+  verbatim, no orchestrator LLM. Predictable, cheaper, **resumable per step** (a
+  crash/deploy resumes from the first unfinished step via the workflow journal).
+- **Agentic** (`mode: 'agentic'`) — an orchestrator LLM drives the tools and may
+  reorder/insert/skip the suggested plan, bounded by `maxSteps`.
+
+And two authoring **front doors** that lower to one engine:
+
+- **Code-first `defineFlow(...)`** — typed, testable, diffable; validates every
+  `{{ref}}` at registration (dangling refs fail at boot, not mid-run).
+- **Data-driven** — a stored `_voltro_ai_flows` row (from a visual editor); hot-editable,
+  no deploy.
+
+## Install
+
+```ts
+// app.config.ts
+import { aiFlowsPlugin } from '@voltro/plugin-ai-flows'
+export default { plugins: [aiFlowsPlugin()] }   // contributes _voltro_ai_flows + _voltro_ai_flow_runs
+```
+
+## Author a flow (code-first)
+
+```ts
+import { defineFlow, flowStep } from '@voltro/plugin-ai-flows'
+
+defineFlow({
+  name: 'blog-article',
+  brief: [{ key: 'topic', label: 'Topic', type: 'text', required: true }],
+  steps: [
+    flowStep.agent({ agentRef: 'writer', prompt: 'Draft a post about {{topic}}', outputKey: 'draft' }),
+    flowStep.human({ reviewMode: 'approve', prompt: 'Approve this draft?' }),
+    flowStep.media('image', { prompt: 'Hero image for: {{draft}}', outputKey: 'hero' }),
+    flowStep.note({ prompt: '# {{topic}}\n\n{{draft}}\n\n![hero]({{hero}})', outputKey: 'final' }),
+  ],
+})
+```
+
+Each step writes `context[outputKey]`; later steps reference it as `{{outputKey}}`
+(alongside `{{briefKey}}`). The **result bundle** is `outputKey → value`.
+
+## Step kinds
+
+- **`agent`** — delegate to a sub-agent (its system prompt + model), text-only.
+- **`generate`** — `text` / `image` / `video` / `audio` via `@voltro/ai`.
+- **`structured`** — a JSON object.
+- **`note`** — the interpolated prompt itself is the output (no model call).
+- **`human`** — pause for review (`approve` / `choice` / `text`).
+
+## Human-in-the-loop
+
+A `human` step sets the run to `waiting` and **parks the workflow without holding
+a worker** (the durable suspend). The user answers via `respondToFlow`; a reject
+ends the run cancelled, otherwise the answer lands in `context` and the run
+resumes. Thousands of runs can wait on review for days at no runtime cost.
+
+## Chaining & cadence
+
+- **`chainTo`** launches a follow-up flow on success (result ⊕ input → the child's
+  brief); `requireConfirmation` stages it for the user to confirm.
+- **`cadence`** schedules runs — `weekly` (with `intervalWeeks` + `anchorDate`) or
+  `monthly` (`weekOfMonth`, incl. `'last'`). `cadenceMatches` / `nextRuns` are
+  exported so the editor's "next 3 runs" preview and the scheduler agree exactly.
+
+## Live timeline
+
+`_voltro_ai_flow_runs` is reactive (the default): the engine patches the row (`steps[]`, `status`,
+`costMicroUsd`, …) as it runs, and the client's subscription streams the timeline
+over CDC — no polling, no sockets.
+
+## Wiring (once per app)
+
+The engine runs as one durable workflow; the operations are server helpers (a
+plugin route's context is subject-only, so the app owns the thin RPC surface):
+
+```ts
+// api/flows/flow.run.workflow.tsx
+export { flowRunWorkflow as default } from '@voltro/plugin-ai-flows/workflow'
+
+// api/flows/flow.run.workflow.server.tsx
+import { buildFlowRunExecute, makeMediaGenerator } from '@voltro/plugin-ai-flows'
+export default (ctx) => buildFlowRunExecute(ctx, {
+  resolveAgent:  (ref) => /* → { system, model } */,
+  // No AI Gateway key? Route model strings to a direct provider (or honour a
+  // `provider/model` prefix). Absent → every call goes to the gateway.
+  resolveModel:  (model) => providerFromEnv(),
+  // `run.tenantId` is the durable tenant from the run row — pin persistence to
+  // it so a resume stores into the right tenant even when the subject has none.
+  generateMedia: makeMediaGenerator({ put: ({ data, mediaType, run }) => storage.put({ bytes: data, contentType: mediaType, tenantId: run.tenantId }), ingestUrl: (u, run) => storage.ingestUrl(u, { tenantId: run.tenantId }) }, { resolveModel: (m) => providerFromEnv() }),
+  onEvent:       (e) => /* notify via @voltro/plugin-notifications */,
+  memoryPrefix:  (ownerId) => /* long-term memory */,
+})
+
+// api/flows/aiFlows.launch.action.server.ts  (+ retry / cancel / respond)
+import { launchFlow } from '@voltro/plugin-ai-flows'
+export default (ctx) => (input) => launchFlow(ctx, input)
+
+// The plugin OWNS _voltro_ai_flows — import its CRUD helpers over the plugin's table
+// instead of forking your own entity + a store bridge:
+import { getFlow, listFlows, createFlow, updateFlow, deleteFlow } from '@voltro/plugin-ai-flows'
+// e.g. api/flows/aiFlows.list.query.server.ts → (ctx) => () => listFlows(ctx)
+
+// api/flows/flows.cadence.cron.tsx
+import { defineSchedule } from '@voltro/runtime'
+import { runCadenceTick } from '@voltro/plugin-ai-flows'
+import { Effect } from 'effect'
+export default defineSchedule({ cron: '*/15 * * * *', timezone: 'Europe/Berlin', handler: (s) => Effect.promise(() => runCadenceTick(s.app)) })
+```
+
+Adopt `@voltro/plugin-versioning` on `_voltro_ai_flows` for automatic edit history.
+
+## Deployment notes
+
+- **Durability**: each generation is a durable step — deterministic runs resume
+  from the first unfinished step; agentic runs aren't replay-deterministic (LLM
+  planner), so a mid-run crash re-plans (`retry` = fresh run).
+- **Cadence + scale-to-zero**: `dormancy: 'sleep'` won't fire an in-process tick —
+  use an external waker or `trigger: 'external'`.
+- **Media retention**: not automatic — add a `*.cron.tsx` deleting old artifacts
+  via `storage.delete(id)` (a plain retention sweep would orphan the blobs).
+- **Media tenant on resume**: `generateMedia` receives `run.tenantId`, read from
+  the durable run row. Pin persistence to it (as above) rather than the caller
+  subject — a resumed run executes under a tenant-less system subject, so reading
+  the tenant from the subject would fail closed or store into the wrong tenant.
+- **Cost** is tracked in `costMicroUsd` (micro-USD) on the run + per step; project
+  to your display currency in the view.

package/templates/agent-docs/plugins/analytics-postgres.md

@@ -0,0 +1,90 @@
+# Postgres analytics
+
+> First-party lite AnalyticsSink — stores events in the main DataStore, cross-dialect, zero external infra. ~10M events/day ceiling.
+
+
+
+---
+
+<!-- source: en/plugins/analytics-postgres.md -->
+## Postgres analytics
+
+_First-party lite AnalyticsSink — stores events in the main DataStore, cross-dialect, zero external infra. ~10M events/day ceiling._
+
+`@voltro/plugin-analytics-postgres` is the day-1 `AnalyticsSink` — it stores
+events in an `_voltro_events` table on the **main DataStore**, so there's no
+external service to run. It implements all four contract methods (`track` /
+`aggregate` / `timeseries` / `topN`) by compiling to portable SQL that works on
+every dialect (postgres / mysql / mariadb / mssql / sqlite). Pick it first;
+swap to a real OLAP sink (DuckDB / ClickHouse / Tinybird) only once you outgrow
+its **~10M events/day** ceiling — the swap is a one-line config change because
+every sink shares the same contract. For the shared `AnalyticsSink` API and the
+`useAnalytics()` read methods, see [Analytics & warehouse sinks](/docs/plugins/analytics).
+
+## Install
+
+```
+pnpm add @voltro/plugin-analytics-postgres
+```
+
+## Wiring
+
+```ts
+// app.config.ts
+import { postgresAnalytics } from '@voltro/plugin-analytics-postgres'
+
+export default {
+  type:      'api' as const,
+  name:      'myApi',
+  store:     'postgres' as const,
+  analytics: postgresAnalytics(),
+}
+```
+
+The framework calls the factory at boot, hands it the `SqlClient` bound to the
+running DataStore, and provides the resulting sink under `AnalyticsSink`. The
+plugin's `_voltro_events` table is auto-merged into your schema, so
+`applySchema()` creates it on first boot — no `*.entity.ts` needed.
+
+## Options
+
+`postgresAnalytics(options?)` — all optional:
+
+| Option | Type | Default | Notes |
+|---|---|---|---|
+| `sqlClient` | `SqlClient.SqlClient` | the main DataStore's client | Override to land events in a SEPARATE database (e.g. a dedicated analytics Postgres while the app runs MySQL). You must create the events table there yourself. |
+| `mirrorTables` | `ReadonlyArray<string>` | `[]` (events-only) | Reactive tables to CDC-mirror into `_voltro_mirror_<table>` (`{ id, data }`) so analytical queries can JOIN events against live user data. |
+| `mirrorPrimaryKey` | `string` | `'id'` | Primary-key column on the mirrored source rows. |
+
+```ts
+analytics: postgresAnalytics({ mirrorTables: ['users', 'teams'] })
+```
+
+## Environment
+
+- **`VOLTRO_EVENTS_TTL_HOURS`** — retention TTL for `_voltro_events`. Default
+  `8760` (365 days). A boot retention sweep drains events past the TTL so the
+  table never grows without bound.
+
+## Honest ceiling
+
+By ~10M events/day, range aggregates over 30 days take >5s on Postgres. Past
+that, switch to [`@voltro/plugin-duckdb`](/docs/plugins/duckdb) (embedded) or
+[`@voltro/plugin-clickhouse`](/docs/plugins/clickhouse) (external). Reads are
+tenant-scoped automatically — `useAnalytics()` stamps the caller's `tenantId`
+onto every `track` and every aggregate.
+
+## Schema introspection
+
+The plugin re-exports its events-table descriptor so you can extend the schema
+(add a GIN index on `properties`, partition by month) via your own migration:
+
+```ts
+import { _voltroEventsTable } from '@voltro/plugin-analytics-postgres'
+```
+
+## See also
+
+- [Analytics & warehouse sinks](/docs/plugins/analytics) — the shared
+  `AnalyticsSink` contract, the `useAnalytics()` read API, `composeAnalytics`,
+  and the CDC-mirror details.

package/templates/agent-docs/plugins/atlassian.md

@@ -0,0 +1,378 @@
+# Atlassian
+
+> JiraService + ConfluenceService over the Atlassian REST / Greenhopper / Agile APIs, with a per-subject PAT resolver, transient retry, SSRF guard, an avatar proxy, and per-tenant caching.
+
+
+
+---
+
+<!-- source: en/plugins/atlassian.md -->
+## Atlassian
+
+_JiraService + ConfluenceService over the Atlassian REST / Greenhopper / Agile APIs, with a per-subject PAT resolver, transient retry, SSRF guard, an avatar proxy, and per-tenant caching._
+
+`@voltro/plugin-atlassian` exposes `JiraService` + `ConfluenceService` over the Atlassian REST / Greenhopper / Agile APIs. The app supplies a `credentialsResolver({ subject, store })` — the plugin never reads your schema; the caller's credentials are resolved per request from the Subject (populated by `AuthMiddleware`).
+
+**Status:** ✓ shipped.
+
+Two auth modes, both first-class (choose per deployment):
+
+- **PAT / basic** — a Personal Access Token per subject. The default for Jira/Confluence **Data Center / Server**. Wire it via `credentialsResolver` (below).
+- **OAuth 2.0 (3LO)** — the authorization-code flow for Atlassian **Cloud**, where the app acts on behalf of a consenting user. Use the toolkit ([OAuth 2.0 (3LO)](#oauth-20-3lo)) to obtain an access token, then feed it into the same `credentialsResolver`.
+
+It also supports [inbound Jira/Confluence webhooks](#inbound-webhooks) (signature-verified) and writing comments to issues and pages.
+
+## Wiring
+
+```ts
+// app.config.ts
+import { Effect } from 'effect'
+import { atlassianPlugin } from '@voltro/plugin-atlassian'
+
+export default {
+  type: 'api' as const,
+  name: 'api',
+  plugins: [
+    atlassianPlugin({
+      credentialsResolver: ({ subject, store }) =>
+        Effect.gen(function* () {
+          const pat = yield* lookupPatForSubject(store, subject)   // your schema
+          return {
+            baseUrl:        process.env.JIRA_BASE_URL!,
+            token:          pat,
+            patApplication: 'my-app',
+            patEnvironment: process.env.PAT_ENVIRONMENT!,
+          }
+        }),
+      // optional: cache, avatar proxy, retry/timeout policy — see below
+    }),
+  ],
+}
+```
+
+> **Never put the credential in `subject.metadata`.** The resolver used to take a
+> bare `Subject`, so that was the only place to keep a per-user PAT — and from
+> there it travels with the identity into everything that persists a Subject. A
+> reporter found a working Jira PAT in plaintext in 12 of 23 rows of their
+> `_voltro_audit_log` exactly that way. The `store` handle above exists so it
+> never has to enter the Subject; [`connectionCredentials`](#connections) is
+> better still, because then you do not hold the token at all.
+
+The resolver returns `AtlassianCredentials`:
+
+```ts
+interface AtlassianCredentials {
+  readonly baseUrl:        string  // the Atlassian site root
+  readonly token:          string  // the caller's Personal Access Token
+  readonly patApplication: string  // → X-PAT-Application header
+  readonly patEnvironment: string  // → X-PAT-Environment header
+}
+```
+
+Every method resolves the caller's PAT by calling `credentialsResolver({ subject: yield* SubjectService, store })`. The handler context satisfies that requirement, so you never thread credentials by hand. If a subject has no PAT on file, fail the resolver with a `JiraError` and the call surfaces it as a typed error.
+
+## Using it in a handler
+
+```ts
+import { Effect } from 'effect'
+import { JiraService, ConfluenceService } from '@voltro/plugin-atlassian'
+
+export default (input) => Effect.gen(function* () {
+  const jira = yield* JiraService
+
+  const issues = yield* jira.searchIssues(
+    `project = ${input.project} AND sprint in openSprints()`,
+  )
+  const board  = yield* jira.getGreenhopperBoard(input.boardId)  // { issues, columns, swimlanes, raw }
+  const sprint = yield* jira.getActiveSprint(input.boardId)      // SprintRef | null
+
+  return { count: issues.length, sprint }
+})
+```
+
+`JiraService` and `ConfluenceService` are both Effect-returning with typed errors, so a caller can branch on the failure tag:
+
+```ts
+yield* jira.getIssue('ABC-1').pipe(
+  Effect.catchTag('JiraError', (err) =>
+    err.code === 'session_expired'
+      ? Effect.fail(reauthNeeded())     // PAT is stale — re-auth
+      : Effect.fail(err),
+  ),
+)
+```
+
+## JiraService
+
+| Method | Atlassian endpoint |
+|---|---|
+| `searchIssues(jql, options?)` | `POST /rest/api/2/search` — JQL, batched 100, follows pagination → all matches |
+| `getGreenhopperBoard(boardId, options?)` | `GET /rest/greenhopper/1.0/xboard/work/allData.json` → `{ issues, columns, swimlanes, raw }` |
+| `getBoardConfig(boardId)` | `GET /rest/greenhopper/1.0/rapidviewconfig/editmodel` |
+| `getActiveSprint(boardId)` | `GET /rest/agile/1.0/board/{id}/sprint?state=active` → `SprintRef \| null` |
+| `getSprintIssues(sprintId)` | `GET /rest/agile/1.0/sprint/{id}/issue` |
+| `getSprintInfo(sprintId)` | `GET /rest/agile/1.0/sprint/{id}` |
+| `getIssue(key, options?)` | `GET /rest/api/2/issue/{key}` (`expand` / `fields`) |
+| `getIssueChangelog(key)` | `GET /rest/api/2/issue/{key}?expand=changelog` |
+| `getComments(key)` | `GET /rest/api/2/issue/{key}/comment` |
+| `addComment(key, body)` | `POST /rest/api/2/issue/{key}/comment` — add a comment |
+| `getLinkedIssues(key)` | resolves an issue's `issuelinks` to the linked issues |
+| `getUser({ key?, username? })` | `GET /rest/api/2/user` / `/rest/api/2/user/search` |
+| `getMyself()` | `GET /rest/api/2/myself` |
+| `getIssueTransitions(key)` | `GET /rest/api/2/issue/{key}/transitions` |
+| `transitionIssue(key, transitionId, options?)` | `POST /rest/api/2/issue/{key}/transitions` |
+| `createIssue(payload)` | `POST /rest/api/2/issue` |
+| `updateIssue(key, payload)` | `PUT /rest/api/2/issue/{key}` |
+| `getProject(key)` | `GET /rest/api/2/project/{key}` |
+| `getFields()` | `GET /rest/api/2/field` |
+| `getStatuses()` | `GET /rest/api/2/status` |
+| `getFilters()` | `GET /rest/api/2/filter` |
+| `getAvatarUrl(ownerId)` | builds the `/secure/useravatar?ownerId=…` URL |
+| `getBoard(boardId)` | `GET /rest/agile/1.0/board/{id}` |
+| `getBoardQuickFilters(boardId)` | `GET /rest/agile/1.0/board/{id}/quickfilter` (→ `.values`) |
+| `getBoardFilterJql(boardId)` | `/board/{id}/configuration` → `/filter/{id}.jql` (board's saved-filter JQL, or `null`) |
+| `assignIssue(key, assignee)` | `PUT /rest/api/2/issue/{key}/assignee` (`{ name }`; `null` unassigns) |
+| `deleteIssue(key, { deleteSubtasks? })` | `DELETE /rest/api/2/issue/{key}` |
+| `getBaseUrl()` | the configured base URL (no HTTP) |
+
+## ConfluenceService
+
+Same PAT scheme and resilience as Jira.
+
+| Method | Atlassian endpoint |
+|---|---|
+| `getContent(id, options?)` | `GET /rest/api/content/{id}?expand=body.view,version` |
+| `searchContent(cql, options?)` | `GET /rest/api/content/search?cql=…&expand=version,space` |
+| `getSpace(spaceKey)` | `GET /rest/api/space/{key}` |
+| `createContent(payload)` | `POST /rest/api/content` |
+| `updateContent(id, payload, { version })` | `PUT /rest/api/content/{id}` (version-bumped) |
+| `getAttachments(contentId)` | `GET /rest/api/content/{id}/child/attachment` |
+| `addComment(pageId, body)` | `POST /rest/api/content` — a `type: 'comment'` content (storage markup) anchored to the page |
+| `downloadImage(url)` | PAT-gated binary fetch of a same-host embedded image → `{ bytes, contentType }` (SSRF-guarded) |
+
+## Resilience
+
+Every call goes through one HTTP choke point that:
+
+- **Retries** transient failures — `408 / 425 / 429 / 500 / 502 / 503 / 504` plus network blips / timeouts — with exponential backoff (default 4 attempts, 500 ms initial, capped at 10 s).
+- **Honours `Retry-After`** on the response over the computed backoff (`honourRetryAfter: true` by default).
+- **Times out** each request (default 20 s) and treats the timeout as transient.
+- **SSRF-guards** every URL: the resolved host must equal the configured base host, so a crafted ref can't pivot the server-side fetch to an internal address.
+- **Treats 401 as non-transient** `session_expired` — the stored PAT is stale, so re-auth rather than retry. It surfaces as a `JiraError` / `ConfluenceError` with `transient: false` and `code: 'session_expired'`.
+
+Override the policy per instance:
+
+```ts
+atlassianPlugin({
+  credentialsResolver,
+  policy: {
+    maxAttempts:      6,
+    initialDelayMs:   250,
+    maxDelayMs:       20_000,
+    timeoutMs:        30_000,
+    honourRetryAfter: true,
+  },
+})
+```
+
+## OAuth 2.0 (3LO)
+
+For Atlassian **Cloud**, where a PAT isn't available and the app acts on behalf of a consenting user, use the OAuth 2.0 three-legged-auth toolkit. It is an **alternative** to PAT auth, not a replacement — PAT/basic stays fully supported for Data Center / Server. The plugin holds **no** token storage of its own: the app persists the token set (the same seam PAT credentials use) and the toolkit handles the authorization-code exchange + refresh. The `clientSecret` and tokens are runtime values sourced from config/env, never logged, never bundled.
+
+```ts
+import { Effect } from 'effect'
+import {
+  buildAuthorizeUrl,
+  exchangeCode,
+  withFreshToken,
+  type OAuthConfig,
+  type OAuthTokens,
+} from '@voltro/plugin-atlassian'
+
+const oauth: OAuthConfig = {
+  clientId:     process.env.ATLASSIAN_CLIENT_ID!,
+  clientSecret: process.env.ATLASSIAN_CLIENT_SECRET!,   // secret — env/config only
+  redirectUri:  'https://app.example.com/oauth/atlassian/callback',
+}
+
+// 1. Redirect the user to consent. Store `state`; verify it on the callback.
+//    `offline_access` is required to receive a refresh token.
+const authorizeUrl = buildAuthorizeUrl(oauth, {
+  scopes: ['read:jira-work', 'write:jira-work', 'offline_access'],
+  state:  crypto.randomUUID(),
+  prompt: 'consent',
+})
+
+// 2. On the callback (`?code=…&state=…`), exchange the code + persist the set.
+const onCallback = (code: string) => Effect.gen(function* () {
+  const tokens = yield* exchangeCode({ ...oauth, fetchImpl: globalThis.fetch as never }, code)
+  yield* persistTokensForSubject(tokens)   // your store — { accessToken, refreshToken, expiresAt }
+})
+
+// 3. Before an OAuth call, get a still-valid token — refreshes near expiry.
+const accessTokenFor = (stored: OAuthTokens) =>
+  withFreshToken(
+    { ...oauth, fetchImpl: globalThis.fetch as never },
+    stored,
+    (rotated) => persistTokensForSubject(rotated),
+  )
+```
+
+Then feed the access token into the SAME `credentialsResolver` — the services send `Authorization: Bearer <accessToken>`, identical to the PAT path:
+
+```ts
+atlassianPlugin({
+  credentialsResolver: (subject) => Effect.gen(function* () {
+    const stored = yield* loadTokensForSubject(subject)   // your store
+    const fresh  = yield* accessTokenFor(stored)
+    return {
+      baseUrl:        `https://api.atlassian.com/ex/jira/${cloudIdForSubject(subject)}`,
+      token:          fresh.accessToken,
+      patApplication: 'my-app',
+      patEnvironment: process.env.PAT_ENVIRONMENT!,
+    }
+  }),
+})
+```
+
+Exchange/refresh failures are a typed `AtlassianOAuthError` (`{ message, transient, status? }`) — `transient: true` only for a 5xx / network blip at the token endpoint; a missing refresh token surfaces as a non-transient re-consent signal. The `clientSecret` and tokens never appear in `message`.
+
+## Inbound webhooks
+
+Receive Jira/Confluence webhook events over the framework's normal webhook seam. Atlassian signs the raw body with HMAC-SHA-256 and writes `X-Hub-Signature: sha256=<hex>` (the shared secret is configured on the webhook — env/config only, never logged).
+
+**Recommended — the `*.webhook.tsx` provider path** (durable, dashboard-listed, auto-verified + de-duped by the framework). `atlassianWebhookProvider()` is a drop-in `@voltro/plugin-webhooks` provider preset:
+
+```ts
+import { Schema } from 'effect'
+import { defineIncomingWebhook } from '@voltro/plugin-webhooks'
+import { atlassianWebhookProvider } from '@voltro/plugin-atlassian/webhook'
+
+export default defineIncomingWebhook({
+  id:       'jira-events',
+  provider: atlassianWebhookProvider(),   // HMAC-SHA-256 signature + idempotency
+  payload:  Schema.Any,                   // narrow per event in the handler
+  handler:  async (ctx) => {
+    // Signature already verified by the framework; switch on the event type.
+    switch ((ctx.body as { webhookEvent?: string }).webhookEvent) {
+      case 'jira:issue_updated': break
+      case 'comment_created':    break
+    }
+  },
+})
+```
+
+The preset extracts the event type from the body's `webhookEvent` field and the idempotency key from the `X-Atlassian-Webhook-Identifier` header (falling back to `<event>:<timestamp>`).
+
+**Raw-route path** — if you wire the webhook onto a `PluginHttpRoute` (or any HTTP surface) yourself, verify + parse with the standalone primitives:
+
+```ts
+import { verifyWebhookSignature, parseWebhookEnvelope } from '@voltro/plugin-atlassian/webhook'
+
+const handle = (rawBody: Uint8Array, headers: Record<string, string>) => {
+  verifyWebhookSignature({ rawBody, headers, secret: process.env.ATLASSIAN_WEBHOOK_SECRET! })
+  const event = parseWebhookEnvelope(rawBody)   // { webhookEvent, issue?, comment?, page?, raw }
+  // dispatch on event.webhookEvent
+}
+```
+
+Both reject failures with a typed `AtlassianWebhookError` — `reason: 'signature'` (missing/invalid signature → map to 401) or `reason: 'payload'` (bad body → 400). Verification is constant-time.
+
+## Avatar proxy
+
+Jira user avatars require the PAT, so the browser can't fetch them directly. The proxy resolves the avatar server-side and serves the **bytes** — the artefact the browser gets is credential-free, which is the whole point: the PAT is spent on the fetch and never reaches the client.
+
+The route serves bytes at `/_voltro/atlassian/avatar/:ownerId` — fetched server-side with binary headers (no `Accept`, so Jira returns the raw image), SSRF-guarded to the configured host, `image/*`-only (never proxies an HTML error page), with a 1-year `immutable` cache (a Jira avatar for an `ownerId` never changes).
+
+`avatar` is a **discriminated union on a required `mode`**. The two modes are not interchangeable, and a config file must not leave which one is in play to inference:
+
+| `mode` | Whose credential fetches | Route access | Cache key |
+|---|---|---|---|
+| `'service'` | one shared service token | public | the avatar ref alone |
+| `'perUser'` | the **viewing** subject's own | authenticated only | viewer + avatar ref |
+
+### `mode: 'service'`
+
+One shared credential fetches every avatar and the route is public. Cheap, and every caller sees the same bytes:
+
+```ts
+atlassianPlugin({
+  credentialsResolver,
+  avatar: {
+    mode: 'service',
+    resolveCredentials: () => ({
+      baseUrl:        process.env.JIRA_BASE_URL!,
+      token:          process.env.JIRA_SERVICE_PAT!,   // dedicated read-only token
+      patApplication: 'my-app',
+      patEnvironment: process.env.PAT_ENVIRONMENT!,
+    }),
+    // pathPrefix defaults to '/_voltro/atlassian/avatar'
+  },
+})
+```
+
+### `mode: 'perUser'`
+
+Every fetch runs with the **viewing** subject's own credential, resolved per request — for deployments where a service PAT must not exist at all:
+
+```ts
+atlassianPlugin({
+  credentialsResolver,
+  avatar: {
+    mode: 'perUser',
+    // The framework does NOT authenticate plugin HTTP routes, so the app
+    // resolves the acting subject itself — typically from its session cookie.
+    resolveSubject: (req) => resolveSubjectFromCookie(req.headers['cookie']),
+    // That subject's own PAT. Throw when they have none — the route answers 403.
+    resolveCredentials: (subject) => loadPatForSubject(subject),
+  },
+})
+```
+
+`resolveSubject` is app-supplied because `PluginHttpRouteRequest` carries **no subject**: a plugin HTTP route is not part of the rpc pipeline, so nothing upstream has authenticated the caller. Verify the session yourself (`readCookie` + `verifySession` from `@voltro/protocol/session`) inside your own server-only module — that subpath must not be imported from a browser-reachable file. Return `null` for an unauthenticated caller.
+
+Three properties of this mode are load-bearing:
+
+- **Anonymous is refused outright.** `null`, an `anonymous` subject, or a subject with no `id` gets a `401` with **no upstream fetch and no cache read** — the identity is settled before anything else happens.
+- **There is no service fallback.** A subject with no PAT on file gets a `403`. Falling back to a shared credential is precisely what a deployment choosing this mode cannot do.
+- **The cache key is the VIEWER, never the avatar's owner.** A per-user entry keys on `type` + `id` + `tenantId` of the subject whose credential paid for the fetch, plus the avatar ref. Keying by the owner alone would be a cross-user read: user A's fetch would populate an entry served straight to user B without B's PAT ever being checked against Jira. The cost is a lower hit rate — one entry per (viewer, avatar) pair — and that is the correct trade, because a shared entry *is* the cross-user read. (`service` mode keys by the avatar ref alone, which is correct there: one credential authorised the fetch and every caller of the public route is entitled to exactly those bytes.)
+
+Pass a `cache` (`{ store, ttlMs? }`) in either mode; the stored value is content-type + base64 bytes, so a hit costs no upstream call and leaks no token.
+
+Upgrading from a config without `mode`? `voltro update` ships a codemod for it — the previous shape was service-only by construction (a zero-argument `resolveCredentials`, public route), so it inserts `mode: 'service'` at every `atlassianPlugin({ avatar: … })` site. Opting into `perUser` is a deliberate act afterwards: it needs a `resolveSubject` only your app can write.
+
+## Caching
+
+Pass a `@voltro/cache` store to memoise read calls per tenant. Keys are namespaced `atlassian:<namespace>:<tenant>:<key>`, so one org never reads another's cached board:
+
+```ts
+import { atlassianPlugin } from '@voltro/plugin-atlassian'
+
+atlassianPlugin({
+  credentialsResolver,
+  cache: {
+    store,                              // a @voltro/cache CacheStore
+    ttlMs: { boardConfig: 60_000, project: 30_000 },
+  },
+})
+```
+
+Only reference-data reads are cached — the four namespaces `boardConfig` (`getBoardConfig`), `project` (`getProject`), `field` (`getFields`), `status` (`getStatuses`). Issue/board *content* is never cached (it changes too often to serve stale). A missing namespace TTL falls back to the store default. Caching is best-effort: a cache read/write failure never fails the call — it falls through to the live request. With no `cache` option, every call is a direct pass-through.
+
+## Multiple sites
+
+Run two instances against two Atlassian sites by naming them:
+
+```ts
+plugins: [
+  atlassianPlugin({ name: 'eu', credentialsResolver: euResolver }),
+  atlassianPlugin({ name: 'us', credentialsResolver: usResolver }),
+]
+```
+
+## Anti-patterns
+
+- **Hard-coding a single shared PAT.** Resolve per subject so each caller acts as themselves and a stale token surfaces as `session_expired` for that user only.
+- **Fetching Jira avatars from the browser.** They need the PAT; use the avatar proxy and let the browser hit `/_voltro/atlassian/avatar/:ownerId`.
+- **Retrying a 401 yourself.** It's non-transient by design — re-auth the subject instead.
+- **Caching writes.** Only read calls (board config, project / field / status metadata) belong in the cache; mutations always go live.