chore(release): v5.1.3

Co-authored-by: Crowdin Bot <support+bot@crowdin.com>

.dockerignore

@@ -1,15 +1,31 @@
-dist
-docs
+# VCS and editor state
+.git
+.gitignore
+.cursor
+.DS_Store
+
+# Local configuration and runtime state
 .env*
 /data
+
+# Dependency and package-manager caches
+node_modules
+**/node_modules
+.pnpm-store
+
+# Build, test, and framework output
+dist
+**/dist
 .nitro
-.cursor
 .output
 .vercel
 .netlify
-coverage
-.DS_Store
 .tanstack
-node_modules
+.turbo
+**/.turbo
+coverage
+reports
+
+# Generated service-worker assets are rebuilt during the web build.
 public/sw.js
-public/workbox-*.js
+public/workbox-*.js

.env.example

@@ -1,48 +1,60 @@
-# --- Server ---
-TZ="Etc/UTC"
+# --- Application ---
+# Port used by the web server in local development and self-hosted containers.
+PORT="3000"
+
+# Public URL where the app is served. Used for auth callbacks, OAuth issuer URLs,
+# OpenGraph metadata, and absolute upload URLs.
 APP_URL="http://localhost:3000"
 
-# Optional, uses APP_URL by default
-# This can be set to a different URL (like http://host.docker.internal:3000 or http://{docker_service}:3000)
-# to let the browser navigate to a non-public instance of Reactive Resume
-PRINTER_APP_URL="http://host.docker.internal:3000"
-
-# Note: set this to `http://host.docker.internal:3000` if your `gotenberg` service is running on docker, but Reactive Resume is running outside of Docker.
-
-# --- Printer ---
-GOTENBERG_ENDPOINT="http://localhost:4000"
-
-# Gotenberg Authentication (Optional)
-# TIP: It's safest to avoid exposing your Gotenberg instance to the public internet; connect via a private Docker network instead.
-# However, if Gotenberg needs to be hosted remotely from Reactive Resume, use these credentials to enable basic authentication for security.
-# For setup details and security best practices, see: https://gotenberg.dev/docs/configuration#api:~:text=API%5FENABLE%5FBASIC%5FAUTH
-# GOTENBERG_USERNAME=""
-# GOTENBERG_PASSWORD=""
-
 # --- Database (PostgreSQL) ---
+# PostgreSQL connection URL. In Docker Compose, the hostname is usually `postgres`;
+# when running directly on your machine, `localhost` is typical.
 DATABASE_URL="postgresql://postgres:postgres@localhost:5432/postgres"
 
 # --- Authentication ---
 # Generated using `openssl rand -hex 32`
 AUTH_SECRET="change-me-to-a-secure-secret-key-in-production"
 
+# Better Auth Dashboard (optional)
+# Enables the Better Auth Dashboard plugin when set, you probably don't need this.
+BETTER_AUTH_API_KEY=""
+
 # Social Auth (Google, optional)
+# Set both values to enable Google sign-in.
 GOOGLE_CLIENT_ID=""
 GOOGLE_CLIENT_SECRET=""
 
 # Social Auth (GitHub, optional)
+# Set both values to enable GitHub sign-in.
 GITHUB_CLIENT_ID=""
 GITHUB_CLIENT_SECRET=""
 
-# Custom OAuth Provider
+# Social Auth (LinkedIn, optional)
+# Set both values to enable LinkedIn sign-in.
+LINKEDIN_CLIENT_ID=""
+LINKEDIN_CLIENT_SECRET=""
+
+# Custom OAuth Provider (optional)
+# Set OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET plus either OAUTH_DISCOVERY_URL or
+# the three manual endpoint URLs below.
 OAUTH_PROVIDER_NAME=""
 OAUTH_CLIENT_ID=""
 OAUTH_CLIENT_SECRET=""
 OAUTH_DISCOVERY_URL=""
 OAUTH_AUTHORIZATION_URL=""
+OAUTH_TOKEN_URL=""
+OAUTH_USER_INFO_URL=""
+
+# Space-separated scopes requested from the custom OAuth provider.
+OAUTH_SCOPES="openid profile email"
+
+# Comma-separated extra hosts/origins allowed for dynamic OAuth client redirect URIs.
+# By default, only the APP_URL origin is allowed.
+OAUTH_DYNAMIC_CLIENT_REDIRECT_HOSTS=""
 
 # --- Email (optional) ---
-# If all keys are disabled, the app logs the email to be sent to the console instead.
+# If SMTP_HOST, SMTP_USER, SMTP_PASS, or SMTP_FROM is missing, the app logs the
+# email to the console instead.
 SMTP_HOST="localhost"
 SMTP_PORT="1025"
 SMTP_USER=""
@@ -51,8 +63,11 @@ SMTP_FROM="Reactive Resume <noreply@rxresu.me>"
 SMTP_SECURE="false"
 
 # --- Storage (optional) ---
-# If all keys are disabled, the app uses local filesystem (/data) to store uploads instead.
+# If all S3 keys are disabled, the app uses local filesystem storage instead.
 # Make sure to mount this directory to a volume or the host filesystem to ensure data integrity.
+# LOCAL_STORAGE_PATH overrides where local uploads/cache are written.
+# Defaults to /app/data in the official Docker image; in dev, defaults to <workspace>/data.
+# LOCAL_STORAGE_PATH="/app/data"
 
 # Seaweedfs
 S3_ACCESS_KEY_ID="seaweedfs"
@@ -63,15 +78,24 @@ S3_BUCKET="reactive-resume"
 S3_FORCE_PATH_STYLE="true"
 
 # --- Feature Flags ---
-# This flag bypasses the check that the endpoint to fetch data for the printing of PDFs `getByIdForPrinter`, is only accessible from the server.
-# Useful for when you want to debug the /printer/{resumeId} route to quickly take a peek at the page that is sent to the printer.
-FLAG_DEBUG_PRINTER="false"
-
 # This flag disables new signups, both on the web app and the server.
-FLAG_DISABLE_SIGNUP="false"
+FLAG_DISABLE_SIGNUPS="false"
+
+# This flag disables email/password login. Disables email verification, forgot password, and reset password flows.
+# Users can still sign up via social auth (Google/GitHub/Custom OAuth), unless FLAG_DISABLE_SIGNUPS is also set to true.
+FLAG_DISABLE_EMAIL_AUTH="false"
+
+# This flag disables the image processing.
+# This is useful if you are using a machine with limited resources, like a Raspberry Pi.
+FLAG_DISABLE_IMAGE_PROCESSING="false"
 
 # --- Others ---
 # Google Cloud API Key (optional)
-# This is not used within Reactive Resume, but in src/scripts/fonts/generate.ts to generate a list of fonts served by Google Fonts.
-# Note: Make sure "Google Fonts Developer API" is unrestricted.
+# For font-list generation tooling.
+# Requires "Google Fonts Developer API" to be enabled.
 GOOGLE_CLOUD_API_KEY=""
+
+# Crowdin (optional)
+# For translation tooling.
+CROWDIN_PROJECT_ID=""
+CROWDIN_PERSONAL_TOKEN=""

.github/.well-known/funding.json

@@ -5,7 +5,7 @@
 		"type": "individual",
 		"role": "maintainer",
 		"name": "Amruth Pillai",
-		"email": "im.amruth@gmail.com",
+		"email": "hello@amruthpillai.com",
 		"description": "Software Engineer",
 		"webpageUrl": {
 			"url": "https://rxresu.me/funding.json"
@@ -20,8 +20,8 @@
 				"url": "https://rxresu.me"
 			},
 			"repositoryUrl": {
-				"url": "https://github.com/AmruthPillai/Reactive-Resume",
-				"wellKnown": "https://github.com/AmruthPillai/Reactive-Resume/blob/main/.github/.well-known/funding-manifest-urls"
+				"url": "https://github.com/amruthpillai/reactive-resume",
+				"wellKnown": "https://github.com/amruthpillai/reactive-resume/blob/main/.github/.well-known/funding-manifest-urls"
 			},
 			"licenses": ["spdx:MIT"],
 			"tags": ["data", "design", "productivity", "resume-builder"]
@@ -61,7 +61,7 @@
 				"guid": "open-collective",
 				"type": "payment-provider",
 				"description": "Open Collective",
-				"address": "https://opencollective.com/reactive-resume"
+				"address": "https://opencollective.com/reactive-resume/donate"
 			}
 		]
 	}

.github/FUNDING.yml

@@ -1,2 +1,2 @@
 github: AmruthPillai
-open_collective: reactive-resume
+open_collective: reactive-resume

.github/ISSUE_TEMPLATE/1-bug-report.yml

@@ -53,6 +53,7 @@ body:
         - Onyx
         - Pikachu
         - Rhyhorn
+        - Scizor
     validations:
       required: false
 

.github/ISSUE_TEMPLATE/2-feature-request.yml

@@ -3,7 +3,7 @@ name: ✨ Feature Request
 description: Suggest an feature or idea that you would like to see in Reactive Resume
 
 title: "[Feature] <title>"
-labels: [feature, v5, needs triage]
+labels: [enhancement, v5, needs triage]
 assignees: "AmruthPillai"
 
 body:
@@ -20,4 +20,4 @@ body:
       label: Feature Description
       description: A detailed description of the feature you would like to see in Reactive Resume. Please provide as much detail as possible as it will help me implement the feature faster.
     validations:
-      required: true
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -1 +1 @@
-blank_issues_enabled: false
+blank_issues_enabled: false

.github/workflows/autofix.yml

@@ -0,0 +1,41 @@
+name: autofix.ci
+
+on:
+  pull_request:
+  push:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  autofix:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v6
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: "lts/*"
+          cache: "pnpm"
+
+      - name: Install Dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Remove Unused Dependencies
+        run: pnpm knip --fix
+
+      - name: Lint and Format
+        run: pnpm check
+
+      - name: Autofix
+        uses: autofix-ci/action@7a166d7532b277f34e16238930461bf77f9d7ed8

.github/workflows/crowdin-sync.yml

@@ -0,0 +1,36 @@
+name: Sync Translations from Crowdin
+
+on:
+  push:
+    branches: ["main"]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  crowdin-sync:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v6
+
+      - name: Sync Translations from Crowdin
+        uses: crowdin/github-action@v2
+        with:
+          download_translations: true
+          localization_branch_name: "l10n"
+          commit_message: "[skip ci] chore(i18n): sync translations from crowdin"
+          pull_request_title: "Sync Translations from Crowdin"
+          pull_request_body: "This is an automated pull request to sync translations from [Crowdin](https://crowdin.com/project/reactive-resume)."
+          pull_request_labels: "l10n"
+          pull_request_reviewers: "amruthpillai"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }}
+          CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}

.github/workflows/docker-build.yml

@@ -2,9 +2,6 @@ name: Build Docker Image
 
 on:
   workflow_dispatch:
-  push:
-    branches: ["main"]
-    tags: ["v*.*.*"]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -12,6 +9,7 @@ concurrency:
 
 env:
   IMAGE: ${{ github.repository }}
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
   build:
@@ -44,16 +42,16 @@ jobs:
         run: echo "version=$(jq -r .version package.json)" >> "$GITHUB_OUTPUT"
 
       - name: Setup Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4
 
       - name: Login to Docker Hub
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           username: ${{ secrets.DOCKER_USERNAME }}
           password: ${{ secrets.DOCKER_PASSWORD }}
 
       - name: Login to GitHub Container Registry
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -61,18 +59,17 @@ jobs:
 
       - name: Extract metadata (tags, labels) for Docker
         id: meta
-        uses: docker/metadata-action@v5
+        uses: docker/metadata-action@v6
         with:
           images: |
             ghcr.io/${{ env.IMAGE }}
             docker.io/${{ env.IMAGE }}
           tags: |
-            type=sha,format=short,suffix=-${{ matrix.arch }}
-            type=raw,value=v${{ steps.version.outputs.version }}-${{ matrix.arch }}
+            type=sha,prefix=sha-,suffix=-${{ matrix.arch }}
 
       - name: Build and Push by Digest
         id: build
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@v7
         with:
           context: .
           sbom: true
