docs(changelog): update title and description for clarity

* fix(dsh-plugin): accept the DSH 0.2 host line in peer ranges

The Harness peer ranges pinned `^0.1.0-rc.6`, which the 0.2.0-rc.2 host
rejects, so a profile on the new core refused to load the plugin:

  Plugin dsh-plugin-reactive-resume@0.1.0 is incompatible with dsh 0.2.0-rc.2

The host decides that with
`semver.satisfies(runtime, range, { includePrerelease: true })`. Under that
mode the upper bound is what fails: `^0.1.0-rc.6` expands to
`>=0.1.0-rc.6 <0.2.0-0`, and `0.2.0-rc.2` sorts above `0.2.0-0` because the
numeric identifier `0` precedes `rc`.

npm's default mode, which the plugin market's checker uses, is stricter: a
prerelease only satisfies a comparator set that pins the same
major.minor.patch tuple with a prerelease of its own. There the bare
`^0.1.0-rc.6` admits only `0.1.0-rc.6` through `0.1.0-rc.8`;
`>=0.1.0-rc.6 <0.3.0-0` still admits only those three, and `*` admits none of
the 29 published releases. An explicit union is the only form both modes
accept, so the MCP bridge peer and the prompt peer both become
`^0.1.0-rc.6 || ^0.2.0-rc.1`.

The union is additive: everything the old range admitted is still admitted.
`devDependencies` move to `^0.2.0-rc.2` so the package develops against the
core it now claims.

No source change was needed. `dsh-mcp-client@0.2.0-rc.2` keeps its `Config`
union, its `apply(ctx, config)` signature, and the
`mcp__<serverName>__<rawName>` public tool name, while
`dsh-system-prompt@0.2.0-rc.2` keeps `section({ name, order, text })`. The
0.2 additions to the bridge — MCP resource publishing and a
server-instructions prompt section — are additive and scoped to
`ctx.inject(["mcpResources"])` and `ctx.inject(["systemPrompt"])`, neither of
which this package depends on.

The README records the two comparison modes, since the prerelease rule makes
the obvious alternatives silently wrong.

* fix(dsh-plugin): refresh DSH 0.2 lockfile

---------

Co-authored-by: ddddd-ren <ddddd-ren@users.noreply.github.com>
Co-authored-by: Amruth Pillai <im.amruth@gmail.com>

.dockerignore

@@ -3,6 +3,7 @@
 .gitignore
 .cursor
 .DS_Store
+.vite-hooks
 
 # Local configuration and runtime state
 .env*

.env.example

@@ -1,15 +1,33 @@
 # --- Application ---
-# Port used by the web server in local development and self-hosted containers.
+# 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: serve one already-public resume at /. Use the ID from /builder/<id>.
+# Unset or blank keeps the marketing home. Restart after changes.
+# ROOT_RESUME_ID=
+
+# Vercel: APP_URL can be omitted; production uses VERCEL_PROJECT_PRODUCTION_URL.
+
 # --- Database (PostgreSQL) ---
 # PostgreSQL connection URL. In Docker Compose, the hostname is usually `postgres`;
 # when running directly on your machine, `localhost` is typical.
-DATABASE_URL="postgresql://postgres:postgres@localhost:5432/postgres"
+DATABASE_URL="postgresql://postgres:postgres@postgres:5432/postgres"
+
+# Optional direct connection for migrations (Neon: DATABASE_URL_UNPOOLED alias).
+# DATABASE_MIGRATION_URL=""
+# DATABASE_POOL_MAX="10"
+
+# When "true", the server refuses to boot if the live database schema has drifted from
+# the migration ledger (e.g. a table dropped outside migrations). Default "false" logs
+# the drift loudly at startup and continues.
+STRICT_SCHEMA_CHECK="false"
 
 # --- Authentication ---
 # Generated using `openssl rand -hex 32`
@@ -48,32 +66,47 @@ OAUTH_USER_INFO_URL=""
 # Space-separated scopes requested from the custom OAuth provider.
 OAUTH_SCOPES="openid profile email"
 
-# Comma-separated extra hosts/origins allowed for dynamic OAuth client redirect URIs.
-# By default, only the APP_URL origin is allowed.
-OAUTH_DYNAMIC_CLIENT_REDIRECT_HOSTS=""
-
 # --- Email (optional) ---
 # If SMTP_HOST, SMTP_USER, SMTP_PASS, or SMTP_FROM is missing, the app logs the
 # email to the console instead.
-SMTP_HOST="localhost"
-SMTP_PORT="1025"
+SMTP_HOST=""
+SMTP_PORT=""
 SMTP_USER=""
 SMTP_PASS=""
 SMTP_FROM="Reactive Resume <noreply@rxresu.me>"
 SMTP_SECURE="false"
 
 # --- Storage (optional) ---
-# If all keys are disabled, the app uses local filesystem (/data) to store uploads instead.
+# Backend defaults to S3 when all credentials are present, otherwise local.
+# Vercel defaults to private Blob. Explicit selection: local, s3, blob.
+# STORAGE_BACKEND="local"
+# BLOB_READ_WRITE_TOKEN=""
+# BLOB_STORE_ID=""
+# DEPLOYMENT_NAMESPACE="default"
+# Vercel previews need isolated resources before setting ALLOW_PREVIEW_MIGRATIONS=true.
+
+# If all S3 keys are disabled, Docker uses local filesystem storage instead.
 # Make sure to mount this directory to a volume or the host filesystem to ensure data integrity.
+# LOCAL_STORAGE_PATH overrides where local uploads/cache are written.
+# Defaults to /app/data in the official Docker image; in dev, defaults to <workspace>/data.
+# LOCAL_STORAGE_PATH="/app/data"
 
 # Seaweedfs
 S3_ACCESS_KEY_ID="seaweedfs"
 S3_SECRET_ACCESS_KEY="seaweedfs"
 S3_REGION="us-east-1"
-S3_ENDPOINT="http://localhost:8333"
+S3_ENDPOINT="http://seaweedfs:8333"
 S3_BUCKET="reactive-resume"
 S3_FORCE_PATH_STYLE="true"
 
+# --- AI Agent Workspace (optional) ---
+# ENCRYPTION_SECRET is required for saved AI providers and the assistant.
+# Redis is optional on a single server. Providers and conversations persist in PostgreSQL.
+# Redis shares rate limits, resume events, cancellation and view deduplication, and resumes reply streams.
+# Vercel Upstash KV_URL is accepted as an alias for REDIS_URL.
+REDIS_URL="redis://redis:6379"
+ENCRYPTION_SECRET="change-me-to-a-secure-agent-secret-in-production"
+
 # --- Feature Flags ---
 # This flag disables new signups, both on the web app and the server.
 FLAG_DISABLE_SIGNUPS="false"
@@ -86,6 +119,23 @@ FLAG_DISABLE_EMAIL_AUTH="false"
 # This is useful if you are using a machine with limited resources, like a Raspberry Pi.
 FLAG_DISABLE_IMAGE_PROCESSING="false"
 
+# This flag disables API and authentication rate limiting, including PDF export and AI requests.
+# Rate limiting is enabled by default in production to prevent abuse.
+FLAG_DISABLE_API_RATE_LIMIT="false"
+
+
+# Allows dynamic OAuth client registration to use any parseable redirect URI,
+# including custom schemes, private hosts, and non-loopback http:// URLs.
+# WARNING: Enabling this on a public or multi-tenant deployment can enable phishing
+# or token exfiltration. Only enable this on a trusted, self-hosted instance.
+FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI="false"
+
+# Allows AI providers to be configured with any base URL, including http:// and
+# private/loopback addresses (e.g. http://localhost:11434 for a local Ollama instance).
+# WARNING: Enabling this on a multi-tenant deployment is a Server-Side Request Forgery (SSRF)
+# risk. Only enable this on a trusted, single-tenant self-hosted instance.
+FLAG_ALLOW_UNSAFE_AI_BASE_URL="false"
+
 # --- Others ---
 # Google Cloud API Key (optional)
 # For font-list generation tooling.

.github/.well-known/funding.json

@@ -15,13 +15,13 @@
 		{
 			"guid": "reactive-resume",
 			"name": "Reactive Resume",
-			"description": "A free and open-source resume builder that simplifies the process of creating, updating, and sharing your resume.",
+			"description": "A free and open-source resume builder that makes it easy to create, update, and share your resume.",
 			"webpageUrl": {
 				"url": "https://rxresu.me"
 			},
 			"repositoryUrl": {
-				"url": "https://github.com/amruthpillai/reactive-resume",
-				"wellKnown": "https://github.com/amruthpillai/reactive-resume/blob/main/.github/.well-known/funding-manifest-urls"
+				"url": "https://github.com/reactive-resume/reactive-resume",
+				"wellKnown": "https://github.com/reactive-resume/reactive-resume/blob/main/.github/.well-known/funding-manifest-urls"
 			},
 			"licenses": ["spdx:MIT"],
 			"tags": ["data", "design", "productivity", "resume-builder"]
@@ -61,7 +61,7 @@
 				"guid": "open-collective",
 				"type": "payment-provider",
 				"description": "Open Collective",
-				"address": "https://opencollective.com/reactive-resume"
+				"address": "https://opencollective.com/reactive-resume/donate"
 			}
 		]
 	}

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

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

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

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

.github/ISSUE_TEMPLATE/config.yml

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

.github/copilot-instructions.md

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

.github/workflows/autofix.yml

@@ -13,19 +13,31 @@ env:
 
 jobs:
   autofix:
-    runs-on: ubuntu-latest
+    runs-on: ${{ vars.USE_BLACKSMITH == 'true' && 'blacksmith-32vcpu-ubuntu-2404' || 'ubuntu-latest' }}
 
     steps:
       - name: Checkout Repository
+        if: ${{ vars.USE_BLACKSMITH != 'true' }}
         uses: actions/checkout@v6
 
+      - name: Checkout Repository (Blacksmith)
+        if: ${{ vars.USE_BLACKSMITH == 'true' }}
+        uses: useblacksmith/checkout@v1
+
+      - name: Check for merge conflict markers
+        run: |
+          if git grep -nEI '<{7} |>{7} |^={7}$' -- ':(exclude)*.md' ':(exclude)*.mdx'; then
+            echo "::error::Merge conflict markers found in tracked files"
+            exit 1
+          fi
+
       - name: Install pnpm
         uses: pnpm/action-setup@v6
 
       - name: Setup Node
         uses: actions/setup-node@v6
         with:
-          node-version: "lts/*"
+          node-version-file: ".nvmrc"
           cache: "pnpm"
 
       - name: Install Dependencies

.github/workflows/crowdin-sync.yml

@@ -10,7 +10,7 @@ concurrency:
 
 jobs:
   crowdin-sync:
-    runs-on: ubuntu-latest
+    runs-on: ${{ vars.USE_BLACKSMITH == 'true' && 'blacksmith-2vcpu-ubuntu-2404' || 'ubuntu-latest' }}
 
     permissions:
       contents: write
@@ -18,12 +18,22 @@ jobs:
 
     steps:
       - name: Checkout Repository
+        if: ${{ vars.USE_BLACKSMITH != 'true' }}
         uses: actions/checkout@v6
 
+      # The Crowdin action runs in a container that cannot reach the git mirror mount, so copy its objects.
+      - name: Checkout Repository (Blacksmith)
+        if: ${{ vars.USE_BLACKSMITH == 'true' }}
+        uses: useblacksmith/checkout@v1
+        with:
+          dissociate: true
+
       - name: Sync Translations from Crowdin
         uses: crowdin/github-action@v2
         with:
           download_translations: true
+          export_only_approved: true
+          skip_untranslated_strings: true
           localization_branch_name: "l10n"
           commit_message: "[skip ci] chore(i18n): sync translations from crowdin"
           pull_request_title: "Sync Translations from Crowdin"

.github/workflows/docker-build.yml

@@ -2,26 +2,69 @@ name: Build Docker Image
 
 on:
   workflow_dispatch:
+    inputs:
+      release:
+        description: Publish release aliases and redeploy production (false runs a cache-only build, then publishes a canary)
+        type: boolean
+        default: false
+  push:
+    branches:
+      - main
+    tags:
+      - "v*"
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 env:
-  IMAGE: ${{ github.repository }}
+  GHCR_IMAGE: ghcr.io/${{ github.repository }}
+  DOCKER_IMAGE: docker.io/amruthpillai/reactive-resume
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
+  mode:
+    runs-on: ${{ vars.USE_BLACKSMITH == 'true' && 'blacksmith-2vcpu-ubuntu-2404' || 'ubuntu-latest' }}
+
+    outputs:
+      nightly: ${{ steps.mode.outputs.nightly }}
+      release: ${{ steps.mode.outputs.release }}
+      canary: ${{ steps.mode.outputs.canary }}
+
+    steps:
+      - name: Determine publishing mode
+        id: mode
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          GIT_REF: ${{ github.ref }}
+          RELEASE: ${{ inputs.release }}
+        run: |
+          if [[ "$EVENT_NAME" == "push" && "$GIT_REF" == "refs/heads/main" ]]; then
+            echo "nightly=true" >> "$GITHUB_OUTPUT"
+            echo "release=false" >> "$GITHUB_OUTPUT"
+            echo "canary=false" >> "$GITHUB_OUTPUT"
+          elif [[ "$EVENT_NAME" == "workflow_dispatch" && "$RELEASE" != "true" ]]; then
+            echo "nightly=false" >> "$GITHUB_OUTPUT"
+            echo "release=false" >> "$GITHUB_OUTPUT"
+            echo "canary=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "nightly=false" >> "$GITHUB_OUTPUT"
+            echo "release=true" >> "$GITHUB_OUTPUT"
+            echo "canary=false" >> "$GITHUB_OUTPUT"
+          fi
+
   build:
+    needs: mode
+
     strategy:
       fail-fast: false
       matrix:
         include:
           - platform: linux/amd64
-            runner: ubuntu-latest
+            runner: ${{ vars.USE_BLACKSMITH == 'true' && 'blacksmith-32vcpu-ubuntu-2404' || 'ubuntu-latest' }}
             arch: amd64
           - platform: linux/arm64
-            runner: ubuntu-24.04-arm
+            runner: ${{ vars.USE_BLACKSMITH == 'true' && 'blacksmith-32vcpu-ubuntu-2404-arm' || 'ubuntu-24.04-arm' }}
             arch: arm64
 
     runs-on: ${{ matrix.runner }}
@@ -35,16 +78,53 @@ jobs:
 
     steps:
       - name: Checkout Repository
+        if: ${{ vars.USE_BLACKSMITH != 'true' }}
         uses: actions/checkout@v6
 
-      - name: Get version from package.json
-        id: version
-        run: echo "version=$(jq -r .version package.json)" >> "$GITHUB_OUTPUT"
+      - name: Checkout Repository (Blacksmith)
+        if: ${{ vars.USE_BLACKSMITH == 'true' }}
+        uses: useblacksmith/checkout@v1
 
       - name: Setup Docker Buildx
+        if: ${{ vars.USE_BLACKSMITH != 'true' }}
         uses: docker/setup-buildx-action@v4
 
