diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index dea5311..2aa7785 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -86,42 +86,4 @@ jobs:
         with:
           name: compiled-templates
           path: templates-parser/out
-
-  docker:
-    name: docker build & push
-    runs-on: ubuntu-latest
-    needs: [fmt, clippy, test, templates-build]
-    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
-    permissions:
-      contents: read
-    steps:
-      - uses: actions/checkout@v4
-      - uses: docker/setup-qemu-action@v3
-      - uses: docker/setup-buildx-action@v3
-      - name: Log in to Docker Hub
-        uses: docker/login-action@v3
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-      - name: Extract metadata
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: ${{ secrets.DOCKERHUB_USERNAME }}/mailify
-          tags: |
-            type=ref,event=branch
-            type=semver,pattern={{version}}
-            type=semver,pattern={{major}}.{{minor}}
-            type=sha,prefix=sha-
-            type=raw,value=latest,enable={{is_default_branch}}
-      - name: Build and push
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          file: docker/Dockerfile
-          platforms: linux/amd64,linux/arm64
-          push: true
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
+# docker image build + push lives in .github/workflows/docker.yml (tag-triggered)
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
new file mode 100644
index 0000000..eceea9f
--- /dev/null
+++ b/.github/workflows/docker.yml
@@ -0,0 +1,98 @@
+name: docker
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: build (${{ matrix.platform }})
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: linux/amd64
+            runner: ubuntu-24.04
+            arch: amd64
+          - platform: linux/arm64
+            runner: ubuntu-24.04-arm
+            arch: arm64
+    runs-on: ${{ matrix.runner }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ secrets.DOCKERHUB_USERNAME }}/mailify
+      - name: Build and push by digest
+        id: build
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: docker/Dockerfile
+          platforms: ${{ matrix.platform }}
+          labels: ${{ steps.meta.outputs.labels }}
+          outputs: type=image,name=${{ secrets.DOCKERHUB_USERNAME }}/mailify,push-by-digest=true,name-canonical=true,push=true
+          cache-from: type=gha,scope=${{ matrix.arch }}
+          cache-to: type=gha,mode=max,scope=${{ matrix.arch }}
+      - name: Export digest
+        run: |
+          mkdir -p /tmp/digests
+          digest="${{ steps.build.outputs.digest }}"
+          touch "/tmp/digests/${digest#sha256:}"
+      - name: Upload digest
+        uses: actions/upload-artifact@v4
+        with:
+          name: digest-${{ matrix.arch }}
+          path: /tmp/digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+  manifest:
+    name: manifest & push
+    needs: build
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    steps:
+      - name: Download digests
+        uses: actions/download-artifact@v4
+        with:
+          path: /tmp/digests
+          pattern: digest-*
+          merge-multiple: true
+      - uses: docker/setup-buildx-action@v3
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ secrets.DOCKERHUB_USERNAME }}/mailify
+          tags: |
+            type=ref,event=branch
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=sha,prefix=sha-
+            type=raw,value=latest,enable={{is_default_branch}}
+      - name: Create manifest list and push
+        working-directory: /tmp/digests
+        run: |
+          docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
+            $(printf '${{ secrets.DOCKERHUB_USERNAME }}/mailify@sha256:%s ' *)
+      - name: Inspect image
+        run: |
+          docker buildx imagetools inspect ${{ secrets.DOCKERHUB_USERNAME }}/mailify:${{ steps.meta.outputs.version }}
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 0000000..fd4ac0d
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,200 @@
+name: release
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Tag to release (e.g. v0.2.0). Tag must already exist.'
+        required: true
+
+env:
+  CARGO_TERM_COLOR: always
+  BIN_NAME: mailify
+
+jobs:
+  # ─────────────────────────────────────────────────────────────
+  # 1. Create a draft GitHub Release up-front so matrix jobs upload into it
+  # ─────────────────────────────────────────────────────────────
+  create-release:
+    name: create draft release
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+    outputs:
+      tag: ${{ steps.resolve.outputs.tag }}
+      version: ${{ steps.resolve.outputs.version }}
+    steps:
+      - name: Resolve tag
+        id: resolve
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            TAG="${{ inputs.tag }}"
+          else
+            TAG="${GITHUB_REF#refs/tags/}"
+          fi
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ steps.resolve.outputs.tag }}
+      - name: Create draft release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          if gh release view "${{ steps.resolve.outputs.tag }}" >/dev/null 2>&1; then
+            echo "Release already exists — skipping creation."
+          else
+            gh release create "${{ steps.resolve.outputs.tag }}" \
+              --draft \
+              --title "${{ steps.resolve.outputs.tag }}" \
+              --generate-notes
+          fi
+
+  # ─────────────────────────────────────────────────────────────
+  # 2. Build binaries on native runners, upload signed archive + SHA256
+  # ─────────────────────────────────────────────────────────────
+  build-binaries:
+    name: build ${{ matrix.target }}
+    needs: create-release
+    permissions:
+      contents: write
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - target: x86_64-unknown-linux-gnu
+            runner: ubuntu-24.04
+            archive: tar.gz
+          - target: x86_64-unknown-linux-musl
+            runner: ubuntu-24.04
+            archive: tar.gz
+            musl: true
+          - target: aarch64-unknown-linux-gnu
+            runner: ubuntu-24.04-arm
+            archive: tar.gz
+          - target: x86_64-apple-darwin
+            runner: macos-13
+            archive: tar.gz
+          - target: aarch64-apple-darwin
+            runner: macos-14
+            archive: tar.gz
+          - target: x86_64-pc-windows-msvc
+            runner: windows-2022
+            archive: zip
+    runs-on: ${{ matrix.runner }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.create-release.outputs.tag }}
+
+      - name: Install Bun (templates build)
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.3"
+
+      - name: Build templates
+        working-directory: templates-parser
+        run: |
+          bun install --frozen-lockfile
+          bun run build
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+
+      - name: Install musl tools
+        if: matrix.musl == true
+        run: sudo apt-get update && sudo apt-get install -y --no-install-recommends musl-tools
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          key: ${{ matrix.target }}
+
+      - name: Build release binary
+        run: cargo build --release --bin ${{ env.BIN_NAME }} --target ${{ matrix.target }}
+
+      - name: Stage archive (Unix)
+        if: runner.os != 'Windows'
+        shell: bash
+        run: |
+          STAGE="${BIN_NAME}-${{ needs.create-release.outputs.version }}-${{ matrix.target }}"
+          mkdir -p "dist/$STAGE"
+          cp "target/${{ matrix.target }}/release/${BIN_NAME}" "dist/$STAGE/"
+          cp -r templates-parser/out "dist/$STAGE/templates"
+          cp README.md LICENSE* "dist/$STAGE/" 2>/dev/null || true
+          cd dist
+          tar -czf "$STAGE.tar.gz" "$STAGE"
+          shasum -a 256 "$STAGE.tar.gz" > "$STAGE.tar.gz.sha256"
+          echo "ASSET=dist/$STAGE.tar.gz" >> "$GITHUB_ENV"
+          echo "ASSET_SHA=dist/$STAGE.tar.gz.sha256" >> "$GITHUB_ENV"
+
+      - name: Stage archive (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $stage = "$env:BIN_NAME-${{ needs.create-release.outputs.version }}-${{ matrix.target }}"
+          New-Item -ItemType Directory -Force -Path "dist/$stage" | Out-Null
+          Copy-Item "target/${{ matrix.target }}/release/$env:BIN_NAME.exe" "dist/$stage/"
+          Copy-Item -Recurse "templates-parser/out" "dist/$stage/templates"
+          Copy-Item README.md,LICENSE* "dist/$stage/" -ErrorAction SilentlyContinue
+          Push-Location dist
+          Compress-Archive -Path $stage -DestinationPath "$stage.zip"
+          (Get-FileHash "$stage.zip" -Algorithm SHA256).Hash.ToLower() + "  $stage.zip" | Out-File "$stage.zip.sha256" -Encoding ascii
+          Pop-Location
+          "ASSET=dist/$stage.zip"      | Out-File -FilePath $env:GITHUB_ENV -Append
+          "ASSET_SHA=dist/$stage.zip.sha256" | Out-File -FilePath $env:GITHUB_ENV -Append
+
+      - name: Upload to release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release upload "${{ needs.create-release.outputs.tag }}" "${{ env.ASSET }}" "${{ env.ASSET_SHA }}" --clobber
+
+  # ─────────────────────────────────────────────────────────────
+  # 3. Publish crates to crates.io
+  #    Disabled by default — enable once libs are deemed API-stable and
+  #    CARGO_REGISTRY_TOKEN is set in repo secrets.
+  # ─────────────────────────────────────────────────────────────
+  publish-crates:
+    name: cargo publish
+    needs: build-binaries
+    runs-on: ubuntu-24.04
+    if: false  # flip to: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.create-release.outputs.tag }}
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Publish in dep order
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+        run: |
+          set -e
+          for crate in mailify-core mailify-config mailify-templates mailify-smtp mailify-auth mailify-queue mailify-api; do
+            echo "::group::publish $crate"
+            cargo publish -p "$crate" --no-verify
+            # Wait for crates.io index propagation before next dependent publish
+            sleep 30
+            echo "::endgroup::"
+          done
+
+  # ─────────────────────────────────────────────────────────────
+  # 4. Finalize: flip draft → published
+  # ─────────────────────────────────────────────────────────────
+  finalize:
+    name: publish release
+    needs: [create-release, build-binaries]
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.create-release.outputs.tag }}
+      - name: Flip draft to published
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh release edit "${{ needs.create-release.outputs.tag }}" --draft=false
diff --git a/Cargo.lock b/Cargo.lock
index 83d7db5..ec283c4 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1331,7 +1331,7 @@ checksum = "112b39cec0b298b6c1999fee3e31427f74f676e4cb9879ed1a121b43661a4154"
 
 [[package]]
 name = "mailify-api"