@@ -81,6 +78,7 @@ jobs:
           platforms: ${{ matrix.platform }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
+          annotations: ${{ steps.meta.outputs.annotations }}
           cache-from: type=gha,scope=${{ env.IMAGE }}-${{ matrix.arch }}
           cache-to: type=gha,mode=max,scope=${{ env.IMAGE }}-${{ matrix.arch }}
 
@@ -91,7 +89,7 @@ jobs:
           touch "/tmp/digests/${digest#sha256:}"
 
       - name: Upload digest
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: digests-${{ matrix.arch }}
           path: /tmp/digests/*
@@ -111,7 +109,7 @@ jobs:
 
     steps:
       - name: Checkout Repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           sparse-checkout: package.json
           sparse-checkout-cone-mode: false
@@ -121,55 +119,93 @@ jobs:
         run: echo "version=$(jq -r .version package.json)" >> "$GITHUB_OUTPUT"
 
       - name: Download digests
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
         with:
           path: /tmp/digests
           pattern: digests-*
           merge-multiple: true
 
       - name: Setup Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4
 
       - name: Login to Docker Hub
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           username: ${{ secrets.DOCKER_USERNAME }}
           password: ${{ secrets.DOCKER_PASSWORD }}
 
       - name: Login to GitHub Container Registry
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Parse version components
+        id: semver
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          MAJOR=$(echo "$VERSION" | cut -d. -f1)
+          MINOR=$(echo "$VERSION" | cut -d. -f2)
+
+          echo "major=$MAJOR" >> "$GITHUB_OUTPUT"
+          echo "minor=$MINOR" >> "$GITHUB_OUTPUT"
+
       - name: Extract metadata for Docker
         id: meta
-        uses: docker/metadata-action@v5
+        uses: docker/metadata-action@v6
         with:
           images: |
             ghcr.io/${{ env.IMAGE }}
             docker.io/${{ env.IMAGE }}
           tags: |
-            type=sha,format=short
+            type=sha,prefix=sha-
             type=raw,value=latest
             type=raw,value=v${{ steps.version.outputs.version }}
+            type=raw,value=v${{ steps.semver.outputs.major }}.${{ steps.semver.outputs.minor }}
+            type=raw,value=v${{ steps.semver.outputs.major }}
 
       - name: Create manifest list and push
+        id: manifest
         working-directory: /tmp/digests
         run: |
           set -euo pipefail
           docker buildx imagetools create \
             $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
+            --annotation "index:org.opencontainers.image.licenses=MIT" \
+            --annotation "index:org.opencontainers.image.title=Reactive Resume" \
+            --annotation "index:org.opencontainers.image.description=A free and open-source resume builder." \
+            --annotation "index:org.opencontainers.image.vendor=Amruth Pillai" \
+            --annotation "index:org.opencontainers.image.url=https://rxresu.me" \
+            --annotation "index:org.opencontainers.image.documentation=https://docs.rxresu.me" \
+            --annotation "index:org.opencontainers.image.source=https://github.com/amruthpillai/reactive-resume" \
+            --annotation "index:org.opencontainers.image.version=${{ steps.version.outputs.version }}" \
             $(printf 'ghcr.io/${{ env.IMAGE }}@sha256:%s ' *) \
             $(printf 'docker.io/${{ env.IMAGE }}@sha256:%s ' *)
 
+          # Get the digest of the multi-arch manifest
+          GHCR_DIGEST=$(docker buildx imagetools inspect ghcr.io/${{ env.IMAGE }}:v${{ steps.version.outputs.version }} --format '{{json .Manifest.Digest}}' | tr -d '"')
+          DOCKER_DIGEST=$(docker buildx imagetools inspect docker.io/${{ env.IMAGE }}:v${{ steps.version.outputs.version }} --format '{{json .Manifest.Digest}}' | tr -d '"')
+          echo "ghcr_digest=$GHCR_DIGEST" >> "$GITHUB_OUTPUT"
+          echo "docker_digest=$DOCKER_DIGEST" >> "$GITHUB_OUTPUT"
+
+      - name: Install Cosign
+        uses: sigstore/cosign-installer@v3
+
+      - name: Sign images with Cosign
+        run: |
+          # Sign GHCR image
+          cosign sign --yes ghcr.io/${{ env.IMAGE }}@${{ steps.manifest.outputs.ghcr_digest }}
+
+          # Sign Docker Hub image
+          cosign sign --yes docker.io/${{ env.IMAGE }}@${{ steps.manifest.outputs.docker_digest }}
+
       - name: Inspect image
         run: |
-          docker buildx imagetools inspect ghcr.io/${{ env.IMAGE }}:latest
+          docker buildx imagetools inspect ghcr.io/${{ env.IMAGE }}:v${{ steps.version.outputs.version }}
+          docker buildx imagetools inspect docker.io/${{ env.IMAGE }}:v${{ steps.version.outputs.version }}
 
-      - name: Redeploy Service
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+      - name: Redeploy Stack
         uses: appleboy/ssh-action@v1
         with:
           key: ${{ secrets.SSH_KEY }}
@@ -177,4 +213,4 @@ jobs:
           username: ${{ secrets.SSH_USER }}
           script: |
             cd docker
-            ./manage_stack.sh up reactive_resume
+            ./manage_stack.sh up reactive_resume

.gitignore

@@ -1,15 +1,54 @@
-dist
-.env*
-/data
-.nitro
+# Dependencies
+node_modules
+.pnpm-store
+
+# Build Outputs
 .output
 .vercel
-.cursor
-coverage
-.netlify
-.DS_Store
-.tanstack
-node_modules
+.wrangler
+
+# Environment Variables
+.env*
 !.env.example
-public/sw.js
-public/workbox-*.js
+
+# IDEs and Editors
+*~
+*.swp
+*.swo
+.DS_Store
+.idea
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+
+# Log Files
+logs
+*.log*
+
+# Turborepo
+.turbo
+
+# TanStack Start
+.tanstack
+
+# Testing
+coverage
+reports
+
+# Cache
+tmp
+temp
+.cache
+
+# AI
+.codex
+.claude
+.cursor
+.superpowers
+docs/superpowers
+
+# Local Storage Data
+/data
+/apps/web/data

.gitlab-ci.yml

@@ -1,48 +0,0 @@
-stages:
-  - build
-
-variables:
-  DOCKER_DRIVER: overlay2
-  DOCKER_TLS_CERTDIR: "/certs"
-
-build-and-push:
-  stage: build
-  image: docker:24
-  services:
-    - docker:24-dind
-  rules:
-    - if: $CI_COMMIT_BRANCH == "main"
-    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
-    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
-    - if: $CI_PIPELINE_SOURCE == "web"
-  before_script:
-    - apk add --no-cache jq
-    - echo "$CI_REGISTRY_PASSWORD" | docker login -u $CI_REGISTRY_USER --password-stdin $CI_REGISTRY
-    - |
-      export VERSION=$(jq -r .version package.json)
-      echo "VERSION=$VERSION" >> build.env
-  script:
-    - source build.env
-    - |
-      SHORT_SHA=$CI_COMMIT_SHORT_SHA
-      PRIMARY_TAG="$CI_REGISTRY_IMAGE:$SHORT_SHA"
-      
-      # Build the image
-      docker build -f ./Dockerfile -t $PRIMARY_TAG .
-      
-      # Tag with additional tags
-      docker tag $PRIMARY_TAG $CI_REGISTRY_IMAGE:latest
-      if [ -n "$VERSION" ] && [ "$VERSION" != "null" ]; then
-        docker tag $PRIMARY_TAG $CI_REGISTRY_IMAGE:v$VERSION
-      fi
-      
-      # Push all tags (only if not a merge request)
-      if [ "$CI_PIPELINE_SOURCE" != "merge_request_event" ]; then
-        docker push $PRIMARY_TAG
-        docker push $CI_REGISTRY_IMAGE:latest
-        if [ -n "$VERSION" ] && [ "$VERSION" != "null" ]; then
-          docker push $CI_REGISTRY_IMAGE:v$VERSION
-        fi
-      fi
-  after_script:
-    - docker logout $CI_REGISTRY || true

.ncurc.cjs

@@ -1,16 +1,14 @@
 // @ts-check
 
-const nextPackages = ["@monaco-editor/react"];
-
-const betaPackages = ["drizzle-orm", "drizzle-kit", "@better-auth/core", "@better-auth/passkey", "better-auth"];
+const betaPackages = ["drizzle-orm", "drizzle-kit", "drizzle-zod"];
 
 /** @type {import('npm-check-updates').RunOptions} */
 module.exports = {
 	upgrade: true,
+	workspaces: true,
 	install: "always",
 	packageManager: "pnpm",
 	target: (packageName) => {
-		if (nextPackages.includes(packageName)) return "@next";
 		if (betaPackages.includes(packageName)) return "@beta";
 		return "latest";
 	},

.planning/codebase/ARCHITECTURE.md

@@ -0,0 +1,332 @@
+<!-- refreshed: 2026-05-11 -->
+# Architecture
+
+**Analysis Date:** 2026-05-11
+
+## System Overview
+
+Reactive Resume is a single full-stack web application running as one Node.js process on port 3000. The web app is a TanStack Start application (Vite + React 19 + Nitro server) packaged in a pnpm/Turborepo monorepo. All API surface area, server-side rendering, file uploads, OAuth, OpenAPI, MCP, and PWA assets are served from the same process. Internal packages are consumed as TypeScript source through `package.json` `exports` maps that point directly at `src` files; there is no per-package `dist` output to depend on.
+
+```text
+┌────────────────────────────────────────────────────────────────────────────┐
+│                              Browser (React 19)                            │
+│  TanStack Router  ·  TanStack Query  ·  Zustand stores  ·  React PDF view  │
+│  `apps/web/src/router.tsx`  ·  `apps/web/src/routes/__root.tsx`            │
+└──────────┬─────────────────────────────────────────────────────┬───────────┘
+           │ HTTP / SSR hydration                                │ /api/rpc (RPCLink)
+           ▼                                                     ▼
+┌────────────────────────────────────────────────────────────────────────────┐
+│                  Nitro server entry (TanStack Start)                       │
+│           `apps/web/src/server.ts`  ·  Nitro plugins (`apps/web/plugins/`) │
+├──────────────────────────┬─────────────────────────────────────────────────┤
+│  File-based routes        │  Route `server.handlers` blocks               │
+│  `apps/web/src/routes/*` │  `api/rpc.$.ts` · `api/auth.$.ts` · `api/health.ts`│
+│                           │  `api/openapi.$.ts` · `api/uploads/$userId.$.ts`│
+│                           │  `mcp/index.ts` · `[.]well-known/*` · `schema.json.ts`│
+└──────────┬───────────────┴──────────────────────────────┬─────────────────┘
+           │ in-process router client                       │ HTTP handler
+           ▼                                                ▼
+┌────────────────────────────────────────────────────────────────────────────┐
+│                              oRPC routers                                  │
+│  `packages/api/src/routers/{ai,auth,flags,resume,statistics,storage}.ts`  │
+│  Procedures: `publicProcedure` / `protectedProcedure`                      │
+│  Middleware: `packages/api/src/middleware/rate-limit/index.ts`             │
+└──────────┬─────────────────────────────────────────────────────────────────┘
+           │
+           ▼
+┌────────────────────────────────────────────────────────────────────────────┐
+│                          Services & helpers                                │
+│  `packages/api/src/services/{resume,ai,auth,storage,flags,statistics}.ts` │
+│  `packages/api/src/helpers/{resume-access,resume-access-policy}.ts`        │
+│  `packages/api/src/services/resume-events.ts` (Postgres LISTEN/NOTIFY)     │
+│  `packages/auth/src/config.ts` (Better Auth)                               │
+└──────────┬──────────────────────────────────────┬──────────────────────────┘
+           │ Drizzle ORM                          │ S3 / local FS
+           ▼                                      ▼
+┌──────────────────────────────────┐   ┌──────────────────────────────────┐
+│      PostgreSQL (via `pg`)        │   │ Storage (S3 or `<workspace>/data`)│
+│  `packages/db/src/client.ts`     │   │  `packages/api/src/services/storage.ts`│
+│  schema: `packages/db/src/schema/*`│   │  served by `routes/uploads/$userId.$.tsx`│
+│  migrations: `migrations/`        │   └──────────────────────────────────┘
+└──────────────────────────────────┘
+```
+
+## Component Responsibilities
+
+| Component | Responsibility | File |
+|-----------|----------------|------|
+| Web app shell | TanStack Start app, route tree, SSR/CSR boundary, PWA, builder UI | `apps/web/src/router.tsx`, `apps/web/src/routes/__root.tsx` |
+| Server entry | Nitro fetch handler wrapping `react-start/server-entry` | `apps/web/src/server.ts` |
+| Migration plugin | Walks up to repo root, runs Drizzle migrations on boot | `apps/web/plugins/1.migrate.ts` |
+| Storage plugin | Validates `<workspace>/data` writability when S3 is unused | `apps/web/plugins/2.storage.ts` |
+| oRPC router root | Aggregates all sub-routers exposed at `/api/rpc` and OpenAPI | `packages/api/src/routers/index.ts` |
+| oRPC context | Header-based auth resolution, `publicProcedure`/`protectedProcedure` | `packages/api/src/context.ts` |
+| Resume service | CRUD, patch (RFC 6902), password, lock, statistics, analysis, events | `packages/api/src/services/resume.ts` |
+| Storage service | S3 + local FS abstraction, image processing via `sharp` | `packages/api/src/services/storage.ts` |
+| Resume access policy | Owner/viewer/redaction rules for `getBySlug` and statistics | `packages/api/src/helpers/resume-access-policy.ts` |
+| Resume events | Postgres `LISTEN/NOTIFY` channel for live updates | `packages/api/src/services/resume-events.ts` |
+| Auth | Better Auth config, OAuth provider, passkey, 2FA, API keys, JWKS | `packages/auth/src/config.ts` |
+| Database | Drizzle client singleton, schema, generated migrations | `packages/db/src/client.ts`, `packages/db/src/schema/*.ts`, `migrations/` |
+| Schema | Zod resume/page/template models shared across web + API + PDF + MCP | `packages/schema/src/resume/data.ts`, `packages/schema/src/templates.ts` |
+| PDF rendering | React PDF `Document`, font registration, 14 template implementations | `packages/pdf/src/document.tsx`, `packages/pdf/src/templates/index.ts`, `packages/pdf/src/hooks/use-register-fonts.ts` |
+| Shared UI | Base UI / shadcn-style component library and hooks | `packages/ui/src/components/*.tsx`, `packages/ui/src/hooks/*.tsx` |
+| MCP server | Model Context Protocol server backed by oRPC routers | `apps/web/src/routes/mcp/index.ts`, `apps/web/src/routes/mcp/-helpers/*` |
+
+## Pattern Overview
+
+**Overall:** Modular monolith. One deployable web app + a constellation of source-only TypeScript packages communicating through typed `package.json` `exports`. Browser ↔ server communication uses **oRPC** (typed RPC with REST/OpenAPI generation) instead of REST/tRPC. SSR and client share the same router/queryClient via TanStack Start.
+
+**Key Characteristics:**
+- Source-consumed workspace packages (no per-package `dist` build) keep types end-to-end.
+- The oRPC router is mounted twice: as a Fetch handler at `/api/rpc` and as an in-process `createRouterClient` for SSR/server functions, with identical types on both paths.
+- Browser-only code (React PDF preview, PDF.js, canvas) is isolated behind explicit `.browser.tsx` files and `ssr: false` / `ssr: "data-only"` route opts to keep SSR bundles small and safe.
+- Postgres is both the data store and the event bus (`pg_notify` channel `resume_updated` for live builder sync).
+- Shared concerns (auth, theme, locale, feature flags, oRPC client, query client) are loaded once and passed through TanStack Router `context` rather than fetched per-route.
+
+## Layers
+
+**Routes (`apps/web/src/routes/`):**
+- Purpose: File-based TanStack Router routes; some are pure UI, others embed `server.handlers` blocks that act as HTTP endpoints.
+- Location: `apps/web/src/routes/`
+- Contains: Page components, route loaders, server-only API handlers, layout wrappers.
+- Depends on: `packages/api/routers` (mounted at `/api/rpc`), `packages/auth/config` (mounted at `/api/auth`), `packages/db/client`, `packages/api/services/*`.
+- Used by: TanStack Router (route tree is regenerated into `apps/web/src/routeTree.gen.ts`).
+
+**oRPC API layer (`packages/api/src/routers/`):**
+- Purpose: Public typed contract for the browser, in-process callers, and OpenAPI/MCP consumers.
+- Location: `packages/api/src/routers/{ai,auth,flags,resume,statistics,storage}.ts`, aggregated in `packages/api/src/routers/index.ts`.
+- Contains: Procedure definitions, Zod input/output schemas, REST metadata, rate-limit middleware bindings.
+- Depends on: `packages/api/src/context.ts`, `packages/api/src/dto/*`, `packages/api/src/services/*`.
+- Used by: `apps/web/src/routes/api/rpc.$.ts` (RPCHandler), `apps/web/src/routes/api/openapi.$.ts` (OpenAPIHandler), `apps/web/src/libs/orpc/client.ts` (isomorphic client), MCP tools in `apps/web/src/routes/mcp/-helpers/tools.ts`.
+
+**Services / business logic (`packages/api/src/services/`):**
+- Purpose: All cross-cutting business rules — resume CRUD, statistics, AI orchestration, storage, feature flags, auth helpers, event publishing.
+- Location: `packages/api/src/services/*.ts`
+- Contains: Side-effecting functions with explicit `userId`-style inputs. No request/response coupling.
+- Depends on: `packages/db/client`, `packages/db/schema`, `packages/auth/config`, `packages/schema/resume/*`, `packages/utils/*`, `packages/email/transport`, AI SDKs.
+- Used by: Routers, MCP helpers, the `/api/health` route.
+
+**Persistence (`packages/db/`):**
+- Purpose: Drizzle ORM client + schema definitions; the only place SQL is written.
+- Location: `packages/db/src/client.ts`, `packages/db/src/schema/{auth,resume,index}.ts`, `packages/db/src/relations.ts`.
+- Contains: Postgres `Pool` singleton (stored on `globalThis.__pool` to survive HMR), `drizzle()` client, table definitions, relations.
+- Depends on: `pg`, `drizzle-orm`, `packages/env/server`.
+- Migrations: Generated by `drizzle-kit` into the repo-root `migrations/` directory (see `packages/db/drizzle.config.ts`) and applied at startup by `apps/web/plugins/1.migrate.ts`.
+
+**Auth (`packages/auth/`):**
+- Purpose: Better Auth instance with email/password, OAuth (Google/GitHub/LinkedIn + generic), passkey, 2FA, API keys, JWKS, and a JWT-issuing OAuth provider for MCP clients.
+- Location: `packages/auth/src/config.ts`, `packages/auth/src/functions.ts`, `packages/auth/src/types.ts`.
+- Mounted at: `apps/web/src/routes/api/auth.$.ts` (delegates `request → auth.handler(request)` after sanitizing OAuth params).
+- Verifies tokens for MCP at `apps/web/src/routes/mcp/index.ts` via `verifyOAuthToken`.
+
+**PDF rendering (`packages/pdf/`):**
+- Purpose: React PDF document and 14 visual templates (named after Pokémon).
+- Location: `packages/pdf/src/document.tsx` mounts `getTemplatePage(template)`; templates live under `packages/pdf/src/templates/<name>/`.
+- Shared template primitives: `packages/pdf/src/templates/shared/{filtering,rich-text,sections,primitives,picture,page-size,columns}.ts(x)`.
+- Fonts: `packages/pdf/src/hooks/use-register-fonts.ts` owns React PDF font registration, standard PDF font handling, CJK fallback stacks, and global hyphenation.
+- Consumed by: Web builder preview (`apps/web/src/components/resume/preview*.tsx`, `pdf-canvas.tsx`), public resume page (`apps/web/src/routes/$username/$slug.tsx`), and the OpenAPI `/resumes/{id}/download` procedure (`apps/web/src/routes/api/-helpers/resume-pdf.ts`).
+
+**Shared schemas (`packages/schema/`):**
+- Purpose: Zod source of truth for resume data, templates, page settings, and AI analysis.
+- Location: `packages/schema/src/resume/{data,default,sample,analysis}.ts`, `packages/schema/src/templates.ts`, `packages/schema/src/page.ts`, `packages/schema/src/icons.ts`.
+- Used by: API DTOs (`packages/api/src/dto/resume.ts`), DB column typing (`packages/db/src/schema/resume.ts`), import package, PDF rendering, web forms, MCP tool descriptions, and the public JSON schema at `/schema.json`.
+
+**Shared UI (`packages/ui/`):**
+- Purpose: Headless/styled component library (Base UI + shadcn-style) used by `apps/web`.
+- Location: `packages/ui/src/components/*.tsx`, `packages/ui/src/hooks/*.tsx`.
+- Examples: `dialog`, `dropdown-menu`, `command`, `resizable`, `sonner`, `tooltip`, `form`, `direction`.
+- Styles: `packages/ui/src/styles/globals.css` (Tailwind v4 entry).
+
+**Support packages:**
+- `packages/utils` — small focused helpers (`color`, `date`, `field`, `file`, `html`, `level`, `locale`, `network-icons`, `rate-limit`, `sanitize`, `string`, `style`, `url`, plus Node-only `monorepo.node`, `url-security.node`, and `resume/{docx,patch}`).
+- `packages/env` — `@t3-oss/env-core` server schema; `dotenv` loads the repo-root `.env` (`packages/env/src/server.ts`).
+- `packages/email` — `nodemailer` transport + `react-email` templates (`packages/email/src/transport.ts`, `packages/email/src/templates/*.tsx`).
+- `packages/import` — converters for JSON Resume, Reactive Resume v3/v4 JSON (`packages/import/src/*.tsx`).
+- `packages/ai` — Zustand store, AI prompts (`packages/ai/src/prompts/*.md`), patch-resume tool, sanitize/extraction helpers consumed by the AI router.
+- `packages/fonts` — generated Google Fonts metadata (`packages/fonts/src/webfontlist.json`, `packages/fonts/src/index.ts`).
+- `packages/scripts` — repo-level scripts (`packages/scripts/database/reset.ts`, `packages/scripts/fonts/generate.ts`).
+- `packages/config` — shared TypeScript/Vitest base configs (`packages/config/tsconfig.base.json`, `packages/config/vitest.config.ts`).
+- `packages/runtime-externals` — declares `bcrypt`, `sharp`, `@aws-sdk/client-s3` so they remain runtime-only (externalized in `apps/web/vite.config.ts`).
+
+## Data Flow
+
+### Primary Request Path (browser RPC call)
+
+1. Browser route uses `orpc.resume.getById.queryOptions(...)` from `apps/web/src/libs/orpc/client.ts:84` to fetch data.
+2. The isomorphic oRPC client (`apps/web/src/libs/orpc/client.ts:28-47`) creates an `RPCLink` pointing at `${window.location.origin}/api/rpc` with `credentials: "include"` and a `BatchLinkPlugin`.
+3. Request hits the file route `apps/web/src/routes/api/rpc.$.ts`, where `RPCHandler` (line 9) dispatches with `BatchHandlerPlugin`, `RequestHeadersPlugin`, and `StrictGetMethodPlugin`.
+4. `publicProcedure` (`packages/api/src/context.ts:79`) resolves the user from headers (`x-api-key` → bearer JWT via JWKS → Better Auth session cookie).
+5. `protectedProcedure` (`packages/api/src/context.ts:90`) rejects unauthenticated callers with `ORPCError("UNAUTHORIZED")`.
+6. Router handler in `packages/api/src/routers/resume.ts` calls into `packages/api/src/services/resume.ts`, which queries Drizzle (`packages/db/src/client.ts:32`).
+7. Response is serialized back through oRPC and consumed by TanStack Query / the route component.
+
+### SSR / Server-Side Path
+
+1. During SSR, `apps/web/src/libs/orpc/client.ts:13-27` short-circuits the HTTP path via `createRouterClient(router, { context: async () => ({ locale, reqHeaders }) })`.
+2. The same `publicProcedure`/`protectedProcedure` middleware runs in-process — no socket hop — but still resolves auth from the original request headers via `getRequestHeaders()` from `@tanstack/react-start/server`.
+3. Route loaders (e.g. `apps/web/src/routes/builder/$resumeId/route.tsx:39-44`) populate the query cache via `context.queryClient.ensureQueryData(orpc.resume.getById.queryOptions(...))`.
+
+### Resume Live-Update Flow
+
+1. `subscribe` procedure in `packages/api/src/routers/resume.ts:76` returns an async generator.
+2. On any mutation, `packages/api/src/services/resume-events.ts:37` calls `pg_notify('resume_updated', JSON.stringify(event))`.
+3. Subscribing clients receive `resume.updated` SSE-style events via oRPC streaming (`apps/web/src/libs/orpc/client.ts:51-82`, `streamClient`).
+4. The builder route consumes them through `useResumeUpdateSubscription` (`apps/web/src/components/resume/builder-resume-draft.ts`).
+
+### PDF Download Path
+
+1. Web client requests `GET /api/openapi/resumes/{id}/download` (oRPC OpenAPI handler at `apps/web/src/routes/api/openapi.$.ts`).
+2. `downloadResumePdfProcedure` in `apps/web/src/routes/api/-helpers/resume-pdf.ts` loads the resume, renders `ResumeDocument` from `packages/pdf/src/document.tsx`, persists to storage via `getStorageService()`, and returns/streams the PDF.
+
+### Public Resume Path
+
+1. `apps/web/src/routes/$username/$slug.tsx` uses `ssr: "data-only"` — server fetches `resume.getBySlug` but renders the React PDF preview only on the client.
+2. `packages/api/src/helpers/resume-access-policy.ts` enforces visibility, redacts non-public fields, and throws `NEED_PASSWORD` for password-protected resumes (the route then redirects to `/auth/resume-password`).
+
+**State Management:**
+- Server cache: TanStack Query (`apps/web/src/libs/query/client.ts`) wrapped by oRPC's `createTanstackQueryUtils`.
+- Local UI state: Zustand stores under `apps/web/src/routes/builder/$resumeId/-store/{section,sidebar}.ts`, `apps/web/src/dialogs/store.ts`, `apps/web/src/components/command-palette/store.ts`, `apps/web/src/components/resume/builder-resume-draft.ts`.
+- Router context: `theme`, `locale`, `session`, `flags`, `queryClient`, `orpc` are computed once in `apps/web/src/router.tsx` (and again in the root route `beforeLoad`) and reused by descendants.
+- Cookies: builder layout (`BUILDER_LAYOUT_COOKIE_NAME`), theme, and locale are persisted via `getCookie`/`setCookie` server functions.
+
+## Key Abstractions
+
+**oRPC procedures (`os.$context<ORPCContext>()`):**
+- Purpose: Typed RPC procedures that double as REST endpoints and MCP tool surfaces.
+- Examples: `publicProcedure` and `protectedProcedure` in `packages/api/src/context.ts:79`/`:90`.
+- Pattern: `procedure.route({...openapi metadata}).input(zodSchema).use(rateLimitMiddleware).output(zodSchema).handler(async ({ context, input }) => ...)`.
+
+**Drizzle tables:**
+- Purpose: Strongly-typed Postgres schema; `.jsonb()` columns are typed against Zod-derived TypeScript (`ResumeData`, `StoredResumeAnalysis`).
+- Examples: `packages/db/src/schema/resume.ts` (resume, resumeStatistics, resumeAnalysis), `packages/db/src/schema/auth.ts` (Better Auth tables).
+- Pattern: `pg.pgTable("name", { ... }, (t) => [pg.index().on(...), pg.unique().on(...)])`.
+
+**Template pages (React PDF):**
+- Purpose: One `TemplatePage` component per visual template, mapped by name in `packages/pdf/src/templates/index.ts`.
+- Examples: `packages/pdf/src/templates/azurill/AzurillPage.tsx`, `packages/pdf/src/templates/onyx/OnyxPage.tsx`.
+- Pattern: `(props: { page: LayoutPage; pageIndex: number }) => JSX`, consuming `RenderProvider` from `packages/pdf/src/context.tsx`.
+
+**Base UI components:**
+- Purpose: Headless primitives styled with Tailwind v4 and exported as composable parts.
+- Examples: `packages/ui/src/components/dialog.tsx`, `packages/ui/src/components/command.tsx`, `packages/ui/src/components/resizable.tsx`.
+- Imported via deep paths: `import { Dialog } from "@reactive-resume/ui/components/dialog";`.
+
+**TanStack Router file routes:**
+- Purpose: Page components, loaders, and optional `server.handlers` blocks per file.
+- Examples: `apps/web/src/routes/builder/$resumeId/route.tsx`, `apps/web/src/routes/api/rpc.$.ts`.
+- Pattern: `export const Route = createFileRoute("/path")({ component, loader, beforeLoad, server: { handlers: { GET, POST } }, ssr });`.
+
+## Entry Points
+
+**Vite + Nitro build entry:**
+- Location: `apps/web/vite.config.ts`
+- Triggers: `pnpm dev`, `pnpm build`. Wires TanStack Start, Tailwind v4, Lingui (i18n), Nitro plugins, and the Vite PWA plugin.
+- Externals: `bcrypt`, `sharp`, `@aws-sdk/client-s3` (declared in `packages/runtime-externals`).
+
+**Server fetch entry:**
+- Location: `apps/web/src/server.ts`
+- Responsibilities: Wraps `@tanstack/react-start/server-entry` and substitutes `srvx`'s `FastResponse` as the global `Response`.
+
+**Nitro startup plugins:**
+- `apps/web/plugins/1.migrate.ts` — resolves the repo-root `migrations/` folder, opens its own `pg.Pool`, runs Drizzle migrations on boot, then closes the pool.
+- `apps/web/plugins/2.storage.ts` — when S3 env vars are absent, ensures the local storage directory is writable before serving requests.
+
+**Router entry:**
+- Location: `apps/web/src/router.tsx`
+- Responsibilities: Builds `queryClient`, loads `theme`/`locale`/`session`/`flags` in parallel, creates the TanStack Router with router context, registers SSR query integration.
+
+**Root route:**
+- Location: `apps/web/src/routes/__root.tsx`
+- Responsibilities: HTML shell, providers (`I18nProvider`, `ThemeProvider`, `HotkeysProvider`, `DirectionProvider`, `TooltipProvider`, `ConfirmDialogProvider`, `PromptDialogProvider`), PWA head/scripts, `DialogManager`, `CommandPalette`, `Toaster`.
+
+**HTTP endpoints (route `server.handlers`):**
+- `apps/web/src/routes/api/rpc.$.ts` — `/api/rpc/*` oRPC handler (browser RPC).
+- `apps/web/src/routes/api/auth.$.ts` — `/api/auth/*` Better Auth handler (with OAuth payload sanitization).
+- `apps/web/src/routes/api/health.ts` — `/api/health` JSON probe (db + storage with timeouts).
+- `apps/web/src/routes/api/openapi.$.ts` — `/api/openapi/*` OpenAPI handler + spec.
+- `apps/web/src/routes/api/uploads/$userId.$.ts` and `apps/web/src/routes/uploads/$userId.$.tsx` — signed/etagged static file serving from storage.
+- `apps/web/src/routes/mcp/index.ts` — `/mcp` Model Context Protocol server (OAuth-protected).
+- `apps/web/src/routes/[.]well-known/*` — `/.well-known/oauth-authorization-server`, `/.well-known/oauth-protected-resource`, `/.well-known/openid-configuration`, `/.well-known/mcp` discovery documents.
+- `apps/web/src/routes/schema[.]json.ts` — `/schema.json` public JSON Schema for `ResumeData`.
+
+**Builder + public resume entry points:**
+- `apps/web/src/routes/builder/$resumeId/route.tsx` — authenticated builder shell (header + resizable left/right sidebars + artboard outlet + assistant).
+- `apps/web/src/routes/builder/$resumeId/index.tsx` — `ssr: false`; lazy-loaded `PreviewPage` running React PDF/canvas only in the browser.
+- `apps/web/src/routes/$username/$slug.tsx` — `ssr: "data-only"`; public/shared resume view (with password gating via `NEED_PASSWORD` ORPCError).
+
+## Architectural Constraints
+
+- **Single Node process:** Everything (web, oRPC, auth, MCP, OpenAPI, file serving) runs in one Node 24 process on port 3000. No separate API service.
+- **Source-only workspace packages:** `package.json` `exports` point at `src/*.ts(x)`; do not assume `dist` output exists. The Vite build externalizes `bcrypt`, `sharp`, `@aws-sdk/client-s3` (`apps/web/vite.config.ts:55`).
+- **Globals on `globalThis` for DB pool:** `packages/db/src/client.ts:8-11` caches the `pg.Pool` and Drizzle client on `globalThis.__pool` / `globalThis.__drizzle` to survive HMR reloads.
+- **Browser-only PDF rendering:** PDF.js, `@react-pdf/renderer` canvas, and the builder preview must stay off the SSR path. Use `.browser.tsx` suffix files and `ssr: false` (builder preview) or `ssr: "data-only"` (public resume).
+- **Generated route tree:** `apps/web/src/routeTree.gen.ts` is regenerated by TanStack Router tooling; never edit by hand.
+- **Migrations folder location:** `drizzle-kit` writes to `../../migrations` from `packages/db/drizzle.config.ts`, so all migration directories live at the repo root, not inside the package.
+- **DATABASE_URL not auto-loaded for drizzle-kit:** `pnpm db:migrate` / `pnpm db:generate` require `DATABASE_URL` exported in the shell; only the runtime Node code loads `.env` via `packages/env/src/server.ts`.
+- **Rate limiting is production-only:** `packages/api/src/middleware/rate-limit/index.ts:5` and the Better Auth config gate rate limits on `process.env.NODE_ENV === "production"`.
+- **OAuth audience binding:** `verifyOAuthToken` (`packages/auth/src/config.ts:40`) only accepts JWTs whose `aud` matches `${APP_URL}` (with/without trailing slash) or `${APP_URL}/mcp`.
+- **Postgres LISTEN/NOTIFY coupling:** Live resume updates depend on a single shared `pg.Pool` (`packages/db/src/client.ts:13`); scaling beyond one process requires replacing `pg_notify` with a broker.
+
+## Anti-Patterns
+
+### Ad-hoc fetching of router context
+
+**What happens:** Components separately calling `getSession()`, `getTheme()`, or `getLocale()` instead of reading them from TanStack Router context.
+**Why it's wrong:** The root route's `beforeLoad` already loads these in parallel (`apps/web/src/routes/__root.tsx:82-93`) and exposes them via `Route.useRouteContext()`; duplicating the calls causes extra round-trips during SSR and triggers locale reloads.
+**Do this instead:** Use `Route.useRouteContext()` or read from a parent route loader, as `apps/web/src/routes/__root.tsx:101` does for theme/locale.
+
+### Direct DB or storage imports in client code
+
+**What happens:** Importing `@reactive-resume/db/client` or `@reactive-resume/api/services/storage` from a non-route component.
+**Why it's wrong:** Pulls `pg`, `sharp`, `bcrypt`, `@aws-sdk/client-s3` into the client bundle (which Vite externalizes — the build will fail or break at runtime).
+**Do this instead:** Call the corresponding oRPC procedure from `packages/api/src/routers/*`. Server-only imports belong inside route `server.handlers` blocks or `.server.tsx` files like `apps/web/src/libs/resume/pdf-document.server.tsx`.
+
+### PDF/canvas code in shared modules
+
+**What happens:** Importing `@react-pdf/renderer` or PDF.js from a file that participates in SSR.
+**Why it's wrong:** These libraries crash under Node SSR (canvas/DOM dependencies).
+**Do this instead:** Keep browser code in `*.browser.tsx` / `pdf-canvas.tsx` and gate with `ssr: false` (e.g. `apps/web/src/routes/builder/$resumeId/index.tsx:6`) or `ssr: "data-only"` (e.g. `apps/web/src/routes/$username/$slug.tsx:40`).
+
+### Bypassing the resume access policy
+
+**What happens:** Reading resume rows directly from Drizzle in a public procedure without applying redaction.
+**Why it's wrong:** Leaks owner-only fields (password hash, private flags, statistics) and breaks the password-gate flow that depends on `NEED_PASSWORD` errors.
+**Do this instead:** Route through `packages/api/src/helpers/resume-access-policy.ts` (`assertCanView`, `redactResumeForViewer`, `shouldCountForStatistics`) as `packages/api/src/services/resume.ts` does.
+
+### Hand-editing generated files
+
+**What happens:** Modifying `apps/web/src/routeTree.gen.ts` or migration SQL after Drizzle writes it.
+**Why it's wrong:** Edits are overwritten on the next `tanstack-router` regen or migration; data drift between snapshots and SQL breaks future migrations.
+**Do this instead:** Add a route file under `apps/web/src/routes/`, or change the Drizzle schema in `packages/db/src/schema/*.ts` and run `pnpm db:generate`.
+
+## Error Handling
+
+**Strategy:** Typed errors via `ORPCError` codes; HTTP responses for low-level handlers; route-level `defaultErrorComponent` and `onError` for UI fallbacks.
+
+**Patterns:**
+- Procedures throw `ORPCError("UNAUTHORIZED"|"NOT_FOUND"|"NEED_PASSWORD"|...)` or use `.errors({ ... })` to declare typed application errors (e.g. `RESUME_SLUG_ALREADY_EXISTS`, `RESUME_VERSION_CONFLICT` in `packages/api/src/routers/resume.ts`).
+- The OAuth bearer / API key / session resolvers in `packages/api/src/context.ts:14-55` swallow verification errors and log via `console.warn` so unauthenticated requests fall through to the next strategy.
+- `apps/web/src/routes/api/rpc.$.ts` and `apps/web/src/routes/api/openapi.$.ts` install `onError` interceptors that log every server error with a tag (`[oRPC Server]`, `[OpenAPI]`).
+- Route-level `onError` (e.g. `apps/web/src/routes/$username/$slug.tsx:24`) translates `NEED_PASSWORD` into a redirect.
+- Top-level UI fallbacks: `apps/web/src/components/layout/error-screen.tsx`, `loading-screen.tsx`, `not-found-screen.tsx` (wired in `apps/web/src/router.tsx:30-32`).
+- Healthcheck uses a 1.5s timeout helper (`apps/web/src/routes/api/health.ts:22-34`) so a stuck dependency cannot stall the probe.
+
+## Cross-Cutting Concerns
+
+**Logging:** `console.info`/`console.warn`/`console.error` with bracketed prefixes (e.g. `[oRPC Server]`, `[Healthcheck]`, `[oRPC client]`). No external log shipping is wired.
+
+**Validation:** Zod 4 everywhere — Drizzle column types (`packages/db/src/schema/resume.ts`), oRPC input/output schemas, AI tool inputs, environment variables (`packages/env/src/server.ts`), and the public `/schema.json` route.
+
+**Authentication:** Better Auth in `packages/auth/src/config.ts` (Drizzle adapter, email/password + OAuth + passkey + 2FA + admin + API keys + JWT + generic OAuth + dynamic client registration + custom `oauthProvider` for MCP). The unified resolver in `packages/api/src/context.ts:64` is the only place that decides which credential wins.
+
+**Internationalization:** Lingui — `apps/web/lingui.config.ts`, `apps/web/locales/*.po`, `apps/web/src/libs/locale.ts`, RTL toggling in `__root.tsx`.
+
+**Theming:** `apps/web/src/libs/theme.ts` (cookie-backed), `apps/web/src/components/theme/provider.tsx` (`next-themes`).
+
+**Rate limiting:** `@orpc/experimental-ratelimit` with an in-memory ratelimiter from `packages/api/src/middleware/rate-limit/index.ts`. Trusted IP headers come from `packages/utils/src/rate-limit.ts`.
+
+**Feature flags:** Server-resolved at boot (`packages/api/src/routers/flags.ts` and `packages/api/src/services/flags.ts`), then carried in router context via `apps/web/src/router.tsx:20`.
+
+---
+
+*Architecture analysis: 2026-05-11*

.planning/codebase/CONCERNS.md

@@ -0,0 +1,393 @@
+# Codebase Concerns
+
+**Analysis Date:** 2026-05-11
+
+## TODO / FIXME / HACK / XXX Comments
+
+A repo-wide grep for `TODO`, `FIXME`, `HACK`, and `XXX` markers across `apps/web/src/**` and `packages/**` returned **zero hits** in source code. The team appears to track follow-ups in PRs/issues rather than inline. Two referenced issues remain anchored in inline comments:
+
+- `packages/pdf/src/hooks/use-register-fonts.ts:22` — references issue `#2986` (CJK glyph-level font fallback).
+- `packages/pdf/src/hooks/use-register-fonts.ts:103` — references issue `#2986` again for CJK textkit substitution.
+
+These are stable design references, not unresolved debt — included for traceability only.
+
+The remaining inline-comment "concerns" found during exploration sit in the **Anti-debt narrative** below, derived from code shape rather than comment markers.
+
+---
+
+## High Severity
+
+### Security: SMTP-disabled fallback logs full email bodies (incl. verification/reset links)
+
+When `SMTP_HOST` / `SMTP_USER` / `SMTP_PASS` / `SMTP_FROM` are not all set, the email transport logs the entire payload — including `text` and `html` bodies — to `stdout`.
+
+- File: `packages/email/src/transport.ts:59-66`
+
+```ts
+console.info("SMTP not configured; skipping email send.", {
+    to: payload.to,
+    subject: payload.subject,
+    text: payload.text,
+    html: payload.html,
+});
+```
+
+**Impact:**
+- Password reset, email verification, and email-change confirmation URLs (which are credential-equivalent bearer tokens) are written to server logs whenever SMTP is not fully configured.
+- In any shared-log / log-shipping environment (Docker, Kubernetes, journald, cloud logging) this is a credential leak.
+- The README and `AGENTS.md:101` describe this as a dev convenience; nothing prevents an operator from running production with partial SMTP config.
+
+**Fix approach:**
+1. Add a server-startup assertion that, if `NODE_ENV === "production"`, `isSmtpEnabled()` must be true.
+2. Redact `text` / `html` from the `console.info` call — log only `to` and `subject`.
+3. Document the production SMTP requirement in `.env.example` alongside `AUTH_SECRET`.
+
+### Security: rate limiting is silently disabled in non-production
+
+Both the oRPC rate-limit middleware and Better Auth's rate-limit config gate on `process.env.NODE_ENV === "production"`. Anything that does not set `NODE_ENV=production` at runtime (default `node` invocation, custom Docker entrypoints that forget to set it, self-hosters running `pnpm start` without `NODE_ENV`) runs with **all rate limiting disabled**, including:
+- `/sign-in/email`, `/sign-up/email`, password-reset, OAuth `register`/`authorize`/`token` (`packages/auth/src/config.ts:30, :69-78, :249-251, :388-390`)
+- Resume password verification, AI calls, PDF export, storage uploads/deletes, resume mutations (`packages/api/src/middleware/rate-limit/index.ts:5, :75`)
+
+**Impact:** brute-force-friendly. A self-hosted deployment that omits `NODE_ENV=production` is wide open on auth and resume-password endpoints.
+
+**Fix approach:**
+- Either default `isRateLimitEnabled = true` and provide a `RATE_LIMIT_DISABLED` opt-out env var, or assert `NODE_ENV === "production"` at boot when not running tests.
+
+### Security: rate limiter is in-process memory only — broken under horizontal scaling
+
+`MemoryRatelimiter` is used for every oRPC rate limit (`packages/api/src/middleware/rate-limit/index.ts:59-66`). Better Auth's `rateLimit` and `apiKey.rateLimit` blocks (`packages/auth/src/config.ts:248-251, :387-391`) similarly do not configure a distributed store.
+
+**Impact:** Running >1 Node instance behind a load balancer multiplies the effective rate limit by the instance count. Brute-force attacks bypass the limit by retrying until they hit a different replica.
+
+**Fix approach:** Swap `MemoryRatelimiter` for a Redis-backed ratelimiter (the package supports it via `@orpc/experimental-ratelimit`) once a redis dependency is acceptable. Until then, document the single-instance constraint in the deployment docs.
+
+### Security: file upload accepts arbitrary MIME with image processing disabled
+
+`uploadFile` (`packages/api/src/routers/storage.ts:42-71`) only runs the sharp image-processing pipeline for files where `isImageFile(file.type)` returns true based on the **client-supplied `file.type`**, and even that pipeline is skipped if `FLAG_DISABLE_IMAGE_PROCESSING=true` (`packages/api/src/services/storage.ts:96-101`).
+
+**Impact:**
+- A client can claim `content-type: text/html` (or any non-image MIME) on a 10 MB upload, and the file is stored verbatim into `uploads/{userId}/pictures/...` with the user-claimed content type.
+- Served back from `apps/web/src/routes/uploads/$userId.$.tsx`. `X-Content-Type-Options: nosniff` is set (`:159`) and the storage route forces `application/octet-stream` only for `.pdf` (`:39, :148-153`), so a stored HTML body could be served as HTML if the inferred extension matches. The picture key always ends in `.jpeg` (`storage.ts:60`), which mitigates this in the picture path, but there is no MIME allow-list enforced at upload time.
+- With `FLAG_DISABLE_IMAGE_PROCESSING` on, the same applies to genuine images (no resize/strip-metadata path), so EXIF data is preserved unredacted.
+
+**Fix approach:**
+1. Add a strict allow-list at the router boundary (`packages/api/src/routers/storage.ts:9`) — `z.file().mime(["image/png", "image/jpeg", "image/webp", "image/gif"])` plus magic-byte validation.
+2. Reject upload if claimed MIME does not match the sharp-detected MIME; do not fall back to client claim.
+3. Surface a startup warning when `FLAG_DISABLE_IMAGE_PROCESSING=true` so it is not enabled in production unknowingly.
+
+### Tech Debt: web app has near-zero test coverage
+
+- `apps/web/src` has **11 test files** across **~224 source files** (~5%) — `find apps/web/src -name "*.test.*"`.
+- `apps/web/src/routes` has **1 test file** across **125 route files** (`apps/web/src/routes/builder/$resumeId/-components/donation-toast.test.tsx`).
+- Total repo: ~93 test files / ~385 source files (~24%). Most coverage lives in `packages/ui`, `packages/utils`, `packages/pdf/src/templates/shared`, and `packages/api` (5 tests).
+
+**Impact:**
+- Refactors to routes, builder shell, sidebar forms, resume preview wiring, MCP tools, and uploads handler land without a regression net.
+- Particularly thin: `apps/web/src/routes/api/**` (rpc, auth, openapi, mcp, uploads) and `apps/web/src/routes/builder/$resumeId/**`.
+
+**Fix approach:** Phase-by-phase, add server-handler integration tests for `api/health.ts`, `api/auth.$.ts` (registration-validation path), `uploads/$userId.$.tsx` (path traversal), and at least smoke tests around the builder store in `apps/web/src/components/resume/builder-resume-draft.ts`.
+
+---
+
+## Medium Severity
+
+### Fragile: PDF.js / canvas SSR boundary is enforced by convention only
+
+The SSR/CSR split for the resume preview is hand-maintained:
+
+- `apps/web/src/components/resume/preview.tsx:14` returns `null` until `useIsClient()` resolves and then lazy-loads the browser bundle.
+- `apps/web/src/components/resume/preview.browser.tsx:2` imports `@react-pdf/renderer` (`pdf`).
+- `apps/web/src/components/resume/pdf-canvas.tsx:1, :4, :9` imports PDF.js types/runtime and sets a module-level `GlobalWorkerOptions.workerSrc`.
+- `apps/web/src/routes/templates/$.tsx:1` imports `PDFViewer` at the **top level** but the route component itself bails on `!isClient`. Top-level import means the bundle reaches the SSR chunk; correctness relies on the import being tree-shaken away when SSR runs.
+- `apps/web/src/routes/dashboard/resumes/-components/cards/resume-thumbnail.tsx` uses dynamic `await import("pdfjs-dist")` — a different convention from `pdf-canvas.tsx`'s static import.
+- SSR mode hints: `apps/web/src/routes/builder/$resumeId/index.tsx:4` (`ssr: false`), `apps/web/src/routes/$username/$slug.tsx` (`ssr: "data-only"`).
+
+**Impact:** A future contributor adding a static PDF.js import inside a SSR-rendered route component will break SSR with a `window is not defined` error at build/run time. There is no lint rule or build-time guard enforcing this.
+
+**Fix approach:**
+1. Document the boundary explicitly at the top of `apps/web/src/components/resume/preview.tsx` and `pdf-canvas.tsx` (currently only described in `AGENTS.md:35`).
+2. Consider a Vite SSR-externals config that aborts the build if `pdfjs-dist` / `@react-pdf/renderer` is reachable from an SSR-eligible route.
+3. Switch `apps/web/src/routes/templates/$.tsx:1` to a dynamic `import("@react-pdf/renderer")` inside the `useIsClient()` branch for consistency with the rest of the preview pipeline.
+
+### Fragile: `getStorageService()` is captured at module load in router
+
+`packages/api/src/routers/storage.ts:7` calls `getStorageService()` at module top level. Because `apps/web/src/routes/api/rpc.$.ts` constructs a new `RPCHandler` on every request, the router's storage reference is fixed for the lifetime of the Node process.
+
+**Impact:** Switching backends (e.g. flipping S3 vars on at runtime) requires a process restart, which is normally fine — but the singleton is also held inside Nitro's HMR boundary in dev, so config changes during `pnpm dev` need a full restart (not just a save).
+
+**Fix approach:** Call `getStorageService()` inside each handler instead, or invalidate the cached service when env values change.
+
+### Fragile: `RPCHandler` instantiated per-request
+
+`apps/web/src/routes/api/rpc.$.ts:8-16` creates a new `RPCHandler` (with plugins) for every incoming request. Each instance re-walks the router tree and re-constructs plugin pipelines.
+
+**Impact:** Measurable per-request cost on high-RPS dashboards; not catastrophic but unnecessary.
+
+**Fix approach:** Move `new RPCHandler(...)` out of the handler and reuse a module-level instance; only `getLocale()` should run per-request.
+
+### Performance: PDF preview regenerates entire PDF on every change
+
+`apps/web/src/components/resume/preview.browser.tsx:103-131` debounces PDF generation by 100ms and calls `pdf(resumeDocument).toBlob()` on every resume change. For multi-page resumes with images, this re-renders the full document and re-loads it into PDF.js.
+
+**Impact:** Builder feels sluggish on slower hardware when typing into fields; CPU spikes on each keystroke after debounce.
+
+**Mitigation in place:** `UPDATE_DEBOUNCE_MS = 100`, crossfade between staged/active layers (`:20-80`).
+
+**Fix approach:** Long-term, switch to incremental rendering or page-level memoization keyed by section hash. Short-term, raise debounce to 200–300 ms while typing.
+
+### Performance: font registration cost
+
+`packages/pdf/src/hooks/use-register-fonts.ts:18, :86` keeps a module-level `registeredFontVariants` Set keyed by `family:weight:style`. Per-resume registration calls `Font.register` once per (family × weight × italic × CJK-fallback) combination, with web-font fetches resolved through `getWebFontSource`. This Set never expires — if many resumes with different typography are previewed in one session, the registered-font count grows for the page lifetime.
+
+**Impact:** Memory grows in the builder for sessions that switch typography frequently. Not a leak in the GC sense, but bounded only by the size of the registered-font universe.
+
+**Fix approach:** Acceptable for current usage. Document the cap and reconsider if typography switching becomes more common.
+
+### Performance: large source files hint at oversized modules
+
+Top offenders by line count (excluding generated/test fixtures):
+
+| Lines | File |
+|------:|------|
+| 1535 | `packages/schema/src/icons.ts` (static data) |
+| 1088 | `apps/web/src/routes/builder/$resumeId/-components/assistant.tsx` |
+|  900 | `packages/pdf/src/templates/shared/sections.tsx` |
+|  789 | `apps/web/src/components/input/rich-input.tsx` |
+|  785 | `packages/import/src/reactive-resume-v4-json.tsx` |
+|  685 | `packages/ui/src/components/sidebar.tsx` |
+|  556 | `apps/web/src/routes/builder/$resumeId/-sidebar/left/sections/picture.tsx` |
+|  543 | `packages/api/src/services/resume.ts` |
+
+`assistant.tsx` (1088 lines) and `sections.tsx` (900 lines) are particularly likely to accumulate further complexity without splitting. `rich-input.tsx` (789 lines) is the rich-text editor — likely justifies its size but has zero direct tests.
+
+**Fix approach:** Split `assistant.tsx` along tool boundaries; extract per-section renderers from `sections.tsx` if any individual section grows further.
+
+### Security: `verifyPassword` rate limit keyed by `username:slug:ip`
+
+`packages/api/src/middleware/rate-limit/index.ts:77-83` keys the resume-password limiter on `resume-password:{username}:{slug}:{clientKey}` where `clientKey` is the client IP. The window/max is 5 attempts per 10 minutes (`packages/utils/src/rate-limit.ts:43`). This is reasonable, but the global Better Auth global rule for `/two-factor/verify-otp` is also 5 per 600s. An attacker on a botnet (different IPs) is not blocked at the resource level — each IP gets its own 5/10min budget against the same resume.
+
+**Impact:** Limited but present brute-force surface on password-protected public resumes.
+
+**Fix approach:** Add a per-resume global cap on top of the per-IP limit (e.g. 50/hour per `username:slug` regardless of IP).
+
+### Security: `as string` cast on password hash
+
+`packages/api/src/services/resume.ts:487` casts `resume.password` to `string` after a `isNotNull(schema.resume.password)` WHERE clause. The cast is correct in context, but if a future refactor drops the `isNotNull` guard the cast silently allows `null` through `bcrypt.compare`.
+
+**Fix approach:** Replace `as string` with a runtime `if (!resume.password) throw new ORPCError(...)` check.
+
+### Security: trust of `TRUSTED_IP_HEADERS` is unconditional
+
+`packages/utils/src/rate-limit.ts:1-7` defines a list of trusted IP headers (`CF-Connecting-IP`, `True-Client-IP`, `X-Forwarded-For`, etc.) that the rate limiter and Better Auth (`packages/auth/src/config.ts:276`) honour from any caller.
+
+**Impact:** If the app is deployed without a proxy that strips client-supplied versions of these headers, any client can spoof their rate-limit identity by setting `X-Forwarded-For: 1.2.3.4`.
+
+**Fix approach:** Document that operators **must** terminate at a trusted proxy (Cloudflare, nginx, Caddy) that strips inbound `X-Forwarded-For` / `X-Real-IP`. Optionally, add a `TRUST_PROXY` env flag and only honour those headers when set.
+
+### Fragile: `cachedTransport` in `email/transport.ts` ignores env mutation
+
+`packages/email/src/transport.ts:21-37` caches the nodemailer transport on first use. If SMTP creds change at runtime (e.g. credential rotation in a deployed instance), the cached transport keeps using the stale credentials until the process restarts.
+
+**Fix approach:** Detect cred changes and rebuild, or document the restart-on-rotation behaviour.
+
+### Storage gotcha: statistics cache is filesystem-bound even with S3 configured
+
+`packages/api/src/services/statistics.ts:21-52` caches user/resume/star counts as files in `getLocalDataDirectory(env.LOCAL_STORAGE_PATH)` regardless of whether S3 is enabled.
+
+**Impact:** When S3 is configured and `LOCAL_STORAGE_PATH` is on ephemeral storage (e.g. container scratch), the cache is recreated on every redeploy — meaning a cold start always queries the DB / GitHub API rather than re-using the cache. Also breaks horizontal scaling — each replica has its own cache file.
+
+**Fix approach:** Cache via the configured storage service (`getStorageService`) instead of raw `fs`, or move to an in-memory + TTL cache.
+
+---
+
+## Low Severity
+
+### Tech Debt: generated file you must not edit
+
+`apps/web/src/routeTree.gen.ts` (983 lines, `eslint-disable`, `@ts-nocheck` at top) is auto-generated by TanStack Router. It is correctly excluded from Biome (`biome.json:14`) and noted in `AGENTS.md:31`.
+
+**Action required of contributors:** Never hand-edit. Regenerate by running `pnpm dev` (TanStack tooling watches `apps/web/src/routes/**`).
+
+### Tech Debt: dev workflow — `pnpm check` is write-capable
+
+`package.json:20` defines `"check": "biome check --write --unsafe ."`. Running `pnpm check` will modify files. The lefthook pre-commit (`lefthook.yml:7-9`) runs the same command on staged files only, and `stage_fixed: true` re-stages them.
+
+**Impact:** Surprise file modifications when a contributor runs `pnpm check` expecting a non-mutating audit.
+
+**Fix approach:** Add a parallel `pnpm check:ci` (no `--write`) for inspection, and document the distinction (already covered in `AGENTS.md:103`).
+
+### Tech Debt: dev gotcha — `drizzle-kit` does not auto-load `.env`
+
+`packages/db/drizzle.config.ts:8` reads `process.env.DATABASE_URL || ""`. The `@reactive-resume/env` package auto-loads `.env` via dotenv (`packages/env/src/server.ts:9-11`), but `drizzle-kit` runs as a separate process that does not import `@reactive-resume/env`.
+
+**Impact:** Fresh `pnpm db:migrate` silently fails with an empty connection string unless `DATABASE_URL` is exported in the shell. Documented in `AGENTS.md:58, :79-80`.
+
+**Fix approach:** Either import the env package from `drizzle.config.ts` to inherit the `.env` load, or wrap the script with a one-liner that exports `DATABASE_URL`.
+
+### Tech Debt: Nitro plugin auto-runs migrations on dev/prod boot
+
+`apps/web/plugins/1.migrate.ts:23-40` runs migrations on every Nitro startup. This is convenient but couples app-boot health to migration health.
+
+**Impact:**
+- A bad migration takes down the whole web service on boot, not just future migration runs.
+- Two app instances starting concurrently both call `migrate()`; Drizzle's `migrations` table uses transactions to avoid duplicate apply, but the race adds startup latency.
+- For prod self-hosters, there is no "boot-without-migrate" knob.
+
+**Fix approach:** Gate on an env flag (e.g. `RUN_MIGRATIONS_ON_BOOT=true`, default true) and document running `pnpm db:migrate` separately in zero-downtime deploys.
+
+### Tech Debt: S3 toggle is all-or-nothing
+
+`packages/api/src/services/storage.ts:336` and `apps/web/plugins/2.storage.ts:7`: storage backend selection requires all three of `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_BUCKET` to be set. Setting two of three silently falls back to local storage.
+
+**Impact:** Operator misconfigures S3 (e.g. forgets `S3_BUCKET`), app silently writes to local FS — uploads disappear on next container restart on ephemeral disks.
+
+**Fix approach:** Treat "any S3 var set" as "S3 intended" — throw on partial config rather than silently downgrading.
+
+### Security: no global CSP / X-Frame-Options on HTML responses
+
+A repo-wide grep for `Content-Security-Policy`, `X-Frame-Options`, `Strict-Transport-Security` finds them only in the uploads route (`apps/web/src/routes/uploads/$userId.$.tsx:159-165`) and the schema JSON route (`apps/web/src/routes/schema[.]json.ts`). The HTML shell (`apps/web/src/routes/__root.tsx`) sets no CSP, no HSTS, no `Permissions-Policy`, no `Referrer-Policy`.
+
+**Impact:**
+- No clickjacking protection on the resume builder or public resume pages — they can be framed by any origin.
+- No CSP means an XSS through rich-text rendering (`packages/utils/src/sanitize.*`, `packages/pdf/src/templates/shared/rich-text-html.ts`) has no defence-in-depth.
+
+**Fix approach:** Add a Nitro response hook that sets `Content-Security-Policy`, `Strict-Transport-Security`, `Referrer-Policy: strict-origin-when-cross-origin`, `X-Content-Type-Options: nosniff`, and `X-Frame-Options: SAMEORIGIN` on all HTML responses. Validate that the CSP allows `pdf.worker.min.mjs`, `@react-pdf/renderer` font fetches, and the configured S3/SeaweedFS origin.
+
+### Security: OAuth dynamic-client registration allows unauthenticated callers
+
+`packages/auth/src/config.ts:395-401` enables `allowDynamicClientRegistration: true` and `allowUnauthenticatedClientRegistration: true` on the oauthProvider plugin. The comment (`:397-399`) explicitly states this is required for MCP onboarding (RFC 7591) and that the phishing vector is closed by the redirect-URI allowlist in `hooks.before` (`:253-271`) and `apps/web/src/routes/api/auth.$.ts:97-111`.
+
+**Impact:** Anyone can register an OAuth client. The protection depends entirely on the redirect-URI allowlist correctness in `parseAllowedHostList(env.OAUTH_DYNAMIC_CLIENT_REDIRECT_HOSTS)` and `isAllowedOAuthRedirectUri`.
+
+**Fix approach:** Already mitigated in code; the residual risk is operator misconfiguration of `OAUTH_DYNAMIC_CLIENT_REDIRECT_HOSTS`. Add a startup warning when `OAUTH_DYNAMIC_CLIENT_REDIRECT_HOSTS` is empty (i.e. allowlist is APP_URL-only).
+
+### Tech Debt: log noise on auth fallthrough
+
+`packages/api/src/context.ts:25, :37, :53` calls `console.warn` for every failed Bearer / session / API-key validation. In an unauthenticated user flow that hits the same route via Bearer-not-present → session-cookie path, no warning fires, but in an actual token-mismatch path the warning fires on every request.
+
+**Impact:** Log volume in production when API keys expire or rotate. Logs may leak token shape information indirectly via repeated warnings.
+
+**Fix approach:** Drop to `console.debug` (which is no-op in default Node), or rate-limit the warning per token-hash.
+
+### Tech Debt: `getStorageService()` cached service singleton in module-load order
+
+`packages/api/src/services/storage.ts:343-350` caches the service at first call. Combined with the `packages/api/src/routers/storage.ts:7` top-level call, if storage env vars are not present at module-load time (e.g. `.env` not loaded yet) the local backend is wired in permanently for the process.
+
+**Fix approach:** Lazy-validate env on first use, not at module load.
+
+### Anti-pattern: empty catch swallows preview generation errors
+
+`apps/web/src/components/resume/preview.browser.tsx:120`:
+
+```ts
+} catch {}
+```
+
+A failed PDF generation in the builder preview is silently swallowed. The crossfade machinery keeps showing the previous preview, masking template bugs or runtime errors from contributors during development.
+
+**Fix approach:** At minimum, `console.error` the failure (matching the pattern used in `pdf-canvas.tsx:68`). Better: surface a toast or banner so failed-preview state is visible.
+
+### Anti-pattern: `console.warn`/`error` lacks structure
+
+Every error log in `packages/api/src` uses `console.warn`/`console.error` with positional args (e.g. `services/resume.ts:158, :293, :363`, `context.ts:25, :37, :53`). There is no centralised logger, no structured fields, no request correlation ID.
+
+**Fix approach:** Introduce a minimal logger (pino-light or a thin wrapper) with `level`, `event`, `userId`, `requestId` fields. Already partly done in the healthcheck (`apps/web/src/routes/api/health.ts:65, "[Healthcheck]"`).
+
+### Fragile: in-process pub/sub for resume update events
+
+`packages/api/src/services/resume-events.ts` (the subscribe path consumed by `packages/api/src/routers/resume.ts:99-103`'s `subscribeResumeUpdates`) is in-process. Two web replicas will not see each other's resume update events.
+
+**Impact:** Multi-tab / multi-device builder sync across replicas does not work behind a load balancer.
+
+**Fix approach:** Redis pub/sub or Postgres `LISTEN/NOTIFY` once distributed deployment becomes a target.
+
+---
+
+## Migration & Schema Concerns
+
+### Migration count is small but each is unversioned in app
+
+- 13 migration files in `migrations/` (`migrations/20260114102228_*` through `migrations/20260507144406_*`).
+- The Nitro plugin runs every pending migration on every boot (`apps/web/plugins/1.migrate.ts:23-40`).
+- There is no "down" / rollback story. Drizzle-kit generates forward-only migrations.
+
+**Action:** Standard for drizzle workflows. Document that downgrade requires manual SQL.
+
+### Schema notes
+
+- `packages/db/src/schema/resume.ts:24` stores `password` as plaintext column type `text`, but content is always bcrypt-hashed at write (`packages/api/src/services/resume.ts:453`). Column name is misleading — should be `password_hash`. Renaming requires a non-trivial migration.
+
+---
+
+## Dependency Risk
+
+### Pre-1.0 / preview dependencies in production critical path
+
+| Package | Version | Risk |
+|---|---|---|
+| `drizzle-orm` | `1.0.0-beta.22` | Beta. Breaking changes possible until 1.0.0 stable. (`packages/api/package.json`, `packages/auth/package.json`, `packages/db/package.json`, `apps/web/package.json`) |
+| `drizzle-kit` | `1.0.0-beta.22` | Beta migrator. Snapshot format may change. (`packages/db/package.json`) |
+| `drizzle-zod` | `1.0.0-beta.14-a36c63d` | Beta + specific commit hash — version drift risk. (`packages/api/package.json`) |
+| `nitro` | `3.0.260429-beta` | Beta server runtime in the critical path. (`apps/web/package.json`) |
+| `@typescript/native-preview` | `7.0.0-dev.20260510.1` | Dev build of `tsgo`. All packages use it for `typecheck`. |
+| `typescript` | `^6.0.3` | TS 6 — recent major. |
+| `vite` | `^8.0.11` | Vite 8 — recent major. |
+| `react` / `react-dom` | `^19.2.6` | React 19. |
+| `@orpc/experimental-ratelimit` | `^1.14.2` | Explicitly experimental in the package name. (`packages/api/package.json`) |
+| `@tanstack/react-start` | `^1.167.65` | TanStack Start is pre-1.x semver but not labelled beta. |
+| `better-auth` | `1.6.10` (exact) | Pinned exact, not `^`. Manual upgrade required for security patches. |
+
+**Impact:** Library upgrades in this stack are high-risk; the team must follow each upstream's release notes closely. The `BETA` / `DEV` versions also affect lockfile churn.
+
+**Fix approach:**
+- Set up Renovate / Dependabot for the beta packages specifically, so security patches are caught.
+- Run `pnpm knip` and `pnpm dlx npm-check-updates` regularly (both are devDependencies, `package.json:34, :40`).
+
+### Several heavy native dependencies are externalised at build time
+
+`apps/web/vite.config.ts:55-57` externals `bcrypt`, `sharp`, `@aws-sdk/client-s3`. `packages/runtime-externals` is the workspace package that wraps these. Knip is configured to ignore them (`knip.json:14`).
+
+**Risk:** Operators must ensure these are installed at runtime (covered in `Dockerfile`). Self-hosters using a Node base image without build-essentials may hit `bcrypt` build failures.
+
+**Fix approach:** Mostly documented; consider switching `bcrypt` → `bcryptjs` (pure JS) to remove a build dependency.
+
+---
+
+## Cross-Cutting Hard-to-Find Logic
+
+These are non-obvious surfaces that consumers of this map should know about before changing related code:
+
+1. **PDF section filtering** — `packages/pdf/src/templates/shared/filtering.ts:25-60` decides which resume sections render in PDFs based on hidden flags and required title fields. Per-template visual exceptions live in each template directory; cross-template visual changes go here. Noted in `AGENTS.md:44`.
+
+2. **React-PDF font registration & CJK fallback stack** — `packages/pdf/src/hooks/use-register-fonts.ts:68-133`. Owns standard-PDF-font handling (`isStandardPdfFontFamily`), CJK glyph-level fallback (#2986), and global hyphenation callback. Module-level registration cache (`:18`). Noted in `AGENTS.md:45`.
+
+3. **Resume access policy** — `packages/api/src/helpers/resume-access-policy.ts`. Single source of truth for owner-vs-viewer redaction (`name` and `metadata.notes` stripped for non-owners), `NOT_FOUND`-vs-`FORBIDDEN` choice (not-found used to avoid existence disclosure), and self-view statistics exclusion. Owner-only mutations rely on SQL `WHERE userId =` clauses, not this policy — drift between SQL guards and policy is silent.
+
+4. **Resume password cookie** — `packages/api/src/helpers/resume-access.ts`. Cookie name `resume_access_{resumeId}`, signed value is `sha256(resumeId:passwordHash)`, TTL 10 minutes, `httpOnly`, `sameSite: lax`, `secure` only when `APP_URL` starts with `https`. Forgetting to set `APP_URL=https://...` in production drops the secure flag.
+
+5. **OAuth `authorize` request sanitization** — `apps/web/src/routes/api/auth.$.ts:6-51` strips control chars from OAuth parameters and decodes broken-but-decodable redirect URIs before passing to Better Auth. Easy to bypass if a new OAuth flow is added that does not route through this handler.
+
+6. **Dynamic client registration coercion to public client** — `apps/web/src/routes/api/auth.$.ts:53-80` forces `token_endpoint_auth_method = "none"` for unauthenticated registrations (specifically for Claude.ai's MCP onboarding quirk). This is non-standard behaviour buried in a request preprocessor.
+
+7. **Builder draft sync** — `apps/web/src/components/resume/builder-resume-draft.ts:46-100` manages per-resume zustand stores keyed by resume id, with debounced patch-and-resync. Failure to clean up `runtimes` Map on resume close = subscription/timer leaks.
+
+---
+
+## Test Coverage Gaps (Priority Map)
+
+| Area | Source files | Test files | Priority |
+|------|-------------:|-----------:|----------|
+| `apps/web/src/routes/**` | 125 | 1 | **High** — covers all server handlers and the builder shell |
+| `apps/web/src/routes/api/**` (rpc/auth/uploads/openapi/mcp) | ~10 | 0 | **High** — security-sensitive route handlers |
+| `apps/web/src/components/resume/**` | 5 | 2 | Medium |
+| `apps/web/src/dialogs/**` | ~30 | 1 (`store.test.ts`) | Medium |
+| `packages/api/src/routers/**` | 7 | 0 (DTO test only) | **High** — auth-protected procedures |
+| `packages/api/src/services/**` | 8 | 1 (`ai.test.ts`) | High |
+| `packages/auth/src/**` | 3 | 0 | **High** — central auth config never directly tested |
+| `packages/email/src/**` | ~5 | 0 | Medium |
+| `packages/import/src/**` | several importers | 1 (v4) | Medium |
+| `packages/pdf/src/templates/shared/**` | ~20 | 11 | Low (well covered) |
+
+---
+
+*Concerns audit: 2026-05-11*

.planning/codebase/CONVENTIONS.md

@@ -0,0 +1,238 @@
+# Coding Conventions
+
+**Analysis Date:** 2026-05-11
+
+This document is the canonical short-form reference for code style, structure, and feature-boundary rules in the Reactive Resume monorepo. The authoritative long-form reference lives in `AGENTS.md` at the repo root — when in doubt, defer to it.
+
+## Tooling Stack
+
+- **Formatter + linter:** Biome 2.x (`biome.json`). Pre-commit hook (`lefthook.yml`) runs `biome check --write --unsafe` on staged JS/TS/JSON files.
+- **Type checker:** `tsgo --noEmit` (the `@typescript/native-preview` TS implementation) in every workspace package and `apps/web`. Use `pnpm typecheck` at the root or `pnpm --filter <pkg> typecheck` per package.
+- **TypeScript base config:** `packages/config/tsconfig.base.json`, consumed by `tsconfig.json` at root and per-package `tsconfig.json` files.
+- **Commit hook:** commitlint with `@commitlint/config-conventional` (`commitlint.config.cjs`). `body-max-line-length` is disabled.
+- **Internal CLI:** `pnpm check` is **write-capable** (`biome check --write --unsafe .`). Use `biome check .` (no `--write`) for read-only inspection.
+
+## Biome Configuration (`biome.json`)
+
+**Formatter:**
+- `lineWidth: 120`
+- `indentStyle: "tab"`
+- `javascript.formatter.quoteStyle: "double"`
+- CSS parser has `tailwindDirectives: true`
+
+**Linter rules (notable):**
+- `recommended: true`
+- `suspicious.noExplicitAny: "error"` — `any` is forbidden
+- `suspicious.noArrayIndexKey: "off"`
+- `correctness.useExhaustiveDependencies: "info"` (not an error)
+- `style.useImportType: { level: "on", options: { style: "separatedType" } }` — `import type` is required when an import is type-only and must be on its own line (not inlined per-specifier)
+- `style.noInferrableTypes: "error"` — drop redundant annotations like `const x: number = 1`
+- `style.noUselessElse: "error"`
+- `style.useSelfClosingElements: "error"`
+- `style.useSingleVarDeclarator: "error"`
+- `style.noParameterAssign: "error"`
+- `style.useDefaultParameterLast: "error"`
+- `nursery.useSortedClasses: { level: "warn", fix: "safe", functions: ["clsx", "cva", "cn"] }` — Tailwind class strings inside these wrappers are sorted automatically
+
+**Import organization:** Biome's `assist.actions.source.organizeImports` is `on`, grouped in this order (`biome.json` lines 32-39):
+
+1. Type-only imports (`{ "type": true }`)
+2. Node built-ins (`":NODE:"`, excluding Bun)
+3. Vitest + Testing Library (`vitest`, `vitest/**`, `@testing-library/**`)
+4. External npm packages (`:PACKAGE:`, excluding `@reactive-resume/**`)
+5. Internal workspace packages (`@reactive-resume/**`)
+6. App-local aliases / relative paths (`:ALIAS:`, `:PATH:`)
+
+A representative file that demonstrates the order: `packages/api/src/services/resume.ts` (type imports → node-free externals → `@reactive-resume/*` → relatives).
+
+**Biome ignores:** `**/.turbo`, `**/.output`, `**/.vercel`, `**/.wrangler`, `**/coverage`, `**/reports`, `**/routeTree.gen.ts`.
+
+## TypeScript Conventions
+
+**Strictness flags** in `packages/config/tsconfig.base.json` are intentionally aggressive:
+
+- `strict: true`
+- `verbatimModuleSyntax: true` (pairs with Biome's `useImportType` enforcement)
+- `exactOptionalPropertyTypes: true`
+- `noUncheckedIndexedAccess: true`
+- `noUncheckedSideEffectImports: true`
+- `noUnusedLocals: true`, `noUnusedParameters: true`
+- `noFallthroughCasesInSwitch: true`
+- `isolatedModules: true`, `moduleResolution: "bundler"`
+- `target: "ESNext"`, `module: "ESNext"`
+
+**Type-only imports:** Always use `import type { … }` on its own line when an import is only used in type positions. See `packages/api/src/services/resume.ts:1-5` and `packages/api/src/context.ts:1-2`.
+
+**`any`:** Banned by Biome (`noExplicitAny: "error"`). Use `unknown` and narrow, or use a discriminated union.
+
+**Path aliases (web app only):** `apps/web/tsconfig.json` declares:
+- `@/*` → `./src/*`
+- `@reactive-resume/ui/*` → `../../packages/ui/src/*` (build-time alias for direct source resolution)
+
+Internal packages do NOT use `@/*` aliases — they import siblings via relative paths and cross-package code via the `@reactive-resume/*` export maps.
+
+## Package Export Conventions (source-consumed packages)
+
+**Internal packages export `src` files directly via `package.json` `exports`.** There is no per-package build step; consumers pick up the TS source through bundler/vitest resolution. Do not assume any `dist/` output.
+
+Sample (`packages/utils/package.json`):
+
+```json
+{
+    "name": "@reactive-resume/utils",
+    "type": "module",
+    "exports": {
+        "./color": "./src/color.ts",
+        "./date": "./src/date.ts",
+        "./resume/docx": "./src/resume/docx/index.ts",
+        "./resume/patch": "./src/resume/patch.ts",
+        "./url-security.node": "./src/url-security.node.ts"
+    }
+}
+```
+
+**Conventions when adding cross-package exports:**
+
+- Use **explicit subpath exports**, not wildcards in `@reactive-resume/utils`/`@reactive-resume/db`. Some packages (`@reactive-resume/api`) do use wildcards like `"./services/*"` — match the style of the package you're editing.
+- Filenames ending in `.node.ts` (e.g. `packages/utils/src/url-security.node.ts`, `packages/utils/src/monorepo.node.ts`) are reserved for Node-only code that must not be imported from the browser bundle.
+- Filename suffixes `.browser.tsx` (e.g. `apps/web/src/components/resume/preview.browser.tsx`) mark code that must stay out of SSR paths.
+
+## React & Web App Conventions
+
+**Routing:** TanStack Router with file-based routes under `apps/web/src/routes`.
+- Each route file calls `createFileRoute("/path")({ … })` and exports `Route`. Example: `apps/web/src/routes/auth/login.tsx:18`.
+- `apps/web/src/routeTree.gen.ts` is generated — never hand-edit it (also Biome-ignored).
+- Server-only handlers live in `server.handlers` blocks on routes like `apps/web/src/routes/api/rpc.$.ts`, `apps/web/src/routes/api/auth.$.ts`, `apps/web/src/routes/api/health.ts`.
+- Public resume route `apps/web/src/routes/$username/$slug.tsx` is `ssr: "data-only"`; nested builder preview is `ssr: false`.
+
+**Router context** (`apps/web/src/router.tsx`) provides `queryClient`, `orpc`, `theme`, `locale`, `session`, and `flags`. Read them via `Route.useRouteContext()` rather than refetching.
+
+**Components:**
+- Functional components only. React 19.
+- File naming: **kebab-case** for files and directories (e.g. `apps/web/src/components/command-palette/`, `packages/ui/src/components/alert-dialog.tsx`, `apps/web/src/dialogs/api-key/create.tsx`).
+- Test file: `<name>.test.ts(x)` colocated with the implementation (e.g. `packages/ui/src/components/button.tsx` + `packages/ui/src/components/button.test.tsx`).
+- shadcn/Base UI primitive components in `packages/ui/src/components/*.tsx` are exported via the `./components/*` subpath. Hooks via `./hooks/*`.
+
+**Tailwind class strings:** Always wrap in `clsx`, `cva`, or `cn` so Biome's `useSortedClasses` rule can sort them safely.
+
+## oRPC Conventions (`packages/api`)
+
+- **Procedures:** Build new procedures with `publicProcedure` or `protectedProcedure` from `packages/api/src/context.ts:79-99`. `protectedProcedure` adds the authenticated `User` to context and throws `ORPCError("UNAUTHORIZED")` otherwise; prefer it for anything authenticated.
+- **Routers** live in `packages/api/src/routers/*.ts` and are composed in `packages/api/src/routers/index.ts` (`ai`, `auth`, `flags`, `resume`, `statistics`, `storage`). Each router file may export sub-routers internally (see `tagsRouter`, `statisticsRouter`, `analysisRouter`, `updatesRouter` in `packages/api/src/routers/resume.ts`).
+- **Business logic** belongs in `packages/api/src/services/*.ts`. Handlers must stay thin: validate input, call a service, return its output. Example pattern: `packages/api/src/routers/resume.ts:24-26` calls `resumeService.tags.list(...)`.
+- **DTOs / IO schemas** live in `packages/api/src/dto/*.ts` and are imported as `resumeDto.<op>.input` / `resumeDto.<op>.output`.
+- **Errors:** Declare typed errors with `.errors({ CODE: { message, status } })` on the procedure (see `packages/api/src/routers/resume.ts:282-291`). Throw `new ORPCError("CODE")` inside services. The web side translates codes to user-facing strings in `apps/web/src/libs/error-message.ts`.
+- **Route metadata:** Every procedure declares `.route({ method, path, tags, operationId, summary, description, successDescription })` so the OpenAPI/MCP endpoints stay accurate.
+- **Rate limiting:** Apply via `.use(resumeMutationRateLimit)` / `.use(resumePasswordRateLimit)` from `packages/api/src/middleware/rate-limit`.
+- **Web exposure:** Routers are mounted at `/api/rpc` by `apps/web/src/routes/api/rpc.$.ts`. The isomorphic client lives at `apps/web/src/libs/orpc/client.ts` — server-side calls use the in-process router client and browser calls hit `/api/rpc` with credentials.
+
+## Drizzle Conventions (`packages/db`)
+
+- **Schema location:** `packages/db/src/schema/*.ts`. Tables exported from `packages/db/src/schema/index.ts`.
+- **Client:** `packages/db/src/client.ts`, exported as `@reactive-resume/db/client`.
+- **Migrations:** Generated to **`migrations/` at the repo root** by `drizzle-kit generate`. Use `pnpm db:generate` after schema changes.
+- **`DATABASE_URL` handling:** `drizzle-kit` does **not** auto-load `.env`. Always export `DATABASE_URL` in the shell (or prefix the command) before running `pnpm db:generate` / `pnpm db:migrate`.
+- **Runtime migration:** `apps/web/plugins/1.migrate.ts` runs migrations on Nitro startup, so `pnpm db:migrate` is mostly used for first-time setup or debugging.
+- **Patterns observed in `packages/db/src/schema/resume.ts`:**
+  - Primary keys use `pg.text("id").$defaultFn(() => generateId())` (UUIDv7 from `@reactive-resume/utils/string`).
+  - `createdAt` / `updatedAt` use `withTimezone: true`, `.defaultNow()`, and `$onUpdate(() => new Date())`.
+  - JSONB columns get `.$type<T>()` for end-to-end typing.
+  - Composite uniques/indexes are declared in the table's tuple callback.
+  - Foreign keys use `onDelete: "cascade"`.
+
+## Schema-First Change Workflow
+
+When changing resume data shape, propagate in this order (per `AGENTS.md`):
+
+1. **`packages/schema/src/resume/*.ts`** — Zod schemas and types (entry point).
+2. **`packages/api/src/dto/*.ts`** — API DTOs that re-use those schemas.
+3. **`packages/import/src/*.tsx`** — importers (`json-resume`, `reactive-resume-json`, `reactive-resume-v4-json`).
+4. **`packages/pdf/src/templates/**`** — PDF rendering for every template (`azurill`, `bronzor`, `chikorita`, `ditgar`, `ditto`, `gengar`, `glalie`, `kakuna`, `lapras`, `leafish`, `meowth`, `onyx`, `pikachu`, `rhyhorn`, `scizor`). Shared filtering: `packages/pdf/src/templates/shared/filtering.ts`.
+5. **`apps/web/src/`** — builder forms and any consumer hooks.
+
+Adding/renaming a template requires changes in `packages/schema/src/templates.ts`, `packages/pdf/src/templates/index.ts`, the template directory `packages/pdf/src/templates/<name>/`, and static previews under `apps/web/public/templates/{jpg,pdf}/`.
+
+## Error Handling Patterns
+
+- **Services:** Throw `new ORPCError("CODE")` (e.g. `NOT_FOUND`, `UNAUTHORIZED`, custom `RESUME_LOCKED`). Example: `packages/api/src/services/resume.ts:54`.
+- **Routers:** Declare expected codes via `.errors({ … })` so callers get typed error narrowing.
+- **Auth helpers** in `packages/api/src/context.ts:14-55` catch verification errors and `console.warn(...)` rather than throwing, returning `null` so the caller can fall through to the next auth method.
+- **Web side:** `apps/web/src/libs/error-message.ts` exposes `getReadableErrorMessage`, `getOrpcErrorMessage`, and `getResumeErrorMessage` for translating raw errors into UI-safe strings. Pair with `sonner` toasts (see `apps/web/src/routes/auth/login.tsx:45-64`).
+
+## Logging
+
+- No dedicated logging framework. Use `console.warn` / `console.error` for diagnostic output, scoped tightly (see `packages/api/src/context.ts:25`).
+- Server logs are also where dev-mode email verification links surface when SMTP is unconfigured.
+
+## i18n & Translations (Lingui)
+
+- **Library:** `@lingui/core`, `@lingui/react` with the babel macro plugin enabled in `apps/web/vitest.config.ts` and Vite config.
+- **Config:** `apps/web/lingui.config.ts` — source locale `en-US`, pseudo locale `zu-ZA`, 50+ supported locales. Catalogs live in `apps/web/locales/{locale}.po`.
+- **Usage:**
+  - Import macros: `import { t } from "@lingui/core/macro"` and `import { Trans } from "@lingui/react/macro"` (`apps/web/src/routes/auth/login.tsx:1-2`).
+  - Wrap displayed text in `<Trans>...</Trans>` for JSX or `` t`...` `` / `t({ message, comment })` for strings.
+  - Provide `comment:` for ambiguous fallback strings (see `login.tsx:57-60`).
+- **Extraction:** `pnpm lingui:extract` (turbo task in `apps/web`). Crowdin sync runs via `.github/workflows/crowdin-sync.yml`.
+
+## Comments Policy
+
+Comments stay short and explain **why**, not what. Patterns observed:
+
+- One-line `//` comments before a non-obvious decision (`vitest.setup.ts:5-7` explains why `cleanup()` is registered manually; `packages/utils/src/monorepo.node.test.ts:11` explains the `realpathSync` call).
+- JSDoc/TSDoc only on cross-package public functions where intent matters (e.g. `packages/api/src/context.ts:57-63` documents `resolveUserFromRequestHeaders`).
+- Inline `/* @__PURE__ */` annotations on `$onUpdate(() => new Date())` in Drizzle schemas (`packages/db/src/schema/resume.ts:36`).
+- No commented-out code in commits.
+
+## Git Hooks & Commit Style
+
+**Lefthook (`lefthook.yml`):**
+
+```yaml
+pre-commit:
+  parallel: true
+  jobs:
+    - name: lint and format
+      glob: "*.{js,ts,cjs,mjs,d.cts,d.mts,jsx,tsx,json,jsonc}"
+      run: pnpm biome check --write --unsafe --no-errors-on-unmatched --files-ignore-unknown=true {staged_files}
+      stage_fixed: true
+
+commit-msg:
+  jobs:
+    - name: commitlint
+      run: pnpm commitlint --edit {1}
+```
+
+The pre-commit hook **rewrites staged files** with Biome fixes (`stage_fixed: true`). Run `pnpm check` before staging to avoid surprises.
+
+**Commit messages:** Conventional Commits (`commitlint.config.cjs` extends `@commitlint/config-conventional`). Examples from `git log`:
+
+- `feat: implement an AI chat window for agentic resume building`
+- `fix(pdf): register CJK fallback font so Chinese/Japanese/Korean text renders correctly`
+- `fix(lapras): adjust lapras border color to fixed gray`
+- `chore: migrate from jsdom to happy-dom for testing environment`
+- `docs: update AGENTS.md with detailed codebase structure`
+- `test: add unit and component tests across the monorepo`
+- `chore(release): v5.1.2`
+
+Allowed types: `feat`, `fix`, `chore`, `docs`, `test`, `refactor`, `style`, `perf`, `build`, `ci`, `revert`. Scope is optional and lowercase. `body-max-line-length` is disabled, so long PR bodies are fine.
+
+## CI Workflows
+
+- **`.github/workflows/autofix.yml`** runs on every PR and push to `main`: `pnpm install --frozen-lockfile` → `pnpm knip --fix` (prune unused deps) → `pnpm check` (Biome) → `autofix-ci/action` opens fix commits.
+- **`.github/workflows/docker-build.yml`** is `workflow_dispatch` only, builds multi-arch Docker images.
+- **`.github/workflows/crowdin-sync.yml`** syncs translation catalogs.
+- There is no CI workflow that runs `pnpm test` today. Tests run locally via `pnpm test` / `pnpm test:ci` and through turbo's `test:agent` reporter for agent-driven runs.
+
+## Function & Module Design
+
+- **Function size:** Most service functions stay under ~40 lines. Bigger flows (e.g. `resumeService.patch`) are decomposed into helpers in `packages/api/src/helpers/*` and `packages/api/src/services/resume-events.ts`.
+- **Parameters:** Service helpers consistently take a single object argument (`async ({ id, userId })`) rather than positional args. See `packages/api/src/services/resume.ts:27,41,65`.
+- **Return values:** Services return plain typed objects; routers shape the response via `.output(schema)` so Zod validates at the boundary.
+- **Module boundaries:**
+  - Cross-package imports must go through declared `exports` subpaths. Reaching into `packages/<x>/src/internal-file` directly is not allowed.
+  - `packages/utils` exports are narrowly scoped — if you need a new helper for another package, add a new explicit subpath in `packages/utils/package.json`.
+  - `packages/runtime-externals` and `packages/scripts` are support packages; avoid importing them into runtime code.
+
+---
+
+*Convention analysis: 2026-05-11*

.planning/codebase/INTEGRATIONS.md

@@ -0,0 +1,239 @@
+# External Integrations
+
+**Analysis Date:** 2026-05-11
+
+## APIs & External Services
+
+**AI Providers (user-supplied API keys, called per-request from `packages/api/src/services/ai.ts`):**
+- OpenAI — Default base URL `https://api.openai.com/v1` (`packages/ai/src/types.ts`)
+  - SDK: `@ai-sdk/openai ^3.0.63` via `createOpenAI(...).chat(model)`
+  - API key supplied per-call from the resume's `ai` config; not read from server env
+- Anthropic — Default base URL `https://api.anthropic.com/v1`
+  - SDK: `@ai-sdk/anthropic ^3.0.76` via `createAnthropic(...).languageModel(model)`
+- Google Gemini — Default base URL `https://generativelanguage.googleapis.com/v1beta`
+  - SDK: `@ai-sdk/google ^3.0.71` via `createGoogleGenerativeAI(...).languageModel(model)`
+- Vercel AI Gateway — Default base URL `https://ai-gateway.vercel.sh/v3/ai`
+  - SDK: `ai ^6.0.177` via `createGateway(...).languageModel(model)`
+- OpenRouter — Default base URL `https://openrouter.ai/api/v1`
+  - SDK: `@ai-sdk/openai-compatible ^2.0.47` via `createOpenAICompatible({ name: "openrouter", ... })`
+- Ollama — Default base URL `https://ollama.com/api`
+  - SDK: `ollama-ai-provider-v2 ^3.5.0` via `createOllama(...)`
+- Security: `packages/api/src/services/ai.ts` `resolveBaseUrl` rejects non-HTTPS URLs, credentialed URLs, and private/loopback hosts (via `packages/utils/src/url-security.node.ts`).
+- File-input AI calls are capped at 10MB (`MAX_AI_FILE_BYTES`).
+
+**OAuth Identity Providers (server-side env-configured, optional):**
+- Google — `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` (config in `packages/auth/src/config.ts`).
+- GitHub — `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET`.
+- LinkedIn — `LINKEDIN_CLIENT_ID` / `LINKEDIN_CLIENT_SECRET`.
+- Custom Generic OAuth — `OAUTH_PROVIDER_NAME`, `OAUTH_CLIENT_ID`, `OAUTH_CLIENT_SECRET`, plus either `OAUTH_DISCOVERY_URL` or all three of `OAUTH_AUTHORIZATION_URL`/`OAUTH_TOKEN_URL`/`OAUTH_USER_INFO_URL`. Scopes from `OAUTH_SCOPES` (defaults `openid profile email`). Wired via Better Auth's `genericOAuth` plugin.
+- Trusted providers for account linking (`packages/auth/src/config.ts`): `google`, `github`, `linkedin`.
+
+**Translation / Localization:**
+- Crowdin — `CROWDIN_PROJECT_ID`, `CROWDIN_PERSONAL_TOKEN`. Config in `crowdin.yml`; pull request automation labelled `l10n`. Source catalog `apps/web/locales/en-US.po`.
+
+**Font Catalog Tooling:**
+- Google Fonts Developer API — `GOOGLE_CLOUD_API_KEY` consumed by `packages/scripts/fonts/generate.ts` hitting `https://www.googleapis.com/webfonts/v1/webfonts`. Output committed at `packages/fonts/src/webfontlist.json`.
+
+## Data Storage
+
+**Databases:**
+- PostgreSQL — Required relational database.
+  - Connection env: `DATABASE_URL` (validated as `postgres(ql)://...` in `packages/env/src/server.ts`)
+  - Client: `drizzle-orm 1.0.0-beta.22` with `pg ^8.20.0` Pool, instantiated in `packages/db/src/client.ts` (singleton via `globalThis.__pool` / `globalThis.__drizzle`).
+  - Schema location: `packages/db/src/schema/index.ts` (auth + resume tables) with `packages/db/src/relations.ts`.
+  - Migrations: generated by `drizzle-kit` into repo-root `migrations/` (e.g. `20260507144406_fast_nova/`). Generator config at `packages/db/drizzle.config.ts`.
+  - Auto-migration on app start: `apps/web/plugins/1.migrate.ts` runs `drizzle-orm/node-postgres/migrator` against the resolved migrations folder.
+  - `drizzle-kit` does NOT auto-load `.env` — `DATABASE_URL` must be exported before running `pnpm db:generate` / `pnpm db:migrate` (see `AGENTS.md` "Important" callout).
+  - Health probe: `packages/api/src/services/storage.ts` healthcheck + `apps/web/src/routes/api/health.ts` runs `SELECT 1` through Drizzle (1.5s timeout).
+
+**File Storage (selected at runtime in `packages/api/src/services/storage.ts`):**
+- S3-compatible object storage when all three of `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_BUCKET` are set.
+  - Client: `@aws-sdk/client-s3 ^3.1045.0` (`S3Client` constructed in `S3StorageService`).
+  - Options: `S3_REGION` (default `us-east-1`), `S3_ENDPOINT` (for non-AWS), `S3_FORCE_PATH_STYLE`.
+  - Tested compatible backends: AWS S3 and SeaweedFS (see `compose.dev.yml` / `compose.yml`).
+  - All writes use `ACL: "public-read"` (consumed publicly from `/uploads/$userId/$` route, with path validation).
+- Local filesystem fallback (`LocalStorageService`) used when any of the three S3 vars is missing.
+  - Path: `LOCAL_STORAGE_PATH` if set (must be absolute); otherwise `<workspace>/data` in dev or `/app/data` in the Docker image.
+  - Validated at boot by `apps/web/plugins/2.storage.ts` (mkdir + access check).
+- Key layout (built in `packages/api/src/services/storage.ts`):
+  - `uploads/{userId}/pictures/{timestamp}.jpeg`
+  - `uploads/{userId}/screenshots/{resumeId}/{timestamp}.jpeg`
+  - `uploads/{userId}/pdfs/{resumeId}/{timestamp}.pdf`
+- Public read route: `apps/web/src/routes/uploads/$userId.$.tsx` (ETag, content-type sniffing, path traversal protection).
+- Image preprocessing: `sharp ^0.34.5` resizes to 800x800 and re-encodes JPEG at quality 80, unless `FLAG_DISABLE_IMAGE_PROCESSING=true`.
+
+**Caching:**
+- No external cache (Redis/Memcached) configured.
+- In-process rate limiter: `@orpc/experimental-ratelimit` `MemoryRatelimiter` (`packages/api/src/middleware/rate-limit/index.ts`).
+- Workbox precache in the service worker (PWA) — `apps/web/vite.config.ts` `VitePWA` setup (skipWaiting, clientsClaim, cleanupOutdatedCaches).
+
+## Authentication & Identity
+
+**Auth Provider:** Better Auth `1.6.10`, configured in `packages/auth/src/config.ts`.
+- Mounted as a TanStack Start server handler at `/api/auth/*` via `apps/web/src/routes/api/auth.$.ts`.
+- Drizzle adapter: `@better-auth/drizzle-adapter` bound to `db` + schema (provider `pg`).
+- Trusted origins: `http://localhost:3000`, `http://127.0.0.1:3000`, and the normalized origin of `APP_URL`.
+- Secure cookies enabled automatically when `APP_URL` is `https://`.
+- Trusted IP headers (used by both Better Auth `advanced.ipAddress.ipAddressHeaders` and the oRPC rate limiter): `CF-Connecting-IP`, `CF-Connecting-IPv6`, `True-Client-IP`, `X-Forwarded-For`, `X-Real-IP` (`packages/utils/src/rate-limit.ts`).
+- Telemetry: explicitly disabled.
+
+**Email/Password:**
+- Enabled unless `FLAG_DISABLE_EMAIL_AUTH=true`.
+- Password hash: `bcrypt` (cost 10) via `hash` / `compare` from `bcrypt ^6.0.0`.
+- Min 8, max 64 char passwords.
+- Email verification: sent on signup using `VerifyEmail` template from `@reactive-resume/email/templates/auth`.
+- Reset password: `sendResetPassword` -> `ResetPasswordEmail` template.
+- Email change: `sendChangeEmailConfirmation` -> `VerifyEmailChange` template.
+
+**Better Auth Plugins (in `packages/auth/src/config.ts`):**
+- `jwt()` — JWKS published at `/api/auth/jwks` (also referenced by `verifyOAuthToken`).
+- `admin()` — Admin operations.
+- `passkey()` (`@better-auth/passkey ^1.6.10`) — WebAuthn passkeys.
+- `genericOAuth({ config })` — Driven by `OAUTH_*` env vars when configured.
+- `twoFactor({ issuer: "Reactive Resume" })` — TOTP + backup codes; UI routes `/auth/verify-2fa` and `/auth/verify-2fa-backup`.
+- `apiKey()` (`@better-auth/api-key ^1.6.10`) — Header `x-api-key`; `enableSessionForAPIKeys: true`; per-key rate limit 1000 req/hour.
+- `oauthProvider()` (`@better-auth/oauth-provider ^1.6.10`) — Makes this app act as an OAuth 2.1 authorization server for MCP clients. Allows dynamic and unauthenticated client registration (RFC 7591) but redirect URIs are gated by an allowlist in the auth `hooks.before` middleware and `OAUTH_DYNAMIC_CLIENT_REDIRECT_HOSTS`. Audiences whitelist: `${APP_URL}`, `${APP_URL}/`, `${APP_URL}/mcp`, `${APP_URL}/mcp/`.
+- `username()` — Normalized lowercase usernames (`^[a-z0-9._-]+$`, length 3–64).
+- `dash({ apiKey: BETTER_AUTH_API_KEY })` — Better Auth Dashboard (only when `BETTER_AUTH_API_KEY` is set).
+
+**Social Providers:**
+- Google, GitHub, LinkedIn — Each activates only when both `*_CLIENT_ID` and `*_CLIENT_SECRET` env vars are set (`packages/auth/src/config.ts`). `disableImplicitSignUp: true`; account linking enabled.
+
+**Session / Access in API context:**
+- `packages/api/src/context.ts` exposes `protectedProcedure` (referenced in `AGENTS.md`) for authenticated procedures.
+- oRPC middleware reads request headers via `RequestHeadersPlugin` (`apps/web/src/routes/api/rpc.$.ts`, `apps/web/src/routes/api/openapi.$.ts`).
+
+**API Key Auth for HTTP / MCP:**
+- `x-api-key` header recognised by Better Auth API Key plugin.
+- OpenAPI spec at `/api/openapi/spec.json` declares `apiKey` security scheme (`apps/web/src/routes/api/openapi.$.ts`).
+- MCP server first tries OAuth Bearer (`Authorization: Bearer ...`), then falls back to `x-api-key` (`apps/web/src/routes/mcp/index.ts`).
+
+## Monitoring & Observability
+
+**Error Tracking:**
+- None — no Sentry/Datadog/Rollbar SDK present.
+- Errors are logged via `console.error` (oRPC interceptors `onError` in `apps/web/src/routes/api/rpc.$.ts` and `apps/web/src/routes/api/openapi.$.ts`).
+
+**Health Checks:**
+- `GET /api/health` — `apps/web/src/routes/api/health.ts` returns JSON with DB and storage status; 503 if unhealthy. Used by Docker `HEALTHCHECK`.
+
+**Logs:**
+- `console.info`/`console.warn`/`console.error` only. SMTP failures, missing config, sanitization diagnostics, and migration progress are all written to stdout/stderr.
+
+## CI/CD & Deployment
+
+**Hosting / Distribution:**
+- Self-hosted Docker image — `Dockerfile` builds final image around `node:24-slim`, expose port 3000, default `LOCAL_STORAGE_PATH=/app/data`. Multi-stage uses `turbo prune` for both the web app and the `runtime-externals` package (which carries `bcrypt`, `sharp`, `@aws-sdk/client-s3` as native deps).
+- Container labels point to `https://rxresu.me` and `https://docs.rxresu.me`.
+
+**CI Pipeline:**
+- Not present in this worktree (no `.github/workflows/` enumerated here). Scripts produce CI-friendly Vitest reports (`reports/vitest-junit.xml`, `reports/vitest-results.json`) via the `test:ci` task.
+
+**Local Orchestration:**
+- `compose.dev.yml` — `postgres:latest`, `seaweedfs:latest`, `seaweedfs_create_bucket` (uses `quay.io/minio/mc:latest`).
+- `compose.yml` — Same services plus `reactive_resume` app container, networks `data_network` / `storage_network`.
+
+**Git Hooks:**
+- Lefthook (`lefthook.yml`) — `pre-commit` runs `biome check --write --unsafe` on staged JS/TS/JSON files; `commit-msg` runs `commitlint --edit`.
+
+## Environment Configuration
+
+**Required env vars (validated by Zod in `packages/env/src/server.ts`):**
+- `APP_URL` — http(s) URL, used for auth base URL, OAuth audiences, OG metadata, and public upload URLs.
+- `DATABASE_URL` — `postgres(ql)://...`.
+- `AUTH_SECRET` — Better Auth signing secret (`openssl rand -hex 32`).
+
+**Optional auth env vars:**
+- `BETTER_AUTH_API_KEY` — Enables Better Auth Dashboard plugin.
+- `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`.
+- `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`.
+- `LINKEDIN_CLIENT_ID`, `LINKEDIN_CLIENT_SECRET`.
+- `OAUTH_PROVIDER_NAME`, `OAUTH_CLIENT_ID`, `OAUTH_CLIENT_SECRET`, `OAUTH_DISCOVERY_URL`, `OAUTH_AUTHORIZATION_URL`, `OAUTH_TOKEN_URL`, `OAUTH_USER_INFO_URL`, `OAUTH_SCOPES`, `OAUTH_DYNAMIC_CLIENT_REDIRECT_HOSTS`.
+
+**Optional SMTP env vars (all required together to enable real sends):**
+- `SMTP_HOST`, `SMTP_PORT` (default 587), `SMTP_USER`, `SMTP_PASS`, `SMTP_FROM`, `SMTP_SECURE` (default false). Fallback in `packages/email/src/transport.ts`: log to console with subject/body when SMTP is not fully configured.
+
+**Optional storage env vars:**
+- `LOCAL_STORAGE_PATH` — Must be absolute when set.
+- `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_REGION` (default `us-east-1`), `S3_ENDPOINT`, `S3_BUCKET`, `S3_FORCE_PATH_STYLE` (default false).
+
+**Optional feature flags:**
+- `FLAG_DISABLE_SIGNUPS` — Disables signups across all providers.
+- `FLAG_DISABLE_EMAIL_AUTH` — Disables email/password auth and verification flows.
+- `FLAG_DISABLE_IMAGE_PROCESSING` — Skips Sharp resize/encode (useful on resource-constrained hardware).
+
+**Optional tooling env vars:**
+- `CROWDIN_PROJECT_ID` and `CROWDIN_PERSONAL_TOKEN` for Crowdin translation sync.
+- `GOOGLE_CLOUD_API_KEY` — For `packages/scripts/fonts/generate.ts`.
+
+**Secrets location:**
+- `.env` at the repo root (gitignored). `.env.example` provides documented defaults. Existence noted: `.env.local`, `.env.production` files present locally (contents not read; may contain secrets).
+- Turbo cache invalidation tied to env vars via `turbo.json` `globalEnv` whitelist.
+
+## Webhooks & Callbacks
+
+**Incoming:**
+- OAuth provider callbacks served by Better Auth: `/api/auth/oauth2/callback/{providerId}` (e.g. `/api/auth/oauth2/callback/custom` configured in `packages/auth/src/config.ts`).
+- OAuth Authorization Server endpoints (when this app acts as an OAuth provider for MCP clients): handled by Better Auth `oauthProvider` plugin under `/api/auth/oauth2/*`. Login/consent pages at `/auth/oauth` (`apps/web/src/routes/auth/oauth.ts`).
+- `.well-known` discovery routes:
+  - `apps/web/src/routes/[.]well-known/oauth-authorization-server.ts` and `.../oauth-authorization-server.$.ts`
+  - `apps/web/src/routes/[.]well-known/oauth-protected-resource.ts` and `.../oauth-protected-resource.$.ts`
+  - `apps/web/src/routes/[.]well-known/openid-configuration.ts`
+  - `apps/web/src/routes/[.]well-known/mcp/server-card[.]json.ts`
+  - Generic catch-all: `apps/web/src/routes/[.]well-known/$.ts`
+- MCP Streamable HTTP transport: `apps/web/src/routes/mcp/index.ts` (uses `WebStandardStreamableHTTPServerTransport`). Authenticates via OAuth Bearer or `x-api-key`.
+
+**Outgoing:**
+- AI provider HTTPS requests (see "AI Providers" above) — initiated per user request from `packages/api/src/services/ai.ts`.
+- SMTP outbound (`packages/email/src/transport.ts`) for verification, password reset, and email-change confirmations.
+- S3 PUT/GET/DELETE/LIST through `@aws-sdk/client-s3` when S3 storage is configured.
+- Crowdin and Google Fonts requests only from CI / scripts, not from the runtime web app.
+
+## API Endpoints Exposed by the App
+
+| Endpoint | Handler | Purpose |
+|----------|---------|---------|
+| `/api/health` | `apps/web/src/routes/api/health.ts` | Liveness/readiness JSON (DB + storage). |
+| `/api/auth/*` | `apps/web/src/routes/api/auth.$.ts` | Better Auth handler (sessions, OAuth, passkey, JWKS, etc.). |
+| `/api/rpc/*` | `apps/web/src/routes/api/rpc.$.ts` | oRPC server (`packages/api/src/routers/index.ts`: `ai`, `auth`, `flags`, `resume`, `statistics`, `storage`). |
+| `/api/openapi/*` | `apps/web/src/routes/api/openapi.$.ts` | OpenAPI-style REST wrapper of the oRPC router; spec at `/api/openapi/spec.json`. Auth via `x-api-key`. |
+| `/mcp` | `apps/web/src/routes/mcp/index.ts` | MCP Streamable HTTP server (`@modelcontextprotocol/sdk`). |
+| `/uploads/{userId}/...` | `apps/web/src/routes/uploads/$userId.$.tsx` | Public read of stored images/PDFs with ETag + path validation. |
+| `/schema.json` | `apps/web/src/routes/schema[.]json.ts` | Resume JSON schema. |
+| `/.well-known/...` | `apps/web/src/routes/[.]well-known/*` | OAuth/OIDC/MCP discovery documents. |
+
+## Rate Limiting
+
+**Better Auth (production only, see `packages/auth/src/config.ts` `isRateLimitEnabled`):**
+- Global default: 60 req / 60s.
+- `/sign-in/email`: 5/60s; `/sign-up/email`: 3/60s.
+- `/request-password-reset`, `/send-verification-email`: 3/600s.
+- `/two-factor/verify-otp`, `/verify-totp`, `/verify-backup-code`: 5/600s.
+- `/is-username-available`: 20/60s.
+- OAuth provider endpoints: `register` 5/60s, `authorize` 30/60s, `token` 20/60s, `introspect` 60/60s, `revoke` 30/60s, `userinfo` 60/60s.
+- API keys: 1000 req / hour per key.
+- Source: `packages/utils/src/rate-limit.ts`.
+
+**oRPC procedure-level (in-memory, production only, see `packages/api/src/middleware/rate-limit/index.ts`):**
+- `resumePassword`: 5 / 10min.
+- `pdfExport`: 5 / 60s.
+- `aiRequest`: 20 / 60s.
+- `jobsSearch`: 30 / 60s.
+- `jobsTestConnection`: 10 / 60s.
+- `storageUpload`: 20 / 60s.
+- `storageDelete`: 30 / 60s.
+- `resumeMutations`: 60 / 60s.
+- Keys are derived from authenticated user id when present, otherwise from the first trusted-IP header or a UA+language fingerprint.
+
+## Optional Services Declared in Compose Files
+
+| Service | Image | Purpose | File |
+|---------|-------|---------|------|
+| `postgres` | `postgres:latest` | Required PostgreSQL DB | `compose.dev.yml`, `compose.yml` |
+| `seaweedfs` | `chrislusf/seaweedfs:latest` | Optional S3-compatible storage for dev/prod | `compose.dev.yml`, `compose.yml` |
+| `seaweedfs_create_bucket` | `quay.io/minio/mc:latest` | One-shot init that creates `reactive-resume` bucket | `compose.dev.yml`, `compose.yml` |
+| `reactive_resume` | Built from `Dockerfile` | The app itself in prod compose | `compose.yml` |
+
+---
+
+*Integration audit: 2026-05-11*

.planning/codebase/STACK.md

@@ -0,0 +1,210 @@
+# Technology Stack
+
+**Analysis Date:** 2026-05-11
+
+## Languages
+
+**Primary:**
+- TypeScript `^6.0.3` — All workspace code under `apps/web/src` and `packages/*/src`. Typechecked with the experimental TS native compiler `@typescript/native-preview` (`7.0.0-dev.20260510.1`) via `tsgo --noEmit`.
+- TSX (React 19) — UI components in `apps/web/src`, `packages/ui/src/components`, `packages/pdf/src/templates`, and email templates in `packages/email/src/templates`.
+
+**Secondary:**
+- JavaScript (ESM, `"type": "module"`) — A handful of config files such as `commitlint.config.cjs` and `apps/web/postcss.config` style snippets.
+- JSON / JSONC — `package.json`, `tsconfig.json`, `biome.json`, `turbo.json`, `knip.json`, `apps/web/components.json`, `packages/schema/schema.json`, locale and webfont metadata.
+- SQL — Drizzle-generated migrations under `migrations/` (e.g. `migrations/20260507144406_fast_nova/`).
+- YAML — `compose.yml`, `compose.dev.yml`, `lefthook.yml`, `crowdin.yml`, `pnpm-workspace.yaml`.
+- Markdown — `AGENTS.md`, `README.md`, `SECURITY.md`, `LICENSE`, docs under `docs/`.
+
+## Runtime
+
+**Environment:**
+- Node.js `24` — Pinned in `Dockerfile` via `ARG NODE_VERSION=24`. Single Node process exposes the web app on port `3000`.
+- Browser runtime — React 19 SSR + hydration via TanStack Start. PWA service worker registered from `apps/web/vite.config.ts`.
+
+**Package Manager:**
+- pnpm `11.0.9` — Pinned in `package.json` `packageManager` field (with integrity hash). Managed via Corepack (`corepack enable`) per `AGENTS.md`.
+- Workspace topology: `pnpm-workspace.yaml` includes `apps/*` and `packages/*`.
+- Lockfile: `pnpm-lock.yaml` is present and committed at repo root.
+- `allowBuilds` in `pnpm-workspace.yaml`: `bcrypt`, `esbuild`, `lefthook`, `msw`, `sharp`.
+- `postcss` is pinned by an override to `^8.5.14` in `pnpm-workspace.yaml`.
+
+**Build Orchestrator:**
+- Turborepo `^2.9.12` — `turbo.json` defines tasks (`build`, `dev`, `typecheck`, `test`, `db:generate`, `db:migrate`, `db:studio`, `lingui:extract`) and the `globalEnv` whitelist for cache invalidation.
+- The Docker build also pins `turbo@2.9.9` via `pnpm dlx` for the pruner stages.
+
+## Frameworks
+
+**Core (apps/web):**
+- React `^19.2.6` with `react-dom ^19.2.6` (from `apps/web/package.json`).
+- TanStack Start `^1.167.65` — Full-stack framework wiring Vite, Nitro, and React Router. Server handlers live in route files under `apps/web/src/routes`.
+- TanStack Router `^1.169.2` — File-based router. `apps/web/src/routeTree.gen.ts` is generated.
+- TanStack React Query `^5.100.9` with SSR bridge `@tanstack/react-router-ssr-query ^1.166.12`.
+- TanStack React Form `^1.32.0` and React Hotkeys `^0.10.0`.
+- Vite `^8.0.11` (rolldown-based) — `apps/web/vite.config.ts` orchestrates plugins.
+- Nitro `3.0.260429-beta` — Server framework used through `nitro/vite`. Plugins at `apps/web/plugins/1.migrate.ts` and `apps/web/plugins/2.storage.ts` run on Nitro startup.
+- `srvx ^0.11.15` — HTTP server runtime used by Nitro/TanStack Start.
+
+**RPC / API:**
+- oRPC `^1.14.2` family — `@orpc/server`, `@orpc/client`, `@orpc/openapi`, `@orpc/json-schema`, `@orpc/zod`, `@orpc/tanstack-query`, `@orpc/experimental-ratelimit`.
+- `@modelcontextprotocol/sdk ^1.29.0` — MCP server exposed at `/mcp` via `apps/web/src/routes/mcp/index.ts`.
+
+**Auth:**
+- Better Auth `1.6.10` — Core auth framework configured in `packages/auth/src/config.ts`.
+- Better Auth plugins: `@better-auth/api-key ^1.6.10`, `@better-auth/drizzle-adapter ^1.6.10`, `@better-auth/infra ^0.2.6` (dashboard), `@better-auth/oauth-provider ^1.6.10`, `@better-auth/passkey ^1.6.10`, plus built-ins (`admin`, `jwt`, `twoFactor`, `username`, `genericOAuth`).
+- `jose ^6.2.3` — JWT verification for OAuth tokens (MCP authentication).
+- `bcrypt ^6.0.0` — Password hashing (10 rounds in `packages/auth/src/config.ts`).
+
+**Database & ORM:**
+- Drizzle ORM `1.0.0-beta.22` with PostgreSQL driver `pg ^8.20.0` (node-postgres).
+- `drizzle-kit 1.0.0-beta.22` — Migration tooling. Config at `packages/db/drizzle.config.ts` (dialect `postgresql`, schema `./src/schema/index.ts`, out `../../migrations`).
+- `drizzle-zod 1.0.0-beta.14-a36c63d` — Schema-derived Zod validators in `packages/api`.
+
+**PDF / Rendering:**
+- `@react-pdf/renderer ^4.5.1` with types `@react-pdf/types ^2.11.1` — Used by `packages/pdf/src/document.tsx` and all templates under `packages/pdf/src/templates/<name>/`.
+- `pdfjs-dist 5.7.284` — Client-side PDF rendering and parsing (browser-only paths).
+- `react-pdf-html ^2.1.5`, `node-html-parser ^7.1.0`, `phosphor-icons-react-pdf ^0.1.3`, `cjk-regex ^3.4.0` — PDF helpers and CJK fallback.
+- Font registration owned by `packages/pdf/src/hooks/use-register-fonts.ts`; webfont catalog at `packages/fonts/src/webfontlist.json`.
+
+**UI / Styling:**
+- Base UI / shadcn-style components — `@base-ui/react ^1.4.1`, `shadcn ^4.7.0` (CLI), components live in `packages/ui/src/components/*.tsx`. Config at `apps/web/components.json` (style `base-nova`, base color `zinc`, icon library `phosphor`).
+- Tailwind CSS `^4.3.0` via `@tailwindcss/vite ^4.3.0` and `@tailwindcss/postcss ^4.3.0`. Plugin `@tailwindcss/typography ^0.5.19`. Global stylesheet at `packages/ui/src/styles/globals.css`.
+- PostCSS `^8.5.14` and `tw-animate-css ^1.4.0`.
+- `class-variance-authority ^0.7.1`, `clsx ^2.1.1`, `tailwind-merge ^3.6.0`.
+- Icons: `@phosphor-icons/react ^2.1.10`, `@phosphor-icons/web ^2.1.2`.
+- Fonts: `@fontsource-variable/ibm-plex-sans ^5.2.8` (shipped with `packages/ui`).
+- Theming: `next-themes ^0.4.6`.
+- Animation: `motion ^12.38.0`.
+- Toasts: `sonner ^2.0.7`.
+- Command palette: `cmdk ^1.1.1`.
+- Misc UI: `react-resizable-panels ^4.11.0`, `react-window ^2.2.7`, `react-zoom-pan-pinch ^4.0.3`, `qrcode.react ^4.2.0`, `@uiw/color-convert ^2.10.1`, `@uiw/react-color-colorful ^2.10.1`.
+
+**Drag & Drop and Editing:**
+- `@dnd-kit/core ^6.3.1`, `@dnd-kit/sortable ^10.0.0`, `@dnd-kit/utilities ^3.2.2`.
+- TipTap `^3.23.1` editor with `starter-kit`, `pm`, `react`, plus extensions `color`, `highlight`, `table`, `text-align`, `text-style`.
+
+**State / Validation / Patterns:**
+- Zustand `^5.0.13` — Client and AI state stores (`packages/ai/src/store.ts`).
+- Immer `^11.1.8`.
+- Zod `^4.4.3` — Validators across schema, api, env, ai, import, utils packages.
+- `ts-pattern ^5.9.0` — Pattern matching in API services.
+- `es-toolkit ^1.46.1` and `fuse.js ^7.3.0`.
+
+**Internationalization (i18n):**
+- Lingui `^6.0.1` family — `@lingui/core`, `@lingui/react`, `@lingui/cli`, `@lingui/format-po`, `@lingui/vite-plugin`, `@lingui/babel-plugin-lingui-macro`.
+- Babel transformer chain via `@rolldown/plugin-babel ^0.2.3` and `babel-plugin-macros ^3.1.0`.
+- Locale config at `apps/web/lingui.config.ts` (source locale `en-US`, ~55 target locales, pseudo-locale `zu-ZA`).
+- Translation catalogs at `apps/web/locales/{locale}.po`. Crowdin sync configured in `crowdin.yml`.
+
+**Email:**
+- React Email `^6.1.1` with `@react-email/ui ^6.1.1` — Templates in `packages/email/src/templates/auth.tsx`.
+- Nodemailer `^8.0.7` SMTP transport — `packages/email/src/transport.ts`.
+
+**AI:**
+- Vercel AI SDK `ai ^6.0.177` and `@ai-sdk/react ^3.0.179`.
+- Provider SDKs: `@ai-sdk/openai ^3.0.63`, `@ai-sdk/anthropic ^3.0.76`, `@ai-sdk/google ^3.0.71`, `@ai-sdk/openai-compatible ^2.0.47`, `ollama-ai-provider-v2 ^3.5.0`.
+- Supported providers enumerated at `packages/ai/src/types.ts`: `openai`, `anthropic`, `gemini`, `vercel-ai-gateway`, `openrouter`, `ollama`.
+- JSON patch / repair: `fast-json-patch ^3.1.1`, `jsonrepair ^3.14.0`, `deepmerge-ts ^7.1.5`.
+
+**Storage:**
+- AWS SDK v3 — `@aws-sdk/client-s3 ^3.1045.0` used in `packages/api/src/services/storage.ts`. Marked external in the rolldown build (see `apps/web/vite.config.ts`) and isolated into `packages/runtime-externals` for Docker.
+
+**Image Processing:**
+- Sharp `^0.34.5` — Used in `packages/api/src/services/storage.ts` `processImageForUpload`. Disabled when `FLAG_DISABLE_IMAGE_PROCESSING` is true.
+
+**Document Generation / Import:**
+- `docx ^9.6.1` — DOCX export utilities in `packages/utils/src/resume/docx/`.
+- JSON Resume importers in `packages/import` (`json-resume`, `reactive-resume-json`, `reactive-resume-v4-json`).
+
+**HTML Sanitization:**
+- `dompurify ^3.4.2` — Used in `packages/utils/src/sanitize.ts`.
+- `@sindresorhus/slugify ^3.0.0`, `unique-names-generator ^4.7.1`, `uuid ^14.0.0`.
+
+**PWA:**
+- `vite-plugin-pwa ^1.3.0` — Workbox-based service worker, manifest defined in `apps/web/src/libs/pwa`.
+
+**Testing:**
+- Vitest `^4.1.5` with `@vitest/coverage-v8 ^4.1.5` (provider `v8`).
+- Shared config in `vitest.shared.ts`; per-package configs at `<pkg>/vitest.config.ts`.
+- DOM: `happy-dom ^20.9.0` (`disableJavaScriptFileLoading`, `disableCSSFileLoading`, navigation disabled in `vitest.shared.ts`).
+- Testing Library: `@testing-library/react ^16.3.2`, `@testing-library/dom ^10.4.1`, `@testing-library/jest-dom ^6.9.1`, `@testing-library/user-event ^14.6.1`.
+- Tests are co-located in each package's `src/**/*.{test,spec}.{ts,tsx}` and discovered automatically.
+
+**Lint / Format / Tooling:**
+- Biome `^2.4.15` — Sole linter + formatter (`biome.json`: tabs, double quotes, line width 120, organized import groups, `useSortedClasses` for `clsx`/`cva`/`cn`). Pre-commit runs through Lefthook.
+- Lefthook `^2.1.6` — Git hooks defined in `lefthook.yml` (`biome check --write --unsafe` on staged JS/TS/JSON files; `commitlint --edit` on commit messages).
+- Commitlint `^21.0.0` with `@commitlint/config-conventional` (see `commitlint.config.cjs`).
+- Knip `^6.12.2` — Dead-code/unused-deps detection (`knip.json`).
+- `npm-check-updates ^22.1.1`.
+- `tsx ^4.21.0` — Used by `packages/scripts` for ad hoc TS scripts.
+
+## Key Dependencies
+
+**Critical:**
+- `@tanstack/react-start ^1.167.65` — App framework boundary; route server handlers depend on it.
+- `@orpc/server ^1.14.2` — Type-safe RPC; backbone of `/api/rpc` and `/api/openapi`.
+- `better-auth 1.6.10` — Identity, sessions, OAuth provider, MCP auth.
+- `drizzle-orm 1.0.0-beta.22` + `pg ^8.20.0` — All DB access.
+- `@react-pdf/renderer ^4.5.1` — Resume PDF generation.
+- `@aws-sdk/client-s3 ^3.1045.0` — S3-compatible object storage.
+- `@modelcontextprotocol/sdk ^1.29.0` — MCP server endpoint.
+- `ai ^6.0.177` + `@ai-sdk/*` — Resume AI features (analysis, parsing, chat).
+
+**Infrastructure:**
+- `vite ^8.0.11` + `nitro 3.0.260429-beta` — Build and server runtime.
+- `turbo ^2.9.12` — Workspace task graph and caching.
+- `dotenv ^17.4.2` — Loaded by `packages/env/src/server.ts` for app/server code (drizzle-kit does NOT auto-load).
+- `@t3-oss/env-core ^0.13.11` — Server env validation in `packages/env/src/server.ts`.
+
+## Configuration
+
+**TypeScript:**
+- Root `tsconfig.json` extends `@reactive-resume/config/tsconfig.base.json` (`packages/config/tsconfig.base.json`).
+- Each package has its own `tsconfig.json` and runs `tsgo --noEmit`.
+- Apps/packages export source from `src/*.ts` via package.json `exports` — no `dist/` artifacts unless explicitly built (e.g. `apps/web/.output`).
+
+**Build:**
+- `apps/web/vite.config.ts` orchestrates `tailwindcss`, `tanstackStart`, `viteReact`, `lingui`, `babel` (Lingui macro preset), `nitro` (with `1.migrate.ts` and `2.storage.ts` plugins), and `VitePWA`.
+- Rolldown externals: `bcrypt`, `sharp`, `@aws-sdk/client-s3` (kept out of the client/server bundle and provided by `packages/runtime-externals` in Docker).
+- Output: `apps/web/.output/server/index.mjs` (Nitro), public assets in `apps/web/.output/public`.
+
+**Database:**
+- Drizzle config: `packages/db/drizzle.config.ts` — `dialect: "postgresql"`, schema in `packages/db/src/schema/index.ts`, migrations written to repo-root `migrations/`.
+- Client: `packages/db/src/client.ts` exposes singleton `db` plus `Pool` via `pg`, using `env.DATABASE_URL`.
+- Startup auto-migration: `apps/web/plugins/1.migrate.ts` runs `drizzle-orm/node-postgres/migrator` against the resolved `migrations/` folder.
+
+**Environment:**
+- Server env contract validated by Zod in `packages/env/src/server.ts` (via `@t3-oss/env-core`).
+- `dotenv` auto-loads root `.env` from `packages/env/src/server.ts` using `findWorkspaceRoot()`.
+- Required: `APP_URL`, `DATABASE_URL`, `AUTH_SECRET`.
+- Cache invalidation env vars listed in `turbo.json` `globalEnv`.
+- `.env.example` present at repo root; `.env.local` and `.env.production` exist locally (contents not read — may contain secrets).
+
+**Linting / Formatting:**
+- `biome.json` — Tabs, 120-col, double quotes, sorted Tailwind classes for `clsx|cva|cn`, organized import groups (`type` imports first, then Node built-ins, test packages, third-party, `@reactive-resume/**`, then aliases/relative).
+- `lefthook.yml` — Pre-commit Biome on staged files; commit-msg Commitlint.
+- `commitlint.config.cjs` — Conventional commits.
+- `knip.json` — Workspace-level ignores for `runtime-externals` external deps.
+
+**Container / Compose:**
+- `Dockerfile` (multi-stage): `base` (Node 24 slim + corepack), `pruner` (turbo prune), `builder` (frozen lockfile install + `pnpm turbo run build --filter=web --force`), `runtime-pruner` + `runtime-deps` (deploy `@reactive-resume/runtime-externals` with native deps), final `runtime` image running `node .output/server/index.mjs`, HEALTHCHECK on `/api/health`.
+- `compose.dev.yml` — Dev `postgres:latest` + `seaweedfs:latest` (S3 emulator) + `seaweedfs_create_bucket` init container using `quay.io/minio/mc:latest`.
+- `compose.yml` — Same services plus the app container `reactive_resume` built from `Dockerfile`, with `data_network`/`storage_network` and S3 env defaults pointing at SeaweedFS.
+
+## Platform Requirements
+
+**Development:**
+- Node.js 24, pnpm 11.0.9 (via Corepack), Docker (for Postgres / SeaweedFS).
+- Repo-local `data/` directory for local-storage mode (auto-created by `apps/web/plugins/2.storage.ts`).
+- `LOCAL_STORAGE_PATH` must be absolute when set.
+- SMTP optional; without it `packages/email/src/transport.ts` logs the email to console.
+
+**Production:**
+- Single Node 24 process on port 3000 (`apps/web/.output/server/index.mjs`).
+- Official Docker image listed in `Dockerfile` labels (`org.opencontainers.image.url=https://rxresu.me`).
+- Production uses S3-compatible storage when all three of `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_BUCKET` are set; otherwise falls back to local filesystem under `/app/data` (per Dockerfile `ENV LOCAL_STORAGE_PATH=/app/data`).
+- HEALTHCHECK polls `GET /api/health` (handler at `apps/web/src/routes/api/health.ts` checks DB and storage with a 1.5s timeout).
+- Rate limiting only active when `NODE_ENV=production` (see `packages/auth/src/config.ts` and `packages/api/src/middleware/rate-limit/index.ts`).
+
+---
+
+*Stack analysis: 2026-05-11*

.planning/codebase/STRUCTURE.md

@@ -0,0 +1,394 @@
+# Codebase Structure
+
+**Analysis Date:** 2026-05-11
+
+## Directory Layout
+
+```text
+reactive-resume/
+├── apps/
+│   └── web/                            # Sole deployable application (TanStack Start / Vite / Nitro)
+│       ├── plugins/                    # Nitro startup plugins (run on `pnpm dev` / `pnpm start`)
+│       ├── public/                     # Static assets (PWA, opengraph, templates, screenshots)
+│       ├── locales/                    # Lingui `.po` translation catalogs (~40 locales)
+│       ├── src/
+│       │   ├── components/             # Reusable web components grouped by feature
+│       │   ├── dialogs/                # Global dialog system + dialog implementations
+│       │   ├── hooks/                  # App-level React hooks
+│       │   ├── libs/                   # Browser/server glue (auth, orpc, query, resume, theme, locale, pwa)
+│       │   ├── routes/                 # File-based TanStack Router routes (UI + `server.handlers`)
+│       │   ├── router.tsx              # Router factory (builds query client, context, SSR query integration)
+│       │   ├── routeTree.gen.ts        # GENERATED — do not hand-edit
+│       │   ├── server.ts               # Nitro fetch entry (wraps `react-start/server-entry`)
+│       │   └── index.css               # Tailwind v4 entry
+│       ├── components.json             # shadcn config
+│       ├── lingui.config.ts            # i18n extract config
+│       ├── vite.config.ts              # Vite + TanStack Start + Nitro + PWA + Lingui
+│       └── vitest.config.ts
+├── packages/
+│   ├── ai/                             # AI prompts, Zustand store, patch-resume tool
+│   ├── api/                            # oRPC routers, services, helpers, DTOs, rate-limit middleware
+│   ├── auth/                           # Better Auth config and helpers
+│   ├── config/                         # Shared tsconfig + vitest base configs
+│   ├── db/                             # Drizzle client + schema (Postgres)
+│   ├── email/                          # Nodemailer transport + react-email templates
+│   ├── env/                            # `@t3-oss/env-core` server env (auto-loads root `.env`)
+│   ├── fonts/                          # Google Fonts metadata
+│   ├── import/                         # JSON Resume / Reactive Resume v3/v4 importers
+│   ├── pdf/                            # React PDF document, fonts, 14 templates, shared primitives
+│   ├── runtime-externals/              # Declares bcrypt, sharp, @aws-sdk/client-s3 as runtime-only
+│   ├── schema/                         # Zod schemas (resume data, templates, page, analysis, icons)
+│   ├── scripts/                        # Standalone tsx scripts (db reset, font generation)
+│   ├── ui/                             # Shared Base UI + shadcn-style components
+│   └── utils/                          # Small focused helpers (color, date, html, sanitize, etc.)
+├── migrations/                         # Drizzle-generated SQL + snapshots (one folder per migration)
+├── docs/                               # Project documentation
+├── skills/                             # Internal agent skill definitions
+├── data/                               # Local-FS storage root (when S3 is unset) — gitignored runtime data
+├── .vite-hooks/                        # Lefthook-managed git hooks (commit-msg, pre-commit)
+├── .github/                            # GitHub Actions / issue templates
+├── .claude/                            # Project-local Claude/Codex agent assets
+├── .codex/
+├── .planning/                          # GSD planning + codebase maps (this directory)
+├── .vscode/
+├── compose.dev.yml                     # Postgres + SeaweedFS for local dev
+├── compose.yml                         # Production-shaped compose
+├── Dockerfile                          # Node 24 multi-stage build
+├── AGENTS.md                           # Canonical agent guide (symlinked from CLAUDE.md)
+├── README.md
+├── SECURITY.md
+├── LICENSE
+├── package.json                        # Root scripts (turbo run …) + workspace devDeps
+├── pnpm-workspace.yaml                 # `apps/*` + `packages/*`
+├── pnpm-lock.yaml
+├── turbo.json                          # Pipeline + globalEnv allowlist
+├── biome.json                          # Biome (lint + format) config
+├── knip.json                           # Dead-code/dep analysis config
+├── lefthook.yml                        # Git hooks
+├── commitlint.config.cjs
+├── crowdin.yml                         # Translation sync config
+├── tsconfig.json                       # Root TS solution config
+├── vitest.shared.ts / vitest.setup.ts  # Shared vitest config and global setup
+├── .ncurc.cjs                          # npm-check-updates ignore list
+├── .env.example                        # Documented env vars
+└── .gitignore / .dockerignore
+```
+
+## Directory Purposes
+
+**`apps/web/`:**
+- Purpose: The only deployed app — TanStack Start / React 19 / Vite / Nitro.
+- Contains: Routes, components, dialogs, hooks, libs, server entry, build config.
+- Key files: `apps/web/vite.config.ts`, `apps/web/src/router.tsx`, `apps/web/src/server.ts`, `apps/web/src/routes/__root.tsx`, `apps/web/plugins/1.migrate.ts`, `apps/web/plugins/2.storage.ts`.
+
+**`apps/web/src/routes/`:**
+- Purpose: TanStack Router file-based route tree. Each file is either a UI route, a server-only endpoint (`server.handlers`), or both.
+- Notable subtrees:
+  - `__root.tsx` — global HTML shell, providers, head/meta, PWA scripts.
+  - `_home/` — public marketing layout (`route.tsx`, `index.tsx`, `-sections/{hero,features,faq,testimonials,...}.tsx`).
+  - `auth/` — login/register/2FA/password flows and OAuth callback (`oauth.ts`).
+  - `dashboard/` — authenticated dashboard (`route.tsx`, `index.tsx`, `resumes/`, `settings/{profile,preferences,api-keys,authentication,integrations,job-search,danger-zone}.tsx`, `-components/{header,sidebar,functions}.{ts,tsx}`).
+  - `builder/$resumeId/` — resume builder (`route.tsx` shell, `index.tsx` browser-only preview, `-components/`, `-sidebar/{left,right}/`, `-store/{section,sidebar}.ts`).
+  - `$username/$slug.tsx` — public/shared resume route (`ssr: "data-only"`).
+  - `api/` — server-only endpoints (`rpc.$.ts`, `auth.$.ts`, `health.ts`, `openapi.$.ts`, `uploads/$userId.$.ts`, `-helpers/resume-pdf.ts`).
+  - `mcp/` — Model Context Protocol server (`index.ts`, `-helpers/{tools,resources,prompts,mcp-server-card,mcp-tool-names,tool-annotations}.ts`).
+  - `[.]well-known/` — OAuth/OIDC/MCP discovery documents.
+  - `uploads/$userId.$.tsx` — etag/security-validated file serving.
+  - `templates/$.tsx` — template preview/download.
+  - `schema[.]json.ts` — `/schema.json` endpoint.
+
+**`apps/web/src/components/`:**
+- Purpose: Reusable, app-scoped components organized by domain.
+- Subdirectories:
+  - `animation/` — Motion-driven UI (`comet-card`, `count-up`, `spotlight`, `text-mask`).
+  - `command-palette/` — Cmd-K UI (`index.tsx`, `store.ts`, `pages/`).
+  - `input/` — Custom inputs (`chip-input`, `color-picker`, `github-stars-button`, `icon-picker`, `rich-input`, `url-input`).
+  - `layout/` — Error/loading/not-found screens, breakpoint indicator.
+  - `level/`, `locale/`, `theme/`, `typography/` — combobox/toggle utilities for those concerns.
+  - `resume/` — Builder preview surface (`preview.tsx`, `preview.browser.tsx`, `preview.shared.tsx`, `pdf-canvas.tsx`, `builder-resume-draft.ts`).
+  - `ui/` — App-level UI extensions (`combobox.tsx`, `copyright.tsx`).
+  - `user/` — User dropdown menu.
+
+**`apps/web/src/libs/`:**
+- Purpose: Glue between UI and external systems.
+- Contents:
+  - `auth/{client.ts,session.ts}` — Better Auth browser client + SSR session getter.
+  - `orpc/client.ts` — Isomorphic oRPC client (in-process server + RPCLink browser).
+  - `query/client.ts` — TanStack Query client factory.
+  - `resume/` — Section, PDF, and ordering helpers (`make-section-item.ts`, `move-item.ts`, `section-actions.ts`, `section-title.ts`, `section-title-locale.ts`, `pdf-document.tsx`, `pdf-document.server.tsx`, `section.tsx`).
+  - `theme.ts`, `locale.ts`, `pwa.ts`, `error-message.ts`, `tanstack-form.tsx` — direct app utilities.
+
+**`apps/web/src/dialogs/`:**
+- Purpose: Global imperative dialog system.
+- Contents: `manager.tsx` (renders open dialogs), `store.ts` (Zustand store), then domain dialogs under `auth/`, `resume/{sections,template,index.tsx,import.tsx}`, `api-key/`.
+
+**`apps/web/src/hooks/`:**
+- Purpose: Web-app hooks. (Shared cross-package hooks live in `packages/ui/src/hooks/`.)
+- Contents: `use-confirm.tsx`, `use-controlled-state.tsx`, `use-form-blocker.tsx`, `use-mobile.tsx`, `use-prompt.tsx`, `use-sync-form-values.ts`.
+
+**`apps/web/plugins/`:**
+- Purpose: Nitro startup plugins.
+- Contents: `1.migrate.ts` (runs Drizzle migrations on boot), `2.storage.ts` (validates the local data dir when S3 isn't configured).
+
+**`apps/web/public/`:**
+- Purpose: Static assets served at the site root.
+- Notable subdirs: `templates/{jpg,pdf}/` (per-template previews), `screenshots/` (PWA + marketing), `opengraph/`, `icon/`, `logo/`, `fonts/`, `photos/`, `sounds/`, `videos/`. Top-level files include `favicon.{ico,svg}`, `apple-touch-icon-180x180.png`, `manifest.webmanifest`, `pwa-{64,192,512}x.png`, `maskable-icon-512x512.png`, `robots.txt`, `sitemap.xml`, `funding.json`.
+
+**`apps/web/locales/`:**
+- Purpose: Lingui `.po` translation catalogs (~40 languages, `en-US` is source).
+- Synced via `crowdin.yml` and `pnpm lingui:extract`.
+
+**`packages/ai/`:**
+- Purpose: AI prompt assets, patch-resume tool, sanitize/extraction helpers.
+- Key paths: `packages/ai/src/prompts/{chat,analyze-resume,docx-parser,pdf-parser}-*.md`, `packages/ai/src/store.ts`, `packages/ai/src/tools/{patch-resume,patch-proposal}.ts`, `packages/ai/src/resume/{extraction-template,sanitize}.ts`.
+
+**`packages/api/`:**
+- Purpose: Server-side business logic exposed over oRPC. The only place oRPC procedures live.
+- Key paths: `packages/api/src/context.ts` (auth context + `publicProcedure`/`protectedProcedure`), `packages/api/src/routers/{ai,auth,flags,resume,statistics,storage,index}.ts`, `packages/api/src/services/{resume,resume-events,storage,ai,auth,flags,statistics}.ts`, `packages/api/src/dto/resume.ts`, `packages/api/src/helpers/{resume-access,resume-access-policy}.ts`, `packages/api/src/middleware/rate-limit/index.ts`.
+
+**`packages/auth/`:**
+- Purpose: Better Auth instance and types reused by web routes and API context.
+- Key paths: `packages/auth/src/config.ts` (Drizzle adapter, OAuth/passkey/2FA/api-key/JWT/MCP OAuth provider), `packages/auth/src/functions.ts`, `packages/auth/src/types.ts`.
+
+**`packages/config/`:**
+- Purpose: Shared tsconfig and vitest base configs consumed via workspace devDep.
+- Key paths: `packages/config/tsconfig.base.json`, `packages/config/vitest.config.ts`.
+
+**`packages/db/`:**
+- Purpose: Drizzle client and schema. Migration tooling but **migrations live in repo-root `migrations/`** (`packages/db/drizzle.config.ts` → `out: "../../migrations"`).
+- Key paths: `packages/db/src/client.ts` (singleton `pg.Pool` + `drizzle()` on `globalThis`), `packages/db/src/schema/{auth,resume,index}.ts`, `packages/db/src/relations.ts`.
+
+**`packages/email/`:**
+- Purpose: SMTP transport + react-email templates.
+- Key paths: `packages/email/src/transport.ts`, `packages/email/src/templates/{auth,reset-password,verify-email,verify-email-change}.tsx`.
+
+**`packages/env/`:**
+- Purpose: Type-safe server environment variables. Auto-loads the repo-root `.env` for app/server callers (drizzle-kit must export `DATABASE_URL` manually).
+- Key paths: `packages/env/src/server.ts`.
+
+**`packages/fonts/`:**
+- Purpose: Generated Google Fonts metadata used by the typography combobox and React PDF font registration.
+- Key paths: `packages/fonts/src/index.ts`, `packages/fonts/src/webfontlist.json` (regenerated by `packages/scripts/fonts/generate.ts`).
+
+**`packages/import/`:**
+- Purpose: Importers that convert external resume formats into the shared `ResumeData` schema.
+- Key paths: `packages/import/src/{json-resume,reactive-resume-json,reactive-resume-v4-json}.tsx`.
+
+**`packages/pdf/`:**
+- Purpose: React PDF rendering — the same code paths used by the browser preview and the server-side PDF download.
+- Key paths: `packages/pdf/src/document.tsx`, `packages/pdf/src/context.tsx`, `packages/pdf/src/section-title.ts`, `packages/pdf/src/hooks/use-register-fonts.ts`, `packages/pdf/src/templates/index.ts`, `packages/pdf/src/templates/<name>/<Name>Page.tsx` (14 templates: `azurill`, `bronzor`, `chikorita`, `ditgar`, `ditto`, `gengar`, `glalie`, `kakuna`, `lapras`, `leafish`, `meowth`, `onyx`, `pikachu`, `rhyhorn`, `scizor`), shared primitives under `packages/pdf/src/templates/shared/` (`filtering.ts`, `rich-text.tsx`, `sections.tsx`, `primitives.tsx`, `picture.ts`, `page-size.ts`, `columns.ts`, `metrics.ts`, `meta-line.tsx`, `contact.ts`, `contact-item.tsx`, `level-display.tsx`, `section-links.ts`, `rich-text-html.ts`, `rich-text-spacing.ts`, `styles.ts`, `types.ts`, `context.tsx`).
+
+**`packages/runtime-externals/`:**
+- Purpose: Vendors `bcrypt`, `sharp`, `@aws-sdk/client-s3` so they stay runtime-only (Vite externalizes them in `apps/web/vite.config.ts:55`).
+- No `src/` — `package.json` is the entire surface.
+
+**`packages/schema/`:**
+- Purpose: Source-of-truth Zod schemas for resume data, templates, page settings, AI analysis, and icon catalog.
+- Key paths: `packages/schema/src/resume/{data,default,sample,analysis}.ts`, `packages/schema/src/templates.ts`, `packages/schema/src/page.ts`, `packages/schema/src/icons.ts`.
+
+**`packages/scripts/`:**
+- Purpose: Standalone tsx scripts; no exports.
+- Key paths: `packages/scripts/database/reset.ts` (`pnpm --filter @reactive-resume/scripts db:reset`), `packages/scripts/fonts/generate.ts` (`pnpm --filter @reactive-resume/scripts fonts:generate`).
+
+**`packages/ui/`:**
+- Purpose: Shared component library (Base UI primitives + shadcn-style wrappers, Tailwind v4 styles).
+- Key paths: `packages/ui/src/components/{dialog,dropdown-menu,command,resizable,form,tooltip,sonner,…}.tsx`, `packages/ui/src/hooks/{use-confirm,use-controlled-state,use-mobile,use-prompt}.tsx`, `packages/ui/src/styles/globals.css`.
+
+**`packages/utils/`:**
+- Purpose: Pure utility functions used everywhere. Each helper has its own export path; do not import internal files.
+- Key paths: `packages/utils/src/{color,date,field,file,html,level,locale,network-icons,rate-limit,sanitize,string,style,url}.ts`, Node-only `packages/utils/src/{monorepo.node,url-security.node}.ts`, and `packages/utils/src/resume/{docx/index.ts,patch.ts}`.
+
+**`migrations/`:**
+- Purpose: Drizzle-generated migration directories (one per migration), kept at the repo root.
+- Layout: each `YYYYMMDDhhmmss_<adjective>_<noun>/` contains `migration.sql` (the SQL Drizzle will apply) and `snapshot.json` (Drizzle's internal state).
+- Applied by `apps/web/plugins/1.migrate.ts` on every server boot, and manually by `pnpm db:migrate`. Generated by `pnpm db:generate` (which writes here because of `out: "../../migrations"` in `packages/db/drizzle.config.ts`). Do not hand-edit `migration.sql`/`snapshot.json`.
+
+**`data/` (and `apps/web/data/`):**
+- Purpose: Default local-filesystem storage root when S3 vars are unset. `<workspace>/data` is validated/created at boot by `apps/web/plugins/2.storage.ts`. Override with `LOCAL_STORAGE_PATH` (must be absolute).
+- `data/statistics/` and `apps/web/data/statistics/` exist as runtime byproducts; treat as gitignored runtime state.
+
+**`.vite-hooks/`:**
+- Purpose: Lefthook-managed git hooks (`pre-commit` runs `biome check`, `commit-msg` runs commitlint). Configured by `lefthook.yml` and `commitlint.config.cjs`.
+
+**`.planning/`:**
+- Purpose: GSD planning artifacts.
+- Subdirectories: `.planning/codebase/` (this directory — analysis docs).
+
+## Key File Locations
+
+**Entry Points:**
+- `apps/web/src/server.ts` — Nitro fetch entry.
+- `apps/web/src/router.tsx` — Router factory.
+- `apps/web/src/routes/__root.tsx` — Root route + global providers.
+- `apps/web/plugins/1.migrate.ts` — Migration on boot.
+- `apps/web/plugins/2.storage.ts` — Local storage validation on boot.
+
+**Configuration:**
+- `apps/web/vite.config.ts` — Vite + TanStack Start + Nitro + PWA + Lingui.
+- `turbo.json` — Pipeline + `globalEnv` allowlist.
+- `pnpm-workspace.yaml` — Workspaces (`apps/*` + `packages/*`).
+- `biome.json` — Lint + format rules.
+- `knip.json` — Dead-code analysis config.
+- `lefthook.yml` — Git hooks.
+- `packages/db/drizzle.config.ts` — Drizzle migration config (writes to `../../migrations`).
+- `packages/env/src/server.ts` — Server env schema + `.env` loader.
+- `apps/web/lingui.config.ts` — i18n extract config.
+- `compose.dev.yml` / `compose.yml` — Postgres + SeaweedFS (dev) and prod-shaped compose.
+
+**Core API:**
+- `packages/api/src/routers/index.ts` — Router root.
+- `packages/api/src/context.ts` — Auth resolver + procedure factories.
+- `packages/api/src/services/resume.ts` — Resume CRUD/patch/lock/password/duplication.
+- `packages/api/src/services/storage.ts` — S3 + local FS storage abstraction.
+- `packages/api/src/helpers/resume-access-policy.ts` — Visibility/redaction policy.
+
+**Core data:**
+- `packages/db/src/schema/resume.ts` — Resume, statistics, analysis tables.
+- `packages/db/src/schema/auth.ts` — Better Auth tables.
+- `packages/db/src/client.ts` — Singleton `pg.Pool` + `drizzle()` client.
+- `packages/schema/src/resume/data.ts` — Canonical Zod schema for `ResumeData`.
+- `packages/schema/src/templates.ts` — Enum of template names.
+
+**Core PDF:**
+- `packages/pdf/src/document.tsx` — `ResumeDocument` root component.
+- `packages/pdf/src/templates/index.ts` — Template registry.
+- `packages/pdf/src/hooks/use-register-fonts.ts` — Font registration + CJK fallbacks.
+- `packages/pdf/src/templates/shared/filtering.ts` — Shared section filtering.
+
+**Auth:**
+- `packages/auth/src/config.ts` — Better Auth instance.
+- `apps/web/src/routes/api/auth.$.ts` — `/api/auth/*` handler with OAuth sanitization.
+- `apps/web/src/libs/auth/{client.ts,session.ts}` — Browser client + SSR session helper.
+
+**Testing:**
+- `vitest.shared.ts`, `vitest.setup.ts` — Repo-wide setup (Testing Library, jest-dom, happy-dom env).
+- `packages/config/vitest.config.ts` — Reusable Vitest base.
+- `apps/web/vitest.config.ts` — Web app Vitest config.
+
+## Naming Conventions
+
+**Files:**
+- Source files: `kebab-case.ts` / `kebab-case.tsx` (e.g. `resume-access-policy.ts`, `command-palette.tsx`).
+- Component PascalCase is reserved for component names *inside* files; filenames stay kebab-case (e.g. `Button` exported from `packages/ui/src/components/button.tsx`).
+- PDF template components are the one PascalCase exception: `packages/pdf/src/templates/azurill/AzurillPage.tsx` (kept that way because the directory name doubles as the template enum value).
+- Tests sit next to their subject: `foo.ts` ↔ `foo.test.ts`, `foo.tsx` ↔ `foo.test.tsx`.
+- Browser-only modules use a `.browser.tsx` suffix (e.g. `apps/web/src/components/resume/preview.browser.tsx`).
+- Server-only modules use a `.server.tsx` suffix when they live next to browser counterparts (e.g. `apps/web/src/libs/resume/pdf-document.server.tsx`).
+- Generated files use `.gen.ts` (e.g. `apps/web/src/routeTree.gen.ts`).
+- Node-only utilities use a `.node.ts` suffix (e.g. `packages/utils/src/monorepo.node.ts`, `packages/utils/src/url-security.node.ts`).
+
+**Routes (TanStack Router file conventions):**
+- `$param.tsx` — dynamic path segment (e.g. `apps/web/src/routes/$username/$slug.tsx`).
+- `$.tsx` — splat (matches the rest of the path; used for `api/rpc/$`, `api/auth/$`, `[.]well-known/$`).
+- `_layout/` (underscore prefix) — pathless layout group (e.g. `apps/web/src/routes/_home/`).
+- `-folder/` (dash prefix) — colocated, non-route helpers (`-components/`, `-sidebar/`, `-store/`, `-sections/`, `-helpers/`). The router ignores these.
+- `[.]well-known` — escaped folder name for paths starting with a dot.
+- `name[.]json.ts` — escaped dot in a route filename (used for `/schema.json`).
+- `route.tsx` — layout/wrapper route at a directory level; `index.tsx` — index route inside it.
+
+**Directories:**
+- `apps/<app>` and `packages/<name>` — kebab-case workspace members.
+- `packages/<name>/src/<subdomain>/<file>.ts` — every public path in `package.json` exports points into `src/`.
+
+**Package names:** All workspace packages are scoped under `@reactive-resume/*` (`api`, `auth`, `db`, `ui`, etc.). The web app is just `web`.
+
+## Where to Add New Code
+
+**New oRPC procedure:**
+- Define in `packages/api/src/routers/<domain>.ts`, register it on the exported router map, and add corresponding business logic to `packages/api/src/services/<domain>.ts`.
+- If authenticated, prefer `protectedProcedure` from `packages/api/src/context.ts`.
+- If it mutates resumes, attach `resumeMutationRateLimit` from `packages/api/src/middleware/rate-limit/index.ts`.
+- Define input/output Zod schemas in `packages/api/src/dto/<domain>.ts` when reused.
+
+**New database table or column:**
+- Add the table/column to `packages/db/src/schema/<file>.ts`, update `packages/db/src/relations.ts` if needed, re-export from `packages/db/src/schema/index.ts`.
+- Run `DATABASE_URL=... pnpm db:generate` to write a migration directory under `migrations/`.
+- Apply with `DATABASE_URL=... pnpm db:migrate` (or just start the app — `apps/web/plugins/1.migrate.ts` runs them on boot).
+
+**New resume field or section:**
+- Update Zod first in `packages/schema/src/resume/data.ts` (and `default.ts` / `sample.ts` if applicable).
+- Adjust API DTOs (`packages/api/src/dto/resume.ts`), importers (`packages/import/src/*.tsx`), PDF templates and shared primitives (`packages/pdf/src/templates/...`), and the builder forms under `apps/web/src/routes/builder/$resumeId/-sidebar/`.
+
+**New resume template:**
+- Add to the template enum in `packages/schema/src/templates.ts`.
+- Implement the page component at `packages/pdf/src/templates/<name>/<Name>Page.tsx` and register it in `packages/pdf/src/templates/index.ts`.
+- Drop static previews into `apps/web/public/templates/jpg/<name>.jpg` and `apps/web/public/templates/pdf/<name>.pdf`.
+
+**New web route:**
+- Add the file under `apps/web/src/routes/...`. Use `$param.tsx` for dynamic segments, `_layout/` for pathless groups, and `-folder/` for colocated helpers.
+- The route tree regenerates into `apps/web/src/routeTree.gen.ts` — do not hand-edit.
+- For browser-only sub-routes, set `ssr: false` (see `apps/web/src/routes/builder/$resumeId/index.tsx`) or `ssr: "data-only"` (see `apps/web/src/routes/$username/$slug.tsx`).
+
+**New server-only HTTP endpoint:**
+- Add a route file (typically under `apps/web/src/routes/api/`) and export `Route = createFileRoute(...)({ server: { handlers: { GET/POST/ANY: handler } } })`.
+- Import server-only deps (`@reactive-resume/db/client`, `@reactive-resume/api/services/*`) only inside the handler module so they stay out of the client bundle.
+
+**New shared component:**
+- App-only: `apps/web/src/components/<group>/<name>.tsx` (with colocated test if behaviour is non-trivial).
+- Reused across packages: `packages/ui/src/components/<name>.tsx` (export via deep path `@reactive-resume/ui/components/<name>`).
+
+**New shared utility:**
+- Add to `packages/utils/src/<topic>.ts` and an explicit `"./<topic>": "./src/<topic>.ts"` entry in `packages/utils/package.json` `exports`. Never import private files across packages.
+
+**New dialog:**
+- Implement under `apps/web/src/dialogs/<group>/<name>.tsx`.
+- Register with the dialog store and ensure `apps/web/src/dialogs/manager.tsx` renders it.
+
+**New AI prompt or tool:**
+- Prompts go in `packages/ai/src/prompts/<name>.md` (re-exported via `packages/ai/src/prompts.ts`).
+- Tools go in `packages/ai/src/tools/<name>.ts` and are exposed through the AI router in `packages/api/src/routers/ai.ts`.
+
+**New MCP tool/resource/prompt:**
+- Register in `apps/web/src/routes/mcp/-helpers/{tools,resources,prompts}.ts`; reuse existing oRPC services for actual logic.
+
+## Special Directories
+
+**`apps/web/src/routes/`:**
+- Purpose: Source for the file-based route tree.
+- Generated artifact: `apps/web/src/routeTree.gen.ts`.
+- Committed: Yes (the tree file is committed; regenerated by TanStack Router tooling on dev/build).
+
+**`migrations/`:**
+- Purpose: Drizzle-generated SQL + snapshots.
+- Generated: Yes (by `pnpm db:generate`).
+- Committed: Yes — do not hand-edit, but always commit new migration folders.
+
+**`apps/web/.output/`:**
+- Purpose: Nitro/Vite production build output (server + client + PWA assets).
+- Generated: Yes (by `pnpm build`).
+- Committed: No (gitignored).
+
+**`apps/web/locales/`:**
+- Purpose: Lingui `.po` catalogs.
+- Generated: `en-US.po` is the source; other locales are synced via Crowdin (`crowdin.yml`).
+- Committed: Yes.
+
+**`data/` and `apps/web/data/`:**
+- Purpose: Default local storage root when S3 is unset (`<workspace>/data`).
+- Generated: Yes (at runtime by `apps/web/plugins/2.storage.ts` or service calls).
+- Committed: No (gitignored runtime state).
+
+**`.turbo/`, `.pnpm-store/`, `node_modules/`:**
+- Purpose: Tool caches and dependency stores.
+- Committed: No.
+
+**`.vite-hooks/`:**
+- Purpose: Lefthook-installed git hooks (`commit-msg`, `pre-commit`).
+- Committed: Yes (so contributors get hooks automatically), but the underlying behavior is defined by `lefthook.yml`.
+
+**`packages/runtime-externals/`:**
+- Purpose: Marks `bcrypt`, `sharp`, `@aws-sdk/client-s3` as runtime dependencies that Vite externalizes.
+- No source files — package.json is the entire contract.
+
+## Files / Locations to Avoid Hand-Editing
+
+- `apps/web/src/routeTree.gen.ts` — regenerated by TanStack Router tooling.
+- `migrations/<timestamp>_<name>/migration.sql` and `snapshot.json` — generated by `drizzle-kit`. Add a new migration via `pnpm db:generate` instead of editing past ones.
+- `pnpm-lock.yaml` — managed by pnpm. Update via `pnpm install`.
+- `apps/web/.output/`, `apps/web/coverage/`, `packages/*/coverage/`, `packages/*/reports/` — build/test artifacts.
+- `apps/web/locales/*.po` (except `en-US.po`) — synced from Crowdin per `crowdin.yml`.
+- `apps/web/public/screenshots/`, `apps/web/public/opengraph/`, `apps/web/public/templates/{jpg,pdf}/` — regenerated assets; replace files wholesale rather than diff-editing.
+
+---
+
+*Structure analysis: 2026-05-11*

.planning/codebase/TESTING.md

@@ -0,0 +1,253 @@
+# Testing Patterns
+
+**Analysis Date:** 2026-05-11
+
+## Test Framework
+
+**Runner:** Vitest 4.x.
+- Root devDependency in `package.json`: `"vitest": "^4.1.5"`, `"@vitest/coverage-v8": "^4.1.5"`.
+- Every workspace package and `apps/web` has its own `vitest.config.ts` that delegates to the shared factory at `vitest.shared.ts`.
+
+**DOM environment:** `happy-dom` 20.x (migrated from jsdom in commit `7a60a42a0`). Default test environment per `vitest.shared.ts:19` is `"node"`; per-package configs opt into browser-like envs.
+
+**Assertion / testing libraries** (root `package.json` devDependencies):
+
+- `@testing-library/react` ^16.3.2
+- `@testing-library/dom` ^10.4.1
+- `@testing-library/jest-dom` ^6.9.1 — registered globally in `vitest.setup.ts:1`
+- `@testing-library/user-event` ^14.6.1
+
+**Run commands** (root `package.json`):
+
+```bash
+pnpm test               # turbo run test → vitest run --passWithNoTests in every package
+pnpm test:coverage      # turbo run test:coverage → adds --coverage flag
+pnpm test:ci            # adds GitHub Actions, JSON, and JUnit reporters
+pnpm test:agent         # agent-friendly reporter + JSON output for agentic runs
+```
+
+Per-package commands (uniform across all packages, see `packages/api/package.json:13-19`):
+
+```bash
+pnpm --filter @reactive-resume/utils test
+pnpm --filter @reactive-resume/api test
+pnpm --filter web test
+```
+
+Vitest test paths are package-relative when filtering: `pnpm --filter @reactive-resume/utils test -- src/string.test.ts`.
+
+## Shared Vitest Configuration
+
+`vitest.shared.ts` exports `createVitestProjectConfig({ name, dirname, environment, plugins })`. Highlights:
+
+- `root: dirname` — each package runs in isolation.
+- `envDir: workspaceRoot` — `.env` at repo root is loaded for every package.
+- `resolve: { tsconfigPaths: true }` — TS path aliases resolve from the package's own `tsconfig.json`.
+- `setupFiles: [./vitest.setup.ts]` — global hooks applied to all projects.
+- `include: ["src/**/*.{test,spec}.?(c|m)[jt]s?(x)"]` — both `.test.*` and `.spec.*` are picked up.
+- `exclude: ["node_modules", "dist", ".output", "coverage", "reports"]`.
+- `pool: "threads"`, `isolate: false` — fast threaded execution with shared module state inside a worker.
+- `passWithNoTests: true` — packages without tests don't fail CI.
+- `environmentOptions.happyDOM` disables JS/CSS file loading and navigation for safety.
+
+Coverage is configured directly in `vitest.shared.ts:49-56`:
+
+- Provider: `v8`
+- Output: `./coverage` per package
+- Reporters: `text`, `text-summary`, `json-summary`, `json`, `lcov`, `html`
+- Include: `src/**/*.{ts,tsx}`
+- Exclude: `src/**/*.{test,spec}.*`, `src/**/*.d.ts`, `src/routeTree.gen.ts`
+- `reportOnFailure: true`
+
+No global coverage thresholds are enforced (no `thresholds: {...}` block). Per-package coverage HTML lives under each package's `coverage/` directory after `pnpm test:coverage`.
+
+## Global Setup (`vitest.setup.ts`)
+
+Applied to every project:
+
+1. `import "@testing-library/jest-dom/vitest"` — registers `toBeInTheDocument`, `toHaveAttribute`, etc.
+2. `afterEach(() => cleanup())` — explicit RTL cleanup (Vitest doesn't expose `afterEach` globally without `test.globals: true`).
+3. Polyfills for jsdom/happy-dom gaps: `ResizeObserver`, `IntersectionObserver`, `Element.prototype.scrollIntoView`, `window.matchMedia` (used by `cmdk`, Base UI, `next-themes`).
+
+## Per-Package Vitest Configs
+
+All `vitest.config.ts` files reuse the shared factory. Notable variants:
+
+- **Node default** (`packages/utils/vitest.config.ts`, `packages/api/vitest.config.ts`, `packages/db/vitest.config.ts`, `packages/schema/vitest.config.ts`, `packages/ai/vitest.config.ts`, `packages/email/vitest.config.ts`, `packages/fonts/vitest.config.ts`, `packages/env/vitest.config.ts`, `packages/auth/vitest.config.ts`, `packages/import/vitest.config.ts`, `packages/pdf/vitest.config.ts`, `packages/config/vitest.config.ts`) — `environment: "node"`.
+- **DOM** (`packages/ui/vitest.config.ts:7`) — `environment: "happy-dom"` for component tests.
+- **Web app** (`apps/web/vitest.config.ts`) — `environment: "node"` plus Vite plugins to mirror dev: `@tailwindcss/vite`, `@lingui/vite-plugin` (with `linguiTransformerBabelPreset`), and `@rolldown/plugin-babel`. Individual web tests opt into the DOM via the `@vitest-environment happy-dom` file-level comment.
+
+Per-test environment overrides (declared at the top of the file as `// @vitest-environment happy-dom` or in a `/** @vitest-environment happy-dom */` block):
+
+- `packages/utils/src/sanitize.test.ts`
+- `packages/utils/src/file.test.ts`
+- `apps/web/src/components/resume/preview.browser.test.tsx`
+- `apps/web/src/components/resume/preview.shared.test.tsx`
+- `apps/web/src/components/typography/combobox.test.tsx`
+
+## Test File Organization
+
+**Location:** Co-located with implementation. `foo.ts` lives next to `foo.test.ts` (or `foo.test.tsx` for React).
+
+**Naming:**
+- `<name>.test.ts` — Node/pure logic (e.g. `packages/utils/src/string.test.ts`).
+- `<name>.test.tsx` — JSX/component tests (e.g. `packages/ui/src/components/button.test.tsx`).
+- `<name>.node.test.ts` — Node-only modules whose implementation is also `.node.ts` (e.g. `packages/utils/src/url-security.node.test.ts`, `packages/utils/src/monorepo.node.test.ts`).
+- No `.spec.*` files in the repo today, but the include pattern supports them.
+
+**Test counts (current):** 127 `*.test.ts` files + 98 `*.test.tsx` files across `packages/` and `apps/web/src/`.
+
+**Hot spots (where coverage is densest):**
+
+- `packages/utils/src/*.test.ts` — string, color, html, date, level, locale, sanitize, rate-limit, field, file, network-icons, style, url, url-security.node, monorepo.node, plus `resume/patch.test.ts`.
+- `packages/ui/src/components/*.test.tsx` — ~30+ component tests (button, dialog, alert, badge, card, combobox, command, popover, scroll-area, sidebar, switch, tabs, textarea, toggle, tooltip, etc.).
+- `packages/pdf/src/templates/shared/*.test.ts` — columns, section-links, rich-text, metrics, picture, filtering.
+- `packages/pdf/src/section-title.test.ts` and `packages/pdf/src/hooks/use-register-fonts.test.ts`.
+- `packages/api/src/{dto,helpers,services}/*.test.ts` — `dto/resume`, `helpers/resume-access-policy`, `services/ai`.
+- `packages/schema/src/{templates,page}.test.ts` and `packages/schema/src/resume/{data,default}.test.ts`.
+- `packages/ai/src/{tools,resume}/*.test.ts` — patch-proposal, sanitize, extraction-template.
+- `packages/import/src/reactive-resume-v4-json.test.ts`, `packages/fonts/src/index.test.ts`.
+- `apps/web/src/libs/{pwa,locale,theme,error-message}.test.ts`, `apps/web/src/dialogs/store.test.ts`, `apps/web/src/components/resume/preview.{browser,shared}.test.tsx`, `apps/web/src/components/typography/combobox.test.tsx`.
+
+## Test Structure Patterns
+
+**Idiomatic skeleton** (from `packages/utils/src/string.test.ts:1-21` and `packages/api/src/helpers/resume-access-policy.test.ts:1-17`):
+
+```typescript
+import { describe, expect, it } from "vitest";
+import { thingUnderTest } from "./thing";
+
+describe("thingUnderTest", () => {
+    it("returns X for Y", () => {
+        expect(thingUnderTest(input)).toBe(expected);
+    });
+
+    it("returns Z for empty input", () => {
+        expect(thingUnderTest("")).toBe("");
+    });
+});
+```
+
+**Patterns observed:**
+
+- Top-level `describe` per exported function; nested `describe` blocks group behaviors.
+- One assertion focus per `it` — short, declarative names ("returns X", "throws Y when Z", "does not mutate the input").
+- Negative cases are first-class — every helper has tests for `null`, empty string, unknown shapes, etc.
+- `it.each([...] as const)("variant=%s renders without throwing", (variant) => {...})` for matrix tests over discriminated union variants (see `packages/ui/src/components/button.test.tsx:55-79`).
+- Setup with `beforeEach` / `afterEach` is used only when needed (timers, temp dirs, store reset). Example: `apps/web/src/dialogs/store.test.ts:4-13` resets a Zustand store between tests with `useDialogStore.setState(...)`.
+- Temp directories use `fs.mkdtempSync` + `realpathSync` and are torn down in `afterEach` (`packages/utils/src/monorepo.node.test.ts:7-17`).
+- Fake timers via `vi.useFakeTimers()` / `vi.advanceTimersByTime(300)` for animation/transition assertions (`apps/web/src/dialogs/store.test.ts:54-65`).
+
+## Mocking
+
+**Library:** Vitest's built-in `vi` (no Jest). Used sparingly — most tests cover pure functions.
+
+**Patterns:**
+
+- `vi.fn()` for callback assertions: `expect(onClick).toHaveBeenCalledOnce()` (`packages/ui/src/components/button.test.tsx:32-37`).
+- `vi.fn().mockResolvedValue(true)` for async handlers (`apps/web/src/dialogs/store.test.ts:86-93`).
+- `vi.mock("module-path", () => ({ ... }))` for replacing modules. Heaviest example: `apps/web/src/components/resume/preview.browser.test.tsx:25-81` mocks `@react-pdf/renderer`, `@/libs/resume/pdf-document`, `./builder-resume-draft`, and `./pdf-canvas` so the preview component can be exercised without React PDF.
+- `vi.hoisted(() => ({ ... }))` to share mutable state with hoisted `vi.mock` factories (`apps/web/src/components/resume/preview.browser.test.tsx:8-12`). This is required because `vi.mock` calls are hoisted above imports.
+- Spies via `vi.spyOn` are rare; mock modules are preferred so the real implementation stays out of scope.
+
+**Test data / fixtures:**
+
+- No central `fixtures/` directory. Tests build minimal objects inline or extend canonical defaults from the schema package:
+  - `import { defaultResumeData } from "@reactive-resume/schema/resume/default"` (used by `packages/api/src/helpers/resume-access-policy.test.ts:2`).
+  - `import { sampleResumeData } from "@reactive-resume/schema/resume/sample"` (used by `apps/web/src/components/resume/preview.browser.test.tsx:5`).
+- Local helper builders are inlined per test file (e.g. the `resumeDataWithPageCount` helper at `apps/web/src/components/resume/preview.browser.test.tsx:14-23`).
+
+## React Component Testing
+
+**Render + query** via Testing Library (`packages/ui/src/components/button.test.tsx`):
+
+```typescript
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+render(<Button onClick={onClick}>Click</Button>);
+await userEvent.click(screen.getByRole("button"));
+```
+
+**Accessibility-first queries:** `getByRole("button", { name: "..." })` is the default; `aria-label` is asserted explicitly (`packages/ui/src/components/button.test.tsx:81-84`).
+
+**Slot / data-attr conventions:** Components expose `data-slot` for shadcn/Base UI slotting and tests assert it (`button.test.tsx:22-25`).
+
+**Async UI:** Use `waitFor` from `@testing-library/react` and `await userEvent.*`. The `cleanup()` afterEach in `vitest.setup.ts` ensures DOM doesn't leak between tests despite `isolate: false`.
+
+## Reporters
+
+Per-package `package.json` scripts (uniform pattern, e.g. `packages/api/package.json:15-18`):
+
+- `test` → `vitest run --passWithNoTests`
+- `test:coverage` → `vitest run --coverage --passWithNoTests`
+- `test:ci` → `vitest run --coverage --reporter=default --reporter=github-actions --reporter=json --reporter=junit --outputFile.json=reports/vitest-results.json --outputFile.junit=reports/vitest-junit.xml --passWithNoTests`
+- `test:agent` → `vitest run --reporter=agent --reporter=json --outputFile.json=reports/vitest-results.json --passWithNoTests`
+
+The `agent` reporter is a Vitest 4 feature optimized for LLM-driven runs; `pnpm test:agent` is the canonical script to use when an agent needs structured pass/fail data.
+
+JUnit + JSON outputs land in `reports/` inside each package (Biome-ignored).
+
+## CI
+
+- **`.github/workflows/autofix.yml`** — runs on every PR and push to `main`. It runs `pnpm knip --fix` and `pnpm check`. **It does NOT run `pnpm test`.** Tests are not currently gating CI.
+- **`.github/workflows/docker-build.yml`** — `workflow_dispatch` only; builds multi-arch images. No test step.
+- **`.github/workflows/crowdin-sync.yml`** — translation sync only.
+
+Tests are run locally (`pnpm test`) or by agents via `pnpm test:agent` / `pnpm test:ci`. No PR is currently blocked by a failing test on GitHub Actions.
+
+## Test Types
+
+- **Unit tests** — Dominant. Pure functions in `packages/utils`, `packages/schema`, `packages/pdf/src/templates/shared`, `packages/api/src/{helpers,dto}` are exercised in isolation.
+- **Component tests** — `packages/ui/src/components/*.test.tsx` and a handful in `apps/web/src/components/`. Driven by `@testing-library/react` + `happy-dom` (file-level override) or `packages/ui`'s package-level `environment: "happy-dom"`.
+- **Integration tests** — None against the live Drizzle client or the running TanStack Start server. `apps/web/src/components/resume/preview.browser.test.tsx` is the closest, mocking React PDF and exercising the preview pipeline end-to-end in happy-dom.
+- **E2E / browser tests** — Not present. No Playwright, Cypress, or `vitest --browser` config.
+
+## Common Patterns
+
+**Async error testing:**
+
+```typescript
+expect(() => assertCanView({ userId: "u1", isPublic: false }, null)).toThrow();
+try {
+    assertCanView({ userId: "u1", isPublic: false }, null);
+    expect.unreachable();
+} catch (error: unknown) {
+    expect((error as { code?: string }).code).toBe("NOT_FOUND");
+}
+```
+(See `packages/api/src/helpers/resume-access-policy.test.ts:29-44`.)
+
+**Immutability assertions:**
+
+```typescript
+const before = JSON.stringify(resume);
+redactResumeForViewer(resume, false);
+expect(JSON.stringify(resume)).toBe(before);
+```
+(See `packages/api/src/helpers/resume-access-policy.test.ts:86-93`.)
+
+**Time-sensitive logic:** UUIDv7 ordering is verified with a `setTimeout` and a string compare instead of mocking time (`packages/utils/src/string.test.ts:15-20`).
+
+## Coverage Gaps Worth Flagging
+
+These areas have implementation but no `*.test.*` files alongside them today — agents adding features here should consider adding tests.
+
+- **`packages/email/src/transport.ts` and templates** — no tests. SMTP transport is untested.
+- **`packages/env/src/server.ts`** — no tests for env-var schema validation.
+- **`packages/auth/`** — no tests; Better Auth config and helpers are uncovered.
+- **`packages/api/src/services/{resume,storage,statistics,auth,flags,resume-events}.ts`** — only `ai.ts` has a service-level test (`ai.test.ts`). Most resume mutation flow logic is exercised only indirectly through `helpers/resume-access-policy.test.ts` and `dto/resume.test.ts`.
+- **`packages/api/src/routers/*`** — no router-level tests. End-to-end oRPC procedure behavior (auth + rate limit + service composition) is not asserted.
+- **`packages/api/src/middleware/rate-limit/*`** — no tests.
+- **`packages/db/src/schema/*`** — no tests (schema correctness is implicit, but no migration roundtrip tests).
+- **`packages/scripts/`** — no tests.
+- **`packages/runtime-externals/`** — no tests.
+- **`apps/web/src/routes/**`** — route handlers (`api/rpc.$.ts`, `api/auth.$.ts`, `api/health.ts`, `uploads/...`, `mcp/...`, `auth/oauth.ts`) and most builder UI under `routes/builder/$resumeId` are uncovered.
+- **`apps/web/src/dialogs/**`** — only `store.test.ts` covers the dialog store. Individual dialog components (resume create/update/import, two-factor, api-key) are uncovered.
+- **`packages/pdf/src/templates/{azurill,bronzor,...}`** — individual template renderers have no tests; only the shared primitives in `templates/shared/` are covered.
+
+When adding tests in any of these areas, follow the colocation rule (`foo.ts` ↔ `foo.test.ts`) and reuse `defaultResumeData` / `sampleResumeData` from `@reactive-resume/schema/resume/*` instead of inventing new fixtures.
+
+---
+
+*Testing analysis: 2026-05-11*

.vite-hooks/_/commit-msg

@@ -0,0 +1,71 @@
+#!/bin/sh
+
+if [ "$LEFTHOOK_VERBOSE" = "1" -o "$LEFTHOOK_VERBOSE" = "true" ]; then
+  set -x
+fi
+
+if [ "$LEFTHOOK" = "0" ]; then
+  exit 0
+fi
+
+call_lefthook()
+{
+  if test -n "$LEFTHOOK_BIN"
+  then
+    "$LEFTHOOK_BIN" "$@"
+  elif lefthook -h >/dev/null 2>&1
+  then
+    lefthook "$@"
+  elif /Users/amruth/Projects/reactive-resume/node_modules/.pnpm/lefthook-darwin-arm64@2.1.6/node_modules/lefthook-darwin-arm64/bin/lefthook -h >/dev/null 2>&1
+  then
+    /Users/amruth/Projects/reactive-resume/node_modules/.pnpm/lefthook-darwin-arm64@2.1.6/node_modules/lefthook-darwin-arm64/bin/lefthook "$@"
+  else
+    dir="$(git rev-parse --show-toplevel)"
+    osArch=$(uname | tr '[:upper:]' '[:lower:]')
+    cpuArch=$(uname -m | sed 's/aarch64/arm64/;s/x86_64/x64/')
+    if test -f "$dir/node_modules/lefthook-${osArch}-${cpuArch}/bin/lefthook"
+    then
+      "$dir/node_modules/lefthook-${osArch}-${cpuArch}/bin/lefthook" "$@"
+    elif test -f "$dir/node_modules/@evilmartians/lefthook/bin/lefthook-${osArch}-${cpuArch}/lefthook"
+    then
+      "$dir/node_modules/@evilmartians/lefthook/bin/lefthook-${osArch}-${cpuArch}/lefthook" "$@"
+    elif test -f "$dir/node_modules/@evilmartians/lefthook-installer/bin/lefthook"
+    then
+      "$dir/node_modules/@evilmartians/lefthook-installer/bin/lefthook" "$@"
+    elif test -f "$dir/node_modules/lefthook/bin/index.js"
+    then
+      "$dir/node_modules/lefthook/bin/index.js" "$@"
+    elif go tool lefthook -h >/dev/null 2>&1
+    then
+      go tool lefthook "$@"
+    elif bundle exec lefthook -h >/dev/null 2>&1
+    then
+      bundle exec lefthook "$@"
+    elif yarn lefthook -h >/dev/null 2>&1
+    then
+      yarn lefthook "$@"
+    elif pnpm lefthook -h >/dev/null 2>&1
+    then
+      pnpm lefthook "$@"
+    elif swift package lefthook >/dev/null 2>&1
+    then
+      swift package --build-path .build/lefthook --disable-sandbox lefthook "$@"
+    elif command -v mint >/dev/null 2>&1
+    then
+      mint run csjones/lefthook-plugin "$@"
+    elif uv run lefthook -h >/dev/null 2>&1
+    then
+      uv run lefthook "$@"
+    elif mise exec -- lefthook -h >/dev/null 2>&1
+    then
+      mise exec -- lefthook "$@"
+    elif devbox run lefthook -h >/dev/null 2>&1
+    then
+      devbox run lefthook "$@"
+    else
+      echo "Can't find lefthook in PATH"
+    fi
+  fi
+}
+
+call_lefthook run "commit-msg" "$@"

.vite-hooks/_/pre-commit

@@ -0,0 +1,71 @@
+#!/bin/sh
+
+if [ "$LEFTHOOK_VERBOSE" = "1" -o "$LEFTHOOK_VERBOSE" = "true" ]; then
+  set -x
+fi
+
+if [ "$LEFTHOOK" = "0" ]; then
+  exit 0
+fi
+
+call_lefthook()
+{
+  if test -n "$LEFTHOOK_BIN"
+  then
+    "$LEFTHOOK_BIN" "$@"
+  elif lefthook -h >/dev/null 2>&1
+  then
+    lefthook "$@"
+  elif /Users/amruth/Projects/reactive-resume/node_modules/.pnpm/lefthook-darwin-arm64@2.1.6/node_modules/lefthook-darwin-arm64/bin/lefthook -h >/dev/null 2>&1
+  then
+    /Users/amruth/Projects/reactive-resume/node_modules/.pnpm/lefthook-darwin-arm64@2.1.6/node_modules/lefthook-darwin-arm64/bin/lefthook "$@"
+  else
+    dir="$(git rev-parse --show-toplevel)"
+    osArch=$(uname | tr '[:upper:]' '[:lower:]')
+    cpuArch=$(uname -m | sed 's/aarch64/arm64/;s/x86_64/x64/')
+    if test -f "$dir/node_modules/lefthook-${osArch}-${cpuArch}/bin/lefthook"
+    then
+      "$dir/node_modules/lefthook-${osArch}-${cpuArch}/bin/lefthook" "$@"
+    elif test -f "$dir/node_modules/@evilmartians/lefthook/bin/lefthook-${osArch}-${cpuArch}/lefthook"
+    then
+      "$dir/node_modules/@evilmartians/lefthook/bin/lefthook-${osArch}-${cpuArch}/lefthook" "$@"
+    elif test -f "$dir/node_modules/@evilmartians/lefthook-installer/bin/lefthook"
+    then
+      "$dir/node_modules/@evilmartians/lefthook-installer/bin/lefthook" "$@"
+    elif test -f "$dir/node_modules/lefthook/bin/index.js"
+    then
+      "$dir/node_modules/lefthook/bin/index.js" "$@"
+    elif go tool lefthook -h >/dev/null 2>&1
+    then
+      go tool lefthook "$@"
+    elif bundle exec lefthook -h >/dev/null 2>&1
+    then
+      bundle exec lefthook "$@"
+    elif yarn lefthook -h >/dev/null 2>&1
+    then
+      yarn lefthook "$@"
+    elif pnpm lefthook -h >/dev/null 2>&1
+    then
+      pnpm lefthook "$@"
+    elif swift package lefthook >/dev/null 2>&1
+    then
+      swift package --build-path .build/lefthook --disable-sandbox lefthook "$@"
+    elif command -v mint >/dev/null 2>&1
+    then
+      mint run csjones/lefthook-plugin "$@"
+    elif uv run lefthook -h >/dev/null 2>&1
+    then
+      uv run lefthook "$@"
+    elif mise exec -- lefthook -h >/dev/null 2>&1
+    then
+      mise exec -- lefthook "$@"
+    elif devbox run lefthook -h >/dev/null 2>&1
+    then
+      devbox run lefthook "$@"
+    else
+      echo "Can't find lefthook in PATH"
+    fi
+  fi
+}
+
+call_lefthook run "pre-commit" "$@"

.vscode/extensions.json

@@ -1,3 +1,3 @@
 {
-	"recommendations": ["biomejs.biome", "bradlc.vscode-tailwindcss", "lokalise.i18n-ally"]
+	"recommendations": ["biomejs.biome", "bradlc.vscode-tailwindcss", "typescriptteam.native-preview"]
 }

.vscode/settings.json

@@ -1,36 +1,24 @@
 {
-	"[mdx]": {
-		"editor.defaultFormatter": "unifiedjs.vscode-mdx"
-	},
 	"biome.enabled": true,
 	"editor.codeActionsOnSave": {
-		"source.biome": "explicit",
 		"source.fixAll.biome": "explicit",
 		"source.organizeImports.biome": "explicit"
 	},
 	"editor.defaultFormatter": "biomejs.biome",
-	"eslint.enable": false,
-	"files.associations": {
-		"*.css": "tailwindcss"
-	},
 	"files.readonlyInclude": {
-		"locales/*.po": true,
-		"pnpm-lock.yaml": true,
-		"**/routeTree.gen.ts": true
+		"**/locales/**.po": true,
+		"**/routeTree.gen.ts": true,
+		"pnpm-lock.yaml": true
 	},
 	"files.watcherExclude": {
-		"locales/*.po": true,
-		"pnpm-lock.yaml": true,
-		"**/routeTree.gen.ts": true
+		"**/locales/**.po": true,
+		"**/routeTree.gen.ts": true,
+		"pnpm-lock.yaml": true
 	},
-	"i18n-ally.enabledParsers": ["po"],
-	"i18n-ally.localesPaths": ["locales"],
-	"i18n-ally.sourceLanguage": "en-US",
-	"prettier.enable": false,
 	"search.exclude": {
-		"locales/*.po": true,
-		"pnpm-lock.yaml": true,
-		"**/routeTree.gen.ts": true
+		"**/locales/**.po": true,
+		"**/routeTree.gen.ts": true,
+		"pnpm-lock.yaml": true
 	},
 	"tailwindCSS.classFunctions": ["cn", "cva"],
 	"tailwindCSS.experimental.classRegex": [
@@ -39,5 +27,5 @@
 		["cn\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
 	],
 	"tailwindCSS.experimental.configFile": "src/styles/globals.css",
-	"typescript.tsdk": "node_modules/typescript/lib"
+	"typescript.experimental.useTsgo": true
 }

AGENTS.md

@@ -0,0 +1,106 @@
+# AGENTS.md
+
+## Cursor Cloud specific instructions
+
+### Overview
+
+Reactive Resume is a pnpm monorepo (Turborepo) with a single full-stack web app at `apps/web` (TanStack Start / React 19 / Vite) and ~15 internal packages under `packages/`. It runs as a single Node.js process on port 3000.
+
+Internal packages are source-consumed through `package.json` export maps that point at `src` files. Do not assume package-local `dist` output exists unless a package explicitly adds it.
+
+### Prerequisites
+
+- **Node.js 24** (matches Dockerfile `ARG NODE_VERSION=24`). Use `nvm install 24 && nvm use 24` if needed.
+- **Docker** is required to run PostgreSQL. Start it with `sudo dockerd &` if the daemon isn't running.
+- **pnpm 11.0.9** is managed via corepack (`corepack enable`).
+
+### Codebase map
+
+- `apps/web` is the only app. It owns TanStack Start routes, Vite/Nitro config, PWA setup, oRPC client wiring, route-level server handlers, and the resume builder UI.
+- `packages/api` contains oRPC routers, services, DTOs, storage, resume access policy, statistics, AI services, and rate limiting. The web route `apps/web/src/routes/api/rpc.$.ts` exposes these routers at `/api/rpc`.
+- `packages/auth` contains Better Auth config, auth helper functions, and exported auth types. The web route `apps/web/src/routes/api/auth.$.ts` delegates to `auth.handler`.
+- `packages/db` contains the Drizzle client and schema. Migration files live at the repo root in `migrations/`.
+- `packages/env` defines server environment validation and auto-loads the root `.env` for app/server code.
+- `packages/schema` contains Zod schemas and typed resume/page/template models.
+- `packages/pdf` contains the React PDF document, font registration, shared template primitives, and template implementations.
+- `packages/ui` contains shared Base UI/shadcn-style components and hooks.
+- `packages/fonts`, `packages/email`, `packages/import`, `packages/ai`, `packages/utils`, `packages/scripts`, `packages/config`, and `packages/runtime-externals` provide focused support surfaces. Prefer their existing exports over adding cross-package shortcuts.
+
+### Web app conventions
+
+- Routes are file-based under `apps/web/src/routes`. Do not hand-edit `apps/web/src/routeTree.gen.ts`; it is generated by TanStack Router tooling.
+- Server-only route handlers use route `server.handlers` blocks, for example `api/rpc.$.ts`, `api/auth.$.ts`, `api/health.ts`, uploads, schema, OpenAPI, MCP, and `.well-known` routes.
+- `apps/web/src/router.tsx` initializes router context with `queryClient`, `orpc`, `theme`, `locale`, `session`, and `flags`. Reuse route context where possible instead of refetching these concerns ad hoc.
+- The builder shell lives under `apps/web/src/routes/builder/$resumeId`. The nested preview route is client-only (`ssr: false`), while the public resume route `apps/web/src/routes/$username/$slug.tsx` uses `ssr: "data-only"`.
+- Browser-only resume preview code is split across `apps/web/src/components/resume/preview.tsx`, `preview.browser.tsx`, `pdf-canvas.tsx`, and shared helpers. Keep PDF.js/canvas/browser APIs out of SSR paths.
+- The isomorphic oRPC client is in `apps/web/src/libs/orpc/client.ts`; server calls use an in-process router client and browser calls use `/api/rpc` with credentials included.
+
+### Package and feature boundaries
+
+- Add new API procedures in `packages/api/src/routers/*` and keep business logic in `packages/api/src/services/*` or helpers. Prefer `protectedProcedure` from `packages/api/src/context.ts` for authenticated procedures.
+- Add database columns/tables in `packages/db/src/schema/*`, then generate root-level migrations with `pnpm db:generate`.
+- Add or change resume data shape in `packages/schema/src/resume/*` first, then update API DTOs, importers, PDF rendering, and web forms that consume that shape.
+- Add or rename templates in all relevant places: `packages/schema/src/templates.ts`, `packages/pdf/src/templates/index.ts`, template source under `packages/pdf/src/templates/<name>/`, and static previews under `apps/web/public/templates/{jpg,pdf}`.
+- Shared PDF section filtering lives in `packages/pdf/src/templates/shared/filtering.ts`. Keep template-specific visual exceptions in the owning template directory unless multiple templates need the same behavior.
+- `packages/pdf/src/hooks/use-register-fonts.ts` owns React PDF font registration, standard PDF font handling, CJK fallback stacks, and global hyphenation behavior.
+- `packages/utils` has narrowly exported helpers. If another package needs a utility, add an explicit export path instead of importing private files.
+
+### Database
+
+PostgreSQL runs via Docker Compose:
+
+```
+sudo docker compose -f compose.dev.yml up -d postgres
+```
+
+The dev default connection string is `postgresql://postgres:postgres@localhost:5432/postgres`.
+
+**Important**: `drizzle-kit` (used by `pnpm db:migrate`) reads `DATABASE_URL` from `process.env` directly — it does **not** auto-load the `.env` file. You must `export DATABASE_URL=...` before running migration commands, or set it in your shell profile.
+
+The web app also runs migrations during Nitro startup via `apps/web/plugins/1.migrate.ts`. Manual `pnpm db:migrate` is mainly for first setup, migration debugging, or applying migrations without starting the app.
+
+### Environment
+
+Copy `.env.example` to `.env`. The three required variables are:
+
+- `APP_URL` (default `http://localhost:3000`)
+- `DATABASE_URL` (default `postgresql://postgres:postgres@localhost:5432/postgres`)
+- `AUTH_SECRET` (any non-empty string)
+
+S3/SeaweedFS is optional. If `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, and `S3_BUCKET` are all set, the app uses S3-compatible storage. The checked-in `.env.example` sets SeaweedFS defaults, so either start the `seaweedfs` compose service too or comment out those S3 vars to use local filesystem storage under `<workspace>/data`. `LOCAL_STORAGE_PATH` must be absolute when set.
+
+### Common commands
+
+| Task | Command |
+|------|---------|
+| Install deps | `pnpm install` |
+| Start Postgres only | `sudo docker compose -f compose.dev.yml up -d postgres` |
+| Start Postgres + SeaweedFS | `sudo docker compose -f compose.dev.yml up -d postgres seaweedfs seaweedfs_create_bucket` |
+| Generate migrations | `DATABASE_URL="postgresql://postgres:postgres@localhost:5432/postgres" pnpm db:generate` |
+| Run migrations | `DATABASE_URL="postgresql://postgres:postgres@localhost:5432/postgres" pnpm db:migrate` |
+| Dev server | `pnpm dev` (starts on port 3000) |
+| Web dev server only | `pnpm dev:web` |
+| Lint/format | `pnpm check` (Biome) |
+| Tests | `pnpm test` (Vitest) |
+| Build | `pnpm build` |
+| Typecheck | `pnpm typecheck` |
+
+For focused validation, prefer package filters before repo-wide commands, for example:
+
+```
+pnpm --filter web typecheck
+pnpm --filter @reactive-resume/pdf test
+pnpm --filter @reactive-resume/api test
+```
+
+Vitest test paths are package-relative when running through `pnpm --filter <package> test -- <path>`.
+
+### Gotchas
+
+- The dev server (`pnpm dev`) auto-runs migrations on startup via Nitro, so `pnpm db:migrate` is only strictly needed for first-time setup or after pulling new migration files.
+- Email sending requires SMTP config; without it, emails are logged to console. This is fine for dev — the app still functions, but email verification links appear in server logs.
+- The `lefthook.yml` pre-commit hook runs `biome check` on staged files. Run `pnpm check` before committing to avoid hook failures.
+- `pnpm check` is write-capable (`biome check --write --unsafe .`). Call that out when using it, and use narrower Biome commands if you need a non-mutating inspection.
+- Biome uses tabs, double quotes, line width 120, organized import groups, and sorted Tailwind classes for `clsx`, `cva`, and `cn`.
+- Most packages use `tsgo --noEmit` for typechecking and `vitest run --passWithNoTests` for tests.
+- There may be unrelated local edits in the worktree. Inspect `git status --short` first and avoid reverting files you did not touch.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

Dockerfile

@@ -1,48 +1,72 @@
-# syntax=docker/dockerfile:1
+# syntax=docker/dockerfile:1.7
 
-# ---------- Dependencies Layer ----------
-FROM node:24-slim AS dependencies
+ARG NODE_VERSION=24
 
-ENV PNPM_HOME="/pnpm"
-ENV PATH="$PNPM_HOME:$PATH"
-RUN corepack enable
-
-RUN mkdir -p /tmp/dev /tmp/prod
-
-COPY package.json pnpm-lock.yaml /tmp/dev/
-COPY package.json pnpm-lock.yaml /tmp/prod/
-
-RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
-    cd /tmp/dev && pnpm install --frozen-lockfile
-
-RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
-    cd /tmp/prod && pnpm install --frozen-lockfile --prod
-
-# ---------- Builder Layer ----------
-FROM node:24-slim AS builder
-
-ENV PNPM_HOME="/pnpm"
-ENV PATH="$PNPM_HOME:$PATH"
-RUN corepack enable
+FROM node:${NODE_VERSION}-slim AS base
 
 WORKDIR /app
 
-COPY --from=dependencies /tmp/dev/node_modules ./node_modules
+ENV COREPACK_ENABLE_DOWNLOAD_PROMPT=0 \
+    PNPM_HOME="/pnpm" \
+    PATH="/pnpm:$PATH" \
+    TURBO_TELEMETRY_DISABLED=1
+
+RUN corepack enable
+
+FROM base AS pruner
 COPY . .
+RUN --mount=type=cache,id=pnpm-store,target=/pnpm/store,sharing=locked \
+    pnpm dlx turbo@2.9.9 prune web --docker
 
-RUN pnpm run build
+FROM base AS builder
+COPY --from=pruner /app/out/json/ ./
+COPY --from=pruner /app/out/pnpm-lock.yaml ./pnpm-lock.yaml
+RUN --mount=type=cache,id=pnpm-store,target=/pnpm/store,sharing=locked \
+    pnpm install --frozen-lockfile
 
-# ---------- Runtime Layer ----------
-FROM node:24-slim AS runtime
+COPY --from=pruner /app/out/full/ ./
+RUN rm -rf apps/web/.output && pnpm turbo run build --filter=web --force
+
+FROM base AS runtime-pruner
+COPY . .
+RUN --mount=type=cache,id=pnpm-store,target=/pnpm/store,sharing=locked \
+    pnpm dlx turbo@2.9.9 prune @reactive-resume/runtime-externals --docker
+
+FROM base AS runtime-deps
+COPY --from=runtime-pruner /app/out/json/ ./
+COPY --from=runtime-pruner /app/out/pnpm-lock.yaml ./pnpm-lock.yaml
+RUN --mount=type=cache,id=pnpm-store,target=/pnpm/store,sharing=locked \
+    pnpm --filter=@reactive-resume/runtime-externals deploy --prod --legacy /runtime-deps
+
+FROM node:${NODE_VERSION}-slim AS runtime
+
+LABEL maintainer="amruthpillai"
+LABEL org.opencontainers.image.licenses="MIT"
+LABEL org.opencontainers.image.title="Reactive Resume"
+LABEL org.opencontainers.image.description="A free and open-source resume builder."
+LABEL org.opencontainers.image.vendor="Amruth Pillai"
+LABEL org.opencontainers.image.url="https://rxresu.me"
+LABEL org.opencontainers.image.documentation="https://docs.rxresu.me"
+LABEL org.opencontainers.image.source="https://github.com/amruthpillai/reactive-resume"
+
+ENV NODE_ENV="production" \
+    PORT=3000 \
+    LOCAL_STORAGE_PATH=/app/data
 
 WORKDIR /app
 
-ENV NODE_ENV=production
+RUN mkdir -p /app/apps/web /app/data && chown node:node /app/data
 
-COPY --from=builder /app/.output ./.output
-COPY --from=builder /app/migrations ./migrations
-COPY --from=dependencies /tmp/prod/node_modules ./node_modules
+COPY --from=runtime-deps --chown=node:node /runtime-deps/node_modules ./node_modules
+COPY --from=builder --chown=node:node /app/apps/web/.output ./apps/web/.output
+COPY --from=pruner --chown=node:node /app/migrations ./migrations
+
+WORKDIR /app/apps/web
+
+USER node
 
 EXPOSE 3000/tcp
+HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
+    CMD ["node", "-e", "fetch('http://127.0.0.1:3000/api/health').then((r) => { if (!r.ok) process.exit(1); }).catch(() => process.exit(1));"]
 
-ENTRYPOINT ["node", "-r", "reflect-metadata", ".output/server/index.mjs"]
+CMD ["node", ".output/server/index.mjs"]

ISSUE_AI_CHAT_BUILDER.md

@@ -1,194 +0,0 @@
-# Feature Request: AI Chat Builder for Resume Editing
-
-I don't know much about this, so I'm looking for volunteers to help with the implementation of this feature I'd like to see on Reactive Resume, and I hope the community finds interest in this feature too.
-
-## Prerequisites
-
-For this feature to work, the following conditions must be met:
-
-- User is logged into Reactive Resume
-- User has set up AI integration on their account
-  - This means that an AI provider, model and API key should be available for usage on the browser through `useAIStore`
-
-## User Story
-
-1. I have just created a new resume, or I am currently editing a resume I made earlier and I'm on the builder screen.
-2. I know what I want, I need to make a few edits here and there, rewrite my summary so it reads better, but I'm lazy.
-3. I see a button (outline) on the header, right next to the name on the resume and the menu icon that reads **"Build with AI"** and has a sparkles ✨ icon on its left.
-   - This button is only enabled if I have AI integration enabled. If I don't, this button shouldn't be visible at all so as to not hinder the user experience for non-AI enabled users.
-4. Clicking on the button displays a chat overlay that can be toggled open/close which covers the right portion of the screen (about 380px width).
-5. The chat window should animate open, sliding from the bottom. Below the window, there should be a floating action button which controls the visibility of this window. If the button hasn't been interacted with in the last 1 minute, hide the button until the user clicks on the "Build with AI" button again.
-6. The AI chat should display an initial greeting message. Users can type in what they want to change specifically in the resume, some examples include:
-   - "Rewrite the professional summary"
-   - "Translate all of the section headings to German"
-   - "Make my work experience descriptions more impactful"
-   - "Add keywords related to software engineering"
-7. The request should be sent using `await client.ai.chat({ input: { aiStoreData, resumeId } })`. Ideally, the oRPC chat route should explicitly accept the `resumeId` in its input and have it available in the context, ensuring that any AI-driven changes or updates are accurately mapped to the correct resume.
-8. This should display the changes to be made to the resume and apply them. Maybe using tools? I'm not too sure if that's what tools are used for.
-
-## What Already Exists
-
-The codebase already has the foundational pieces in place:
-
-### AI Store (`src/integrations/ai/store.ts`)
-
-Manages the AI configuration stored in localStorage:
-
-```typescript
-type AIStoreState = {
-  enabled: boolean;
-  provider: AIProvider; // "openai" | "gemini" | "anthropic" | "ollama" | ...;
-  model: string;
-  apiKey: string;
-  baseURL: string;
-  testStatus: TestStatus;
-};
-```
-
-You can check if AI is enabled via:
-
-```typescript
-const enabled = useAIStore((state) => state.enabled);
-```
-
-### oRPC AI Router (`src/integrations/orpc/router/ai.ts`)
-
-Existing AI endpoints that demonstrate streaming patterns:
-
-```typescript
-// Example: testConnection streams a response
-testConnection: protectedProcedure
-  .input(z.object({ provider, model, apiKey, baseURL }))
-  .handler(async function* ({ input }) {
-    const stream = streamText({
-      model: getModel(input),
-      messages: [{ role: "user", content: 'Respond with "1"' }],
-    });
-    yield* stream.textStream;
-  }),
-```
-
-The router also uses `generateText` with structured output for parsing documents - this pattern could be useful for applying changes to resume data.
-
-### Resume Store (`src/components/resume/store/resume.ts`)
-
-Provides `updateResumeData()` for modifying the resume:
-
-```typescript
-updateResumeData: (fn) => {
-  set((state) => {
-    if (!state.resume) return state;
-    if (state.resume.isLocked) {
-      // show error toast
-      return state;
-    }
-    fn(state.resume.data as WritableDraft<ResumeData>);
-    syncResume(current(state.resume));
-  });
-},
-```
-
-### Builder Header (`src/routes/builder/$resumeId/-components/header.tsx`)
-
-This is where the "Build with AI" button should be placed, next to the resume name and dropdown menu.
-
-## Technical Considerations
-
-Here are some implementation hints for anyone interested in picking this up:
-
-### 1. Button Placement
-
-Add the button in the `BuilderHeader` component, conditionally rendered based on `useAIStore().enabled`:
-
-```typescript
-const enabled = useAIStore((state) => state.enabled);
-
-// In the JSX, only show if enabled
-{enabled && (
-  <Button variant="outline" onClick={openChatPanel}>
-    <SparkleIcon />
-    Build with AI
-  </Button>
-)}
-```
-
-### 2. Chat Panel Component
-
-- Create a new component (e.g., `AIChatPanel`) that renders as an overlay
-- Width: ~380px, positioned on the right side of the screen
-- Animate in from the bottom using Framer Motion (already in the project as `motion/react`)
-- Include a floating action button (FAB) below the panel for quick toggle
-- Auto-hide the FAB after 1 minute of inactivity
-
-### 3. Chat State Management
-
-Consider creating a new Zustand store for chat state:
-
-```typescript
-type AIChatStore = {
-  isOpen: boolean;
-  messages: ChatMessage[];
-  lastInteraction: number;
-  // actions...
-};
-```
-
-### 4. oRPC Route for Chat
-
-Create a new route in `src/integrations/orpc/router/ai.ts`:
-
-```typescript
-chat: protectedProcedure
-  .input(z.object({
-    ...aiCredentialsSchema.shape,
-    resumeId: z.string(),
-    message: z.string(),
-  }))
-  .handler(async function* ({ input, context }) {
-    // Get resume data for context
-    // Stream AI response
-    // Optionally use tools for structured changes
-  }),
-```
-
-### 5. Applying Changes
-
-The tricky part is how to apply AI-suggested changes to the resume. Some options:
-
-- **AI SDK Tools**: Use the Vercel AI SDK's tool calling feature to let the AI invoke specific functions like `updateSummary`, `translateHeadings`, etc.
-- **Structured Output**: Have the AI return a JSON patch or specific update instructions that can be applied via `updateResumeData()`
-- **Diff Display**: Show proposed changes before applying them, letting users accept/reject
-
-### 6. Resume Data Schema
-
-The resume data schema is defined in `src/schema/resume/data.ts` and includes sections like:
-- `basics` (name, headline, summary, contact info)
-- `experience`, `education`, `skills`, `projects`, etc.
-- `metadata` (template, typography, colors)
-- `customSections`
-
-## Design Principles
-
-The premise is simple and nothing that hasn't been done before, but I'd like to see it done **subtly** as this is not an AI-first app, it should just be AI-enabled.
-
-- The feature should feel like an optional enhancement, not a core requirement
-- Non-AI users should not feel like they're missing out or see disabled features
-- The UI should be clean and non-intrusive
-- Performance should not be impacted when AI features are not in use
-
-## Getting Started
-
-If you're interested in contributing:
-
-1. Fork the repository
-2. Set up the development environment (see README)
-3. Configure AI settings in Dashboard > Settings > AI
-4. Start exploring the code references mentioned above
-
-## Questions?
-
-Feel free to ask questions in the comments below. I'm happy to provide more context or clarify any requirements.
-
----
-
-**Labels**: `enhancement`, `help wanted`, `good first issue`, `ai`

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amruth Pillai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,20 +1,6 @@
-<!--
-<div align="center" markdown="1">
-  <a href="https://go.warp.dev/Reactive-Resume">
-    <img alt="Warp Sponsorship" width="400" src="https://github.com/warpdotdev/brand-assets/blob/main/Github/Sponsor/Warp-Github-LG-03.png?raw=true" />
-  </a>
-
-  ### [Warp, built for coding with multiple AI agents.](https://go.warp.dev/Reactive-Resume)
-
-  [Available for MacOS, Linux, & Windows](https://go.warp.dev/Reactive-Resume)
-</div>
-
----
--->
-
 <div align="center">
   <a href="https://rxresu.me">
-    <img src="public/opengraph/banner.jpg" alt="Reactive Resume" />
+    <img src="apps/web/public/opengraph/banner.jpg" alt="Reactive Resume" />
   </a>
 
   <h1>Reactive Resume</h1>
@@ -28,15 +14,15 @@
   </p>
 
   <p>
-    <img src="https://img.shields.io/github/stars/AmruthPillai/Reactive-Resume?style=flat-square" alt="Stars" />
-    <img src="https://img.shields.io/github/license/AmruthPillai/Reactive-Resume?style=flat-square" alt="License" />
+    <img src="https://img.shields.io/github/package-json/v/amruthpillai/reactive-resume?style=flat-square" alt="Reactive Resume Version">
+    <img src="https://img.shields.io/github/stars/amruthpillai/Reactive-Resume?style=flat-square" alt="GitHub Stars">
+    <img src="https://img.shields.io/github/license/amruthpillai/Reactive-Resume?style=flat-square" alt="License" />
     <img src="https://img.shields.io/docker/pulls/amruthpillai/reactive-resume?style=flat-square" alt="Docker Pulls" />
-    <a href="https://discord.gg/hzwkZbyvUW"><img src="https://img.shields.io/discord/1173518977851473940?label=Discord&style=flat-square&logo=discord" alt="Discord" /></a>
+    <a href="https://discord.gg/aSyA5ZSxpb"><img src="https://img.shields.io/discord/1173518977851473940?style=flat-square&label=discord" alt="Discord" /></a>
     <a href="https://crowdin.com/project/reactive-resume"><img src="https://badges.crowdin.net/reactive-resume/localized.svg?style=flat-square" alt="Crowdin" /></a>
-    <a href="https://opencollective.com/reactive-resume"><img src="https://img.shields.io/opencollective/all/reactive-resume?style=flat-square" alt="Open Collective" /></a>
+    <a href="https://github.com/sponsors/AmruthPillai"><img src="https://img.shields.io/github/sponsors/AmruthPillai?style=flat-square&label=sponsors" alt="Sponsors" /></a>
+    <a href="https://opencollective.com/reactive-resume/donate"><img src="https://img.shields.io/opencollective/backers/reactive-resume?style=flat-square&label=donations" alt="Donations" /></a>
   </p>
-
-  <a href="https://www.producthunt.com/products/reactive-resume?embed=true&amp;utm_source=badge-featured&amp;utm_medium=badge&amp;utm_campaign=badge-reactive-resume-v5-2" target="_blank" rel="noopener noreferrer"><img alt="Reactive Resume v5 - A free and open-source resume builder. | Product Hunt" width="250" height="54" src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1065182&amp;theme=light&amp;t=1768850745585"></a>
 </div>
 
 ---
@@ -50,7 +36,7 @@ Built with privacy as a core principle, Reactive Resume gives you complete owner
 **Resume Building**
 
 - Real-time preview as you type
-- Multiple export formats (PDF, JSON)
+- Multiple export formats (PDF, JSON, DOCX)
 - Drag-and-drop section ordering
 - Custom sections for any content type
 - Rich text editor with formatting support
@@ -83,63 +69,71 @@ Built with privacy as a core principle, Reactive Resume gives you complete owner
 <table>
   <tr>
     <td align="center">
-      <img src="public/templates/jpg/azurill.jpg" alt="Azurill" width="150" />
+      <img src="apps/web/public/templates/jpg/azurill.jpg" alt="Azurill" width="150" />
       <br /><sub><b>Azurill</b></sub>
     </td>
     <td align="center">
-      <img src="public/templates/jpg/bronzor.jpg" alt="Bronzor" width="150" />
+      <img src="apps/web/public/templates/jpg/bronzor.jpg" alt="Bronzor" width="150" />
       <br /><sub><b>Bronzor</b></sub>
     </td>
     <td align="center">
-      <img src="public/templates/jpg/chikorita.jpg" alt="Chikorita" width="150" />
+      <img src="apps/web/public/templates/jpg/chikorita.jpg" alt="Chikorita" width="150" />
       <br /><sub><b>Chikorita</b></sub>
     </td>
     <td align="center">
-      <img src="public/templates/jpg/ditto.jpg" alt="Ditto" width="150" />
+      <img src="apps/web/public/templates/jpg/ditto.jpg" alt="Ditto" width="150" />
       <br /><sub><b>Ditto</b></sub>
     </td>
   </tr>
   <tr>
     <td align="center">
-      <img src="public/templates/jpg/gengar.jpg" alt="Gengar" width="150" />
+      <img src="apps/web/public/templates/jpg/gengar.jpg" alt="Gengar" width="150" />
       <br /><sub><b>Gengar</b></sub>
     </td>
     <td align="center">
-      <img src="public/templates/jpg/glalie.jpg" alt="Glalie" width="150" />
+      <img src="apps/web/public/templates/jpg/glalie.jpg" alt="Glalie" width="150" />
       <br /><sub><b>Glalie</b></sub>
     </td>
     <td align="center">
-      <img src="public/templates/jpg/kakuna.jpg" alt="Kakuna" width="150" />
+      <img src="apps/web/public/templates/jpg/kakuna.jpg" alt="Kakuna" width="150" />
       <br /><sub><b>Kakuna</b></sub>
     </td>
     <td align="center">
-      <img src="public/templates/jpg/lapras.jpg" alt="Lapras" width="150" />
+      <img src="apps/web/public/templates/jpg/lapras.jpg" alt="Lapras" width="150" />
       <br /><sub><b>Lapras</b></sub>
     </td>
   </tr>
   <tr>
     <td align="center">
-      <img src="public/templates/jpg/leafish.jpg" alt="Leafish" width="150" />
+      <img src="apps/web/public/templates/jpg/leafish.jpg" alt="Leafish" width="150" />
       <br /><sub><b>Leafish</b></sub>
     </td>
     <td align="center">
-      <img src="public/templates/jpg/onyx.jpg" alt="Onyx" width="150" />
+      <img src="apps/web/public/templates/jpg/onyx.jpg" alt="Onyx" width="150" />
       <br /><sub><b>Onyx</b></sub>
     </td>
     <td align="center">
-      <img src="public/templates/jpg/pikachu.jpg" alt="Pikachu" width="150" />
+      <img src="apps/web/public/templates/jpg/pikachu.jpg" alt="Pikachu" width="150" />
       <br /><sub><b>Pikachu</b></sub>
     </td>
     <td align="center">
-      <img src="public/templates/jpg/rhyhorn.jpg" alt="Rhyhorn" width="150" />
+      <img src="apps/web/public/templates/jpg/rhyhorn.jpg" alt="Rhyhorn" width="150" />
       <br /><sub><b>Rhyhorn</b></sub>
     </td>
   </tr>
   <tr>
     <td align="center">
-      <img src="public/templates/jpg/ditgar.jpg" alt="Ditgar" width="150" />
+      <img src="apps/web/public/templates/jpg/ditgar.jpg" alt="Ditgar" width="150" />
       <br /><sub><b>Ditgar</b></sub>
     </td>
+    <td align="center">
+      <img src="apps/web/public/templates/jpg/meowth.jpg" alt="Meowth" width="150" />
+      <br /><sub><b>Meowth</b></sub>
+    </td>
+    <td align="center">
+      <img src="apps/web/public/templates/jpg/scizor.jpg" alt="Scizor" width="150" />
+      <br /><sub><b>Scizor</b></sub>
+    </td>
   </tr>
 </table>
 
@@ -149,8 +143,8 @@ The quickest way to run Reactive Resume locally:
 
 ```bash
 # Clone the repository
-git clone https://github.com/AmruthPillai/Reactive-Resume.git
-cd Reactive-Resume
+git clone https://github.com/amruthpillai/reactive-resume.git
+cd reactive-resume
 
 # Start all services
 docker compose up -d
@@ -159,42 +153,45 @@ docker compose up -d
 open http://localhost:3000
 ```
 
+[![Build with Ona](https://ona.com/build-with-ona.svg)](https://app.ona.com/#https://github.com/amruthpillai/reactive-resume)
+
 For detailed setup instructions, environment configuration, and self-hosting guides, see the [documentation](https://docs.rxresu.me).
 
 ## Tech Stack
 
-| Category         | Technology                           |
-| ---------------- | ------------------------------------ |
-| Framework        | TanStack Start (React 19, Vite)      |
-| Runtime          | Node.js                              |
-| Language         | TypeScript                           |
-| Database         | PostgreSQL with Drizzle ORM          |
-| API              | ORPC (Type-safe RPC)                 |
-| Auth             | Better Auth                          |
-| Styling          | Tailwind CSS                         |
-| UI Components    | Radix UI                             |
-| State Management | Zustand + TanStack Query             |
+| Category         | Technology                      |
+| ---------------- | ------------------------------- |
+| Framework        | TanStack Start (React 19, Vite) |
+| Runtime          | Node.js                         |
+| Language         | TypeScript                      |
+| Database         | PostgreSQL with Drizzle ORM     |
+| API              | ORPC (Type-safe RPC)            |
+| Auth             | Better Auth                     |
+| Styling          | Tailwind CSS                    |
+| UI Components    | Radix UI                        |
+| State Management | Zustand + TanStack Query        |
 
 ## Documentation
 
 Comprehensive guides are available at [docs.rxresu.me](https://docs.rxresu.me):
 
-| Guide                                                                       | Description                       |
-| --------------------------------------------------------------------------- | --------------------------------- |
-| [Getting Started](https://docs.rxresu.me/getting-started)                   | First-time setup and basic usage  |
-| [Self-Hosting](https://docs.rxresu.me/guides/self-hosting-with-docker)      | Deploy on your own server         |
-| [Development Setup](https://docs.rxresu.me/contributing/development)        | Local development environment     |
-| [Project Architecture](https://docs.rxresu.me/contributing/architecture)    | Codebase structure and patterns   |
-| [Exporting Your Resume](https://docs.rxresu.me/guides/exporting-your-resume)| PDF and JSON export options       |
+| Guide                                                                        | Description                      |
+| ---------------------------------------------------------------------------- | -------------------------------- |
+| [Getting Started](https://docs.rxresu.me/getting-started)                    | First-time setup and basic usage |
+| [Self-Hosting](https://docs.rxresu.me/self-hosting/docker)                   | Deploy on your own server        |
+| [Development Setup](https://docs.rxresu.me/contributing/development)         | Local development environment    |
+| [Project Architecture](https://docs.rxresu.me/contributing/architecture)     | Codebase structure and patterns  |
+| [Exporting Your Resume](https://docs.rxresu.me/guides/exporting-your-resume) | PDF and JSON export options      |
 
 ## Self-Hosting
 
 Reactive Resume can be self-hosted using Docker. The stack includes:
 
 - **PostgreSQL** — Database for storing user data and resumes
-- **Gotenberg** — Headless Chrome service for PDF generation
 - **SeaweedFS** (optional) — S3-compatible storage for file uploads
 
+> **From v5.1.0 onwards** — PDF generation now runs entirely client-side via `@react-pdf/renderer`. New deployments no longer require Browserless, Chromium, or any external print service as a dependency. The `PRINTER_*` and `BROWSERLESS_*` environment variables are no longer read and can be removed from your `.env`.
+
 Pull the latest image from Docker Hub or GitHub Container Registry:
 
 ```bash
@@ -205,7 +202,7 @@ docker pull amruthpillai/reactive-resume:latest
 docker pull ghcr.io/amruthpillai/reactive-resume:latest
 ```
 
-See the [self-hosting guide](https://docs.rxresu.me/guides/self-hosting-with-docker) for complete instructions.
+See the [self-hosting guide](https://docs.rxresu.me/self-hosting/docker) for complete instructions.
 
 ## Support
 
@@ -215,7 +212,7 @@ Reactive Resume is and always will be free and open-source. If it has helped you
   <a href="https://github.com/sponsors/AmruthPillai">
     <img src="https://img.shields.io/badge/GitHub%20Sponsors-Support-ea4aaa?style=flat-square&logo=github-sponsors" alt="GitHub Sponsors" />
   </a>
-  <a href="https://opencollective.com/reactive-resume">
+  <a href="https://opencollective.com/reactive-resume/donate">
     <img src="https://img.shields.io/badge/Open%20Collective-Contribute-7FADF2?style=flat-square&logo=open-collective" alt="Open Collective" />
   </a>
 </p>
@@ -227,6 +224,16 @@ Other ways to support:
 - Improve documentation
 - Help with translations
 
+## Star History
+
+<a href="https://www.star-history.com/#amruthpillai/reactive-resume&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=amruthpillai/reactive-resume&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=amruthpillai/reactive-resume&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=amruthpillai/reactive-resume&type=date&legend=top-left" />
+ </picture>
+</a>
+
 ## Contributing
 
 Contributions make open-source thrive. Whether fixing a typo or adding a feature, all contributions are welcome.

SECURITY.md

@@ -0,0 +1,34 @@
+# Security Policy
+
+## Supported Versions
+
+Reactive Resume provides security updates for version `5.0.x` and newer.
+Earlier major versions are no longer supported.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| >= 5.0  | :white_check_mark: |
+| 4.x     | :x:                |
+| < 4.0   | :x:                |
+
+## Reporting a Vulnerability
+
+If you believe you have found a security vulnerability, please report it
+privately instead of opening a public issue.
+
+Preferred reporting channels:
+
+- Use GitHub's private vulnerability reporting for this repository.
+- If that is unavailable, email `hello@amruthpillai.com` with the subject
+  `Security Vulnerability: Reactive Resume`.
+
+Please include as much detail as possible, including:
+
+- A description of the vulnerability and its impact.
+- Steps to reproduce or a proof of concept.
+- Affected versions, configuration, or deployment details.
+- Any relevant logs, screenshots, or links.
+
+You can expect an initial response within 7 days. If the report is accepted,
+we will coordinate remediation and disclosure timing with you before publishing
+details publicly.

apps/web/components.json

@@ -0,0 +1,25 @@
+{
+	"$schema": "https://ui.shadcn.com/schema.json",
+	"style": "base-nova",
+	"rsc": false,
+	"tsx": true,
+	"tailwind": {
+		"config": "",
+		"css": "../../packages/ui/src/styles/globals.css",
+		"baseColor": "zinc",
+		"cssVariables": true,
+		"prefix": ""
+	},
+	"iconLibrary": "phosphor",
+	"aliases": {
+		"components": "@reactive-resume/ui/components",
+		"utils": "@reactive-resume/utils/style",
+		"hooks": "@reactive-resume/ui/hooks",
+		"lib": "@reactive-resume/utils",
+		"ui": "@reactive-resume/ui/components"
+	},
+	"rtl": true,
+	"menuColor": "default-translucent",
+	"menuAccent": "subtle",
+	"registries": {}
+}

apps/web/lingui.config.ts

@@ -1,4 +1,5 @@
 import { defineConfig } from "@lingui/cli";
+import { formatter } from "@lingui/format-po";
 
 export default defineConfig({
 	sourceLocale: "en-US",
@@ -16,6 +17,7 @@ export default defineConfig({
 		"de-DE",
 		"el-GR",
 		"en-US",
+		"en-GB",
 		"es-ES",
 		"fa-IR",
 		"fi-FI",
@@ -44,6 +46,7 @@ export default defineConfig({
 		"ro-RO",
 		"ru-RU",
 		"sk-SK",
+		"sl-SI",
 		"sq-AL",
 		"sr-SP",
 		"sv-SE",
@@ -62,6 +65,9 @@ export default defineConfig({
 		"zu-ZA": "en-US",
 		default: "en-US",
 	},
+	format: formatter({
+		lineNumbers: false,
+	}),
 	catalogs: [
 		{
 			path: "<rootDir>/locales/{locale}",

apps/web/package.json

@@ -0,0 +1,109 @@
+{
+	"name": "web",
+	"version": "0.0.0",
+	"type": "module",
+	"private": true,
+	"scripts": {
+		"build": "rm -rf .output && vite build",
+		"dev": "vite dev",
+		"serve": "vite preview",
+		"start": "node .output/server/index.mjs",
+		"typecheck": "tsgo --noEmit",
+		"test": "vitest run --passWithNoTests",
+		"test:coverage": "vitest run --coverage --passWithNoTests",
+		"test:ci": "vitest run --coverage --reporter=default --reporter=github-actions --reporter=json --reporter=junit --outputFile.json=reports/vitest-results.json --outputFile.junit=reports/vitest-junit.xml --passWithNoTests",
+		"test:agent": "vitest run --reporter=agent --reporter=json --outputFile.json=reports/vitest-results.json --passWithNoTests",
+		"lingui:extract": "lingui extract --clean --overwrite"
+	},
+	"dependencies": {
+		"@ai-sdk/react": "^3.0.182",
+		"@base-ui/react": "^1.4.1",
+		"@better-auth/api-key": "^1.6.11",
+		"@better-auth/infra": "^0.2.8",
+		"@better-auth/oauth-provider": "^1.6.11",
+		"@better-auth/passkey": "^1.6.11",
+		"@dnd-kit/core": "^6.3.1",
+		"@dnd-kit/sortable": "^10.0.0",
+		"@dnd-kit/utilities": "^3.2.2",
+		"@lingui/core": "^6.0.1",
+		"@lingui/react": "^6.0.1",
+		"@modelcontextprotocol/sdk": "^1.29.0",
+		"@orpc/client": "^1.14.3",
+		"@orpc/json-schema": "^1.14.3",
+		"@orpc/openapi": "^1.14.3",
+		"@orpc/server": "^1.14.3",
+		"@orpc/tanstack-query": "^1.14.3",
+		"@orpc/zod": "^1.14.3",
+		"@phosphor-icons/react": "^2.1.10",
+		"@react-pdf/renderer": "^4.5.1",
+		"@reactive-resume/ai": "workspace:*",
+		"@reactive-resume/api": "workspace:*",
+		"@reactive-resume/auth": "workspace:*",
+		"@reactive-resume/db": "workspace:*",
+		"@reactive-resume/env": "workspace:*",
+		"@reactive-resume/fonts": "workspace:*",
+		"@reactive-resume/import": "workspace:*",
+		"@reactive-resume/pdf": "workspace:*",
+		"@reactive-resume/schema": "workspace:*",
+		"@reactive-resume/ui": "workspace:*",
+		"@reactive-resume/utils": "workspace:*",
+		"@tailwindcss/vite": "^4.3.0",
+		"@tanstack/react-form": "^1.32.0",
+		"@tanstack/react-hotkeys": "^0.10.0",
+		"@tanstack/react-query": "^5.100.10",
+		"@tanstack/react-router": "^1.169.2",
+		"@tanstack/react-router-ssr-query": "^1.166.12",
+		"@tanstack/react-start": "^1.167.65",
+		"@tiptap/extension-color": "^3.23.2",
+		"@tiptap/extension-highlight": "^3.23.2",
+		"@tiptap/extension-table": "^3.23.2",
+		"@tiptap/extension-text-align": "^3.23.2",
+		"@tiptap/extension-text-style": "^3.23.2",
+		"@tiptap/pm": "^3.23.2",
+		"@tiptap/react": "^3.23.2",
+		"@tiptap/starter-kit": "^3.23.2",
+		"@types/js-cookie": "^3.0.6",
+		"@uiw/color-convert": "^2.10.1",
+		"@uiw/react-color-colorful": "^2.10.1",
+		"better-auth": "1.6.11",
+		"cmdk": "^1.1.1",
+		"drizzle-orm": "1.0.0-beta.22",
+		"es-toolkit": "^1.46.1",
+		"fuse.js": "^7.3.0",
+		"immer": "^11.1.8",
+		"js-cookie": "^3.0.5",
+		"motion": "^12.38.0",
+		"pdfjs-dist": "5.7.284",
+		"pg": "^8.20.0",
+		"qrcode.react": "^4.2.0",
+		"react": "^19.2.6",
+		"react-dom": "^19.2.6",
+		"react-resizable-panels": "^4.11.0",
+		"react-window": "^2.2.7",
+		"react-zoom-pan-pinch": "^4.0.3",
+		"sonner": "^2.0.7",
+		"srvx": "^0.11.15",
+		"ts-pattern": "^5.9.0",
+		"usehooks-ts": "^3.1.1",
+		"zod": "^4.4.3",
+		"zustand": "^5.0.13"
+	},
+	"devDependencies": {
+		"@lingui/babel-plugin-lingui-macro": "^6.0.1",
+		"@lingui/cli": "^6.0.1",
+		"@lingui/format-po": "^6.0.1",
+		"@lingui/vite-plugin": "^6.0.1",
+		"@reactive-resume/config": "workspace:*",
+		"@rolldown/plugin-babel": "^0.2.3",
+		"@types/pg": "^8.20.0",
+		"@types/react": "^19.2.14",
+		"@types/react-dom": "^19.2.3",
+		"@typescript/native-preview": "7.0.0-dev.20260512.1",
+		"@vitejs/plugin-react": "^6.0.1",
+		"babel-plugin-macros": "^3.1.0",
+		"nitro": "3.0.260429-beta",
+		"typescript": "^6.0.3",
+		"vite": "^8.0.12",
+		"vite-plugin-pwa": "^1.3.0"
+	}
+}

apps/web/plugins/1.migrate.ts

@@ -0,0 +1,40 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { migrate } from "drizzle-orm/node-postgres/migrator";
+import { definePlugin } from "nitro";
+import { Pool } from "pg";
+import { env } from "@reactive-resume/env/server";
+
+function resolveMigrationsFolder(): string {
+	let dir = import.meta.dirname;
+
+	while (dir !== path.dirname(dir)) {
+		const candidate = path.join(dir, "migrations");
+		if (existsSync(candidate)) return candidate;
+		dir = path.dirname(dir);
+	}
+
+	throw new Error(`Could not locate migrations folder relative to ${import.meta.dirname}`);
+}
+
+const migrationsFolder = resolveMigrationsFolder();
+
+export default definePlugin(async () => {
+	console.info("Running database migrations...");
+
+	const connectionString = env.DATABASE_URL;
+
+	const pool = new Pool({ connectionString });
+	const db = drizzle({ client: pool });
+
+	try {
+		await migrate(db, { migrationsFolder });
+		console.info("Database migrations completed");
+	} catch (error) {
+		console.error("Database migrations failed", { error });
+		throw error;
+	} finally {
+		await pool.end();
+	}
+});

apps/web/plugins/2.storage.ts

@@ -0,0 +1,24 @@
+import fs from "node:fs/promises";
+import { definePlugin } from "nitro";
+import { env } from "@reactive-resume/env/server";
+import { getLocalDataDirectory } from "@reactive-resume/utils/monorepo.node";
+
+export default definePlugin(async () => {
+	if (env.S3_ACCESS_KEY_ID && env.S3_SECRET_ACCESS_KEY && env.S3_BUCKET) return;
+
+	const dataDirectory = getLocalDataDirectory(env.LOCAL_STORAGE_PATH);
+	console.info(`Validating local storage path: ${dataDirectory}`);
+
+	try {
+		await fs.mkdir(dataDirectory, { recursive: true });
+		await fs.access(dataDirectory, fs.constants.R_OK | fs.constants.W_OK);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : "Unknown error";
+		console.error(
+			`Local storage path is not writable: ${dataDirectory}\n` +
+				`  ${message}\n` +
+				"Set LOCAL_STORAGE_PATH to a writable directory or fix permissions on the existing path.",
+		);
+		throw error;
+	}
+});

apps/web/public/funding.json

@@ -5,7 +5,7 @@
 		"type": "individual",
 		"role": "maintainer",
 		"name": "Amruth Pillai",
-		"email": "im.amruth@gmail.com",
+		"email": "hello@amruthpillai.com",
 		"description": "Software Engineer",
 		"webpageUrl": {
 			"url": "https://rxresu.me/funding.json"
@@ -20,8 +20,8 @@
 				"url": "https://rxresu.me"
 			},
 			"repositoryUrl": {
-				"url": "https://github.com/AmruthPillai/Reactive-Resume",
-				"wellKnown": "https://github.com/AmruthPillai/Reactive-Resume/blob/main/.github/.well-known/funding-manifest-urls"
+				"url": "https://github.com/amruthpillai/reactive-resume",
+				"wellKnown": "https://github.com/amruthpillai/reactive-resume/blob/main/.github/.well-known/funding-manifest-urls"
 			},
 			"licenses": ["spdx:MIT"],
 			"tags": ["data", "design", "productivity", "resume-builder"]
@@ -61,7 +61,7 @@
 				"guid": "open-collective",
 				"type": "payment-provider",
 				"description": "Open Collective",
-				"address": "https://opencollective.com/reactive-resume"
+				"address": "https://opencollective.com/reactive-resume/donate"
 			}
 		]
 	}