+      # Persists BuildKit layers and the Dockerfile's pnpm cache mounts between runs, one cache per architecture.
+      - name: Setup Docker Builder (Blacksmith)
+        if: ${{ vars.USE_BLACKSMITH == 'true' }}
+        uses: useblacksmith/setup-docker-builder@v2
+        with:
+          cache-key: Dockerfile-${{ matrix.arch }}
+
+      - &registries
+        name: Determine registries
+        id: registries
+        env:
+          DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
+          DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
+        run: |
+          set -euo pipefail
+
+          dockerhub=false
+          ghcr_image="${GHCR_IMAGE,,}"
+          docker_image="${DOCKER_IMAGE,,}"
+          images="$ghcr_image"
+          if [[ -n "$DOCKER_USERNAME" && -n "$DOCKER_PASSWORD" ]]; then
+            dockerhub=true
+            images="${images}"$'\n'"$docker_image"
+          fi
+
+          {
+            echo "ghcr_image=$ghcr_image"
+            echo "docker_image=$docker_image"
+            echo "images<<EOF"
+            echo "$images"
+            echo "EOF"
+            echo "dockerhub=$dockerhub"
+          } >> "$GITHUB_OUTPUT"
+
       - name: Login to Docker Hub
+        if: ${{ steps.registries.outputs.dockerhub == 'true' }}
         uses: docker/login-action@v4
         with:
           username: ${{ secrets.DOCKER_USERNAME }}
@@ -61,16 +141,28 @@ jobs:
         id: meta
         uses: docker/metadata-action@v6
         with:
-          images: |
-            ghcr.io/${{ env.IMAGE }}
-            docker.io/${{ env.IMAGE }}
+          images: ${{ steps.registries.outputs.images }}
           tags: |
             type=sha,prefix=sha-,suffix=-${{ matrix.arch }}
 
+      - name: Cache-only smoke build
+        if: ${{ needs.mode.outputs.canary == 'true' && vars.USE_BLACKSMITH != 'true' }}
+        uses: docker/build-push-action@v7
+        with: &cache-only-build
+          context: .
+          platforms: ${{ matrix.platform }}
+          outputs: type=cacheonly
+
+      - name: Cache-only smoke build (Blacksmith)
+        if: ${{ needs.mode.outputs.canary == 'true' && vars.USE_BLACKSMITH == 'true' }}
+        uses: useblacksmith/build-push-action@v2
+        with: *cache-only-build
+
       - name: Build and Push by Digest
         id: build
+        if: ${{ vars.USE_BLACKSMITH != 'true' }}
         uses: docker/build-push-action@v7
-        with:
+        with: &build-push
           context: .
           sbom: true
           push: true
@@ -79,13 +171,17 @@ jobs:
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
           annotations: ${{ steps.meta.outputs.annotations }}
-          cache-from: type=gha,scope=${{ env.IMAGE }}-${{ matrix.arch }}
-          cache-to: type=gha,mode=max,scope=${{ env.IMAGE }}-${{ matrix.arch }}
+
+      - name: Build and Push by Digest (Blacksmith)
+        id: build-blacksmith
+        if: ${{ vars.USE_BLACKSMITH == 'true' }}
+        uses: useblacksmith/build-push-action@v2
+        with: *build-push
 
       - name: Export digest
         run: |
           mkdir -p /tmp/digests
-          digest="${{ steps.build.outputs.digest }}"
+          digest="${{ steps.build.outputs.digest || steps.build-blacksmith.outputs.digest }}"
           touch "/tmp/digests/${digest#sha256:}"
 
       - name: Upload digest
@@ -97,9 +193,15 @@ jobs:
           retention-days: 1
 
   merge:
-    needs: build
+    needs:
+      - mode
+      - build
     timeout-minutes: 30
-    runs-on: ubuntu-latest
+    runs-on: ${{ vars.USE_BLACKSMITH == 'true' && 'blacksmith-2vcpu-ubuntu-2404' || 'ubuntu-latest' }}
+
+    env:
+      DEPLOY: ${{ secrets.SSH_KEY != '' && secrets.SSH_HOST != '' && secrets.SSH_USER != '' }}
+      PURGE_CLOUDFLARE: ${{ secrets.CLOUDFLARE_ZONE_ID != '' && secrets.CLOUDFLARE_API_TOKEN != '' }}
 
     permissions:
       contents: read
@@ -109,11 +211,17 @@ jobs:
 
     steps:
       - name: Checkout Repository
+        if: ${{ vars.USE_BLACKSMITH != 'true' }}
         uses: actions/checkout@v6
-        with:
+        with: &checkout-package-json
           sparse-checkout: package.json
           sparse-checkout-cone-mode: false
 
+      - name: Checkout Repository (Blacksmith)
+        if: ${{ vars.USE_BLACKSMITH == 'true' }}
+        uses: useblacksmith/checkout@v1
+        with: *checkout-package-json
+
       - name: Get version from package.json
         id: version
         run: echo "version=$(jq -r .version package.json)" >> "$GITHUB_OUTPUT"
@@ -128,7 +236,10 @@ jobs:
       - name: Setup Docker Buildx
         uses: docker/setup-buildx-action@v4
 
+      - *registries
+
       - name: Login to Docker Hub
+        if: ${{ steps.registries.outputs.dockerhub == 'true' }}
         uses: docker/login-action@v4
         with:
           username: ${{ secrets.DOCKER_USERNAME }}
@@ -155,21 +266,31 @@ jobs:
         id: meta
         uses: docker/metadata-action@v6
         with:
-          images: |
-            ghcr.io/${{ env.IMAGE }}
-            docker.io/${{ env.IMAGE }}
+          images: ${{ steps.registries.outputs.images }}
           tags: |
             type=sha,prefix=sha-
-            type=raw,value=latest
-            type=raw,value=v${{ steps.version.outputs.version }}
-            type=raw,value=v${{ steps.semver.outputs.major }}.${{ steps.semver.outputs.minor }}
-            type=raw,value=v${{ steps.semver.outputs.major }}
+            type=raw,value=canary-${{ github.run_id }}-${{ github.run_attempt }},enable=${{ needs.mode.outputs.canary == 'true' }}
+            type=raw,value=nightly,enable=${{ needs.mode.outputs.nightly == 'true' }}
+            type=raw,value=nightly-{{date 'YYYYMMDDHHmmss' tz='UTC'}},enable=${{ needs.mode.outputs.nightly == 'true' }}
+            type=raw,value=latest,enable=${{ needs.mode.outputs.release == 'true' }}
+            type=raw,value=v${{ steps.version.outputs.version }},enable=${{ needs.mode.outputs.release == 'true' }}
+            type=raw,value=v${{ steps.semver.outputs.major }}.${{ steps.semver.outputs.minor }},enable=${{ needs.mode.outputs.release == 'true' }}
+            type=raw,value=v${{ steps.semver.outputs.major }},enable=${{ needs.mode.outputs.release == 'true' }}
 
       - name: Create manifest list and push
         id: manifest
         working-directory: /tmp/digests
         run: |
           set -euo pipefail
+
+          if [[ "${{ needs.mode.outputs.nightly }}" == "true" ]]; then
+            FINAL_TAG="nightly"
+          elif [[ "${{ needs.mode.outputs.canary }}" == "true" ]]; then
+            FINAL_TAG="canary-${{ github.run_id }}-${{ github.run_attempt }}"
+          else
+            FINAL_TAG="v${{ steps.version.outputs.version }}"
+          fi
+
           docker buildx imagetools create \
             $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
             --annotation "index:org.opencontainers.image.licenses=MIT" \
@@ -178,16 +299,19 @@ jobs:
             --annotation "index:org.opencontainers.image.vendor=Amruth Pillai" \
             --annotation "index:org.opencontainers.image.url=https://rxresu.me" \
             --annotation "index:org.opencontainers.image.documentation=https://docs.rxresu.me" \
-            --annotation "index:org.opencontainers.image.source=https://github.com/amruthpillai/reactive-resume" \
+            --annotation "index:org.opencontainers.image.source=https://github.com/${{ github.repository }}" \
             --annotation "index:org.opencontainers.image.version=${{ steps.version.outputs.version }}" \
-            $(printf 'ghcr.io/${{ env.IMAGE }}@sha256:%s ' *) \
-            $(printf 'docker.io/${{ env.IMAGE }}@sha256:%s ' *)
+            $(printf '${{ steps.registries.outputs.ghcr_image }}@sha256:%s ' *)
 
           # Get the digest of the multi-arch manifest
-          GHCR_DIGEST=$(docker buildx imagetools inspect ghcr.io/${{ env.IMAGE }}:v${{ steps.version.outputs.version }} --format '{{json .Manifest.Digest}}' | tr -d '"')
-          DOCKER_DIGEST=$(docker buildx imagetools inspect docker.io/${{ env.IMAGE }}:v${{ steps.version.outputs.version }} --format '{{json .Manifest.Digest}}' | tr -d '"')
+          GHCR_DIGEST=$(docker buildx imagetools inspect ${{ steps.registries.outputs.ghcr_image }}:${FINAL_TAG} --format '{{json .Manifest.Digest}}' | tr -d '"')
+          echo "final_tag=$FINAL_TAG" >> "$GITHUB_OUTPUT"
           echo "ghcr_digest=$GHCR_DIGEST" >> "$GITHUB_OUTPUT"
-          echo "docker_digest=$DOCKER_DIGEST" >> "$GITHUB_OUTPUT"
+
+          if [[ "${{ steps.registries.outputs.dockerhub }}" == "true" ]]; then
+            DOCKER_DIGEST=$(docker buildx imagetools inspect ${{ steps.registries.outputs.docker_image }}:${FINAL_TAG} --format '{{json .Manifest.Digest}}' | tr -d '"')
+            echo "docker_digest=$DOCKER_DIGEST" >> "$GITHUB_OUTPUT"
+          fi
 
       - name: Install Cosign
         uses: sigstore/cosign-installer@v3
@@ -195,17 +319,40 @@ jobs:
       - name: Sign images with Cosign
         run: |
           # Sign GHCR image
-          cosign sign --yes ghcr.io/${{ env.IMAGE }}@${{ steps.manifest.outputs.ghcr_digest }}
+          cosign sign --yes ${{ steps.registries.outputs.ghcr_image }}@${{ steps.manifest.outputs.ghcr_digest }}
 
-          # Sign Docker Hub image
-          cosign sign --yes docker.io/${{ env.IMAGE }}@${{ steps.manifest.outputs.docker_digest }}
+          if [[ "${{ steps.registries.outputs.dockerhub }}" == "true" ]]; then
+            # Sign Docker Hub image
+            cosign sign --yes ${{ steps.registries.outputs.docker_image }}@${{ steps.manifest.outputs.docker_digest }}
+          fi
 
       - name: Inspect image
         run: |
-          docker buildx imagetools inspect ghcr.io/${{ env.IMAGE }}:v${{ steps.version.outputs.version }}
-          docker buildx imagetools inspect docker.io/${{ env.IMAGE }}:v${{ steps.version.outputs.version }}
+          docker buildx imagetools inspect ${{ steps.registries.outputs.ghcr_image }}:${{ steps.manifest.outputs.final_tag }}
+          if [[ "${{ steps.registries.outputs.dockerhub }}" == "true" ]]; then
+            docker buildx imagetools inspect ${{ steps.registries.outputs.docker_image }}:${{ steps.manifest.outputs.final_tag }}
+          fi
+
+      - name: Verify anonymous pulls on both architectures
+        run: |
+          set -euo pipefail
+          registry_config=$(mktemp -d)
+          trap 'rm -rf "$registry_config"' EXIT
+          # Prevent Docker from discovering a system credential helper.
+          printf '%s\n' '{"auths":{"ghcr.io":{},"https://index.docker.io/v1/":{}}}' > "$registry_config/config.json"
+          images=("${{ steps.registries.outputs.ghcr_image }}")
+          if [[ "${{ steps.registries.outputs.dockerhub }}" == "true" ]]; then
+            images+=("${{ steps.registries.outputs.docker_image }}")
+          fi
+          for image in "${images[@]}"; do
+            for platform in linux/amd64 linux/arm64; do
+              docker --config "$registry_config" pull --quiet --platform "$platform" \
+                "$image:${{ steps.manifest.outputs.final_tag }}"
+            done
+          done
 
       - name: Redeploy Stack
+        if: ${{ needs.mode.outputs.release == 'true' && env.DEPLOY == 'true' }}
         uses: appleboy/ssh-action@v1
         with:
           key: ${{ secrets.SSH_KEY }}
@@ -214,3 +361,24 @@ jobs:
           script: |
             cd docker
             ./manage_stack.sh up reactive_resume
+
+      - name: Purge Cloudflare cache
+        if: ${{ needs.mode.outputs.release == 'true' && env.PURGE_CLOUDFLARE == 'true' }}
+        env:
+          CLOUDFLARE_ZONE_ID: ${{ secrets.CLOUDFLARE_ZONE_ID }}
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          response=$(curl -fsS --max-time 10 --retry 3 --retry-delay 5 --retry-connrefused -X POST \
+            "https://api.cloudflare.com/client/v4/zones/${CLOUDFLARE_ZONE_ID}/purge_cache" \
+            -H "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
+            -H "Content-Type: application/json" \
+            --data '{"purge_everything":true}')
+
+          if [ "$(jq -r '.success' <<< "$response")" != "true" ]; then
+            echo "$response" | jq .
+            exit 1
+          fi
+
+          echo "Cloudflare cache purged successfully."

.github/workflows/e2e.yml

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

.github/workflows/label-issues.yml

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

.github/workflows/stale-issues.yml

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

.github/workflows/vercel.yml

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

.gitignore

@@ -3,7 +3,8 @@ node_modules
 .pnpm-store
 
 # Build Outputs
-.output
+dist
+dist-prerender
 .vercel
 .wrangler
 
@@ -36,6 +37,8 @@ logs
 # Testing
 coverage
 reports
+playwright-report
+test-results
 
 # Cache
 tmp
@@ -44,8 +47,23 @@ temp
 
 # AI
 .codex
+.agents
 .claude
 .cursor
+.opencode
+.codegraph
+.superpowers
+.worktrees
+.migration
+/plans
+
+# Local Storage Data
+/data
+/apps/web/data
+
+# Redesign handoff (design references, not source)
+/design_handoff_reactive_resume_redesign
+
+# Git Hooks
+.vite-hooks
 
-# Data
-apps/web/data

.ncurc.cjs

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

.nvmrc

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

.turbo/cache/0c7a15dde9d26988-manifest.json

@@ -1 +0,0 @@
-{"files":{"packages/utils/.turbo/turbo-typecheck.log":{"size":29,"mtime_nanos":1778158664889981519,"mode":420,"is_dir":false}},"order":["packages/utils/.turbo/turbo-typecheck.log"]}

.turbo/cache/0c7a15dde9d26988-meta.json

@@ -1 +0,0 @@
-{"hash":"0c7a15dde9d26988","duration":955,"sha":"1b345014be41f65c6fe7ac9f42ddef9ef3a8575c","dirty_hash":"5c14d1e7f0f28737d20df1e16b72d63386130eec2a28a7842a26eab88a949a82"}

.turbo/cache/18315d11067e0830-meta.json

@@ -1 +0,0 @@
-{"hash":"18315d11067e0830","duration":9205,"sha":"1b345014be41f65c6fe7ac9f42ddef9ef3a8575c","dirty_hash":"ee0217b2e9df145b45e6731ac512d88ad59406eee553ed1b197bdf1eef2d5689"}

.turbo/cache/24552bdffdc5ebcb-manifest.json

@@ -1 +0,0 @@
-{"files":{"packages/env/.turbo/turbo-typecheck.log":{"size":29,"mtime_nanos":1778158665081126046,"mode":420,"is_dir":false}},"order":["packages/env/.turbo/turbo-typecheck.log"]}

.turbo/cache/24552bdffdc5ebcb-meta.json

