feat(deploy): deploy Vercel as frontend and backend services

Vercel now deploys Reactive Resume as two services in one project:
`frontend` serves the static Vite build from apps/web/dist, and
`backend` runs the Hono server Function from apps/server. Top-level
rewrites send server-owned paths (/api, /uploads, /mcp, /.well-known,
robots.txt, sitemap.xml, llms.txt, schema.json, index.html) and every
path without a file extension to `backend`, so HTML shells keep their
injected SEO metadata. Paths with a file extension go to `frontend`.

The service builder needs a few accommodations:

- apps/server/vercel.mjs replaces api/index.mjs as the entrypoint,
  because a service entrypoint must exist before the build runs.
- `outputDirectory: "."` stops the builder from using the Docker
  entrypoint in dist/ as the Function handler.
- The builder loads external CommonJS dependencies through pnpm links
  that it leaves out of the Function. ioredis and react-reconciler are
  now bundled with their dependencies, and bcrypt is replaced with
  bcryptjs, which reads and writes the same $2b$ hashes.

The Vercel compatibility workflow now builds with the services
framework and loads a copy of the backend Function outside the
checkout, so a dependency missing from the Function fails CI. The stale
PDFKit trace checks are removed.

Existing Vercel installations must set Framework Preset to Services
before redeploying; the self-hosting guide documents this.

.design-sync/NOTES.md

