Release v5.2.9 (#3382 )

* feat(ats): add ATS checker and replace resume analysis Adds a public, browser-only ATS checker at /ats-checker and an ATS Check section in the builder's right sidebar. PDFs are parsed locally: text extraction, reading order, contact and date recovery, section detection, and file-level readability are scored deterministically, with evidence cited per finding and skipped checks reported rather than counted as passes. Removes the AI-scored resume analysis it supersedes: the resume_analysis table (dropped via migration), the get_resume_analysis MCP tool, and POST /ai/analyze-resume. The replacement, POST /ai/ats-review, reviews extracted resume text and returns qualitative feedback with no score. Also bumps the version to 5.2.9 and adds the changelog entry. * chore(deps): bump workspace dependencies * fix(ats-checker): keep negation inside each 'what this does not do' bullet The three bullets were bare fragments whose negation came from the section heading, which translators never see. A dozen locales rendered them as affirmative assertions or imperatives, so the page claimed the checker enforces a one-page rule and predicts rejection -- the opposite of the source, and directly contradicted by the sentence beside it. Each bullet now carries its own negation, so the polarity cannot be lost in translation. Re-extracted and refilled across all 53 target locales.
fix(pdf): resolve bold text weight from the family's bold face (#3335 )
2026-09-29 16:24:22 +10:00 · 2026-08-27 03:37:01 +02:00 · 2026-08-27 03:16:46 +02:00 · 2026-08-27 03:15:34 +02:00 · 2026-08-27 03:15:31 +02:00 · 2026-08-27 03:15:28 +02:00
1120 changed files with 347588 additions and 46061 deletions
@@ -1,68 +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
        - Scizor
-    validations:
-      required: false

  - 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.
@@ -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.
@@ -1 +1,8 @@
 blank_issues_enabled: false
+contact_links:
+  - name: Questions and support
+    url: https://github.com/amruthpillai/reactive-resume/discussions/categories/q-a
+    about: Get help with setup, configuration, and using Reactive Resume.
+  - name: Security vulnerability
+    url: https://github.com/amruthpillai/reactive-resume/security/advisories/new
+    about: Report security vulnerabilities privately.
@@ -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 -->
@@ -19,6 +19,13 @@ jobs:
      - name: Checkout Repository
        uses: actions/checkout@v6

+      - 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

@@ -0,0 +1,91 @@
+name: E2E Tests
+
+on:
+  pull_request:
+  push:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+  APP_URL: http://localhost:3000
+  PORT: "3000"
+  DATABASE_URL: postgresql://postgres:postgres@localhost:5432/postgres
+  FLAG_DISABLE_SIGNUPS: "false"
+  FLAG_DISABLE_EMAIL_AUTH: "false"
+  FLAG_DISABLE_API_RATE_LIMIT: "true"
+  LOCAL_STORAGE_PATH: /tmp/reactive-resume-e2e-storage
+
+jobs:
+  e2e:
+    runs-on: 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
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          cache: "pnpm"
+
+      - name: Install Dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run Server and Tooling Tests
+        run: pnpm exec turbo run test:ci --filter=server --filter=@reactive-resume/tooling
+
+      - name: Install Playwright Browser
+        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: Build
+        run: pnpm build
+
+      - name: Run Baseline E2E Tests
+        run: pnpm exec playwright test --grep-invert "@semantic-css"
+
+      - 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
@@ -0,0 +1,34 @@
+name: Label New Issues
+
+on:
+  issues:
+    types: [opened]
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  label:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        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,
+              });
+            }
@@ -0,0 +1,30 @@
+name: Close Issues Awaiting Information
+
+on:
+  schedule:
+    - cron: "23 4 * * *"
+  workflow_dispatch:
+
+permissions:
+  issues: write
+
+jobs:
+  stale:
+    runs-on: 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
@@ -36,6 +36,8 @@ logs
 # Testing
 coverage
 reports
+playwright-report
+test-results

 # Cache
 tmp
@@ -47,12 +49,16 @@ temp
 .agents
 .claude
 .cursor
-.codegraph
+.opencode
 .superpowers
+.worktrees
+.migration
+graphify-out

 # Local Storage Data
 /data
 /apps/web/data

 # Git Hooks
-.vite-hooks/
+.vite-hooks
+
@@ -0,0 +1,31 @@
+config:
+  default: true
+  MD007: false
+  MD009: false
+  MD010: false
+  MD012: false
+  MD013: false
+  MD001: false
+  MD022: false
+  MD024: false
+  MD025: false
+  MD028: false
+  MD031: false
+  MD032: false
+  MD033: false
+  MD034: false
+  MD036: false
+  MD040: false
+  MD041: false
+  MD046: false
+  MD060: false
+
+frontMatter: "^---[\\s\\S]*?---"
+gitignore: true
+globs:
+  - "**/*.{md,mdx}"
+ignores:
+  - ".design-sync/**"
+  - "node_modules/**"
+  - ".turbo/**"
+  - "dist/**"
@@ -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"
+	}
 }
@@ -1,5 +1,59 @@
+<!-- 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 -->
+
+<!-- graphify-begin -->
+## graphify
+
+This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.
+
+When the user types `/graphify`, use the installed graphify skill or instructions before doing anything else.
+
+Rules:
+- For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
+- Dirty graphify-out/ files are expected after hooks or incremental updates; dirty graph files are not a reason to skip graphify. Only skip graphify if the task is about stale or incorrect graph output, or the user explicitly says not to use it.
+- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
+- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
+- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).
+<!-- graphify-end -->
+
 # AGENTS.md

+## Agent skills
+
+### Issue tracker
+
+Issues and specs are tracked in GitHub Issues for `amruthpillai/reactive-resume`. See `docs/agents/issue-tracker.md`.
+
+### Domain docs
+
+This repository uses a multi-context domain-doc layout. See `docs/agents/domain.md`.
+
 ## Cursor Cloud specific instructions

 ### Overview
@@ -12,7 +66,7 @@ Internal packages are source-consumed through `package.json` export maps that po

 - **Node.js 24** (matches Dockerfile `ARG NODE_VERSION=24`). Use `nvm install 24 && nvm use 24` if needed.
 - **Docker** is required to run PostgreSQL. Start it with `sudo dockerd &` if the daemon isn't running.