@@ -1 +0,0 @@
-{"hash":"24552bdffdc5ebcb","duration":1146,"sha":"1b345014be41f65c6fe7ac9f42ddef9ef3a8575c","dirty_hash":"5c14d1e7f0f28737d20df1e16b72d63386130eec2a28a7842a26eab88a949a82"}

.turbo/cache/2c1f239ac1e9bd96-manifest.json

@@ -1 +0,0 @@
-{"files":{"packages/fonts/.turbo/turbo-typecheck.log":{"size":29,"mtime_nanos":1778158665816497121,"mode":420,"is_dir":false}},"order":["packages/fonts/.turbo/turbo-typecheck.log"]}

.turbo/cache/2c1f239ac1e9bd96-meta.json

@@ -1 +0,0 @@
-{"hash":"2c1f239ac1e9bd96","duration":1882,"sha":"1b345014be41f65c6fe7ac9f42ddef9ef3a8575c","dirty_hash":"5c14d1e7f0f28737d20df1e16b72d63386130eec2a28a7842a26eab88a949a82"}

.turbo/cache/5fff137e287b47d8-manifest.json

@@ -1 +0,0 @@
-{"files":{"packages/import/.turbo/turbo-typecheck.log":{"size":29,"mtime_nanos":1778158667091029787,"mode":420,"is_dir":false}},"order":["packages/import/.turbo/turbo-typecheck.log"]}

.turbo/cache/5fff137e287b47d8-meta.json

@@ -1 +0,0 @@
-{"hash":"5fff137e287b47d8","duration":3154,"sha":"1b345014be41f65c6fe7ac9f42ddef9ef3a8575c","dirty_hash":"5c14d1e7f0f28737d20df1e16b72d63386130eec2a28a7842a26eab88a949a82"}

.turbo/cache/6711a052e760da9a-manifest.json

@@ -1 +0,0 @@
-{"files":{"apps/web/.turbo/turbo-typecheck.log":{"size":29,"mtime_nanos":1778158668660018078,"mode":420,"is_dir":false}},"order":["apps/web/.turbo/turbo-typecheck.log"]}

.turbo/cache/6711a052e760da9a-meta.json

@@ -1 +0,0 @@
-{"hash":"6711a052e760da9a","duration":3049,"sha":"1b345014be41f65c6fe7ac9f42ddef9ef3a8575c","dirty_hash":"5c14d1e7f0f28737d20df1e16b72d63386130eec2a28a7842a26eab88a949a82"}

.turbo/cache/72c3ccc9f2f5feed-manifest.json

@@ -1 +0,0 @@
-{"files":{"packages/ui/.turbo/turbo-typecheck.log":{"size":29,"mtime_nanos":1778158666985313670,"mode":420,"is_dir":false}},"order":["packages/ui/.turbo/turbo-typecheck.log"]}

.turbo/cache/72c3ccc9f2f5feed-meta.json

@@ -1 +0,0 @@
-{"hash":"72c3ccc9f2f5feed","duration":3048,"sha":"1b345014be41f65c6fe7ac9f42ddef9ef3a8575c","dirty_hash":"5c14d1e7f0f28737d20df1e16b72d63386130eec2a28a7842a26eab88a949a82"}

.turbo/cache/7ad6f44ecc30113b-manifest.json

@@ -1 +0,0 @@
-{"files":{"packages/scripts/.turbo/turbo-typecheck.log":{"size":29,"mtime_nanos":1778158665609656007,"mode":420,"is_dir":false}},"order":["packages/scripts/.turbo/turbo-typecheck.log"]}

.turbo/cache/7ad6f44ecc30113b-meta.json

@@ -1 +0,0 @@
-{"hash":"7ad6f44ecc30113b","duration":1673,"sha":"1b345014be41f65c6fe7ac9f42ddef9ef3a8575c","dirty_hash":"5c14d1e7f0f28737d20df1e16b72d63386130eec2a28a7842a26eab88a949a82"}

.turbo/cache/8ac845ee07e175fc-manifest.json

@@ -1 +0,0 @@
-{"files":{"packages/schema/.turbo/turbo-typecheck.log":{"size":29,"mtime_nanos":1778158666036371217,"mode":420,"is_dir":false}},"order":["packages/schema/.turbo/turbo-typecheck.log"]}

.turbo/cache/8ac845ee07e175fc-meta.json

@@ -1 +0,0 @@
-{"hash":"8ac845ee07e175fc","duration":2102,"sha":"1b345014be41f65c6fe7ac9f42ddef9ef3a8575c","dirty_hash":"5c14d1e7f0f28737d20df1e16b72d63386130eec2a28a7842a26eab88a949a82"}

.turbo/cache/a1fc5770a21706e7-manifest.json

@@ -1 +0,0 @@
-{"files":{"packages/auth/.turbo/turbo-typecheck.log":{"size":29,"mtime_nanos":1778158667978449652,"mode":420,"is_dir":false}},"order":["packages/auth/.turbo/turbo-typecheck.log"]}

.turbo/cache/a1fc5770a21706e7-meta.json

@@ -1 +0,0 @@
-{"hash":"a1fc5770a21706e7","duration":2896,"sha":"1b345014be41f65c6fe7ac9f42ddef9ef3a8575c","dirty_hash":"5c14d1e7f0f28737d20df1e16b72d63386130eec2a28a7842a26eab88a949a82"}

.turbo/cache/b5f38c54fffff57f-manifest.json

@@ -1 +0,0 @@
-{"files":{"packages/email/.turbo/turbo-typecheck.log":{"size":29,"mtime_nanos":1778158665401936928,"mode":420,"is_dir":false}},"order":["packages/email/.turbo/turbo-typecheck.log"]}

.turbo/cache/b5f38c54fffff57f-meta.json

@@ -1 +0,0 @@
-{"hash":"b5f38c54fffff57f","duration":1465,"sha":"1b345014be41f65c6fe7ac9f42ddef9ef3a8575c","dirty_hash":"5c14d1e7f0f28737d20df1e16b72d63386130eec2a28a7842a26eab88a949a82"}

.turbo/cache/b849023dfa3fccd9-manifest.json

@@ -1 +0,0 @@
-{"files":{"packages/db/.turbo/turbo-typecheck.log":{"size":29,"mtime_nanos":1778158666974087786,"mode":420,"is_dir":false}},"order":["packages/db/.turbo/turbo-typecheck.log"]}

.turbo/cache/b849023dfa3fccd9-meta.json

@@ -1 +0,0 @@
-{"hash":"b849023dfa3fccd9","duration":3037,"sha":"1b345014be41f65c6fe7ac9f42ddef9ef3a8575c","dirty_hash":"5c14d1e7f0f28737d20df1e16b72d63386130eec2a28a7842a26eab88a949a82"}

.turbo/cache/baf3349509c6078b-meta.json

@@ -1 +0,0 @@
-{"hash":"baf3349509c6078b","duration":10422,"sha":"1b345014be41f65c6fe7ac9f42ddef9ef3a8575c","dirty_hash":"d2396996b2d0bdfaf37211bb596304c9daba172ce6f30ef038c35f558dc27c1e"}

.turbo/cache/c747964dd160f1ea-meta.json

@@ -1 +0,0 @@
-{"hash":"c747964dd160f1ea","duration":12224,"sha":"1b345014be41f65c6fe7ac9f42ddef9ef3a8575c","dirty_hash":"e19f2793896093dc74f2a4eb044a4b4d3eb636c2509fb38e823941865cdf28e3"}

.turbo/cache/e1524476910e6054-manifest.json

@@ -1 +0,0 @@
-{"files":{"packages/ai/.turbo/turbo-typecheck.log":{"size":29,"mtime_nanos":1778158666319285663,"mode":420,"is_dir":false}},"order":["packages/ai/.turbo/turbo-typecheck.log"]}

.turbo/cache/e1524476910e6054-meta.json

@@ -1 +0,0 @@
-{"hash":"e1524476910e6054","duration":2383,"sha":"1b345014be41f65c6fe7ac9f42ddef9ef3a8575c","dirty_hash":"5c14d1e7f0f28737d20df1e16b72d63386130eec2a28a7842a26eab88a949a82"}

.turbo/cache/e956e719e41d711e-manifest.json

@@ -1 +0,0 @@
-{"files":{"packages/api/.turbo/turbo-typecheck.log":{"size":29,"mtime_nanos":1778158668358064434,"mode":420,"is_dir":false}},"order":["packages/api/.turbo/turbo-typecheck.log"]}

.turbo/cache/e956e719e41d711e-meta.json

@@ -1 +0,0 @@
-{"hash":"e956e719e41d711e","duration":2955,"sha":"1b345014be41f65c6fe7ac9f42ddef9ef3a8575c","dirty_hash":"5c14d1e7f0f28737d20df1e16b72d63386130eec2a28a7842a26eab88a949a82"}

.turbo/cache/fe9e2236067e95bd-manifest.json

@@ -1 +0,0 @@
-{"files":{"packages/pdf/.turbo/turbo-typecheck.log":{"size":29,"mtime_nanos":1778158667367331180,"mode":420,"is_dir":false}},"order":["packages/pdf/.turbo/turbo-typecheck.log"]}

.turbo/cache/fe9e2236067e95bd-meta.json

@@ -1 +0,0 @@
-{"hash":"fe9e2236067e95bd","duration":2476,"sha":"1b345014be41f65c6fe7ac9f42ddef9ef3a8575c","dirty_hash":"5c14d1e7f0f28737d20df1e16b72d63386130eec2a28a7842a26eab88a949a82"}

.turbo/preferences/tui.json

@@ -1,4 +0,0 @@
-{
-  "is_task_list_visible": true,
-  "active_task": null
-}

.vercelignore

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

.vite-hooks/_/commit-msg

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

.vite-hooks/_/pre-commit

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

.vscode/settings.json

@@ -27,5 +27,8 @@
 		["cn\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
 	],
 	"tailwindCSS.experimental.configFile": "src/styles/globals.css",
-	"typescript.experimental.useTsgo": true
+	"typescript.experimental.useTsgo": true,
+	"[json]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	}
 }

AGENTS.md