@@ -1,55 +0,0 @@
-# design-sync notes — @reactive-resume/ui
-
-Syncs to Claude Design project **Reactive Resume** (`3c0f6556-050a-41e5-9886-c3f1ea950517`).
-
-## Repo shape / build
-
-- `@reactive-resume/ui` is **source-consumed** (pnpm workspace, no `dist`, exports point at `src/components/*.tsx`). Runs in the converter's **synth-entry mode** (no `--entry`).
-- `buildCmd` = `node .design-sync/build-css.mjs`. That one script does three things, all required before every converter run:
-  1. Creates the workspace **self-symlink** `packages/ui/node_modules/@reactive-resume/ui -> ../../../ui` (pnpm doesn't self-install it; the converter resolves the DS as `node_modules/<pkg>` and esbuild needs it for `@reactive-resume/ui/components/*` self-imports).
-  2. Emits real **`.d.ts`** to `packages/ui/dist/types` via `tsc -p packages/ui/tsconfig.emit.json`. Without this, synth-entry mode gives weak `{[key]: unknown}` prop contracts; with it the converter's `findTypesRoot` picks up `dist/types` and every component gets real props (variant/size unions, inherited Base UI props).
-  3. Compiles Tailwind v4 `globals.css` → self-contained `packages/ui/.ds-compiled.css` (`cfg.cssEntry`): inlines the IBM Plex Sans latin variable woff2 as a data-URI and strips all other `@font-face` (extra scripts + the Phosphor icon web font, which previews don't use — components render Phosphor as inline React SVGs). This is why previews are fully styled with tokens + brand font and there are zero dangling font URLs.
-- CSS entry scans `.design-sync/tw-entry.css` which `@import`s globals.css and adds `@source "./previews/*.tsx"` so utility classes used in authored previews are compiled. **Preview layout wrappers use inline styles** anyway (so subagents needn't recompile the shared CSS); only component-level utility classes need the recompile.
-
-## Card scope
-
-- The package exports **202 symbols** (39 primary components + 163 compound sub-parts). User chose **~40 primary cards**: `cfg.componentSrcMap` nulls the 163 sub-parts. All 202 stay importable from `window.RRUI` (the bundle exports everything regardless of the card list), so previews compose sub-parts (`RRUI.DialogContent`, etc.) freely.
-- Multi-primary files represented by one card: `combobox.tsx`→ComboboxRoot, `form.tsx`→FormItem, `resizable.tsx`→ResizableGroup, `sonner.tsx`→Toaster.
-
-## Preview authoring conventions (calibrated on Button / Alert / Dialog)
-
-- Import naturally: `import { Button } from "@reactive-resume/ui/components/button"` — converter rule 2 redirects any exported-component module to `window.RRUI`, and sub-parts resolve too.
-- Icons: `@phosphor-icons/react` with the `*Icon` suffix (e.g. `PlusIcon`, `TrashIcon`, `WarningIcon`). Bundles into the preview.
-- Base UI compose pattern: `render={<Button variant="outline" />}` on `*.Trigger` / `*.Close` etc.
-- Layout wrappers: inline `style={{ display:"flex", gap, padding }}` — not Tailwind (keeps fan-out from needing CSS recompiles).
-- **Overlays** (Dialog, and expect the same for AlertDialog/Sheet/Popover/HoverCard/DropdownMenu/ContextMenu/Tooltip/Command-dialog): render open via `defaultOpen`, and set `cfg.overrides.<Name> = {cardMode:"single", primaryStory:"<export>", viewport:"WxH"}`. Use viewport width ≥ 640 so `sm:` breakpoint styles (e.g. horizontal dialog footer) engage — Dialog uses `760x440`.
-- Realistic resume-app content (resumes, sections, publish/export/share), never foo/bar.
-
-## Component composition notes (from the authoring wave)
-
-- **Real `.d.ts` contracts require the barrel** (see build step 2 + `publishConfig.types`). Base UI prop names differ from Radix/native: Switch `defaultChecked`+`size`; Toggle `defaultPressed`+`variant`+`size`; Slider `defaultValue` array (`[n]` single / `[a,b]` range). Use uncontrolled `default*` props in previews to avoid controlled-without-onChange warnings.
-- **BrandIcon renders the app's own logo/icon** (`variant="logo"|"icon"`), NOT a social/brand-slug icon. It `<img src>`s `/logo/*.svg` + `/icon/*.svg`, which the preview server (serving `ds-bundle/`) 404s. The BrandIcon preview inlines the real `apps/web/public/{logo,icon}/light.svg` as base64 `src` overrides (component spreads `{...props}` after its own `src`, so the override wins).
-- **Overlays** handled by the orchestrator with `cfg.overrides` (cardMode single + primaryStory Open + viewport): Dialog, AlertDialog, Sheet, Popover, Tooltip, HoverCard, DropdownMenu, ContextMenu, ComboboxRoot. Command renders **inline** (cmdk, no overlay); Sidebar uses `collapsible="none"` to render inline (default offcanvas is fixed-positioned); Toaster fires a `duration:Infinity` toast on mount.
-- **Providers composed in-preview** (no cfg.provider): Tooltip→TooltipProvider, Sidebar→SidebarProvider, MessageScroller→MessageScrollerProvider (+ explicit container height — Root is `size-full min-h-0` and collapses otherwise), FormItem carries its own context.
-- **Accordion** opens statically via `defaultValue={[...itemValues]}` (the `--accordion-panel-height` warn is a non-issue — panels measure fine). **Tabs** via `defaultValue`. **ScrollArea/ResizableGroup/InputGroup** need an inline container height/width. **Separator** vertical needs an explicit height.
-- Chat/attachment components (Attachment, Bubble, Message, MessageScroller, Marker) are all used only in `apps/web/src/routes/agent/-components/agent-chat.tsx` — the canonical composition source.
-
-## Build/verify gotchas (learned the hard way)
-
-- **A full `package-build` takes ~3-4 minutes** — not a hang. `@phosphor-icons/react` is a giant barrel, so each icon-importing preview costs ~10-20s of esbuild parse, and 30+ authored previews compile serially. Always run it in a real background task (not a 120s-capped foreground shell) and wait for completion.
-- **Do NOT add a barrel `index.d.ts` + `publishConfig.types`** to get rich props for inline-param-typed components: it makes ts-morph resolve all 200+ inline Base UI param types and hangs the build for many minutes. Tried and reverted. Result: components with a named `<Name>Props` source type (Button) get real props; the rest get honest `{[key]: unknown}`.
-- **Base UI menu Labels must be inside a Group**: `DropdownMenuLabel`/`ContextMenuLabel` throw `MenuGroupContext is missing` unless wrapped in `DropdownMenuGroup`/`ContextMenuGroup`. Same likely for other `*Label`/`*GroupLabel` menu parts.
-- **`[RENDER_THIN]` (height 0px) is benign for fixed-position overlays** (Dialog, AlertDialog, Sheet): the content is `position:fixed` so it measures 0 in normal flow, but `rootEmpty:false` and the screenshot is correct. Confirmed via review sheets — not a failure.
-- **`[GRID_OVERFLOW]` wide** → `cfg.overrides.<Name> = {cardMode:"column"}` applied to: Accordion, Attachment, Bubble, FormItem, InputGroup, Marker, Message, ResizableGroup, Tabs, Textarea. Toaster (portal escape) → `{cardMode:"single", primaryStory:"Notification"}`.
-
-## Known render warns (triaged, not failures)
-
-- `[TOKENS_MISSING]`: `--active-tab-{top,left,height,width}` (Base UI tab indicator sets these at runtime), `--accordion-panel-height` (Base UI accordion runtime), `--tw` (Tailwind internal), plus app-level `--resume-preview-page-gap` / `--page-primary-color` (defined by apps/web, not this package). All expected absent from the shipped stylesheet — components set them at runtime. Do not chase.
-- `--font-heading` is referenced (DialogTitle `font-heading`) but not defined in the UI package tokens (app-level). Falls back to `--font-body` (IBM Plex). Cosmetic only.
-- Unauthored primitives render near-empty floor cards (`[RENDER_BLANK]` for empty Button/Input/etc.) — resolved once authored.
-
-## Re-sync risks
-
-- `packages/ui/dist/types`, `packages/ui/.ds-compiled.css`, `packages/ui/.ds-tw-raw.css`, and the self-symlink are all gitignored build artifacts regenerated by `buildCmd` — always run `node .design-sync/build-css.mjs` before the converter/driver.
-- The inlined IBM Plex font path in `build-css.mjs` is pinned to `@fontsource-variable/ibm-plex-sans/files/ibm-plex-sans-latin-wght-normal.woff2`; if that dep moves, the font inline breaks (previews fall back to system sans).
-- `tsconfig.emit.json` is committed; if the package adds a real build later, prefer pointing the converter at that dist and drop the emit step.

.design-sync/build-css.mjs

@@ -1,55 +0,0 @@
-#!/usr/bin/env node
-// design-sync CSS build: compile the UI package's Tailwind v4 globals.css to
-// static CSS, then make it self-contained for preview rendering by inlining the
-// IBM Plex Sans (latin) variable webfont as a data-URI and dropping the other
-// @font-face rules (extra scripts + the Phosphor icon font, which previews
-// don't use — components render Phosphor as inline React SVGs).
-//
-// Output: packages/ui/.ds-compiled.css  (cfg.cssEntry, bounded to the package)
-import { execFileSync } from "node:child_process";
-import { existsSync, readFileSync, symlinkSync, writeFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const here = dirname(fileURLToPath(import.meta.url));
-const repo = resolve(here, "..");
-
-// pnpm doesn't self-install the workspace package into its own node_modules,
-// but the design-sync converter resolves the DS as node_modules/<pkg>. Create
-// the self-symlink so PKG_DIR resolves and esbuild finds @reactive-resume/ui/*
-// self-imports. Mirrors the sibling symlinks pnpm already writes (utils, config).
-const selfLink = resolve(repo, "packages/ui/node_modules/@reactive-resume/ui");
-if (!existsSync(selfLink)) symlinkSync("../../../ui", selfLink);
-
-// Emit real .d.ts declarations (the package is source-consumed with no build).
-// The converter's findTypesRoot picks up dist/types, giving components real
-// prop contracts (variant/size unions, inherited Base UI props) instead of the
-// weak `{[key]: unknown}` synth-entry fallback.
-execFileSync(resolve(repo, "node_modules/.bin/tsc"), ["-p", "tsconfig.emit.json"], {
-	cwd: resolve(repo, "packages/ui"),
-	stdio: "inherit",
-});
-// NOTE: a barrel index.d.ts + publishConfig.types was tried to give the prop
-// extractor an entry for components with inline param types — but resolving all
-// 200+ inline Base UI param types through ts-morph's checker hangs the build
-// (many minutes). Reverted. Components with a named <Name>Props source type
-// (e.g. Button) still extract real props from dist/types; the rest fall back to
-// the honest `{[key]: unknown}` contract, with usage carried by the preview +
-// .prompt.md. See .design-sync/NOTES.md "Re-sync risks".
-const cli = resolve(repo, ".ds-sync/node_modules/.bin/tailwindcss");
-const entry = resolve(here, "tw-entry.css");
-const tmp = resolve(repo, "packages/ui/.ds-tw-raw.css");
-const out = resolve(repo, "packages/ui/.ds-compiled.css");
-const font = resolve(
-	repo,
-	"packages/ui/node_modules/@fontsource-variable/ibm-plex-sans/files/ibm-plex-sans-latin-wght-normal.woff2",
-);
-
-execFileSync(cli, ["-i", entry, "-o", tmp], { stdio: "inherit" });
-
-let css = readFileSync(tmp, "utf8");
-css = css.replace(/@font-face\s*\{[^}]*\}/g, ""); // drop all shipped @font-face
-const b64 = readFileSync(font).toString("base64");
-const face = `@font-face{font-family:"IBM Plex Sans Variable";font-style:normal;font-weight:100 700;font-display:swap;src:url(data:font/woff2;base64,${b64}) format("woff2-variations")}\n`;
-writeFileSync(out, face + css);
-console.error(`  build-css: wrote ${out} (${(Buffer.byteLength(face + css) / 1024).toFixed(0)} KB, font inlined)`);

.design-sync/config.json

@@ -1,256 +0,0 @@
-{
-	"projectId": "3c0f6556-050a-41e5-9886-c3f1ea950517",
-	"pkg": "@reactive-resume/ui",
-	"globalName": "RRUI",
-	"shape": "package",
-	"buildCmd": "node .design-sync/build-css.mjs",
-	"tsconfig": "tsconfig.json",
-	"cssEntry": ".ds-compiled.css",
-	"componentSrcMap": {
-		"AccordionContent": null,
-		"AccordionItem": null,
-		"AccordionTrigger": null,
-		"AlertAction": null,
-		"AlertDescription": null,
-		"AlertDialogAction": null,
-		"AlertDialogCancel": null,
-		"AlertDialogContent": null,
-		"AlertDialogDescription": null,
-		"AlertDialogFooter": null,
-		"AlertDialogHeader": null,
-		"AlertDialogMedia": null,
-		"AlertDialogOverlay": null,
-		"AlertDialogPortal": null,
-		"AlertDialogTitle": null,
-		"AlertDialogTrigger": null,
-		"AlertTitle": null,
-		"AttachmentAction": null,
-		"AttachmentActions": null,
-		"AttachmentContent": null,
-		"AttachmentDescription": null,
-		"AttachmentGroup": null,
-		"AttachmentMedia": null,
-		"AttachmentTitle": null,
-		"AttachmentTrigger": null,
-		"AvatarBadge": null,
-		"AvatarFallback": null,
-		"AvatarGroup": null,
-		"AvatarGroupCount": null,
-		"AvatarImage": null,
-		"BubbleContent": null,
-		"BubbleGroup": null,
-		"BubbleReactions": null,
-		"ButtonGroupSeparator": null,
-		"ButtonGroupText": null,
-		"ComboboxChip": null,
-		"ComboboxChips": null,
-		"ComboboxChipsInput": null,
-		"ComboboxClear": null,
-		"ComboboxCollection": null,
-		"ComboboxContent": null,
-		"ComboboxEmpty": null,
-		"ComboboxGroup": null,
-		"ComboboxInput": null,
-		"ComboboxItem": null,
-		"ComboboxLabel": null,
-		"ComboboxList": null,
-		"ComboboxSeparator": null,
-		"ComboboxTrigger": null,
-		"ComboboxValue": null,
-		"CommandDialog": null,
-		"CommandEmpty": null,
-		"CommandGroup": null,
-		"CommandInput": null,
-		"CommandItem": null,
-		"CommandList": null,
-		"CommandSeparator": null,
-		"CommandShortcut": null,
-		"ContextMenuCheckboxItem": null,
-		"ContextMenuContent": null,
-		"ContextMenuGroup": null,
-		"ContextMenuItem": null,
-		"ContextMenuLabel": null,
-		"ContextMenuPortal": null,
-		"ContextMenuRadioGroup": null,
-		"ContextMenuRadioItem": null,
-		"ContextMenuSeparator": null,
-		"ContextMenuShortcut": null,
-		"ContextMenuSub": null,
-		"ContextMenuSubContent": null,
-		"ContextMenuSubTrigger": null,
-		"ContextMenuTrigger": null,
-		"DialogClose": null,
-		"DialogContent": null,
-		"DialogDescription": null,
-		"DialogFooter": null,
-		"DialogHeader": null,
-		"DialogOverlay": null,
-		"DialogPortal": null,
-		"DialogTitle": null,
-		"DialogTrigger": null,
-		"DropdownMenuCheckboxItem": null,
-		"DropdownMenuContent": null,
-		"DropdownMenuGroup": null,
-		"DropdownMenuItem": null,
-		"DropdownMenuLabel": null,
-		"DropdownMenuPortal": null,
-		"DropdownMenuRadioGroup": null,
-		"DropdownMenuRadioItem": null,
-		"DropdownMenuSeparator": null,
-		"DropdownMenuShortcut": null,
-		"DropdownMenuSub": null,
-		"DropdownMenuSubContent": null,
-		"DropdownMenuSubTrigger": null,
-		"DropdownMenuTrigger": null,
-		"FormControl": null,
-		"FormDescription": null,
-		"FormLabel": null,
-		"FormMessage": null,
-		"HoverCardContent": null,
-		"HoverCardTrigger": null,
-		"InputGroupAddon": null,
-		"InputGroupButton": null,
-		"InputGroupInput": null,
-		"InputGroupText": null,
-		"InputGroupTextarea": null,
-		"KbdGroup": null,
-		"MarkerContent": null,
-		"MarkerIcon": null,
-		"MessageAvatar": null,
-		"MessageContent": null,
-		"MessageFooter": null,
-		"MessageGroup": null,
-		"MessageHeader": null,
-		"MessageScrollerButton": null,
-		"MessageScrollerContent": null,
-		"MessageScrollerItem": null,
-		"MessageScrollerProvider": null,
-		"MessageScrollerViewport": null,
-		"PopoverContent": null,
-		"PopoverDescription": null,
-		"PopoverHeader": null,
-		"PopoverTitle": null,
-		"PopoverTrigger": null,
-		"ResizablePanel": null,
-		"ResizableSeparator": null,
-		"ScrollBar": null,
-		"SheetClose": null,
-		"SheetContent": null,
-		"SheetDescription": null,
-		"SheetFooter": null,
-		"SheetHeader": null,
-		"SheetTitle": null,
-		"SheetTrigger": null,
-		"SidebarContent": null,
-		"SidebarFooter": null,
-		"SidebarGroup": null,
-		"SidebarGroupAction": null,
-		"SidebarGroupContent": null,
-		"SidebarGroupLabel": null,
-		"SidebarHeader": null,
-		"SidebarInput": null,
-		"SidebarInset": null,
-		"SidebarMenu": null,
-		"SidebarMenuAction": null,
-		"SidebarMenuBadge": null,
-		"SidebarMenuButton": null,
-		"SidebarMenuItem": null,
-		"SidebarMenuSkeleton": null,
-		"SidebarMenuSub": null,
-		"SidebarMenuSubButton": null,
-		"SidebarMenuSubItem": null,
-		"SidebarProvider": null,
-		"SidebarRail": null,
-		"SidebarSeparator": null,
-		"SidebarTrigger": null,
-		"TabsContent": null,
-		"TabsIndicator": null,
-		"TabsList": null,
-		"TabsTrigger": null,
-		"TooltipContent": null,
-		"TooltipProvider": null,
-		"TooltipTrigger": null
-	},
-	"overrides": {
-		"Dialog": {
-			"cardMode": "single",
-			"primaryStory": "Open",
-			"viewport": "760x440"
-		},
-		"AlertDialog": {
-			"cardMode": "single",
-			"primaryStory": "Open",
-			"viewport": "640x460"
-		},
-		"Sheet": {
-			"cardMode": "single",
-			"primaryStory": "Open",
-			"viewport": "760x480"
-		},
-		"Popover": {
-			"cardMode": "single",
-			"primaryStory": "Open",
-			"viewport": "420x340"
-		},
-		"Tooltip": {
-			"cardMode": "single",
-			"primaryStory": "Open",
-			"viewport": "360x260"
-		},
-		"HoverCard": {
-			"cardMode": "single",
-			"primaryStory": "Open",
-			"viewport": "440x320"
-		},
-		"DropdownMenu": {
-			"cardMode": "single",
-			"primaryStory": "Open",
-			"viewport": "440x360"
-		},
-		"ContextMenu": {
-			"cardMode": "single",
-			"primaryStory": "Open",
-			"viewport": "440x340"
-		},
-		"ComboboxRoot": {
-			"cardMode": "single",
-			"primaryStory": "Open",
-			"viewport": "420x360"
-		},
-		"Accordion": {
-			"cardMode": "column"
-		},
-		"Attachment": {
-			"cardMode": "column"
-		},
-		"Bubble": {
-			"cardMode": "column"
-		},
-		"FormItem": {
-			"cardMode": "column"
-		},
-		"InputGroup": {
-			"cardMode": "column"
-		},
-		"Marker": {
-			"cardMode": "column"
-		},
-		"Message": {
-			"cardMode": "column"
-		},
-		"ResizableGroup": {
-			"cardMode": "column"
-		},
-		"Tabs": {
-			"cardMode": "column"
-		},
-		"Textarea": {
-			"cardMode": "column"
-		},
-		"Toaster": {
-			"cardMode": "single",
-			"primaryStory": "Notification"
-		}
-	},
-	"readmeHeader": ".design-sync/conventions.md"
-}

.design-sync/conventions.md

@@ -1,60 +0,0 @@
-# Reactive Resume UI — how to build with it
-
-This is `@reactive-resume/ui`: a shadcn-style React component library built on **Base UI**
-primitives and **Tailwind CSS v4**. Every component is real upstream code, bundled to the
-`window.RRUI` global; the 39 cards are the primary components, but all their compound
-sub-parts (e.g. `DialogContent`, `AccordionItem`, `SidebarMenuButton`) are also on `RRUI`.
-
-## Setup & wrapping
-
-- **No global provider is required.** All design tokens live on `:root` in `styles.css` (loaded
-  for you), so components are styled out of the box. For dark mode, add `class="dark"` to a
-  wrapping element — the same tokens flip to their dark values.
-- **A few components need their own provider — wrap only where you use them:**
-  - `Tooltip*` → wrap in `RRUI.TooltipProvider`.
-  - `Sidebar*` → wrap in `RRUI.SidebarProvider`.
-  - `MessageScroller*` → wrap in `RRUI.MessageScrollerProvider` and give it a bounded height.
-  - Form fields → `RRUI.FormItem` provides the field context for `FormLabel`/`FormControl`/`FormMessage`.
-- **Compose compound components** from their parts, e.g. `Dialog` = `DialogTrigger` + `DialogContent`
-  (+ `DialogHeader`/`DialogTitle`/`DialogDescription`/`DialogFooter`). Overlay parts (Dialog, Sheet,
-  Popover, DropdownMenu, ContextMenu, Tooltip, HoverCard) render into a portal. Menu labels must sit
-  inside a `*Group` (`DropdownMenuGroup`, `ContextMenuGroup`).
-- Icons come from `@phosphor-icons/react` (the `*Icon` suffix, e.g. `PlusIcon`).
-
-## Styling idiom — Tailwind utilities on semantic tokens
-
-Components style themselves; for **your own** layout and surfaces, use Tailwind utility classes
-bound to the design system's **semantic color tokens** (never raw hex — these adapt to light/dark):
-
-| Purpose | Utilities |
-|---|---|
-| Surfaces | `bg-background`, `bg-card`, `bg-popover`, `bg-muted`, `bg-sidebar` |
-| Brand / actions | `bg-primary` + `text-primary-foreground`, `bg-secondary` + `text-secondary-foreground` |
-| Accents / hover | `bg-accent` + `text-accent-foreground`, `hover:bg-muted` |
-| Danger | `bg-destructive`, `text-destructive` |
-| Text | `text-foreground` (primary), `text-muted-foreground` (secondary) |
-| Borders / focus | `border`, `border-input`, `ring-ring`, `outline-ring` |
-| Radius | `rounded-md`, `rounded-lg` (driven by `--radius`) |
-
-Each token is also a CSS variable (`var(--primary)`, `var(--muted-foreground)`, `var(--border)`,
-`var(--radius)`, `--font-body` = IBM Plex Sans) if you need it in inline styles.
-
-## Where the truth lives
-
-- **Styling:** `styles.css` and its `@import` closure (`_ds_bundle.css` = component styles; the
-  token definitions on `:root`/`.dark`). Read these before inventing a class or color.
-- **Per component:** `components/<group>/<Name>/<Name>.prompt.md` (usage) and `<Name>.d.ts` (props —
-  variant/size unions where a named type exists; some fall back to a permissive shape).
-
-## Idiomatic snippet
-
-```jsx
-// A confirm action, styled with the DS's own tokens for the surrounding layout.
-<div className="flex flex-col gap-3 rounded-lg border bg-card p-4">
-  <p className="text-sm text-muted-foreground">Publish this resume to your public profile?</p>
-  <div className="flex justify-end gap-2">
-    <RRUI.Button variant="outline">Cancel</RRUI.Button>
-    <RRUI.Button>Publish</RRUI.Button>
-  </div>
-</div>
-```

.design-sync/previews/Accordion.tsx

@@ -1,52 +0,0 @@
-import type * as React from "react";
-import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from "@reactive-resume/ui/components/accordion";
-
-const wrap: React.CSSProperties = { width: 420, padding: 16 };
-
-// Open by default so the panel content is visible in the card (Base UI accordion
-// is uncontrolled via defaultValue, matching item `value` props).
-export const Sections = () => (
-	<div style={wrap}>
-		<Accordion defaultValue={["experience"]}>
-			<AccordionItem value="experience">
-				<AccordionTrigger>Work Experience</AccordionTrigger>
-				<AccordionContent>
-					<p>Senior Product Designer · Framer — 2021 to Present</p>
-					<p>Led the redesign of the onboarding flow, lifting activation by 24% across web and mobile.</p>
-				</AccordionContent>
-			</AccordionItem>
-			<AccordionItem value="education">
-				<AccordionTrigger>Education</AccordionTrigger>
-				<AccordionContent>
-					<p>B.Des in Interaction Design · Rhode Island School of Design</p>
-				</AccordionContent>
-			</AccordionItem>
-			<AccordionItem value="skills">
-				<AccordionTrigger>Skills</AccordionTrigger>
-				<AccordionContent>
-					<p>Figma, prototyping, design systems, user research, and front-end handoff.</p>
-				</AccordionContent>
-			</AccordionItem>
-		</Accordion>
-	</div>
-);
-
-export const MultipleOpen = () => (
-	<div style={wrap}>
-		<Accordion multiple defaultValue={["summary", "certifications"]}>
-			<AccordionItem value="summary">
-				<AccordionTrigger>Professional Summary</AccordionTrigger>
-				<AccordionContent>
-					<p>Full-stack engineer with eight years shipping resilient TypeScript services and design systems.</p>
-				</AccordionContent>
-			</AccordionItem>
-			<AccordionItem value="certifications">
-				<AccordionTrigger>Certifications</AccordionTrigger>
-				<AccordionContent>
-					<p>AWS Solutions Architect · Professional</p>
-					<p>Certified Kubernetes Administrator</p>
-				</AccordionContent>
-			</AccordionItem>
-		</Accordion>
-	</div>
-);

.design-sync/previews/Alert.tsx

@@ -1,38 +0,0 @@
-import type * as React from "react";
-import { InfoIcon, WarningIcon } from "@phosphor-icons/react";
-import { Alert, AlertAction, AlertDescription, AlertTitle } from "@reactive-resume/ui/components/alert";
-import { Button } from "@reactive-resume/ui/components/button";
-
-const wrap: React.CSSProperties = { display: "flex", flexDirection: "column", gap: 16, padding: 16, maxWidth: 540 };
-
-export const Default = () => (
-	<div style={wrap}>
-		<Alert>
-			<InfoIcon />
-			<AlertTitle>Resume saved</AlertTitle>
-			<AlertDescription>Your changes were saved automatically and synced to your account.</AlertDescription>
-		</Alert>
-	</div>
-);
-
-export const Destructive = () => (
-	<div style={wrap}>
-		<Alert variant="destructive">
-			<WarningIcon />
-			<AlertTitle>Export failed</AlertTitle>
-			<AlertDescription>We couldn't generate your PDF. Check your connection and try again.</AlertDescription>
-		</Alert>
-	</div>
-);
-
-export const WithAction = () => (
-	<div style={wrap}>
-		<Alert>
-			<AlertTitle>Unsaved changes</AlertTitle>
-			<AlertDescription>You have edits that haven't been published to your public resume yet.</AlertDescription>
-			<AlertAction>
-				<Button size="sm">Publish</Button>
-			</AlertAction>
-		</Alert>
-	</div>
-);

.design-sync/previews/AlertDialog.tsx

@@ -1,34 +0,0 @@
-import { WarningIcon } from "@phosphor-icons/react";
-import {
-	AlertDialog,
-	AlertDialogAction,
-	AlertDialogCancel,
-	AlertDialogContent,
-	AlertDialogDescription,
-	AlertDialogFooter,
-	AlertDialogHeader,
-	AlertDialogMedia,
-	AlertDialogTitle,
-} from "@reactive-resume/ui/components/alert-dialog";
-
-// Overlay — rendered open (defaultOpen). cfg.overrides.AlertDialog pins
-// cardMode: single + viewport (content is fixed-positioned, centred).
-export const Open = () => (
-	<AlertDialog defaultOpen>
-		<AlertDialogContent>
-			<AlertDialogHeader>
-				<AlertDialogMedia>
-					<WarningIcon />
-				</AlertDialogMedia>
-				<AlertDialogTitle>Delete this resume?</AlertDialogTitle>
-				<AlertDialogDescription>
-					“Software Engineer” and its entire version history will be permanently removed. This action can’t be undone.
-				</AlertDialogDescription>
-			</AlertDialogHeader>
-			<AlertDialogFooter>
-				<AlertDialogCancel>Cancel</AlertDialogCancel>
-				<AlertDialogAction variant="destructive">Delete resume</AlertDialogAction>
-			</AlertDialogFooter>
-		</AlertDialogContent>
-	</AlertDialog>
-);

.design-sync/previews/Attachment.tsx

@@ -1,84 +0,0 @@
-import type * as React from "react";
-import { DownloadSimpleIcon, FileDocIcon, FilePdfIcon, TrashIcon, WarningIcon } from "@phosphor-icons/react";
-import {
-	Attachment,
-	AttachmentAction,
-	AttachmentActions,
-	AttachmentContent,
-	AttachmentDescription,
-	AttachmentGroup,
-	AttachmentMedia,
-	AttachmentTitle,
-} from "@reactive-resume/ui/components/attachment";
-
-const wrap: React.CSSProperties = { display: "flex", flexDirection: "column", gap: 12, padding: 16, width: 360 };
-
-export const WithActions = () => (
-	<div style={wrap}>
-		<Attachment>
-			<AttachmentMedia>
-				<FilePdfIcon />
-			</AttachmentMedia>
-			<AttachmentContent>
-				<AttachmentTitle>Ansel_Bradford_Resume.pdf</AttachmentTitle>
-				<AttachmentDescription>248 KB · PDF</AttachmentDescription>
-			</AttachmentContent>
-			<AttachmentActions>
-				<AttachmentAction aria-label="Download">
-					<DownloadSimpleIcon />
-				</AttachmentAction>
-				<AttachmentAction aria-label="Remove">
-					<TrashIcon />
-				</AttachmentAction>
-			</AttachmentActions>
-		</Attachment>
-	</div>
-);
-
-export const States = () => (
-	<div style={wrap}>
-		<Attachment size="sm" state="uploading">
-			<AttachmentMedia>
-				<FileDocIcon />
-			</AttachmentMedia>
-			<AttachmentContent>
-				<AttachmentTitle>cover-letter.docx</AttachmentTitle>
-				<AttachmentDescription>Uploading…</AttachmentDescription>
-			</AttachmentContent>
-		</Attachment>
-		<Attachment size="sm" state="error">
-			<AttachmentMedia>
-				<WarningIcon />
-			</AttachmentMedia>
-			<AttachmentContent>
-				<AttachmentTitle>portfolio-2024.zip</AttachmentTitle>
-				<AttachmentDescription>Upload failed · file too large</AttachmentDescription>
-			</AttachmentContent>
-		</Attachment>
-	</div>
-);
-
-export const Group = () => (
-	<div style={{ padding: 16, width: 360 }}>
-		<AttachmentGroup>
-			<Attachment orientation="vertical" size="sm">
-				<AttachmentMedia>
-					<FilePdfIcon />
-				</AttachmentMedia>
-				<AttachmentContent>
-					<AttachmentTitle>Resume.pdf</AttachmentTitle>
-					<AttachmentDescription>248 KB</AttachmentDescription>
-				</AttachmentContent>
-			</Attachment>
-			<Attachment orientation="vertical" size="sm">
-				<AttachmentMedia>
-					<FileDocIcon />
-				</AttachmentMedia>
-				<AttachmentContent>
-					<AttachmentTitle>cover-letter.docx</AttachmentTitle>
-					<AttachmentDescription>19 KB</AttachmentDescription>
-				</AttachmentContent>
-			</Attachment>
-		</AttachmentGroup>
-	</div>
-);

.design-sync/previews/Avatar.tsx

@@ -1,71 +0,0 @@
-import type * as React from "react";
-import { CheckIcon } from "@phosphor-icons/react";
-import {
-	Avatar,
-	AvatarBadge,
-	AvatarFallback,
-	AvatarGroup,
-	AvatarGroupCount,
-} from "@reactive-resume/ui/components/avatar";
-
-const row: React.CSSProperties = { display: "flex", alignItems: "center", gap: 16, padding: 20 };
-
-export const Fallback = () => (
-	<div style={row}>
-		<Avatar>
-			<AvatarFallback>AP</AvatarFallback>
-		</Avatar>
-		<Avatar>
-			<AvatarFallback>JD</AvatarFallback>
-		</Avatar>
-		<Avatar>
-			<AvatarFallback>MK</AvatarFallback>
-		</Avatar>
-	</div>
-);
-
-export const WithStatus = () => (
-	<div style={row}>
-		<Avatar>
-			<AvatarFallback>AP</AvatarFallback>
-			<AvatarBadge>
-				<CheckIcon weight="bold" />
-			</AvatarBadge>
-		</Avatar>
-		<Avatar size="lg">
-			<AvatarFallback>SR</AvatarFallback>
-			<AvatarBadge />
-		</Avatar>
-	</div>
-);
-
-export const Sizes = () => (
-	<div style={row}>
-		<Avatar size="sm">
-			<AvatarFallback>AP</AvatarFallback>
-		</Avatar>
-		<Avatar size="default">
-			<AvatarFallback>AP</AvatarFallback>
-		</Avatar>
-		<Avatar size="lg">
-			<AvatarFallback>AP</AvatarFallback>
-		</Avatar>
-	</div>
-);
-
-export const Group = () => (
-	<div style={row}>
-		<AvatarGroup>
-			<Avatar>
-				<AvatarFallback>AP</AvatarFallback>
-			</Avatar>
-			<Avatar>
-				<AvatarFallback>JD</AvatarFallback>
-			</Avatar>
-			<Avatar>
-				<AvatarFallback>MK</AvatarFallback>
-			</Avatar>
-			<AvatarGroupCount>+5</AvatarGroupCount>
-		</AvatarGroup>
-	</div>
-);

.design-sync/previews/Badge.tsx

@@ -1,40 +0,0 @@
-import type * as React from "react";
-import { CheckCircleIcon, PencilSimpleIcon, SparkleIcon } from "@phosphor-icons/react";
-import { Badge } from "@reactive-resume/ui/components/badge";
-
-const row: React.CSSProperties = { display: "flex", flexWrap: "wrap", alignItems: "center", gap: 10, padding: 20 };
-
-export const Variants = () => (
-	<div style={row}>
-		<Badge>Default</Badge>
-		<Badge variant="secondary">Secondary</Badge>
-		<Badge variant="destructive">Destructive</Badge>
-		<Badge variant="outline">Outline</Badge>
-	</div>
-);
-
-export const StatusLabels = () => (
-	<div style={row}>
-		<Badge variant="secondary">
-			<CheckCircleIcon weight="fill" data-icon="inline-start" />
-			Published
-		</Badge>
-		<Badge variant="outline">
-			<PencilSimpleIcon data-icon="inline-start" />
-			Draft
-		</Badge>
-		<Badge>
-			<SparkleIcon weight="fill" data-icon="inline-start" />
-			Pro
-		</Badge>
-		<Badge variant="destructive">Expired</Badge>
-	</div>
-);
-
-export const Counts = () => (
-	<div style={row}>
-		<Badge>12</Badge>
-		<Badge variant="secondary">New</Badge>
-		<Badge variant="outline">v5.2</Badge>
-	</div>
-);

.design-sync/previews/Bubble.tsx

@@ -1,48 +0,0 @@
-import type * as React from "react";
-import { Bubble, BubbleContent, BubbleGroup, BubbleReactions } from "@reactive-resume/ui/components/bubble";
-
-const wrap: React.CSSProperties = { display: "flex", flexDirection: "column", gap: 8, padding: 16, width: 420 };
-
-export const Conversation = () => (
-	<div style={wrap}>
-		<BubbleGroup>
-			<Bubble align="end">
-				<BubbleContent>Can you make my summary sound more senior without exaggerating?</BubbleContent>
-			</Bubble>
-			<Bubble variant="muted" align="start">
-				<BubbleContent>
-					I tightened it to lead with scope and outcomes. Want me to mirror that tone in your experience bullets too?
-				</BubbleContent>
-			</Bubble>
-			<Bubble align="end">
-				<BubbleContent>Yes, keep it concise.</BubbleContent>
-			</Bubble>
-		</BubbleGroup>
-	</div>
-);
-
-export const Variants = () => (
-	<div style={wrap}>
-		<Bubble variant="default" align="end">
-			<BubbleContent>Applied 3 edits to your resume.</BubbleContent>
-		</Bubble>
-		<Bubble variant="tinted" align="start">
-			<BubbleContent>I emphasized measurable launch outcomes in your last role.</BubbleContent>
-		</Bubble>
-		<Bubble variant="outline" align="start">
-			<BubbleContent>Draft saved — publish when you're ready.</BubbleContent>
-		</Bubble>
-		<Bubble variant="destructive" align="start">
-			<BubbleContent>Couldn't reach the AI provider. Retry?</BubbleContent>
-		</Bubble>
-	</div>
-);
-
-export const WithReactions = () => (
-	<div style={{ padding: 24, width: 420 }}>
-		<Bubble variant="secondary" align="start">
-			<BubbleContent>Rewrote your headline to target a Senior Product Manager role.</BubbleContent>
-			<BubbleReactions>👍 2</BubbleReactions>
-		</Bubble>
-	</div>
-);

.design-sync/previews/Button.tsx

@@ -1,51 +0,0 @@
-import type * as React from "react";
-import { ArrowRightIcon, PlusIcon, TrashIcon } from "@phosphor-icons/react";
-import { Button } from "@reactive-resume/ui/components/button";
-
-const row: React.CSSProperties = { display: "flex", flexWrap: "wrap", alignItems: "center", gap: 12, padding: 16 };
-
-export const Variants = () => (
-	<div style={row}>
-		<Button>Save changes</Button>
-		<Button variant="secondary">Secondary</Button>
-		<Button variant="outline">Outline</Button>
-		<Button variant="ghost">Ghost</Button>
-		<Button variant="destructive">Delete</Button>
-		<Button variant="link">Learn more</Button>
-	</div>
-);
-
-export const Sizes = () => (
-	<div style={row}>
-		<Button size="xs">Extra small</Button>
-		<Button size="sm">Small</Button>
-		<Button size="default">Default</Button>
-		<Button size="lg">Large</Button>
-	</div>
-);
-
-export const WithIcons = () => (
-	<div style={row}>
-		<Button>
-			<PlusIcon /> Add section
-		</Button>
-		<Button variant="outline">
-			Continue <ArrowRightIcon />
-		</Button>
-		<Button variant="destructive">
-			<TrashIcon /> Remove
-		</Button>
-		<Button size="icon" variant="outline" aria-label="Add section">
-			<PlusIcon />
-		</Button>
-	</div>
-);
-
-export const Disabled = () => (
-	<div style={row}>
-		<Button disabled>Saving…</Button>
-		<Button variant="outline" disabled>
-			Disabled
-		</Button>
-	</div>
-);

.design-sync/previews/ButtonGroup.tsx

@@ -1,67 +0,0 @@
-import type * as React from "react";
-import {
-	AlignCenterHorizontalIcon,
-	AlignLeftIcon,
-	AlignRightIcon,
-	ArrowClockwiseIcon,
-	ArrowCounterClockwiseIcon,
-	TextBIcon,
-	TextItalicIcon,
-	TextUnderlineIcon,
-} from "@phosphor-icons/react";
-import { Button } from "@reactive-resume/ui/components/button";
-import { ButtonGroup, ButtonGroupSeparator, ButtonGroupText } from "@reactive-resume/ui/components/button-group";
-
-const wrap: React.CSSProperties = { display: "flex", flexDirection: "column", gap: 16, padding: 16 };
-
-export const Formatting = () => (
-	<div style={wrap}>
-		<ButtonGroup>
-			<Button variant="outline" size="icon" aria-label="Bold">
-				<TextBIcon />
-			</Button>
-			<Button variant="outline" size="icon" aria-label="Italic">
-				<TextItalicIcon />
-			</Button>
-			<Button variant="outline" size="icon" aria-label="Underline">
-				<TextUnderlineIcon />
-			</Button>
-			<ButtonGroupSeparator />
-			<Button variant="outline" size="icon" aria-label="Align left">
-				<AlignLeftIcon />
-			</Button>
-			<Button variant="outline" size="icon" aria-label="Align center">
-				<AlignCenterHorizontalIcon />
-			</Button>
-			<Button variant="outline" size="icon" aria-label="Align right">
-				<AlignRightIcon />
-			</Button>
-		</ButtonGroup>
-
-		<ButtonGroup>
-			<Button variant="outline">
-				<ArrowCounterClockwiseIcon /> Undo
-			</Button>
-			<Button variant="outline">
-				<ArrowClockwiseIcon /> Redo
-			</Button>
-		</ButtonGroup>
-	</div>
-);
-
-export const WithText = () => (
-	<div style={wrap}>
-		<ButtonGroup>
-			<ButtonGroupText>Zoom</ButtonGroupText>
-			<Button variant="outline">50%</Button>
-			<Button variant="outline">100%</Button>
-			<Button variant="outline">150%</Button>
-		</ButtonGroup>
-
-		<ButtonGroup orientation="vertical">
-			<Button variant="outline">Export PDF</Button>
-			<Button variant="outline">Export DOCX</Button>
-			<Button variant="outline">Copy link</Button>
-		</ButtonGroup>
-	</div>
-);

.design-sync/previews/ComboboxRoot.tsx

@@ -1,30 +0,0 @@
-import {
-	ComboboxContent,
-	ComboboxEmpty,
-	ComboboxInput,
-	ComboboxItem,
-	ComboboxList,
-	ComboboxRoot,
-} from "@reactive-resume/ui/components/combobox";
-
-const skills = ["TypeScript", "React", "Node.js", "GraphQL", "PostgreSQL", "Kubernetes"];
-
-// Base UI Combobox — items passed to Root, rendered open (defaultOpen).
-// cfg.overrides.ComboboxRoot pins cardMode: single + viewport with room below.
-export const Open = () => (
-	<div style={{ width: 320, padding: 16, paddingBottom: 200 }}>
-		<ComboboxRoot items={skills} defaultOpen>
-			<ComboboxInput placeholder="Add a skill…" />
-			<ComboboxContent>
-				<ComboboxEmpty>No skills found.</ComboboxEmpty>
-				<ComboboxList>
-					{(item: string) => (
-						<ComboboxItem key={item} value={item}>
-							{item}
-						</ComboboxItem>
-					)}
-				</ComboboxList>
-			</ComboboxContent>
-		</ComboboxRoot>
-	</div>
-);

.design-sync/previews/Command.tsx

@@ -1,42 +0,0 @@
-import { DownloadSimpleIcon, GearIcon, PlusIcon, UserIcon } from "@phosphor-icons/react";
-import {
-	Command,
-	CommandGroup,
-	CommandInput,
-	CommandItem,
-	CommandList,
-	CommandSeparator,
-	CommandShortcut,
-} from "@reactive-resume/ui/components/command";
-
-// Command renders inline (cmdk) — a searchable command palette. No overlay.
-export const Palette = () => (
-	<div style={{ width: 400, padding: 16 }}>
-		<div style={{ border: "1px solid var(--border)", borderRadius: 10, overflow: "hidden" }}>
-			<Command>
-				<CommandInput placeholder="Type a command or search…" />
-				<CommandList>
-					<CommandGroup heading="Actions">
-						<CommandItem>
-							<PlusIcon /> New resume
-							<CommandShortcut>⌘N</CommandShortcut>
-						</CommandItem>
-						<CommandItem>
-							<DownloadSimpleIcon /> Export as PDF
-						</CommandItem>
-					</CommandGroup>
-					<CommandSeparator />
-					<CommandGroup heading="Account">
-						<CommandItem>
-							<UserIcon /> Profile
-						</CommandItem>
-						<CommandItem>
-							<GearIcon /> Settings
-							<CommandShortcut>⌘,</CommandShortcut>
-						</CommandItem>
-					</CommandGroup>
-				</CommandList>
-			</Command>
-		</div>
-	</div>
-);

.design-sync/previews/ContextMenu.tsx

@@ -1,48 +0,0 @@
-import {
-	ContextMenu,
-	ContextMenuContent,
-	ContextMenuGroup,
-	ContextMenuItem,
-	ContextMenuLabel,
-	ContextMenuSeparator,
-	ContextMenuShortcut,
-	ContextMenuTrigger,
-} from "@reactive-resume/ui/components/context-menu";
-
-// Right-click menu — rendered open (defaultOpen) so the card shows the menu.
-// cfg.overrides.ContextMenu pins cardMode: single + viewport.
-export const Open = () => (
-	<div style={{ display: "flex", justifyContent: "center", padding: 24, paddingBottom: 160 }}>
-		<ContextMenu defaultOpen>
-			<ContextMenuTrigger>
-				<div
-					style={{
-						display: "grid",
-						placeItems: "center",
-						width: 240,
-						height: 96,
-						border: "1px dashed var(--border)",
-						borderRadius: 8,
-						color: "var(--muted-foreground)",
-						fontSize: 13,
-					}}
-				>
-					Right-click a resume card
-				</div>
-			</ContextMenuTrigger>
-			<ContextMenuContent>
-				<ContextMenuGroup>
-					<ContextMenuLabel>Software Engineer</ContextMenuLabel>
-					<ContextMenuItem>Open</ContextMenuItem>
-					<ContextMenuItem>
-						Rename
-						<ContextMenuShortcut>F2</ContextMenuShortcut>
-					</ContextMenuItem>
-					<ContextMenuItem>Duplicate</ContextMenuItem>
-				</ContextMenuGroup>
-				<ContextMenuSeparator />
-				<ContextMenuItem variant="destructive">Delete</ContextMenuItem>
-			</ContextMenuContent>
-		</ContextMenu>
-	</div>
-);

.design-sync/previews/Dialog.tsx

@@ -1,30 +0,0 @@
-import { Button } from "@reactive-resume/ui/components/button";
-import {
-	Dialog,
-	DialogClose,
-	DialogContent,
-	DialogDescription,
-	DialogFooter,
-	DialogHeader,
-	DialogTitle,
-} from "@reactive-resume/ui/components/dialog";
-
-// Overlay component — rendered open (defaultOpen) so the card shows the real
-// dialog surface. cfg.overrides.Dialog pins cardMode: single + a viewport for
-// the portal (content is fixed-positioned at the viewport centre).
-export const Open = () => (
-	<Dialog defaultOpen>
-		<DialogContent>
-			<DialogHeader>
-				<DialogTitle>Delete resume</DialogTitle>
-				<DialogDescription>
-					This permanently deletes “Software Engineer” along with its version history. This action cannot be undone.
-				</DialogDescription>
-			</DialogHeader>
-			<DialogFooter>
-				<DialogClose render={<Button variant="outline" />}>Cancel</DialogClose>
-				<DialogClose render={<Button variant="destructive" />}>Delete resume</DialogClose>
-			</DialogFooter>
-		</DialogContent>
-	</Dialog>
-);

.design-sync/previews/DropdownMenu.tsx

@@ -1,41 +0,0 @@
-import { CopyIcon, DownloadSimpleIcon, PencilIcon, TrashIcon } from "@phosphor-icons/react";
-import { Button } from "@reactive-resume/ui/components/button";
-import {
-	DropdownMenu,
-	DropdownMenuContent,
-	DropdownMenuGroup,
-	DropdownMenuItem,
-	DropdownMenuLabel,
-	DropdownMenuSeparator,
-	DropdownMenuShortcut,
-	DropdownMenuTrigger,
-} from "@reactive-resume/ui/components/dropdown-menu";
-
-// Anchored menu — rendered open (defaultOpen), positioned below its trigger.
-// cfg.overrides.DropdownMenu pins cardMode: single + viewport with room below.
-export const Open = () => (
-	<div style={{ display: "flex", justifyContent: "center", paddingTop: 16, paddingBottom: 220 }}>
-		<DropdownMenu defaultOpen>
-			<DropdownMenuTrigger render={<Button variant="outline" />}>Resume actions</DropdownMenuTrigger>
-			<DropdownMenuContent>
-				<DropdownMenuGroup>
-					<DropdownMenuLabel>Software Engineer</DropdownMenuLabel>
-					<DropdownMenuItem>
-						<PencilIcon /> Rename
-					</DropdownMenuItem>
-					<DropdownMenuItem>
-						<CopyIcon /> Duplicate
-						<DropdownMenuShortcut>⌘D</DropdownMenuShortcut>
-					</DropdownMenuItem>
-					<DropdownMenuItem>
-						<DownloadSimpleIcon /> Export PDF
-					</DropdownMenuItem>
-				</DropdownMenuGroup>
-				<DropdownMenuSeparator />
-				<DropdownMenuItem variant="destructive">
-					<TrashIcon /> Delete
-				</DropdownMenuItem>
-			</DropdownMenuContent>
-		</DropdownMenu>
-	</div>
-);

.design-sync/previews/FormItem.tsx

@@ -1,27 +0,0 @@
-import type * as React from "react";
-import { FormControl, FormDescription, FormItem, FormLabel, FormMessage } from "@reactive-resume/ui/components/form";
-import { Input } from "@reactive-resume/ui/components/input";
-
-// FormItem carries its own field context (id + error state) — FormLabel /
-// FormControl / FormDescription / FormMessage compose under it standalone.
-const wrap: React.CSSProperties = { display: "flex", flexDirection: "column", gap: 16, padding: 16, width: 340 };
-
-export const Default = () => (
-	<div style={wrap}>
-		<FormItem>
-			<FormLabel>Headline</FormLabel>
-			<FormControl render={<Input placeholder="Senior Software Engineer" />} />
-			<FormDescription>Shown under your name at the top of the resume.</FormDescription>
-		</FormItem>
-	</div>
-);
-
-export const WithError = () => (
-	<div style={wrap}>
-		<FormItem hasError>
-			<FormLabel>Email</FormLabel>
-			<FormControl render={<Input defaultValue="jane@" />} />
-			<FormMessage errors={["Enter a valid email address."]} />
-		</FormItem>
-	</div>
-);

.design-sync/previews/HoverCard.tsx

@@ -1,19 +0,0 @@
-import { Button } from "@reactive-resume/ui/components/button";
-import { HoverCard, HoverCardContent, HoverCardTrigger } from "@reactive-resume/ui/components/hover-card";
-
-// Anchored preview-card overlay — rendered open (defaultOpen).
-// cfg.overrides.HoverCard pins cardMode: single + viewport with room below the trigger.
-export const Open = () => (
-	<div style={{ display: "flex", justifyContent: "center", paddingTop: 24, paddingBottom: 180 }}>
-		<HoverCard defaultOpen>
-			<HoverCardTrigger render={<Button variant="link" />}>@jane-doe</HoverCardTrigger>
-			<HoverCardContent>
-				<div style={{ display: "flex", flexDirection: "column", gap: 6 }}>
-					<span style={{ fontWeight: 600 }}>Jane Doe</span>
-					<span style={{ color: "var(--muted-foreground)" }}>Senior Software Engineer · San Francisco</span>
-					<span style={{ color: "var(--muted-foreground)", fontSize: 12 }}>3 published resumes · joined 2023</span>
-				</div>
-			</HoverCardContent>
-		</HoverCard>
-	</div>
-);

.design-sync/previews/Input.tsx

@@ -1,40 +0,0 @@
-import type * as React from "react";
-import { Input } from "@reactive-resume/ui/components/input";
-import { Label } from "@reactive-resume/ui/components/label";
-
-const field: React.CSSProperties = { display: "flex", flexDirection: "column", gap: 6, padding: 16, width: 320 };
-
-export const Default = () => (
-	<div style={field}>
-		<Label htmlFor="full-name">Full name</Label>
-		<Input id="full-name" defaultValue="Ada Lovelace" />
-	</div>
-);
-
-export const Placeholder = () => (
-	<div style={field}>
-		<Label htmlFor="headline">Headline</Label>
-		<Input id="headline" placeholder="e.g. Senior Software Engineer" />
-	</div>
-);
-
-export const Email = () => (
-	<div style={field}>
-		<Label htmlFor="email">Email</Label>
-		<Input id="email" type="email" defaultValue="ada@analyticalengine.dev" />
-	</div>
-);
-
-export const Invalid = () => (
-	<div style={field}>
-		<Label htmlFor="website">Website</Label>
-		<Input id="website" aria-invalid defaultValue="not-a-valid-url" />
-	</div>
-);
-
-export const Disabled = () => (
-	<div style={field}>
-		<Label htmlFor="username">Username</Label>
-		<Input id="username" disabled defaultValue="ada.lovelace" />
-	</div>
-);

.design-sync/previews/InputGroup.tsx

@@ -1,55 +0,0 @@
-import type * as React from "react";
-import { CopyIcon, GlobeIcon, MagnifyingGlassIcon } from "@phosphor-icons/react";
-import {
-	InputGroup,
-	InputGroupAddon,
-	InputGroupButton,
-	InputGroupInput,
-	InputGroupText,
-	InputGroupTextarea,
-} from "@reactive-resume/ui/components/input-group";
-
-const wrap: React.CSSProperties = { display: "flex", flexDirection: "column", gap: 16, padding: 16, width: 380 };
-
-export const Addons = () => (
-	<div style={wrap}>
-		<InputGroup>
-			<InputGroupAddon>
-				<MagnifyingGlassIcon />
-			</InputGroupAddon>
-			<InputGroupInput placeholder="Search resumes" defaultValue="Product Designer" />
-		</InputGroup>
-
-		<InputGroup>
-			<InputGroupAddon>
-				<GlobeIcon />
-				<InputGroupText>rxresu.me/u/</InputGroupText>
-			</InputGroupAddon>
-			<InputGroupInput defaultValue="jordan-rivera" />
-		</InputGroup>
-
-		<InputGroup>
-			<InputGroupInput readOnly defaultValue="rxr_live_9f3c8a21bd47e50a" />
-			<InputGroupAddon align="inline-end">
-				<InputGroupButton size="icon-sm" aria-label="Copy API key">
-					<CopyIcon />
-				</InputGroupButton>
-			</InputGroupAddon>
-		</InputGroup>
-	</div>
-);
-
-export const WithTextarea = () => (
-	<div style={wrap}>
-		<InputGroup>
-			<InputGroupTextarea
-				rows={3}
-				defaultValue="Senior product designer focused on design systems, accessibility, and shipping polished interfaces."
-			/>
-			<InputGroupAddon align="block-end">
-				<InputGroupText>240 characters left</InputGroupText>
-				<InputGroupButton style={{ marginLeft: "auto" }}>Generate with AI</InputGroupButton>
-			</InputGroupAddon>
-		</InputGroup>
-	</div>
-);

.design-sync/previews/Kbd.tsx

@@ -1,68 +0,0 @@
-import type * as React from "react";
-import { Kbd, KbdGroup } from "@reactive-resume/ui/components/kbd";
-
-const row: React.CSSProperties = { display: "flex", flexWrap: "wrap", alignItems: "center", gap: 12, padding: 20 };
-const listRow: React.CSSProperties = {
-	display: "flex",
-	alignItems: "center",
-	justifyContent: "space-between",
-	gap: 24,
-	fontSize: 13,
-	color: "var(--foreground)",
-};
-const col: React.CSSProperties = { display: "flex", flexDirection: "column", gap: 10, padding: 20, minWidth: 260 };
-
-export const Keys = () => (
-	<div style={row}>
-		<Kbd>⌘</Kbd>
-		<Kbd>⇧</Kbd>
-		<Kbd>⌥</Kbd>
-		<Kbd>Esc</Kbd>
-		<Kbd>Enter</Kbd>
-		<Kbd>Tab</Kbd>
-	</div>
-);
-
-export const Combinations = () => (
-	<div style={row}>
-		<KbdGroup>
-			<Kbd>⌘</Kbd>
-			<Kbd>K</Kbd>
-		</KbdGroup>
-		<KbdGroup>
-			<Kbd>⌘</Kbd>
-			<Kbd>S</Kbd>
-		</KbdGroup>
-		<KbdGroup>
-			<Kbd>⌘</Kbd>
-			<Kbd>⇧</Kbd>
-			<Kbd>P</Kbd>
-		</KbdGroup>
-	</div>
-);
-
-export const ShortcutList = () => (
-	<div style={col}>
-		<div style={listRow}>
-			<span>Command palette</span>
-			<KbdGroup>
-				<Kbd>⌘</Kbd>
-				<Kbd>K</Kbd>
-			</KbdGroup>
-		</div>
-		<div style={listRow}>
-			<span>Save resume</span>
-			<KbdGroup>
-				<Kbd>⌘</Kbd>
-				<Kbd>S</Kbd>
-			</KbdGroup>
-		</div>
-		<div style={listRow}>
-			<span>Undo</span>
-			<KbdGroup>
-				<Kbd>⌘</Kbd>
-				<Kbd>Z</Kbd>
-			</KbdGroup>
-		</div>
-	</div>
-);

.design-sync/previews/Label.tsx

@@ -1,39 +0,0 @@
-import type * as React from "react";
-import { Input } from "@reactive-resume/ui/components/input";
-import { Label } from "@reactive-resume/ui/components/label";
-import { Switch } from "@reactive-resume/ui/components/switch";
-
-const field: React.CSSProperties = { display: "flex", flexDirection: "column", gap: 6, padding: 16, width: 320 };
-const row: React.CSSProperties = { display: "flex", alignItems: "center", gap: 10, padding: 16, width: 320 };
-
-export const WithInput = () => (
-	<div style={field}>
-		<Label htmlFor="company">Company</Label>
-		<Input id="company" defaultValue="Analytical Engine Co." />
-	</div>
-);
-
-export const Required = () => (
-	<div style={field}>
-		<Label htmlFor="job-title">
-			Job title <span style={{ color: "var(--destructive)" }}>*</span>
-		</Label>
-		<Input id="job-title" placeholder="e.g. Lead Engineer" />
-	</div>
-);
-
-export const WithSwitch = () => (
-	<div style={row}>
-		<Switch id="public-resume" defaultChecked />
-		<Label htmlFor="public-resume">Public resume</Label>
-	</div>
-);
-
-export const Disabled = () => (
-	<div style={field}>
-		<Label htmlFor="locked-field" data-disabled="true" style={{ opacity: 0.5 }}>
-			Locked field
-		</Label>
-		<Input id="locked-field" disabled defaultValue="Read only" />
-	</div>
-);

.design-sync/previews/Marker.tsx

@@ -1,39 +0,0 @@
-import type * as React from "react";
-import { CheckCircleIcon, SparkleIcon, WarningCircleIcon } from "@phosphor-icons/react";
-import { Marker, MarkerContent, MarkerIcon } from "@reactive-resume/ui/components/marker";
-
-const wrap: React.CSSProperties = { display: "flex", flexDirection: "column", gap: 12, padding: 16, width: 360 };
-
-export const Statuses = () => (
-	<div style={wrap}>
-		<Marker style={{ width: "fit-content", borderRadius: 8, padding: "12px 16px", background: "var(--muted)" }}>
-			<MarkerIcon>
-				<SparkleIcon />
-			</MarkerIcon>
-			<MarkerContent>Tailoring your resume…</MarkerContent>
-		</Marker>
-		<Marker style={{ width: "fit-content" }}>
-			<MarkerIcon>
-				<CheckCircleIcon />
-			</MarkerIcon>
-			<MarkerContent>Applied 4 edits to your resume</MarkerContent>
-		</Marker>
-		<Marker style={{ width: "fit-content" }}>
-			<MarkerIcon>
-				<WarningCircleIcon />
-			</MarkerIcon>
-			<MarkerContent>Couldn't reach the AI provider</MarkerContent>
-		</Marker>
-	</div>
-);
-
-export const Dividers = () => (
-	<div style={wrap}>
-		<Marker variant="separator">
-			<MarkerContent>Today</MarkerContent>
-		</Marker>
-		<Marker variant="border">
-			<MarkerContent>Conversation history</MarkerContent>
-		</Marker>
-	</div>
-);

.design-sync/previews/Message.tsx

@@ -1,65 +0,0 @@
-import type * as React from "react";
-import { SparkleIcon, UserIcon } from "@phosphor-icons/react";
-import { Bubble, BubbleContent } from "@reactive-resume/ui/components/bubble";
-import {
-	Message,
-	MessageAvatar,
-	MessageContent,
-	MessageFooter,
-	MessageGroup,
-	MessageHeader,
-} from "@reactive-resume/ui/components/message";
-
-const avatar: React.CSSProperties = { display: "flex", alignItems: "center", justifyContent: "center", padding: 8 };
-
-export const Conversation = () => (
-	<div style={{ display: "flex", padding: 16, width: 460 }}>
-		<MessageGroup style={{ width: "100%" }}>
-			<Message align="end">
-				<MessageAvatar>
-					<span style={avatar}>
-						<UserIcon />
-					</span>
-				</MessageAvatar>
-				<MessageContent>
-					<Bubble align="end">
-						<BubbleContent>Tailor my resume for a product manager role.</BubbleContent>
-					</Bubble>
-				</MessageContent>
-			</Message>
-			<Message align="start">
-				<MessageAvatar>
-					<span style={avatar}>
-						<SparkleIcon />
-					</span>
-				</MessageAvatar>
-				<MessageContent>
-					<Bubble variant="muted" align="start">
-						<BubbleContent>
-							Done — I emphasized roadmap ownership and stakeholder communication in your summary.
-						</BubbleContent>
-					</Bubble>
-				</MessageContent>
-			</Message>
-		</MessageGroup>
-	</div>
-);
-
-export const WithMeta = () => (
-	<div style={{ display: "flex", padding: 16, width: 460 }}>
-		<Message align="start">
-			<MessageAvatar>
-				<span style={avatar}>
-					<SparkleIcon />
-				</span>
-			</MessageAvatar>
-			<MessageContent>
-				<MessageHeader>Reactive AI</MessageHeader>
-				<Bubble variant="tinted" align="start">
-					<BubbleContent>I found 4 weak bullets and rewrote them with stronger verbs and metrics.</BubbleContent>
-				</Bubble>
-				<MessageFooter>Just now · applied 4 edits</MessageFooter>
-			</MessageContent>
-		</Message>
-	</div>
-);

.design-sync/previews/MessageScroller.tsx

@@ -1,57 +0,0 @@
-import type * as React from "react";
-import { SparkleIcon, UserIcon } from "@phosphor-icons/react";
-import { Bubble, BubbleContent } from "@reactive-resume/ui/components/bubble";
-import { Message, MessageAvatar, MessageContent } from "@reactive-resume/ui/components/message";
-import {
-	MessageScroller,
-	MessageScrollerButton,
-	MessageScrollerContent,
-	MessageScrollerItem,
-	MessageScrollerProvider,
-	MessageScrollerViewport,
-} from "@reactive-resume/ui/components/message-scroller";
-
-const avatar: React.CSSProperties = { display: "flex", alignItems: "center", justifyContent: "center", padding: 8 };
-
-const turns = [
-	{ role: "user", text: "Can you review my resume for a senior engineering role?" },
-	{ role: "assistant", text: "Sure — I'll focus on scope, impact, and leadership signals. Reading it now." },
-	{ role: "user", text: "Great, keep the tone concise." },
-	{
-		role: "assistant",
-		text: "I rewrote your summary and tightened three experience bullets with measurable outcomes.",
-	},
-	{ role: "user", text: "Perfect, publish the draft." },
-	{ role: "assistant", text: "Draft saved and published to your public resume. Anything else you'd like to refine?" },
-];
-
-export const Thread = () => (
-	<div style={{ height: 340, width: 460, padding: 12 }}>
-		<MessageScrollerProvider autoScroll defaultScrollPosition="end">
-			<MessageScroller>
-				<MessageScrollerViewport>
-					<MessageScrollerContent style={{ padding: 12 }}>
-						{turns.map((turn, index) => (
-							<MessageScrollerItem key={turn.text} messageId={`turn-${index}`}>
-								<Message align={turn.role === "user" ? "end" : "start"}>
-									<MessageAvatar>
-										<span style={avatar}>{turn.role === "user" ? <UserIcon /> : <SparkleIcon />}</span>
-									</MessageAvatar>
-									<MessageContent>
-										<Bubble
-											variant={turn.role === "user" ? "default" : "muted"}
-											align={turn.role === "user" ? "end" : "start"}
-										>
-											<BubbleContent>{turn.text}</BubbleContent>
-										</Bubble>
-									</MessageContent>
-								</Message>
-							</MessageScrollerItem>
-						))}
-					</MessageScrollerContent>
-				</MessageScrollerViewport>
-				<MessageScrollerButton />
-			</MessageScroller>
-		</MessageScrollerProvider>
-	</div>
-);

.design-sync/previews/Popover.tsx

@@ -1,33 +0,0 @@
-import { Button } from "@reactive-resume/ui/components/button";
-import {
-	Popover,
-	PopoverContent,
-	PopoverDescription,
-	PopoverHeader,
-	PopoverTitle,
-	PopoverTrigger,
-} from "@reactive-resume/ui/components/popover";
-
-// Anchored overlay — rendered open (defaultOpen), positioned below its trigger.
-// cfg.overrides.Popover pins cardMode: single + viewport with room for the popup.
-export const Open = () => (
-	<div style={{ display: "flex", justifyContent: "center", paddingTop: 24, paddingBottom: 220 }}>
-		<Popover defaultOpen>
-			<PopoverTrigger render={<Button variant="outline" />}>Share resume</PopoverTrigger>
-			<PopoverContent>
-				<PopoverHeader>
-					<PopoverTitle>Public link</PopoverTitle>
-					<PopoverDescription>Anyone with this link can view your published resume.</PopoverDescription>
-				</PopoverHeader>
-				<div style={{ display: "flex", gap: 8 }}>
-					<Button size="sm" variant="secondary">
-						Copy link
-					</Button>
-					<Button size="sm" variant="ghost">
-						Open
-					</Button>
-				</div>
-			</PopoverContent>
-		</Popover>
-	</div>
-);

.design-sync/previews/ResizableGroup.tsx

@@ -1,57 +0,0 @@
-import type * as React from "react";
-import { ResizableGroup, ResizablePanel, ResizableSeparator } from "@reactive-resume/ui/components/resizable";
-
-const panelStyle: React.CSSProperties = { height: "100%", padding: 16, fontSize: 14, lineHeight: 1.6 };
-const label: React.CSSProperties = {
-	fontSize: 11,
-	fontWeight: 600,
-	textTransform: "uppercase",
-	letterSpacing: "0.05em",
-	color: "var(--muted-foreground)",
-	marginBottom: 8,
-};
-
-export const BuilderLayout = () => (
-	<div style={{ height: 240, width: 460, border: "1px solid var(--border)", borderRadius: 8, overflow: "hidden" }}>
-		<ResizableGroup orientation="horizontal">
-			<ResizablePanel defaultSize={40}>
-				<div style={panelStyle}>
-					<div style={label}>Editor</div>
-					<div>Basics</div>
-					<div>Work Experience</div>
-					<div>Education</div>
-					<div>Skills</div>
-				</div>
-			</ResizablePanel>
-			<ResizableSeparator withHandle />
-			<ResizablePanel defaultSize={60}>
-				<div style={{ ...panelStyle, background: "var(--muted)" }}>
-					<div style={label}>Live Preview</div>
-					<div style={{ fontWeight: 600, fontSize: 16 }}>Jordan Rivera</div>
-					<div style={{ color: "var(--muted-foreground)" }}>Senior Product Designer</div>
-				</div>
-			</ResizablePanel>
-		</ResizableGroup>
-	</div>
-);
-
-export const VerticalSplit = () => (
-	<div style={{ height: 240, width: 300, border: "1px solid var(--border)", borderRadius: 8, overflow: "hidden" }}>
-		<ResizableGroup orientation="vertical">
-			<ResizablePanel defaultSize={50}>
-				<div style={panelStyle}>
-					<div style={label}>Summary</div>
-					<div>Eight years building design systems and shipping delightful product experiences.</div>
-				</div>
-			</ResizablePanel>
-			<ResizableSeparator withHandle />
-			<ResizablePanel defaultSize={50}>
-				<div style={{ ...panelStyle, background: "var(--muted)" }}>
-					<div style={label}>Contact</div>
-					<div>jordan.rivera@email.com</div>
-					<div>San Francisco, CA</div>
-				</div>
-			</ResizablePanel>
-		</ResizableGroup>
-	</div>
-);

.design-sync/previews/ScrollArea.tsx

@@ -1,39 +0,0 @@
-import type * as React from "react";
-import { ScrollArea } from "@reactive-resume/ui/components/scroll-area";
-
-const templates = [
-	{ name: "Azurill", tag: "Minimal" },
-	{ name: "Bronzor", tag: "Classic" },
-	{ name: "Chikorita", tag: "Modern" },
-	{ name: "Ditto", tag: "Compact" },
-	{ name: "Gengar", tag: "Bold" },
-	{ name: "Glalie", tag: "Elegant" },
-	{ name: "Kakuna", tag: "Timeless" },
-	{ name: "Leafish", tag: "Creative" },
-	{ name: "Nosepass", tag: "Formal" },
-	{ name: "Onyx", tag: "Technical" },
-	{ name: "Pikachu", tag: "Friendly" },
-	{ name: "Rhyhorn", tag: "Corporate" },
-];
-
-const rowStyle: React.CSSProperties = {
-	display: "flex",
-	alignItems: "center",
-	justifyContent: "space-between",
-	padding: "10px 14px",
-	borderBottom: "1px solid var(--border)",
-	fontSize: 14,
-};
-
-export const TemplateList = () => (
-	<ScrollArea style={{ height: 240, width: 320, border: "1px solid var(--border)", borderRadius: 8 }}>
-		<div style={{ padding: 4 }}>
-			{templates.map((template) => (
-				<div key={template.name} style={rowStyle}>
-					<span style={{ fontWeight: 500 }}>{template.name}</span>
-					<span style={{ color: "var(--muted-foreground)", fontSize: 12 }}>{template.tag}</span>
-				</div>
-			))}
-		</div>
-	</ScrollArea>
-);

.design-sync/previews/Separator.tsx

@@ -1,45 +0,0 @@
-import type * as React from "react";
-import { Separator } from "@reactive-resume/ui/components/separator";
-
-const block: React.CSSProperties = {
-	display: "flex",
-	flexDirection: "column",
-	gap: 12,
-	padding: 20,
-	maxWidth: 360,
-	fontSize: 13,
-	color: "var(--foreground)",
-};
-const inline: React.CSSProperties = {
-	display: "flex",
-	alignItems: "center",
-	gap: 12,
-	padding: 20,
-	fontSize: 13,
-	color: "var(--muted-foreground)",
-};
-
-export const Horizontal = () => (
-	<div style={block}>
-		<div>
-			<strong style={{ display: "block", fontSize: 14 }}>Amruth Pillai</strong>
-			<span style={{ color: "var(--muted-foreground)" }}>Senior Software Engineer</span>
-		</div>
-		<Separator />
-		<span style={{ color: "var(--muted-foreground)" }}>
-			Building resume tooling at Reactive Resume. Open-source enthusiast.
-		</span>
-	</div>
-);
-
-export const Vertical = () => (
-	<div style={inline}>
-		<span>Profile</span>
-		<Separator orientation="vertical" style={{ height: 16 }} />
-		<span>Experience</span>
-		<Separator orientation="vertical" style={{ height: 16 }} />
-		<span>Education</span>
-		<Separator orientation="vertical" style={{ height: 16 }} />
-		<span>Skills</span>
-	</div>
-);

.design-sync/previews/Sheet.tsx

@@ -1,38 +0,0 @@
-import { Button } from "@reactive-resume/ui/components/button";
-import { Label } from "@reactive-resume/ui/components/label";
-import {
-	Sheet,
-	SheetClose,
-	SheetContent,
-	SheetDescription,
-	SheetFooter,
-	SheetHeader,
-	SheetTitle,
-} from "@reactive-resume/ui/components/sheet";
-
-// Side drawer — rendered open (defaultOpen), anchored to the right edge.
-// cfg.overrides.Sheet pins cardMode: single + viewport.
-export const Open = () => (
-	<Sheet defaultOpen>
-		<SheetContent side="right">
-			<SheetHeader>
-				<SheetTitle>Resume settings</SheetTitle>
-				<SheetDescription>Control how “Software Engineer” appears when shared publicly.</SheetDescription>
-			</SheetHeader>
-			<div style={{ display: "flex", flexDirection: "column", gap: 14, padding: "0 16px" }}>
-				<div style={{ display: "flex", flexDirection: "column", gap: 6 }}>
-					<Label>Public slug</Label>
-					<span style={{ fontSize: 13, color: "var(--muted-foreground)" }}>rxresume.me/jane-doe</span>
-				</div>
-				<div style={{ display: "flex", flexDirection: "column", gap: 6 }}>
-					<Label>Visibility</Label>
-					<span style={{ fontSize: 13, color: "var(--muted-foreground)" }}>Anyone with the link can view</span>
-				</div>
-			</div>
-			<SheetFooter>
-				<SheetClose render={<Button variant="outline" />}>Cancel</SheetClose>
-				<SheetClose render={<Button />}>Save changes</SheetClose>
-			</SheetFooter>
-		</SheetContent>
-	</Sheet>
-);

.design-sync/previews/Sidebar.tsx

@@ -1,61 +0,0 @@
-import { FileTextIcon, GearIcon, HouseIcon, PlusIcon } from "@phosphor-icons/react";
-import {
-	Sidebar,
-	SidebarContent,
-	SidebarFooter,
-	SidebarGroup,
-	SidebarGroupLabel,
-	SidebarHeader,
-	SidebarMenu,
-	SidebarMenuButton,
-	SidebarMenuItem,
-	SidebarProvider,
-} from "@reactive-resume/ui/components/sidebar";
-
-// SidebarProvider supplies context + --sidebar-width. `collapsible="none"`
-// renders the sidebar inline (the default offcanvas variant is fixed-positioned
-// and would escape the card).
-export const Navigation = () => (
-	<SidebarProvider>
-		<div
-			style={{ height: 400, display: "flex", border: "1px solid var(--border)", borderRadius: 10, overflow: "hidden" }}
-		>
-			<Sidebar collapsible="none">
-				<SidebarHeader>
-					<div style={{ padding: 8, fontWeight: 600, fontSize: 14 }}>Reactive Resume</div>
-				</SidebarHeader>
-				<SidebarContent>
-					<SidebarGroup>
-						<SidebarGroupLabel>Workspace</SidebarGroupLabel>
-						<SidebarMenu>
-							<SidebarMenuItem>
-								<SidebarMenuButton isActive>
-									<HouseIcon /> Dashboard
-								</SidebarMenuButton>
-							</SidebarMenuItem>
-							<SidebarMenuItem>
-								<SidebarMenuButton>
-									<FileTextIcon /> Resumes
-								</SidebarMenuButton>
-							</SidebarMenuItem>
-							<SidebarMenuItem>
-								<SidebarMenuButton>
-									<PlusIcon /> New resume
-								</SidebarMenuButton>
-							</SidebarMenuItem>
-						</SidebarMenu>
-					</SidebarGroup>
-				</SidebarContent>
-				<SidebarFooter>
-					<SidebarMenu>
-						<SidebarMenuItem>
-							<SidebarMenuButton>
-								<GearIcon /> Settings
-							</SidebarMenuButton>
-						</SidebarMenuItem>
-					</SidebarMenu>
-				</SidebarFooter>
-			</Sidebar>
-		</div>
-	</SidebarProvider>
-);

.design-sync/previews/Skeleton.tsx

@@ -1,41 +0,0 @@
-import type * as React from "react";
-import { Skeleton } from "@reactive-resume/ui/components/skeleton";
-
-const pad: React.CSSProperties = { padding: 20 };
-
-export const TextLines = () => (
-	<div style={{ ...pad, display: "flex", flexDirection: "column", gap: 10, width: 320 }}>
-		<Skeleton style={{ height: 12, width: "70%" }} />
-		<Skeleton style={{ height: 12, width: "100%" }} />
-		<Skeleton style={{ height: 12, width: "90%" }} />
-		<Skeleton style={{ height: 12, width: "40%" }} />
-	</div>
-);
-
-export const ProfileHeader = () => (
-	<div style={{ ...pad, display: "flex", alignItems: "center", gap: 14 }}>
-		<Skeleton style={{ height: 48, width: 48, borderRadius: "9999px" }} />
-		<div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
-			<Skeleton style={{ height: 14, width: 160 }} />
-			<Skeleton style={{ height: 12, width: 100 }} />
-		</div>
-	</div>
-);
-
-export const ResumeCard = () => (
-	<div
-		style={{
-			...pad,
-			display: "flex",
-			flexDirection: "column",
-			gap: 12,
-			width: 220,
-			border: "1px solid var(--border)",
-			borderRadius: 12,
-		}}
-	>
-		<Skeleton style={{ height: 140, width: "100%" }} />
-		<Skeleton style={{ height: 14, width: "60%" }} />
-		<Skeleton style={{ height: 12, width: "40%" }} />
-	</div>
-);

.design-sync/previews/Slider.tsx

@@ -1,33 +0,0 @@
-import type * as React from "react";
-import { Label } from "@reactive-resume/ui/components/label";
-import { Slider } from "@reactive-resume/ui/components/slider";
-
-const field: React.CSSProperties = { display: "flex", flexDirection: "column", gap: 10, padding: 16, width: 320 };
-
-export const Single = () => (
-	<div style={field}>
-		<Label>Skill level</Label>
-		<Slider defaultValue={[4]} min={0} max={5} step={1} />
-	</div>
-);
-
-export const Range = () => (
-	<div style={field}>
-		<Label>Experience (years)</Label>
-		<Slider defaultValue={[2, 8]} min={0} max={15} step={1} />
-	</div>
-);
-
-export const FontScale = () => (
-	<div style={field}>
-		<Label>Font size</Label>
-		<Slider defaultValue={[62]} min={0} max={100} />
-	</div>
-);
-
-export const Disabled = () => (
-	<div style={field}>
-		<Label style={{ opacity: 0.5 }}>Line height (locked)</Label>
-		<Slider defaultValue={[50]} min={0} max={100} disabled />
-	</div>
-);

.design-sync/previews/Spinner.tsx

@@ -1,35 +0,0 @@
-import type * as React from "react";
-import { Spinner } from "@reactive-resume/ui/components/spinner";
-
-const row: React.CSSProperties = { display: "flex", alignItems: "center", gap: 20, padding: 24 };
-
-export const Sizes = () => (
-	<div style={row}>
-		<Spinner style={{ width: 16, height: 16 }} />
-		<Spinner style={{ width: 24, height: 24 }} />
-		<Spinner style={{ width: 32, height: 32 }} />
-	</div>
-);
-
-export const Colors = () => (
-	<div style={row}>
-		<Spinner style={{ width: 28, height: 28, color: "var(--primary)" }} />
-		<Spinner style={{ width: 28, height: 28, color: "var(--muted-foreground)" }} />
-	</div>
-);
-
-export const LoadingRow = () => (
-	<div
-		style={{
-			display: "flex",
-			alignItems: "center",
-			gap: 10,
-			padding: 20,
-			fontSize: 13,
-			color: "var(--muted-foreground)",
-		}}
-	>
-		<Spinner style={{ width: 18, height: 18 }} />
-		<span>Generating your PDF…</span>
-	</div>
-);

.design-sync/previews/Switch.tsx

@@ -1,40 +0,0 @@
-import type * as React from "react";
-import { Label } from "@reactive-resume/ui/components/label";
-import { Switch } from "@reactive-resume/ui/components/switch";
-
-const row: React.CSSProperties = { display: "flex", alignItems: "center", gap: 10, padding: 16, width: 300 };
-const stack: React.CSSProperties = { display: "flex", flexDirection: "column", gap: 16, padding: 16, width: 300 };
-
-export const On = () => (
-	<div style={row}>
-		<Switch id="sw-public" defaultChecked />
-		<Label htmlFor="sw-public">Public resume</Label>
-	</div>
-);
-
-export const Off = () => (
-	<div style={row}>
-		<Switch id="sw-template" />
-		<Label htmlFor="sw-template">Show icons in template</Label>
-	</div>
-);
-
-export const Small = () => (
-	<div style={row}>
-		<Switch id="sw-page-numbers" size="sm" defaultChecked />
-		<Label htmlFor="sw-page-numbers">Show page numbers</Label>
-	</div>
-);
-
-export const Disabled = () => (
-	<div style={stack}>
-		<div style={{ display: "flex", alignItems: "center", gap: 10 }}>
-			<Switch id="sw-ai" disabled defaultChecked />
-			<Label htmlFor="sw-ai">AI suggestions</Label>
-		</div>
-		<div style={{ display: "flex", alignItems: "center", gap: 10 }}>
-			<Switch id="sw-index" disabled />
-			<Label htmlFor="sw-index">Index on search engines</Label>
-		</div>
-	</div>
-);

.design-sync/previews/Tabs.tsx

@@ -1,57 +0,0 @@
-import type * as React from "react";
-import { BriefcaseIcon, GraduationCapIcon, SparkleIcon } from "@phosphor-icons/react";
-import { Tabs, TabsContent, TabsList, TabsTrigger } from "@reactive-resume/ui/components/tabs";
-
-const wrap: React.CSSProperties = { width: 460, padding: 16 };
-const panel: React.CSSProperties = { padding: "12px 4px", lineHeight: 1.6 };
-
-export const ResumeSections = () => (
-	<div style={wrap}>
-		<Tabs defaultValue="experience">
-			<TabsList>
-				<TabsTrigger value="experience">
-					<BriefcaseIcon /> Experience
-				</TabsTrigger>
-				<TabsTrigger value="education">
-					<GraduationCapIcon /> Education
-				</TabsTrigger>
-				<TabsTrigger value="skills">
-					<SparkleIcon /> Skills
-				</TabsTrigger>
-			</TabsList>
-			<TabsContent value="experience" style={panel}>
-				<strong>Staff Engineer · Vercel</strong>
-				<div>Owned the edge runtime rollout serving 2B requests per day.</div>
-			</TabsContent>
-			<TabsContent value="education" style={panel}>
-				<strong>M.S. Computer Science · Carnegie Mellon</strong>
-				<div>Focus on distributed systems and human-computer interaction.</div>
-			</TabsContent>
-			<TabsContent value="skills" style={panel}>
-				<strong>Core stack</strong>
-				<div>TypeScript, React, Go, PostgreSQL, and Kubernetes.</div>
-			</TabsContent>
-		</Tabs>
-	</div>
-);
-
-export const LineVariant = () => (
-	<div style={wrap}>
-		<Tabs defaultValue="preview">
-			<TabsList variant="line">
-				<TabsTrigger value="preview">Preview</TabsTrigger>
-				<TabsTrigger value="share">Share</TabsTrigger>
-				<TabsTrigger value="export">Export</TabsTrigger>
-			</TabsList>
-			<TabsContent value="preview" style={panel}>
-				Your resume renders live as you edit each section.
-			</TabsContent>
-			<TabsContent value="share" style={panel}>
-				Publish a public link at reactive-resume.app/u/your-name.
-			</TabsContent>
-			<TabsContent value="export" style={panel}>
-				Download a print-ready PDF or DOCX in one click.
-			</TabsContent>
-		</Tabs>
-	</div>
-);

.design-sync/previews/Textarea.tsx

@@ -1,37 +0,0 @@
-import type * as React from "react";
-import { Label } from "@reactive-resume/ui/components/label";
-import { Textarea } from "@reactive-resume/ui/components/textarea";
-
-const field: React.CSSProperties = { display: "flex", flexDirection: "column", gap: 6, padding: 16, width: 360 };
-
-export const Default = () => (
-	<div style={field}>
-		<Label htmlFor="summary">Summary</Label>
-		<Textarea id="summary" placeholder="Write a short professional summary…" rows={4} />
-	</div>
-);
-
-export const Filled = () => (
-	<div style={field}>
-		<Label htmlFor="about">About</Label>
-		<Textarea
-			id="about"
-			rows={4}
-			defaultValue="Mathematician and writer, known for early work on Charles Babbage's Analytical Engine and the first published algorithm intended for a machine."
-		/>
-	</div>
-);
-
-export const Invalid = () => (
-	<div style={field}>
-		<Label htmlFor="bio">Biography</Label>
-		<Textarea id="bio" aria-invalid rows={3} defaultValue="Too short." />
-	</div>
-);
-
-export const Disabled = () => (
-	<div style={field}>
-		<Label htmlFor="notes">Internal notes</Label>
-		<Textarea id="notes" disabled rows={3} defaultValue="Notes are locked while this resume is published." />
-	</div>
-);

.design-sync/previews/Toaster.tsx

@@ -1,19 +0,0 @@
-import { useEffect } from "react";
-import { toast } from "sonner";
-import { Toaster } from "@reactive-resume/ui/components/sonner";
-
-// Toaster is the toast host. Fire a persistent toast on mount so the card
-// shows a real notification instead of an empty portal.
-export const Notification = () => {
-	useEffect(() => {
-		toast.success("Resume published", {
-			description: "“Software Engineer” is now live at rxresume.me/jane-doe.",
-			duration: Number.POSITIVE_INFINITY,
-		});
-	}, []);
-	return (
-		<div style={{ minHeight: 140 }}>
-			<Toaster position="top-center" />
-		</div>
-	);
-};

.design-sync/previews/Toggle.tsx

@@ -1,66 +0,0 @@
-import type * as React from "react";
-import {
-	TextAlignCenterIcon,
-	TextAlignLeftIcon,
-	TextAlignRightIcon,
-	TextBolderIcon,
-	TextItalicIcon,
-	TextUnderlineIcon,
-} from "@phosphor-icons/react";
-import { Toggle } from "@reactive-resume/ui/components/toggle";
-
-const row: React.CSSProperties = { display: "flex", alignItems: "center", gap: 8, padding: 16 };
-const group: React.CSSProperties = { display: "flex", alignItems: "center", gap: 2, padding: 16 };
-
-export const States = () => (
-	<div style={row}>
-		<Toggle aria-label="Bold" defaultPressed>
-			<TextBolderIcon />
-		</Toggle>
-		<Toggle aria-label="Italic">
-			<TextItalicIcon />
-		</Toggle>
-		<Toggle aria-label="Underline" disabled>
-			<TextUnderlineIcon />
-		</Toggle>
-	</div>
-);
-
-export const Outline = () => (
-	<div style={row}>
-		<Toggle variant="outline" defaultPressed>
-			<TextBolderIcon /> Bold
-		</Toggle>
-		<Toggle variant="outline">
-			<TextItalicIcon /> Italic
-		</Toggle>
-	</div>
-);
-
-export const Sizes = () => (
-	<div style={row}>
-		<Toggle size="sm" aria-label="Bold small">
-			<TextBolderIcon />
-		</Toggle>
-		<Toggle size="default" aria-label="Bold default" defaultPressed>
-			<TextBolderIcon />
-		</Toggle>
-		<Toggle size="lg" aria-label="Bold large">
-			<TextBolderIcon />
-		</Toggle>
-	</div>
-);
-
-export const AlignmentGroup = () => (
-	<div style={group}>
-		<Toggle variant="outline" aria-label="Align left" defaultPressed>
-			<TextAlignLeftIcon />
-		</Toggle>
-		<Toggle variant="outline" aria-label="Align center">
-			<TextAlignCenterIcon />
-		</Toggle>
-		<Toggle variant="outline" aria-label="Align right">
-			<TextAlignRightIcon />
-		</Toggle>
-	</div>
-);

.design-sync/previews/Tooltip.tsx

@@ -1,18 +0,0 @@
-import { InfoIcon } from "@phosphor-icons/react";
-import { Button } from "@reactive-resume/ui/components/button";
-import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@reactive-resume/ui/components/tooltip";
-
-// Anchored overlay — needs TooltipProvider; rendered open (defaultOpen).
-// cfg.overrides.Tooltip pins cardMode: single + viewport with room above the trigger.
-export const Open = () => (
-	<TooltipProvider>
-		<div style={{ display: "flex", justifyContent: "center", paddingTop: 120, paddingBottom: 24 }}>
-			<Tooltip defaultOpen>
-				<TooltipTrigger render={<Button variant="outline" size="icon" aria-label="About visibility" />}>
-					<InfoIcon />
-				</TooltipTrigger>
-				<TooltipContent>Only you can see private resumes</TooltipContent>
-			</Tooltip>
-		</div>
-	</TooltipProvider>
-);

.design-sync/tw-entry.css

@@ -1,4 +0,0 @@
-/* design-sync Tailwind entry — compiles the UI package's globals.css to static CSS
-   for preview rendering, and also scans authored previews for used utilities. */
-@import "../packages/ui/src/styles/globals.css";
-@source "./previews/*.tsx";

.env.example

@@ -9,11 +9,26 @@ SERVER_PORT="3001"
 # OpenGraph metadata, and absolute upload URLs.
 APP_URL="http://localhost:3000"
 
+# Optional: serve one already-public resume at /. Use the ID from /builder/<id>.
+# Unset or blank keeps the marketing home. Restart after changes.
+# ROOT_RESUME_ID=
+
+# Vercel: APP_URL can be omitted; production uses VERCEL_PROJECT_PRODUCTION_URL.
+
 # --- Database (PostgreSQL) ---
 # PostgreSQL connection URL. In Docker Compose, the hostname is usually `postgres`;
 # when running directly on your machine, `localhost` is typical.
 DATABASE_URL="postgresql://postgres:postgres@postgres:5432/postgres"
 
+# Optional direct connection for migrations (Neon: DATABASE_URL_UNPOOLED alias).
+# DATABASE_MIGRATION_URL=""
+# DATABASE_POOL_MAX="10"
+
+# When "true", the server refuses to boot if the live database schema has drifted from
+# the migration ledger (e.g. a table dropped outside migrations). Default "false" logs
+# the drift loudly at startup and continues.
+STRICT_SCHEMA_CHECK="false"
+
 # --- Authentication ---
 # Generated using `openssl rand -hex 32`
 AUTH_SECRET="change-me-to-a-secure-secret-key-in-production"
@@ -62,7 +77,15 @@ SMTP_FROM="Reactive Resume <noreply@rxresu.me>"
 SMTP_SECURE="false"
 
 # --- Storage (optional) ---
-# If all S3 keys are disabled, the app uses local filesystem storage instead.
+# Backend defaults to S3 when all credentials are present, otherwise local.
+# Vercel defaults to private Blob. Explicit selection: local, s3, blob.
+# STORAGE_BACKEND="local"
+# BLOB_READ_WRITE_TOKEN=""
+# BLOB_STORE_ID=""
+# DEPLOYMENT_NAMESPACE="default"
+# Vercel previews need isolated resources before setting ALLOW_PREVIEW_MIGRATIONS=true.
+
+# If all S3 keys are disabled, Docker uses local filesystem storage instead.
 # Make sure to mount this directory to a volume or the host filesystem to ensure data integrity.
 # LOCAL_STORAGE_PATH overrides where local uploads/cache are written.
 # Defaults to /app/data in the official Docker image; in dev, defaults to <workspace>/data.
@@ -77,7 +100,9 @@ S3_BUCKET="reactive-resume"
 S3_FORCE_PATH_STYLE="true"
 
 # --- AI Agent Workspace (optional) ---
-# Required only for the authenticated /agent workspace and saved AI providers.
+# Required for the authenticated /agent workspace and saved AI providers.
+# Redis also shares rate limits, resume events, cancellation and view deduplication.
+# Vercel Upstash KV_URL is accepted as an alias for REDIS_URL.
 REDIS_URL="redis://redis:6379"
 ENCRYPTION_SECRET="change-me-to-a-secure-agent-secret-in-production"
 
@@ -97,8 +122,6 @@ FLAG_DISABLE_IMAGE_PROCESSING="false"
 # Rate limiting is enabled by default in production to prevent abuse.
 FLAG_DISABLE_API_RATE_LIMIT="false"
 
-# This flag shows sponsor placements on the public landing page.
-FLAG_SHOW_SPONSORS="false"
 
 # Allows dynamic OAuth client registration to use any parseable redirect URI,
 # including custom schemes, private hosts, and non-loopback http:// URLs.

.github/.well-known/funding.json

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

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

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

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

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

.github/ISSUE_TEMPLATE/config.yml

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

.github/copilot-instructions.md

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

.github/workflows/autofix.yml

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

.github/workflows/crowdin-sync.yml

@@ -10,7 +10,7 @@ concurrency:
 
 jobs:
   crowdin-sync:
-    runs-on: ubuntu-latest
+    runs-on: ${{ vars.USE_BLACKSMITH == 'true' && 'blacksmith-2vcpu-ubuntu-2404' || 'ubuntu-latest' }}
 
     permissions:
       contents: write
@@ -18,8 +18,16 @@ jobs:
 
     steps:
       - name: Checkout Repository
+        if: ${{ vars.USE_BLACKSMITH != 'true' }}
         uses: actions/checkout@v6
 
+      # The Crowdin action runs in a container that cannot reach the git mirror mount, so copy its objects.
+      - name: Checkout Repository (Blacksmith)
+        if: ${{ vars.USE_BLACKSMITH == 'true' }}
+        uses: useblacksmith/checkout@v1
+        with:
+          dissociate: true
+
       - name: Sync Translations from Crowdin
         uses: crowdin/github-action@v2
         with:

.github/workflows/docker-build.yml

@@ -2,6 +2,11 @@ name: Build Docker Image
 
 on:
   workflow_dispatch:
+    inputs:
+      release:
+        description: Publish release aliases and redeploy production (false runs a cache-only build, then publishes a canary)
+        type: boolean
+        default: false
   push:
     branches:
       - main
@@ -13,30 +18,39 @@ concurrency:
   cancel-in-progress: true
 
 env:
-  IMAGE: ${{ github.repository }}
+  GHCR_IMAGE: ghcr.io/${{ github.repository }}
+  DOCKER_IMAGE: docker.io/amruthpillai/reactive-resume
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
   mode:
-    runs-on: ubuntu-latest
+    runs-on: ${{ vars.USE_BLACKSMITH == 'true' && 'blacksmith-2vcpu-ubuntu-2404' || 'ubuntu-latest' }}
 
     outputs:
       nightly: ${{ steps.mode.outputs.nightly }}
       release: ${{ steps.mode.outputs.release }}
-      matrix: ${{ steps.mode.outputs.matrix }}
+      canary: ${{ steps.mode.outputs.canary }}
 
     steps:
       - name: Determine publishing mode
         id: mode
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          GIT_REF: ${{ github.ref }}
+          RELEASE: ${{ inputs.release }}
         run: |
-          if [[ "${{ github.event_name }}" == "push" && "${{ github.ref }}" == "refs/heads/main" ]]; then
+          if [[ "$EVENT_NAME" == "push" && "$GIT_REF" == "refs/heads/main" ]]; then
             echo "nightly=true" >> "$GITHUB_OUTPUT"
             echo "release=false" >> "$GITHUB_OUTPUT"
-            echo 'matrix={"include":[{"platform":"linux/amd64","runner":"ubuntu-latest","arch":"amd64"}]}' >> "$GITHUB_OUTPUT"
+            echo "canary=false" >> "$GITHUB_OUTPUT"
+          elif [[ "$EVENT_NAME" == "workflow_dispatch" && "$RELEASE" != "true" ]]; then
+            echo "nightly=false" >> "$GITHUB_OUTPUT"
+            echo "release=false" >> "$GITHUB_OUTPUT"
+            echo "canary=true" >> "$GITHUB_OUTPUT"
           else
             echo "nightly=false" >> "$GITHUB_OUTPUT"
             echo "release=true" >> "$GITHUB_OUTPUT"
-            echo 'matrix={"include":[{"platform":"linux/amd64","runner":"ubuntu-latest","arch":"amd64"},{"platform":"linux/arm64","runner":"ubuntu-24.04-arm","arch":"arm64"}]}' >> "$GITHUB_OUTPUT"
+            echo "canary=false" >> "$GITHUB_OUTPUT"
           fi
 
   build:
@@ -44,7 +58,14 @@ jobs:
 
     strategy:
       fail-fast: false
-      matrix: ${{ fromJSON(needs.mode.outputs.matrix) }}
+      matrix:
+        include:
+          - platform: linux/amd64
+            runner: ${{ vars.USE_BLACKSMITH == 'true' && 'blacksmith-32vcpu-ubuntu-2404' || 'ubuntu-latest' }}
+            arch: amd64
+          - platform: linux/arm64
+            runner: ${{ vars.USE_BLACKSMITH == 'true' && 'blacksmith-32vcpu-ubuntu-2404-arm' || 'ubuntu-24.04-arm' }}
+            arch: arm64
 
     runs-on: ${{ matrix.runner }}
     timeout-minutes: 30
@@ -57,16 +78,53 @@ jobs:
 
     steps:
       - name: Checkout Repository
+        if: ${{ vars.USE_BLACKSMITH != 'true' }}
         uses: actions/checkout@v6
 
-      - name: Get version from package.json
-        id: version
-        run: echo "version=$(jq -r .version package.json)" >> "$GITHUB_OUTPUT"
+      - name: Checkout Repository (Blacksmith)
+        if: ${{ vars.USE_BLACKSMITH == 'true' }}
+        uses: useblacksmith/checkout@v1
 
       - name: Setup Docker Buildx
+        if: ${{ vars.USE_BLACKSMITH != 'true' }}
         uses: docker/setup-buildx-action@v4
 
+      # Persists BuildKit layers and the Dockerfile's pnpm cache mounts between runs, one cache per architecture.
+      - name: Setup Docker Builder (Blacksmith)
+        if: ${{ vars.USE_BLACKSMITH == 'true' }}
+        uses: useblacksmith/setup-docker-builder@v2
+        with:
+          cache-key: Dockerfile-${{ matrix.arch }}
+
+      - &registries
+        name: Determine registries
+        id: registries
+        env:
+          DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
+          DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
+        run: |
+          set -euo pipefail
+
+          dockerhub=false
+          ghcr_image="${GHCR_IMAGE,,}"
+          docker_image="${DOCKER_IMAGE,,}"
+          images="$ghcr_image"
+          if [[ -n "$DOCKER_USERNAME" && -n "$DOCKER_PASSWORD" ]]; then
+            dockerhub=true
+            images="${images}"$'\n'"$docker_image"
+          fi
+
+          {
+            echo "ghcr_image=$ghcr_image"
+            echo "docker_image=$docker_image"
+            echo "images<<EOF"
+            echo "$images"
+            echo "EOF"
+            echo "dockerhub=$dockerhub"
+          } >> "$GITHUB_OUTPUT"
+
       - name: Login to Docker Hub
+        if: ${{ steps.registries.outputs.dockerhub == 'true' }}
         uses: docker/login-action@v4
         with:
           username: ${{ secrets.DOCKER_USERNAME }}
@@ -83,16 +141,28 @@ jobs:
         id: meta
         uses: docker/metadata-action@v6
         with:
-          images: |
-            ghcr.io/${{ env.IMAGE }}
-            docker.io/${{ env.IMAGE }}
+          images: ${{ steps.registries.outputs.images }}
           tags: |
             type=sha,prefix=sha-,suffix=-${{ matrix.arch }}
 
+      - name: Cache-only smoke build
+        if: ${{ needs.mode.outputs.canary == 'true' && vars.USE_BLACKSMITH != 'true' }}
+        uses: docker/build-push-action@v7
+        with: &cache-only-build
+          context: .
+          platforms: ${{ matrix.platform }}
+          outputs: type=cacheonly
+
+      - name: Cache-only smoke build (Blacksmith)
+        if: ${{ needs.mode.outputs.canary == 'true' && vars.USE_BLACKSMITH == 'true' }}
+        uses: useblacksmith/build-push-action@v2
+        with: *cache-only-build
+
       - name: Build and Push by Digest
         id: build
+        if: ${{ vars.USE_BLACKSMITH != 'true' }}
         uses: docker/build-push-action@v7
-        with:
+        with: &build-push
           context: .
           sbom: true
           push: true
@@ -101,13 +171,17 @@ jobs:
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
           annotations: ${{ steps.meta.outputs.annotations }}
-          cache-from: type=gha,scope=${{ env.IMAGE }}-${{ matrix.arch }}
-          cache-to: type=gha,mode=max,scope=${{ env.IMAGE }}-${{ matrix.arch }}
+
+      - name: Build and Push by Digest (Blacksmith)
+        id: build-blacksmith
+        if: ${{ vars.USE_BLACKSMITH == 'true' }}
+        uses: useblacksmith/build-push-action@v2
+        with: *build-push
 
       - name: Export digest
         run: |
           mkdir -p /tmp/digests
-          digest="${{ steps.build.outputs.digest }}"
+          digest="${{ steps.build.outputs.digest || steps.build-blacksmith.outputs.digest }}"
           touch "/tmp/digests/${digest#sha256:}"
 
       - name: Upload digest
@@ -123,7 +197,11 @@ jobs:
       - mode
       - build
     timeout-minutes: 30
-    runs-on: ubuntu-latest
+    runs-on: ${{ vars.USE_BLACKSMITH == 'true' && 'blacksmith-2vcpu-ubuntu-2404' || 'ubuntu-latest' }}
+
+    env:
+      DEPLOY: ${{ secrets.SSH_KEY != '' && secrets.SSH_HOST != '' && secrets.SSH_USER != '' }}
+      PURGE_CLOUDFLARE: ${{ secrets.CLOUDFLARE_ZONE_ID != '' && secrets.CLOUDFLARE_API_TOKEN != '' }}
 
     permissions:
       contents: read
@@ -133,11 +211,17 @@ jobs:
 
     steps:
       - name: Checkout Repository
+        if: ${{ vars.USE_BLACKSMITH != 'true' }}
         uses: actions/checkout@v6
-        with:
+        with: &checkout-package-json
           sparse-checkout: package.json
           sparse-checkout-cone-mode: false
 
+      - name: Checkout Repository (Blacksmith)
+        if: ${{ vars.USE_BLACKSMITH == 'true' }}
+        uses: useblacksmith/checkout@v1
+        with: *checkout-package-json
+
       - name: Get version from package.json
         id: version
         run: echo "version=$(jq -r .version package.json)" >> "$GITHUB_OUTPUT"
@@ -152,7 +236,10 @@ jobs:
       - name: Setup Docker Buildx
         uses: docker/setup-buildx-action@v4
 
+      - *registries
+
       - name: Login to Docker Hub
+        if: ${{ steps.registries.outputs.dockerhub == 'true' }}
         uses: docker/login-action@v4
         with:
           username: ${{ secrets.DOCKER_USERNAME }}
@@ -179,11 +266,10 @@ jobs:
         id: meta
         uses: docker/metadata-action@v6
         with:
-          images: |
-            ghcr.io/${{ env.IMAGE }}
-            docker.io/${{ env.IMAGE }}
+          images: ${{ steps.registries.outputs.images }}
           tags: |
             type=sha,prefix=sha-
+            type=raw,value=canary-${{ github.run_id }}-${{ github.run_attempt }},enable=${{ needs.mode.outputs.canary == 'true' }}
             type=raw,value=nightly,enable=${{ needs.mode.outputs.nightly == 'true' }}
             type=raw,value=nightly-{{date 'YYYYMMDDHHmmss' tz='UTC'}},enable=${{ needs.mode.outputs.nightly == 'true' }}
             type=raw,value=latest,enable=${{ needs.mode.outputs.release == 'true' }}
@@ -199,6 +285,8 @@ jobs:
 
           if [[ "${{ needs.mode.outputs.nightly }}" == "true" ]]; then
             FINAL_TAG="nightly"
+          elif [[ "${{ needs.mode.outputs.canary }}" == "true" ]]; then
+            FINAL_TAG="canary-${{ github.run_id }}-${{ github.run_attempt }}"
           else
             FINAL_TAG="v${{ steps.version.outputs.version }}"
           fi
@@ -211,17 +299,19 @@ jobs:
             --annotation "index:org.opencontainers.image.vendor=Amruth Pillai" \
             --annotation "index:org.opencontainers.image.url=https://rxresu.me" \
             --annotation "index:org.opencontainers.image.documentation=https://docs.rxresu.me" \
-            --annotation "index:org.opencontainers.image.source=https://github.com/amruthpillai/reactive-resume" \
+            --annotation "index:org.opencontainers.image.source=https://github.com/${{ github.repository }}" \
             --annotation "index:org.opencontainers.image.version=${{ steps.version.outputs.version }}" \
-            $(printf 'ghcr.io/${{ env.IMAGE }}@sha256:%s ' *) \
-            $(printf 'docker.io/${{ env.IMAGE }}@sha256:%s ' *)
+            $(printf '${{ steps.registries.outputs.ghcr_image }}@sha256:%s ' *)
 
           # Get the digest of the multi-arch manifest
-          GHCR_DIGEST=$(docker buildx imagetools inspect ghcr.io/${{ env.IMAGE }}:${FINAL_TAG} --format '{{json .Manifest.Digest}}' | tr -d '"')
-          DOCKER_DIGEST=$(docker buildx imagetools inspect docker.io/${{ env.IMAGE }}:${FINAL_TAG} --format '{{json .Manifest.Digest}}' | tr -d '"')
+          GHCR_DIGEST=$(docker buildx imagetools inspect ${{ steps.registries.outputs.ghcr_image }}:${FINAL_TAG} --format '{{json .Manifest.Digest}}' | tr -d '"')
           echo "final_tag=$FINAL_TAG" >> "$GITHUB_OUTPUT"
           echo "ghcr_digest=$GHCR_DIGEST" >> "$GITHUB_OUTPUT"
-          echo "docker_digest=$DOCKER_DIGEST" >> "$GITHUB_OUTPUT"
+
+          if [[ "${{ steps.registries.outputs.dockerhub }}" == "true" ]]; then
+            DOCKER_DIGEST=$(docker buildx imagetools inspect ${{ steps.registries.outputs.docker_image }}:${FINAL_TAG} --format '{{json .Manifest.Digest}}' | tr -d '"')
+            echo "docker_digest=$DOCKER_DIGEST" >> "$GITHUB_OUTPUT"
+          fi
 
       - name: Install Cosign
         uses: sigstore/cosign-installer@v3
@@ -229,18 +319,40 @@ jobs:
       - name: Sign images with Cosign
         run: |
           # Sign GHCR image
-          cosign sign --yes ghcr.io/${{ env.IMAGE }}@${{ steps.manifest.outputs.ghcr_digest }}
+          cosign sign --yes ${{ steps.registries.outputs.ghcr_image }}@${{ steps.manifest.outputs.ghcr_digest }}
 
-          # Sign Docker Hub image
-          cosign sign --yes docker.io/${{ env.IMAGE }}@${{ steps.manifest.outputs.docker_digest }}
+          if [[ "${{ steps.registries.outputs.dockerhub }}" == "true" ]]; then
+            # Sign Docker Hub image
+            cosign sign --yes ${{ steps.registries.outputs.docker_image }}@${{ steps.manifest.outputs.docker_digest }}
+          fi
 
       - name: Inspect image
         run: |
-          docker buildx imagetools inspect ghcr.io/${{ env.IMAGE }}:${{ steps.manifest.outputs.final_tag }}
-          docker buildx imagetools inspect docker.io/${{ env.IMAGE }}:${{ steps.manifest.outputs.final_tag }}
+          docker buildx imagetools inspect ${{ steps.registries.outputs.ghcr_image }}:${{ steps.manifest.outputs.final_tag }}
+          if [[ "${{ steps.registries.outputs.dockerhub }}" == "true" ]]; then
+            docker buildx imagetools inspect ${{ steps.registries.outputs.docker_image }}:${{ steps.manifest.outputs.final_tag }}
+          fi
+
+      - name: Verify anonymous pulls on both architectures
+        run: |
+          set -euo pipefail
+          registry_config=$(mktemp -d)
+          trap 'rm -rf "$registry_config"' EXIT
+          # Prevent Docker from discovering a system credential helper.
+          printf '%s\n' '{"auths":{"ghcr.io":{},"https://index.docker.io/v1/":{}}}' > "$registry_config/config.json"
+          images=("${{ steps.registries.outputs.ghcr_image }}")
+          if [[ "${{ steps.registries.outputs.dockerhub }}" == "true" ]]; then
+            images+=("${{ steps.registries.outputs.docker_image }}")
+          fi
+          for image in "${images[@]}"; do
+            for platform in linux/amd64 linux/arm64; do
+              docker --config "$registry_config" pull --quiet --platform "$platform" \
+                "$image:${{ steps.manifest.outputs.final_tag }}"
+            done
+          done
 
       - name: Redeploy Stack
-        if: ${{ needs.mode.outputs.release == 'true' }}
+        if: ${{ needs.mode.outputs.release == 'true' && env.DEPLOY == 'true' }}
         uses: appleboy/ssh-action@v1
         with:
           key: ${{ secrets.SSH_KEY }}
@@ -251,7 +363,7 @@ jobs:
             ./manage_stack.sh up reactive_resume
 
       - name: Purge Cloudflare cache
-        if: ${{ needs.mode.outputs.release == 'true' }}
+        if: ${{ needs.mode.outputs.release == 'true' && env.PURGE_CLOUDFLARE == 'true' }}
         env:
           CLOUDFLARE_ZONE_ID: ${{ secrets.CLOUDFLARE_ZONE_ID }}
           CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}

.github/workflows/e2e.yml

@@ -17,10 +17,16 @@ env:
   FLAG_DISABLE_EMAIL_AUTH: "false"
   FLAG_DISABLE_API_RATE_LIMIT: "true"
   LOCAL_STORAGE_PATH: /tmp/reactive-resume-e2e-storage
+  # The assistant spec talks to a scripted provider on 127.0.0.1.
+  FLAG_ALLOW_UNSAFE_AI_BASE_URL: "true"
+  # Real-database unit suites. The cover-letter suite works in its own schema; the OAuth flow suite writes
+  # signing keys under its own secret, so it gets a database the e2e server never reads.
+  COVER_LETTER_TEST_DATABASE_URL: postgresql://postgres:postgres@localhost:5432/postgres
+  OAUTH_TEST_DATABASE_URL: postgresql://postgres:postgres@localhost:5432/oauth_test
 
 jobs:
   e2e:
-    runs-on: ubuntu-latest
+    runs-on: ${{ vars.USE_BLACKSMITH == 'true' && 'blacksmith-32vcpu-ubuntu-2404' || 'ubuntu-latest' }}
     timeout-minutes: 30
 
     services:
@@ -40,26 +46,31 @@ jobs:
 
     steps:
       - name: Checkout Repository
+        if: ${{ vars.USE_BLACKSMITH != 'true' }}
         uses: actions/checkout@v6
         with:
           persist-credentials: false
 
+      - name: Checkout Repository (Blacksmith)
+        if: ${{ vars.USE_BLACKSMITH == 'true' }}
+        uses: useblacksmith/checkout@v1
+        with:
+          persist-credentials: false
+
       - name: Install pnpm
         uses: pnpm/action-setup@v6
 
       - name: Setup Node
         uses: actions/setup-node@v6
         with:
-          node-version: "24"
+          node-version-file: ".nvmrc"
           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
+        timeout-minutes: 10
         run: pnpm exec playwright install --with-deps chromium
 
       - name: Generate Test Secrets
@@ -73,11 +84,23 @@ jobs:
       - name: Run Database Migrations
         run: pnpm db:migrate
 
+      - name: Prepare OAuth Test Database
+        run: |
+          psql "$DATABASE_URL" -c "CREATE DATABASE oauth_test"
+          DATABASE_URL="$OAUTH_TEST_DATABASE_URL" pnpm db:migrate
+
+      # Runs every workspace package, not a hand-maintained filter list, so a package
+      # cannot silently lose coverage by being left out. Serial execution: the PDF
+      # rasterization and API rate-limit suites time out when several packages' Vitest
+      # thread pools oversubscribe the runner at once.
+      - name: Run Unit Tests
+        run: pnpm exec turbo run test:ci --concurrency=1
+
       - name: Build
         run: pnpm build
 
-      - name: Run Baseline E2E Tests
-        run: pnpm exec playwright test --grep-invert "@semantic-css"
+      - name: Run E2E Tests
+        run: pnpm exec playwright test
 
       - name: Upload Playwright Report
         if: always()

.github/workflows/label-issues.yml

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

.github/workflows/stale-issues.yml

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

.github/workflows/vercel.yml

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

.gitignore

@@ -4,6 +4,7 @@ node_modules
 
 # Build Outputs
 dist
+dist-prerender
 .vercel
 .wrangler
 
@@ -49,23 +50,20 @@ temp
 .agents
 .claude
 .cursor
+.opencode
 .codegraph
 .superpowers
 .worktrees
 .migration
+/plans
 
 # Local Storage Data
 /data
 /apps/web/data
 
+# Redesign handoff (design references, not source)
+/design_handoff_reactive_resume_redesign
+
 # Git Hooks
-.vite-hooks/
-.ds-sync/
-ds-bundle/
-.design-sync/.cache/
-.design-sync/learnings/
-.design-sync/node_modules
-packages/ui/.ds-compiled.css
-packages/ui/.ds-tw-raw.css
-packages/ui/dist/
-i18n.cache
+.vite-hooks
+

.markdownlint-cli2.yaml

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

.ncurc.cjs

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

.nvmrc

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

.superpowers/sdd/pr-3274-review-followups-plan/task-1-report.md

@@ -1,23 +0,0 @@
-# Task 1: Harden public PDF response contract
-
-## Implemented
-
-- Pinned successful public PDF responses to `Content-Type: application/pdf` at the HTTP boundary.
-- Kept `Cache-Control: private, no-store` hardcoded at that boundary for successful, validation-error, and service-error responses.
-- Removed the unused `cacheControl` member from `createPublicResumePdf` and all affected tests/mocks.
-- Updated the route regression to return a `text/plain` file from the service mock while asserting the HTTP response remains `application/pdf`.
-
-## Verification
-
-- `pnpm --filter server test -- src/http/public-resume-pdf.test.ts` — 13 files / 71 tests passed.
-- `dotenvx run -f .env.local -- pnpm exec vitest run packages/api/src/features/resume/public-pdf.test.ts` — 1 file / 7 tests passed.
-- `pnpm exec biome check apps/server/src/http/public-resume-pdf.ts apps/server/src/http/public-resume-pdf.test.ts packages/api/src/features/resume/public-pdf.ts packages/api/src/features/resume/public-pdf.test.ts` — passed.
-- `pnpm --filter server typecheck` and `pnpm --filter @reactive-resume/api typecheck` — passed.
-
-## Note
-
-The API package test script did not scope to the supplied test path and initially ran the package suite, which has two unrelated baseline failures: `src/features/ai/url-policy.test.ts` and `src/features/resume/export.test.ts` (missing required env). The target test was then run directly with `.env.local` and passed.
-
-## Self-review
-
-`git diff --check` passed. The diff is restricted to the public PDF service contract, HTTP response header, and their focused tests.

.vercelignore

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

AGENTS.md

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

DESIGN.md

@@ -1,347 +1,205 @@
 ---
-version: alpha
-name: Reactive Resume
-description: A monochrome, content-first design system for a free and open-source resume builder. Dark-by-default with light mode support.
+version: 6.0.0
+name: Reactive Resume · Desk & Paper
+description: A quiet, warm desk around a bright page. The resume is the only white, detailed object on screen; one moss-green accent marks the next action. Light and dark themes, with the page always white.
 colors:
-  primary: "#343434"
-  primary-foreground: "#FBFBFB"
-  secondary: "#F7F7F7"
-  secondary-foreground: "#343434"
-  background: "#FFFFFF"
-  foreground: "#252525"
-  muted: "#F7F7F7"
-  muted-foreground: "#8E8E8E"
-  card: "#FFFFFF"
-  card-foreground: "#252525"
-  border: "#EBEBEB"
-  input: "#EBEBEB"
-  ring: "#B5B5B5"
-  destructive: "#DC2626"
-  on-destructive: "#FFFFFF"
+  light:
+    bg: "#F8F7F3"
+    surface: "#FEFDFC"
+    raised: "#FFFFFF"
+    sunken: "#F0EFEB"
+    line: "#DFDEDA"
+    line-2: "#C5C4BE"
+    ink: "#1C1B15"
+    ink-2: "#4F4D47"
+    ink-3: "#6D6C65"
+    accent: "#337344"
+    accent-hover: "#206133"
+    on-accent: "#F7FEF8"
+    accent-soft: "#DCF2DF"
+    accent-text: "#195C2E"
+    danger: "#BA3630"
+    danger-soft: "#FFE7E4"
+    danger-text: "#A92321"
+    warn: "#D29922"
+    warn-soft: "#FCEDCD"
+    warn-text: "#81520A"
+    info-soft: "#E0F1FF"
+    info-text: "#1D5B92"
+  dark:
+    bg: "#100F0C"
+    surface: "#171613"
+    raised: "#1F1E1A"
+    sunken: "#0B0A08"
+    line: "#2C2B27"
+    line-2: "#494843"
+    ink: "#EFEEEB"
+    ink-2: "#BCBAB5"
+    ink-3: "#979590"
+    accent: "#6FC082"
+    accent-hover: "#83D494"
+    on-accent: "#07150A"
+    accent-soft: "#1A3520"
+    accent-text: "#8FD89E"
+    danger: "#D9544B"
+    danger-soft: "#47211D"
+    danger-text: "#FDA297"
+    warn: "#E4B750"
+    warn-soft: "#3E2D10"
+    warn-text: "#EFCC83"
+    info-soft: "#192F46"
+    info-text: "#9DC9F7"
+  paper: "#FFFFFF"
+  stages:
+    saved: "#908C7F"
+    applied: "#5590CC"
+    screening: "#00A0A6"
+    interview: "#AF8433"
+    offer: "#579F68"
+    closed: "#C67067"
 typography:
-  heading:
-    fontFamily: IBM Plex Sans Variable
-    fontSize: 1rem
-    fontWeight: 500
-  body:
-    fontFamily: IBM Plex Sans Variable
-    fontSize: 0.875rem
-    fontWeight: 400
-  body-sm:
-    fontFamily: IBM Plex Sans Variable
-    fontSize: 0.75rem
-    fontWeight: 400
-  label:
-    fontFamily: IBM Plex Sans Variable
-    fontSize: 0.8rem
-    fontWeight: 500
-  hero-heading:
-    fontFamily: IBM Plex Sans Variable
-    fontSize: 3.75rem
-    fontWeight: 700
-    letterSpacing: -0.025em
+  display: { fontFamily: Newsreader, fontSize: 44px, lineHeight: 48px, fontWeight: 500, letterSpacing: -0.01em }
+  title: { fontFamily: Newsreader, fontSize: 30px, lineHeight: 36px, fontWeight: 500 }
+  sheet-title: { fontFamily: Newsreader, fontSize: 22px, lineHeight: 28px, fontWeight: 500 }
+  heading: { fontFamily: Hanken Grotesk, fontSize: 20px, lineHeight: 28px, fontWeight: 600 }
+  section-heading: { fontFamily: Hanken Grotesk, fontSize: 17px, lineHeight: 24px, fontWeight: 600 }
+  label: { fontFamily: Hanken Grotesk, fontSize: 15px, lineHeight: 22px, fontWeight: 600 }
+  body: { fontFamily: Hanken Grotesk, fontSize: 15px, lineHeight: 24px, fontWeight: 400 }
+  ui: { fontFamily: Hanken Grotesk, fontSize: 14px, lineHeight: 20px, fontWeight: 400 }
+  small: { fontFamily: Hanken Grotesk, fontSize: 13px, lineHeight: 18px, fontWeight: 400 }
+  caption: { fontFamily: Hanken Grotesk, fontSize: 12px, lineHeight: 16px, fontWeight: 500 }
+  mono: { fontFamily: JetBrains Mono, fontSize: 12px, lineHeight: 16px, fontWeight: 500 }
 rounded:
-  sm: 0.18rem
-  md: 0.24rem
-  lg: 0.3rem
-  xl: 0.42rem
-  2xl: 0.54rem
-  3xl: 0.66rem
-  4xl: 0.78rem
-spacing:
-  xs: 4px
-  sm: 8px
-  md: 16px
-  lg: 24px
-  xl: 32px
-  2xl: 48px
-components:
-  button-default:
-    backgroundColor: "{colors.primary}"
-    textColor: "{colors.primary-foreground}"
-    rounded: "{rounded.lg}"
-    padding: 10px
-    height: 36px
-  button-outline:
-    backgroundColor: "{colors.background}"
-    textColor: "{colors.foreground}"
-    rounded: "{rounded.lg}"
-    padding: 10px
-    height: 36px
-  button-secondary:
-    backgroundColor: "{colors.secondary}"
-    textColor: "{colors.secondary-foreground}"
-    rounded: "{rounded.lg}"
-    padding: 10px
-    height: 36px
-  button-ghost:
-    backgroundColor: "{colors.background}"
-    textColor: "{colors.foreground}"
-    rounded: "{rounded.lg}"
-    padding: 10px
-    height: 36px
-  button-destructive:
-    backgroundColor: "{colors.destructive}"
-    textColor: "{colors.on-destructive}"
-    rounded: "{rounded.lg}"
-    padding: 10px
-    height: 36px
-  card:
-    backgroundColor: "{colors.card}"
-    textColor: "{colors.card-foreground}"
-    rounded: "{rounded.lg}"
-    padding: 16px
-  input:
-    backgroundColor: "{colors.background}"
-    textColor: "{colors.foreground}"
-    rounded: "{rounded.lg}"
-    height: 36px
-    padding: 10px
-  input-focus:
-    backgroundColor: "{colors.background}"
-    textColor: "{colors.foreground}"
-    rounded: "{rounded.lg}"
-    height: 36px
-    padding: 10px
-  badge:
-    backgroundColor: "{colors.primary}"
-    textColor: "{colors.primary-foreground}"
-    rounded: "{rounded.md}"
-    padding: 4px
-  popover:
-    backgroundColor: "{colors.card}"
-    textColor: "{colors.card-foreground}"
-    rounded: "{rounded.xl}"
-    padding: 4px
-  sidebar:
-    backgroundColor: "{colors.muted}"
-    textColor: "{colors.foreground}"
-    padding: 8px
-  sidebar-item:
-    backgroundColor: "{colors.muted}"
-    textColor: "{colors.muted-foreground}"
-    rounded: "{rounded.lg}"
-    padding: 8px
-  sidebar-item-active:
-    backgroundColor: "{colors.primary}"
-    textColor: "{colors.primary-foreground}"
-    rounded: "{rounded.lg}"
-    padding: 8px
-  tooltip:
-    backgroundColor: "{colors.primary}"
-    textColor: "{colors.primary-foreground}"
-    rounded: "{rounded.md}"
-    padding: 6px
-  separator:
-    backgroundColor: "{colors.border}"
-    height: 1px
-  dialog:
-    backgroundColor: "{colors.card}"
-    textColor: "{colors.card-foreground}"
-    rounded: "{rounded.xl}"
-    padding: 24px
-  input-invalid:
-    backgroundColor: "{colors.background}"
-    textColor: "{colors.destructive}"
-    rounded: "{rounded.lg}"
-    height: 36px
-    padding: 10px
+  sm: 6px
+  md: 8px
+  lg: 10px
+  xl: 12px
+  2xl: 16px
+  3xl: 18px
+  full: 999px
+spacing: [4, 8, 12, 16, 24, 32, 48, 64]
+motion:
+  quick: 120ms
+  standard: 200ms
+  emphasized: 320ms
+  easing: cubic-bezier(0.2, 0.8, 0.2, 1)
+  exit: 70% of the entering duration
 ---
 
 ## Overview
 
-Reactive Resume is a monochrome, content-first design system built for a resume builder used by tens of thousands of people worldwide. The visual identity prioritizes readability and unobtrusiveness — the user's resume content is always the hero, never the chrome around it.
+Reactive Resume's interface is a quiet, warm desk around a bright page. The resume or letter page is the only white, detailed object on screen; everything around it uses low-contrast warm neutrals, thin rules instead of boxes, and a single moss-green accent.
 
-The system defaults to dark mode with a warm near-black backdrop that makes the resume preview "float" as the visual anchor. Light mode is supported as a full alternative. The authenticated app shell (dashboard, builder, settings) uses an entirely achromatic grayscale palette — the sole chromatic exception is destructive red for dangerous actions. The landing page introduces subtle chromatic accents: blue-tinted spotlight gradients on the hero, a multicolor text-mask animation on hover, and social auth provider brand colors (Google blue, LinkedIn blue) on the login page.
+The full specification lives in the redesign handoff (`design_handoff_reactive_resume_redesign/README.md`, kept out of version control) and the milestone plan in `REDESIGN_PLAN.md`. This document records the rules the code follows.
 
-The overall aesthetic is a professional tool UI: clean grid lines, subtle borders, generous whitespace, and typography that steps back to let the content shine. Think "VS Code meets Figma" — a productivity workspace, not a marketing site.
+Five principles decide most questions:
 
-One deliberate counterpoint to the serious UI: all resume templates are named after Pokemon (Azurill, Bronzor, Chikorita, Ditgar, Gengar, Pikachu, etc.). This is an intentional brand choice — playful naming for templates injects personality into an otherwise utilitarian interface, making templates feel collectible and memorable rather than generic ("Template 1", "Modern", "Classic").
+1. **The page is the interface.** The live page is on screen in every editor mode. Clicking a line on the page opens its field.
+2. **One obvious next step.** Each view has at most one accent-filled button. Accent means "do this next" or "this is working" and is never decoration.
+3. **Nothing is lost.** Everything autosaves and can be undone. Confirmation dialogs are only for irreversible actions.
+4. **Detail on demand.** Defaults cover most people; advanced controls sit one disclosure deeper.
+5. **AI proposes, you decide.** The assistant never writes directly; every change is a reviewable proposal.
 
-## Colors
+Resume templates keep their Pokémon names (Azurill, Onyx, Glalie…), their own fonts and their own colors. None of the rules below apply inside a template.
 
-The palette is rooted in achromatic OKLch values (chroma = 0), producing a pure grayscale scale without warm or cool casts. Colors are defined as CSS custom properties using `oklch()` and consumed through Tailwind CSS 4 theme tokens. Always prefer CSS variables (e.g., `var(--primary)`) or Tailwind tokens (e.g., `bg-primary`) over raw color values. The hex values in this document's YAML front matter are agent-friendly approximations of the canonical OKLch definitions in `packages/ui/src/styles/globals.css` — use hex only where OKLch is unavailable.
+## Tokens
 
-- **Primary (#343434 light / #EBEBEB dark):** Used for high-emphasis interactive surfaces — default buttons, selected states, and text selection. In dark mode this inverts to near-white so buttons remain prominent.
-- **Foreground (#252525 light / #FBFBFB dark):** Body text and headings. High contrast against the background in both themes.
-- **Background (#FFFFFF light / #252525 dark):** The canvas. Pure white in light mode, warm near-black in dark mode.
-- **Card (#FFFFFF light / #343434 dark):** Elevated surface for cards, panels, and the builder sidebar. In dark mode, one step lighter than the background to create subtle depth.
-- **Muted (#F7F7F7 light / #454545 dark):** De-emphasized backgrounds for secondary UI regions, hover states, and inactive tabs.
-- **Muted Foreground (#8E8E8E light / #B5B5B5 dark):** Captions, helper text, timestamps, and metadata. Deliberately low-contrast against the background to recede visually.
-- **Border (#EBEBEB light / white at 10% opacity dark):** Thin separator lines. In dark mode, uses transparent white rather than a solid gray to blend naturally with any underlying surface color.
-- **Input (#EBEBEB light / white at 15% opacity dark):** Form field borders, slightly more prominent than general borders to make input areas discoverable.
-- **Destructive (#DC2626 light / #EF4444 dark):** The only chromatic color in the palette. Reserved exclusively for delete actions, error states, and danger-zone operations. Used at 10% opacity as a background tint with full saturation for text, creating a soft but unmistakable warning.
-- **Ring (#B5B5B5 light / #8E8E8E dark):** Focus ring indicator at 50% opacity, surrounding focused interactive elements.
-- **Sidebar Primary (dark only, #6366F1):** An indigo value inherited from the shadcn/ui defaults. Not actively used in the current UI — sidebar active states use the standard grayscale primary token instead. Retained in the CSS custom properties for potential future customization.
+Tokens are CSS custom properties in `packages/ui/src/styles/globals.css`, light on `:root` and dark on `.dark`. The source of truth is oklch; the hex values above are sRGB approximations. Tailwind exposes each one under the same name: `bg-bg`, `bg-surface`, `bg-raised`, `bg-sunken`, `border-line`, `border-line-2`, `text-ink`, `text-ink-2`, `text-ink-3`, `bg-accent`, `text-on-accent`, `bg-accent-soft`, `text-accent-text`, `bg-danger`, `bg-danger-soft`, `text-danger-text`, `bg-warn`, `bg-warn-soft`, `text-warn-text`, `bg-info-soft`, `text-info-text`, `bg-hover`, `bg-press`, `bg-scrim`, `bg-paper` and `bg-stage-*`.
 
-Resume templates have their own independent color system — users pick primary, text, and background colors per resume through a color picker in the builder's Design panel. These template colors are completely separate from the app shell palette.
+- **Surfaces:** `bg` is the app desk, `surface` holds panels and cards, `raised` holds menus, dialogs and inputs, `sunken` is for wells, tracks and the page canvas.
+- **Text:** `ink` for primary text, `ink-2` for secondary text, `ink-3` for meta and placeholders. `ink-3` is the lightest color allowed for text (about 4.9:1).
+- **Signals:** `danger` for errors and irreversible actions, `warn` for check issues and things to review, `info` for neutral guidance and the assistant's questions. Success uses `accent-soft`.
+- **Overlays:** `hover` and `press` are translucent, so they work on any surface.
+- **Paper:** `--paper` is white in both themes. Pages never invert.
+- **Stages:** application stage colors share lightness and chroma. They appear only as 8px dots or 6px stepper bars, always next to the stage name.
+
+The previous shadcn-style names (`background`, `foreground`, `primary`, `muted`, `border`, `input`, `ring`, `destructive`, `card`, `popover`, `sidebar-*`) still resolve to these tokens so screens that haven't been rebuilt stay legible. Don't use them in new code; they're removed once every screen has moved.
 
 ## Typography
 
-The entire application uses a single typeface: **IBM Plex Sans Variable**. This is a humanist sans-serif with an extensive weight range (100–900) and excellent readability at small sizes, both on screen and in PDFs.
+- **Newsreader** (display serif, optical sizes 6–72) is only for page titles, dialog and sheet titles, empty-state headlines and large stat numerals. Use `font-display`.
+- **Hanken Grotesk** handles everything functional. It's the default `font-sans`.
+- **JetBrains Mono** is for shortcuts, URLs and slugs, file names, counts and section eyebrows. Use `font-mono`.
+- Field labels are 12px, medium weight, `ink-2`, above the control with a 5–6px gap. Uppercase group eyebrows are 12px semibold `ink-3` with 0.02em tracking.
+- Inputs render at 16px on touch devices so iOS doesn't zoom.
+- All three fonts are self-hosted through `@fontsource-variable`.
 
-- **Hero heading (responsive: 2.25rem mobile / 3rem tablet / 3.75rem desktop, weight 700, tracking-tight):** Landing page headline only. Large, bold, and commanding. Scales across three breakpoints.
-- **Section heading (1rem / 16px, weight 500):** Used for section titles in the builder sidebar, settings panels, and dashboard cards. Medium weight provides hierarchy without shouting.
-- **Body (0.875rem / 14px, weight 400):** The workhorse. All form labels, descriptions, card content, and general UI text.
-- **Small body (0.75rem / 12px, weight 400):** Captions, helper text, timestamps, and metadata.
-- **Label (0.8rem / ~13px, weight 500):** Button text, badge labels, and form field labels. Slightly heavier than body to denote interactivity.
+## Iconography
 
-The resume content itself uses a separate font system — users choose from 1,000+ Google Fonts for their resume headings and body text, with category-aware fallback stacks including CJK support (Noto Sans SC, PingFang SC, Hiragino Sans GB for sans-serif; Noto Serif SC, Songti SC for serif). Standard PDF fonts (Helvetica, Courier, Times-Roman) are available as offline fallbacks.
+App icons are **Material Symbols Rounded** at weight 300, rendered by `Icon` from `@reactive-resume/ui/components/icon`. The font is a self-hosted subset that contains only the glyphs listed in `packages/ui/src/icons/names.ts`:
 
-Font rendering uses `antialiased` (grayscale AA) and `proportional-nums` across the board for clean rendering and properly spaced numerals in dates and phone numbers.
+1. Add the name to that list (TypeScript then accepts it in `<Icon name="…" />`).
+2. Run `pnpm icons:build`. The script checks every name against the published codepoints, downloads the subset and updates the manifest. A unit test fails if the manifest and the list disagree.
 
-## Layout
+Rules:
 
-### Builder (Three-Panel Workspace)
+- 20px on desktop, 24px on touch. Outline by default; `filled` only for the selected navigation item.
+- Icons always sit beside a text label, except back, close, more, undo/redo, history, assistant and zoom. Those use `IconButton`, which requires a label and shows it in a tooltip with the shortcut.
+- `Icon` is `aria-hidden` and `translate="no"`, so the ligature text never becomes an accessible name.
+- Directional icons (arrows, chevrons, undo, redo) mirror in right-to-left layouts automatically.
+- Icons inside resumes are a separate system: Phosphor, because resume data stores Phosphor names and the PDF renderer draws them.
 
-The core builder uses a resizable three-panel layout powered by `react-resizable-panels`:
+## Space, shape and elevation
 
-- **Left sidebar (default 22%):** Resume section forms — personal info, experience, education, skills, and custom sections. Scrollable with collapsible section groups.
-- **Center artboard (default 56%):** Live resume preview rendered via PDF.js canvas. Supports zoom, pan, and pinch gestures via `react-zoom-pan-pinch`. The preview maintains A4 aspect ratio (210:297) with a subtle shadow to simulate a physical page.
-- **Right sidebar (default 22%):** Design controls — template picker, font selection, color picker, layout manager (page assignments, section ordering via drag-and-drop).
+- **Spacing** follows a 4pt scale: 4, 8, 12, 16, 24, 32, 48, 64. Cards use 16px padding, panels 16–24px, the mobile margin is 16px and the desktop page margin 32–40px.
+- **Radius:** `rounded-sm` 6px for chips and small buttons, `rounded-md` 8px for controls and inputs, `rounded-lg` 10px for list items, `rounded-xl` 12px for cards and menus, `rounded-2xl` 16px for dialogs, `rounded-3xl` 18px for mobile sheets, `rounded-full` for pills.
+- **Elevation:** `shadow-e1` for cards, `shadow-e2` for menus, popovers and hover-lifted cards, `shadow-e3` for dialogs, sheets and toasts, `shadow-page` for the resume page on the canvas.
+- **Control heights:** 28px small, 36px default, 44px touch. Icon buttons are 32–36px on desktop and 44px on touch.
+- **Layout constants** are CSS variables: `--editor-bar` 56px, `--editor-panel` 400px, `--app-sidebar` 240px, `--sheet-share` 440px, `--sheet-detail` 480px, `--assistant` 400px.
 
-Panel sizes persist in cookies. On mobile (< 768px), sidebars collapse to 0% width and become toggleable overlays (max 95% width when open). The desktop minimum collapsed width is 48px (icon rail).
+## Motion
 
-### Dashboard
+| Token | Duration | Use |
+|---|---|---|
+| `duration-quick` | 120ms | hover, press, toggle, checkbox, focus |
+| `duration-standard` | 200ms | menus, popovers, expand and collapse, mode switch, dialogs |
+| `duration-emphasized` | 320ms | side and bottom sheets, toasts, the assistant column |
 
-Standard sidebar navigation layout using the `Sidebar` component system. The sidebar contains: logo, resume list link, agent link, settings subnavigation (profile, preferences, authentication, API keys, integrations, danger zone), and a footer with user avatar. Content area shows a responsive grid of resume cards.
-
-### Landing Page
-
-Full-width single-column marketing layout:
-1. **Floating builder preview** — A non-interactive screenshot of the builder as a hero visual, creating an immediate "this is what you get" impression.
-2. **Hero** — Centered headline, subheadline, and two CTAs (primary "Get Started" with arrow, ghost "Learn More" with icon).
-3. **Features grid** — 4-column responsive grid with icon + title + description cards, separated by thin border lines.
-4. **Template carousel** — Horizontally scrolling row of template preview thumbnails with Pokemon-themed names.
-5. **Testimonials** — Tiled user quotes in a masonry-style grid.
-6. **Support / FAQ / Footer** — Accordion FAQ, community section, and a 4-column footer with logo, resource links, community links, and license info.
-
-### Responsive Breakpoints
-
-Mobile detection uses a 768px threshold via `MediaQueryList`. The layout is optimized for workspace productivity on larger screens, with responsive mobile support that adapts the multi-panel builder into a streamlined single-panel experience. Both desktop and mobile are supported experiences — the builder's three-panel layout leverages desktop space, while mobile surfaces the same editing capabilities through collapsible overlays.
-
-### Page Aspect Ratio
-
-A custom Tailwind token `--aspect-page: 210 / 297` enforces A4 paper proportions wherever resume pages are rendered (builder preview, public view, PDF export).
-
-## Animation
-
-Animations use the Motion library (formerly Framer Motion) and follow a consistent choreography pattern:
-
-**Entrance animations** use a fade-up reveal: elements start at `opacity: 0, y: 20-100` and animate to `opacity: 1, y: 0`. The hero section uses a larger y-offset (100px) for dramatic effect; subsequent sections use 20px for subtlety.
-
-**Timing principles:**
-- **Base duration:** 0.35s–0.6s for standard section reveals, 0.45s for hero elements, up to 1.1s for the hero video entrance.
-- **Stagger pattern:** Sequential delays within a group, typically 0.1s–0.15s apart (hero: 0.55s, 0.7s, 0.82s, 0.95s). For grids, use `index * 0.03`–`0.1` for per-item stagger.
-- **Easing:** `easeOut` for entrances (elements decelerate into position). `easeInOut` for looping/ambient animations.
-- **Performance:** Apply `will-change-[transform,opacity]` on animated elements and `will-change-transform` on continuously animated elements.
-
-**Hover/interaction animations** are quick (0.2s) and subtle — small scale bumps (`scale: 1.01`), slight y-offsets (`y: -2`), and `active:translate-y-px` for button press.
-
-**Ambient animations** loop infinitely with `easeInOut` — the scroll indicator bounces gently (`y: [0, 5, 0]` over 1.5s).
-
-**Reduced motion:** All CSS transitions and animations collapse to `0.01ms` duration and single iteration when `prefers-reduced-motion: reduce` is active. Motion library animations should also respect this preference.
-
-## Elevation & Depth
-
-Elevation is handled through background color layering rather than drop shadows:
-
-- **Level 0 — Background:** The base canvas (`--background`).
-- **Level 1 — Card:** One step lighter in dark mode (`--card`), used for sidebars, panels, and cards.
-- **Level 2 — Popover:** Same as card, but appears above the content layer in popovers, dropdowns, and command palette.
-- **Level 3 — Overlay:** Backdrop blur (`backdrop-blur-xs` at 0.5px or `backdrop-blur-2xl` at 40px) with `backdrop-saturate-150` for modal overlays, creating a frosted-glass effect over the workspace.
-
-The resume preview page uses a subtle drop shadow to simulate a physical sheet of paper floating above the dark artboard — one of the few places actual shadows appear.
-
-## Shapes
-
-Border radius follows a multiplicative scale from a single `--radius` base of `0.3rem`:
-
-| Token | Value | Usage |
-|:------|:------|:------|
-| `sm` | 0.18rem (≈3px) | Small badges, inline chips |
-| `md` | 0.24rem (≈4px) | XS/SM buttons, compact elements |
-| `lg` | 0.3rem (≈5px) | Default buttons, cards, inputs |
-| `xl` | 0.42rem (≈7px) | Larger cards, modal corners |
-| `2xl` | 0.54rem (≈9px) | Dialog containers |
-| `3xl` | 0.66rem (≈11px) | Large panels |
-| `4xl` | 0.78rem (≈12px) | Full-page modals |
-
-The radius scale is deliberately tight — the largest value (0.78rem) is still quite subtle. This avoids the "rounded everything" aesthetic and keeps the UI feeling precise and tool-like. Interactive elements consistently use `rounded-lg` as the default.
+- Everything that enters uses `ease-enter` (`cubic-bezier(0.2, 0.8, 0.2, 1)`). Exits run at 70% of the duration.
+- Motion explains where something went. Nothing loops, bounces or plays on load; loading placeholders stay still. Reflowing the page after an edit is never animated.
+- With `prefers-reduced-motion`, the duration tokens become 1ms and every CSS transition collapses; spinners keep turning because they're status.
+- Motion (`motion/react`) animations run under `MotionConfig reducedMotion="user"`; mirror the tokens in `apps/web/src/libs/motion.ts` when one needs them.
 
 ## Components
 
-### Buttons
+Generic primitives live in `packages/ui/src/components` and wrap Base UI (and cmdk for the command bar). Feature-specific UI lives with its feature in `apps/web`.
 
-Six variants, all sharing `rounded-lg` corners, `font-medium`, `text-sm`, and a 1px `translate-y` on active press (except when the button opens a popup):
+- **Buttons:** `primary` (accent fill, the one filled button per view), `secondary` (bordered surface), `ghost`, `danger`, `link`. Sizes `sm` 28, `default` 36, `lg` 44 (touch), plus icon sizes. `loading` shows a spinner, sets `aria-busy` and blocks activation; pair it with a present-participle label ("Preparing…").
+- **Inputs:** 36px (44px on touch), `raised` background, `line-2` border. Focus is an accent border plus a 3px `accent-soft` ring. Errors appear after the first blur, in `danger-text`, with an icon and words that say how to fix it.
+- **Switches:** prefer `SwitchRow`, where the whole row is the switch. Checkboxes are 18px with a 5px radius; radios are 18px with an 8px accent dot.
+- **Segmented controls:** `SegmentedControl` for 2–4 options (a radio group); `Tabs` with the default variant when segments switch panels, `Tabs variant="line"` for underline tabs.
+- **Menus** (dropdown, context, combobox lists): 220px minimum width, 12px radius, 36px items, destructive items last after a separator.
+- **Layers, lightest to heaviest:** menu, popover, sheet, dialog. Sheets are for tasks beside the page and become bottom sheets on mobile. Dialogs are for decisions; destructive confirmations use `AlertDialog` and the cancel label says what is kept.
+- **Toasts:** one at a time, bottom center, ink on the desk color, 6 seconds, with an optional underlined Undo action.
+- **Alerts:** `info`, `success`, `warn` and `error`; only errors are announced (`role="alert"`).
+- **Empty states:** a Newsreader 22px headline, a 14px body up to 300px wide, then a primary and a secondary action.
 
-- **Default:** Solid primary background. The highest-emphasis action on any screen.
-- **Outline:** Transparent with a border. For secondary actions that need clear boundaries.
-- **Secondary:** Muted background. For paired actions alongside a primary button.
-- **Ghost:** No background or border. For toolbar actions and inline controls where chrome would be noise.
-- **Destructive:** Red at 10% opacity background with red text. Visually alarming without being garish.
-- **Link:** Underline-on-hover text. For inline navigation within prose.
+## Accessibility
 
-Size scale: `xs` (28px), `sm` (32px), `default` (36px), `lg` (40px), plus `icon` variants at each size for square icon-only buttons.
+WCAG 2.2 AA is the floor.
 
-### Cards
+- Every interactive element shows a 2px accent focus ring with a 2px gap on `:focus-visible`. Never remove it; inputs replace it with their accent border and soft ring.
+- Pointer targets are at least 24px and touch targets at least 44px. Every drag has a keyboard and a menu alternative.
+- Color is never the only signal: stages, issues and states always pair color with text and an icon.
+- Sheets and dialogs trap focus; Esc closes the top layer and returns focus to its trigger. Save state and toasts announce through a polite live region.
 
-White/dark surface with foreground text. Composed of `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`, and `CardAction` slots. Default vertical padding is `py-4` (compact: `py-3`).
+## Themes
 
-### Forms
-
-Built on TanStack Form with Zod validation. Composed of `FormItem`, `FormLabel`, `FormControl`, `FormMessage`, and `FormDescription`. Validation errors only appear after field touch. Invalid fields get a red destructive border with a ring.
-
-### Dialogs
-
-Centralized dialog manager with 40+ dialog types, all rendered via pattern matching (`ts-pattern`). Dialogs support before-close validation, form blocking for unsaved changes, and confirmation prompts. Used for all CRUD operations on resume sections, settings changes, and import/export flows.
-
-### Command Palette
-
-Triggered by `Cmd+K` / `Ctrl+K`. Built on `cmdk` with fuzzy search via `Fuse.js`. Multi-page navigation (resumes, settings, preferences) with back navigation via Backspace. Screen-reader accessible with `sr-only` headings.
-
-### Toast Notifications
-
-Powered by Sonner, positioned bottom-right with rich colors. Used for auto-save feedback, form submission status, error reporting, and donation prompts. Loading toasts are used during async operations (PDF generation, resume creation) with dismiss-on-complete.
-
-### Drag and Drop
-
-Powered by `@dnd-kit` with `PointerSensor` and `KeyboardSensor`. Used in chip inputs (skill tags, URL lists) and page layout management (section ordering across resume pages). Smooth animations via Motion library.
+The theme cookie holds `light`, `dark` or `system` (the default); `system` follows `prefers-color-scheme` live. `ThemeProvider` owns the `.dark` class on `<html>`, and an inline script in `index.html` sets it before first paint. Resumes and letters always render on white paper, whatever the theme.
 
 ## Internationalization
 
-The app supports 40+ locales including RTL languages (Arabic, Hebrew, Persian, Urdu, Uyghur, Yiddish). i18n is not an afterthought — it shapes layout decisions:
+- Every user-facing string goes through Lingui (`t`, `msg`, `<Trans>`); catalogs are PO files in `apps/web/locales`. Primitives in `packages/ui` can't use Lingui, so they take labels as props (for example `closeLabel`).
+- 55 interface languages, including right-to-left ones. `<html dir>` follows the locale and `DirectionProvider` passes it to Base UI.
+- Use logical properties (`ps`, `pe`, `ms`, `me`, `inset-s`, `inset-e`) instead of physical ones.
+- Translations run 30–50% longer than English; avoid fixed widths on text.
 
-**Direction:** The `<html>` element receives `dir="rtl"` or `dir="ltr"` based on the active locale, detected via `isRTL()` which checks the language prefix against a known RTL set. All layout mirroring flows from this single attribute.
+## Do and don't
 
-**Logical properties:** Use CSS logical properties (`ps-`, `pe-`, `ms-`, `me-`, `inline-start`, `inline-end`, `inset-s-`, `inset-e-`) instead of physical (`pl-`, `pr-`, `ml-`, `mr-`, `left`, `right`). Button components already use `has-data-[icon=inline-start]:ps-2` and `has-data-[icon=inline-end]:pe-2` patterns. This ensures correct spacing in both LTR and RTL layouts without separate stylesheets.
-
-**Variable-length text:** Translations can be 30–50% longer than English (German, Finnish) or significantly shorter (CJK). UI elements should accommodate variable text length — avoid fixed widths on buttons and labels. Use `whitespace-nowrap` only where truncation is acceptable, and prefer `min-w-0` with `truncate` over fixed-width containers.
-
-**Icons:** Directional icons (arrows, chevrons, progress indicators) should mirror in RTL contexts. Phosphor Icons provides mirrored variants for directional icons. Non-directional icons (settings gear, checkmark, delete) do not mirror.
-
-**Strings:** All user-facing strings use Lingui macros (`t`, `msg`, `<Trans>`) — never hardcode English text in components. Translation files are `.po` format under `/locale/`.
-
-## Do's and Don'ts
-
-### Do
-
-- **Use the grayscale palette for all app chrome.** The absence of color is the brand. The resume content is the only thing that should be colorful.
-- **Default to dark mode.** The dark workspace makes resume previews pop and reduces eye strain during extended editing sessions.
-- **Use `text-sm` (14px) as the base text size.** The UI is information-dense — form fields, section labels, metadata — and needs to be scannable without feeling cramped.
-- **Keep border radius tight.** Use `rounded-lg` (0.3rem) as the default. The tool should feel precise, not playful.
-- **Respect reduced motion preferences.** All animations collapse to 0.01ms when `prefers-reduced-motion: reduce` is active.
-- **Use Phosphor Icons consistently.** Regular weight, `size-4` (16px) default. Icons should be functional labels, not decorative.
-- **Maintain the three-panel builder proportions.** The center artboard should always dominate. Sidebars are support panels, not equal peers.
-- **Use transparent-white borders in dark mode.** `oklch(1 0 0 / 10%)` blends naturally with any surface rather than introducing a distinct gray band.
-
-### Don't
-
-- **Don't introduce accent colors into the app shell.** No blues, greens, or purples for primary actions. The only chromatic color is destructive red. The inherited indigo sidebar-primary token exists in CSS custom properties but is not actively used.
-- **Don't use drop shadows for elevation.** Rely on background color layering and border separation. The one exception is the resume page preview shadow.
-- **Don't make the UI compete with the resume content.** If a new feature draws more visual attention than the resume preview, it needs to be toned down.
-- **Don't use large border radii.** Nothing above `rounded-xl` on standard components. Large pills and full-round shapes conflict with the precision-tool aesthetic.
-- **Don't hardcode colors outside the token system.** All colors flow through CSS custom properties so that dark/light mode switching works automatically.
-- **Don't use multiple typefaces in the app shell.** IBM Plex Sans Variable is the only UI font. Resume templates have their own font system, but the chrome stays single-family.
-- **Don't skip the `data-slot` attribute on components.** It's used for styling hooks and accessibility selectors throughout the component library.
-- **Don't forget RTL.** The app supports 40+ locales including Arabic, Hebrew, Persian, and Urdu. Use logical properties (`ps`, `pe`, `ms`, `me`) instead of physical (`pl`, `pr`, `ml`, `mr`).
+- **Do** keep one accent-filled button per view, and keep accent for next actions and working states.
+- **Do** use `ink-3` as the lightest text color, and pair every color signal with text.
+- **Do** build states in full: empty, loading (placeholders at their real size), error (why and what to do) and success.
+- **Don't** hard-code colors, including Tailwind palette classes such as `amber-600`; use the semantic tokens.
+- **Don't** use Newsreader for anything smaller than a sheet title.
+- **Don't** ask for confirmation for something that can be undone; use an undo toast instead.
+- **Don't** skip `data-slot` on primitives; tests and styles rely on it.

Dockerfile

@@ -1,5 +1,6 @@
 # syntax=docker/dockerfile:1.7
 
+# Base image only; pnpm self-manages to the `packageManager` version in package.json.
 ARG PNPM_VERSION=11.21.0
 ARG NODE_VERSION=24
 
@@ -25,7 +26,7 @@ RUN --mount=type=cache,id=pnpm-store,target=/pnpm/store,sharing=locked \
     pnpm install --frozen-lockfile
 
 COPY --from=pruner /app/out/full/ ./
-RUN rm -rf apps/web/dist apps/server/dist && pnpm turbo run build --filter=web --filter=server --force
+RUN rm -rf apps/web/dist apps/web/dist-prerender apps/server/dist && pnpm turbo run build --filter=web --filter=server --force
 
 FROM base AS runtime-pruner
 COPY . .
@@ -47,7 +48,7 @@ LABEL org.opencontainers.image.description="A free and open-source resume builde
 LABEL org.opencontainers.image.vendor="Amruth Pillai"
 LABEL org.opencontainers.image.url="https://rxresu.me"
 LABEL org.opencontainers.image.documentation="https://docs.rxresu.me"
-LABEL org.opencontainers.image.source="https://github.com/amruthpillai/reactive-resume"
+LABEL org.opencontainers.image.source="https://github.com/reactive-resume/reactive-resume"
 
 ENV NODE_ENV="production" \
     PORT=3000 \
@@ -62,6 +63,7 @@ COPY --from=pruner --chown=node:node /app/package.json /app/pnpm-lock.yaml /app/
 COPY --from=runtime-deps --chown=node:node /app/apps/server/package.json ./apps/server/package.json
 COPY --from=runtime-deps --chown=node:node /app/apps/server/node_modules ./apps/server/node_modules
 COPY --from=builder --chown=node:node /app/apps/web/dist ./apps/web/dist
+COPY --from=builder --chown=node:node /app/apps/web/dist-prerender ./apps/web/dist-prerender
 COPY --from=builder --chown=node:node /app/apps/server/dist ./apps/server/dist
 COPY --from=pruner --chown=node:node /app/migrations ./migrations
 

GLOSSARY.md

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

README.md

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

apps/server/package.json

@@ -11,91 +11,92 @@
 		"typecheck": "tsgo --noEmit",
 		"test": "vitest run --passWithNoTests",
 		"test:coverage": "vitest run --coverage --passWithNoTests",
-		"test:ci": "vitest run --coverage --reporter=default --reporter=github-actions --reporter=json --reporter=junit --outputFile.json=reports/vitest-results.json --outputFile.junit=reports/vitest-junit.xml --passWithNoTests",
+		"test:ci": "vitest run --reporter=default --reporter=github-actions --reporter=json --reporter=junit --outputFile.json=reports/vitest-results.json --outputFile.junit=reports/vitest-junit.xml --passWithNoTests",
 		"test:agent": "vitest run --reporter=agent --reporter=json --outputFile.json=reports/vitest-results.json --passWithNoTests"
 	},
-	"imports": {
-		"#react-pdf-renderer": "@react-pdf/renderer"
-	},
 	"dependencies": {
-		"@ai-sdk/anthropic": "^4.0.36",
-		"@ai-sdk/cerebras": "^3.0.28",
-		"@ai-sdk/cohere": "^4.0.25",
-		"@ai-sdk/deepseek": "^3.0.26",
-		"@ai-sdk/fireworks": "^3.0.30",
-		"@ai-sdk/google": "^4.0.39",
-		"@ai-sdk/groq": "^4.0.26",
-		"@ai-sdk/mistral": "^4.0.27",
-		"@ai-sdk/openai": "^4.0.36",
-		"@ai-sdk/openai-compatible": "^3.0.28",
-		"@ai-sdk/perplexity": "^4.0.27",
-		"@ai-sdk/togetherai": "^3.0.29",
-		"@ai-sdk/xai": "^4.0.33",
-		"@aws-sdk/client-s3": "^3.1106.0",
-		"@better-auth/api-key": "^1.6.26",
-		"@better-auth/drizzle-adapter": "^1.6.26",
-		"@better-auth/infra": "^0.3.7",
-		"@better-auth/oauth-provider": "^1.6.26",
-		"@better-auth/passkey": "^1.6.26",
+		"@ai-sdk/anthropic": "^4.0.68",
+		"@ai-sdk/cerebras": "^3.0.59",
+		"@ai-sdk/cohere": "^4.0.52",
+		"@ai-sdk/deepseek": "^3.0.56",
+		"@ai-sdk/fireworks": "^3.0.62",
+		"@ai-sdk/google": "^4.0.85",
+		"@ai-sdk/groq": "^4.0.52",
+		"@ai-sdk/mistral": "^4.0.54",
+		"@ai-sdk/openai": "^4.0.81",
+		"@ai-sdk/openai-compatible": "^3.0.59",
+		"@ai-sdk/perplexity": "^5.0.3",
+		"@ai-sdk/togetherai": "^3.0.60",
+		"@ai-sdk/xai": "^5.0.12",
+		"@aws-sdk/client-s3": "^3.1143.0",
+		"@better-auth/api-key": "^1.7.6",
+		"@better-auth/drizzle-adapter": "^1.7.6",
+		"@better-auth/infra": "^0.4.13",
+		"@better-auth/oauth-provider": "^1.7.6",
+		"@better-auth/passkey": "^1.7.6",
 		"@bramus/specificity": "^2.4.2",
-		"@hono/node-server": "^2.1.0",
-		"@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.6.0",
+		"@formepdf/core": "0.25.0",
+		"@formepdf/react": "0.25.0",
+		"@hono/node-server": "^2.1.3",
+		"@modelcontextprotocol/sdk": "^1.31.0",
+		"@orpc/client": "^1.15.4",
+		"@orpc/experimental-ratelimit": "^1.15.4",
+		"@orpc/json-schema": "^1.15.4",
+		"@orpc/openapi": "^1.15.4",
+		"@orpc/server": "^1.15.4",
+		"@orpc/zod": "^1.15.4",
 		"@reactive-resume/api": "workspace:*",
 		"@reactive-resume/auth": "workspace:*",
 		"@reactive-resume/db": "workspace:*",
 		"@reactive-resume/env": "workspace:*",
 		"@reactive-resume/mcp": "workspace:*",
-		"@reactive-resume/pdf": "workspace:*",
 		"@reactive-resume/schema": "workspace:*",
 		"@reactive-resume/utils": "workspace:*",
-		"@sindresorhus/slugify": "^3.0.0",
+		"@sindresorhus/slugify": "^3.0.1",
 		"@t3-oss/env-core": "^0.13.11",
 		"@uiw/color-convert": "^2.10.3",
-		"ai": "^7.0.58",
-		"bcrypt": "^6.0.0",
-		"better-auth": "1.6.26",
-		"canonicalize": "^3.0.0",
-		"cjk-regex": "^3.4.0",
+		"@vercel/blob": "^2.8.0",
+		"@vercel/functions": "^3.9.9",
+		"ai": "^7.0.122",
+		"bcryptjs": "^3.0.3",
+		"better-auth": "1.7.6",
+		"cjk-regex": "^3.5.0",
 		"css-tree": "^3.2.1",
-		"deepmerge-ts": "^7.1.5",
 		"drizzle-orm": "1.0.0-rc.4",
 		"drizzle-zod": "1.0.0-beta.14-a36c63d",
-		"es-toolkit": "^1.50.0",
+		"es-toolkit": "^1.52.0",
 		"fast-json-patch": "^3.1.1",
-		"hono": "^4.13.1",
+		"fast-png": "^8.0.0",
+		"fflate": "^0.8.3",
+		"hono": "^4.13.11",
+		"ioredis": "^6.0.0",
+		"jose": "^6.2.12",
 		"jsonrepair": "^3.15.0",
-		"node-html-parser": "^9.0.1",
-		"nodemailer": "^9.0.5",
+		"node-html-parser": "^9.0.4",
+		"nodemailer": "^10.0.12",
 		"ollama-ai-provider-v2": "^4.0.1",
-		"pdfjs-dist": "^6.2.108",
 		"pg": "^8.23.0",
-		"phosphor-icons-react-pdf": "^0.1.3",
-		"react": "^19.2.8",
-		"react-email": "^6.9.2",
-		"react-pdf-html": "^2.1.5",
-		"resumable-stream": "^2.2.12",
-		"sharp": "^0.35.3",
+		"react": "^19.3.0",
+		"react-email": "^6.11.0",
+		"react-reconciler": "0.34.0",
+		"resumable-stream": "^2.2.13",
+		"sanitize-html": "^2.17.7",
+		"sharp": "^0.35.5",
+		"tokenx": "^2.1.0",
 		"ts-pattern": "^5.9.0",
 		"unique-names-generator": "^4.7.1",
-		"uuid": "^14.0.1",
-		"zod": "^4.4.3"
+		"uuid": "^14.0.2",
+		"zod": "^4.6.5"
 	},
 	"devDependencies": {
 		"@reactive-resume/config": "workspace:*",
-		"@types/node": "^26.2.0",
-		"@types/pg": "^8.21.0",
-		"@types/react": "^19.2.18",
+		"@types/node": "^26.6.3",
+		"@types/pg": "^8.23.1",
+		"@types/react": "^19.3.0",
 		"@typescript/native-preview": "7.0.0-dev.20260707.2",
-		"tsdown": "^0.22.14",
-		"tsx": "^4.23.12",
+		"tsdown": "^0.23.0",
+		"tsx": "^4.23.15",
 		"typescript": "^7.0.2",
-		"vitest": "^4.1.10"
+		"vitest": "^5.0.2"
 	}
 }

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

@@ -1,3 +1,4 @@
+import { gunzipSync } from "node:zlib";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const mocks = vi.hoisted(() => ({
@@ -113,28 +114,16 @@ describe("createApp", () => {
 		await expect(response.text()).resolves.toBe("oauth");
 		expect(mocks.handleOAuth).toHaveBeenCalledWith(request);
 		expect(mocks.handleAuth).not.toHaveBeenCalled();
-	});
-
-	it("routes signed resume PDF downloads before the web fallback", async () => {
-		const { createApp } = await import("./app");
-		const app = createApp();
-		const request = new Request("http://localhost:3001/api/resumes/resume-1/pdf?token=signed");
-
-		const response = await app.fetch(request);
-
-		await expect(response.text()).resolves.toBe("pdf");
-		expect(mocks.handleResumePdfDownload).toHaveBeenCalledWith(request, "resume-1");
-		expect(mocks.serveWebDistStatic).not.toHaveBeenCalled();
-		expect(mocks.handleWebApp).not.toHaveBeenCalled();
-	});
+		// The first test pays for the cold import of the whole app, which takes seconds under a parallel run.
+	}, 15_000);
 
 	it("uses the transport address for public PDF fallback despite rotated forwarding headers", async () => {
 		const { createApp } = await import("./app");
 		const app = createApp();
-		const first = new Request("http://localhost:3001/api/resumes/jane/resume/pdf?reason=render-data-hash", {
+		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?reason=render-data-hash", {
+		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");
@@ -159,8 +148,8 @@ describe("createApp", () => {
 		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/style-projection");
-		const unknownOpenApiRequest = new Request("http://localhost:3001/api/openapi/resumes/jane/resume/style-projection");
+		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);
@@ -173,23 +162,55 @@ describe("createApp", () => {
 		expect(mocks.handleOpenApi).toHaveBeenNthCalledWith(2, unknownOpenApiRequest, "unknown");
 	});
 
-	it.each([
-		["GET", "/robots.txt", "robots", mocks.handleRobots],
-		["HEAD", "/robots.txt", "", mocks.handleRobots],
-		["GET", "/sitemap.xml", "sitemap", mocks.handleSitemap],
-		["HEAD", "/sitemap.xml", "", mocks.handleSitemap],
-		["GET", "/llms.txt", "llms", mocks.handleLlms],
-		["HEAD", "/llms.txt", "", mocks.handleLlms],
-	])("routes %s %s before the static fallback", async (method, pathname, expectedBody, handler) => {
+	it("routes GET / to the web app handler so SEO markup is injected", async () => {
 		const { createApp } = await import("./app");
 		const app = createApp();
-		const request = new Request(`http://localhost:3001${pathname}`, { method });
+		const request = new Request("http://localhost:3001/");
 
 		const response = await app.fetch(request);
 
-		await expect(response.text()).resolves.toBe(expectedBody);
-		expect(handler).toHaveBeenCalledWith({ head: method === "HEAD" });
+		expect(response.status).toBe(200);
+		expect(mocks.handleWebApp).toHaveBeenCalledWith(request);
 		expect(mocks.serveWebDistStatic).not.toHaveBeenCalled();
-		expect(mocks.handleWebApp).not.toHaveBeenCalled();
+	});
+
+	it("compresses the web app's HTML but never API streams or the Vercel app", async () => {
+		const { createApp } = await import("./app");
+		const html = `<!doctype html>${"<p>Reactive Resume</p>".repeat(200)}`;
+		const htmlResponse = () =>
+			new Response(html, {
+				headers: { "Content-Type": "text/html; charset=UTF-8", "Cache-Control": "private, no-store", Vary: "Cookie" },
+			});
+		const stream = () => new Response("data: x\n\n".repeat(500), { headers: { "Content-Type": "application/json" } });
+		mocks.handleWebApp.mockImplementation(async () => htmlResponse());
+		mocks.handleRpc.mockImplementation(async () => stream());
+		mocks.handleMcp.mockImplementation(async () => stream());
+		const headers = { "Accept-Encoding": "br, gzip" };
+
+		const page = await createApp().request("http://localhost:3000/", { headers });
+		const rpc = await createApp().request("http://localhost:3000/api/rpc/agent/chat", { headers });
+		const mcp = await createApp().request("http://localhost:3000/mcp", { headers });
+		const vercelPage = await createApp({ serveStatic: false }).request("http://localhost:3000/", { headers });
+
+		expect(page.headers.get("content-encoding")).toBe("gzip");
+		expect(page.headers.get("vary")).toBe("Cookie, Accept-Encoding");
+		expect(page.headers.get("cache-control")).toBe("private, no-store");
+		expect(gunzipSync(Buffer.from(await page.arrayBuffer())).toString()).toBe(html);
+		for (const response of [rpc, mcp, vercelPage]) expect(response.headers.get("content-encoding")).toBeNull();
+		expect(vercelPage.headers.get("vary")).toBe("Cookie");
 	});
 });
+
+it.each(["/auth/consent", "/auth/consent/", "/auth/login"])("prevents framing or caching %s", async (path) => {
+	const { createApp } = await import("./app");
+	mocks.serveWebDistStatic.mockImplementationOnce(async (_context: unknown, next: () => Promise<void>) => {
+		await next();
+	});
+	const response = await createApp().request(`http://localhost:3000${path}?sig=signed`);
+	expect(response.status).toBe(200);
+	expect(await response.text()).toBe("web");
+	expect(response.headers.get("content-security-policy")).toBe("frame-ancestors 'none'");
+	expect(response.headers.get("x-frame-options")).toBe("DENY");
+	expect(response.headers.get("referrer-policy")).toBe("no-referrer");
+	expect(response.headers.get("cache-control")).toBe("no-store");
+});

apps/server/src/http/app.ts

@@ -3,6 +3,8 @@ import type { Context } from "hono";
 import { isIP } from "node:net";
 import { getConnInfo } from "@hono/node-server/conninfo";
 import { Hono } from "hono";
+import { compress } from "hono/compress";
+import { prepareStagedBody, withStagedBody } from "@reactive-resume/api/features/storage/transport";
 import { handleMcp } from "../mcp/handler";
 import { handleOpenApi } from "../openapi/handler";
 import {
@@ -33,18 +35,33 @@ const getTrustedClient = (context: Context<ServerEnvironment>): string => {
 	}
 };
 
-export function createApp() {
-	const app = new Hono<ServerEnvironment>();
+type AppOptions = {
+	serveStatic?: boolean;
+	trustedClient?: (request: Request) => string;
+};
 
-	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)));
+export function createApp(options: AppOptions = {}) {
+	const app = new Hono<ServerEnvironment>();
+	const client = (c: Context<ServerEnvironment>) => options.trustedClient?.(c.req.raw) ?? getTrustedClient(c);
+
+	app.use("/auth/*", async (c, next) => {
+		await next();
+		c.header("Content-Security-Policy", "frame-ancestors 'none'");
+		c.header("X-Frame-Options", "DENY");
+		c.header("Referrer-Policy", "no-referrer");
+		c.header("Cache-Control", "no-store");
+	});
+
+	app.post("/api/storage/stage", (c) => prepareStagedBody(c.req.raw));
+	app.all("/api/rpc", (c) => withStagedBody(c.req.raw, (request) => handleRpc(request, client(c))));
+	app.all("/api/rpc/*", (c) => withStagedBody(c.req.raw, (request) => handleRpc(request, client(c))));
+	app.all("/api/openapi", (c) => handleOpenApi(c.req.raw, client(c)));
+	app.all("/api/openapi/*", (c) => handleOpenApi(c.req.raw, client(c)));
 	app.get("/api/auth/oauth", (c) => handleOAuth(c.req.raw));
 	app.all("/api/auth/*", (c) => handleAuth(c.req.raw));
 	app.get("/api/health", () => handleHealth());
 	app.get("/api/resumes/:username/:slug/pdf", (c) =>
-		handlePublicResumePdf(c.req.raw, c.req.param("username"), c.req.param("slug"), getTrustedClient(c)),
+		handlePublicResumePdf(c.req.raw, c.req.param("username"), c.req.param("slug"), client(c)),
 	);
 	app.get("/api/resumes/:id/pdf", (c) => handleResumePdfDownload(c.req.raw, c.req.param("id")));
 	app.get("/api/uploads/*", (c) => handleUpload(c.req.raw));
@@ -65,7 +82,15 @@ 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" }));
 
-	app.use("/*", serveWebDistStatic);
+	// Compresses only the web app's files and HTML shells: every route registered above answers before reaching
+	// it, so API, MCP, and upload streams are never buffered or re-encoded. Where a CDN serves the static files
+	// (Vercel), it also compresses at its edge.
+	if (options.serveStatic !== false) app.use("/*", compress());
+
+	// Must precede the static middleware: serveStatic resolves "/" to dist/index.html and would
+	// return it verbatim, skipping the OpenGraph/Twitter/canonical/JSON-LD injection in handleWebApp.
+	app.on(["GET", "HEAD"], "/", (c) => handleWebApp(c.req.raw));
+	if (options.serveStatic !== false) app.use("/*", serveWebDistStatic);
 	app.on(["GET", "HEAD"], "/*", (c) => handleWebApp(c.req.raw));
 
 	return app;

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

@@ -2,6 +2,8 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const mocks = vi.hoisted(() => ({
 	getSession: vi.fn(),
+	consent: vi.fn(),
+	continueOAuth: vi.fn(),
 	handler: vi.fn(),
 	env: {
 		SERVER_PORT: 3001,
@@ -14,6 +16,8 @@ vi.mock("@reactive-resume/auth/config", () => ({
 	auth: {
 		api: {
 			getSession: mocks.getSession,
+			oauth2Consent: mocks.consent,
+			oauth2Continue: mocks.continueOAuth,
 		},
 		handler: mocks.handler,
 	},
@@ -32,13 +36,30 @@ beforeEach(() => {
 });
 
 describe("handleAuth", () => {
-	it("rejects untrusted dynamic OAuth redirect URIs in safe mode", async () => {
+	it.for([null, false, 42, "client", [], [{ redirect_uris: [] }]])(
+		"rejects non-object registration payload %j",
+		async (body) => {
+			const { handleAuth } = await import("./auth");
+			const response = await handleAuth(
+				new Request("http://localhost:3000/api/auth/oauth2/register", {
+					method: "POST",
+					headers: { "content-type": "application/json" },
+					body: JSON.stringify(body),
+				}),
+			);
+			expect(response.status).toBe(400);
+			await expect(response.json()).resolves.toEqual({ message: "Invalid registration payload" });
+			expect(mocks.handler).not.toHaveBeenCalled();
+		},
+	);
+
+	it("rejects unsafe dynamic OAuth redirect URIs in safe mode", async () => {
 		const { handleAuth } = await import("./auth");
 
 		const response = await handleAuth(
 			new Request("http://localhost:3001/api/auth/oauth2/register", {
 				method: "POST",
-				body: JSON.stringify({ redirect_uris: ["https://evil.example.com/callback"] }),
+				body: JSON.stringify({ redirect_uris: ["https://192.168.1.10/callback"] }),
 				headers: { "content-type": "application/json" },
 			}),
 		);
@@ -51,20 +72,61 @@ describe("handleAuth", () => {
 		expect(mocks.handler).not.toHaveBeenCalled();
 	});
 
-	it("forwards custom-scheme dynamic OAuth redirect URIs when unsafe mode is enabled", async () => {
+	it.each(["localhost", "127.0.0.1", "[::1]"])(
+		"infers native application type for exact %s loopback callbacks",
+		async (host) => {
+			const { handleAuth } = await import("./auth");
+			await handleAuth(
+				new Request("http://localhost:3000/api/auth/oauth2/register", {
+					method: "POST",
+					headers: { "content-type": "application/json" },
+					body: JSON.stringify({ redirect_uris: [`http://${host}:3210/callback`] }),
+				}),
+			);
+			const forwarded = mocks.handler.mock.calls[0]?.[0] as Request;
+			await expect(forwarded.json()).resolves.toMatchObject({
+				application_type: "native",
+				token_endpoint_auth_method: "none",
+			});
+		},
+	);
+
+	it.each(["client_secret_basic", "client_secret_post"])(
+		"keeps an explicitly registered %s so the client receives a client secret",
+		async (method) => {
+			const { handleAuth } = await import("./auth");
+			await handleAuth(
+				new Request("http://localhost:3000/api/auth/oauth2/register", {
+					method: "POST",
+					headers: { "content-type": "application/json" },
+					body: JSON.stringify({
+						redirect_uris: ["https://example.com/callback"],
+						token_endpoint_auth_method: method,
+					}),
+				}),
+			);
+			const forwarded = mocks.handler.mock.calls[0]?.[0] as Request;
+			await expect(forwarded.json()).resolves.toMatchObject({ token_endpoint_auth_method: method });
+		},
+	);
+
+	it.each([
+		{ redirect_uris: ["https://example.com/callback"] },
+		{ redirect_uris: ["http://localhost.evil.example/callback"] },
+		{ redirect_uris: ["http://localhost:3210/callback"], application_type: "web" },
+		{ redirect_uris: ["http://localhost:3210/callback", "https://example.com/callback"] },
+	])("does not infer native for explicit web or non-loopback clients: %j", async (body) => {
 		const { handleAuth } = await import("./auth");
 		mocks.env.FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI = true;
-
-		const response = await handleAuth(
-			new Request("http://localhost:3001/api/auth/oauth2/register", {
+		await handleAuth(
+			new Request("http://localhost:3000/api/auth/oauth2/register", {
 				method: "POST",
-				body: JSON.stringify({ redirect_uris: ["myapp://callback"] }),
 				headers: { "content-type": "application/json" },
+				body: JSON.stringify(body),
 			}),
 		);
-
-		expect(response.status).toBe(200);
-		expect(mocks.handler).toHaveBeenCalledOnce();
+		const forwarded = mocks.handler.mock.calls[0]?.[0] as Request;
+		expect((await forwarded.json()).application_type).not.toBe("native");
 	});
 });
 
@@ -91,7 +153,55 @@ describe("handleOAuth", () => {
 		expect(callbackUrl.searchParams.get("client_id")).toBe("test-client");
 		expect(callbackUrl.searchParams.get("redirect_uri")).toBe("https://example.com/callback");
 		expect(callbackUrl.searchParams.get("state")).toBe("abc");
-		expect(callbackUrl.searchParams.has("exp")).toBe(false);
-		expect(callbackUrl.searchParams.has("sig")).toBe(false);
+		expect(callbackUrl.searchParams.get("exp")).toBe("123");
+		expect(callbackUrl.searchParams.get("sig")).toBe("456");
+	});
+	it("continues signed authorization without approving consent on GET", async () => {
+		const { handleOAuth } = await import("./auth");
+		mocks.getSession.mockResolvedValueOnce({ user: { id: "owner" } });
+		mocks.continueOAuth.mockResolvedValueOnce(
+			Response.json({ redirect: true, url: "/auth/consent?client_id=client&sig=signed" }),
+		);
+		const query = "client_id=client&resource=one&resource=two&exp=123&sig=456";
+		const response = await handleOAuth(new Request(`http://localhost:3000/api/auth/oauth?${query}`));
+		expect(mocks.continueOAuth).toHaveBeenCalledWith(
+			expect.objectContaining({ body: { postLogin: true, oauth_query: query } }),
+		);
+		expect(mocks.consent).not.toHaveBeenCalled();
+		expect(response.status).toBe(302);
+		expect(response.headers.get("location")).toBe("/auth/consent?client_id=client&sig=signed");
+	});
+
+	it("preserves provider cookies and cache headers on forced reauthentication", async () => {
+		const { handleOAuth } = await import("./auth");
+		mocks.getSession.mockResolvedValueOnce({ user: { id: "owner" } });
+		const headers = new Headers({ "cache-control": "no-store", "content-length": "123" });
+		headers.append("set-cookie", "oauth_state=state; Path=/; HttpOnly");
+		headers.append("set-cookie", "session=refreshed; Path=/; HttpOnly");
+		mocks.continueOAuth.mockResolvedValueOnce(
+			Response.json({ redirect: true, url: "/api/auth/oauth?prompt=login&sig=signed" }, { headers }),
+		);
+		const response = await handleOAuth(new Request("http://localhost:3000/api/auth/oauth?sig=original"));
+		expect(response.status).toBe(302);
+		expect(response.headers.get("location")).toMatch(/^\/auth\/login\?reauthenticate=true&/);
+		expect(response.headers.getSetCookie()).toEqual(headers.getSetCookie());
+		expect(response.headers.get("cache-control")).toBe("no-store");
+		expect(response.headers.get("content-type")).toBeNull();
+		expect(response.headers.get("content-length")).toBeNull();
 	});
 });
+
+describe("OAuth provider response validation", () => {
+	it.for([{}, { url: null }, { url: 7 }, { url: "" }, { url: "undefined" }, { url: "javascript:alert(1)" }])(
+		"fails closed for malformed provider response %j",
+		async (body) => {
+			const { handleOAuth } = await import("./auth");
+			mocks.getSession.mockResolvedValueOnce({ user: { id: "owner" } });
+			mocks.continueOAuth.mockResolvedValueOnce(Response.json(body));
+			const response = await handleOAuth(new Request("http://localhost:3000/api/auth/oauth?sig=signed"));
+			expect(response.status).toBe(502);
+			expect(response.headers.get("location")).toBeNull();
+			expect(mocks.consent).not.toHaveBeenCalled();
+		},
+	);
+});

apps/server/src/http/auth.ts

@@ -1,10 +1,6 @@
-import crypto from "node:crypto";
-import { eq } from "drizzle-orm";
+import { APIError } from "better-auth/api";
 import { auth } from "@reactive-resume/auth/config";
-import { db } from "@reactive-resume/db/client";
-import { oauthClient, verification } from "@reactive-resume/db/schema";
 import { env } from "@reactive-resume/env/server";
-import { generateId } from "@reactive-resume/utils/string";
 import { isAllowedOAuthRedirectUri } from "@reactive-resume/utils/url-security.node";
 
 const oauthAuthorizeSanitizedParams = [
@@ -19,8 +15,6 @@ const oauthAuthorizeSanitizedParams = [
 	"resource",
 ] as const;
 
-const oauthCallbackPassthroughExcludedParams = new Set(["exp", "sig"]);
-
 function sanitizeOAuthAuthorizeRequest(request: Request): Request {
 	if (request.method !== "GET") return request;
 
@@ -33,9 +27,10 @@ function sanitizeOAuthAuthorizeRequest(request: Request): Request {
 			.replace(/\s+/g, " ")
 			.trim();
 	const sanitizeParam = (key: string) => {
-		const value = url.searchParams.get(key);
-		if (!value) return;
-		url.searchParams.set(key, sanitizeValue(value));
+		const values = url.searchParams.getAll(key);
+		if (!values.length) return;
+		url.searchParams.delete(key);
+		for (const value of values) url.searchParams.append(key, sanitizeValue(value));
 	};
 
 	for (const key of oauthAuthorizeSanitizedParams) sanitizeParam(key);
@@ -56,6 +51,10 @@ function sanitizeOAuthAuthorizeRequest(request: Request): Request {
 	return new Request(url.toString(), request);
 }
 
+function isRegistrationPayload(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 async function defaultPublicClientRegistration(request: Request): Promise<Request> {
 	if (request.method !== "POST") return request;
 
@@ -66,13 +65,29 @@ async function defaultPublicClientRegistration(request: Request): Promise<Reques
 	let body: Record<string, unknown>;
 
 	try {
-		body = await cloned.json();
+		const payload: unknown = await cloned.json();
+		if (!isRegistrationPayload(payload)) return request;
+		body = payload;
 	} catch {
 		return request;
 	}
 
+	// MCP native clients often omit OIDC application_type. Infer it only for
+	// exact HTTP loopback callbacks; the provider still validates every URI.
+	if (body.application_type === undefined && Array.isArray(body.redirect_uris) && body.redirect_uris.length > 0) {
+		const allLoopback = body.redirect_uris.every(
+			(uri: unknown) =>
+				typeof uri === "string" && /^http:\/\/(?:localhost|127\.0\.0\.1|\[::1\])(?::[0-9]+)?(?:[/?]|$)/i.test(uri),
+		);
+		if (allLoopback) body.application_type = "native";
+	}
+
+	// MCP clients that authenticate with PKCE alone omit the method, and Better Auth
+	// would otherwise register them as `client_secret_basic`. Honor an explicit choice:
+	// forcing it to "none" issues no client secret, so the client's own Basic/post
+	// credentials are rejected at the token endpoint with 401 invalid_client.
 	if (!request.headers.get("authorization")) {
-		body.token_endpoint_auth_method = "none";
+		body.token_endpoint_auth_method ??= "none";
 	}
 
 	return new Request(url.toString(), {
@@ -92,7 +107,11 @@ async function validateDynamicClientRegistrationRequest(request: Request): Promi
 	let body: Record<string, unknown>;
 
 	try {
-		body = await cloned.json();
+		const payload: unknown = await cloned.json();
+		if (!isRegistrationPayload(payload)) {
+			return Response.json({ message: "Invalid registration payload" }, { status: 400 });
+		}
+		body = payload;
 	} catch {
 		return Response.json({ message: "Invalid registration payload" }, { status: 400 });
 	}
@@ -125,90 +144,68 @@ export async function handleAuth(request: Request) {
 	return auth.handler(finalRequest);
 }
 
-function generateCode() {
-	return crypto.randomBytes(32).toString("base64url");
-}
-
-function hashCode(code: string) {
-	return crypto.createHash("sha256").update(code).digest("base64url");
-}
-
 export async function handleOAuth(request: Request) {
+	try {
+		return await resumeOAuth(request);
+	} catch (error) {
+		// Before-hooks can throw even when the provider is called with asResponse.
+		if (error instanceof APIError) return Response.json(error.body, { status: error.statusCode });
+		throw error;
+	}
+}
+
+async function resumeOAuth(request: Request) {
 	const session = await auth.api.getSession({ headers: request.headers });
 	const url = new URL(request.url);
 
 	if (session?.user) {
-		const clientId = url.searchParams.get("client_id");
-		const redirectUri = url.searchParams.get("redirect_uri");
-		const state = url.searchParams.get("state");
-		const scope = url.searchParams.get("scope");
-		const codeChallenge = url.searchParams.get("code_challenge");
-		const codeChallengeMethod = url.searchParams.get("code_challenge_method");
-
-		if (!clientId || !redirectUri) {
-			return Response.json({ error: "missing client_id or redirect_uri" }, { status: 400 });
-		}
-
-		const [client] = await db.select().from(oauthClient).where(eq(oauthClient.clientId, clientId)).limit(1);
-
-		if (!client) {
-			return Response.json({ error: "invalid client" }, { status: 400 });
-		}
-
-		if (!client.redirectUris.includes(redirectUri)) {
-			return Response.json({ error: "invalid redirect_uri" }, { status: 400 });
-		}
-
-		const code = generateCode();
-		const hashedCode = hashCode(code);
-		const now = new Date();
-		const expiresAt = new Date(now.getTime() + 600_000);
-
-		await db.insert(verification).values({
-			id: generateId(),
-			identifier: hashedCode,
-			value: JSON.stringify({
-				type: "authorization_code",
-				query: {
-					response_type: "code",
-					client_id: clientId,
-					redirect_uri: redirectUri,
-					scope,
-					state,
-					code_challenge: codeChallenge,
-					code_challenge_method: codeChallengeMethod,
-				},
-				userId: session.user.id,
-				sessionId: session.session.id,
-				authTime: new Date(session.session.createdAt).getTime(),
-			}),
-			expiresAt,
-			createdAt: now,
-			updatedAt: now,
-		});
-
-		const callbackUrl = new URL(redirectUri);
-		callbackUrl.searchParams.set("code", code);
-		if (state) callbackUrl.searchParams.set("state", state);
-		callbackUrl.searchParams.set("iss", `${env.APP_URL}/api/auth`);
-
-		return new Response(null, {
-			status: 302,
-			headers: { Location: callbackUrl.toString() },
+		// Resume authorization without granting consent. The provider decides whether
+		// the user must sign in, explicitly approve a client, or reuse an existing grant.
+		// Its signed query must survive the login round trip byte-for-byte.
+		const response = await auth.api.oauth2Continue({
+			asResponse: true,
+			request,
+			headers: request.headers,
+			body: { postLogin: true, oauth_query: url.search.slice(1) },
 		});
+		if (!(response instanceof Response)) throw new Error("OAuth provider did not return a response");
+		if (!response.ok) return response;
+		const result: unknown = await response.json().catch(() => null);
+		if (
+			!result ||
+			typeof result !== "object" ||
+			!("url" in result) ||
+			typeof result.url !== "string" ||
+			!result.url ||
+			!(result.url.startsWith("/") || URL.canParse(result.url)) ||
+			!URL.canParse(result.url, env.APP_URL)
+		)
+			return Response.json({ error: "invalid_provider_response" }, { status: 502 });
+		const headers = new Headers(response.headers);
+		headers.delete("content-type");
+		headers.delete("content-length");
+		const target = new URL(result.url, env.APP_URL);
+		if (["javascript:", "data:", "vbscript:", "file:", "blob:"].includes(target.protocol)) {
+			return Response.json({ error: "invalid_provider_response" }, { status: 502 });
+		}
+		if (target.origin === new URL(env.APP_URL).origin && target.pathname === "/api/auth/oauth") {
+			return redirectToOAuthLogin(target, true, headers);
+		}
+		headers.set("Location", result.url);
+		return new Response(null, { status: 302, headers });
 	}
 
-	const loginUrl = new URL("/auth/login", env.APP_URL);
-	const oauthParams = new URLSearchParams();
-	for (const [key, value] of url.searchParams) {
-		if (!oauthCallbackPassthroughExcludedParams.has(key)) {
-			oauthParams.set(key, value);
-		}
-	}
-	loginUrl.searchParams.set("callbackURL", `/api/auth/oauth?${oauthParams.toString()}`);
+	return redirectToOAuthLogin(url);
+}
 
+function redirectToOAuthLogin(url: URL, reauthenticate = false, headers = new Headers()) {
+	const prompt = new Set(url.searchParams.get("prompt")?.split(" ") ?? []);
+	const loginUrl = new URL(prompt.has("create") ? "/auth/register" : "/auth/login", env.APP_URL);
+	if (reauthenticate) loginUrl.searchParams.set("reauthenticate", "true");
+	loginUrl.searchParams.set("callbackURL", `/api/auth/oauth${url.search}`);
+	headers.set("Location", `${loginUrl.pathname}${loginUrl.search}`);
 	return new Response(null, {
 		status: 302,
-		headers: { Location: `${loginUrl.pathname}${loginUrl.search}` },
+		headers,
 	});
 }

apps/server/src/http/headers.ts

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

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

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

apps/server/src/http/health.ts

@@ -2,6 +2,8 @@ import { sql } from "drizzle-orm";
 import { withTimeout } from "es-toolkit";
 import { getStorageService } from "@reactive-resume/api/features/storage";
 import { db } from "@reactive-resume/db/client";
+import { getRedis } from "@reactive-resume/db/redis";
+import { appVersion } from "../app-version";
 
 const HEALTHCHECK_TIMEOUT_MS = 1_500;
 
@@ -31,6 +33,16 @@ async function runCheck(check: () => Promise<object>): Promise<CheckResult> {
 	}
 }
 
+function publicCheck(check: CheckResult, name: "Database" | "Storage" | "Redis"): CheckResult {
+	if (check.status === "healthy") return check;
+	return {
+		status: check.status,
+		latencyMs: check.latencyMs,
+		error: `${name} health check failed.`,
+		...(check.type === "local" || check.type === "s3" || check.type === "blob" ? { type: check.type } : {}),
+	};
+}
+
 // ponytail: inner try/catches removed; runCheck's outer catch handles all errors
 async function checkDatabase() {
 	await db.execute(sql`SELECT 1`);
@@ -40,30 +52,33 @@ async function checkDatabase() {
 const checkStorage = () => getStorageService().healthcheck();
 
 export async function handleHealth() {
-	const [database, storage] = await Promise.all([runCheck(checkDatabase), runCheck(checkStorage)]);
-	const status = [database, storage].some((check) => check.status === "unhealthy") ? "unhealthy" : "healthy";
+	const redisClient = getRedis();
+	const [database, storage, redis] = await Promise.all([
+		runCheck(checkDatabase),
+		runCheck(checkStorage),
+		redisClient
+			? runCheck(async () => {
+					await redisClient.ping();
+					return { status: "healthy" };
+				})
+			: undefined,
+	]);
+	const status = [database, storage, redis].some((check) => check?.status === "unhealthy") ? "unhealthy" : "healthy";
 
 	const checks = {
 		service: "reactive-resume",
-		version: process.env.npm_package_version,
+		version: appVersion,
 		status,
 		timestamp: new Date().toISOString(),
 		uptime: `${process.uptime().toFixed(2)}s`,
-		database,
-		storage,
+		database: publicCheck(database, "Database"),
+		storage: publicCheck(storage, "Storage"),
+		...(redis ? { redis: publicCheck(redis, "Redis") } : {}),
 	};
 
 	if (status === "unhealthy") {
 		console.warn("[Healthcheck]", { route: "/api/health", database, storage });
 	}
 
-	const headers = new Headers();
-	const body = JSON.stringify(checks);
-	headers.set("Content-Type", "application/json; charset=UTF-8");
-	headers.set("Content-Length", Buffer.byteLength(body, "utf-8").toString());
-
-	return new Response(body, {
-		headers,
-		status: checks.status === "unhealthy" ? 503 : 200,
-	});
+	return Response.json(checks, { status: checks.status === "unhealthy" ? 503 : 200 });
 }

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

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

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

@@ -6,16 +6,6 @@ const mocks = vi.hoisted(() => ({
 
 vi.mock("@reactive-resume/api/features/resume/public-pdf", () => ({
 	createPublicResumePdf: mocks.createPublicResumePdf,
-	PUBLIC_RESUME_PDF_MISMATCH_REASONS: [
-		"missing-projection",
-		"format-version",
-		"language-version",
-		"semantic-tree-version",
-		"registry-fingerprint",
-		"adapter-fingerprint",
-		"render-data-hash",
-		"invalid-projection",
-	],
 }));
 
 const { handlePublicResumePdf } = await import("./public-resume-pdf");
@@ -24,18 +14,15 @@ const trustedClient = "203.0.113.9";
 describe("handlePublicResumePdf", () => {
 	beforeEach(() => vi.clearAllMocks());
 
-	it("returns the authorized fallback PDF with strict mismatch metadata and cache policy", async () => {
+	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 registry = "0".repeat(64);
-		const adapter = "1".repeat(64);
-		const request = new Request(
-			`https://example.com/api/resumes/jane/resume/pdf?reason=render-data-hash&registryFingerprint=${registry}&adapterFingerprint=${adapter}`,
-			{ headers: { "x-forwarded-for": "203.0.113.7" } },
-		);
+		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);
 
@@ -50,60 +37,6 @@ describe("handlePublicResumePdf", () => {
 			slug: "resume",
 			requestHeaders: request.headers,
 			trustedClient,
-			mismatchReason: "render-data-hash",
-			clientRegistryFingerprint: registry,
-			clientAdapterFingerprint: adapter,
 		});
 	});
-
-	it("defaults a missing mismatch reason and keeps password/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(
-			expect.objectContaining({ mismatchReason: "missing-projection" }),
-		);
-	});
-
-	it.each([
-		[{ code: "BAD_REQUEST" }, 400],
-		[{ 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");
-	});
-
-	it.each(["?reason=private-source", "?registryFingerprint=unsafe", "?adapterFingerprint=unsafe"])(
-		"rejects invalid fallback metadata before the API service",
-		async (search) => {
-			const response = await handlePublicResumePdf(
-				new Request(`https://example.com/api/resumes/jane/resume/pdf${search}`),
-				"jane",
-				"resume",
-				trustedClient,
-			);
-
-			expect(response.status).toBe(400);
-			expect(response.headers.get("Cache-Control")).toBe("private, no-store");
-			expect(mocks.createPublicResumePdf).not.toHaveBeenCalled();
-		},
-	);
 });

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

@@ -1,57 +1,28 @@
-import type { PublicResumePdfMismatchReason } from "@reactive-resume/api/features/resume/public-pdf";
-import {
-	createPublicResumePdf,
-	PUBLIC_RESUME_PDF_MISMATCH_REASONS,
-} from "@reactive-resume/api/features/resume/public-pdf";
+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 === "BAD_REQUEST") return 400;
 	if (code === "NEED_PASSWORD") return 401;
 	if (code === "NOT_FOUND") return 404;
 	if (code === "RATE_LIMIT_EXCEEDED") return 429;
 	return 500;
 };
 
-const fingerprint = (value: string | null): string | undefined => {
-	if (value === null) return;
-	return /^[a-f0-9]{64}$/.test(value) ? value : undefined;
-};
-
 export async function handlePublicResumePdf(
 	request: Request,
 	username: string,
 	slug: string,
-	trustedClient = "unknown",
+	trustedClient: string,
 ): Promise<Response> {
-	const searchParams = new URL(request.url).searchParams;
-	const rawReason = searchParams.get("reason") ?? "missing-projection";
-	if (!PUBLIC_RESUME_PDF_MISMATCH_REASONS.includes(rawReason as PublicResumePdfMismatchReason)) {
-		return noStoreResponse("Invalid fallback metadata", 400);
-	}
-	const rawRegistryFingerprint = searchParams.get("registryFingerprint");
-	const rawAdapterFingerprint = searchParams.get("adapterFingerprint");
-	const clientRegistryFingerprint = fingerprint(rawRegistryFingerprint);
-	const clientAdapterFingerprint = fingerprint(rawAdapterFingerprint);
-	if (
-		(rawRegistryFingerprint !== null && clientRegistryFingerprint === undefined) ||
-		(rawAdapterFingerprint !== null && clientAdapterFingerprint === undefined)
-	) {
-		return noStoreResponse("Invalid fallback metadata", 400);
-	}
-
 	try {
 		const result = await createPublicResumePdf({
 			username,
 			slug,
 			requestHeaders: request.headers,
 			trustedClient,
-			mismatchReason: rawReason as PublicResumePdfMismatchReason,
-			...(clientRegistryFingerprint ? { clientRegistryFingerprint } : {}),
-			...(clientAdapterFingerprint ? { clientAdapterFingerprint } : {}),
 		});
 
 		return new Response(result.body, {
@@ -64,6 +35,7 @@ export async function handlePublicResumePdf(
 		});
 	} catch (error) {
 		const status = errorStatus(error);
+		if (status === 500) console.error("Public resume PDF generation failed", error);
 		return noStoreResponse(
 			status === 500 ? "Failed to generate public resume PDF" : "Public resume PDF unavailable",
 			status,

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

@@ -23,7 +23,6 @@ describe("handleResumePdfDownload", () => {
 			ok: true,
 			resumeId: "resume-1",
 			userId: "user-1",
-			target: "resume",
 			expiresAt: "2026-06-01T10:10:00.000Z",
 		});
 		mocks.createResumePdfDownload.mockResolvedValueOnce({
@@ -41,89 +40,7 @@ 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", 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();
+		expect(mocks.createResumePdfDownload).toHaveBeenCalledWith({ id: "resume-1", userId: "user-1" });
 	});
 
 	it("rejects missing, invalid, and expired tokens before rendering", async () => {

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

@@ -30,17 +30,13 @@ export async function handleResumePdfDownload(request: Request, id: string) {
 
 	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();
+	// Links made before letters left resumes may ask for the resume's cover letter, which is now a letter of its own.
+	const target = searchParams.get("target");
+	if (target && target !== "resume")
+		return new Response("Not found", { status: 404, headers: { "Cache-Control": "private, no-store" } });
 
 	try {
-		const target = verification.target ?? "resume";
-		const download = await createResumePdfDownload({ id, userId: verification.userId, target });
+		const download = await createResumePdfDownload({ id, userId: verification.userId });
 
 		return new Response(download.body, {
 			headers: {

apps/server/src/index.test.ts

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

apps/server/src/index.ts

@@ -1,15 +1,16 @@
 import { pathToFileURL } from "node:url";
 import { serve } from "@hono/node-server";
 import { env } from "@reactive-resume/env/server";
-import { createApp } from "./http/app";
-import { stylesheetPreflightRunner } from "./services/stylesheet-preflight";
 import { runStartupChecks } from "./startup/checks";
 
-export { createApp } from "./http/app";
-
-async function main() {
+export async function main() {
 	await runStartupChecks();
 
+	// Load and initialize auth only after migrations have created the provider tables.
+	const { createApp } = await import("./http/app");
+	const { initializeAuth } = await import("@reactive-resume/auth/config");
+	await initializeAuth();
+
 	// Safety net: Node 24 crashes the whole process on an unhandled rejection. One request's
 	// stray promise must not take the server down for everyone, so log and keep serving.
 	// Registered after startup checks so a broken startup still fails loudly. (Left uncaught
@@ -32,10 +33,6 @@ async function main() {
 			console.info(`🚀 Up and running on http://localhost:${info.port}`);
 		},
 	);
-
-	// Load the heavy PDF preflight runtime once, now, so the first semantic-CSS edit
-	// does not pay (and time out on) the cold worker start.
-	stylesheetPreflightRunner.warmup();
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {

apps/server/src/mcp/server.ts

@@ -3,7 +3,13 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { onError } from "@orpc/client";
 import { createRouterClient } from "@orpc/server";
 import router from "@reactive-resume/api/routers";
-import { MCP_TOOL_NAME, registerPrompts, registerResources, registerTools } from "@reactive-resume/mcp";
+import {
+	buildMcpServerInfo,
+	MCP_TOOL_NAME,
+	registerPrompts,
+	registerResources,
+	registerTools,
+} from "@reactive-resume/mcp";
 import { appVersion } from "../app-version";
 import { getRequestLocale } from "../rpc/locale";
 
@@ -23,41 +29,19 @@ function createRequestClient(request: Request): RouterClient<typeof router> {
 }
 
 export function createMcpServer(request: Request) {
-	const server = new McpServer(
-		{
-			name: "reactive-resume",
-			version: appVersion,
-			title: "Reactive Resume",
-			websiteUrl: "https://rxresu.me",
-			description:
-				"Reactive Resume is a free and open-source resume builder. Use this MCP server to interact with your resume using an LLM of your choice.",
-			icons: [
-				{
-					src: "https://rxresu.me/icon/light.svg",
-					mimeType: "image/svg+xml",
-					theme: "light",
-				},
-				{
-					src: "https://rxresu.me/icon/dark.svg",
-					mimeType: "image/svg+xml",
-					theme: "dark",
-				},
-			],
-		},
-		{
-			instructions: [
-				"You are connected to Reactive Resume over MCP.",
-				"Authenticate with OAuth (recommended) or an API key (`x-api-key`).",
-				`Discover resume IDs with \`${MCP_TOOL_NAME.listResumes}\` (not \`resources/list\`).`,
-				`List distinct tags with \`${MCP_TOOL_NAME.listResumeTags}\`.`,
-				`Read schema at \`resume://_meta/schema\`; read resume JSON via \`resume://{id}\` or \`${MCP_TOOL_NAME.getResume}\`.`,
-				`Apply body edits with JSON Patch through \`${MCP_TOOL_NAME.patchResume}\`.`,
-				`Change name, slug, tags, or public visibility with \`${MCP_TOOL_NAME.updateResume}\` (returns canonical share URL; anonymous access only when \`isPublic\` is true; passwords are managed in the web app only).`,
-				`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}\`; read saved AI analysis with \`${MCP_TOOL_NAME.getResumeAnalysis}\`.`,
-			].join(" "),
-		},
-	);
+	const server = new McpServer(buildMcpServerInfo(appVersion), {
+		instructions: [
+			"You are connected to Reactive Resume over MCP.",
+			"Authenticate with OAuth (recommended) or an API key (`x-api-key`).",
+			`Discover resume IDs with \`${MCP_TOOL_NAME.listResumes}\` (not \`resources/list\`).`,
+			`List distinct tags with \`${MCP_TOOL_NAME.listResumeTags}\`.`,
+			`Read schema at \`resume://_meta/schema\`; read resume JSON via \`resume://{id}\` or \`${MCP_TOOL_NAME.getResume}\`.`,
+			`Apply body edits with JSON Patch through \`${MCP_TOOL_NAME.patchResume}\`.`,
+			`Change name, slug, tags, or public visibility with \`${MCP_TOOL_NAME.updateResume}\` (returns canonical share URL; anonymous access only when \`isPublic\` is true; passwords are managed in the web app only).`,
+			`Create short-lived authenticated PDF download URLs with \`${MCP_TOOL_NAME.downloadResumePdf}\`; set target to \`cover-letter\` to export a visible cover letter separately.`,
+			`Import full ResumeData JSON with \`${MCP_TOOL_NAME.importResume}\`.`,
+		].join(" "),
+	});
 
 	const client = createRequestClient(request);
 	registerResources(server, client);

apps/server/src/migrate-legacy-styles.ts

@@ -0,0 +1,69 @@
+import type { StylesheetChange } from "@reactive-resume/api/features/resume/legacy-styles-migration";
+import { closeSync, openSync, readFileSync, writeSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+import { migrateLegacyStyles, restoreLegacyStyles } from "@reactive-resume/api/features/resume/legacy-styles-migration";
+import { env } from "@reactive-resume/env/server";
+
+const usage = `Converts resumes and letters still styled by the old style editor (legacy style rules) to Semantic CSS.
+Uses DATABASE_URL. Run it once after deploying the version without the legacy renderer.
+
+  node apps/server/dist/migrate-legacy-styles.mjs
+      Dry run: converts every row that needs it in memory and reports the counts. Writes nothing.
+
+  node apps/server/dist/migrate-legacy-styles.mjs --apply --backup <file>
+      Converts and saves. Every replaced stylesheet is appended to <file> (NDJSON) before its row is written.
+      Safe to run again or after an interruption: converted rows are skipped. Use a new file or the same one.
+
+  node apps/server/dist/migrate-legacy-styles.mjs --restore <file>
+      Puts back the stylesheets recorded in <file>, except on rows whose stylesheet was edited since.
+`;
+
+const { values } = parseArgs({
+	options: {
+		apply: { type: "boolean", default: false },
+		backup: { type: "string" },
+		restore: { type: "string" },
+		help: { type: "boolean", default: false },
+	},
+});
+
+if (values.help || (values.apply && !values.backup) || (values.restore && (values.apply || values.backup))) {
+	console.info(usage);
+	process.exit(values.help ? 0 : 1);
+}
+
+// Opened before connecting, so an unwritable path fails before anything changes.
+const backup = values.backup ? openSync(values.backup, "a") : undefined;
+
+const pool = new Pool({ connectionString: env.DATABASE_URL, max: 1, connectionTimeoutMillis: 10_000 });
+const client = await pool.connect();
+const log = (message: string) => console.info(`[${new Date().toISOString()}] ${message}`);
+
+try {
+	// Finding the rows is one scan per table, which can outlast the database's default statement timeout.
+	await client.query("SET statement_timeout = 0");
+	const db = drizzle({ client });
+
+	if (values.restore) {
+		const changes = readFileSync(values.restore, "utf8")
+			.split("\n")
+			.filter((line) => line.trim())
+			.map((line) => JSON.parse(line) as StylesheetChange);
+		log(`Restoring ${changes.length} stylesheets from ${values.restore}`);
+		log(`Done: ${JSON.stringify(await restoreLegacyStyles(db, changes))}`);
+	} else {
+		log(values.apply ? `Converting, backing up to ${values.backup}` : "Dry run: nothing will be written");
+		const summary = await migrateLegacyStyles(db, {
+			apply: values.apply,
+			log,
+			...(backup === undefined ? {} : { onChange: (change) => writeSync(backup, `${JSON.stringify(change)}\n`) }),
+		});
+		log(`Done: ${JSON.stringify(summary)}`);
+	}
+} finally {
+	if (backup !== undefined) closeSync(backup);
+	client.release();
+	await pool.end();
+}

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

@@ -1,7 +1,7 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 
-export async function generateOpenApiDocumentation(
+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 {

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

@@ -1,8 +1,11 @@
-import { describe, expect, it } from "vitest";
-import z from "zod";
-import { defaultResumeData } from "@reactive-resume/schema/resume/default";
+import { describe, expect, it, vi } from "vitest";
 import { createResumeDataJsonSchema } from "@reactive-resume/schema/resume/json-schema";
 
+// Spec generation reads procedure contracts without executing authentication. Keep the
+// provider's resource seeding out of this unit test; real OAuth initialization is covered
+// by the opt-in PostgreSQL integration suite after migrations run.
+vi.mock("@reactive-resume/auth/config", () => ({ auth: {}, verifyOAuthToken: vi.fn() }));
+
 type GeneratedSpecView = {
 	components?: { schemas?: Record<string, unknown> };
 	paths?: Record<
@@ -18,10 +21,12 @@ type GeneratedSpecView = {
 	>;
 };
 
-async function generateSpec() {
-	process.env.APP_URL ??= "https://rxresu.me";
-	process.env.DATABASE_URL ??= "postgresql://localhost/reactive_resume_test";
-	process.env.AUTH_SECRET ??= "openapi-generator-test-process-only";
+// 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",
@@ -29,6 +34,11 @@ async function generateSpec() {
 	});
 }
 
+function generateSpec() {
+	specPromise ??= generateOnce();
+	return specPromise;
+}
+
 function getRequestSchema(spec: GeneratedSpecView, path: string, method: string) {
 	return spec.paths?.[path]?.[method]?.requestBody?.content?.["application/json"]?.schema;
 }
@@ -59,20 +69,6 @@ function findImpossibleRequestSchemas(spec: GeneratedSpecView) {
 }
 
 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();
@@ -83,65 +79,11 @@ describe("generateOpenApiSpec", () => {
 				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);
-	});
+	}, 15_000);
 
 	it("does not publish impossible request schemas", async () => {
 		const spec = (await generateSpec()) as GeneratedSpecView;
 
 		expect(findImpossibleRequestSchemas(spec)).toEqual([]);
 	});
-
-	it("checks every request body media type for impossible schemas", () => {
-		const spec: GeneratedSpecView = {
-			paths: {
-				"/documents": {
-					post: {
-						requestBody: {
-							content: {
-								"application/json": { schema: { type: "object" } },
-								"multipart/form-data": { schema: { not: {} } },
-							},
-						},
-					},
-				},
-			},
-		};
-
-		expect(findImpossibleRequestSchemas(spec)).toEqual(["POST /documents (multipart/form-data)"]);
-	});
-
-	it("documents imported data as an accepted ResumeData input", async () => {
-		const spec = (await generateSpec()) as GeneratedSpecView;
-
-		expect(getRequestSchema(spec, "/resumes/import", "post")).toEqual({
-			type: "object",
-			properties: {
-				data: { $ref: "#/components/schemas/ResumeData" },
-			},
-			required: ["data"],
-		});
-	});
 });

apps/server/src/openapi/generator.ts

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

apps/server/src/openapi/handler.ts

@@ -25,7 +25,7 @@ const openAPIHandler = new OpenAPIHandler(openAPIRouter, {
 	],
 });
 
-export async function handleOpenApi(request: Request, trustedClient = "unknown") {
+export async function handleOpenApi(request: Request, trustedClient: string) {
 	if (request.method === "GET" && (request.url.endsWith("/spec.json") || request.url.endsWith("/spec"))) {
 		return Response.json(await generateOpenApiSpec({ appUrl: env.APP_URL, version: appVersion }));
 	}

apps/server/src/prepare-deployment.ts

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

apps/server/src/rpc/handler.ts

@@ -3,7 +3,6 @@ import { RPCHandler } from "@orpc/server/fetch";
 import { BatchHandlerPlugin, RequestHeadersPlugin, StrictGetMethodPlugin } from "@orpc/server/plugins";
 import router from "@reactive-resume/api/routers";
 import { mergeResponseHeaders } from "../http/headers";
-import { stylesheetPreflightRunner } from "../services/stylesheet-preflight";
 import { getRequestLocale } from "./locale";
 
 const rpcHandler = new RPCHandler(router, {
@@ -15,7 +14,7 @@ const rpcHandler = new RPCHandler(router, {
 	],
 });
 
-export async function handleRpc(request: Request, trustedClient = "unknown") {
+export async function handleRpc(request: Request, trustedClient: string) {
 	const resHeaders = new Headers();
 	const { response } = await rpcHandler.handle(request, {
 		prefix: "/api/rpc",
@@ -24,7 +23,6 @@ export async function handleRpc(request: Request, trustedClient = "unknown") {
 			reqHeaders: request.headers,
 			resHeaders,
 			trustedClient,
-			stylesheetPreflightRunner,
 		},
 	});
 

apps/server/src/rpc/locale.ts

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

apps/server/src/services/stylesheet-preflight.test.ts

@@ -1,332 +0,0 @@
-import { afterEach, describe, expect, it } from "vitest";
-import { defaultResumeData } from "@reactive-resume/schema/resume/default";
-import { createStylesheetPreflightRunner, STYLESHEET_PREFLIGHT_LIMITS } from "./stylesheet-preflight";
-
-const validStylesheet = {
-	languageVersion: 1,
-	text: "@version 1;",
-} as const;
-
-const input = {
-	data: defaultResumeData,
-	template: defaultResumeData.metadata.template,
-	stylesheet: validStylesheet,
-} as const;
-
-// Runners now own a long-lived, reused worker; destroy them so no worker thread
-// outlives its test.
-const runners: Array<{ destroy(): Promise<void> }> = [];
-const track = <T extends { destroy(): Promise<void> }>(runner: T): T => {
-	runners.push(runner);
-	return runner;
-};
-afterEach(async () => {
-	await Promise.all(runners.splice(0).map((runner) => runner.destroy()));
-});
-
-const memoryExhaustionWorker = new URL(
-	`data:text/javascript,${encodeURIComponent(`
-		const retained = [];
-		while (true) {
-			const batch = Array.from({ length: 100_000 }, (_, index) => ({ batch: retained.length, index }));
-			retained.push(batch);
-		}
-	`)}`,
-);
-
-const failedWorker = new URL(
-	`data:text/javascript,${encodeURIComponent('throw new Error("sensitive worker details");')}`,
-);
-
-// Counts how many preflights this single worker instance served so a reuse test
-// can prove the worker is not respawned per request.
-const reuseCountingWorker = new URL(
-	`data:text/javascript,${encodeURIComponent(`
-		import { parentPort } from "node:worker_threads";
-		let served = 0;
-		parentPort.postMessage({ type: "ready" });
-		parentPort.on("message", (message) => {
-			if (message?.type !== "preflight") return;
-			served += 1;
-			parentPort.postMessage({
-				type: "result",
-				requestId: message.requestId,
-				result: { ok: true, pageCount: 1, byteCount: served, diagnostics: [] },
-			});
-		});
-	`)}`,
-);
-
-const delayedSuccessfulWorker = new URL(
-	`data:text/javascript,${encodeURIComponent(`
-		import { parentPort } from "node:worker_threads";
-		parentPort.postMessage({ type: "ready" });
-		parentPort.on("message", (message) => {
-			if (message?.type !== "preflight") return;
-			setTimeout(() => {
-				parentPort.postMessage({
-					type: "result",
-					requestId: message.requestId,
-					result: {
-						ok: true,
-						pageCount: 1,
-						byteCount: Number(message.input.data.basics.name),
-						diagnostics: [],
-					},
-				});
-			}, 300);
-		});
-	`)}`,
-);
-
-const delayedReadyWorker = new URL(
-	`data:text/javascript,${encodeURIComponent(`
-		import { parentPort } from "node:worker_threads";
-		parentPort.on("message", (message) => {
-			if (message?.type !== "preflight") return;
-			setTimeout(() => {
-				parentPort.postMessage({
-					type: "result",
-					requestId: message.requestId,
-					result: { ok: true, pageCount: 1, byteCount: 1, diagnostics: [] },
-				});
-			}, 10);
-		});
-		setTimeout(() => parentPort.postMessage({ type: "ready" }), 50);
-	`)}`,
-);
-
-const neverCompletesWorker = new URL(
-	`data:text/javascript,${encodeURIComponent(`
-		import { parentPort } from "node:worker_threads";
-		parentPort.postMessage({ type: "ready" });
-		setInterval(() => {}, 1_000);
-	`)}`,
-);
-
-const synchronousFailureWorker = new URL("https://example.com/stylesheet-preflight.mjs");
-
-const numberedInput = (number: number) => ({
-	...input,
-	data: {
-		...input.data,
-		basics: {
-			...input.data.basics,
-			name: String(number),
-		},
-	},
-});
-
-const invalidInput = () => {
-	const data = structuredClone(defaultResumeData);
-	data.customSections = [
-		{
-			id: "custom-experience",
-			type: "experience",
-			title: "Experience",
-			icon: "",
-			columns: 1,
-			hidden: false,
-			keepTogether: false,
-			startOnNewPage: false,
-			items: [{ id: "summary-shaped-item", hidden: false, content: "<p>Missing company</p>" }],
-		} as never,
-	];
-	return { ...input, data };
-};
-
-describe("stylesheet PDF preflight worker", () => {
-	it("keeps the production resource policy fixed and immutable", () => {
-		expect(STYLESHEET_PREFLIGHT_LIMITS).toEqual({
-			timeoutMs: 30_000,
-			maxPages: 20,
-			maxBytes: 10_000_000,
-			maxPageWidthPt: 2_000,
-			maxPageHeightPt: 20_000,
-			maxPageAreaPt2: 20_000_000,
-			maxOldGenerationMb: 256,
-			maxConcurrentWorkers: 1,
-			maxQueuedRequests: 32,
-		});
-		expect(Object.isFrozen(STYLESHEET_PREFLIGHT_LIMITS)).toBe(true);
-	});
-
-	it("accepts a bounded candidate render in an isolated worker", async () => {
-		const runner = track(createStylesheetPreflightRunner({ timeoutMs: 15_000 }));
-
-		const result = await runner.run(input);
-
-		expect(result).toEqual(
-			expect.objectContaining({
-				ok: true,
-				pageCount: 1,
-				byteCount: expect.any(Number),
-			}),
-		);
-		if (!result.ok) throw new Error(`Expected successful preflight, received ${result.code}.`);
-		expect(result.byteCount).toBeGreaterThan(0);
-		expect(runner.activeWorkerCount).toBe(0);
-	}, 45_000);
-
-	it("reuses one warm worker across sequential requests instead of cold-starting each one", async () => {
-		const runner = track(createStylesheetPreflightRunner({}, reuseCountingWorker));
-
-		const first = await runner.run(input);
-		const second = await runner.run(input);
-		const third = await runner.run(input);
-
-		// A single reused worker increments its per-instance counter; a per-request
-		// worker would report byteCount 1 every time.
-		expect([first, second, third].map((result) => (result.ok ? result.byteCount : -1))).toEqual([1, 2, 3]);
-		expect(runner.activeWorkerCount).toBe(0);
-		expect(runner.queuedPreflightCount).toBe(0);
-	});
-
-	it("preserves structured resume-data failures across the worker boundary", async () => {
-		const runner = track(createStylesheetPreflightRunner({ timeoutMs: 15_000 }));
-
-		const result = runner.run(invalidInput());
-
-		await expect(result).rejects.toMatchObject({
-			name: "ZodError",
-			issues: expect.arrayContaining([expect.objectContaining({ path: ["customSections", 0, "items", 0, "company"] })]),
-		});
-		expect(runner.activeWorkerCount).toBe(0);
-		expect(runner.queuedPreflightCount).toBe(0);
-	}, 20_000);
-
-	it("terminates a worker when the render exceeds its deadline", async () => {
-		const runner = track(createStylesheetPreflightRunner({ timeoutMs: 1 }, neverCompletesWorker));
-
-		const result = await runner.run(input);
-
-		expect(result).toEqual(expect.objectContaining({ ok: false, code: "STYLESHEET_PREFLIGHT_TIMEOUT" }));
-		expect(runner.activeWorkerCount).toBe(0);
-		expect(runner.queuedPreflightCount).toBe(0);
-	});
-
-	it("starts the authored render deadline after the worker runtime is ready", async () => {
-		const runner = track(createStylesheetPreflightRunner({ timeoutMs: 20 }, delayedReadyWorker));
-
-		await expect(runner.run(input)).resolves.toEqual(expect.objectContaining({ ok: true, pageCount: 1 }));
-		expect(runner.activeWorkerCount).toBe(0);
-	});
-
-	it("returns deterministic output byte and page limit codes", async () => {
-		const byteRunner = track(createStylesheetPreflightRunner({ maxBytes: 16 }));
-		const pageRunner = track(createStylesheetPreflightRunner({ maxPages: 0 }));
-
-		await expect(byteRunner.run(input)).resolves.toEqual(
-			expect.objectContaining({ ok: false, code: "STYLESHEET_PREFLIGHT_BYTE_LIMIT" }),
-		);
-		await expect(pageRunner.run(input)).resolves.toEqual(
-			expect.objectContaining({ ok: false, code: "STYLESHEET_PREFLIGHT_PAGE_LIMIT" }),
-		);
-		expect(byteRunner.activeWorkerCount).toBe(0);
-		expect(pageRunner.activeWorkerCount).toBe(0);
-	}, 30_000);
-
-	it("maps worker heap exhaustion to a controlled memory-limit result", async () => {
-		const runner = track(
-			createStylesheetPreflightRunner({ maxOldGenerationMb: 8, timeoutMs: 10_000 }, memoryExhaustionWorker),
-		);
-
-		const result = await runner.run(input);
-
-		expect(result).toEqual(expect.objectContaining({ ok: false, code: "STYLESHEET_PREFLIGHT_MEMORY_LIMIT" }));
-		expect(runner.activeWorkerCount).toBe(0);
-	}, 15_000);
-
-	it("does not expose internal errors from a failed worker bootstrap", async () => {
-		const runner = track(createStylesheetPreflightRunner({}, failedWorker));
-
-		const result = await runner.run(input);
-
-		expect(result).toEqual({
-			ok: false,
-			code: "STYLESHEET_PREFLIGHT_WORKER_FAILED",
-			message: "The PDF preflight worker failed.",
-			diagnostics: [],
-		});
-		expect(runner.activeWorkerCount).toBe(0);
-		expect(runner.queuedPreflightCount).toBe(0);
-	});
-
-	it("surfaces sanitized render failures from inside the worker catch path", async () => {
-		const throwingWorker = new URL(
-			`data:text/javascript,${encodeURIComponent(`
-				import { parentPort } from "node:worker_threads";
-				parentPort.postMessage({ type: "ready" });
-				parentPort.on("message", (message) => {
-					if (message?.type !== "preflight") return;
-					parentPort.postMessage({
-						type: "result",
-						requestId: message.requestId,
-						result: {
-							ok: false,
-							code: "STYLESHEET_PREFLIGHT_WORKER_FAILED",
-							message: "The PDF preflight worker failed. (Error: Canvas is already closed)",
-							diagnostics: [],
-						},
-					});
-				});
-			`)}`,
-		);
-		const runner = track(createStylesheetPreflightRunner({ timeoutMs: 5_000 }, throwingWorker));
-
-		const result = await runner.run(input);
-
-		expect(result).toEqual({
-			ok: false,
-			code: "STYLESHEET_PREFLIGHT_WORKER_FAILED",
-			message: "The PDF preflight worker failed. (Error: Canvas is already closed)",
-			diagnostics: [],
-		});
-	});
-
-	it("bounds concurrent workers and queued requests without charging queue time to the worker deadline", async () => {
-		const runner = track(
-			createStylesheetPreflightRunner(
-				{
-					timeoutMs: 500,
-					maxConcurrentWorkers: 1,
-					maxQueuedRequests: 2,
-				},
-				delayedSuccessfulWorker,
-			),
-		);
-		const completionOrder: number[] = [];
-		const accepted = [1, 2, 3].map((number) =>
-			runner.run(numberedInput(number)).then((result) => {
-				if (result.ok) completionOrder.push(result.byteCount);
-				return result;
-			}),
-		);
-		const rejected = runner.run(numberedInput(4));
-
-		expect(runner.activeWorkerCount).toBe(1);
-		expect(runner.queuedPreflightCount).toBe(2);
-		await expect(rejected).resolves.toEqual(
-			expect.objectContaining({
-				code: "STYLESHEET_PREFLIGHT_WORKER_FAILED",
-				message: "The PDF preflight queue is full.",
-			}),
-		);
-		const results = await Promise.all(accepted);
-
-		expect(results.every((result) => result.ok)).toBe(true);
-		expect(completionOrder).toEqual([1, 2, 3]);
-		expect(runner.activeWorkerCount).toBe(0);
-		expect(runner.queuedPreflightCount).toBe(0);
-	}, 5_000);
-
-	it("does not leak a slot when the worker constructor throws synchronously", async () => {
-		const runner = track(createStylesheetPreflightRunner({}, synchronousFailureWorker));
-
-		await expect(runner.run(input)).resolves.toEqual(
-			expect.objectContaining({ ok: false, code: "STYLESHEET_PREFLIGHT_WORKER_FAILED" }),
-		);
-		expect(runner.activeWorkerCount).toBe(0);
-		expect(runner.queuedPreflightCount).toBe(0);
-	});
-});

apps/server/src/services/stylesheet-preflight.ts

@@ -1,362 +0,0 @@
-import type {
-	PdfPreflightFailure,
-	PdfPreflightResult,
-	StylesheetPreflightInput,
-	StylesheetPreflightRunner,
-} from "@reactive-resume/pdf/server";
-import { fileURLToPath } from "node:url";
-import { Worker } from "node:worker_threads";
-import { STYLESHEET_PREFLIGHT_LIMITS } from "@reactive-resume/pdf/preflight-reference";
-
-export { STYLESHEET_PREFLIGHT_LIMITS } from "@reactive-resume/pdf/preflight-reference";
-
-type StylesheetPreflightLimits = {
-	timeoutMs: number;
-	maxPages: number;
-	maxBytes: number;
-	maxPageWidthPt: number;
-	maxPageHeightPt: number;
-	maxPageAreaPt2: number;
-	maxOldGenerationMb: number;
-	maxConcurrentWorkers: number;
-	maxQueuedRequests: number;
-};
-
-const SOURCE_WORKER_LOADER_HEAP_MB = 256;
-// The worker is warmed once and reused, so the one-time cold load (which is
-// super-linear in available CPU — measured ~9s at 0.5 vCPU, ~53s at 0.35, ~93s at
-// 0.25) is paid at startup, not per request. This ceiling must exceed that cold
-// load or warmup is killed mid-bootstrap and never completes on a throttled box;
-// it only bounds a genuinely stuck bootstrap and is off the per-edit path.
-const WORKER_READINESS_TIMEOUT_MS = 120_000;
-
-type SerializedPreflightCause = {
-	name: string;
-	message: string;
-	issues: readonly unknown[];
-};
-
-type StylesheetPreflightWorkerMessage =
-	| { type: "ready" }
-	| { type: "load_error"; message: string }
-	| { type: "result"; requestId: number; result: PdfPreflightResult }
-	| { type: "preflight_error"; requestId: number; cause: SerializedPreflightCause };
-
-export type NodeStylesheetPreflightRunner = StylesheetPreflightRunner & {
-	readonly activeWorkerCount: number;
-	readonly queuedPreflightCount: number;
-	warmup(): void;
-	destroy(): Promise<void>;
-};
-
-const failure = (code: PdfPreflightFailure["code"], message: string): PdfPreflightFailure => ({
-	ok: false,
-	code,
-	message,
-	diagnostics: [],
-});
-
-const workerFailure = (error: Error): PdfPreflightFailure => {
-	const code = (error as NodeJS.ErrnoException).code;
-	return code === "ERR_WORKER_OUT_OF_MEMORY" || /heap out of memory/i.test(error.message)
-		? failure("STYLESHEET_PREFLIGHT_MEMORY_LIMIT", "The PDF preflight worker exceeded its memory limit.")
-		: failure("STYLESHEET_PREFLIGHT_WORKER_FAILED", "The PDF preflight worker failed.");
-};
-
-const sourceWorkerExecArgv = () => {
-	const importIndex = process.execArgv.findIndex(
-		(argument, index, arguments_) =>
-			(argument === "--import" && arguments_[index + 1]?.includes("tsx")) ||
-			(argument.startsWith("--import=") && argument.includes("tsx")),
-	);
-	const inherited = process.execArgv[importIndex];
-	if (inherited?.startsWith("--import=")) return [inherited];
-	if (inherited === "--import") return [inherited, process.execArgv[importIndex + 1] as string];
-	return ["--import", import.meta.resolve("tsx")];
-};
-
-const workerLocation = () => {
-	const source = import.meta.url.endsWith(".ts");
-	return {
-		source,
-		url: source
-			? new URL("../workers/stylesheet-preflight.ts", import.meta.url)
-			: new URL("./stylesheet-preflight-worker.mjs", import.meta.url),
-		// Production must not inherit parent execArgv (e.g. --import/--input-type); source workers need tsx.
-		execArgv: source ? sourceWorkerExecArgv() : [],
-		...(source
-			? {
-					env: {
-						...process.env,
-						TSX_TSCONFIG_PATH: fileURLToPath(new URL("../../tsconfig.json", import.meta.url)),
-					},
-				}
-			: {}),
-	};
-};
-
-type PendingRequest = {
-	resolve: (result: PdfPreflightResult) => void;
-	reject: (cause: unknown) => void;
-	renderTimer?: ReturnType<typeof setTimeout>;
-};
-
-type Readiness = {
-	promise: Promise<Worker>;
-	resolve: (worker: Worker) => void;
-	reject: (error: Error) => void;
-	timer: ReturnType<typeof setTimeout>;
-};
-
-export function createStylesheetPreflightRunner(
-	overrides: Partial<StylesheetPreflightLimits> = {},
-	testWorkerUrl?: URL,
-): NodeStylesheetPreflightRunner {
-	const limits = Object.freeze({ ...STYLESHEET_PREFLIGHT_LIMITS, ...overrides });
-
-	let worker: Worker | undefined;
-	let ready = false;
-	let readiness: Readiness | undefined;
-	let destroyed = false;
-	let requestSeq = 0;
-
-	const pending = new Map<number, PendingRequest>();
-	// ponytail: process-local, bounded admission; upgrade to a pooled/distributed queue only for multi-process coordination.
-	const queue: Array<{
-		input: StylesheetPreflightInput;
-		resolve: PendingRequest["resolve"];
-		reject: PendingRequest["reject"];
-	}> = [];
-
-	const teardownWorker = () => {
-		const dead = worker;
-		worker = undefined;
-		ready = false;
-		if (readiness) {
-			clearTimeout(readiness.timer);
-			readiness.reject(new Error("Stylesheet preflight worker did not become ready."));
-			readiness = undefined;
-		}
-		if (!dead) return;
-		dead.off("message", onMessage);
-		dead.off("error", onError);
-		dead.off("exit", onExit);
-		void dead.terminate().catch(() => undefined);
-	};
-
-	const clearPending = (requestId: number): PendingRequest | undefined => {
-		const entry = pending.get(requestId);
-		if (!entry) return undefined;
-		if (entry.renderTimer) clearTimeout(entry.renderTimer);
-		pending.delete(requestId);
-		return entry;
-	};
-
-	const drainQueue = () => {
-		while (!destroyed && pending.size < limits.maxConcurrentWorkers && queue.length > 0) {
-			const next = queue.shift();
-			if (!next) return;
-			dispatch(next.input, next.resolve, next.reject);
-		}
-	};
-
-	const resolveRequest = (requestId: number, result: PdfPreflightResult) => {
-		const entry = clearPending(requestId);
-		if (!entry) return;
-		entry.resolve(result);
-		drainQueue();
-	};
-
-	const rejectRequest = (requestId: number, cause: unknown) => {
-		const entry = clearPending(requestId);
-		if (!entry) return;
-		entry.reject(cause);
-		drainQueue();
-	};
-
-	// A crashed/exited/timed-out worker is torn down and its in-flight requests are
-	// failed; the next dispatch (including any queued requests) spawns a fresh one,
-	// so a poisoned render never lingers across requests.
-	const failWorker = (result: PdfPreflightFailure) => {
-		teardownWorker();
-		const stale = [...pending.keys()];
-		for (const requestId of stale) resolveRequest(requestId, result);
-		drainQueue();
-	};
-
-	function onMessage(message: StylesheetPreflightWorkerMessage) {
-		if (message.type === "ready") {
-			if (readiness) {
-				clearTimeout(readiness.timer);
-				ready = true;
-				const resolveReady = readiness.resolve;
-				const readyWorker = worker;
-				readiness = undefined;
-				if (readyWorker) resolveReady(readyWorker);
-			}
-			return;
-		}
-		if (message.type === "load_error") {
-			failWorker(failure("STYLESHEET_PREFLIGHT_WORKER_FAILED", message.message));
-			return;
-		}
-		if (message.type === "result") {
-			resolveRequest(message.requestId, message.result);
-			return;
-		}
-		if (message.type === "preflight_error") {
-			rejectRequest(
-				message.requestId,
-				Object.assign(new Error(message.cause.message), { name: message.cause.name, issues: message.cause.issues }),
-			);
-		}
-	}
-
-	function onError(error: Error) {
-		console.warn("[stylesheet-preflight] worker error:", error.message);
-		failWorker(workerFailure(error));
-	}
-
-	function onExit(code: number) {
-		if (destroyed || (!worker && pending.size === 0)) return;
-		console.warn(`[stylesheet-preflight] worker exited unexpectedly (code ${code})`);
-		failWorker(failure("STYLESHEET_PREFLIGHT_WORKER_FAILED", "The PDF preflight worker failed."));
-	}
-
-	const startWorker = (): Promise<Worker> => {
-		const location = testWorkerUrl ? { source: false, url: testWorkerUrl, execArgv: [] as string[] } : workerLocation();
-		let spawned: Worker;
-		try {
-			spawned = new Worker(location.url, {
-				name: "stylesheet-preflight",
-				resourceLimits: {
-					// The source-only tsx compiler heap is outside the production render budget.
-					maxOldGenerationSizeMb: limits.maxOldGenerationMb + (location.source ? SOURCE_WORKER_LOADER_HEAP_MB : 0),
-				},
-				execArgv: location.execArgv,
-				...("env" in location ? { env: location.env } : {}),
-			});
-		} catch (error) {
-			return Promise.reject(error instanceof Error ? error : new Error("Failed to start PDF preflight worker."));
-		}
-
-		worker = spawned;
-		ready = false;
-		// The idle reused worker must not keep the process (or a test run) alive; active
-		// requests stay alive through their ref'd readiness/render timers.
-		spawned.unref();
-		spawned.on("message", onMessage);
-		spawned.once("error", onError);
-		spawned.once("exit", onExit);
-
-		let resolve!: (value: Worker) => void;
-		let reject!: (error: Error) => void;
-		const promise = new Promise<Worker>((resolvePromise, rejectPromise) => {
-			resolve = resolvePromise;
-			reject = rejectPromise;
-		});
-		const timer = setTimeout(() => {
-			console.warn(`[stylesheet-preflight] worker did not become ready within ${WORKER_READINESS_TIMEOUT_MS}ms`);
-			teardownWorker();
-		}, WORKER_READINESS_TIMEOUT_MS);
-		readiness = { promise, resolve, reject, timer };
-		return promise;
-	};
-
-	const getReadyWorker = (): Promise<Worker> => {
-		if (destroyed) return Promise.reject(new Error("Stylesheet preflight worker was terminated."));
-		if (worker && ready) return Promise.resolve(worker);
-		if (readiness) return readiness.promise;
-		return startWorker();
-	};
-
-	// One retry: a worker that failed to become ready is torn down; a second
-	// attempt spawns a fresh worker before the request gives up.
-	const waitUntilReady = async (): Promise<Worker> => {
-		try {
-			return await getReadyWorker();
-		} catch {
-			return await getReadyWorker();
-		}
-	};
-
-	function dispatch(
-		input: StylesheetPreflightInput,
-		resolve: PendingRequest["resolve"],
-		reject: PendingRequest["reject"],
-	) {
-		const requestId = ++requestSeq;
-		pending.set(requestId, { resolve, reject });
-		void waitUntilReady()
-			.then((readyWorker) => {
-				const entry = pending.get(requestId);
-				if (!entry) return;
-				entry.renderTimer = setTimeout(() => {
-					// A stuck render poisons the reused worker: tear it down and respawn — but
-					// only the worker this request actually ran on, so a stale timer can never
-					// kill a newer worker already serving other requests.
-					clearPending(requestId);
-					if (worker === readyWorker) teardownWorker();
-					resolve(failure("STYLESHEET_PREFLIGHT_TIMEOUT", "The PDF preflight exceeded its deadline."));
-					drainQueue();
-				}, limits.timeoutMs);
-				readyWorker.postMessage({ type: "preflight", requestId, input, limits });
-			})
-			.catch((error: unknown) => {
-				resolveRequest(
-					requestId,
-					workerFailure(error instanceof Error ? error : new Error("Failed to start PDF preflight worker.")),
-				);
-			});
-	}
-
-	return {
-		get activeWorkerCount() {
-			return pending.size;
-		},
-		get queuedPreflightCount() {
-			return queue.length;
-		},
-
-		warmup() {
-			void waitUntilReady().catch(() => undefined);
-		},
-
-		run(input: StylesheetPreflightInput): Promise<PdfPreflightResult> {
-			return new Promise<PdfPreflightResult>((resolve, reject) => {
-				if (destroyed) {
-					resolve(failure("STYLESHEET_PREFLIGHT_WORKER_FAILED", "The PDF preflight worker was terminated."));
-					return;
-				}
-				if (pending.size < limits.maxConcurrentWorkers) {
-					dispatch(input, resolve, reject);
-					return;
-				}
-				if (queue.length >= limits.maxQueuedRequests) {
-					resolve(failure("STYLESHEET_PREFLIGHT_WORKER_FAILED", "The PDF preflight queue is full."));
-					return;
-				}
-				queue.push({ input, resolve, reject });
-			});
-		},
-
-		async destroy() {
-			destroyed = true;
-			const dead = worker;
-			teardownWorker();
-			await dead?.terminate().catch(() => undefined);
-			for (const requestId of [...pending.keys()]) {
-				resolveRequest(
-					requestId,
-					failure("STYLESHEET_PREFLIGHT_WORKER_FAILED", "The PDF preflight worker was terminated."),
-				);
-			}
-			while (queue.length > 0) {
-				const next = queue.shift();
-				next?.resolve(failure("STYLESHEET_PREFLIGHT_WORKER_FAILED", "The PDF preflight worker was terminated."));
-			}
-		},
-	};
-}
-
-export const stylesheetPreflightRunner = createStylesheetPreflightRunner();

apps/server/src/startup/checks.ts

@@ -7,6 +7,7 @@ import { migrate } from "drizzle-orm/node-postgres/migrator";
 import { Pool } from "pg";
 import { env } from "@reactive-resume/env/server";
 import { getLocalDataDirectory } from "@reactive-resume/utils/monorepo.node";
+import { verifyMigratedSchema } from "./schema-check";
 
 function resolveFromCurrentModule(relativePath: string) {
 	return fileURLToPath(new URL(relativePath, import.meta.url));
@@ -24,25 +25,54 @@ function resolveWorkspaceFolder(folderName: string): string {
 	throw new Error(`Could not locate ${folderName} folder relative to ${resolveFromCurrentModule(".")}`);
 }
 
-async function runDatabaseMigrations() {
+export async function runDatabaseMigrations() {
 	console.info("Running database migrations...");
 
-	const pool = new Pool({ connectionString: env.DATABASE_URL });
-	const db = drizzle({ client: pool });
+	const pool = new Pool({
+		connectionString: env.DATABASE_MIGRATION_URL ?? env.DATABASE_URL,
+		max: 1,
+		connectionTimeoutMillis: 10_000,
+	});
 
 	try {
-		await migrate(db, { migrationsFolder: resolveWorkspaceFolder("migrations") });
-		console.info("Database migrations completed");
-	} catch (error) {
-		console.error("Database migrations failed", { error });
-		throw error;
+		const client = await pool.connect();
+		try {
+			await client.query("SELECT pg_advisory_lock(721830451)");
+			const db = drizzle({ client });
+			try {
+				await migrate(db, { migrationsFolder: resolveWorkspaceFolder("migrations") });
+				console.info("Database migrations completed");
+			} catch (error) {
+				console.error("Database migrations failed", { error });
+				throw error;
+			}
+
+			// Post-migration verification is not a migration failure, so it gets its own log
+			// message. A drifted schema still lets the server boot; STRICT_SCHEMA_CHECK=true
+			// makes the drift fatal instead.
+			try {
+				await verifyMigratedSchema(client);
+			} catch (error) {
+				console.error("Database schema verification failed", { error });
+				if (env.STRICT_SCHEMA_CHECK) throw error;
+				console.error(
+					"Continuing with a drifted database schema; set STRICT_SCHEMA_CHECK=true to refuse startup instead.",
+				);
+			}
+		} finally {
+			try {
+				await client.query("SELECT pg_advisory_unlock(721830451)");
+			} finally {
+				client.release();
+			}
+		}
 	} finally {
 		await pool.end();
 	}
 }
 
 async function validateLocalStoragePath() {
-	if (env.S3_ACCESS_KEY_ID && env.S3_SECRET_ACCESS_KEY && env.S3_BUCKET) return;
+	if (env.STORAGE_BACKEND !== "local") return;
 
 	const dataDirectory = getLocalDataDirectory(env.LOCAL_STORAGE_PATH);
 	console.info(`Validating local storage path: ${dataDirectory}`);
@@ -61,7 +91,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();
 }

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

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { collectExpectedColumns, verifyMigratedSchema } from "./schema-check";
+
+describe("collectExpectedColumns", () => {
+	it("collects every column of every schema table", () => {
+		const expected = collectExpectedColumns();
+		expect(expected.length).toBeGreaterThan(0);
+		expect(expected).toContainEqual({ tableName: "ai_providers", columnName: "user_id" });
+		expect(expected).toContainEqual({ tableName: "user", columnName: "id" });
+	});
+});
+
+describe("verifyMigratedSchema", () => {
+	it("fails with the table name when every column of a table is missing", async () => {
+		const rows = collectExpectedColumns()
+			.filter((e) => e.tableName === "ai_providers")
+			.map((e) => ({ table_name: e.tableName, column_name: e.columnName }));
+
+		const queryable = { query: async () => ({ rows }) };
+		await expect(verifyMigratedSchema(queryable)).rejects.toThrow('table "ai_providers"');
+	});
+});

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

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

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

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

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

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