chore(release): v5.1.7

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

.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,33 +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": [
-        "oxc.oxc-vscode",
-        "bradlc.vscode-tailwindcss",
-        "lokalise.i18n-ally",
-        "typescriptteam.native-preview"
-      ],
-      "settings": {
-        "editor.defaultFormatter": "oxc.oxc-vscode",
-        "editor.codeActionsOnSave": {
-          "source.fixAll.oxc": "always"
-        }
-      }
-    }
-  },
-
-  "postCreateCommand": "corepack enable && pnpm install"
-}

.devcontainer/docker-compose.yml

@@ -1,95 +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,93 +1,117 @@
-# --- 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"
-
-# --- Printer ---
-PRINTER_ENDPOINT="ws://localhost:4000?token=change-me"
-
 # --- 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"
 
 # --- 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=""
 
 # 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_DYNAMIC_CLIENT_REDIRECT_HOSTS=""
+OAUTH_TOKEN_URL=""
+OAUTH_USER_INFO_URL=""
 
-# AI provider base URL allowlist (optional, comma-separated hosts/origins)
-# Example: api.openai.com,https://gateway.ai.vercel.com
-AI_ALLOWED_BASE_URLS=""
+# 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.
+# If all S3 keys are disabled, the app uses local filesystem storage instead.
 # Make sure to mount this directory to a volume or the host filesystem to ensure data integrity.
+# LOCAL_STORAGE_PATH overrides where local uploads/cache are written.
+# Defaults to /app/data in the official Docker image; in dev, defaults to <workspace>/data.
+# LOCAL_STORAGE_PATH="/app/data"
 
 # Seaweedfs
 S3_ACCESS_KEY_ID="seaweedfs"
 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 only for the authenticated /agent workspace and saved AI providers.
+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"
 
+# 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 ---
+# Crowdin (optional)
+# For translation tooling.
 CROWDIN_PROJECT_ID=""
-CROWDIN_API_TOKEN=""
+CROWDIN_API_TOKEN=""

.gitattributes

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

.github/.well-known/funding.json

@@ -1,68 +1,68 @@
 {
-  "$schema": "https://fundingjson.org/schema/v1.1.0.json",
-  "version": "v1.1.0",
-  "entity": {
-    "type": "individual",
-    "role": "maintainer",
-    "name": "Amruth Pillai",
-    "email": "im.amruth@gmail.com",
-    "description": "Software Engineer",
-    "webpageUrl": {
-      "url": "https://rxresu.me/funding.json"
-    }
-  },
-  "projects": [
-    {
-      "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.",
-      "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"
-      },
-      "licenses": ["spdx:MIT"],
-      "tags": ["data", "design", "productivity", "resume-builder"]
-    }
-  ],
-  "funding": {
-    "plans": [
-      {
-        "guid": "sponsor",
-        "status": "active",
-        "name": "Sponsor",
-        "description": "Support the project on a recurring basis by becoming a sponsor.",
-        "amount": 10,
-        "currency": "EUR",
-        "frequency": "monthly",
-        "channels": ["github", "open-collective"]
-      },
-      {
-        "guid": "donation",
-        "status": "active",
-        "name": "Donation",
-        "description": "Show your support for the project by making a one-time donation.",
-        "amount": 0,
-        "currency": "EUR",
-        "frequency": "one-time",
-        "channels": ["github", "open-collective"]
-      }
-    ],
-    "channels": [
-      {
-        "guid": "github",
-        "type": "payment-provider",
-        "description": "GitHub Sponsors",
-        "address": "https://github.com/sponsors/AmruthPillai"
-      },
-      {
-        "guid": "open-collective",
-        "type": "payment-provider",
-        "description": "Open Collective",
-        "address": "https://opencollective.com/reactive-resume"
-      }
-    ]
-  }
+	"$schema": "https://fundingjson.org/schema/v1.1.0.json",
+	"version": "v1.1.0",
+	"entity": {
+		"type": "individual",
+		"role": "maintainer",
+		"name": "Amruth Pillai",
+		"email": "hello@amruthpillai.com",
+		"description": "Software Engineer",
+		"webpageUrl": {
+			"url": "https://rxresu.me/funding.json"
+		}
+	},
+	"projects": [
+		{
+			"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.",
+			"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"
+			},
+			"licenses": ["spdx:MIT"],
+			"tags": ["data", "design", "productivity", "resume-builder"]
+		}
+	],
+	"funding": {
+		"plans": [
+			{
+				"guid": "sponsor",
+				"status": "active",
+				"name": "Sponsor",
+				"description": "Support the project on a recurring basis by becoming a sponsor.",
+				"amount": 10,
+				"currency": "EUR",
+				"frequency": "monthly",
+				"channels": ["github", "open-collective"]
+			},
+			{
+				"guid": "donation",
+				"status": "active",
+				"name": "Donation",
+				"description": "Show your support for the project by making a one-time donation.",
+				"amount": 0,
+				"currency": "EUR",
+				"frequency": "one-time",
+				"channels": ["github", "open-collective"]
+			}
+		],
+		"channels": [
+			{
+				"guid": "github",
+				"type": "payment-provider",
+				"description": "GitHub Sponsors",
+				"address": "https://github.com/sponsors/AmruthPillai"
+			},
+			{
+				"guid": "open-collective",
+				"type": "payment-provider",
+				"description": "Open Collective",
+				"address": "https://opencollective.com/reactive-resume/donate"
+			}
+		]
+	}
 }

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

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

.github/workflows/autofix.yml

@@ -19,20 +19,23 @@ jobs:
       - name: Checkout Repository
         uses: actions/checkout@v6
 
-      - name: Setup Vite+
-        uses: voidzero-dev/setup-vp@v1
+      - name: Install pnpm
+        uses: pnpm/action-setup@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
         with:
-          node-version: "24"
-          cache: true
+          node-version: "lts/*"
+          cache: "pnpm"
 
       - name: Install Dependencies
-        run: vp install --frozen-lockfile
+        run: pnpm install --frozen-lockfile
 
-      - name: Run Tests
-        run: vp test
+      - name: Remove Unused Dependencies
+        run: pnpm knip --fix
 
-      - name: Run Lint and Format
-        run: vp check --fix
+      - name: Lint and Format
+        run: pnpm check
 
       - name: Autofix
         uses: autofix-ci/action@7a166d7532b277f34e16238930461bf77f9d7ed8

.github/workflows/docker-build.yml

@@ -2,6 +2,11 @@ name: Build Docker Image
 
 on:
   workflow_dispatch:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*"
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -12,17 +17,34 @@ env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
+  mode:
+    runs-on: ubuntu-latest
+
+    outputs:
+      nightly: ${{ steps.mode.outputs.nightly }}
+      release: ${{ steps.mode.outputs.release }}
+      matrix: ${{ steps.mode.outputs.matrix }}
+
+    steps:
+      - name: Determine publishing mode
+        id: mode
+        run: |
+          if [[ "${{ github.event_name }}" == "push" && "${{ github.ref }}" == "refs/heads/main" ]]; then
+            echo "nightly=true" >> "$GITHUB_OUTPUT"
+            echo "release=false" >> "$GITHUB_OUTPUT"
+            echo 'matrix={"include":[{"platform":"linux/amd64","runner":"ubuntu-latest","arch":"amd64"}]}' >> "$GITHUB_OUTPUT"
+          else
+            echo "nightly=false" >> "$GITHUB_OUTPUT"
+            echo "release=true" >> "$GITHUB_OUTPUT"
+            echo 'matrix={"include":[{"platform":"linux/amd64","runner":"ubuntu-latest","arch":"amd64"},{"platform":"linux/arm64","runner":"ubuntu-24.04-arm","arch":"arm64"}]}' >> "$GITHUB_OUTPUT"
+          fi
+
   build:
+    needs: mode
+
     strategy:
       fail-fast: false
-      matrix:
-        include:
-          - platform: linux/amd64
-            runner: ubuntu-latest
-            arch: amd64
-          - platform: linux/arm64
-            runner: ubuntu-24.04-arm
-            arch: arm64
+      matrix: ${{ fromJSON(needs.mode.outputs.matrix) }}
 
     runs-on: ${{ matrix.runner }}
     timeout-minutes: 30
@@ -97,7 +119,9 @@ jobs:
           retention-days: 1
 
   merge:
-    needs: build
+    needs:
+      - mode
+      - build
     timeout-minutes: 30
     runs-on: ubuntu-latest
 
@@ -160,16 +184,25 @@ jobs:
             docker.io/${{ env.IMAGE }}
           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=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"
+          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" \
@@ -184,8 +217,9 @@ jobs:
             $(printf 'docker.io/${{ env.IMAGE }}@sha256:%s ' *)
 
           # Get the digest of the multi-arch manifest