@@ -0,0 +1,237 @@
+# Reactive Resume: agent instructions
+
+This file applies across the repository. Follow a closer `AGENTS.md` when one exists. Keep this guide focused on agent workflows; user-facing documentation lives in `README.md` and `docs/`. Format guidance: [agents.md](https://agents.md/).
+
+<!-- intent-skills:start -->
+## Skill Loading
+
+Before editing files for a substantial task:
+- Run `pnpm dlx @tanstack/intent@latest list` from the workspace root to see available local skills.
+- If a listed skill matches the task, run `pnpm dlx @tanstack/intent@latest load <package>#<skill>` before changing files.
+- Use the loaded `SKILL.md` guidance while making the change.
+- Monorepos: when working across packages, run the skill check from the workspace root and prefer the local skill for the package being changed.
+- Multiple matches: prefer the most specific local skill for the package or concern you are changing; load additional skills only when the task spans multiple packages or concerns.
+<!-- intent-skills:end -->
+
+<!-- caveman-begin -->
+Respond terse like smart caveman. All technical substance stay. Only fluff die.
+
+Rules:
+- Drop: articles (a/an/the), filler (just/really/basically), pleasantries, hedging
+- Fragments OK. Short synonyms. Technical terms exact. Code unchanged.
+- Pattern: [thing] [action] [reason]. [next step].
+- Not: "Sure! I'd be happy to help you with that."
+- Yes: "Bug in auth middleware. Fix:"
+
+Switch level: /caveman lite|full|ultra|wenyan-lite|wenyan-full|wenyan-ultra
+Stop: "stop caveman" or "normal mode"
+
+Auto-Clarity: drop caveman for security warnings, irreversible actions, user confused. Resume after.
+
+Boundaries: code/commits/PRs written normal.
+<!-- caveman-end -->
+
+<!-- BEGIN:turborepo-agent-rules -->
+
+# This is NOT the Turborepo you know
+
+Turborepo configuration, task behavior, and CLI commands can vary between installed versions and may differ from your training data. Resolve the `turbo` package from this file's directory or relevant workspace; in monorepos, it may not be visible from the repository root. For example, run `node -p "require.resolve('turbo/package.json')"` from a workspace that depends on `turbo`.
+
+Read `docs/README.md` inside that installed package first, then read the relevant pages from its `docs/` directory before changing Turborepo configuration or commands. Heed deprecation notices. These bundled docs match the installed package version and are available without network access.
+
+This block is written and re-added by `turbo` before repository-scoped commands when an AI agent is detected. In the Turborepo source repository, its template is defined in `crates/turborepo-cli/src/cli/agent_guidance.rs`. Removing the managed block while updates are enabled means a later qualifying invocation will add it again. Set `"agentGuidance": false` in the root `turbo.json` or `turbo.jsonc` to opt out; this does not remove an existing block. Keep the block committed with your work to avoid an uncommitted change on the next agent invocation.
+<!-- END:turborepo-agent-rules -->
+
+## Agent skills
+
+- Issues and specs: GitHub Issues for `reactive-resume/reactive-resume`. See `docs/agents/issue-tracker.md`.
+- Check `git status --short` before editing. Preserve unrelated changes, including existing edits in this file.
+- Use scripts and configuration as the source of truth when documentation disagrees with them.
+
+## Overview
+
+Reactive Resume is a free, open-source resume builder for creating, importing, exporting, and sharing resumes, cover letters, and job applications. It is a TypeScript pnpm monorepo managed by Turborepo, with two apps: `apps/web` (React 19 SPA with TanStack Router, TanStack Query, Tailwind CSS, and Vite) and `apps/server` (Hono / Node.js). oRPC connects browser workflows to server business logic; Better Auth handles authentication; Drizzle accesses PostgreSQL. Forme renders PDFs in the browser and on the server.
+
+The production Docker image runs a single Node.js process on port 3000; `apps/server` mounts the API/auth/MCP/static routes and serves the built web app. On Vercel, the `frontend` service serves static assets through its CDN and the `backend` service runs the same Hono application in a Node.js Function.
+
+Internal packages are source-consumed through `package.json` export maps pointing at `src` files. Do not assume package-local `dist` output exists unless a package explicitly adds it.
+
+## Setup
+
+Prerequisites: **Node.js 24** (`.nvmrc`, root `engines`, and Dockerfile), **pnpm 12.8.1** (root `packageManager`; pnpm self-manages to this version), and **Docker with Docker Compose** for local infrastructure. The Dockerfile's `ARG PNPM_VERSION` chooses its base image, not the project's pnpm version. Start your Docker daemon before running Compose.
+
+Run commands from the workspace root unless stated otherwise:
+
+```sh
+pnpm install --frozen-lockfile
+test -e .env.local || cp .env.example .env.local
+docker compose -f compose.dev.yml up -d postgres redis seaweedfs seaweedfs_create_bucket
+docker compose -f compose.dev.yml ps
+```
+
+Copy the environment template only when `.env.local` does not already exist. For host-run development, edit these values in `.env.local`; the template uses container hostnames:
+
+```dotenv
+APP_URL=http://localhost:3000
+DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres
+S3_ENDPOINT=http://localhost:8333
+REDIS_URL=redis://localhost:6379
+```
+
+Set `AUTH_SECRET` to a generated secret (`openssl rand -hex 32`). If using saved AI providers or the assistant, also set a separate `ENCRYPTION_SECRET` of at least 32 characters. For database-only development, start just `postgres` and set `STORAGE_BACKEND=local` to avoid the template's S3 defaults.
+
+## Development workflow
+
+```sh
+pnpm dev
+pnpm dev:web
+pnpm db:generate
+pnpm db:migrate
+pnpm db:studio
+```
+
+- `pnpm dev` runs Vite on `PORT` (default `3000`), Hono on `SERVER_PORT` (default `3001`), and the email template preview on `3002`. Vite proxies API requests to Hono. Vite supplies hot reload; `tsx watch` restarts the server.
+- `pnpm dev:web` starts only Vite; API workflows still need a server. If ports are busy, change `PORT` and `SERVER_PORT` consistently in `.env.local`; keep the email preview's `3002` port free when running all dev tasks.
+- Server startup applies migrations before initializing auth and serving traffic. `pnpm db:migrate` applies them without starting the app; `pnpm db:studio` opens the database UI.
+- After adding user-facing strings, use Lingui macros and run `pnpm lingui:extract`. Catalogs live in `apps/web/locales/*.po`; `pnpm pdf:translations` regenerates PDF translations. Root build/check scripts run PDF translation generation automatically.
+- `pnpm docs:gen` regenerates the OpenAPI spec and semantic CSS reference. Use it when changing those public surfaces.
+
+## Ownership map
+
+Where each concern lives, and where new code for it goes:
+
+| Area | Owner |
+|------|-------|
+| Web routes, loaders, user-facing workflows | `apps/web/src/routes`, `apps/web/src/features` (file-based; never hand-edit `routeTree.gen.ts`) |
+| Server HTTP routes/adapters, startup checks, static handlers, MCP transport, OpenAPI/well-known | `apps/server/src/{http,rpc,mcp,openapi,static,startup}` |
+| Authenticated API contracts + business logic | `packages/api/src/features/*` (oRPC routers, DTOs, rate limiting; aggregated at `@reactive-resume/api/routers` for `/api/rpc`) |
+| Auth | `packages/auth` (Better Auth config/helpers/types; `apps/server/src/http/auth.ts` delegates to `auth.handler`) |
+| DB client + schema | `packages/db` (Drizzle; migrations at repo root `migrations/`) |
+| Server env validation | `packages/env` (auto-loads root `.env`) |
+| Resume/page/template Zod schemas | `packages/schema` |
+| Pure resume-domain behavior (no DB/HTTP/DOM/renderer deps) | `packages/resume` (JSON Patch helpers, social-network icons) |
+| Resume PDF rendering | `packages/pdf` (React templates converted through `src/forme` to Forme documents, font resolution, browser/server adapters) |
+| PDF.js viewer/canvas UI | `apps/web/src/features/resume` — never in `packages/pdf` |
+| DOCX export | `packages/docx` |
+| MCP tools/prompts/resources/server-card | `packages/mcp` |
+| Generic UI primitives + hooks | `packages/ui` (Base UI/shadcn-style); workflow-specific UI stays in the owning web feature |
+| DeepSeek Harness integration | `packages/dsh-plugin` (separately built/published plugin) |
+| Focused support surfaces | `packages/fonts`, `packages/email`, `packages/import`, `packages/ai`, `packages/utils`, `packages/config` — prefer existing exports over cross-package shortcuts |
+| Dev-only scripts | `tooling/`, not `packages/`, so packages only hold runtime-bundled code |
+
+Narrow cross-cutting helpers go in `packages/utils` only after checking no domain package is a better owner. Specifically: resume JSON Patch behavior belongs in `@reactive-resume/resume/patch` and DOCX builders in `@reactive-resume/docx` — not in `@reactive-resume/utils`.
+
+## Web app conventions
+
+- `apps/web/src/router.tsx` initializes router context with `queryClient`, `orpc`, `theme`, `locale`, `session`, and `flags`. Reuse route context instead of refetching these ad hoc.
+- The web app is a client-rendered SPA. The web build prerenders marketing homepages per locale; there is no request-time React SSR. `apps/server/src/static/web.ts` serves HTML and injects OpenGraph, canonical, and JSON-LD metadata. When adding a public marketing route, update its server fallback/SEO handling as well as the TanStack route; Vite's dev fallback can otherwise hide production 404s.
+- Builder shell: `apps/web/src/routes/builder/$resumeId`. Public resume route: `apps/web/src/routes/$username/$slug.tsx`.
+- Browser-only preview code: `apps/web/src/features/resume/preview`. Public PDF viewer: `apps/web/src/features/resume/public`. Keep PDF.js/canvas code in these features, not in `packages/pdf`.
+- oRPC client: `apps/web/src/libs/orpc/client.ts` calls `/api/rpc` with credentials included. `apps/web/src/libs/orpc/fetch.ts` stages large request bodies through Blob on Vercel.
+- For React components with explicit props, use a named props type (e.g. `type FooProps = {...}` with `function Foo(props: FooProps)`) rather than inline object annotations, especially with more than one field or with generics.
+
+## Package boundaries
+
+`pnpm exec turbo boundaries` is the executable check. Rules:
+
+- Workspace deps go through package names and export maps. Never import another workspace's `src` tree via repo paths, `@reactive-resume/*/src/*`, or TS path aliases.
+- Workspace `turbo.json` files declare coarse tags: `app:web`, `app:server`, `runtime:server` (server-only packages: API/auth/db/env/email/MCP), `runtime:browser` (browser-only shared UI), `runtime:universal` (environment-neutral domain packages), plus `role:domain|infra|adapter|api|rendering|tooling` for intent.
+- Runtime-specific code lives behind explicit export subpaths (`@reactive-resume/pdf/browser`, `@reactive-resume/pdf/server`, `@reactive-resume/env/server`). Keep root exports environment-neutral unless the package is intentionally server-only.
+- Wildcard exports are allowed only for leaf libraries with an intentionally file-like surface — currently `@reactive-resume/ui/components/*`, `@reactive-resume/ui/hooks/*`, and schema resume/application model files. Prefer explicit exports for packages owning runtime behavior.
+- Prefer `protectedProcedure` from `packages/api/src/context.ts` for authenticated procedures. Expose only intentional public surfaces through `packages/api/package.json`.
+- Shared PDF section filtering: `packages/pdf/src/templates/shared/filtering.ts`. Template-specific visual exceptions stay in the owning template directory unless multiple templates need the behavior. `packages/pdf/src/hooks/use-register-fonts.ts` resolves font families, weights, and script fallback stacks; the Forme adapter owns conversion/rendering. PDF generation needs no Browserless or Chromium service.
+
+Multi-place changes:
+
+- **Resume data shape**: `packages/schema/src/resume/*` first, then API DTOs, importers, PDF rendering, and web forms consuming it.
+- **New template**: `packages/schema/src/templates.ts`, `packages/pdf/src/templates/index.ts`, source under `packages/pdf/src/templates/<name>/`, and previews under `apps/web/public/templates/{jpg,pdf}`.
+- **New DB column/table**: `packages/db/src/schema/*`, then `pnpm db:generate`.
+- **New env var**: `packages/env/src/server.ts`, `.env.example`, **and** the `globalEnv` array in `turbo.json`. Add deployment aliases in `packages/env/src/deployment.ts` when needed. Turborepo strict env mode filters unlisted injected variables from task processes.
+
+## Environment and database
+
+Host development requires `APP_URL`, `DATABASE_URL`, and non-empty `AUTH_SECRET`. `packages/env/src/server.ts` also loads root `.env` through Node's native `process.loadEnvFile`; existing process variables take precedence. Root dev/database scripts explicitly load `.env.local` through `dotenvx`. Tests and application code can have their own environment loaders; do not assume every command loads `.env.local`.
+
+- **Storage**: explicit `STORAGE_BACKEND=local|s3|blob` wins. Otherwise, complete S3 credentials select S3; Vercel selects private Blob; other deployments select local storage. `.env.example` ships SeaweedFS defaults, so either run SeaweedFS or select `local`/remove the S3 credentials. Local storage defaults to `<workspace>/data` in development and `/app/data` in Docker. `LOCAL_STORAGE_PATH` must be absolute and writable; persist it in deployed installations.
+- **`ENCRYPTION_SECRET`** is required for saved AI providers and the assistant. **`REDIS_URL`** is optional outside Vercel; it shares rate limits, cancellation and resumable replies between processes. Vercel deployment preparation requires Redis. Host-run dev uses `REDIS_URL=redis://localhost:6379`; the container-run app uses `redis://redis:6379`.
+- **`drizzle-kit` (used by `pnpm db:migrate`) reads `DATABASE_URL` from `process.env` directly** — it does not auto-load `.env`. The root migration scripts load `.env.local` through `dotenvx` before invoking Drizzle Kit.
+- `DATABASE_MIGRATION_URL` supplies a direct migration connection when runtime `DATABASE_URL` is pooled. Review generated migration SQL before applying it; avoid resetting databases or deleting volumes to fix setup errors.
+- Startup verifies the migrated schema. `STRICT_SCHEMA_CHECK=true` makes detected drift fatal; otherwise the server logs it and continues.
+
+## Testing and checks
+
+Prefer package-scoped checks for the files changed. Package names come from their `package.json`: the apps are `web` and `server`, most shared packages are `@reactive-resume/<name>`.
+
+```sh
+pnpm --filter web typecheck
+pnpm --filter @reactive-resume/pdf test
+pnpm --filter @reactive-resume/pdf test src/templates/shared/filtering.test.ts
+pnpm --filter @reactive-resume/pdf exec vitest run src/templates/shared/filtering.test.ts -t "filterItems"
+pnpm --filter @reactive-resume/pdf test:coverage
+pnpm exec biome check apps/web/src/features/resume
+pnpm exec turbo boundaries
+```
+
+- Vitest tests live alongside source as `src/**/*.test.ts(x)` or `src/**/*.spec.ts(x)` (including integration tests). Paths under `pnpm --filter <package>` are package-relative. Pass paths directly after `test`: an extra `--` currently prevents Vitest from filtering the run. Shared settings live in `vitest.shared.mts` and setup in `vitest.setup.ts`; most packages use Node, while `packages/ui` uses `happy-dom`.
+- Coverage uses V8 and writes package-local `coverage/` reports. No shared minimum coverage threshold is configured. `test:ci` writes JSON/JUnit results under package-local `reports/`.
+- Root `pnpm test`, `pnpm test:coverage`, and `pnpm typecheck` run workspace checks through Turbo. CI runs `pnpm exec turbo run test:ci --concurrency=1` to avoid CPU contention in PDF/rate-limit suites.
+- Real-database unit suites use `COVER_LETTER_TEST_DATABASE_URL` and `OAUTH_TEST_DATABASE_URL`; see `.github/workflows/e2e.yml` for isolated database setup. Never point test fixtures at production data.
+- After changing shared contracts, exports, or imports, check affected consumers and run `pnpm exec turbo boundaries`.
+
+### Browser tests
+
+Playwright specs live in `tests/e2e/specs/*.spec.ts`, with fixtures in `tests/e2e/fixtures`. Configure a disposable PostgreSQL database and export test environment variables before building/running; these root scripts do not wrap `dotenvx`.
+
+```sh
+pnpm exec playwright install chromium
+pnpm build
+pnpm test:e2e
+pnpm test:e2e tests/e2e/specs/auth.spec.ts
+pnpm test:e2e:ui
+```
+
+- `playwright.config.ts` starts `node apps/server/dist/index.mjs` in production mode and waits for `/api/health`; locally it can reuse an existing server. Build first. Keep the direct Node command: pnpm's script process groups can prevent Playwright from cleaning up a server started through `pnpm start`.
+- Export `APP_URL`, `PORT`, `DATABASE_URL`, `AUTH_SECRET`, and `ENCRYPTION_SECRET`, and choose an absolute writable `LOCAL_STORAGE_PATH`. Auth fixtures need signups/email auth enabled; `FLAG_DISABLE_API_RATE_LIMIT=true` is appropriate for this isolated test installation.
+- Assistant specs use a deterministic local AI stub and need `FLAG_ALLOW_UNSAFE_AI_BASE_URL=true`; otherwise those specs skip. See `tests/e2e/README.md` for the full environment recipe; adapt its example storage path to your machine.
+- Playwright runs Chromium with no retries. CI uses one worker and retains failure traces, screenshots, videos, and reports. PDF/DOCX rasterization and visual regression are outside this browser gate.
+
+## Code style
+
+- TypeScript is strict, including `exactOptionalPropertyTypes`, `noUncheckedIndexedAccess`, and unused-symbol checks; packages typecheck with `tsgo --noEmit`.
+- Biome uses tabs, double quotes, 120-column lines, separated type imports, organized import groups, and sorted Tailwind classes in `clsx`, `cva`, and `cn`. Use existing file naming and feature-local conventions.
+- **`pnpm check` modifies files**: it regenerates PDF translations and runs Biome with `--write --unsafe`. Call out its write behavior and review the diff; use narrow non-mutating commands when inspecting unrelated edits.
+- Lefthook's pre-commit hook checks conflict markers and runs write-capable Biome on supported staged files, staging fixes. The commit-message hook enforces Conventional Commits (`fix:`, `feat:`, `docs:`, etc.).
+
+## Build and deployment
+
+```sh
+pnpm build
+NODE_ENV=production pnpm start
+docker compose up -d --build
+```
+
+- Build outputs: `apps/web/dist` (SPA/assets), `apps/web/dist-prerender` (localized marketing HTML), and `apps/server/dist` (`index.mjs` plus server/deployment chunks). `pnpm start` runs the built server; set `NODE_ENV=production` so it uses `PORT` instead of `SERVER_PORT`. Export runtime variables or provide root `.env`; `.env.local` is not loaded by `start`.
+- Production Compose loads `.env.example` then `.env`, not `.env.local`. Configure `.env` with container hostnames (`postgres`, `redis`, `seaweedfs`) and production secrets before running it. The Docker image runs as `node`, listens on `3000`, and persists local storage through `/app/data`. Health endpoint: `/api/health`.
+- `vercel.json` defines Vercel Services (project framework must be `Services`): `frontend` (`apps/web`, static `dist`) and `backend` (`apps/server`, entrypoint `apps/server/vercel.mjs` re-exporting the tsdown build). The backend build runs `pnpm build` for both apps, then `node apps/server/dist/prepare-deployment.mjs`. Top-level rewrites send paths whose last segment has a file extension to `frontend` and everything else, including HTML shells, to `backend`, except the server-owned paths listed first. The Function uses Node 24 and a 300-second budget. `outputDirectory: "."` on `backend` stops the builder from treating `dist/index.mjs` (the Docker entrypoint) as the handler.
+- Vercel environment normalization accepts `POSTGRES_URL`, direct/unpooled DB aliases, and `KV_URL`. `APP_URL` can be derived from Vercel host variables. Blob is the default when no S3 credentials are set. Preview deployments require isolated resources before enabling `ALLOW_PREVIEW_MIGRATIONS=true`; see `docs/self-hosting/vercel.mdx`.
+- `.github/workflows/e2e.yml` gates core unit/browser flows; `vercel.yml` builds and checks the serverless artifact on PRs and pushes to `main`. `autofix.yml` runs write-capable `pnpm knip --fix` and `pnpm check`. GitHub runners are the default; `USE_BLACKSMITH=true` switches runners and paired actions.
+- `docker-build.yml` publishes native AMD64/ARM64 images. `main` publishes nightly aliases; release tags/explicit release dispatch publish stable aliases and can trigger configured production integrations. See `docs/agents/container-publishing.md` before release work.
+- Deployment smoke tests create/delete accounts and files; run only against a dedicated test installation. Details: `docs/contributing/deployment-checks.mdx`.
+
+## Security and pull requests
+
+- Keep credentials and personal resume data out of source, logs, test artifacts, issues, and PRs. Do not commit local environment files or substitute production secrets for test values.
+- Authenticated procedures use `protectedProcedure`; enforce resource ownership in feature logic. Reuse shared auth resolution for API keys, bearer tokens, and cookies rather than adding a separate auth path.
+- Keep unsafe OAuth redirect/AI URL flags disabled on public deployments. They relax redirect validation and SSRF protections for trusted self-hosted/test use.
+- Keep PRs focused. Describe the problem, resulting behavior, and checks actually run; link the relevant GitHub issue. Conventional Commits are enforced for commit messages; no separate PR-title convention is configured.
+- Before submitting, run applicable typechecks/tests and non-mutating lint checks; run the production build for runtime/bundling changes. Match CI's database/browser prerequisites when reproducing its checks. Report skipped checks and failures instead of claiming they passed.
+- Never add AI attribution, co-author trailers naming AI tools, or session/chat links to commits or PR descriptions.
+
+## Gotchas
+
+- Email sending needs SMTP config; without it emails are logged to console. Dev still works — verification links appear in server logs.
+- Database connection errors: check `docker compose -f compose.dev.yml ps` and use `localhost` for host-run code, service names inside containers.
+- S3 errors: check `docker compose -f compose.dev.yml logs seaweedfs seaweedfs_create_bucket`; verify endpoint and bucket, or select local storage.
+- Route-tree errors after adding routes: run Vite dev/build to regenerate `apps/web/src/routeTree.gen.ts`; never edit it by hand.
+- Serverless module-loading failures: inspect `bundledInteropPackages` in `apps/server/tsdown.config.ts` and the Vercel compatibility workflow. External CommonJS server dependencies break on Vercel because its service builder drops their pnpm links; bundle them with their dependencies.
+- Most test scripts use `--passWithNoTests`; a successful run with zero tests does not verify the behavior you changed.

CLAUDE.md

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

DESIGN.md

@@ -0,0 +1,205 @@
+---
+version: 6.0.0
+name: Reactive Resume · Desk & Paper
+description: A quiet, warm desk around a bright page. The resume is the only white, detailed object on screen; one moss-green accent marks the next action. Light and dark themes, with the page always white.
+colors:
+  light:
+    bg: "#F8F7F3"
+    surface: "#FEFDFC"
+    raised: "#FFFFFF"
+    sunken: "#F0EFEB"
+    line: "#DFDEDA"
+    line-2: "#C5C4BE"
+    ink: "#1C1B15"
+    ink-2: "#4F4D47"
+    ink-3: "#6D6C65"
+    accent: "#337344"
+    accent-hover: "#206133"
+    on-accent: "#F7FEF8"
+    accent-soft: "#DCF2DF"
+    accent-text: "#195C2E"
+    danger: "#BA3630"
+    danger-soft: "#FFE7E4"
+    danger-text: "#A92321"
+    warn: "#D29922"
+    warn-soft: "#FCEDCD"
+    warn-text: "#81520A"
+    info-soft: "#E0F1FF"
+    info-text: "#1D5B92"
+  dark:
+    bg: "#100F0C"
+    surface: "#171613"
+    raised: "#1F1E1A"
+    sunken: "#0B0A08"
+    line: "#2C2B27"
+    line-2: "#494843"
+    ink: "#EFEEEB"
+    ink-2: "#BCBAB5"
+    ink-3: "#979590"
+    accent: "#6FC082"
+    accent-hover: "#83D494"
+    on-accent: "#07150A"
+    accent-soft: "#1A3520"
+    accent-text: "#8FD89E"
+    danger: "#D9544B"
+    danger-soft: "#47211D"
+    danger-text: "#FDA297"
+    warn: "#E4B750"
+    warn-soft: "#3E2D10"
+    warn-text: "#EFCC83"
+    info-soft: "#192F46"
+    info-text: "#9DC9F7"
+  paper: "#FFFFFF"
+  stages:
+    saved: "#908C7F"
+    applied: "#5590CC"
+    screening: "#00A0A6"
+    interview: "#AF8433"
+    offer: "#579F68"
+    closed: "#C67067"
+typography:
+  display: { fontFamily: Newsreader, fontSize: 44px, lineHeight: 48px, fontWeight: 500, letterSpacing: -0.01em }
+  title: { fontFamily: Newsreader, fontSize: 30px, lineHeight: 36px, fontWeight: 500 }
+  sheet-title: { fontFamily: Newsreader, fontSize: 22px, lineHeight: 28px, fontWeight: 500 }
+  heading: { fontFamily: Hanken Grotesk, fontSize: 20px, lineHeight: 28px, fontWeight: 600 }
+  section-heading: { fontFamily: Hanken Grotesk, fontSize: 17px, lineHeight: 24px, fontWeight: 600 }
+  label: { fontFamily: Hanken Grotesk, fontSize: 15px, lineHeight: 22px, fontWeight: 600 }
+  body: { fontFamily: Hanken Grotesk, fontSize: 15px, lineHeight: 24px, fontWeight: 400 }
+  ui: { fontFamily: Hanken Grotesk, fontSize: 14px, lineHeight: 20px, fontWeight: 400 }
+  small: { fontFamily: Hanken Grotesk, fontSize: 13px, lineHeight: 18px, fontWeight: 400 }
+  caption: { fontFamily: Hanken Grotesk, fontSize: 12px, lineHeight: 16px, fontWeight: 500 }
+  mono: { fontFamily: JetBrains Mono, fontSize: 12px, lineHeight: 16px, fontWeight: 500 }
+rounded:
+  sm: 6px
+  md: 8px
+  lg: 10px
+  xl: 12px
+  2xl: 16px
+  3xl: 18px
+  full: 999px
+spacing: [4, 8, 12, 16, 24, 32, 48, 64]
+motion:
+  quick: 120ms
+  standard: 200ms
+  emphasized: 320ms
+  easing: cubic-bezier(0.2, 0.8, 0.2, 1)
+  exit: 70% of the entering duration
+---
+
+## Overview
+
+Reactive Resume's interface is a quiet, warm desk around a bright page. The resume or letter page is the only white, detailed object on screen; everything around it uses low-contrast warm neutrals, thin rules instead of boxes, and a single moss-green accent.
+
+The full specification lives in the redesign handoff (`design_handoff_reactive_resume_redesign/README.md`, kept out of version control) and the milestone plan in `REDESIGN_PLAN.md`. This document records the rules the code follows.
+
+Five principles decide most questions:
+
+1. **The page is the interface.** The live page is on screen in every editor mode. Clicking a line on the page opens its field.
+2. **One obvious next step.** Each view has at most one accent-filled button. Accent means "do this next" or "this is working" and is never decoration.
+3. **Nothing is lost.** Everything autosaves and can be undone. Confirmation dialogs are only for irreversible actions.
+4. **Detail on demand.** Defaults cover most people; advanced controls sit one disclosure deeper.
+5. **AI proposes, you decide.** The assistant never writes directly; every change is a reviewable proposal.
+
+Resume templates keep their Pokémon names (Azurill, Onyx, Glalie…), their own fonts and their own colors. None of the rules below apply inside a template.
+
+## Tokens
+
+Tokens are CSS custom properties in `packages/ui/src/styles/globals.css`, light on `:root` and dark on `.dark`. The source of truth is oklch; the hex values above are sRGB approximations. Tailwind exposes each one under the same name: `bg-bg`, `bg-surface`, `bg-raised`, `bg-sunken`, `border-line`, `border-line-2`, `text-ink`, `text-ink-2`, `text-ink-3`, `bg-accent`, `text-on-accent`, `bg-accent-soft`, `text-accent-text`, `bg-danger`, `bg-danger-soft`, `text-danger-text`, `bg-warn`, `bg-warn-soft`, `text-warn-text`, `bg-info-soft`, `text-info-text`, `bg-hover`, `bg-press`, `bg-scrim`, `bg-paper` and `bg-stage-*`.
+
+- **Surfaces:** `bg` is the app desk, `surface` holds panels and cards, `raised` holds menus, dialogs and inputs, `sunken` is for wells, tracks and the page canvas.
+- **Text:** `ink` for primary text, `ink-2` for secondary text, `ink-3` for meta and placeholders. `ink-3` is the lightest color allowed for text (about 4.9:1).
+- **Signals:** `danger` for errors and irreversible actions, `warn` for check issues and things to review, `info` for neutral guidance and the assistant's questions. Success uses `accent-soft`.
+- **Overlays:** `hover` and `press` are translucent, so they work on any surface.
+- **Paper:** `--paper` is white in both themes. Pages never invert.
+- **Stages:** application stage colors share lightness and chroma. They appear only as 8px dots or 6px stepper bars, always next to the stage name.
+
+The previous shadcn-style names (`background`, `foreground`, `primary`, `muted`, `border`, `input`, `ring`, `destructive`, `card`, `popover`, `sidebar-*`) still resolve to these tokens so screens that haven't been rebuilt stay legible. Don't use them in new code; they're removed once every screen has moved.
+
+## Typography
+
+- **Newsreader** (display serif, optical sizes 6–72) is only for page titles, dialog and sheet titles, empty-state headlines and large stat numerals. Use `font-display`.
+- **Hanken Grotesk** handles everything functional. It's the default `font-sans`.
+- **JetBrains Mono** is for shortcuts, URLs and slugs, file names, counts and section eyebrows. Use `font-mono`.
+- Field labels are 12px, medium weight, `ink-2`, above the control with a 5–6px gap. Uppercase group eyebrows are 12px semibold `ink-3` with 0.02em tracking.
+- Inputs render at 16px on touch devices so iOS doesn't zoom.
+- All three fonts are self-hosted through `@fontsource-variable`.
+
+## Iconography
+
+App icons are **Material Symbols Rounded** at weight 300, rendered by `Icon` from `@reactive-resume/ui/components/icon`. The font is a self-hosted subset that contains only the glyphs listed in `packages/ui/src/icons/names.ts`:
+
+1. Add the name to that list (TypeScript then accepts it in `<Icon name="…" />`).
+2. Run `pnpm icons:build`. The script checks every name against the published codepoints, downloads the subset and updates the manifest. A unit test fails if the manifest and the list disagree.
+
+Rules:
+
+- 20px on desktop, 24px on touch. Outline by default; `filled` only for the selected navigation item.
+- Icons always sit beside a text label, except back, close, more, undo/redo, history, assistant and zoom. Those use `IconButton`, which requires a label and shows it in a tooltip with the shortcut.
+- `Icon` is `aria-hidden` and `translate="no"`, so the ligature text never becomes an accessible name.
+- Directional icons (arrows, chevrons, undo, redo) mirror in right-to-left layouts automatically.
+- Icons inside resumes are a separate system: Phosphor, because resume data stores Phosphor names and the PDF renderer draws them.
+
+## Space, shape and elevation
+
+- **Spacing** follows a 4pt scale: 4, 8, 12, 16, 24, 32, 48, 64. Cards use 16px padding, panels 16–24px, the mobile margin is 16px and the desktop page margin 32–40px.
+- **Radius:** `rounded-sm` 6px for chips and small buttons, `rounded-md` 8px for controls and inputs, `rounded-lg` 10px for list items, `rounded-xl` 12px for cards and menus, `rounded-2xl` 16px for dialogs, `rounded-3xl` 18px for mobile sheets, `rounded-full` for pills.
+- **Elevation:** `shadow-e1` for cards, `shadow-e2` for menus, popovers and hover-lifted cards, `shadow-e3` for dialogs, sheets and toasts, `shadow-page` for the resume page on the canvas.
+- **Control heights:** 28px small, 36px default, 44px touch. Icon buttons are 32–36px on desktop and 44px on touch.
+- **Layout constants** are CSS variables: `--editor-bar` 56px, `--editor-panel` 400px, `--app-sidebar` 240px, `--sheet-share` 440px, `--sheet-detail` 480px, `--assistant` 400px.
+
+## Motion
+
+| Token | Duration | Use |
+|---|---|---|
+| `duration-quick` | 120ms | hover, press, toggle, checkbox, focus |
+| `duration-standard` | 200ms | menus, popovers, expand and collapse, mode switch, dialogs |
+| `duration-emphasized` | 320ms | side and bottom sheets, toasts, the assistant column |
+
+- Everything that enters uses `ease-enter` (`cubic-bezier(0.2, 0.8, 0.2, 1)`). Exits run at 70% of the duration.
+- Motion explains where something went. Nothing loops, bounces or plays on load; loading placeholders stay still. Reflowing the page after an edit is never animated.
+- With `prefers-reduced-motion`, the duration tokens become 1ms and every CSS transition collapses; spinners keep turning because they're status.
+- Motion (`motion/react`) animations run under `MotionConfig reducedMotion="user"`; mirror the tokens in `apps/web/src/libs/motion.ts` when one needs them.
+
+## Components
+
+Generic primitives live in `packages/ui/src/components` and wrap Base UI (and cmdk for the command bar). Feature-specific UI lives with its feature in `apps/web`.
+
+- **Buttons:** `primary` (accent fill, the one filled button per view), `secondary` (bordered surface), `ghost`, `danger`, `link`. Sizes `sm` 28, `default` 36, `lg` 44 (touch), plus icon sizes. `loading` shows a spinner, sets `aria-busy` and blocks activation; pair it with a present-participle label ("Preparing…").
+- **Inputs:** 36px (44px on touch), `raised` background, `line-2` border. Focus is an accent border plus a 3px `accent-soft` ring. Errors appear after the first blur, in `danger-text`, with an icon and words that say how to fix it.
+- **Switches:** prefer `SwitchRow`, where the whole row is the switch. Checkboxes are 18px with a 5px radius; radios are 18px with an 8px accent dot.
+- **Segmented controls:** `SegmentedControl` for 2–4 options (a radio group); `Tabs` with the default variant when segments switch panels, `Tabs variant="line"` for underline tabs.
+- **Menus** (dropdown, context, combobox lists): 220px minimum width, 12px radius, 36px items, destructive items last after a separator.
+- **Layers, lightest to heaviest:** menu, popover, sheet, dialog. Sheets are for tasks beside the page and become bottom sheets on mobile. Dialogs are for decisions; destructive confirmations use `AlertDialog` and the cancel label says what is kept.
+- **Toasts:** one at a time, bottom center, ink on the desk color, 6 seconds, with an optional underlined Undo action.
+- **Alerts:** `info`, `success`, `warn` and `error`; only errors are announced (`role="alert"`).
+- **Empty states:** a Newsreader 22px headline, a 14px body up to 300px wide, then a primary and a secondary action.
+
+## Accessibility
+
+WCAG 2.2 AA is the floor.
+
+- Every interactive element shows a 2px accent focus ring with a 2px gap on `:focus-visible`. Never remove it; inputs replace it with their accent border and soft ring.
+- Pointer targets are at least 24px and touch targets at least 44px. Every drag has a keyboard and a menu alternative.
+- Color is never the only signal: stages, issues and states always pair color with text and an icon.
+- Sheets and dialogs trap focus; Esc closes the top layer and returns focus to its trigger. Save state and toasts announce through a polite live region.
+
+## Themes
+
+The theme cookie holds `light`, `dark` or `system` (the default); `system` follows `prefers-color-scheme` live. `ThemeProvider` owns the `.dark` class on `<html>`, and an inline script in `index.html` sets it before first paint. Resumes and letters always render on white paper, whatever the theme.
+
+## Internationalization
+
+- Every user-facing string goes through Lingui (`t`, `msg`, `<Trans>`); catalogs are PO files in `apps/web/locales`. Primitives in `packages/ui` can't use Lingui, so they take labels as props (for example `closeLabel`).
+- 55 interface languages, including right-to-left ones. `<html dir>` follows the locale and `DirectionProvider` passes it to Base UI.
+- Use logical properties (`ps`, `pe`, `ms`, `me`, `inset-s`, `inset-e`) instead of physical ones.
+- Translations run 30–50% longer than English; avoid fixed widths on text.
+
+## Do and don't
+
+- **Do** keep one accent-filled button per view, and keep accent for next actions and working states.
+- **Do** use `ink-3` as the lightest text color, and pair every color signal with text.
+- **Do** build states in full: empty, loading (placeholders at their real size), error (why and what to do) and success.
+- **Don't** hard-code colors, including Tailwind palette classes such as `amber-600`; use the semantic tokens.
+- **Don't** use Newsreader for anything smaller than a sheet title.
+- **Don't** ask for confirmation for something that can be undone; use an undo toast instead.
+- **Don't** skip `data-slot` on primitives; tests and styles rely on it.

Dockerfile

@@ -1,22 +1,23 @@
 # syntax=docker/dockerfile:1.7
 
+# Base image only; pnpm self-manages to the `packageManager` version in package.json.
+ARG PNPM_VERSION=11.21.0
 ARG NODE_VERSION=24
 
-FROM node:${NODE_VERSION}-slim AS base
+FROM ghcr.io/pnpm/pnpm:${PNPM_VERSION} AS base
+
+ARG NODE_VERSION
+
+RUN pnpm runtime set node ${NODE_VERSION} -g --config.store-dir=/pnpm/runtime-store
 
 WORKDIR /app
 
-ENV COREPACK_ENABLE_DOWNLOAD_PROMPT=0 \
-    PNPM_HOME="/pnpm" \
-    PATH="/pnpm:$PATH" \
-    TURBO_TELEMETRY_DISABLED=1
-
-RUN corepack enable
+ENV TURBO_TELEMETRY_DISABLED=1
 
 FROM base AS pruner
 COPY . .
 RUN --mount=type=cache,id=pnpm-store,target=/pnpm/store,sharing=locked \
-    pnpm dlx turbo@2.9.9 prune web --docker
+    pnpm dlx turbo@2.9.12 prune web server --docker
 
 FROM base AS builder
 COPY --from=pruner /app/out/json/ ./
@@ -25,18 +26,18 @@ RUN --mount=type=cache,id=pnpm-store,target=/pnpm/store,sharing=locked \
     pnpm install --frozen-lockfile
 
 COPY --from=pruner /app/out/full/ ./
-RUN pnpm turbo run build --filter=web
+RUN rm -rf apps/web/dist apps/web/dist-prerender 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.9 prune @reactive-resume/runtime-externals --docker
+    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 --filter=@reactive-resume/runtime-externals deploy --prod --legacy /runtime-deps
+    pnpm install --prod --frozen-lockfile
 
 FROM node:${NODE_VERSION}-slim AS runtime
 
@@ -47,25 +48,31 @@ LABEL org.opencontainers.image.description="A free and open-source resume builde
 LABEL org.opencontainers.image.vendor="Amruth Pillai"
 LABEL org.opencontainers.image.url="https://rxresu.me"
 LABEL org.opencontainers.image.documentation="https://docs.rxresu.me"
-LABEL org.opencontainers.image.source="https://github.com/amruthpillai/reactive-resume"
+LABEL org.opencontainers.image.source="https://github.com/reactive-resume/reactive-resume"
 
 ENV NODE_ENV="production" \
-    PORT=3000
+    PORT=3000 \
+    LOCAL_STORAGE_PATH=/app/data
 
 WORKDIR /app
 
-RUN mkdir -p /app/apps/web /app/data && chown node:node /app/data
+RUN mkdir -p /app/apps/server /app/apps/web /app/data && chown node:node /app/data
 
-COPY --from=runtime-deps --chown=node:node /runtime-deps/node_modules ./node_modules
-COPY --from=builder --chown=node:node /app/apps/web/.output ./apps/web/.output
+COPY --from=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/web/dist-prerender ./apps/web/dist-prerender
+COPY --from=builder --chown=node:node /app/apps/server/dist ./apps/server/dist
 COPY --from=pruner --chown=node:node /app/migrations ./migrations
 
-WORKDIR /app/apps/web
+WORKDIR /app
 
 USER node
 
 EXPOSE 3000/tcp
 HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
-    CMD ["node", "-e", "fetch('http://127.0.0.1:3000/api/health').then((r) => { if (!r.ok) process.exit(1); }).catch(() => process.exit(1));"]
+    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));"]
 
