Add Vercel OSS Program badge to README

Workflows now run on GitHub-hosted runners unless the repository
variable USE_BLACKSMITH is "true", so forks work without setup. When
enabled, jobs run on Blacksmith runners (32 vCPU for build/test, 2 vCPU
for lightweight jobs) and use useblacksmith/checkout,
useblacksmith/setup-docker-builder, and useblacksmith/build-push-action.
Docker layer caches are keyed per architecture.

Replaces the CI_RUNNER_X64 and CI_RUNNER_ARM64 variables.

.codacy.yml

@@ -0,0 +1,3 @@
+---
+exclude_paths:
+  - "migrations/**"

.devcontainer/Dockerfile

@@ -1,10 +0,0 @@
-FROM mcr.microsoft.com/devcontainers/typescript-node:24
-
-RUN corepack enable
-
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    git \
-    curl \
-    && rm -rf /var/lib/apt/lists/*
-
-EXPOSE 3000

.devcontainer/devcontainer.json

@@ -1,32 +0,0 @@
-{
-	"name": "Reactive Resume",
-	"service": "reactive_resume",
-	"dockerComposeFile": "docker-compose.yml",
-	"workspaceFolder": "/workspace",
-
-	"forwardPorts": [3000, 4000, 5432, 8333],
-	"portsAttributes": {
-		"3000": { "label": "Reactive Resume", "onAutoForward": "openBrowser" },
-		"4000": { "label": "Browserless (Printer)" },
-		"5432": { "label": "PostgreSQL" },
-		"8333": { "label": "SeaweedFS (S3)" }
-	},
-
-	"customizations": {
-		"vscode": {
-			"extensions": ["biomejs.biome", "bradlc.vscode-tailwindcss", "lokalise.i18n-ally"],
-			"settings": {
-				"biome.enabled": true,
-				"editor.codeActionsOnSave": {
-					"source.biome": "explicit",
-					"source.fixAll.biome": "explicit",
-					"source.organizeImports.biome": "explicit"
-				},
-				"editor.defaultFormatter": "biomejs.biome",
-				"typescript.tsdk": "node_modules/typescript/lib"
-			}
-		}
-	},
-
-	"postCreateCommand": "corepack enable && pnpm install"
-}

.devcontainer/docker-compose.yml

@@ -1,96 +0,0 @@
-services:
-  reactive_resume:
-    build:
-      context: ..
-      dockerfile: .devcontainer/Dockerfile
-    volumes:
-      - ..:/workspace:cached
-    command: sleep infinity
-    depends_on:
-      postgres:
-        condition: service_healthy
-      browserless:
-        condition: service_started
-      seaweedfs:
-        condition: service_healthy
-      seaweedfs_create_bucket:
-        condition: service_completed_successfully
-    environment:
-      TZ: Etc/UTC
-      APP_URL: http://localhost:3000
-      PRINTER_APP_URL: http://reactive_resume:3000
-      PRINTER_ENDPOINT: ws://browserless:3000?token=1234567890
-      DATABASE_URL: postgresql://postgres:postgres@postgres:5432/postgres
-      AUTH_SECRET: change-me-to-a-secure-secret-key-in-production
-      S3_ACCESS_KEY_ID: seaweedfs
-      S3_SECRET_ACCESS_KEY: seaweedfs
-      S3_REGION: us-east-1
-      S3_ENDPOINT: http://seaweedfs:8333
-      S3_BUCKET: reactive-resume
-      S3_FORCE_PATH_STYLE: "true"
-
-  postgres:
-    image: postgres:latest
-    restart: unless-stopped
-    environment:
-      POSTGRES_DB: postgres
-      POSTGRES_USER: postgres
-      POSTGRES_PASSWORD: postgres
-    volumes:
-      - postgres_data:/var/lib/postgresql
-    healthcheck:
-      test: ["CMD", "pg_isready", "-U", "postgres", "-d", "postgres"]
-      start_period: 10s
-      interval: 30s
-      timeout: 10s
-      retries: 3
-
-  browserless:
-    image: ghcr.io/browserless/chromium:latest
-    restart: unless-stopped
-    environment:
-      QUEUED: "10"
-      HEALTH: "true"
-      CONCURRENT: "5"
-      TOKEN: "1234567890"
-    healthcheck:
-      test:
-        ["CMD", "curl", "-f", "http://localhost:3000/pressure?token=1234567890"]
-      interval: 10s
-      timeout: 5s
-      retries: 10
-
-  seaweedfs:
-    image: chrislusf/seaweedfs:latest
-    restart: unless-stopped
-    command: server -s3 -filer -dir=/data -ip=0.0.0.0
-    environment:
-      AWS_ACCESS_KEY_ID: seaweedfs
-      AWS_SECRET_ACCESS_KEY: seaweedfs
-    volumes:
-      - seaweedfs_data:/data
-    healthcheck:
-      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://localhost:8888"]
-      start_period: 10s
-      interval: 30s
-      timeout: 10s
-      retries: 3
-
-  seaweedfs_create_bucket:
-    image: quay.io/minio/mc:latest
-    restart: on-failure
-    entrypoint: >
-      /bin/sh -c "
-        until mc alias set seaweedfs http://seaweedfs:8333 seaweedfs seaweedfs; do
-          echo 'Waiting for SeaweedFS...';
-          sleep 2;
-        done;
-        mc mb seaweedfs/reactive-resume --ignore-existing;
-      "
-    depends_on:
-      seaweedfs:
-        condition: service_healthy
-
-volumes:
-  postgres_data:
-  seaweedfs_data:

.dockerignore

@@ -1,15 +1,32 @@
-dist
-docs
+# VCS and editor state
+.git
+.gitignore
+.cursor
+.DS_Store
+.vite-hooks
+
+# 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,77 +1,147 @@
-# --- Server ---
-TZ="Etc/UTC"
+# --- Application ---
+# Public port used by the production server and the Vite web server in local development.
+PORT="3000"
+
+# Port used by the Hono server in local development. Vite proxies API requests to this port.
+SERVER_PORT="3001"
+
+# 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
-# PLEASE READ: This should be set to an internal 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.
-# This is required when the printer service is running inside Docker, and cannot reach the app via the APP URL,
-# which is usually when the APP_URL is localhost or a local network IP/hostname.
-PRINTER_APP_URL="http://host.docker.internal:3000"
+# Optional: serve one already-public resume at /. Use the ID from /builder/<id>.
+# Unset or blank keeps the marketing home. Restart after changes.
+# ROOT_RESUME_ID=
 
-# --- Printer ---
-PRINTER_ENDPOINT="ws://localhost:4000?token=1234567890"
+# Vercel: APP_URL can be omitted; production uses VERCEL_PROJECT_PRODUCTION_URL.
 
 # --- Database (PostgreSQL) ---
-DATABASE_URL="postgresql://postgres:postgres@localhost:5432/postgres"
+# 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@postgres:5432/postgres"
+
+# Optional direct connection for migrations (Neon: DATABASE_URL_UNPOOLED alias).
+# DATABASE_MIGRATION_URL=""
+# DATABASE_POOL_MAX="10"
+
+# When "true", the server refuses to boot if the live database schema has drifted from
+# the migration ledger (e.g. a table dropped outside migrations). Default "false" logs
+# the drift loudly at startup and continues.
+STRICT_SCHEMA_CHECK="false"
 
 # --- 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"
 
 # --- Email (optional) ---
-# If all keys are disabled, the app logs the email to be sent to the console instead.
-SMTP_HOST="localhost"
-SMTP_PORT="1025"
+# If SMTP_HOST, SMTP_USER, SMTP_PASS, or SMTP_FROM is missing, the app logs the
+# email to the console instead.
+SMTP_HOST=""
+SMTP_PORT=""
 SMTP_USER=""
 SMTP_PASS=""
 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.
+# Backend defaults to S3 when all credentials are present, otherwise local.
+# Vercel defaults to private Blob. Explicit selection: local, s3, blob.
+# STORAGE_BACKEND="local"
+# BLOB_READ_WRITE_TOKEN=""
+# BLOB_STORE_ID=""
+# DEPLOYMENT_NAMESPACE="default"
+# Vercel previews need isolated resources before setting ALLOW_PREVIEW_MIGRATIONS=true.
+
+# If all S3 keys are disabled, Docker 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"
 S3_SECRET_ACCESS_KEY="seaweedfs"
 S3_REGION="us-east-1"
-S3_ENDPOINT="http://localhost:8333"
+S3_ENDPOINT="http://seaweedfs:8333"
 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"
+# --- AI Agent Workspace (optional) ---
+# Required for the authenticated /agent workspace and saved AI providers.
+# Redis also shares rate limits, resume events, cancellation and view deduplication.
+# Vercel Upstash KV_URL is accepted as an alias for REDIS_URL.
+REDIS_URL="redis://redis:6379"
+ENCRYPTION_SECRET="change-me-to-a-secure-agent-secret-in-production"
 
+# --- Feature Flags ---
 # This flag disables new signups, both on the web app and the server.
 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.
+# 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"
 
+# This flag disables API rate limiting for authentication endpoints.
+# Rate limiting is enabled by default in production to prevent abuse.
+FLAG_DISABLE_API_RATE_LIMIT="false"
+
+
+# Allows dynamic OAuth client registration to use any parseable redirect URI,
+# including custom schemes, private hosts, and non-loopback http:// URLs.
+# WARNING: Enabling this on a public or multi-tenant deployment can enable phishing
+# or token exfiltration. Only enable this on a trusted, self-hosted instance.
+FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI="false"
+
+# Allows AI providers to be configured with any base URL, including http:// and
+# private/loopback addresses (e.g. http://localhost:11434 for a local Ollama instance).
+# WARNING: Enabling this on a multi-tenant deployment is a Server-Side Request Forgery (SSRF)
+# risk. Only enable this on a trusted, single-tenant self-hosted instance.
+FLAG_ALLOW_UNSAFE_AI_BASE_URL="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_API_TOKEN=""

.gitattributes

@@ -1 +0,0 @@
-locales/*.po linguist-generated=true

.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"
@@ -15,13 +15,13 @@
 		{
 			"guid": "reactive-resume",
 			"name": "Reactive Resume",
-			"description": "A free and open-source resume builder that simplifies the process of creating, updating, and sharing your resume.",
+			"description": "A free and open-source resume builder that makes it easy to create, update, and share your resume.",
 			"webpageUrl": {
 				"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/reactive-resume/reactive-resume",
+				"wellKnown": "https://github.com/reactive-resume/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

@@ -1,67 +1,124 @@
 name: 🐞 Bug Report
 
-description: Create a bug report to help improve Reactive Resume
+description: Report a reproducible problem with Reactive Resume
 
-title: "[Bug] <title>"
-labels: [bug, v5, needs triage]
-assignees: "AmruthPillai"
+labels: ["bug", "status: needs triage"]
+assignees: []
 
 body:
   - type: checkboxes
     attributes:
-      label: Is there an existing issue for this?
-      description: Please search to see if an issue already exists for the bug you encountered.
+      label: Existing issue
+      description: Search open and closed issues before submitting a new report.
       options:
-        - label: Yes, I have searched the existing issues and none of them match my problem.
+        - label: I searched the existing issues and could not find a matching report.
           required: true
 
   - type: dropdown
     id: variant
     attributes:
-      label: Product Variant
-      description: What variant of Reactive Resume are you using?
+      label: Product variant
+      description: Where does the problem occur?
       options:
-        - Cloud (https://rxresu.me)
-        - Self-Hosted
+        - Cloud
+        - Self-hosted
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Reactive Resume version
+      description: Find this in Settings or provide the container image tag or commit SHA.
+      placeholder: 5.2.6
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      description: Choose the part of Reactive Resume most closely related to the problem.
+      options:
+        - Resume builder & data
+        - Templates, preview & export
+        - Accounts & sharing
+        - AI & Agent
+        - Language & localization
+        - Self-hosting
+        - API & integrations
+        - Applications & cover letters
+        - Other / unsure
+    validations:
+      required: true
+
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      description: Include your operating system and browser. For self-hosted installations, also include the deployment method.
+      placeholder: Firefox 143 on Ubuntu 26.04, deployed with Docker Compose
     validations:
       required: true
 
   - type: textarea
+    id: summary
     attributes:
-      label: Describe the bug you're experiencing
-      description: A detailed description of what you're experiencing. Please provide as much detail as possible as it will help me diagnose and fix the issue faster.
+      label: Summary
+      description: Briefly describe the problem and its impact.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      description: Provide the smallest reliable sequence that demonstrates the problem.
+      placeholder: |
+        1. Open ...
+        2. Select ...
+        3. Observe ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
     validations:
       required: true
 
   - type: dropdown
     id: template
     attributes:
-      label: What template are you using?
-      description: Leave blank if the issue applies to all templates, or is not template-specific.
-      multiple: false
+      label: Template
+      description: Leave blank when the problem is not template-specific.
       options:
         - Azurill
         - Bronzor
         - Chikorita
-        - Ditto
         - Ditgar
+        - Ditto
         - Gengar
         - Glalie
         - Kakuna
         - Lapras
         - Leafish
+        - Meowth
         - Onyx
         - Pikachu
         - Rhyhorn
-    validations:
-      required: false
+        - Scizor
 
   - type: textarea
+    id: logs
     attributes:
-      label: Anything else?
-      description: |
-        Links? References? Anything that will give us more context about the issue you are encountering!
-
-        Tip: You can attach images or log files by clicking this area to highlight it and then dragging files in.
-    validations:
-      required: false
+      label: Logs and screenshots
+      description: Add relevant logs, screenshots, or a minimal reproduction. Remove secrets and personal resume data first.

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

@@ -1,23 +1,82 @@
 name: ✨ Feature Request
 
-description: Suggest an feature or idea that you would like to see in Reactive Resume
+description: Propose an actionable improvement to Reactive Resume
 
-title: "[Feature] <title>"
-labels: [enhancement, v5, needs triage]
-assignees: "AmruthPillai"
+labels: ["enhancement", "status: needs triage"]
+assignees: []
 
 body:
   - type: checkboxes
     attributes:
-      label: Is there an existing issue for this feature?
-      description: Please search to see if an issue already exists for the feature you requested.
+      label: Existing issue
+      description: Search open and closed issues before submitting a new proposal.
       options:
-        - label: Yes, I have searched the existing issues and it doesn't exist.
+        - label: I searched the existing issues and could not find a matching proposal.
           required: true
 
-  - type: textarea
+  - type: dropdown
+    id: variant
     attributes:
-      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.
+      label: Product variant
+      description: Choose the primary environment for this proposal.
+      options:
+        - Cloud
+        - Self-hosted
     validations:
-      required: true
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      description: Choose the part of Reactive Resume most closely related to the proposal.
+      options:
+        - Resume builder & data
+        - Templates, preview & export
+        - Accounts & sharing
+        - AI & Agent
+        - Language & localization
+        - Self-hosting
+        - API & integrations
+        - Applications & cover letters
+        - Other / unsure
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What user problem or limitation should Reactive Resume solve?
+    validations:
+      required: true
+
+  - type: textarea
+    id: outcome
+    attributes:
+      label: Desired outcome
+      description: Describe the behavior you want without prescribing an implementation.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Describe current workarounds or alternatives. Write "None" if there are none.
+    validations:
+      required: true
+
+  - type: textarea
+    id: scope
+    attributes:
+      label: Proposed scope
+      description: Explain what should be included and what can remain out of scope.
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Add examples, mockups, or related issues when useful. Remove personal resume data first.

.github/ISSUE_TEMPLATE/config.yml

@@ -1 +1,8 @@
-blank_issues_enabled: false
+blank_issues_enabled: false
+contact_links:
+  - name: Questions and support
+    url: https://github.com/reactive-resume/reactive-resume/discussions/categories/q-a
+    about: Get help with setup, configuration, and using Reactive Resume.
+  - name: Security vulnerability
+    url: https://github.com/reactive-resume/reactive-resume/security/advisories/new
+    about: Report security vulnerabilities privately.

.github/actionlint.yaml

@@ -0,0 +1,5 @@
+self-hosted-runner:
+  labels:
+    - blacksmith-2vcpu-ubuntu-2404
+    - blacksmith-32vcpu-ubuntu-2404
+    - blacksmith-32vcpu-ubuntu-2404-arm

.github/copilot-instructions.md

@@ -0,0 +1,17 @@
+<!-- caveman-begin -->
+Respond terse like smart caveman. All technical substance stay. Only fluff die.
+
+Rules:
+- Drop: articles (a/an/the), filler (just/really/basically), pleasantries, hedging
+- Fragments OK. Short synonyms. Technical terms exact. Code unchanged.
+- Pattern: [thing] [action] [reason]. [next step].
+- Not: "Sure! I'd be happy to help you with that."
+- Yes: "Bug in auth middleware. Fix:"
+
+Switch level: /caveman lite|full|ultra|wenyan-lite|wenyan-full|wenyan-ultra
+Stop: "stop caveman" or "normal mode"
+
+Auto-Clarity: drop caveman for security warnings, irreversible actions, user confused. Resume after.
+
+Boundaries: code/commits/PRs written normal.
+<!-- caveman-end -->

.github/workflows/autofix.yml

@@ -0,0 +1,53 @@
+name: autofix.ci
+
+on:
+  pull_request:
+  push:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  autofix:
+    runs-on: ${{ vars.USE_BLACKSMITH == 'true' && 'blacksmith-32vcpu-ubuntu-2404' || 'ubuntu-latest' }}
+
+    steps:
+      - name: Checkout Repository
+        if: ${{ vars.USE_BLACKSMITH != 'true' }}
+        uses: actions/checkout@v6
+
+      - name: Checkout Repository (Blacksmith)
+        if: ${{ vars.USE_BLACKSMITH == 'true' }}
+        uses: useblacksmith/checkout@v1
+
+      - name: Check for merge conflict markers
+        run: |
+          if git grep -nEI '<{7} |>{7} |^={7}$' -- ':(exclude)*.md' ':(exclude)*.mdx'; then
+            echo "::error::Merge conflict markers found in tracked files"
+            exit 1
+          fi
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: ".nvmrc"
+          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,44 @@
+name: Sync Translations from Crowdin
+
+on:
+  push:
+    branches: ["main"]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  crowdin-sync:
+    runs-on: ${{ vars.USE_BLACKSMITH == 'true' && 'blacksmith-2vcpu-ubuntu-2404' || 'ubuntu-latest' }}
+
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout Repository
+        if: ${{ vars.USE_BLACKSMITH != 'true' }}
+        uses: actions/checkout@v6
+
+      # The Crowdin action runs in a container that cannot reach the git mirror mount, so copy its objects.
+      - name: Checkout Repository (Blacksmith)
+        if: ${{ vars.USE_BLACKSMITH == 'true' }}
+        uses: useblacksmith/checkout@v1
+        with:
+          dissociate: true
+
+      - 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,25 +2,69 @@ name: Build Docker Image
 
 on:
   workflow_dispatch:
+    inputs:
+      release:
+        description: Publish release aliases and redeploy production (false runs a cache-only build, then publishes a canary)
+        type: boolean
+        default: false
+  push:
+    branches:
+      - main
+    tags:
+      - "v*"
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 env:
-  IMAGE: ${{ github.repository }}
+  GHCR_IMAGE: ghcr.io/${{ github.repository }}
+  DOCKER_IMAGE: docker.io/amruthpillai/reactive-resume
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
+  mode:
+    runs-on: ${{ vars.USE_BLACKSMITH == 'true' && 'blacksmith-2vcpu-ubuntu-2404' || 'ubuntu-latest' }}
+
+    outputs:
+      nightly: ${{ steps.mode.outputs.nightly }}
+      release: ${{ steps.mode.outputs.release }}
+      canary: ${{ steps.mode.outputs.canary }}
+
+    steps:
+      - name: Determine publishing mode
+        id: mode
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          GIT_REF: ${{ github.ref }}
+          RELEASE: ${{ inputs.release }}
+        run: |
+          if [[ "$EVENT_NAME" == "push" && "$GIT_REF" == "refs/heads/main" ]]; then
+            echo "nightly=true" >> "$GITHUB_OUTPUT"
+            echo "release=false" >> "$GITHUB_OUTPUT"
+            echo "canary=false" >> "$GITHUB_OUTPUT"
+          elif [[ "$EVENT_NAME" == "workflow_dispatch" && "$RELEASE" != "true" ]]; then
+            echo "nightly=false" >> "$GITHUB_OUTPUT"
+            echo "release=false" >> "$GITHUB_OUTPUT"
+            echo "canary=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "nightly=false" >> "$GITHUB_OUTPUT"
+            echo "release=true" >> "$GITHUB_OUTPUT"
+            echo "canary=false" >> "$GITHUB_OUTPUT"
+          fi
+
   build:
+    needs: mode
+
     strategy:
       fail-fast: false
       matrix:
         include:
           - platform: linux/amd64
-            runner: ubuntu-latest
+            runner: ${{ vars.USE_BLACKSMITH == 'true' && 'blacksmith-32vcpu-ubuntu-2404' || 'ubuntu-latest' }}
             arch: amd64
           - platform: linux/arm64
-            runner: ubuntu-24.04-arm
+            runner: ${{ vars.USE_BLACKSMITH == 'true' && 'blacksmith-32vcpu-ubuntu-2404-arm' || 'ubuntu-24.04-arm' }}
             arch: arm64
 
     runs-on: ${{ matrix.runner }}
@@ -34,23 +78,60 @@ jobs:
 
     steps:
       - name: Checkout Repository
+        if: ${{ vars.USE_BLACKSMITH != 'true' }}
         uses: actions/checkout@v6
 
-      - name: Get version from package.json
-        id: version
-        run: echo "version=$(jq -r .version package.json)" >> "$GITHUB_OUTPUT"
+      - name: Checkout Repository (Blacksmith)
+        if: ${{ vars.USE_BLACKSMITH == 'true' }}
+        uses: useblacksmith/checkout@v1
 
       - name: Setup Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        if: ${{ vars.USE_BLACKSMITH != 'true' }}
+        uses: docker/setup-buildx-action@v4
+
+      # Persists BuildKit layers and the Dockerfile's pnpm cache mounts between runs, one cache per architecture.
+      - name: Setup Docker Builder (Blacksmith)
+        if: ${{ vars.USE_BLACKSMITH == 'true' }}
+        uses: useblacksmith/setup-docker-builder@v2
+        with:
+          cache-key: Dockerfile-${{ matrix.arch }}
+
+      - &registries
+        name: Determine registries
+        id: registries
+        env:
+          DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
+          DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
+        run: |
+          set -euo pipefail
+
+          dockerhub=false
+          ghcr_image="${GHCR_IMAGE,,}"
+          docker_image="${DOCKER_IMAGE,,}"
+          images="$ghcr_image"
+          if [[ -n "$DOCKER_USERNAME" && -n "$DOCKER_PASSWORD" ]]; then
+            dockerhub=true
+            images="${images}"$'\n'"$docker_image"
+          fi
+
+          {
+            echo "ghcr_image=$ghcr_image"
+            echo "docker_image=$docker_image"
+            echo "images<<EOF"
+            echo "$images"
+            echo "EOF"
+            echo "dockerhub=$dockerhub"
+          } >> "$GITHUB_OUTPUT"
 
       - name: Login to Docker Hub
-        uses: docker/login-action@v3
+        if: ${{ steps.registries.outputs.dockerhub == 'true' }}
+        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 }}
@@ -58,18 +139,30 @@ 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 }}
+          images: ${{ steps.registries.outputs.images }}
           tags: |
             type=sha,prefix=sha-,suffix=-${{ matrix.arch }}
 
+      - name: Cache-only smoke build
+        if: ${{ needs.mode.outputs.canary == 'true' && vars.USE_BLACKSMITH != 'true' }}
+        uses: docker/build-push-action@v7
+        with: &cache-only-build
+          context: .
+          platforms: ${{ matrix.platform }}
+          outputs: type=cacheonly
+
+      - name: Cache-only smoke build (Blacksmith)
+        if: ${{ needs.mode.outputs.canary == 'true' && vars.USE_BLACKSMITH == 'true' }}
+        uses: useblacksmith/build-push-action@v2
+        with: *cache-only-build
+
       - name: Build and Push by Digest
         id: build
-        uses: docker/build-push-action@v6
-        with:
+        if: ${{ vars.USE_BLACKSMITH != 'true' }}
+        uses: docker/build-push-action@v7
+        with: &build-push
           context: .
           sbom: true
           push: true
@@ -78,17 +171,21 @@ jobs:
           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 }}
+
+      - name: Build and Push by Digest (Blacksmith)
+        id: build-blacksmith
+        if: ${{ vars.USE_BLACKSMITH == 'true' }}
+        uses: useblacksmith/build-push-action@v2
+        with: *build-push
 
       - name: Export digest
         run: |
           mkdir -p /tmp/digests
-          digest="${{ steps.build.outputs.digest }}"
+          digest="${{ steps.build.outputs.digest || steps.build-blacksmith.outputs.digest }}"
           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/*
@@ -96,9 +193,15 @@ jobs:
           retention-days: 1
 
   merge:
-    needs: build
+    needs:
+      - mode
+      - build
     timeout-minutes: 30
-    runs-on: ubuntu-latest
+    runs-on: ${{ vars.USE_BLACKSMITH == 'true' && 'blacksmith-2vcpu-ubuntu-2404' || 'ubuntu-latest' }}
+
+    env:
+      DEPLOY: ${{ secrets.SSH_KEY != '' && secrets.SSH_HOST != '' && secrets.SSH_USER != '' }}
+      PURGE_CLOUDFLARE: ${{ secrets.CLOUDFLARE_ZONE_ID != '' && secrets.CLOUDFLARE_API_TOKEN != '' }}
 
     permissions:
       contents: read
@@ -108,33 +211,42 @@ jobs:
 
     steps:
       - name: Checkout Repository
+        if: ${{ vars.USE_BLACKSMITH != 'true' }}
         uses: actions/checkout@v6
-        with:
+        with: &checkout-package-json
           sparse-checkout: package.json
           sparse-checkout-cone-mode: false
 
+      - name: Checkout Repository (Blacksmith)
+        if: ${{ vars.USE_BLACKSMITH == 'true' }}
+        uses: useblacksmith/checkout@v1
+        with: *checkout-package-json
+
       - name: Get version from package.json
         id: version
         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
+
+      - *registries
 
       - name: Login to Docker Hub
-        uses: docker/login-action@v3
+        if: ${{ steps.registries.outputs.dockerhub == 'true' }}
+        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 }}
@@ -146,29 +258,39 @@ jobs:
           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 }}
+          images: ${{ steps.registries.outputs.images }}
           tags: |
             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 }}
+            type=raw,value=canary-${{ github.run_id }}-${{ github.run_attempt }},enable=${{ needs.mode.outputs.canary == 'true' }}
+            type=raw,value=nightly,enable=${{ needs.mode.outputs.nightly == 'true' }}
+            type=raw,value=nightly-{{date 'YYYYMMDDHHmmss' tz='UTC'}},enable=${{ needs.mode.outputs.nightly == 'true' }}
+            type=raw,value=latest,enable=${{ needs.mode.outputs.release == 'true' }}
+            type=raw,value=v${{ steps.version.outputs.version }},enable=${{ needs.mode.outputs.release == 'true' }}
+            type=raw,value=v${{ steps.semver.outputs.major }}.${{ steps.semver.outputs.minor }},enable=${{ needs.mode.outputs.release == 'true' }}
+            type=raw,value=v${{ steps.semver.outputs.major }},enable=${{ needs.mode.outputs.release == 'true' }}
 
       - name: Create manifest list and push
         id: manifest
         working-directory: /tmp/digests
         run: |
           set -euo pipefail
+
+          if [[ "${{ needs.mode.outputs.nightly }}" == "true" ]]; then
+            FINAL_TAG="nightly"
+          elif [[ "${{ needs.mode.outputs.canary }}" == "true" ]]; then
+            FINAL_TAG="canary-${{ github.run_id }}-${{ github.run_attempt }}"
+          else
+            FINAL_TAG="v${{ steps.version.outputs.version }}"
+          fi
+
           docker buildx imagetools create \
             $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
             --annotation "index:org.opencontainers.image.licenses=MIT" \
@@ -177,16 +299,19 @@ jobs:
             --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.source=https://github.com/${{ github.repository }}" \
             --annotation "index:org.opencontainers.image.version=${{ steps.version.outputs.version }}" \
-            $(printf 'ghcr.io/${{ env.IMAGE }}@sha256:%s ' *) \
-            $(printf 'docker.io/${{ env.IMAGE }}@sha256:%s ' *)
-          
+            $(printf '${{ steps.registries.outputs.ghcr_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 '"')
+          GHCR_DIGEST=$(docker buildx imagetools inspect ${{ steps.registries.outputs.ghcr_image }}:${FINAL_TAG} --format '{{json .Manifest.Digest}}' | tr -d '"')
+          echo "final_tag=$FINAL_TAG" >> "$GITHUB_OUTPUT"
           echo "ghcr_digest=$GHCR_DIGEST" >> "$GITHUB_OUTPUT"
-          echo "docker_digest=$DOCKER_DIGEST" >> "$GITHUB_OUTPUT"
+
+          if [[ "${{ steps.registries.outputs.dockerhub }}" == "true" ]]; then
+            DOCKER_DIGEST=$(docker buildx imagetools inspect ${{ steps.registries.outputs.docker_image }}:${FINAL_TAG} --format '{{json .Manifest.Digest}}' | tr -d '"')
+            echo "docker_digest=$DOCKER_DIGEST" >> "$GITHUB_OUTPUT"
+          fi
 
       - name: Install Cosign
         uses: sigstore/cosign-installer@v3
@@ -194,17 +319,40 @@ jobs:
       - 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 }}
+          cosign sign --yes ${{ steps.registries.outputs.ghcr_image }}@${{ steps.manifest.outputs.ghcr_digest }}
+
+          if [[ "${{ steps.registries.outputs.dockerhub }}" == "true" ]]; then
+            # Sign Docker Hub image
+            cosign sign --yes ${{ steps.registries.outputs.docker_image }}@${{ steps.manifest.outputs.docker_digest }}
+          fi
 
       - name: Inspect image
         run: |
-          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 }}
+          docker buildx imagetools inspect ${{ steps.registries.outputs.ghcr_image }}:${{ steps.manifest.outputs.final_tag }}
+          if [[ "${{ steps.registries.outputs.dockerhub }}" == "true" ]]; then
+            docker buildx imagetools inspect ${{ steps.registries.outputs.docker_image }}:${{ steps.manifest.outputs.final_tag }}
+          fi
+
+      - name: Verify anonymous pulls on both architectures
+        run: |
+          set -euo pipefail
+          registry_config=$(mktemp -d)
+          trap 'rm -rf "$registry_config"' EXIT
+          # Prevent Docker from discovering a system credential helper.
+          printf '%s\n' '{"auths":{"ghcr.io":{},"https://index.docker.io/v1/":{}}}' > "$registry_config/config.json"
+          images=("${{ steps.registries.outputs.ghcr_image }}")
+          if [[ "${{ steps.registries.outputs.dockerhub }}" == "true" ]]; then
+            images+=("${{ steps.registries.outputs.docker_image }}")
+          fi
+          for image in "${images[@]}"; do
+            for platform in linux/amd64 linux/arm64; do
+              docker --config "$registry_config" pull --quiet --platform "$platform" \
+                "$image:${{ steps.manifest.outputs.final_tag }}"
+            done
+          done
 
       - name: Redeploy Stack
+        if: ${{ needs.mode.outputs.release == 'true' && env.DEPLOY == 'true' }}
         uses: appleboy/ssh-action@v1
         with:
           key: ${{ secrets.SSH_KEY }}
@@ -212,4 +360,25 @@ jobs:
           username: ${{ secrets.SSH_USER }}
           script: |
             cd docker
-            ./manage_stack.sh up reactive_resume
+            ./manage_stack.sh up reactive_resume
+
+      - name: Purge Cloudflare cache
+        if: ${{ needs.mode.outputs.release == 'true' && env.PURGE_CLOUDFLARE == 'true' }}
+        env:
+          CLOUDFLARE_ZONE_ID: ${{ secrets.CLOUDFLARE_ZONE_ID }}
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          response=$(curl -fsS --max-time 10 --retry 3 --retry-delay 5 --retry-connrefused -X POST \
+            "https://api.cloudflare.com/client/v4/zones/${CLOUDFLARE_ZONE_ID}/purge_cache" \
+            -H "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
+            -H "Content-Type: application/json" \
+            --data '{"purge_everything":true}')
+
+          if [ "$(jq -r '.success' <<< "$response")" != "true" ]; then
+            echo "$response" | jq .
+            exit 1
+          fi
+
+          echo "Cloudflare cache purged successfully."

.github/workflows/e2e.yml

@@ -0,0 +1,103 @@
+name: E2E Tests
+
+on:
+  pull_request:
+  push:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+  APP_URL: http://localhost:3000
+  PORT: "3000"
+  DATABASE_URL: postgresql://postgres:postgres@localhost:5432/postgres
+  FLAG_DISABLE_SIGNUPS: "false"
+  FLAG_DISABLE_EMAIL_AUTH: "false"
+  FLAG_DISABLE_API_RATE_LIMIT: "true"
+  LOCAL_STORAGE_PATH: /tmp/reactive-resume-e2e-storage
+
+jobs:
+  e2e:
+    runs-on: ${{ vars.USE_BLACKSMITH == 'true' && 'blacksmith-32vcpu-ubuntu-2404' || 'ubuntu-latest' }}
+    timeout-minutes: 30
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_DB: postgres
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres -d postgres"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - name: Checkout Repository
+        if: ${{ vars.USE_BLACKSMITH != 'true' }}
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Checkout Repository (Blacksmith)
+        if: ${{ vars.USE_BLACKSMITH == 'true' }}
+        uses: useblacksmith/checkout@v1
+        with:
+          persist-credentials: false
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: ".nvmrc"
+          cache: "pnpm"
+
+      - name: Install Dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Install Playwright Browser
+        timeout-minutes: 10
+        run: pnpm exec playwright install --with-deps chromium
+
+      - name: Generate Test Secrets
+        run: |
+          echo "AUTH_SECRET=$(openssl rand -hex 32)" >> "$GITHUB_ENV"
+          echo "ENCRYPTION_SECRET=$(openssl rand -hex 32)" >> "$GITHUB_ENV"
+
+      - name: Prepare Storage
+        run: mkdir -p "$LOCAL_STORAGE_PATH"
+
+      - name: Run Database Migrations
+        run: pnpm db:migrate
+
+      # Runs every workspace package, not a hand-maintained filter list, so a package
+      # cannot silently lose coverage by being left out. Serial execution: the PDF
+      # rasterization and API rate-limit suites time out when several packages' Vitest
+      # thread pools oversubscribe the runner at once.
+      - name: Run Unit Tests
+        run: pnpm exec turbo run test:ci --concurrency=1
+
+      - name: Build
+        run: pnpm build
+
+      - name: Run E2E Tests
+        run: pnpm exec playwright test
+
+      - name: Upload Playwright Report
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: playwright-report
+          path: |
+            playwright-report
+            test-results
+          if-no-files-found: ignore
+          retention-days: 7

.github/workflows/label-issues.yml

@@ -0,0 +1,41 @@
+name: Label New Issues
+
+on:
+  issues:
+    types: [opened]
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  label:
+    runs-on: ${{ vars.USE_BLACKSMITH == 'true' && 'blacksmith-2vcpu-ubuntu-2404' || 'ubuntu-latest' }}
+
+    steps:
+      - name: Checkout Repository
+        if: ${{ vars.USE_BLACKSMITH != 'true' }}
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Checkout Repository (Blacksmith)
+        if: ${{ vars.USE_BLACKSMITH == 'true' }}
+        uses: useblacksmith/checkout@v1
+        with:
+          persist-credentials: false
+
+      - name: Apply Form Labels
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9
+        with:
+          script: |
+            const { getIssueLabels } = await import(`${process.env.GITHUB_WORKSPACE}/tooling/issue-labels.mjs`);
+            const labels = getIssueLabels(context.payload.issue.body ?? "");
+
+            if (labels.length > 0) {
+              await github.rest.issues.addLabels({
+                ...context.repo,
+                issue_number: context.issue.number,
+                labels,
+              });
+            }

.github/workflows/stale-issues.yml

@@ -0,0 +1,30 @@
+name: Close Issues Awaiting Information
+
+on:
+  schedule:
+    - cron: "23 4 * * *"
+  workflow_dispatch:
+
+permissions:
+  issues: write
+
+jobs:
+  stale:
+    runs-on: ${{ vars.USE_BLACKSMITH == 'true' && 'blacksmith-2vcpu-ubuntu-2404' || 'ubuntu-latest' }}
+
+    steps:
+      - name: Close Inactive Issues Awaiting Information
+        uses: actions/stale@4391f3da665fdf50b6810c1a66712fb9ba21aa93 # v11
+        with:
+          only-issue-labels: "status: needs info"
+          days-before-issue-stale: 14
+          days-before-issue-close: 7
+          days-before-pr-stale: -1
+          days-before-pr-close: -1
+          stale-issue-label: stale
+          stale-issue-message: >-
+            This issue is waiting for information requested by a maintainer. It will close in 7 days if no new information is provided.
+          close-issue-message: >-
+            Closing because the requested information was not provided. Add the missing details in a comment and a maintainer can reopen the issue.
+          close-issue-reason: not_planned
+          remove-issue-stale-when-updated: true

.github/workflows/vercel.yml

@@ -0,0 +1,109 @@
+name: Vercel compatibility
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  artifact:
+    runs-on: ${{ vars.USE_BLACKSMITH == 'true' && 'blacksmith-32vcpu-ubuntu-2404' || 'ubuntu-latest' }}
+    timeout-minutes: 20
+    services:
+      postgres:
+        image: postgres:17-alpine
+        env:
+          POSTGRES_PASSWORD: postgres
+        ports: [5432:5432]
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 5s --health-timeout 5s --health-retries 10
+    env:
+      APP_URL: http://localhost:3000
+      DATABASE_URL: postgresql://postgres:postgres@localhost:5432/postgres
+      AUTH_SECRET: isolated-ci-auth-secret-32-characters
+      ENCRYPTION_SECRET: isolated-ci-encryption-secret-32-characters
+      REDIS_URL: redis://localhost:6379
+      STORAGE_BACKEND: blob
+      BLOB_READ_WRITE_TOKEN: vercel_blob_rw_ci_fake_build_only
+      VERCEL: "1"
+      VERCEL_ENV: production
+    steps:
+      - if: ${{ vars.USE_BLACKSMITH != 'true' }}
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - if: ${{ vars.USE_BLACKSMITH == 'true' }}
+        uses: useblacksmith/checkout@v1
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      # Local project settings avoid authentication and API calls. Forks receive no cloud credentials.
+      - name: Build Vercel artifact against isolated PostgreSQL
+        run: |
+          mkdir -p .vercel
+          node --input-type=module - <<'JS'
+          import { writeFileSync } from 'node:fs';
+          writeFileSync('.vercel/project.json', JSON.stringify({
+            projectId: 'prj_ci', orgId: 'team_ci', projectName: 'reactive-resume-ci',
+            settings: { framework: null, nodeVersion: '24.x', createdAt: 0 }
+          }));
+          JS
+          pnpm dlx --allow-build=esbuild vercel@60.0.1 build --prod --yes --global-config "$RUNNER_TEMP/vercel-offline"
+      - name: Check Lambda module loading and function budget
+        run: |
+          node --no-experimental-require-module --input-type=module - <<'JS'
+          import assert from 'node:assert/strict';
+          import { readFileSync, readdirSync } from 'node:fs';
+          const config = JSON.parse(readFileSync('.vercel/output/functions/api/index.func/.vc-config.json'));
+          assert.equal(config.runtime, 'nodejs24.x');
+          assert.equal(config.maxDuration, 300);
+          const tracedFiles = Object.keys(config.filePathMap ?? {});
+          assert.ok(tracedFiles.some((path) => path.endsWith('/pdfkit/js/standard-fonts/Helvetica.cjs')));
+          assert.ok(tracedFiles.some((path) => path.endsWith('/pdfkit/js/data/Helvetica.afm')));
+          for (const name of readdirSync('apps/server/dist')) {
+            if (name.endsWith('.mjs') && !['index.mjs', 'prepare-deployment.mjs'].includes(name)) {
+              await import(`./apps/server/dist/${name}`);
+            }
+          }
+          const { default: app } = await import('./apps/server/dist/vercel.mjs');
+          const response = await app.fetch(new Request('http://localhost:3000/api/storage/stage', { method: 'POST', body: '{}' }));
+          assert.equal(response.status, 401);
+          process.exit(0);
+          JS
+
+  live-smoke:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ${{ vars.USE_BLACKSMITH == 'true' && 'blacksmith-2vcpu-ubuntu-2404' || 'ubuntu-latest' }}
+    environment: vercel-smoke
+    timeout-minutes: 10
+    steps:
+      - if: ${{ vars.USE_BLACKSMITH != 'true' }}
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - if: ${{ vars.USE_BLACKSMITH == 'true' }}
+        uses: useblacksmith/checkout@v1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: .nvmrc
+      - name: Smoke-test dedicated deployment
+        env:
+          SMOKE_URL: ${{ vars.VERCEL_SMOKE_URL }}
+          SMOKE_AI_BASE_URL: ${{ vars.VERCEL_SMOKE_AI_BASE_URL }}
+          SMOKE_AI_API_KEY: ${{ secrets.VERCEL_SMOKE_AI_API_KEY }}
+        run: node tooling/deployment/smoke.mjs

.gitignore

@@ -1,19 +1,65 @@
-dist
-.env*
-/data
-.nitro
-.output
-.vercel
-.cursor
-TODO.md
-coverage
-.netlify
-.DS_Store
-.tanstack
+# Dependencies
 node_modules
+.pnpm-store
+
+# Build Outputs
+dist
+.vercel
+.wrangler
+
+# Environment Variables
+.env*
 !.env.example
-public/sw.js
-public/sw.js.map
-scripts/**/*.json
-public/workbox-*.js
-public/workbox-*.js.map
+
+# 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
+playwright-report
+test-results
+
+# Cache
+tmp
+temp
+.cache
+
+# AI
+.codex
+.agents
+.claude
+.cursor
+.opencode
+.codegraph
+.superpowers
+.worktrees
+.migration
+graphify-out
+
+# Local Storage Data
+/data
+/apps/web/data
+
+# Git Hooks
+.vite-hooks
+