-          GHCR_DIGEST=$(docker buildx imagetools inspect ghcr.io/${{ env.IMAGE }}:v${{ steps.version.outputs.version }} --format '{{json .Manifest.Digest}}' | tr -d '"')
-          DOCKER_DIGEST=$(docker buildx imagetools inspect docker.io/${{ env.IMAGE }}:v${{ steps.version.outputs.version }} --format '{{json .Manifest.Digest}}' | tr -d '"')
+          GHCR_DIGEST=$(docker buildx imagetools inspect ghcr.io/${{ env.IMAGE }}:${FINAL_TAG} --format '{{json .Manifest.Digest}}' | tr -d '"')
+          DOCKER_DIGEST=$(docker buildx imagetools inspect docker.io/${{ env.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"
 
@@ -202,10 +236,11 @@ jobs:
 
       - 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 ghcr.io/${{ env.IMAGE }}:${{ steps.manifest.outputs.final_tag }}
+          docker buildx imagetools inspect docker.io/${{ env.IMAGE }}:${{ steps.manifest.outputs.final_tag }}
 
       - name: Redeploy Stack
+        if: ${{ needs.mode.outputs.release == 'true' }}
         uses: appleboy/ssh-action@v1
         with:
           key: ${{ secrets.SSH_KEY }}

.gitignore

@@ -1,21 +1,58 @@
-dist
-.env*
-/data
-.nitro
-.agents
-.output
-.vercel
-.cursor
-.claude
-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
+
+# Cache
+tmp
+temp
+.cache
+
+# AI
+.codex
+.agents
+.claude
+.cursor
+.codegraph
+.superpowers
+
+# Local Storage Data
+/data
+/apps/web/data
+
+# Git Hooks
+.vite-hooks/

.ncurc.cjs

@@ -1,17 +1,17 @@
 // @ts-check
 
-const nextPackages = ["@monaco-editor/react"];
-
-const betaPackages = ["drizzle-orm", "drizzle-kit", "drizzle-zod"];
+const betaPackages = ["drizzle-zod"];
+const rcPackages = ["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";
-  },
+	upgrade: true,
+	workspaces: true,
+	install: "always",
+	packageManager: "pnpm",
+	target: (packageName) => {
+		if (betaPackages.includes(packageName)) return "@beta";
+		if (rcPackages.includes(packageName)) return "@rc";
+		return "latest";
+	},
 };

.vite-hooks/pre-commit

@@ -1 +0,0 @@
-vp staged

.vscode/extensions.json

@@ -1,9 +1,3 @@
 {
-  "recommendations": [
-    "oxc.oxc-vscode",
-    "bradlc.vscode-tailwindcss",
-    "lokalise.i18n-ally",
-    "typescriptteam.native-preview",
-    "VoidZero.vite-plus-extension-pack"
-  ]
+	"recommendations": ["biomejs.biome", "bradlc.vscode-tailwindcss", "typescriptteam.native-preview"]
 }

.vscode/settings.json

@@ -1,41 +1,31 @@
 {
-  "editor.defaultFormatter": "oxc.oxc-vscode",
-  "editor.codeActionsOnSave": {
-    "source.organizeImports": "explicit",
-    "source.fixAll.oxc": "explicit"
-  },
-  "editor.formatOnSave": true,
-  "editor.formatOnSaveMode": "file",
-  "files.associations": {
-    "*.css": "tailwindcss"
-  },
-  "files.readonlyInclude": {
-    "**/routeTree.gen.ts": true,
-    "pnpm-lock.yaml": true
-  },
-  "files.watcherExclude": {
-    "**/routeTree.gen.ts": true,
-    "locales/**.po": true,
-    "pnpm-lock.yaml": true
-  },
-  "i18n-ally.enabledParsers": ["po"],
-  "i18n-ally.localesPaths": ["locales"],
-  "i18n-ally.sourceLanguage": "en-US",
-  "oxc.enable.oxfmt": true,
-  "oxc.enable.oxlint": true,
-  "oxc.configPath": "./vite.config.ts",
-  "oxc.fmt.configPath": "./vite.config.ts",
-  "search.exclude": {
-    "**/routeTree.gen.ts": true,
-    "locales/**.po": true,
-    "pnpm-lock.yaml": true
-  },
-  "tailwindCSS.classFunctions": ["cn", "cva"],
-  "tailwindCSS.experimental.classRegex": [
-    ["class:\\s*?[\"'`]([^\"'`]*).*?,"],
-    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"],
-    ["cn\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
-  ],
-  "tailwindCSS.experimental.configFile": "src/styles/globals.css",
-  "typescript.experimental.useTsgo": true
+	"biome.enabled": true,
+	"editor.codeActionsOnSave": {
+		"source.fixAll.biome": "explicit",
+		"source.organizeImports.biome": "explicit"
+	},
+	"editor.defaultFormatter": "biomejs.biome",
+	"files.readonlyInclude": {
+		"**/locales/**.po": true,
+		"**/routeTree.gen.ts": true,
+		"pnpm-lock.yaml": true
+	},
+	"files.watcherExclude": {
+		"**/locales/**.po": true,
+		"**/routeTree.gen.ts": true,
+		"pnpm-lock.yaml": true
+	},
+	"search.exclude": {
+		"**/locales/**.po": true,
+		"**/routeTree.gen.ts": true,
+		"pnpm-lock.yaml": true
+	},
+	"tailwindCSS.classFunctions": ["cn", "cva"],
+	"tailwindCSS.experimental.classRegex": [
+		["class:\\s*?[\"'`]([^\"'`]*).*?,"],
+		["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"],
+		["cn\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
+	],
+	"tailwindCSS.experimental.configFile": "src/styles/globals.css",
+	"typescript.experimental.useTsgo": true
 }

AGENTS.md

@@ -1,131 +1,157 @@
-## Overview
+# AGENTS.md
 
-Reactive Resume is a single-package full-stack TypeScript app (not a monorepo) built with [TanStack Start](https://tanstack.com/start/latest/docs/framework/react/overview) (React, Vite, Nitro). It serves both frontend and API on port 3000.
+## Cursor Cloud specific instructions
 
-This project uses [Vite+](https://vite.dev/blog/announcing-viteplus), a unified toolchain built on top of Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task. Vite+ wraps runtime management, package management, and frontend tooling in a single global CLI called `vp`. All modules should be imported from the `vite-plus` dependency (e.g., `import { defineConfig } from 'vite-plus'` or `import { expect, test, vi } from 'vite-plus/test'`).
+### Overview
 
-## Key Libraries
+Reactive Resume is a pnpm monorepo (Turborepo) with two deployable apps: `apps/web` (TanStack Start / React 19 / Vite) and `apps/server` (Hono / Node.js). The production Docker image runs a single Node.js process on port 3000, with `apps/server` mounting the API/auth/MCP/static routes and serving the built web app.
 
-| Area                 | Library                                                                  | Docs                               |
-| -------------------- | ------------------------------------------------------------------------ | ---------------------------------- |
-| Frontend framework   | React                                                                    | https://react.dev                  |
-| Full-stack framework | TanStack Start                                                           | https://tanstack.com/start/latest  |
-| Router               | TanStack React Router                                                    | https://tanstack.com/router/latest |
-| Server state         | TanStack React Query                                                     | https://tanstack.com/query/latest  |
-| Client state         | Zustand (+ Zundo for undo/redo, Immer for immutable updates)             | https://zustand.docs.pmnd.rs       |
-| Type-safe API        | oRPC                                                                     | https://orpc.unnoq.com             |
-| Database ORM         | Drizzle ORM (PostgreSQL)                                                 | https://orm.drizzle.team           |
-| Authentication       | Better Auth (+ Drizzle adapter, OAuth provider, API keys, 2FA, Passkeys) | https://www.better-auth.com        |
-| Styling              | Tailwind CSS                                                             | https://tailwindcss.com            |
-| UI Components        | shadcn/ui (built on Base UI)                                             | https://ui.shadcn.com              |
-| Icons                | Phosphor Icons                                                           | https://phosphoricons.com          |
-| Forms                | React Hook Form (+ Zod resolvers)                                        | https://react-hook-form.com        |
-| Rich text editor     | Tiptap                                                                   | https://tiptap.dev                 |
-| Validation           | Zod                                                                      | https://zod.dev                    |
-| AI                   | Vercel AI SDK (OpenAI, Anthropic, Google, Ollama providers)              | https://ai-sdk.dev                 |
-| MCP                  | Model Context Protocol SDK                                               | https://modelcontextprotocol.io    |
-| i18n                 | Lingui                                                                   | https://lingui.dev                 |
-| Animations           | Motion (Framer Motion)                                                   | https://motion.dev                 |
-| PDF export           | Puppeteer Core (via Browserless)                                         | https://pptr.dev                   |
-| Drag and drop        | dnd-kit                                                                  | https://dndkit.com                 |
-| Server engine        | Nitro                                                                    | https://nitro.build                |
-| PWA                  | Vite PWA Plugin                                                          | https://vite-pwa-org.netlify.app   |
-| Unused deps          | Knip                                                                     | https://knip.dev                   |
+Internal packages are source-consumed through `package.json` export maps that point at `src` files. Do not assume package-local `dist` output exists unless a package explicitly adds it.
 
-## Project Structure
+### Prerequisites
 
-```
-src/
-  components/     UI, resume, layout, animation, theme, locale components
-  routes/         File-based routing (TanStack React Router)
-  integrations/   Feature modules (auth, drizzle, orpc, ai, email, jobs, mcp, storage)
-  schema/         Zod schemas for resume data validation
-  utils/          Utility functions (locale, theme, env, resume processing)
-  dialogs/        Modal/dialog components
-  hooks/          Custom React hooks
-  styles/         CSS and Tailwind configuration
-  stores/         Zustand stores (resume, AI, dialog, command palette)
-migrations/       Drizzle database migrations
-locales/          Lingui i18n message catalogs (47+ locales)
+- **Node.js 24** (matches Dockerfile `ARG NODE_VERSION=24`). Use `nvm install 24 && nvm use 24` if needed.
+- **Docker** is required to run PostgreSQL. Start it with `sudo dockerd &` if the daemon isn't running.
+- **pnpm 11.1.2** is managed via corepack (`corepack enable`).
+
+### Codebase map
+
+- `apps/web` owns TanStack Start routes, Vite config, PWA setup, oRPC browser client wiring, web features, and the resume builder UI.
+- `apps/server` owns the production Hono app, route composition, auth/RPC/MCP/OpenAPI handlers, static uploads, schema JSON, web-dist fallback serving, and startup checks.
+- `packages/api` contains oRPC routers, DTOs, rate limiting, and feature-owned API modules under `packages/api/src/features/*`. The router export at `@reactive-resume/api/routers` aggregates those feature routers for `/api/rpc`.
+- `packages/auth` contains Better Auth config, auth helper functions, and exported auth types. The server auth adapter in `apps/server/src/http/auth.ts` delegates to `auth.handler`.
+- `packages/db` contains the Drizzle client and schema. Migration files live at the repo root in `migrations/`.
+- `packages/env` defines server environment validation and auto-loads the root `.env` for app/server code.
+- `packages/schema` contains Zod schemas and typed resume/page/template models.
+- `packages/pdf` contains the React PDF document, font registration, shared template primitives, template implementations, and browser/server PDF generation adapters. PDF.js viewer UI stays in `apps/web`.
+- `packages/resume` contains pure resume-domain behavior such as JSON Patch helpers and social-network icon mapping.
+- `packages/docx` contains DOCX export generation.
+- `packages/mcp` contains MCP tools, prompts, resources, server-card generation, and tool metadata.
+- `packages/ui` contains shared Base UI/shadcn-style components and hooks.
+- `packages/fonts`, `packages/email`, `packages/import`, `packages/ai`, `packages/utils`, and `packages/config` provide focused support surfaces. Prefer their existing exports over adding cross-package shortcuts.
+- Development-only scripts live in `tooling/`, not under `packages/`, so packages only contain code bundled by the app/runtime.
+
+### Web app conventions
+
+- Routes are file-based under `apps/web/src/routes`. Do not hand-edit `apps/web/src/routeTree.gen.ts`; it is generated by TanStack Router tooling.
+- Server-owned HTTP behavior lives in `apps/server/src/{http,rpc,mcp,openapi,static,startup}`. Keep API/RPC/auth/MCP/static route wiring in `apps/server`, not in web routes.
+- `apps/web/src/router.tsx` initializes router context with `queryClient`, `orpc`, `theme`, `locale`, `session`, and `flags`. Reuse route context where possible instead of refetching these concerns ad hoc.
+- The builder shell lives under `apps/web/src/routes/builder/$resumeId`. The nested preview route is client-only (`ssr: false`), while the public resume route `apps/web/src/routes/$username/$slug.tsx` uses `ssr: "data-only"`.
+- Browser-only resume preview code lives under `apps/web/src/features/resume/preview`, and public resume PDF viewer code lives under `apps/web/src/features/resume/public`. Keep PDF.js/canvas/browser APIs out of SSR paths and out of `packages/pdf`.
+- The isomorphic oRPC client is in `apps/web/src/libs/orpc/client.ts`; server calls use an in-process router client and browser calls use `/api/rpc` with credentials included.
+- For React components with explicit props, prefer a named TypeScript props type over inline object annotations in the function signature, especially once the props include more than one field or generics. For example:
+
+```ts
+type IntentSelectFieldProps<TValue extends string> = {
+	label: string;
+	id: string;
+	value: TValue | undefined;
+	options: readonly ComboboxOption<TValue>[];
+	onChange: (value: TValue | undefined) => void;
+};
+
+function IntentSelectField<TValue extends string>(props: IntentSelectFieldProps<TValue>) {
+	// ...
+}
 ```
 
-### Key Config Files
+### Package and feature boundaries
 
-- `vite.config.ts` — Vite + Nitro + TanStack Start + PWA + Tailwind + Lingui
-- `drizzle.config.ts` — PostgreSQL dialect, schema at `./src/integrations/drizzle/schema.ts`
-- `tsconfig.json` — ES2022, strict mode, path alias `@/*` → `./src/*`
-- `lingui.config.ts` — i18n extraction and locale configuration
-- `components.json` — shadcn CLI configuration
+- Workspace dependencies must go through package names and package export maps. Do not import another workspace's `src` tree through repository paths, `@reactive-resume/*/src/*`, or TypeScript path aliases.
+- `turbo boundaries` is the executable package-boundary check. Workspace-level `turbo.json` files declare coarse tags:
+  - `app:web` for the TanStack Start app.
+  - `app:server` and `runtime:server` for the Node/Hono process.
+  - `runtime:server` for server-only packages such as API/auth/db/env/email/MCP.
+  - `runtime:browser` for browser-only shared UI.
+  - `runtime:universal` for environment-neutral domain packages.
+  - `role:domain`, `role:infra`, `role:adapter`, `role:api`, `role:rendering`, and `role:tooling` for package intent.
+- Browser/server runtime-specific code should live behind explicit export subpaths such as `@reactive-resume/pdf/browser`, `@reactive-resume/pdf/server`, or `@reactive-resume/env/server`. Keep root exports environment-neutral unless the package is intentionally server-only.
+- Wildcard exports are allowed only for leaf libraries whose public surface is intentionally file-like, currently `@reactive-resume/ui/components/*`, `@reactive-resume/ui/hooks/*`, and schema resume model files. Prefer explicit exports for packages that own runtime behavior.
+- Add new API procedures and business logic inside the owning `packages/api/src/features/*` module. Keep route wiring, DTO usage, helpers, and services colocated by feature/capability, then expose only intentional public surfaces through `packages/api/package.json`. Prefer `protectedProcedure` from `packages/api/src/context.ts` for authenticated procedures.
+- Add database columns/tables in `packages/db/src/schema/*`, then generate root-level migrations with `dotenvx run -f .env.local -- pnpm db:generate`.
+- Add or change resume data shape in `packages/schema/src/resume/*` first, then update API DTOs, importers, PDF rendering, and web forms that consume that shape.
+- Add or rename templates in all relevant places: `packages/schema/src/templates.ts`, `packages/pdf/src/templates/index.ts`, template source under `packages/pdf/src/templates/<name>/`, and static previews under `apps/web/public/templates/{jpg,pdf}`.
+- Resume JSON Patch behavior belongs in `@reactive-resume/resume/patch`; do not put resume-domain helpers in `@reactive-resume/utils`.
+- DOCX export behavior belongs in `@reactive-resume/docx`; do not put DOCX builders in `@reactive-resume/utils`.
+- Shared PDF section filtering lives in `packages/pdf/src/templates/shared/filtering.ts`. Keep template-specific visual exceptions in the owning template directory unless multiple templates need the same behavior.
+- `packages/pdf/src/hooks/use-register-fonts.ts` owns React PDF font registration, standard PDF font handling, CJK fallback stacks, and global hyphenation behavior.
+- PDF generation helpers live behind `@reactive-resume/pdf/browser` and `@reactive-resume/pdf/server`; locale-specific section-title resolution stays in the caller.
+- MCP implementation belongs in `@reactive-resume/mcp`; app packages must not import MCP implementation from another app's source tree.
+- `packages/utils` has narrowly exported helpers. If another package needs a utility, add an explicit export path instead of importing private files.
 
-### API Architecture
+Placement decision tree:
 
-- **oRPC API** (`/api/rpc/*`) — Type-safe RPC with routers for: `ai`, `auth`, `resume`, `storage`, `printer`, `jobs`, `statistics`, `flags`. Three procedure types: `publicProcedure`, `protectedProcedure`, `serverOnlyProcedure`.
-- **Better Auth API** (`/api/auth/*`) — OAuth, session management, social provider callbacks.
-- **MCP Server** (`/mcp/`) — Model Context Protocol with OAuth Bearer tokens and API key auth. Exposes resumes as resources and tools for resume CRUD.
+1. If the change is a web route, route loader, or user-facing web workflow, start in `apps/web/src/routes` or `apps/web/src/features`.
+2. If the change is a server HTTP route/adapter, startup check, static handler, MCP transport, or OpenAPI/well-known handler, start in `apps/server/src`.
+3. If it is authenticated API behavior, put the contract and implementation in the owning `packages/api/src/features/*` module.
+4. If it is pure resume data behavior with no DB, HTTP, DOM, or PDF renderer dependency, put it in `packages/resume`.
+5. If it renders resume PDFs, put shared React PDF/template code in `packages/pdf`; put PDF.js viewer/canvas UI in `apps/web/src/features/resume`.
+6. If it creates DOCX exports, put it in `packages/docx`.
+7. If it exposes MCP tools/prompts/resources, put it in `packages/mcp`.
+8. If it is a generic UI primitive or hook, put it in `packages/ui`; if it is workflow-specific UI, keep it in the owning web feature.
+9. If it is a narrow cross-cutting helper, add an explicit `packages/utils` export only after checking that no domain package is a better owner.
 
-## Infrastructure Services
+### Database
 
-Before running the dev server, Docker must be running with at least PostgreSQL. Start services via `compose.dev.yml`:
+PostgreSQL runs via Docker Compose:
 
-```bash
-sudo dockerd &>/var/log/dockerd.log &
-sudo docker compose -f compose.dev.yml up -d postgres browserless
+```
+sudo docker compose -f compose.dev.yml up -d postgres
 ```
 
-- **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.
+The dev default connection string is `postgresql://postgres:postgres@localhost:5432/postgres`.
 
-## Environment Variables
+**Important**: `drizzle-kit` (used by `pnpm db:migrate`) reads `DATABASE_URL` from `process.env` directly — it does **not** auto-load the `.env` file. Run migration commands through `dotenvx`, for example `dotenvx run -f .env.local -- pnpm db:migrate`, so `DATABASE_URL` is present in the process environment.
 
-Copy `.env.example` to `.env` if not present. Key notes for local dev:
+The production server runs migrations during startup before serving traffic. Manual `pnpm db:migrate` is mainly for first setup, migration debugging, or applying migrations without starting the app.
 
-- `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.
+### Environment
 
-## Common Commands
+Copy `.env.example` to `.env`. The three required variables are:
 
-`vp` is the global CLI for Vite+. Do not use pnpm/npm/yarn directly — Vite+ wraps the underlying package manager.
+- `APP_URL` (default `http://localhost:3000`)
+- `DATABASE_URL` (default `postgresql://postgres:postgres@localhost:5432/postgres`)
+- `AUTH_SECRET` (any non-empty string)
 
-| Task                          | Command                                                         |
-| ----------------------------- | --------------------------------------------------------------- |
-| Install dependencies          | `vp install`                                                    |
-| Dev server (port 3000)        | `vp dev`                                                        |
-| Lint (Oxlint, type-aware)     | `vp lint --type-aware`                                          |
-| Format (Oxfmt)                | `vp fmt`                                                        |
-| Check (lint + format + types) | `vp check`                                                      |
-| Typecheck                     | `pnpm typecheck` (uses tsgo)                                    |
-| Run tests                     | `vp test`                                                       |
-| DB migrations                 | `pnpm db:generate` / `pnpm db:migrate` (auto-runs on dev start) |
-| DB studio                     | `pnpm db:studio`                                                |
-| i18n extraction               | `pnpm lingui:extract`                                           |
-| Add a dependency              | `vp add <package>`                                              |
-| Remove a dependency           | `vp remove <package>`                                           |
-| One-off binary                | `vp dlx <package>`                                              |
-| Build for production          | `vp build`                                                      |
-| Preview production build      | `vp preview`                                                    |
-| Start production server       | `pnpm start`                                                    |
+S3/SeaweedFS is optional. If `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, and `S3_BUCKET` are all set, the app uses S3-compatible storage. The checked-in `.env.example` sets SeaweedFS defaults, so either start the `seaweedfs` compose service too or comment out those S3 vars to use local filesystem storage under `<workspace>/data`. `LOCAL_STORAGE_PATH` must be absolute when set.
 
-## Vite+ Pitfalls
+When running dev servers or migration commands, prefix the command with `dotenvx run -f .env.local --`. For example: `dotenvx run -f .env.local -- pnpm dev`. Tests, typechecks, linters, boundary checks, and `pnpm build` do not need this prefix by default. If one of those commands fails because a specific environment variable is required, rerun it with the `dotenvx run -f .env.local --` prefix.
 
-- **Do not use pnpm/npm/yarn directly** for package operations — use `vp add`, `vp remove`, `vp install`, etc.
-- **Do not run `vp vitest` or `vp oxlint`** — they don't exist. Use `vp test` and `vp lint`.
-- **Do not install Vitest, Oxlint, Oxfmt, or tsdown directly** — Vite+ bundles them.
-- **Import from `vite-plus`**, not from `vite` or `vitest` directly (e.g., `import { defineConfig } from 'vite-plus'`).
-- **Vite+ commands take precedence** over `package.json` scripts. If there's a naming conflict, use `vp run <script>`.
-- **Use `vp dlx`** instead of `npx` or `pnpm dlx`.
-- **Type-aware linting** works out of the box with `vp lint --type-aware` — no need to install `oxlint-tsgolint`.
+### Common commands
 
-## Gotchas
+| Task | Command |
+|------|---------|
+| Install deps | `pnpm install` |
+| Start Postgres only | `sudo docker compose -f compose.dev.yml up -d postgres` |
+| Start Postgres + SeaweedFS | `sudo docker compose -f compose.dev.yml up -d postgres seaweedfs seaweedfs_create_bucket` |
+| Generate migrations | `dotenvx run -f .env.local -- pnpm db:generate` |
+| Run migrations | `dotenvx run -f .env.local -- pnpm db:migrate` |
+| Dev server | `dotenvx run -f .env.local -- pnpm dev` (starts on port 3000) |
+| Web dev server only | `dotenvx run -f .env.local -- pnpm dev:web` |
+| Lint/format | `pnpm check` (Biome) |
+| Boundary check | `pnpm exec turbo boundaries` |
+| Tests | `pnpm test` (Vitest) |
+| Build | `pnpm build` |
+| Typecheck | `pnpm typecheck` |
 
-- 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 and Nitro use beta/nightly builds. Occasional upstream issues may occur.
+For focused validation, prefer package filters before repo-wide commands, for example:
 
-## Review Checklist for Agents
+```
+pnpm --filter web typecheck
+pnpm --filter @reactive-resume/pdf test
+pnpm --filter @reactive-resume/api test
+pnpm exec turbo boundaries
+```
 
-- [ ] Run `vp install` after pulling remote changes and before getting started.
-- [ ] Run `pnpm lint:fix`, `pnpm format:fix`, `pnpm typecheck` and `vp test` to validate changes.
+Vitest test paths are package-relative when running through `pnpm --filter <package> test -- <path>`.
+
+### Gotchas
+
+- The server startup path auto-runs migrations before serving traffic, so `pnpm db:migrate` is mainly needed for first-time setup, migration debugging, or applying migrations without starting the app.
+- Email sending requires SMTP config; without it, emails are logged to console. This is fine for dev — the app still functions, but email verification links appear in server logs.
+- The `lefthook.yml` pre-commit hook runs `biome check` on staged files. Run `pnpm check` before committing to avoid hook failures.
+- `pnpm check` is write-capable (`biome check --write --unsafe .`). Call that out when using it, and use narrower Biome commands if you need a non-mutating inspection.
+- Biome uses tabs, double quotes, line width 120, organized import groups, and sorted Tailwind classes for `clsx`, `cva`, and `cn`.
+- Most packages use `tsgo --noEmit` for typechecking and `vitest run --passWithNoTests` for tests.
+- There may be unrelated local edits in the worktree. Inspect `git status --short` first and avoid reverting files you did not touch.
+- **New env vars require a `turbo.json` entry.** Turborepo 2.x runs in strict env mode by default — it filters out env vars that are not listed in `globalEnv` (or task-level `env`/`passThroughEnv`). Any new environment variable added to `packages/env/src/server.ts` must also be added to the `globalEnv` array in `turbo.json`, or the variable will be `undefined` inside child processes at runtime even if it is correctly set in the OS/container environment.

DESIGN.md

@@ -0,0 +1,347 @@
+---
+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
+
+Animations use the Motion library (formerly Framer Motion) and follow a consistent choreography pattern:
+
+**Entrance animations** use a fade-up reveal: elements start at `opacity: 0, y: 20-100` and animate to `opacity: 1, y: 0`. The hero section uses a larger y-offset (100px) for dramatic effect; subsequent sections use 20px for subtlety.
+
+**Timing principles:**
+- **Base duration:** 0.35s–0.6s for standard section reveals, 0.45s for hero elements, up to 1.1s for the hero video entrance.
+- **Stagger pattern:** Sequential delays within a group, typically 0.1s–0.15s apart (hero: 0.55s, 0.7s, 0.82s, 0.95s). For grids, use `index * 0.03`–`0.1` for per-item stagger.
+- **Easing:** `easeOut` for entrances (elements decelerate into position). `easeInOut` for looping/ambient animations.
+- **Performance:** Apply `will-change-[transform,opacity]` on animated elements and `will-change-transform` on continuously animated elements.
+
+**Hover/interaction animations** are quick (0.2s) and subtle — small scale bumps (`scale: 1.01`), slight y-offsets (`y: -2`), and `active:translate-y-px` for button press.
+
+**Ambient animations** loop infinitely with `easeInOut` — the scroll indicator bounces gently (`y: [0, 5, 0]` over 1.5s).
+
+**Reduced motion:** All CSS transitions and animations collapse to `0.01ms` duration and single iteration when `prefers-reduced-motion: reduce` is active. Motion library animations should also respect this preference.
+
+## 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,44 @@
-# syntax=docker/dockerfile:1
+# syntax=docker/dockerfile:1.7
 
-# ---------- Dependencies Layer ----------
-FROM node:24-slim AS dependencies
+ARG NODE_VERSION=24
 
-ENV PNPM_HOME="/pnpm"
-ENV PATH="$PNPM_HOME:$PATH"
-RUN corepack enable
-
-RUN mkdir -p /tmp/dev /tmp/prod
-
-COPY package.json pnpm-lock.yaml /tmp/dev/
-COPY package.json pnpm-lock.yaml /tmp/prod/
-
-RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
-    cd /tmp/dev && pnpm install --frozen-lockfile
-
-RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
-    cd /tmp/prod && pnpm install --frozen-lockfile --prod
-
-# ---------- Builder Layer ----------
-FROM node:24-slim AS builder
-
-ENV PNPM_HOME="/pnpm"
-ENV PATH="$PNPM_HOME:$PATH"
-RUN corepack enable
+FROM node:${NODE_VERSION}-slim AS base
 
 WORKDIR /app
 
-COPY --from=dependencies /tmp/dev/node_modules ./node_modules
+ENV COREPACK_ENABLE_DOWNLOAD_PROMPT=0 \
+    PNPM_HOME="/pnpm" \
+    PATH="/pnpm:$PATH" \
+    TURBO_TELEMETRY_DISABLED=1
+
+RUN corepack enable
+
+FROM base AS pruner
 COPY . .
+RUN --mount=type=cache,id=pnpm-store,target=/pnpm/store,sharing=locked \
+    pnpm dlx turbo@2.9.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"
@@ -44,20 +49,28 @@ 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"
 
-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

@@ -1,21 +1,43 @@
-# syntax=docker/dockerfile:1
+# syntax=docker/dockerfile:1.7
 
-# ---------- Development Layer ----------
-FROM node:24-slim AS development
+ARG NODE_VERSION=24
 
-ENV NODE_ENV="development"
-ENV PNPM_HOME="/pnpm"
-ENV PATH="$PNPM_HOME:$PATH"
-
-RUN corepack enable
+FROM node:${NODE_VERSION}-slim AS dev
 
 WORKDIR /app
 
-COPY package.json pnpm-lock.yaml ./
+ENV COREPACK_ENABLE_DOWNLOAD_PROMPT=0 \
+	PNPM_HOME="/pnpm" \
+	PATH="/pnpm:$PATH" \
+	NODE_ENV=development \
+	TURBO_TELEMETRY_DISABLED=1
 
-RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
-    pnpm install --frozen-lockfile
+RUN corepack enable
 
-EXPOSE 3000
+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"]

README.md

@@ -1,6 +1,6 @@
 <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>
@@ -14,14 +14,14 @@
   </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/package-json/v/amruthpillai/reactive-resume?style=flat-square" alt="Reactive Resume Version">
     <img src="https://img.shields.io/github/stars/amruthpillai/Reactive-Resume?style=flat-square" alt="GitHub Stars">
     <img src="https://img.shields.io/github/license/amruthpillai/Reactive-Resume?style=flat-square" alt="License" />
     <img src="https://img.shields.io/docker/pulls/amruthpillai/reactive-resume?style=flat-square" alt="Docker Pulls" />
     <a href="https://discord.gg/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>
 </div>
 
@@ -36,7 +36,7 @@ Built with privacy as a core principle, Reactive Resume gives you complete owner
 **Resume Building**
 
 - Real-time preview as you type
-- Multiple export formats (PDF, JSON)
+- Multiple export formats (PDF, JSON, DOCX)
 - Drag-and-drop section ordering
 - Custom sections for any content type
 - Rich text editor with formatting support
@@ -69,63 +69,71 @@ Built with privacy as a core principle, Reactive Resume gives you complete owner
 <table>
   <tr>
     <td align="center">
-      <img src="public/templates/jpg/azurill.jpg" alt="Azurill" width="150" />
+      <img src="apps/web/public/templates/jpg/azurill.jpg" alt="Azurill" width="150" />
       <br /><sub><b>Azurill</b></sub>
     </td>
     <td align="center">
-      <img src="public/templates/jpg/bronzor.jpg" alt="Bronzor" width="150" />
+      <img src="apps/web/public/templates/jpg/bronzor.jpg" alt="Bronzor" width="150" />
       <br /><sub><b>Bronzor</b></sub>
     </td>
     <td align="center">
-      <img src="public/templates/jpg/chikorita.jpg" alt="Chikorita" width="150" />
+      <img src="apps/web/public/templates/jpg/chikorita.jpg" alt="Chikorita" width="150" />
       <br /><sub><b>Chikorita</b></sub>
     </td>
     <td align="center">
-      <img src="public/templates/jpg/ditto.jpg" alt="Ditto" width="150" />
+      <img src="apps/web/public/templates/jpg/ditto.jpg" alt="Ditto" width="150" />
       <br /><sub><b>Ditto</b></sub>
     </td>
   </tr>
   <tr>
     <td align="center">
-      <img src="public/templates/jpg/gengar.jpg" alt="Gengar" width="150" />
+      <img src="apps/web/public/templates/jpg/gengar.jpg" alt="Gengar" width="150" />
       <br /><sub><b>Gengar</b></sub>
     </td>
     <td align="center">
-      <img src="public/templates/jpg/glalie.jpg" alt="Glalie" width="150" />
+      <img src="apps/web/public/templates/jpg/glalie.jpg" alt="Glalie" width="150" />
       <br /><sub><b>Glalie</b></sub>
     </td>
     <td align="center">
-      <img src="public/templates/jpg/kakuna.jpg" alt="Kakuna" width="150" />
+      <img src="apps/web/public/templates/jpg/kakuna.jpg" alt="Kakuna" width="150" />
       <br /><sub><b>Kakuna</b></sub>
     </td>
     <td align="center">
-      <img src="public/templates/jpg/lapras.jpg" alt="Lapras" width="150" />
+      <img src="apps/web/public/templates/jpg/lapras.jpg" alt="Lapras" width="150" />
       <br /><sub><b>Lapras</b></sub>
     </td>
   </tr>
   <tr>
     <td align="center">
-      <img src="public/templates/jpg/leafish.jpg" alt="Leafish" width="150" />
+      <img src="apps/web/public/templates/jpg/leafish.jpg" alt="Leafish" width="150" />
       <br /><sub><b>Leafish</b></sub>
     </td>
     <td align="center">
-      <img src="public/templates/jpg/onyx.jpg" alt="Onyx" width="150" />
+      <img src="apps/web/public/templates/jpg/onyx.jpg" alt="Onyx" width="150" />
       <br /><sub><b>Onyx</b></sub>
     </td>
     <td align="center">
-      <img src="public/templates/jpg/pikachu.jpg" alt="Pikachu" width="150" />
+      <img src="apps/web/public/templates/jpg/pikachu.jpg" alt="Pikachu" width="150" />
       <br /><sub><b>Pikachu</b></sub>
     </td>
     <td align="center">
-      <img src="public/templates/jpg/rhyhorn.jpg" alt="Rhyhorn" width="150" />
+      <img src="apps/web/public/templates/jpg/rhyhorn.jpg" alt="Rhyhorn" width="150" />
       <br /><sub><b>Rhyhorn</b></sub>
     </td>
   </tr>
   <tr>
     <td align="center">
-      <img src="public/templates/jpg/ditgar.jpg" alt="Ditgar" width="150" />
+      <img src="apps/web/public/templates/jpg/ditgar.jpg" alt="Ditgar" width="150" />
       <br /><sub><b>Ditgar</b></sub>
     </td>
+    <td align="center">
+      <img src="apps/web/public/templates/jpg/meowth.jpg" alt="Meowth" width="150" />
+      <br /><sub><b>Meowth</b></sub>
+    </td>
+    <td align="center">
+      <img src="apps/web/public/templates/jpg/scizor.jpg" alt="Scizor" width="150" />
+      <br /><sub><b>Scizor</b></sub>
+    </td>
   </tr>
 </table>
 
@@ -135,7 +143,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/amruthpillai/reactive-resume.git
 cd reactive-resume
 
 # Start all services
@@ -160,7 +168,7 @@ For detailed setup instructions, environment configuration, and self-hosting gui
 | API              | ORPC (Type-safe RPC)            |
 | Auth             | Better Auth                     |
 | Styling          | Tailwind CSS                    |
-| UI Components    | Radix UI                        |
+| UI Components    | Base UI + shadcn-style package  |
 | State Management | Zustand + TanStack Query        |
 
 ## Documentation
@@ -180,9 +188,10 @@ Comprehensive guides are available at [docs.rxresu.me](https://docs.rxresu.me):
 Reactive Resume can be self-hosted using 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 now runs entirely client-side via `@react-pdf/renderer`. New deployments no longer require Browserless, Chromium, or any external print service as a dependency. The `PRINTER_*` and `BROWSERLESS_*` environment variables are no longer read and can be removed from your `.env`.
+
 Pull the latest image from Docker Hub or GitHub Container Registry:
 
 ```bash
@@ -203,7 +212,7 @@ Reactive Resume is and always will be free and open-source. If it has helped you
   <a href="https://github.com/sponsors/AmruthPillai">
     <img src="https://img.shields.io/badge/GitHub%20Sponsors-Support-ea4aaa?style=flat-square&logo=github-sponsors" alt="GitHub Sponsors" />
   </a>
-  <a href="https://opencollective.com/reactive-resume">
+  <a href="https://opencollective.com/reactive-resume/donate">
     <img src="https://img.shields.io/badge/Open%20Collective-Contribute-7FADF2?style=flat-square&logo=open-collective" alt="Open Collective" />
   </a>
 </p>

apps/server/package.json

@@ -0,0 +1,88 @@
+{
+	"name": "server",
+	"version": "0.0.0",
+	"type": "module",
+	"private": true,
+	"scripts": {
+		"dev": "tsx watch src/index.ts",
+		"build": "tsdown",
+		"start": "node dist/index.mjs",
+		"typecheck": "tsgo --noEmit",
+		"test": "vitest run --passWithNoTests",
+		"test:coverage": "vitest run --coverage --passWithNoTests",
+		"test:ci": "vitest run --coverage --reporter=default --reporter=github-actions --reporter=json --reporter=junit --outputFile.json=reports/vitest-results.json --outputFile.junit=reports/vitest-junit.xml --passWithNoTests",
+		"test:agent": "vitest run --reporter=agent --reporter=json --outputFile.json=reports/vitest-results.json --passWithNoTests"
+	},
+	"imports": {
+		"#react-pdf-renderer": "@react-pdf/renderer"
+	},
+	"dependencies": {
+		"@ai-sdk/anthropic": "^3.0.80",
+		"@ai-sdk/google": "^3.0.80",
+		"@ai-sdk/openai": "^3.0.65",
+		"@ai-sdk/openai-compatible": "^2.0.48",
+		"@aws-sdk/client-s3": "^3.1055.0",
+		"@better-auth/api-key": "^1.6.11",
+		"@better-auth/drizzle-adapter": "^1.6.11",
+		"@better-auth/infra": "^0.2.10",
+		"@better-auth/oauth-provider": "^1.6.11",
+		"@better-auth/passkey": "^1.6.11",
+		"@hono/node-server": "^2.0.4",
+		"@modelcontextprotocol/sdk": "^1.29.0",
+		"@orpc/client": "^1.14.3",
+		"@orpc/experimental-ratelimit": "^1.14.3",
+		"@orpc/json-schema": "^1.14.3",
+		"@orpc/openapi": "^1.14.3",
+		"@orpc/server": "^1.14.3",
+		"@orpc/zod": "^1.14.3",
+		"@react-pdf/renderer": "^4.5.1",
+		"@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.0",
+		"@t3-oss/env-core": "^0.13.11",
+		"@uiw/color-convert": "^2.10.3",
+		"ai": "^6.0.191",
+		"bcrypt": "^6.0.0",
+		"better-auth": "1.6.11",
+		"cjk-regex": "^3.4.0",
+		"deepmerge-ts": "^7.1.5",
+		"dompurify": "^3.4.7",
+		"dotenv": "^17.4.2",
+		"drizzle-orm": "1.0.0-rc.3",
+		"drizzle-zod": "1.0.0-beta.14-a36c63d",
+		"es-toolkit": "^1.47.0",
+		"fast-json-patch": "^3.1.1",
+		"hono": "^4.12.23",
+		"jsonrepair": "^3.14.0",
+		"node-html-parser": "^7.1.0",
+		"nodemailer": "^8.0.9",
+		"ollama-ai-provider-v2": "^3.5.1",
+		"pg": "^8.21.0",
+		"phosphor-icons-react-pdf": "^0.1.3",
+		"react": "^19.2.6",
+		"react-email": "^6.5.0",
+		"react-pdf-html": "^2.1.5",
+		"resumable-stream": "^2.2.12",
+		"sharp": "^0.34.5",
+		"ts-pattern": "^5.9.0",
+		"unique-names-generator": "^4.7.1",
+		"uuid": "^14.0.0",
+		"zod": "^4.4.3"
+	},
+	"devDependencies": {
+		"@reactive-resume/config": "workspace:*",
+		"@types/node": "^25.9.1",
+		"@types/pg": "^8.20.0",
+		"@types/react": "^19.2.15",
+		"@typescript/native-preview": "7.0.0-dev.20260527.1",
+		"tsdown": "^0.22.0",
+		"tsx": "^4.22.3",
+		"typescript": "^6.0.3",
+		"vitest": "^4.1.7"
+	}
+}

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

@@ -0,0 +1,124 @@
+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(),
+	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(),
+	handleWebAppHead: 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,
+	handleWebAppHead: mocks.handleWebAppHead,
+}));
+
+vi.mock("../mcp/handler", () => ({
+	handleMcp: mocks.handleMcp,
+}));
+
+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.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"));
+	mocks.handleWebAppHead.mockReturnValue(new Response(null));
+});
+
+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.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();
+		expect(mocks.handleWebAppHead).not.toHaveBeenCalled();
+	});
+});

apps/server/src/http/app.ts

@@ -0,0 +1,52 @@
+import { Hono } from "hono";
+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, handleWebAppHead, serveWebDistStatic } from "../static/web";
+import { handleAuth, handleOAuth } from "./auth";
+import { handleHealth } from "./health";
+
+export function createApp() {
+	const app = new Hono();
+
+	app.all("/api/rpc", (c) => handleRpc(c.req.raw));
+	app.all("/api/rpc/*", (c) => handleRpc(c.req.raw));
+	app.all("/api/openapi", (c) => handleOpenApi(c.req.raw));
+	app.all("/api/openapi/*", (c) => handleOpenApi(c.req.raw));
+	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/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" }));
+
+	app.use("/*", serveWebDistStatic);
+	app.on(["GET"], "/*", (c) => handleWebApp(c.req.raw));
+	app.on(["HEAD"], "/*", (c) => handleWebAppHead(c.req.raw));
+
+	return app;
+}

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

@@ -0,0 +1,97 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+	getSession: 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,
+		},
+		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("rejects untrusted 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://evil.example.com/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();
+	});
+});
+
+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.has("exp")).toBe(false);
+		expect(callbackUrl.searchParams.has("sig")).toBe(false);
+	});
+});

apps/server/src/http/auth.ts

@@ -0,0 +1,214 @@
+import crypto from "node:crypto";
+import { eq } from "drizzle-orm";
+import { auth } from "@reactive-resume/auth/config";
+import { db } from "@reactive-resume/db/client";
+import { oauthClient, verification } from "@reactive-resume/db/schema";
+import { env } from "@reactive-resume/env/server";
+import { generateId } from "@reactive-resume/utils/string";
+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;
+
+const oauthCallbackPassthroughExcludedParams = new Set(["exp", "sig"]);
+
+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 value = url.searchParams.get(key);
+		if (!value) return;
+		url.searchParams.set(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);
+}
+
+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 {
+		body = await cloned.json();
+	} catch {
+		return request;
+	}
+
+	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 {
+		body = await cloned.json();
+	} 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);
+}
+
+function generateCode() {
+	return crypto.randomBytes(32).toString("base64url");
+}
+
+function hashCode(code: string) {
+	return crypto.createHash("sha256").update(code).digest("base64url");
+}
+
+export async function handleOAuth(request: Request) {
+	const session = await auth.api.getSession({ headers: request.headers });
+	const url = new URL(request.url);
+
+	if (session?.user) {
+		const clientId = url.searchParams.get("client_id");
+		const redirectUri = url.searchParams.get("redirect_uri");
+		const state = url.searchParams.get("state");
+		const scope = url.searchParams.get("scope");
+		const codeChallenge = url.searchParams.get("code_challenge");
+		const codeChallengeMethod = url.searchParams.get("code_challenge_method");
+
+		if (!clientId || !redirectUri) {
+			return Response.json({ error: "missing client_id or redirect_uri" }, { status: 400 });
+		}
+
+		const [client] = await db.select().from(oauthClient).where(eq(oauthClient.clientId, clientId)).limit(1);
+
+		if (!client) {
+			return Response.json({ error: "invalid client" }, { status: 400 });
+		}
+
+		if (!client.redirectUris.includes(redirectUri)) {
+			return Response.json({ error: "invalid redirect_uri" }, { status: 400 });
+		}
+
+		const code = generateCode();
+		const hashedCode = hashCode(code);
+		const now = new Date();
+		const expiresAt = new Date(now.getTime() + 600_000);
+
+		await db.insert(verification).values({
+			id: generateId(),
+			identifier: hashedCode,
+			value: JSON.stringify({
+				type: "authorization_code",
+				query: {
+					response_type: "code",
+					client_id: clientId,
+					redirect_uri: redirectUri,
+					scope,
+					state,
+					code_challenge: codeChallenge,
+					code_challenge_method: codeChallengeMethod,
+				},
+				userId: session.user.id,
+				sessionId: session.session.id,
+				authTime: new Date(session.session.createdAt).getTime(),
+			}),
+			expiresAt,
+			createdAt: now,
+			updatedAt: now,
+		});
+
+		const callbackUrl = new URL(redirectUri);
+		callbackUrl.searchParams.set("code", code);
+		if (state) callbackUrl.searchParams.set("state", state);
+		callbackUrl.searchParams.set("iss", `${env.APP_URL}/api/auth`);
+
+		return new Response(null, {
+			status: 302,
+			headers: { Location: callbackUrl.toString() },
+		});
+	}
+
+	const loginUrl = new URL("/auth/login", env.APP_URL);
+	const oauthParams = new URLSearchParams();
+	for (const [key, value] of url.searchParams) {
+		if (!oauthCallbackPassthroughExcludedParams.has(key)) {
+			oauthParams.set(key, value);
+		}
+	}
+	loginUrl.searchParams.set("callbackURL", `/api/auth/oauth?${oauthParams.toString()}`);
+
+	return new Response(null, {
+		status: 302,
+		headers: { Location: `${loginUrl.pathname}${loginUrl.search}` },
+	});
+}

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.ts

@@ -0,0 +1,102 @@
+import { sql } from "drizzle-orm";
+import { getStorageService } from "@reactive-resume/api/features/storage";
+import { db } from "@reactive-resume/db/client";
+
+const HEALTHCHECK_TIMEOUT_MS = 1_500;
+
+type CheckResult = {
+	status: "healthy" | "unhealthy";
+	latencyMs: number;
+	error?: string;
+	[key: string]: unknown;
+};
+
+function getErrorMessage(error: unknown): string {
+	if (error instanceof Error) return error.message;
+	return "Unknown error";
+}
+
+async function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
+	let timeoutId: NodeJS.Timeout | undefined;
+
+	const timeout = new Promise<never>((_, reject) => {
+		timeoutId = setTimeout(() => reject(new Error(`Timed out after ${timeoutMs}ms`)), timeoutMs);
+	});
+
+	try {
+		return await Promise.race([promise, timeout]);
+	} finally {
+		if (timeoutId) clearTimeout(timeoutId);
+	}
+}
+
+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: getErrorMessage(error),
+			latencyMs: Math.round(performance.now() - startedAt),
+		};
+	}
+}
+
+async function checkDatabase() {
+	try {
+		await db.execute(sql`SELECT 1`);
+		return { status: "healthy" };
+	} catch (error) {
+		return {
+			status: "unhealthy",
+			error: error instanceof Error ? error.message : "Unknown error",
+		};
+	}
+}
+
+async function checkStorage() {
+	try {
+		const storageService = getStorageService();
+		return await storageService.healthcheck();
+	} catch (error) {
+		return {
+			status: "unhealthy",
+			error: error instanceof Error ? error.message : "Unknown error",
+		};
+	}
+}
+
+export async function handleHealth() {
+	const [database, storage] = await Promise.all([runCheck(checkDatabase), runCheck(checkStorage)]);
+	const status = [database, storage].some((check) => check.status === "unhealthy") ? "unhealthy" : "healthy";
+
+	const checks = {
+		service: "reactive-resume",
+		version: process.env.npm_package_version,
+		status,
+		timestamp: new Date().toISOString(),
+		uptime: `${process.uptime().toFixed(2)}s`,
+		database,
+		storage,
+	};
+
+	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/index.ts

@@ -0,0 +1,33 @@
+import { pathToFileURL } from "node:url";
+import { serve } from "@hono/node-server";
+import { env } from "@reactive-resume/env/server";
+import { createApp } from "./http/app";
+import { runStartupChecks } from "./startup/checks";
+
+export { createApp } from "./http/app";
+
+async function main() {
+	await runStartupChecks();
+
+	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,33 @@
+import { auth, verifyOAuthToken } from "@reactive-resume/auth/config";
+
+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;
+		} catch {
+			// Invalid or expired token; fall through to API key auth.
+		}
+	}
+
+	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 = await 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,66 @@
+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 { MCP_TOOL_NAME, registerPrompts, registerResources, registerTools } from "@reactive-resume/mcp";
+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 async function createMcpServer(request: Request) {
+	const server = new McpServer(
+		{
+			name: "reactive-resume",
+			version: __APP_VERSION__,
+			title: "Reactive Resume",
+			websiteUrl: "https://rxresu.me",
+			description:
+				"Reactive Resume is a free and open-source resume builder. Use this MCP server to interact with your resume using an LLM of your choice.",
+			icons: [
+				{
+					src: "https://rxresu.me/icon/light.svg",
+					mimeType: "image/svg+xml",
+					theme: "light",
+				},
+				{
+					src: "https://rxresu.me/icon/dark.svg",
+					mimeType: "image/svg+xml",
+					theme: "dark",
+				},
+			],
+		},
+		{
+			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).`,
+				`Import full ResumeData JSON with \`${MCP_TOOL_NAME.importResume}\`; read saved AI analysis with \`${MCP_TOOL_NAME.getResumeAnalysis}\`.`,
+			].join(" "),
+		},
+	);
+
+	const client = createRequestClient(request);
+	registerResources(server, client);
+	registerTools(server, client, request.headers);
+	registerPrompts(server);
+
+	return server;
+}

apps/server/src/openapi/handler.ts

@@ -0,0 +1,82 @@
+import { SmartCoercionPlugin } from "@orpc/json-schema";
+import { OpenAPIGenerator } from "@orpc/openapi";
+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 { downloadResumePdfProcedure } from "@reactive-resume/api/features/resume/export";
+import router from "@reactive-resume/api/routers";
+import { env } from "@reactive-resume/env/server";
+import { resumeDataSchema } from "@reactive-resume/schema/resume/data";
+import { mergeResponseHeaders } from "../http/headers";
+import { getRequestLocale } from "../rpc/locale";
+
+const openAPIRouter = {
+	...router,
+	resume: {
+		...router.resume,
+		downloadPdf: downloadResumePdfProcedure,
+	},
+};
+
+const openAPIHandler = new OpenAPIHandler(openAPIRouter, {
+	plugins: [
+		new BatchHandlerPlugin(),
+		new RequestHeadersPlugin(),
+		new StrictGetMethodPlugin(),
+		new SmartCoercionPlugin({
+			schemaConverters: [new ZodToJsonSchemaConverter()],
+		}),
+	],
+	interceptors: [
+		onError((error) => {
+			console.error("[OpenAPI]", error);
+		}),
+	],
+});
+
+const openAPIGenerator = new OpenAPIGenerator({
+	schemaConverters: [new ZodToJsonSchemaConverter()],
+});
+
+export async function handleOpenApi(request: Request) {
+	if (request.method === "GET" && (request.url.endsWith("/spec.json") || request.url.endsWith("/spec"))) {
+		const spec = await openAPIGenerator.generate(openAPIRouter, {
+			info: {
+				title: "Reactive Resume",
+				version: __APP_VERSION__,
+				description: "Reactive Resume API",
+				license: { name: "MIT", url: "https://github.com/amruthpillai/reactive-resume/blob/main/LICENSE" },
+				contact: { name: "Amruth Pillai", email: "hello@amruthpillai.com", url: "https://amruthpillai.com" },
+			},
+			servers: [{ url: `${env.APP_URL}/api/openapi` }],
+			externalDocs: { url: "https://docs.rxresu.me", description: "Reactive Resume Documentation" },
+			commonSchemas: {
+				ResumeData: { schema: resumeDataSchema },
+			},
+			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"),
+		});
+
+		return Response.json(spec);
+	}
+
+	const resHeaders = new Headers();
+	const { response } = await openAPIHandler.handle(request, {
+		prefix: "/api/openapi",
+		context: { locale: getRequestLocale(request), reqHeaders: request.headers, resHeaders },
+	});
+
+	if (!response) return new Response("NOT_FOUND", { status: 404 });
+	return mergeResponseHeaders(response, resHeaders);
+}

apps/server/src/openapi/metadata.ts

@@ -0,0 +1,43 @@
+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";
+
+const oauthAuthorizationServerHandler = oauthProviderAuthServerMetadata(auth);
+const openIdConfigurationHandler = oauthProviderOpenIdConfigMetadata(auth);
+
+export function handleWellKnownFallback() {
+	return new Response("OK", { status: 200 });
+}
+
+export function handleMcpServerCard() {
+	return Response.json(buildMcpServerCard(__APP_VERSION__), {
+		headers: {
+			"Content-Type": "application/json",
+			"Cache-Control": "public, max-age=60, stale-while-revalidate=120",
+		},
+	});
+}
+
+export function handleOAuthAuthorizationServer(request: Request) {
+	return oauthAuthorizationServerHandler(request);
+}
+
+export function handleOpenIdConfiguration(request: Request) {
+	return openIdConfigurationHandler(request);
+}
+
+export async function handleOAuthProtectedResource() {
+	const metadata = {
+		resource: env.APP_URL,
+		bearer_methods_supported: ["header"],
+		authorization_servers: [env.APP_URL, `${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/rpc/handler.ts

@@ -0,0 +1,26 @@
+import { onError } from "@orpc/server";
+import { RPCHandler } from "@orpc/server/fetch";
+import { BatchHandlerPlugin, RequestHeadersPlugin, StrictGetMethodPlugin } from "@orpc/server/plugins";
+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) => {
+			console.error("[oRPC Server]", error);
+		}),
+	],
+});
+
+export async function handleRpc(request: Request) {
+	const resHeaders = new Headers();
+	const { response } = await rpcHandler.handle(request, {
+		prefix: "/api/rpc",
+		context: { locale: getRequestLocale(request), reqHeaders: request.headers, resHeaders },
+	});
+
+	if (!response) return new Response("NOT_FOUND", { status: 404 });
+	return mergeResponseHeaders(response, resHeaders);
+}

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,67 @@
+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";
+
+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(".")}`);
+}
+
+async function runDatabaseMigrations() {
+	console.info("Running database migrations...");
+
+	const pool = new Pool({ connectionString: env.DATABASE_URL });
+	const db = drizzle({ client: pool });
+
+	try {
+		await migrate(db, { migrationsFolder: resolveWorkspaceFolder("migrations") });
+		console.info("Database migrations completed");
+	} catch (error) {
+		console.error("Database migrations failed", { error });
+		throw error;
+	} finally {
+		await pool.end();
+	}
+}
+
+async function validateLocalStoragePath() {
+	if (env.S3_ACCESS_KEY_ID && env.S3_SECRET_ACCESS_KEY && env.S3_BUCKET) return;
+
+	const dataDirectory = getLocalDataDirectory(env.LOCAL_STORAGE_PATH);
+	console.info(`Validating local storage path: ${dataDirectory}`);
+
+	try {
+		await fs.mkdir(dataDirectory, { recursive: true });
+		await fs.access(dataDirectory, 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;
+	}
+}
+
+export async function runStartupChecks() {
+	await runDatabaseMigrations();
+	await validateLocalStoragePath();
+}

apps/server/src/static/schema.ts

@@ -0,0 +1,19 @@
+import z from "zod";
+import { resumeDataSchema } from "@reactive-resume/schema/resume/data";
+
+export function handleSchemaJson() {
+	const resumeDataJSONSchema = z.toJSONSchema(resumeDataSchema);
+
+	return Response.json(resumeDataJSONSchema, {
+		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: __APP_VERSION__,
+			Vary: "Accept",
+		},
+	});
+}

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

@@ -0,0 +1,68 @@
+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).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,75 @@
+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>",
+		"</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.test.ts

@@ -0,0 +1,52 @@
+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");
+	});
+
+	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

@@ -0,0 +1,160 @@
+import { createHash } from "node:crypto";
+import { basename, extname, normalize } from "node:path";
+import { getStorageService } from "@reactive-resume/api/features/storage";
+import { env } from "@reactive-resume/env/server";
+
+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 });
+
+	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;
+	const ext = extname(filename).toLowerCase();
+	const contentType = storedFile.contentType ?? inferContentTypeFromExtension(ext);
+	const etag = createEtag(storedFile);
+
+	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);
+
+	return new Response(buffer, { headers });
+}
+
+function inferContentTypeFromExtension(ext: string): string {
+	switch (ext) {
+		case ".webp":
+			return "image/webp";
+		case ".png":
+			return "image/png";
+		case ".jpg":
+		case ".jpeg":
+			return "image/jpeg";
+		case ".gif":
+			return "image/gif";
+		case ".pdf":
+			return "application/pdf";
+		default:
+			return "application/octet-stream";
+	}
+}
+
+function parseRouteParams(url: string): { userId: string | undefined; filePath: string | undefined } {
+	const pathname = new URL(url).pathname;
+	const [, pathAfterUploads] = pathname.split("/uploads/");
+	if (!pathAfterUploads) return { userId: undefined, filePath: undefined };
+	const firstSlashIndex = pathAfterUploads.indexOf("/");
+
+	if (firstSlashIndex === -1) {
+		return { userId: pathAfterUploads, filePath: undefined };
+	}
+
+	const userId = pathAfterUploads.slice(0, firstSlashIndex);
+	const filePath = pathAfterUploads.slice(firstSlashIndex + 1);
+
+	return { userId, filePath: filePath || undefined };
+}
+
+function isValidPath(segment: string): boolean {
+	const normalized = normalize(segment).replace(/^(\.\.(\/|\\|$))+/, "");
+
+	return normalized === segment;
+}
+
+function isValidPathSegments(path: string): boolean {
+	const segments = path.split("/");
+
+	return segments.every((segment) => isValidPath(segment));
+}
+
+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()) ?? [];
+
+	return candidates.includes(etag);
+}
+
+function makeNotModifiedResponse(etag: string): Response {
+	return new Response(null, {
+		status: 304,
+		headers: { ETag: etag, "Cache-Control": "public, max-age=31536000, immutable" },
+	});
+}
+
+type BuildResponseHeaderArgs = {
+	filename: string;
+	storedFile: { size: number };
+	contentType: string;
+	etag: string;
+	shouldForceDownload: boolean;
+};
+
+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);
+	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");
+	headers.set("Access-Control-Allow-Origin", env.APP_URL);
+
+	return headers;
+}
+
+function toArrayBuffer(data: Uint8Array): ArrayBuffer {
+	return data.byteOffset === 0 && data.byteLength === data.buffer.byteLength
+		? (data.buffer as ArrayBuffer)
+		: (data.slice().buffer as ArrayBuffer);
+}
+
+function createEtag(storedFile: { data: Uint8Array; size: number; etag?: string }): string {
+	if (storedFile.etag) {
+		const tag = storedFile.etag.trim();
+
+		if (tag.startsWith("W/") || tag.startsWith('"')) {
+			return tag;
+		}
+		return `"${tag}"`;
+	}
+
+	const hash = createHash("sha256").update(storedFile.data).digest("hex");
+
+	return `"${storedFile.size}-${hash}"`;
+}

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

@@ -0,0 +1,106 @@
+import fs from "node:fs/promises";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+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: vi.fn(() => vi.fn()),
+}));
+
+const { handleWebApp, handleWebAppHead } = await import("./web");
+
+describe("web app fallback classification", () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+		vi.mocked(fs.readFile).mockResolvedValue("<html>app</html>");
+	});
+
+	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.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 = handleWebAppHead(new Request("https://example.com/dashboard"));
+		const unknownResponse = handleWebAppHead(new Request("https://example.com/unknown/extra/path"));
+
+		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("");
+	});
+});

apps/server/src/static/web.ts

@@ -0,0 +1,96 @@
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { serveStatic } from "@hono/node-server/serve-static";
+
+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"];
+const reservedPublicResumeSegments = new Set([
+	"api",
+	"mcp",
+	".well-known",
+	"uploads",
+	"auth",
+	"dashboard",
+	"builder",
+	"agent",
+	"templates",
+]);
+
+export const serveWebDistStatic = serveStatic({ root: staticRoot });
+
+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);
+}
+
+function getFallbackResponseHeaders(pathname: string) {
+	if (pathname === "/") return { "Content-Type": "text/html; charset=UTF-8" };
+	if (isNoindexShellPath(pathname) || isPublicResumePath(pathname)) {
+		return {
+			"Content-Type": "text/html; charset=UTF-8",
+			"X-Robots-Tag": "noindex, follow",
+		};
+	}
+
+	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,
+	});
+}
+
+export async function handleWebApp(request: Request) {
+	const pathname = new URL(request.url).pathname;
+	if (!isNoindexShellPath(pathname) && isAssetPath(pathname)) return new Response("Not Found", { status: 404 });
+
+	const headers = getFallbackResponseHeaders(pathname);
+	if (!headers) return notFoundResponse({ noindex: true });
+
+	const html = await fs.readFile(indexHtmlPath, "utf-8");
+	return new Response(html, { headers });
+}
+
+export function handleWebAppHead(request: Request) {
+	const pathname = new URL(request.url).pathname;
+	if (!isNoindexShellPath(pathname) && isAssetPath(pathname)) return new Response(null, { status: 404 });
+
+	const headers = getFallbackResponseHeaders(pathname);
+	if (!headers) return notFoundResponse({ head: true, noindex: true });
+
+	return new Response(null, { status: 200, 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,51 @@
+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;
+};
+
+const shouldExternalizeThirdParty = (id: string) => {
+	if (id.startsWith("@reactive-resume/")) 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" },
+	format: "esm",
+	platform: "node",
+	target: "node24",
+	outDir: "dist",
+	clean: true,
+	shims: true,
+	dts: false,
+	define: { __APP_VERSION__: JSON.stringify(rootPackageJson.version ?? "0.0.0") },
+	outExtensions: () => ({ js: ".mjs" }),
+	deps: {
+		alwaysBundle: [/^@reactive-resume\//],
+		neverBundle: shouldExternalizeThirdParty,
+	},
+	plugins: [promptAssetsPlugin],
+});

apps/server/turbo.json

@@ -0,0 +1,4 @@
+{
+	"extends": ["//"],
+	"tags": ["app:server", "runtime:server", "role:adapter"]
+}

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";
+
+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,25 @@
+<!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" />
+		<meta name="description" content="Reactive Resume is a free and open-source resume builder that simplifies the process of creating, updating, and sharing your resume.">
+
+		<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</title>
+	</head>
+	<body>
+		<div id="app"></div>
+		<script type="module" src="/src/main.tsx"></script>
+	</body>
+</html>

apps/web/lingui.config.ts

@@ -0,0 +1,77 @@
+import { defineConfig } from "@lingui/cli";
+import { formatter } from "@lingui/format-po";
+
+export default defineConfig({
+	sourceLocale: "en-US",
+	pseudoLocale: "zu-ZA",
+	locales: [
+		"af-ZA",
+		"am-ET",
+		"ar-SA",
+		"az-AZ",
+		"bg-BG",
+		"bn-BD",
+		"ca-ES",
+		"cs-CZ",
+		"da-DK",
+		"de-DE",
+		"el-GR",
+		"en-US",
+		"en-GB",
+		"es-ES",
+		"fa-IR",
+		"fi-FI",
+		"fr-FR",
+		"he-IL",
+		"hi-IN",
+		"hu-HU",
+		"id-ID",
+		"it-IT",
+		"ja-JP",
+		"km-KH",
+		"kn-IN",
+		"ko-KR",
+		"lt-LT",
+		"lv-LV",
+		"ml-IN",
+		"mr-IN",
+		"ms-MY",
+		"ne-NP",
+		"nl-NL",
+		"no-NO",
+		"or-IN",
+		"pl-PL",
+		"pt-BR",
+		"pt-PT",
+		"ro-RO",
+		"ru-RU",
+		"sk-SK",
+		"sl-SI",
+		"sq-AL",
+		"sr-SP",
+		"sv-SE",
+		"ta-IN",
+		"te-IN",
+		"th-TH",
+		"tr-TR",
+		"uk-UA",
+		"uz-UZ",
+		"vi-VN",
+		"zh-CN",
+		"zh-TW",
+		"zu-ZA",
+	],
+	fallbackLocales: {
+		"zu-ZA": "en-US",
+		default: "en-US",
+	},
+	format: formatter({
+		lineNumbers: false,
+	}),
+	catalogs: [
+		{
+			path: "<rootDir>/locales/{locale}",
+			include: ["src"],
+		},
+	],
+});