-CMD ["node", ".output/server/index.mjs"]
+CMD ["node", "apps/server/dist/index.mjs"]

Dockerfile.dev

@@ -0,0 +1,47 @@
+# syntax=docker/dockerfile:1.7
+
+# Base image only; pnpm self-manages to the packageManager version.
+ARG PNPM_VERSION=11.21.0
+ARG NODE_VERSION=24
+
+FROM ghcr.io/pnpm/pnpm:${PNPM_VERSION} AS dev
+
+ARG NODE_VERSION
+
+RUN pnpm runtime set node ${NODE_VERSION} -g --config.store-dir=/pnpm/runtime-store
+
+WORKDIR /app
+
+ENV NODE_ENV=development \
+	TURBO_TELEMETRY_DISABLED=1
+
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml turbo.json ./
+COPY 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 packages/docx/package.json ./packages/docx/package.json
+COPY packages/mcp/package.json ./packages/mcp/package.json
+COPY packages/resume/package.json ./packages/resume/package.json
+COPY packages/dsh-plugin/package.json ./packages/dsh-plugin/package.json
+COPY tooling/package.json ./tooling/package.json
+
+RUN --mount=type=cache,id=reactive-resume-dev-pnpm-store,target=/pnpm/store,sharing=locked \
+	pnpm install --frozen-lockfile
+
+COPY . .
+
+EXPOSE 3000/tcp 3001/tcp
+
+CMD ["pnpm", "run", "dev"]