- **pnpm 11.1.2** is managed via corepack (`corepack enable`).
+- **pnpm 11.21.0**. Install pnpm directly using the [official installation guide](https://pnpm.io/installation).

 ### Codebase map

@@ -107,7 +161,7 @@ The production server runs migrations during startup before serving traffic. Man

 ### Environment

-Copy `.env.example` to `.env`. The three required variables are:
+Copy `.env.example` to `.env.local`. The three required variables are:

 - `APP_URL` (default `http://localhost:3000`)
 - `DATABASE_URL` (default `postgresql://postgres:postgres@localhost:5432/postgres`)
@@ -115,6 +169,8 @@ Copy `.env.example` to `.env`. The three required variables are:

 S3/SeaweedFS is optional. If `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, and `S3_BUCKET` are all set, the app uses S3-compatible storage. The checked-in `.env.example` sets SeaweedFS defaults, so either start the `seaweedfs` compose service too or comment out those S3 vars to use local filesystem storage under `<workspace>/data`. `LOCAL_STORAGE_PATH` must be absolute when set.

+`REDIS_URL` and `ENCRYPTION_SECRET` are optional for core resume flows, but both are required for saved AI providers and the authenticated `/agent` workspace. Start the `redis` compose service and set both vars in `.env.local` when working on those features. For host-run development, use `REDIS_URL=redis://localhost:6379`; the container-run app uses `REDIS_URL=redis://redis:6379`.
+
 When running dev servers or migration commands, prefix the command with `dotenvx run -f .env.local --`. For example: `dotenvx run -f .env.local -- pnpm dev`. Tests, typechecks, linters, boundary checks, and `pnpm build` do not need this prefix by default. If one of those commands fails because a specific environment variable is required, rerun it with the `dotenvx run -f .env.local --` prefix.

 ### Common commands
@@ -124,6 +180,7 @@ When running dev servers or migration commands, prefix the command with `dotenvx
 | Install deps | `pnpm install` |
 | Start Postgres only | `sudo docker compose -f compose.dev.yml up -d postgres` |
 | Start Postgres + SeaweedFS | `sudo docker compose -f compose.dev.yml up -d postgres seaweedfs seaweedfs_create_bucket` |
+| Start full dev infrastructure | `sudo docker compose -f compose.dev.yml up -d postgres redis seaweedfs seaweedfs_create_bucket` |
 | Generate migrations | `dotenvx run -f .env.local -- pnpm db:generate` |
 | Run migrations | `dotenvx run -f .env.local -- pnpm db:migrate` |
 | Dev server | `dotenvx run -f .env.local -- pnpm dev` (starts on port 3000) |
@@ -1,17 +1,17 @@
 # syntax=docker/dockerfile:1.7

+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 . .
@@ -1,19 +1,19 @@
 # syntax=docker/dockerfile:1.7

+ARG PNPM_VERSION=11.21.0
 ARG NODE_VERSION=24

-FROM node:${NODE_VERSION}-slim AS dev
+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 COREPACK_ENABLE_DOWNLOAD_PROMPT=0 \
-	PNPM_HOME="/pnpm" \
-	PATH="/pnpm:$PATH" \
-	NODE_ENV=development \
+ENV NODE_ENV=development \
 	TURBO_TELEMETRY_DISABLED=1

-RUN corepack enable
-
 COPY package.json pnpm-lock.yaml pnpm-workspace.yaml turbo.json ./
 COPY patches ./patches
 COPY apps/server/package.json ./apps/server/package.json
@@ -60,7 +60,7 @@ If your company would like to sponsor Reactive Resume, email [hello@amruthpillai
 - Professionally designed templates
 - A4 and Letter size support
 - Customizable colors, fonts, and spacing
- Custom CSS for advanced styling
+- Structured Style Rules for section and text styling

 **Privacy & Control**

@@ -234,17 +234,18 @@ 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/amruthpillai/reactive-resume/discussions/categories/q-a)
 - Improve documentation
 - Help with translations

 ## 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=amruthpillai%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=amruthpillai/reactive-resume&type=date&theme=dark&legend=top-left&sealed_token=QmaOn4Ech499R6kpQe8ONn911UjGUaJfQBT0MXlQLU9hTo-Ie7lTxIILWbBvmtzDGHk7ziWKN_N5iM5mgP8widn_FGHd9-PHNokPtSji8XLgbFpqatgyqIDPnOys-IhO40W3J0HeH07FL-Q8Bq6ArRk3LDtJDwjh4m0ya-2L59ULb7BaqxkSDuCytkCr" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=amruthpillai/reactive-resume&type=date&legend=top-left&sealed_token=QmaOn4Ech499R6kpQe8ONn911UjGUaJfQBT0MXlQLU9hTo-Ie7lTxIILWbBvmtzDGHk7ziWKN_N5iM5mgP8widn_FGHd9-PHNokPtSji8XLgbFpqatgyqIDPnOys-IhO40W3J0HeH07FL-Q8Bq6ArRk3LDtJDwjh4m0ya-2L59ULb7BaqxkSDuCytkCr" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=amruthpillai/reactive-resume&type=date&legend=top-left&sealed_token=QmaOn4Ech499R6kpQe8ONn911UjGUaJfQBT0MXlQLU9hTo-Ie7lTxIILWbBvmtzDGHk7ziWKN_N5iM5mgP8widn_FGHd9-PHNokPtSji8XLgbFpqatgyqIDPnOys-IhO40W3J0HeH07FL-Q8Bq6ArRk3LDtJDwjh4m0ya-2L59ULb7BaqxkSDuCytkCr" />
 </picture>
 </a>

@@ -260,6 +261,10 @@ Contributions make open-source thrive. Whether fixing a typo or adding a feature

 See the [development setup guide](https://docs.rxresu.me/contributing/development) for detailed instructions on how to set up the project locally.

+Maintainers review the [`status: needs triage` queue](https://github.com/amruthpillai/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

 [MIT](./LICENSE) — do whatever you want with it.
@@ -7,6 +7,7 @@
 		"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",
@@ -17,25 +18,35 @@
 		"#react-pdf-renderer": "@react-pdf/renderer"
 	},
 	"dependencies": {
-		"@ai-sdk/anthropic": "^3.0.85",
-		"@ai-sdk/google": "^3.0.83",
-		"@ai-sdk/openai": "^3.0.72",
-		"@ai-sdk/openai-compatible": "^2.0.51",
-		"@aws-sdk/client-s3": "^3.1070.0",
-		"@better-auth/api-key": "^1.6.19",
-		"@better-auth/drizzle-adapter": "^1.6.19",
-		"@better-auth/infra": "^0.2.14",
-		"@better-auth/oauth-provider": "^1.6.19",
-		"@better-auth/passkey": "^1.6.19",
-		"@hono/node-server": "^2.0.5",
-		"@modelcontextprotocol/sdk": "^1.29.0",
-		"@orpc/client": "^1.14.6",
-		"@orpc/experimental-ratelimit": "^1.14.6",
-		"@orpc/json-schema": "^1.14.6",
-		"@orpc/openapi": "^1.14.6",
-		"@orpc/server": "^1.14.6",
-		"@orpc/zod": "^1.14.6",
-		"@react-pdf/renderer": "^4.5.1",
+		"@ai-sdk/anthropic": "^4.0.44",
+		"@ai-sdk/cerebras": "^3.0.39",
+		"@ai-sdk/cohere": "^4.0.33",
+		"@ai-sdk/deepseek": "^3.0.35",
+		"@ai-sdk/fireworks": "^3.0.42",
+		"@ai-sdk/google": "^4.0.54",
+		"@ai-sdk/groq": "^4.0.33",
+		"@ai-sdk/mistral": "^4.0.35",
+		"@ai-sdk/openai": "^4.0.50",
+		"@ai-sdk/openai-compatible": "^3.0.39",
+		"@ai-sdk/perplexity": "^4.0.34",
+		"@ai-sdk/togetherai": "^3.0.40",
+		"@ai-sdk/xai": "^4.0.47",
+		"@aws-sdk/client-s3": "^3.1119.0",
+		"@better-auth/api-key": "^1.7.2",
+		"@better-auth/drizzle-adapter": "^1.7.2",
+		"@better-auth/infra": "^0.4.3",
+		"@better-auth/oauth-provider": "^1.7.2",
+		"@better-auth/passkey": "^1.7.2",
+		"@bramus/specificity": "^2.4.2",
+		"@hono/node-server": "^2.1.1",
+		"@modelcontextprotocol/sdk": "^1.30.0",
+		"@orpc/client": "^1.15.0",
+		"@orpc/experimental-ratelimit": "^1.15.0",
+		"@orpc/json-schema": "^1.15.0",
+		"@orpc/openapi": "^1.15.0",
+		"@orpc/server": "^1.15.0",
+		"@orpc/zod": "^1.15.0",
+		"@react-pdf/renderer": "^4.8.1",
 		"@reactive-resume/api": "workspace:*",
 		"@reactive-resume/auth": "workspace:*",
 		"@reactive-resume/db": "workspace:*",
@@ -46,43 +57,43 @@
 		"@sindresorhus/slugify": "^3.0.0",
 		"@t3-oss/env-core": "^0.13.11",
 		"@uiw/color-convert": "^2.10.3",
-		"ai": "^6.0.207",
+		"ai": "^7.0.83",
 		"bcrypt": "^6.0.0",
-		"better-auth": "1.6.19",
+		"better-auth": "1.7.2",
 		"cjk-regex": "^3.4.0",
-		"deepmerge-ts": "^7.1.5",
-		"dompurify": "^3.4.10",
-		"dotenv": "^17.4.2",
-		"drizzle-orm": "1.0.0-rc.3",
+		"css-tree": "^3.2.1",
+		"deepmerge-ts": "^8.0.2",
+		"drizzle-orm": "1.0.0-rc.4",
 		"drizzle-zod": "1.0.0-beta.14-a36c63d",
-		"es-toolkit": "^1.47.1",
+		"es-toolkit": "^1.51.0",
 		"fast-json-patch": "^3.1.1",
-		"hono": "^4.12.25",
-		"jsonrepair": "^3.14.0",
-		"node-html-parser": "^7.1.0",
-		"nodemailer": "^9.0.0",
-		"ollama-ai-provider-v2": "^3.6.0",
-		"pg": "^8.21.0",
+		"hono": "^4.13.5",
+		"jsonrepair": "^3.15.0",
+		"node-html-parser": "^9.0.1",
+		"nodemailer": "^9.0.5",
+		"ollama-ai-provider-v2": "^4.0.1",
+		"pg": "^8.23.0",
 		"phosphor-icons-react-pdf": "^0.1.3",
-		"react": "^19.2.7",
-		"react-email": "^6.6.3",
+		"react": "^19.2.8",
+		"react-email": "^6.9.3",
 		"react-pdf-html": "^2.1.5",
 		"resumable-stream": "^2.2.12",
-		"sharp": "^0.35.1",
+		"sharp": "^0.35.4",
+		"tokenx": "^2.1.0",
 		"ts-pattern": "^5.9.0",
 		"unique-names-generator": "^4.7.1",
-		"uuid": "^14.0.0",
+		"uuid": "^14.0.2",
 		"zod": "^4.4.3"
 	},
 	"devDependencies": {
 		"@reactive-resume/config": "workspace:*",
-		"@types/node": "^25.9.3",
-		"@types/pg": "^8.20.0",
-		"@types/react": "^19.2.17",
-		"@typescript/native-preview": "7.0.0-dev.20260617.2",
-		"tsdown": "^0.22.3",
-		"tsx": "^4.22.4",
-		"typescript": "^6.0.3",
-		"vitest": "^4.1.9"
+		"@types/node": "^26.4.0",
+		"@types/pg": "^8.23.1",
+		"@types/react": "^19.2.18",
+		"@typescript/native-preview": "7.0.0-dev.20260707.2",
+		"tsdown": "^0.22.14",
+		"tsx": "^4.23.12",
+		"typescript": "^7.0.2",
+		"vitest": "^4.1.11"
 	}
 }
@@ -9,6 +9,7 @@ const mocks = vi.hoisted(() => ({
 	handleUpload: vi.fn(),
 	handleMcp: vi.fn(),
 	handleResumePdfDownload: vi.fn(),
+	handlePublicResumePdf: vi.fn(),
 	handleMcpServerCard: vi.fn(),
 	handleOAuthAuthorizationServer: vi.fn(),
 	handleOAuthProtectedResource: vi.fn(),
@@ -19,7 +20,6 @@ const mocks = vi.hoisted(() => ({
 	handleLlms: vi.fn(),
 	serveWebDistStatic: vi.fn(),
 	handleWebApp: vi.fn(),
-	handleWebAppHead: vi.fn(),
 }));

 vi.mock("./auth", () => ({
@@ -60,7 +60,6 @@ vi.mock("../static/seo", () => ({
 vi.mock("../static/web", () => ({
 	serveWebDistStatic: mocks.serveWebDistStatic,
 	handleWebApp: mocks.handleWebApp,
-	handleWebAppHead: mocks.handleWebAppHead,
 }));

 vi.mock("../mcp/handler", () => ({
@@ -71,6 +70,15 @@ 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"));
@@ -81,6 +89,7 @@ beforeEach(() => {
 	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"));
@@ -91,7 +100,6 @@ beforeEach(() => {
 	mocks.handleLlms.mockReturnValue(new Response("llms"));
 	mocks.serveWebDistStatic.mockResolvedValue(undefined);
 	mocks.handleWebApp.mockResolvedValue(new Response("web"));
-	mocks.handleWebAppHead.mockReturnValue(new Response(null));
 });

 describe("createApp", () => {
@@ -120,6 +128,51 @@ describe("createApp", () => {
 		expect(mocks.handleWebApp).not.toHaveBeenCalled();
 	});

+	it("uses the transport address for public PDF fallback despite rotated forwarding headers", async () => {
+		const { createApp } = await import("./app");
+		const app = createApp();
+		const first = new Request("http://localhost:3001/api/resumes/jane/resume/pdf", {
+			headers: { "x-forwarded-for": "198.51.100.1" },
+		});
+		const rotated = new Request("http://localhost:3001/api/resumes/jane/resume/pdf", {
+			headers: { "x-forwarded-for": "198.51.100.2" },
+		});
+		const env = transportEnv("203.0.113.9");
+
+		const response = await app.fetch(first, env);
+		await app.fetch(rotated, env);
+
+		await expect(response.text()).resolves.toBe("public-pdf");
+		expect(mocks.handlePublicResumePdf).toHaveBeenNthCalledWith(1, first, "jane", "resume", "203.0.113.9");
+		expect(mocks.handlePublicResumePdf).toHaveBeenNthCalledWith(2, rotated, "jane", "resume", "203.0.113.9");
+		expect(mocks.handleResumePdfDownload).not.toHaveBeenCalled();
+		expect(mocks.serveWebDistStatic).not.toHaveBeenCalled();
+		expect(mocks.handleWebApp).not.toHaveBeenCalled();
+	});
+
+	it("passes the transport address to RPC and OpenAPI and fails closed when it is unavailable", async () => {
+		const { createApp } = await import("./app");
+		const app = createApp();
+		const trustedRpcRequest = new Request("http://localhost:3001/api/rpc", {
+			headers: { "cf-connecting-ip": "198.51.100.1" },
+		});
+		const unknownRpcRequest = new Request("http://localhost:3001/api/rpc", {
+			headers: { "cf-connecting-ip": "198.51.100.2" },
+		});
+		const trustedOpenApiRequest = new Request("http://localhost:3001/api/openapi/resumes/jane/resume");
+		const unknownOpenApiRequest = new Request("http://localhost:3001/api/openapi/resumes/jane/resume");
+
+		await app.fetch(trustedRpcRequest, transportEnv("203.0.113.9"));
+		await app.fetch(unknownRpcRequest);
+		await app.fetch(trustedOpenApiRequest, transportEnv("203.0.113.9"));
+		await app.fetch(unknownOpenApiRequest);
+
+		expect(mocks.handleRpc).toHaveBeenNthCalledWith(1, trustedRpcRequest, "203.0.113.9");
+		expect(mocks.handleRpc).toHaveBeenNthCalledWith(2, unknownRpcRequest, "unknown");
+		expect(mocks.handleOpenApi).toHaveBeenNthCalledWith(1, trustedOpenApiRequest, "203.0.113.9");
+		expect(mocks.handleOpenApi).toHaveBeenNthCalledWith(2, unknownOpenApiRequest, "unknown");
+	});
+
 	it.each([
 		["GET", "/robots.txt", "robots", mocks.handleRobots],
 		["HEAD", "/robots.txt", "", mocks.handleRobots],
@@ -138,6 +191,17 @@ describe("createApp", () => {
 		expect(handler).toHaveBeenCalledWith({ head: method === "HEAD" });
 		expect(mocks.serveWebDistStatic).not.toHaveBeenCalled();
 		expect(mocks.handleWebApp).not.toHaveBeenCalled();
-		expect(mocks.handleWebAppHead).not.toHaveBeenCalled();
+	});
+
+	it.each(["GET", "HEAD"])("routes %s / to the web app handler so SEO markup is injected", async (method) => {
+		const { createApp } = await import("./app");
+		const app = createApp();
+		const request = new Request("http://localhost:3001/", { method });
+
+		const response = await app.fetch(request);
+
+		expect(response.status).toBe(200);
+		expect(mocks.handleWebApp).toHaveBeenCalledWith(request);
+		expect(mocks.serveWebDistStatic).not.toHaveBeenCalled();
 	});
 });
@@ -1,3 +1,7 @@
+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 { handleMcp } from "../mcp/handler";
 import { handleOpenApi } from "../openapi/handler";
@@ -12,21 +16,36 @@ import { handleRpc } from "../rpc/handler";
 import { handleSchemaJson } from "../static/schema";
 import { handleLlms, handleRobots, handleSitemap } from "../static/seo";
 import { handleUpload } from "../static/uploads";
-import { handleWebApp, handleWebAppHead, serveWebDistStatic } from "../static/web";
+import { 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";

-export function createApp() {
-	const app = new Hono();
+type ServerEnvironment = { Bindings: HttpBindings | Http2Bindings };

-	app.all("/api/rpc", (c) => handleRpc(c.req.raw));
-	app.all("/api/rpc/*", (c) => handleRpc(c.req.raw));
-	app.all("/api/openapi", (c) => handleOpenApi(c.req.raw));
-	app.all("/api/openapi/*", (c) => handleOpenApi(c.req.raw));
+const getTrustedClient = (context: Context<ServerEnvironment>): string => {
+	try {
+		const address = getConnInfo(context).remote.address?.trim();
+		return address && isIP(address) ? address : "unknown";
+	} catch {
+		return "unknown";
+	}
+};
+
+export function createApp() {
+	const app = new Hono<ServerEnvironment>();
+
+	app.all("/api/rpc", (c) => handleRpc(c.req.raw, getTrustedClient(c)));
+	app.all("/api/rpc/*", (c) => handleRpc(c.req.raw, getTrustedClient(c)));
+	app.all("/api/openapi", (c) => handleOpenApi(c.req.raw, getTrustedClient(c)));
+	app.all("/api/openapi/*", (c) => handleOpenApi(c.req.raw, getTrustedClient(c)));
 	app.get("/api/auth/oauth", (c) => handleOAuth(c.req.raw));
 	app.all("/api/auth/*", (c) => handleAuth(c.req.raw));
 	app.get("/api/health", () => handleHealth());
+	app.get("/api/resumes/:username/:slug/pdf", (c) =>
+		handlePublicResumePdf(c.req.raw, c.req.param("username"), c.req.param("slug"), getTrustedClient(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));
@@ -46,9 +65,11 @@ export function createApp() {
 	app.on(["GET", "HEAD"], "/sitemap.xml", (c) => handleSitemap({ head: c.req.method === "HEAD" }));
 	app.on(["GET", "HEAD"], "/llms.txt", (c) => handleLlms({ head: c.req.method === "HEAD" }));

+	// Must precede the static middleware: serveStatic resolves "/" to dist/index.html and would
+	// return it verbatim, skipping the OpenGraph/Twitter/canonical/JSON-LD injection in handleWebApp.
+	app.on(["GET", "HEAD"], "/", (c) => handleWebApp(c.req.raw));
 	app.use("/*", serveWebDistStatic);
-	app.on(["GET"], "/*", (c) => handleWebApp(c.req.raw));
-	app.on(["HEAD"], "/*", (c) => handleWebAppHead(c.req.raw));
+	app.on(["GET", "HEAD"], "/*", (c) => handleWebApp(c.req.raw));

 	return app;
 }
@@ -1,4 +1,5 @@
 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";

@@ -11,30 +12,12 @@ type CheckResult = {
 	[key: string]: unknown;
 };

-function getErrorMessage(error: unknown): string {
-	if (error instanceof Error) return error.message;
-	return "Unknown error";
-}
-
-async function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
-	let timeoutId: NodeJS.Timeout | undefined;
-
-	const timeout = new Promise<never>((_, reject) => {
-		timeoutId = setTimeout(() => reject(new Error(`Timed out after ${timeoutMs}ms`)), timeoutMs);
-	});
-
-	try {
-		return await Promise.race([promise, timeout]);
-	} finally {
-		if (timeoutId) clearTimeout(timeoutId);
-	}
-}
-
+// 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 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 };
@@ -42,35 +25,19 @@ async function runCheck(check: () => Promise<object>): Promise<CheckResult> {
 	} catch (error) {
 		return {
 			status: "unhealthy",
-			error: getErrorMessage(error),
+			error: error instanceof Error ? error.message : "Unknown error",
 			latencyMs: Math.round(performance.now() - startedAt),
 		};
 	}
 }

+// ponytail: inner try/catches removed; runCheck's outer catch handles all errors
 async function checkDatabase() {
-	try {
-		await db.execute(sql`SELECT 1`);
-		return { status: "healthy" };
-	} catch (error) {
-		return {
-			status: "unhealthy",
-			error: error instanceof Error ? error.message : "Unknown error",
-		};
-	}
+	await db.execute(sql`SELECT 1`);
+	return { status: "healthy" };
 }

-async function checkStorage() {
-	try {
-		const storageService = getStorageService();
-		return await storageService.healthcheck();
-	} catch (error) {
-		return {
-			status: "unhealthy",
-			error: error instanceof Error ? error.message : "Unknown error",
-		};
-	}
-}
+const checkStorage = () => getStorageService().healthcheck();

 export async function handleHealth() {
 	const [database, storage] = await Promise.all([runCheck(checkDatabase), runCheck(checkStorage)]);
@@ -0,0 +1,79 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+	createPublicResumePdf: vi.fn(),
+}));
+
+vi.mock("@reactive-resume/api/features/resume/public-pdf", () => ({
+	createPublicResumePdf: mocks.createPublicResumePdf,
+}));
+
+const { handlePublicResumePdf } = await import("./public-resume-pdf");
+const trustedClient = "203.0.113.9";
+
+describe("handlePublicResumePdf", () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it("returns the authorized on-demand PDF without forwarding compatibility metadata", async () => {
+		const body = new File(["%PDF"], "Ada_Lovelace.pdf", { type: "text/plain" });
+		mocks.createPublicResumePdf.mockResolvedValueOnce({
+			body,
+			filename: "Ada_Lovelace.pdf",
+		});
+		const request = new Request("https://example.com/api/resumes/jane/resume/pdf?ignored=true", {
+			headers: { "x-forwarded-for": "203.0.113.7" },
+		});
+
+		const response = await handlePublicResumePdf(request, "jane", "resume", trustedClient);
+
+		expect(response.status).toBe(200);
+		expect(response.headers.get("Content-Type")).toBe("application/pdf");
+		expect(response.headers.get("Content-Disposition")).toBe('inline; filename="Ada_Lovelace.pdf"');
+		expect(response.headers.get("Cache-Control")).toBe("private, no-store");
+		expect(response.headers.get("X-Content-Type-Options")).toBe("nosniff");
+		expect(await response.text()).toBe("%PDF");
+		expect(mocks.createPublicResumePdf).toHaveBeenCalledWith({
+			username: "jane",
+			slug: "resume",
+			requestHeaders: request.headers,
+			trustedClient,
+		});
+	});
+
+	it("keeps password and private responses uncacheable", async () => {
+		mocks.createPublicResumePdf.mockResolvedValueOnce({
+			body: new File(["%PDF"], "resume.pdf", { type: "application/pdf" }),
+			filename: "resume.pdf",
+		});
+		const request = new Request("https://example.com/api/resumes/jane/resume/pdf");
+
+		const response = await handlePublicResumePdf(request, "jane", "resume", trustedClient);
+
+		expect(response.headers.get("Cache-Control")).toBe("private, no-store");
+		expect(mocks.createPublicResumePdf).toHaveBeenCalledWith({
+			username: "jane",
+			slug: "resume",
+			requestHeaders: request.headers,
+			trustedClient,
+		});
+	});
+
+	it.each([
+		[{ code: "NEED_PASSWORD" }, 401],
+		[{ code: "NOT_FOUND" }, 404],
+		[{ code: "RATE_LIMIT_EXCEEDED" }, 429],
+		[{ code: "INTERNAL_SERVER_ERROR" }, 500],
+	])("maps controlled API errors without caching the response", async (error, status) => {
+		mocks.createPublicResumePdf.mockRejectedValueOnce(error);
+
+		const response = await handlePublicResumePdf(
+			new Request("https://example.com/api/resumes/jane/resume/pdf"),
+			"jane",
+			"resume",
+			trustedClient,
+		);
+
+		expect(response.status).toBe(status);
+		expect(response.headers.get("Cache-Control")).toBe("private, no-store");
+	});
+});
@@ -0,0 +1,43 @@
+import { createPublicResumePdf } from "@reactive-resume/api/features/resume/public-pdf";
+
+const noStoreResponse = (body: string, status: number) =>
+	new Response(body, { status, headers: { "Cache-Control": "private, no-store" } });
+
+const errorStatus = (error: unknown): number => {
+	const code = typeof error === "object" && error && "code" in error ? (error as { code?: unknown }).code : undefined;
+	if (code === "NEED_PASSWORD") return 401;
+	if (code === "NOT_FOUND") return 404;
+	if (code === "RATE_LIMIT_EXCEEDED") return 429;
+	return 500;
+};
+
+export async function handlePublicResumePdf(
+	request: Request,
+	username: string,
+	slug: string,
+	trustedClient = "unknown",
+): Promise<Response> {
+	try {
+		const result = await createPublicResumePdf({
+			username,
+			slug,
+			requestHeaders: request.headers,
+			trustedClient,
+		});
+
+		return new Response(result.body, {
+			headers: {
+				"Content-Type": "application/pdf",
+				"Content-Disposition": `inline; filename="${result.filename.replaceAll('"', "")}"`,
+				"Cache-Control": "private, no-store",
+				"X-Content-Type-Options": "nosniff",
+			},
+		});
+	} catch (error) {
+		const status = errorStatus(error);
+		return noStoreResponse(
+			status === 500 ? "Failed to generate public resume PDF" : "Public resume PDF unavailable",
+			status,
+		);
+	}
+}
@@ -23,6 +23,7 @@ describe("handleResumePdfDownload", () => {
 			ok: true,
 			resumeId: "resume-1",
 			userId: "user-1",
+			target: "resume",
 			expiresAt: "2026-06-01T10:10:00.000Z",
 		});
 		mocks.createResumePdfDownload.mockResolvedValueOnce({
@@ -40,7 +41,89 @@ describe("handleResumePdfDownload", () => {
 		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" });
+		expect(mocks.createResumePdfDownload).toHaveBeenCalledWith({ id: "resume-1", userId: "user-1", target: "resume" });
+	});
+
+	it("passes the cover letter target through to PDF rendering", async () => {
+		const pdf = new File([new Uint8Array([37, 80, 68, 70])], "Cover Letter.pdf", { type: "application/pdf" });
+		mocks.verifyResumePdfDownloadToken.mockReturnValueOnce({
+			ok: true,
+			resumeId: "resume-1",
+			userId: "user-1",
+			target: "cover-letter",
+			expiresAt: "2026-06-01T10:10:00.000Z",
+		});
+		mocks.createResumePdfDownload.mockResolvedValueOnce({
+			headers: { "content-disposition": 'attachment; filename="Cover Letter.pdf"' },
+			body: pdf,
+		});
+
+		await handleResumePdfDownload(
+			new Request("https://example.com/api/resumes/resume-1/pdf?token=signed&target=cover-letter"),
+			"resume-1",
+		);
+
+		expect(mocks.createResumePdfDownload).toHaveBeenCalledWith({
+			id: "resume-1",
+			userId: "user-1",
+			target: "cover-letter",
+		});
+	});
+
+	it("defaults a legacy token without a target to resume", async () => {
+		mocks.verifyResumePdfDownloadToken.mockReturnValueOnce({
+			ok: true,
+			resumeId: "resume-1",
+			userId: "user-1",
+			expiresAt: "2026-06-01T10:10:00.000Z",
+		});
+		mocks.createResumePdfDownload.mockResolvedValueOnce({
+			headers: { "content-disposition": 'attachment; filename="Cover Letter.pdf"' },
+			body: new File([], "Cover Letter.pdf", { type: "application/pdf" }),
+		});
+
+		await handleResumePdfDownload(new Request("https://example.com/api/resumes/resume-1/pdf?token=legacy"), "resume-1");
+
+		expect(mocks.createResumePdfDownload).toHaveBeenCalledWith({
+			id: "resume-1",
+			userId: "user-1",
+			target: "resume",
+		});
+	});
+
+	it("rejects a cover-letter target for a legacy token without one", async () => {
+		mocks.verifyResumePdfDownloadToken.mockReturnValueOnce({
+			ok: true,
+			resumeId: "resume-1",
+			userId: "user-1",
+			expiresAt: "2026-06-01T10:10:00.000Z",
+		});
+
+		const response = await handleResumePdfDownload(
+			new Request("https://example.com/api/resumes/resume-1/pdf?token=legacy&target=cover-letter"),
+			"resume-1",
+		);
+
+		expect(response.status).toBe(401);
+		expect(mocks.createResumePdfDownload).not.toHaveBeenCalled();
+	});
+
+	it("rejects a target that differs from the signed token", async () => {
+		mocks.verifyResumePdfDownloadToken.mockReturnValueOnce({
+			ok: true,
+			resumeId: "resume-1",
+			userId: "user-1",
+			target: "resume",
+			expiresAt: "2026-06-01T10:10:00.000Z",
+		});
+
+		const response = await handleResumePdfDownload(
+			new Request("https://example.com/api/resumes/resume-1/pdf?token=signed&target=cover-letter"),
+			"resume-1",
+		);
+
+		expect(response.status).toBe(401);
+		expect(mocks.createResumePdfDownload).not.toHaveBeenCalled();
 	});

 	it("rejects missing, invalid, and expired tokens before rendering", async () => {
@@ -24,14 +24,23 @@ function errorStatus(error: unknown) {
 }

 export async function handleResumePdfDownload(request: Request, id: string) {
-	const token = new URL(request.url).searchParams.get("token");
+	const searchParams = new URL(request.url).searchParams;
+	const token = searchParams.get("token");
 	if (!token) return unauthorizedResponse();

 	const verification = verifyResumePdfDownloadToken({ resumeId: id, token });
 	if (!verification.ok) return verification.reason === "expired" ? expiredResponse() : unauthorizedResponse();
+	const queryTarget = searchParams.get("target");
+	if (
+		verification.target
+			? queryTarget !== null && queryTarget !== verification.target
+			: queryTarget && queryTarget !== "resume"
+	)
+		return unauthorizedResponse();

 	try {
-		const download = await createResumePdfDownload({ id, userId: verification.userId });
+		const target = verification.target ?? "resume";
+		const download = await createResumePdfDownload({ id, userId: verification.userId, target });

 		return new Response(download.body, {
 			headers: {
@@ -9,6 +9,14 @@ export { createApp } from "./http/app";
 async function main() {
 	await runStartupChecks();

+	// 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;

@@ -1,5 +1,21 @@
 import { auth, verifyOAuthToken } from "@reactive-resume/auth/config";

+const OAUTH_WARN_THROTTLE_MS = 60_000;
+let lastOAuthWarnAt = 0;
+
+function warnOAuthThrottled(message: string, detail?: unknown): void {
+	const now = Date.now();
+	if (now - lastOAuthWarnAt < OAUTH_WARN_THROTTLE_MS) return;
+	lastOAuthWarnAt = now;
+
+	if (detail !== undefined) {
+		console.warn(message, detail);
+		return;
+	}
+
+	console.warn(message);
+}
+
 export class AuthError extends Error {
 	constructor() {
 		super("Unauthorized");
@@ -13,8 +29,9 @@ export async function authenticateRequest(request: Request): Promise<void> {
 		try {
 			const payload = await verifyOAuthToken(authHeader.slice(7));
 			if (payload?.sub) return;
-		} catch {
-			// Invalid or expired token; fall through to API key auth.
+			warnOAuthThrottled("[MCP] OAuth token verified but missing `sub` claim");
+		} catch (error) {
+			warnOAuthThrottled("[MCP] OAuth token verification failed:", error);
 		}
 	}

@@ -7,7 +7,7 @@ export async function handleMcp(request: Request) {
 	try {
 		await authenticateRequest(request);

-		const server = await createMcpServer(request);
+		const server = createMcpServer(request);
 		const transport = new WebStandardStreamableHTTPServerTransport({
 			enableJsonResponse: true,
 		});
@@ -22,7 +22,7 @@ function createRequestClient(request: Request): RouterClient<typeof router> {
 	});
 }

-export async function createMcpServer(request: Request) {
+export function createMcpServer(request: Request) {
 	const server = new McpServer(
 		{
 			name: "reactive-resume",
@@ -53,8 +53,8 @@ export async function createMcpServer(request: Request) {
 				`Read schema at \`resume://_meta/schema\`; read resume JSON via \`resume://{id}\` or \`${MCP_TOOL_NAME.getResume}\`.`,
 				`Apply body edits with JSON Patch through \`${MCP_TOOL_NAME.patchResume}\`.`,
 				`Change name, slug, tags, or public visibility with \`${MCP_TOOL_NAME.updateResume}\` (returns canonical share URL; anonymous access only when \`isPublic\` is true; passwords are managed in the web app only).`,
-				`Create short-lived authenticated PDF download URLs with \`${MCP_TOOL_NAME.downloadResumePdf}\`.`,
-				`Import full ResumeData JSON with \`${MCP_TOOL_NAME.importResume}\`; read saved AI analysis with \`${MCP_TOOL_NAME.getResumeAnalysis}\`.`,
+				`Create short-lived authenticated PDF download URLs with \`${MCP_TOOL_NAME.downloadResumePdf}\`; set target to \`cover-letter\` to export a visible cover letter separately.`,
+				`Import full ResumeData JSON with \`${MCP_TOOL_NAME.importResume}\`.`,
 			].join(" "),
 		},
 	);
@@ -0,0 +1,20 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+export async function generateOpenApiDocumentation(
+	target = fileURLToPath(new URL("../../../../docs/spec.json", import.meta.url)),
+) {
+	const packageJson = JSON.parse(await readFile(new URL("../../../../package.json", import.meta.url), "utf8")) as {
+		version: string;
+	};
+	process.env.APP_URL ??= "https://rxresu.me";
+	process.env.DATABASE_URL ??= "postgresql://localhost/reactive_resume_docs";
+	process.env.AUTH_SECRET ??= "documentation-generation-isolated-process-only";
+	const { generateOpenApiSpec } = await import("./generator");
+	const spec = await generateOpenApiSpec({ appUrl: "https://rxresu.me", version: packageJson.version });
+	await writeFile(target, `${JSON.stringify(spec, null, "\t")}\n`);
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+	await generateOpenApiDocumentation(process.argv[2]);
+}
@@ -0,0 +1,154 @@
+import { describe, expect, it } from "vitest";
+import z from "zod";
+import { defaultResumeData } from "@reactive-resume/schema/resume/default";
+import { createResumeDataJsonSchema } from "@reactive-resume/schema/resume/json-schema";
+
+type GeneratedSpecView = {
+	components?: { schemas?: Record<string, unknown> };
+	paths?: Record<
+		string,
+		Record<
+			string,
+			{
+				requestBody?: {
+					content?: Record<string, { schema?: unknown }>;
+				};
+			}
+		>
+	>;
+};
+
+// Building the spec walks every router and resume JSON schema, which costs seconds. It is
+// deterministic and every test here only reads it, so generate it once for the whole file —
+// regenerating per test made the first case time out under a loaded machine.
+let specPromise: ReturnType<typeof generateOnce> | undefined;
+
+async function generateOnce() {
+	const { generateOpenApiSpec } = await import("./generator");
+	return generateOpenApiSpec({
+		appUrl: "https://rxresu.me",
+		version: "9.8.7",
+	});
+}
+
+function generateSpec() {
+	specPromise ??= generateOnce();
+	return specPromise;
+}
+
+function getRequestSchema(spec: GeneratedSpecView, path: string, method: string) {
+	return spec.paths?.[path]?.[method]?.requestBody?.content?.["application/json"]?.schema;
+}
+
+function containsImpossibleSchema(value: unknown): boolean {
+	if (Array.isArray(value)) return value.some(containsImpossibleSchema);
+	if (typeof value !== "object" || value === null) return false;
+	const object = value as Record<string, unknown>;
+	const negated = object.not;
+	if (typeof negated === "object" && negated !== null && Object.keys(negated).length === 0) {
+		return true;
+	}
+	return Object.values(object).some(containsImpossibleSchema);
+}
+
+function findImpossibleRequestSchemas(spec: GeneratedSpecView) {
+	const impossibleRequests: string[] = [];
+	for (const [path, operations] of Object.entries(spec.paths ?? {})) {
+		for (const [method, operation] of Object.entries(operations)) {
+			for (const [mediaType, content] of Object.entries(operation.requestBody?.content ?? {})) {
+				if (containsImpossibleSchema(content.schema)) {
+					impossibleRequests.push(`${method.toUpperCase()} ${path} (${mediaType})`);
+				}
+			}
+		}
+	}
+	return impossibleRequests;
+}
+
+describe("generateOpenApiSpec", () => {
+	it("uses caller-provided application URL and version", async () => {
+		const spec = await generateSpec();
+
+		expect(spec.info).toMatchObject({
+			title: "Reactive Resume",
+			version: "9.8.7",
+		});
+		expect(spec.servers).toEqual([{ url: "https://rxresu.me/api/openapi" }]);
+		expect(spec.externalDocs).toEqual({
+			url: "https://docs.rxresu.me",
+			description: "Reactive Resume Documentation",
+		});
+	}, 15_000);
+
+	it("uses the canonical input-side ResumeData schema in update requests", async () => {
+		const spec = (await generateSpec()) as GeneratedSpecView;
+		const { $schema: _dialect, ...canonicalInputSchema } = createResumeDataJsonSchema();
+
+		expect(spec.components?.schemas?.ResumeData).toEqual(canonicalInputSchema);
+		expect(getRequestSchema(spec, "/resumes/{id}", "put")).toMatchObject({
+			properties: {
+				data: { $ref: "#/components/schemas/ResumeData" },
+			},
+		});
+	});
+
+	it("publishes the custom-section type and item correlation", async () => {
+		const spec = (await generateSpec()) as GeneratedSpecView;
+		const schema = z.fromJSONSchema(spec.components?.schemas?.ResumeData as Parameters<typeof z.fromJSONSchema>[0]);
+		const mismatched = {
+			...defaultResumeData,
+			customSections: [
+				{
+					id: "custom-experience",
+					type: "experience",
+					title: "Experience",
+					icon: "",
+					columns: 1,
+					hidden: false,
+					keepTogether: false,
+					startOnNewPage: false,
+					items: [{ id: "summary-item", hidden: false, content: "<p>Not an experience item</p>" }],
+				},
+			],
+		};
+
+		expect(schema.safeParse(mismatched).success).toBe(false);
+	});
+
+	it("does not publish impossible request schemas", async () => {
+		const spec = (await generateSpec()) as GeneratedSpecView;
+
+		expect(findImpossibleRequestSchemas(spec)).toEqual([]);
+	});
+
+	it("checks every request body media type for impossible schemas", () => {
+		const spec: GeneratedSpecView = {
+			paths: {
+				"/documents": {
+					post: {
+						requestBody: {
+							content: {
+								"application/json": { schema: { type: "object" } },
+								"multipart/form-data": { schema: { not: {} } },
+							},
+						},
+					},
+				},
+			},
+		};
+
+		expect(findImpossibleRequestSchemas(spec)).toEqual(["POST /documents (multipart/form-data)"]);
+	});
+
+	it("documents imported data as an accepted ResumeData input", async () => {
+		const spec = (await generateSpec()) as GeneratedSpecView;
+
+		expect(getRequestSchema(spec, "/resumes/import", "post")).toEqual({
+			type: "object",
+			properties: {
+				data: { $ref: "#/components/schemas/ResumeData" },
+			},
+			required: ["data"],
+		});
+	});
+});
@@ -0,0 +1,80 @@
+import { OpenAPIGenerator } from "@orpc/openapi";
+import { JSON_SCHEMA_INPUT_REGISTRY, ZodToJsonSchemaConverter } from "@orpc/zod/zod4";
+import { downloadResumePdfProcedure } from "@reactive-resume/api/features/resume/export";
+import router from "@reactive-resume/api/routers";
+import { resumeDataSchema } from "@reactive-resume/schema/resume/data";
+import { createResumeDataJsonSchema } from "@reactive-resume/schema/resume/json-schema";
+
+export const openAPIRouter = {
+	...router,
+	resume: {
+		...router.resume,
+		downloadPdf: downloadResumePdfProcedure,
+	},
+};
+
+const { $schema: _dialect, ...resumeDataInputSchema } = createResumeDataJsonSchema();
+type ResumeDataInputJsonSchema = Parameters<typeof JSON_SCHEMA_INPUT_REGISTRY.add<typeof resumeDataSchema>>[1];
+JSON_SCHEMA_INPUT_REGISTRY.add(resumeDataSchema, resumeDataInputSchema as unknown as ResumeDataInputJsonSchema);
+const importResumeInputSchema = openAPIRouter.resume.import["~orpc"].inputSchema;
+if (importResumeInputSchema) {
+	JSON_SCHEMA_INPUT_REGISTRY.add(importResumeInputSchema, {
+		type: "object",
+		properties: {
+			data: { $ref: "#/components/schemas/ResumeData" },
+		},
+		required: ["data"],
+	});
+}
+
+const openAPIGenerator = new OpenAPIGenerator({
+	schemaConverters: [
+		new ZodToJsonSchemaConverter({
+			interceptors: [
+				({ options, next }) => {
+					const [required, schema] = next();
+					const impossible =
+						Object.keys(schema).length === 1 &&
+						typeof schema.not === "object" &&
+						schema.not !== null &&
+						Object.keys(schema.not).length === 0;
+					return options.strategy === "input" && impossible ? [required, {}] : [required, schema];
+				},
+			],
+		}),
+	],
+});
+
+type GenerateOpenApiSpecOptions = {
+	appUrl: string;
+	version: string;
+};
+
+export async function generateOpenApiSpec({ appUrl, version }: GenerateOpenApiSpecOptions) {
+	return await openAPIGenerator.generate(openAPIRouter, {
+		info: {
+			title: "Reactive Resume",
+			version,
+			description: "Reactive Resume API",
+			license: { name: "MIT", url: "https://github.com/amruthpillai/reactive-resume/blob/main/LICENSE" },
+			contact: { name: "Amruth Pillai", email: "hello@amruthpillai.com", url: "https://amruthpillai.com" },
+		},
+		servers: [{ url: `${appUrl}/api/openapi` }],
+		externalDocs: { url: "https://docs.rxresu.me", description: "Reactive Resume Documentation" },
+		commonSchemas: {
+			ResumeData: { schema: resumeDataSchema, strategy: "input" },
+		},
+		components: {
+			securitySchemes: {
+				apiKey: {
+					type: "apiKey",
+					name: "x-api-key",
+					in: "header",
+					description: "The API key to authenticate requests.",
+				},
+			},
+		},
+		security: [{ apiKey: [] }],
+		filter: ({ contract }) => !contract["~orpc"].route.tags?.includes("Internal"),
+	});
+}
@@ -1,24 +1,13 @@
 import { SmartCoercionPlugin } from "@orpc/json-schema";
-import { OpenAPIGenerator } from "@orpc/openapi";
 import { OpenAPIHandler } from "@orpc/openapi/fetch";
 import { onError } from "@orpc/server";
 import { BatchHandlerPlugin, RequestHeadersPlugin, StrictGetMethodPlugin } from "@orpc/server/plugins";
 import { ZodToJsonSchemaConverter } from "@orpc/zod/zod4";
-import { downloadResumePdfProcedure } from "@reactive-resume/api/features/resume/export";
-import router from "@reactive-resume/api/routers";
 import { env } from "@reactive-resume/env/server";
-import { resumeDataSchema } from "@reactive-resume/schema/resume/data";
 import { appVersion } from "../app-version";
 import { mergeResponseHeaders } from "../http/headers";
 import { getRequestLocale } from "../rpc/locale";
-
-const openAPIRouter = {
-	...router,
-	resume: {
-		...router.resume,
-		downloadPdf: downloadResumePdfProcedure,
-	},
-};
+import { generateOpenApiSpec, openAPIRouter } from "./generator";

 const openAPIHandler = new OpenAPIHandler(openAPIRouter, {
 	plugins: [
@@ -36,46 +25,15 @@ const openAPIHandler = new OpenAPIHandler(openAPIRouter, {
 	],
 });

-const openAPIGenerator = new OpenAPIGenerator({
-	schemaConverters: [new ZodToJsonSchemaConverter()],
-});
-
-export async function handleOpenApi(request: Request) {
+export async function handleOpenApi(request: Request, trustedClient = "unknown") {
 	if (request.method === "GET" && (request.url.endsWith("/spec.json") || request.url.endsWith("/spec"))) {
-		const spec = await openAPIGenerator.generate(openAPIRouter, {
-			info: {
-				title: "Reactive Resume",
-				version: appVersion,
-				description: "Reactive Resume API",
-				license: { name: "MIT", url: "https://github.com/amruthpillai/reactive-resume/blob/main/LICENSE" },
-				contact: { name: "Amruth Pillai", email: "hello@amruthpillai.com", url: "https://amruthpillai.com" },
-			},
-			servers: [{ url: `${env.APP_URL}/api/openapi` }],
-			externalDocs: { url: "https://docs.rxresu.me", description: "Reactive Resume Documentation" },
-			commonSchemas: {
-				ResumeData: { schema: resumeDataSchema },
-			},
-			components: {
-				securitySchemes: {
-					apiKey: {
-						type: "apiKey",
-						name: "x-api-key",
-						in: "header",
-						description: "The API key to authenticate requests.",
-					},
-				},
-			},
-			security: [{ apiKey: [] }],
-			filter: ({ contract }) => !contract["~orpc"].route.tags?.includes("Internal"),
-		});
-
-		return Response.json(spec);
+		return Response.json(await generateOpenApiSpec({ appUrl: env.APP_URL, version: appVersion }));
 	}

 	const resHeaders = new Headers();
 	const { response } = await openAPIHandler.handle(request, {
 		prefix: "/api/openapi",
-		context: { locale: getRequestLocale(request), reqHeaders: request.headers, resHeaders },
+		context: { locale: getRequestLocale(request), reqHeaders: request.headers, resHeaders, trustedClient },
 	});

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

-const oauthAuthorizationServerHandler = oauthProviderAuthServerMetadata(auth);
-const openIdConfigurationHandler = oauthProviderOpenIdConfigMetadata(auth);
+export const handleOAuthAuthorizationServer = oauthProviderAuthServerMetadata(auth);
+export const handleOpenIdConfiguration = oauthProviderOpenIdConfigMetadata(auth);

 export function handleWellKnownFallback() {
 	return new Response("OK", { status: 200 });
@@ -20,19 +20,11 @@ export function handleMcpServerCard() {
 	});
 }

-export function handleOAuthAuthorizationServer(request: Request) {
-	return oauthAuthorizationServerHandler(request);
-}
-
-export function handleOpenIdConfiguration(request: Request) {
-	return openIdConfigurationHandler(request);
-}
-
-export async function handleOAuthProtectedResource() {
+export function handleOAuthProtectedResource() {
 	const metadata = {
 		resource: env.APP_URL,
 		bearer_methods_supported: ["header"],
-		authorization_servers: [env.APP_URL, `${env.APP_URL}/api/auth`],
+		authorization_servers: [`${env.APP_URL}/api/auth`],
 	};

 	return Response.json(metadata, {
@@ -14,11 +14,16 @@ const rpcHandler = new RPCHandler(router, {
 	],
 });

-export async function handleRpc(request: Request) {
+export async function handleRpc(request: Request, trustedClient = "unknown") {
 	const resHeaders = new Headers();
 	const { response } = await rpcHandler.handle(request, {
 		prefix: "/api/rpc",
-		context: { locale: getRequestLocale(request), reqHeaders: request.headers, resHeaders },
+		context: {
+			locale: getRequestLocale(request),
+			reqHeaders: request.headers,
+			resHeaders,
+			trustedClient,
+		},
 	});

 	if (!response) return new Response("NOT_FOUND", { status: 404 });
@@ -61,7 +61,18 @@ async function validateLocalStoragePath() {
 	}
 }

+async function reapStaleAgentRuns() {
+	try {
+		const { reapStaleAgentRunsAtBoot } = await import("@reactive-resume/api/features/agent/runs");
+		await reapStaleAgentRunsAtBoot();
+	} catch (error) {
+		// A reap failure must not block serving traffic; stuck runs also heal lazily on access.
+		console.error("Failed to reap stale agent runs at boot", { error });
+	}
+}
+
 export async function runStartupChecks() {
 	await runDatabaseMigrations();
 	await validateLocalStoragePath();
+	await reapStaleAgentRuns();
 }
@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import z from "zod";
+import { defaultResumeData } from "@reactive-resume/schema/resume/default";
+import { handleSchemaJson } from "./schema";
+
+describe("handleSchemaJson", () => {
+	it("publishes the custom-section type and item correlation", async () => {
+		const response = handleSchemaJson();
+		const schema = z.fromJSONSchema((await response.json()) as Parameters<typeof z.fromJSONSchema>[0]);
+		const mismatched = {
+			...defaultResumeData,
+			customSections: [
+				{
+					id: "custom-experience",
+					type: "experience",
+					title: "Experience",
+					icon: "",
+					columns: 1,
+					hidden: false,
+					keepTogether: false,
+					startOnNewPage: false,
+					items: [{ id: "summary-item", hidden: false, content: "<p>Not an experience item</p>" }],
+				},
+			],
+		};
+
+		expect(schema.safeParse(mismatched).success).toBe(false);
+	});
+});
@@ -1,11 +1,8 @@
-import z from "zod";
-import { resumeDataSchema } from "@reactive-resume/schema/resume/data";
+import { createResumeDataJsonSchema } from "@reactive-resume/schema/resume/json-schema";
 import { appVersion } from "../app-version";

 export function handleSchemaJson() {
-	const resumeDataJSONSchema = z.toJSONSchema(resumeDataSchema);
-
-	return Response.json(resumeDataJSONSchema, {
+	return Response.json(createResumeDataJsonSchema(), {
 		status: 200,
 		headers: {
 			"Content-Type": "application/schema+json; charset=utf-8",
@@ -33,6 +33,7 @@ describe("SEO static endpoints", () => {
 		expect(response.status).toBe(200);
 		expect(response.headers.get("Content-Type")).toBe("application/xml; charset=UTF-8");
 		expect(text).toContain("<loc>https://app.example.com/</loc>");
+		expect(text).toContain("<loc>https://app.example.com/ats-checker</loc>");
 		expect(text).not.toContain("docs.rxresu.me");
 		expect(text).not.toContain("/auth");
 		expect(text).not.toContain("/dashboard");
@@ -42,6 +42,9 @@ export function handleSitemap(options?: StaticSeoOptions) {
 		"  <url>",
 		`    <loc>${baseUrl}/</loc>`,
 		"  </url>",
+		"  <url>",
+		`    <loc>${baseUrl}/ats-checker</loc>`,
+		"  </url>",
 		"</urlset>",
 		"",
 	].join("\n");
@@ -33,6 +33,8 @@ describe("handleUpload", () => {
 		expect(response.status).toBe(200);
 		expect(readMock).toHaveBeenCalledWith("uploads/user-1/pictures/photo.jpeg");
 		expect(response.headers.get("Content-Type")).toBe("image/jpeg");
+		expect(response.headers.get("Cross-Origin-Resource-Policy")).toBe("same-site");
+		expect(response.headers.get("Access-Control-Allow-Origin")).toBeNull();
 	});

 	it("does not serve private agent attachment keys through the public uploads route", async () => {
@@ -1,7 +1,6 @@
 import { createHash } from "node:crypto";
 import { basename, extname, normalize } from "node:path";
-import { getStorageService } from "@reactive-resume/api/features/storage";
-import { env } from "@reactive-resume/env/server";
+import { getStorageService, inferContentType } from "@reactive-resume/api/features/storage";

 export async function handleUpload(request: Request) {
 	const { userId, filePath } = parseRouteParams(request.url);
@@ -18,41 +17,31 @@ export async function handleUpload(request: Request) {

 	const filename = filePath.split("/").pop() ?? filePath;
 	const ext = extname(filename).toLowerCase();
-	const contentType = storedFile.contentType ?? inferContentTypeFromExtension(ext);
+	const contentType = storedFile.contentType ?? inferContentType(filename);
 	const etag = createEtag(storedFile);

 	if (isNotModified(request.headers, etag)) return makeNotModifiedResponse(etag);

 	const shouldForceDownload = [".pdf"].includes(ext);
-	const headers = buildResponseHeaders({
-		filename,
-		storedFile,
-		contentType,
-		etag,
-		shouldForceDownload,
-	});

-	const buffer = toArrayBuffer(storedFile.data);
+	const headers = new Headers();
+	headers.set("Content-Type", shouldForceDownload ? "application/octet-stream" : contentType);
+	headers.set("Content-Length", storedFile.size.toString());

-	return new Response(buffer, { headers });
-}
-
-function inferContentTypeFromExtension(ext: string): string {
-	switch (ext) {
-		case ".webp":
-			return "image/webp";
-		case ".png":
-			return "image/png";
-		case ".jpg":
-		case ".jpeg":
-			return "image/jpeg";
-		case ".gif":
-			return "image/gif";
-		case ".pdf":
-			return "application/pdf";
-		default:
-			return "application/octet-stream";
+	if (shouldForceDownload) {
+		headers.set("Content-Disposition", `attachment; filename="${encodeURIComponent(basename(filename))}"`);
 	}
+
+	headers.set("Cache-Control", "public, max-age=31536000, immutable");
+	headers.set("ETag", etag);
+	headers.set("X-Content-Type-Options", "nosniff");
+	headers.set("X-Robots-Tag", "noindex, nofollow");
+	headers.set("Cross-Origin-Resource-Policy", "same-site");
+	headers.set("Referrer-Policy", "strict-origin-when-cross-origin");
+	headers.set("X-Frame-Options", "DENY");
+	headers.set("X-Download-Options", "noopen");
+
+	return new Response(toArrayBuffer(storedFile.data), { headers });
 }

 function parseRouteParams(url: string): { userId: string | undefined; filePath: string | undefined } {
@@ -101,43 +90,6 @@ function makeNotModifiedResponse(etag: string): Response {
 	});
 }

-type BuildResponseHeaderArgs = {
-	filename: string;
-	storedFile: { size: number };
-	contentType: string;
-	etag: string;
-	shouldForceDownload: boolean;
-};
-
-function buildResponseHeaders({
-	filename,
-	storedFile,
-	contentType,
-	etag,
-	shouldForceDownload,
-}: BuildResponseHeaderArgs): Headers {
-	const headers = new Headers();
-
-	headers.set("Content-Type", shouldForceDownload ? "application/octet-stream" : contentType);
-	headers.set("Content-Length", storedFile.size.toString());
-
-	if (shouldForceDownload) {
-		headers.set("Content-Disposition", `attachment; filename="${encodeURIComponent(basename(filename))}"`);
-	}
-
-	headers.set("Cache-Control", "public, max-age=31536000, immutable");
-	headers.set("ETag", etag);
-	headers.set("X-Content-Type-Options", "nosniff");
-	headers.set("X-Robots-Tag", "noindex, nofollow");
-	headers.set("Cross-Origin-Resource-Policy", "same-site");
-	headers.set("Referrer-Policy", "strict-origin-when-cross-origin");
-	headers.set("X-Frame-Options", "DENY");
-	headers.set("X-Download-Options", "noopen");
-	headers.set("Access-Control-Allow-Origin", env.APP_URL);
-
-	return headers;
-}
-
 function toArrayBuffer(data: Uint8Array): ArrayBuffer {
 	return data.byteOffset === 0 && data.byteLength === data.buffer.byteLength
 		? (data.buffer as ArrayBuffer)
@@ -1,6 +1,16 @@
 import fs from "node:fs/promises";
 import { beforeEach, describe, expect, it, vi } from "vitest";

+const mocks = vi.hoisted(() => ({
+	env: { APP_URL: "https://rxresu.me" },
+	serveStatic: vi.fn((_options?: unknown) => vi.fn()),
+	getPublicResumeSocialMeta: vi.fn(),
+}));
+
+vi.mock("@reactive-resume/api/features/resume/social-meta", () => ({
+	getPublicResumeSocialMeta: mocks.getPublicResumeSocialMeta,
+}));
+
 vi.mock("node:fs", () => ({
 	existsSync: vi.fn(() => true),
 }));
@@ -12,15 +22,31 @@ vi.mock("node:fs/promises", () => ({
 }));

 vi.mock("@hono/node-server/serve-static", () => ({
-	serveStatic: vi.fn(() => vi.fn()),
+	serveStatic: mocks.serveStatic,
 }));

-const { handleWebApp, handleWebAppHead } = await import("./web");
+vi.mock("@reactive-resume/env/server", () => ({
+	env: mocks.env,
+}));
+
+type StaticOptions = {
+	onFound?: (
+		path: string,
+		context: {
+			req: { path: string };
+			header: (name: string, value: string) => void;
+		},
+	) => void | Promise<void>;
+};
+
+const { handleWebApp } = await import("./web");
+const staticOptions = mocks.serveStatic.mock.calls[0]?.[0] as StaticOptions | undefined;

 describe("web app fallback classification", () => {
 	beforeEach(() => {
 		vi.clearAllMocks();
 		vi.mocked(fs.readFile).mockResolvedValue("<html>app</html>");
+		mocks.getPublicResumeSocialMeta.mockResolvedValue(null);
 	});

 	it("serves the shell for the root app route without noindex", async () => {
@@ -32,22 +58,180 @@ describe("web app fallback classification", () => {
 		expect(await response.text()).toBe("<html>app</html>");
 	});

-	it.each([
-		"/auth/login",
-		"/dashboard",
-		"/builder/resume-1",
-		"/agent",
-		"/templates",
-		"/templates/azurill.pdf",
-	])("serves noindex shell for known app prefix %s", async (pathname) => {
+	it("injects canonical metadata and structured data into tracking-parameter root requests only", async () => {
+		vi.mocked(fs.readFile).mockResolvedValue(`
+			<!doctype html>
+			<html>
+				<head>
+					<title>Reactive Resume — A free and open-source resume builder</title>
+					<meta
+						name="description"
+						content="Reactive Resume is a free and open-source resume builder that simplifies the process of creating, updating, and sharing your resume."
+					>
+				</head>
+				<body><div id="app"></div></body>
+			</html>
+		`);
+
+		const response = await handleWebApp(new Request("http://server.internal/?utm_source=search"));
+		const html = await response.text();
+
+		expect(html).toContain('<link rel="canonical" href="https://rxresu.me/">');
+		expect(html).toContain('<link rel="preload" href="/videos/timelapse-v1.webp" as="image" fetchpriority="high">');
+		expect(html).toContain('<meta property="og:url" content="https://rxresu.me/">');
+		expect(html).toContain('<meta property="og:image" content="https://rxresu.me/opengraph/banner.jpg">');
+		expect(html).toContain('id="reactive-resume-structured-data"');
+		expect(html).toContain('"@type":["SoftwareApplication","WebApplication"]');
+		expect(html).toContain('"url":"https://rxresu.me/"');
+		expect(html).not.toContain("utm_source");
+
+		const dashboardResponse = await handleWebApp(new Request("https://example.com/dashboard"));
+		expect(await dashboardResponse.text()).not.toContain('rel="canonical"');
+	});
+
+	describe("the ATS checker page", () => {
+		const shell = `<html><head><title>Reactive Resume — A free and open-source resume builder</title><meta name="description" content="Marketing copy."></head><body></body></html>`;
+
+		it("serves an indexable shell rather than a 404", async () => {
+			vi.mocked(fs.readFile).mockResolvedValue(shell);
+
+			const response = await handleWebApp(new Request("https://example.com/ats-checker"));
+
+			expect(response.status).toBe(200);
+			expect(response.headers.get("Content-Type")).toBe("text/html; charset=UTF-8");
+			expect(response.headers.get("X-Robots-Tag")).toBeNull();
+		});
+
+		it("replaces the shell metadata with the checker's own", async () => {
+			vi.mocked(fs.readFile).mockResolvedValue(shell);
+
+			const html = await (await handleWebApp(new Request("https://example.com/ats-checker"))).text();
+
+			expect(html).toContain("<title>ATS Checker - Reactive Resume</title>");
+			expect(html).toContain('<link rel="canonical" href="https://rxresu.me/ats-checker">');
+			expect(html).toContain('<meta property="og:url" content="https://rxresu.me/ats-checker">');
+			expect(html).toContain('<meta property="og:image" content="https://rxresu.me/opengraph/ats-checker.png">');
+			expect(html).toContain('id="ats-checker-structured-data"');
+			expect(html).not.toContain("Marketing copy.");
+		});
+
+		it("answers HEAD without a body", async () => {
+			const response = await handleWebApp(new Request("https://example.com/ats-checker", { method: "HEAD" }));
+
+			expect(response.status).toBe(200);
+			expect(await response.text()).toBe("");
+		});
+
+		it("does not treat the checker path as a public resume owner", async () => {
+			const response = await handleWebApp(new Request("https://example.com/ats-checker/anything"));
+
+			expect(response.status).toBe(404);
+			expect(mocks.getPublicResumeSocialMeta).not.toHaveBeenCalled();
+		});
+	});
+
+	describe("public resume social cards", () => {
+		const shell = `<html><head><title>Reactive Resume — A free and open-source resume builder</title><meta name="description" content="Marketing copy."></head><body></body></html>`;
+
+		it("injects resume-specific social metadata and replaces the shell title", async () => {
+			vi.mocked(fs.readFile).mockResolvedValue(shell);
+			mocks.getPublicResumeSocialMeta.mockResolvedValue({
+				name: "Jane Doe",
+				title: "Jane Doe — Staff Engineer",
+				description: "Builds resilient distributed systems.",
+				template: "azurill",
+			});
+
+			const html = await (await handleWebApp(new Request("https://example.com/jane/resume"))).text();
+
+			expect(mocks.getPublicResumeSocialMeta).toHaveBeenCalledWith({ username: "jane", slug: "resume" });
+			expect(html).toContain("<title>Jane Doe - Reactive Resume</title>");
+			expect(html).toContain('<meta name="description" content="Builds resilient distributed systems.">');
+			expect(html).not.toContain("Marketing copy.");
+			expect(html).toContain('<link rel="canonical" href="https://rxresu.me/jane/resume">');
+			expect(html).toContain('<meta property="og:type" content="profile">');
+			expect(html).toContain('<meta property="og:title" content="Jane Doe — Staff Engineer">');
+			expect(html).toContain('<meta property="og:image" content="https://rxresu.me/templates/jpg/azurill.jpg">');
+			expect(html).toContain('<meta name="twitter:card" content="summary_large_image">');
+			expect(html).toContain('<meta name="twitter:image" content="https://rxresu.me/templates/jpg/azurill.jpg">');
+		});
+
+		it("escapes user-authored values so resume content cannot break out of the attribute", async () => {
+			vi.mocked(fs.readFile).mockResolvedValue(shell);
+			mocks.getPublicResumeSocialMeta.mockResolvedValue({
+				name: 'Jane" onload="alert(1)',
+				title: "<script>alert(1)</script>",
+				description: 'Ends with " and & ampersand',
+				template: "azurill",
+			});
+
+			const html = await (await handleWebApp(new Request("https://example.com/jane/resume"))).text();
+
+			expect(html).not.toContain("<script>alert(1)</script>");
+			expect(html).not.toContain('onload="alert(1)');
+			expect(html).toContain('<meta property="og:title" content="&lt;script&gt;alert(1)&lt;/script&gt;">');
+			expect(html).toContain('content="Ends with &quot; and &amp; ampersand"');
+		});
+
+		it("serves the plain shell when the resume is not publicly shareable", async () => {
+			vi.mocked(fs.readFile).mockResolvedValue(shell);
+
+			const html = await (await handleWebApp(new Request("https://example.com/jane/private"))).text();
+
+			expect(html).toBe(shell);
+		});
+
+		it("serves the plain shell when the lookup fails", async () => {
+			vi.mocked(fs.readFile).mockResolvedValue(shell);
+			mocks.getPublicResumeSocialMeta.mockRejectedValue(new Error("database unavailable"));
+
+			const response = await handleWebApp(new Request("https://example.com/jane/resume"));
+
+			expect(response.status).toBe(200);
+			await expect(response.text()).resolves.toBe(shell);
+		});
+	});
+
+	it("caches versioned homepage media immutably", async () => {
+		const headers = new Headers();
+
+		await staticOptions?.onFound?.("", {
+			req: { path: "/videos/timelapse-v1.mp4" },
+			header: (name, value) => headers.set(name, value),
+		});
+
+		expect(headers.get("Cache-Control")).toBe("public, max-age=31536000, immutable");
+
+		const unversionedHeaders = new Headers();
+		await staticOptions?.onFound?.("", {
+			req: { path: "/videos/timelapse.mp4" },
+			header: (name, value) => unversionedHeaders.set(name, value),
+		});
+
+		expect(unversionedHeaders.get("Cache-Control")).toBeNull();
+	});
+
+	it.each(["/", "/alice/resume"])("sets framing and report-only CSP security headers on %s", async (pathname) => {
 		const response = await handleWebApp(new Request(`https://example.com${pathname}`));

 		expect(response.status).toBe(200);
-		expect(response.headers.get("Content-Type")).toBe("text/html; charset=UTF-8");
-		expect(response.headers.get("X-Robots-Tag")).toBe("noindex, follow");
-		expect(await response.text()).toBe("<html>app</html>");
+		expect(response.headers.get("X-Frame-Options")).toBe("DENY");
+		expect(response.headers.get("X-Content-Type-Options")).toBe("nosniff");
+		expect(response.headers.get("Content-Security-Policy-Report-Only")).toContain("frame-ancestors 'none'");
 	});

+	it.each(["/auth/login", "/dashboard", "/builder/resume-1", "/agent", "/templates", "/templates/azurill.pdf"])(
+		"serves noindex shell for known app prefix %s",
+		async (pathname) => {
+			const response = await handleWebApp(new Request(`https://example.com${pathname}`));
+
+			expect(response.status).toBe(200);
+			expect(response.headers.get("Content-Type")).toBe("text/html; charset=UTF-8");
+			expect(response.headers.get("X-Robots-Tag")).toBe("noindex, follow");
+			expect(await response.text()).toBe("<html>app</html>");
+		},
+	);
+
 	it("serves noindex shell for public resume shaped routes", async () => {
 		const response = await handleWebApp(new Request("https://example.com/alice/resume"));

@@ -66,19 +250,18 @@ describe("web app fallback classification", () => {
 		expect(fs.readFile).not.toHaveBeenCalled();
 	});

-	it.each([
-		"/api/foo",
-		"/mcp/foo",
-		"/uploads/foo",
-	])("does not treat reserved two-segment path %s as a public resume", async (pathname) => {
-		const response = await handleWebApp(new Request(`https://example.com${pathname}`));
+	it.each(["/api/foo", "/mcp/foo", "/uploads/foo"])(
+		"does not treat reserved two-segment path %s as a public resume",
+		async (pathname) => {
+			const response = await handleWebApp(new Request(`https://example.com${pathname}`));

-		expect(response.status).toBe(404);
-		expect(response.headers.get("Content-Type")).toBe("text/plain; charset=UTF-8");
-		expect(response.headers.get("X-Robots-Tag")).toBe("noindex, nofollow");
-		expect(await response.text()).toBe("Not Found");
-		expect(fs.readFile).not.toHaveBeenCalled();
-	});
+			expect(response.status).toBe(404);
+			expect(response.headers.get("Content-Type")).toBe("text/plain; charset=UTF-8");
+			expect(response.headers.get("X-Robots-Tag")).toBe("noindex, nofollow");
+			expect(await response.text()).toBe("Not Found");
+			expect(fs.readFile).not.toHaveBeenCalled();
+		},
+	);

 	it("returns plain 404 for missing asset-looking paths", async () => {
 		const response = await handleWebApp(new Request("https://example.com/assets/missing.css"));
@@ -90,8 +273,10 @@ describe("web app fallback classification", () => {
 	});

 	it("mirrors fallback status and headers for HEAD without a body", async () => {
-		const knownResponse = handleWebAppHead(new Request("https://example.com/dashboard"));
-		const unknownResponse = handleWebAppHead(new Request("https://example.com/unknown/extra/path"));
+		const knownResponse = await handleWebApp(new Request("https://example.com/dashboard", { method: "HEAD" }));
+		const unknownResponse = await handleWebApp(
+			new Request("https://example.com/unknown/extra/path", { method: "HEAD" }),
+		);

 		expect(knownResponse.status).toBe(200);
 		expect(knownResponse.headers.get("Content-Type")).toBe("text/html; charset=UTF-8");
@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { serveStatic } from "@hono/node-server/serve-static";
+import { env } from "@reactive-resume/env/server";

 function resolveWebDistPath() {
 	const candidates = [
@@ -19,6 +20,13 @@ function resolveWebDistPath() {
 const staticRoot = resolveWebDistPath();
 const indexHtmlPath = `${staticRoot}/index.html`;
 const noindexShellPrefixes = ["/auth", "/dashboard", "/builder", "/agent", "/templates"];
+/**
+ * Marketing pages the SPA owns that search engines should index.
+ *
+ * Without an entry here the fallback below returns 404 for the path in production — the dev Vite
+ * server serves the shell for anything, so this failure only ever shows up once deployed.
+ */
+const indexableAppPaths = new Set(["/ats-checker"]);
 const reservedPublicResumeSegments = new Set([
 	"api",
 	"mcp",
@@ -29,10 +37,9 @@ const reservedPublicResumeSegments = new Set([
 	"builder",
 	"agent",
 	"templates",
+	"ats-checker",
 ]);

-export const serveWebDistStatic = serveStatic({ root: staticRoot });
-
 function isAssetPath(pathname: string): boolean {
 	return pathname.split("/").pop()?.includes(".") ?? false;
 }
@@ -52,12 +59,215 @@ function isPublicResumePath(pathname: string): boolean {
 	return segments.length === 2 && firstSegment !== undefined && !reservedPublicResumeSegments.has(firstSegment);
 }

+const BASE_SECURITY_HEADERS = {
+	"X-Frame-Options": "DENY",
+	"X-Content-Type-Options": "nosniff",
+	"Referrer-Policy": "strict-origin-when-cross-origin",
+	"Content-Security-Policy-Report-Only":
+		"default-src 'self'; img-src 'self' data: blob:; font-src 'self' data:; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'; connect-src 'self'; frame-ancestors 'none'; base-uri 'self'; object-src 'none'",
+};
+
+const ROOT_TITLE = "Reactive Resume — A free and open-source resume builder";
+// Keep under ~120 characters so Google's mobile SERP snippet is not truncated at 3 lines.
+const ROOT_DESCRIPTION =
+	"Free, open-source resume builder. Create, update, and share a professional resume in minutes — no ads, no paywall.";
+const ROOT_POSTER_PATH = "/videos/timelapse-v1.webp";
+const ROOT_FAQ_ITEMS = [
+	{
+		question: "Is Reactive Resume really free?",
+		answer:
+			"Yes! Reactive Resume is completely free to use, with no hidden costs, premium tiers, or subscription fees. It's open-source and will always remain free.",
+	},
+	{
+		question: "How is my data protected?",
+		answer:
+			"Your data is stored securely and is never shared with third parties. You can also self-host Reactive Resume on your own servers for complete control over your data.",
+	},
+	{
+		question: "Can I export my resume to PDF?",
+		answer:
+			"Absolutely! You can export your resume to PDF with a single click. The exported PDF maintains all your formatting and styling perfectly.",
+	},
+	{
+		question: "Is Reactive Resume available in multiple languages?",
+		answer:
+			"Yes, Reactive Resume is available in multiple languages. You can choose your preferred language in the settings page, or using the language switcher in the top right corner. If you don't see your language, or you would like to improve the existing translations, you can contribute to the translations on Crowdin.",
+	},
+	{
+		question: "What makes Reactive Resume different from other resume builders?",
+		answer:
+			"Reactive Resume is open-source, privacy-focused, and completely free. Unlike other resume builders, it doesn't show ads, track your data, or limit your features behind a paywall.",
+	},
+	{
+		question: "How do I share my resume?",
+		answer:
+			"You can share your resume via a unique public URL, protect it with a password, or download it as a PDF to share directly. The choice is yours!",
+	},
+] as const;
+
+function createRootSeoMarkup(canonicalUrl: string) {
+	const origin = new URL(canonicalUrl).origin;
+	const imageUrl = `${origin}/opengraph/banner.jpg`;
+	const structuredData = {
+		"@context": "https://schema.org",
+		"@graph": [
+			{
+				"@type": "WebSite",
+				name: "Reactive Resume",
+				url: canonicalUrl,
+			},
+			{
+				"@type": ["SoftwareApplication", "WebApplication"],
+				name: "Reactive Resume",
+				url: canonicalUrl,
+				description: ROOT_DESCRIPTION,
+				applicationCategory: "BusinessApplication",
+				operatingSystem: "Web",
+				isAccessibleForFree: true,
+				offers: {
+					"@type": "Offer",
+					price: "0",
+					priceCurrency: "USD",
+				},
+				codeRepository: "https://github.com/amruthpillai/reactive-resume",
+			},
+			{
+				"@type": "Project",
+				name: "Reactive Resume",
+				url: canonicalUrl,
+				sameAs: ["https://github.com/amruthpillai/reactive-resume"],
+			},
+			{
+				"@type": "FAQPage",
+				mainEntity: ROOT_FAQ_ITEMS.map((item) => ({
+					"@type": "Question",
+					name: item.question,
+					acceptedAnswer: {
+						"@type": "Answer",
+						text: item.answer,
+					},
+				})),
+			},
+		],
+	};
+
+	return `
+		<link rel="canonical" href="${canonicalUrl}">
+		<link rel="preload" href="${ROOT_POSTER_PATH}" as="image" fetchpriority="high">
+		<meta property="og:type" content="website">
+		<meta property="og:site_name" content="Reactive Resume">
+		<meta property="og:title" content="${ROOT_TITLE}">
+		<meta property="og:description" content="${ROOT_DESCRIPTION}">
+		<meta property="og:url" content="${canonicalUrl}">
+		<meta property="og:image" content="${imageUrl}">
+		<meta name="twitter:card" content="summary_large_image">
+		<meta name="twitter:title" content="${ROOT_TITLE}">
+		<meta name="twitter:description" content="${ROOT_DESCRIPTION}">
+		<meta name="twitter:image" content="${imageUrl}">
+		<script id="reactive-resume-structured-data" type="application/ld+json">${JSON.stringify(structuredData)}</script>
+	`;
+}
+
+const ATS_CHECKER_TITLE = "ATS Checker - Reactive Resume";
+// Kept under ~120 characters so Google's mobile SERP snippet is not truncated at 3 lines.
+const ATS_CHECKER_DESCRIPTION =
+	"Check whether software can read your resume PDF. Runs in your browser, so your file is never uploaded.";
+
+function createAtsCheckerSeoMarkup(origin: string) {
+	const canonicalUrl = `${origin}/ats-checker`;
+	const imageUrl = `${origin}/opengraph/ats-checker.png`;
+	const structuredData = {
+		"@context": "https://schema.org",
+		"@type": "WebApplication",
+		name: "ATS Checker",
+		url: canonicalUrl,
+		description: ATS_CHECKER_DESCRIPTION,
+		applicationCategory: "BusinessApplication",
+		operatingSystem: "Web",
+		isAccessibleForFree: true,
+		offers: { "@type": "Offer", price: "0", priceCurrency: "USD" },
+		isPartOf: { "@type": "WebSite", name: "Reactive Resume", url: `${origin}/` },
+	};
+
+	return `
+		<link rel="canonical" href="${canonicalUrl}">
+		<meta property="og:type" content="website">
+		<meta property="og:site_name" content="Reactive Resume">
+		<meta property="og:title" content="${ATS_CHECKER_TITLE}">
+		<meta property="og:description" content="${ATS_CHECKER_DESCRIPTION}">
+		<meta property="og:url" content="${canonicalUrl}">
+		<meta property="og:image" content="${imageUrl}">
+		<meta name="twitter:card" content="summary_large_image">
+		<meta name="twitter:title" content="${ATS_CHECKER_TITLE}">
+		<meta name="twitter:description" content="${ATS_CHECKER_DESCRIPTION}">
+		<meta name="twitter:image" content="${imageUrl}">
+		<script id="ats-checker-structured-data" type="application/ld+json">${JSON.stringify(structuredData)}</script>
+	`;
+}
+
+// Resume names, headlines, and summaries are user-authored, so they must never reach the served
+// HTML unescaped.
+const escapeAttribute = (value: string) =>
+	value
+		.replaceAll("&", "&amp;")
+		.replaceAll("<", "&lt;")
+		.replaceAll(">", "&gt;")
+		.replaceAll('"', "&quot;")
+		.replaceAll("'", "&#39;");
+
+async function createPublicResumeSeoMarkup(pathname: string, origin: string) {
+	const [username, slug] = getPathSegments(pathname);
+	if (!username || !slug) return null;
+
+	// A card render must never take down the page: any lookup failure falls back to the plain shell.
+	const meta = await import("@reactive-resume/api/features/resume/social-meta")
+		.then((module) => module.getPublicResumeSocialMeta({ username, slug }))
+		.catch(() => null);
+	if (!meta) return null;
+
+	const canonicalUrl = `${origin}/${username}/${slug}`;
+	const imageUrl = `${origin}/templates/jpg/${meta.template}.jpg`;
+	const pageTitle = escapeAttribute(`${meta.name} - Reactive Resume`);
+	const title = escapeAttribute(meta.title);
+	const description = escapeAttribute(meta.description);
+
+	return {
+		pageTitle,
+		description,
+		markup: `
+		<link rel="canonical" href="${canonicalUrl}">
+		<meta property="og:type" content="profile">
+		<meta property="og:site_name" content="Reactive Resume">
+		<meta property="og:title" content="${title}">
+		<meta property="og:description" content="${description}">
+		<meta property="og:url" content="${canonicalUrl}">
+		<meta property="og:image" content="${imageUrl}">
+		<meta name="twitter:card" content="summary_large_image">
+		<meta name="twitter:title" content="${title}">
+		<meta name="twitter:description" content="${description}">
+		<meta name="twitter:image" content="${imageUrl}">
+	`,
+	};
+}
+
+export const serveWebDistStatic = serveStatic({
+	root: staticRoot,
+	onFound: (_path, context) => {
+		if (/^\/videos\/.*-v\d+\.(?:mp4|webp)$/.test(context.req.path)) {
+			context.header("Cache-Control", "public, max-age=31536000, immutable");
+		}
+	},
+});
+
 function getFallbackResponseHeaders(pathname: string) {
-	if (pathname === "/") return { "Content-Type": "text/html; charset=UTF-8" };
+	if (pathname === "/" || indexableAppPaths.has(pathname)) {
+		return { "Content-Type": "text/html; charset=UTF-8", ...BASE_SECURITY_HEADERS };
+	}
 	if (isNoindexShellPath(pathname) || isPublicResumePath(pathname)) {
 		return {
 			"Content-Type": "text/html; charset=UTF-8",
 			"X-Robots-Tag": "noindex, follow",
+			...BASE_SECURITY_HEADERS,
 		};
 	}

@@ -74,23 +284,48 @@ function notFoundResponse(options: { head?: boolean; noindex?: boolean } = {}) {
 	});
 }

+// ponytail: GET and HEAD share the same routing logic; method determines body presence
 export async function handleWebApp(request: Request) {
+	const isHead = request.method === "HEAD";
 	const pathname = new URL(request.url).pathname;
-	if (!isNoindexShellPath(pathname) && isAssetPath(pathname)) return new Response("Not Found", { status: 404 });
+
+	if (!isNoindexShellPath(pathname) && isAssetPath(pathname)) {
+		return new Response(isHead ? null : "Not Found", { status: 404 });
+	}

 	const headers = getFallbackResponseHeaders(pathname);
-	if (!headers) return notFoundResponse({ noindex: true });
+	if (!headers) return notFoundResponse({ head: isHead, noindex: true });
+
+	if (isHead) return new Response(null, { status: 200, headers });

 	const html = await fs.readFile(indexHtmlPath, "utf-8");
+	const canonicalUrl = new URL("/", env.APP_URL).toString();
+
+	if (pathname === "/") {
+		return new Response(html.replace("</head>", `${createRootSeoMarkup(canonicalUrl)}</head>`), { headers });
+	}
+
+	if (pathname === "/ats-checker") {
+		const origin = new URL(env.APP_URL).origin;
+		const withTitle = html
+			.replace(/<title>[^<]*<\/title>/, `<title>${ATS_CHECKER_TITLE}</title>`)
+			.replace(/<meta\s+name="description"[^>]*>/, `<meta name="description" content="${ATS_CHECKER_DESCRIPTION}">`);
+
+		return new Response(withTitle.replace("</head>", `${createAtsCheckerSeoMarkup(origin)}</head>`), { headers });
+	}
+
+	if (isPublicResumePath(pathname)) {
+		const resumeSeo = await createPublicResumeSeoMarkup(pathname, new URL(env.APP_URL).origin);
+		if (resumeSeo) {
+			// The shell's generic title/description are replaced so shares and previews show the resume,
+			// not the marketing copy baked into index.html.
+			const withTitle = html
+				.replace(/<title>[^<]*<\/title>/, `<title>${resumeSeo.pageTitle}</title>`)
+				.replace(/<meta\s+name="description"[^>]*>/, `<meta name="description" content="${resumeSeo.description}">`);
+
+			return new Response(withTitle.replace("</head>", `${resumeSeo.markup}</head>`), { headers });
+		}
+	}
+
 	return new Response(html, { headers });
 }
-
-export function handleWebAppHead(request: Request) {
-	const pathname = new URL(request.url).pathname;
-	if (!isNoindexShellPath(pathname) && isAssetPath(pathname)) return new Response(null, { status: 404 });
-
-	const headers = getFallbackResponseHeaders(pathname);
-	if (!headers) return notFoundResponse({ head: true, noindex: true });
-
-	return new Response(null, { status: 200, headers });
-}
@@ -42,6 +42,9 @@ export default defineConfig({
 	shims: true,
 	dts: false,
 	define: { __APP_VERSION__: JSON.stringify(rootPackageJson.version ?? "0.0.0") },
+	// The flagged dynamic imports are deliberate: they defer evaluation of env-dependent
+	// modules so tests can run without env vars, not to split chunks.
+	suppressWarnings: [/dynamic import will not move module into another chunk/],
 	outExtensions: () => ({ js: ".mjs" }),
 	deps: {
 		alwaysBundle: [/^@reactive-resume\//],
@@ -1,4 +1,9 @@
 {
 	"extends": ["//"],
-	"tags": ["app:server", "runtime:server", "role:adapter"]
+	"tags": ["app:server", "runtime:server", "role:adapter"],
+	"tasks": {
+		"test:ci": {
+			"cache": false
+		}
+	}
 }
@@ -1,6 +1,6 @@
 import { fileURLToPath } from "node:url";
 // @boundaries-ignore root shared Vitest config
-import { createVitestProjectConfig } from "../../vitest.shared";
+import { createVitestProjectConfig } from "../../vitest.shared.mts";

 export default createVitestProjectConfig({
 	name: "server",
@@ -9,17 +9,54 @@
 		<meta name="apple-mobile-web-app-capable" content="yes" />
 		<meta name="apple-mobile-web-app-title" content="Reactive Resume" />
 		<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
-		<meta name="description" content="Reactive Resume is a free and open-source resume builder that simplifies the process of creating, updating, and sharing your resume.">
+		<!-- Keep under ~120 characters so Google's mobile SERP snippet is not truncated at 3 lines. -->
+		<meta name="description" content="Free, open-source resume builder. Create, update, and share a professional resume in minutes — no ads, no paywall.">

 		<link rel="icon" href="/favicon.ico" type="image/x-icon" sizes="128x128" />
 		<link rel="icon" href="/favicon.svg" type="image/svg+xml" sizes="256x256 any" />
 		<link rel="apple-touch-icon" href="/apple-touch-icon-180x180.png" type="image/png" sizes="180x180 any" />
 		<link rel="manifest" href="/manifest.webmanifest" crossorigin="use-credentials" />

-		<title>Reactive Resume</title>
+		<title>Reactive Resume — A free and open-source resume builder</title>
 	</head>
 	<body>
+		<!-- Keep #app empty: main.tsx only mounts React when rootElement has no children. -->
 		<div id="app"></div>
-		<script type="module" src="/src/main.tsx"></script>
+		<!-- Branded first paint; hidden once React populates #app (higher-specificity rule below). -->
+		<div id="initial-loader">
+			<img src="/icon/dark.svg" width="48" height="48" alt="Reactive Resume" />
+			<div class="initial-loader__spinner"></div>
+			<span class="initial-loader__sr-only">Loading</span>
+		</div>
+		<style>
+			@keyframes app-spin { to { transform: rotate(360deg) } }
+			#initial-loader {
+				position: fixed;
+				inset: 0;
+				display: flex;
+				flex-direction: column;
+				align-items: center;
+				justify-content: center;
+				gap: 24px;
+				background: #09090b;
+			}
+			#app:not(:empty) ~ #initial-loader { display: none; }
+			.initial-loader__spinner {
+				width: 24px;
+				height: 24px;
+				border: 2px solid rgba(250, 250, 250, 0.2);
+				border-top-color: #fafafa;
+				border-radius: 9999px;
+				animation: app-spin 0.7s linear infinite;
+			}
+			.initial-loader__sr-only {
+				position: absolute;
+				width: 1px;
+				height: 1px;
+				overflow: hidden;
+				clip: rect(0 0 0 0);
+			}
+		</style>
+		<script type="module" data-cfasync="false" src="/src/main.tsx"></script>
 	</body>
 </html>
--- a/Show More
+++ b/Show More