-version = "0.1.0"
+version = "0.1.2"
 dependencies = [
  "anyhow",
  "axum",
@@ -1363,7 +1363,7 @@ dependencies = [
 
 [[package]]
 name = "mailify-auth"
-version = "0.1.0"
+version = "0.1.2"
 dependencies = [
  "argon2",
  "async-trait",
@@ -1382,7 +1382,7 @@ dependencies = [
 
 [[package]]
 name = "mailify-config"
-version = "0.1.0"
+version = "0.1.2"
 dependencies = [
  "dotenvy",
  "figment",
@@ -1396,7 +1396,7 @@ dependencies = [
 
 [[package]]
 name = "mailify-core"
-version = "0.1.0"
+version = "0.1.2"
 dependencies = [
  "chrono",
  "serde",
@@ -1409,7 +1409,7 @@ dependencies = [
 
 [[package]]
 name = "mailify-queue"
-version = "0.1.0"
+version = "0.1.2"
 dependencies = [
  "apalis",
  "apalis-sql",
@@ -1434,7 +1434,7 @@ dependencies = [
 
 [[package]]
 name = "mailify-smtp"
-version = "0.1.0"
+version = "0.1.2"
 dependencies = [
  "async-trait",
  "base64",
@@ -1452,7 +1452,7 @@ dependencies = [
 
 [[package]]
 name = "mailify-templates"
-version = "0.1.0"
+version = "0.1.2"
 dependencies = [
  "mailify-config",
  "mailify-core",
diff --git a/Cargo.toml b/Cargo.toml
index ffc1908..7a58bad 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -11,7 +11,7 @@ members = [
 ]
 
 [workspace.package]
-version = "0.1.0"
+version = "0.1.2"
 edition = "2021"
 rust-version = "1.88"
 authors = ["Doni Lite"]
diff --git a/DESIGN.md b/DESIGN.md
new file mode 100644
index 0000000..858cd5a
--- /dev/null
+++ b/DESIGN.md
@@ -0,0 +1,364 @@
+# Mailify — Design System
+
+> Single source of truth for brand, visual tokens, typography, and UI patterns used across the site, the docs, the email templates, and any future UI surface (admin dashboard, CLI output styling, OG images).
+
+---
+
+## 1. Brand essence
+
+### 1.1 Name & etymology
+**Mailify** = *mail* + *-ify* (the suffix "to make into"). The product takes plain mail and *makes it yours* — branded, themed, shaped to your visual identity. The name is a promise: give us a theme, we give you back mail that looks like you.
+
+### 1.2 Positioning statement
+> *Mailify is the self-hosted transactional email server that wears your brand. One Docker image, your colors, your templates, zero vendor lock-in.*
+
+### 1.3 Tone of voice
+- **Direct, technical, confident** — we talk to developers, no marketing fluff.
+- **Pragmatic over poetic** — "send branded mail in 5 minutes" > "elevate your communication".
+- **Self-deprecating OK** — "yes, it's just a wrapper around lettre + axum, but it's a well-dressed one".
+- **FR/EN switch** — the site is EN-first for reach. Internal docs + CLAUDE.md + commit messages stay FR when natural.
+
+### 1.4 What we are NOT
+- Not a SaaS. No pricing page with tiers. No "enterprise" upsell.
+- Not a full marketing suite. No campaigns, no segmentation, no drag-and-drop editor.
+- Not trying to replace Postmark / Resend for everyone — trying to be the right tool for devs who want to **own** their mail stack.
+
+---
+
+## 2. Color tokens
+
+All tokens exposed as CSS custom properties on `:root`. Dark mode flips via `[data-theme="dark"]`.
+
+### 2.1 Brand scale
+
+| Token | Light | Dark | Contrast target |
+|-------|-------|------|-----------------|
+| `--brand-primary` | `#2D5BFF` | `#5B82FF` | WCAG AA on paper + ink |
+| `--brand-primary-hover` | `#1E43D9` | `#7A9CFF` | — |
+| `--brand-primary-muted` | `#E7EDFF` | `#1A2449` | bg for subtle highlights |
+| `--brand-accent` | `#FF8A3D` | `#FFA466` | highlights, never body text |
+| `--brand-accent-muted` | `#FFF0E5` | `#3D2414` | bg for callouts |
+
+### 2.2 Neutral scale (ink → paper)
+
+| Token | Light | Dark |
+|-------|-------|------|
+| `--ink-900` | `#0B1020` | `#F8FAFC` |
+| `--ink-700` | `#1F2937` | `#E2E8F0` |
+| `--ink-500` | `#475569` | `#94A3B8` |
+| `--ink-300` | `#94A3B8` | `#475569` |
+| `--ink-100` | `#E2E8F0` | `#1F2937` |
+| `--paper` | `#F8FAFC` | `#0B1020` |
+| `--paper-raised` | `#FFFFFF` | `#111832` |
+| `--border` | `#E2E8F0` | `#1F2937` |
+
+### 2.3 Semantic tokens (role, not color)
+
+| Token | Maps to |
+|-------|---------|
+| `--text` | `--ink-900` |
+| `--text-muted` | `--ink-500` |
+| `--link` | `--brand-primary` |
+| `--bg` | `--paper` |
+| `--bg-raised` | `--paper-raised` |
+| `--success` | `#10B981` |
+| `--warning` | `#F59E0B` |
+| `--danger` | `#EF4444` |
+| `--info` | `--brand-primary` |
+
+**Rule:** components always reference *semantic* tokens, never brand/neutral tokens directly. Easier to re-theme.
+
+### 2.4 Email-template palette
+The mail templates have their own theme object (`cfg.theme.colors`) injected at render time. The **default** theme ships with these same brand values, so out-of-the-box a Mailify install sends mails in Mailify's own brand. Users override per install.
+
+---
+
+## 3. Typography
+
+### 3.1 Typefaces
+
+| Role | Family | Weights | Fallback |
+|------|--------|---------|----------|
+| Display | **Geist Sans** | 500, 600, 700 | Inter, -apple-system, system-ui |
+| Body | **Inter** | 400, 500 | -apple-system, Segoe UI, Roboto |
+| Mono | **Geist Mono** | 400, 500 | JetBrains Mono, Menlo, Consolas, monospace |
+
+Self-host via `@fontsource/*` packages (no Google Fonts request → better SEO + privacy + Lighthouse).
+
+### 3.2 Scale (modular, ratio 1.250 "major third")
+
+| Token | Size | Line-height | Use |
+|-------|------|-------------|-----|
+| `--fs-xs` | 0.75rem / 12px | 1.5 | captions, labels |
+| `--fs-sm` | 0.875rem / 14px | 1.5 | body small, UI controls |
+| `--fs-base` | 1rem / 16px | 1.65 | body default |
+| `--fs-md` | 1.125rem / 18px | 1.6 | lede paragraphs |
+| `--fs-lg` | 1.5rem / 24px | 1.3 | h3, section intros |
+| `--fs-xl` | 1.875rem / 30px | 1.25 | h2 |
+| `--fs-2xl` | 2.5rem / 40px | 1.15 | h1 docs |
+| `--fs-3xl` | 3.5rem / 56px | 1.05 | hero landing |
+| `--fs-4xl` | 4.5rem / 72px | 1 | mega hero (desktop only) |
+
+### 3.3 Headings
+- `h1` hero landing: `--fs-3xl` Geist Sans 700, tracking `-0.03em`.
+- `h1` doc page: `--fs-2xl` Geist Sans 600, tracking `-0.02em`.
+- `h2`..`h4` docs: Geist Sans 600, tracking `-0.01em`.
+- Body: Inter 400, no tracking adjustment.
+- **Always semibold, never bold** for UI surfaces (Geist is already heavy at 600).
+
+### 3.4 Mono rules
+- Inline code: `--fs-[0.925em]` relative to parent + `--brand-primary-muted` background + 4px horizontal padding + 4px radius.
+- Code blocks: `--fs-sm`, full width, no inline background on tokens, `--paper-raised` bg, border `1px --border`, radius `--radius-md`.
+
+---
+
+## 4. Space & layout
+
+### 4.1 Spacing scale (4px base)
+
+| Token | Value |
+|-------|-------|
+| `--space-1` | 4px |
+| `--space-2` | 8px |
+| `--space-3` | 12px |
+| `--space-4` | 16px |
+| `--space-6` | 24px |
+| `--space-8` | 32px |
+| `--space-12` | 48px |
+| `--space-16` | 64px |
+| `--space-24` | 96px |
+| `--space-32` | 128px |
+
+### 4.2 Radii
+
+| Token | Value | Use |
+|-------|-------|-----|
+| `--radius-sm` | 4px | inline code, badges |
+| `--radius-md` | 8px | buttons, inputs, cards |
+| `--radius-lg` | 12px | larger cards, modals |
+| `--radius-full` | 9999px | pills, avatars |
+
+### 4.3 Elevation (shadows)
+
+| Token | Value |
+|-------|-------|
+| `--shadow-sm` | `0 1px 2px rgba(11,16,32,0.06)` |
+| `--shadow-md` | `0 4px 12px rgba(11,16,32,0.08)` |
+| `--shadow-lg` | `0 12px 32px rgba(11,16,32,0.12)` |
+
+Dark mode: reduce alpha by half and switch to `rgba(0,0,0,...)`.
+
+### 4.4 Container widths
+
+| Token | Value | Use |
+|-------|-------|-----|
+| `--container-prose` | 720px | doc article max-width |
+| `--container-main` | 1120px | landing sections |
+| `--container-wide` | 1280px | full-width marketing blocks |
+
+### 4.5 Breakpoints
+
+| Token | Value |
+|-------|-------|
+| `--bp-sm` | 640px |
+| `--bp-md` | 768px |
+| `--bp-lg` | 1024px |
+| `--bp-xl` | 1280px |
+
+Mobile-first everywhere.
+
+---
+
+## 5. Components — visual rules
+
+### 5.1 Button
+
+| Variant | Bg | Text | Border | Hover |
+|---------|-----|------|--------|-------|
+| primary | `--brand-primary` | white | none | `--brand-primary-hover` |
+| secondary | `--paper-raised` | `--text` | `1px --border` | `--ink-100` bg |
+| ghost | transparent | `--link` | none | `--brand-primary-muted` bg |
+| danger | `--danger` | white | none | darker red |
+
+- Padding: `--space-3 --space-6`.
+- Radius: `--radius-md`.
+- Font: Geist Sans 500, `--fs-sm`.
+- Focus ring: `2px solid --brand-primary` + `2px` offset.
+- No shadow by default on buttons — keep them flat.
+
+### 5.2 Code block
+- Header row (optional): filename left, language badge right, copy button far right.
+- Line numbers optional, off by default (on for install/config snippets > 5 lines).
+- Syntax theme: **Shiki** with dual-theme support — `github-light` / `github-dark`, matched to our `[data-theme]`.
+- Copy button on hover top-right, icon `clipboard` from Lucide.
+
+### 5.3 Callouts / admonitions (for docs)
+Four variants, all share left border 3px + tinted bg + icon:
+
+| Kind | Border | Bg | Icon |
+|------|--------|-----|------|
+| note | `--brand-primary` | `--brand-primary-muted` | info circle |
+| tip | `--success` | green-muted | lightbulb |
+| warning | `--warning` | amber-muted | triangle |
+| danger | `--danger` | red-muted | octagon |
+
+### 5.4 Cards (features on landing)
+- `--paper-raised` bg, `1px --border`, `--radius-lg`, padding `--space-6`.
+- No shadow at rest; `--shadow-md` on hover with `translateY(-2px)` transition 150ms ease-out.
+- Icon top-left, 32px, colored `--brand-primary`.
+- Title Geist Sans 600 `--fs-md`, body Inter 400 `--fs-sm` `--text-muted`.
+
+### 5.5 Navigation
+- Top bar 64px, sticky, `--paper` bg with blur `backdrop-filter: blur(12px)` and 80% alpha when scrolled.
+- Logo left (mark + wordmark), nav links center (Docs, GitHub, Sponsors), CTA right (primary button "Get started").
+- Sidebar docs: 280px wide, sticky, collapsible groups. Active item = left border 2px `--brand-primary` + `--brand-primary-muted` bg.
+
+### 5.6 Footer
+- 3 columns on desktop, stacks on mobile.
+- Columns: *Product* (Docs, Changelog, Roadmap), *Project* (GitHub, Sponsors, Discussions), *Community* (Twitter/X, RSS).
+- Bottom row: logo + copyright + "made in Rust" badge + theme toggle.
+
+---
+
+## 6. Iconography
+
+- **Lucide Icons** (open source, tree-shakeable, matches our geometric feel).
+- Stroke width: 1.75 default, 2 for small sizes.
+- Size tokens: `--icon-sm` 16px, `--icon-md` 20px, `--icon-lg` 24px, `--icon-xl` 32px.
+- Never fill icons — always stroke.
+- Use sparingly in body text; more generously in UI chrome.
+
+---
+
+## 7. Imagery & illustration
+
+### 7.1 Landing illustrations
+- Abstract, geometric, flat vector — same language as the logo.
+- Palette restricted to brand tokens; no external colors.
+- No stock photography, no 3D, no AI-gen "corporate glow".
+- One signature illustration on the hero; smaller spots on feature sections.
+
+### 7.2 OG / social cards
+- 1200×630, generated per page via Astro's `@vercel/og`-equivalent (`satori` + `astro-og-canvas` or similar).
+- Template: dark `--ink-900` bg, big wordmark top-left, page title center-left Geist 600 72px white, subtitle `--ink-300` 32px below, accent diagonal stripe `--brand-primary` bottom-right.
+- One shared template, dynamic title from page frontmatter.
+
+### 7.3 Architecture diagrams
+- **Excalidraw** hand-drawn style OR clean SVG with brand palette — pick one and stay consistent.
+- Export as SVG, never PNG, so they scale and theme-invert cleanly.
+
+---
+
+## 8. Motion
+
+- **Default transition:** `150ms ease-out` for color/opacity/transform.
+- **Page transitions:** none (SSG, hard reloads are fine).
+- **View transitions API** enabled via Astro for same-origin nav (smooth fade between docs pages).
+- **Scroll reveal:** subtle `opacity 0 → 1` + `translateY(12px → 0)` on landing feature cards, via `Intersection Observer`, once per element.
+- **Respect `prefers-reduced-motion`** — disable all non-essential motion.
+- **No auto-playing anything.** No carousels that move on their own.
+
+---
+
+## 9. Accessibility
+
+Non-negotiable baseline:
+
+- **WCAG 2.1 AA** contrast on all text (verified via Lighthouse CI).
+- **Keyboard nav** — every interactive element reachable via Tab, visible focus ring always.
+- **Skip-to-content** link on every page (first Tab stop).
+- **Semantic HTML** — `<nav>`, `<main>`, `<article>`, `<aside>`, heading hierarchy never skipped.
+- **Alt text** required on all images; decorative images get `alt=""`.
+- **Dark mode preference** respected via `prefers-color-scheme`, overridable via manual toggle stored in `localStorage`.
+- **Focus management** on route change (focus the `<h1>`).
+- **Form labels** always explicit, never placeholder-only.
+
+---
+
+## 10. Responsive behavior
+
+| Breakpoint | Layout adjustments |
+|-----------|--------------------|
+| `< 640px` | Single column everywhere. Nav collapses to hamburger. Hero type drops to `--fs-2xl`. Code blocks horizontal-scroll. |
+| `640–1023px` | 2-column feature grids. Sidebar docs goes to drawer. |
+| `≥ 1024px` | Full desktop: 3-column footer, sticky sidebar + TOC on docs, `--fs-3xl` or `--fs-4xl` hero. |
+
+Touch targets ≥ 44×44px on mobile. No hover-only interactions.
+
+---
+
+## 11. Applied examples
+
+### 11.1 Landing hero (structure)
+```
+[Top nav —————————————————————————————————— CTA]
+
+  Eyebrow badge: "v0.2 — now on crates.io"          (Geist 500 fs-xs, --brand-primary)
+
+  # The mail server that                            (h1, fs-3xl, --text)
+    wears your brand.
+  
+  Self-hosted, theme-aware transactional mail.      (fs-md, --text-muted, max 620px)
+  One Docker image. Your colors. Zero lock-in.
+  
+  [ Get started →  ]  [ docker pull donighost/mailify ]
+  (primary button)    (mono pill, --paper-raised bg, copy-on-click)
+
+  — illustration: envelope morphing into color swipe, right side, 1/3 width —
+```
+
+### 11.2 Docs page (structure)
+```
+[Top nav                                                          ]
+[Sidebar —————————— | Article prose max 720px | ————— TOC (sticky)]
+                    |                          |
+                    |  # Page title           |
+                    |  meta: last updated     |
+                    |                         |
+                    |  Body with code blocks, |
+                    |  callouts, links.       |
+                    |                         |
+                    |  "Edit this page"       |
+                    |  + prev/next links      |
+[Footer                                                           ]
+```
+
+---
+
+## 12. Asset inventory (to produce)
+
+- [ ] Logo mark SVG (light + dark) — prompt in `TODO.md §0.3`
+- [ ] Logo wordmark SVG
+- [ ] Logo lockup (mark + wordmark horizontal)
+- [ ] Favicon (SVG + 32×32 PNG fallback)
+- [ ] Apple touch icon 180×180
+- [ ] OG default 1200×630
+- [ ] Hero illustration (envelope → palette)
+- [ ] 3 feature-card spot illustrations
+- [ ] Architecture SVG (7 crates, data flow)
+- [ ] Screenshot: CLI output of `mailify config print`
+- [ ] Screenshot: an example branded email rendered
+
+---
+
+## 13. Design principles (decision heuristics)
+
+When in doubt, apply these in order:
+
+1. **Remove before you add.** Every element must justify its pixels.
+2. **One primary action per screen.** If there are two, one is secondary.
+3. **Semantic over aesthetic.** A component named `<Card>` is a card because of its role, not because of its shadow.
+4. **Brand expresses through restraint.** The orange accent is powerful *because* it's rare. Don't spray it.
+5. **Mobile is not a fallback.** Start there; desktop adds breathing room, not new content.
+6. **Performance is a design concern.** A 200KB JS bundle is a design failure, not a dev one.
+7. **Accessibility is not an extra pass.** It's the baseline; you don't ship without it.
+
+---
+
+## 14. Versioning this document
+
+- Bump `## N. …` section number only when adding new sections (never renumber).
+- Changes to tokens (colors, sizes) = note in `CHANGELOG.md` under `### Design`.
+- Major palette/typography changes = bump to a new major doc version in a `DESIGN-v2.md` and link back, so historical context is preserved.
+
+**Current version:** `v1` — 2026-04-23 — initial system.
diff --git a/crates/mailify-api/Cargo.toml b/crates/mailify-api/Cargo.toml
index 4f98cb8..1ed57b8 100644
--- a/crates/mailify-api/Cargo.toml
+++ b/crates/mailify-api/Cargo.toml
@@ -11,12 +11,12 @@ name = "mailify"
 path = "src/main.rs"
 
 [dependencies]
-mailify-core = { path = "../mailify-core" }
-mailify-config = { path = "../mailify-config" }
-mailify-templates = { path = "../mailify-templates" }
-mailify-smtp = { path = "../mailify-smtp" }
-mailify-queue = { path = "../mailify-queue" }
-mailify-auth = { path = "../mailify-auth" }
+mailify-core = { path = "../mailify-core", version = "0.1.2" }
+mailify-config = { path = "../mailify-config", version = "0.1.2" }
+mailify-templates = { path = "../mailify-templates", version = "0.1.2" }
+mailify-smtp = { path = "../mailify-smtp", version = "0.1.2" }
+mailify-queue = { path = "../mailify-queue", version = "0.1.2" }
+mailify-auth = { path = "../mailify-auth", version = "0.1.2" }
 
 axum = { workspace = true }
 tower = { workspace = true }
@@ -43,8 +43,8 @@ tower = { workspace = true }
 tokio-util = { workspace = true }
 reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }
 urlencoding = "2"
-mailify-auth = { path = "../mailify-auth" }
-mailify-queue = { path = "../mailify-queue" }
-mailify-smtp = { path = "../mailify-smtp" }
-mailify-templates = { path = "../mailify-templates" }
-mailify-core = { path = "../mailify-core" }
+mailify-auth = { path = "../mailify-auth", version = "0.1.2" }
+mailify-queue = { path = "../mailify-queue", version = "0.1.2" }
+mailify-smtp = { path = "../mailify-smtp", version = "0.1.2" }
+mailify-templates = { path = "../mailify-templates", version = "0.1.2" }
+mailify-core = { path = "../mailify-core", version = "0.1.2" }
diff --git a/crates/mailify-auth/Cargo.toml b/crates/mailify-auth/Cargo.toml
index 46eef1b..6f9a977 100644
--- a/crates/mailify-auth/Cargo.toml
+++ b/crates/mailify-auth/Cargo.toml
@@ -7,8 +7,8 @@ license.workspace = true
 repository.workspace = true
 
 [dependencies]
-mailify-core = { path = "../mailify-core" }
-mailify-config = { path = "../mailify-config" }
+mailify-core = { path = "../mailify-core", version = "0.1.2" }
+mailify-config = { path = "../mailify-config", version = "0.1.2" }
 serde = { workspace = true }
 jsonwebtoken = { workspace = true }
 argon2 = { workspace = true }
diff --git a/crates/mailify-config/Cargo.toml b/crates/mailify-config/Cargo.toml
index 94eb91d..758b2a3 100644
--- a/crates/mailify-config/Cargo.toml
+++ b/crates/mailify-config/Cargo.toml
@@ -7,7 +7,7 @@ license.workspace = true
 repository.workspace = true
 
 [dependencies]
-mailify-core = { path = "../mailify-core" }
+mailify-core = { path = "../mailify-core", version = "0.1.2" }
 serde = { workspace = true }
 serde_json = { workspace = true }
 toml = { workspace = true }
diff --git a/crates/mailify-config/src/lib.rs b/crates/mailify-config/src/lib.rs
index b5755cd..65f9f45 100644
--- a/crates/mailify-config/src/lib.rs
+++ b/crates/mailify-config/src/lib.rs
@@ -1,6 +1,10 @@
 //! Central configuration loader.
 //!
-//! Precedence (lowest → highest): defaults → optional TOML file (`MAILIFY_CONFIG` env) → env vars (`MAILIFY_*`).
+//! Precedence (lowest → highest): defaults → auto-discovered TOML file → env vars (`MAILIFY_*`).
+//!
+//! TOML discovery (first match wins): `$MAILIFY_CONFIG` → `./Mailify.toml` →
+//! `$XDG_CONFIG_HOME/mailify/config.toml` (fallback `$HOME/.config/mailify/config.toml` on Unix,
+//! `%APPDATA%\mailify\config.toml` on Windows) → `/etc/mailify/config.toml` (Unix).
 
 pub mod theme;
 
@@ -179,7 +183,14 @@ impl Default for AppConfig {
 }
 
 impl AppConfig {
-    /// Load config: dotenv → defaults → optional TOML → env vars prefixed `MAILIFY_` (nested via `__`).
+    /// Load config: dotenv → defaults → auto-discovered TOML → env vars prefixed `MAILIFY_` (nested via `__`).
+    ///
+    /// TOML discovery order (first found wins):
+    ///   1. `MAILIFY_CONFIG` env var (explicit file path)
+    ///   2. `./Mailify.toml` in current working directory
+    ///   3. `$XDG_CONFIG_HOME/mailify/config.toml` (or `$HOME/.config/mailify/config.toml` on Unix,
+    ///      `%APPDATA%\mailify\config.toml` on Windows)
+    ///   4. `/etc/mailify/config.toml` (Unix system-wide, last resort)
     ///
     /// Dotenv loading order (first found wins, does not override already-set vars):
     ///   1. `MAILIFY_DOTENV_PATH` (explicit file)
@@ -188,13 +199,13 @@ impl AppConfig {
     ///   4. `.env.local`
     ///   5. `.env`
     ///
-    /// Disable by setting `MAILIFY_DOTENV=false`.
+    /// Disable dotenv by setting `MAILIFY_DOTENV=false`.
     pub fn load() -> Result<Self> {
         load_dotenv();
 
         let mut fig = Figment::from(Serialized::defaults(AppConfig::default()));
 
-        if let Ok(path) = std::env::var("MAILIFY_CONFIG") {
+        if let Some(path) = discover_config_file() {
             fig = fig.merge(Toml::file(path));
         }
 
@@ -205,6 +216,65 @@ impl AppConfig {
     }
 }
 
+/// Resolve the TOML config file to load. Returns `None` when no candidate exists.
+///
+/// Searches in this order, returning the first existing path:
+///   1. `$MAILIFY_CONFIG`
+///   2. `./Mailify.toml`
+///   3. Per-user config dir: `$XDG_CONFIG_HOME/mailify/config.toml`, else
+///      `$HOME/.config/mailify/config.toml` on Unix, `%APPDATA%\mailify\config.toml` on Windows
+///   4. `/etc/mailify/config.toml` on Unix
+fn discover_config_file() -> Option<PathBuf> {
+    config_candidates().into_iter().find(|c| c.is_file())
+}
+
+fn config_candidates() -> Vec<PathBuf> {
+    let mut out = Vec::new();
+
+    if let Ok(explicit) = std::env::var("MAILIFY_CONFIG") {
+        out.push(PathBuf::from(explicit));
+    }
+
+    out.push(PathBuf::from("Mailify.toml"));
+
+    if let Some(user_dir) = user_config_dir() {
+        out.push(user_dir.join("mailify").join("config.toml"));
+    }
+
+    #[cfg(unix)]
+    out.push(PathBuf::from("/etc/mailify/config.toml"));
+
+    out
+}
+
+fn user_config_dir() -> Option<PathBuf> {
+    if let Ok(xdg) = std::env::var("XDG_CONFIG_HOME") {
+        if !xdg.is_empty() {
+            return Some(PathBuf::from(xdg));
+        }
+    }
+
+    #[cfg(unix)]
+    {
+        if let Ok(home) = std::env::var("HOME") {
+            if !home.is_empty() {
+                return Some(PathBuf::from(home).join(".config"));
+            }
+        }
+    }
+
+    #[cfg(windows)]
+    {
+        if let Ok(appdata) = std::env::var("APPDATA") {
+            if !appdata.is_empty() {
+                return Some(PathBuf::from(appdata));
+            }
+        }
+    }
+
+    None
+}
+
 fn load_dotenv() {
     if std::env::var("MAILIFY_DOTENV")
         .map(|v| v.eq_ignore_ascii_case("false") || v == "0")
@@ -272,3 +342,41 @@ fn load_dotenv_from_file(path: &str) -> std::result::Result<(), String> {
     }
     Ok(())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn candidates_include_cwd_and_explicit() {
+        // SAFETY: test-only env mutation; other discovery tests are skipped to avoid races.
+        let prev = std::env::var("MAILIFY_CONFIG").ok();
+        unsafe {
+            std::env::set_var("MAILIFY_CONFIG", "/custom/path.toml");
+        }
+        let c = config_candidates();
+        assert_eq!(
+            c.first().map(PathBuf::as_path),
+            Some(std::path::Path::new("/custom/path.toml"))
+        );
+        assert!(c.iter().any(|p| p == std::path::Path::new("Mailify.toml")));
+
+        match prev {
+            Some(v) => unsafe { std::env::set_var("MAILIFY_CONFIG", v) },
+            None => unsafe { std::env::remove_var("MAILIFY_CONFIG") },
+        }
+    }
+
+    #[test]
+    fn user_config_dir_prefers_xdg() {
+        let prev = std::env::var("XDG_CONFIG_HOME").ok();
+        unsafe {
+            std::env::set_var("XDG_CONFIG_HOME", "/xdg/override");
+        }
+        assert_eq!(user_config_dir(), Some(PathBuf::from("/xdg/override")));
+        match prev {
+            Some(v) => unsafe { std::env::set_var("XDG_CONFIG_HOME", v) },
+            None => unsafe { std::env::remove_var("XDG_CONFIG_HOME") },
+        }
+    }
+}
diff --git a/crates/mailify-queue/Cargo.toml b/crates/mailify-queue/Cargo.toml
index 29b0420..6bd5e3b 100644
--- a/crates/mailify-queue/Cargo.toml
+++ b/crates/mailify-queue/Cargo.toml
@@ -7,10 +7,10 @@ license.workspace = true
 repository.workspace = true
 
 [dependencies]
-mailify-core = { path = "../mailify-core" }
-mailify-config = { path = "../mailify-config" }
-mailify-smtp = { path = "../mailify-smtp" }
-mailify-templates = { path = "../mailify-templates" }
+mailify-core = { path = "../mailify-core", version = "0.1.2" }
+mailify-config = { path = "../mailify-config", version = "0.1.2" }
+mailify-smtp = { path = "../mailify-smtp", version = "0.1.2" }
+mailify-templates = { path = "../mailify-templates", version = "0.1.2" }
 apalis = { workspace = true }
 apalis-sql = { workspace = true }
 sqlx = { workspace = true }
diff --git a/crates/mailify-smtp/Cargo.toml b/crates/mailify-smtp/Cargo.toml
index 66d0789..c3a4cd9 100644
--- a/crates/mailify-smtp/Cargo.toml
+++ b/crates/mailify-smtp/Cargo.toml
@@ -7,8 +7,8 @@ license.workspace = true
 repository.workspace = true
 
 [dependencies]
-mailify-core = { path = "../mailify-core" }
-mailify-config = { path = "../mailify-config" }
+mailify-core = { path = "../mailify-core", version = "0.1.2" }
+mailify-config = { path = "../mailify-config", version = "0.1.2" }
 lettre = { workspace = true }
 thiserror = { workspace = true }
 tracing = { workspace = true }
@@ -22,4 +22,4 @@ reqwest = { version = "0.12", default-features = false, features = ["json", "rus
 serde_json = { workspace = true }
 uuid = { workspace = true }
 urlencoding = "2"
-mailify-config = { path = "../mailify-config" }
+mailify-config = { path = "../mailify-config", version = "0.1.2" }
diff --git a/crates/mailify-templates/Cargo.toml b/crates/mailify-templates/Cargo.toml
index a3cbbe6..19bff49 100644
--- a/crates/mailify-templates/Cargo.toml
+++ b/crates/mailify-templates/Cargo.toml
@@ -7,8 +7,8 @@ license.workspace = true
 repository.workspace = true
 
 [dependencies]
-mailify-core = { path = "../mailify-core" }
-mailify-config = { path = "../mailify-config" }
+mailify-core = { path = "../mailify-core", version = "0.1.2" }
+mailify-config = { path = "../mailify-config", version = "0.1.2" }
 serde = { workspace = true }
 serde_json = { workspace = true }
 minijinja = { workspace = true }
diff --git a/docker/Dockerfile b/docker/Dockerfile
index cb53d4c..841d521 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -9,17 +9,33 @@ RUN bun install --frozen-lockfile
 COPY templates-parser/ ./
 RUN bun run build
 
-# ─────────────────────────── 2. Rust builder ───────────────────────────
-FROM rust:1.88-slim AS rs-builder
+# ─────────────────────────── 2a. Rust chef base ───────────────────────────
+FROM rust:1.88-slim AS chef
 RUN apt-get update && apt-get install -y --no-install-recommends \
     pkg-config libssl-dev ca-certificates curl unzip build-essential && rm -rf /var/lib/apt/lists/*
-
+RUN --mount=type=cache,target=/usr/local/cargo/registry \
+    cargo install cargo-chef --locked --version ^0.1
 WORKDIR /w
 
-# Dependency-cache trick: copy manifests first, build stub crates so deps get cached.
+# ─────────────────────────── 2b. Planner: compute dep recipe ───────────────────────────
+FROM chef AS planner
 COPY Cargo.toml Cargo.lock* ./
 COPY crates/ ./crates/
+RUN cargo chef prepare --recipe-path recipe.json
 
+# ─────────────────────────── 2c. Cacher: build deps only (stable layer) ───────────────────────────
+FROM chef AS cacher
+COPY --from=planner /w/recipe.json recipe.json
+RUN --mount=type=cache,target=/usr/local/cargo/registry \
+    --mount=type=cache,target=/w/target \
+    cargo chef cook --release --recipe-path recipe.json
+
+# ─────────────────────────── 2d. Builder: compile the workspace binary ───────────────────────────
+FROM chef AS rs-builder
+COPY --from=cacher /w/target /w/target
+COPY --from=cacher /usr/local/cargo /usr/local/cargo
+COPY Cargo.toml Cargo.lock* ./
+COPY crates/ ./crates/
 RUN --mount=type=cache,target=/usr/local/cargo/registry \
     --mount=type=cache,target=/w/target \
     cargo build --release --bin mailify && \
diff --git a/docs/contributing/architecture.md b/docs/contributing/architecture.md
new file mode 100644
index 0000000..491d6ac
--- /dev/null
+++ b/docs/contributing/architecture.md
@@ -0,0 +1,164 @@
+---
+title: Architecture
+description: Workspace layout, crate responsibilities, and the request-to-send flow.
+sidebar:
+  order: 1
+---
+
+# Architecture
+
+Mailify is a Cargo workspace (`resolver = "2"`) with seven crates, layered so that only `mailify-api` is binary-shaped. Every other crate is a reusable lib.
+
+## Crate map
+
+```
+mailify-core       → domain types (EmailMessage, Priority, SmtpOverride, CoreError)
+mailify-config     → figment loader + Theme (TOML + dotenv + env)
+mailify-templates  → TemplateRegistry (loads compiled HTML dir) + minijinja renderer
+mailify-smtp       → lettre wrapper, accepts per-job SmtpOverride
+mailify-queue      → apalis + apalis-sql/postgres MailJob storage + worker runtime
+mailify-auth       → argon2 API-key verify + JWT issuer + axum require_jwt middleware
+mailify-api        → axum router, OpenAPI (utoipa), Swagger UI, binary `mailify`
+```
+
+### `mailify-core`
+
+Pure domain types. No I/O, no async runtime dependencies beyond `tokio` re-exports. Every other crate depends on it.
+
+Key exports:
+
+- `EmailMessage`, `EmailAddress`, `Attachment` — value types for mail content.
+- `Priority` — the enum used for queue weighting.
+- `SmtpOverride`, `TlsMode` — per-job SMTP credentials. The `Debug` impl redacts secrets.
+- `CoreError` — the error enum all other crates lift via `From`.
+
+### `mailify-config`
+
+Responsible for turning environment + TOML + defaults into a single `AppConfig` struct at boot.
+
+Built on [figment](https://github.com/SergioBenitez/figment) for precedence-aware layering. The only public entry point is `AppConfig::load()`. Everything else — `Theme`, `ServerConfig`, etc. — is exposed so `AppConfig` can be cloned into `AppState` downstream.
+
+### `mailify-templates`
+
+Owns the `TemplateRegistry` (file-system scan at boot) and the `TemplateRenderer` (minijinja, with `theme` + `vars` + `locale` context injection).
+
+Critically: **does not parse React Email**. Templates are expected to be pre-rendered HTML. See [Template contract](../reference/template-contract.md) for the layout.
+
+### `mailify-smtp`
+
+A thin wrapper around [lettre](https://github.com/lettre/lettre). Two entry points:
+
+- `SmtpSender::default_from_config(&SmtpConfig)` — the process-wide default sender.
+- `SmtpSender::from_override(&SmtpOverride)` — a one-off sender for a single job.
+
+The distinction matters for multi-tenant flows — see [Per-job SMTP override](../guides/per-job-smtp-override.md).
+
+### `mailify-queue`
+
+Wraps [apalis](https://github.com/geofmureithi/apalis) with `PostgresStorage<MailJob>`. Exposes:
+
+- `QueueHandle` — the producer side, used by HTTP handlers to enqueue jobs.
+- `QueueRuntime` — the consumer side, spawned in `main.rs`; runs the worker loop with configurable concurrency and retries.
+
+Also owns the PostgreSQL connection + migrations. Running `QueueRuntime::init()` runs the apalis migrations automatically.
+
+### `mailify-auth`
+
+Argon2 + JWT. Public surface:
+
+- `hash_api_key(plaintext) -> ArgonHash` — used by the `hash-key` Cargo example.
+- `verify_api_key(plaintext, &hash) -> bool` — called by the `/auth/token` handler.
+- `issue_jwt(sub, scopes, ttl, secret, issuer) -> String` — mints tokens.
+- `require_jwt` — the axum middleware applied via `.route_layer(...)` in `mailify-api`.
+
+Plus the `bootstrap` module (ephemeral key generation at boot when no keys are configured).
+
+### `mailify-api`
+
+The only binary. Owns:
+
+- The axum router (protected vs. public split).
+- `AppState` — the `Arc`-shared state cloned into handlers.
+- OpenAPI spec via `utoipa` + Swagger UI at `/swagger-ui`.
+- `main.rs` — boot sequence, tracing init, DB ping, template load, bootstrap auth, spawn queue worker, start HTTP server.
+
+## Request → send flow
+
+Step by step, what happens when a client hits `/mail/send`:
+
+1. **Auth.** Client calls `POST /auth/token` with their plaintext API key. `argon2::verify_password` compares against hashes in `cfg.auth.api_keys`. On success, returns a short-lived JWT.
+2. **Protected request.** Client calls `POST /mail/send` with `Authorization: Bearer <jwt>`. The `require_jwt` axum middleware verifies the signature and claims. On success, the handler runs.
+3. **Template lookup.** For `/mail/send`, the handler looks up `template_id` in `TemplateRegistry` to ensure it exists. `/mail/send-custom` skips this — the raw HTML comes in the request.
+4. **Job construction.** Handler builds a `MailJob { id, priority, kind, from, to, locale, vars, smtp_override, ... }`.
+5. **Enqueue.** `QueueHandle::push(&job)` inserts into `apalis.jobs` via `PostgresStorage`. apalis assigns its own ULID (`TaskId`), which is what Mailify returns to the caller as `job_id` — **not** the `MailJob.id` UUID.
+6. **Worker pickup.** The apalis worker loop polls `apalis.jobs`, locks the next runnable row, and hands it to the worker fn.
+7. **Render.** The worker fn builds a `RenderContext { theme, vars, locale }` and calls `TemplateRenderer::render(&job)`. For `Custom` kind, the HTML is passed through as-is.
+8. **Dispatch.** If `job.smtp_override` is `Some`, build a one-off `SmtpSender`; otherwise use the process-wide `default_sender` from `AppState`. Send via lettre.
+9. **Persist outcome.** apalis marks the job `Done` or increments `attempts` + stores `last_error` and moves back to `Pending` / `Failed` depending on retry count.
+
+## Config precedence
+
+Implemented in `AppConfig::load()`:
+
+```
+defaults → auto-discovered TOML → env vars (MAILIFY_*)
+```
+
+TOML discovery order (first match wins):
+
+1. `$MAILIFY_CONFIG` (explicit path)
+2. `./Mailify.toml`
+3. `$XDG_CONFIG_HOME/mailify/config.toml` (or fallback `~/.config/mailify/config.toml` / `%APPDATA%\mailify\config.toml`)
+4. `/etc/mailify/config.toml`
+
+See the [config reference](../reference/config.md) for the full set of keys.
+
+## Data flow diagram (text)
+
+```
+           ┌──────────┐   api_key
+   Client ─┤  Backend ├──────────────► POST /auth/token
+           └────┬─────┘                       │
+                │ JWT                         ▼
+                │                     argon2::verify
+                │                          │
+                ├───► POST /mail/send ◄─────┘ (bearer JWT)
+                │        │
+                │        ▼
+                │   require_jwt
+                │        │
+                │        ▼
+                │   TemplateRegistry (lookup)
+                │        │
+                │        ▼
+                │   MailJob enqueue
+                │        │
+                │        ▼                                   ┌──────────────────┐
+                │   apalis.jobs (Postgres) ───► worker ──┬──►│ default_sender   │
+                │                                       │   │  (lettre + SMTP) │
+                │                                       │   └──────────────────┘
+                │                                       │   ┌──────────────────┐
+                │                                       └──►│ SmtpSender       │
+                │                                           │  (from override) │
+                │                                           └──────────────────┘
+                ▼
+          GET /mail/jobs/:id  ◄──── apalis_sql::fetch_by_id ───── apalis.jobs
+```
+
+## Dockerfile shape
+
+Three-stage build:
+
+1. **tpl-builder** (`oven/bun:1.3-alpine`) — compiles `.tsx` → HTML bundle.
+2. **rs-builder** (`rust:1.88-slim` + `cargo-chef`) — dep layer first (stable), sources layer second (changes often). Produces `./target/release/mailify`.
+3. **runtime** (`gcr.io/distroless/cc-debian12:nonroot`) — copies the binary + the template bundle + sets env defaults. No shell, no package manager, no root user.
+
+Final image is ~20 MB and runs as uid `nonroot`.
+
+## Testing philosophy
+
+- **Unit tests live next to the code.** `#[cfg(test)] mod tests` inside each module.
+- **Integration tests** under `crates/mailify-api/tests/` spin up the full axum app, a real queue (via `testcontainers` — declared, adoption in progress), and Mailpit as an SMTP sink.
+- **CI runs the same `make ci` target** a contributor runs locally: fmt-check + clippy (`-D warnings`) + tests.
+
+No mocking of the database. We'd rather rely on a throwaway Postgres in CI than accept the drift between mocked and real behavior.
diff --git a/docs/contributing/dev-setup.md b/docs/contributing/dev-setup.md
new file mode 100644
index 0000000..f70df51
--- /dev/null
+++ b/docs/contributing/dev-setup.md
@@ -0,0 +1,139 @@
+---
+title: Dev setup
+description: Local toolchain, make targets, and running the full Mailify stack for development.
+sidebar:
+  order: 2
+---
+
+# Dev setup
+
+## Prerequisites
+
+- **Rust** ≥ 1.88 (pinned in `rust-toolchain.toml`)
+- **Bun** ≥ 1.3 (for React Email templates)
+- **Docker** + **Docker Compose** (for Postgres + Mailpit)
+- **make** (the Makefile is the canonical entry point)
+
+Optional:
+
+- `swaks` for SMTP smoke testing.
+- `jq` for piping JSON responses.
+- `psql` for poking the apalis job table.
+
+## First clone
+
+```bash
+git clone https://github.com/donilite/mailify.git
+cd mailify
+
+# Install JS deps for the templates workspace
+make setup
+
+# Bring up Postgres + Mailpit
+make up-deps
+
+# Compile templates once
+make build-templates
+
+# Run the server
+make dev
+```
+
+Visit <http://localhost:8080/swagger-ui> for the API explorer. Mailpit UI at <http://localhost:8025>.
+
+## Daily workflow
+
+| Task | Command |
+|------|---------|
+| Start deps | `make up-deps` |
+| Run server with hot restart | `make dev` (Ctrl+C and re-run on edits) |
+| Preview templates | `make dev-templates` |
+| Rebuild templates after `.tsx` edit | `make build-templates` |
+| Run all tests | `make test` |
+| Run a single test | `cargo test -p <crate> <test_name>` |
+| Format | `make fmt` |
+| Lint (CI-strict) | `make clippy` |
+| Full CI check | `make ci` |
+
+## Running integration tests
+
+Integration tests under `crates/mailify-api/tests/` require Postgres + Mailpit.
+
+```bash
+# In one terminal, bring up deps:
+make up-deps
+
+# In another:
+cargo test -p mailify-api --test it_e2e
+```
+
+Environment variables the tests expect:
+
+```bash
+MAILIFY_DATABASE__URL=postgres://mailify:mailify@localhost:5432/mailify
+MAILIFY_SMTP__HOST=localhost
+MAILIFY_SMTP__PORT=1025
+MAILIFY_SMTP__TLS=none
+MAILPIT_API_URL=http://localhost:8025
+MAILIFY_DOTENV=false
+```
+
+These are set automatically by the CI workflow — see [.github/workflows/ci.yml](https://github.com/donilite/mailify/blob/master/.github/workflows/ci.yml).
+
+## Editor setup
+
+### VSCode
+
+Recommended extensions:
+
+- `rust-analyzer` (Rust)
+- `Even Better TOML` (config files — once we publish a JSON schema, this will autocomplete `Mailify.toml`)
+- `Prettier` or `Biome` (templates-parser/)
+
+`.vscode/settings.json` suggestions:
+
+```json
+{
+  "rust-analyzer.cargo.allTargets": true,
+  "rust-analyzer.check.command": "clippy",
+  "rust-analyzer.check.extraArgs": ["--", "-D", "warnings"],
+  "[rust]": {
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "rust-lang.rust-analyzer"
+  }
+}
+```
+
+### Neovim / Zed / Helix
+
+Configure LSP to target rust-analyzer with the same `--all-targets` + `clippy` args. Format-on-save is enforced by CI (`make fmt-check`), so wire it up in your editor to save headaches.
+
+## Commit style
+
+[Conventional Commits](https://www.conventionalcommits.org/) — prefixes like `feat:`, `fix:`, `chore:`, `refactor:`, `test:`, `docs:`. These drive the auto-generated changelog on release.
+
+Good examples from history:
+
+```
+feat: enhance CI/CD pipeline with multi-platform Docker builds and configuration file discovery
+test: update expected status from "queued" to "pending" in mailpit delivery test
+chore: update package versions to 0.1.2 in Cargo.lock and Cargo.toml
+fix: propagate MAILIFY_AUTH__JWT_SECRET through AppState for require_jwt middleware
+```
+
+## Before opening a PR
+
+Run:
+
+```bash
+make ci
+```
+
+That runs fmt-check + clippy (`-D warnings`) + tests. If `make ci` is green, CI will be green too.
+
+Small things to remember:
+
+- **New public API?** Doc-comment it, and if it affects a user-facing endpoint, update `docs/reference/http-api.md`.
+- **New config key?** Add it to `docs/reference/config.md` with its TOML path, env var, type, default, and purpose.
+- **New error?** Consider adding it to `docs/troubleshooting/common-errors.md` with a diagnosis + fix.
+- **Breaking change?** Call it out in the PR description. It'll show up in the release notes.
diff --git a/docs/contributing/overview.md b/docs/contributing/overview.md
new file mode 100644
index 0000000..55eaa76
--- /dev/null
+++ b/docs/contributing/overview.md
@@ -0,0 +1,67 @@
+---
+title: Contributing
+description: Mailify's philosophy, where it's going, and the three kinds of help it needs.
+sidebar:
+  order: 0
+---
+
+# Contributing to Mailify
+
+Mailify is a solo-built, MIT-licensed project with a clear scope: **give dev teams a self-hosted, theme-aware transactional mail server that takes 5 minutes to deploy and 0 minutes to re-brand.** Every feature added should make that sentence more true.
+
+If you're reading this, you're considering contributing — thank you. This page is the orientation; the rest of this section has the operational details.
+
+## Three kinds of help
+
+### 1. Code (most valuable)
+
+- **Bug fixes.** Real reports tied to real reproductions beat architectural musings every time. Check the [common errors](../troubleshooting/common-errors.md) page — if it's not there and you can reproduce it, we want to know.
+- **Feature implementations** that already have a tracked issue or appear in [`TODO.md`](https://github.com/donilite/mailify/blob/master/TODO.md). Drive-by PRs that introduce new scope without prior discussion will be closed with a request to open an issue first.
+- **Documentation fixes.** These docs live in `docs/` and are rendered by the website. Typos, outdated commands, missing provider recipes — all welcome as drive-by PRs.
+- **Test coverage.** Integration tests for `/mail/send*` edge cases, retries, multi-tenant `smtp_override` scenarios, locale fallbacks. See [dev-setup](./dev-setup.md) for how to run them.
+
+### 2. Reach / promotion
+
+- Write a blog post about deploying Mailify for your use case.
+- Compare it against alternatives honestly — strengths *and* weaknesses.
+- Star the repo, share it where it fits.
+- File issues describing your use case even if you can't fix them — "here's what I tried, here's what broke" is signal.
+
+### 3. Financial
+
+Once Mailify has a GitHub Sponsors / OpenCollective presence, sponsorship tiers will be published there. For now, the best financial support is to deploy it at work and push for your employer to sponsor infrastructure-level OSS.
+
+## Philosophy (the non-negotiable parts)
+
+- **Self-hosted, always.** There will never be a managed "Mailify Cloud" tier maintained by the core project. The docker image is the distribution.
+- **Templates are code.** React Email + your IDE beat any WYSIWYG builder for long-term maintainability. This is not up for debate.
+- **Rust-fast, but pragmatic.** Clean crate boundaries, but no over-engineering. We'd rather ship a simple sync path that works than a beautiful actor-model abstraction that almost works.
+- **Env-var configurable end-to-end.** Every knob reachable via `MAILIFY_*`. No "config is code" patterns that require a rebuild.
+- **Durable by default.** Jobs in Postgres. No Redis side-channel for state. Losing a server restart does not lose mail.
+- **Secrets never on disk, never in logs.** SMTP credentials, argon2 plaintexts, JWT tokens.
+- **Multi-tenant first-class.** Per-job SMTP override is a feature, not a plugin.
+
+## Philosophy (open to debate)
+
+- Scope of the lib crates and whether to publish them to crates.io.
+- Whether to grow a `mailify` CLI with subcommands (`init`, `config check`, `config print`).
+- Observability story — Prometheus metrics, OTLP traces.
+- Rate limiting as a first-class feature vs. "your reverse proxy's problem".
+- Admin dashboard UI — currently out of scope but a reasonable experimental fork.
+
+File issues, argue in threads.
+
+## Where to start
+
+Easiest first PRs:
+
+1. Add an SMTP provider recipe to [Configure SMTP](../guides/configure-smtp.md).
+2. Add a common error you hit to [Common errors](../troubleshooting/common-errors.md).
+3. Improve an existing error message in the Rust code — match it to the troubleshooting page phrasing.
+4. Add integration tests for an untested code path (see `crates/mailify-api/tests/`).
+5. Pick any item tagged `good-first-issue` on GitHub.
+
+## Next steps
+
+- [Architecture →](./architecture.md)
+- [Dev setup →](./dev-setup.md)
diff --git a/docs/getting-started/concepts.md b/docs/getting-started/concepts.md
new file mode 100644
index 0000000..89f4b9b
--- /dev/null
+++ b/docs/getting-started/concepts.md
@@ -0,0 +1,106 @@
+---
+title: Concepts
+description: The vocabulary of Mailify — template, theme, job, queue, override, bootstrap.
+sidebar:
+  order: 3
+---
+
+# Concepts
+
+Reading the rest of these docs is easier once the core vocabulary is locked in. Each term below maps to a specific type or module in the codebase.
+
+## Template
+
+A **template** is a directory keyed by an `id` under `MAILIFY_TEMPLATES__PATH`. Inside:
+
+```
+<id>/
+  <locale>.html            # pre-rendered React Email HTML with minijinja spans
+  subject.<locale>.txt     # optional, minijinja-rendered at send
+  text.<locale>.txt        # optional plaintext alternative
+```
+
+Templates are loaded into an in-memory `TemplateRegistry` at boot. Editing a `.tsx` in `templates-parser/` requires re-running `make build-templates` before restart for changes to appear.
+
+See [Template contract](../reference/template-contract.md).
+
+## Theme
+
+The **theme** is a set of branding tokens (colors, fonts, radius, logo URL, footer text, social links, arbitrary extras) declared once in config and injected into *every* render via the minijinja `{{ theme.* }}` namespace.
+
+Re-branding your entire email output = change config, restart. No template edit needed.
+
+```toml
+[theme]
+brand_name = "Acme Corp"
+brand_logo_url = "https://cdn.acme.com/logo.png"
+footer_text = "© Acme. All rights reserved."
+
+[theme.colors]
+primary = "#FF4500"
+primary_foreground = "#ffffff"
+```
+
+See [Configure theme](../guides/configure-theme.md).
+
+## MailJob
+
+Every send becomes a **MailJob** — a struct pushed onto the durable Postgres queue. Key fields:
+
+- `id` — UUID for caller-side tracking.
+- `kind` — either `Registered { template_id }` (render from the registry) or `Custom { html, subject, text? }` (one-shot raw HTML).
+- `priority` — weighted scheduling. `Low` / `Normal` / `High` / `Critical`.
+- `smtp_override` — per-job SMTP credentials, memory-only, never logged. Enables multi-tenant fan-out.
+- `vars` — arbitrary JSON passed to the minijinja renderer.
+- `locale` — selects which `<id>/<locale>.html` to render.
+
+## Queue / worker
+
+Mailify uses [apalis](https://github.com/geofmureithi/apalis) with `PostgresStorage<MailJob>`. The queue table is `apalis.jobs`. On boot, `PostgresStorage::setup()` runs the apalis migrations automatically.
+
+The worker loop pulls jobs concurrently (`MAILIFY_QUEUE__WORKER_CONCURRENCY`, default 4), retries on failure up to `MAX_RETRIES` with `RETRY_BACKOFF_SECS`, and persists `last_error` on the job row so the `GET /mail/jobs/:id` endpoint can surface it.
+
+Jobs survive server restarts.
+
+## SMTP override
+
+By default every job goes through the **process-wide default SMTP sender** built from `MAILIFY_SMTP__*` config.
+
+When a job carries `smtp_override: { host, port, username?, password?, tls }`, the worker builds a one-off `SmtpSender` for that job. The credentials never hit disk, logs, or the queue table — they live in the in-flight `MailJob` and are wiped when the job finishes.
+
+Primary use case: a multi-tenant SaaS where each tenant brings their own SMTP provider.
+
+See [Per-job SMTP override](../guides/per-job-smtp-override.md).
+
+## Authentication
+
+Two layers:
+
+1. **API key** — long-lived secret, stored as an argon2 hash in `MAILIFY_AUTH__API_KEYS__<ID>`. Generated via `make hash-key` or auto-provisioned at boot in bootstrap mode.
+2. **JWT** — short-lived bearer token obtained by `POST /auth/token` with the API key. Used on all protected routes.
+
+The split lets you rotate JWTs without rotating API keys, and lets clients cache tokens instead of re-hashing on every request.
+
+See [Auth & tokens](../guides/auth-and-tokens.md).
+
+## Bootstrap mode
+
+`MAILIFY_AUTH__BOOTSTRAP=true` (default). If no API keys are configured at boot, Mailify:
+
+1. Generates a random key in memory.
+2. Hashes it with argon2 in memory.
+3. Logs the plaintext + the `MAILIFY_AUTH__API_KEYS__<ID>=<hash>` env line you should copy into a `.env` or config file for persistence.
+4. Accepts requests using that key for the lifetime of the process.
+
+This is the zero-friction first-boot path. Disable by setting `MAILIFY_AUTH__BOOTSTRAP=false` in production once you've persisted a real key.
+
+## Config precedence
+
+Lowest → highest:
+
+1. Compile-time defaults (see `AppConfig::default`).
+2. Auto-discovered TOML file (see [Config reference](../reference/config.md#discovery)).
+3. Dotenv chain (`.env.<MAILIFY_ENV>.local`, etc — does not override existing env vars).
+4. Process environment variables prefixed `MAILIFY_`, nested via `__`.
+
+So: `MAILIFY_SMTP__HOST=foo` beats `[smtp] host = "bar"` in `Mailify.toml`, which beats the compile-time default of `localhost`.
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
new file mode 100644
index 0000000..42012a1
--- /dev/null
+++ b/docs/getting-started/installation.md
@@ -0,0 +1,104 @@
+---
+title: Installation
+description: Install Mailify via Docker, the universal install script, cargo install, or a prebuilt binary.
+sidebar:
+  order: 1
+---
+
+# Installation
+
+Mailify ships four install paths. Pick the one that matches your target.
+
+## 1. Docker (recommended)
+
+The Docker image bundles the binary + compiled templates + distroless runtime (~20 MB, non-root).
+
+```bash
+docker run -d \
+  --name mailify \
+  -p 8080:8080 \
+  -e MAILIFY_DATABASE__URL=postgres://user:pass@host:5432/mailify \
+  -e MAILIFY_SMTP__HOST=smtp.example.com \
+  -e MAILIFY_SMTP__PORT=587 \
+  -e MAILIFY_SMTP__USERNAME=postmaster@example.com \
+  -e MAILIFY_SMTP__PASSWORD=secret \
+  -e MAILIFY_SMTP__TLS=starttls \
+  donighost/mailify:latest
+```
+
+See [Docker deployment guide](../guides/deploy-docker.md) for a full `docker-compose.yml` with Postgres attached.
+
+### Available tags
+
+| Tag | Meaning |
+|-----|---------|
+| `latest` | Latest release from the default branch |
+| `0.1`, `0.1.2` | Semver-pinned (major.minor or major.minor.patch) |
+| `sha-<short>` | Exact commit SHA |
+
+Multi-arch: `linux/amd64` and `linux/arm64` published side-by-side — pull the same tag everywhere, Docker picks the right one.
+
+## 2. Universal install script
+
+One-liner that downloads the right prebuilt archive for your OS + arch from the latest GitHub Release, verifies the SHA256, installs the binary to `~/.local/bin` and the template bundle to `~/.local/share/mailify/templates`.
+
+**Linux / macOS:**
+
+```bash
+curl -fsSL https://mailify.donilite.me/install.sh | sh
+```
+
+**Windows (PowerShell):**
+
+```powershell
+irm https://mailify.donilite.me/install.ps1 | iex
+```
+
+### Script options
+
+| Flag / env | Effect |
+|-----------|--------|
+| `--version v0.2.0` / `MAILIFY_VERSION` | Pin a specific tag (default: latest) |
+| `--dir ~/bin` / `MAILIFY_INSTALL_DIR` | Change install directory |
+| `MAILIFY_NO_VERIFY=1` | Skip checksum (not recommended) |
+
+After install, point Mailify at its templates:
+
+```bash
+export MAILIFY_TEMPLATES__PATH="$HOME/.local/share/mailify/templates"
+mailify
+```
+
+## 3. `cargo install` (Rust toolchain)
+
+> **Status:** planned. Publishing to crates.io is gated on the lib crates being deemed API-stable. Track progress in [`TODO.md §4.1`](https://github.com/donilite/mailify/blob/master/TODO.md).
+
+When ready:
+
+```bash
+cargo install mailify-api --locked
+```
+
+This installs the `mailify` binary into `$CARGO_HOME/bin`. Note that `cargo install` does **not** ship the compiled template bundle — you will need to either build them from source (see [Template contract](../reference/template-contract.md)) or point `MAILIFY_TEMPLATES__PATH` at a pre-built bundle extracted from a GitHub Release archive.
+
+## 4. Build from source
+
+```bash
+git clone https://github.com/donilite/mailify.git
+cd mailify
+
+# 1. Build React Email templates (requires Bun ≥ 1.3)
+cd templates-parser && bun install && bun run build && cd ..
+
+# 2. Build the binary (requires Rust ≥ 1.88)
+cargo build --release --bin mailify
+
+# 3. Run it
+./target/release/mailify
+```
+
+## Next steps
+
+- [Send your first email →](./quickstart.md)
+- [Understand the moving parts →](./concepts.md)
+- [Configure SMTP for your provider →](../guides/configure-smtp.md)
diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md
new file mode 100644
index 0000000..e5d72c3
--- /dev/null
+++ b/docs/getting-started/quickstart.md
@@ -0,0 +1,121 @@
+---
+title: Quickstart
+description: Send your first email through Mailify in five minutes using Docker and Mailpit.
+sidebar:
+  order: 2
+---
+
+# Quickstart
+
+Goal: boot Mailify locally, trade an API key for a JWT, enqueue an email, and inspect it in [Mailpit](https://mailpit.axllent.org/) — all in five minutes.
+
+## 1. Boot the stack
+
+Create a `docker-compose.yml`:
+
+```yaml
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: mailify
+      POSTGRES_PASSWORD: mailify
+      POSTGRES_DB: mailify
+    ports: ["5432:5432"]
+    healthcheck:
+      test: ["CMD", "pg_isready", "-U", "mailify"]
+      interval: 5s
+      retries: 10
+
+  mailpit:
+    image: axllent/mailpit:latest
+    ports:
+      - "1025:1025"   # SMTP in
+      - "8025:8025"   # Web UI
+    environment:
+      MP_SMTP_AUTH_ACCEPT_ANY: "true"
+      MP_SMTP_AUTH_ALLOW_INSECURE: "true"
+
+  mailify:
+    image: donighost/mailify:latest
+    depends_on:
+      postgres:
+        condition: service_healthy
+    ports: ["8080:8080"]
+    environment:
+      MAILIFY_DATABASE__URL: postgres://mailify:mailify@postgres:5432/mailify
+      MAILIFY_SMTP__HOST: mailpit
+      MAILIFY_SMTP__PORT: "1025"
+      MAILIFY_SMTP__TLS: none
+      MAILIFY_AUTH__JWT_SECRET: dev-secret-change-me
+      MAILIFY_AUTH__BOOTSTRAP: "true"
+```
+
+Boot it:
+
+```bash
+docker compose up -d
+```
+
+Mailify starts with `MAILIFY_AUTH__BOOTSTRAP: "true"` and no pre-configured API key, so on first boot it generates an ephemeral key and prints both the plaintext and the `MAILIFY_AUTH__API_KEYS__<ID>=<hash>` line you can persist:
+
+```
+docker compose logs mailify | grep -A2 "ephemeral API key"
+```
+
+Copy the plaintext (e.g. `mky_abc123…`). You will use it below.
+
+## 2. Trade the API key for a JWT
+
+```bash
+API_KEY="mky_abc123..."
+
+TOKEN=$(curl -s -X POST http://localhost:8080/auth/token \
+  -H 'content-type: application/json' \
+  -d "{\"api_key\": \"$API_KEY\"}" | jq -r '.token')
+
+echo "$TOKEN"
+```
+
+The JWT is short-lived (default: 1 hour). See [Auth & tokens](../guides/auth-and-tokens.md) for scopes, TTLs, and refresh strategies.
+
+## 3. Send a custom-HTML email
+
+```bash
+curl -s -X POST http://localhost:8080/mail/send-custom \
+  -H "authorization: Bearer $TOKEN" \
+  -H 'content-type: application/json' \
+  -d '{
+    "from": { "address": "no-reply@example.com", "name": "Example" },
+    "to":   [{ "address": "alice@example.com", "name": "Alice" }],
+    "subject": "Hello from Mailify",
+    "html": "<h1>It works.</h1><p>Sent via Mailify.</p>",
+    "locale": "en"
+  }'
+```
+
+Response:
+
+```json
+{ "job_id": "01J...ULID", "status": "pending" }
+```
+
+## 4. Inspect the mail in Mailpit
+
+Open <http://localhost:8025>. Your message appears within seconds of the worker picking up the job.
+
+## 5. Check job state
+
+```bash
+curl -s -H "authorization: Bearer $TOKEN" \
+  http://localhost:8080/mail/jobs/01J...ULID | jq
+```
+
+You should see a status of `Done` (or `Failed` with `last_error` populated) once the worker has processed it.
+
+## Next steps
+
+- [Register your own React Email templates →](../guides/configure-templates.md)
+- [Switch SMTP provider →](../guides/configure-smtp.md)
+- [Theme your outgoing mail →](../guides/configure-theme.md)
+- [Full HTTP API reference →](../reference/http-api.md)
diff --git a/docs/guides/auth-and-tokens.md b/docs/guides/auth-and-tokens.md
new file mode 100644
index 0000000..b0ac7f0
--- /dev/null
+++ b/docs/guides/auth-and-tokens.md
@@ -0,0 +1,138 @@
+---
+title: Auth & tokens
+description: How Mailify's API-key-to-JWT handshake works, how to rotate secrets, and how to bootstrap a fresh install.
+sidebar:
+  order: 3
+---
+
+# Auth & tokens
+
+Mailify has two auth layers, serving different needs:
+
+| Layer | Who holds it | Lifetime | Verified by |
+|-------|-------------|----------|-------------|
+| **API key** | Your backend / CI secret store | Long (months) | argon2 hash compare |
+| **JWT** | Any client talking to Mailify | Short (default 1 hour) | HS256 signature |
+
+Clients exchange the API key for a JWT once (usually on startup), then reuse the JWT until it expires. This avoids doing a CPU-heavy argon2 verify on every request.
+
+## Generating an API key
+
+```bash
+make hash-key KEY=my-secret-plaintext ID=web
+```
+
+This prints something like:
+
+```
+MAILIFY_AUTH__API_KEYS__WEB=$argon2id$v=19$m=19456,t=2,p=1$...
+```
+
+- **Plaintext** (`my-secret-plaintext`): hand to your client. **Never logged by Mailify.**
+- **Hash** (the `$argon2id$...` string): put into the Mailify process environment or `Mailify.toml`.
+
+## Adding keys via TOML
+
+```toml
+[auth.api_keys]
+web       = "$argon2id$v=19$m=19456,t=2,p=1$...hash-1..."
+ci-pipe   = "$argon2id$v=19$m=19456,t=2,p=1$...hash-2..."
+mobile    = "$argon2id$v=19$m=19456,t=2,p=1$...hash-3..."
+```
+
+Each key has an `id` (the map key) that appears in the JWT `sub` claim — useful for per-client audit trails.
+
+## Adding keys via env
+
+```
+MAILIFY_AUTH__API_KEYS__WEB=$argon2id$...
+MAILIFY_AUTH__API_KEYS__CI_PIPE=$argon2id$...
+```
+
+Double-underscore between env path levels, single underscore inside the leaf name. So `AUTH__API_KEYS__CI_PIPE` maps to `auth.api_keys.ci_pipe`.
+
+## Exchanging key for token
+
+```bash
+curl -s -X POST http://localhost:8080/auth/token \
+  -H 'content-type: application/json' \
+  -d '{ "api_key": "my-secret-plaintext" }'
+```
+
+```json
+{
+  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
+  "expires_at": "2026-04-23T14:00:00Z",
+  "issuer": "mailify"
+}
+```
+
+Use it as `Authorization: Bearer <token>` on every protected route.
+
+## Token claims
+
+Decoded JWT payload:
+
+```json
+{
+  "iss": "mailify",
+  "sub": "web",                    // the api_key id
+  "iat": 1745420400,
+  "exp": 1745424000,
+  "scopes": ["mail:send"]          // reserved for future scope-based authz
+}
+```
+
+Scopes are declared in claims today but **not** enforced by middleware. Scope-gated routes are on the roadmap.
+
+## Bootstrap mode
+
+The first-boot ergonomic. When `MAILIFY_AUTH__BOOTSTRAP=true` (the default) **and** `cfg.auth.api_keys` is empty, Mailify:
+
+1. Generates a random plaintext key.
+2. Argon2-hashes it in memory.
+3. Logs both the plaintext and the `MAILIFY_AUTH__API_KEYS__<ID>=<hash>` env line you should persist.
+4. Accepts that key for the lifetime of the process.
+
+Looks like this in logs:
+
+```
+INFO mailify::bootstrap: generated ephemeral API key — save the env line below before restart
+INFO mailify::bootstrap:   id=bootstrap plaintext=mky_abc123def456...
+INFO mailify::bootstrap:   MAILIFY_AUTH__API_KEYS__BOOTSTRAP=$argon2id$v=19$m=19456,t=2,p=1$...
+```
+
+**Disable in production** once you've persisted a real key:
+
+```toml
+[auth]
+bootstrap = false
+```
+
+Bootstrap mode is only for zero-config demos and first-boot. Keeping it on in prod means an operator restart with a wiped config file would silently mint a new key and hand it to any log reader.
+
+## JWT secret
+
+Set `MAILIFY_AUTH__JWT_SECRET` to a long random string in production. The default (`CHANGE_ME_IN_PRODUCTION`) is a red flag — Mailify **does not** refuse to start with it, but it will log a warning.
+
+Rotating the secret invalidates every issued JWT. See the [FAQ](../troubleshooting/faq.md#how-do-i-rotate-the-jwt-secret-without-breaking-active-clients) for strategies.
+
+## Offline token minting
+
+For scripts, CI, or tests, you can mint a JWT without round-tripping through `/auth/token`:
+
+```bash
+make issue-token SUBJECT=ci SCOPES=mail:send
+```
+
+This uses the same `jwt_secret` the server would — works only when you control both ends (i.e., not usable by external clients).
+
+## Revocation
+
+Not implemented. JWTs are valid until `exp`. Practical options:
+
+- **Short TTLs.** `jwt_ttl_secs = 300` limits blast radius of a leaked token.
+- **Remove the API key.** Removing the argon2 hash from config + restart prevents new token issuance. Already-issued tokens remain valid until expiry.
+- **Rotate the JWT secret.** Nuclear option — invalidates every token.
+
+A stateful revocation list is a reasonable PR opportunity.
diff --git a/docs/guides/configure-smtp.md b/docs/guides/configure-smtp.md
new file mode 100644
index 0000000..d16e94e
--- /dev/null
+++ b/docs/guides/configure-smtp.md
@@ -0,0 +1,155 @@
+---
+title: Configure SMTP
+description: Wire Mailify to SES, Mailgun, Brevo, Postmark, Resend, SendGrid, or a local relay.
+sidebar:
+  order: 1
+---
+
+# Configure SMTP
+
+Mailify uses [lettre](https://github.com/lettre/lettre) and speaks stock SMTP. Any provider that gives you credentials for `host:port` + `username:password` over SMTPS/STARTTLS will work.
+
+## The four knobs
+
+| Key | Values | Notes |
+|-----|--------|-------|
+| `smtp.host` | e.g. `smtp.resend.com` | Provider's SMTP endpoint. |
+| `smtp.port` | `25`, `587`, `465`, `1025` | 587 = submission + STARTTLS, 465 = implicit TLS, 1025 = Mailpit local. |
+| `smtp.tls` | `none`, `starttls`, `tls` | Match the port. |
+| `smtp.username` / `smtp.password` | string / secret | Usually from provider dashboard. |
+
+**Rule of thumb**
+
+- Port 587 → `tls = "starttls"`.
+- Port 465 → `tls = "tls"`.
+- Port 25 / 1025 → `tls = "none"`.
+
+## Provider recipes
+
+### Resend
+
+```toml
+[smtp]
+host = "smtp.resend.com"
+port = 587
+tls = "starttls"
+username = "resend"
+# password = your Resend API key, from env MAILIFY_SMTP__PASSWORD
+default_from_email = "you@yourdomain.com"
+```
+
+### Amazon SES
+
+Get SMTP credentials from the SES console (different from your AWS access keys).
+
+```toml
+[smtp]
+host = "email-smtp.us-east-1.amazonaws.com"
+port = 587
+tls = "starttls"
+username = "AKIA..."
+# password from MAILIFY_SMTP__PASSWORD
+default_from_email = "no-reply@yourdomain.com"
+```
+
+Region suffix matters — pick the endpoint that matches where your SES identity is verified.
+
+### Mailgun
+
+```toml
+[smtp]
+host = "smtp.mailgun.org"
+port = 587
+tls = "starttls"
+username = "postmaster@mg.yourdomain.com"
+# password from MAILIFY_SMTP__PASSWORD (Mailgun SMTP password, not the API key)
+```
+
+Use `smtp.eu.mailgun.org` if your domain is in the EU region.
+
+### Brevo (Sendinblue)
+
+```toml
+[smtp]
+host = "smtp-relay.brevo.com"
+port = 587
+tls = "starttls"
+username = "<your-brevo-login-email>"
+# password from MAILIFY_SMTP__PASSWORD (SMTP key, not API key)
+```
+
+### Postmark
+
+```toml
+[smtp]
+host = "smtp.postmarkapp.com"
+port = 587
+tls = "starttls"
+username = "<server-api-token>"
+# password = same server-api-token
+```
+
+Postmark's SMTP uses the same token as username and password.
+
+### SendGrid
+
+```toml
+[smtp]
+host = "smtp.sendgrid.net"
+port = 587
+tls = "starttls"
+username = "apikey"    # literal string "apikey"
+# password from MAILIFY_SMTP__PASSWORD (SendGrid API key)
+```
+
+### Local Mailpit (dev)
+
+```toml
+[smtp]
+host = "localhost"   # or "mailpit" in docker-compose
+port = 1025
+tls = "none"
+```
+
+No auth. Inspect mail at <http://localhost:8025>.
+
+## Where to put the password
+
+**Do not** commit passwords to `Mailify.toml`. Load them from the environment:
+
+```toml
+[smtp]
+host = "smtp.resend.com"
+port = 587
+tls = "starttls"
+username = "resend"
+# password intentionally omitted → comes from MAILIFY_SMTP__PASSWORD
+```
+
+```bash
+# .env (gitignored)
+MAILIFY_SMTP__PASSWORD=re_live_...
+```
+
+Or use a secret manager (Doppler, 1Password CLI, AWS Secrets Manager) and export the env var at process start.
+
+## Test the setup
+
+From the running Mailify:
+
+```bash
+curl -s -X POST http://localhost:8080/mail/send-custom \
+  -H "authorization: Bearer $TOKEN" \
+  -H 'content-type: application/json' \
+  -d '{
+    "from": { "address": "no-reply@yourdomain.com" },
+    "to": [{ "address": "you@yourdomain.com" }],
+    "subject": "SMTP test from Mailify",
+    "html": "<p>It arrives.</p>",
+    "locale": "en"
+  }'
+```
+
+Then hit `GET /mail/jobs/:id` with the returned ULID until you see `status: "Done"`.
+
+If it fails, [Debugging §5](../troubleshooting/debugging.md#5-test-smtp-connectivity-standalone) shows how to bypass Mailify and test the provider directly with `swaks`.
diff --git a/docs/guides/configure-theme.md b/docs/guides/configure-theme.md
new file mode 100644
index 0000000..fa98cd0
--- /dev/null
+++ b/docs/guides/configure-theme.md
@@ -0,0 +1,126 @@
+---
+title: Configure theme
+description: Override Mailify's branding tokens — colors, fonts, logo, footer — via a single config block.
+sidebar:
+  order: 2
+---
+
+# Configure theme
+
+The **theme** is Mailify's headline feature. Every template references `{{ theme.* }}` at render time, so changing the theme object re-brands every outgoing mail without editing a single template.
+
+## What's in the theme
+
+See the [full config reference](../reference/config.md#theme) for the authoritative list. At a glance:
+
+```toml
+[theme]
+brand_name     = "Acme"
+brand_logo_url = "https://cdn.acme.com/logo.svg"
+radius         = "12px"
+footer_text    = "© Acme Corp · 100 Main St · San Francisco"
+
+[theme.colors]
+primary             = "#2D5BFF"
+primary_foreground  = "#ffffff"
+secondary           = "#1F2937"
+secondary_foreground = "#F8FAFC"
+background          = "#F8FAFC"
+foreground          = "#0B1020"
+muted               = "#94A3B8"
+border              = "#E2E8F0"
+danger              = "#EF4444"
+success             = "#10B981"
+
+[theme.fonts]
+body    = "Inter, -apple-system, sans-serif"
+heading = "Geist Sans, Inter, sans-serif"
+
+[theme.social_links]
+twitter  = "https://x.com/acme"
+linkedin = "https://linkedin.com/company/acme"
+github   = "https://github.com/acme"
+
+[theme.extra]
+support_email = "support@acme.com"
+docs_url      = "https://docs.acme.com"
+```
+
+## How templates consume it
+
+Inside a React Email component (`.tsx`):
+
+```tsx
+import { Button, Container, Text } from "@react-email/components";
+
+export default function Welcome() {
+  return (
+    <Container
+      style={{
+        backgroundColor: "{{ theme.colors.background }}",
+        color: "{{ theme.colors.foreground }}",
+        fontFamily: "{{ theme.fonts.body }}",
+      }}
+    >
+      <Text>Hello {{ vars.first_name }},</Text>
+      <Button
+        href="{{ vars.cta_url }}"
+        style={{
+          backgroundColor: "{{ theme.colors.primary }}",
+          color: "{{ theme.colors.primary_foreground }}",
+          borderRadius: "{{ theme.radius }}",
+        }}
+      >
+        {{ theme.brand_name }} →
+      </Button>
+      <Text style={{ color: "{{ theme.colors.muted }}" }}>
+        {{ theme.footer_text }}
+      </Text>
+    </Container>
+  );
+}
+```
+
+The `post-build.ts` step decodes the HTML-entity-escaped `{{ }}` spans so minijinja can resolve them at send time. See [Template contract](../reference/template-contract.md) for the full pipeline.
+
+## The `extra` bag
+
+`theme.extra` is an arbitrary `HashMap<String, String>` for tenant-specific or template-specific values that don't fit elsewhere:
+
+```toml
+[theme.extra]
+help_center_url = "https://help.acme.com"
+app_store_badge = "https://cdn.acme.com/badges/app-store.svg"
+```
+
+```tsx
+<Link href="{{ theme.extra.help_center_url }}">Need help?</Link>
+```
+
+This beats encoding everything in `vars` when the value is a constant per install (not per email).
+
+## Re-theming in production
+
+Two paths:
+
+1. **Edit config + restart.** Cheapest and most correct. The theme is read once at boot and cloned into `AppState`. A restart takes seconds with Docker.
+2. **Hot-reload config.** Not implemented. If you want it, file an issue — there's a reasonable PR here that polls the TOML file for changes.
+
+## Branding multiple tenants from one install
+
+Today the theme is **global per process**. To run multi-tenant with distinct branding:
+
+- Easiest: one Mailify instance per tenant. Cheap in Docker — ~20 MB per container.
+- Or: pass tenant-specific values in `vars` and reference `vars.*` instead of `theme.*` in your templates. Lose the "re-theme via config" ergonomics, gain per-request flexibility.
+- Or: contribute a `theme_override` field on `MailJob` (same pattern as `smtp_override`).
+
+## Preview the theme locally
+
+Pair `MAILIFY_THEME__*` overrides with `make dev-templates` to iterate:
+
+```bash
+cd templates-parser
+MAILIFY_THEME__COLORS__PRIMARY=#ff4500 bun run dev
+```
+
+The React Email dev server runs on `:3000` and hot-reloads as you edit `.tsx`. Themes are hard-coded in the dev preview by default — you'll want to wire your `.tsx` components to read theme values from a shared constants file and swap it out during build.
diff --git a/docs/guides/deploy-docker.md b/docs/guides/deploy-docker.md
new file mode 100644
index 0000000..8430380
--- /dev/null
+++ b/docs/guides/deploy-docker.md
@@ -0,0 +1,228 @@
+---
+title: Deploy with Docker
+description: Production-ready docker-compose stack for Mailify with Postgres, backups, and secret management.
+sidebar:
+  order: 5
+---
+
+# Deploy with Docker
+
+Mailify ships a distroless image (~20 MB, non-root) that expects Postgres + SMTP and nothing else. This guide covers a production-ready compose stack; for local dev, see the [Quickstart](../getting-started/quickstart.md).
+
+## Minimal production stack
+
+```yaml
+# docker-compose.yml
+services:
+  postgres:
+    image: postgres:16-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+      POSTGRES_DB: ${POSTGRES_DB}
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD", "pg_isready", "-U", "${POSTGRES_USER}"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    # Don't expose to the public internet — Mailify connects on the private network.
+    # ports: ["127.0.0.1:5432:5432"]  # uncomment for host-side psql access
+
+  mailify:
+    image: donighost/mailify:${MAILIFY_TAG:-latest}
+    restart: unless-stopped
+    depends_on:
+      postgres:
+        condition: service_healthy
+    ports:
+      - "127.0.0.1:8080:8080"   # put a reverse proxy in front
+    environment:
+      # Server
+      MAILIFY_SERVER__HOST: 0.0.0.0
+      MAILIFY_SERVER__PORT: "8080"
+
+      # Database
+      MAILIFY_DATABASE__URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
+      MAILIFY_DATABASE__MAX_CONNECTIONS: "20"
+
+      # SMTP (example: Resend)
+      MAILIFY_SMTP__HOST: smtp.resend.com
+      MAILIFY_SMTP__PORT: "587"
+      MAILIFY_SMTP__TLS: starttls
+      MAILIFY_SMTP__USERNAME: resend
+      MAILIFY_SMTP__PASSWORD: ${RESEND_API_KEY}
+      MAILIFY_SMTP__DEFAULT_FROM_EMAIL: no-reply@yourdomain.com
+      MAILIFY_SMTP__DEFAULT_FROM_NAME: Your App
+
+      # Auth
+      MAILIFY_AUTH__JWT_SECRET: ${MAILIFY_JWT_SECRET}
+      MAILIFY_AUTH__JWT_TTL_SECS: "3600"
+      MAILIFY_AUTH__BOOTSTRAP: "false"
+      MAILIFY_AUTH__API_KEYS__WEB: ${MAILIFY_API_KEY_WEB_HASH}
+
+      # Queue
+      MAILIFY_QUEUE__WORKER_CONCURRENCY: "8"
+      MAILIFY_QUEUE__MAX_RETRIES: "5"
+
+      # Observability
+      MAILIFY_OBSERVABILITY__LOG_LEVEL: info
+      MAILIFY_OBSERVABILITY__LOG_FORMAT: json
+      RUST_LOG: "mailify=info,mailify_api=info,tower_http=info"
+
+volumes:
+  postgres_data:
+```
+
+And a `.env` (gitignored) alongside:
+
+```bash
+POSTGRES_USER=mailify
+POSTGRES_PASSWORD=<long-random>
+POSTGRES_DB=mailify
+RESEND_API_KEY=re_live_...
+MAILIFY_JWT_SECRET=<64-char-random>
+MAILIFY_API_KEY_WEB_HASH='$argon2id$v=19$m=19456,t=2,p=1$...'
+MAILIFY_TAG=0.1.2
+```
+
+Generate the `MAILIFY_JWT_SECRET`:
+
+```bash
+openssl rand -hex 32
+```
+
+Generate the API key hash:
+
+```bash
+docker run --rm -it donighost/mailify:latest \
+  /app/mailify --help   # (future) subcommand
+# or, from a clone of the repo:
+make hash-key KEY=<plaintext> ID=web
+```
+
+Boot:
+
+```bash
+docker compose up -d
+docker compose logs -f mailify
+```
+
+## Reverse proxy
+
+Don't expose `8080` directly. Put Caddy / nginx / Traefik in front for TLS + rate limiting.
+
+### Caddy example
+
+```caddy
+mailify.yourdomain.com {
+    reverse_proxy localhost:8080
+    encode zstd gzip
+    log {
+        output file /var/log/caddy/mailify.log
+    }
+}
+```
+
+### nginx example
+
+```nginx
+server {
+    listen 443 ssl http2;
+    server_name mailify.yourdomain.com;
+
+    ssl_certificate     /etc/letsencrypt/live/mailify.yourdomain.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/mailify.yourdomain.com/privkey.pem;
+
+    location / {
+        proxy_pass http://127.0.0.1:8080;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    # Rate limit the auth endpoint to slow down brute force against argon2
+    location = /auth/token {
+        limit_req zone=mailify_auth burst=5 nodelay;
+        proxy_pass http://127.0.0.1:8080;
+    }
+}
+```
+
+## Templates
+
+The Docker image bakes the default template bundle at `/app/templates` (set via `MAILIFY_TEMPLATES__PATH=/app/templates`). To ship your own:
+
+1. Build templates on your side:
+
+   ```bash
+   cd templates-parser && bun install && bun run build
+   ```
+
+2. Mount the output directory:
+
+   ```yaml
+   services:
+     mailify:
+       volumes:
+         - ./my-templates/out:/app/templates:ro
+       environment:
+         MAILIFY_TEMPLATES__PATH: /app/templates
+   ```
+
+3. Or bake your own image: `FROM donighost/mailify:0.1.2` + `COPY my-templates/out /app/templates`.
+
+## Backups
+
+Mailify stores all durable state in Postgres. Back up Postgres, nothing else.
+
+```bash
+# nightly cron
+docker compose exec -T postgres \
+  pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB" | gzip > "/backups/mailify-$(date +%F).sql.gz"
+```
+
+Restore:
+
+```bash
+gunzip -c backup.sql.gz | docker compose exec -T postgres psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"
+```
+
+## Upgrades
+
+Mailify uses semantic versioning on tags.
+
+```bash
+# pin a specific version in .env, then:
+docker compose pull mailify
+docker compose up -d mailify
+```
+
+Apalis schema migrations run automatically at boot. If the upgrade includes a major version bump, read the release notes for breaking changes.
+
+## Health probes
+
+`GET /health` returns `200 OK` when the process is live. Wire it into your orchestrator:
+
+```yaml
+# in docker-compose, or translate to k8s livenessProbe
+healthcheck:
+  test: ["CMD", "wget", "--spider", "-q", "http://localhost:8080/health"]
+  interval: 30s
+  timeout: 3s
+  retries: 3
+```
+
+Note `/health` does **not** check Postgres or SMTP reachability — it's a pure liveness probe. Readiness checks via DB ping are on the roadmap.
+
+## Resource sizing
+
+Rules of thumb:
+
+- **CPU** — 0.25 vCPU idle, 1 vCPU when argon2-verifying under load (API key exchange). Scale up if `/auth/token` is called often without token caching on the client.
+- **Memory** — 64–128 MB baseline. Grows with `worker_concurrency × avg_template_size`.
+- **Network** — outbound to SMTP provider. Nothing else.
+
+One instance comfortably handles thousands of sends per minute through a well-provisioned SMTP upstream. Horizontal scale is a matter of spawning more containers pointing at the same Postgres.
diff --git a/docs/guides/per-job-smtp-override.md b/docs/guides/per-job-smtp-override.md
new file mode 100644
index 0000000..7ae51bc
--- /dev/null
+++ b/docs/guides/per-job-smtp-override.md
@@ -0,0 +1,103 @@
+---
+title: Per-job SMTP override
+description: Drive one Mailify install that fans out to many SMTP providers — one per tenant, request, or environment.
+sidebar:
+  order: 4
+---
+
+# Per-job SMTP override
+
+By default every `MailJob` is dispatched through the **process-wide default sender** built from `MAILIFY_SMTP__*`. That works for the common case: one Mailify install, one upstream SMTP.
+
+For multi-tenant SaaS, you often want each tenant's mail to go through their own SMTP provider, using their own domain's reputation. Mailify supports this natively: attach a `smtp_override` to any send request, and the worker builds a one-off sender for just that job.
+
+## Request shape
+
+```json
+POST /mail/send-custom
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "from": { "address": "billing@tenant-a.com", "name": "Tenant A" },
+  "to":   [{ "address": "customer@example.com" }],
+  "subject": "Your invoice",
+  "html": "<h1>Invoice #1234</h1>",
+  "locale": "en",
+  "smtp_override": {
+    "host": "smtp.sendgrid.net",
+    "port": 587,
+    "tls": "starttls",
+    "username": "apikey",
+    "password": "SG.tenant-a-api-key"
+  }
+}
+```
+
+Every field in `smtp_override` mirrors the global `[smtp]` block. Missing fields are **not** inherited from the default — if you pass an override, it must be self-contained.
+
+## Security properties
+
+- **Never logged.** The `Debug` impl on `SmtpOverride` redacts `username` and `password`. The tracing layer never sees them.
+- **Never persisted.** Credentials live in the in-memory `MailJob` while it's being processed. They are skipped on serialization (`#[serde(skip_serializing_if = "Option::is_none")]` is combined with an explicit redaction helper used when the job is stored in Postgres).
+- **Scoped to one send.** The override sender is constructed, used once, and dropped. There is no credential cache.
+
+## Use cases
+
+### Multi-tenant per-domain reputation
+
+Each tenant's customers receive mail from `mail.<tenant-domain>` with its own DKIM/SPF setup. You store each tenant's SMTP creds in your own DB; when enqueueing a send, look up the tenant and inject `smtp_override`.
+
+### Environment-scoped routing
+
+Route staging mail through Mailpit, production through Resend — without running two Mailify instances. Your backend decides based on env.
+
+### Per-campaign throttling
+
+Some providers apply per-account rate limits. If you spread large sends across multiple provider accounts, each campaign can carry its own credentials.
+
+## When not to use
+
+- **Single-tenant / single-domain.** Just configure `[smtp]` globally and skip overrides.
+- **Shared infrastructure.** If tenants share an SMTP provider, no override needed — set the `From:` per request, let the global sender handle the rest.
+
+## Implementation notes
+
+The override is plumbed through:
+
+1. HTTP handler in `crates/mailify-api/src/routes/mail.rs` deserializes `smtp_override` into `SmtpOverride`.
+2. It's attached to the `MailJob` and pushed through `QueueHandle::push`.
+3. The apalis worker pops the job and calls `SmtpSender::from_override(&override)` to build a dedicated `lettre` transport.
+4. The sender is dropped as soon as the send resolves.
+
+If `smtp_override` is `None`, the worker uses the shared `default_sender` from `AppState`.
+
+## Example: per-tenant sender in your backend
+
+```rust
+let smtp_override = db
+    .get_tenant_smtp(tenant_id)
+    .await?
+    .map(|creds| SmtpOverride {
+        host: creds.host,
+        port: creds.port,
+        tls: creds.tls,
+        username: Some(creds.user),
+        password: Some(creds.password),
+    });
+
+let body = SendCustomRequest {
+    from: tenant.from_addr(),
+    to: vec![customer],
+    subject,
+    html,
+    text: None,
+    locale: "en".into(),
+    priority: Priority::Normal,
+    smtp_override,
+};
+
+mailify_client.send_custom(&body).await?;
+```
+
+Your backend owns the tenant → credentials mapping. Mailify owns the send.
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..80e37a6
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,44 @@
+---
+title: Mailify
+description: Self-hosted, theme-aware transactional mail server in Rust. One Docker image, your brand, zero lock-in.
+sidebar:
+  order: 0
+---
+
+# Mailify
+
+**The mail server that wears your brand.**
+
+Mailify is a self-hosted transactional email server written in Rust. You give it a theme, a template id, and a recipient — it sends a branded email through your own SMTP provider. No SaaS, no vendor lock-in, no external service holding your template library hostage.
+
+## Why Mailify
+
+- **Branded out of the box** — palette, fonts, logo, footer text injected into every template via a single `Theme` config object.
+- **One Docker image** — `donighost/mailify:<tag>` ships binary + compiled templates + built-in migrations. `docker run`, done.
+- **Templates as code** — React Email (`.tsx`) compiles to pre-rendered HTML with minijinja placeholders preserved for runtime variables. Edit in your editor, ship in CI.
+- **Durable queue** — jobs persist in Postgres via [apalis](https://github.com/geofmureithi/apalis). A worker crash does not eat your outbound.
+- **Per-job SMTP override** — one install can fan out to many tenants, each using their own SMTP provider, with credentials accepted in-memory only.
+- **Argon2 + JWT auth** — API keys are argon2-hashed at rest; clients exchange them for short-lived JWTs per session.
+- **Rust-fast, distroless-small** — final image ≈20 MB, non-root, nothing but `cc` libs and the binary.
+
+## Who it's for
+
+- **Indie / solo backend devs** who don't want to write a `MJML` template every time.
+- **Small SaaS teams** needing Postmark-like ergonomics without paying per email.
+- **Agencies** running multi-tenant stacks where each client needs its own visual identity.
+
+If you need drag-and-drop campaign editors, audience segmentation, or bounce-analytics dashboards — Mailify is not for you. This is a *sending* server, not a marketing suite.
+
+## Quick links
+
+- [Install →](./getting-started/installation.md)
+- [Send your first mail →](./getting-started/quickstart.md)
+- [Concepts & vocabulary →](./getting-started/concepts.md)
+- [Full config reference →](./reference/config.md)
+- [HTTP API →](./reference/http-api.md)
+- [Troubleshooting →](./troubleshooting/common-errors.md)
+- [Contribute →](./contributing/overview.md)
+
+## License
+
+MIT. See [`LICENSE`](https://github.com/donilite/mailify/blob/master/LICENSE).
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
new file mode 100644
index 0000000..d023885
--- /dev/null
+++ b/docs/reference/cli.md
@@ -0,0 +1,97 @@
+---
+title: CLI reference
+description: The mailify binary, the Make targets, and the cargo-run examples that ship with Mailify.
+sidebar:
+  order: 3
+---
+
+# CLI reference
+
+Mailify ships a single long-running binary (`mailify`) plus a handful of Cargo examples that stand in for ops subcommands. A first-class `mailify` CLI with subcommands (`init`, `config check`, `config print`) is on the roadmap — see [TODO.md §3.3](https://github.com/donilite/mailify/blob/master/TODO.md).
+
+## `mailify`
+
+The server binary. Takes no arguments — all configuration comes from `Mailify.toml`, dotenv, and env vars.
+
+```bash
+mailify
+```
+
+Startup order:
+
+1. Load dotenv (unless `MAILIFY_DOTENV=false`).
+2. Discover and merge `Mailify.toml` (see [config discovery](./config.md#discovery)).
+3. Merge `MAILIFY_*` env vars on top.
+4. Initialize tracing (respects `RUST_LOG`).
+5. Ping Postgres with `SELECT 1` and run apalis migrations.
+6. Load `TemplateRegistry` from `MAILIFY_TEMPLATES__PATH`.
+7. Maybe-bootstrap auth (generate ephemeral key if none configured).
+8. Spawn the queue worker.
+9. Start the axum HTTP server on `MAILIFY_SERVER__HOST:MAILIFY_SERVER__PORT`.
+
+## Ops helpers (via Cargo examples)
+
+These are thin binaries kept as `cargo run -p mailify-auth --example <name>` so they share the crate's code without needing a second published binary.
+
+### `hash-key` — argon2-hash an API key
+
+```bash
+cargo run -p mailify-auth --example hash-key -- <plaintext> <id>
+
+# via Make:
+make hash-key KEY=my-secret-key ID=web
+```
+
+Prints a `MAILIFY_AUTH__API_KEYS__<ID>=<hash>` line you can paste into your env source.
+
+### `issue-token` — mint a JWT offline
+
+```bash
+cargo run -p mailify-auth --example issue-token -- <subject> <scopes-csv>
+
+# via Make:
+make issue-token SUBJECT=dev SCOPES=mail:send,mail:admin
+```
+
+Uses the same JWT secret the server would — useful for scripted tests or for bootstrapping clients without round-tripping through `/auth/token`.
+
+## Make targets
+
+The project's `Makefile` is the canonical entry point for routine tasks.
+
+```bash
+make help                  # list every target with inline help text
+```
+
+Most-used targets:
+
+| Target | What it does |
+|--------|--------------|
+| `make dev` | `cargo run --bin mailify` — assumes deps are up. |
+| `make build` | `cargo build --release` |
+| `make test` | `cargo test --workspace` |
+| `make check` | `cargo check --workspace --all-targets` |
+| `make clippy` | `cargo clippy --workspace --all-targets -- -D warnings` |
+| `make fmt` / `make fmt-check` | rustfmt apply / verify |
+| `make ci` | Full CI parity: fmt-check + clippy + test |
+| `make setup` | `bun install` inside `templates-parser/` (once) |
+| `make gen` | Regenerate `.tsx` + sidecars from `scripts/templates.config.ts` |
+| `make build-templates` | Full template pipeline (generate → export → post-build) |
+| `make dev-templates` | React Email preview server on `:3000` |
+| `make up` | `docker-compose up` (postgres + mailpit + mailify) |
+| `make up-deps` | Just postgres + mailpit — for local `make dev` |
+| `make down` / `make down-volumes` | Tear down |
+| `make docker-build` | Build local image `mailify:local` |
+| `make openapi` | Curl running server's `/api-docs/openapi.json` into `./openapi.json` |
+| `make hash-key KEY=… ID=…` | argon2-hash an API key (see above) |
+| `make issue-token SUBJECT=… SCOPES=…` | Mint a JWT offline (see above) |
+
+## Running a single test
+
+```bash
+cargo test -p <crate> <test_name>
+
+# examples:
+cargo test -p mailify-auth jwt::tests::issues_and_validates
+cargo test -p mailify-config tests::user_config_dir_prefers_xdg
+```
diff --git a/docs/reference/config.md b/docs/reference/config.md
new file mode 100644
index 0000000..e79f6ba
--- /dev/null
+++ b/docs/reference/config.md
@@ -0,0 +1,212 @@
+---
+title: Configuration reference
+description: Every config option Mailify understands — TOML path, env var, default, and why it exists.
+sidebar:
+  order: 1
+---
+
+# Configuration reference
+
+Every runtime setting Mailify honors lives in this table. The same value can be set three ways — TOML, dotenv, or direct process env — with precedence resolved as documented in [Concepts: Config precedence](../getting-started/concepts.md#config-precedence).
+
+## Discovery
+
+Mailify looks for a TOML config file in this order at startup, using the first one that exists:
+
+1. `$MAILIFY_CONFIG` (explicit path)
+2. `./Mailify.toml` in the current working directory
+3. Per-user config dir:
+   - Linux/macOS: `$XDG_CONFIG_HOME/mailify/config.toml` (fallback `~/.config/mailify/config.toml`)
+   - Windows: `%APPDATA%\mailify\config.toml`
+4. `/etc/mailify/config.toml` (Unix system-wide, last resort)
+
+If no file is found, defaults + env vars still drive config.
+
+## Environment variables
+
+The env prefix is `MAILIFY_`. Nested keys use double underscore `__`:
+
+| TOML path | Env var |
+|-----------|---------|
+| `server.host` | `MAILIFY_SERVER__HOST` |
+| `smtp.host` | `MAILIFY_SMTP__HOST` |
+| `auth.api_keys.web` | `MAILIFY_AUTH__API_KEYS__WEB` |
+| `theme.colors.primary` | `MAILIFY_THEME__COLORS__PRIMARY` |
+
+## `[server]`
+
+| Key | Type | Default | Purpose |
+|-----|------|---------|---------|
+| `host` | string | `0.0.0.0` | Bind address. Use `127.0.0.1` for loopback-only. |
+| `port` | u16 | `8080` | HTTP listen port. |
+| `request_timeout_secs` | u64 | `30` | Per-request timeout applied by `tower-http`. |
+| `body_limit_bytes` | usize | `10485760` (10 MiB) | Max request body. Raise if you attach large files via `/mail/send-custom`. |
+
+## `[database]`
+
+| Key | Type | Default | Purpose |
+|-----|------|---------|---------|
+| `url` | string | `postgres://mailify:mailify@localhost:5432/mailify` | Postgres connection URL. Used by apalis for job storage and migrations. |
+| `max_connections` | u32 | `10` | sqlx pool upper bound. |
+| `min_connections` | u32 | `1` | sqlx pool lower bound (kept warm). |
+
+## `[smtp]`
+
+Process-wide default SMTP sender. Can be overridden per-job via `smtp_override`.
+
+| Key | Type | Default | Purpose |
+|-----|------|---------|---------|
+| `host` | string | `localhost` | SMTP server hostname. |
+| `port` | u16 | `1025` | SMTP port. 25/587/465 in prod, 1025 for Mailpit dev. |
+| `username` | option\<string> | — | SMTP AUTH user. Omit for unauthenticated. |
+| `password` | option\<string> | — | SMTP AUTH password. **Never logged.** |
+| `tls` | enum | `none` | One of `none`, `starttls`, `tls`. `starttls` for 587, `tls` for 465. |
+| `default_from_email` | string | `no-reply@mailify.local` | Default `From:` when the caller omits it. |
+| `default_from_name` | option\<string> | `Mailify` | Display name paired with default From. |
+| `timeout_secs` | u64 | `30` | lettre SMTP client timeout. |
+
+## `[auth]`
+
+| Key | Type | Default | Purpose |
+|-----|------|---------|---------|
+| `jwt_secret` | string | `CHANGE_ME_IN_PRODUCTION` | HS256 secret. **Must** be changed in prod. |
+| `jwt_issuer` | string | `mailify` | `iss` claim. |
+| `jwt_ttl_secs` | u64 | `3600` | JWT lifetime. |
+| `api_keys` | map\<id, hash> | `{}` | Argon2-hashed API keys. Key = id, value = hash. |
+| `bootstrap` | bool | `true` | If `true` **and** `api_keys` is empty at boot, auto-generate an ephemeral key. |
+
+Generate an argon2 hash:
+
+```bash
+make hash-key KEY=my-secret ID=web
+# or
+cargo run -p mailify-auth --example hash-key -- "my-secret" "web"
+```
+
+Paste the printed `MAILIFY_AUTH__API_KEYS__WEB=…` line into your env source.
+
+## `[queue]`
+
+| Key | Type | Default | Purpose |
+|-----|------|---------|---------|
+| `worker_concurrency` | usize | `4` | Simultaneous in-flight jobs the worker will run. |
+| `max_retries` | usize | `5` | Max retry count before a job is marked `Failed`. |
+| `retry_backoff_secs` | u64 | `30` | Seconds between retries. |
+
+## `[templates]`
+
+| Key | Type | Default | Purpose |
+|-----|------|---------|---------|
+| `path` | path | `./templates-parser/out` | Directory with compiled HTML bundle. |
+| `strict` | bool | `false` | If `true`, missing built-in template files for the default locale fail startup. |
+
+## `[theme]`
+
+Branding tokens injected into every render under the `{{ theme.* }}` namespace.
+
+| Key | Type | Default | Purpose |
+|-----|------|---------|---------|
+| `brand_name` | string | `Mailify` | Shown in subject lines, footer, default logo alt. |
+| `brand_logo_url` | option\<string> | — | Public URL to the logo (prefer HTTPS + CDN). |
+| `radius` | string | `8px` | CSS radius token applied to buttons/cards in templates. |
+| `footer_text` | option\<string> | — | Footer legalese. |
+| `social_links` | map\<string, string> | `{}` | Social icon → URL map. |
+| `extra` | map\<string, string> | `{}` | Arbitrary key/value bag for custom template variables. |
+
+### `[theme.colors]`
+
+All hex strings.
+
+| Key | Default |
+|-----|---------|
+| `primary` | — |
+| `primary_foreground` | — |
+| `secondary` | — |
+| `secondary_foreground` | — |
+| `background` | — |
+| `foreground` | — |
+| `muted` | — |
+| `border` | — |
+| `danger` | — |
+| `success` | — |
+
+### `[theme.fonts]`
+
+| Key | Default |
+|-----|---------|
+| `body` | — |
+| `heading` | — |
+
+See [Configure theme](../guides/configure-theme.md) for the full mapping to minijinja spans in templates.
+
+## `[i18n]`
+
+| Key | Type | Default | Purpose |
+|-----|------|---------|---------|
+| `default_locale` | string | `en` | Used when a send request omits `locale`. |
+| `fallback_chain` | list\<string> | `["en"]` | Tried in order when the requested locale's asset is missing. |
+| `supported_locales` | list\<string> | `["en", "fr"]` | Declared locales — used by startup strict-mode checks. |
+
+## `[observability]`
+
+| Key | Type | Default | Purpose |
+|-----|------|---------|---------|
+| `log_level` | string | `info` | `tracing` env filter. Overridden by `RUST_LOG` if set. |
+| `log_format` | enum | `pretty` | `pretty` or `json`. Use `json` for structured log shipping. |
+
+## Dotenv
+
+In addition to the OS env, Mailify reads the first existing `.env`-style file from:
+
+1. `$MAILIFY_DOTENV_PATH`
+2. `.env.<MAILIFY_ENV>.local`
+3. `.env.<MAILIFY_ENV>`
+4. `.env.local`
+5. `.env`
+
+Existing env vars are **not** overridden — dotenv only fills gaps. Disable dotenv entirely with `MAILIFY_DOTENV=false`.
+
+## Example `Mailify.toml`
+
+```toml
+[server]
+host = "0.0.0.0"
+port = 8080
+
+[database]
+url = "postgres://mailify:secret@db.internal:5432/mailify"
+max_connections = 20
+
+[smtp]
+host = "smtp.resend.com"
+port = 587
+tls = "starttls"
+username = "resend"
+# password loaded from env: MAILIFY_SMTP__PASSWORD
+default_from_email = "hello@acme.com"
+default_from_name = "Acme"
+
+[auth]
+jwt_secret = "a-very-long-random-secret-from-a-secret-manager"
+jwt_ttl_secs = 900
+bootstrap = false
+
+[auth.api_keys]
+web = "$argon2id$v=19$m=19456,t=2,p=1$...hash..."
+
+[queue]
+worker_concurrency = 8
+max_retries = 10
+
+[theme]
+brand_name = "Acme"
+brand_logo_url = "https://cdn.acme.com/logo.svg"
+footer_text = "© Acme Corp · 100 Main St · San Francisco"
+
+[theme.colors]
+primary = "#2D5BFF"
+primary_foreground = "#ffffff"
+
+[observability]
+log_format = "json"
+```
diff --git a/docs/reference/http-api.md b/docs/reference/http-api.md
new file mode 100644
index 0000000..56eb38d
--- /dev/null
+++ b/docs/reference/http-api.md
@@ -0,0 +1,177 @@
+---
+title: HTTP API
+description: Every endpoint Mailify exposes — auth, send, templates, jobs, health.
+sidebar:
+  order: 2
+---
+
+# HTTP API
+
+Live OpenAPI spec is served at `/api-docs/openapi.json` and a Swagger UI at `/swagger-ui` on every running Mailify instance. This page is the narrated overview; the JSON is the source of truth.
+
+## Authentication
+
+All routes under `/mail/*`, `/templates/*`, and `/config` require a **Bearer JWT** in the `Authorization` header. Acquire one via `POST /auth/token` by exchanging a long-lived API key.
+
+```
+Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
+```
+
+Public routes: `GET /health`, `POST /auth/token`, `GET /swagger-ui*`, `GET /api-docs/openapi.json`.
+
+## Endpoints
+
+### `GET /health`
+
+Liveness probe. Returns `200 OK` with a JSON body when the process is running. Does not check Postgres or SMTP — see [Observability](../guides/observability.md) for how to add deeper probes.
+
+### `POST /auth/token`
+
+Exchange an API key for a short-lived JWT.
+
+**Request**
+
+```json
+{ "api_key": "mky_abc123..." }
+```
+
+**Response** `200 OK`
+
+```json
+{
+  "token": "eyJ...",
+  "expires_at": "2026-04-23T14:00:00Z",
+  "issuer": "mailify"
+}
+```
+
+**Errors**
+
+- `401` — invalid or unknown API key (argon2 verification failed).
+- `400` — malformed request body.
+
+### `POST /mail/send` *(protected)*
+
+Enqueue a send using a **registered** template from `TemplateRegistry`.
+
+**Request**
+
+```json
+{
+  "template_id": "welcome",
+  "locale": "en",
+  "from": { "address": "no-reply@example.com", "name": "Example" },
+  "to": [{ "address": "alice@example.com", "name": "Alice" }],
+  "cc": [],
+  "bcc": [],
+  "reply_to": null,
+  "priority": "normal",
+  "vars": { "first_name": "Alice", "activation_url": "https://..." },
+  "headers": { "X-Campaign-Id": "welcome-v2" },
+  "subject_override": null,
+  "smtp_override": null
+}
+```
+
+**Response** `202 Accepted`
+
+```json
+{ "job_id": "01J8KZ7...", "status": "pending" }
+```
+
+- `job_id` is an apalis ULID (string). Use it with `GET /mail/jobs/:id`.
+- `status` is always `"pending"` at enqueue time — check the jobs endpoint for live state.
+
+### `POST /mail/send-custom` *(protected)*
+
+Send a one-shot email with caller-supplied raw HTML (no template registry lookup).
+
+**Request**
+
+```json
+{
+  "from": { "address": "no-reply@example.com", "name": "Example" },
+  "to":   [{ "address": "alice@example.com" }],
+  "subject": "Hello",
+  "html": "<h1>Hi</h1>",
+  "text": "Hi",
+  "locale": "en",
+  "priority": "high",
+  "smtp_override": {
+    "host": "smtp.tenant.com",
+    "port": 587,
+    "tls": "starttls",
+    "username": "postmaster",
+    "password": "secret"
+  }
+}
+```
+
+Same response shape as `/mail/send`. Custom HTML is still sent through the priority queue and the worker.
+
+### `GET /mail/jobs/:id` *(protected)*
+
+Look up the state of a previously enqueued job.
+
+**Response** `200 OK`
+
+```json
+{
+  "id": "01J8KZ7...",
+  "status": "Done",
+  "attempts": 1,
+  "last_error": null,
+  "run_at": "2026-04-23T13:00:00Z",
+  "done_at": "2026-04-23T13:00:02Z"
+}
+```
+
+`status` is one of: `Pending`, `Scheduled`, `Running`, `Done`, `Failed`, `Killed` (apalis state enum).
+
+**Errors**
+
+- `404` — unknown id (or id mismatch — apalis uses ULIDs, not the caller's UUID).
+
+### `GET /templates` *(protected)*
+
+List every template id + locale currently loaded in `TemplateRegistry`.
+
+### `GET /templates/:id/preview` *(protected)*
+
+Render a registered template with placeholder data — useful for design review without sending.
+
+### `POST /templates/:id/preview` *(protected)*
+
+Same, with caller-supplied `vars` to inspect a specific render.
+
+### `GET /config` *(protected)*
+
+Dump the resolved config with secrets redacted. Useful when debugging "which env var actually took effect".
+
+## Priority
+
+`priority` on any send request controls scheduling weight. Lower weight runs earlier.
+
+| Value | Weight |
+|-------|--------|
+| `critical` | 0 |
+| `high` | 10 |
+| `normal` | 50 (default) |
+| `low` | 100 |
+
+## Rate limiting
+
+Not built-in. Put Mailify behind your reverse proxy (nginx, Caddy, Traefik) or API gateway and rate-limit at the edge.
+
+## OpenAPI schema
+
+```
+GET /api-docs/openapi.json
+```
+
+Pipe to a file:
+
+```bash
+make openapi
+# writes ./openapi.json
+```
diff --git a/docs/reference/template-contract.md b/docs/reference/template-contract.md
new file mode 100644
index 0000000..0581c2f
--- /dev/null
+++ b/docs/reference/template-contract.md
@@ -0,0 +1,120 @@
+---
+title: Template contract
+description: The directory layout, minijinja-in-HTML convention, and build pipeline Mailify's TemplateRegistry expects.
+sidebar:
+  order: 4
+---
+
+# Template contract
+
+Mailify's `TemplateRegistry` is a flat, file-based store. It does not parse React Email at runtime — the `.tsx` compilation happens ahead of time, and the Rust side just reads prebuilt HTML + sidecar files.
+
+## Directory layout
+
+At the path pointed to by `MAILIFY_TEMPLATES__PATH` (default `./templates-parser/out`):
+
+```
+<template_id>/
+  <locale>.html              # required — pre-rendered React Email HTML
+  subject.<locale>.txt       # optional — minijinja-rendered at send time
+  text.<locale>.txt          # optional — plaintext alternative
+```
+
+Plus a `catalog.json` at the root listing every `(id, locale)` pair for registry boot.
+
+Example:
+
+```
+templates-parser/out/
+├── catalog.json
+├── welcome/
+│   ├── en.html
+│   ├── fr.html
+│   ├── subject.en.txt
+│   ├── subject.fr.txt
+│   ├── text.en.txt
+│   └── text.fr.txt
+└── password-reset/
+    ├── en.html
+    └── subject.en.txt
+```
+
+## Minijinja in HTML
+
+React Email HTML-encodes `{{ }}` and `{% %}` during export. Mailify's `post-build.ts` step **entity-decodes** those spans so the server-side minijinja can parse them at render time.
+
+This means:
+
+- Variables: `{{ vars.first_name }}`, `{{ theme.brand_name }}`, `{{ theme.colors.primary }}`.
+- Control flow: `{% if vars.admin %}…{% endif %}`, `{% for item in vars.items %}…{% endfor %}`.
+- Built-in filters: `{{ vars.email | escape }}`, etc.
+
+If you skip `post-build.ts`, your templates will ship with literal `&#123;&#123; vars.foo &#125;&#125;` and never resolve.
+
+## `RenderContext`
+
+Every render receives:
+
+- `theme` — the full `Theme` config object, with colors, fonts, logo URL, social links, and `extra` bag.
+- `vars` — the caller-supplied JSON blob from the send request.
+- `locale` — the resolved locale (after fallback chain).
+
+Example minijinja snippet inside a React Email component:
+
+```tsx
+<Text style={{ color: "{{ theme.colors.primary }}" }}>
+  Hi {{ vars.first_name | default("there") }},
+</Text>
+```
+
+## Strict mode
+
+If `templates.strict = true`, Mailify fails startup whenever any **built-in** template id is missing for the default locale. This catches "I renamed a template but forgot to rebuild" before it reaches a user.
+
+What counts as "built-in" is defined in `mailify-templates`'s registry code — custom user templates are always optional.
+
+## Build pipeline
+
+```
+templates-parser/scripts/templates.config.ts      (source of truth — ids + metadata)
+        ↓  make gen
+templates-parser/emails/<id>.tsx                   (React Email components)
+        ↓  make build-templates  →  email export
+templates-parser/out/<id>/<locale>.html            (HTML-encoded placeholders)
+        ↓  post-build.ts
+templates-parser/out/<id>/<locale>.html            (decoded, + subject/text sidecars)
+        ↓  build ./target/release/mailify
+./target/release/mailify                            (reads out/ at boot)
+```
+
+### Adding a new template
+
+1. Add its entry to `templates-parser/scripts/templates.config.ts`:
+
+   ```ts
+   {
+     id: "invoice-reminder",
+     subject: { en: "Payment due: {{ vars.invoice_number }}", fr: "..." },
+     locales: ["en", "fr"],
+   }
+   ```
+
+2. Run `make gen` — generates a `.tsx` scaffold in `templates-parser/emails/` and sidecar files.
+3. Fill in the React Email component.
+4. `make build-templates` — regenerates `out/` with your new template.
+5. Restart Mailify (or `docker compose up -d --force-recreate mailify`).
+
+## Serving precompiled templates from a different location
+
+For production installs where you don't want to ship `node_modules` + bun, pre-build elsewhere and point Mailify at the output directory:
+
+```bash
+# on your build machine or in CI:
+cd templates-parser && bun install && bun run build
+
+# ship templates-parser/out to the server, then:
+export MAILIFY_TEMPLATES__PATH=/opt/mailify/templates
+mailify
+```
+
+The universal install script ([installation](../getting-started/installation.md#2-universal-install-script)) extracts this bundle into `~/.local/share/mailify/templates` automatically.
diff --git a/docs/troubleshooting/common-errors.md b/docs/troubleshooting/common-errors.md
new file mode 100644
index 0000000..557359f
--- /dev/null
+++ b/docs/troubleshooting/common-errors.md
@@ -0,0 +1,145 @@
+---
+title: Common errors
+description: Mailify error symptoms mapped to causes and fixes.
+sidebar:
+  order: 1
+---
+
+# Common errors
+
+Errors are grouped by stage. If yours isn't here, check [Debugging](./debugging.md) and [FAQ](./faq.md).
+
+## Startup
+
+### `error: figment error: missing field smtp.host`
+
+**Cause** — no `[smtp]` block in `Mailify.toml` and no `MAILIFY_SMTP__HOST` env var. Smtp defaults exist, so this means the TOML file was found but declared `[smtp]` without `host`.
+
+**Fix** — either add `host = "…"` under `[smtp]`, or drop the partial `[smtp]` block entirely so defaults apply.
+
+### `error: pool timed out while waiting for an open connection`
+
+**Cause** — Postgres is unreachable or rejecting connections.
+
+**Diagnostic**
+
+```bash
+# inside the Mailify container/host:
+pg_isready -h <host> -p <port> -U mailify
+psql "$MAILIFY_DATABASE__URL" -c 'SELECT 1'
+```
+
+**Fix**
+
+- Check `MAILIFY_DATABASE__URL` for typos in user/password/host.
+- Confirm the Postgres container is healthy: `docker compose ps postgres`.
+- Inside a Docker network, don't use `localhost` — use the service name (`postgres`, not `localhost`).
+
+### `error: template "<id>" not found for locale "<loc>"`
+
+**Cause** — `TemplateRegistry` scanned `MAILIFY_TEMPLATES__PATH` and found no `<id>/<locale>.html`.
+
+**Fix**
+
+- Did you run `make build-templates` after adding/editing the template?
+- Is `MAILIFY_TEMPLATES__PATH` pointing at the right directory? Check with:
+
+  ```bash
+  ls "$MAILIFY_TEMPLATES__PATH"/<id>/
+  ```
+
+- In Docker, the default is `/app/templates` — don't override unless you mount your own.
+
+### `error: invalid bearer token`
+
+**Cause** — JWT rejected by `require_jwt` middleware. Reasons:
+
+- **Expired** — default TTL is 1 hour. Refresh via `POST /auth/token`.
+- **Wrong secret** — the server was restarted with a different `MAILIFY_AUTH__JWT_SECRET`, invalidating every previously issued token.
+- **Issuer mismatch** — you minted the token with a different `jwt_issuer`.
+
+**Fix** — request a new token. Verify the server's active secret with `GET /config` (it's redacted, but you can correlate against what you configured).
+
+### `error: argon2 verification failed`
+
+**Cause** — API key did not match any hash in `cfg.auth.api_keys`.
+
+**Fix**
+
+- Double-check you copied the **plaintext** key, not the hash.
+- Make sure `MAILIFY_AUTH__API_KEYS__<ID>` contains the **hash**, not the plaintext.
+- Regenerate with `make hash-key KEY=… ID=…` if in doubt.
+
+### `MAILIFY_AUTH__BOOTSTRAP=true` but no key printed
+
+**Cause** — `cfg.auth.api_keys` is not actually empty. Bootstrap only runs when there are zero configured keys.
+
+**Fix** — list env vars matching `MAILIFY_AUTH__API_KEYS__*`. Remove any stale values before relying on bootstrap mode.
+
+## Sending
+
+### Mailpit shows nothing
+
+**Cause** — SMTP host resolution inside Docker.
+
+**Fix**
+
+- In `docker-compose.yml`, set `MAILIFY_SMTP__HOST=mailpit` (the service name), not `localhost`.
+- When running Mailify **on the host** (`make dev`), `localhost:1025` is fine — Mailpit is published to host ports.
+- When running Mailify **in Docker** with Mailpit **on host**, use `host.docker.internal` on Docker Desktop, or the host's LAN IP on Linux.
+
+### `apalis: job stuck in Running forever`
+
+**Cause** — worker process crashed without releasing the job's lock. apalis heartbeats will eventually reclaim it, but in the meantime `GET /mail/jobs/:id` shows `Running`.
+
+**Fix**
+
+- Check `docker compose logs mailify` for the worker panic.
+- If stuck past `retry_backoff_secs`, restart the server — apalis will requeue on next poll.
+- Persistent hangs often mean an external dependency (SMTP provider) is timing out silently; raise `MAILIFY_SMTP__TIMEOUT_SECS` briefly to confirm, then fix the upstream.
+
+### `relay access denied` / `550 5.7.1`
+
+**Cause** — SMTP provider refused the `From:` domain. Most transactional providers (SES, Mailgun, Postmark) require you to prove domain ownership via DNS records (SPF, DKIM, DMARC) before accepting mail from `@yourdomain.com`.
+
+**Fix** — complete the provider's domain verification flow. Mailify faithfully relays whatever the provider tells it; this is not a Mailify bug.
+
+## Build
+
+### `docker build` on arm64 takes 40+ minutes
+
+**Cause** — you are emulating arm64 on an x86 runner via QEMU. Rust release builds under QEMU are 10–20× slower than native.
+
+**Fix** — switch to native arm runners. See `.github/workflows/docker.yml` in this repo for the matrix (`ubuntu-24.04` + `ubuntu-24.04-arm`) plus a `manifest` job that stitches the digests into a multi-arch image.
+
+### `cargo chef cook` fails with `error: no such subcommand`
+
+**Cause** — `cargo-chef` not installed in the Docker build stage.
+
+**Fix** — the `docker/Dockerfile` installs it in the `chef` base stage:
+
+```dockerfile
+RUN cargo install cargo-chef --locked --version ^0.1
+```
+
+Make sure the stage that uses `cargo chef …` inherits from `chef`, not from raw `rust:1.88-slim`.
+
+## Config
+
+### Env var does not take effect
+
+**Cause** — wrong nesting syntax. Double underscore separates levels, single underscore is a literal character.
+
+**Fix**
+
+- `MAILIFY_SMTP__HOST` ✅ (smtp.host)
+- `MAILIFY_SMTP_HOST` ❌ (parsed as `smtp_host`, which is not a field)
+- `MAILIFY_AUTH__API_KEYS__WEB` ✅ (auth.api_keys.web)
+
+Hit `GET /config` to see which values actually landed in the resolved `AppConfig`.
+
+### Mailify picks up an unexpected config file
+
+**Cause** — discovery is hierarchical. If you have a stale `/etc/mailify/config.toml` from an earlier install, it wins over nothing.
+
+**Fix** — check which file was loaded at startup. With `RUST_LOG=mailify=debug`, the server logs the resolved path.
diff --git a/docs/troubleshooting/debugging.md b/docs/troubleshooting/debugging.md
new file mode 100644
index 0000000..ac3f3ce
--- /dev/null
+++ b/docs/troubleshooting/debugging.md
@@ -0,0 +1,111 @@
+---
+title: Debugging
+description: Tactics for diagnosing Mailify — logs, tracing, queue inspection, SMTP checks.
+sidebar:
+  order: 3
+---
+
+# Debugging
+
+When something's off, start at the top of this list and work down.
+
+## 1. Turn up the logs
+
+Mailify honors `RUST_LOG` with higher priority than the config file. For deep dives:
+
+```bash
+RUST_LOG="mailify=debug,mailify_api=debug,mailify_queue=debug,tower_http=debug,apalis=info" mailify
+```
+
+What each target is useful for:
+
+- `mailify_api` — HTTP request/response, middleware (auth, trace layer).
+- `mailify_queue` — worker lifecycle, job pickup, retries, failures.
+- `mailify_templates` — registry load, render errors.
+- `mailify_auth` — JWT issue/verify flow.
+- `tower_http` — raw request spans with latency + status.
+- `apalis` — underlying queue engine.
+
+Set `MAILIFY_OBSERVABILITY__LOG_FORMAT=json` to emit JSON logs for shipping into Loki / Datadog / ELK.
+
+## 2. Inspect the resolved config
+
+```bash
+curl -s -H "authorization: Bearer $TOKEN" http://localhost:8080/config | jq
+```
+
+Passwords and the JWT secret are redacted. Everything else is authoritative — if a value looks wrong here, check the env vs. TOML precedence order.
+
+## 3. Check health + Postgres
+
+```bash
+curl http://localhost:8080/health
+
+# or straight to Postgres:
+psql "$MAILIFY_DATABASE__URL" -c 'SELECT count(*) FROM apalis.jobs;'
+psql "$MAILIFY_DATABASE__URL" -c "SELECT status, count(*) FROM apalis.jobs GROUP BY status;"
+```
+
+## 4. Inspect the queue
+
+```sql
+-- last 20 jobs
+SELECT id, status, attempts, last_error, run_at, done_at
+FROM apalis.jobs
+ORDER BY run_at DESC
+LIMIT 20;
+
+-- stuck-in-running jobs
+SELECT id, attempts, lock_at
+FROM apalis.jobs
+WHERE status = 'Running'
+  AND lock_at < now() - INTERVAL '10 minutes';
+
+-- failed jobs with errors
+SELECT id, last_error, attempts
+FROM apalis.jobs
+WHERE status = 'Failed'
+ORDER BY done_at DESC NULLS LAST
+LIMIT 20;
+```
+
+## 5. Test SMTP connectivity standalone
+
+Bypass Mailify entirely:
+
+```bash
+# one-liner to prove the SMTP endpoint works from wherever Mailify is running
+swaks --to you@example.com \
+      --from no-reply@example.com \
+      --server smtp.example.com:587 \
+      --auth LOGIN --auth-user postmaster --auth-password 'secret' \
+      --tls
+```
+
+If `swaks` succeeds and Mailify fails, the issue is in Mailify's config (tls mode, credentials) or auth handshake. If `swaks` also fails, fix the SMTP provider or network route first.
+
+## 6. Render a template in isolation
+
+Don't send to debug a template — use the preview endpoint:
+
+```bash
+curl -s -H "authorization: Bearer $TOKEN" \
+  -H 'content-type: application/json' \
+  -d '{ "locale": "en", "vars": { "first_name": "Test" } }' \
+  http://localhost:8080/templates/welcome/preview | less
+```
+
+This renders through the same minijinja pipeline but returns the HTML instead of enqueuing a send.
+
+## 7. Reproduce in `docker compose`
+
+Most "it works on my laptop" bugs are environment mismatches (Docker network, env var casing, missing secret). Boot the stack locally with the exact compose file from [Quickstart](../getting-started/quickstart.md), reproduce, and compare.
+
+## 8. When all else fails
+
+Open an issue at <https://github.com/donilite/mailify/issues> with:
+
+- Mailify version (`mailify --version` once implemented, or the image tag you ran).
+- The `GET /config` dump (redact anything extra you consider sensitive).
+- Relevant log lines at `RUST_LOG=debug`.
+- A minimal reproduction (the smallest request + config that triggers it).
diff --git a/docs/troubleshooting/faq.md b/docs/troubleshooting/faq.md
new file mode 100644
index 0000000..642544d
--- /dev/null
+++ b/docs/troubleshooting/faq.md
@@ -0,0 +1,73 @@
+---
+title: FAQ
+description: Frequently asked questions about Mailify's scope, ops, and roadmap.
+sidebar:
+  order: 2
+---
+
+# FAQ
+
+## Is Mailify a replacement for Postmark / Resend / SES?
+
+Partially. Mailify replaces the **templating + sending + queueing** layers. It does **not** replace the underlying SMTP relay — you still need a provider (or a self-run Postfix) to actually deliver mail to `gmail.com`. Mailify sits *in front of* that relay and handles everything between your app and it.
+
+## Can I use it without Postgres?
+
+No. The durable queue is the reason to use Mailify at all — Postgres is not optional. Sqlite-backed queue is not on the roadmap; if you don't need durability, you don't need Mailify.
+
+## Can I have multiple Mailify instances sharing one Postgres?
+
+Yes. apalis with `PostgresStorage` supports multiple workers on the same `apalis.jobs` table out of the box — jobs are locked atomically. Horizontal scale works.
+
+## How do I rotate the JWT secret without breaking active clients?
+
+Short answer: you can't — rotating `MAILIFY_AUTH__JWT_SECRET` invalidates every token signed with the old secret. Options:
+
+- **Short TTLs + forced refresh.** Set `jwt_ttl_secs` low (e.g. 300). Clients re-call `/auth/token` often. Rotate at a time when fresh tokens will issue soon.
+- **Accept downtime.** Rotate during a planned window and tell clients to re-auth.
+- **Roll-your-own dual-secret middleware.** Not in core yet.
+
+## How do I rotate an API key?
+
+- Generate a new hash: `make hash-key KEY=new-plaintext ID=new-web`.
+- Add it to `cfg.auth.api_keys` alongside the old one. Restart. Both now work.
+- Roll clients over to the new plaintext.
+- Remove the old entry. Restart.
+
+## Why is a job "Failed" after exactly 5 retries?
+
+Default `MAILIFY_QUEUE__MAX_RETRIES=5`. Apalis counts from zero — the first attempt is attempt 1, and it'll give up after the 5th failed attempt.
+
+## Why does `GET /mail/jobs/:id` return 404 with the UUID I got from my send call?
+
+It shouldn't — as of the current release, `job_id` returned by `/mail/send*` is the apalis ULID, which is what `/mail/jobs/:id` expects. If you stored a `MailJob.id` UUID from a pre-ULID version, that one won't work — apalis indexes by its own ULID.
+
+## Can I use Mailify as a library (not a server)?
+
+Not right now. The lib crates (`mailify-core`, `mailify-templates`, etc.) are workspace-internal — not published to crates.io. Publishing is gated on API-stability review; see [TODO.md §4.1](https://github.com/donilite/mailify/blob/master/TODO.md).
+
+## What happens if Postgres goes away mid-flight?
+
+- **Enqueued jobs** — persisted in Postgres. They resume when Postgres comes back.
+- **In-flight jobs** — the worker loses its DB connection; depending on timing, the job is either retried by the next worker poll or marked as stuck in `Running` until another instance reclaims the lock.
+- **Requests during the outage** — `/mail/send*` returns 500 because enqueue writes to Postgres.
+
+## Does Mailify store the message body?
+
+Yes — the full `MailJob` (including `kind.Custom.html`) is serialized into the `apalis.jobs` table. If you send PII, treat your Postgres as sensitive. `smtp_override` credentials are **never** stored (skipped at serialization).
+
+## How do I test Mailify in CI without a real SMTP provider?
+
+Use Mailpit as a test double. `docker-compose up postgres mailpit mailify` and point your tests at `http://localhost:8080`. Mailpit has its own JSON API for inspecting received mail, which makes assertions easy. See the integration tests under `crates/mailify-api/tests/` for working examples.
+
+## Can I brand emails per-tenant at render time?
+
+Yes, with a caveat: the `theme` is currently **global** — baked into `AppState` at boot. Per-request theme overrides are not exposed in the public HTTP API today. If you need per-tenant theming, options are:
+
+1. Run one Mailify instance per tenant (cheap in Docker).
+2. Pass tenant-specific values via the `vars` JSON blob and render them in your `.tsx` instead of using `{{ theme.* }}`.
+3. Contribute a `theme_override` field on `MailJob` — there's a PR opportunity here.
+
+## What's the lock-in story?
+
+Near-zero. The durable state lives in Postgres in a well-known apalis schema. Your templates are `.tsx` files in your repo. Your SMTP provider is yours. If Mailify disappears tomorrow, you can migrate queues with a `pg_dump` and re-render templates through any React Email pipeline.
diff --git a/install/install.ps1 b/install/install.ps1
new file mode 100644
index 0000000..b1ebc37
--- /dev/null
+++ b/install/install.ps1
@@ -0,0 +1,87 @@
+<#
+.SYNOPSIS
+    Mailify installer for Windows.
+.EXAMPLE
+    irm https://mailify.donilite.me/install.ps1 | iex
+.EXAMPLE
+    & ([ScriptBlock]::Create((irm https://mailify.donilite.me/install.ps1))) -Version v0.2.0 -InstallDir C:\tools\mailify
+#>
+[CmdletBinding()]
+param(
+    [string] $Version      = $(if ($env:MAILIFY_VERSION)      { $env:MAILIFY_VERSION }      else { 'latest' }),
+    [string] $InstallDir   = $(if ($env:MAILIFY_INSTALL_DIR)  { $env:MAILIFY_INSTALL_DIR }  else { "$env:LOCALAPPDATA\Programs\mailify" }),
+    [string] $Repo         = $(if ($env:MAILIFY_REPO)         { $env:MAILIFY_REPO }         else { 'donilite/mailify' }),
+    [switch] $NoVerify
+)
+
+$ErrorActionPreference = 'Stop'
+Set-StrictMode -Version Latest
+
+function Write-Log { param([string]$Msg) Write-Host "→ $Msg" -ForegroundColor Cyan }
+function Fail      { param([string]$Msg) Write-Host "✗ $Msg" -ForegroundColor Red; exit 1 }
+
+# --- detect arch ---
+$arch = $env:PROCESSOR_ARCHITECTURE
+switch ($arch) {
+    'AMD64' { $target = 'x86_64-pc-windows-msvc' }
+    default { Fail "unsupported arch: $arch" }
+}
+
+# --- resolve version ---
+if ($Version -eq 'latest') {
+    Write-Log "Resolving latest release tag from github.com/$Repo"
+    $api = Invoke-RestMethod -Uri "https://api.github.com/repos/$Repo/releases/latest" -UseBasicParsing
+    $Version = $api.tag_name
+    if (-not $Version) { Fail "could not resolve latest version" }
+}
+$versionNoV = $Version.TrimStart('v')
+$archive = "mailify-$versionNoV-$target.zip"
+$url     = "https://github.com/$Repo/releases/download/$Version/$archive"
+$shaUrl  = "$url.sha256"
+
+# --- download ---
+$tmp = Join-Path ([IO.Path]::GetTempPath()) ("mailify-" + [Guid]::NewGuid().ToString('N'))
+New-Item -ItemType Directory -Path $tmp | Out-Null
+try {
+    Write-Log "Downloading $archive"
+    $archivePath = Join-Path $tmp $archive
+    Invoke-WebRequest -Uri $url -OutFile $archivePath -UseBasicParsing
+
+    if (-not $NoVerify) {
+        Write-Log "Verifying SHA256"
+        $shaPath = "$archivePath.sha256"
+        Invoke-WebRequest -Uri $shaUrl -OutFile $shaPath -UseBasicParsing
+        $expected = (Get-Content $shaPath -First 1).Split(' ')[0].ToLower()
+        $actual   = (Get-FileHash $archivePath -Algorithm SHA256).Hash.ToLower()
+        if ($expected -ne $actual) { Fail "checksum mismatch (expected $expected, got $actual)" }
+    }
+
+    Write-Log "Extracting"
+    Expand-Archive -Path $archivePath -DestinationPath $tmp -Force
+    $stage = Join-Path $tmp "mailify-$versionNoV-$target"
+
+    # --- install binary ---
+    New-Item -ItemType Directory -Force -Path $InstallDir | Out-Null
+    Copy-Item -Force (Join-Path $stage 'mailify.exe') (Join-Path $InstallDir 'mailify.exe')
+
+    # --- install templates to %APPDATA%\mailify\templates ---
+    $dataDir = Join-Path $env:APPDATA 'mailify'
+    New-Item -ItemType Directory -Force -Path $dataDir | Out-Null
+    $tplDest = Join-Path $dataDir 'templates'
+    if (Test-Path $tplDest) { Remove-Item -Recurse -Force $tplDest }
+    Copy-Item -Recurse (Join-Path $stage 'templates') $tplDest
+
+    Write-Log "Installed mailify $Version → $InstallDir\mailify.exe"
+    Write-Log "Templates → $tplDest"
+    Write-Log "Set MAILIFY_TEMPLATES__PATH=$tplDest or put path in Mailify.toml"
+
+    $currentPath = [Environment]::GetEnvironmentVariable('Path', 'User')
+    if (($currentPath -split ';') -notcontains $InstallDir) {
+        Write-Log "Adding $InstallDir to user PATH"
+        [Environment]::SetEnvironmentVariable('Path', "$currentPath;$InstallDir", 'User')
+        Write-Log "Open a new terminal for PATH to take effect."
+    }
+}
+finally {
+    Remove-Item -Recurse -Force $tmp -ErrorAction SilentlyContinue
+}
diff --git a/install/install.sh b/install/install.sh
new file mode 100755
index 0000000..358851c
--- /dev/null
+++ b/install/install.sh
@@ -0,0 +1,123 @@
+#!/usr/bin/env sh
+# Mailify installer — POSIX sh, no bashisms.
+#
+# Usage:
+#   curl -fsSL https://mailify.donilite.me/install.sh | sh
+#   curl -fsSL https://mailify.donilite.me/install.sh | sh -s -- --version v0.2.0 --dir ~/bin
+#
+# Env overrides:
+#   MAILIFY_VERSION   pin a specific tag (default: latest)
+#   MAILIFY_INSTALL_DIR   install path (default: $HOME/.local/bin)
+#   MAILIFY_REPO      GitHub repo (default: donilite/mailify)
+#   MAILIFY_NO_VERIFY=1   skip checksum verification (not recommended)
+
+set -eu
+
+REPO="${MAILIFY_REPO:-donilite/mailify}"
+VERSION="${MAILIFY_VERSION:-latest}"
+INSTALL_DIR="${MAILIFY_INSTALL_DIR:-$HOME/.local/bin}"
+
+log() { printf '→ %s\n' "$*"; }
+err() { printf '✗ %s\n' "$*" >&2; exit 1; }
+
+# --- parse flags ---
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --version) VERSION="$2"; shift 2 ;;
+    --dir) INSTALL_DIR="$2"; shift 2 ;;
+    -h|--help)
+      cat <<EOF
+Mailify installer
+
+Options:
+  --version <TAG>     Pin version (e.g. v0.2.0). Default: latest
+  --dir <PATH>        Install directory. Default: \$HOME/.local/bin
+  -h, --help          Show this help
+EOF
+      exit 0 ;;
+    *) err "unknown flag: $1" ;;
+  esac
+done
+
+# --- detect OS ---
+OS="$(uname -s)"
+case "$OS" in
+  Linux)  OS=linux ;;
+  Darwin) OS=darwin ;;
+  *) err "unsupported OS: $OS" ;;
+esac
+
+# --- detect arch ---
+ARCH="$(uname -m)"
+case "$ARCH" in
+  x86_64|amd64) ARCH=x86_64 ;;
+  aarch64|arm64) ARCH=aarch64 ;;
+  *) err "unsupported arch: $ARCH" ;;
+esac
+
+# --- resolve target triple ---
+case "$OS-$ARCH" in
+  linux-x86_64)  TARGET=x86_64-unknown-linux-gnu ;;
+  linux-aarch64) TARGET=aarch64-unknown-linux-gnu ;;
+  darwin-x86_64) TARGET=x86_64-apple-darwin ;;
+  darwin-aarch64) TARGET=aarch64-apple-darwin ;;
+  *) err "no prebuilt target for $OS-$ARCH" ;;
+esac
+
+# --- resolve version ---
+if [ "$VERSION" = "latest" ]; then
+  log "Resolving latest release tag from github.com/$REPO"
+  VERSION="$(curl -fsSL "https://api.github.com/repos/$REPO/releases/latest" \
+    | sed -n 's/.*"tag_name": *"\([^"]*\)".*/\1/p')"
+  [ -n "$VERSION" ] || err "could not resolve latest version (API rate limit? set MAILIFY_VERSION=vX.Y.Z)"
+fi
+
+VERSION_NOV="${VERSION#v}"
+ARCHIVE="mailify-${VERSION_NOV}-${TARGET}.tar.gz"
+URL="https://github.com/$REPO/releases/download/$VERSION/$ARCHIVE"
+SHA_URL="$URL.sha256"
+
+log "Downloading $ARCHIVE"
+TMPDIR="$(mktemp -d)"
+trap 'rm -rf "$TMPDIR"' EXIT
+
+curl -fsSL "$URL" -o "$TMPDIR/$ARCHIVE" || err "download failed: $URL"
+
+# --- checksum ---
+if [ "${MAILIFY_NO_VERIFY:-0}" != "1" ]; then
+  log "Verifying SHA256"
+  curl -fsSL "$SHA_URL" -o "$TMPDIR/$ARCHIVE.sha256" || err "could not fetch checksum"
+  (
+    cd "$TMPDIR"
+    if command -v sha256sum >/dev/null 2>&1; then
+      sha256sum -c "$ARCHIVE.sha256" >/dev/null || err "checksum mismatch"
+    else
+      EXPECTED="$(awk '{print $1}' "$ARCHIVE.sha256")"
+      ACTUAL="$(shasum -a 256 "$ARCHIVE" | awk '{print $1}')"
+      [ "$EXPECTED" = "$ACTUAL" ] || err "checksum mismatch (expected $EXPECTED, got $ACTUAL)"
+    fi
+  )
+fi
+
+log "Extracting"
+tar -xzf "$TMPDIR/$ARCHIVE" -C "$TMPDIR"
+STAGE="$TMPDIR/mailify-${VERSION_NOV}-${TARGET}"
+
+mkdir -p "$INSTALL_DIR"
+install -m 0755 "$STAGE/mailify" "$INSTALL_DIR/mailify"
+
+# --- templates go to XDG data dir ---
+DATA_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/mailify"
+mkdir -p "$DATA_DIR"
+rm -rf "$DATA_DIR/templates"
+cp -R "$STAGE/templates" "$DATA_DIR/templates"
+
+log "Installed mailify $VERSION → $INSTALL_DIR/mailify"
+log "Templates → $DATA_DIR/templates"
+log "Set MAILIFY_TEMPLATES__PATH=$DATA_DIR/templates or put path in Mailify.toml"
+
+case ":$PATH:" in
+  *":$INSTALL_DIR:"*) ;;
+  *) log "Warning: $INSTALL_DIR is not in \$PATH. Add this to your shell rc:"
+     log "  export PATH=\"$INSTALL_DIR:\$PATH\"" ;;
+esac
diff --git a/static/logo.png b/static/logo.png
new file mode 100644
index 0000000..b709c84
Binary files /dev/null and b/static/logo.png differ