GLOSSARY.md

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

README.md

@@ -1,3 +1,9 @@
+> [!IMPORTANT]
+> **Repository moved:** Reactive Resume now lives at **[`reactive-resume/reactive-resume`](https://github.com/reactive-resume/reactive-resume)** on GitHub.
+> **Docker Hub stays at `amruthpillai/reactive-resume`.** GHCR builds now publish to `ghcr.io/reactive-resume/reactive-resume`.
+> Verified image tags: `latest`, `v5`, `v5.3`, and `v5.3.0` (AMD64 and ARM64). The current version was rebuilt and production redeployed for this rename; no new GitHub release or version bump was made. See [migration details](https://github.com/reactive-resume/reactive-resume/issues/3503).
+> GitHub Sponsors and Open Collective funding links remain unchanged.
+
 <div align="center">
   <a href="https://rxresu.me">
     <img src="apps/web/public/opengraph/banner.jpg" alt="Reactive Resume" />
@@ -5,7 +11,7 @@
 
   <h1>Reactive Resume</h1>
 
-  <p>Reactive Resume is a free and open-source resume builder that simplifies the process of creating, updating, and sharing your resume.</p>
+  <p>Reactive Resume is a free and open-source resume builder that makes it easy to create, update, and share your resume.</p>
 
   <p>
     <a href="https://rxresu.me"><strong>Get Started</strong></a>
@@ -14,39 +20,39 @@
   </p>
 
   <p>
-    <img src="https://img.shields.io/github/package-json/v/amruthpillai/reactive-resume?style=flat-square" alt="Reactive Resume Version">
-    <img src="https://img.shields.io/github/stars/amruthpillai/Reactive-Resume?style=flat-square" alt="GitHub Stars">
-    <img src="https://img.shields.io/github/license/amruthpillai/Reactive-Resume?style=flat-square" alt="License" />
+    <img src="https://img.shields.io/github/package-json/v/reactive-resume/reactive-resume?style=flat-square" alt="Reactive Resume Version">
+    <img src="https://img.shields.io/github/stars/reactive-resume/reactive-resume?style=flat-square" alt="GitHub Stars">
+    <img src="https://img.shields.io/github/license/reactive-resume/reactive-resume?style=flat-square" alt="License" />
     <img src="https://img.shields.io/docker/pulls/amruthpillai/reactive-resume?style=flat-square" alt="Docker Pulls" />
     <a href="https://discord.gg/aSyA5ZSxpb"><img src="https://img.shields.io/discord/1173518977851473940?style=flat-square&label=discord" alt="Discord" /></a>
     <a href="https://crowdin.com/project/reactive-resume"><img src="https://badges.crowdin.net/reactive-resume/localized.svg?style=flat-square" alt="Crowdin" /></a>
     <a href="https://github.com/sponsors/AmruthPillai"><img src="https://img.shields.io/github/sponsors/AmruthPillai?style=flat-square&label=sponsors" alt="Sponsors" /></a>
-    <a href="https://opencollective.com/reactive-resume"><img src="https://img.shields.io/opencollective/backers/reactive-resume?style=flat-square&label=donations" alt="Donations" /></a>
+    <a href="https://opencollective.com/reactive-resume/donate"><img src="https://img.shields.io/opencollective/backers/reactive-resume?style=flat-square&label=donations" alt="Donations" /></a>
   </p>
 </div>
 
 ---
 
-Reactive Resume makes building resumes straightforward. Pick a template, fill in your details, and export to PDF—no account required for basic use. For those who want more control, the entire application can be self-hosted on your own infrastructure.
+Pick a template, fill in your details, and export to PDF. Basic use needs no account. If you want more control, you can run the whole application on your own infrastructure.
 
-Built with privacy as a core principle, Reactive Resume gives you complete ownership of your data. The codebase is fully open-source under the MIT license, with no tracking, no ads, and no hidden costs.
+You own your data. The codebase is open source under the MIT license, with no tracking, no ads, and no hidden costs.
 
 ## Features
 
 **Resume Building**
 
-- Real-time preview as you type
-- Multiple export formats (PDF, JSON)
+- Live preview as you type
+- Multiple export formats (PDF, JSON, DOCX)
 - Drag-and-drop section ordering
 - Custom sections for any content type
-- Rich text editor with formatting support
+- Rich text editor
 
 **Templates**
 
-- Professionally designed templates
-- A4 and Letter size support
+- 15 templates to choose from
+- A4 and Letter page sizes
 - Customizable colors, fonts, and spacing
-- Custom CSS for advanced styling
+- Structured Style Rules for section and text styling
 
 **Privacy & Control**
 
@@ -61,7 +67,7 @@ Built with privacy as a core principle, Reactive Resume gives you complete owner
 - Multi-language support
 - Share resumes via unique links
 - Import from JSON Resume format
-- Dark mode support
+- Dark mode
 - Passkey and two-factor authentication
 
 ## Templates
@@ -130,6 +136,10 @@ Built with privacy as a core principle, Reactive Resume gives you complete owner
       <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>
 
@@ -139,7 +149,7 @@ The quickest way to run Reactive Resume locally:
 
 ```bash
 # Clone the repository
-git clone https://github.com/amruthpillai/reactive-resume.git
+git clone --depth=1  https://github.com/reactive-resume/reactive-resume.git reactive-resume
 cd reactive-resume
 
 # Start all services
@@ -149,44 +159,48 @@ docker compose up -d
 open http://localhost:3000
 ```
 
-[![Build with Ona](https://ona.com/build-with-ona.svg)](https://app.ona.com/#https://github.com/amruthpillai/reactive-resume)
-
 For detailed setup instructions, environment configuration, and self-hosting guides, see the [documentation](https://docs.rxresu.me).
 
 ## Tech Stack
 
 | Category         | Technology                      |
 | ---------------- | ------------------------------- |
-| Framework        | TanStack Start (React 19, Vite) |
+| Framework        | TanStack Router (React 19, Vite) |
 | Runtime          | Node.js                         |
 | Language         | TypeScript                      |
 | Database         | PostgreSQL with Drizzle ORM     |
 | API              | ORPC (Type-safe RPC)            |
 | Auth             | Better Auth                     |
 | Styling          | Tailwind CSS                    |
-| UI Components    | Radix UI                        |
+| UI Components    | Base UI + shadcn-style package  |
 | State Management | Zustand + TanStack Query        |
 
 ## Documentation
 
-Comprehensive guides are available at [docs.rxresu.me](https://docs.rxresu.me):
+The full documentation lives at [docs.rxresu.me](https://docs.rxresu.me):
 
 | Guide                                                                        | Description                      |
 | ---------------------------------------------------------------------------- | -------------------------------- |
 | [Getting Started](https://docs.rxresu.me/getting-started)                    | First-time setup and basic usage |
 | [Self-Hosting](https://docs.rxresu.me/self-hosting/docker)                   | Deploy on your own server        |
-| [Development Setup](https://docs.rxresu.me/contributing/development)         | Local development environment    |
-| [Project Architecture](https://docs.rxresu.me/contributing/architecture)     | Codebase structure and patterns  |
+| [Development setup](https://docs.rxresu.me/contributing/development)         | Local development environment    |
+| [Project architecture](https://docs.rxresu.me/contributing/architecture)     | Codebase structure and patterns  |
 | [Exporting Your Resume](https://docs.rxresu.me/guides/exporting-your-resume) | PDF and JSON export options      |
 
 ## Self-Hosting
 
-Reactive Resume can be self-hosted using Docker. The stack includes:
+Reactive Resume supports Docker and Vercel Hobby.
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Freactive-resume%2Freactive-resume&project-name=reactive-resume&repository-name=reactive-resume&env=AUTH_SECRET%2CENCRYPTION_SECRET&envDescription=Generate+two+independent+secrets+with+openssl+rand+-hex+32.+Keep+these+values+across+deployments.&envLink=https%3A%2F%2Fdocs.rxresu.me%2Fself-hosting%2Fvercel&stores=%5B%7B%22type%22%3A%22integration%22%2C%22protocol%22%3A%22storage%22%2C%22integrationSlug%22%3A%22neon%22%2C%22productSlug%22%3A%22neon%22%7D%2C%7B%22type%22%3A%22integration%22%2C%22protocol%22%3A%22storage%22%2C%22integrationSlug%22%3A%22upstash%22%2C%22productSlug%22%3A%22upstash-kv%22%7D%2C%7B%22type%22%3A%22blob%22%2C%22access%22%3A%22private%22%7D%5D)
+
+Vercel provisions Neon PostgreSQL, private Blob storage, and Upstash Redis through its deployment wizard. Supply two persistent secrets, then deploy. See the [Vercel guide](docs/self-hosting/vercel.mdx) for setup, limits, and optional SMTP/OAuth configuration.
+
+For Docker, the stack includes:
 
 - **PostgreSQL** — Database for storing user data and resumes
 - **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`.
+> **From v6 onwards** — PDF generation uses Forme in the browser and on the server. New deployments no longer need Browserless, Chromium, or any external print service. The `PRINTER_*` and `BROWSERLESS_*` environment variables are no longer read and can be removed from your `.env`.
 
 Pull the latest image from Docker Hub or GitHub Container Registry:
 
@@ -195,20 +209,20 @@ Pull the latest image from Docker Hub or GitHub Container Registry:
 docker pull amruthpillai/reactive-resume:latest
 
 # GitHub Container Registry
-docker pull ghcr.io/amruthpillai/reactive-resume:latest
+docker pull ghcr.io/reactive-resume/reactive-resume:latest
 ```
 
 See the [self-hosting guide](https://docs.rxresu.me/self-hosting/docker) for complete instructions.
 
 ## Support
 
-Reactive Resume is and always will be free and open-source. If it has helped you land a job or saved you time, please consider supporting continued development:
+Reactive Resume is and always will be free and open source. If it has helped you land a job or saved you time, please consider supporting continued development:
 
 <p>
   <a href="https://github.com/sponsors/AmruthPillai">
     <img src="https://img.shields.io/badge/GitHub%20Sponsors-Support-ea4aaa?style=flat-square&logo=github-sponsors" alt="GitHub Sponsors" />
   </a>
-  <a href="https://opencollective.com/reactive-resume">
+  <a href="https://opencollective.com/reactive-resume/donate">
     <img src="https://img.shields.io/badge/Open%20Collective-Contribute-7FADF2?style=flat-square&logo=open-collective" alt="Open Collective" />
   </a>
 </p>
@@ -216,23 +230,28 @@ Reactive Resume is and always will be free and open-source. If it has helped you
 Other ways to support:
 
 - Star this repository
-- Report bugs and suggest features
+- Report reproducible bugs and suggest actionable features
+- Help other users in [GitHub Discussions](https://github.com/reactive-resume/reactive-resume/discussions/categories/q-a)
 - Improve documentation
 - Help with translations
 
+<a href="https://blacksmith.sh/">
+  <img width="368" height="126" alt="powered-by-blacksmith" src="https://github.com/user-attachments/assets/3e95d11b-4579-4082-8d0c-6b574f925625" />
+</a>
+
 ## Star History
 
-<a href="https://www.star-history.com/#amruthpillai/reactive-resume&type=date&legend=top-left">
+<a href="https://www.star-history.com/?repos=reactive-resume%2Freactive-resume&type=date&legend=top-left">
  <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=amruthpillai/reactive-resume&type=date&theme=dark&legend=top-left" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=amruthpillai/reactive-resume&type=date&legend=top-left" />
-   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=amruthpillai/reactive-resume&type=date&legend=top-left" />
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=reactive-resume/reactive-resume&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=reactive-resume/reactive-resume&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=reactive-resume/reactive-resume&type=date&legend=top-left" />
  </picture>
 </a>
 
 ## Contributing
 
-Contributions make open-source thrive. Whether fixing a typo or adding a feature, all contributions are welcome.
+Every contribution helps, whether it is a typo fix or a new feature.
 
 1. Fork the repository
 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
@@ -240,7 +259,11 @@ Contributions make open-source thrive. Whether fixing a typo or adding a feature
 4. Push to the branch (`git push origin feature/amazing-feature`)
 5. Open a Pull Request
 
-See the [development setup guide](https://docs.rxresu.me/contributing/development) for detailed instructions on how to set up the project locally.
+See the [development setup guide](https://docs.rxresu.me/contributing/development) for how to run the project locally.
+
+Maintainers review the [`status: needs triage` queue](https://github.com/reactive-resume/reactive-resume/issues?q=is%3Aissue+is%3Aopen+label%3A%22status%3A+needs+triage%22)
+weekly. Triaged bugs become `status: confirmed`; feature proposals become `status: accepted`; reports that need details become
+`status: needs info`.
 
 ## License
 

apps/server/package.json

@@ -0,0 +1,102 @@
+{
+	"name": "server",
+	"version": "0.0.0",
+	"type": "module",
+	"private": true,
+	"scripts": {
+		"dev": "tsx watch src/index.ts",
+		"build": "tsdown",
+		"start": "node dist/index.mjs",
+		"docs:gen": "tsx src/openapi/generate-spec.ts",
+		"typecheck": "tsgo --noEmit",
+		"test": "vitest run --passWithNoTests",
+		"test:coverage": "vitest run --coverage --passWithNoTests",
+		"test:ci": "vitest run --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"
+	},
+	"dependencies": {
+		"@ai-sdk/anthropic": "^4.0.68",
+		"@ai-sdk/cerebras": "^3.0.59",
+		"@ai-sdk/cohere": "^4.0.52",
+		"@ai-sdk/deepseek": "^3.0.56",
+		"@ai-sdk/fireworks": "^3.0.62",
+		"@ai-sdk/google": "^4.0.85",
+		"@ai-sdk/groq": "^4.0.52",
+		"@ai-sdk/mistral": "^4.0.54",
+		"@ai-sdk/openai": "^4.0.81",
+		"@ai-sdk/openai-compatible": "^3.0.59",
+		"@ai-sdk/perplexity": "^5.0.3",
+		"@ai-sdk/togetherai": "^3.0.60",
+		"@ai-sdk/xai": "^5.0.12",
+		"@aws-sdk/client-s3": "^3.1143.0",
+		"@better-auth/api-key": "^1.7.6",
+		"@better-auth/drizzle-adapter": "^1.7.6",
+		"@better-auth/infra": "^0.4.13",
+		"@better-auth/oauth-provider": "^1.7.6",
+		"@better-auth/passkey": "^1.7.6",
+		"@bramus/specificity": "^2.4.2",
+		"@formepdf/core": "0.25.0",
+		"@formepdf/react": "0.25.0",
+		"@hono/node-server": "^2.1.3",
+		"@modelcontextprotocol/sdk": "^1.31.0",
+		"@orpc/client": "^1.15.4",
+		"@orpc/experimental-ratelimit": "^1.15.4",
+		"@orpc/json-schema": "^1.15.4",
+		"@orpc/openapi": "^1.15.4",
+		"@orpc/server": "^1.15.4",
+		"@orpc/zod": "^1.15.4",
+		"@reactive-resume/api": "workspace:*",
+		"@reactive-resume/auth": "workspace:*",
+		"@reactive-resume/db": "workspace:*",
+		"@reactive-resume/env": "workspace:*",
+		"@reactive-resume/mcp": "workspace:*",
+		"@reactive-resume/schema": "workspace:*",
+		"@reactive-resume/utils": "workspace:*",
+		"@sindresorhus/slugify": "^3.0.1",
+		"@t3-oss/env-core": "^0.13.11",
+		"@uiw/color-convert": "^2.10.3",
+		"@vercel/blob": "^2.8.0",
+		"@vercel/functions": "^3.9.9",
+		"ai": "^7.0.122",
+		"bcryptjs": "^3.0.3",
+		"better-auth": "1.7.6",
+		"cjk-regex": "^3.5.0",
+		"css-tree": "^3.2.1",
+		"drizzle-orm": "1.0.0-rc.4",
+		"drizzle-zod": "1.0.0-beta.14-a36c63d",
+		"es-toolkit": "^1.52.0",
+		"fast-json-patch": "^3.1.1",
+		"fast-png": "^8.0.0",
+		"fflate": "^0.8.3",
+		"hono": "^4.13.11",
+		"ioredis": "^6.0.0",
+		"jose": "^6.2.12",
+		"jsonrepair": "^3.15.0",
+		"node-html-parser": "^9.0.4",
+		"nodemailer": "^10.0.12",
+		"ollama-ai-provider-v2": "^4.0.1",
+		"pg": "^8.23.0",
+		"react": "^19.3.0",
+		"react-email": "^6.11.0",
+		"react-reconciler": "0.34.0",
+		"resumable-stream": "^2.2.13",
+		"sanitize-html": "^2.17.7",
+		"sharp": "^0.35.5",
+		"tokenx": "^2.1.0",
+		"ts-pattern": "^5.9.0",
+		"unique-names-generator": "^4.7.1",
+		"uuid": "^14.0.2",
+		"zod": "^4.6.5"
+	},
+	"devDependencies": {
+		"@reactive-resume/config": "workspace:*",
+		"@types/node": "^26.6.3",
+		"@types/pg": "^8.23.1",
+		"@types/react": "^19.3.0",
+		"@typescript/native-preview": "7.0.0-dev.20260707.2",
+		"tsdown": "^0.23.0",
+		"tsx": "^4.23.15",
+		"typescript": "^7.0.2",
+		"vitest": "^5.0.2"
+	}
+}

apps/server/src/app-version.ts

@@ -0,0 +1,4 @@
+// @boundaries-ignore root release metadata
+import { version } from "../../../package.json";
+
+export const appVersion = typeof __APP_VERSION__ === "undefined" ? version : __APP_VERSION__;

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

@@ -0,0 +1,216 @@
+import { gunzipSync } from "node:zlib";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+	handleAuth: vi.fn(),
+	handleOAuth: vi.fn(),
+	handleRpc: vi.fn(),
+	handleOpenApi: vi.fn(),
+	handleHealth: vi.fn(),
+	handleUpload: vi.fn(),
+	handleMcp: vi.fn(),
+	handleResumePdfDownload: vi.fn(),
+	handlePublicResumePdf: vi.fn(),
+	handleMcpServerCard: vi.fn(),
+	handleOAuthAuthorizationServer: vi.fn(),
+	handleOAuthProtectedResource: vi.fn(),
+	handleOpenIdConfiguration: vi.fn(),
+	handleWellKnownFallback: vi.fn(),
+	handleRobots: vi.fn(),
+	handleSitemap: vi.fn(),
+	handleLlms: vi.fn(),
+	serveWebDistStatic: vi.fn(),
+	handleWebApp: vi.fn(),
+}));
+
+vi.mock("./auth", () => ({
+	handleAuth: mocks.handleAuth,
+	handleOAuth: mocks.handleOAuth,
+}));
+
+vi.mock("./health", () => ({
+	handleHealth: mocks.handleHealth,
+}));
+
+vi.mock("../rpc/handler", () => ({
+	handleRpc: mocks.handleRpc,
+}));
+
+vi.mock("../openapi/handler", () => ({
+	handleOpenApi: mocks.handleOpenApi,
+}));
+
+vi.mock("../openapi/metadata", () => ({
+	handleMcpServerCard: mocks.handleMcpServerCard,
+	handleOAuthAuthorizationServer: mocks.handleOAuthAuthorizationServer,
+	handleOAuthProtectedResource: mocks.handleOAuthProtectedResource,
+	handleOpenIdConfiguration: mocks.handleOpenIdConfiguration,
+	handleWellKnownFallback: mocks.handleWellKnownFallback,
+}));
+
+vi.mock("../static/uploads", () => ({
+	handleUpload: mocks.handleUpload,
+}));
+
+vi.mock("../static/seo", () => ({
+	handleRobots: mocks.handleRobots,
+	handleSitemap: mocks.handleSitemap,
+	handleLlms: mocks.handleLlms,
+}));
+
+vi.mock("../static/web", () => ({
+	serveWebDistStatic: mocks.serveWebDistStatic,
+	handleWebApp: mocks.handleWebApp,
+}));
+
+vi.mock("../mcp/handler", () => ({
+	handleMcp: mocks.handleMcp,
+}));
+
+vi.mock("./resume-pdf", () => ({
+	handleResumePdfDownload: mocks.handleResumePdfDownload,
+}));
+
+vi.mock("./public-resume-pdf", () => ({
+	handlePublicResumePdf: mocks.handlePublicResumePdf,
+}));
+
+const transportEnv = (remoteAddress: string) =>
+	({
+		incoming: { socket: { remoteAddress } },
+	}) as never;
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	mocks.handleAuth.mockResolvedValue(new Response("auth"));
+	mocks.handleOAuth.mockResolvedValue(new Response("oauth"));
+	mocks.handleRpc.mockResolvedValue(new Response("rpc"));
+	mocks.handleOpenApi.mockResolvedValue(new Response("openapi"));
+	mocks.handleHealth.mockReturnValue(new Response("health"));
+	mocks.handleUpload.mockResolvedValue(new Response("upload"));
+	mocks.handleMcp.mockResolvedValue(new Response("mcp"));
+	mocks.handleResumePdfDownload.mockResolvedValue(new Response("pdf"));
+	mocks.handlePublicResumePdf.mockResolvedValue(new Response("public-pdf"));
+	mocks.handleMcpServerCard.mockReturnValue(new Response("server-card"));
+	mocks.handleOAuthAuthorizationServer.mockReturnValue(new Response("oauth-authorization-server"));
+	mocks.handleOAuthProtectedResource.mockReturnValue(new Response("oauth-protected-resource"));
+	mocks.handleOpenIdConfiguration.mockReturnValue(new Response("openid-configuration"));
+	mocks.handleWellKnownFallback.mockReturnValue(new Response("well-known"));
+	mocks.handleRobots.mockReturnValue(new Response("robots"));
+	mocks.handleSitemap.mockReturnValue(new Response("sitemap"));
+	mocks.handleLlms.mockReturnValue(new Response("llms"));
+	mocks.serveWebDistStatic.mockResolvedValue(undefined);
+	mocks.handleWebApp.mockResolvedValue(new Response("web"));
+});
+
+describe("createApp", () => {
+	it("routes /api/auth/oauth to the OAuth bridge before the Better Auth wildcard", async () => {
+		const { createApp } = await import("./app");
+		const app = createApp();
+		const request = new Request("http://localhost:3001/api/auth/oauth?client_id=test-client");
+
+		const response = await app.fetch(request);
+
+		await expect(response.text()).resolves.toBe("oauth");
+		expect(mocks.handleOAuth).toHaveBeenCalledWith(request);
+		expect(mocks.handleAuth).not.toHaveBeenCalled();
+		// The first test pays for the cold import of the whole app, which takes seconds under a parallel run.
+	}, 15_000);
+
+	it("uses the transport address for public PDF fallback despite rotated forwarding headers", async () => {
+		const { createApp } = await import("./app");
+		const app = createApp();
+		const first = new Request("http://localhost:3001/api/resumes/jane/resume/pdf", {
+			headers: { "x-forwarded-for": "198.51.100.1" },
+		});
+		const rotated = new Request("http://localhost:3001/api/resumes/jane/resume/pdf", {
+			headers: { "x-forwarded-for": "198.51.100.2" },
+		});
+		const env = transportEnv("203.0.113.9");
+
+		const response = await app.fetch(first, env);
+		await app.fetch(rotated, env);
+
+		await expect(response.text()).resolves.toBe("public-pdf");
+		expect(mocks.handlePublicResumePdf).toHaveBeenNthCalledWith(1, first, "jane", "resume", "203.0.113.9");
+		expect(mocks.handlePublicResumePdf).toHaveBeenNthCalledWith(2, rotated, "jane", "resume", "203.0.113.9");
+		expect(mocks.handleResumePdfDownload).not.toHaveBeenCalled();
+		expect(mocks.serveWebDistStatic).not.toHaveBeenCalled();
+		expect(mocks.handleWebApp).not.toHaveBeenCalled();
+	});
+
+	it("passes the transport address to RPC and OpenAPI and fails closed when it is unavailable", async () => {
+		const { createApp } = await import("./app");
+		const app = createApp();
+		const trustedRpcRequest = new Request("http://localhost:3001/api/rpc", {
+			headers: { "cf-connecting-ip": "198.51.100.1" },
+		});
+		const unknownRpcRequest = new Request("http://localhost:3001/api/rpc", {
+			headers: { "cf-connecting-ip": "198.51.100.2" },
+		});
+		const trustedOpenApiRequest = new Request("http://localhost:3001/api/openapi/resumes/jane/resume");
+		const unknownOpenApiRequest = new Request("http://localhost:3001/api/openapi/resumes/jane/resume");
+
+		await app.fetch(trustedRpcRequest, transportEnv("203.0.113.9"));
+		await app.fetch(unknownRpcRequest);
+		await app.fetch(trustedOpenApiRequest, transportEnv("203.0.113.9"));
+		await app.fetch(unknownOpenApiRequest);
+
+		expect(mocks.handleRpc).toHaveBeenNthCalledWith(1, trustedRpcRequest, "203.0.113.9");
+		expect(mocks.handleRpc).toHaveBeenNthCalledWith(2, unknownRpcRequest, "unknown");
+		expect(mocks.handleOpenApi).toHaveBeenNthCalledWith(1, trustedOpenApiRequest, "203.0.113.9");
+		expect(mocks.handleOpenApi).toHaveBeenNthCalledWith(2, unknownOpenApiRequest, "unknown");
+	});
+
+	it("routes GET / to the web app handler so SEO markup is injected", async () => {
+		const { createApp } = await import("./app");
+		const app = createApp();
+		const request = new Request("http://localhost:3001/");
+
+		const response = await app.fetch(request);
+
+		expect(response.status).toBe(200);
+		expect(mocks.handleWebApp).toHaveBeenCalledWith(request);
+		expect(mocks.serveWebDistStatic).not.toHaveBeenCalled();
+	});
+
+	it("compresses the web app's HTML but never API streams or the Vercel app", async () => {
+		const { createApp } = await import("./app");
+		const html = `<!doctype html>${"<p>Reactive Resume</p>".repeat(200)}`;
+		const htmlResponse = () =>
+			new Response(html, {
+				headers: { "Content-Type": "text/html; charset=UTF-8", "Cache-Control": "private, no-store", Vary: "Cookie" },
+			});
+		const stream = () => new Response("data: x\n\n".repeat(500), { headers: { "Content-Type": "application/json" } });
+		mocks.handleWebApp.mockImplementation(async () => htmlResponse());
+		mocks.handleRpc.mockImplementation(async () => stream());
+		mocks.handleMcp.mockImplementation(async () => stream());
+		const headers = { "Accept-Encoding": "br, gzip" };
+
+		const page = await createApp().request("http://localhost:3000/", { headers });
+		const rpc = await createApp().request("http://localhost:3000/api/rpc/agent/chat", { headers });
+		const mcp = await createApp().request("http://localhost:3000/mcp", { headers });
+		const vercelPage = await createApp({ serveStatic: false }).request("http://localhost:3000/", { headers });
+
+		expect(page.headers.get("content-encoding")).toBe("gzip");
+		expect(page.headers.get("vary")).toBe("Cookie, Accept-Encoding");
+		expect(page.headers.get("cache-control")).toBe("private, no-store");
+		expect(gunzipSync(Buffer.from(await page.arrayBuffer())).toString()).toBe(html);
+		for (const response of [rpc, mcp, vercelPage]) expect(response.headers.get("content-encoding")).toBeNull();
+		expect(vercelPage.headers.get("vary")).toBe("Cookie");
+	});
+});
+
+it.each(["/auth/consent", "/auth/consent/", "/auth/login"])("prevents framing or caching %s", async (path) => {
+	const { createApp } = await import("./app");
+	mocks.serveWebDistStatic.mockImplementationOnce(async (_context: unknown, next: () => Promise<void>) => {
+		await next();
+	});
+	const response = await createApp().request(`http://localhost:3000${path}?sig=signed`);
+	expect(response.status).toBe(200);
+	expect(await response.text()).toBe("web");
+	expect(response.headers.get("content-security-policy")).toBe("frame-ancestors 'none'");
+	expect(response.headers.get("x-frame-options")).toBe("DENY");
+	expect(response.headers.get("referrer-policy")).toBe("no-referrer");
+	expect(response.headers.get("cache-control")).toBe("no-store");
+});

apps/server/src/http/app.ts

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

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

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

apps/server/src/http/auth.ts

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

apps/server/src/http/headers.ts

@@ -0,0 +1,12 @@
+export function mergeResponseHeaders(response: Response, headers: Headers): Response {
+	if ([...headers].length === 0) return response;
+
+	const nextHeaders = new Headers(response.headers);
+	for (const [key, value] of headers) nextHeaders.append(key, value);
+
+	return new Response(response.body, {
+		status: response.status,
+		statusText: response.statusText,
+		headers: nextHeaders,
+	});
+}

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

@@ -0,0 +1,71 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { execute, healthcheck, ping } = vi.hoisted(() => ({ execute: vi.fn(), healthcheck: vi.fn(), ping: vi.fn() }));
+
+vi.mock("@reactive-resume/db/client", () => ({ db: { execute } }));
+vi.mock("@reactive-resume/api/features/storage", () => ({ getStorageService: () => ({ healthcheck }) }));
+vi.mock("@reactive-resume/db/redis", () => ({ getRedis: () => ({ ping }) }));
+
+import { handleHealth } from "./health";
+
+describe("health failure reporting", () => {
+	beforeEach(() => {
+		execute.mockResolvedValue([]);
+		healthcheck.mockResolvedValue({ status: "healthy" });
+		ping.mockResolvedValue("PONG");
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it.each(["database", "storage", "redis"])("keeps thrown %s error details in server logs only", async (dependency) => {
+		const detail = "Connection failed for private-user at internal.example:5432";
+		const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+		({ database: execute, storage: healthcheck, redis: ping })[dependency]?.mockRejectedValueOnce(new Error(detail));
+
+		const response = await handleHealth();
+		const body = await response.json();
+
+		expect(response.status).toBe(503);
+		expect(JSON.stringify(body)).not.toContain(detail);
+		expect(body[dependency]).toMatchObject({
+			status: "unhealthy",
+			error: expect.stringContaining("health check failed"),
+		});
+		expect(warn).toHaveBeenCalledWith(
+			"[Healthcheck]",
+			expect.objectContaining({
+				[dependency]: expect.objectContaining({ error: detail }),
+			}),
+		);
+	});
+
+	it("redacts returned storage failures while preserving diagnostics in server logs", async () => {
+		const detail = "Access denied to bucket private-bucket on internal.example";
+		const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+		healthcheck.mockResolvedValueOnce({
+			status: "unhealthy",
+			type: "s3",
+			message: detail,
+			error: detail,
+			internalDetail: detail,
+		});
+
+		const response = await handleHealth();
+		const body = await response.json();
+
+		expect(response.status).toBe(503);
+		expect(body.storage).toEqual({
+			status: "unhealthy",
+			type: "s3",
+			latencyMs: expect.any(Number),
+			error: "Storage health check failed.",
+		});
+		expect(JSON.stringify(body)).not.toContain(detail);
+		expect(warn).toHaveBeenCalledWith(
+			"[Healthcheck]",
+			expect.objectContaining({ storage: expect.objectContaining({ error: detail, message: detail }) }),
+		);
+	});
+});

apps/server/src/http/health.ts

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,58 @@
+import { createResumePdfDownload, verifyResumePdfDownloadToken } from "@reactive-resume/api/features/resume/export";
+
+function unauthorizedResponse() {
+	return new Response("Unauthorized", {
+		status: 401,
+		headers: {
+			"Cache-Control": "private, no-store",
+		},
+	});
+}
+
+function expiredResponse() {
+	return new Response("Download link expired", {
+		status: 410,
+		headers: {
+			"Cache-Control": "private, no-store",
+		},
+	});
+}
+
+function errorStatus(error: unknown) {
+	const code = typeof error === "object" && error && "code" in error ? (error as { code?: unknown }).code : undefined;
+	return code === "NOT_FOUND" ? 404 : 500;
+}
+
+export async function handleResumePdfDownload(request: Request, id: string) {
+	const searchParams = new URL(request.url).searchParams;
+	const token = searchParams.get("token");
+	if (!token) return unauthorizedResponse();
+
+	const verification = verifyResumePdfDownloadToken({ resumeId: id, token });
+	if (!verification.ok) return verification.reason === "expired" ? expiredResponse() : unauthorizedResponse();
+	// Links made before letters left resumes may ask for the resume's cover letter, which is now a letter of its own.
+	const target = searchParams.get("target");
+	if (target && target !== "resume")
+		return new Response("Not found", { status: 404, headers: { "Cache-Control": "private, no-store" } });
+
+	try {
+		const download = await createResumePdfDownload({ id, userId: verification.userId });
+
+		return new Response(download.body, {
+			headers: {
+				"Content-Type": download.body.type || "application/pdf",
+				"Content-Disposition": download.headers["content-disposition"],
+				"Cache-Control": "private, no-store",
+				"X-Content-Type-Options": "nosniff",
+			},
+		});
+	} catch (error) {
+		console.error("[PDF Download]", error);
+		return new Response("Failed to generate resume PDF", {
+			status: errorStatus(error),
+			headers: {
+				"Cache-Control": "private, no-store",
+			},
+		});
+	}
+}

apps/server/src/index.test.ts

@@ -0,0 +1,88 @@
+import { once } from "node:events";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { serve } from "@hono/node-server";
+
+const events = vi.hoisted(() => [] as string[]);
+const appFetch = vi.hoisted(() => vi.fn());
+vi.mock("./startup/checks", () => ({
+	runStartupChecks: async () => {
+		await Promise.resolve();
+		events.push("migrations complete");
+	},
+}));
+vi.mock("./http/app", () => {
+	events.push("auth imported");
+	return {
+		createApp: () => {
+			events.push("app created");
+			return { fetch: appFetch };
+		},
+	};
+});
+vi.mock("@reactive-resume/auth/config", () => ({
+	initializeAuth: async () => {
+		await Promise.resolve();
+		events.push("auth ready");
+	},
+}));
+vi.mock("@hono/node-server", () => ({
+	serve: vi.fn(() => {
+		events.push("server listening");
+	}),
+}));
+vi.mock("@reactive-resume/env/server", () => ({ env: { SERVER_PORT: 0 } }));
+afterEach(() => vi.restoreAllMocks());
+
+describe("server startup", () => {
+	it("finishes migrations before importing auth and seeding OAuth resources", async () => {
+		vi.spyOn(process, "on").mockReturnValue(process);
+		vi.spyOn(process, "once").mockReturnValue(process);
+		const entry = await import("./index");
+		expect(events).toEqual([]);
+		await entry.main();
+		expect(events).toEqual(["migrations complete", "auth imported", "auth ready", "app created", "server listening"]);
+	});
+
+	it.each(["SIGTERM", "SIGINT"])("drains active requests before exiting on %s", async (signal) => {
+		vi.spyOn(process, "on").mockReturnValue(process);
+		const signals = vi.spyOn(process, "once").mockReturnValue(process);
+		const exit = vi.spyOn(process, "exit").mockImplementation(() => undefined as never);
+		const started = Promise.withResolvers<void>();
+		const finished = Promise.withResolvers<Response>();
+		appFetch.mockImplementation(() => {
+			started.resolve();
+			return finished.promise;
+		});
+		const { serve: realServe } = await vi.importActual<typeof import("@hono/node-server")>("@hono/node-server");
+		let server: ReturnType<typeof serve> | undefined;
+		vi.mocked(serve).mockImplementationOnce((options, callback) => {
+			server = realServe(options, callback);
+			return server;
+		});
+		await (await import("./index")).main();
+		if (!server) throw new Error("Server did not start");
+		const runningServer = server;
+		try {
+			if (!server.listening) await once(server, "listening");
+			const address = server.address();
+			if (!address || typeof address === "string") throw new Error("Missing HTTP address");
+			const url = `http://127.0.0.1:${address.port}`;
+			const response = fetch(url);
+			await started.promise;
+			const shutdown = signals.mock.calls.find(([name]) => name === signal)?.[1];
+			expect(shutdown).toBeTypeOf("function");
+			const closed = once(server, "close");
+			shutdown?.();
+			shutdown?.();
+			expect(exit).not.toHaveBeenCalled();
+			await expect(fetch(url)).rejects.toThrow();
+			finished.resolve(new Response("drained"));
+			expect(await (await response).text()).toBe("drained");
+			await closed;
+			expect(exit).toHaveBeenCalledExactlyOnceWith(0);
+		} finally {
+			finished.resolve(new Response("drained"));
+			await new Promise<void>((resolve) => runningServer.close(() => resolve()));
+		}
+	});
+});

apps/server/src/index.ts

@@ -0,0 +1,59 @@
+import { pathToFileURL } from "node:url";
+import { serve } from "@hono/node-server";
+import { env } from "@reactive-resume/env/server";
+import { runStartupChecks } from "./startup/checks";
+
+export async function main() {
+	await runStartupChecks();
+
+	// Load and initialize auth only after migrations have created the provider tables.
+	const { createApp } = await import("./http/app");
+	const { initializeAuth } = await import("@reactive-resume/auth/config");
+	await initializeAuth();
+
+	// Safety net: Node 24 crashes the whole process on an unhandled rejection. One request's
+	// stray promise must not take the server down for everyone, so log and keep serving.
+	// Registered after startup checks so a broken startup still fails loudly. (Left uncaught
+	// exceptions on Node's default crash-and-restart, since process state is unsafe after one.)
+	process.on("unhandledRejection", (reason) => {
+		console.error("[unhandledRejection]", reason);
+	});
+
+	const port =
+		process.env.NODE_ENV === "production" ? Number.parseInt(process.env.PORT ?? "3000", 10) : env.SERVER_PORT;
+
+	const app = createApp();
+
+	const server = serve(
+		{
+			fetch: app.fetch,
+			port,
+		},
+		(info) => {
+			console.info(`🚀 Up and running on http://localhost:${info.port}`);
+		},
+	);
+
+	let shuttingDown = false;
+	const shutdown = () => {
+		if (shuttingDown) return;
+		shuttingDown = true;
+		// Stop accepting connections, then wait for active requests before exiting.
+		server.close((error) => {
+			if (error) {
+				console.error("Failed to drain HTTP requests", error);
+				process.exit(1);
+			}
+			process.exit(0);
+		});
+	};
+	process.once("SIGTERM", shutdown);
+	process.once("SIGINT", shutdown);
+}
+
+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.test.ts

@@ -0,0 +1,24 @@
+import { beforeEach, expect, it, vi } from "vitest";
+
+const resolve = vi.hoisted(() => vi.fn());
+vi.mock("@reactive-resume/api/context", () => ({ resolveUserFromRequestHeaders: resolve }));
+
+import { AuthError, authenticateRequest } from "./auth";
+
+beforeEach(() => resolve.mockReset());
+it("resolves MCP credentials through the shared API auth policy without accepting cookies", async () => {
+	resolve.mockResolvedValue({ id: "user-1" });
+	await authenticateRequest(
+		new Request("https://resume.example/mcp", {
+			headers: { authorization: "Bearer valid-token", "x-api-key": "expired-key", cookie: "session=browser" },
+		}),
+	);
+	const headers = resolve.mock.calls[0]?.[0] as Headers;
+	expect(headers.get("authorization")).toBe("Bearer valid-token");
+	expect(headers.get("x-api-key")).toBe("expired-key");
+	expect(headers.has("cookie")).toBe(false);
+});
+it("rejects requests when shared credential resolution finds no user", async () => {
+	resolve.mockResolvedValue(null);
+	await expect(authenticateRequest(new Request("https://resume.example/mcp"))).rejects.toBeInstanceOf(AuthError);
+});

apps/server/src/mcp/auth.ts

@@ -0,0 +1,15 @@
+import { resolveUserFromRequestHeaders } from "@reactive-resume/api/context";
+
+export class AuthError extends Error {
+	constructor() {
+		super("Unauthorized");
+	}
+}
+
+export async function authenticateRequest(request: Request): Promise<void> {
+	// MCP accepts API keys and bearer tokens; share their priority and validation with its oRPC tools.
+	const headers = new Headers(request.headers);
+	headers.delete("cookie");
+	if (await resolveUserFromRequestHeaders(headers)) return;
+	throw new AuthError();
+}

apps/server/src/mcp/handler.ts

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