chore: update translations

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

.design-sync/NOTES.md

@@ -0,0 +1,55 @@
+# 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

@@ -0,0 +1,55 @@
+#!/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

@@ -0,0 +1,256 @@
+{
+	"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

@@ -0,0 +1,60 @@
+# 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

@@ -0,0 +1,52 @@
+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

@@ -0,0 +1,38 @@
+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

@@ -0,0 +1,34 @@
+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

@@ -0,0 +1,84 @@
+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

@@ -0,0 +1,71 @@
+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

@@ -0,0 +1,40 @@
+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

@@ -0,0 +1,48 @@
+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

@@ -0,0 +1,51 @@
+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

@@ -0,0 +1,67 @@
+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

@@ -0,0 +1,30 @@
+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

@@ -0,0 +1,42 @@
+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

@@ -0,0 +1,48 @@
+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

@@ -0,0 +1,30 @@
+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

@@ -0,0 +1,41 @@
+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

@@ -0,0 +1,27 @@
+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

@@ -0,0 +1,19 @@
+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

@@ -0,0 +1,40 @@
+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

@@ -0,0 +1,55 @@
+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

@@ -0,0 +1,68 @@
+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

@@ -0,0 +1,39 @@
+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

@@ -0,0 +1,39 @@
+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

@@ -0,0 +1,65 @@
+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

@@ -0,0 +1,57 @@
+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

@@ -0,0 +1,33 @@
+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

@@ -0,0 +1,57 @@
+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

@@ -0,0 +1,39 @@
+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

@@ -0,0 +1,45 @@
+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

@@ -0,0 +1,38 @@
+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

@@ -0,0 +1,61 @@
+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

@@ -0,0 +1,41 @@
+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

@@ -0,0 +1,33 @@
+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

@@ -0,0 +1,35 @@
+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

@@ -0,0 +1,40 @@
+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

@@ -0,0 +1,57 @@
+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

@@ -0,0 +1,37 @@
+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

@@ -0,0 +1,19 @@
+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

@@ -0,0 +1,66 @@
+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

@@ -0,0 +1,18 @@
+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

@@ -0,0 +1,4 @@
+/* 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";

.dockerignore

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

.env.example

@@ -1,7 +1,10 @@
 # --- Application ---
-# Port used by the web server in local development and self-hosted containers.
+# Public port used by the production server and the Vite web server in local development.
 PORT="3000"
 
+# Port used by the Hono server in local development. Vite proxies API requests to this port.
+SERVER_PORT="3001"
+
 # Public URL where the app is served. Used for auth callbacks, OAuth issuer URLs,
 # OpenGraph metadata, and absolute upload URLs.
 APP_URL="http://localhost:3000"
@@ -9,7 +12,7 @@ APP_URL="http://localhost:3000"
 # --- Database (PostgreSQL) ---
 # PostgreSQL connection URL. In Docker Compose, the hostname is usually `postgres`;
 # when running directly on your machine, `localhost` is typical.
-DATABASE_URL="postgresql://postgres:postgres@localhost:5432/postgres"
+DATABASE_URL="postgresql://postgres:postgres@postgres:5432/postgres"
 
 # --- Authentication ---
 # Generated using `openssl rand -hex 32`
@@ -48,15 +51,11 @@ OAUTH_USER_INFO_URL=""
 # Space-separated scopes requested from the custom OAuth provider.
 OAUTH_SCOPES="openid profile email"
 
-# Comma-separated extra hosts/origins allowed for dynamic OAuth client redirect URIs.
-# By default, only the APP_URL origin is allowed.
-OAUTH_DYNAMIC_CLIENT_REDIRECT_HOSTS=""
-
 # --- Email (optional) ---
 # If SMTP_HOST, SMTP_USER, SMTP_PASS, or SMTP_FROM is missing, the app logs the
 # email to the console instead.
-SMTP_HOST="localhost"
-SMTP_PORT="1025"
+SMTP_HOST=""
+SMTP_PORT=""
 SMTP_USER=""
 SMTP_PASS=""
 SMTP_FROM="Reactive Resume <noreply@rxresu.me>"
@@ -73,10 +72,15 @@ SMTP_SECURE="false"
 S3_ACCESS_KEY_ID="seaweedfs"
 S3_SECRET_ACCESS_KEY="seaweedfs"
 S3_REGION="us-east-1"
-S3_ENDPOINT="http://localhost:8333"
+S3_ENDPOINT="http://seaweedfs:8333"
 S3_BUCKET="reactive-resume"
 S3_FORCE_PATH_STYLE="true"
 
+# --- AI Agent Workspace (optional) ---
+# Required only for the authenticated /agent workspace and saved AI providers.
+REDIS_URL="redis://redis:6379"
+ENCRYPTION_SECRET="change-me-to-a-secure-agent-secret-in-production"
+
 # --- Feature Flags ---
 # This flag disables new signups, both on the web app and the server.
 FLAG_DISABLE_SIGNUPS="false"
@@ -89,6 +93,25 @@ FLAG_DISABLE_EMAIL_AUTH="false"
 # This is useful if you are using a machine with limited resources, like a Raspberry Pi.
 FLAG_DISABLE_IMAGE_PROCESSING="false"
 
+# This flag disables API rate limiting for authentication endpoints.
+# 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.
+# WARNING: Enabling this on a public or multi-tenant deployment can enable phishing
+# or token exfiltration. Only enable this on a trusted, self-hosted instance.
+FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI="false"
+
+# Allows AI providers to be configured with any base URL, including http:// and
+# private/loopback addresses (e.g. http://localhost:11434 for a local Ollama instance).
+# WARNING: Enabling this on a multi-tenant deployment is a Server-Side Request Forgery (SSRF)
+# risk. Only enable this on a trusted, single-tenant self-hosted instance.
+FLAG_ALLOW_UNSAFE_AI_BASE_URL="false"
+
 # --- Others ---
 # Google Cloud API Key (optional)
 # For font-list generation tooling.

.github/.well-known/funding.json

@@ -61,7 +61,7 @@
 				"guid": "open-collective",
 				"type": "payment-provider",
 				"description": "Open Collective",
-				"address": "https://opencollective.com/reactive-resume"
+				"address": "https://opencollective.com/reactive-resume/donate"
 			}
 		]
 	}

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

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

.github/workflows/autofix.yml

@@ -19,6 +19,13 @@ jobs:
       - name: Checkout Repository
         uses: actions/checkout@v6
 
+      - name: Check for merge conflict markers
+        run: |
+          if git grep -nEI '<{7} |>{7} |^={7}$' -- ':(exclude)*.md' ':(exclude)*.mdx'; then
+            echo "::error::Merge conflict markers found in tracked files"
+            exit 1
+          fi
+
       - name: Install pnpm
         uses: pnpm/action-setup@v6
 

.github/workflows/docker-build.yml

@@ -2,6 +2,11 @@ name: Build Docker Image
 
 on:
   workflow_dispatch:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*"
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -12,17 +17,34 @@ env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
+  mode:
+    runs-on: ubuntu-latest
+
+    outputs:
+      nightly: ${{ steps.mode.outputs.nightly }}
+      release: ${{ steps.mode.outputs.release }}
+      matrix: ${{ steps.mode.outputs.matrix }}
+
+    steps:
+      - name: Determine publishing mode
+        id: mode
+        run: |
+          if [[ "${{ github.event_name }}" == "push" && "${{ github.ref }}" == "refs/heads/main" ]]; then
+            echo "nightly=true" >> "$GITHUB_OUTPUT"
+            echo "release=false" >> "$GITHUB_OUTPUT"
+            echo 'matrix={"include":[{"platform":"linux/amd64","runner":"ubuntu-latest","arch":"amd64"}]}' >> "$GITHUB_OUTPUT"
+          else
+            echo "nightly=false" >> "$GITHUB_OUTPUT"
+            echo "release=true" >> "$GITHUB_OUTPUT"
+            echo 'matrix={"include":[{"platform":"linux/amd64","runner":"ubuntu-latest","arch":"amd64"},{"platform":"linux/arm64","runner":"ubuntu-24.04-arm","arch":"arm64"}]}' >> "$GITHUB_OUTPUT"
+          fi
+
   build:
+    needs: mode
+
     strategy:
       fail-fast: false
-      matrix:
-        include:
-          - platform: linux/amd64
-            runner: ubuntu-latest
-            arch: amd64
-          - platform: linux/arm64
-            runner: ubuntu-24.04-arm
-            arch: arm64
+      matrix: ${{ fromJSON(needs.mode.outputs.matrix) }}
 
     runs-on: ${{ matrix.runner }}
     timeout-minutes: 30
@@ -97,7 +119,9 @@ jobs:
           retention-days: 1
 
   merge:
-    needs: build
+    needs:
+      - mode
+      - build
     timeout-minutes: 30
     runs-on: ubuntu-latest
 
@@ -160,16 +184,25 @@ jobs:
             docker.io/${{ env.IMAGE }}
           tags: |
             type=sha,prefix=sha-
-            type=raw,value=latest
-            type=raw,value=v${{ steps.version.outputs.version }}
-            type=raw,value=v${{ steps.semver.outputs.major }}.${{ steps.semver.outputs.minor }}
-            type=raw,value=v${{ steps.semver.outputs.major }}
+            type=raw,value=nightly,enable=${{ needs.mode.outputs.nightly == 'true' }}
+            type=raw,value=nightly-{{date 'YYYYMMDDHHmmss' tz='UTC'}},enable=${{ needs.mode.outputs.nightly == 'true' }}
+            type=raw,value=latest,enable=${{ needs.mode.outputs.release == 'true' }}
+            type=raw,value=v${{ steps.version.outputs.version }},enable=${{ needs.mode.outputs.release == 'true' }}
+            type=raw,value=v${{ steps.semver.outputs.major }}.${{ steps.semver.outputs.minor }},enable=${{ needs.mode.outputs.release == 'true' }}
+            type=raw,value=v${{ steps.semver.outputs.major }},enable=${{ needs.mode.outputs.release == 'true' }}
 
       - name: Create manifest list and push
         id: manifest
         working-directory: /tmp/digests
         run: |
           set -euo pipefail
+
+          if [[ "${{ needs.mode.outputs.nightly }}" == "true" ]]; then
+            FINAL_TAG="nightly"
+          else
+            FINAL_TAG="v${{ steps.version.outputs.version }}"
+          fi
+
           docker buildx imagetools create \
             $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
             --annotation "index:org.opencontainers.image.licenses=MIT" \
@@ -184,8 +217,9 @@ jobs:
             $(printf 'docker.io/${{ env.IMAGE }}@sha256:%s ' *)
 
           # Get the digest of the multi-arch manifest
-          GHCR_DIGEST=$(docker buildx imagetools inspect ghcr.io/${{ env.IMAGE }}:v${{ steps.version.outputs.version }} --format '{{json .Manifest.Digest}}' | tr -d '"')
-          DOCKER_DIGEST=$(docker buildx imagetools inspect docker.io/${{ env.IMAGE }}:v${{ steps.version.outputs.version }} --format '{{json .Manifest.Digest}}' | tr -d '"')
+          GHCR_DIGEST=$(docker buildx imagetools inspect ghcr.io/${{ env.IMAGE }}:${FINAL_TAG} --format '{{json .Manifest.Digest}}' | tr -d '"')
+          DOCKER_DIGEST=$(docker buildx imagetools inspect docker.io/${{ env.IMAGE }}:${FINAL_TAG} --format '{{json .Manifest.Digest}}' | tr -d '"')
+          echo "final_tag=$FINAL_TAG" >> "$GITHUB_OUTPUT"
           echo "ghcr_digest=$GHCR_DIGEST" >> "$GITHUB_OUTPUT"
           echo "docker_digest=$DOCKER_DIGEST" >> "$GITHUB_OUTPUT"
 
@@ -202,10 +236,11 @@ jobs:
 
       - name: Inspect image
         run: |
-          docker buildx imagetools inspect ghcr.io/${{ env.IMAGE }}:v${{ steps.version.outputs.version }}
-          docker buildx imagetools inspect docker.io/${{ env.IMAGE }}:v${{ steps.version.outputs.version }}
+          docker buildx imagetools inspect ghcr.io/${{ env.IMAGE }}:${{ steps.manifest.outputs.final_tag }}
+          docker buildx imagetools inspect docker.io/${{ env.IMAGE }}:${{ steps.manifest.outputs.final_tag }}
 
       - name: Redeploy Stack
+        if: ${{ needs.mode.outputs.release == 'true' }}
         uses: appleboy/ssh-action@v1
         with:
           key: ${{ secrets.SSH_KEY }}
@@ -214,3 +249,24 @@ jobs:
           script: |
             cd docker
             ./manage_stack.sh up reactive_resume
+
+      - name: Purge Cloudflare cache
+        if: ${{ needs.mode.outputs.release == 'true' }}
+        env:
+          CLOUDFLARE_ZONE_ID: ${{ secrets.CLOUDFLARE_ZONE_ID }}
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          response=$(curl -fsS --max-time 10 --retry 3 --retry-delay 5 --retry-connrefused -X POST \
+            "https://api.cloudflare.com/client/v4/zones/${CLOUDFLARE_ZONE_ID}/purge_cache" \
+            -H "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
+            -H "Content-Type: application/json" \
+            --data '{"purge_everything":true}')
+
+          if [ "$(jq -r '.success' <<< "$response")" != "true" ]; then
+            echo "$response" | jq .
+            exit 1
+          fi
+
+          echo "Cloudflare cache purged successfully."

.github/workflows/e2e.yml

@@ -0,0 +1,121 @@
+name: E2E Tests
+
+on:
+  pull_request:
+  push:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+  APP_URL: http://localhost:3000
+  PORT: "3000"
+  DATABASE_URL: postgresql://postgres:postgres@localhost:5432/postgres
+  FLAG_DISABLE_SIGNUPS: "false"
+  FLAG_DISABLE_EMAIL_AUTH: "false"
+  FLAG_DISABLE_API_RATE_LIMIT: "true"
+  LOCAL_STORAGE_PATH: /tmp/reactive-resume-e2e-storage
+
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_DB: postgres
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres -d postgres"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          cache: "pnpm"
+
+      - name: Install Dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run Server and Tooling Tests
+        run: pnpm exec turbo run test:ci --filter=server --filter=@reactive-resume/tooling
+
+      - name: Install Playwright Browser
+        run: pnpm exec playwright install --with-deps chromium
+
+      - name: Generate Test Secrets
+        run: |
+          echo "AUTH_SECRET=$(openssl rand -hex 32)" >> "$GITHUB_ENV"
+          echo "ENCRYPTION_SECRET=$(openssl rand -hex 32)" >> "$GITHUB_ENV"
+
+      - name: Prepare Storage
+        run: mkdir -p "$LOCAL_STORAGE_PATH"
+
+      - name: Run Database Migrations
+        run: pnpm db:migrate
+
+      - name: Build
+        run: pnpm build
+
+      - name: Run Baseline E2E Tests
+        env:
+          FLAG_SEMANTIC_CSS_AUTHORING: "false"
+          FLAG_SEMANTIC_CSS_DEFAULT: "false"
+        run: pnpm exec playwright test --grep-invert "@semantic-css"
+
+      - name: Run Semantic CSS Opt-In Acceptance
+        env:
+          FLAG_SEMANTIC_CSS_AUTHORING: "true"
+          FLAG_SEMANTIC_CSS_DEFAULT: "false"
+        run: |
+          pnpm exec playwright test \
+            tests/e2e/specs/semantic-css/legacy-conversion.spec.ts \
+            tests/e2e/specs/semantic-css/invalid-last-valid.spec.ts \
+            tests/e2e/specs/semantic-css/portable-stylesheet.spec.ts \
+            tests/e2e/specs/semantic-css/revision-conflict.spec.ts \
+            tests/e2e/specs/semantic-css/template-visual.spec.ts
+
+      - name: Run Semantic CSS Default-On Acceptance
+        env:
+          FLAG_SEMANTIC_CSS_AUTHORING: "true"
+          FLAG_SEMANTIC_CSS_DEFAULT: "true"
+        run: pnpm exec playwright test tests/e2e/specs/semantic-css/default-mode.spec.ts
+
+      - name: Run Semantic CSS Dormant Acceptance
+        env:
+          FLAG_SEMANTIC_CSS_AUTHORING: "false"
+          FLAG_SEMANTIC_CSS_DEFAULT: "false"
+        run: |
+          pnpm exec playwright test \
+            tests/e2e/specs/semantic-css/dormant-mode.spec.ts \
+            tests/e2e/specs/semantic-css/flag-off-semantic.spec.ts
+
+      - name: Upload Playwright Report
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: playwright-report
+          path: |
+            playwright-report
+            test-results
+          if-no-files-found: ignore
+          retention-days: 7

.gitignore

@@ -3,7 +3,7 @@ node_modules
 .pnpm-store
 
 # Build Outputs
-.output
+dist
 .vercel
 .wrangler
 
@@ -36,6 +36,8 @@ logs
 # Testing
 coverage
 reports
+playwright-report
+test-results
 
 # Cache
 tmp
@@ -44,11 +46,26 @@ temp
 
 # AI
 .codex
+.agents
 .claude
 .cursor
+.codegraph
 .superpowers
-docs/superpowers
+.worktrees
+.migration
 
 # Local Storage Data
 /data
 /apps/web/data
+
+# 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

.markdownlint-cli2.yaml

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

.ncurc.cjs

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

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

@@ -0,0 +1,23 @@
+# 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.

.vite-hooks/_/commit-msg

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

.vite-hooks/_/pre-commit

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

.vscode/settings.json

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

AGENTS.md

@@ -0,0 +1,157 @@
+# AGENTS.md
+
+## Cursor Cloud specific instructions
+
+### Overview
+
+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.
+
+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.
+
+### Prerequisites
+
+- **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.17.0** is managed via corepack (`corepack enable`).
+
+### Codebase map
+
+- `apps/web` owns TanStack Start routes, Vite config, PWA setup, oRPC browser client wiring, web features, and the resume builder UI.
+- `apps/server` owns the production Hono app, route composition, auth/RPC/MCP/OpenAPI handlers, static uploads, schema JSON, web-dist fallback serving, and startup checks.
+- `packages/api` contains oRPC routers, DTOs, rate limiting, and feature-owned API modules under `packages/api/src/features/*`. The router export at `@reactive-resume/api/routers` aggregates those feature routers for `/api/rpc`.
+- `packages/auth` contains Better Auth config, auth helper functions, and exported auth types. The server auth adapter in `apps/server/src/http/auth.ts` delegates to `auth.handler`.
+- `packages/db` contains the Drizzle client and schema. Migration files live at the repo root in `migrations/`.
+- `packages/env` defines server environment validation and auto-loads the root `.env` for app/server code.
+- `packages/schema` contains Zod schemas and typed resume/page/template models.
+- `packages/pdf` contains the React PDF document, font registration, shared template primitives, template implementations, and browser/server PDF generation adapters. PDF.js viewer UI stays in `apps/web`.
+- `packages/resume` contains pure resume-domain behavior such as JSON Patch helpers and social-network icon mapping.
+- `packages/docx` contains DOCX export generation.
+- `packages/mcp` contains MCP tools, prompts, resources, server-card generation, and tool metadata.
+- `packages/ui` contains shared Base UI/shadcn-style components and hooks.
+- `packages/fonts`, `packages/email`, `packages/import`, `packages/ai`, `packages/utils`, and `packages/config` provide focused support surfaces. Prefer their existing exports over adding cross-package shortcuts.
+- Development-only scripts live in `tooling/`, not under `packages/`, so packages only contain code bundled by the app/runtime.
+
+### Web app conventions
+
+- Routes are file-based under `apps/web/src/routes`. Do not hand-edit `apps/web/src/routeTree.gen.ts`; it is generated by TanStack Router tooling.
+- Server-owned HTTP behavior lives in `apps/server/src/{http,rpc,mcp,openapi,static,startup}`. Keep API/RPC/auth/MCP/static route wiring in `apps/server`, not in web routes.
+- `apps/web/src/router.tsx` initializes router context with `queryClient`, `orpc`, `theme`, `locale`, `session`, and `flags`. Reuse route context where possible instead of refetching these concerns ad hoc.
+- The builder shell lives under `apps/web/src/routes/builder/$resumeId`. The nested preview route is client-only (`ssr: false`), while the public resume route `apps/web/src/routes/$username/$slug.tsx` uses `ssr: "data-only"`.
+- Browser-only resume preview code lives under `apps/web/src/features/resume/preview`, and public resume PDF viewer code lives under `apps/web/src/features/resume/public`. Keep PDF.js/canvas/browser APIs out of SSR paths and out of `packages/pdf`.
+- The isomorphic oRPC client is in `apps/web/src/libs/orpc/client.ts`; server calls use an in-process router client and browser calls use `/api/rpc` with credentials included.
+- For React components with explicit props, prefer a named TypeScript props type over inline object annotations in the function signature, especially once the props include more than one field or generics. For example:
+
+```ts
+type IntentSelectFieldProps<TValue extends string> = {
+	label: string;
+	id: string;
+	value: TValue | undefined;
+	options: readonly ComboboxOption<TValue>[];
+	onChange: (value: TValue | undefined) => void;
+};
+
+function IntentSelectField<TValue extends string>(props: IntentSelectFieldProps<TValue>) {
+	// ...
+}
+```
+
+### Package and feature boundaries
+
+- 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
+```
+
+The dev default connection string is `postgresql://postgres:postgres@localhost:5432/postgres`.
+
+**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`. 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.
+
+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` |
+| 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:
+
+```
+pnpm --filter web typecheck
+pnpm --filter @reactive-resume/pdf test
+pnpm --filter @reactive-resume/api test
+pnpm exec turbo boundaries
+```
+
+Vitest test paths are package-relative when running through `pnpm --filter <package> test -- <path>`.
+
+### Gotchas
+
+- The server startup path auto-runs migrations before serving traffic, so `pnpm db:migrate` is mainly needed for first-time setup, migration debugging, or applying migrations without starting the app.
+- Email sending requires SMTP config; without it, emails are logged to console. This is fine for dev — the app still functions, but email verification links appear in server logs.
+- The `lefthook.yml` pre-commit hook runs `biome check` on staged files. Run `pnpm check` before committing to avoid hook failures.
+- `pnpm check` is write-capable (`biome check --write --unsafe .`). Call that out when using it, and use narrower Biome commands if you need a non-mutating inspection.
+- Biome uses tabs, double quotes, line width 120, organized import groups, and sorted Tailwind classes for `clsx`, `cva`, and `cn`.
+- Most packages use `tsgo --noEmit` for typechecking and `vitest run --passWithNoTests` for tests.
+- There may be unrelated local edits in the worktree. Inspect `git status --short` first and avoid reverting files you did not touch.
+- **New env vars require a `turbo.json` entry.** Turborepo 2.x runs in strict env mode by default — it filters out env vars that are not listed in `globalEnv` (or task-level `env`/`passThroughEnv`). Any new environment variable added to `packages/env/src/server.ts` must also be added to the `globalEnv` array in `turbo.json`, or the variable will be `undefined` inside child processes at runtime even if it is correctly set in the OS/container environment.

CLAUDE.md

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

DESIGN.md

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

Dockerfile

@@ -16,7 +16,7 @@ RUN corepack enable
 FROM base AS pruner
 COPY . .
 RUN --mount=type=cache,id=pnpm-store,target=/pnpm/store,sharing=locked \
-    pnpm dlx turbo@2.9.9 prune web --docker
+    pnpm dlx turbo@2.9.12 prune web server --docker
 
 FROM base AS builder
 COPY --from=pruner /app/out/json/ ./
@@ -25,18 +25,18 @@ RUN --mount=type=cache,id=pnpm-store,target=/pnpm/store,sharing=locked \
     pnpm install --frozen-lockfile
 
 COPY --from=pruner /app/out/full/ ./
-RUN pnpm turbo run build --filter=web
+RUN rm -rf apps/web/dist apps/server/dist && pnpm turbo run build --filter=web --filter=server --force
 
 FROM base AS runtime-pruner
 COPY . .
 RUN --mount=type=cache,id=pnpm-store,target=/pnpm/store,sharing=locked \
-    pnpm dlx turbo@2.9.9 prune @reactive-resume/runtime-externals --docker
+    pnpm dlx turbo@2.9.12 prune server --docker
 
 FROM base AS runtime-deps
 COPY --from=runtime-pruner /app/out/json/ ./
 COPY --from=runtime-pruner /app/out/pnpm-lock.yaml ./pnpm-lock.yaml
 RUN --mount=type=cache,id=pnpm-store,target=/pnpm/store,sharing=locked \
-    pnpm --filter=@reactive-resume/runtime-externals deploy --prod --legacy /runtime-deps
+    pnpm install --prod --frozen-lockfile
 
 FROM node:${NODE_VERSION}-slim AS runtime
 
@@ -55,18 +55,22 @@ ENV NODE_ENV="production" \
 
 WORKDIR /app
 
-RUN mkdir -p /app/apps/web /app/data && chown node:node /app/data
+RUN mkdir -p /app/apps/server /app/apps/web /app/data && chown node:node /app/data
 
-COPY --from=runtime-deps --chown=node:node /runtime-deps/node_modules ./node_modules
-COPY --from=builder --chown=node:node /app/apps/web/.output ./apps/web/.output
+COPY --from=runtime-deps --chown=node:node /app/node_modules ./node_modules
+COPY --from=pruner --chown=node:node /app/package.json /app/pnpm-lock.yaml /app/pnpm-workspace.yaml ./
+COPY --from=runtime-deps --chown=node:node /app/apps/server/package.json ./apps/server/package.json
+COPY --from=runtime-deps --chown=node:node /app/apps/server/node_modules ./apps/server/node_modules
+COPY --from=builder --chown=node:node /app/apps/web/dist ./apps/web/dist
+COPY --from=builder --chown=node:node /app/apps/server/dist ./apps/server/dist
 COPY --from=pruner --chown=node:node /app/migrations ./migrations
 
-WORKDIR /app/apps/web
+WORKDIR /app
 
 USER node
 
 EXPOSE 3000/tcp
 HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
-    CMD ["node", "-e", "fetch('http://127.0.0.1:3000/api/health').then((r) => { if (!r.ok) process.exit(1); }).catch(() => process.exit(1));"]
+    CMD ["node", "-e", "fetch(`http://127.0.0.1:${process.env.PORT ?? 3000}/api/health`).then((r) => { if (!r.ok) process.exit(1); }).catch(() => process.exit(1));"]
 
-CMD ["node", ".output/server/index.mjs"]
+CMD ["node", "apps/server/dist/index.mjs"]

Dockerfile.dev

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

README.md

@@ -21,7 +21,7 @@
     <a href="https://discord.gg/aSyA5ZSxpb"><img src="https://img.shields.io/discord/1173518977851473940?style=flat-square&label=discord" alt="Discord" /></a>
     <a href="https://crowdin.com/project/reactive-resume"><img src="https://badges.crowdin.net/reactive-resume/localized.svg?style=flat-square" alt="Crowdin" /></a>
     <a href="https://github.com/sponsors/AmruthPillai"><img src="https://img.shields.io/github/sponsors/AmruthPillai?style=flat-square&label=sponsors" alt="Sponsors" /></a>
-    <a href="https://opencollective.com/reactive-resume"><img src="https://img.shields.io/opencollective/backers/reactive-resume?style=flat-square&label=donations" alt="Donations" /></a>
+    <a href="https://opencollective.com/reactive-resume/donate"><img src="https://img.shields.io/opencollective/backers/reactive-resume?style=flat-square&label=donations" alt="Donations" /></a>
   </p>
 </div>
 
@@ -31,12 +31,26 @@ Reactive Resume makes building resumes straightforward. Pick a template, fill in
 
 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).
+
 ## Features
 
 **Resume Building**
 
 - Real-time preview as you type
-- Multiple export formats (PDF, JSON)
+- Multiple export formats (PDF, JSON, DOCX)
 - Drag-and-drop section ordering
 - Custom sections for any content type
 - Rich text editor with formatting support
@@ -46,7 +60,7 @@ Built with privacy as a core principle, Reactive Resume gives you complete owner
 - Professionally designed templates
 - A4 and Letter size support
 - Customizable colors, fonts, and spacing
-- Custom CSS for advanced styling
+- Structured Style Rules for section and text styling
 
 **Privacy & Control**
 
@@ -130,6 +144,10 @@ Built with privacy as a core principle, Reactive Resume gives you complete owner
       <img src="apps/web/public/templates/jpg/meowth.jpg" alt="Meowth" width="150" />
       <br /><sub><b>Meowth</b></sub>
     </td>
+    <td align="center">
+      <img src="apps/web/public/templates/jpg/scizor.jpg" alt="Scizor" width="150" />
+      <br /><sub><b>Scizor</b></sub>
+    </td>
   </tr>
 </table>
 
@@ -139,7 +157,7 @@ The quickest way to run Reactive Resume locally:
 
 ```bash
 # Clone the repository
-git clone https://github.com/amruthpillai/reactive-resume.git
+git clone --depth=1  https://github.com/amruthpillai/reactive-resume.git
 cd reactive-resume
 
 # Start all services
@@ -164,7 +182,7 @@ For detailed setup instructions, environment configuration, and self-hosting gui
 | API              | ORPC (Type-safe RPC)            |
 | Auth             | Better Auth                     |
 | Styling          | Tailwind CSS                    |
-| UI Components    | Radix UI                        |
+| UI Components    | Base UI + shadcn-style package  |
 | State Management | Zustand + TanStack Query        |
 
 ## Documentation
@@ -208,7 +226,7 @@ Reactive Resume is and always will be free and open-source. If it has helped you
   <a href="https://github.com/sponsors/AmruthPillai">
     <img src="https://img.shields.io/badge/GitHub%20Sponsors-Support-ea4aaa?style=flat-square&logo=github-sponsors" alt="GitHub Sponsors" />
   </a>
-  <a href="https://opencollective.com/reactive-resume">
+  <a href="https://opencollective.com/reactive-resume/donate">
     <img src="https://img.shields.io/badge/Open%20Collective-Contribute-7FADF2?style=flat-square&logo=open-collective" alt="Open Collective" />
   </a>
 </p>
@@ -222,11 +240,11 @@ Other ways to support:
 
 ## Star History
 
-<a href="https://www.star-history.com/#amruthpillai/reactive-resume&type=date&legend=top-left">
+<a href="https://www.star-history.com/?repos=amruthpillai%2Freactive-resume&type=date&legend=top-left">
  <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=amruthpillai/reactive-resume&type=date&theme=dark&legend=top-left" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=amruthpillai/reactive-resume&type=date&legend=top-left" />
-   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=amruthpillai/reactive-resume&type=date&legend=top-left" />
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=amruthpillai/reactive-resume&type=date&theme=dark&legend=top-left&sealed_token=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" />
  </picture>
 </a>
 

apps/server/package.json

@@ -0,0 +1,101 @@
+{
+	"name": "server",
+	"version": "0.0.0",
+	"type": "module",
+	"private": true,
+	"scripts": {
+		"dev": "tsx watch src/index.ts",
+		"build": "tsdown",
+		"start": "node dist/index.mjs",
+		"docs:gen": "tsx src/openapi/generate-spec.ts",
+		"typecheck": "tsgo --noEmit",
+		"test": "vitest run --passWithNoTests",
+		"test:coverage": "vitest run --coverage --passWithNoTests",
+		"test:ci": "vitest run --coverage --reporter=default --reporter=github-actions --reporter=json --reporter=junit --outputFile.json=reports/vitest-results.json --outputFile.junit=reports/vitest-junit.xml --passWithNoTests",
+		"test:agent": "vitest run --reporter=agent --reporter=json --outputFile.json=reports/vitest-results.json --passWithNoTests"
+	},
+	"imports": {
+		"#react-pdf-renderer": "@react-pdf/renderer"
+	},
+	"dependencies": {
+		"@ai-sdk/anthropic": "^4.0.24",
+		"@ai-sdk/cerebras": "^3.0.17",
+		"@ai-sdk/cohere": "^4.0.15",
+		"@ai-sdk/deepseek": "^3.0.16",
+		"@ai-sdk/fireworks": "^3.0.18",
+		"@ai-sdk/google": "^4.0.28",
+		"@ai-sdk/groq": "^4.0.16",
+		"@ai-sdk/mistral": "^4.0.17",
+		"@ai-sdk/openai": "^4.0.24",
+		"@ai-sdk/openai-compatible": "^3.0.17",
+		"@ai-sdk/perplexity": "^4.0.17",
+		"@ai-sdk/togetherai": "^3.0.18",
+		"@ai-sdk/xai": "^4.0.22",
+		"@aws-sdk/client-s3": "^3.1098.0",
+		"@better-auth/api-key": "^1.6.25",
+		"@better-auth/drizzle-adapter": "^1.6.25",
+		"@better-auth/infra": "^0.3.7",
+		"@better-auth/oauth-provider": "^1.6.25",
+		"@better-auth/passkey": "^1.6.25",
+		"@bramus/specificity": "^2.4.2",
+		"@hono/node-server": "^2.0.12",
+		"@modelcontextprotocol/sdk": "^1.30.0",
+		"@orpc/client": "^1.14.13",
+		"@orpc/experimental-ratelimit": "^1.14.13",
+		"@orpc/json-schema": "^1.14.13",
+		"@orpc/openapi": "^1.14.13",
+		"@orpc/server": "^1.14.13",
+		"@orpc/zod": "^1.14.13",
+		"@react-pdf/renderer": "^4.5.1",
+		"@reactive-resume/api": "workspace:*",
+		"@reactive-resume/auth": "workspace:*",
+		"@reactive-resume/db": "workspace:*",
+		"@reactive-resume/env": "workspace:*",
+		"@reactive-resume/mcp": "workspace:*",
+		"@reactive-resume/pdf": "workspace:*",
+		"@reactive-resume/schema": "workspace:*",
+		"@reactive-resume/utils": "workspace:*",
+		"@sindresorhus/slugify": "^3.0.0",
+		"@t3-oss/env-core": "^0.13.11",
+		"@uiw/color-convert": "^2.10.3",
+		"ai": "^7.0.42",
+		"bcrypt": "^6.0.0",
+		"better-auth": "1.6.25",
+		"canonicalize": "^3.0.0",
+		"cjk-regex": "^3.4.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",
+		"fast-json-patch": "^3.1.1",
+		"hono": "^4.12.32",
+		"jsonrepair": "^3.15.0",
+		"node-html-parser": "^9.0.1",
+		"nodemailer": "^9.0.3",
+		"ollama-ai-provider-v2": "^4.0.1",
+		"pdfjs-dist": "^6.2.108",
+		"pg": "^8.22.0",
+		"phosphor-icons-react-pdf": "^0.1.3",
+		"react": "^19.2.8",
+		"react-email": "^6.9.1",
+		"react-pdf-html": "^2.1.5",
+		"resumable-stream": "^2.2.12",
+		"sharp": "^0.35.3",
+		"ts-pattern": "^5.9.0",
+		"unique-names-generator": "^4.7.1",
+		"uuid": "^14.0.1",
+		"zod": "^4.4.3"
+	},
+	"devDependencies": {
+		"@reactive-resume/config": "workspace:*",
+		"@types/node": "^26.1.2",
+		"@types/pg": "^8.20.0",
+		"@types/react": "^19.2.17",
+		"@typescript/native-preview": "7.0.0-dev.20260707.2",
+		"tsdown": "^0.22.14",
+		"tsx": "^4.23.1",
+		"typescript": "^7.0.2",
+		"vitest": "^4.1.10"
+	}
+}

apps/server/src/app-version.ts

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

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

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

apps/server/src/http/app.ts

@@ -0,0 +1,72 @@
+import type { Http2Bindings, HttpBindings } from "@hono/node-server";
+import type { Context } from "hono";
+import { isIP } from "node:net";
+import { getConnInfo } from "@hono/node-server/conninfo";
+import { Hono } from "hono";
+import { handleMcp } from "../mcp/handler";
+import { handleOpenApi } from "../openapi/handler";
+import {
+	handleMcpServerCard,
+	handleOAuthAuthorizationServer,
+	handleOAuthProtectedResource,
+	handleOpenIdConfiguration,
+	handleWellKnownFallback,
+} from "../openapi/metadata";
+import { handleRpc } from "../rpc/handler";
+import { handleSchemaJson } from "../static/schema";
+import { handleLlms, handleRobots, handleSitemap } from "../static/seo";
+import { handleUpload } from "../static/uploads";
+import { handleWebApp, serveWebDistStatic } from "../static/web";
+import { handleAuth, handleOAuth } from "./auth";
+import { handleHealth } from "./health";
+import { handlePublicResumePdf } from "./public-resume-pdf";
+import { handleResumePdfDownload } from "./resume-pdf";
+
+type ServerEnvironment = { Bindings: HttpBindings | Http2Bindings };
+
+const getTrustedClient = (context: Context<ServerEnvironment>): string => {
+	try {
+		const address = getConnInfo(context).remote.address?.trim();
+		return address && isIP(address) ? address : "unknown";
+	} catch {
+		return "unknown";
+	}
+};
+
+export function createApp() {
+	const app = new Hono<ServerEnvironment>();
+
+	app.all("/api/rpc", (c) => handleRpc(c.req.raw, getTrustedClient(c)));
+	app.all("/api/rpc/*", (c) => handleRpc(c.req.raw, getTrustedClient(c)));
+	app.all("/api/openapi", (c) => handleOpenApi(c.req.raw, getTrustedClient(c)));
+	app.all("/api/openapi/*", (c) => handleOpenApi(c.req.raw, getTrustedClient(c)));
+	app.get("/api/auth/oauth", (c) => handleOAuth(c.req.raw));
+	app.all("/api/auth/*", (c) => handleAuth(c.req.raw));
+	app.get("/api/health", () => handleHealth());
+	app.get("/api/resumes/:username/:slug/pdf", (c) =>
+		handlePublicResumePdf(c.req.raw, c.req.param("username"), c.req.param("slug"), getTrustedClient(c)),
+	);
+	app.get("/api/resumes/:id/pdf", (c) => handleResumePdfDownload(c.req.raw, c.req.param("id")));
+	app.get("/api/uploads/*", (c) => handleUpload(c.req.raw));
+	app.get("/uploads/*", (c) => handleUpload(c.req.raw));
+	app.get("/schema.json", () => handleSchemaJson());
+	app.all("/mcp", (c) => handleMcp(c.req.raw));
+	app.all("/mcp/*", (c) => handleMcp(c.req.raw));
+
+	app.get("/.well-known/mcp/server-card.json", () => handleMcpServerCard());
+	app.get("/.well-known/oauth-authorization-server", (c) => handleOAuthAuthorizationServer(c.req.raw));
+	app.get("/.well-known/oauth-authorization-server/*", (c) => handleOAuthAuthorizationServer(c.req.raw));
+	app.get("/.well-known/openid-configuration", (c) => handleOpenIdConfiguration(c.req.raw));
+	app.get("/.well-known/oauth-protected-resource", () => handleOAuthProtectedResource());
+	app.get("/.well-known/oauth-protected-resource/*", () => handleOAuthProtectedResource());
+	app.all("/.well-known/*", () => handleWellKnownFallback());
+
+	app.on(["GET", "HEAD"], "/robots.txt", (c) => handleRobots({ head: c.req.method === "HEAD" }));
+	app.on(["GET", "HEAD"], "/sitemap.xml", (c) => handleSitemap({ head: c.req.method === "HEAD" }));
+	app.on(["GET", "HEAD"], "/llms.txt", (c) => handleLlms({ head: c.req.method === "HEAD" }));
+
+	app.use("/*", serveWebDistStatic);
+	app.on(["GET", "HEAD"], "/*", (c) => handleWebApp(c.req.raw));
+
+	return app;
+}

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

@@ -0,0 +1,97 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+	getSession: vi.fn(),
+	handler: vi.fn(),
+	env: {
+		SERVER_PORT: 3001,
+		APP_URL: "http://localhost:3000",
+		FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI: false,
+	},
+}));
+
+vi.mock("@reactive-resume/auth/config", () => ({
+	auth: {
+		api: {
+			getSession: mocks.getSession,
+		},
+		handler: mocks.handler,
+	},
+}));
+
+vi.mock("@reactive-resume/db/client", () => ({ db: {} }));
+vi.mock("@reactive-resume/db/schema", () => ({ oauthClient: {}, verification: {} }));
+vi.mock("@reactive-resume/env/server", () => ({
+	env: mocks.env,
+}));
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	mocks.env.FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI = false;
+	mocks.handler.mockResolvedValue(new Response("ok"));
+});
+
+describe("handleAuth", () => {
+	it("rejects untrusted dynamic OAuth redirect URIs in safe mode", async () => {
+		const { handleAuth } = await import("./auth");
+
+		const response = await handleAuth(
+			new Request("http://localhost:3001/api/auth/oauth2/register", {
+				method: "POST",
+				body: JSON.stringify({ redirect_uris: ["https://evil.example.com/callback"] }),
+				headers: { "content-type": "application/json" },
+			}),
+		);
+
+		expect(response.status).toBe(400);
+		await expect(response.json()).resolves.toEqual({
+			error: "invalid_redirect_uri",
+			error_description: "redirect_uri is not allowed",
+		});
+		expect(mocks.handler).not.toHaveBeenCalled();
+	});
+
+	it("forwards custom-scheme dynamic OAuth redirect URIs when unsafe mode is enabled", async () => {
+		const { handleAuth } = await import("./auth");
+		mocks.env.FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI = true;
+
+		const response = await handleAuth(
+			new Request("http://localhost:3001/api/auth/oauth2/register", {
+				method: "POST",
+				body: JSON.stringify({ redirect_uris: ["myapp://callback"] }),
+				headers: { "content-type": "application/json" },
+			}),
+		);
+
+		expect(response.status).toBe(200);
+		expect(mocks.handler).toHaveBeenCalledOnce();
+	});
+});
+
+describe("handleOAuth", () => {
+	it("redirects unauthenticated users to the same-origin login route", async () => {
+		const { handleOAuth } = await import("./auth");
+		mocks.getSession.mockResolvedValueOnce(null);
+
+		const response = await handleOAuth(
+			new Request(
+				"http://localhost:3001/api/auth/oauth?client_id=test-client&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&state=abc&exp=123&sig=456",
+			),
+		);
+
+		expect(response.status).toBe(302);
+		const location = response.headers.get("Location");
+		expect(location).toMatch(/^\/auth\/login\?/);
+
+		const loginUrl = new URL(location ?? "", "http://localhost:3000");
+		const callbackUrl = new URL(loginUrl.searchParams.get("callbackURL") ?? "", "http://localhost:3000");
+
+		expect(loginUrl.origin).toBe("http://localhost:3000");
+		expect(callbackUrl.pathname).toBe("/api/auth/oauth");
+		expect(callbackUrl.searchParams.get("client_id")).toBe("test-client");
+		expect(callbackUrl.searchParams.get("redirect_uri")).toBe("https://example.com/callback");
+		expect(callbackUrl.searchParams.get("state")).toBe("abc");
+		expect(callbackUrl.searchParams.has("exp")).toBe(false);
+		expect(callbackUrl.searchParams.has("sig")).toBe(false);
+	});
+});

apps/server/src/http/auth.ts

@@ -0,0 +1,214 @@
+import crypto from "node:crypto";
+import { eq } from "drizzle-orm";
+import { auth } from "@reactive-resume/auth/config";
+import { db } from "@reactive-resume/db/client";
+import { oauthClient, verification } from "@reactive-resume/db/schema";
+import { env } from "@reactive-resume/env/server";
+import { generateId } from "@reactive-resume/utils/string";
+import { isAllowedOAuthRedirectUri } from "@reactive-resume/utils/url-security.node";
+
+const oauthAuthorizeSanitizedParams = [
+	"prompt",
+	"redirect_uri",
+	"client_id",
+	"code_challenge",
+	"code_challenge_method",
+	"response_type",
+	"scope",
+	"state",
+	"resource",
+] as const;
+
+const oauthCallbackPassthroughExcludedParams = new Set(["exp", "sig"]);
+
+function sanitizeOAuthAuthorizeRequest(request: Request): Request {
+	if (request.method !== "GET") return request;
+
+	const url = new URL(request.url);
+	if (!url.pathname.endsWith("/oauth2/authorize")) return request;
+
+	const sanitizeValue = (value: string) =>
+		value
+			.replace(/[\r\n\t]+/g, " ")
+			.replace(/\s+/g, " ")
+			.trim();
+	const sanitizeParam = (key: string) => {
+		const value = url.searchParams.get(key);
+		if (!value) return;
+		url.searchParams.set(key, sanitizeValue(value));
+	};
+
+	for (const key of oauthAuthorizeSanitizedParams) sanitizeParam(key);
+
+	const redirectUri = url.searchParams.get("redirect_uri");
+	if (redirectUri && !URL.canParse(redirectUri)) {
+		try {
+			const decodedRedirectUri = decodeURIComponent(redirectUri);
+			if (URL.canParse(decodedRedirectUri)) {
+				url.searchParams.set("redirect_uri", decodedRedirectUri);
+			}
+		} catch {
+			// Ignore malformed encoded values and let Better Auth validation handle them.
+		}
+	}
+
+	if (url.toString() === request.url) return request;
+	return new Request(url.toString(), request);
+}
+
+async function defaultPublicClientRegistration(request: Request): Promise<Request> {
+	if (request.method !== "POST") return request;
+
+	const url = new URL(request.url);
+	if (!url.pathname.endsWith("/oauth2/register")) return request;
+
+	const cloned = request.clone();
+	let body: Record<string, unknown>;
+
+	try {
+		body = await cloned.json();
+	} catch {
+		return request;
+	}
+
+	if (!request.headers.get("authorization")) {
+		body.token_endpoint_auth_method = "none";
+	}
+
+	return new Request(url.toString(), {
+		method: request.method,
+		headers: request.headers,
+		body: JSON.stringify(body),
+	});
+}
+
+async function validateDynamicClientRegistrationRequest(request: Request): Promise<Response | undefined> {
+	if (request.method !== "POST") return;
+
+	const url = new URL(request.url);
+	if (!url.pathname.endsWith("/oauth2/register")) return;
+
+	const cloned = request.clone();
+	let body: Record<string, unknown>;
+
+	try {
+		body = await cloned.json();
+	} catch {
+		return Response.json({ message: "Invalid registration payload" }, { status: 400 });
+	}
+
+	const oauthTrustedOrigins = [new URL(env.APP_URL).origin.toLowerCase()];
+
+	const redirectUris = Array.isArray(body.redirect_uris) ? body.redirect_uris : [];
+	for (const redirectUri of redirectUris) {
+		if (
+			typeof redirectUri !== "string" ||
+			!isAllowedOAuthRedirectUri(redirectUri, oauthTrustedOrigins, {
+				allowUnsafe: env.FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI,
+			})
+		) {
+			return Response.json(
+				{ error: "invalid_redirect_uri", error_description: "redirect_uri is not allowed" },
+				{ status: 400 },
+			);
+		}
+	}
+}
+
+export async function handleAuth(request: Request) {
+	const registrationValidationError = await validateDynamicClientRegistrationRequest(request);
+	if (registrationValidationError) return registrationValidationError;
+
+	const sanitizedRequest = sanitizeOAuthAuthorizeRequest(request);
+	const finalRequest = await defaultPublicClientRegistration(sanitizedRequest);
+
+	return auth.handler(finalRequest);
+}
+
+function generateCode() {
+	return crypto.randomBytes(32).toString("base64url");
+}
+
+function hashCode(code: string) {
+	return crypto.createHash("sha256").update(code).digest("base64url");
+}
+
+export async function handleOAuth(request: Request) {
+	const session = await auth.api.getSession({ headers: request.headers });
+	const url = new URL(request.url);
+
+	if (session?.user) {
+		const clientId = url.searchParams.get("client_id");
+		const redirectUri = url.searchParams.get("redirect_uri");
+		const state = url.searchParams.get("state");
+		const scope = url.searchParams.get("scope");
+		const codeChallenge = url.searchParams.get("code_challenge");
+		const codeChallengeMethod = url.searchParams.get("code_challenge_method");
+
+		if (!clientId || !redirectUri) {
+			return Response.json({ error: "missing client_id or redirect_uri" }, { status: 400 });
+		}
+
+		const [client] = await db.select().from(oauthClient).where(eq(oauthClient.clientId, clientId)).limit(1);
+
+		if (!client) {
+			return Response.json({ error: "invalid client" }, { status: 400 });
+		}
+
+		if (!client.redirectUris.includes(redirectUri)) {
+			return Response.json({ error: "invalid redirect_uri" }, { status: 400 });
+		}
+
+		const code = generateCode();
+		const hashedCode = hashCode(code);
+		const now = new Date();
+		const expiresAt = new Date(now.getTime() + 600_000);
+
+		await db.insert(verification).values({
+			id: generateId(),
+			identifier: hashedCode,
+			value: JSON.stringify({
+				type: "authorization_code",
+				query: {
+					response_type: "code",
+					client_id: clientId,
+					redirect_uri: redirectUri,
+					scope,
+					state,
+					code_challenge: codeChallenge,
+					code_challenge_method: codeChallengeMethod,
+				},
+				userId: session.user.id,
+				sessionId: session.session.id,
+				authTime: new Date(session.session.createdAt).getTime(),
+			}),
+			expiresAt,
+			createdAt: now,
+			updatedAt: now,
+		});
+
+		const callbackUrl = new URL(redirectUri);
+		callbackUrl.searchParams.set("code", code);
+		if (state) callbackUrl.searchParams.set("state", state);
+		callbackUrl.searchParams.set("iss", `${env.APP_URL}/api/auth`);
+
+		return new Response(null, {
+			status: 302,
+			headers: { Location: callbackUrl.toString() },
+		});
+	}
+
+	const loginUrl = new URL("/auth/login", env.APP_URL);
+	const oauthParams = new URLSearchParams();
+	for (const [key, value] of url.searchParams) {
+		if (!oauthCallbackPassthroughExcludedParams.has(key)) {
+			oauthParams.set(key, value);
+		}
+	}
+	loginUrl.searchParams.set("callbackURL", `/api/auth/oauth?${oauthParams.toString()}`);
+
+	return new Response(null, {
+		status: 302,
+		headers: { Location: `${loginUrl.pathname}${loginUrl.search}` },
+	});
+}

apps/server/src/http/headers.ts

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

apps/server/src/http/health.ts

@@ -1,8 +1,6 @@
-// Server-only API route. Lazy-imports keep db/storage/drizzle out of the client bundle.
-
-import { createFileRoute } from "@tanstack/react-router";
 import { sql } from "drizzle-orm";
-import { getStorageService } from "@reactive-resume/api/services/storage";
+import { withTimeout } from "es-toolkit";
+import { getStorageService } from "@reactive-resume/api/features/storage";
 import { db } from "@reactive-resume/db/client";
 
 const HEALTHCHECK_TIMEOUT_MS = 1_500;
@@ -14,30 +12,12 @@ type CheckResult = {
 	[key: string]: unknown;
 };
 
-function getErrorMessage(error: unknown): string {
-	if (error instanceof Error) return error.message;
-	return "Unknown error";
-}
-
-async function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
-	let timeoutId: NodeJS.Timeout | undefined;
-
-	const timeout = new Promise<never>((_, reject) => {
-		timeoutId = setTimeout(() => reject(new Error(`Timed out after ${timeoutMs}ms`)), timeoutMs);
-	});
-
-	try {
-		return await Promise.race([promise, timeout]);
-	} finally {
-		if (timeoutId) clearTimeout(timeoutId);
-	}
-}
-
+// ponytail: es-toolkit withTimeout takes a fn, not a promise — call site passes check (not check())
 async function runCheck(check: () => Promise<object>): Promise<CheckResult> {
 	const startedAt = performance.now();
 
 	try {
-		const data = await withTimeout(check(), HEALTHCHECK_TIMEOUT_MS);
+		const data = await withTimeout(check, HEALTHCHECK_TIMEOUT_MS);
 		const latencyMs = Math.round(performance.now() - startedAt);
 		const result = data as { status?: string };
 		if (result.status === "unhealthy") return { ...(data as object), status: "unhealthy", latencyMs };
@@ -45,13 +25,21 @@ async function runCheck(check: () => Promise<object>): Promise<CheckResult> {
 	} catch (error) {
 		return {
 			status: "unhealthy",
-			error: getErrorMessage(error),
+			error: error instanceof Error ? error.message : "Unknown error",
 			latencyMs: Math.round(performance.now() - startedAt),
 		};
 	}
 }
 
-async function healthHandler() {
+// ponytail: inner try/catches removed; runCheck's outer catch handles all errors
+async function checkDatabase() {
+	await db.execute(sql`SELECT 1`);
+	return { status: "healthy" };
+}
+
+const checkStorage = () => getStorageService().healthcheck();
+
+export async function handleHealth() {
 	const [database, storage] = await Promise.all([runCheck(checkDatabase), runCheck(checkStorage)]);
 	const status = [database, storage].some((check) => check.status === "unhealthy") ? "unhealthy" : "healthy";
 
@@ -79,35 +67,3 @@ async function healthHandler() {
 		status: checks.status === "unhealthy" ? 503 : 200,
 	});
 }
-
-async function checkDatabase() {
-	try {
-		await db.execute(sql`SELECT 1`);
-		return { status: "healthy" };
-	} catch (error) {
-		return {
-			status: "unhealthy",
-			error: error instanceof Error ? error.message : "Unknown error",
-		};
-	}
-}
-
-async function checkStorage() {
-	try {
-		const storageService = getStorageService();
-		return await storageService.healthcheck();
-	} catch (error) {
-		return {
-			status: "unhealthy",
-			error: error instanceof Error ? error.message : "Unknown error",
-		};
-	}
-}
-
-export const Route = createFileRoute("/api/health")({
-	server: {
-		handlers: {
-			GET: healthHandler,
-		},
-	},
-});

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

@@ -0,0 +1,109 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+	createPublicResumePdf: vi.fn(),
+}));
+
+vi.mock("@reactive-resume/api/features/resume/public-pdf", () => ({
+	createPublicResumePdf: mocks.createPublicResumePdf,
+	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");
+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 () => {
+		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 response = await handlePublicResumePdf(request, "jane", "resume", trustedClient);
+
+		expect(response.status).toBe(200);
+		expect(response.headers.get("Content-Type")).toBe("application/pdf");
+		expect(response.headers.get("Content-Disposition")).toBe('inline; filename="Ada_Lovelace.pdf"');
+		expect(response.headers.get("Cache-Control")).toBe("private, no-store");
+		expect(response.headers.get("X-Content-Type-Options")).toBe("nosniff");
+		expect(await response.text()).toBe("%PDF");
+		expect(mocks.createPublicResumePdf).toHaveBeenCalledWith({
+			username: "jane",
+			slug: "resume",
+			requestHeaders: request.headers,
+			trustedClient,
+			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

@@ -0,0 +1,72 @@
+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";
+
+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",
+): 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, {
+			headers: {
+				"Content-Type": "application/pdf",
+				"Content-Disposition": `inline; filename="${result.filename.replaceAll('"', "")}"`,
+				"Cache-Control": "private, no-store",
+				"X-Content-Type-Options": "nosniff",
+			},
+		});
+	} catch (error) {
+		const status = errorStatus(error);
+		return noStoreResponse(
+			status === 500 ? "Failed to generate public resume PDF" : "Public resume PDF unavailable",
+			status,
+		);
+	}
+}

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

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

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

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

apps/server/src/index.ts

@@ -0,0 +1,33 @@
+import { pathToFileURL } from "node:url";
+import { serve } from "@hono/node-server";
+import { env } from "@reactive-resume/env/server";
+import { createApp } from "./http/app";
+import { runStartupChecks } from "./startup/checks";
+
+export { createApp } from "./http/app";
+
+async function main() {
+	await runStartupChecks();
+
+	const port =
+		process.env.NODE_ENV === "production" ? Number.parseInt(process.env.PORT ?? "3000", 10) : env.SERVER_PORT;
+
+	const app = createApp();
+
+	serve(
+		{
+			fetch: app.fetch,
+			port,
+		},
+		(info) => {
+			console.info(`🚀 Up and running on http://localhost:${info.port}`);
+		},
+	);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+	main().catch((error) => {
+		console.error(error);
+		process.exit(1);
+	});
+}

apps/server/src/mcp/auth.ts

@@ -0,0 +1,33 @@
+import { auth, verifyOAuthToken } from "@reactive-resume/auth/config";
+
+export class AuthError extends Error {
+	constructor() {
+		super("Unauthorized");
+	}
+}
+
+export async function authenticateRequest(request: Request): Promise<void> {
+	const authHeader = request.headers.get("authorization");
+
+	if (authHeader?.startsWith("Bearer ")) {
+		try {
+			const payload = await verifyOAuthToken(authHeader.slice(7));
+			if (payload?.sub) return;
+		} catch {
+			// Invalid or expired token; fall through to API key auth.
+		}
+	}
+
+	const apiKey = request.headers.get("x-api-key");
+
+	if (apiKey) {
+		try {
+			const result = await auth.api.verifyApiKey({ body: { key: apiKey } });
+			if (result.valid) return;
+		} catch {
+			// Invalid or malformed key; fall through to AuthError.
+		}
+	}
+
+	throw new AuthError();
+}

apps/server/src/mcp/handler.ts

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

apps/server/src/mcp/server.ts

@@ -0,0 +1,68 @@
+import type { RouterClient } from "@orpc/server";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { onError } from "@orpc/client";
+import { createRouterClient } from "@orpc/server";
+import router from "@reactive-resume/api/routers";
+import { MCP_TOOL_NAME, registerPrompts, registerResources, registerTools } from "@reactive-resume/mcp";
+import { appVersion } from "../app-version";
+import { getRequestLocale } from "../rpc/locale";
+
+function createRequestClient(request: Request): RouterClient<typeof router> {
+	return createRouterClient(router, {
+		interceptors: [
+			onError((error) => {
+				console.error("[MCP oRPC]", error);
+			}),
+		],
+		context: () => ({
+			locale: getRequestLocale(request),
+			reqHeaders: request.headers,
+			resHeaders: new Headers(),
+		}),
+	});
+}
+
+export function createMcpServer(request: Request) {
+	const server = new McpServer(
+		{
+			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}\`.`,
+				`Import full ResumeData JSON with \`${MCP_TOOL_NAME.importResume}\`; read saved AI analysis with \`${MCP_TOOL_NAME.getResumeAnalysis}\`.`,
+			].join(" "),
+		},
+	);
+
+	const client = createRequestClient(request);
+	registerResources(server, client);
+	registerTools(server, client, request.headers);
+	registerPrompts(server);
+
+	return server;
+}

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

@@ -0,0 +1,27 @@
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, expect, it } from "vitest";
+import { generateOpenApiDocumentation } from "./generate-spec";
+
+const temporaryDirectories: string[] = [];
+const committedSpec = new URL("../../../../docs/spec.json", import.meta.url);
+
+afterEach(async () => {
+	await Promise.all(temporaryDirectories.splice(0).map((path) => rm(path, { recursive: true, force: true })));
+});
+
+it("keeps the committed OpenAPI specification synchronized without rewriting it", async () => {
+	const directory = await mkdtemp(join(tmpdir(), "openapi-documentation-"));
+	temporaryDirectories.push(directory);
+	const firstTarget = join(directory, "first.json");
+	const secondTarget = join(directory, "second.json");
+	const before = await readFile(committedSpec, "utf8");
+
+	await generateOpenApiDocumentation(firstTarget);
+	await generateOpenApiDocumentation(secondTarget);
+
+	expect(await readFile(firstTarget, "utf8")).toBe(before);
+	expect(await readFile(secondTarget, "utf8")).toBe(before);
+	expect(await readFile(committedSpec, "utf8")).toBe(before);
+});

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

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

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

@@ -0,0 +1,147 @@
+import { describe, expect, it } from "vitest";
+import z from "zod";
+import { defaultResumeData } from "@reactive-resume/schema/resume/default";
+import { createResumeDataJsonSchema } from "@reactive-resume/schema/resume/json-schema";
+
+type GeneratedSpecView = {
+	components?: { schemas?: Record<string, unknown> };
+	paths?: Record<
+		string,
+		Record<
+			string,
+			{
+				requestBody?: {
+					content?: Record<string, { schema?: unknown }>;
+				};
+			}
+		>
+	>;
+};
+
+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";
+	const { generateOpenApiSpec } = await import("./generator");
+	return generateOpenApiSpec({
+		appUrl: "https://rxresu.me",
+		version: "9.8.7",
+	});
+}
+
+function getRequestSchema(spec: GeneratedSpecView, path: string, method: string) {
+	return spec.paths?.[path]?.[method]?.requestBody?.content?.["application/json"]?.schema;
+}
+
+function containsImpossibleSchema(value: unknown): boolean {
+	if (Array.isArray(value)) return value.some(containsImpossibleSchema);
+	if (typeof value !== "object" || value === null) return false;
+	const object = value as Record<string, unknown>;
+	const negated = object.not;
+	if (typeof negated === "object" && negated !== null && Object.keys(negated).length === 0) {
+		return true;
+	}
+	return Object.values(object).some(containsImpossibleSchema);
+}
+
+function findImpossibleRequestSchemas(spec: GeneratedSpecView) {
+	const impossibleRequests: string[] = [];
+	for (const [path, operations] of Object.entries(spec.paths ?? {})) {
+		for (const [method, operation] of Object.entries(operations)) {
+			for (const [mediaType, content] of Object.entries(operation.requestBody?.content ?? {})) {
+				if (containsImpossibleSchema(content.schema)) {
+					impossibleRequests.push(`${method.toUpperCase()} ${path} (${mediaType})`);
+				}
+			}
+		}
+	}
+	return impossibleRequests;
+}
+
+describe("generateOpenApiSpec", () => {
+	it("uses caller-provided application URL and version", async () => {
+		const spec = await generateSpec();
+
+		expect(spec.info).toMatchObject({
+			title: "Reactive Resume",
+			version: "9.8.7",
+		});
+		expect(spec.servers).toEqual([{ url: "https://rxresu.me/api/openapi" }]);
+		expect(spec.externalDocs).toEqual({
+			url: "https://docs.rxresu.me",
+			description: "Reactive Resume Documentation",
+		});
+	}, 15_000);
+
+	it("uses the canonical input-side ResumeData schema in update requests", async () => {
+		const spec = (await generateSpec()) as GeneratedSpecView;
+		const { $schema: _dialect, ...canonicalInputSchema } = createResumeDataJsonSchema();
+
+		expect(spec.components?.schemas?.ResumeData).toEqual(canonicalInputSchema);
+		expect(getRequestSchema(spec, "/resumes/{id}", "put")).toMatchObject({
+			properties: {
+				data: { $ref: "#/components/schemas/ResumeData" },
+			},
+		});
+	});
+
+	it("publishes the custom-section type and item correlation", async () => {
+		const spec = (await generateSpec()) as GeneratedSpecView;
+		const schema = z.fromJSONSchema(spec.components?.schemas?.ResumeData as Parameters<typeof z.fromJSONSchema>[0]);
+		const mismatched = {
+			...defaultResumeData,
+			customSections: [
+				{
+					id: "custom-experience",
+					type: "experience",
+					title: "Experience",
+					icon: "",
+					columns: 1,
+					hidden: false,
+					keepTogether: false,
+					startOnNewPage: false,
+					items: [{ id: "summary-item", hidden: false, content: "<p>Not an experience item</p>" }],
+				},
+			],
+		};
+
+		expect(schema.safeParse(mismatched).success).toBe(false);
+	});
+
+	it("does not publish impossible request schemas", async () => {
+		const spec = (await generateSpec()) as GeneratedSpecView;
+
+		expect(findImpossibleRequestSchemas(spec)).toEqual([]);
+	});
+
+	it("checks every request body media type for impossible schemas", () => {
+		const spec: GeneratedSpecView = {
+			paths: {
+				"/documents": {
+					post: {
+						requestBody: {
+							content: {
+								"application/json": { schema: { type: "object" } },
+								"multipart/form-data": { schema: { not: {} } },
+							},
+						},
+					},
+				},
+			},
+		};
+
+		expect(findImpossibleRequestSchemas(spec)).toEqual(["POST /documents (multipart/form-data)"]);
+	});
+
+	it("documents imported data as an accepted ResumeData input", async () => {
+		const spec = (await generateSpec()) as GeneratedSpecView;
+
+		expect(getRequestSchema(spec, "/resumes/import", "post")).toEqual({
+			type: "object",
+			properties: {
+				data: { $ref: "#/components/schemas/ResumeData" },
+			},
+			required: ["data"],
+		});
+	});
+});

apps/server/src/openapi/generator.ts

@@ -0,0 +1,80 @@
+import { OpenAPIGenerator } from "@orpc/openapi";
+import { JSON_SCHEMA_INPUT_REGISTRY, ZodToJsonSchemaConverter } from "@orpc/zod/zod4";
+import { downloadResumePdfProcedure } from "@reactive-resume/api/features/resume/export";
+import router from "@reactive-resume/api/routers";
+import { resumeDataSchema } from "@reactive-resume/schema/resume/data";
+import { createResumeDataJsonSchema } from "@reactive-resume/schema/resume/json-schema";
+
+export const openAPIRouter = {
+	...router,
+	resume: {
+		...router.resume,
+		downloadPdf: downloadResumePdfProcedure,
+	},
+};
+
+const { $schema: _dialect, ...resumeDataInputSchema } = createResumeDataJsonSchema();
+type ResumeDataInputJsonSchema = Parameters<typeof JSON_SCHEMA_INPUT_REGISTRY.add<typeof resumeDataSchema>>[1];
+JSON_SCHEMA_INPUT_REGISTRY.add(resumeDataSchema, resumeDataInputSchema as unknown as ResumeDataInputJsonSchema);
+const importResumeInputSchema = openAPIRouter.resume.import["~orpc"].inputSchema;
+if (importResumeInputSchema) {
+	JSON_SCHEMA_INPUT_REGISTRY.add(importResumeInputSchema, {
+		type: "object",
+		properties: {
+			data: { $ref: "#/components/schemas/ResumeData" },
+		},
+		required: ["data"],
+	});
+}
+
+const openAPIGenerator = new OpenAPIGenerator({
+	schemaConverters: [
+		new ZodToJsonSchemaConverter({
+			interceptors: [
+				({ options, next }) => {
+					const [required, schema] = next();
+					const impossible =
+						Object.keys(schema).length === 1 &&
+						typeof schema.not === "object" &&
+						schema.not !== null &&
+						Object.keys(schema.not).length === 0;
+					return options.strategy === "input" && impossible ? [required, {}] : [required, schema];
+				},
+			],
+		}),
+	],
+});
+
+type GenerateOpenApiSpecOptions = {
+	appUrl: string;
+	version: string;
+};
+
+export async function generateOpenApiSpec({ appUrl, version }: GenerateOpenApiSpecOptions) {
+	return await openAPIGenerator.generate(openAPIRouter, {
+		info: {
+			title: "Reactive Resume",
+			version,
+			description: "Reactive Resume API",
+			license: { name: "MIT", url: "https://github.com/amruthpillai/reactive-resume/blob/main/LICENSE" },
+			contact: { name: "Amruth Pillai", email: "hello@amruthpillai.com", url: "https://amruthpillai.com" },
+		},
+		servers: [{ url: `${appUrl}/api/openapi` }],
+		externalDocs: { url: "https://docs.rxresu.me", description: "Reactive Resume Documentation" },
+		commonSchemas: {
+			ResumeData: { schema: resumeDataSchema, strategy: "input" },
+		},
+		components: {
+			securitySchemes: {
+				apiKey: {
+					type: "apiKey",
+					name: "x-api-key",
+					in: "header",
+					description: "The API key to authenticate requests.",
+				},
+			},
+		},
+		security: [{ apiKey: [] }],
+		filter: ({ contract }) => !contract["~orpc"].route.tags?.includes("Internal"),
+	});
+}

apps/server/src/openapi/handler.ts

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

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

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

apps/server/src/openapi/metadata.ts

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

apps/server/src/rpc/handler.ts

@@ -0,0 +1,33 @@
+import { onError } from "@orpc/server";
+import { RPCHandler } from "@orpc/server/fetch";
+import { BatchHandlerPlugin, RequestHeadersPlugin, StrictGetMethodPlugin } from "@orpc/server/plugins";
+import router from "@reactive-resume/api/routers";
+import { mergeResponseHeaders } from "../http/headers";
+import { stylesheetPreflightRunner } from "../services/stylesheet-preflight";
+import { getRequestLocale } from "./locale";
+
+const rpcHandler = new RPCHandler(router, {
+	plugins: [new BatchHandlerPlugin(), new RequestHeadersPlugin(), new StrictGetMethodPlugin()],
+	interceptors: [
+		onError((error) => {
+			console.error("[oRPC Server]", error);
+		}),
+	],
+});
+
+export async function handleRpc(request: Request, trustedClient = "unknown") {
+	const resHeaders = new Headers();
+	const { response } = await rpcHandler.handle(request, {
+		prefix: "/api/rpc",
+		context: {
+			locale: getRequestLocale(request),
+			reqHeaders: request.headers,
+			resHeaders,
+			trustedClient,
+			stylesheetPreflightRunner,
+		},
+	});
+
+	if (!response) return new Response("NOT_FOUND", { status: 404 });
+	return mergeResponseHeaders(response, resHeaders);
+}

apps/server/src/rpc/locale.ts

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

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

@@ -0,0 +1,248 @@
+import { 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;
+
+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");')}`,
+);
+
+const delayedSuccessfulWorker = new URL(
+	`data:text/javascript,${encodeURIComponent(`
+		import { parentPort, workerData } from "node:worker_threads";
+		parentPort.postMessage({ type: "ready" });
+		setTimeout(() => {
+			parentPort.postMessage({
+				ok: true,
+				pageCount: 1,
+				byteCount: Number(workerData.input.data.basics.name),
+				diagnostics: [],
+			});
+		}, 300);
+	`)}`,
+);
+
+const delayedReadyWorker = new URL(
+	`data:text/javascript,${encodeURIComponent(`
+		import { parentPort } from "node:worker_threads";
+		setTimeout(() => {
+			parentPort.postMessage({ type: "ready" });
+			setTimeout(() => {
+				parentPort.postMessage({
+					ok: true,
+					pageCount: 1,
+					byteCount: 1,
+					diagnostics: [],
+				});
+			}, 10);
+		}, 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: 5_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 = 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("preserves structured resume-data failures across the worker boundary", async () => {
+		const runner = 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 = 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 = 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 = createStylesheetPreflightRunner({ maxBytes: 16 });
+		const pageRunner = 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 = 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", async () => {
+		const runner = 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("bounds concurrent workers and queued requests without charging queue time to the worker deadline", async () => {
+		const runner = 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 = 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

@@ -0,0 +1,225 @@
+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;
+const SOURCE_WORKER_STARTUP_TIMEOUT_MS = 30_000;
+const WORKER_STARTUP_TIMEOUT_MS = 15_000;
+
+type SerializedPreflightCause = {
+	name: string;
+	message: string;
+	issues: readonly unknown[];
+};
+
+type StylesheetPreflightWorkerMessage =
+	| PdfPreflightResult
+	| { type: "ready" }
+	| { type: "preflight_error"; cause: SerializedPreflightCause };
+
+export type NodeStylesheetPreflightRunner = StylesheetPreflightRunner & {
+	readonly activeWorkerCount: number;
+	readonly queuedPreflightCount: number;
+};
+
+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),
+		...(source
+			? {
+					execArgv: sourceWorkerExecArgv(),
+					env: {
+						...process.env,
+						TSX_TSCONFIG_PATH: fileURLToPath(new URL("../../tsconfig.json", import.meta.url)),
+					},
+				}
+			: {}),
+	};
+};
+
+export function createStylesheetPreflightRunner(
+	overrides: Partial<StylesheetPreflightLimits> = {},
+	testWorkerUrl?: URL,
+): NodeStylesheetPreflightRunner {
+	const limits = Object.freeze({ ...STYLESHEET_PREFLIGHT_LIMITS, ...overrides });
+	let activeWorkerCount = 0;
+	// ponytail: Keep admission process-local and bounded; upgrade to a distributed/pooled queue only for multi-process coordination.
+	const queue: Array<{
+		input: StylesheetPreflightInput;
+		resolve: (result: PdfPreflightResult) => void;
+		reject: (cause: unknown) => void;
+	}> = [];
+
+	const runWorker = (
+		input: StylesheetPreflightInput,
+		resolve: (result: PdfPreflightResult) => void,
+		reject: (cause: unknown) => void,
+	): boolean => {
+		// The URL seam is internal to the server package and keeps worker failure tests independent from the PDF renderer.
+		const location = testWorkerUrl ? { source: false, url: testWorkerUrl } : workerLocation();
+		let worker: Worker;
+		try {
+			worker = new Worker(location.url, {
+				name: "stylesheet-preflight",
+				workerData: { input, limits },
+				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" in location ? { execArgv: location.execArgv } : {}),
+				...("env" in location ? { env: location.env } : {}),
+			});
+		} catch (error) {
+			resolve(workerFailure(error instanceof Error ? error : new Error("Failed to start PDF preflight worker.")));
+			return false;
+		}
+
+		activeWorkerCount += 1;
+		let settled = false;
+		let renderTimer: ReturnType<typeof setTimeout> | undefined;
+		let startupTimer: ReturnType<typeof setTimeout> | undefined;
+
+		const cleanup = () => {
+			if (renderTimer) clearTimeout(renderTimer);
+			if (startupTimer) clearTimeout(startupTimer);
+			worker.off("message", onMessage);
+			worker.off("error", onError);
+			worker.off("exit", onExit);
+			activeWorkerCount -= 1;
+		};
+
+		const finish = async (result: PdfPreflightResult) => {
+			if (settled) return;
+			settled = true;
+			await worker.terminate().catch(() => undefined);
+			cleanup();
+			resolve(result);
+			drainQueue();
+		};
+		const fail = async (cause: SerializedPreflightCause) => {
+			if (settled) return;
+			settled = true;
+			await worker.terminate().catch(() => undefined);
+			cleanup();
+			reject(Object.assign(new Error(cause.message), { name: cause.name, issues: cause.issues }));
+			drainQueue();
+		};
+
+		const onMessage = (message: StylesheetPreflightWorkerMessage) => {
+			if ("type" in message) {
+				if (message.type === "preflight_error") {
+					void fail(message.cause);
+					return;
+				}
+				if (startupTimer) clearTimeout(startupTimer);
+				renderTimer = setTimeout(() => {
+					void finish(failure("STYLESHEET_PREFLIGHT_TIMEOUT", "The PDF preflight exceeded its deadline."));
+				}, limits.timeoutMs);
+				return;
+			}
+			void finish(message);
+		};
+		const onError = (error: Error) => {
+			void finish(workerFailure(error));
+		};
+		const onExit = () => {
+			if (!settled) {
+				void finish(failure("STYLESHEET_PREFLIGHT_WORKER_FAILED", "The PDF preflight worker failed."));
+			}
+		};
+
+		worker.on("message", onMessage);
+		worker.once("error", onError);
+		worker.once("exit", onExit);
+		startupTimer = setTimeout(
+			() => {
+				void finish(failure("STYLESHEET_PREFLIGHT_WORKER_FAILED", "The PDF preflight worker failed."));
+			},
+			location.source ? SOURCE_WORKER_STARTUP_TIMEOUT_MS : WORKER_STARTUP_TIMEOUT_MS,
+		);
+		return true;
+	};
+
+	function drainQueue() {
+		while (activeWorkerCount < limits.maxConcurrentWorkers && queue.length > 0) {
+			const next = queue.shift();
+			if (!next) return;
+			runWorker(next.input, next.resolve, next.reject);
+		}
+	}
+
+	return {
+		get activeWorkerCount() {
+			return activeWorkerCount;
+		},
+		get queuedPreflightCount() {
+			return queue.length;
+		},
+
+		run(input: StylesheetPreflightInput): Promise<PdfPreflightResult> {
+			return new Promise<PdfPreflightResult>((resolve, reject) => {
+				if (activeWorkerCount < limits.maxConcurrentWorkers) {
+					runWorker(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 });
+			});
+		},
+	};
+}
+
+export const stylesheetPreflightRunner = createStylesheetPreflightRunner();

apps/server/src/startup/checks.ts

@@ -0,0 +1,67 @@
+import { constants, existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { migrate } from "drizzle-orm/node-postgres/migrator";
+import { Pool } from "pg";
+import { env } from "@reactive-resume/env/server";
+import { getLocalDataDirectory } from "@reactive-resume/utils/monorepo.node";
+
+function resolveFromCurrentModule(relativePath: string) {
+	return fileURLToPath(new URL(relativePath, import.meta.url));
+}
+
+function resolveWorkspaceFolder(folderName: string): string {
+	let dir = resolveFromCurrentModule(".");
+
+	while (dir !== path.dirname(dir)) {
+		const candidate = path.join(dir, folderName);
+		if (existsSync(candidate)) return candidate;
+		dir = path.dirname(dir);
+	}
+
+	throw new Error(`Could not locate ${folderName} folder relative to ${resolveFromCurrentModule(".")}`);
+}
+
+async function runDatabaseMigrations() {
+	console.info("Running database migrations...");
+
+	const pool = new Pool({ connectionString: env.DATABASE_URL });
+	const db = drizzle({ client: pool });
+
+	try {
+		await migrate(db, { migrationsFolder: resolveWorkspaceFolder("migrations") });
+		console.info("Database migrations completed");
+	} catch (error) {
+		console.error("Database migrations failed", { error });
+		throw error;
+	} finally {
+		await pool.end();
+	}
+}
+
+async function validateLocalStoragePath() {
+	if (env.S3_ACCESS_KEY_ID && env.S3_SECRET_ACCESS_KEY && env.S3_BUCKET) return;
+
+	const dataDirectory = getLocalDataDirectory(env.LOCAL_STORAGE_PATH);
+	console.info(`Validating local storage path: ${dataDirectory}`);
+
+	try {
+		await fs.mkdir(dataDirectory, { recursive: true });
+		await fs.access(dataDirectory, constants.R_OK | constants.W_OK);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : "Unknown error";
+		console.error(
+			`Local storage path is not writable: ${dataDirectory}\n` +
+				`  ${message}\n` +
+				"Set LOCAL_STORAGE_PATH to a writable directory or fix permissions on the existing path.",
+		);
+		throw error;
+	}
+}
+
+export async function runStartupChecks() {
+	await runDatabaseMigrations();
+	await validateLocalStoragePath();
+}

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

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

apps/server/src/static/schema.ts

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

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

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

apps/server/src/static/seo.ts

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

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

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

apps/server/src/static/uploads.ts

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

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

@@ -0,0 +1,182 @@
+import fs from "node:fs/promises";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+	env: { APP_URL: "https://rxresu.me" },
+	serveStatic: vi.fn((_options?: unknown) => vi.fn()),
+}));
+
+vi.mock("node:fs", () => ({
+	existsSync: vi.fn(() => true),
+}));
+
+vi.mock("node:fs/promises", () => ({
+	default: {
+		readFile: vi.fn(),
+	},
+}));
+
+vi.mock("@hono/node-server/serve-static", () => ({
+	serveStatic: mocks.serveStatic,
+}));
+
+vi.mock("@reactive-resume/env/server", () => ({
+	env: mocks.env,
+}));
+
+type StaticOptions = {
+	onFound?: (
+		path: string,
+		context: {
+			req: { path: string };
+			header: (name: string, value: string) => void;
+		},
+	) => void | Promise<void>;
+};
+
+const { handleWebApp } = await import("./web");
+const staticOptions = mocks.serveStatic.mock.calls[0]?.[0] as StaticOptions | undefined;
+
+describe("web app fallback classification", () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+		vi.mocked(fs.readFile).mockResolvedValue("<html>app</html>");
+	});
+
+	it("serves the shell for the root app route without noindex", async () => {
+		const response = await handleWebApp(new Request("https://example.com/"));
+
+		expect(response.status).toBe(200);
+		expect(response.headers.get("Content-Type")).toBe("text/html; charset=UTF-8");
+		expect(response.headers.get("X-Robots-Tag")).toBeNull();
+		expect(await response.text()).toBe("<html>app</html>");
+	});
+
+	it("injects canonical metadata and structured data into tracking-parameter root requests only", async () => {
+		vi.mocked(fs.readFile).mockResolvedValue(`
+			<!doctype html>
+			<html>
+				<head>
+					<title>Reactive Resume — A free and open-source resume builder</title>
+					<meta
+						name="description"
+						content="Reactive Resume is a free and open-source resume builder that simplifies the process of creating, updating, and sharing your resume."
+					>
+				</head>
+				<body><div id="app"></div></body>
+			</html>
+		`);
+
+		const response = await handleWebApp(new Request("http://server.internal/?utm_source=search"));
+		const html = await response.text();
+
+		expect(html).toContain('<link rel="canonical" href="https://rxresu.me/">');
+		expect(html).toContain('<link rel="preload" href="/videos/timelapse-v1.webp" as="image" fetchpriority="high">');
+		expect(html).toContain('<meta property="og:url" content="https://rxresu.me/">');
+		expect(html).toContain('<meta property="og:image" content="https://rxresu.me/opengraph/banner.jpg">');
+		expect(html).toContain('id="reactive-resume-structured-data"');
+		expect(html).toContain('"@type":["SoftwareApplication","WebApplication"]');
+		expect(html).toContain('"url":"https://rxresu.me/"');
+		expect(html).not.toContain("utm_source");
+
+		const dashboardResponse = await handleWebApp(new Request("https://example.com/dashboard"));
+		expect(await dashboardResponse.text()).not.toContain('rel="canonical"');
+	});
+
+	it("caches versioned homepage media immutably", async () => {
+		const headers = new Headers();
+
+		await staticOptions?.onFound?.("", {
+			req: { path: "/videos/timelapse-v1.mp4" },
+			header: (name, value) => headers.set(name, value),
+		});
+
+		expect(headers.get("Cache-Control")).toBe("public, max-age=31536000, immutable");
+
+		const unversionedHeaders = new Headers();
+		await staticOptions?.onFound?.("", {
+			req: { path: "/videos/timelapse.mp4" },
+			header: (name, value) => unversionedHeaders.set(name, value),
+		});
+
+		expect(unversionedHeaders.get("Cache-Control")).toBeNull();
+	});
+
+	it.each(["/", "/alice/resume"])("sets framing and report-only CSP security headers on %s", async (pathname) => {
+		const response = await handleWebApp(new Request(`https://example.com${pathname}`));
+
+		expect(response.status).toBe(200);
+		expect(response.headers.get("X-Frame-Options")).toBe("DENY");
+		expect(response.headers.get("X-Content-Type-Options")).toBe("nosniff");
+		expect(response.headers.get("Content-Security-Policy-Report-Only")).toContain("frame-ancestors 'none'");
+	});
+
+	it.each(["/auth/login", "/dashboard", "/builder/resume-1", "/agent", "/templates", "/templates/azurill.pdf"])(
+		"serves noindex shell for known app prefix %s",
+		async (pathname) => {
+			const response = await handleWebApp(new Request(`https://example.com${pathname}`));
+
+			expect(response.status).toBe(200);
+			expect(response.headers.get("Content-Type")).toBe("text/html; charset=UTF-8");
+			expect(response.headers.get("X-Robots-Tag")).toBe("noindex, follow");
+			expect(await response.text()).toBe("<html>app</html>");
+		},
+	);
+
+	it("serves noindex shell for public resume shaped routes", async () => {
+		const response = await handleWebApp(new Request("https://example.com/alice/resume"));
+
+		expect(response.status).toBe(200);
+		expect(response.headers.get("X-Robots-Tag")).toBe("noindex, follow");
+		expect(await response.text()).toBe("<html>app</html>");
+	});
+
+	it("returns noindex 404 for unknown non-asset routes", async () => {
+		const response = await handleWebApp(new Request("https://example.com/unknown/extra/path"));
+
+		expect(response.status).toBe(404);
+		expect(response.headers.get("Content-Type")).toBe("text/plain; charset=UTF-8");
+		expect(response.headers.get("X-Robots-Tag")).toBe("noindex, nofollow");
+		expect(await response.text()).toBe("Not Found");
+		expect(fs.readFile).not.toHaveBeenCalled();
+	});
+
+	it.each(["/api/foo", "/mcp/foo", "/uploads/foo"])(
+		"does not treat reserved two-segment path %s as a public resume",
+		async (pathname) => {
+			const response = await handleWebApp(new Request(`https://example.com${pathname}`));
+
+			expect(response.status).toBe(404);
+			expect(response.headers.get("Content-Type")).toBe("text/plain; charset=UTF-8");
+			expect(response.headers.get("X-Robots-Tag")).toBe("noindex, nofollow");
+			expect(await response.text()).toBe("Not Found");
+			expect(fs.readFile).not.toHaveBeenCalled();
+		},
+	);
+
+	it("returns plain 404 for missing asset-looking paths", async () => {
+		const response = await handleWebApp(new Request("https://example.com/assets/missing.css"));
+
+		expect(response.status).toBe(404);
+		expect(response.headers.get("X-Robots-Tag")).toBeNull();
+		expect(await response.text()).toBe("Not Found");
+		expect(fs.readFile).not.toHaveBeenCalled();
+	});
+
+	it("mirrors fallback status and headers for HEAD without a body", async () => {
+		const knownResponse = await handleWebApp(new Request("https://example.com/dashboard", { method: "HEAD" }));
+		const unknownResponse = await handleWebApp(
+			new Request("https://example.com/unknown/extra/path", { method: "HEAD" }),
+		);
+
+		expect(knownResponse.status).toBe(200);
+		expect(knownResponse.headers.get("Content-Type")).toBe("text/html; charset=UTF-8");
+		expect(knownResponse.headers.get("X-Robots-Tag")).toBe("noindex, follow");
+		expect(await knownResponse.text()).toBe("");
+
+		expect(unknownResponse.status).toBe(404);
+		expect(unknownResponse.headers.get("Content-Type")).toBe("text/plain; charset=UTF-8");
+		expect(unknownResponse.headers.get("X-Robots-Tag")).toBe("noindex, nofollow");
+		expect(await unknownResponse.text()).toBe("");
+	});
+});

apps/server/src/static/web.ts

@@ -0,0 +1,213 @@
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { serveStatic } from "@hono/node-server/serve-static";
+import { env } from "@reactive-resume/env/server";
+
+function resolveWebDistPath() {
+	const candidates = [
+		// Source layout: apps/server/src/static/web.ts -> apps/web/dist
+		fileURLToPath(new URL("../../../web/dist", import.meta.url)),
+		// Bundled layout: apps/server/dist/index.mjs -> apps/web/dist
+		fileURLToPath(new URL("../../web/dist", import.meta.url)),
+	];
+	const [fallback] = candidates;
+	if (!fallback) throw new Error("Could not resolve web dist path");
+
+	return candidates.find((candidate) => existsSync(candidate)) ?? fallback;
+}
+
+const staticRoot = resolveWebDistPath();
+const indexHtmlPath = `${staticRoot}/index.html`;
+const noindexShellPrefixes = ["/auth", "/dashboard", "/builder", "/agent", "/templates"];
+const reservedPublicResumeSegments = new Set([
+	"api",
+	"mcp",
+	".well-known",
+	"uploads",
+	"auth",
+	"dashboard",
+	"builder",
+	"agent",
+	"templates",
+]);
+
+function isAssetPath(pathname: string): boolean {
+	return pathname.split("/").pop()?.includes(".") ?? false;
+}
+
+function getPathSegments(pathname: string) {
+	return pathname.split("/").filter(Boolean);
+}
+
+function isNoindexShellPath(pathname: string): boolean {
+	return noindexShellPrefixes.some((prefix) => pathname === prefix || pathname.startsWith(`${prefix}/`));
+}
+
+function isPublicResumePath(pathname: string): boolean {
+	const segments = getPathSegments(pathname);
+	const [firstSegment] = segments;
+
+	return segments.length === 2 && firstSegment !== undefined && !reservedPublicResumeSegments.has(firstSegment);
+}
+
+const BASE_SECURITY_HEADERS = {
+	"X-Frame-Options": "DENY",
+	"X-Content-Type-Options": "nosniff",
+	"Referrer-Policy": "strict-origin-when-cross-origin",
+	"Content-Security-Policy-Report-Only":
+		"default-src 'self'; img-src 'self' data: blob:; font-src 'self' data:; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'; connect-src 'self'; frame-ancestors 'none'; base-uri 'self'; object-src 'none'",
+};
+
+const ROOT_TITLE = "Reactive Resume — A free and open-source resume builder";
+const ROOT_DESCRIPTION =
+	"Reactive Resume is a free and open-source resume builder that simplifies the process of creating, updating, and sharing your resume.";
+const ROOT_POSTER_PATH = "/videos/timelapse-v1.webp";
+const ROOT_FAQ_ITEMS = [
+	{
+		question: "Is Reactive Resume really free?",
+		answer:
+			"Yes! Reactive Resume is completely free to use, with no hidden costs, premium tiers, or subscription fees. It's open-source and will always remain free.",
+	},
+	{
+		question: "How is my data protected?",
+		answer:
+			"Your data is stored securely and is never shared with third parties. You can also self-host Reactive Resume on your own servers for complete control over your data.",
+	},
+	{
+		question: "Can I export my resume to PDF?",
+		answer:
+			"Absolutely! You can export your resume to PDF with a single click. The exported PDF maintains all your formatting and styling perfectly.",
+	},
+	{
+		question: "Is Reactive Resume available in multiple languages?",
+		answer:
+			"Yes, Reactive Resume is available in multiple languages. You can choose your preferred language in the settings page, or using the language switcher in the top right corner. If you don't see your language, or you would like to improve the existing translations, you can contribute to the translations on Crowdin.",
+	},
+	{
+		question: "What makes Reactive Resume different from other resume builders?",
+		answer:
+			"Reactive Resume is open-source, privacy-focused, and completely free. Unlike other resume builders, it doesn't show ads, track your data, or limit your features behind a paywall.",
+	},
+	{
+		question: "How do I share my resume?",
+		answer:
+			"You can share your resume via a unique public URL, protect it with a password, or download it as a PDF to share directly. The choice is yours!",
+	},
+] as const;
+
+function createRootSeoMarkup(canonicalUrl: string) {
+	const origin = new URL(canonicalUrl).origin;
+	const imageUrl = `${origin}/opengraph/banner.jpg`;
+	const structuredData = {
+		"@context": "https://schema.org",
+		"@graph": [
+			{
+				"@type": "WebSite",
+				name: "Reactive Resume",
+				url: canonicalUrl,
+			},
+			{
+				"@type": ["SoftwareApplication", "WebApplication"],
+				name: "Reactive Resume",
+				url: canonicalUrl,
+				description: ROOT_DESCRIPTION,
+				applicationCategory: "BusinessApplication",
+				operatingSystem: "Web",
+				isAccessibleForFree: true,
+				offers: {
+					"@type": "Offer",
+					price: "0",
+					priceCurrency: "USD",
+				},
+				codeRepository: "https://github.com/amruthpillai/reactive-resume",
+			},
+			{
+				"@type": "Project",
+				name: "Reactive Resume",
+				url: canonicalUrl,
+				sameAs: ["https://github.com/amruthpillai/reactive-resume"],
+			},
+			{
+				"@type": "FAQPage",
+				mainEntity: ROOT_FAQ_ITEMS.map((item) => ({
+					"@type": "Question",
+					name: item.question,
+					acceptedAnswer: {
+						"@type": "Answer",
+						text: item.answer,
+					},
+				})),
+			},
+		],
+	};
+
+	return `
+		<link rel="canonical" href="${canonicalUrl}">
+		<link rel="preload" href="${ROOT_POSTER_PATH}" as="image" fetchpriority="high">
+		<meta property="og:type" content="website">
+		<meta property="og:site_name" content="Reactive Resume">
+		<meta property="og:title" content="${ROOT_TITLE}">
+		<meta property="og:description" content="${ROOT_DESCRIPTION}">
+		<meta property="og:url" content="${canonicalUrl}">
+		<meta property="og:image" content="${imageUrl}">
+		<meta name="twitter:card" content="summary_large_image">
+		<meta name="twitter:title" content="${ROOT_TITLE}">
+		<meta name="twitter:description" content="${ROOT_DESCRIPTION}">
+		<meta name="twitter:image" content="${imageUrl}">
+		<script id="reactive-resume-structured-data" type="application/ld+json">${JSON.stringify(structuredData)}</script>
+	`;
+}
+
+export const serveWebDistStatic = serveStatic({
+	root: staticRoot,
+	onFound: (_path, context) => {
+		if (/^\/videos\/.*-v\d+\.(?:mp4|webp)$/.test(context.req.path)) {
+			context.header("Cache-Control", "public, max-age=31536000, immutable");
+		}
+	},
+});
+
+function getFallbackResponseHeaders(pathname: string) {
+	if (pathname === "/") return { "Content-Type": "text/html; charset=UTF-8", ...BASE_SECURITY_HEADERS };
+	if (isNoindexShellPath(pathname) || isPublicResumePath(pathname)) {
+		return {
+			"Content-Type": "text/html; charset=UTF-8",
+			"X-Robots-Tag": "noindex, follow",
+			...BASE_SECURITY_HEADERS,
+		};
+	}
+
+	return null;
+}
+
+function notFoundResponse(options: { head?: boolean; noindex?: boolean } = {}) {
+	const headers = new Headers({ "Content-Type": "text/plain; charset=UTF-8" });
+	if (options.noindex) headers.set("X-Robots-Tag", "noindex, nofollow");
+
+	return new Response(options.head ? null : "Not Found", {
+		status: 404,
+		headers,
+	});
+}
+
+// ponytail: GET and HEAD share the same routing logic; method determines body presence
+export async function handleWebApp(request: Request) {
+	const isHead = request.method === "HEAD";
+	const pathname = new URL(request.url).pathname;
+
+	if (!isNoindexShellPath(pathname) && isAssetPath(pathname)) {
+		return new Response(isHead ? null : "Not Found", { status: 404 });
+	}
+
+	const headers = getFallbackResponseHeaders(pathname);
+	if (!headers) return notFoundResponse({ head: isHead, noindex: true });
+
+	if (isHead) return new Response(null, { status: 200, headers });
+
+	const html = await fs.readFile(indexHtmlPath, "utf-8");
+	const canonicalUrl = new URL("/", env.APP_URL).toString();
+	const responseHtml = pathname === "/" ? html.replace("</head>", `${createRootSeoMarkup(canonicalUrl)}</head>`) : html;
+
+	return new Response(responseHtml, { headers });
+}