.markdownlint-cli2.yaml

@@ -0,0 +1,31 @@
+config:
+  default: true
+  MD007: false
+  MD009: false
+  MD010: false
+  MD012: false
+  MD013: false
+  MD001: false
+  MD022: false
+  MD024: false
+  MD025: false
+  MD028: false
+  MD031: false
+  MD032: false
+  MD033: false
+  MD034: false
+  MD036: false
+  MD040: false
+  MD041: false
+  MD046: false
+  MD060: false
+
+frontMatter: "^---[\\s\\S]*?---"
+gitignore: true
+globs:
+  - "**/*.{md,mdx}"
+ignores:
+  - ".design-sync/**"
+  - "node_modules/**"
+  - ".turbo/**"
+  - "dist/**"

.ncurc.cjs

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

.nvmrc

@@ -0,0 +1 @@
+24

.orchestration/imported-table-raster-ci-fix.md

@@ -0,0 +1,39 @@
+# Imported-table raster CI fix
+
+## Root cause
+
+Hosted runs `34007560930` (PR #3471) and `34007788443` (PR #3472) failed only in
+`tests/e2e/specs/imported-table.spec.ts` with `horizontal: 18` instead of Plan 16's
+`horizontal: 17`; text and vertical checks passed.
+
+The PDF operator dump from the failed hosted artifact showed 29 table path records matching the Plan 16 contract
+(17 horizontal, 12 vertical), followed by an unrelated `constructPath` `endPath` bbox:
+`[0, 19.65, 358.93, 20.65]`. Its stroke color was reported as `#cc00cc` only because the helper retained the
+last table stroke color. It was a later red section-divider fill/no-paint path, not an extra table border. The old
+helper classified every thin bbox after the last matching color state, so it counted this false positive.
+
+The table's explicit width is stable at 300pt, while row height legitimately changes from 30pt to 31pt after the
+`Beta!` edit. The helper therefore scopes candidate paths by the fixture's 300pt horizontal grid envelope, not by a
+row-height tolerance. Missing or duplicated paths inside that envelope still change the exact 17/12 contract.
+
+## Change
+
+- Added `tests/e2e/fixtures/pdf-borders.ts` with deterministic `countTableBorderGeometry` filtering.
+- Updated browser/server PDF inspection in `tests/e2e/specs/imported-table.spec.ts` to use the helper.
+- Added `tests/e2e/fixtures/pdf-borders.test.ts`; regression proves old stale-color counting returns 2 horizontal
+  paths while topology-scoped counting returns 1.
+
+## Verification
+
+- Intent skill inventory: 7 packages, 26 skills; no matching local skill for this E2E/PDF helper.
+- Focused helper regression: 1 file, 1 passed.
+- Dedicated imported-table E2E: 2 consecutive runs, each 1 passed; both exercise initial, unrelated-edit, and table-edit
+  stages plus browser and server PDF exports.
+- Production build: 3/3 tasks successful.
+- Web typecheck via `rtk proxy pnpm --filter web typecheck`: passed (`tsgo --noEmit`).
+- Turbo boundaries: 1,443 files across 20 packages, no issues.
+- Targeted Biome: 3 files, no issues.
+- `git diff --check`: passed.
+
+The root `pnpm typecheck` wrapper was also tried but invokes an incompatible `tsc` path and reports TS5096 for
+`allowImportingTsExtensions`; the package's documented `tsgo --noEmit` typecheck passes.

.orchestration/plan-21-implementation.md

@@ -0,0 +1,33 @@
+# Plan 21 implementation evidence
+
+## Revision and scope
+
+- Worktree: `issue-3060-section-heading-visibility`
+- Base: current `origin/main` at dispatch, `2a4a1583b` (`fix(pdf): restore Gengar skill rating order (#3473)`)
+- Product decisions applied: Q1 explicit Show heading toggle; Q2 Move-to continuations default visible; Q3 visual omission in preview/PDF/DOCX with accessible outline labels retained.
+- No `.codegraph/` directory exists in this worktree, so CodeGraph was skipped after the required presence check.
+- Intent discovery ran before edits; no matching local skill was available for this schema/PDF/DOCX/web change.
+
+## Implementation
+
+- Added backward-compatible `showHeading` section data for summary, built-ins, and custom sections. `parseResumeData` normalizes absent legacy values to `true`; explicit `false` survives round trips.
+- Added heading toggles to built-in/summary and custom section menus. Toggle mutations use `useUpdateResumeData`, preserving undo/autosave/save/reload behavior; legacy absent values are treated as visible. Existing lock fieldset remains authoritative.
+- Move-to-created custom sections explicitly set `showHeading: true`, independent of source heading state or copied title.
+- `SectionShell` omits complete heading/icon/decoration output when disabled in both icon and no-icon branches. Empty titles still resolve localized defaults.
+- DOCX section renderers omit visible heading paragraphs for summary, built-in, and custom sections while retaining content. Screen-reader mirror continues to expose section labels regardless of visual setting.
+- Added characterization for Semantic CSS `section[id="..."] section-heading { display: none; }`; body remains while heading is omitted.
+- Updated default/sample fixtures, generated schema references, recovery hashes, and compatibility tests; existing Gengar renderer/order changes remain untouched.
+
+## Verification
+
+- `pnpm --filter @reactive-resume/schema test`: 9 files, 132 tests passed.
+- `pnpm --filter @reactive-resume/pdf test`: 81 files, 1059 tests passed.
+- `pnpm --filter @reactive-resume/docx test`: 9 files, 76 tests passed.
+- `pnpm --filter web test`: 135 files, 942 tests passed.
+- `pnpm test`: full Turborepo suite passed (19 successful tasks; 10 cache hits).
+- Affected typechecks passed: schema, PDF, DOCX, web.
+- Focused menu, Move-to, accessible-outline, schema, PDF semantic, and DOCX renderer tests passed.
+- `pnpm exec turbo boundaries`: passed (1108 files, 20 packages).
+- Read-only `pnpm exec biome check` on 22 changed source/test files: passed; no write-capable `pnpm check` run.
+- `git diff --check`: passed.
+- Final diff review completed; local commit follows.

.orchestration/plan-23-item-pagination-blocker.md

@@ -0,0 +1,32 @@
+# Plan 23 item-pagination execution evidence
+
+## Scope
+
+Plan 23 steps 1–3 were evaluated from `origin/main` at `368858a56` (Plan 21 / PR #3477 merged). Widow/orphan UI and authored-page continuation guidance remain deferred from this execution, and Semantic CSS was not changed.
+
+## Durable diagnostic matrix
+
+`packages/pdf/src/templates/shared/item-pagination.test.tsx` renders physical PDF pages and checks numbered tokens exactly once for:
+
+- an item that fits remaining space;
+- an item that fits a full page but not the remaining space;
+- an oversized item taller than one page;
+- a two-line paragraph at a boundary;
+- nested bullets; and
+- built-in plus custom items in an Azurill sidebar/main-column overflow fixture.
+
+The fixture also keeps authored `metadata.layout.pages` separate from renderer-generated physical pages.
+
+The current deterministic baseline is: fit remainder = 1 physical page; full-page-but-not-remainder = 3 pages with sampled tokens on pages 2/2/3; oversized = 5 pages with sampled tokens on pages 1/3/5; two-line boundary = 2 pages; nested bullets = 1 page; Azurill built-in/custom/sidebar = 5 pages with sampled tokens on pages 1/4/5/5/1. Page numbers here are 1-based; every token still appears exactly once.
+
+## Concrete blocker
+
+React PDF's only available item-level keep-together primitive is `View wrap={false}`. A durable renderer fixture with 180 paragraph-like child views shows that a non-wrapping item cannot safely fall back when its content exceeds one page: the renderer omits the oversized tail instead of splitting it. Applying the same prop to shared `SectionItem` would therefore violate the lossless token requirement; no item schema flag or menu control was added.
+
+Do not estimate item height from HTML length, persist physical pages, alter existing Semantic CSS, or claim #3350 complete. A future implementation needs renderer-supported conditional keep-together behavior or an actual measured two-pass fallback that preserves every token.
+
+## Verification
+
+- `pnpm --filter @reactive-resume/pdf exec vitest run src/templates/shared/item-pagination.test.tsx`: 7 tests passed.
+- No production source or schema changes made after the unsafe fallback was reproduced.
+- Undo/persistence/lock UI coverage is intentionally absent because no item control was shipped; add it only when safe fallback exists.

.orchestration/plan-27a-diagnostic.md

@@ -0,0 +1,157 @@
+# Plan 27 Phase A diagnostic evidence
+
+Date: 2026-09-06  
+Issue: [#3377](https://github.com/reactive-resume/reactive-resume/issues/3377)<br>
+Revision: `2a4a1583b` (`origin/main` at run start)  
+Scope: Phase A, steps 1–2 only. No resolver, runtime behavior, or remote-source behavior changed.
+
+## Drift and authority
+
+- Worktree started clean and `HEAD` matched `origin/main`; `git diff origin/main...HEAD` was empty.
+- Current catalog is `packages/fonts/src/webfontlist.json`. Its web font records point at both Google Fonts static assets and jsDelivr assets; “Google blocked” is not an offline proof.
+- Browser preview is `apps/web/src/components/typography/font-display.tsx` and calls `FontFace.load()` against each catalog preview URL.
+- Browser PDF preview/download is `apps/web/src/features/resume/export/pdf-document.tsx` → `@reactive-resume/pdf/browser`; registration is `packages/pdf/src/hooks/use-register-fonts.ts`.
+- Server PDF is `apps/server/src/http/resume-pdf.ts` → `createResumePdfDownload`; Playwright browser routing cannot observe that process’s outbound font fetches.
+- The issue is open and unmodified. PR #3455 is the approved planning PR; its plan/decision log grants execution of this bounded diagnostic and manifest evidence.
+
+## Deterministic fixture
+
+`tests/e2e/fixtures/offline-fonts.ts` seeds one disposable resume after sample creation. It writes the same text into basics and summary, hides the picture, selects IBM Plex Serif 400/700 for body and heading, and marks the row public for the server-PDF surface.
+
+The exact markers are versioned as `offline-font-scripts-v1`:
+
+| Marker | Script or coverage |
+| --- | --- |
+| `Latin punctuation • — “quotes” €` | Latin plus General Punctuation and currency |
+| `简体中文` | Han / Simplified Chinese |
+| `العربية` | Arabic |
+| `עברית` | Hebrew |
+| `ไทย` | Thai |
+| `Emoji 🚀` | Emoji |
+
+`tests/e2e/specs/offline-fonts.spec.ts` is opt-in (`OFFLINE_FONT_DIAGNOSTIC=1`) so the normal PR E2E suite does not become network-dependent. Each surface creates a new browser context with persisted auth state, disabled service workers, and no prior browser cache. Every non-same-origin request is aborted and recorded as `{ hostname, path }`; query strings, fragments, headers, bodies, tokens, and full URLs never enter diagnostic output. Reports are attached as JSON and emitted with the same sanitized shape.
+
+The four surfaces are separate tests:
+
+1. Font picker preview opens Typography → Font Family and waits for lazy `FontFace` preview loads.
+2. Builder PDF preview navigates to the builder, captures the active PDF canvas, and measures marker-local raster crops.
+3. Browser PDF download uses the Export dialog, rasterizes the downloaded PDF, and measures marker-local crops when generation succeeds.
+4. Server PDF calls the public PDF endpoint and records text-layer marker presence when generation succeeds.
+
+Builder/browser-PDF reports keep PDF text extraction as a separate `textLayerMarkers` signal; it does not prove visible glyph outlines. Raster evidence attaches a rendered PNG and per-marker crop metrics, failing for blank or tofu-like visible crops. Blocked browser font requests classify browser surfaces as `network-error`. The server report deliberately says `server-outbound-requests-unobservable-from-playwright`; its cold-network gate remains unresolved because server outbound capture and verifiable restart identity require external host-level controls.
+
+## Run protocol and cold-cache boundary
+
+Build and database setup follow `tests/e2e/README.md`. Run each surface in a separately restarted production server process so module-level PDF font registration state cannot leak between controls:
+
+```text
+OFFLINE_FONT_DIAGNOSTIC=1 OFFLINE_FONT_DIAGNOSTIC_SERVER_RESTARTED=1 \
+  pnpm exec playwright test tests/e2e/specs/offline-fonts.spec.ts --grep "picker preview"
+```
+
+Stop and restart the production server before repeating the command with `builder PDF`, `browser PDF`, and `server PDF` grep patterns. The environment used for this change had no built `apps/server/dist` or `apps/web/dist`, no running PostgreSQL instance, and no production server to restart, so the cold E2E matrix was not run. This is an explicit infrastructure blocker, not a pass claim. The test records `serverRestartFlag` only as caller input and labels it non-proof; it does not claim a completed cold-network gate.
+
+The current Playwright route guard cannot impose host-level egress denial on Node.js running the server. A genuinely cold server test therefore needs a separately restarted server plus host-level egress capture/deny (for example, a controlled network namespace or an approved outbound proxy). Do not infer server network behavior from an empty browser request list.
+
+## Administrator-hosted manifest proposal
+
+This is a proposal, not an asset download. It intentionally contains only the primary family and glyph fallbacks required by the fixture and current PDF fallback map, not the full catalog.
+
+```json
+{
+  "schemaVersion": "offline-fonts-v1",
+  "mode": "local-only",
+  "assetRoot": "/fonts/offline/v1",
+  "families": {
+    "IBM Plex Serif": {
+      "normal": { "400": "ibm-plex-serif/400.ttf", "700": "ibm-plex-serif/700.ttf" },
+      "italic": { "400": "ibm-plex-serif/400-italic.ttf", "700": "ibm-plex-serif/700-italic.ttf" },
+      "preview": "ibm-plex-serif/preview.ttf"
+    },
+    "IBM Plex Sans": {
+      "normal": { "400": "ibm-plex-sans/400.ttf", "700": "ibm-plex-sans/700.ttf" },
+      "italic": { "400": "ibm-plex-sans/400-italic.ttf", "700": "ibm-plex-sans/700-italic.ttf" },
+      "preview": "ibm-plex-sans/preview.ttf"
+    },
+    "Noto Serif": {
+      "normal": { "400": "noto-serif/400.ttf", "700": "noto-serif/700.ttf" },
+      "italic": { "400": "noto-serif/400-italic.ttf", "700": "noto-serif/700-italic.ttf" },
+      "preview": "noto-serif/preview.ttf"
+    },
+    "Noto Sans": {
+      "normal": { "400": "noto-sans/400.ttf", "700": "noto-sans/700.ttf" },
+      "italic": { "400": "noto-sans/400-italic.ttf", "700": "noto-sans/700-italic.ttf" },
+      "preview": "noto-sans/preview.ttf"
+    },
+    "Noto Sans SC": { "normal": { "400": "noto-sans-sc/400.ttf", "700": "noto-sans-sc/700.ttf" }, "italic": "reuse-normal", "preview": "noto-sans-sc/preview.ttf" },
+    "Noto Serif SC": { "normal": { "400": "noto-serif-sc/400.ttf", "700": "noto-serif-sc/700.ttf" }, "italic": "reuse-normal", "preview": "noto-serif-sc/preview.ttf" },
+    "Noto Sans TC": { "normal": { "400": "noto-sans-tc/400.ttf", "700": "noto-sans-tc/700.ttf" }, "italic": "reuse-normal", "preview": "noto-sans-tc/preview.ttf" },
+    "Noto Serif TC": { "normal": { "400": "noto-serif-tc/400.ttf", "700": "noto-serif-tc/700.ttf" }, "italic": "reuse-normal", "preview": "noto-serif-tc/preview.ttf" },
+    "Noto Sans JP": { "normal": { "400": "noto-sans-jp/400.ttf", "700": "noto-sans-jp/700.ttf" }, "italic": "reuse-normal", "preview": "noto-sans-jp/preview.ttf" },
+    "Noto Serif JP": { "normal": { "400": "noto-serif-jp/400.ttf", "700": "noto-serif-jp/700.ttf" }, "italic": "reuse-normal", "preview": "noto-serif-jp/preview.ttf" },
+    "Noto Sans KR": { "normal": { "400": "noto-sans-kr/400.ttf", "700": "noto-sans-kr/700.ttf" }, "italic": "reuse-normal", "preview": "noto-sans-kr/preview.ttf" },
+    "Noto Serif KR": { "normal": { "400": "noto-serif-kr/400.ttf", "700": "noto-serif-kr/700.ttf" }, "italic": "reuse-normal", "preview": "noto-serif-kr/preview.ttf" },
+    "Noto Sans Arabic": { "normal": { "400": "noto-sans-arabic/400.ttf", "700": "noto-sans-arabic/700.ttf" }, "italic": "reuse-normal", "preview": "noto-sans-arabic/preview.ttf" },
+    "Noto Naskh Arabic": { "normal": { "400": "noto-naskh-arabic/400.ttf", "700": "noto-naskh-arabic/700.ttf" }, "italic": "reuse-normal", "preview": "noto-naskh-arabic/preview.ttf" },
+    "Noto Sans Hebrew": { "normal": { "400": "noto-sans-hebrew/400.ttf", "700": "noto-sans-hebrew/700.ttf" }, "italic": "reuse-normal", "preview": "noto-sans-hebrew/preview.ttf" },
+    "Noto Sans Thai": { "normal": { "400": "noto-sans-thai/400.ttf", "700": "noto-sans-thai/700.ttf" }, "italic": "reuse-normal", "preview": "noto-sans-thai/preview.ttf" },
+    "Noto Emoji": { "normal": { "400": "noto-emoji/400.ttf", "700": "noto-emoji/700.ttf" }, "italic": "reuse-normal", "preview": "noto-emoji/preview.ttf" }
+  }
+}
+```
+
+### Candidate source, license, script, and size evidence
+
+Sizes are `Content-Length` bytes from a HEAD request to the exact current catalog assets on 2026-09-06. Responses reported `Content-Encoding: gzip`; these are compressed transfer-size estimates, not a claim about the eventual on-disk representation. Preview paths are aliases to the selected 400 face and add no extra bytes when stored once. Primary sources: [IBM Plex LICENSE.txt](https://github.com/IBM/plex/blob/master/LICENSE.txt), [Noto core LICENSE](https://github.com/notofonts/noto-fonts/blob/main/LICENSE), [Noto CJK Sans LICENSE](https://github.com/notofonts/noto-cjk/blob/main/Sans/LICENSE), and [Noto Emoji font LICENSE](https://github.com/googlefonts/noto-emoji/blob/main/fonts/LICENSE).
+
+| Family | Style/weights in proposal | Current catalog source version | License | Script/fallback role | Gzip bytes (selected files) | Build owner; runtime owners |
+| --- | --- | --- | --- | --- | ---: | --- |
+| IBM Plex Serif | normal 400/700; italic 400/700 | `fonts.gstatic.com/s/ibmplexserif/v20` | OFL 1.1, Reserved Font Name `Plex` | Primary serif; Latin and punctuation stack | 294,717 | `packages/fonts`; `apps/web` FontDisplay; `packages/pdf` registration |
+| IBM Plex Sans | normal 400/700; italic 400/700 | `fonts.gstatic.com/s/ibmplexsans/v23` | OFL 1.1, Reserved Font Name `Plex` | Primary sans | 435,469 | `packages/fonts`; `apps/web` FontDisplay; `packages/pdf` registration |
+| Noto Serif | normal 400/700; italic 400/700 | `fonts.gstatic.com/s/notoserif/v33` | OFL 1.1 | Serif punctuation fallback | 1,055,120 | `packages/fonts`; `packages/pdf` fallback registration |
+| Noto Sans | normal 400/700; italic 400/700 | `fonts.gstatic.com/s/notosans/v42` | OFL 1.1 | Sans punctuation fallback | 1,236,259 | `packages/fonts`; `packages/pdf` fallback registration |
+| Noto Sans SC | normal 400/700; italic reuses normal | `fonts.gstatic.com/s/notosanssc/v40` | OFL 1.1 (Noto CJK) | Simplified Han; CJK fallback | 12,766,416 | `packages/fonts`; `packages/pdf` CJK fallback |
+| Noto Serif SC | normal 400/700; italic reuses normal | `fonts.gstatic.com/s/notoserifsc/v35` | OFL 1.1 (Noto CJK) | Simplified Han serif fallback | 17,350,185 | `packages/fonts`; `packages/pdf` CJK fallback |
+| Noto Sans TC | normal 400/700; italic reuses normal | `fonts.gstatic.com/s/notosanstc/v39` | OFL 1.1 (Noto CJK) | Traditional Han fallback | 8,628,278 | `packages/fonts`; `packages/pdf` CJK fallback |
+| Noto Serif TC | normal 400/700; italic reuses normal | `fonts.gstatic.com/s/notoseriftc/v36` | OFL 1.1 (Noto CJK) | Traditional Han serif fallback | 11,804,923 | `packages/fonts`; `packages/pdf` CJK fallback |
+| Noto Sans JP | normal 400/700; italic reuses normal | `fonts.gstatic.com/s/notosansjp/v56` | OFL 1.1 (Noto CJK) | Kana and Japanese Han fallback | 6,383,035 | `packages/fonts`; `packages/pdf` CJK fallback |
+| Noto Serif JP | normal 400/700; italic reuses normal | `fonts.gstatic.com/s/notoserifjp/v33` | OFL 1.1 (Noto CJK) | Kana and Japanese Han serif fallback | 8,685,862 | `packages/fonts`; `packages/pdf` CJK fallback |
+| Noto Sans KR | normal 400/700; italic reuses normal | `fonts.gstatic.com/s/notosanskr/v39` | OFL 1.1 (Noto CJK) | Hangul and Korean Han fallback | 6,102,888 | `packages/fonts`; `packages/pdf` CJK fallback |
+| Noto Serif KR | normal 400/700; italic reuses normal | `fonts.gstatic.com/s/notoserifkr/v31` | OFL 1.1 (Noto CJK) | Hangul and Korean Han serif fallback | 11,113,442 | `packages/fonts`; `packages/pdf` CJK fallback |
+| Noto Sans Arabic | normal 400/700; italic reuses normal | `fonts.gstatic.com/s/notosansarabic/v33` | OFL 1.1 | Arabic sans fallback | 178,455 | `packages/fonts`; `packages/pdf` script fallback |
+| Noto Naskh Arabic | normal 400/700; italic reuses normal | `fonts.gstatic.com/s/notonaskharabic/v44` | OFL 1.1 | Arabic serif fallback | 190,924 | `packages/fonts`; `packages/pdf` script fallback |
+| Noto Sans Hebrew | normal 400/700; italic reuses normal | `fonts.gstatic.com/s/notosanshebrew/v50` | OFL 1.1 | Hebrew fallback for both serif/sans slots | 55,707 | `packages/fonts`; `packages/pdf` script fallback |
+| Noto Sans Thai | normal 400/700; italic reuses normal | `fonts.gstatic.com/s/notosansthai/v29` | OFL 1.1 | Thai fallback for both serif/sans slots | 55,173 | `packages/fonts`; `packages/pdf` script fallback |
+| Noto Emoji | normal 400/700; italic reuses normal | `fonts.gstatic.com/s/notoemoji/v62` | OFL 1.1 for font files; assets/tools have separate licenses | Emoji outline fallback; verify renderer support | 1,153,847 | `packages/fonts`; `packages/pdf` script fallback |
+
+Estimated transfer size for all rows and listed styles: **87,490,700 bytes (~83.44 MiB)**. This confirms why a full-catalog bundle is out of scope. A later implementation should subset by declared glyph requirements or make the administrator choose fallback families; it must not silently fetch another CDN.
+
+### Source and license obligations
+
+- Pin an upstream release/commit and retain source attribution plus the complete applicable license with hosted assets. Do not use mutable `@latest` URLs as runtime sources.
+- IBM Plex’s license has Reserved Font Name `Plex`; modified/subset outputs must follow OFL naming requirements.
+- Noto core, Noto CJK, and Noto Emoji font files are OFL 1.1, but Noto Emoji documents separate Apache/public-domain treatment for tools and flag image assets. Bundle only font files unless those other assets are intentionally needed and separately attributed.
+- License checks are build-owner responsibility (`packages/fonts`/tooling); runtime owners (`apps/web` and `packages/pdf`) consume only the validated manifest.
+
+### Missing-family and missing-asset behavior
+
+Local mode must resolve only same-origin administrator-hosted manifest paths. If imported resume data names an unavailable family, show an actionable missing-family error naming the family and required local asset; apply a configured local fallback only when the administrator explicitly supplied one. If a required weight/style/fallback asset is absent, fail the affected preview/export with an actionable diagnostic containing family/style/weight and local path. Never retry Google Fonts, jsDelivr, or any other remote URL in local mode.
+
+Standard PDF families (Helvetica, Courier, Times-Roman) remain file-free. They do not prove that a document containing punctuation, CJK, Arabic, Hebrew, Thai, or emoji is network-free; the script fallback rows remain required.
+
+## Verification record
+
+Completed read-only checks before handoff:
+
+- CodeGraph exploration of font catalog, picker preview, browser PDF, server PDF, and existing fallback tests.
+- `pnpm dlx @tanstack/intent@latest list`: no matching local intent skill for this work.
+- `pnpm exec biome check tests/e2e/specs/offline-fonts.spec.ts tests/e2e/fixtures/offline-fonts.ts turbo.json`: passed.
+- `git diff --check`: passed.
+- `pnpm --filter @reactive-resume/fonts test`: passed (55 tests).
+- `pnpm --filter @reactive-resume/pdf exec vitest run src/hooks/use-register-fonts.test.ts`: passed (35 tests).
+- Web typography/regression suite: passed (940 tests across 135 files); web and server package typechecks passed.
+- `pnpm exec playwright test tests/e2e/specs/offline-fonts.spec.ts --list`: passed (4 diagnostic tests collected).
+- E2E diagnostic execution: blocked by missing build outputs and unavailable PostgreSQL/server; no success claim made.
+- `pnpm exec turbo boundaries`: passed on fresh rerun (Turbo 2.10.12, 1108 files, no issues).
+
+The implementation intentionally stops at diagnostic fixtures and manifest evidence. Shared source resolution, asset hosting, local-mode configuration, and production behavior remain Phase A step 3+ work.

.orchestration/plan-27a-remediation-round-2.md

@@ -0,0 +1,22 @@
+# Plan 27A remediation round 2
+
+Date: 2026-09-06
+Base: `ae8e2f76f`
+
+## Focused fixes
+
+- Removed multilingual markers from the fixture headline. Each marker now exists only in its dedicated summary paragraph.
+- Added pure marker-location helpers. Marker lookup joins PDF text items, supports markers split across items, rejects duplicate occurrences, and rejects non-whitespace neighbors that could contaminate a local crop.
+- Raster measurement still scans with antialiasing padding but counts ink only inside the marker box, preventing neighboring glyphs from making blank or tofu-like evidence pass.
+- Browser PDF download now separates download errors from post-download evidence errors. A received download with failed rasterization is reported as `unresolved-raster-evidence-error` and fails the opt-in test rather than passing as a generic download error.
+- Added focused pure tests covering duplicate, split, neighboring, blank, and tofu-like cases.
+- Removed trailing spaces from `plan-27a-remediation.md`.
+
+## Verification
+
+- `pnpm exec vitest run tests/e2e/fixtures/offline-font-markers.test.ts` — 5/5 passed.
+- `pnpm exec biome check tests/e2e/specs/offline-fonts.spec.ts tests/e2e/fixtures/offline-fonts.ts tests/e2e/fixtures/offline-font-markers.ts tests/e2e/fixtures/offline-font-markers.test.ts` — passed.
+- `pnpm exec playwright test tests/e2e/specs/offline-fonts.spec.ts --list` — 4 tests collected.
+- `git diff --check` — passed after remediation-document whitespace cleanup.
+
+Full diagnostic E2E remains opt-in and was not run in this focused round. Server outbound request capture and verifiable restart identity remain explicit external host-level blockers; no production resolver changes were made.

.orchestration/plan-27a-remediation.md

@@ -0,0 +1,24 @@
+# Plan 27A remediation
+
+Date: 2026-09-06
+Base: `61b58ae9a`
+Scope: concrete findings from `.orchestration/plan-27a-independent-review.md` only.
+
+## Remediated findings
+
+- Builder PDF preview and browser PDF download now produce raster evidence. The fixture stores each multilingual marker in its own summary paragraph, allowing the diagnostic to locate marker-local PDF text boxes and measure only those raster crops. Reports attach a rendered PNG plus per-marker `inkPixels`, trimmed dimensions, and status. Blank and tofu-like crops fail assertions; no whole-page snapshot is used.
+- PDF text extraction is reported separately as `textLayerMarkers`. It is not described or asserted as proof of visible glyph outlines.
+- Server PDF output remains text-extraction-only and is explicitly classified as `serverGateStatus: unresolved-external-host-level-blocker`. `serverRestartFlag` is caller input, not restart proof. Browser Playwright routing is not used to infer server egress, and no production resolver or instrumentation behavior was added.
+- `.orchestration/plan-27a-diagnostic.md` now records a fresh boundaries pass and the corrected `87,490,700 bytes (~83.44 MiB)` arithmetic.
+- Diagnostic remains opt-in through `OFFLINE_FONT_DIAGNOSTIC=1`; normal CI behavior remains unchanged. Request logs stay sanitized to hostname and pathname.
+
+## Verification
+
+- `pnpm exec biome check tests/e2e/specs/offline-fonts.spec.ts tests/e2e/fixtures/offline-fonts.ts` — passed.
+- `git diff --check` — passed.
+- `pnpm exec playwright test tests/e2e/specs/offline-fonts.spec.ts --list` — 4 tests collected.
+- `pnpm --filter @reactive-resume/fonts test` — 55/55 passed.
+- `pnpm --filter @reactive-resume/pdf exec vitest run src/hooks/use-register-fonts.test.ts` — 35/35 passed.
+- `pnpm exec turbo boundaries` — passed on fresh rerun (Turbo 2.10.12, 1108 files, no issues).
+
+Full diagnostic E2E remains unrun because this environment lacks production build output, PostgreSQL, and a production server. Server cold-network capture and verifiable restart identity remain external host-level blockers by design; this remediation does not claim that gate is complete.

.orchestration/remediation-issue-3350-item-pagination.md

@@ -0,0 +1,17 @@
+# Issue 3350 remediation evidence
+
+## Findings addressed
+
+- `item-pagination.test.tsx` now derives complete numbered-token inventories for each generated fixture and asserts every token exactly once. Sampled token-to-physical-page placement checks remain separate.
+- Pagination fixtures snapshot `metadata.layout.pages` before rendering and assert authored layout pages are unchanged afterward. Overflow fixtures also assert physical PDF page count exceeds authored page count.
+- Unsafe `wrap={false}` renderer coverage remains diagnostic-only; no item controls, schema flags, or runtime behavior were added.
+
+## Verification
+
+- `rtk proxy pnpm --filter @reactive-resume/pdf exec vitest run src/semantic/pagination.test.tsx src/templates/shared/item-pagination.test.tsx` — 2 files, 11 tests passed.
+- `rtk proxy pnpm --filter @reactive-resume/pdf typecheck` — passed.
+- `rtk proxy pnpm exec biome check packages/pdf/src/templates/shared/item-pagination.test.tsx` — passed.
+- `rtk proxy pnpm exec turbo boundaries` — passed; 1109 files checked.
+- `rtk git diff --check origin/main...HEAD` — passed.
+
+Only PDF test coverage and this evidence file changed; production behavior remains untouched.

.vercelignore

@@ -0,0 +1,27 @@
+.env*
+!.env.example
+.git
+.codegraph
+.superpowers
+.agents
+.codex
+.claude
+.turbo
+**/node_modules
+**/dist
+**/coverage
+**/reports
+data
+apps/web/data
+screenshots
+.vercel
+.wrangler
+.tanstack
+.worktrees
+.migration
+.supermemory
+.cache
+tmp
+temp
+**/test-results
+**/playwright-report

.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,32 +1,23 @@
 {
-	"[typescript]": {
-		"editor.defaultFormatter": "biomejs.biome"
-	},
 	"biome.enabled": true,
 	"editor.codeActionsOnSave": {
-		"source.biome": "explicit",
 		"source.fixAll.biome": "explicit",
 		"source.organizeImports.biome": "explicit"
 	},
 	"editor.defaultFormatter": "biomejs.biome",
-	"files.associations": {
-		"*.css": "tailwindcss"
-	},
 	"files.readonlyInclude": {
+		"**/locales/**.po": true,
 		"**/routeTree.gen.ts": true,
 		"pnpm-lock.yaml": true
 	},
 	"files.watcherExclude": {
+		"**/locales/**.po": true,
 		"**/routeTree.gen.ts": true,
-		"locales/**.po": true,
 		"pnpm-lock.yaml": true
 	},
-	"i18n-ally.enabledParsers": ["po"],
-	"i18n-ally.localesPaths": ["locales"],
-	"i18n-ally.sourceLanguage": "en-US",
 	"search.exclude": {
+		"**/locales/**.po": true,
 		"**/routeTree.gen.ts": true,
-		"locales/**.po": true,
 		"pnpm-lock.yaml": true
 	},
 	"tailwindCSS.classFunctions": ["cn", "cva"],
@@ -36,5 +27,8 @@
 		["cn\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
 	],
 	"tailwindCSS.experimental.configFile": "src/styles/globals.css",
-	"typescript.tsdk": "node_modules/typescript/lib"
+	"typescript.experimental.useTsgo": true,
+	"[json]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	}
 }

AGENTS.md

@@ -1,47 +1,124 @@
-# AGENTS.md
+<!-- intent-skills:start -->
+## Skill Loading
 
-## Cursor Cloud specific instructions
+Before editing files for a substantial task:
+- Run `pnpm dlx @tanstack/intent@latest list` from the workspace root to see available local skills.
+- If a listed skill matches the task, run `pnpm dlx @tanstack/intent@latest load <package>#<skill>` before changing files.
+- Use the loaded `SKILL.md` guidance while making the change.
+- Monorepos: when working across packages, run the skill check from the workspace root and prefer the local skill for the package being changed.
+- Multiple matches: prefer the most specific local skill for the package or concern you are changing; load additional skills only when the task spans multiple packages or concerns.
+<!-- intent-skills:end -->
 
-### Overview
+<!-- caveman-begin -->
+Respond terse like smart caveman. All technical substance stay. Only fluff die.
 
-Reactive Resume is a single-package full-stack TypeScript app (not a monorepo) built with TanStack Start (React 19, Vite, Nitro). It serves both frontend and API on port 3000.
+Rules:
+- Drop: articles (a/an/the), filler (just/really/basically), pleasantries, hedging
+- Fragments OK. Short synonyms. Technical terms exact. Code unchanged.
+- Pattern: [thing] [action] [reason]. [next step].
+- Not: "Sure! I'd be happy to help you with that."
+- Yes: "Bug in auth middleware. Fix:"
 
-### Infrastructure services
+Switch level: /caveman lite|full|ultra|wenyan-lite|wenyan-full|wenyan-ultra
+Stop: "stop caveman" or "normal mode"
 
-Before running the dev server, Docker must be running with at least PostgreSQL. Start services via `compose.dev.yml`:
+Auto-Clarity: drop caveman for security warnings, irreversible actions, user confused. Resume after.
 
-```bash
-sudo dockerd &>/var/log/dockerd.log &
-sudo docker compose -f compose.dev.yml up -d postgres browserless
+Boundaries: code/commits/PRs written normal.
+<!-- caveman-end -->
+
+## Agent skills
+
+- Issues and specs: GitHub Issues for `reactive-resume/reactive-resume`. See `docs/agents/issue-tracker.md`.
+
+## Overview
+
+Reactive Resume is a pnpm monorepo (Turborepo) with two deployable apps: `apps/web` (React 19 SPA with TanStack Router and Vite) and `apps/server` (Hono / Node.js). The production Docker image runs a single Node.js process on port 3000; `apps/server` mounts the API/auth/MCP/static routes and serves the built web app.
+
+Internal packages are source-consumed through `package.json` export maps pointing at `src` files. Do not assume package-local `dist` output exists unless a package explicitly adds it.
+
+Prerequisites: **Node.js 24** (pinned in `.nvmrc`; matches Dockerfile `ARG NODE_VERSION=24`), **pnpm 12.3.4** (pinned by `packageManager` in the root `package.json`; pnpm self-manages to it, so any recent pnpm can bootstrap — the Dockerfile's `ARG PNPM_VERSION` only picks the base image) ([install guide](https://pnpm.io/installation)), and **Docker** for PostgreSQL (`sudo dockerd &` if the daemon isn't running).
+
+## Ownership map
+
+Where each concern lives, and where new code for it goes:
+
+| Area | Owner |
+|------|-------|
+| Web routes, loaders, user-facing workflows | `apps/web/src/routes`, `apps/web/src/features` (file-based; never hand-edit `routeTree.gen.ts`) |
+| Server HTTP routes/adapters, startup checks, static handlers, MCP transport, OpenAPI/well-known | `apps/server/src/{http,rpc,mcp,openapi,static,startup}` |
+| Authenticated API contracts + business logic | `packages/api/src/features/*` (oRPC routers, DTOs, rate limiting; aggregated at `@reactive-resume/api/routers` for `/api/rpc`) |
+| Auth | `packages/auth` (Better Auth config/helpers/types; `apps/server/src/http/auth.ts` delegates to `auth.handler`) |
+| DB client + schema | `packages/db` (Drizzle; migrations at repo root `migrations/`) |
+| Server env validation | `packages/env` (auto-loads root `.env`) |
+| Resume/page/template Zod schemas | `packages/schema` |
+| Pure resume-domain behavior (no DB/HTTP/DOM/renderer deps) | `packages/resume` (JSON Patch helpers, social-network icons) |
+| Resume PDF rendering | `packages/pdf` (React PDF document, font registration, template primitives, browser/server adapters) |
+| PDF.js viewer/canvas UI | `apps/web/src/features/resume` — never in `packages/pdf` |
+| DOCX export | `packages/docx` |
+| MCP tools/prompts/resources/server-card | `packages/mcp` |
+| Generic UI primitives + hooks | `packages/ui` (Base UI/shadcn-style); workflow-specific UI stays in the owning web feature |
+| Focused support surfaces | `packages/fonts`, `packages/email`, `packages/import`, `packages/ai`, `packages/utils`, `packages/config` — prefer existing exports over cross-package shortcuts |
+| Dev-only scripts | `tooling/`, not `packages/`, so packages only hold runtime-bundled code |
+
+Narrow cross-cutting helpers go in `packages/utils` only after checking no domain package is a better owner. Specifically: resume JSON Patch behavior belongs in `@reactive-resume/resume/patch` and DOCX builders in `@reactive-resume/docx` — not in `@reactive-resume/utils`.
+
+## Web app conventions
+
+- `apps/web/src/router.tsx` initializes router context with `queryClient`, `orpc`, `theme`, `locale`, `session`, and `flags`. Reuse route context instead of refetching these ad hoc.
+- The web app is a client-rendered SPA. `apps/server` serves `index.html` and injects page metadata (OpenGraph, canonical, JSON-LD) in `apps/server/src/static/web.ts`; there is no React SSR.
+- Builder shell: `apps/web/src/routes/builder/$resumeId`. Public resume route: `apps/web/src/routes/$username/$slug.tsx`.
+- Browser-only preview code: `apps/web/src/features/resume/preview`. Public PDF viewer: `apps/web/src/features/resume/public`. Keep PDF.js/canvas code in these features, not in `packages/pdf`.
+- oRPC client: `apps/web/src/libs/orpc/client.ts` calls `/api/rpc` with credentials included. `apps/web/src/libs/orpc/fetch.ts` stages large request bodies through Blob on Vercel.
+- For React components with explicit props, use a named props type (e.g. `type FooProps = {...}` with `function Foo(props: FooProps)`) rather than inline object annotations, especially with more than one field or with generics.
+
+## Package boundaries
+
+`pnpm exec turbo boundaries` is the executable check. Rules:
+
+- Workspace deps go through package names and export maps. Never import another workspace's `src` tree via repo paths, `@reactive-resume/*/src/*`, or TS path aliases.
+- Workspace `turbo.json` files declare coarse tags: `app:web`, `app:server`, `runtime:server` (server-only packages: API/auth/db/env/email/MCP), `runtime:browser` (browser-only shared UI), `runtime:universal` (environment-neutral domain packages), plus `role:domain|infra|adapter|api|rendering|tooling` for intent.
+- Runtime-specific code lives behind explicit export subpaths (`@reactive-resume/pdf/browser`, `@reactive-resume/pdf/server`, `@reactive-resume/env/server`). Keep root exports environment-neutral unless the package is intentionally server-only.
+- Wildcard exports are allowed only for leaf libraries with an intentionally file-like surface — currently `@reactive-resume/ui/components/*`, `@reactive-resume/ui/hooks/*`, and schema resume model files. Prefer explicit exports for packages owning runtime behavior.
+- Prefer `protectedProcedure` from `packages/api/src/context.ts` for authenticated procedures. Expose only intentional public surfaces through `packages/api/package.json`.
+- Shared PDF section filtering: `packages/pdf/src/templates/shared/filtering.ts`. Template-specific visual exceptions stay in the owning template directory unless multiple templates need the behavior. `packages/pdf/src/hooks/use-register-fonts.ts` owns font registration, standard PDF fonts, CJK fallback stacks, and global hyphenation.
+
+Multi-place changes:
+
+- **Resume data shape**: `packages/schema/src/resume/*` first, then API DTOs, importers, PDF rendering, and web forms consuming it.
+- **New template**: `packages/schema/src/templates.ts`, `packages/pdf/src/templates/index.ts`, source under `packages/pdf/src/templates/<name>/`, and previews under `apps/web/public/templates/{jpg,pdf}`.
+- **New DB column/table**: `packages/db/src/schema/*`, then `pnpm db:generate`.
+- **New env var**: `packages/env/src/server.ts` **and** the `globalEnv` array in `turbo.json`. Turborepo 2.x strict env mode filters out unlisted vars, so the variable will be `undefined` in child processes at runtime even when correctly set in the OS/container environment.
+
+## Environment and database
+
+Copy `.env.example` to `.env.local`. Three required vars: `APP_URL` (default `http://localhost:3000`), `DATABASE_URL` (default `postgresql://postgres:postgres@localhost:5432/postgres`), `AUTH_SECRET` (any non-empty string).
+
+- **S3/SeaweedFS optional.** If `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, and `S3_BUCKET` are all set, the app uses S3-compatible storage. `.env.example` ships SeaweedFS defaults, so either start the `seaweedfs` compose service or comment those vars out to use local filesystem storage under `<workspace>/data`. `LOCAL_STORAGE_PATH` must be absolute when set.
+- **`REDIS_URL` and `ENCRYPTION_SECRET`** are optional for core resume flows but both required for saved AI providers and the authenticated `/agent` workspace. Host-run dev uses `REDIS_URL=redis://localhost:6379`; the container-run app uses `redis://redis:6379`.
+- **`drizzle-kit` (used by `pnpm db:migrate`) reads `DATABASE_URL` from `process.env` directly** — it does not auto-load `.env`. The root migration scripts load `.env.local` through `dotenvx` before invoking Drizzle Kit.
+- The production server auto-runs migrations at startup before serving traffic, so manual `pnpm db:migrate` is mainly for first setup, migration debugging, or applying migrations without starting the app.
+
+## Commands
+
+Dev server and migration scripts load `.env.local` through the project-local `dotenvx`. Tests, typechecks, linters, boundary checks, and `pnpm build` do not load it automatically.
+
+```
+sudo docker compose -f compose.dev.yml up -d postgres                                    # DB only
+sudo docker compose -f compose.dev.yml up -d postgres redis seaweedfs seaweedfs_create_bucket   # full infra
+pnpm dev                                          # port 3000 (dev:web for web only)
+pnpm db:generate                                  # db:migrate to apply
+pnpm check                                       # Biome — WRITE-CAPABLE (--write --unsafe)
+pnpm test | pnpm typecheck | pnpm build | pnpm exec turbo boundaries
 ```
 
-- **PostgreSQL** (port 5432) — required. The app auto-runs Drizzle migrations on startup via a Nitro plugin.
-- **Browserless** (port 4000) — required for PDF export. Maps container port 3000 to host port 4000.
+Prefer package filters over repo-wide runs, e.g. `pnpm --filter web typecheck`, `pnpm --filter @reactive-resume/pdf test`. Vitest paths are package-relative under `pnpm --filter <package> test -- <path>`.
 
-### Environment variables
+## Gotchas
 
-Copy `.env.example` to `.env` if not present. Key notes for local dev:
-
-- `APP_URL` — local dev server origin on port 3000.
-- `PRINTER_APP_URL` — must use the Docker bridge gateway IP (not localhost) so the Browserless container can reach the app on the host. Get the IP with: `sudo docker network inspect reactive_resume_default --format '{{range .IPAM.Config}}{{.Gateway}}{{end}}'`
-- `PRINTER_ENDPOINT` — websocket URL to Browserless on host port 4000 with token `1234567890`.
-- `DATABASE_URL` — PostgreSQL connection using `postgres:postgres` credentials on localhost:5432.
-- S3/Storage and SMTP vars can be left empty — the app falls back to local filesystem and console-logged emails.
-
-### Common commands
-
-See `scripts` in `package.json`. Key ones:
-
-| Task | Command |
-|---|---|
-| Dev server | `pnpm dev` (port 3000) |
-| Lint (Biome) | `pnpm lint` |
-| Typecheck | `pnpm typecheck` |
-| DB migrations | `pnpm db:generate` / `pnpm db:migrate` (auto-runs on dev start) |
-
-### Gotchas
-
-- The Docker daemon needs `fuse-overlayfs` storage driver and `iptables-legacy` in the cloud VM (nested container environment).
-- `pnpm.onlyBuiltDependencies` in `package.json` controls which packages are allowed to run install scripts — no interactive `pnpm approve-builds` needed.
-- Email verification is optional in dev — after signup, click "Continue" to skip.
-- Vite 8 is beta (`^8.0.0-beta.15`); Nitro uses a nightly build. Occasional upstream issues may occur.
+- Email sending needs SMTP config; without it emails are logged to console. Dev still works — verification links appear in server logs.
+- `lefthook.yml` pre-commit runs `biome check` on staged files. Run `pnpm check` before committing.
+- `pnpm check` is write-capable. Call that out when using it, and use narrower Biome commands for a non-mutating inspection.
+- Biome: tabs, double quotes, line width 120, organized import groups, sorted Tailwind classes for `clsx`, `cva`, `cn`.
+- Most packages typecheck with `tsgo --noEmit` and test with `vitest run --passWithNoTests`.
+- There may be unrelated local edits in the worktree. Check `git status --short` first; do not revert files you did not touch.

CLAUDE.md

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

DESIGN.md

@@ -0,0 +1,350 @@
+---
+version: alpha
+name: Reactive Resume
+description: A monochrome, content-first design system for a free and open-source resume builder. Dark-by-default with light mode support.
+colors:
+  primary: "#343434"
+  primary-foreground: "#FBFBFB"
+  secondary: "#F7F7F7"
+  secondary-foreground: "#343434"
+  background: "#FFFFFF"
+  foreground: "#252525"
+  muted: "#F7F7F7"
+  muted-foreground: "#8E8E8E"
+  card: "#FFFFFF"
+  card-foreground: "#252525"
+  border: "#EBEBEB"
+  input: "#EBEBEB"
+  ring: "#B5B5B5"
+  destructive: "#DC2626"
+  on-destructive: "#FFFFFF"
+typography:
+  heading:
+    fontFamily: IBM Plex Sans Variable
+    fontSize: 1rem
+    fontWeight: 500
+  body:
+    fontFamily: IBM Plex Sans Variable
+    fontSize: 0.875rem
+    fontWeight: 400
+  body-sm:
+    fontFamily: IBM Plex Sans Variable
+    fontSize: 0.75rem
+    fontWeight: 400
+  label:
+    fontFamily: IBM Plex Sans Variable
+    fontSize: 0.8rem
+    fontWeight: 500
+  hero-heading:
+    fontFamily: IBM Plex Sans Variable
+    fontSize: 3.75rem
+    fontWeight: 700
+    letterSpacing: -0.025em
+rounded:
+  sm: 0.18rem
+  md: 0.24rem
+  lg: 0.3rem
+  xl: 0.42rem
+  2xl: 0.54rem
+  3xl: 0.66rem
+  4xl: 0.78rem
+spacing:
+  xs: 4px
+  sm: 8px
+  md: 16px
+  lg: 24px
+  xl: 32px
+  2xl: 48px
+components:
+  button-default:
+    backgroundColor: "{colors.primary}"
+    textColor: "{colors.primary-foreground}"
+    rounded: "{rounded.lg}"
+    padding: 10px
+    height: 36px
+  button-outline:
+    backgroundColor: "{colors.background}"
+    textColor: "{colors.foreground}"
+    rounded: "{rounded.lg}"
+    padding: 10px
+    height: 36px
+  button-secondary:
+    backgroundColor: "{colors.secondary}"
+    textColor: "{colors.secondary-foreground}"
+    rounded: "{rounded.lg}"
+    padding: 10px
+    height: 36px
+  button-ghost:
+    backgroundColor: "{colors.background}"
+    textColor: "{colors.foreground}"
+    rounded: "{rounded.lg}"
+    padding: 10px
+    height: 36px
+  button-destructive:
+    backgroundColor: "{colors.destructive}"
+    textColor: "{colors.on-destructive}"
+    rounded: "{rounded.lg}"
+    padding: 10px
+    height: 36px
+  card:
+    backgroundColor: "{colors.card}"
+    textColor: "{colors.card-foreground}"
+    rounded: "{rounded.lg}"
+    padding: 16px
+  input:
+    backgroundColor: "{colors.background}"
+    textColor: "{colors.foreground}"
+    rounded: "{rounded.lg}"
+    height: 36px
+    padding: 10px
+  input-focus:
+    backgroundColor: "{colors.background}"
+    textColor: "{colors.foreground}"
+    rounded: "{rounded.lg}"
+    height: 36px
+    padding: 10px
+  badge:
+    backgroundColor: "{colors.primary}"
+    textColor: "{colors.primary-foreground}"
+    rounded: "{rounded.md}"
+    padding: 4px
+  popover:
+    backgroundColor: "{colors.card}"
+    textColor: "{colors.card-foreground}"
+    rounded: "{rounded.xl}"
+    padding: 4px
+  sidebar:
+    backgroundColor: "{colors.muted}"
+    textColor: "{colors.foreground}"
+    padding: 8px
+  sidebar-item:
+    backgroundColor: "{colors.muted}"
+    textColor: "{colors.muted-foreground}"
+    rounded: "{rounded.lg}"
+    padding: 8px
+  sidebar-item-active:
+    backgroundColor: "{colors.primary}"
+    textColor: "{colors.primary-foreground}"
+    rounded: "{rounded.lg}"
+    padding: 8px
+  tooltip:
+    backgroundColor: "{colors.primary}"
+    textColor: "{colors.primary-foreground}"
+    rounded: "{rounded.md}"
+    padding: 6px
+  separator:
+    backgroundColor: "{colors.border}"
+    height: 1px
+  dialog:
+    backgroundColor: "{colors.card}"
+    textColor: "{colors.card-foreground}"
+    rounded: "{rounded.xl}"
+    padding: 24px
+  input-invalid:
+    backgroundColor: "{colors.background}"
+    textColor: "{colors.destructive}"
+    rounded: "{rounded.lg}"
+    height: 36px
+    padding: 10px
+---
+
+## Overview
+
+Reactive Resume is a monochrome, content-first design system built for a resume builder used by tens of thousands of people worldwide. The visual identity prioritizes readability and unobtrusiveness — the user's resume content is always the hero, never the chrome around it.
+
+The system defaults to dark mode with a warm near-black backdrop that makes the resume preview "float" as the visual anchor. Light mode is supported as a full alternative. The authenticated app shell (dashboard, builder, settings) uses an entirely achromatic grayscale palette — the sole chromatic exception is destructive red for dangerous actions. The landing page introduces subtle chromatic accents: blue-tinted spotlight gradients on the hero, a multicolor text-mask animation on hover, and social auth provider brand colors (Google blue, LinkedIn blue) on the login page.
+
+The overall aesthetic is a professional tool UI: clean grid lines, subtle borders, generous whitespace, and typography that steps back to let the content shine. Think "VS Code meets Figma" — a productivity workspace, not a marketing site.
+
+One deliberate counterpoint to the serious UI: all resume templates are named after Pokemon (Azurill, Bronzor, Chikorita, Ditgar, Gengar, Pikachu, etc.). This is an intentional brand choice — playful naming for templates injects personality into an otherwise utilitarian interface, making templates feel collectible and memorable rather than generic ("Template 1", "Modern", "Classic").
+
+## Colors
+
+The palette is rooted in achromatic OKLch values (chroma = 0), producing a pure grayscale scale without warm or cool casts. Colors are defined as CSS custom properties using `oklch()` and consumed through Tailwind CSS 4 theme tokens. Always prefer CSS variables (e.g., `var(--primary)`) or Tailwind tokens (e.g., `bg-primary`) over raw color values. The hex values in this document's YAML front matter are agent-friendly approximations of the canonical OKLch definitions in `packages/ui/src/styles/globals.css` — use hex only where OKLch is unavailable.
+
+- **Primary (#343434 light / #EBEBEB dark):** Used for high-emphasis interactive surfaces — default buttons, selected states, and text selection. In dark mode this inverts to near-white so buttons remain prominent.
+- **Foreground (#252525 light / #FBFBFB dark):** Body text and headings. High contrast against the background in both themes.
+- **Background (#FFFFFF light / #252525 dark):** The canvas. Pure white in light mode, warm near-black in dark mode.
+- **Card (#FFFFFF light / #343434 dark):** Elevated surface for cards, panels, and the builder sidebar. In dark mode, one step lighter than the background to create subtle depth.
+- **Muted (#F7F7F7 light / #454545 dark):** De-emphasized backgrounds for secondary UI regions, hover states, and inactive tabs.
+- **Muted Foreground (#8E8E8E light / #B5B5B5 dark):** Captions, helper text, timestamps, and metadata. Deliberately low-contrast against the background to recede visually.
+- **Border (#EBEBEB light / white at 10% opacity dark):** Thin separator lines. In dark mode, uses transparent white rather than a solid gray to blend naturally with any underlying surface color.
+- **Input (#EBEBEB light / white at 15% opacity dark):** Form field borders, slightly more prominent than general borders to make input areas discoverable.
+- **Destructive (#DC2626 light / #EF4444 dark):** The only chromatic color in the palette. Reserved exclusively for delete actions, error states, and danger-zone operations. Used at 10% opacity as a background tint with full saturation for text, creating a soft but unmistakable warning.
+- **Ring (#B5B5B5 light / #8E8E8E dark):** Focus ring indicator at 50% opacity, surrounding focused interactive elements.
+- **Sidebar Primary (dark only, #6366F1):** An indigo value inherited from the shadcn/ui defaults. Not actively used in the current UI — sidebar active states use the standard grayscale primary token instead. Retained in the CSS custom properties for potential future customization.
+
+Resume templates have their own independent color system — users pick primary, text, and background colors per resume through a color picker in the builder's Design panel. These template colors are completely separate from the app shell palette.
+
+## Typography
+
+The entire application uses a single typeface: **IBM Plex Sans Variable**. This is a humanist sans-serif with an extensive weight range (100–900) and excellent readability at small sizes, both on screen and in PDFs.
+
+- **Hero heading (responsive: 2.25rem mobile / 3rem tablet / 3.75rem desktop, weight 700, tracking-tight):** Landing page headline only. Large, bold, and commanding. Scales across three breakpoints.
+- **Section heading (1rem / 16px, weight 500):** Used for section titles in the builder sidebar, settings panels, and dashboard cards. Medium weight provides hierarchy without shouting.
+- **Body (0.875rem / 14px, weight 400):** The workhorse. All form labels, descriptions, card content, and general UI text.
+- **Small body (0.75rem / 12px, weight 400):** Captions, helper text, timestamps, and metadata.
+- **Label (0.8rem / ~13px, weight 500):** Button text, badge labels, and form field labels. Slightly heavier than body to denote interactivity.
+
+The resume content itself uses a separate font system — users choose from 1,000+ Google Fonts for their resume headings and body text, with category-aware fallback stacks including CJK support (Noto Sans SC, PingFang SC, Hiragino Sans GB for sans-serif; Noto Serif SC, Songti SC for serif). Standard PDF fonts (Helvetica, Courier, Times-Roman) are available as offline fallbacks.
+
+Font rendering uses `antialiased` (grayscale AA) and `proportional-nums` across the board for clean rendering and properly spaced numerals in dates and phone numbers.
+
+## Layout
+
+### Builder (Three-Panel Workspace)
+
+The core builder uses a resizable three-panel layout powered by `react-resizable-panels`:
+
+- **Left sidebar (default 22%):** Resume section forms — personal info, experience, education, skills, and custom sections. Scrollable with collapsible section groups.
+- **Center artboard (default 56%):** Live resume preview rendered via PDF.js canvas. Supports zoom, pan, and pinch gestures via `react-zoom-pan-pinch`. The preview maintains A4 aspect ratio (210:297) with a subtle shadow to simulate a physical page.
+- **Right sidebar (default 22%):** Design controls — template picker, font selection, color picker, layout manager (page assignments, section ordering via drag-and-drop).
+
+Panel sizes persist in cookies. On mobile (< 768px), sidebars collapse to 0% width and become toggleable overlays (max 95% width when open). The desktop minimum collapsed width is 48px (icon rail).
+
+### Dashboard
+
+Standard sidebar navigation layout using the `Sidebar` component system. The sidebar contains: logo, resume list link, agent link, settings subnavigation (profile, preferences, authentication, API keys, integrations, danger zone), and a footer with user avatar. Content area shows a responsive grid of resume cards.
+
+### Landing Page
+
+Full-width single-column marketing layout:
+1. **Floating builder preview** — A non-interactive screenshot of the builder as a hero visual, creating an immediate "this is what you get" impression.
+2. **Hero** — Centered headline, subheadline, and two CTAs (primary "Get Started" with arrow, ghost "Learn More" with icon).
+3. **Features grid** — 4-column responsive grid with icon + title + description cards, separated by thin border lines.
+4. **Template carousel** — Horizontally scrolling row of template preview thumbnails with Pokemon-themed names.
+5. **Testimonials** — Tiled user quotes in a masonry-style grid.
+6. **Support / FAQ / Footer** — Accordion FAQ, community section, and a 4-column footer with logo, resource links, community links, and license info.
+
+### Responsive Breakpoints
+
+Mobile detection uses a 768px threshold via `MediaQueryList`. The layout is optimized for workspace productivity on larger screens, with responsive mobile support that adapts the multi-panel builder into a streamlined single-panel experience. Both desktop and mobile are supported experiences — the builder's three-panel layout leverages desktop space, while mobile surfaces the same editing capabilities through collapsible overlays.
+
+### Page Aspect Ratio
+
+A custom Tailwind token `--aspect-page: 210 / 297` enforces A4 paper proportions wherever resume pages are rendered (builder preview, public view, PDF export).
+
+## Animation
+
+Motion exists to explain a change, confirm an action, or soften a jump. This is a tool people use for hours, so it stays crisp: short, precise, rarely decorative.
+
+**Frequency decides first.** Keyboard-initiated actions (the command palette, ⌘B sidebar toggle, zoom shortcuts, keyboard-opened menus via Base UI's `data-instant`) do not animate. Things hit tens of times a day (list rows, tooltips after the first, context menus) get opacity-only or no motion. Dialogs, sheets and toasts get a standard transition. Only rare moments (marketing pages, first load) get more.
+
+**Tokens.** Never hand-type a curve.
+- CSS: `ease-out-strong` / `var(--ease-out-strong)` (`cubic-bezier(0.23, 1, 0.32, 1)`) for anything entering, exiting or responding; `ease-in-out-strong` for on-screen movement nobody is waiting on (ambient loops, carousels); `ease-drawer` for sheets. Never `ease-in`.
+- Motion (JS): `EASE_OUT_STRONG` from `apps/web/src/libs/motion.ts`.
+
+**Durations.** Press feedback 100–160ms, tooltips/popovers/menus 150ms in and 100ms out, dialogs 200ms in and 150ms out, sheets 300ms. App UI stays under 300ms; marketing reveals may run 0.5–0.9s. Exits are faster than entrances.
+
+**Mechanics.**
+- Popups use interruptible CSS transitions on Base UI's `data-starting-style` / `data-ending-style`, scale from `0.95` (never `0`) and grow from `origin-(--transform-origin)`. Modals stay centred.
+- Animate `transform`/`translate`/`scale` and `opacity` only. No `transition-all`, no permanent `will-change` (Motion promotes layers while it animates).
+- Presses use `active:scale-[0.97]`. `Button` already has it; don't wrap it in Motion hover/tap wrappers.
+- Lists use `AnimatePresence initial={false}` so items animate when added or removed, not every time the list mounts.
+- Continuous loops (marquees, drifting spotlights) are CSS keyframes, so they run off the main thread.
+
+**Reduced motion:** `MotionConfig reducedMotion="user"` disables Motion transforms, and CSS transitions and animations collapse to `0.01ms` — except `animate-spin`, which keeps spinning so loading never looks frozen. Values driven by `useSpring`/`useMotionValue` bypass `MotionConfig`, so check `useReducedMotion()` there.
+
+## Elevation & Depth
+
+Elevation is handled through background color layering rather than drop shadows:
+
+- **Level 0 — Background:** The base canvas (`--background`).
+- **Level 1 — Card:** One step lighter in dark mode (`--card`), used for sidebars, panels, and cards.
+- **Level 2 — Popover:** Same as card, but appears above the content layer in popovers, dropdowns, and command palette.
+- **Level 3 — Overlay:** Backdrop blur (`backdrop-blur-xs` at 0.5px or `backdrop-blur-2xl` at 40px) with `backdrop-saturate-150` for modal overlays, creating a frosted-glass effect over the workspace.
+
+The resume preview page uses a subtle drop shadow to simulate a physical sheet of paper floating above the dark artboard — one of the few places actual shadows appear.
+
+## Shapes
+
+Border radius follows a multiplicative scale from a single `--radius` base of `0.3rem`:
+
+| Token | Value | Usage |
+|:------|:------|:------|
+| `sm` | 0.18rem (≈3px) | Small badges, inline chips |
+| `md` | 0.24rem (≈4px) | XS/SM buttons, compact elements |
+| `lg` | 0.3rem (≈5px) | Default buttons, cards, inputs |
+| `xl` | 0.42rem (≈7px) | Larger cards, modal corners |
+| `2xl` | 0.54rem (≈9px) | Dialog containers |
+| `3xl` | 0.66rem (≈11px) | Large panels |
+| `4xl` | 0.78rem (≈12px) | Full-page modals |
+
+The radius scale is deliberately tight — the largest value (0.78rem) is still quite subtle. This avoids the "rounded everything" aesthetic and keeps the UI feeling precise and tool-like. Interactive elements consistently use `rounded-lg` as the default.
+
+## Components
+
+### Buttons
+
+Six variants, all sharing `rounded-lg` corners, `font-medium`, `text-sm`, and a 1px `translate-y` on active press (except when the button opens a popup):
+
+- **Default:** Solid primary background. The highest-emphasis action on any screen.
+- **Outline:** Transparent with a border. For secondary actions that need clear boundaries.
+- **Secondary:** Muted background. For paired actions alongside a primary button.
+- **Ghost:** No background or border. For toolbar actions and inline controls where chrome would be noise.
+- **Destructive:** Red at 10% opacity background with red text. Visually alarming without being garish.
+- **Link:** Underline-on-hover text. For inline navigation within prose.
+
+Size scale: `xs` (28px), `sm` (32px), `default` (36px), `lg` (40px), plus `icon` variants at each size for square icon-only buttons.
+
+### Cards
+
+White/dark surface with foreground text. Composed of `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`, and `CardAction` slots. Default vertical padding is `py-4` (compact: `py-3`).
+
+### Forms
+
+Built on TanStack Form with Zod validation. Composed of `FormItem`, `FormLabel`, `FormControl`, `FormMessage`, and `FormDescription`. Validation errors only appear after field touch. Invalid fields get a red destructive border with a ring.
+
+### Dialogs
+
+Centralized dialog manager with 40+ dialog types, all rendered via pattern matching (`ts-pattern`). Dialogs support before-close validation, form blocking for unsaved changes, and confirmation prompts. Used for all CRUD operations on resume sections, settings changes, and import/export flows.
+
+### Command Palette
+
+Triggered by `Cmd+K` / `Ctrl+K`. Built on `cmdk` with fuzzy search via `Fuse.js`. Multi-page navigation (resumes, settings, preferences) with back navigation via Backspace. Screen-reader accessible with `sr-only` headings.
+
+### Toast Notifications
+
+Powered by Sonner, positioned bottom-right with rich colors. Used for auto-save feedback, form submission status, error reporting, and donation prompts. Loading toasts are used during async operations (PDF generation, resume creation) with dismiss-on-complete.
+
+### Drag and Drop
+
+Powered by `@dnd-kit` with `PointerSensor` and `KeyboardSensor`. Used in chip inputs (skill tags, URL lists) and page layout management (section ordering across resume pages). Smooth animations via Motion library.
+
+## Internationalization
+
+The app supports 40+ locales including RTL languages (Arabic, Hebrew, Persian, Urdu, Uyghur, Yiddish). i18n is not an afterthought — it shapes layout decisions:
+
+**Direction:** The `<html>` element receives `dir="rtl"` or `dir="ltr"` based on the active locale, detected via `isRTL()` which checks the language prefix against a known RTL set. All layout mirroring flows from this single attribute.
+
+**Logical properties:** Use CSS logical properties (`ps-`, `pe-`, `ms-`, `me-`, `inline-start`, `inline-end`, `inset-s-`, `inset-e-`) instead of physical (`pl-`, `pr-`, `ml-`, `mr-`, `left`, `right`). Button components already use `has-data-[icon=inline-start]:ps-2` and `has-data-[icon=inline-end]:pe-2` patterns. This ensures correct spacing in both LTR and RTL layouts without separate stylesheets.
+
+**Variable-length text:** Translations can be 30–50% longer than English (German, Finnish) or significantly shorter (CJK). UI elements should accommodate variable text length — avoid fixed widths on buttons and labels. Use `whitespace-nowrap` only where truncation is acceptable, and prefer `min-w-0` with `truncate` over fixed-width containers.
+
+**Icons:** Directional icons (arrows, chevrons, progress indicators) should mirror in RTL contexts. Phosphor Icons provides mirrored variants for directional icons. Non-directional icons (settings gear, checkmark, delete) do not mirror.
+
+**Strings:** All user-facing strings use Lingui macros (`t`, `msg`, `<Trans>`) — never hardcode English text in components. Translation files are `.po` format under `/locale/`.
+
+## Do's and Don'ts
+
+### Do
+
+- **Use the grayscale palette for all app chrome.** The absence of color is the brand. The resume content is the only thing that should be colorful.
+- **Default to dark mode.** The dark workspace makes resume previews pop and reduces eye strain during extended editing sessions.
+- **Use `text-sm` (14px) as the base text size.** The UI is information-dense — form fields, section labels, metadata — and needs to be scannable without feeling cramped.
+- **Keep border radius tight.** Use `rounded-lg` (0.3rem) as the default. The tool should feel precise, not playful.
+- **Respect reduced motion preferences.** All animations collapse to 0.01ms when `prefers-reduced-motion: reduce` is active.
+- **Use Phosphor Icons consistently.** Regular weight, `size-4` (16px) default. Icons should be functional labels, not decorative.
+- **Maintain the three-panel builder proportions.** The center artboard should always dominate. Sidebars are support panels, not equal peers.
+- **Use transparent-white borders in dark mode.** `oklch(1 0 0 / 10%)` blends naturally with any surface rather than introducing a distinct gray band.
+
+### Don't
+
+- **Don't introduce accent colors into the app shell.** No blues, greens, or purples for primary actions. The only chromatic color is destructive red. The inherited indigo sidebar-primary token exists in CSS custom properties but is not actively used.
+- **Don't use drop shadows for elevation.** Rely on background color layering and border separation. The one exception is the resume page preview shadow.
+- **Don't make the UI compete with the resume content.** If a new feature draws more visual attention than the resume preview, it needs to be toned down.
+- **Don't use large border radii.** Nothing above `rounded-xl` on standard components. Large pills and full-round shapes conflict with the precision-tool aesthetic.
+- **Don't hardcode colors outside the token system.** All colors flow through CSS custom properties so that dark/light mode switching works automatically.
+- **Don't use multiple typefaces in the app shell.** IBM Plex Sans Variable is the only UI font. Resume templates have their own font system, but the chrome stays single-family.
+- **Don't skip the `data-slot` attribute on components.** It's used for styling hooks and accessibility selectors throughout the component library.
+- **Don't forget RTL.** The app supports 40+ locales including Arabic, Hebrew, Persian, and Urdu. Use logical properties (`ps`, `pe`, `ms`, `me`) instead of physical (`pl`, `pr`, `ml`, `mr`).

Dockerfile

@@ -1,39 +1,45 @@
-# syntax=docker/dockerfile:1
+# syntax=docker/dockerfile:1.7
 
-# ---------- Dependencies Layer ----------
-FROM node:24-slim AS dependencies
+# Base image only; pnpm self-manages to the `packageManager` version in package.json.
+ARG PNPM_VERSION=11.21.0
+ARG NODE_VERSION=24
 
-ENV PNPM_HOME="/pnpm"
-ENV PATH="$PNPM_HOME:$PATH"
-RUN corepack enable
+FROM ghcr.io/pnpm/pnpm:${PNPM_VERSION} AS base
 
-RUN mkdir -p /tmp/dev /tmp/prod
+ARG NODE_VERSION
 
-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
+RUN pnpm runtime set node ${NODE_VERSION} -g --config.store-dir=/pnpm/runtime-store
 
 WORKDIR /app
 
-COPY --from=dependencies /tmp/dev/node_modules ./node_modules
+ENV TURBO_TELEMETRY_DISABLED=1
+
+FROM base AS pruner
 COPY . .
+RUN --mount=type=cache,id=pnpm-store,target=/pnpm/store,sharing=locked \
+    pnpm dlx turbo@2.9.12 prune web server --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/dist apps/server/dist && pnpm turbo run build --filter=web --filter=server --force
+
+FROM base AS runtime-pruner
+COPY . .
+RUN --mount=type=cache,id=pnpm-store,target=/pnpm/store,sharing=locked \
+    pnpm dlx turbo@2.9.12 prune server --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 install --prod --frozen-lockfile
+
+FROM node:${NODE_VERSION}-slim AS runtime
 
 LABEL maintainer="amruthpillai"
 LABEL org.opencontainers.image.licenses="MIT"
@@ -42,22 +48,30 @@ LABEL org.opencontainers.image.description="A free and open-source resume builde
 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"
+LABEL org.opencontainers.image.source="https://github.com/reactive-resume/reactive-resume"
 
-RUN apt-get update && apt-get install -y --no-install-recommends curl \
-    && rm -rf /var/lib/apt/lists/*
+ENV NODE_ENV="production" \
+    PORT=3000 \
+    LOCAL_STORAGE_PATH=/app/data
 
 WORKDIR /app
 
-ENV NODE_ENV=production
+RUN mkdir -p /app/apps/server /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 /app/node_modules ./node_modules
+COPY --from=pruner --chown=node:node /app/package.json /app/pnpm-lock.yaml /app/pnpm-workspace.yaml ./
+COPY --from=runtime-deps --chown=node:node /app/apps/server/package.json ./apps/server/package.json
+COPY --from=runtime-deps --chown=node:node /app/apps/server/node_modules ./apps/server/node_modules
+COPY --from=builder --chown=node:node /app/apps/web/dist ./apps/web/dist
+COPY --from=builder --chown=node:node /app/apps/server/dist ./apps/server/dist
+COPY --from=pruner --chown=node:node /app/migrations ./migrations
+
+WORKDIR /app
+
+USER node
 
 EXPOSE 3000/tcp
-
 HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
-    CMD curl -f http://localhost:3000/api/health || exit 1
+    CMD ["node", "-e", "fetch(`http://127.0.0.1:${process.env.PORT ?? 3000}/api/health`).then((r) => { if (!r.ok) process.exit(1); }).catch(() => process.exit(1));"]
 
-ENTRYPOINT ["node", ".output/server/index.mjs"]
+CMD ["node", "apps/server/dist/index.mjs"]

Dockerfile.dev

@@ -0,0 +1,43 @@
+# syntax=docker/dockerfile:1.7
+
+ARG PNPM_VERSION=11.21.0
+ARG NODE_VERSION=24
+
+FROM ghcr.io/pnpm/pnpm:${PNPM_VERSION} AS dev
+
+ARG NODE_VERSION
+
+RUN pnpm runtime set node ${NODE_VERSION} -g --config.store-dir=/pnpm/runtime-store
+
+WORKDIR /app
+
+ENV NODE_ENV=development \
+	TURBO_TELEMETRY_DISABLED=1
+
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml turbo.json ./
+COPY patches ./patches
+COPY apps/server/package.json ./apps/server/package.json
+COPY apps/web/package.json ./apps/web/package.json
+COPY packages/ai/package.json ./packages/ai/package.json
+COPY packages/api/package.json ./packages/api/package.json
+COPY packages/auth/package.json ./packages/auth/package.json
+COPY packages/config/package.json ./packages/config/package.json
+COPY packages/db/package.json ./packages/db/package.json
+COPY packages/email/package.json ./packages/email/package.json
+COPY packages/env/package.json ./packages/env/package.json
+COPY packages/fonts/package.json ./packages/fonts/package.json
+COPY packages/import/package.json ./packages/import/package.json
+COPY packages/pdf/package.json ./packages/pdf/package.json
+COPY packages/schema/package.json ./packages/schema/package.json
+COPY packages/ui/package.json ./packages/ui/package.json
+COPY packages/utils/package.json ./packages/utils/package.json
+COPY tooling/package.json ./tooling/package.json
+
+RUN --mount=type=cache,id=reactive-resume-dev-pnpm-store,target=/pnpm/store,sharing=locked \
+	pnpm install --frozen-lockfile
+
+COPY . .
+
+EXPOSE 3000/tcp 3001/tcp
+
+CMD ["pnpm", "run", "dev"]

GLOSSARY.md

@@ -0,0 +1,260 @@
+# Glossary
+
+What the recurring terms in Reactive Resume's interface actually mean.
+
+This file exists because most of the interface is translated from short, standalone strings.
+A translator, human or machine, sees `Board` or `Resume` with no surrounding sentence, picks the
+most common English sense, and gets it wrong. Every entry below has been mistranslated that way
+in at least one shipped locale.
+
+**If you are translating, read the term here before translating it.** When the English word has
+a common sense that is *not* the one used here, that wrong sense is listed explicitly.
+
+Terms are grouped by the part of the product they belong to. Source references point at where the
+string is defined, so you can read the surrounding code when this file is not enough.
+
+## Always left untranslated
+
+Product and technology names stay in English (or in the locale's established transliteration, if
+the catalog already uses one consistently):
+
+Reactive Resume, GitHub, Crowdin, Docker, PostgreSQL, Better Auth, TanStack, Microsoft Word,
+PDF, DOCX, JSON, CSV, API, MCP, oRPC, SSO, CSS, URL, JSON Resume.
+
+AI provider names are brand names and stay in English: OpenAI, Anthropic Claude, Google
+Gemini, Vercel AI Gateway, OpenRouter, Mistral AI, Cohere, xAI Grok, Groq, DeepSeek, Together.ai,
+Fireworks, Cerebras, Perplexity, Ollama Cloud.
+
+Template names are proper nouns and are never translated: Azurill, Bronzor, Chikorita, Ditgar,
+Ditto, Gengar, Glalie, Kakuna, Lapras, Leafish, Meowth, Onyx, Pikachu, Rhyhorn, Scizor.
+
+## The document
+
+**Resume** — the job-application document the app builds. Always a noun.
+Not the verb "to resume", "to continue", or "to restart". This is the single most common
+mistranslation in the catalogs: many locales render the standalone `Resume` label as the verb.
+In `application-form-sheet.tsx` the label marks the resume attached to a job application.
+Where a locale's normal word for this document is CV, use CV.
+
+**Resumes** — plural of the above. A list of the user's documents.
+
+**Cover letter** — the letter accompanying a resume. Stored as a resume section, not a separate
+document.
+
+**Builder** — the editor where a resume is composed. A tool, not a construction worker or a
+person who builds.
+
+**Template** — a visual design for a resume. Not a "model" in the machine-learning sense, and
+not a "sample" or "example" document. Beware in languages where the natural word for template
+is also the word for model: the app uses "model" separately, for AI models.
+
+**Section** — one block of a resume, such as Experience or Education. Not a legal section or a
+document chapter.
+
+**Item** — one entry inside a section, for example a single job or a single degree. Generic on
+purpose. Not "product", "article", or "column".
+
+**Page** — one physical page of the rendered resume. Not a web page.
+
+**Columns** — the column count of a resume layout. Not database or spreadsheet columns.
+
+**Slug** — the URL-safe identifier in a resume's public address. Usually kept in English or
+transliterated; never translated as "snail".
+
+### Resume section names
+
+These are the built-in section presets, defined in `apps/web/src/libs/resume/section.tsx` and
+`apps/web/src/dialogs/resume/sections/custom.tsx`. Translate them the way a resume in the target
+language would label them:
+
+**Basics** — name, contact details, and headline. Not "fundamentals" or "basic settings".
+
+**Summary** — the short personal statement at the top of a resume. Not a summary of the app, and
+not an AI-generated abstract.
+
+**Profiles** — links to the user's social and professional accounts (LinkedIn, GitHub). Plural.
+Distinct from **Profile**, below, which is the user's own account page. These two are different
+things and several catalogs have collapsed them into one word.
+
+**Volunteer** — volunteering experience. A noun naming a section, not the verb "to volunteer".
+
+Also: Experience, Education, Skills, Languages, Awards, Certifications, Interests, Projects,
+Publications, References, Custom.
+
+## The application tracker
+
+**Applications** — job applications the user has submitted. Not software applications, apps, or
+programs. Frequently mistranslated as the software sense.
+
+**Board** — the kanban board view of applications, arranged in columns by stage. Not a board of
+directors, a committee, a plank, or a noticeboard.
+
+**Stage** — where an application sits in the pipeline (applied, interviewing, offer, rejected).
+Not a theatre stage or a phase of construction.
+
+**Source** — where the user found the job listing (a job board, a referral, a company site).
+Singular, and specific to one application. Not a source code file and not a data source.
+
+**Pipeline** — the sequence of stages an application moves through. A recruiting funnel, not a
+physical pipe, duct, conduit, or oil pipeline. Seven locales translated it as plumbing.
+
+**Table** — the table view of applications, one of the view options next to Board and List. Not a
+piece of furniture.
+
+**Archive** — a verb in this context: to move an application out of the active list. Not the
+noun "an archive". It is a menu action and pairs with **Unarchive**; almost every locale had the
+noun here.
+
+**Applied on** — the date the user submitted the application. "Applied" is the job-application
+verb, not "applied a substance onto a surface" and not "applied a patch".
+
+**Mark rejected / Mark as…** — "Mark" is the verb, to set a status. It is not the given name Mark.
+
+**Match score** — how well a resume matches a job description. A degree of correspondence, not a
+sporting fixture.
+
+**Fit**, as in "Score my fit" or "Strong fit" — how well the user suits the role. Not physical
+fitness, and not how clothing fits.
+
+**A stretch** — a role the user is unlikely to get, an ambitious application. Not a stretching
+exercise.
+
+**Notes** — the user's free-text notes on an application. Compare **Note** in the ATS checker,
+which is not the same thing.
+
+**Timeline** — the dated history of one application.
+
+## The AI agent
+
+**Threads** — conversations with the AI agent. The chat sense, as in a message thread. Not
+sewing thread, not string, not yarn, and not a CPU thread. Several locales use the textile word.
+
+**Provider** — a third-party AI service the user configures, such as OpenAI or Anthropic. A
+service supplier. Not a healthcare provider, and not a person who provides for a family.
+
+**Model** — the specific AI model chosen from a provider, such as Claude Sonnet or GPT. Not a
+**Template** (several locales used the same word for both), not a device model or product
+variant, and not a "style" or "pattern".
+
+**Working resume** — the resume a thread is currently editing. "Working" describes the draft
+being worked on, not the user's employment. It is not their work history, not a "job resume",
+and not a *functional résumé*, which is a real and different résumé format.
+
+**Tailor** — a verb: to adapt a resume to a specific job description. Nothing to do with
+dressmaking or sewing.
+
+**Sources** — the citations the agent attaches to an answer. Plural, and distinct from **Source**
+in the application tracker above.
+
+**Draft** — a working copy of a resume the agent edits. A noun.
+
+**Patch** — a set of JSON Patch operations the agent proposes. Kept in English in most catalogs.
+Not a cloth patch, a scrap of fabric, an adhesive bandage, or a connector.
+
+## The ATS checker
+
+**ATS** — applicant tracking system: recruiting software that parses resumes. Spell it out on
+first use in languages where the acronym is unfamiliar. It is not a drug test, a transmission,
+or any other expansion of the letters; at least one catalog translated `ATS Check` as a test for
+amphetamines.
+
+**Readability, Layout, Sections, Contact details, Dates, Writing** — the six check categories, in
+`apps/web/src/features/ats-checker/messages.ts`. "Layout" here means page geometry and reading
+order, not the builder's layout settings.
+
+**Blocker, Warning, Tip** — the three severity levels of a finding.
+
+**Note** — the label for an informational finding, in
+`apps/web/src/routes/builder/$resumeId/-sidebar/right/sections/ats-check.tsx`. A severity label,
+not a written note. Unrelated to **Notes** in the application tracker.
+
+**Parse / parsing** — software reading text out of the PDF.
+
+## Account and security
+
+**Passkey / Passkeys** — a WebAuthn credential that replaces a password, stored on the user's
+device or security key. **It is not a password.** Many catalogs translate it with their word for
+"password", which is actively confusing: both appear together on the security settings page, so
+the user cannot tell which credential a message refers to. If the target language has no
+established term, keep "passkey" in English rather than reusing the word for password.
+
+**Password** — the ordinary secret. Distinct from the above, always.
+
+**Two-factor authentication (2FA)** — a second verification step at sign-in.
+
+**Backup codes** — single-use codes for signing in when the second factor is unavailable.
+
+**API key** — a token for programmatic access. **Key** on its own, in `ai-section.tsx`, means the
+AI provider's API key. Not a physical door key, not a keyboard key, and not the adjective "key"
+in the sense of crucial or main.
+
+**Session** — an active sign-in on one device.
+
+**Sign in / Sign out** — the app's chosen verbs. Prefer the locale's equivalent of "sign in"
+over "log in" where both exist, and keep whichever the catalog already uses consistently.
+
+## Navigation and app shell
+
+**Dashboard** — the main page after signing in, listing resumes and applications. Not a vehicle
+dashboard, an instrument panel, or a control panel in the machinery sense.
+
+**Profile** — the user's own account settings page. Distinct from **Profiles**, the resume
+section, above.
+
+**Lock / Unlock** — verbs: to make a resume read-only, and to release it.
+
+**Tags** — user-defined labels for organizing resumes and applications.
+
+**Custom** — in `color-picker.tsx`, a user-chosen color as opposed to a preset. An adjective.
+
+**Public URL** — the shareable address of a published resume. Use one term consistently; the
+English strings say "public URL" rather than "public link".
+
+## Verbs that read as adjectives or nouns
+
+Button labels and `aria-label` strings are usually **imperative verbs**: they say what the
+control does. Read as a noun or an adjective, they turn into nonsense. This is the most common
+error in the catalogs after the ambiguous nouns above.
+
+**Open** — the verb. `Open AI agent` means *open the AI agent panel*; it does not describe an
+agent that is "open", and it is **not a reference to OpenAI, the company**. Around forty-five of
+the fifty-three catalogs got this wrong, split between "an open AI agent" and a transliteration
+of *OpenAI*. The same applies to `Open in builder`.
+
+**Close** — likewise the verb, as in `Close AI assistant`. Not "an assistant for closing things",
+and not the adjective "close/nearby".
+
+The app names two different surfaces here, and both strings are real: **AI agent** is the
+full workspace at `/agent`, opened from the builder dock (`Open AI agent`), while **AI assistant**
+is the panel that slides out inside the builder (`Open AI assistant`, `Close AI assistant`).
+Translate them as two distinct names, the way the English does.
+
+**Clear** — the verb, to empty a field or remove filters. Not the adjective "transparent",
+"obvious", or "clear-cut".
+
+**Lock / Unlock** — verbs. `Unlock` is specifically the opposite of `Lock`, not a synonym for
+`Open`; several catalogs collapsed the two and produced two identical menu items.
+
+**Archive / Unarchive**, **Mark**, **Tailor**, **Duplicate**, **Import**, **Export**, **Share**,
+**Star** — all verbs when they appear as a control label. Check the `#:` source reference if you
+are unsure whether a given string is a button or a heading.
+
+## Message syntax
+
+These are not words to translate, and breaking them breaks the interface:
+
+- `{name}`, `{count}`, `{email}`, `{MAX_IMPORT}`, `{overflow}` — value placeholders. Keep the
+  spelling exactly, keep every one that appears in the source, and add none.
+- `{count, plural, one {# item} other {# items}}` — ICU plurals. Translate only the text inside
+  the inner braces, keep the `#`, and use the plural categories your language actually needs
+  (Arabic and the Slavic languages legitimately have more than English).
+- `<0>…</0>`, `<1>…</1>`, `<0/>` — indexes pointing at interface elements such as links and bold
+  spans. Keep every index and keep the pairs matched. You may move a tag inside the sentence for
+  word order, as long as it still wraps the corresponding words.
+
+A missing or renamed placeholder is a runtime error, not a style problem.
+
+## Adding to this file
+
+When a translator asks what a term means, the answer belongs here. When you add a term, say what
+it means in this app and, if the English word is ambiguous, say plainly which sense is wrong.

README.md

@@ -1,11 +1,17 @@
+> [!IMPORTANT]
+> **Repository moved:** Reactive Resume now lives at **[`reactive-resume/reactive-resume`](https://github.com/reactive-resume/reactive-resume)** on GitHub.
+> **Docker Hub stays at `amruthpillai/reactive-resume`.** GHCR builds now publish to `ghcr.io/reactive-resume/reactive-resume`.
+> Verified image tags: `latest`, `v5`, `v5.3`, and `v5.3.0` (AMD64 and ARM64). The current version was rebuilt and production redeployed for this rename; no new GitHub release or version bump was made. See [migration details](https://github.com/reactive-resume/reactive-resume/issues/3503).
+> GitHub Sponsors and Open Collective funding links remain unchanged.
+
 <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>
 
-  <p>Reactive Resume is a free and open-source resume builder that simplifies the process of creating, updating, and sharing your resume.</p>
+  <p>Reactive Resume is a free and open-source resume builder that makes it easy to create, update, and share your resume.</p>
 
   <p>
     <a href="https://rxresu.me"><strong>Get Started</strong></a>
@@ -14,39 +20,44 @@
   </p>
 
   <p>
-    <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/github/package-json/v/reactive-resume/reactive-resume?style=flat-square" alt="Reactive Resume Version">
+    <img src="https://img.shields.io/github/stars/reactive-resume/reactive-resume?style=flat-square" alt="GitHub Stars">
+    <img src="https://img.shields.io/github/license/reactive-resume/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/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://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"><img src="https://img.shields.io/opencollective/backers/reactive-resume?style=flat-square&label=donations" alt="Donations" /></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>
+
+  <br />
+  <a href="https://vercel.com/open-source-program">
+    <img alt="Vercel OSS Program" src="https://vercel.com/oss/program-badge-2026.svg" />
+  </a>
 </div>
 
 ---
 
-Reactive Resume makes building resumes straightforward. Pick a template, fill in your details, and export to PDF—no account required for basic use. For those who want more control, the entire application can be self-hosted on your own infrastructure.
+Pick a template, fill in your details, and export to PDF. Basic use needs no account. If you want more control, you can run the whole application on your own infrastructure.
 
-Built with privacy as a core principle, Reactive Resume gives you complete ownership of your data. The codebase is fully open-source under the MIT license, with no tracking, no ads, and no hidden costs.
+You own your data. The codebase is open source under the MIT license, with no tracking, no ads, and no hidden costs.
 
 ## Features
 
 **Resume Building**
 
-- Real-time preview as you type
-- Multiple export formats (PDF, JSON)
+- Live preview as you type
+- Multiple export formats (PDF, JSON, DOCX)
 - Drag-and-drop section ordering
 - Custom sections for any content type
-- Rich text editor with formatting support
+- Rich text editor
 
 **Templates**
 
-- Professionally designed templates
-- A4 and Letter size support
+- 15 templates to choose from
+- A4 and Letter page sizes
 - Customizable colors, fonts, and spacing
-- Custom CSS for advanced styling
+- Structured Style Rules for section and text styling
 
 **Privacy & Control**
 
@@ -61,7 +72,7 @@ Built with privacy as a core principle, Reactive Resume gives you complete owner
 - Multi-language support
 - Share resumes via unique links
 - Import from JSON Resume format
-- Dark mode support
+- Dark mode
 - Passkey and two-factor authentication
 
 ## Templates
@@ -69,63 +80,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>
 
@@ -135,7 +154,7 @@ The quickest way to run Reactive Resume locally:
 
 ```bash
 # Clone the repository
-git clone https://github.com/amruthpillai/reactive-resume.git
+git clone --depth=1  https://github.com/reactive-resume/reactive-resume.git reactive-resume
 cd reactive-resume
 
 # Start all services
@@ -145,44 +164,49 @@ 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 Router (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    | Base UI + shadcn-style package  |
+| State Management | Zustand + TanStack Query        |
 
 ## Documentation
 
-Comprehensive guides are available at [docs.rxresu.me](https://docs.rxresu.me):
+The full documentation lives 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/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       |
+| 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:
+Reactive Resume supports Docker and Vercel Hobby.
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Freactive-resume%2Freactive-resume&project-name=reactive-resume&repository-name=reactive-resume&env=AUTH_SECRET%2CENCRYPTION_SECRET&envDescription=Generate+two+independent+secrets+with+openssl+rand+-hex+32.+Keep+these+values+across+deployments.&envLink=https%3A%2F%2Fdocs.rxresu.me%2Fself-hosting%2Fvercel&stores=%5B%7B%22type%22%3A%22integration%22%2C%22protocol%22%3A%22storage%22%2C%22integrationSlug%22%3A%22neon%22%2C%22productSlug%22%3A%22neon%22%7D%2C%7B%22type%22%3A%22integration%22%2C%22protocol%22%3A%22storage%22%2C%22integrationSlug%22%3A%22upstash%22%2C%22productSlug%22%3A%22upstash-kv%22%7D%2C%7B%22type%22%3A%22blob%22%2C%22access%22%3A%22private%22%7D%5D)
+
+Vercel provisions Neon PostgreSQL, private Blob storage, and Upstash Redis through its deployment wizard. Supply two persistent secrets, then deploy. See the [Vercel guide](docs/self-hosting/vercel.mdx) for setup, limits, and optional SMTP/OAuth configuration.
+
+For Docker, the stack includes:
 
 - **PostgreSQL** — Database for storing user data and resumes
-- **Printer** — Headless Chromium service for PDF and screenshot generation
 - **SeaweedFS** (optional) — S3-compatible storage for file uploads
 
+> **From v5.1.0 onwards** — PDF generation runs entirely client-side via `@react-pdf/renderer`. New deployments no longer need Browserless, Chromium, or any external print service. 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
@@ -190,20 +214,20 @@ Pull the latest image from Docker Hub or GitHub Container Registry:
 docker pull amruthpillai/reactive-resume:latest
 
 # GitHub Container Registry
-docker pull ghcr.io/amruthpillai/reactive-resume:latest
+docker pull ghcr.io/reactive-resume/reactive-resume:latest
 ```
 
 See the [self-hosting guide](https://docs.rxresu.me/self-hosting/docker) for complete instructions.
 
 ## Support
 
-Reactive Resume is and always will be free and open-source. If it has helped you land a job or saved you time, please consider supporting continued development:
+Reactive Resume is and always will be free and open source. If it has helped you land a job or saved you time, please consider supporting continued development:
 
 <p>
   <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>
@@ -211,23 +235,28 @@ Reactive Resume is and always will be free and open-source. If it has helped you
 Other ways to support:
 
 - Star this repository
-- Report bugs and suggest features
+- Report reproducible bugs and suggest actionable features
+- Help other users in [GitHub Discussions](https://github.com/reactive-resume/reactive-resume/discussions/categories/q-a)
 - Improve documentation
 - Help with translations
 
+<a href="https://blacksmith.sh/">
+  <img width="368" height="126" alt="powered-by-blacksmith" src="https://github.com/user-attachments/assets/3e95d11b-4579-4082-8d0c-6b574f925625" />
+</a>
+
 ## Star History
 
-<a href="https://www.star-history.com/#amruthpillai/reactive-resume&type=date&legend=top-left">
+<a href="https://www.star-history.com/?repos=reactive-resume%2Freactive-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" />
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=reactive-resume/reactive-resume&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=reactive-resume/reactive-resume&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=reactive-resume/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.
+Every contribution helps, whether it is a typo fix or a new feature.
 
 1. Fork the repository
 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
@@ -235,7 +264,11 @@ Contributions make open-source thrive. Whether fixing a typo or adding a feature
 4. Push to the branch (`git push origin feature/amazing-feature`)
 5. Open a Pull Request
 
-See the [development setup guide](https://docs.rxresu.me/contributing/development) for detailed instructions on how to set up the project locally.
+See the [development setup guide](https://docs.rxresu.me/contributing/development) for how to run the project locally.
+
+Maintainers review the [`status: needs triage` queue](https://github.com/reactive-resume/reactive-resume/issues?q=is%3Aissue+is%3Aopen+label%3A%22status%3A+needs+triage%22)
+weekly. Triaged bugs become `status: confirmed`; feature proposals become `status: accepted`; reports that need details become
+`status: needs info`.
 
 ## License
 

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.

api/index.mjs

@@ -0,0 +1 @@
+export { default } from "../apps/server/dist/vercel.mjs";

apps/server/package.json

@@ -0,0 +1,106 @@
+{
+	"name": "server",
+	"version": "0.0.0",
+	"type": "module",
+	"private": true,
+	"scripts": {
+		"dev": "tsx watch src/index.ts",
+		"build": "tsdown",
+		"start": "node dist/index.mjs",
+		"docs:gen": "tsx src/openapi/generate-spec.ts",
+		"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"
+	},
+	"imports": {
+		"#react-pdf-renderer": "@react-pdf/renderer"
+	},
+	"dependencies": {
+		"@ai-sdk/anthropic": "^4.0.65",
+		"@ai-sdk/cerebras": "^3.0.57",
+		"@ai-sdk/cohere": "^4.0.50",
+		"@ai-sdk/deepseek": "^3.0.54",
+		"@ai-sdk/fireworks": "^3.0.60",
+		"@ai-sdk/google": "^4.0.82",
+		"@ai-sdk/groq": "^4.0.50",
+		"@ai-sdk/mistral": "^4.0.52",
+		"@ai-sdk/openai": "^4.0.78",
+		"@ai-sdk/openai-compatible": "^3.0.57",
+		"@ai-sdk/perplexity": "^5.0.1",
+		"@ai-sdk/togetherai": "^3.0.58",
+		"@ai-sdk/xai": "^5.0.10",
+		"@aws-sdk/client-s3": "^3.1141.0",
+		"@better-auth/api-key": "^1.7.6",
+		"@better-auth/drizzle-adapter": "^1.7.6",
+		"@better-auth/infra": "^0.4.11",
+		"@better-auth/oauth-provider": "^1.7.6",
+		"@better-auth/passkey": "^1.7.6",
+		"@bramus/specificity": "^2.4.2",
+		"@hono/node-server": "^2.1.1",
+		"@modelcontextprotocol/sdk": "^1.30.1",
+		"@orpc/client": "^1.15.4",
+		"@orpc/experimental-ratelimit": "^1.15.4",
+		"@orpc/json-schema": "^1.15.4",
+		"@orpc/openapi": "^1.15.4",
+		"@orpc/server": "^1.15.4",
+		"@orpc/zod": "^1.15.4",
+		"@react-pdf/hyphenate": "0.1.0",
+		"@react-pdf/renderer": "^4.9.0",
+		"@reactive-resume/api": "workspace:*",
+		"@reactive-resume/auth": "workspace:*",
+		"@reactive-resume/db": "workspace:*",
+		"@reactive-resume/env": "workspace:*",
+		"@reactive-resume/mcp": "workspace:*",
+		"@reactive-resume/schema": "workspace:*",
+		"@reactive-resume/utils": "workspace:*",
+		"@sindresorhus/slugify": "^3.0.1",
+		"@t3-oss/env-core": "^0.13.11",
+		"@uiw/color-convert": "^2.10.3",
+		"@vercel/blob": "^2.8.0",
+		"@vercel/functions": "^3.9.9",
+		"ai": "^7.0.118",
+		"bcrypt": "^6.0.0",
+		"better-auth": "1.7.6",
+		"cjk-regex": "^3.5.0",
+		"css-tree": "^3.2.1",
+		"deepmerge-ts": "^8.0.2",
+		"drizzle-orm": "1.0.0-rc.4",
+		"drizzle-zod": "1.0.0-beta.14-a36c63d",
+		"es-toolkit": "^1.52.0",
+		"fast-json-patch": "^3.1.1",
+		"fast-png": "^8.0.0",
+		"hono": "^4.13.9",
+		"ioredis": "^6.0.0",
+		"jose": "^6.2.12",
+		"jsonrepair": "^3.15.0",
+		"node-html-parser": "^9.0.4",
+		"nodemailer": "^10.0.11",
+		"ollama-ai-provider-v2": "^4.0.1",
+		"pg": "^8.23.0",
+		"phosphor-icons-react-pdf": "^0.1.3",
+		"react": "^19.3.0",
+		"react-email": "^6.11.0",
+		"react-pdf-html": "^2.1.5",
+		"resumable-stream": "^2.2.13",
+		"sanitize-html": "^2.17.7",
+		"sharp": "^0.35.5",
+		"tokenx": "^2.1.0",
+		"ts-pattern": "^5.9.0",
+		"unique-names-generator": "^4.7.1",
+		"uuid": "^14.0.2",
+		"zod": "^4.6.5"
+	},
+	"devDependencies": {
+		"@reactive-resume/config": "workspace:*",
+		"@types/node": "^26.6.3",
+		"@types/pg": "^8.23.1",
+		"@types/react": "^19.3.0",
+		"@typescript/native-preview": "7.0.0-dev.20260707.2",
+		"tsdown": "^0.23.0",
+		"tsx": "^4.23.15",
+		"typescript": "^7.0.2",
+		"vitest": "^5.0.2"
+	}
+}

apps/server/src/app-version.ts

@@ -0,0 +1 @@
+export const appVersion = typeof __APP_VERSION__ === "undefined" ? "0.0.0" : __APP_VERSION__;

apps/server/src/http/app.test.ts

@@ -0,0 +1,221 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+	handleAuth: vi.fn(),
+	handleOAuth: vi.fn(),
+	handleRpc: vi.fn(),
+	handleOpenApi: vi.fn(),
+	handleHealth: vi.fn(),
+	handleUpload: vi.fn(),
+	handleMcp: vi.fn(),
+	handleResumePdfDownload: vi.fn(),
+	handlePublicResumePdf: vi.fn(),
+	handleMcpServerCard: vi.fn(),
+	handleOAuthAuthorizationServer: vi.fn(),
+	handleOAuthProtectedResource: vi.fn(),
+	handleOpenIdConfiguration: vi.fn(),
+	handleWellKnownFallback: vi.fn(),
+	handleRobots: vi.fn(),
+	handleSitemap: vi.fn(),
+	handleLlms: vi.fn(),
+	serveWebDistStatic: vi.fn(),
+	handleWebApp: vi.fn(),
+}));
+
+vi.mock("./auth", () => ({
+	handleAuth: mocks.handleAuth,
+	handleOAuth: mocks.handleOAuth,
+}));
+
+vi.mock("./health", () => ({
+	handleHealth: mocks.handleHealth,
+}));
+
+vi.mock("../rpc/handler", () => ({
+	handleRpc: mocks.handleRpc,
+}));
+
+vi.mock("../openapi/handler", () => ({
+	handleOpenApi: mocks.handleOpenApi,
+}));
+
+vi.mock("../openapi/metadata", () => ({
+	handleMcpServerCard: mocks.handleMcpServerCard,
+	handleOAuthAuthorizationServer: mocks.handleOAuthAuthorizationServer,
+	handleOAuthProtectedResource: mocks.handleOAuthProtectedResource,
+	handleOpenIdConfiguration: mocks.handleOpenIdConfiguration,
+	handleWellKnownFallback: mocks.handleWellKnownFallback,
+}));
+
+vi.mock("../static/uploads", () => ({
+	handleUpload: mocks.handleUpload,
+}));
+
+vi.mock("../static/seo", () => ({
+	handleRobots: mocks.handleRobots,
+	handleSitemap: mocks.handleSitemap,
+	handleLlms: mocks.handleLlms,
+}));
+
+vi.mock("../static/web", () => ({
+	serveWebDistStatic: mocks.serveWebDistStatic,
+	handleWebApp: mocks.handleWebApp,
+}));
+
+vi.mock("../mcp/handler", () => ({
+	handleMcp: mocks.handleMcp,
+}));
+
+vi.mock("./resume-pdf", () => ({
+	handleResumePdfDownload: mocks.handleResumePdfDownload,
+}));
+
+vi.mock("./public-resume-pdf", () => ({
+	handlePublicResumePdf: mocks.handlePublicResumePdf,
+}));
+
+const transportEnv = (remoteAddress: string) =>
+	({
+		incoming: { socket: { remoteAddress } },
+	}) as never;
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	mocks.handleAuth.mockResolvedValue(new Response("auth"));
+	mocks.handleOAuth.mockResolvedValue(new Response("oauth"));
+	mocks.handleRpc.mockResolvedValue(new Response("rpc"));
+	mocks.handleOpenApi.mockResolvedValue(new Response("openapi"));
+	mocks.handleHealth.mockReturnValue(new Response("health"));
+	mocks.handleUpload.mockResolvedValue(new Response("upload"));
+	mocks.handleMcp.mockResolvedValue(new Response("mcp"));
+	mocks.handleResumePdfDownload.mockResolvedValue(new Response("pdf"));
+	mocks.handlePublicResumePdf.mockResolvedValue(new Response("public-pdf"));
+	mocks.handleMcpServerCard.mockReturnValue(new Response("server-card"));
+	mocks.handleOAuthAuthorizationServer.mockReturnValue(new Response("oauth-authorization-server"));
+	mocks.handleOAuthProtectedResource.mockReturnValue(new Response("oauth-protected-resource"));
+	mocks.handleOpenIdConfiguration.mockReturnValue(new Response("openid-configuration"));
+	mocks.handleWellKnownFallback.mockReturnValue(new Response("well-known"));
+	mocks.handleRobots.mockReturnValue(new Response("robots"));
+	mocks.handleSitemap.mockReturnValue(new Response("sitemap"));
+	mocks.handleLlms.mockReturnValue(new Response("llms"));
+	mocks.serveWebDistStatic.mockResolvedValue(undefined);
+	mocks.handleWebApp.mockResolvedValue(new Response("web"));
+});
+
+describe("createApp", () => {
+	it("routes /api/auth/oauth to the OAuth bridge before the Better Auth wildcard", async () => {
+		const { createApp } = await import("./app");
+		const app = createApp();
+		const request = new Request("http://localhost:3001/api/auth/oauth?client_id=test-client");
+
+		const response = await app.fetch(request);
+
+		await expect(response.text()).resolves.toBe("oauth");
+		expect(mocks.handleOAuth).toHaveBeenCalledWith(request);
+		expect(mocks.handleAuth).not.toHaveBeenCalled();
+	});
+
+	it("routes signed resume PDF downloads before the web fallback", async () => {
+		const { createApp } = await import("./app");
+		const app = createApp();
+		const request = new Request("http://localhost:3001/api/resumes/resume-1/pdf?token=signed");
+
+		const response = await app.fetch(request);
+
+		await expect(response.text()).resolves.toBe("pdf");
+		expect(mocks.handleResumePdfDownload).toHaveBeenCalledWith(request, "resume-1");
+		expect(mocks.serveWebDistStatic).not.toHaveBeenCalled();
+		expect(mocks.handleWebApp).not.toHaveBeenCalled();
+	});
+
+	it("uses the transport address for public PDF fallback despite rotated forwarding headers", async () => {
+		const { createApp } = await import("./app");
+		const app = createApp();
+		const first = new Request("http://localhost:3001/api/resumes/jane/resume/pdf", {
+			headers: { "x-forwarded-for": "198.51.100.1" },
+		});
+		const rotated = new Request("http://localhost:3001/api/resumes/jane/resume/pdf", {
+			headers: { "x-forwarded-for": "198.51.100.2" },
+		});
+		const env = transportEnv("203.0.113.9");
+
+		const response = await app.fetch(first, env);
+		await app.fetch(rotated, env);
+
+		await expect(response.text()).resolves.toBe("public-pdf");
+		expect(mocks.handlePublicResumePdf).toHaveBeenNthCalledWith(1, first, "jane", "resume", "203.0.113.9");
+		expect(mocks.handlePublicResumePdf).toHaveBeenNthCalledWith(2, rotated, "jane", "resume", "203.0.113.9");
+		expect(mocks.handleResumePdfDownload).not.toHaveBeenCalled();
+		expect(mocks.serveWebDistStatic).not.toHaveBeenCalled();
+		expect(mocks.handleWebApp).not.toHaveBeenCalled();
+	});
+
+	it("passes the transport address to RPC and OpenAPI and fails closed when it is unavailable", async () => {
+		const { createApp } = await import("./app");
+		const app = createApp();
+		const trustedRpcRequest = new Request("http://localhost:3001/api/rpc", {
+			headers: { "cf-connecting-ip": "198.51.100.1" },
+		});
+		const unknownRpcRequest = new Request("http://localhost:3001/api/rpc", {
+			headers: { "cf-connecting-ip": "198.51.100.2" },
+		});
+		const trustedOpenApiRequest = new Request("http://localhost:3001/api/openapi/resumes/jane/resume");
+		const unknownOpenApiRequest = new Request("http://localhost:3001/api/openapi/resumes/jane/resume");
+
+		await app.fetch(trustedRpcRequest, transportEnv("203.0.113.9"));
+		await app.fetch(unknownRpcRequest);
+		await app.fetch(trustedOpenApiRequest, transportEnv("203.0.113.9"));
+		await app.fetch(unknownOpenApiRequest);
+
+		expect(mocks.handleRpc).toHaveBeenNthCalledWith(1, trustedRpcRequest, "203.0.113.9");
+		expect(mocks.handleRpc).toHaveBeenNthCalledWith(2, unknownRpcRequest, "unknown");
+		expect(mocks.handleOpenApi).toHaveBeenNthCalledWith(1, trustedOpenApiRequest, "203.0.113.9");
+		expect(mocks.handleOpenApi).toHaveBeenNthCalledWith(2, unknownOpenApiRequest, "unknown");
+	});
+
+	it.each([
+		["GET", "/robots.txt", "robots", mocks.handleRobots],
+		["HEAD", "/robots.txt", "", mocks.handleRobots],
+		["GET", "/sitemap.xml", "sitemap", mocks.handleSitemap],
+		["HEAD", "/sitemap.xml", "", mocks.handleSitemap],
+		["GET", "/llms.txt", "llms", mocks.handleLlms],
+		["HEAD", "/llms.txt", "", mocks.handleLlms],
+	])("routes %s %s before the static fallback", async (method, pathname, expectedBody, handler) => {
+		const { createApp } = await import("./app");
+		const app = createApp();
+		const request = new Request(`http://localhost:3001${pathname}`, { method });
+
+		const response = await app.fetch(request);
+
+		await expect(response.text()).resolves.toBe(expectedBody);
+		expect(handler).toHaveBeenCalledWith({ head: method === "HEAD" });
+		expect(mocks.serveWebDistStatic).not.toHaveBeenCalled();
+		expect(mocks.handleWebApp).not.toHaveBeenCalled();
+	});
+
+	it.each(["GET", "HEAD"])("routes %s / to the web app handler so SEO markup is injected", async (method) => {
+		const { createApp } = await import("./app");
+		const app = createApp();
+		const request = new Request("http://localhost:3001/", { method });
+
+		const response = await app.fetch(request);
+
+		expect(response.status).toBe(200);
+		expect(mocks.handleWebApp).toHaveBeenCalledWith(request);
+		expect(mocks.serveWebDistStatic).not.toHaveBeenCalled();
+	});
+});
+
+it.each(["/auth/consent", "/auth/consent/", "/auth/login"])("prevents framing or caching %s", async (path) => {
+	const { createApp } = await import("./app");
+	mocks.serveWebDistStatic.mockImplementationOnce(async (_context: unknown, next: () => Promise<void>) => {
+		await next();
+	});
+	const response = await createApp().request(`http://localhost:3000${path}?sig=signed`);
+	expect(response.status).toBe(200);
+	expect(await response.text()).toBe("web");
+	expect(response.headers.get("content-security-policy")).toBe("frame-ancestors 'none'");
+	expect(response.headers.get("x-frame-options")).toBe("DENY");
+	expect(response.headers.get("referrer-policy")).toBe("no-referrer");
+	expect(response.headers.get("cache-control")).toBe("no-store");
+});

apps/server/src/http/app.ts

@@ -0,0 +1,91 @@
+import type { Http2Bindings, HttpBindings } from "@hono/node-server";
+import type { Context } from "hono";
+import { isIP } from "node:net";
+import { getConnInfo } from "@hono/node-server/conninfo";
+import { Hono } from "hono";
+import { prepareStagedBody, withStagedBody } from "@reactive-resume/api/features/storage/transport";
+import { handleMcp } from "../mcp/handler";
+import { handleOpenApi } from "../openapi/handler";
+import {
+	handleMcpServerCard,
+	handleOAuthAuthorizationServer,
+	handleOAuthProtectedResource,
+	handleOpenIdConfiguration,
+	handleWellKnownFallback,
+} from "../openapi/metadata";
+import { handleRpc } from "../rpc/handler";
+import { handleSchemaJson } from "../static/schema";
+import { handleLlms, handleRobots, handleSitemap } from "../static/seo";
+import { handleUpload } from "../static/uploads";
+import { handleWebApp, serveWebDistStatic } from "../static/web";
+import { handleAuth, handleOAuth } from "./auth";
+import { handleHealth } from "./health";
+import { handlePublicResumePdf } from "./public-resume-pdf";
+import { handleResumePdfDownload } from "./resume-pdf";
+
+type ServerEnvironment = { Bindings: HttpBindings | Http2Bindings };
+
+const getTrustedClient = (context: Context<ServerEnvironment>): string => {
+	try {
+		const address = getConnInfo(context).remote.address?.trim();
+		return address && isIP(address) ? address : "unknown";
+	} catch {
+		return "unknown";
+	}
+};
+
+type AppOptions = {
+	serveStatic?: boolean;
+	trustedClient?: (request: Request) => string;
+};
+
+export function createApp(options: AppOptions = {}) {
+	const app = new Hono<ServerEnvironment>();
+	const client = (c: Context<ServerEnvironment>) => options.trustedClient?.(c.req.raw) ?? getTrustedClient(c);
+
+	app.use("/auth/*", async (c, next) => {
+		await next();
+		c.header("Content-Security-Policy", "frame-ancestors 'none'");
+		c.header("X-Frame-Options", "DENY");
+		c.header("Referrer-Policy", "no-referrer");
+		c.header("Cache-Control", "no-store");
+	});
+
+	app.post("/api/storage/stage", (c) => prepareStagedBody(c.req.raw));
+	app.all("/api/rpc", (c) => withStagedBody(c.req.raw, (request) => handleRpc(request, client(c))));
+	app.all("/api/rpc/*", (c) => withStagedBody(c.req.raw, (request) => handleRpc(request, client(c))));
+	app.all("/api/openapi", (c) => handleOpenApi(c.req.raw, client(c)));
+	app.all("/api/openapi/*", (c) => handleOpenApi(c.req.raw, client(c)));
+	app.get("/api/auth/oauth", (c) => handleOAuth(c.req.raw));
+	app.all("/api/auth/*", (c) => handleAuth(c.req.raw));
+	app.get("/api/health", () => handleHealth());
+	app.get("/api/resumes/:username/:slug/pdf", (c) =>
+		handlePublicResumePdf(c.req.raw, c.req.param("username"), c.req.param("slug"), client(c)),
+	);
+	app.get("/api/resumes/:id/pdf", (c) => handleResumePdfDownload(c.req.raw, c.req.param("id")));
+	app.get("/api/uploads/*", (c) => handleUpload(c.req.raw));
+	app.get("/uploads/*", (c) => handleUpload(c.req.raw));
+	app.get("/schema.json", () => handleSchemaJson());
+	app.all("/mcp", (c) => handleMcp(c.req.raw));
+	app.all("/mcp/*", (c) => handleMcp(c.req.raw));
+
+	app.get("/.well-known/mcp/server-card.json", () => handleMcpServerCard());
+	app.get("/.well-known/oauth-authorization-server", (c) => handleOAuthAuthorizationServer(c.req.raw));
+	app.get("/.well-known/oauth-authorization-server/*", (c) => handleOAuthAuthorizationServer(c.req.raw));
+	app.get("/.well-known/openid-configuration", (c) => handleOpenIdConfiguration(c.req.raw));
+	app.get("/.well-known/oauth-protected-resource", () => handleOAuthProtectedResource());
+	app.get("/.well-known/oauth-protected-resource/*", () => handleOAuthProtectedResource());
+	app.all("/.well-known/*", () => handleWellKnownFallback());
+
+	app.on(["GET", "HEAD"], "/robots.txt", (c) => handleRobots({ head: c.req.method === "HEAD" }));
+	app.on(["GET", "HEAD"], "/sitemap.xml", (c) => handleSitemap({ head: c.req.method === "HEAD" }));
+	app.on(["GET", "HEAD"], "/llms.txt", (c) => handleLlms({ head: c.req.method === "HEAD" }));
+
+	// Must precede the static middleware: serveStatic resolves "/" to dist/index.html and would
+	// return it verbatim, skipping the OpenGraph/Twitter/canonical/JSON-LD injection in handleWebApp.
+	app.on(["GET", "HEAD"], "/", (c) => handleWebApp(c.req.raw));
+	if (options.serveStatic !== false) app.use("/*", serveWebDistStatic);
+	app.on(["GET", "HEAD"], "/*", (c) => handleWebApp(c.req.raw));
+
+	return app;
+}

apps/server/src/http/auth.test.ts

@@ -0,0 +1,260 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+	getSession: vi.fn(),
+	consent: vi.fn(),
+	continueOAuth: vi.fn(),
+	handler: vi.fn(),
+	env: {
+		SERVER_PORT: 3001,
+		APP_URL: "http://localhost:3000",
+		FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI: false,
+	},
+}));
+
+vi.mock("@reactive-resume/auth/config", () => ({
+	auth: {
+		api: {
+			getSession: mocks.getSession,
+			oauth2Consent: mocks.consent,
+			oauth2Continue: mocks.continueOAuth,
+		},
+		handler: mocks.handler,
+	},
+}));
+
+vi.mock("@reactive-resume/db/client", () => ({ db: {} }));
+vi.mock("@reactive-resume/db/schema", () => ({ oauthClient: {}, verification: {} }));
+vi.mock("@reactive-resume/env/server", () => ({
+	env: mocks.env,
+}));
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	mocks.env.FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI = false;
+	mocks.handler.mockResolvedValue(new Response("ok"));
+});
+
+describe("handleAuth", () => {
+	it.for([null, false, 42, "client", [], [{ redirect_uris: [] }]])(
+		"rejects non-object registration payload %j",
+		async (body) => {
+			const { handleAuth } = await import("./auth");
+			const response = await handleAuth(
+				new Request("http://localhost:3000/api/auth/oauth2/register", {
+					method: "POST",
+					headers: { "content-type": "application/json" },
+					body: JSON.stringify(body),
+				}),
+			);
+			expect(response.status).toBe(400);
+			await expect(response.json()).resolves.toEqual({ message: "Invalid registration payload" });
+			expect(mocks.handler).not.toHaveBeenCalled();
+		},
+	);
+
+	it("registers third-party https callbacks so remote MCP clients can complete DCR", async () => {
+		const { handleAuth } = await import("./auth");
+
+		const response = await handleAuth(
+			new Request("http://localhost:3001/api/auth/oauth2/register", {
+				method: "POST",
+				body: JSON.stringify({ redirect_uris: ["https://claude.ai/api/mcp/auth_callback"] }),
+				headers: { "content-type": "application/json" },
+			}),
+		);
+
+		expect(response.status).toBe(200);
+		expect(mocks.handler).toHaveBeenCalledOnce();
+	});
+
+	it("rejects unsafe dynamic OAuth redirect URIs in safe mode", async () => {
+		const { handleAuth } = await import("./auth");
+
+		const response = await handleAuth(
+			new Request("http://localhost:3001/api/auth/oauth2/register", {
+				method: "POST",
+				body: JSON.stringify({ redirect_uris: ["https://192.168.1.10/callback"] }),
+				headers: { "content-type": "application/json" },
+			}),
+		);
+
+		expect(response.status).toBe(400);
+		await expect(response.json()).resolves.toEqual({
+			error: "invalid_redirect_uri",
+			error_description: "redirect_uri is not allowed",
+		});
+		expect(mocks.handler).not.toHaveBeenCalled();
+	});
+
+	it("forwards custom-scheme dynamic OAuth redirect URIs when unsafe mode is enabled", async () => {
+		const { handleAuth } = await import("./auth");
+		mocks.env.FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI = true;
+
+		const response = await handleAuth(
+			new Request("http://localhost:3001/api/auth/oauth2/register", {
+				method: "POST",
+				body: JSON.stringify({ redirect_uris: ["myapp://callback"] }),
+				headers: { "content-type": "application/json" },
+			}),
+		);
+
+		expect(response.status).toBe(200);
+		expect(mocks.handler).toHaveBeenCalledOnce();
+	});
+	it.each(["localhost", "127.0.0.1", "[::1]"])(
+		"infers native application type for exact %s loopback callbacks",
+		async (host) => {
+			const { handleAuth } = await import("./auth");
+			await handleAuth(
+				new Request("http://localhost:3000/api/auth/oauth2/register", {
+					method: "POST",
+					headers: { "content-type": "application/json" },
+					body: JSON.stringify({ redirect_uris: [`http://${host}:3210/callback`] }),
+				}),
+			);
+			const forwarded = mocks.handler.mock.calls[0]?.[0] as Request;
+			await expect(forwarded.json()).resolves.toMatchObject({
+				application_type: "native",
+				token_endpoint_auth_method: "none",
+			});
+		},
+	);
+
+	it.each(["client_secret_basic", "client_secret_post"])(
+		"keeps an explicitly registered %s so the client receives a client secret",
+		async (method) => {
+			const { handleAuth } = await import("./auth");
+			await handleAuth(
+				new Request("http://localhost:3000/api/auth/oauth2/register", {
+					method: "POST",
+					headers: { "content-type": "application/json" },
+					body: JSON.stringify({
+						redirect_uris: ["https://example.com/callback"],
+						token_endpoint_auth_method: method,
+					}),
+				}),
+			);
+			const forwarded = mocks.handler.mock.calls[0]?.[0] as Request;
+			await expect(forwarded.json()).resolves.toMatchObject({ token_endpoint_auth_method: method });
+		},
+	);
+
+	it.each([
+		{ redirect_uris: ["https://example.com/callback"] },
+		{ redirect_uris: ["http://localhost.evil.example/callback"] },
+		{ redirect_uris: ["http://localhost:3210/callback"], application_type: "web" },
+		{ redirect_uris: ["http://localhost:3210/callback", "https://example.com/callback"] },
+	])("does not infer native for explicit web or non-loopback clients: %j", async (body) => {
+		const { handleAuth } = await import("./auth");
+		mocks.env.FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI = true;
+		await handleAuth(
+			new Request("http://localhost:3000/api/auth/oauth2/register", {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify(body),
+			}),
+		);
+		const forwarded = mocks.handler.mock.calls[0]?.[0] as Request;
+		expect((await forwarded.json()).application_type).not.toBe("native");
+	});
+
+	it("preserves repeated resource indicators during authorization sanitization", async () => {
+		const { handleAuth } = await import("./auth");
+		await handleAuth(
+			new Request(
+				"http://localhost:3000/api/auth/oauth2/authorize?resource=http%3A%2F%2Flocalhost%3A3000&resource=http%3A%2F%2Flocalhost%3A3000%2Fmcp",
+			),
+		);
+		const forwarded = mocks.handler.mock.calls[0]?.[0] as Request;
+		expect(new URL(forwarded.url).searchParams.getAll("resource")).toEqual([
+			"http://localhost:3000",
+			"http://localhost:3000/mcp",
+		]);
+	});
+});
+
+describe("handleOAuth", () => {
+	it("redirects unauthenticated users to the same-origin login route", async () => {
+		const { handleOAuth } = await import("./auth");
+		mocks.getSession.mockResolvedValueOnce(null);
+
+		const response = await handleOAuth(
+			new Request(
+				"http://localhost:3001/api/auth/oauth?client_id=test-client&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&state=abc&exp=123&sig=456",
+			),
+		);
+
+		expect(response.status).toBe(302);
+		const location = response.headers.get("Location");
+		expect(location).toMatch(/^\/auth\/login\?/);
+
+		const loginUrl = new URL(location ?? "", "http://localhost:3000");
+		const callbackUrl = new URL(loginUrl.searchParams.get("callbackURL") ?? "", "http://localhost:3000");
+
+		expect(loginUrl.origin).toBe("http://localhost:3000");
+		expect(callbackUrl.pathname).toBe("/api/auth/oauth");
+		expect(callbackUrl.searchParams.get("client_id")).toBe("test-client");
+		expect(callbackUrl.searchParams.get("redirect_uri")).toBe("https://example.com/callback");
+		expect(callbackUrl.searchParams.get("state")).toBe("abc");
+		expect(callbackUrl.searchParams.get("exp")).toBe("123");
+		expect(callbackUrl.searchParams.get("sig")).toBe("456");
+	});
+	it("continues signed authorization without approving consent on GET", async () => {
+		const { handleOAuth } = await import("./auth");
+		mocks.getSession.mockResolvedValueOnce({ user: { id: "owner" } });
+		mocks.continueOAuth.mockResolvedValueOnce(
+			Response.json({ redirect: true, url: "/auth/consent?client_id=client&sig=signed" }),
+		);
+		const query = "client_id=client&resource=one&resource=two&exp=123&sig=456";
+		const response = await handleOAuth(new Request(`http://localhost:3000/api/auth/oauth?${query}`));
+		expect(mocks.continueOAuth).toHaveBeenCalledWith(
+			expect.objectContaining({ body: { postLogin: true, oauth_query: query } }),
+		);
+		expect(mocks.consent).not.toHaveBeenCalled();
+		expect(response.status).toBe(302);
+		expect(response.headers.get("location")).toBe("/auth/consent?client_id=client&sig=signed");
+	});
+
+	it("preserves provider failures instead of issuing an authorization code", async () => {
+		const { handleOAuth } = await import("./auth");
+		mocks.getSession.mockResolvedValueOnce({ user: { id: "owner" } });
+		mocks.continueOAuth.mockResolvedValueOnce(Response.json({ error: "invalid_signature" }, { status: 400 }));
+		const response = await handleOAuth(new Request("http://localhost:3000/api/auth/oauth?sig=invalid"));
+		expect(response.status).toBe(400);
+		expect(response.headers.get("location")).toBeNull();
+		await expect(response.json()).resolves.toEqual({ error: "invalid_signature" });
+	});
+	it("preserves provider cookies and cache headers on forced reauthentication", async () => {
+		const { handleOAuth } = await import("./auth");
+		mocks.getSession.mockResolvedValueOnce({ user: { id: "owner" } });
+		const headers = new Headers({ "cache-control": "no-store", "content-length": "123" });
+		headers.append("set-cookie", "oauth_state=state; Path=/; HttpOnly");
+		headers.append("set-cookie", "session=refreshed; Path=/; HttpOnly");
+		mocks.continueOAuth.mockResolvedValueOnce(
+			Response.json({ redirect: true, url: "/api/auth/oauth?prompt=login&sig=signed" }, { headers }),
+		);
+		const response = await handleOAuth(new Request("http://localhost:3000/api/auth/oauth?sig=original"));
+		expect(response.status).toBe(302);
+		expect(response.headers.get("location")).toMatch(/^\/auth\/login\?reauthenticate=true&/);
+		expect(response.headers.getSetCookie()).toEqual(headers.getSetCookie());
+		expect(response.headers.get("cache-control")).toBe("no-store");
+		expect(response.headers.get("content-type")).toBeNull();
+		expect(response.headers.get("content-length")).toBeNull();
+	});
+});
+
+describe("OAuth provider response validation", () => {
+	it.for([{}, { url: null }, { url: 7 }, { url: "" }, { url: "undefined" }, { url: "javascript:alert(1)" }])(
+		"fails closed for malformed provider response %j",
+		async (body) => {
+			const { handleOAuth } = await import("./auth");
+			mocks.getSession.mockResolvedValueOnce({ user: { id: "owner" } });
+			mocks.continueOAuth.mockResolvedValueOnce(Response.json(body));
+			const response = await handleOAuth(new Request("http://localhost:3000/api/auth/oauth?sig=signed"));
+			expect(response.status).toBe(502);
+			expect(response.headers.get("location")).toBeNull();
+			expect(mocks.consent).not.toHaveBeenCalled();
+		},
+	);
+});

apps/server/src/http/auth.ts

@@ -0,0 +1,211 @@
+import { APIError } from "better-auth/api";
+import { auth } from "@reactive-resume/auth/config";
+import { env } from "@reactive-resume/env/server";
+import { isAllowedOAuthRedirectUri } from "@reactive-resume/utils/url-security.node";
+
+const oauthAuthorizeSanitizedParams = [
+	"prompt",
+	"redirect_uri",
+	"client_id",
+	"code_challenge",
+	"code_challenge_method",
+	"response_type",
+	"scope",
+	"state",
+	"resource",
+] as const;
+
+function sanitizeOAuthAuthorizeRequest(request: Request): Request {
+	if (request.method !== "GET") return request;
+
+	const url = new URL(request.url);
+	if (!url.pathname.endsWith("/oauth2/authorize")) return request;
+
+	const sanitizeValue = (value: string) =>
+		value
+			.replace(/[\r\n\t]+/g, " ")
+			.replace(/\s+/g, " ")
+			.trim();
+	const sanitizeParam = (key: string) => {
+		const values = url.searchParams.getAll(key);
+		if (!values.length) return;
+		url.searchParams.delete(key);
+		for (const value of values) url.searchParams.append(key, sanitizeValue(value));
+	};
+
+	for (const key of oauthAuthorizeSanitizedParams) sanitizeParam(key);
+
+	const redirectUri = url.searchParams.get("redirect_uri");
+	if (redirectUri && !URL.canParse(redirectUri)) {
+		try {
+			const decodedRedirectUri = decodeURIComponent(redirectUri);
+			if (URL.canParse(decodedRedirectUri)) {
+				url.searchParams.set("redirect_uri", decodedRedirectUri);
+			}
+		} catch {
+			// Ignore malformed encoded values and let Better Auth validation handle them.
+		}
+	}
+
+	if (url.toString() === request.url) return request;
+	return new Request(url.toString(), request);
+}
+
+function isRegistrationPayload(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function defaultPublicClientRegistration(request: Request): Promise<Request> {
+	if (request.method !== "POST") return request;
+
+	const url = new URL(request.url);
+	if (!url.pathname.endsWith("/oauth2/register")) return request;
+
+	const cloned = request.clone();
+	let body: Record<string, unknown>;
+
+	try {
+		const payload: unknown = await cloned.json();
+		if (!isRegistrationPayload(payload)) return request;
+		body = payload;
+	} catch {
+		return request;
+	}
+
+	// MCP native clients often omit OIDC application_type. Infer it only for
+	// exact HTTP loopback callbacks; the provider still validates every URI.
+	if (body.application_type === undefined && Array.isArray(body.redirect_uris) && body.redirect_uris.length > 0) {
+		const allLoopback = body.redirect_uris.every(
+			(uri: unknown) =>
+				typeof uri === "string" && /^http:\/\/(?:localhost|127\.0\.0\.1|\[::1\])(?::[0-9]+)?(?:[/?]|$)/i.test(uri),
+		);
+		if (allLoopback) body.application_type = "native";
+	}
+
+	// MCP clients that authenticate with PKCE alone omit the method, and Better Auth
+	// would otherwise register them as `client_secret_basic`. Honor an explicit choice:
+	// forcing it to "none" issues no client secret, so the client's own Basic/post
+	// credentials are rejected at the token endpoint with 401 invalid_client.
+	if (!request.headers.get("authorization")) {
+		body.token_endpoint_auth_method ??= "none";
+	}
+
+	return new Request(url.toString(), {
+		method: request.method,
+		headers: request.headers,
+		body: JSON.stringify(body),
+	});
+}
+
+async function validateDynamicClientRegistrationRequest(request: Request): Promise<Response | undefined> {
+	if (request.method !== "POST") return;
+
+	const url = new URL(request.url);
+	if (!url.pathname.endsWith("/oauth2/register")) return;
+
+	const cloned = request.clone();
+	let body: Record<string, unknown>;
+
+	try {
+		const payload: unknown = await cloned.json();
+		if (!isRegistrationPayload(payload)) {
+			return Response.json({ message: "Invalid registration payload" }, { status: 400 });
+		}
+		body = payload;
+	} catch {
+		return Response.json({ message: "Invalid registration payload" }, { status: 400 });
+	}
+
+	const oauthTrustedOrigins = [new URL(env.APP_URL).origin.toLowerCase()];
+
+	const redirectUris = Array.isArray(body.redirect_uris) ? body.redirect_uris : [];
+	for (const redirectUri of redirectUris) {
+		if (
+			typeof redirectUri !== "string" ||
+			!isAllowedOAuthRedirectUri(redirectUri, oauthTrustedOrigins, {
+				allowUnsafe: env.FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI,
+			})
+		) {
+			return Response.json(
+				{ error: "invalid_redirect_uri", error_description: "redirect_uri is not allowed" },
+				{ status: 400 },
+			);
+		}
+	}
+}
+
+export async function handleAuth(request: Request) {
+	const registrationValidationError = await validateDynamicClientRegistrationRequest(request);
+	if (registrationValidationError) return registrationValidationError;
+
+	const sanitizedRequest = sanitizeOAuthAuthorizeRequest(request);
+	const finalRequest = await defaultPublicClientRegistration(sanitizedRequest);
+
+	return auth.handler(finalRequest);
+}
+
+export async function handleOAuth(request: Request) {
+	try {
+		return await resumeOAuth(request);
+	} catch (error) {
+		// Before-hooks can throw even when the provider is called with asResponse.
+		if (error instanceof APIError) return Response.json(error.body, { status: error.statusCode });
+		throw error;
+	}
+}
+
+async function resumeOAuth(request: Request) {
+	const session = await auth.api.getSession({ headers: request.headers });
+	const url = new URL(request.url);
+
+	if (session?.user) {
+		// Resume authorization without granting consent. The provider decides whether
+		// the user must sign in, explicitly approve a client, or reuse an existing grant.
+		// Its signed query must survive the login round trip byte-for-byte.
+		const response = await auth.api.oauth2Continue({
+			asResponse: true,
+			request,
+			headers: request.headers,
+			body: { postLogin: true, oauth_query: url.search.slice(1) },
+		});
+		if (!(response instanceof Response)) throw new Error("OAuth provider did not return a response");
+		if (!response.ok) return response;
+		const result: unknown = await response.json().catch(() => null);
+		if (
+			!result ||
+			typeof result !== "object" ||
+			!("url" in result) ||
+			typeof result.url !== "string" ||
+			!result.url ||
+			!(result.url.startsWith("/") || URL.canParse(result.url)) ||
+			!URL.canParse(result.url, env.APP_URL)
+		)
+			return Response.json({ error: "invalid_provider_response" }, { status: 502 });
+		const headers = new Headers(response.headers);
+		headers.delete("content-type");
+		headers.delete("content-length");
+		const target = new URL(result.url, env.APP_URL);
+		if (["javascript:", "data:", "vbscript:", "file:", "blob:"].includes(target.protocol)) {
+			return Response.json({ error: "invalid_provider_response" }, { status: 502 });
+		}
+		if (target.origin === new URL(env.APP_URL).origin && target.pathname === "/api/auth/oauth") {
+			return redirectToOAuthLogin(target, true, headers);
+		}
+		headers.set("Location", result.url);
+		return new Response(null, { status: 302, headers });
+	}
+
+	return redirectToOAuthLogin(url);
+}
+
+function redirectToOAuthLogin(url: URL, reauthenticate = false, headers = new Headers()) {
+	const prompt = new Set(url.searchParams.get("prompt")?.split(" ") ?? []);
+	const loginUrl = new URL(prompt.has("create") ? "/auth/register" : "/auth/login", env.APP_URL);
+	if (reauthenticate) loginUrl.searchParams.set("reauthenticate", "true");
+	loginUrl.searchParams.set("callbackURL", `/api/auth/oauth${url.search}`);
+	headers.set("Location", `${loginUrl.pathname}${loginUrl.search}`);
+	return new Response(null, {
+		status: 302,
+		headers,
+	});
+}

apps/server/src/http/headers.ts

@@ -0,0 +1,22 @@
+export function getCookie(request: Request, name: string): string | undefined {
+	const cookieHeader = request.headers.get("cookie");
+	if (!cookieHeader) return;
+
+	for (const part of cookieHeader.split(";")) {
+		const [rawName, ...rawValue] = part.trim().split("=");
+		if (rawName === name && rawValue.length > 0) return rawValue.join("=");
+	}
+}
+
+export function mergeResponseHeaders(response: Response, headers: Headers): Response {
+	if ([...headers].length === 0) return response;
+
+	const nextHeaders = new Headers(response.headers);
+	for (const [key, value] of headers) nextHeaders.append(key, value);
+
+	return new Response(response.body, {
+		status: response.status,
+		statusText: response.statusText,
+		headers: nextHeaders,
+	});
+}

apps/server/src/http/health.test.ts

@@ -0,0 +1,96 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { execute, healthcheck } = vi.hoisted(() => ({ execute: vi.fn(), healthcheck: vi.fn() }));
+
+vi.mock("@reactive-resume/db/client", () => ({ db: { execute } }));
+vi.mock("@reactive-resume/api/features/storage", () => ({ getStorageService: () => ({ healthcheck }) }));
+vi.mock("../app-version", () => ({ appVersion: "9.8.7" }));
+
+import { handleHealth } from "./health";
+
+describe("health version reporting", () => {
+	beforeEach(() => {
+		execute.mockResolvedValue([]);
+		healthcheck.mockResolvedValue({ status: "healthy" });
+	});
+
+	afterEach(() => {
+		vi.unstubAllEnvs();
+		vi.restoreAllMocks();
+	});
+
+	it("reports the built application version when launched directly by Node", async () => {
+		vi.stubEnv("npm_package_version", undefined);
+
+		const response = await handleHealth();
+
+		expect(response.status).toBe(200);
+		expect(await response.json()).toMatchObject({ service: "reactive-resume", version: "9.8.7", status: "healthy" });
+	});
+
+	it("ignores a package manager's workspace package version", async () => {
+		vi.stubEnv("npm_package_version", "0.0.0");
+
+		expect(await (await handleHealth()).json()).toMatchObject({ version: "9.8.7" });
+	});
+
+	it("keeps the version available when a dependency is unhealthy", async () => {
+		vi.stubEnv("npm_package_version", undefined);
+		execute.mockRejectedValueOnce(new Error("Database unavailable"));
+		vi.spyOn(console, "warn").mockImplementation(() => {});
+
+		const response = await handleHealth();
+
+		expect(response.status).toBe(503);
+		expect(await response.json()).toMatchObject({ version: "9.8.7", status: "unhealthy" });
+	});
+	it.each(["database", "storage"])("keeps thrown %s error details in server logs only", async (dependency) => {
+		const detail = "Connection failed for private-user at internal.example:5432";
+		const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+		(dependency === "database" ? execute : healthcheck).mockRejectedValueOnce(new Error(detail));
+
+		const response = await handleHealth();
+		const body = await response.json();
+
+		expect(response.status).toBe(503);
+		expect(JSON.stringify(body)).not.toContain(detail);
+		expect(body[dependency]).toMatchObject({
+			status: "unhealthy",
+			error: expect.stringContaining("health check failed"),
+		});
+		expect(warn).toHaveBeenCalledWith(
+			"[Healthcheck]",
+			expect.objectContaining({
+				[dependency]: expect.objectContaining({ error: detail }),
+			}),
+		);
+	});
+
+	it("redacts returned storage failures while preserving diagnostics in server logs", async () => {
+		const detail = "Access denied to bucket private-bucket on internal.example";
+		const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+		healthcheck.mockResolvedValueOnce({
+			status: "unhealthy",
+			type: "s3",
+			message: detail,
+			error: detail,
+			internalDetail: detail,
+		});
+
+		const response = await handleHealth();
+		const body = await response.json();
+
+		expect(response.status).toBe(503);
+		expect(body.storage).toEqual({
+			status: "unhealthy",
+			type: "s3",
+			latencyMs: expect.any(Number),
+			error: "Storage health check failed.",
+		});
+		expect(JSON.stringify(body)).not.toContain(detail);
+		expect(warn).toHaveBeenCalledWith(
+			"[Healthcheck]",
+			expect.objectContaining({ storage: expect.objectContaining({ error: detail, message: detail }) }),
+		);
+	});
+});

apps/server/src/http/health.ts

@@ -0,0 +1,92 @@
+import { sql } from "drizzle-orm";
+import { withTimeout } from "es-toolkit";
+import { getStorageService } from "@reactive-resume/api/features/storage";
+import { db } from "@reactive-resume/db/client";
+import { getRedis } from "@reactive-resume/db/redis";
+import { appVersion } from "../app-version";
+
+const HEALTHCHECK_TIMEOUT_MS = 1_500;
+
+type CheckResult = {
+	status: "healthy" | "unhealthy";
+	latencyMs: number;
+	error?: string;
+	[key: string]: unknown;
+};
+
+// ponytail: es-toolkit withTimeout takes a fn, not a promise — call site passes check (not check())
+async function runCheck(check: () => Promise<object>): Promise<CheckResult> {
+	const startedAt = performance.now();
+
+	try {
+		const data = await withTimeout(check, HEALTHCHECK_TIMEOUT_MS);
+		const latencyMs = Math.round(performance.now() - startedAt);
+		const result = data as { status?: string };
+		if (result.status === "unhealthy") return { ...(data as object), status: "unhealthy", latencyMs };
+		return { ...(data as object), status: "healthy", latencyMs };
+	} catch (error) {
+		return {
+			status: "unhealthy",
+			error: error instanceof Error ? error.message : "Unknown error",
+			latencyMs: Math.round(performance.now() - startedAt),
+		};
+	}
+}
+
+function publicCheck(check: CheckResult, name: "Database" | "Storage" | "Redis"): CheckResult {
+	if (check.status === "healthy") return check;
+	return {
+		status: check.status,
+		latencyMs: check.latencyMs,
+		error: `${name} health check failed.`,
+		...(check.type === "local" || check.type === "s3" || check.type === "blob" ? { type: check.type } : {}),
+	};
+}
+
+// ponytail: inner try/catches removed; runCheck's outer catch handles all errors
+async function checkDatabase() {
+	await db.execute(sql`SELECT 1`);
+	return { status: "healthy" };
+}
+
+const checkStorage = () => getStorageService().healthcheck();
+
+export async function handleHealth() {
+	const redisClient = getRedis();
+	const [database, storage, redis] = await Promise.all([
+		runCheck(checkDatabase),
+		runCheck(checkStorage),
+		redisClient
+			? runCheck(async () => {
+					await redisClient.ping();
+					return { status: "healthy" };
+				})
+			: undefined,
+	]);
+	const status = [database, storage, redis].some((check) => check?.status === "unhealthy") ? "unhealthy" : "healthy";
+
+	const checks = {
+		service: "reactive-resume",
+		version: appVersion,
+		status,
+		timestamp: new Date().toISOString(),
+		uptime: `${process.uptime().toFixed(2)}s`,
+		database: publicCheck(database, "Database"),
+		storage: publicCheck(storage, "Storage"),
+		...(redis ? { redis: publicCheck(redis, "Redis") } : {}),
+	};
+
+	if (status === "unhealthy") {
+		console.warn("[Healthcheck]", { route: "/api/health", database, storage });
+	}
+
+	const headers = new Headers();
+	const body = JSON.stringify(checks);
+	headers.set("Content-Type", "application/json; charset=UTF-8");
+	headers.set("Content-Length", Buffer.byteLength(body, "utf-8").toString());
+
+	return new Response(body, {
+		headers,
+		status: checks.status === "unhealthy" ? 503 : 200,
+	});
+}

apps/server/src/http/oauth-flow.integration.test.ts

@@ -0,0 +1,337 @@
+import { createHash, randomBytes } from "node:crypto";
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("@reactive-resume/email/transport", () => ({ sendEmail: vi.fn() }));
+
+// Run only against an explicitly supplied disposable database, after applying migrations.
+const databaseURL = process.env.OAUTH_TEST_DATABASE_URL;
+
+describe.skipIf(!databaseURL)("MCP OAuth flow with PostgreSQL", () => {
+	it("registers public clients, resumes login, and exchanges a resource-bound PKCE code", async () => {
+		if (!databaseURL) return;
+		process.env.DATABASE_URL = databaseURL;
+		process.env.APP_URL = "http://localhost:33920";
+		process.env.AUTH_SECRET = "oauth-integration-test-secret-only";
+		const { handleAuth, handleOAuth } = await import("./auth");
+		// Better Auth disables origin checks by default in test mode; exercise production behavior.
+		const { auth } = await import("@reactive-resume/auth/config");
+		(await auth.$context).skipOriginCheck = false;
+		const origin = process.env.APP_URL;
+		const redirectURI = "http://127.0.0.1:33921/callback";
+		const request = (path: string, body: object, cookie = "") =>
+			new Request(`${origin}/api/auth/${path}`, {
+				method: "POST",
+				headers: { "content-type": "application/json", origin, cookie },
+				body: JSON.stringify(body),
+			});
+		const registration = await handleAuth(
+			request("oauth2/register", { client_name: "OAuth integration", redirect_uris: [redirectURI] }),
+		);
+		expect(registration.status, await registration.clone().text()).toBe(201);
+		const client = await registration.json();
+		expect(client.token_endpoint_auth_method).toBe("none");
+
+		const deniedRegistration = await handleAuth(
+			request("oauth2/register", {
+				client_name: "Denied resource",
+				redirect_uris: [redirectURI],
+				resources: ["https://untrusted.example/mcp"],
+			}),
+		);
+		expect(deniedRegistration.status).toBe(400);
+		await expect(deniedRegistration.json()).resolves.toMatchObject({ error: "invalid_target" });
+
+		const verifier = randomBytes(32).toString("base64url");
+		const query = new URLSearchParams({
+			client_id: client.client_id,
+			redirect_uri: redirectURI,
+			response_type: "code",
+			scope: "openid profile offline_access",
+			code_challenge: createHash("sha256").update(verifier).digest("base64url"),
+			code_challenge_method: "S256",
+			resource: `${origin}/mcp`,
+			state: "opaque-state",
+		});
+		const authorize = await handleAuth(new Request(`${origin}/api/auth/oauth2/authorize?${query}`));
+		expect(authorize.status, await authorize.clone().text()).toBe(302);
+		const bridgeURL = authorize.headers.get("location");
+		expect(bridgeURL).toBeTruthy();
+		const login = await handleOAuth(new Request(new URL(bridgeURL ?? "", origin)));
+		const loginURL = new URL(login.headers.get("location") ?? "", origin);
+		const callbackURL = loginURL.searchParams.get("callbackURL");
+		expect(callbackURL).toContain("sig=");
+		expect(callbackURL).toContain("resource=");
+
+		const unique = randomBytes(6).toString("hex");
+		const signup = await handleAuth(
+			request("sign-up/email", {
+				name: "OAuth Test",
+				email: `oauth-${unique}@example.com`,
+				username: `oauth-${unique}`,
+				password: "password123",
+			}),
+		);
+		expect(signup.status, await signup.clone().text()).toBe(200);
+		const cookie = signup.headers
+			.getSetCookie()
+			.map((value) => value.split(";", 1)[0])
+			.join("; ");
+		const tamperedURL = new URL(`${origin}${callbackURL}`);
+		tamperedURL.searchParams.set("state", "tampered");
+		const tampered = await handleOAuth(new Request(tamperedURL, { headers: { cookie } }));
+		expect(tampered.status).toBe(400);
+		await expect(tampered.json()).resolves.toMatchObject({ error: "invalid_signature" });
+		const callback = await handleOAuth(new Request(`${origin}${callbackURL}`, { headers: { cookie } }));
+		expect(callback.status, await callback.clone().text()).toBe(302);
+		const consentURL = new URL(callback.headers.get("location") ?? "", origin);
+		expect(consentURL.pathname).toBe("/auth/consent");
+		expect(consentURL.searchParams.has("code")).toBe(false);
+		const oauth_query = consentURL.search.slice(1);
+		const consents = async () => {
+			const response = await handleAuth(new Request(`${origin}/api/auth/oauth2/get-consents`, { headers: { cookie } }));
+			expect(response.status).toBe(200);
+			return response.json();
+		};
+		expect(await consents()).toEqual([]);
+		const silent = await handleAuth(
+			new Request(`${origin}/api/auth/oauth2/authorize?${query}&prompt=none`, { headers: { cookie } }),
+		);
+		expect(new URL(silent.headers.get("location") ?? "").searchParams.get("error")).toBe("consent_required");
+		const tamperedConsentQuery = new URLSearchParams(oauth_query);
+		tamperedConsentQuery.set("scope", "openid profile email offline_access");
+		const tamperedConsent = await handleAuth(
+			request(
+				"oauth2/consent",
+				{
+					accept: true,
+					oauth_query: tamperedConsentQuery.toString(),
+				},
+				cookie,
+			),
+		);
+		expect(tamperedConsent.status).toBe(400);
+		expect(await consents()).toEqual([]);
+		const csrf = await handleAuth(
+			new Request(`${origin}/api/auth/oauth2/consent`, {
+				method: "POST",
+				headers: { cookie, origin: "https://untrusted.example", "content-type": "application/json" },
+				body: JSON.stringify({ accept: true, oauth_query }),
+			}),
+		);
+		expect(csrf.status).toBe(403);
+		const denied = await handleAuth(request("oauth2/consent", { accept: false, oauth_query }, cookie));
+		expect(denied.status, await denied.clone().text()).toBe(200);
+		const deniedURL = new URL((await denied.json()).url);
+		expect(deniedURL.searchParams.get("error")).toBe("access_denied");
+		expect(deniedURL.searchParams.get("state")).toBe("opaque-state");
+		expect(deniedURL.searchParams.has("code")).toBe(false);
+		expect(await consents()).toEqual([]);
+		const accepted = await handleAuth(request("oauth2/consent", { accept: true, oauth_query }, cookie));
+		expect(accepted.status, await accepted.clone().text()).toBe(200);
+		expect(await consents()).toHaveLength(1);
+		const codeURL = new URL((await accepted.json()).url);
+		expect(codeURL.origin).toBe(new URL(redirectURI).origin);
+		expect(codeURL.searchParams.get("state")).toBe("opaque-state");
+		const code = codeURL.searchParams.get("code");
+		expect(code).toBeTruthy();
+		const tokenRequest = () =>
+			new Request(`${origin}/api/auth/oauth2/token`, {
+				method: "POST",
+				headers: { "content-type": "application/x-www-form-urlencoded" },
+				body: new URLSearchParams({
+					grant_type: "authorization_code",
+					client_id: client.client_id,
+					code: code ?? "",
+					redirect_uri: redirectURI,
+					code_verifier: verifier,
+					resource: `${origin}/mcp`,
+				}),
+			});
+		const tokenResponse = await handleAuth(tokenRequest());
+		expect(tokenResponse.status, await tokenResponse.clone().text()).toBe(200);
+		const token = await tokenResponse.json();
+		expect(token.access_token).toBeTruthy();
+		expect(token.refresh_token).toBeTruthy();
+		const claims = JSON.parse(Buffer.from(token.access_token.split(".")[1], "base64url").toString());
+		expect([claims.aud].flat()).toContain(`${origin}/mcp`);
+		expect((await handleAuth(tokenRequest())).status).toBe(400);
+	}, 30_000);
+	it("exchanges a code for a confidential client that registered client_secret_basic", async () => {
+		if (!databaseURL) return;
+		process.env.DATABASE_URL = databaseURL;
+		process.env.APP_URL = "http://localhost:33920";
+		process.env.AUTH_SECRET = "oauth-integration-test-secret-only";
+		const { handleAuth, handleOAuth } = await import("./auth");
+		const origin = process.env.APP_URL;
+		const redirectURI = "http://127.0.0.1:33921/callback";
+		const request = (path: string, body: object, cookie = "") =>
+			new Request(`${origin}/api/auth/${path}`, {
+				method: "POST",
+				headers: { "content-type": "application/json", origin, cookie },
+				body: JSON.stringify(body),
+			});
+
+		const registration = await handleAuth(
+			request("oauth2/register", {
+				client_name: "Confidential MCP client",
+				redirect_uris: [redirectURI],
+				token_endpoint_auth_method: "client_secret_basic",
+			}),
+		);
+		expect(registration.status, await registration.clone().text()).toBe(201);
+		const client = await registration.json();
+		// Downgrading this to a public client leaves the client without a secret, and its
+		// Basic-authenticated token exchange then fails with 401 invalid_client.
+		expect(client.token_endpoint_auth_method).toBe("client_secret_basic");
+		expect(client.client_secret).toBeTruthy();
+
+		const verifier = randomBytes(32).toString("base64url");
+		const query = new URLSearchParams({
+			client_id: client.client_id,
+			redirect_uri: redirectURI,
+			response_type: "code",
+			scope: "openid profile offline_access",
+			code_challenge: createHash("sha256").update(verifier).digest("base64url"),
+			code_challenge_method: "S256",
+			resource: `${origin}/mcp`,
+			state: "opaque-state",
+		});
+		const authorize = await handleAuth(new Request(`${origin}/api/auth/oauth2/authorize?${query}`));
+		const login = await handleOAuth(new Request(new URL(authorize.headers.get("location") ?? "", origin)));
+		const callbackURL = new URL(login.headers.get("location") ?? "", origin).searchParams.get("callbackURL");
+
+		const unique = randomBytes(6).toString("hex");
+		const signup = await handleAuth(
+			request("sign-up/email", {
+				name: "Confidential Test",
+				email: `confidential-${unique}@example.com`,
+				username: `confidential-${unique}`,
+				password: "password123",
+			}),
+		);
+		expect(signup.status, await signup.clone().text()).toBe(200);
+		const cookie = signup.headers
+			.getSetCookie()
+			.map((value) => value.split(";", 1)[0])
+			.join("; ");
+		const callback = await handleOAuth(new Request(`${origin}${callbackURL}`, { headers: { cookie } }));
+		const oauth_query = new URL(callback.headers.get("location") ?? "", origin).search.slice(1);
+		const accepted = await handleAuth(request("oauth2/consent", { accept: true, oauth_query }, cookie));
+		expect(accepted.status, await accepted.clone().text()).toBe(200);
+		const code = new URL((await accepted.json()).url).searchParams.get("code");
+
+		const tokenResponse = await handleAuth(
+			new Request(`${origin}/api/auth/oauth2/token`, {
+				method: "POST",
+				headers: {
+					"content-type": "application/x-www-form-urlencoded",
+					authorization: `Basic ${Buffer.from(`${client.client_id}:${client.client_secret}`).toString("base64")}`,
+				},
+				body: new URLSearchParams({
+					grant_type: "authorization_code",
+					code: code ?? "",
+					redirect_uri: redirectURI,
+					code_verifier: verifier,
+					resource: `${origin}/mcp`,
+				}),
+			}),
+		);
+		expect(tokenResponse.status, await tokenResponse.clone().text()).toBe(200);
+		await expect(tokenResponse.json()).resolves.toMatchObject({ token_type: "Bearer" });
+	}, 30_000);
+	it.each(["login", "max-age", "create"])(
+		"requires fresh authentication for %s without looping",
+		async (mode) => {
+			if (!databaseURL) return;
+			process.env.DATABASE_URL = databaseURL;
+			process.env.APP_URL = "http://localhost:33920";
+			process.env.AUTH_SECRET = "oauth-integration-test-secret-only";
+			const { handleAuth, handleOAuth } = await import("./auth");
+			const origin = process.env.APP_URL;
+			const cookieOf = (response: Response) =>
+				response.headers
+					.getSetCookie()
+					.map((value) => value.split(";", 1)[0])
+					.join("; ");
+			const post = (path: string, body: object, cookie = "") =>
+				handleAuth(
+					new Request(`${origin}/api/auth/${path}`, {
+						method: "POST",
+						headers: { "content-type": "application/json", origin, cookie },
+						body: JSON.stringify(body),
+					}),
+				);
+			const unique = randomBytes(6).toString("hex");
+			const credentials = {
+				name: "Reauth Test",
+				email: `reauth-${unique}@example.com`,
+				username: `reauth-${unique}`,
+				password: "password123",
+			};
+			const existingSignup = await post("sign-up/email", credentials);
+			expect(existingSignup.status).toBe(200);
+			const oldCookie = cookieOf(existingSignup);
+			const registration = await post("oauth2/register", {
+				client_name: "Reauth integration",
+				redirect_uris: ["http://127.0.0.1:33921/callback"],
+			});
+			expect(registration.status).toBe(201);
+			const client = await registration.json();
+			const query = new URLSearchParams({
+				client_id: client.client_id,
+				redirect_uri: "http://127.0.0.1:33921/callback",
+				response_type: "code",
+				scope: "openid profile",
+				resource: `${origin}/mcp`,
+				code_challenge: createHash("sha256").update(randomBytes(32)).digest("base64url"),
+				code_challenge_method: "S256",
+				...(mode === "max-age" ? { max_age: "0" } : { prompt: mode }),
+			});
+			const authorization = await handleAuth(
+				new Request(`${origin}/api/auth/oauth2/authorize?${query}`, { headers: { cookie: oldCookie } }),
+			);
+			expect(authorization.status).toBe(302);
+			const bridge = await handleOAuth(
+				new Request(new URL(authorization.headers.get("location") ?? "", origin), { headers: { cookie: oldCookie } }),
+			);
+			expect(bridge.status).toBe(302);
+			const loginURL = new URL(bridge.headers.get("location") ?? "", origin);
+			expect(loginURL.pathname).toBe(mode === "create" ? "/auth/register" : "/auth/login");
+			expect(loginURL.searchParams.get("reauthenticate")).toBe("true");
+			const callbackURL = new URL(loginURL.searchParams.get("callbackURL") ?? "", origin);
+			const oauth_query = callbackURL.search.slice(1);
+			const authenticated =
+				mode === "create"
+					? await post(
+							"sign-up/email",
+							{ ...credentials, email: `new-${unique}@example.com`, username: `new-${unique}` },
+							oldCookie,
+						)
+					: await post(
+							"sign-in/email",
+							{ email: credentials.email, password: credentials.password, oauth_query },
+							oldCookie,
+						);
+			expect(authenticated.status, await authenticated.clone().text()).toBe(200);
+			const newCookie = cookieOf(authenticated);
+			expect(newCookie).not.toBe(oldCookie);
+			const continuation =
+				mode === "create" ? await post("oauth2/continue", { created: true, oauth_query }, newCookie) : authenticated;
+			expect(continuation.status, await continuation.clone().text()).toBe(200);
+			const result = await continuation.json();
+			let target = new URL(result.url, origin);
+			if (target.pathname === "/api/auth/oauth") {
+				const response = await handleOAuth(new Request(target, { headers: { cookie: newCookie } }));
+				expect(response.status, await response.clone().text()).toBe(302);
+				target = new URL(response.headers.get("location") ?? "", origin);
+			}
+			expect(target.pathname).toBe("/auth/consent");
+			const accepted = await post("oauth2/consent", { accept: true, oauth_query: target.search.slice(1) }, newCookie);
+			expect(accepted.status, await accepted.clone().text()).toBe(200);
+			target = new URL((await accepted.json()).url, origin);
+			expect(target.origin).toBe("http://127.0.0.1:33921");
+			expect(target.searchParams.get("code")).toBeTruthy();
+		},
+		30_000,
+	);
+});

apps/server/src/http/public-resume-pdf.test.ts

@@ -0,0 +1,79 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+	createPublicResumePdf: vi.fn(),
+}));
+
+vi.mock("@reactive-resume/api/features/resume/public-pdf", () => ({
+	createPublicResumePdf: mocks.createPublicResumePdf,
+}));
+
+const { handlePublicResumePdf } = await import("./public-resume-pdf");
+const trustedClient = "203.0.113.9";
+
+describe("handlePublicResumePdf", () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it("returns the authorized on-demand PDF without forwarding compatibility metadata", async () => {
+		const body = new File(["%PDF"], "Ada_Lovelace.pdf", { type: "text/plain" });
+		mocks.createPublicResumePdf.mockResolvedValueOnce({
+			body,
+			filename: "Ada_Lovelace.pdf",
+		});
+		const request = new Request("https://example.com/api/resumes/jane/resume/pdf?ignored=true", {
+			headers: { "x-forwarded-for": "203.0.113.7" },
+		});
+
+		const response = await handlePublicResumePdf(request, "jane", "resume", trustedClient);
+
+		expect(response.status).toBe(200);
+		expect(response.headers.get("Content-Type")).toBe("application/pdf");
+		expect(response.headers.get("Content-Disposition")).toBe('inline; filename="Ada_Lovelace.pdf"');
+		expect(response.headers.get("Cache-Control")).toBe("private, no-store");
+		expect(response.headers.get("X-Content-Type-Options")).toBe("nosniff");
+		expect(await response.text()).toBe("%PDF");
+		expect(mocks.createPublicResumePdf).toHaveBeenCalledWith({
+			username: "jane",
+			slug: "resume",
+			requestHeaders: request.headers,
+			trustedClient,
+		});
+	});
+
+	it("keeps password and private responses uncacheable", async () => {
+		mocks.createPublicResumePdf.mockResolvedValueOnce({
+			body: new File(["%PDF"], "resume.pdf", { type: "application/pdf" }),
+			filename: "resume.pdf",
+		});
+		const request = new Request("https://example.com/api/resumes/jane/resume/pdf");
+
+		const response = await handlePublicResumePdf(request, "jane", "resume", trustedClient);
+
+		expect(response.headers.get("Cache-Control")).toBe("private, no-store");
+		expect(mocks.createPublicResumePdf).toHaveBeenCalledWith({
+			username: "jane",
+			slug: "resume",
+			requestHeaders: request.headers,
+			trustedClient,
+		});
+	});
+
+	it.each([
+		[{ code: "NEED_PASSWORD" }, 401],
+		[{ code: "NOT_FOUND" }, 404],
+		[{ code: "RATE_LIMIT_EXCEEDED" }, 429],
+		[{ code: "INTERNAL_SERVER_ERROR" }, 500],
+	])("maps controlled API errors without caching the response", async (error, status) => {
+		mocks.createPublicResumePdf.mockRejectedValueOnce(error);
+
+		const response = await handlePublicResumePdf(
+			new Request("https://example.com/api/resumes/jane/resume/pdf"),
+			"jane",
+			"resume",
+			trustedClient,
+		);
+
+		expect(response.status).toBe(status);
+		expect(response.headers.get("Cache-Control")).toBe("private, no-store");
+	});
+});

apps/server/src/http/public-resume-pdf.ts

@@ -0,0 +1,44 @@
+import { createPublicResumePdf } from "@reactive-resume/api/features/resume/public-pdf";
+
+const noStoreResponse = (body: string, status: number) =>
+	new Response(body, { status, headers: { "Cache-Control": "private, no-store" } });
+
+const errorStatus = (error: unknown): number => {
+	const code = typeof error === "object" && error && "code" in error ? (error as { code?: unknown }).code : undefined;
+	if (code === "NEED_PASSWORD") return 401;
+	if (code === "NOT_FOUND") return 404;
+	if (code === "RATE_LIMIT_EXCEEDED") return 429;
+	return 500;
+};
+
+export async function handlePublicResumePdf(
+	request: Request,
+	username: string,
+	slug: string,
+	trustedClient = "unknown",
+): Promise<Response> {
+	try {
+		const result = await createPublicResumePdf({
+			username,
+			slug,
+			requestHeaders: request.headers,
+			trustedClient,
+		});
+
+		return new Response(result.body, {
+			headers: {
+				"Content-Type": "application/pdf",
+				"Content-Disposition": `inline; filename="${result.filename.replaceAll('"', "")}"`,
+				"Cache-Control": "private, no-store",
+				"X-Content-Type-Options": "nosniff",
+			},
+		});
+	} catch (error) {
+		const status = errorStatus(error);
+		if (status === 500) console.error("Public resume PDF generation failed", error);
+		return noStoreResponse(
+			status === 500 ? "Failed to generate public resume PDF" : "Public resume PDF unavailable",
+			status,
+		);
+	}
+}

apps/server/src/http/resume-pdf.test.ts

@@ -0,0 +1,153 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+	createResumePdfDownload: vi.fn(),
+	verifyResumePdfDownloadToken: vi.fn(),
+}));
+
+vi.mock("@reactive-resume/api/features/resume/export", () => ({
+	createResumePdfDownload: mocks.createResumePdfDownload,
+	verifyResumePdfDownloadToken: mocks.verifyResumePdfDownloadToken,
+}));
+
+const { handleResumePdfDownload } = await import("./resume-pdf");
+
+describe("handleResumePdfDownload", () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+	});
+
+	it("renders the PDF when the signed URL token is valid", async () => {
+		const pdf = new File([new Uint8Array([37, 80, 68, 70])], "Scizor.pdf", { type: "application/pdf" });
+		mocks.verifyResumePdfDownloadToken.mockReturnValueOnce({
+			ok: true,
+			resumeId: "resume-1",
+			userId: "user-1",
+			target: "resume",
+			expiresAt: "2026-06-01T10:10:00.000Z",
+		});
+		mocks.createResumePdfDownload.mockResolvedValueOnce({
+			headers: { "content-disposition": 'attachment; filename="Scizor.pdf"' },
+			body: pdf,
+		});
+
+		const response = await handleResumePdfDownload(
+			new Request("https://example.com/api/resumes/resume-1/pdf?token=signed"),
+			"resume-1",
+		);
+
+		expect(response.status).toBe(200);
+		expect(response.headers.get("Content-Type")).toBe("application/pdf");
+		expect(response.headers.get("Content-Disposition")).toBe('attachment; filename="Scizor.pdf"');
+		expect(response.headers.get("Cache-Control")).toBe("private, no-store");
+		expect(await response.text()).toBe("%PDF");
+		expect(mocks.createResumePdfDownload).toHaveBeenCalledWith({ id: "resume-1", userId: "user-1", target: "resume" });
+	});
+
+	it("passes the cover letter target through to PDF rendering", async () => {
+		const pdf = new File([new Uint8Array([37, 80, 68, 70])], "Cover Letter.pdf", { type: "application/pdf" });
+		mocks.verifyResumePdfDownloadToken.mockReturnValueOnce({
+			ok: true,
+			resumeId: "resume-1",
+			userId: "user-1",
+			target: "cover-letter",
+			expiresAt: "2026-06-01T10:10:00.000Z",
+		});
+		mocks.createResumePdfDownload.mockResolvedValueOnce({
+			headers: { "content-disposition": 'attachment; filename="Cover Letter.pdf"' },
+			body: pdf,
+		});
+
+		await handleResumePdfDownload(
+			new Request("https://example.com/api/resumes/resume-1/pdf?token=signed&target=cover-letter"),
+			"resume-1",
+		);
+
+		expect(mocks.createResumePdfDownload).toHaveBeenCalledWith({
+			id: "resume-1",
+			userId: "user-1",
+			target: "cover-letter",
+		});
+	});
+
+	it("defaults a legacy token without a target to resume", async () => {
+		mocks.verifyResumePdfDownloadToken.mockReturnValueOnce({
+			ok: true,
+			resumeId: "resume-1",
+			userId: "user-1",
+			expiresAt: "2026-06-01T10:10:00.000Z",
+		});
+		mocks.createResumePdfDownload.mockResolvedValueOnce({
+			headers: { "content-disposition": 'attachment; filename="Cover Letter.pdf"' },
+			body: new File([], "Cover Letter.pdf", { type: "application/pdf" }),
+		});
+
+		await handleResumePdfDownload(new Request("https://example.com/api/resumes/resume-1/pdf?token=legacy"), "resume-1");
+
+		expect(mocks.createResumePdfDownload).toHaveBeenCalledWith({
+			id: "resume-1",
+			userId: "user-1",
+			target: "resume",
+		});
+	});
+
+	it("rejects a cover-letter target for a legacy token without one", async () => {
+		mocks.verifyResumePdfDownloadToken.mockReturnValueOnce({
+			ok: true,
+			resumeId: "resume-1",
+			userId: "user-1",
+			expiresAt: "2026-06-01T10:10:00.000Z",
+		});
+
+		const response = await handleResumePdfDownload(
+			new Request("https://example.com/api/resumes/resume-1/pdf?token=legacy&target=cover-letter"),
+			"resume-1",
+		);
+
+		expect(response.status).toBe(401);
+		expect(mocks.createResumePdfDownload).not.toHaveBeenCalled();
+	});
+
+	it("rejects a target that differs from the signed token", async () => {
+		mocks.verifyResumePdfDownloadToken.mockReturnValueOnce({
+			ok: true,
+			resumeId: "resume-1",
+			userId: "user-1",
+			target: "resume",
+			expiresAt: "2026-06-01T10:10:00.000Z",
+		});
+
+		const response = await handleResumePdfDownload(
+			new Request("https://example.com/api/resumes/resume-1/pdf?token=signed&target=cover-letter"),
+			"resume-1",
+		);
+
+		expect(response.status).toBe(401);
+		expect(mocks.createResumePdfDownload).not.toHaveBeenCalled();
+	});
+
+	it("rejects missing, invalid, and expired tokens before rendering", async () => {
+		let response = await handleResumePdfDownload(
+			new Request("https://example.com/api/resumes/resume-1/pdf"),
+			"resume-1",
+		);
+		expect(response.status).toBe(401);
+		expect(mocks.createResumePdfDownload).not.toHaveBeenCalled();
+
+		mocks.verifyResumePdfDownloadToken.mockReturnValueOnce({ ok: false, reason: "invalid_signature" });
+		response = await handleResumePdfDownload(
+			new Request("https://example.com/api/resumes/resume-1/pdf?token=bad"),
+			"resume-1",
+		);
+		expect(response.status).toBe(401);
+		expect(mocks.createResumePdfDownload).not.toHaveBeenCalled();
+
+		mocks.verifyResumePdfDownloadToken.mockReturnValueOnce({ ok: false, reason: "expired" });
+		response = await handleResumePdfDownload(
+			new Request("https://example.com/api/resumes/resume-1/pdf?token=expired"),
+			"resume-1",
+		);
+		expect(response.status).toBe(410);
+		expect(mocks.createResumePdfDownload).not.toHaveBeenCalled();
+	});
+});

apps/server/src/http/resume-pdf.ts

@@ -0,0 +1,62 @@
+import { createResumePdfDownload, verifyResumePdfDownloadToken } from "@reactive-resume/api/features/resume/export";
+
+function unauthorizedResponse() {
+	return new Response("Unauthorized", {
+		status: 401,
+		headers: {
+			"Cache-Control": "private, no-store",
+		},
+	});
+}
+
+function expiredResponse() {
+	return new Response("Download link expired", {
+		status: 410,
+		headers: {
+			"Cache-Control": "private, no-store",
+		},
+	});
+}
+
+function errorStatus(error: unknown) {
+	const code = typeof error === "object" && error && "code" in error ? (error as { code?: unknown }).code : undefined;
+	return code === "NOT_FOUND" ? 404 : 500;
+}
+
+export async function handleResumePdfDownload(request: Request, id: string) {
+	const searchParams = new URL(request.url).searchParams;
+	const token = searchParams.get("token");
+	if (!token) return unauthorizedResponse();
+
+	const verification = verifyResumePdfDownloadToken({ resumeId: id, token });
+	if (!verification.ok) return verification.reason === "expired" ? expiredResponse() : unauthorizedResponse();
+	const queryTarget = searchParams.get("target");
+	if (
+		verification.target
+			? queryTarget !== null && queryTarget !== verification.target
+			: queryTarget && queryTarget !== "resume"
+	)
+		return unauthorizedResponse();
+
+	try {
+		const target = verification.target ?? "resume";
+		const download = await createResumePdfDownload({ id, userId: verification.userId, target });
+
+		return new Response(download.body, {
+			headers: {
+				"Content-Type": download.body.type || "application/pdf",
+				"Content-Disposition": download.headers["content-disposition"],
+				"Cache-Control": "private, no-store",
+				"X-Content-Type-Options": "nosniff",
+			},
+		});
+	} catch (error) {
+		console.error("[PDF Download]", error);
+		return new Response("Failed to generate resume PDF", {
+			status: errorStatus(error),
+			headers: {
+				"Cache-Control": "private, no-store",
+			},
+		});
+	}
+}

apps/server/src/index.test.ts

@@ -0,0 +1,41 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const events = vi.hoisted(() => [] as string[]);
+vi.mock("./startup/checks", () => ({
+	runStartupChecks: async () => {
+		await Promise.resolve();
+		events.push("migrations complete");
+	},
+}));
+vi.mock("./http/app", () => {
+	events.push("auth imported");
+	return {
+		createApp: () => {
+			events.push("app created");
+			return { fetch: vi.fn() };
+		},
+	};
+});
+vi.mock("@reactive-resume/auth/config", () => ({
+	initializeAuth: async () => {
+		await Promise.resolve();
+		events.push("auth ready");
+	},
+}));
+vi.mock("@hono/node-server", () => ({
+	serve: () => {
+		events.push("server listening");
+	},
+}));
+vi.mock("@reactive-resume/env/server", () => ({ env: { SERVER_PORT: 3001 } }));
+afterEach(() => vi.restoreAllMocks());
+
+describe("server startup", () => {
+	it("finishes migrations before importing auth and seeding OAuth resources", async () => {
+		vi.spyOn(process, "on").mockReturnValue(process);
+		const entry = await import("./index");
+		expect(events).toEqual([]);
+		await entry.main();
+		expect(events).toEqual(["migrations complete", "auth imported", "auth ready", "app created", "server listening"]);
+	});
+});

apps/server/src/index.ts

@@ -0,0 +1,43 @@
+import { pathToFileURL } from "node:url";
+import { serve } from "@hono/node-server";
+import { env } from "@reactive-resume/env/server";
+import { runStartupChecks } from "./startup/checks";
+
+export async function main() {
+	await runStartupChecks();
+
+	// Load and initialize auth only after migrations have created the provider tables.
+	const { createApp } = await import("./http/app");
+	const { initializeAuth } = await import("@reactive-resume/auth/config");
+	await initializeAuth();
+
+	// Safety net: Node 24 crashes the whole process on an unhandled rejection. One request's
+	// stray promise must not take the server down for everyone, so log and keep serving.
+	// Registered after startup checks so a broken startup still fails loudly. (Left uncaught
+	// exceptions on Node's default crash-and-restart, since process state is unsafe after one.)
+	process.on("unhandledRejection", (reason) => {
+		console.error("[unhandledRejection]", reason);
+	});
+
+	const port =
+		process.env.NODE_ENV === "production" ? Number.parseInt(process.env.PORT ?? "3000", 10) : env.SERVER_PORT;
+
+	const app = createApp();
+
+	serve(
+		{
+			fetch: app.fetch,
+			port,
+		},
+		(info) => {
+			console.info(`🚀 Up and running on http://localhost:${info.port}`);
+		},
+	);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+	main().catch((error) => {
+		console.error(error);
+		process.exit(1);
+	});
+}

apps/server/src/mcp/auth.ts

@@ -0,0 +1,50 @@
+import { auth, verifyOAuthToken } from "@reactive-resume/auth/config";
+
+const OAUTH_WARN_THROTTLE_MS = 60_000;
+let lastOAuthWarnAt = 0;
+
+function warnOAuthThrottled(message: string, detail?: unknown): void {
+	const now = Date.now();
+	if (now - lastOAuthWarnAt < OAUTH_WARN_THROTTLE_MS) return;
+	lastOAuthWarnAt = now;
+
+	if (detail !== undefined) {
+		console.warn(message, detail);
+		return;
+	}
+
+	console.warn(message);
+}
+
+export class AuthError extends Error {
+	constructor() {
+		super("Unauthorized");
+	}
+}
+
+export async function authenticateRequest(request: Request): Promise<void> {
+	const authHeader = request.headers.get("authorization");
+
+	if (authHeader?.startsWith("Bearer ")) {
+		try {
+			const payload = await verifyOAuthToken(authHeader.slice(7));
+			if (payload?.sub) return;
+			warnOAuthThrottled("[MCP] OAuth token verified but missing `sub` claim");
+		} catch (error) {
+			warnOAuthThrottled("[MCP] OAuth token verification failed:", error);
+		}
+	}
+
+	const apiKey = request.headers.get("x-api-key");
+
+	if (apiKey) {
+		try {
+			const result = await auth.api.verifyApiKey({ body: { key: apiKey } });
+			if (result.valid) return;
+		} catch {
+			// Invalid or malformed key; fall through to AuthError.
+		}
+	}
+
+	throw new AuthError();
+}

apps/server/src/mcp/handler.ts

@@ -0,0 +1,42 @@
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { env } from "@reactive-resume/env/server";
+import { AuthError, authenticateRequest } from "./auth";
+import { createMcpServer } from "./server";
+
+export async function handleMcp(request: Request) {
+	try {
+		await authenticateRequest(request);
+
+		const server = createMcpServer(request);
+		const transport = new WebStandardStreamableHTTPServerTransport({
+			enableJsonResponse: true,
+		});
+
+		await server.connect(transport);
+
+		return await transport.handleRequest(request);
+	} catch (error) {
+		if (error instanceof AuthError) {
+			return Response.json(
+				{ id: null, jsonrpc: "2.0", error: { code: -32603, message: "Unauthorized" } },
+				{
+					status: 401,
+					headers: {
+						"WWW-Authenticate": `Bearer resource_metadata="${env.APP_URL}/.well-known/oauth-protected-resource"`,
+					},
+				},
+			);
+		}
+
+		console.error("[MCP]", error);
+
+		return Response.json({
+			id: null,
+			jsonrpc: "2.0",
+			error: {
+				code: -32603,
+				message: `Error handling request: ${error instanceof Error ? error.message : String(error)}`,
+			},
+		});
+	}
+}

apps/server/src/mcp/server.ts

@@ -0,0 +1,52 @@
+import type { RouterClient } from "@orpc/server";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { onError } from "@orpc/client";
+import { createRouterClient } from "@orpc/server";
+import router from "@reactive-resume/api/routers";
+import {
+	buildMcpServerInfo,
+	MCP_TOOL_NAME,
+	registerPrompts,
+	registerResources,
+	registerTools,
+} from "@reactive-resume/mcp";
+import { appVersion } from "../app-version";
+import { getRequestLocale } from "../rpc/locale";
+
+function createRequestClient(request: Request): RouterClient<typeof router> {
+	return createRouterClient(router, {
+		interceptors: [
+			onError((error) => {
+				console.error("[MCP oRPC]", error);
+			}),
+		],
+		context: () => ({
+			locale: getRequestLocale(request),
+			reqHeaders: request.headers,
+			resHeaders: new Headers(),
+		}),
+	});
+}
+
+export function createMcpServer(request: Request) {
+	const server = new McpServer(buildMcpServerInfo(appVersion), {
+		instructions: [
+			"You are connected to Reactive Resume over MCP.",
+			"Authenticate with OAuth (recommended) or an API key (`x-api-key`).",
+			`Discover resume IDs with \`${MCP_TOOL_NAME.listResumes}\` (not \`resources/list\`).`,
+			`List distinct tags with \`${MCP_TOOL_NAME.listResumeTags}\`.`,
+			`Read schema at \`resume://_meta/schema\`; read resume JSON via \`resume://{id}\` or \`${MCP_TOOL_NAME.getResume}\`.`,
+			`Apply body edits with JSON Patch through \`${MCP_TOOL_NAME.patchResume}\`.`,
+			`Change name, slug, tags, or public visibility with \`${MCP_TOOL_NAME.updateResume}\` (returns canonical share URL; anonymous access only when \`isPublic\` is true; passwords are managed in the web app only).`,
+			`Create short-lived authenticated PDF download URLs with \`${MCP_TOOL_NAME.downloadResumePdf}\`; set target to \`cover-letter\` to export a visible cover letter separately.`,
+			`Import full ResumeData JSON with \`${MCP_TOOL_NAME.importResume}\`.`,
+		].join(" "),
+	});
+
+	const client = createRequestClient(request);
+	registerResources(server, client);
+	registerTools(server, client, request.headers);
+	registerPrompts(server);
+
+	return server;
+}

apps/server/src/openapi/generate-spec.ts

@@ -0,0 +1,20 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+async function generateOpenApiDocumentation(
+	target = fileURLToPath(new URL("../../../../docs/spec.json", import.meta.url)),
+) {
+	const packageJson = JSON.parse(await readFile(new URL("../../../../package.json", import.meta.url), "utf8")) as {
+		version: string;
+	};
+	process.env.APP_URL ??= "https://rxresu.me";
+	process.env.DATABASE_URL ??= "postgresql://localhost/reactive_resume_docs";
+	process.env.AUTH_SECRET ??= "documentation-generation-isolated-process-only";
+	const { generateOpenApiSpec } = await import("./generator");
+	const spec = await generateOpenApiSpec({ appUrl: "https://rxresu.me", version: packageJson.version });
+	await writeFile(target, `${JSON.stringify(spec, null, "\t")}\n`);
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+	await generateOpenApiDocumentation(process.argv[2]);
+}

apps/server/src/openapi/generator.test.ts

@@ -0,0 +1,256 @@
+import { readFile } from "node:fs/promises";
+import { describe, expect, it, vi } from "vitest";
+import z from "zod";
+import { defaultResumeData } from "@reactive-resume/schema/resume/default";
+import { createResumeDataJsonSchema } from "@reactive-resume/schema/resume/json-schema";
+import { writableResumeDataSchema } from "@reactive-resume/schema/resume/write";
+
+// Spec generation reads procedure contracts without executing authentication. Keep the
+// provider's resource seeding out of this unit test; real OAuth initialization is covered
+// by the opt-in PostgreSQL integration suite after migrations run.
+vi.mock("@reactive-resume/auth/config", () => ({ auth: {}, verifyOAuthToken: vi.fn() }));
+
+type GeneratedSpecView = {
+	components?: { schemas?: Record<string, unknown> };
+	paths?: Record<
+		string,
+		Record<
+			string,
+			{
+				tags?: string[];
+				operationId?: string;
+				summary?: string;
+				description?: string;
+				responses?: Record<string, { description?: string }>;
+				requestBody?: {
+					content?: Record<string, { schema?: unknown }>;
+				};
+			}
+		>
+	>;
+};
+
+// Building the spec walks every router and resume JSON schema, which costs seconds. It is
+// deterministic and every test here only reads it, so generate it once for the whole file —
+// regenerating per test made the first case time out under a loaded machine.
+let specPromise: ReturnType<typeof generateOnce> | undefined;
+
+async function generateOnce() {
+	const { generateOpenApiSpec } = await import("./generator");
+	return generateOpenApiSpec({
+		appUrl: "https://rxresu.me",
+		version: "9.8.7",
+	});
+}
+
+function generateSpec() {
+	specPromise ??= generateOnce();
+	return specPromise;
+}
+
+function getRequestSchema(spec: GeneratedSpecView, path: string, method: string) {
+	return spec.paths?.[path]?.[method]?.requestBody?.content?.["application/json"]?.schema;
+}
+
+function containsImpossibleSchema(value: unknown): boolean {
+	if (Array.isArray(value)) return value.some(containsImpossibleSchema);
+	if (typeof value !== "object" || value === null) return false;
+	const object = value as Record<string, unknown>;
+	const negated = object.not;
+	if (typeof negated === "object" && negated !== null && Object.keys(negated).length === 0) {
+		return true;
+	}
+	return Object.values(object).some(containsImpossibleSchema);
+}
+
+function findImpossibleRequestSchemas(spec: GeneratedSpecView) {
+	const impossibleRequests: string[] = [];
+	for (const [path, operations] of Object.entries(spec.paths ?? {})) {
+		for (const [method, operation] of Object.entries(operations)) {
+			for (const [mediaType, content] of Object.entries(operation.requestBody?.content ?? {})) {
+				if (containsImpossibleSchema(content.schema)) {
+					impossibleRequests.push(`${method.toUpperCase()} ${path} (${mediaType})`);
+				}
+			}
+		}
+	}
+	return impossibleRequests;
+}
+
+describe("generateOpenApiSpec", () => {
+	it("documents all cover-letter procedures with REST metadata", async () => {
+		const spec = (await generateSpec()) as GeneratedSpecView;
+		const expected = [
+			["get", "/cover-letters", "listCoverLetters", "List cover letters", "200"],
+			["get", "/cover-letters/{id}", "getCoverLetter", "Get cover letter by ID", "200"],
+			["post", "/cover-letters", "createCoverLetter", "Create a cover letter", "200"],
+			["put", "/cover-letters/{id}", "updateCoverLetter", "Update a cover letter", "200"],
+			["post", "/cover-letters/{id}/refresh-style", "refreshCoverLetterStyle", "Refresh cover letter style", "200"],
+			["post", "/cover-letters/{id}/duplicate", "duplicateCoverLetter", "Duplicate a cover letter", "200"],
+			["delete", "/cover-letters/{id}", "deleteCoverLetter", "Delete a cover letter", "200"],
+			["post", "/cover-letters/from-resume", "copyEmbeddedCoverLetter", "Copy an embedded cover letter", "200"],
+			["get", "/cover-letters/{id}/export", "exportCoverLetter", "Export a cover letter", "200"],
+			["post", "/cover-letters/import", "importCoverLetter", "Import a cover letter", "200"],
+		] as const;
+
+		for (const [method, path, operationId, summary, successStatus] of expected) {
+			const operation = spec.paths?.[path]?.[method];
+			expect(operation).toMatchObject({
+				tags: ["Cover Letters"],
+				operationId,
+				summary,
+				description: expect.any(String),
+				responses: { [successStatus]: { description: expect.any(String) } },
+			});
+		}
+	});
+
+	it("keeps published cover-letter operations in sync with the runtime spec", async () => {
+		const published = JSON.parse(
+			await readFile(new URL("../../../../docs/spec.json", import.meta.url), "utf8"),
+		) as GeneratedSpecView;
+		const runtime = await generateSpec();
+		const coverLetterPaths = (spec: GeneratedSpecView) =>
+			Object.fromEntries(
+				Object.entries(spec.paths ?? {}).filter(
+					([path]) => path.startsWith("/cover-letters") || path.startsWith("/coverLetters/"),
+				),
+			);
+
+		const publishedPaths = coverLetterPaths(published);
+		const runtimePaths = coverLetterPaths(runtime as GeneratedSpecView);
+		expect(Object.keys(publishedPaths).sort()).toEqual(Object.keys(runtimePaths).sort());
+		expect(publishedPaths).toEqual(runtimePaths);
+	});
+
+	it("uses caller-provided application URL and version", async () => {
+		const spec = await generateSpec();
+
+		expect(spec.info).toMatchObject({
+			title: "Reactive Resume",
+			version: "9.8.7",
+		});
+		expect(spec.servers).toEqual([{ url: "https://rxresu.me/api/openapi" }]);
+		expect(spec.externalDocs).toEqual({
+			url: "https://docs.rxresu.me",
+			description: "Reactive Resume Documentation",
+		});
+	}, 15_000);
+
+	it("documents the public health endpoint at its actual URL", async () => {
+		const spec = await generateSpec();
+		const health = spec.paths?.["/api/health"]?.get;
+
+		expect(health).toMatchObject({
+			operationId: "getHealth",
+			security: [],
+			servers: [{ url: "https://rxresu.me" }],
+		});
+		for (const status of ["200", "503"]) {
+			expect(health?.responses?.[status]).toMatchObject({
+				content: {
+					"application/json": {
+						schema: {
+							required: expect.arrayContaining(["service", "version", "status"]),
+							properties: { version: { type: "string" } },
+						},
+					},
+				},
+			});
+		}
+	});
+
+	it("uses the canonical input-side ResumeData schema in update requests", async () => {
+		const spec = (await generateSpec()) as GeneratedSpecView;
+		const { $schema: _dialect, ...canonicalInputSchema } = createResumeDataJsonSchema();
+
+		expect(spec.components?.schemas?.ResumeData).toEqual(canonicalInputSchema);
+		expect(getRequestSchema(spec, "/resumes/{id}", "put")).toMatchObject({
+			properties: {
+				data: { $ref: "#/components/schemas/ResumeData" },
+			},
+		});
+	});
+
+	it("accepts legacy input with omitted picture fit in the published request schema", async () => {
+		const spec = (await generateSpec()) as GeneratedSpecView;
+
+		expect(spec.components?.schemas?.ResumeData).toMatchObject({
+			properties: {
+				picture: { required: expect.not.arrayContaining(["fit"]) },
+			},
+		});
+	});
+
+	it("publishes the custom-section type and item correlation", async () => {
+		const spec = (await generateSpec()) as GeneratedSpecView;
+		const schema = z.fromJSONSchema(spec.components?.schemas?.ResumeData as Parameters<typeof z.fromJSONSchema>[0]);
+		const mismatched = {
+			...defaultResumeData,
+			customSections: [
+				{
+					id: "custom-experience",
+					type: "experience",
+					title: "Experience",
+					icon: "",
+					columns: 1,
+					hidden: false,
+					keepTogether: false,
+					startOnNewPage: false,
+					items: [{ id: "summary-item", hidden: false, content: "<p>Not an experience item</p>" }],
+				},
+			],
+		};
+
+		expect(schema.safeParse(mismatched).success).toBe(false);
+	});
+
+	it("enforces the same submitted bounds as the published request schema", async () => {
+		const spec = (await generateSpec()) as GeneratedSpecView;
+		const published = z.fromJSONSchema(spec.components?.schemas?.ResumeData as Parameters<typeof z.fromJSONSchema>[0]);
+		for (const marginX of [0, 100, -1, 500]) {
+			const data = structuredClone(defaultResumeData);
+			data.metadata.page.marginX = marginX;
+			const expected = marginX === 0 || marginX === 100;
+			expect(published.safeParse(data).success).toBe(expected);
+			expect(writableResumeDataSchema.safeParse(data).success).toBe(expected);
+		}
+	});
+
+	it("does not publish impossible request schemas", async () => {
+		const spec = (await generateSpec()) as GeneratedSpecView;
+
+		expect(findImpossibleRequestSchemas(spec)).toEqual([]);
+	});
+
+	it("checks every request body media type for impossible schemas", () => {
+		const spec: GeneratedSpecView = {
+			paths: {
+				"/documents": {
+					post: {
+						requestBody: {
+							content: {
+								"application/json": { schema: { type: "object" } },
+								"multipart/form-data": { schema: { not: {} } },
+							},
+						},
+					},
+				},
+			},
+		};
+
+		expect(findImpossibleRequestSchemas(spec)).toEqual(["POST /documents (multipart/form-data)"]);
+	});
+
+	it("documents imported data as an accepted ResumeData input", async () => {
+		const spec = (await generateSpec()) as GeneratedSpecView;
+
+		expect(getRequestSchema(spec, "/resumes/import", "post")).toEqual({
+			type: "object",
+			properties: {
+				data: { $ref: "#/components/schemas/ResumeData" },
+			},
+			required: ["data"],
+		});
+	});
+});

apps/server/src/openapi/generator.ts

@@ -0,0 +1,130 @@
+import type { OpenAPI } from "@orpc/openapi";
+import { OpenAPIGenerator } from "@orpc/openapi";
+import { JSON_SCHEMA_INPUT_REGISTRY, ZodToJsonSchemaConverter } from "@orpc/zod/zod4";
+import { downloadResumePdfProcedure } from "@reactive-resume/api/features/resume/export";
+import router from "@reactive-resume/api/routers";
+import { resumeDataSchema } from "@reactive-resume/schema/resume/data";
+import { createResumeDataJsonSchema } from "@reactive-resume/schema/resume/json-schema";
+import { writableResumeDataSchema } from "@reactive-resume/schema/resume/write";
+
+export const openAPIRouter = {
+	...router,
+	resume: {
+		...router.resume,
+		downloadPdf: downloadResumePdfProcedure,
+	},
+};
+
+const { $schema: _dialect, ...resumeDataInputSchema } = createResumeDataJsonSchema();
+type ResumeDataInputJsonSchema = Parameters<typeof JSON_SCHEMA_INPUT_REGISTRY.add<typeof resumeDataSchema>>[1];
+JSON_SCHEMA_INPUT_REGISTRY.add(resumeDataSchema, resumeDataInputSchema as unknown as ResumeDataInputJsonSchema);
+JSON_SCHEMA_INPUT_REGISTRY.add(writableResumeDataSchema, resumeDataInputSchema as unknown as ResumeDataInputJsonSchema);
+const importResumeInputSchema = openAPIRouter.resume.import["~orpc"].inputSchema;
+if (importResumeInputSchema) {
+	JSON_SCHEMA_INPUT_REGISTRY.add(importResumeInputSchema, {
+		type: "object",
+		properties: {
+			data: { $ref: "#/components/schemas/ResumeData" },
+		},
+		required: ["data"],
+	});
+}
+
+const openAPIGenerator = new OpenAPIGenerator({
+	schemaConverters: [
+		new ZodToJsonSchemaConverter({
+			interceptors: [
+				({ options, next }) => {
+					const [required, schema] = next();
+					const impossible =
+						Object.keys(schema).length === 1 &&
+						typeof schema.not === "object" &&
+						schema.not !== null &&
+						Object.keys(schema.not).length === 0;
+					return options.strategy === "input" && impossible ? [required, {}] : [required, schema];
+				},
+			],
+		}),
+	],
+});
+
+type GenerateOpenApiSpecOptions = {
+	appUrl: string;
+	version: string;
+};
+
+const healthDependencySchema = {
+	type: "object",
+	properties: {
+		status: { type: "string", enum: ["healthy", "unhealthy"] },
+		latencyMs: { type: "number" },
+		error: { type: "string", description: "Generic failure message. Detailed diagnostics are logged on the server." },
+	},
+	required: ["status", "latencyMs"],
+	additionalProperties: true,
+} satisfies OpenAPI.SchemaObject;
+
+const healthResponseSchema = {
+	type: "object",
+	properties: {
+		service: { type: "string", enum: ["reactive-resume"] },
+		version: { type: "string", description: "The running application's build version." },
+		status: { type: "string", enum: ["healthy", "unhealthy"] },
+		timestamp: { type: "string", format: "date-time" },
+		uptime: { type: "string" },
+		database: healthDependencySchema,
+		storage: healthDependencySchema,
+	},
+	required: ["service", "version", "status", "timestamp", "uptime", "database", "storage"],
+} satisfies OpenAPI.SchemaObject;
+
+export async function generateOpenApiSpec({ appUrl, version }: GenerateOpenApiSpecOptions) {
+	return await openAPIGenerator.generate(openAPIRouter, {
+		info: {
+			title: "Reactive Resume",
+			version,
+			description: "Reactive Resume API",
+			license: { name: "MIT", url: "https://github.com/reactive-resume/reactive-resume/blob/main/LICENSE" },
+			contact: { name: "Amruth Pillai", email: "hello@amruthpillai.com", url: "https://amruthpillai.com" },
+		},
+		servers: [{ url: `${appUrl}/api/openapi` }],
+		paths: {
+			"/api/health": {
+				get: {
+					operationId: "getHealth",
+					tags: ["System"],
+					summary: "Get application health and version",
+					description: "Checks database and storage availability. Does not require authentication.",
+					servers: [{ url: appUrl }],
+					security: [],
+					responses: {
+						"200": {
+							description: "The application and its dependencies are healthy.",
+							content: { "application/json": { schema: healthResponseSchema } },
+						},
+						"503": {
+							description: "One or more application dependencies are unhealthy.",
+							content: { "application/json": { schema: healthResponseSchema } },
+						},
+					},
+				},
+			},
+		},
+		externalDocs: { url: "https://docs.rxresu.me", description: "Reactive Resume Documentation" },
+		commonSchemas: {
+			ResumeData: { schema: writableResumeDataSchema, strategy: "input" },
+		},
+		components: {
+			securitySchemes: {
+				apiKey: {
+					type: "apiKey",
+					name: "x-api-key",
+					in: "header",
+					description: "The API key to authenticate requests.",
+				},
+			},
+		},
+		security: [{ apiKey: [] }],
+		filter: ({ contract }) => !contract["~orpc"].route.tags?.includes("Internal"),
+	});
+}

apps/server/src/openapi/handler.ts

@@ -0,0 +1,41 @@
+import { SmartCoercionPlugin } from "@orpc/json-schema";
+import { OpenAPIHandler } from "@orpc/openapi/fetch";
+import { onError } from "@orpc/server";
+import { BatchHandlerPlugin, RequestHeadersPlugin, StrictGetMethodPlugin } from "@orpc/server/plugins";
+import { ZodToJsonSchemaConverter } from "@orpc/zod/zod4";
+import { env } from "@reactive-resume/env/server";
+import { appVersion } from "../app-version";
+import { mergeResponseHeaders } from "../http/headers";
+import { getRequestLocale } from "../rpc/locale";
+import { generateOpenApiSpec, openAPIRouter } from "./generator";
+
+const openAPIHandler = new OpenAPIHandler(openAPIRouter, {
+	plugins: [
+		new BatchHandlerPlugin(),
+		new RequestHeadersPlugin(),
+		new StrictGetMethodPlugin(),
+		new SmartCoercionPlugin({
+			schemaConverters: [new ZodToJsonSchemaConverter()],
+		}),
+	],
+	interceptors: [
+		onError((error) => {
+			console.error("[OpenAPI]", error);
+		}),
+	],
+});
+
+export async function handleOpenApi(request: Request, trustedClient = "unknown") {
+	if (request.method === "GET" && (request.url.endsWith("/spec.json") || request.url.endsWith("/spec"))) {
+		return Response.json(await generateOpenApiSpec({ appUrl: env.APP_URL, version: appVersion }));
+	}
+
+	const resHeaders = new Headers();
+	const { response } = await openAPIHandler.handle(request, {
+		prefix: "/api/openapi",
+		context: { locale: getRequestLocale(request), reqHeaders: request.headers, resHeaders, trustedClient },
+	});
+
+	if (!response) return new Response("NOT_FOUND", { status: 404 });
+	return mergeResponseHeaders(response, resHeaders);
+}

apps/server/src/openapi/metadata.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+	auth: {},
+	env: {
+		APP_URL: "https://rxresu.me",
+	},
+}));
+
+vi.mock("@better-auth/oauth-provider", () => ({
+	oauthProviderAuthServerMetadata: vi.fn(() => vi.fn(() => Response.json({}))),
+	oauthProviderOpenIdConfigMetadata: vi.fn(() => vi.fn(() => Response.json({}))),
+}));
+
+vi.mock("@reactive-resume/auth/config", () => ({
+	auth: mocks.auth,
+}));
+
+vi.mock("@reactive-resume/env/server", () => ({
+	env: mocks.env,
+}));
+
+vi.mock("@reactive-resume/mcp/server-card", () => ({
+	buildMcpServerCard: vi.fn(() => ({})),
+}));
+
+vi.mock("../app-version", () => ({
+	appVersion: "test",
+}));
+
+describe("handleOAuthProtectedResource", () => {
+	it("advertises the mounted auth issuer as the authorization server", async () => {
+		const { handleOAuthProtectedResource } = await import("./metadata");
+
+		const response = await handleOAuthProtectedResource();
+
+		await expect(response.json()).resolves.toMatchObject({
+			resource: "https://rxresu.me",
+			authorization_servers: ["https://rxresu.me/api/auth"],
+		});
+	});
+});

apps/server/src/openapi/metadata.ts

@@ -0,0 +1,36 @@
+import { oauthProviderAuthServerMetadata, oauthProviderOpenIdConfigMetadata } from "@better-auth/oauth-provider";
+import { auth } from "@reactive-resume/auth/config";
+import { env } from "@reactive-resume/env/server";
+import { buildMcpServerCard } from "@reactive-resume/mcp/server-card";
+import { appVersion } from "../app-version";
+
+export const handleOAuthAuthorizationServer = oauthProviderAuthServerMetadata(auth);
+export const handleOpenIdConfiguration = oauthProviderOpenIdConfigMetadata(auth);
+
+export function handleWellKnownFallback() {
+	return new Response("OK", { status: 200 });
+}
+
+export function handleMcpServerCard() {
+	return Response.json(buildMcpServerCard(appVersion), {
+		headers: {
+			"Content-Type": "application/json",
+			"Cache-Control": "public, max-age=60, stale-while-revalidate=120",
+		},
+	});
+}
+
+export function handleOAuthProtectedResource() {
+	const metadata = {
+		resource: env.APP_URL,
+		bearer_methods_supported: ["header"],
+		authorization_servers: [`${env.APP_URL}/api/auth`],
+	};
+
+	return Response.json(metadata, {
+		headers: {
+			"Content-Type": "application/json",
+			"Cache-Control": "public, max-age=15, stale-while-revalidate=15, stale-if-error=86400",
+		},
+	});
+}

apps/server/src/prepare-deployment.ts

@@ -0,0 +1,20 @@
+import { initializeAuth } from "@reactive-resume/auth/config";
+import { getPool } from "@reactive-resume/db/client";
+import { env } from "@reactive-resume/env/server";
+import { runDatabaseMigrations } from "./startup/checks";
+
+if (process.env.VERCEL_ENV === "preview" && process.env.ALLOW_PREVIEW_MIGRATIONS !== "true") {
+	throw new Error(
+		"Preview deployment needs an isolated database. Set ALLOW_PREVIEW_MIGRATIONS=true only after connecting one.",
+	);
+}
+
+if (process.env.VERCEL === "1") {
+	if (env.STORAGE_BACKEND !== "blob")
+		throw new Error("Vercel requires private Blob storage for direct uploads. Docker supports local, S3, and Blob.");
+	if (!env.REDIS_URL || !env.ENCRYPTION_SECRET) throw new Error("Vercel requires Redis and ENCRYPTION_SECRET.");
+}
+await runDatabaseMigrations();
+
+await initializeAuth();
+await getPool().end();

apps/server/src/rpc/handler.ts

@@ -1,38 +1,31 @@
 import { onError } from "@orpc/server";
 import { RPCHandler } from "@orpc/server/fetch";
 import { BatchHandlerPlugin, RequestHeadersPlugin, StrictGetMethodPlugin } from "@orpc/server/plugins";
-import { createFileRoute } from "@tanstack/react-router";
-import router from "@/integrations/orpc/router";
-import { getLocale } from "@/utils/locale";
-import { logger } from "@/utils/logger";
+import router from "@reactive-resume/api/routers";
+import { mergeResponseHeaders } from "../http/headers";
+import { getRequestLocale } from "./locale";
 
 const rpcHandler = new RPCHandler(router, {
 	plugins: [new BatchHandlerPlugin(), new RequestHeadersPlugin(), new StrictGetMethodPlugin()],
 	interceptors: [
 		onError((error) => {
-			logger.error("oRPC server error", {
-				route: "/api/rpc",
-				error,
-			});
+			console.error("[oRPC Server]", error);
 		}),
 	],
 });
 
-async function handler({ request }: { request: Request }) {
+export async function handleRpc(request: Request, trustedClient = "unknown") {
+	const resHeaders = new Headers();
 	const { response } = await rpcHandler.handle(request, {
 		prefix: "/api/rpc",
-		context: { locale: await getLocale() },
+		context: {
+			locale: getRequestLocale(request),
+			reqHeaders: request.headers,
+			resHeaders,
+			trustedClient,
+		},
 	});
 
 	if (!response) return new Response("NOT_FOUND", { status: 404 });
-
-	return response;
+	return mergeResponseHeaders(response, resHeaders);
 }
-
-export const Route = createFileRoute("/api/rpc/$")({
-	server: {
-		handlers: {
-			ANY: handler,
-		},
-	},
-});

apps/server/src/rpc/locale.ts

@@ -0,0 +1,8 @@
+import type { Locale } from "@reactive-resume/utils/locale";
+import { defaultLocale, isLocale } from "@reactive-resume/utils/locale";
+import { getCookie } from "../http/headers";
+
+export function getRequestLocale(request: Request): Locale {
+	const locale = getCookie(request, "locale");
+	return isLocale(locale) ? locale : defaultLocale;
+}

apps/server/src/startup/checks.ts

@@ -0,0 +1,108 @@
+import { constants, existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { migrate } from "drizzle-orm/node-postgres/migrator";
+import { Pool } from "pg";
+import { env } from "@reactive-resume/env/server";
+import { getLocalDataDirectory } from "@reactive-resume/utils/monorepo.node";
+import { verifyMigratedSchema } from "./schema-check";
+
+function resolveFromCurrentModule(relativePath: string) {
+	return fileURLToPath(new URL(relativePath, import.meta.url));
+}
+
+function resolveWorkspaceFolder(folderName: string): string {
+	let dir = resolveFromCurrentModule(".");
+
+	while (dir !== path.dirname(dir)) {
+		const candidate = path.join(dir, folderName);
+		if (existsSync(candidate)) return candidate;
+		dir = path.dirname(dir);
+	}
+
+	throw new Error(`Could not locate ${folderName} folder relative to ${resolveFromCurrentModule(".")}`);
+}
+
+export async function runDatabaseMigrations() {
+	console.info("Running database migrations...");
+
+	const pool = new Pool({
+		connectionString: env.DATABASE_MIGRATION_URL ?? env.DATABASE_URL,
+		max: 1,
+		connectionTimeoutMillis: 10_000,
+	});
+
+	try {
+		const client = await pool.connect();
+		try {
+			await client.query("SELECT pg_advisory_lock(721830451)");
+			const db = drizzle({ client });
+			try {
+				await migrate(db, { migrationsFolder: resolveWorkspaceFolder("migrations") });
+				console.info("Database migrations completed");
+			} catch (error) {
+				console.error("Database migrations failed", { error });
+				throw error;
+			}
+
+			// Post-migration verification is not a migration failure, so it gets its own log
+			// message. A drifted schema still lets the server boot; STRICT_SCHEMA_CHECK=true
+			// makes the drift fatal instead.
+			try {
+				await verifyMigratedSchema(client);
+			} catch (error) {
+				console.error("Database schema verification failed", { error });
+				if (env.STRICT_SCHEMA_CHECK) throw error;
+				console.error(
+					"Continuing with a drifted database schema; set STRICT_SCHEMA_CHECK=true to refuse startup instead.",
+				);
+			}
+		} finally {
+			try {
+				await client.query("SELECT pg_advisory_unlock(721830451)");
+			} finally {
+				client.release();
+			}
+		}
+	} finally {
+		await pool.end();
+	}
+}
+
+async function validateLocalStoragePath() {
+	if (env.STORAGE_BACKEND !== "local") 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, constants.R_OK | 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;
+	}
+}
+
+async function reapStaleAgentRuns() {
+	try {
+		const { reapStaleAgentRunsAtBoot } = await import("@reactive-resume/api/features/agent/runs");
+		await reapStaleAgentRunsAtBoot();
+	} catch (error) {
+		// A reap failure must not block serving traffic; stuck runs also heal lazily on access.
+		console.error("Failed to reap stale agent runs at boot", { error });
+	}
+}
+
+export async function runStartupChecks() {
+	await runDatabaseMigrations();
+	await validateLocalStoragePath();
+	await reapStaleAgentRuns();
+}

apps/server/src/startup/schema-check.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { collectExpectedColumns, verifyMigratedSchema } from "./schema-check";
+
+describe("collectExpectedColumns", () => {
+	it("collects every column of every schema table", () => {
+		const expected = collectExpectedColumns();
+		expect(expected.length).toBeGreaterThan(0);
+		expect(expected).toContainEqual({ tableName: "ai_providers", columnName: "user_id" });
+		expect(expected).toContainEqual({ tableName: "user", columnName: "id" });
+	});
+});
+
+describe("verifyMigratedSchema", () => {
+	it("passes when the catalog reports nothing missing", async () => {
+		const queryable = { query: async () => ({ rows: [] }) };
+		await expect(verifyMigratedSchema(queryable)).resolves.toBeUndefined();
+	});
+
+	it("fails with the table name when every column of a table is missing", async () => {
+		const rows = collectExpectedColumns()
+			.filter((e) => e.tableName === "ai_providers")
+			.map((e) => ({ table_name: e.tableName, column_name: e.columnName }));
+
+		const queryable = { query: async () => ({ rows }) };
+		await expect(verifyMigratedSchema(queryable)).rejects.toThrow('table "ai_providers"');
+	});
+
+	it("fails with the qualified column name when only some columns are missing", async () => {
+		const queryable = { query: async () => ({ rows: [{ table_name: "user", column_name: "role" }] }) };
+		await expect(verifyMigratedSchema(queryable)).rejects.toThrow('"user"."role"');
+	});
+
+	it("passes the expected table and column lists to the catalog query", async () => {
+		let captured: unknown[] | undefined;
+		const queryable = {
+			query: (_text: string, values?: unknown[]) => {
+				captured = values;
+				return Promise.resolve({ rows: [] });
+			},
+		};
+
+		await verifyMigratedSchema(queryable);
+
+		const [tables, columns] = captured as [string[], string[]];
+		// The query relies on $1/$2 being index-aligned, so each table name must pair
+		// with its own column name at the same index.
+		const pairs = tables.map((table, index) => `${table}.${columns[index]}`);
+		expect(pairs).toContain("ai_providers.user_id");
+	});
+});

apps/server/src/startup/schema-check.ts

@@ -0,0 +1,71 @@
+import { is } from "drizzle-orm";
+import { getTableConfig, PgTable } from "drizzle-orm/pg-core";
+import * as schema from "@reactive-resume/db/schema";
+
+interface SchemaQueryable {
+	query(text: string, values?: unknown[]): Promise<{ rows: { table_name: string; column_name: string }[] }>;
+}
+
+export function collectExpectedColumns() {
+	const expected: { tableName: string; columnName: string }[] = [];
+
+	for (const value of Object.values(schema)) {
+		if (!is(value, PgTable)) continue;
+		const config = getTableConfig(value);
+		for (const column of config.columns) expected.push({ tableName: config.name, columnName: column.name });
+	}
+
+	return expected;
+}
+
+// The migration ledger (drizzle.__drizzle_migrations) only records that a migration ran; it
+// cannot detect objects that were dropped or lost outside the migrator (a partial restore,
+// a manual DROP TABLE, or a recreated "public" schema while the "drizzle" schema survives).
+// Comparing the live catalog with the declared schema turns that silent drift into a startup
+// failure instead of runtime "relation does not exist" (42P01) errors. The comparison covers
+// tables and columns only — indexes, constraints, and enums are intentionally out of scope.
+export async function verifyMigratedSchema(queryable: SchemaQueryable): Promise<void> {
+	const expected = collectExpectedColumns();
+	if (expected.length === 0) return;
+
+	// $1 and $2 are index-aligned: $1[i] is the name of the table expected to contain $2[i].
+	// Names are qualified as "public.<table>" so the lookup does not follow the connection's
+	// search_path — migrations always create these tables in the public schema.
+	const result = await queryable.query(
+		`select e.table_name, e.column_name
+			from unnest($1::text[], $2::text[]) as e(table_name, column_name)
+			where to_regclass('public.' || e.table_name) is null
+				or not exists (
+					select 1 from pg_catalog.pg_attribute a
+					where a.attrelid = to_regclass('public.' || e.table_name)
+						and a.attname = e.column_name
+						and a.attnum > 0 and not a.attisdropped
+				)
+			order by e.table_name, e.column_name`,
+		[expected.map((e) => e.tableName), expected.map((e) => e.columnName)],
+	);
+	if (result.rows.length === 0) return;
+
+	const expectedPerTable = new Map<string, number>();
+	for (const e of expected) expectedPerTable.set(e.tableName, (expectedPerTable.get(e.tableName) ?? 0) + 1);
+
+	const missingByTable = new Map<string, Set<string>>();
+	for (const row of result.rows) {
+		const columns = missingByTable.get(row.table_name) ?? new Set<string>();
+		columns.add(row.column_name);
+		missingByTable.set(row.table_name, columns);
+	}
+
+	const missing = [...missingByTable.entries()].map(([table, columns]) =>
+		columns.size === expectedPerTable.get(table)
+			? `table "${table}"`
+			: `column(s) ${[...columns].map((column) => `"${table}"."${column}"`).join(", ")}`,
+	);
+
+	throw new Error(
+		`Database schema does not match the migration ledger: ${missing.join(", ")} ` +
+			"missing even though all migrations are marked as applied. This usually means the database was " +
+			"restored from a backup that did not include these objects, or they were dropped outside of " +
+			"migrations. Restore a consistent backup or recreate the missing objects, then restart the server.",
+	);
+}

apps/server/src/static/schema.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import z from "zod";
+import { defaultResumeData } from "@reactive-resume/schema/resume/default";
+import { handleSchemaJson } from "./schema";
+
+describe("handleSchemaJson", () => {
+	it("publishes the custom-section type and item correlation", async () => {
+		const response = handleSchemaJson();
+		const schema = z.fromJSONSchema((await response.json()) as Parameters<typeof z.fromJSONSchema>[0]);
+		const mismatched = {
+			...defaultResumeData,
+			customSections: [
+				{
+					id: "custom-experience",
+					type: "experience",
+					title: "Experience",
+					icon: "",
+					columns: 1,
+					hidden: false,
+					keepTogether: false,
+					startOnNewPage: false,
+					items: [{ id: "summary-item", hidden: false, content: "<p>Not an experience item</p>" }],
+				},
+			],
+		};
+
+		expect(schema.safeParse(mismatched).success).toBe(false);
+	});
+});

apps/server/src/static/schema.ts

@@ -0,0 +1,17 @@
+import { createResumeDataJsonSchema } from "@reactive-resume/schema/resume/json-schema";
+import { appVersion } from "../app-version";
+
+export function handleSchemaJson() {
+	return Response.json(createResumeDataJsonSchema(), {
+		status: 200,
+		headers: {
+			"Content-Type": "application/schema+json; charset=utf-8",
+			"Cache-Control": "public, max-age=86400, immutable",
+			"Surrogate-Control": "max-age=86400",
+			"X-Content-Type-Options": "nosniff",
+			"X-Robots-Tag": "index, follow",
+			ETag: appVersion,
+			Vary: "Accept",
+		},
+	});
+}

apps/server/src/static/seo.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("@reactive-resume/env/server", () => ({
+	env: {
+		APP_URL: "https://app.example.com/",
+	},
+}));
+
+const { handleLlms, handleRobots, handleSitemap } = await import("./seo");
+
+describe("SEO static endpoints", () => {
+	it("generates robots.txt from the normalized app URL", async () => {
+		const response = handleRobots();
+		const text = await response.text();
+
+		expect(response.status).toBe(200);
+		expect(response.headers.get("Content-Type")).toBe("text/plain; charset=UTF-8");
+		expect(text).toContain("User-agent: *");
+		expect(text).toContain("Allow: /");
+		expect(text).toContain("Disallow: /api/rpc");
+		expect(text).toContain("Disallow: /api/auth");
+		expect(text).toContain("Disallow: /mcp");
+		expect(text).toContain("Disallow: /.well-known");
+		expect(text).toContain("Sitemap: https://app.example.com/sitemap.xml");
+		expect(text).toContain("Sitemap: https://docs.rxresu.me/sitemap.xml");
+		expect(text).not.toMatch(/GPTBot|ClaudeBot|PerplexityBot|CCBot|ChatGPT-User/);
+	});
+
+	it("generates an app-domain-only sitemap", async () => {
+		const response = handleSitemap();
+		const text = await response.text();
+
+		expect(response.status).toBe(200);
+		expect(response.headers.get("Content-Type")).toBe("application/xml; charset=UTF-8");
+		expect(text).toContain("<loc>https://app.example.com/</loc>");
+		expect(text).toContain("<loc>https://app.example.com/ats-checker</loc>");
+		expect(text).not.toContain("docs.rxresu.me");
+		expect(text).not.toContain("/auth");
+		expect(text).not.toContain("/dashboard");
+		expect(text).not.toContain("/builder");
+		expect(text).not.toContain("/templates");
+		expect(text).not.toContain("/schema.json");
+	});
+
+	it("generates a lightweight llms.txt product index", async () => {
+		const response = handleLlms();
+		const text = await response.text();
+
+		expect(response.status).toBe(200);
+		expect(response.headers.get("Content-Type")).toBe("text/plain; charset=UTF-8");
+		expect(text).toContain("# Reactive Resume");
+		expect(text).toContain("- Product: https://app.example.com");
+		expect(text).toContain("- Documentation: https://docs.rxresu.me");
+		expect(text).toContain("- Documentation sitemap: https://docs.rxresu.me/sitemap.xml");
+		expect(text).toContain("- Documentation llms.txt: https://docs.rxresu.me/llms.txt");
+		expect(text).toContain("- API documentation: https://docs.rxresu.me/api-reference");
+		expect(text).toContain("- Resume schema: https://app.example.com/schema.json");
+		expect(text).toContain("- MCP documentation: https://docs.rxresu.me/guides/using-the-mcp-server");
+		expect(text).toContain("- OpenAPI specification: https://app.example.com/api/openapi/spec.json");
+	});
+
+	it("returns headers without a body for HEAD responses", async () => {
+		const response = handleLlms({ head: true });
+
+		expect(response.status).toBe(200);
+		expect(response.headers.get("Content-Type")).toBe("text/plain; charset=UTF-8");
+		expect(await response.text()).toBe("");
+	});
+});

apps/server/src/static/seo.ts

@@ -0,0 +1,78 @@
+import { env } from "@reactive-resume/env/server";
+
+const DOCS_URL = "https://docs.rxresu.me";
+
+type StaticSeoOptions = {
+	head?: boolean;
+};
+
+function appUrl() {
+	return env.APP_URL.replace(/\/+$/, "");
+}
+
+function textResponse(body: string, options: StaticSeoOptions = {}) {
+	return new Response(options.head ? null : body, {
+		headers: { "Content-Type": "text/plain; charset=UTF-8" },
+	});
+}
+
+export function handleRobots(options?: StaticSeoOptions) {
+	const baseUrl = appUrl();
+	const body = [
+		"User-agent: *",
+		"Allow: /",
+		"Disallow: /api/rpc",
+		"Disallow: /api/auth",
+		"Disallow: /mcp",
+		"Disallow: /.well-known",
+		"",
+		`Sitemap: ${baseUrl}/sitemap.xml`,
+		`Sitemap: ${DOCS_URL}/sitemap.xml`,
+		"",
+	].join("\n");
+
+	return textResponse(body, options);
+}
+
+export function handleSitemap(options?: StaticSeoOptions) {
+	const baseUrl = appUrl();
+	const body = [
+		'<?xml version="1.0" encoding="UTF-8"?>',
+		'<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+		"  <url>",
+		`    <loc>${baseUrl}/</loc>`,
+		"  </url>",
+		"  <url>",
+		`    <loc>${baseUrl}/ats-checker</loc>`,
+		"  </url>",
+		"</urlset>",
+		"",
+	].join("\n");
+
+	return new Response(options?.head ? null : body, {
+		headers: { "Content-Type": "application/xml; charset=UTF-8" },
+	});
+}
+
+export function handleLlms(options?: StaticSeoOptions) {
+	const baseUrl = appUrl();
+	const body = [
+		"# Reactive Resume",
+		"",
+		"Reactive Resume is an open-source resume builder for creating, managing, and exporting resumes.",
+		"",
+		"## Links",
+		"",
+		`- Product: ${baseUrl}`,
+		`- Documentation: ${DOCS_URL}`,
+		`- Documentation sitemap: ${DOCS_URL}/sitemap.xml`,
+		`- Documentation llms.txt: ${DOCS_URL}/llms.txt`,
+		`- API documentation: ${DOCS_URL}/api-reference`,
+		`- Resume schema: ${baseUrl}/schema.json`,
+		`- MCP documentation: ${DOCS_URL}/guides/using-the-mcp-server`,
+		`- OpenAPI specification: ${baseUrl}/api/openapi/spec.json`,
+		"",
+	].join("\n");
+
+	return textResponse(body, options);
+}

apps/server/src/static/uploads-s3.test.ts

@@ -0,0 +1,110 @@
+import type { IncomingHttpHeaders } from "node:http";
+import { createServer } from "node:http";
+import { afterAll, beforeAll, beforeEach, expect, it, vi } from "vitest";
+
+const envMock = vi.hoisted(() => ({
+	APP_URL: "https://resume.example.com",
+	S3_ACCESS_KEY_ID: "test-access-key",
+	S3_SECRET_ACCESS_KEY: "test-secret-key",
+	S3_REGION: "us-east-1",
+	S3_ENDPOINT: "",
+	S3_BUCKET: "test-bucket",
+	S3_FORCE_PATH_STYLE: true,
+}));
+vi.mock("@reactive-resume/env/server", () => ({ env: envMock }));
+
+type StoredObject = { data: Buffer; contentType: string };
+type StorageRequest = { method: string; path: string; headers: IncomingHttpHeaders };
+const objects = new Map<string, StoredObject>();
+const requests: StorageRequest[] = [];
+
+// Wire-contract stub, not an AWS emulator. It applies the documented BucketOwnerEnforced
+// PUT rule to real SDK requests: no ACL or bucket-owner-full-control is accepted.
+// https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-ownership-error-responses.html
+const server = createServer(async (request, response) => {
+	const path = new URL(request.url ?? "/", "http://localhost").pathname;
+	requests.push({ method: request.method ?? "", path, headers: request.headers });
+	const fail = (status: number, code: string) => {
+		response.writeHead(status, { "Content-Type": "application/xml" });
+		response.end(`<Error><Code>${code}</Code><Message>${code}</Message></Error>`);
+	};
+	// Only checks that the SDK authenticates its requests; this stub does not verify signatures.
+	if (!request.headers.authorization?.startsWith("AWS4-HMAC-SHA256 ")) return fail(403, "AccessDenied");
+	if (request.method === "PUT") {
+		const chunks: Buffer[] = [];
+		for await (const chunk of request) chunks.push(Buffer.from(chunk));
+		const acl = request.headers["x-amz-acl"];
+		if (acl && acl !== "bucket-owner-full-control") return fail(400, "AccessControlListNotSupported");
+		objects.set(path, {
+			data: Buffer.concat(chunks),
+			contentType: request.headers["content-type"] ?? "application/octet-stream",
+		});
+		response.writeHead(200, { ETag: '"test-etag"' });
+		return response.end();
+	}
+	if (request.method === "DELETE") {
+		objects.delete(path);
+		response.writeHead(204);
+		return response.end();
+	}
+	const object = objects.get(path);
+	if (!object) return fail(404, "NoSuchKey");
+	response.writeHead(200, { "Content-Type": object.contentType, "Content-Length": object.data.length });
+	response.end(object.data);
+});
+
+let storage: ReturnType<typeof import("@reactive-resume/api/features/storage").getStorageService>;
+let handleUpload: typeof import("./uploads").handleUpload;
+
+beforeAll(async () => {
+	await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+	const address = server.address();
+	if (!address || typeof address === "string") throw new Error("Missing stub TCP address");
+	envMock.S3_ENDPOINT = `http://127.0.0.1:${address.port}`;
+	storage = (await import("@reactive-resume/api/features/storage")).getStorageService();
+	({ handleUpload } = await import("./uploads"));
+});
+
+beforeEach(() => {
+	objects.clear();
+	requests.length = 0;
+});
+
+afterAll(async () => {
+	server.closeAllConnections();
+	await new Promise<void>((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())));
+});
+
+it("keeps the ACL-disabled storage health check healthy", async () => {
+	expect(await storage.healthcheck()).toMatchObject({ status: "healthy", type: "s3" });
+	expect(requests.map(({ method }) => method)).toEqual(["PUT", "DELETE"]);
+	expect(objects.size).toBe(0);
+});
+
+it("stores images without ACLs and serves them through the signed application proxy", async () => {
+	const key = "uploads/user-1/pictures/photo.png";
+	const data = new Uint8Array([137, 80, 78, 71]);
+	await storage.write({ key, data, contentType: "image/png" });
+	expect(requests[0]?.headers["x-amz-acl"]).toBeUndefined();
+	const direct = await fetch(`${envMock.S3_ENDPOINT}/${envMock.S3_BUCKET}/${key}`);
+	expect(direct.status).toBe(403);
+	const response = await handleUpload(new Request(`${envMock.APP_URL}/api/${key}`));
+	expect(response.status).toBe(200);
+	expect(response.headers.get("Content-Type")).toBe("image/png");
+	expect(new Uint8Array(await response.arrayBuffer())).toEqual(data);
+	expect(requests.at(-1)?.headers.authorization).toMatch(/^AWS4-HMAC-SHA256 /);
+});
+
+it("stores private attachments without ACLs while keeping them outside the public proxy", async () => {
+	const key = "uploads/user-1/agent/thread-1/private.txt";
+	const data = new TextEncoder().encode("private attachment");
+	await storage.write({ key, data, contentType: "text/plain", private: true });
+	expect(requests[0]?.headers["x-amz-acl"]).toBeUndefined();
+	const requestCount = requests.length;
+	const response = await handleUpload(new Request(`${envMock.APP_URL}/api/${key}`));
+	expect(response.status).toBe(404);
+	expect(requests).toHaveLength(requestCount);
+	const direct = await fetch(`${envMock.S3_ENDPOINT}/${envMock.S3_BUCKET}/${key}`);
+	expect(direct.status).toBe(403);
+	expect((await storage.read(key))?.data).toEqual(data);
+});

apps/server/src/static/uploads.test.ts

@@ -0,0 +1,54 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const readMock = vi.fn();
+
+vi.mock("@reactive-resume/api/features/storage", () => ({
+	getStorageService: () => ({
+		read: readMock,
+	}),
+}));
+
+vi.mock("@reactive-resume/env/server", () => ({
+	env: {
+		APP_URL: "https://example.com",
+	},
+}));
+
+const { handleUpload } = await import("./uploads");
+
+describe("handleUpload", () => {
+	beforeEach(() => {
+		readMock.mockReset();
+	});
+
+	it("serves public upload keys", async () => {
+		readMock.mockResolvedValueOnce({
+			data: new TextEncoder().encode("image"),
+			size: 5,
+			contentType: "image/jpeg",
+		});
+
+		const response = await handleUpload(new Request("https://example.com/api/uploads/user-1/pictures/photo.jpeg"));
+
+		expect(response.status).toBe(200);
+		expect(readMock).toHaveBeenCalledWith("uploads/user-1/pictures/photo.jpeg");
+		expect(response.headers.get("Content-Type")).toBe("image/jpeg");
+		expect(response.headers.get("Cross-Origin-Resource-Policy")).toBe("same-site");
+		expect(response.headers.get("Access-Control-Allow-Origin")).toBeNull();
+	});
+
+	it("does not serve private agent attachment keys through the public uploads route", async () => {
+		readMock.mockResolvedValueOnce({
+			data: new TextEncoder().encode("secret"),
+			size: 6,
+			contentType: "text/plain",
+		});
+
+		const response = await handleUpload(
+			new Request("https://example.com/api/uploads/user-1/agent/thread-1/attachment.txt"),
+		);
+
+		expect(response.status).toBe(404);
+		expect(readMock).not.toHaveBeenCalled();
+	});
+});

apps/server/src/static/uploads.ts

@@ -1,33 +1,18 @@
 import { createHash } from "node:crypto";
 import { basename, extname, normalize } from "node:path";
-import { createFileRoute } from "@tanstack/react-router";
-import { getStorageService, inferContentType } from "@/integrations/orpc/services/storage";
-import { env } from "@/utils/env";
+import { getStorageService, inferContentType } from "@reactive-resume/api/features/storage";
 
-const storageService = getStorageService();
-
-export const Route = createFileRoute("/uploads/$userId/$")({
-	server: { handlers: { GET: handler } },
-});
-
-/**
- * Handler for GET requests to serve uploaded files, supporting ETags, content security, and path validation.
- * Handles nested paths like:
- * - /uploads/{userId}/pictures/{timestamp}.webp
- * - /uploads/{userId}/screenshots/{resumeId}/{timestamp}.webp
- * - /uploads/{userId}/pdfs/{resumeId}/{timestamp}.pdf
- */
-async function handler({ request }: { request: Request }) {
+export async function handleUpload(request: Request) {
 	const { userId, filePath } = parseRouteParams(request.url);
 
 	if (!userId || !filePath) return new Response("Bad Request", { status: 400 });
 
 	if (!isValidPath(userId) || !isValidPathSegments(filePath)) return new Response("Forbidden", { status: 403 });
+	if (isPrivateUploadPath(filePath)) return new Response("Not Found", { status: 404 });
 
-	// Build the full storage key: uploads/{userId}/{filePath}
+	const storageService = getStorageService();
 	const key = `uploads/${userId}/${filePath}`;
 	const storedFile = await storageService.read(key);
-
 	if (!storedFile) return new Response("Not Found", { status: 404 });
 
 	const filename = filePath.split("/").pop() ?? filePath;
@@ -38,25 +23,31 @@ async function handler({ request }: { request: Request }) {
 	if (isNotModified(request.headers, etag)) return makeNotModifiedResponse(etag);
 
 	const shouldForceDownload = [".pdf"].includes(ext);
-	const headers = buildResponseHeaders({
-		filename,
-		storedFile,
-		contentType,
-		etag,
-		shouldForceDownload,
-	});
 
-	const buffer = toArrayBuffer(storedFile.data);
+	const headers = new Headers();
+	headers.set("Content-Type", shouldForceDownload ? "application/octet-stream" : contentType);
+	headers.set("Content-Length", storedFile.size.toString());
 
-	return new Response(buffer, { headers });
+	if (shouldForceDownload) {
+		headers.set("Content-Disposition", `attachment; filename="${encodeURIComponent(basename(filename))}"`);
+	}
+
+	headers.set("Cache-Control", "public, max-age=31536000, immutable");
+	headers.set("ETag", etag);
+	headers.set("X-Content-Type-Options", "nosniff");
+	headers.set("X-Robots-Tag", "noindex, nofollow");
+	headers.set("Cross-Origin-Resource-Policy", "same-site");
+	headers.set("Referrer-Policy", "strict-origin-when-cross-origin");
+	headers.set("X-Frame-Options", "DENY");
+	headers.set("X-Download-Options", "noopen");
+
+	return new Response(toArrayBuffer(storedFile.data), { headers });
 }
 
-/**
- * Extracts userId and the remaining file path from the request URL.
- */
 function parseRouteParams(url: string): { userId: string | undefined; filePath: string | undefined } {
 	const pathname = new URL(url).pathname;
-	const pathAfterUploads = pathname.replace("/uploads/", "");
+	const [, pathAfterUploads] = pathname.split("/uploads/");
+	if (!pathAfterUploads) return { userId: undefined, filePath: undefined };
 	const firstSlashIndex = pathAfterUploads.indexOf("/");
 
 	if (firstSlashIndex === -1) {
@@ -69,27 +60,22 @@ function parseRouteParams(url: string): { userId: string | undefined; filePath:
 	return { userId, filePath: filePath || undefined };
 }
 
-/**
- * Validates that a path segment does not contain directory traversal attempts.
- */
 function isValidPath(segment: string): boolean {
 	const normalized = normalize(segment).replace(/^(\.\.(\/|\\|$))+/, "");
 
 	return normalized === segment;
 }
 
-/**
- * Validates all segments in a path for directory traversal attempts.
- */
 function isValidPathSegments(path: string): boolean {
 	const segments = path.split("/");
 
 	return segments.every((segment) => isValidPath(segment));
 }
 
-/**
- * Checks for ETag match for conditional GET requests.
- */
+function isPrivateUploadPath(path: string): boolean {
+	return path.split("/")[0] === "agent";
+}
+
 function isNotModified(headers: Headers, etag: string): boolean {
 	const ifNoneMatch = headers.get("If-None-Match");
 	const candidates = ifNoneMatch?.split(",").map((s) => s.trim()) ?? [];
@@ -97,9 +83,6 @@ function isNotModified(headers: Headers, etag: string): boolean {
 	return candidates.includes(etag);
 }
 
-/**
- * Returns a 304 Not Modified response with caching headers.
- */
 function makeNotModifiedResponse(etag: string): Response {
 	return new Response(null, {
 		status: 304,
@@ -107,61 +90,12 @@ function makeNotModifiedResponse(etag: string): Response {
 	});
 }
 
-type BuildResponseHeaderArgs = {
-	filename: string;
-	storedFile: { size: number };
-	contentType: string;
-	etag: string;
-	shouldForceDownload: boolean;
-};
-
-/**
- * Builds all headers for serving the file, including caching, security, and download headers.
- */
-function buildResponseHeaders({
-	filename,
-	storedFile,
-	contentType,
-	etag,
-	shouldForceDownload,
-}: BuildResponseHeaderArgs): Headers {
-	const headers = new Headers();
-
-	headers.set("Content-Type", shouldForceDownload ? "application/octet-stream" : contentType);
-	headers.set("Content-Length", storedFile.size.toString());
-
-	if (shouldForceDownload) {
-		headers.set("Content-Disposition", `attachment; filename="${encodeURIComponent(basename(filename))}"`);
-	}
-
-	headers.set("Cache-Control", "public, max-age=31536000, immutable");
-	headers.set("ETag", etag);
-
-	// Security Headers
-	headers.set("X-Content-Type-Options", "nosniff");
-	headers.set("X-Robots-Tag", "noindex, nofollow");
-	headers.set("Cross-Origin-Resource-Policy", "same-site");
-	headers.set("Referrer-Policy", "strict-origin-when-cross-origin");
-	headers.set("Content-Security-Policy", "default-src 'none'; style-src 'unsafe-inline'; sandbox;");
-	headers.set("X-Frame-Options", "DENY");
-	headers.set("X-Download-Options", "noopen");
-	headers.set("Access-Control-Allow-Origin", env.APP_URL);
-
-	return headers;
-}
-
-/**
- * Converts a Uint8Array to ArrayBuffer efficiently.
- */
 function toArrayBuffer(data: Uint8Array): ArrayBuffer {
 	return data.byteOffset === 0 && data.byteLength === data.buffer.byteLength
 		? (data.buffer as ArrayBuffer)
 		: (data.slice().buffer as ArrayBuffer);
 }
 
-/**
- * Generates or returns the ETag for a stored file.
- */
 function createEtag(storedFile: { data: Uint8Array; size: number; etag?: string }): string {
 	if (storedFile.etag) {
 		const tag = storedFile.etag.trim();

apps/server/src/static/web.test.ts

@@ -0,0 +1,317 @@
+import fs from "node:fs/promises";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+	env: { APP_URL: "https://rxresu.me", ROOT_RESUME_ID: undefined as string | undefined },
+	serveStatic: vi.fn((_options?: unknown) => vi.fn()),
+	getPublicResumeSocialMeta: vi.fn(),
+}));
+
+vi.mock("@reactive-resume/api/features/resume/social-meta", () => ({
+	getPublicResumeSocialMeta: mocks.getPublicResumeSocialMeta,
+}));
+
+vi.mock("node:fs", () => ({
+	existsSync: vi.fn(() => true),
+}));
+
+vi.mock("node:fs/promises", () => ({
+	default: {
+		readFile: vi.fn(),
+	},
+}));
+
+vi.mock("@hono/node-server/serve-static", () => ({
+	serveStatic: mocks.serveStatic,
+}));
+
+vi.mock("@reactive-resume/env/server", () => ({
+	env: mocks.env,
+}));
+
+type StaticOptions = {
+	onFound?: (
+		path: string,
+		context: {
+			req: { path: string };
+			header: (name: string, value: string) => void;
+		},
+	) => void | Promise<void>;
+};
+
+const { handleWebApp } = await import("./web");
+const staticOptions = mocks.serveStatic.mock.calls[0]?.[0] as StaticOptions | undefined;
+
+describe("web app fallback classification", () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+		mocks.env.ROOT_RESUME_ID = undefined;
+		vi.mocked(fs.readFile).mockResolvedValue("<html>app</html>");
+		mocks.getPublicResumeSocialMeta.mockResolvedValue(null);
+	});
+
+	it("serves the shell for the root app route without noindex", async () => {
+		const response = await handleWebApp(new Request("https://example.com/"));
+
+		expect(response.status).toBe(200);
+		expect(response.headers.get("Content-Type")).toBe("text/html; charset=UTF-8");
+		expect(response.headers.get("X-Robots-Tag")).toBeNull();
+		expect(await response.text()).toBe("<html>app</html>");
+	});
+
+	it("injects canonical metadata and structured data into tracking-parameter root requests only", async () => {
+		vi.mocked(fs.readFile).mockResolvedValue(`
+			<!doctype html>
+			<html>
+				<head>
+					<title>Reactive Resume — A free and open-source resume builder</title>
+					<meta
+						name="description"
+						content="Reactive Resume is a free and open-source resume builder that makes it easy to create, update, and share your resume."
+					>
+				</head>
+				<body><div id="app"></div></body>
+			</html>
+		`);
+
+		const response = await handleWebApp(new Request("http://server.internal/?utm_source=search"));
+		const html = await response.text();
+
+		expect(html).toContain('<link rel="canonical" href="https://rxresu.me/">');
+		expect(html).toContain('<link rel="preload" href="/videos/timelapse-v1.webp" as="image" fetchpriority="high">');
+		expect(html).toContain('<meta property="og:url" content="https://rxresu.me/">');
+		expect(html).toContain('<meta property="og:image" content="https://rxresu.me/opengraph/banner.jpg">');
+		expect(html).toContain('id="reactive-resume-structured-data"');
+		expect(html).toContain('"@type":["SoftwareApplication","WebApplication"]');
+		expect(html).toContain('"url":"https://rxresu.me/"');
+		expect(html).not.toContain("utm_source");
+
+		const dashboardResponse = await handleWebApp(new Request("https://example.com/dashboard"));
+		expect(await dashboardResponse.text()).not.toContain('rel="canonical"');
+	});
+
+	describe("the ATS checker page", () => {
+		const shell = `<html><head><title>Reactive Resume — A free and open-source resume builder</title><meta name="description" content="Marketing copy."></head><body></body></html>`;
+
+		it("serves an indexable shell rather than a 404", async () => {
+			vi.mocked(fs.readFile).mockResolvedValue(shell);
+
+			const response = await handleWebApp(new Request("https://example.com/ats-checker"));
+
+			expect(response.status).toBe(200);
+			expect(response.headers.get("Content-Type")).toBe("text/html; charset=UTF-8");
+			expect(response.headers.get("X-Robots-Tag")).toBeNull();
+		});
+
+		it("replaces the shell metadata with the checker's own", async () => {
+			vi.mocked(fs.readFile).mockResolvedValue(shell);
+
+			const html = await (await handleWebApp(new Request("https://example.com/ats-checker"))).text();
+
+			expect(html).toContain("<title>ATS Checker - Reactive Resume</title>");
+			expect(html).toContain('<link rel="canonical" href="https://rxresu.me/ats-checker">');
+			expect(html).toContain('<meta property="og:url" content="https://rxresu.me/ats-checker">');
+			expect(html).toContain('<meta property="og:image" content="https://rxresu.me/opengraph/ats-checker.png">');
+			expect(html).toContain('id="ats-checker-structured-data"');
+			expect(html).not.toContain("Marketing copy.");
+		});
+
+		it("answers HEAD without a body", async () => {
+			const response = await handleWebApp(new Request("https://example.com/ats-checker", { method: "HEAD" }));
+
+			expect(response.status).toBe(200);
+			expect(await response.text()).toBe("");
+		});
+
+		it("does not treat the checker path as a public resume owner", async () => {
+			const response = await handleWebApp(new Request("https://example.com/ats-checker/anything"));
+
+			expect(response.status).toBe(404);
+			expect(mocks.getPublicResumeSocialMeta).not.toHaveBeenCalled();
+		});
+	});
+
+	describe("public resume social cards", () => {
+		const shell = `<html><head><title>Reactive Resume — A free and open-source resume builder</title><meta name="description" content="Marketing copy."></head><body></body></html>`;
+
+		it("injects resume-specific social metadata and replaces the shell title", async () => {
+			vi.mocked(fs.readFile).mockResolvedValue(shell);
+			mocks.getPublicResumeSocialMeta.mockResolvedValue({
+				name: "Jane Doe",
+				title: "Jane Doe — Staff Engineer",
+				description: "Builds resilient distributed systems.",
+				template: "azurill",
+			});
+
+			const html = await (await handleWebApp(new Request("https://example.com/jane/resume"))).text();
+
+			expect(mocks.getPublicResumeSocialMeta).toHaveBeenCalledWith({ username: "jane", slug: "resume" });
+			expect(html).toContain("<title>Jane Doe - Reactive Resume</title>");
+			expect(html).toContain('<meta name="description" content="Builds resilient distributed systems.">');
+			expect(html).not.toContain("Marketing copy.");
+			expect(html).toContain('<link rel="canonical" href="https://rxresu.me/jane/resume">');
+			expect(html).toContain('<meta property="og:type" content="profile">');
+			expect(html).toContain('<meta property="og:title" content="Jane Doe — Staff Engineer">');
+			expect(html).toContain('<meta property="og:image" content="https://rxresu.me/opengraph/banner.jpg">');
+			expect(html).toContain('<meta name="twitter:card" content="summary_large_image">');
+			expect(html).toContain('<meta name="twitter:image" content="https://rxresu.me/opengraph/banner.jpg">');
+		});
+
+		it("escapes user-authored values so resume content cannot break out of the attribute", async () => {
+			vi.mocked(fs.readFile).mockResolvedValue(shell);
+			mocks.getPublicResumeSocialMeta.mockResolvedValue({
+				name: 'Jane" onload="alert(1)',
+				title: "<script>alert(1)</script>",
+				description: 'Ends with " and & ampersand',
+				template: "azurill",
+			});
+
+			const html = await (await handleWebApp(new Request("https://example.com/jane/resume"))).text();
+
+			expect(html).not.toContain("<script>alert(1)</script>");
+			expect(html).not.toContain('onload="alert(1)');
+			expect(html).toContain('<meta property="og:title" content="&lt;script&gt;alert(1)&lt;/script&gt;">');
+			expect(html).toContain('content="Ends with &quot; and &amp; ampersand"');
+		});
+
+		it("serves the plain shell when the resume is not publicly shareable", async () => {
+			vi.mocked(fs.readFile).mockResolvedValue(shell);
+
+			const html = await (await handleWebApp(new Request("https://example.com/jane/private"))).text();
+
+			expect(html).toBe(shell);
+		});
+
+		it("serves the plain shell when the lookup fails", async () => {
+			vi.mocked(fs.readFile).mockResolvedValue(shell);
+			mocks.getPublicResumeSocialMeta.mockRejectedValue(new Error("database unavailable"));
+
+			const response = await handleWebApp(new Request("https://example.com/jane/resume"));
+
+			expect(response.status).toBe(200);
+			await expect(response.text()).resolves.toBe(shell);
+		});
+	});
+
+	it("caches versioned homepage media immutably", async () => {
+		const headers = new Headers();
+
+		await staticOptions?.onFound?.("", {
+			req: { path: "/videos/timelapse-v1.mp4" },
+			header: (name, value) => headers.set(name, value),
+		});
+
+		expect(headers.get("Cache-Control")).toBe("public, max-age=31536000, immutable");
+
+		const unversionedHeaders = new Headers();
+		await staticOptions?.onFound?.("", {
+			req: { path: "/videos/timelapse.mp4" },
+			header: (name, value) => unversionedHeaders.set(name, value),
+		});
+
+		expect(unversionedHeaders.get("Cache-Control")).toBeNull();
+	});
+
+	it.each(["/", "/alice/resume"])("sets framing and report-only CSP security headers on %s", async (pathname) => {
+		const response = await handleWebApp(new Request(`https://example.com${pathname}`));
+
+		expect(response.status).toBe(200);
+		expect(response.headers.get("X-Frame-Options")).toBe("DENY");
+		expect(response.headers.get("X-Content-Type-Options")).toBe("nosniff");
+		expect(response.headers.get("Content-Security-Policy-Report-Only")).toContain("frame-ancestors 'none'");
+	});
+
+	it.each(["/auth/login", "/dashboard", "/builder/resume-1", "/agent", "/templates", "/templates/azurill.pdf"])(
+		"serves noindex shell for known app prefix %s",
+		async (pathname) => {
+			const response = await handleWebApp(new Request(`https://example.com${pathname}`));
+
+			expect(response.status).toBe(200);
+			expect(response.headers.get("Content-Type")).toBe("text/html; charset=UTF-8");
+			expect(response.headers.get("X-Robots-Tag")).toBe("noindex, follow");
+			expect(await response.text()).toBe("<html>app</html>");
+		},
+	);
+
+	it("serves noindex shell for public resume shaped routes", async () => {
+		const response = await handleWebApp(new Request("https://example.com/alice/resume"));
+
+		expect(response.status).toBe(200);
+		expect(response.headers.get("X-Robots-Tag")).toBe("noindex, follow");
+		expect(await response.text()).toBe("<html>app</html>");
+	});
+
+	it("returns noindex 404 for unknown non-asset routes", async () => {
+		const response = await handleWebApp(new Request("https://example.com/unknown/extra/path"));
+
+		expect(response.status).toBe(404);
+		expect(response.headers.get("Content-Type")).toBe("text/plain; charset=UTF-8");
+		expect(response.headers.get("X-Robots-Tag")).toBe("noindex, nofollow");
+		expect(await response.text()).toBe("Not Found");
+		expect(fs.readFile).not.toHaveBeenCalled();
+	});
+
+	it.each(["/api/foo", "/mcp/foo", "/uploads/foo"])(
+		"does not treat reserved two-segment path %s as a public resume",
+		async (pathname) => {
+			const response = await handleWebApp(new Request(`https://example.com${pathname}`));
+
+			expect(response.status).toBe(404);
+			expect(response.headers.get("Content-Type")).toBe("text/plain; charset=UTF-8");
+			expect(response.headers.get("X-Robots-Tag")).toBe("noindex, nofollow");
+			expect(await response.text()).toBe("Not Found");
+			expect(fs.readFile).not.toHaveBeenCalled();
+		},
+	);
+
+	it("returns plain 404 for missing asset-looking paths", async () => {
+		const response = await handleWebApp(new Request("https://example.com/assets/missing.css"));
+
+		expect(response.status).toBe(404);
+		expect(response.headers.get("X-Robots-Tag")).toBeNull();
+		expect(await response.text()).toBe("Not Found");
+		expect(fs.readFile).not.toHaveBeenCalled();
+	});
+
+	it("mirrors fallback status and headers for HEAD without a body", async () => {
+		const knownResponse = await handleWebApp(new Request("https://example.com/dashboard", { method: "HEAD" }));
+		const unknownResponse = await handleWebApp(
+			new Request("https://example.com/unknown/extra/path", { method: "HEAD" }),
+		);
+
+		expect(knownResponse.status).toBe(200);
+		expect(knownResponse.headers.get("Content-Type")).toBe("text/html; charset=UTF-8");
+		expect(knownResponse.headers.get("X-Robots-Tag")).toBe("noindex, follow");
+		expect(await knownResponse.text()).toBe("");
+
+		expect(unknownResponse.status).toBe(404);
+		expect(unknownResponse.headers.get("Content-Type")).toBe("text/plain; charset=UTF-8");
+		expect(unknownResponse.headers.get("X-Robots-Tag")).toBe("noindex, nofollow");
+		expect(await unknownResponse.text()).toBe("");
+	});
+});
+
+describe("configured root shell", () => {
+	it.each(["GET", "HEAD"])("serves no-store noindex headers for %s", async (method) => {
+		mocks.env.ROOT_RESUME_ID = "private-or-missing-id";
+		const response = await handleWebApp(new Request("https://attacker.example/", { method }));
+		expect(response.headers.get("X-Robots-Tag")).toBe("noindex, follow");
+		expect(response.headers.get("Cache-Control")).toBe("private, no-store");
+	});
+	it("uses configured canonical root without leaking ID or marketing metadata", async () => {
+		mocks.env.ROOT_RESUME_ID = "private-or-missing-id";
+		vi.mocked(fs.readFile).mockResolvedValue(
+			'<html><head><title>Marketing title</title><meta name="description" content="Marketing copy."></head><body></body></html>',
+		);
+		const html = await (
+			await handleWebApp(
+				new Request("https://attacker.example/?id=other", {
+					headers: { host: "attacker.example", "x-forwarded-host": "evil.example" },
+				}),
+			)
+		).text();
+		expect(html).toContain('<link rel="canonical" href="https://rxresu.me/" data-root-resume-shell>');
+		expect(html).toContain('<meta name="robots" content="noindex, follow" data-root-resume-shell>');
+		expect(html).not.toMatch(/private-or-missing-id|attacker|evil|Marketing|application\/ld\+json|timelapse/);
+	});
+});

apps/server/src/static/web.ts

@@ -0,0 +1,347 @@
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { serveStatic } from "@hono/node-server/serve-static";
+import { env } from "@reactive-resume/env/server";
+
+function resolveWebDistPath() {
+	const candidates = [
+		// Source layout: apps/server/src/static/web.ts -> apps/web/dist
+		fileURLToPath(new URL("../../../web/dist", import.meta.url)),
+		// Bundled layout: apps/server/dist/index.mjs -> apps/web/dist
+		fileURLToPath(new URL("../../web/dist", import.meta.url)),
+	];
+	const [fallback] = candidates;
+	if (!fallback) throw new Error("Could not resolve web dist path");
+
+	return candidates.find((candidate) => existsSync(candidate)) ?? fallback;
+}
+
+const staticRoot = resolveWebDistPath();
+const indexHtmlPath = `${staticRoot}/index.html`;
+const noindexShellPrefixes = ["/auth", "/dashboard", "/builder", "/agent", "/templates"];
+/**
+ * Marketing pages the SPA owns that search engines should index.
+ *
+ * Without an entry here the fallback below returns 404 for the path in production — the dev Vite
+ * server serves the shell for anything, so this failure only ever shows up once deployed.
+ */
+const indexableAppPaths = new Set(["/ats-checker"]);
+const reservedPublicResumeSegments = new Set([
+	"api",
+	"mcp",
+	".well-known",
+	"uploads",
+	"auth",
+	"dashboard",
+	"builder",
+	"agent",
+	"templates",
+	"ats-checker",
+]);
+
+function isAssetPath(pathname: string): boolean {
+	return pathname.split("/").pop()?.includes(".") ?? false;
+}
+
+function getPathSegments(pathname: string) {
+	return pathname.split("/").filter(Boolean);
+}
+
+function isNoindexShellPath(pathname: string): boolean {
+	return noindexShellPrefixes.some((prefix) => pathname === prefix || pathname.startsWith(`${prefix}/`));
+}
+
+function isPublicResumePath(pathname: string): boolean {
+	const segments = getPathSegments(pathname);
+	const [firstSegment] = segments;
+
+	return segments.length === 2 && firstSegment !== undefined && !reservedPublicResumeSegments.has(firstSegment);
+}
+
+const BASE_SECURITY_HEADERS = {
+	"X-Frame-Options": "DENY",
+	"X-Content-Type-Options": "nosniff",
+	"Referrer-Policy": "strict-origin-when-cross-origin",
+	"Content-Security-Policy-Report-Only":
+		"default-src 'self'; img-src 'self' data: blob:; font-src 'self' data:; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'; connect-src 'self'; frame-ancestors 'none'; base-uri 'self'; object-src 'none'",
+};
+
+const ROOT_TITLE = "Reactive Resume — A free and open-source resume builder";
+// Keep under ~120 characters so Google's mobile SERP snippet is not truncated at 3 lines.
+const ROOT_DESCRIPTION =
+	"Free, open-source resume builder. Create, update, and share your resume, with no ads and no paywall.";
+const ROOT_POSTER_PATH = "/videos/timelapse-v1.webp";
+const ROOT_FAQ_ITEMS = [
+	{
+		question: "Is Reactive Resume really free?",
+		answer:
+			"Yes. Reactive Resume is free to use, with no hidden costs, premium tiers, or subscription fees. It's open source, and it will stay free.",
+	},
+	{
+		question: "How is my data protected?",
+		answer:
+			"Your data is stored securely and never shared with third parties. If you want full control over it, you can self-host Reactive Resume on your own servers.",
+	},
+	{
+		question: "Can I export my resume to PDF?",
+		answer: "Yes. One click exports your resume to PDF, with your formatting and styling intact.",
+	},
+	{
+		question: "Is Reactive Resume available in multiple languages?",
+		answer:
+			"Yes. Pick your language on the settings page, or with the language switcher in the top right corner. If your language is missing, or the existing translation could be better, you can contribute to the translations on Crowdin.",
+	},
+	{
+		question: "What makes Reactive Resume different from other resume builders?",
+		answer:
+			"Reactive Resume is open source, private, and free. It shows no ads, doesn't track what you do, and doesn't lock features behind a paywall.",
+	},
+	{
+		question: "How do I share my resume?",
+		answer: "Share it with a public URL, put a password on that URL, or download the PDF and send it yourself.",
+	},
+] as const;
+
+function createRootSeoMarkup(canonicalUrl: string) {
+	const origin = new URL(canonicalUrl).origin;
+	const imageUrl = `${origin}/opengraph/banner.jpg`;
+	const structuredData = {
+		"@context": "https://schema.org",
+		"@graph": [
+			{
+				"@type": "WebSite",
+				name: "Reactive Resume",
+				url: canonicalUrl,
+			},
+			{
+				"@type": ["SoftwareApplication", "WebApplication"],
+				name: "Reactive Resume",
+				url: canonicalUrl,
+				description: ROOT_DESCRIPTION,
+				applicationCategory: "BusinessApplication",
+				operatingSystem: "Web",
+				isAccessibleForFree: true,
+				offers: {
+					"@type": "Offer",
+					price: "0",
+					priceCurrency: "USD",
+				},
+				codeRepository: "https://github.com/reactive-resume/reactive-resume",
+			},
+			{
+				"@type": "Project",
+				name: "Reactive Resume",
+				url: canonicalUrl,
+				sameAs: ["https://github.com/reactive-resume/reactive-resume"],
+			},
+			{
+				"@type": "FAQPage",
+				mainEntity: ROOT_FAQ_ITEMS.map((item) => ({
+					"@type": "Question",
+					name: item.question,
+					acceptedAnswer: {
+						"@type": "Answer",
+						text: item.answer,
+					},
+				})),
+			},
+		],
+	};
+
+	return `
+		<link rel="canonical" href="${canonicalUrl}">
+		<link rel="preload" href="${ROOT_POSTER_PATH}" as="image" fetchpriority="high">
+		<meta property="og:type" content="website">
+		<meta property="og:site_name" content="Reactive Resume">
+		<meta property="og:title" content="${ROOT_TITLE}">
+		<meta property="og:description" content="${ROOT_DESCRIPTION}">
+		<meta property="og:url" content="${canonicalUrl}">
+		<meta property="og:image" content="${imageUrl}">
+		<meta name="twitter:card" content="summary_large_image">
+		<meta name="twitter:title" content="${ROOT_TITLE}">
+		<meta name="twitter:description" content="${ROOT_DESCRIPTION}">
+		<meta name="twitter:image" content="${imageUrl}">
+		<script id="reactive-resume-structured-data" type="application/ld+json">${JSON.stringify(structuredData)}</script>
+	`;
+}
+
+const ATS_CHECKER_TITLE = "ATS Checker - Reactive Resume";
+// Keep under ~120 characters so Google's mobile SERP snippet is not truncated at 3 lines.
+const ATS_CHECKER_DESCRIPTION =
+	"Check whether software can read your resume PDF. Runs entirely in your browser, so your file is never uploaded.";
+
+function createAtsCheckerSeoMarkup(origin: string) {
+	const canonicalUrl = `${origin}/ats-checker`;
+	const imageUrl = `${origin}/opengraph/ats-checker.png`;
+	const structuredData = {
+		"@context": "https://schema.org",
+		"@type": "WebApplication",
+		name: "ATS Checker",
+		url: canonicalUrl,
+		description: ATS_CHECKER_DESCRIPTION,
+		applicationCategory: "BusinessApplication",
+		operatingSystem: "Web",
+		isAccessibleForFree: true,
+		offers: { "@type": "Offer", price: "0", priceCurrency: "USD" },
+		isPartOf: { "@type": "WebSite", name: "Reactive Resume", url: `${origin}/` },
+	};
+
+	return `
+		<link rel="canonical" href="${canonicalUrl}">
+		<meta property="og:type" content="website">
+		<meta property="og:site_name" content="Reactive Resume">
+		<meta property="og:title" content="${ATS_CHECKER_TITLE}">
+		<meta property="og:description" content="${ATS_CHECKER_DESCRIPTION}">
+		<meta property="og:url" content="${canonicalUrl}">
+		<meta property="og:image" content="${imageUrl}">
+		<meta name="twitter:card" content="summary_large_image">
+		<meta name="twitter:title" content="${ATS_CHECKER_TITLE}">
+		<meta name="twitter:description" content="${ATS_CHECKER_DESCRIPTION}">
+		<meta name="twitter:image" content="${imageUrl}">
+		<script id="ats-checker-structured-data" type="application/ld+json">${JSON.stringify(structuredData)}</script>
+	`;
+}
+
+// Resume names, headlines, and summaries are user-authored, so they must never reach the served
+// HTML unescaped.
+const escapeAttribute = (value: string) =>
+	value
+		.replaceAll("&", "&amp;")
+		.replaceAll("<", "&lt;")
+		.replaceAll(">", "&gt;")
+		.replaceAll('"', "&quot;")
+		.replaceAll("'", "&#39;");
+
+async function createPublicResumeSeoMarkup(pathname: string, origin: string) {
+	const [username, slug] = getPathSegments(pathname);
+	if (!username || !slug) return null;
+
+	// A card render must never take down the page: any lookup failure falls back to the plain shell.
+	const meta = await import("@reactive-resume/api/features/resume/social-meta")
+		.then((module) => module.getPublicResumeSocialMeta({ username, slug }))
+		.catch(() => null);
+	if (!meta) return null;
+
+	const canonicalUrl = `${origin}/${username}/${slug}`;
+	const imageUrl = `${origin}/opengraph/banner.jpg`;
+	const pageTitle = escapeAttribute(`${meta.name} - Reactive Resume`);
+	const title = escapeAttribute(meta.title);
+	const description = escapeAttribute(meta.description);
+
+	return {
+		pageTitle,
+		description,
+		markup: `
+		<link rel="canonical" href="${canonicalUrl}">
+		<meta property="og:type" content="profile">
+		<meta property="og:site_name" content="Reactive Resume">
+		<meta property="og:title" content="${title}">
+		<meta property="og:description" content="${description}">
+		<meta property="og:url" content="${canonicalUrl}">
+		<meta property="og:image" content="${imageUrl}">
+		<meta name="twitter:card" content="summary_large_image">
+		<meta name="twitter:title" content="${title}">
+		<meta name="twitter:description" content="${description}">
+		<meta name="twitter:image" content="${imageUrl}">
+	`,
+	};
+}
+
+export const serveWebDistStatic = serveStatic({
+	root: staticRoot,
+	onFound: (_path, context) => {
+		if (/^\/videos\/.*-v\d+\.(?:mp4|webp)$/.test(context.req.path)) {
+			context.header("Cache-Control", "public, max-age=31536000, immutable");
+		}
+	},
+});
+
+function getFallbackResponseHeaders(pathname: string) {
+	if (pathname === "/" && env.ROOT_RESUME_ID?.trim()) {
+		return {
+			"Content-Type": "text/html; charset=UTF-8",
+			"X-Robots-Tag": "noindex, follow",
+			"Cache-Control": "private, no-store",
+			...BASE_SECURITY_HEADERS,
+		};
+	}
+	if (pathname === "/" || indexableAppPaths.has(pathname)) {
+		return { "Content-Type": "text/html; charset=UTF-8", ...BASE_SECURITY_HEADERS };
+	}
+	if (isNoindexShellPath(pathname) || isPublicResumePath(pathname)) {
+		return {
+			"Content-Type": "text/html; charset=UTF-8",
+			"X-Robots-Tag": "noindex, follow",
+			...BASE_SECURITY_HEADERS,
+		};
+	}
+
+	return null;
+}
+
+function notFoundResponse(options: { head?: boolean; noindex?: boolean } = {}) {
+	const headers = new Headers({ "Content-Type": "text/plain; charset=UTF-8" });
+	if (options.noindex) headers.set("X-Robots-Tag", "noindex, nofollow");
+
+	return new Response(options.head ? null : "Not Found", {
+		status: 404,
+		headers,
+	});
+}
+
+// ponytail: GET and HEAD share the same routing logic; method determines body presence
+export async function handleWebApp(request: Request) {
+	const isHead = request.method === "HEAD";
+	const pathname = new URL(request.url).pathname;
+
+	if (!isNoindexShellPath(pathname) && isAssetPath(pathname)) {
+		return new Response(isHead ? null : "Not Found", { status: 404 });
+	}
+
+	const headers = getFallbackResponseHeaders(pathname);
+	if (!headers) return notFoundResponse({ head: isHead, noindex: true });
+
+	if (isHead) return new Response(null, { status: 200, headers });
+
+	const html = await fs.readFile(indexHtmlPath, "utf-8");
+	const canonicalUrl = new URL("/", env.APP_URL).toString();
+
+	if (pathname === "/" && env.ROOT_RESUME_ID?.trim()) {
+		// Root configuration never discloses a target in the HTML shell. The public API
+		// gates data and browser metadata; shell requests must not count extra views.
+		const shell = html
+			.replace(/<title>[^<]*<\/title>/, "<title>Reactive Resume</title>")
+			.replace(/<meta\s+name="description"[^>]*>/, '<meta name="description" content="">');
+		const markup = `<link rel="canonical" href="${escapeAttribute(canonicalUrl)}" data-root-resume-shell><meta name="robots" content="noindex, follow" data-root-resume-shell>`;
+		return new Response(shell.replace("</head>", `${markup}</head>`), { headers });
+	}
+
+	if (pathname === "/") {
+		return new Response(html.replace("</head>", `${createRootSeoMarkup(canonicalUrl)}</head>`), { headers });
+	}
+
+	if (pathname === "/ats-checker") {
+		const origin = new URL(env.APP_URL).origin;
+		const withTitle = html
+			.replace(/<title>[^<]*<\/title>/, `<title>${ATS_CHECKER_TITLE}</title>`)
+			.replace(/<meta\s+name="description"[^>]*>/, `<meta name="description" content="${ATS_CHECKER_DESCRIPTION}">`);
+
+		return new Response(withTitle.replace("</head>", `${createAtsCheckerSeoMarkup(origin)}</head>`), { headers });
+	}
+
+	if (isPublicResumePath(pathname)) {
+		const resumeSeo = await createPublicResumeSeoMarkup(pathname, new URL(env.APP_URL).origin);
+		if (resumeSeo) {
+			// The shell's generic title/description are replaced so shares and previews show the resume,
+			// not the marketing copy baked into index.html.
+			const withTitle = html
+				.replace(/<title>[^<]*<\/title>/, `<title>${resumeSeo.pageTitle}</title>`)
+				.replace(/<meta\s+name="description"[^>]*>/, `<meta name="description" content="${resumeSeo.description}">`);
+
+			return new Response(withTitle.replace("</head>", `${resumeSeo.markup}</head>`), { headers });
+		}
+	}
+
+	return new Response(html, { headers });
+}

apps/server/src/vercel.test.ts

@@ -0,0 +1,99 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { TRUSTED_IP_HEADERS } from "@reactive-resume/utils/rate-limit";
+
+const mocks = vi.hoisted(() => ({
+	ipAddress: vi.fn<(request: Request) => string | undefined>(),
+	waitUntil: vi.fn(),
+	initializeAuth: vi.fn(),
+	attachDatabasePool: vi.fn(),
+	configureAgentStreamLifetime: vi.fn(),
+	pool: {},
+	getPool: vi.fn(),
+	createApp:
+		vi.fn<
+			(options: { serveStatic: boolean; trustedClient: (request: Request) => string }) => {
+				fetch: (request: Request) => Promise<Response>;
+			}
+		>(),
+	handle: vi.fn<(request: Request) => Promise<Response>>(),
+}));
+
+vi.mock("@vercel/functions", () => ({
+	ipAddress: mocks.ipAddress,
+	waitUntil: mocks.waitUntil,
+	attachDatabasePool: mocks.attachDatabasePool,
+}));
+vi.mock("@reactive-resume/api/features/agent/streams", () => ({
+	configureAgentStreamLifetime: mocks.configureAgentStreamLifetime,
+}));
+vi.mock("@reactive-resume/auth/config", () => ({ initializeAuth: mocks.initializeAuth }));
+vi.mock("@reactive-resume/db/client", () => ({ getPool: mocks.getPool }));
+vi.mock("./http/app", () => ({ createApp: mocks.createApp }));
+
+function spoofedRequest() {
+	return new Request("https://resume.test/api/rpc?batch=1", {
+		method: "POST",
+		body: "original RPC body",
+		headers: {
+			...Object.fromEntries(TRUSTED_IP_HEADERS.map((header) => [header, "192.0.2.66"])),
+			"x-forwarded-for": "192.0.2.66, 192.0.2.77",
+			cookie: "session=original",
+			authorization: "Bearer original",
+			"content-type": "application/json",
+		},
+	});
+}
+
+beforeEach(() => {
+	vi.resetModules();
+	vi.clearAllMocks();
+	mocks.getPool.mockReturnValue(mocks.pool);
+	mocks.handle.mockResolvedValue(new Response("handled"));
+	mocks.createApp.mockReturnValue({ fetch: mocks.handle });
+});
+
+describe("Vercel adapter", () => {
+	it("registers platform lifetime hooks and disables filesystem static serving", async () => {
+		await import("./vercel");
+		expect(mocks.configureAgentStreamLifetime).toHaveBeenCalledExactlyOnceWith(mocks.waitUntil);
+		expect(mocks.attachDatabasePool).toHaveBeenCalledExactlyOnceWith(mocks.pool);
+		expect(mocks.createApp).toHaveBeenCalledExactlyOnceWith({
+			serveStatic: false,
+			trustedClient: expect.any(Function),
+		});
+	});
+
+	it.each(["203.0.113.9", "2001:db8::9"])("replaces all spoofed IP headers with platform IP %s", async (ip) => {
+		mocks.ipAddress.mockReturnValue(ip);
+		const { default: adapter } = await import("./vercel");
+		const request = spoofedRequest();
+		expect(await (await adapter.fetch(request)).text()).toBe("handled");
+		expect(mocks.ipAddress).toHaveBeenCalledExactlyOnceWith(request);
+		const forwarded = mocks.handle.mock.calls[0]?.[0];
+		if (!forwarded) throw new Error("Expected forwarded request");
+		for (const header of TRUSTED_IP_HEADERS) {
+			const expected = ["x-real-ip", "x-forwarded-for"].includes(header.toLowerCase()) ? ip : null;
+			expect(forwarded.headers.get(header)).toBe(expected);
+		}
+		expect(mocks.createApp.mock.calls[0]?.[0].trustedClient(forwarded)).toBe(ip);
+		expect(forwarded.url).toBe(request.url);
+		expect(forwarded.method).toBe("POST");
+		expect(await forwarded.text()).toBe("original RPC body");
+		expect(forwarded.headers.get("cookie")).toBe("session=original");
+		expect(forwarded.headers.get("authorization")).toBe("Bearer original");
+		expect(forwarded.headers.get("content-type")).toBe("application/json");
+	});
+
+	it.each([undefined, "", "invalid-ip", "203.0.113.9, 192.0.2.66"])(
+		"clears attacker headers when platform IP is missing or invalid: %s",
+		async (ip) => {
+			mocks.ipAddress.mockReturnValue(ip);
+			const { default: adapter } = await import("./vercel");
+			await adapter.fetch(spoofedRequest());
+			const forwarded = mocks.handle.mock.calls[0]?.[0];
+			if (!forwarded) throw new Error("Expected forwarded request");
+			for (const header of TRUSTED_IP_HEADERS) expect(forwarded.headers.has(header)).toBe(false);
+			expect(mocks.createApp.mock.calls[0]?.[0].trustedClient(forwarded)).toBe("unknown");
+		},
+	);
+});

apps/server/src/vercel.ts

@@ -0,0 +1,29 @@
+import { isIP } from "node:net";
+import { attachDatabasePool, ipAddress, waitUntil } from "@vercel/functions";
+import { configureAgentStreamLifetime } from "@reactive-resume/api/features/agent/streams";
+import { initializeAuth } from "@reactive-resume/auth/config";
+import { getPool } from "@reactive-resume/db/client";
+import { TRUSTED_IP_HEADERS } from "@reactive-resume/utils/rate-limit";
+import { createApp } from "./http/app";
+
+configureAgentStreamLifetime(waitUntil);
+attachDatabasePool(getPool());
+const app = createApp({
+	serveStatic: false,
+	trustedClient: (request) => request.headers.get("x-real-ip") ?? "unknown",
+});
+
+export default {
+	async fetch(request: Request) {
+		await initializeAuth();
+		const ip = ipAddress(request);
+		const headers = new Headers(request.headers);
+		for (const name of TRUSTED_IP_HEADERS) headers.delete(name);
+		headers.delete("x-real-ip");
+		if (ip && isIP(ip)) {
+			headers.set("x-real-ip", ip);
+			headers.set("x-forwarded-for", ip);
+		}
+		return app.fetch(new Request(request, { headers }));
+	},
+};

apps/server/src/vite-env.d.ts

@@ -0,0 +1 @@
+declare const __APP_VERSION__: string;

apps/server/tsconfig.json

@@ -0,0 +1,12 @@
+{
+	"extends": "@reactive-resume/config/tsconfig.base.json",
+	"include": ["src/**/*.ts", "src/**/*.tsx", "tsdown.config.ts", "vitest.config.ts"],
+	"compilerOptions": {
+		"jsx": "react-jsx",
+		"lib": ["ESNext", "DOM"],
+		"types": ["node"],
+		"paths": {
+			"@/*": ["./src/*"]
+		}
+	}
+}

apps/server/tsdown.config.ts

@@ -0,0 +1,83 @@
+import type { TsdownPlugin } from "tsdown";
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineConfig } from "tsdown";
+
+const rootPackageJson = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf-8")) as {
+	version?: string;
+};
+
+// Lambda disables require(ESM) and uses stricter CJS export detection than standalone Node.
+const bundledInteropPackages = new Set([
+	"@uiw/color-convert",
+	"@babel/runtime",
+	"sanitize-html",
+	"htmlparser2",
+	"domhandler",
+	"domutils",
+	"domelementtype",
+	"dom-serializer",
+	"entities",
+	"deepmerge",
+	"escape-string-regexp",
+	"is-plain-object",
+	"parse-srcset",
+	"postcss",
+	"nanoid",
+	"picocolors",
+	"source-map-js",
+	"launder",
+	"dayjs",
+]);
+
+const shouldExternalizeThirdParty = (id: string) => {
+	const packageName = id
+		.split("/")
+		.slice(0, id.startsWith("@") ? 2 : 1)
+		.join("/");
+	if (id.startsWith("@reactive-resume/") || bundledInteropPackages.has(packageName)) return false;
+	if (id.startsWith("@/") || id.startsWith(".") || id.startsWith("/") || id.startsWith("\0")) return false;
+
+	return true;
+};
+
+const aiPromptsDir = resolve(dirname(fileURLToPath(import.meta.url)), "../../packages/ai/src/prompts");
+
+const promptAssetsPlugin: TsdownPlugin = {
+	name: "prompt-assets",
+	buildStart() {
+		for (const filename of readdirSync(aiPromptsDir)) {
+			if (!filename.endsWith(".md")) continue;
+
+			this.emitFile({
+				type: "asset",
+				fileName: `prompts/${filename}`,
+				source: readFileSync(resolve(aiPromptsDir, filename), "utf-8"),
+			});
+		}
+	},
+};
+
+export default defineConfig({
+	entry: { index: "src/index.ts", vercel: "src/vercel.ts", "prepare-deployment": "src/prepare-deployment.ts" },
+	// Keep import.meta.url-based asset lookup adjacent to the entrypoints.
+	outputOptions: { chunkFileNames: "[name]-[hash].mjs" },
+	format: "esm",
+	platform: "node",
+	target: "node24",
+	outDir: "dist",
+	clean: true,
+	shims: true,
+	dts: false,
+	define: { __APP_VERSION__: JSON.stringify(rootPackageJson.version ?? "0.0.0") },
+	// The flagged dynamic imports are deliberate: they defer evaluation of env-dependent
+	// modules so tests can run without env vars, not to split chunks.
+	suppressWarnings: [/dynamic import will not move module into another chunk/],
+	outExtensions: () => ({ js: ".mjs" }),
+	deps: {
+		alwaysBundle: [/^@reactive-resume\//, ...bundledInteropPackages],
+		neverBundle: shouldExternalizeThirdParty,
+	},
+	plugins: [promptAssetsPlugin],
+});

apps/server/turbo.json

@@ -0,0 +1,13 @@
+{
+	"extends": ["//"],
+	"tags": ["app:server", "runtime:server", "role:adapter"],
+	"tasks": {
+		"test": { "env": ["OAUTH_TEST_DATABASE_URL"] },
+		"test:coverage": { "env": ["OAUTH_TEST_DATABASE_URL"] },
+		"test:agent": { "env": ["OAUTH_TEST_DATABASE_URL"] },
+		"test:ci": {
+			"cache": false,
+			"env": ["OAUTH_TEST_DATABASE_URL"]
+		}
+	}
+}

apps/server/vitest.config.ts

@@ -0,0 +1,8 @@
+import { fileURLToPath } from "node:url";
+// @boundaries-ignore root shared Vitest config
+import { createVitestProjectConfig } from "../../vitest.shared.mts";
+
+export default createVitestProjectConfig({
+	name: "server",
+	dirname: fileURLToPath(new URL(".", import.meta.url)),
+});

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/index.html

@@ -0,0 +1,62 @@
+<!doctype html>
+<html lang="en" class="dark">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<meta name="theme-color" content="#09090B" />
+		<meta name="application-name" content="Reactive Resume" />
+		<meta name="mobile-web-app-capable" content="yes" />
+		<meta name="apple-mobile-web-app-capable" content="yes" />
+		<meta name="apple-mobile-web-app-title" content="Reactive Resume" />
+		<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
+		<!-- Keep under ~120 characters so Google's mobile SERP snippet is not truncated at 3 lines. -->
+		<meta name="description" content="Free, open-source resume builder. Create, update, and share a professional resume in minutes — no ads, no paywall.">
+
+		<link rel="icon" href="/favicon.ico" type="image/x-icon" sizes="128x128" />
+		<link rel="icon" href="/favicon.svg" type="image/svg+xml" sizes="256x256 any" />
+		<link rel="apple-touch-icon" href="/apple-touch-icon-180x180.png" type="image/png" sizes="180x180 any" />
+		<link rel="manifest" href="/manifest.webmanifest" crossorigin="use-credentials" />
+
+		<title>Reactive Resume — A free and open-source resume builder</title>
+	</head>
+	<body>
+		<!-- Keep #app empty: main.tsx only mounts React when rootElement has no children. -->
+		<div id="app"></div>
+		<!-- Branded first paint; hidden once React populates #app (higher-specificity rule below). -->
+		<div id="initial-loader">
+			<img src="/icon/dark.svg" width="48" height="48" alt="Reactive Resume" />
+			<div class="initial-loader__spinner"></div>
+			<span class="initial-loader__sr-only">Loading</span>
+		</div>
+		<style>
+			@keyframes app-spin { to { transform: rotate(360deg) } }
+			#initial-loader {
+				position: fixed;
+				inset: 0;
+				display: flex;
+				flex-direction: column;
+				align-items: center;
+				justify-content: center;
+				gap: 24px;
+				background: #09090b;
+			}
+			#app:not(:empty) ~ #initial-loader { display: none; }
+			.initial-loader__spinner {
+				width: 24px;
+				height: 24px;
+				border: 2px solid rgba(250, 250, 250, 0.2);
+				border-top-color: #fafafa;
+				border-radius: 9999px;
+				animation: app-spin 0.7s linear infinite;
+			}
+			.initial-loader__sr-only {
+				position: absolute;
+				width: 1px;
+				height: 1px;
+				overflow: hidden;
+				clip: rect(0 0 0 0);
+			}
+		</style>
+		<script type="module" data-cfasync="false" src="/src/main.tsx"></script>
+	</body>
+</html>

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,9 +65,9 @@ export default defineConfig({
 		"zu-ZA": "en-US",
 		default: "en-US",
 	},
-	formatOptions: {
+	format: formatter({
 		lineNumbers: false,
-	},
+	}),
 	catalogs: [
 		{
 			path: "<rootDir>/locales/{locale}",