chore: release v5.3.0

Release v5.3.0 with cover letter improvements, accessible resume outlines, original photo upload support, and maintenance updates.

.codacy.yml

@@ -0,0 +1,3 @@
+---
+exclude_paths:
+  - "migrations/**"

.design-sync/NOTES.md

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

.design-sync/build-css.mjs

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

.design-sync/config.json

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

.design-sync/conventions.md

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

.design-sync/previews/Accordion.tsx

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

.design-sync/previews/Alert.tsx

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

.design-sync/previews/AlertDialog.tsx

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

.design-sync/previews/Attachment.tsx

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

.design-sync/previews/Avatar.tsx

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

.design-sync/previews/Badge.tsx

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

.design-sync/previews/Bubble.tsx

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

.design-sync/previews/Button.tsx

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

.design-sync/previews/ButtonGroup.tsx

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

.design-sync/previews/ComboboxRoot.tsx

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

.design-sync/previews/Command.tsx

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

.design-sync/previews/ContextMenu.tsx

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

.design-sync/previews/Dialog.tsx

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

.design-sync/previews/DropdownMenu.tsx

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

.design-sync/previews/FormItem.tsx

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

.design-sync/previews/HoverCard.tsx

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

.design-sync/previews/Input.tsx

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

.design-sync/previews/InputGroup.tsx

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

.design-sync/previews/Kbd.tsx

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

.design-sync/previews/Label.tsx

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

.design-sync/previews/Marker.tsx

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

.design-sync/previews/Message.tsx

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

.design-sync/previews/MessageScroller.tsx

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

.design-sync/previews/Popover.tsx

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

.design-sync/previews/ResizableGroup.tsx

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

.design-sync/previews/ScrollArea.tsx

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

.design-sync/previews/Separator.tsx

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

.design-sync/previews/Sheet.tsx

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

.design-sync/previews/Sidebar.tsx

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

.design-sync/previews/Skeleton.tsx

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

.design-sync/previews/Slider.tsx

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

.design-sync/previews/Spinner.tsx

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

.design-sync/previews/Switch.tsx

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

.design-sync/previews/Tabs.tsx

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

.design-sync/previews/Textarea.tsx

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

.design-sync/previews/Toaster.tsx

@@ -1,20 +0,0 @@
-import { useEffect } from "react";
-import { Toaster, toast } from "@reactive-resume/ui/components/toast";
-
-// 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.add({
-			type: "success",
-			title: "Resume published",
-			description: "“Software Engineer” is now live at rxresume.me/jane-doe.",
-			timeout: 0,
-		});
-	}, []);
-	return (
-		<div style={{ minHeight: 140 }}>
-			<Toaster />
-		</div>
-	);
-};

.design-sync/previews/Toggle.tsx

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

.design-sync/previews/Tooltip.tsx

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

.design-sync/tw-entry.css

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

.env.example

@@ -9,6 +9,10 @@ SERVER_PORT="3001"
 # OpenGraph metadata, and absolute upload URLs.
 APP_URL="http://localhost:3000"
 
+# Optional: serve one already-public resume at /. Use the ID from /builder/<id>.
+# Unset or blank keeps the marketing home. Restart after changes.
+# ROOT_RESUME_ID=
+
 # --- Database (PostgreSQL) ---
 # PostgreSQL connection URL. In Docker Compose, the hostname is usually `postgres`;
 # when running directly on your machine, `localhost` is typical.
@@ -97,8 +101,6 @@ FLAG_DISABLE_IMAGE_PROCESSING="false"
 # Rate limiting is enabled by default in production to prevent abuse.
 FLAG_DISABLE_API_RATE_LIMIT="false"
 
-# This flag shows sponsor placements on the public landing page.
-FLAG_SHOW_SPONSORS="false"
 
 # Allows dynamic OAuth client registration to use any parseable redirect URI,
 # including custom schemes, private hosts, and non-loopback http:// URLs.

.github/.well-known/funding.json

@@ -15,7 +15,7 @@
 		{
 			"guid": "reactive-resume",
 			"name": "Reactive Resume",
-			"description": "A free and open-source resume builder that simplifies the process of creating, updating, and sharing your resume.",
+			"description": "A free and open-source resume builder that makes it easy to create, update, and share your resume.",
 			"webpageUrl": {
 				"url": "https://rxresu.me"
 			},

.github/copilot-instructions.md

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

.github/workflows/e2e.yml

@@ -76,8 +76,8 @@ jobs:
       - name: Build
         run: pnpm build
 
-      - name: Run Baseline E2E Tests
-        run: pnpm exec playwright test --grep-invert "@semantic-css"
+      - name: Run E2E Tests
+        run: pnpm exec playwright test
 
       - name: Upload Playwright Report
         if: always()

.gitignore

@@ -49,23 +49,17 @@ temp
 .agents
 .claude
 .cursor
+.opencode
 .codegraph
 .superpowers
 .worktrees
 .migration
+graphify-out
 
 # 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
+.vite-hooks
+

.orchestration/imported-table-raster-ci-fix.md

@@ -0,0 +1,39 @@
+# Imported-table raster CI fix
+
+## Root cause
+
+Hosted runs `34007560930` (PR #3471) and `34007788443` (PR #3472) failed only in
+`tests/e2e/specs/imported-table.spec.ts` with `horizontal: 18` instead of Plan 16's
+`horizontal: 17`; text and vertical checks passed.
+
+The PDF operator dump from the failed hosted artifact showed 29 table path records matching the Plan 16 contract
+(17 horizontal, 12 vertical), followed by an unrelated `constructPath` `endPath` bbox:
+`[0, 19.65, 358.93, 20.65]`. Its stroke color was reported as `#cc00cc` only because the helper retained the
+last table stroke color. It was a later red section-divider fill/no-paint path, not an extra table border. The old
+helper classified every thin bbox after the last matching color state, so it counted this false positive.
+
+The table's explicit width is stable at 300pt, while row height legitimately changes from 30pt to 31pt after the
+`Beta!` edit. The helper therefore scopes candidate paths by the fixture's 300pt horizontal grid envelope, not by a
+row-height tolerance. Missing or duplicated paths inside that envelope still change the exact 17/12 contract.
+
+## Change
+
+- Added `tests/e2e/fixtures/pdf-borders.ts` with deterministic `countTableBorderGeometry` filtering.
+- Updated browser/server PDF inspection in `tests/e2e/specs/imported-table.spec.ts` to use the helper.
+- Added `tests/e2e/fixtures/pdf-borders.test.ts`; regression proves old stale-color counting returns 2 horizontal
+  paths while topology-scoped counting returns 1.
+
+## Verification
+
+- Intent skill inventory: 7 packages, 26 skills; no matching local skill for this E2E/PDF helper.
+- Focused helper regression: 1 file, 1 passed.
+- Dedicated imported-table E2E: 2 consecutive runs, each 1 passed; both exercise initial, unrelated-edit, and table-edit
+  stages plus browser and server PDF exports.
+- Production build: 3/3 tasks successful.
+- Web typecheck via `rtk proxy pnpm --filter web typecheck`: passed (`tsgo --noEmit`).
+- Turbo boundaries: 1,443 files across 20 packages, no issues.
+- Targeted Biome: 3 files, no issues.
+- `git diff --check`: passed.
+
+The root `pnpm typecheck` wrapper was also tried but invokes an incompatible `tsc` path and reports TS5096 for
+`allowImportingTsExtensions`; the package's documented `tsgo --noEmit` typecheck passes.

.orchestration/plan-21-implementation.md

@@ -0,0 +1,33 @@
+# Plan 21 implementation evidence
+
+## Revision and scope
+
+- Worktree: `issue-3060-section-heading-visibility`
+- Base: current `origin/main` at dispatch, `2a4a1583b` (`fix(pdf): restore Gengar skill rating order (#3473)`)
+- Product decisions applied: Q1 explicit Show heading toggle; Q2 Move-to continuations default visible; Q3 visual omission in preview/PDF/DOCX with accessible outline labels retained.
+- No `.codegraph/` directory exists in this worktree, so CodeGraph was skipped after the required presence check.
+- Intent discovery ran before edits; no matching local skill was available for this schema/PDF/DOCX/web change.
+
+## Implementation
+
+- Added backward-compatible `showHeading` section data for summary, built-ins, and custom sections. `parseResumeData` normalizes absent legacy values to `true`; explicit `false` survives round trips.
+- Added heading toggles to built-in/summary and custom section menus. Toggle mutations use `useUpdateResumeData`, preserving undo/autosave/save/reload behavior; legacy absent values are treated as visible. Existing lock fieldset remains authoritative.
+- Move-to-created custom sections explicitly set `showHeading: true`, independent of source heading state or copied title.
+- `SectionShell` omits complete heading/icon/decoration output when disabled in both icon and no-icon branches. Empty titles still resolve localized defaults.
+- DOCX section renderers omit visible heading paragraphs for summary, built-in, and custom sections while retaining content. Screen-reader mirror continues to expose section labels regardless of visual setting.
+- Added characterization for Semantic CSS `section[id="..."] section-heading { display: none; }`; body remains while heading is omitted.
+- Updated default/sample fixtures, generated schema references, recovery hashes, and compatibility tests; existing Gengar renderer/order changes remain untouched.
+
+## Verification
+
+- `pnpm --filter @reactive-resume/schema test`: 9 files, 132 tests passed.
+- `pnpm --filter @reactive-resume/pdf test`: 81 files, 1059 tests passed.
+- `pnpm --filter @reactive-resume/docx test`: 9 files, 76 tests passed.
+- `pnpm --filter web test`: 135 files, 942 tests passed.
+- `pnpm test`: full Turborepo suite passed (19 successful tasks; 10 cache hits).
+- Affected typechecks passed: schema, PDF, DOCX, web.
+- Focused menu, Move-to, accessible-outline, schema, PDF semantic, and DOCX renderer tests passed.
+- `pnpm exec turbo boundaries`: passed (1108 files, 20 packages).
+- Read-only `pnpm exec biome check` on 22 changed source/test files: passed; no write-capable `pnpm check` run.
+- `git diff --check`: passed.
+- Final diff review completed; local commit follows.

.orchestration/plan-23-item-pagination-blocker.md

@@ -0,0 +1,32 @@
+# Plan 23 item-pagination execution evidence
+
+## Scope
+
+Plan 23 steps 1–3 were evaluated from `origin/main` at `368858a56` (Plan 21 / PR #3477 merged). Widow/orphan UI and authored-page continuation guidance remain deferred from this execution, and Semantic CSS was not changed.
+
+## Durable diagnostic matrix
+
+`packages/pdf/src/templates/shared/item-pagination.test.tsx` renders physical PDF pages and checks numbered tokens exactly once for:
+
+- an item that fits remaining space;
+- an item that fits a full page but not the remaining space;
+- an oversized item taller than one page;
+- a two-line paragraph at a boundary;
+- nested bullets; and
+- built-in plus custom items in an Azurill sidebar/main-column overflow fixture.
+
+The fixture also keeps authored `metadata.layout.pages` separate from renderer-generated physical pages.
+
+The current deterministic baseline is: fit remainder = 1 physical page; full-page-but-not-remainder = 3 pages with sampled tokens on pages 2/2/3; oversized = 5 pages with sampled tokens on pages 1/3/5; two-line boundary = 2 pages; nested bullets = 1 page; Azurill built-in/custom/sidebar = 5 pages with sampled tokens on pages 1/4/5/5/1. Page numbers here are 1-based; every token still appears exactly once.
+
+## Concrete blocker
+
+React PDF's only available item-level keep-together primitive is `View wrap={false}`. A durable renderer fixture with 180 paragraph-like child views shows that a non-wrapping item cannot safely fall back when its content exceeds one page: the renderer omits the oversized tail instead of splitting it. Applying the same prop to shared `SectionItem` would therefore violate the lossless token requirement; no item schema flag or menu control was added.
+
+Do not estimate item height from HTML length, persist physical pages, alter existing Semantic CSS, or claim #3350 complete. A future implementation needs renderer-supported conditional keep-together behavior or an actual measured two-pass fallback that preserves every token.
+
+## Verification
+
+- `pnpm --filter @reactive-resume/pdf exec vitest run src/templates/shared/item-pagination.test.tsx`: 7 tests passed.
+- No production source or schema changes made after the unsafe fallback was reproduced.
+- Undo/persistence/lock UI coverage is intentionally absent because no item control was shipped; add it only when safe fallback exists.

.orchestration/plan-27a-diagnostic.md

@@ -0,0 +1,157 @@
+# Plan 27 Phase A diagnostic evidence
+
+Date: 2026-09-06  
+Issue: [#3377](https://github.com/amruthpillai/reactive-resume/issues/3377)  
+Revision: `2a4a1583b` (`origin/main` at run start)  
+Scope: Phase A, steps 1–2 only. No resolver, runtime behavior, or remote-source behavior changed.
+
+## Drift and authority
+
+- Worktree started clean and `HEAD` matched `origin/main`; `git diff origin/main...HEAD` was empty.
+- Current catalog is `packages/fonts/src/webfontlist.json`. Its web font records point at both Google Fonts static assets and jsDelivr assets; “Google blocked” is not an offline proof.
+- Browser preview is `apps/web/src/components/typography/font-display.tsx` and calls `FontFace.load()` against each catalog preview URL.
+- Browser PDF preview/download is `apps/web/src/features/resume/export/pdf-document.tsx` → `@reactive-resume/pdf/browser`; registration is `packages/pdf/src/hooks/use-register-fonts.ts`.
+- Server PDF is `apps/server/src/http/resume-pdf.ts` → `createResumePdfDownload`; Playwright browser routing cannot observe that process’s outbound font fetches.
+- The issue is open and unmodified. PR #3455 is the approved planning PR; its plan/decision log grants execution of this bounded diagnostic and manifest evidence.
+
+## Deterministic fixture
+
+`tests/e2e/fixtures/offline-fonts.ts` seeds one disposable resume after sample creation. It writes the same text into basics and summary, hides the picture, selects IBM Plex Serif 400/700 for body and heading, and marks the row public for the server-PDF surface.
+
+The exact markers are versioned as `offline-font-scripts-v1`:
+
+| Marker | Script or coverage |
+| --- | --- |
+| `Latin punctuation • — “quotes” €` | Latin plus General Punctuation and currency |
+| `简体中文` | Han / Simplified Chinese |
+| `العربية` | Arabic |
+| `עברית` | Hebrew |
+| `ไทย` | Thai |
+| `Emoji 🚀` | Emoji |
+
+`tests/e2e/specs/offline-fonts.spec.ts` is opt-in (`OFFLINE_FONT_DIAGNOSTIC=1`) so the normal PR E2E suite does not become network-dependent. Each surface creates a new browser context with persisted auth state, disabled service workers, and no prior browser cache. Every non-same-origin request is aborted and recorded as `{ hostname, path }`; query strings, fragments, headers, bodies, tokens, and full URLs never enter diagnostic output. Reports are attached as JSON and emitted with the same sanitized shape.
+
+The four surfaces are separate tests:
+
+1. Font picker preview opens Typography → Font Family and waits for lazy `FontFace` preview loads.
+2. Builder PDF preview navigates to the builder, captures the active PDF canvas, and measures marker-local raster crops.
+3. Browser PDF download uses the Export dialog, rasterizes the downloaded PDF, and measures marker-local crops when generation succeeds.
+4. Server PDF calls the public PDF endpoint and records text-layer marker presence when generation succeeds.
+
+Builder/browser-PDF reports keep PDF text extraction as a separate `textLayerMarkers` signal; it does not prove visible glyph outlines. Raster evidence attaches a rendered PNG and per-marker crop metrics, failing for blank or tofu-like visible crops. Blocked browser font requests classify browser surfaces as `network-error`. The server report deliberately says `server-outbound-requests-unobservable-from-playwright`; its cold-network gate remains unresolved because server outbound capture and verifiable restart identity require external host-level controls.
+
+## Run protocol and cold-cache boundary
+
+Build and database setup follow `tests/e2e/README.md`. Run each surface in a separately restarted production server process so module-level PDF font registration state cannot leak between controls:
+
+```text
+OFFLINE_FONT_DIAGNOSTIC=1 OFFLINE_FONT_DIAGNOSTIC_SERVER_RESTARTED=1 \
+  pnpm exec playwright test tests/e2e/specs/offline-fonts.spec.ts --grep "picker preview"
+```
+
+Stop and restart the production server before repeating the command with `builder PDF`, `browser PDF`, and `server PDF` grep patterns. The environment used for this change had no built `apps/server/dist` or `apps/web/dist`, no running PostgreSQL instance, and no production server to restart, so the cold E2E matrix was not run. This is an explicit infrastructure blocker, not a pass claim. The test records `serverRestartFlag` only as caller input and labels it non-proof; it does not claim a completed cold-network gate.
+
+The current Playwright route guard cannot impose host-level egress denial on Node.js running the server. A genuinely cold server test therefore needs a separately restarted server plus host-level egress capture/deny (for example, a controlled network namespace or an approved outbound proxy). Do not infer server network behavior from an empty browser request list.
+
+## Administrator-hosted manifest proposal
+
+This is a proposal, not an asset download. It intentionally contains only the primary family and glyph fallbacks required by the fixture and current PDF fallback map, not the full catalog.
+
+```json
+{
+  "schemaVersion": "offline-fonts-v1",
+  "mode": "local-only",
+  "assetRoot": "/fonts/offline/v1",
+  "families": {
+    "IBM Plex Serif": {
+      "normal": { "400": "ibm-plex-serif/400.ttf", "700": "ibm-plex-serif/700.ttf" },
+      "italic": { "400": "ibm-plex-serif/400-italic.ttf", "700": "ibm-plex-serif/700-italic.ttf" },
+      "preview": "ibm-plex-serif/preview.ttf"
+    },
+    "IBM Plex Sans": {
+      "normal": { "400": "ibm-plex-sans/400.ttf", "700": "ibm-plex-sans/700.ttf" },
+      "italic": { "400": "ibm-plex-sans/400-italic.ttf", "700": "ibm-plex-sans/700-italic.ttf" },
+      "preview": "ibm-plex-sans/preview.ttf"
+    },
+    "Noto Serif": {
+      "normal": { "400": "noto-serif/400.ttf", "700": "noto-serif/700.ttf" },
+      "italic": { "400": "noto-serif/400-italic.ttf", "700": "noto-serif/700-italic.ttf" },
+      "preview": "noto-serif/preview.ttf"
+    },
+    "Noto Sans": {
+      "normal": { "400": "noto-sans/400.ttf", "700": "noto-sans/700.ttf" },
+      "italic": { "400": "noto-sans/400-italic.ttf", "700": "noto-sans/700-italic.ttf" },
+      "preview": "noto-sans/preview.ttf"
+    },
+    "Noto Sans SC": { "normal": { "400": "noto-sans-sc/400.ttf", "700": "noto-sans-sc/700.ttf" }, "italic": "reuse-normal", "preview": "noto-sans-sc/preview.ttf" },
+    "Noto Serif SC": { "normal": { "400": "noto-serif-sc/400.ttf", "700": "noto-serif-sc/700.ttf" }, "italic": "reuse-normal", "preview": "noto-serif-sc/preview.ttf" },
+    "Noto Sans TC": { "normal": { "400": "noto-sans-tc/400.ttf", "700": "noto-sans-tc/700.ttf" }, "italic": "reuse-normal", "preview": "noto-sans-tc/preview.ttf" },
+    "Noto Serif TC": { "normal": { "400": "noto-serif-tc/400.ttf", "700": "noto-serif-tc/700.ttf" }, "italic": "reuse-normal", "preview": "noto-serif-tc/preview.ttf" },
+    "Noto Sans JP": { "normal": { "400": "noto-sans-jp/400.ttf", "700": "noto-sans-jp/700.ttf" }, "italic": "reuse-normal", "preview": "noto-sans-jp/preview.ttf" },
+    "Noto Serif JP": { "normal": { "400": "noto-serif-jp/400.ttf", "700": "noto-serif-jp/700.ttf" }, "italic": "reuse-normal", "preview": "noto-serif-jp/preview.ttf" },
+    "Noto Sans KR": { "normal": { "400": "noto-sans-kr/400.ttf", "700": "noto-sans-kr/700.ttf" }, "italic": "reuse-normal", "preview": "noto-sans-kr/preview.ttf" },
+    "Noto Serif KR": { "normal": { "400": "noto-serif-kr/400.ttf", "700": "noto-serif-kr/700.ttf" }, "italic": "reuse-normal", "preview": "noto-serif-kr/preview.ttf" },
+    "Noto Sans Arabic": { "normal": { "400": "noto-sans-arabic/400.ttf", "700": "noto-sans-arabic/700.ttf" }, "italic": "reuse-normal", "preview": "noto-sans-arabic/preview.ttf" },
+    "Noto Naskh Arabic": { "normal": { "400": "noto-naskh-arabic/400.ttf", "700": "noto-naskh-arabic/700.ttf" }, "italic": "reuse-normal", "preview": "noto-naskh-arabic/preview.ttf" },
+    "Noto Sans Hebrew": { "normal": { "400": "noto-sans-hebrew/400.ttf", "700": "noto-sans-hebrew/700.ttf" }, "italic": "reuse-normal", "preview": "noto-sans-hebrew/preview.ttf" },
+    "Noto Sans Thai": { "normal": { "400": "noto-sans-thai/400.ttf", "700": "noto-sans-thai/700.ttf" }, "italic": "reuse-normal", "preview": "noto-sans-thai/preview.ttf" },
+    "Noto Emoji": { "normal": { "400": "noto-emoji/400.ttf", "700": "noto-emoji/700.ttf" }, "italic": "reuse-normal", "preview": "noto-emoji/preview.ttf" }
+  }
+}
+```
+
+### Candidate source, license, script, and size evidence
+
+Sizes are `Content-Length` bytes from a HEAD request to the exact current catalog assets on 2026-09-06. Responses reported `Content-Encoding: gzip`; these are compressed transfer-size estimates, not a claim about the eventual on-disk representation. Preview paths are aliases to the selected 400 face and add no extra bytes when stored once. Primary sources: [IBM Plex LICENSE.txt](https://github.com/IBM/plex/blob/master/LICENSE.txt), [Noto core LICENSE](https://github.com/notofonts/noto-fonts/blob/main/LICENSE), [Noto CJK Sans LICENSE](https://github.com/notofonts/noto-cjk/blob/main/Sans/LICENSE), and [Noto Emoji font LICENSE](https://github.com/googlefonts/noto-emoji/blob/main/fonts/LICENSE).
+
+| Family | Style/weights in proposal | Current catalog source version | License | Script/fallback role | Gzip bytes (selected files) | Build owner; runtime owners |
+| --- | --- | --- | --- | --- | ---: | --- |
+| IBM Plex Serif | normal 400/700; italic 400/700 | `fonts.gstatic.com/s/ibmplexserif/v20` | OFL 1.1, Reserved Font Name `Plex` | Primary serif; Latin and punctuation stack | 294,717 | `packages/fonts`; `apps/web` FontDisplay; `packages/pdf` registration |
+| IBM Plex Sans | normal 400/700; italic 400/700 | `fonts.gstatic.com/s/ibmplexsans/v23` | OFL 1.1, Reserved Font Name `Plex` | Primary sans | 435,469 | `packages/fonts`; `apps/web` FontDisplay; `packages/pdf` registration |
+| Noto Serif | normal 400/700; italic 400/700 | `fonts.gstatic.com/s/notoserif/v33` | OFL 1.1 | Serif punctuation fallback | 1,055,120 | `packages/fonts`; `packages/pdf` fallback registration |
+| Noto Sans | normal 400/700; italic 400/700 | `fonts.gstatic.com/s/notosans/v42` | OFL 1.1 | Sans punctuation fallback | 1,236,259 | `packages/fonts`; `packages/pdf` fallback registration |
+| Noto Sans SC | normal 400/700; italic reuses normal | `fonts.gstatic.com/s/notosanssc/v40` | OFL 1.1 (Noto CJK) | Simplified Han; CJK fallback | 12,766,416 | `packages/fonts`; `packages/pdf` CJK fallback |
+| Noto Serif SC | normal 400/700; italic reuses normal | `fonts.gstatic.com/s/notoserifsc/v35` | OFL 1.1 (Noto CJK) | Simplified Han serif fallback | 17,350,185 | `packages/fonts`; `packages/pdf` CJK fallback |
+| Noto Sans TC | normal 400/700; italic reuses normal | `fonts.gstatic.com/s/notosanstc/v39` | OFL 1.1 (Noto CJK) | Traditional Han fallback | 8,628,278 | `packages/fonts`; `packages/pdf` CJK fallback |
+| Noto Serif TC | normal 400/700; italic reuses normal | `fonts.gstatic.com/s/notoseriftc/v36` | OFL 1.1 (Noto CJK) | Traditional Han serif fallback | 11,804,923 | `packages/fonts`; `packages/pdf` CJK fallback |
+| Noto Sans JP | normal 400/700; italic reuses normal | `fonts.gstatic.com/s/notosansjp/v56` | OFL 1.1 (Noto CJK) | Kana and Japanese Han fallback | 6,383,035 | `packages/fonts`; `packages/pdf` CJK fallback |
+| Noto Serif JP | normal 400/700; italic reuses normal | `fonts.gstatic.com/s/notoserifjp/v33` | OFL 1.1 (Noto CJK) | Kana and Japanese Han serif fallback | 8,685,862 | `packages/fonts`; `packages/pdf` CJK fallback |
+| Noto Sans KR | normal 400/700; italic reuses normal | `fonts.gstatic.com/s/notosanskr/v39` | OFL 1.1 (Noto CJK) | Hangul and Korean Han fallback | 6,102,888 | `packages/fonts`; `packages/pdf` CJK fallback |
+| Noto Serif KR | normal 400/700; italic reuses normal | `fonts.gstatic.com/s/notoserifkr/v31` | OFL 1.1 (Noto CJK) | Hangul and Korean Han serif fallback | 11,113,442 | `packages/fonts`; `packages/pdf` CJK fallback |
+| Noto Sans Arabic | normal 400/700; italic reuses normal | `fonts.gstatic.com/s/notosansarabic/v33` | OFL 1.1 | Arabic sans fallback | 178,455 | `packages/fonts`; `packages/pdf` script fallback |
+| Noto Naskh Arabic | normal 400/700; italic reuses normal | `fonts.gstatic.com/s/notonaskharabic/v44` | OFL 1.1 | Arabic serif fallback | 190,924 | `packages/fonts`; `packages/pdf` script fallback |
+| Noto Sans Hebrew | normal 400/700; italic reuses normal | `fonts.gstatic.com/s/notosanshebrew/v50` | OFL 1.1 | Hebrew fallback for both serif/sans slots | 55,707 | `packages/fonts`; `packages/pdf` script fallback |
+| Noto Sans Thai | normal 400/700; italic reuses normal | `fonts.gstatic.com/s/notosansthai/v29` | OFL 1.1 | Thai fallback for both serif/sans slots | 55,173 | `packages/fonts`; `packages/pdf` script fallback |
+| Noto Emoji | normal 400/700; italic reuses normal | `fonts.gstatic.com/s/notoemoji/v62` | OFL 1.1 for font files; assets/tools have separate licenses | Emoji outline fallback; verify renderer support | 1,153,847 | `packages/fonts`; `packages/pdf` script fallback |
+
+Estimated transfer size for all rows and listed styles: **87,490,700 bytes (~83.44 MiB)**. This confirms why a full-catalog bundle is out of scope. A later implementation should subset by declared glyph requirements or make the administrator choose fallback families; it must not silently fetch another CDN.
+
+### Source and license obligations
+
+- Pin an upstream release/commit and retain source attribution plus the complete applicable license with hosted assets. Do not use mutable `@latest` URLs as runtime sources.
+- IBM Plex’s license has Reserved Font Name `Plex`; modified/subset outputs must follow OFL naming requirements.
+- Noto core, Noto CJK, and Noto Emoji font files are OFL 1.1, but Noto Emoji documents separate Apache/public-domain treatment for tools and flag image assets. Bundle only font files unless those other assets are intentionally needed and separately attributed.
+- License checks are build-owner responsibility (`packages/fonts`/tooling); runtime owners (`apps/web` and `packages/pdf`) consume only the validated manifest.
+
+### Missing-family and missing-asset behavior
+
+Local mode must resolve only same-origin administrator-hosted manifest paths. If imported resume data names an unavailable family, show an actionable missing-family error naming the family and required local asset; apply a configured local fallback only when the administrator explicitly supplied one. If a required weight/style/fallback asset is absent, fail the affected preview/export with an actionable diagnostic containing family/style/weight and local path. Never retry Google Fonts, jsDelivr, or any other remote URL in local mode.
+
+Standard PDF families (Helvetica, Courier, Times-Roman) remain file-free. They do not prove that a document containing punctuation, CJK, Arabic, Hebrew, Thai, or emoji is network-free; the script fallback rows remain required.
+
+## Verification record
+
+Completed read-only checks before handoff:
+
+- CodeGraph exploration of font catalog, picker preview, browser PDF, server PDF, and existing fallback tests.
+- `pnpm dlx @tanstack/intent@latest list`: no matching local intent skill for this work.
+- `pnpm exec biome check tests/e2e/specs/offline-fonts.spec.ts tests/e2e/fixtures/offline-fonts.ts turbo.json`: passed.
+- `git diff --check`: passed.
+- `pnpm --filter @reactive-resume/fonts test`: passed (55 tests).
+- `pnpm --filter @reactive-resume/pdf exec vitest run src/hooks/use-register-fonts.test.ts`: passed (35 tests).
+- Web typography/regression suite: passed (940 tests across 135 files); web and server package typechecks passed.
+- `pnpm exec playwright test tests/e2e/specs/offline-fonts.spec.ts --list`: passed (4 diagnostic tests collected).
+- E2E diagnostic execution: blocked by missing build outputs and unavailable PostgreSQL/server; no success claim made.
+- `pnpm exec turbo boundaries`: passed on fresh rerun (Turbo 2.10.12, 1108 files, no issues).
+
+The implementation intentionally stops at diagnostic fixtures and manifest evidence. Shared source resolution, asset hosting, local-mode configuration, and production behavior remain Phase A step 3+ work.

.orchestration/plan-27a-remediation-round-2.md

@@ -0,0 +1,22 @@
+# Plan 27A remediation round 2
+
+Date: 2026-09-06
+Base: `ae8e2f76f`
+
+## Focused fixes
+
+- Removed multilingual markers from the fixture headline. Each marker now exists only in its dedicated summary paragraph.
+- Added pure marker-location helpers. Marker lookup joins PDF text items, supports markers split across items, rejects duplicate occurrences, and rejects non-whitespace neighbors that could contaminate a local crop.
+- Raster measurement still scans with antialiasing padding but counts ink only inside the marker box, preventing neighboring glyphs from making blank or tofu-like evidence pass.
+- Browser PDF download now separates download errors from post-download evidence errors. A received download with failed rasterization is reported as `unresolved-raster-evidence-error` and fails the opt-in test rather than passing as a generic download error.
+- Added focused pure tests covering duplicate, split, neighboring, blank, and tofu-like cases.
+- Removed trailing spaces from `plan-27a-remediation.md`.
+
+## Verification
+
+- `pnpm exec vitest run tests/e2e/fixtures/offline-font-markers.test.ts` — 5/5 passed.
+- `pnpm exec biome check tests/e2e/specs/offline-fonts.spec.ts tests/e2e/fixtures/offline-fonts.ts tests/e2e/fixtures/offline-font-markers.ts tests/e2e/fixtures/offline-font-markers.test.ts` — passed.
+- `pnpm exec playwright test tests/e2e/specs/offline-fonts.spec.ts --list` — 4 tests collected.
+- `git diff --check` — passed after remediation-document whitespace cleanup.
+
+Full diagnostic E2E remains opt-in and was not run in this focused round. Server outbound request capture and verifiable restart identity remain explicit external host-level blockers; no production resolver changes were made.

.orchestration/plan-27a-remediation.md

@@ -0,0 +1,24 @@
+# Plan 27A remediation
+
+Date: 2026-09-06
+Base: `61b58ae9a`
+Scope: concrete findings from `.orchestration/plan-27a-independent-review.md` only.
+
+## Remediated findings
+
+- Builder PDF preview and browser PDF download now produce raster evidence. The fixture stores each multilingual marker in its own summary paragraph, allowing the diagnostic to locate marker-local PDF text boxes and measure only those raster crops. Reports attach a rendered PNG plus per-marker `inkPixels`, trimmed dimensions, and status. Blank and tofu-like crops fail assertions; no whole-page snapshot is used.
+- PDF text extraction is reported separately as `textLayerMarkers`. It is not described or asserted as proof of visible glyph outlines.
+- Server PDF output remains text-extraction-only and is explicitly classified as `serverGateStatus: unresolved-external-host-level-blocker`. `serverRestartFlag` is caller input, not restart proof. Browser Playwright routing is not used to infer server egress, and no production resolver or instrumentation behavior was added.
+- `.orchestration/plan-27a-diagnostic.md` now records a fresh boundaries pass and the corrected `87,490,700 bytes (~83.44 MiB)` arithmetic.
+- Diagnostic remains opt-in through `OFFLINE_FONT_DIAGNOSTIC=1`; normal CI behavior remains unchanged. Request logs stay sanitized to hostname and pathname.
+
+## Verification
+
+- `pnpm exec biome check tests/e2e/specs/offline-fonts.spec.ts tests/e2e/fixtures/offline-fonts.ts` — passed.
+- `git diff --check` — passed.
+- `pnpm exec playwright test tests/e2e/specs/offline-fonts.spec.ts --list` — 4 tests collected.
+- `pnpm --filter @reactive-resume/fonts test` — 55/55 passed.
+- `pnpm --filter @reactive-resume/pdf exec vitest run src/hooks/use-register-fonts.test.ts` — 35/35 passed.
+- `pnpm exec turbo boundaries` — passed on fresh rerun (Turbo 2.10.12, 1108 files, no issues).
+
+Full diagnostic E2E remains unrun because this environment lacks production build output, PostgreSQL, and a production server. Server cold-network capture and verifiable restart identity remain external host-level blockers by design; this remediation does not claim that gate is complete.

.orchestration/remediation-issue-3350-item-pagination.md

@@ -0,0 +1,17 @@
+# Issue 3350 remediation evidence
+
+## Findings addressed
+
+- `item-pagination.test.tsx` now derives complete numbered-token inventories for each generated fixture and asserts every token exactly once. Sampled token-to-physical-page placement checks remain separate.
+- Pagination fixtures snapshot `metadata.layout.pages` before rendering and assert authored layout pages are unchanged afterward. Overflow fixtures also assert physical PDF page count exceeds authored page count.
+- Unsafe `wrap={false}` renderer coverage remains diagnostic-only; no item controls, schema flags, or runtime behavior were added.
+
+## Verification
+
+- `rtk proxy pnpm --filter @reactive-resume/pdf exec vitest run src/semantic/pagination.test.tsx src/templates/shared/item-pagination.test.tsx` — 2 files, 11 tests passed.
+- `rtk proxy pnpm --filter @reactive-resume/pdf typecheck` — passed.
+- `rtk proxy pnpm exec biome check packages/pdf/src/templates/shared/item-pagination.test.tsx` — passed.
+- `rtk proxy pnpm exec turbo boundaries` — passed; 1109 files checked.
+- `rtk git diff --check origin/main...HEAD` — passed.
+
+Only PDF test coverage and this evidence file changed; production behavior remains untouched.

AGENTS.md

@@ -9,163 +9,118 @@ Before editing files for a substantial task:
 - Multiple matches: prefer the most specific local skill for the package or concern you are changing; load additional skills only when the task spans multiple packages or concerns.
 <!-- intent-skills:end -->
 
-# AGENTS.md
+<!-- caveman-begin -->
+Respond terse like smart caveman. All technical substance stay. Only fluff die.
 
-## Cursor Cloud specific instructions
+Rules:
+- Drop: articles (a/an/the), filler (just/really/basically), pleasantries, hedging
+- Fragments OK. Short synonyms. Technical terms exact. Code unchanged.
+- Pattern: [thing] [action] [reason]. [next step].
+- Not: "Sure! I'd be happy to help you with that."
+- Yes: "Bug in auth middleware. Fix:"
 
-### Overview
+Switch level: /caveman lite|full|ultra|wenyan-lite|wenyan-full|wenyan-ultra
+Stop: "stop caveman" or "normal mode"
 
-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.
+Auto-Clarity: drop caveman for security warnings, irreversible actions, user confused. Resume after.
 
-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.
+Boundaries: code/commits/PRs written normal.
+<!-- caveman-end -->
 
-### Prerequisites
+<!-- graphify-begin -->
 
-- **Node.js 24** (matches Dockerfile `ARG NODE_VERSION=24`). Use `nvm install 24 && nvm use 24` if needed.
-- **Docker** is required to run PostgreSQL. Start it with `sudo dockerd &` if the daemon isn't running.
-- **pnpm 11.21.0**. Install pnpm directly using the [official installation guide](https://pnpm.io/installation).
+## Agent skills
 
-### Codebase map
+- Issues and specs: GitHub Issues for `amruthpillai/reactive-resume`. See `docs/agents/issue-tracker.md`.
+- Domain docs use a multi-context layout. See `docs/agents/domain.md`.
 
-- `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.
+## Overview
 
-### Web app conventions
+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; `apps/server` mounts the API/auth/MCP/static routes and serves the built web app.
 
-- 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:
+Internal packages are source-consumed through `package.json` export maps pointing at `src` files. Do not assume package-local `dist` output exists unless a package explicitly adds it.
 
-```ts
-type IntentSelectFieldProps<TValue extends string> = {
-	label: string;
-	id: string;
-	value: TValue | undefined;
-	options: readonly ComboboxOption<TValue>[];
-	onChange: (value: TValue | undefined) => void;
-};
+Prerequisites: **Node.js 24** (matches Dockerfile `ARG NODE_VERSION=24`), **pnpm 11.21.0** ([install guide](https://pnpm.io/installation)), and **Docker** for PostgreSQL (`sudo dockerd &` if the daemon isn't running).
 
-function IntentSelectField<TValue extends string>(props: IntentSelectFieldProps<TValue>) {
-	// ...
-}
-```
+## Ownership map
 
-### Package and feature boundaries
+Where each concern lives, and where new code for it goes:
 
-- 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.
+| Area | Owner |
+|------|-------|
+| Web routes, loaders, user-facing workflows | `apps/web/src/routes`, `apps/web/src/features` (file-based; never hand-edit `routeTree.gen.ts`) |
+| Server HTTP routes/adapters, startup checks, static handlers, MCP transport, OpenAPI/well-known | `apps/server/src/{http,rpc,mcp,openapi,static,startup}` |
+| Authenticated API contracts + business logic | `packages/api/src/features/*` (oRPC routers, DTOs, rate limiting; aggregated at `@reactive-resume/api/routers` for `/api/rpc`) |
+| Auth | `packages/auth` (Better Auth config/helpers/types; `apps/server/src/http/auth.ts` delegates to `auth.handler`) |
+| DB client + schema | `packages/db` (Drizzle; migrations at repo root `migrations/`) |
+| Server env validation | `packages/env` (auto-loads root `.env`) |
+| Resume/page/template Zod schemas | `packages/schema` |
+| Pure resume-domain behavior (no DB/HTTP/DOM/renderer deps) | `packages/resume` (JSON Patch helpers, social-network icons) |
+| Resume PDF rendering | `packages/pdf` (React PDF document, font registration, template primitives, browser/server adapters) |
+| PDF.js viewer/canvas UI | `apps/web/src/features/resume` — never in `packages/pdf` |
+| DOCX export | `packages/docx` |
+| MCP tools/prompts/resources/server-card | `packages/mcp` |
+| Generic UI primitives + hooks | `packages/ui` (Base UI/shadcn-style); workflow-specific UI stays in the owning web feature |
+| Focused support surfaces | `packages/fonts`, `packages/email`, `packages/import`, `packages/ai`, `packages/utils`, `packages/config` — prefer existing exports over cross-package shortcuts |
+| Dev-only scripts | `tooling/`, not `packages/`, so packages only hold runtime-bundled code |
 
-Placement decision tree:
+Narrow cross-cutting helpers go in `packages/utils` only after checking no domain package is a better owner. Specifically: resume JSON Patch behavior belongs in `@reactive-resume/resume/patch` and DOCX builders in `@reactive-resume/docx` — not in `@reactive-resume/utils`.
 
-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.
+## Web app conventions
 
-### Database
+- `apps/web/src/router.tsx` initializes router context with `queryClient`, `orpc`, `theme`, `locale`, `session`, and `flags`. Reuse route context instead of refetching these ad hoc.
+- Builder shell: `apps/web/src/routes/builder/$resumeId`. Its nested preview route is client-only (`ssr: false`); the public resume route `apps/web/src/routes/$username/$slug.tsx` uses `ssr: "data-only"`.
+- Browser-only preview code: `apps/web/src/features/resume/preview`. Public PDF viewer: `apps/web/src/features/resume/public`. Keep PDF.js/canvas/browser APIs out of SSR paths.
+- Isomorphic oRPC client: `apps/web/src/libs/orpc/client.ts` — server calls use an in-process router client, browser calls use `/api/rpc` with credentials included.
+- For React components with explicit props, use a named props type (e.g. `type FooProps = {...}` with `function Foo(props: FooProps)`) rather than inline object annotations, especially with more than one field or with generics.
 
-PostgreSQL runs via Docker Compose:
+## Package boundaries
+
+`pnpm exec turbo boundaries` is the executable check. Rules:
+
+- Workspace deps go through package names and export maps. Never import another workspace's `src` tree via repo paths, `@reactive-resume/*/src/*`, or TS path aliases.
+- Workspace `turbo.json` files declare coarse tags: `app:web`, `app:server`, `runtime:server` (server-only packages: API/auth/db/env/email/MCP), `runtime:browser` (browser-only shared UI), `runtime:universal` (environment-neutral domain packages), plus `role:domain|infra|adapter|api|rendering|tooling` for intent.
+- Runtime-specific code lives behind explicit export subpaths (`@reactive-resume/pdf/browser`, `@reactive-resume/pdf/server`, `@reactive-resume/env/server`). Keep root exports environment-neutral unless the package is intentionally server-only.
+- Wildcard exports are allowed only for leaf libraries with an intentionally file-like surface — currently `@reactive-resume/ui/components/*`, `@reactive-resume/ui/hooks/*`, and schema resume model files. Prefer explicit exports for packages owning runtime behavior.
+- Prefer `protectedProcedure` from `packages/api/src/context.ts` for authenticated procedures. Expose only intentional public surfaces through `packages/api/package.json`.
+- Shared PDF section filtering: `packages/pdf/src/templates/shared/filtering.ts`. Template-specific visual exceptions stay in the owning template directory unless multiple templates need the behavior. `packages/pdf/src/hooks/use-register-fonts.ts` owns font registration, standard PDF fonts, CJK fallback stacks, and global hyphenation.
+
+Multi-place changes:
+
+- **Resume data shape**: `packages/schema/src/resume/*` first, then API DTOs, importers, PDF rendering, and web forms consuming it.
+- **New template**: `packages/schema/src/templates.ts`, `packages/pdf/src/templates/index.ts`, source under `packages/pdf/src/templates/<name>/`, and previews under `apps/web/public/templates/{jpg,pdf}`.
+- **New DB column/table**: `packages/db/src/schema/*`, then `dotenvx run -f .env.local -- pnpm db:generate`.
+- **New env var**: `packages/env/src/server.ts` **and** the `globalEnv` array in `turbo.json`. Turborepo 2.x strict env mode filters out unlisted vars, so the variable will be `undefined` in child processes at runtime even when correctly set in the OS/container environment.
+
+## Environment and database
+
+Copy `.env.example` to `.env.local`. Three required vars: `APP_URL` (default `http://localhost:3000`), `DATABASE_URL` (default `postgresql://postgres:postgres@localhost:5432/postgres`), `AUTH_SECRET` (any non-empty string).
+
+- **S3/SeaweedFS optional.** If `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, and `S3_BUCKET` are all set, the app uses S3-compatible storage. `.env.example` ships SeaweedFS defaults, so either start the `seaweedfs` compose service or comment those vars out to use local filesystem storage under `<workspace>/data`. `LOCAL_STORAGE_PATH` must be absolute when set.
+- **`REDIS_URL` and `ENCRYPTION_SECRET`** are optional for core resume flows but both required for saved AI providers and the authenticated `/agent` workspace. Host-run dev uses `REDIS_URL=redis://localhost:6379`; the container-run app uses `redis://redis:6379`.
+- **`drizzle-kit` (used by `pnpm db:migrate`) reads `DATABASE_URL` from `process.env` directly** — it does not auto-load `.env`. Run migration commands through `dotenvx`.
+- The production server auto-runs migrations at startup before serving traffic, so manual `pnpm db:migrate` is mainly for first setup, migration debugging, or applying migrations without starting the app.
+
+## Commands
+
+Prefix dev servers and migration commands with `dotenvx run -f .env.local --`. Tests, typechecks, linters, boundary checks, and `pnpm build` do not need it; if one fails on a missing env var, rerun it with the prefix.
 
 ```
-sudo docker compose -f compose.dev.yml up -d postgres
+sudo docker compose -f compose.dev.yml up -d postgres                                    # DB only
+sudo docker compose -f compose.dev.yml up -d postgres redis seaweedfs seaweedfs_create_bucket   # full infra
+dotenvx run -f .env.local -- pnpm dev            # port 3000 (dev:web for web only)
+dotenvx run -f .env.local -- pnpm db:generate    # db:migrate to apply
+pnpm check                                       # Biome — WRITE-CAPABLE (--write --unsafe)
+pnpm test | pnpm typecheck | pnpm build | pnpm exec turbo boundaries
 ```
 
-The dev default connection string is `postgresql://postgres:postgres@localhost:5432/postgres`.
+Prefer package filters over repo-wide runs, e.g. `pnpm --filter web typecheck`, `pnpm --filter @reactive-resume/pdf test`. Vitest paths are package-relative under `pnpm --filter <package> test -- <path>`.
 
-**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.
+## Gotchas
 
-The production server runs migrations during startup before serving traffic. Manual `pnpm db:migrate` is mainly for first setup, migration debugging, or applying migrations without starting the app.
-
-### Environment
-
-Copy `.env.example` to `.env.local`. The three required variables are:
-
-- `APP_URL` (default `http://localhost:3000`)
-- `DATABASE_URL` (default `postgresql://postgres:postgres@localhost:5432/postgres`)
-- `AUTH_SECRET` (any non-empty string)
-
-S3/SeaweedFS is optional. If `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, and `S3_BUCKET` are all set, the app uses S3-compatible storage. The checked-in `.env.example` sets SeaweedFS defaults, so either start the `seaweedfs` compose service too or comment out those S3 vars to use local filesystem storage under `<workspace>/data`. `LOCAL_STORAGE_PATH` must be absolute when set.
-
-`REDIS_URL` and `ENCRYPTION_SECRET` are optional for core resume flows, but both are required for saved AI providers and the authenticated `/agent` workspace. Start the `redis` compose service and set both vars in `.env.local` when working on those features. For host-run development, use `REDIS_URL=redis://localhost:6379`; the container-run app uses `REDIS_URL=redis://redis:6379`.
-
-When running dev servers or migration commands, prefix the command with `dotenvx run -f .env.local --`. For example: `dotenvx run -f .env.local -- pnpm dev`. Tests, typechecks, linters, boundary checks, and `pnpm build` do not need this prefix by default. If one of those commands fails because a specific environment variable is required, rerun it with the `dotenvx run -f .env.local --` prefix.
-
-### Common commands
-
-| Task | Command |
-|------|---------|
-| Install deps | `pnpm install` |
-| Start Postgres only | `sudo docker compose -f compose.dev.yml up -d postgres` |
-| Start Postgres + SeaweedFS | `sudo docker compose -f compose.dev.yml up -d postgres seaweedfs seaweedfs_create_bucket` |
-| Start full dev infrastructure | `sudo docker compose -f compose.dev.yml up -d postgres redis seaweedfs seaweedfs_create_bucket` |
-| Generate migrations | `dotenvx run -f .env.local -- pnpm db:generate` |
-| Run migrations | `dotenvx run -f .env.local -- pnpm db:migrate` |
-| Dev server | `dotenvx run -f .env.local -- pnpm dev` (starts on port 3000) |
-| Web dev server only | `dotenvx run -f .env.local -- pnpm dev:web` |
-| Lint/format | `pnpm check` (Biome) |
-| Boundary check | `pnpm exec turbo boundaries` |
-| Tests | `pnpm test` (Vitest) |
-| Build | `pnpm build` |
-| Typecheck | `pnpm typecheck` |
-
-For focused validation, prefer package filters before repo-wide commands, for example:
-
-```
-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.
+- Email sending needs SMTP config; without it emails are logged to console. Dev still works — verification links appear in server logs.
+- `lefthook.yml` pre-commit runs `biome check` on staged files. Run `pnpm check` before committing.
+- `pnpm check` is write-capable. Call that out when using it, and use narrower Biome commands for a non-mutating inspection.
+- Biome: tabs, double quotes, line width 120, organized import groups, sorted Tailwind classes for `clsx`, `cva`, `cn`.
+- Most packages typecheck with `tsgo --noEmit` and test with `vitest run --passWithNoTests`.
+- There may be unrelated local edits in the worktree. Check `git status --short` first; do not revert files you did not touch.

CONTEXT-MAP.md

@@ -0,0 +1,3 @@
+# Domain contexts
+
+- [Resume](packages/resume/CONTEXT.md): authored resume content and presentation concepts shared by the builder and exporters.

GLOSSARY.md

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

README.md

@@ -5,7 +5,7 @@
 
   <h1>Reactive Resume</h1>
 
-  <p>Reactive Resume is a free and open-source resume builder that simplifies the process of creating, updating, and sharing your resume.</p>
+  <p>Reactive Resume is a free and open-source resume builder that makes it easy to create, update, and share your resume.</p>
 
   <p>
     <a href="https://rxresu.me"><strong>Get Started</strong></a>
@@ -27,38 +27,24 @@
 
 ---
 
-Reactive Resume makes building resumes straightforward. Pick a template, fill in your details, and export to PDF—no account required for basic use. For those who want more control, the entire application can be self-hosted on your own infrastructure.
+Pick a template, fill in your details, and export to PDF. Basic use needs no account. If you want more control, you can run the whole application on your own infrastructure.
 
-Built with privacy as a core principle, Reactive Resume gives you complete ownership of your data. The codebase is fully open-source under the MIT license, with no tracking, no ads, and no hidden costs.
-
-## Sponsors
-
-Reactive Resume stays free, open-source, and independent because companies choose to support the work behind it. Thank you to every sponsor who helps fund hosting, maintenance, and continued development for the community.
-
-<p>
-  <a href="https://www.atlascloud.ai/?utm_source=github&utm_medium=link&utm_campaign=reactive-resume">
-    <img src="apps/web/public/sponsors/atlas-cloud-logo-white.svg" alt="Atlas Cloud" width="320" />
-  </a>
-</p>
-
-[Atlas Cloud](https://www.atlascloud.ai/?utm_source=github&utm_medium=link&utm_campaign=reactive-resume) supports Reactive Resume as a project sponsor. Atlas Cloud provides a unified AI platform for developers, with access to hundreds of models for chat, image generation, video generation, media processing, and GPU cloud workloads through one API key, one endpoint, and one billing account.
-
-If your company would like to sponsor Reactive Resume, email [hello@amruthpillai.com](mailto:hello@amruthpillai.com).
+You own your data. The codebase is open source under the MIT license, with no tracking, no ads, and no hidden costs.
 
 ## Features
 
 **Resume Building**
 
-- Real-time preview as you type
+- Live preview as you type
 - Multiple export formats (PDF, JSON, DOCX)
 - Drag-and-drop section ordering
 - Custom sections for any content type
-- Rich text editor with formatting support
+- Rich text editor
 
 **Templates**
 
-- Professionally designed templates
-- A4 and Letter size support
+- 15 templates to choose from
+- A4 and Letter page sizes
 - Customizable colors, fonts, and spacing
 - Structured Style Rules for section and text styling
 
@@ -75,7 +61,7 @@ If your company would like to sponsor Reactive Resume, email [hello@amruthpillai
 - Multi-language support
 - Share resumes via unique links
 - Import from JSON Resume format
-- Dark mode support
+- Dark mode
 - Passkey and two-factor authentication
 
 ## Templates
@@ -187,14 +173,14 @@ For detailed setup instructions, environment configuration, and self-hosting gui
 
 ## Documentation
 
-Comprehensive guides are available at [docs.rxresu.me](https://docs.rxresu.me):
+The full documentation lives at [docs.rxresu.me](https://docs.rxresu.me):
 
 | Guide                                                                        | Description                      |
 | ---------------------------------------------------------------------------- | -------------------------------- |
 | [Getting Started](https://docs.rxresu.me/getting-started)                    | First-time setup and basic usage |
 | [Self-Hosting](https://docs.rxresu.me/self-hosting/docker)                   | Deploy on your own server        |
-| [Development Setup](https://docs.rxresu.me/contributing/development)         | Local development environment    |
-| [Project Architecture](https://docs.rxresu.me/contributing/architecture)     | Codebase structure and patterns  |
+| [Development setup](https://docs.rxresu.me/contributing/development)         | Local development environment    |
+| [Project architecture](https://docs.rxresu.me/contributing/architecture)     | Codebase structure and patterns  |
 | [Exporting Your Resume](https://docs.rxresu.me/guides/exporting-your-resume) | PDF and JSON export options      |
 
 ## Self-Hosting
@@ -204,7 +190,7 @@ Reactive Resume can be self-hosted using Docker. The stack includes:
 - **PostgreSQL** — Database for storing user data and resumes
 - **SeaweedFS** (optional) — S3-compatible storage for file uploads
 
-> **From v5.1.0 onwards** — PDF generation now runs entirely client-side via `@react-pdf/renderer`. New deployments no longer require Browserless, Chromium, or any external print service as a dependency. The `PRINTER_*` and `BROWSERLESS_*` environment variables are no longer read and can be removed from your `.env`.
+> **From v5.1.0 onwards** — PDF generation runs entirely client-side via `@react-pdf/renderer`. New deployments no longer need Browserless, Chromium, or any external print service. The `PRINTER_*` and `BROWSERLESS_*` environment variables are no longer read and can be removed from your `.env`.
 
 Pull the latest image from Docker Hub or GitHub Container Registry:
 
@@ -220,7 +206,7 @@ See the [self-hosting guide](https://docs.rxresu.me/self-hosting/docker) for com
 
 ## Support
 
-Reactive Resume is and always will be free and open-source. If it has helped you land a job or saved you time, please consider supporting continued development:
+Reactive Resume is and always will be free and open source. If it has helped you land a job or saved you time, please consider supporting continued development:
 
 <p>
   <a href="https://github.com/sponsors/AmruthPillai">
@@ -251,7 +237,7 @@ Other ways to support:
 
 ## Contributing
 
-Contributions make open-source thrive. Whether fixing a typo or adding a feature, all contributions are welcome.
+Every contribution helps, whether it is a typo fix or a new feature.
 
 1. Fork the repository
 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
@@ -259,7 +245,7 @@ Contributions make open-source thrive. Whether fixing a typo or adding a feature
 4. Push to the branch (`git push origin feature/amazing-feature`)
 5. Open a Pull Request
 
-See the [development setup guide](https://docs.rxresu.me/contributing/development) for detailed instructions on how to set up the project locally.
+See the [development setup guide](https://docs.rxresu.me/contributing/development) for how to run the project locally.
 
 Maintainers review the [`status: needs triage` queue](https://github.com/amruthpillai/reactive-resume/issues?q=is%3Aissue+is%3Aopen+label%3A%22status%3A+needs+triage%22)
 weekly. Triaged bugs become `status: confirmed`; feature proposals become `status: accepted`; reports that need details become

apps/server/package.json

@@ -18,25 +18,25 @@
 		"#react-pdf-renderer": "@react-pdf/renderer"
 	},
 	"dependencies": {
-		"@ai-sdk/anthropic": "^4.0.39",
-		"@ai-sdk/cerebras": "^3.0.31",
-		"@ai-sdk/cohere": "^4.0.27",
-		"@ai-sdk/deepseek": "^3.0.28",
-		"@ai-sdk/fireworks": "^3.0.33",
-		"@ai-sdk/google": "^4.0.44",
-		"@ai-sdk/groq": "^4.0.28",
-		"@ai-sdk/mistral": "^4.0.29",
-		"@ai-sdk/openai": "^4.0.42",
-		"@ai-sdk/openai-compatible": "^3.0.31",
-		"@ai-sdk/perplexity": "^4.0.29",
-		"@ai-sdk/togetherai": "^3.0.32",
-		"@ai-sdk/xai": "^4.0.40",
-		"@aws-sdk/client-s3": "^3.1111.0",
-		"@better-auth/api-key": "^1.6.29",
-		"@better-auth/drizzle-adapter": "^1.6.29",
-		"@better-auth/infra": "^0.3.7",
-		"@better-auth/oauth-provider": "^1.6.29",
-		"@better-auth/passkey": "^1.6.29",
+		"@ai-sdk/anthropic": "^4.0.49",
+		"@ai-sdk/cerebras": "^3.0.44",
+		"@ai-sdk/cohere": "^4.0.37",
+		"@ai-sdk/deepseek": "^3.0.39",
+		"@ai-sdk/fireworks": "^3.0.47",
+		"@ai-sdk/google": "^4.0.64",
+		"@ai-sdk/groq": "^4.0.37",
+		"@ai-sdk/mistral": "^4.0.39",
+		"@ai-sdk/openai": "^4.0.60",
+		"@ai-sdk/openai-compatible": "^3.0.44",
+		"@ai-sdk/perplexity": "^4.0.39",
+		"@ai-sdk/togetherai": "^3.0.45",
+		"@ai-sdk/xai": "^4.0.54",
+		"@aws-sdk/client-s3": "^3.1127.0",
+		"@better-auth/api-key": "^1.7.3",
+		"@better-auth/drizzle-adapter": "^1.7.3",
+		"@better-auth/infra": "^0.4.5",
+		"@better-auth/oauth-provider": "^1.7.3",
+		"@better-auth/passkey": "^1.7.3",
 		"@bramus/specificity": "^2.4.2",
 		"@hono/node-server": "^2.1.1",
 		"@modelcontextprotocol/sdk": "^1.30.0",
@@ -46,7 +46,8 @@
 		"@orpc/openapi": "^1.15.0",
 		"@orpc/server": "^1.15.0",
 		"@orpc/zod": "^1.15.0",
-		"@react-pdf/renderer": "^4.6.1",
+		"@react-pdf/hyphenate": "0.1.0",
+		"@react-pdf/renderer": "^4.9.0",
 		"@reactive-resume/api": "workspace:*",
 		"@reactive-resume/auth": "workspace:*",
 		"@reactive-resume/db": "workspace:*",
@@ -54,45 +55,48 @@
 		"@reactive-resume/mcp": "workspace:*",
 		"@reactive-resume/schema": "workspace:*",
 		"@reactive-resume/utils": "workspace:*",
-		"@sindresorhus/slugify": "^3.0.0",
+		"@sindresorhus/slugify": "^3.0.1",
 		"@t3-oss/env-core": "^0.13.11",
 		"@uiw/color-convert": "^2.10.3",
-		"ai": "^7.0.66",
+		"ai": "^7.0.93",
 		"bcrypt": "^6.0.0",
-		"better-auth": "1.6.29",
+		"better-auth": "1.7.3",
 		"cjk-regex": "^3.4.0",
 		"css-tree": "^3.2.1",
-		"deepmerge-ts": "^8.0.1",
+		"deepmerge-ts": "^8.0.2",
 		"drizzle-orm": "1.0.0-rc.4",
 		"drizzle-zod": "1.0.0-beta.14-a36c63d",
-		"es-toolkit": "^1.51.0",
+		"es-toolkit": "^1.52.0",
 		"fast-json-patch": "^3.1.1",
-		"hono": "^4.13.2",
+		"fast-png": "^8.0.0",
+		"hono": "^4.13.7",
 		"jsonrepair": "^3.15.0",
-		"node-html-parser": "^9.0.1",
-		"nodemailer": "^9.0.5",
+		"node-html-parser": "^9.0.3",
+		"nodemailer": "^10.0.0",
 		"ollama-ai-provider-v2": "^4.0.1",
 		"pg": "^8.23.0",
 		"phosphor-icons-react-pdf": "^0.1.3",
 		"react": "^19.2.8",
-		"react-email": "^6.9.2",
+		"react-email": "^6.9.3",
 		"react-pdf-html": "^2.1.5",
 		"resumable-stream": "^2.2.12",
-		"sharp": "^0.35.3",
+		"sanitize-html": "^2.17.7",
+		"sharp": "^0.35.4",
+		"tokenx": "^2.1.0",
 		"ts-pattern": "^5.9.0",
 		"unique-names-generator": "^4.7.1",
-		"uuid": "^14.0.1",
-		"zod": "^4.4.3"
+		"uuid": "^14.0.2",
+		"zod": "^4.5.4"
 	},
 	"devDependencies": {
 		"@reactive-resume/config": "workspace:*",
-		"@types/node": "^26.2.0",
-		"@types/pg": "^8.23.0",
+		"@types/node": "^26.4.1",
+		"@types/pg": "^8.23.1",
 		"@types/react": "^19.2.18",
 		"@typescript/native-preview": "7.0.0-dev.20260707.2",
-		"tsdown": "^0.22.14",
-		"tsx": "^4.23.12",
+		"tsdown": "^0.23.0",
+		"tsx": "^4.23.13",
 		"typescript": "^7.0.2",
-		"vitest": "^4.1.10"
+		"vitest": "^5.0.0"
 	}
 }

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

@@ -205,3 +205,17 @@ describe("createApp", () => {
 		expect(mocks.serveWebDistStatic).not.toHaveBeenCalled();
 	});
 });
+
+it.each(["/auth/consent", "/auth/consent/", "/auth/login"])("prevents framing or caching %s", async (path) => {
+	const { createApp } = await import("./app");
+	mocks.serveWebDistStatic.mockImplementationOnce(async (_context: unknown, next: () => Promise<void>) => {
+		await next();
+	});
+	const response = await createApp().request(`http://localhost:3000${path}?sig=signed`);
+	expect(response.status).toBe(200);
+	expect(await response.text()).toBe("web");
+	expect(response.headers.get("content-security-policy")).toBe("frame-ancestors 'none'");
+	expect(response.headers.get("x-frame-options")).toBe("DENY");
+	expect(response.headers.get("referrer-policy")).toBe("no-referrer");
+	expect(response.headers.get("cache-control")).toBe("no-store");
+});

apps/server/src/http/app.ts

@@ -36,6 +36,14 @@ const getTrustedClient = (context: Context<ServerEnvironment>): string => {
 export function createApp() {
 	const app = new Hono<ServerEnvironment>();
 
+	app.use("/auth/*", async (c, next) => {
+		await next();
+		c.header("Content-Security-Policy", "frame-ancestors 'none'");
+		c.header("X-Frame-Options", "DENY");
+		c.header("Referrer-Policy", "no-referrer");
+		c.header("Cache-Control", "no-store");
+	});
+
 	app.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)));

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

@@ -2,6 +2,8 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const mocks = vi.hoisted(() => ({
 	getSession: vi.fn(),
+	consent: vi.fn(),
+	continueOAuth: vi.fn(),
 	handler: vi.fn(),
 	env: {
 		SERVER_PORT: 3001,
@@ -14,6 +16,8 @@ vi.mock("@reactive-resume/auth/config", () => ({
 	auth: {
 		api: {
 			getSession: mocks.getSession,
+			oauth2Consent: mocks.consent,
+			oauth2Continue: mocks.continueOAuth,
 		},
 		handler: mocks.handler,
 	},
@@ -32,6 +36,23 @@ beforeEach(() => {
 });
 
 describe("handleAuth", () => {
+	it.for([null, false, 42, "client", [], [{ redirect_uris: [] }]])(
+		"rejects non-object registration payload %j",
+		async (body) => {
+			const { handleAuth } = await import("./auth");
+			const response = await handleAuth(
+				new Request("http://localhost:3000/api/auth/oauth2/register", {
+					method: "POST",
+					headers: { "content-type": "application/json" },
+					body: JSON.stringify(body),
+				}),
+			);
+			expect(response.status).toBe(400);
+			await expect(response.json()).resolves.toEqual({ message: "Invalid registration payload" });
+			expect(mocks.handler).not.toHaveBeenCalled();
+		},
+	);
+
 	it("rejects untrusted dynamic OAuth redirect URIs in safe mode", async () => {
 		const { handleAuth } = await import("./auth");
 
@@ -66,6 +87,57 @@ describe("handleAuth", () => {
 		expect(response.status).toBe(200);
 		expect(mocks.handler).toHaveBeenCalledOnce();
 	});
+	it.each(["localhost", "127.0.0.1", "[::1]"])(
+		"infers native application type for exact %s loopback callbacks",
+		async (host) => {
+			const { handleAuth } = await import("./auth");
+			await handleAuth(
+				new Request("http://localhost:3000/api/auth/oauth2/register", {
+					method: "POST",
+					headers: { "content-type": "application/json" },
+					body: JSON.stringify({ redirect_uris: [`http://${host}:3210/callback`] }),
+				}),
+			);
+			const forwarded = mocks.handler.mock.calls[0]?.[0] as Request;
+			await expect(forwarded.json()).resolves.toMatchObject({
+				application_type: "native",
+				token_endpoint_auth_method: "none",
+			});
+		},
+	);
+
+	it.each([
+		{ redirect_uris: ["https://example.com/callback"] },
+		{ redirect_uris: ["http://localhost.evil.example/callback"] },
+		{ redirect_uris: ["http://localhost:3210/callback"], application_type: "web" },
+		{ redirect_uris: ["http://localhost:3210/callback", "https://example.com/callback"] },
+	])("does not infer native for explicit web or non-loopback clients: %j", async (body) => {
+		const { handleAuth } = await import("./auth");
+		mocks.env.FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI = true;
+		await handleAuth(
+			new Request("http://localhost:3000/api/auth/oauth2/register", {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify(body),
+			}),
+		);
+		const forwarded = mocks.handler.mock.calls[0]?.[0] as Request;
+		expect((await forwarded.json()).application_type).not.toBe("native");
+	});
+
+	it("preserves repeated resource indicators during authorization sanitization", async () => {
+		const { handleAuth } = await import("./auth");
+		await handleAuth(
+			new Request(
+				"http://localhost:3000/api/auth/oauth2/authorize?resource=http%3A%2F%2Flocalhost%3A3000&resource=http%3A%2F%2Flocalhost%3A3000%2Fmcp",
+			),
+		);
+		const forwarded = mocks.handler.mock.calls[0]?.[0] as Request;
+		expect(new URL(forwarded.url).searchParams.getAll("resource")).toEqual([
+			"http://localhost:3000",
+			"http://localhost:3000/mcp",
+		]);
+	});
 });
 
 describe("handleOAuth", () => {
@@ -91,7 +163,64 @@ describe("handleOAuth", () => {
 		expect(callbackUrl.searchParams.get("client_id")).toBe("test-client");
 		expect(callbackUrl.searchParams.get("redirect_uri")).toBe("https://example.com/callback");
 		expect(callbackUrl.searchParams.get("state")).toBe("abc");
-		expect(callbackUrl.searchParams.has("exp")).toBe(false);
-		expect(callbackUrl.searchParams.has("sig")).toBe(false);
+		expect(callbackUrl.searchParams.get("exp")).toBe("123");
+		expect(callbackUrl.searchParams.get("sig")).toBe("456");
+	});
+	it("continues signed authorization without approving consent on GET", async () => {
+		const { handleOAuth } = await import("./auth");
+		mocks.getSession.mockResolvedValueOnce({ user: { id: "owner" } });
+		mocks.continueOAuth.mockResolvedValueOnce(
+			Response.json({ redirect: true, url: "/auth/consent?client_id=client&sig=signed" }),
+		);
+		const query = "client_id=client&resource=one&resource=two&exp=123&sig=456";
+		const response = await handleOAuth(new Request(`http://localhost:3000/api/auth/oauth?${query}`));
+		expect(mocks.continueOAuth).toHaveBeenCalledWith(
+			expect.objectContaining({ body: { postLogin: true, oauth_query: query } }),
+		);
+		expect(mocks.consent).not.toHaveBeenCalled();
+		expect(response.status).toBe(302);
+		expect(response.headers.get("location")).toBe("/auth/consent?client_id=client&sig=signed");
+	});
+
+	it("preserves provider failures instead of issuing an authorization code", async () => {
+		const { handleOAuth } = await import("./auth");
+		mocks.getSession.mockResolvedValueOnce({ user: { id: "owner" } });
+		mocks.continueOAuth.mockResolvedValueOnce(Response.json({ error: "invalid_signature" }, { status: 400 }));
+		const response = await handleOAuth(new Request("http://localhost:3000/api/auth/oauth?sig=invalid"));
+		expect(response.status).toBe(400);
+		expect(response.headers.get("location")).toBeNull();
+		await expect(response.json()).resolves.toEqual({ error: "invalid_signature" });
+	});
+	it("preserves provider cookies and cache headers on forced reauthentication", async () => {
+		const { handleOAuth } = await import("./auth");
+		mocks.getSession.mockResolvedValueOnce({ user: { id: "owner" } });
+		const headers = new Headers({ "cache-control": "no-store", "content-length": "123" });
+		headers.append("set-cookie", "oauth_state=state; Path=/; HttpOnly");
+		headers.append("set-cookie", "session=refreshed; Path=/; HttpOnly");
+		mocks.continueOAuth.mockResolvedValueOnce(
+			Response.json({ redirect: true, url: "/api/auth/oauth?prompt=login&sig=signed" }, { headers }),
+		);
+		const response = await handleOAuth(new Request("http://localhost:3000/api/auth/oauth?sig=original"));
+		expect(response.status).toBe(302);
+		expect(response.headers.get("location")).toMatch(/^\/auth\/login\?reauthenticate=true&/);
+		expect(response.headers.getSetCookie()).toEqual(headers.getSetCookie());
+		expect(response.headers.get("cache-control")).toBe("no-store");
+		expect(response.headers.get("content-type")).toBeNull();
+		expect(response.headers.get("content-length")).toBeNull();
 	});
 });
+
+describe("OAuth provider response validation", () => {
+	it.for([{}, { url: null }, { url: 7 }, { url: "" }, { url: "undefined" }, { url: "javascript:alert(1)" }])(
+		"fails closed for malformed provider response %j",
+		async (body) => {
+			const { handleOAuth } = await import("./auth");
+			mocks.getSession.mockResolvedValueOnce({ user: { id: "owner" } });
+			mocks.continueOAuth.mockResolvedValueOnce(Response.json(body));
+			const response = await handleOAuth(new Request("http://localhost:3000/api/auth/oauth?sig=signed"));
+			expect(response.status).toBe(502);
+			expect(response.headers.get("location")).toBeNull();
+			expect(mocks.consent).not.toHaveBeenCalled();
+		},
+	);
+});

apps/server/src/http/auth.ts

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

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

@@ -0,0 +1,96 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { execute, healthcheck } = vi.hoisted(() => ({ execute: vi.fn(), healthcheck: vi.fn() }));
+
+vi.mock("@reactive-resume/db/client", () => ({ db: { execute } }));
+vi.mock("@reactive-resume/api/features/storage", () => ({ getStorageService: () => ({ healthcheck }) }));
+vi.mock("../app-version", () => ({ appVersion: "9.8.7" }));
+
+import { handleHealth } from "./health";
+
+describe("health version reporting", () => {
+	beforeEach(() => {
+		execute.mockResolvedValue([]);
+		healthcheck.mockResolvedValue({ status: "healthy" });
+	});
+
+	afterEach(() => {
+		vi.unstubAllEnvs();
+		vi.restoreAllMocks();
+	});
+
+	it("reports the built application version when launched directly by Node", async () => {
+		vi.stubEnv("npm_package_version", undefined);
+
+		const response = await handleHealth();
+
+		expect(response.status).toBe(200);
+		expect(await response.json()).toMatchObject({ service: "reactive-resume", version: "9.8.7", status: "healthy" });
+	});
+
+	it("ignores a package manager's workspace package version", async () => {
+		vi.stubEnv("npm_package_version", "0.0.0");
+
+		expect(await (await handleHealth()).json()).toMatchObject({ version: "9.8.7" });
+	});
+
+	it("keeps the version available when a dependency is unhealthy", async () => {
+		vi.stubEnv("npm_package_version", undefined);
+		execute.mockRejectedValueOnce(new Error("Database unavailable"));
+		vi.spyOn(console, "warn").mockImplementation(() => {});
+
+		const response = await handleHealth();
+
+		expect(response.status).toBe(503);
+		expect(await response.json()).toMatchObject({ version: "9.8.7", status: "unhealthy" });
+	});
+	it.each(["database", "storage"])("keeps thrown %s error details in server logs only", async (dependency) => {
+		const detail = "Connection failed for private-user at internal.example:5432";
+		const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+		(dependency === "database" ? execute : healthcheck).mockRejectedValueOnce(new Error(detail));
+
+		const response = await handleHealth();
+		const body = await response.json();
+
+		expect(response.status).toBe(503);
+		expect(JSON.stringify(body)).not.toContain(detail);
+		expect(body[dependency]).toMatchObject({
+			status: "unhealthy",
+			error: expect.stringContaining("health check failed"),
+		});
+		expect(warn).toHaveBeenCalledWith(
+			"[Healthcheck]",
+			expect.objectContaining({
+				[dependency]: expect.objectContaining({ error: detail }),
+			}),
+		);
+	});
+
+	it("redacts returned storage failures while preserving diagnostics in server logs", async () => {
+		const detail = "Access denied to bucket private-bucket on internal.example";
+		const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+		healthcheck.mockResolvedValueOnce({
+			status: "unhealthy",
+			type: "s3",
+			message: detail,
+			error: detail,
+			internalDetail: detail,
+		});
+
+		const response = await handleHealth();
+		const body = await response.json();
+
+		expect(response.status).toBe(503);
+		expect(body.storage).toEqual({
+			status: "unhealthy",
+			type: "s3",
+			latencyMs: expect.any(Number),
+			error: "Storage health check failed.",
+		});
+		expect(JSON.stringify(body)).not.toContain(detail);
+		expect(warn).toHaveBeenCalledWith(
+			"[Healthcheck]",
+			expect.objectContaining({ storage: expect.objectContaining({ error: detail, message: detail }) }),
+		);
+	});
+});

apps/server/src/http/health.ts

@@ -2,6 +2,7 @@ import { sql } from "drizzle-orm";
 import { withTimeout } from "es-toolkit";
 import { getStorageService } from "@reactive-resume/api/features/storage";
 import { db } from "@reactive-resume/db/client";
+import { appVersion } from "../app-version";
 
 const HEALTHCHECK_TIMEOUT_MS = 1_500;
 
@@ -31,6 +32,16 @@ async function runCheck(check: () => Promise<object>): Promise<CheckResult> {
 	}
 }
 
+function publicCheck(check: CheckResult, name: "Database" | "Storage"): CheckResult {
+	if (check.status === "healthy") return check;
+	return {
+		status: check.status,
+		latencyMs: check.latencyMs,
+		error: `${name} health check failed.`,
+		...(check.type === "local" || check.type === "s3" ? { type: check.type } : {}),
+	};
+}
+
 // ponytail: inner try/catches removed; runCheck's outer catch handles all errors
 async function checkDatabase() {
 	await db.execute(sql`SELECT 1`);
@@ -45,12 +56,12 @@ export async function handleHealth() {
 
 	const checks = {
 		service: "reactive-resume",
-		version: process.env.npm_package_version,
+		version: appVersion,
 		status,
 		timestamp: new Date().toISOString(),
 		uptime: `${process.uptime().toFixed(2)}s`,
-		database,
-		storage,
+		database: publicCheck(database, "Database"),
+		storage: publicCheck(storage, "Storage"),
 	};
 
 	if (status === "unhealthy") {

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

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

apps/server/src/index.test.ts

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

apps/server/src/index.ts

@@ -1,14 +1,15 @@
 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() {
+export async function main() {
 	await runStartupChecks();
 
+	// OAuth resource seeding starts when auth is imported, so load the app only
+	// after migrations have created the provider tables.
+	const { createApp } = await import("./http/app");
+
 	// Safety net: Node 24 crashes the whole process on an unhandled rejection. One request's
 	// stray promise must not take the server down for everyone, so log and keep serving.
 	// Registered after startup checks so a broken startup still fails loudly. (Left uncaught

apps/server/src/mcp/server.ts

@@ -54,7 +54,7 @@ export function createMcpServer(request: Request) {
 				`Apply body edits with JSON Patch through \`${MCP_TOOL_NAME.patchResume}\`.`,
 				`Change name, slug, tags, or public visibility with \`${MCP_TOOL_NAME.updateResume}\` (returns canonical share URL; anonymous access only when \`isPublic\` is true; passwords are managed in the web app only).`,
 				`Create short-lived authenticated PDF download URLs with \`${MCP_TOOL_NAME.downloadResumePdf}\`; set target to \`cover-letter\` to export a visible cover letter separately.`,
-				`Import full ResumeData JSON with \`${MCP_TOOL_NAME.importResume}\`; read saved AI analysis with \`${MCP_TOOL_NAME.getResumeAnalysis}\`.`,
+				`Import full ResumeData JSON with \`${MCP_TOOL_NAME.importResume}\`.`,
 			].join(" "),
 		},
 	);

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

@@ -1,7 +1,13 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import z from "zod";
 import { defaultResumeData } from "@reactive-resume/schema/resume/default";
 import { createResumeDataJsonSchema } from "@reactive-resume/schema/resume/json-schema";
+import { writableResumeDataSchema } from "@reactive-resume/schema/resume/write";
+
+// Spec generation reads procedure contracts without executing authentication. Keep the
+// provider's resource seeding out of this unit test; real OAuth initialization is covered
+// by the opt-in PostgreSQL integration suite after migrations run.
+vi.mock("@reactive-resume/auth/config", () => ({ auth: {}, verifyOAuthToken: vi.fn() }));
 
 type GeneratedSpecView = {
 	components?: { schemas?: Record<string, unknown> };
@@ -80,6 +86,29 @@ describe("generateOpenApiSpec", () => {
 		});
 	}, 15_000);
 
+	it("documents the public health endpoint at its actual URL", async () => {
+		const spec = await generateSpec();
+		const health = spec.paths?.["/api/health"]?.get;
+
+		expect(health).toMatchObject({
+			operationId: "getHealth",
+			security: [],
+			servers: [{ url: "https://rxresu.me" }],
+		});
+		for (const status of ["200", "503"]) {
+			expect(health?.responses?.[status]).toMatchObject({
+				content: {
+					"application/json": {
+						schema: {
+							required: expect.arrayContaining(["service", "version", "status"]),
+							properties: { version: { type: "string" } },
+						},
+					},
+				},
+			});
+		}
+	});
+
 	it("uses the canonical input-side ResumeData schema in update requests", async () => {
 		const spec = (await generateSpec()) as GeneratedSpecView;
 		const { $schema: _dialect, ...canonicalInputSchema } = createResumeDataJsonSchema();
@@ -92,6 +121,16 @@ describe("generateOpenApiSpec", () => {
 		});
 	});
 
+	it("accepts legacy input with omitted picture fit in the published request schema", async () => {
+		const spec = (await generateSpec()) as GeneratedSpecView;
+
+		expect(spec.components?.schemas?.ResumeData).toMatchObject({
+			properties: {
+				picture: { required: expect.not.arrayContaining(["fit"]) },
+			},
+		});
+	});
+
 	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]);
@@ -115,6 +154,18 @@ describe("generateOpenApiSpec", () => {
 		expect(schema.safeParse(mismatched).success).toBe(false);
 	});
 
+	it("enforces the same submitted bounds as the published request schema", async () => {
+		const spec = (await generateSpec()) as GeneratedSpecView;
+		const published = z.fromJSONSchema(spec.components?.schemas?.ResumeData as Parameters<typeof z.fromJSONSchema>[0]);
+		for (const marginX of [0, 100, -1, 500]) {
+			const data = structuredClone(defaultResumeData);
+			data.metadata.page.marginX = marginX;
+			const expected = marginX === 0 || marginX === 100;
+			expect(published.safeParse(data).success).toBe(expected);
+			expect(writableResumeDataSchema.safeParse(data).success).toBe(expected);
+		}
+	});
+
 	it("does not publish impossible request schemas", async () => {
 		const spec = (await generateSpec()) as GeneratedSpecView;
 

apps/server/src/openapi/generator.ts

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

apps/server/src/startup/checks.ts

@@ -61,7 +61,18 @@ async function validateLocalStoragePath() {
 	}
 }
 
+async function reapStaleAgentRuns() {
+	try {
+		const { reapStaleAgentRunsAtBoot } = await import("@reactive-resume/api/features/agent/runs");
+		await reapStaleAgentRunsAtBoot();
+	} catch (error) {
+		// A reap failure must not block serving traffic; stuck runs also heal lazily on access.
+		console.error("Failed to reap stale agent runs at boot", { error });
+	}
+}
+
 export async function runStartupChecks() {
 	await runDatabaseMigrations();
 	await validateLocalStoragePath();
+	await reapStaleAgentRuns();
 }

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

@@ -33,6 +33,7 @@ describe("SEO static endpoints", () => {
 		expect(response.status).toBe(200);
 		expect(response.headers.get("Content-Type")).toBe("application/xml; charset=UTF-8");
 		expect(text).toContain("<loc>https://app.example.com/</loc>");
+		expect(text).toContain("<loc>https://app.example.com/ats-checker</loc>");
 		expect(text).not.toContain("docs.rxresu.me");
 		expect(text).not.toContain("/auth");
 		expect(text).not.toContain("/dashboard");

apps/server/src/static/seo.ts

@@ -42,6 +42,9 @@ export function handleSitemap(options?: StaticSeoOptions) {
 		"  <url>",
 		`    <loc>${baseUrl}/</loc>`,
 		"  </url>",
+		"  <url>",
+		`    <loc>${baseUrl}/ats-checker</loc>`,
+		"  </url>",
 		"</urlset>",
 		"",
 	].join("\n");

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

@@ -0,0 +1,110 @@
+import type { IncomingHttpHeaders } from "node:http";
+import { createServer } from "node:http";
+import { afterAll, beforeAll, beforeEach, expect, it, vi } from "vitest";
+
+const envMock = vi.hoisted(() => ({
+	APP_URL: "https://resume.example.com",
+	S3_ACCESS_KEY_ID: "test-access-key",
+	S3_SECRET_ACCESS_KEY: "test-secret-key",
+	S3_REGION: "us-east-1",
+	S3_ENDPOINT: "",
+	S3_BUCKET: "test-bucket",
+	S3_FORCE_PATH_STYLE: true,
+}));
+vi.mock("@reactive-resume/env/server", () => ({ env: envMock }));
+
+type StoredObject = { data: Buffer; contentType: string };
+type StorageRequest = { method: string; path: string; headers: IncomingHttpHeaders };
+const objects = new Map<string, StoredObject>();
+const requests: StorageRequest[] = [];
+
+// Wire-contract stub, not an AWS emulator. It applies the documented BucketOwnerEnforced
+// PUT rule to real SDK requests: no ACL or bucket-owner-full-control is accepted.
+// https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-ownership-error-responses.html
+const server = createServer(async (request, response) => {
+	const path = new URL(request.url ?? "/", "http://localhost").pathname;
+	requests.push({ method: request.method ?? "", path, headers: request.headers });
+	const fail = (status: number, code: string) => {
+		response.writeHead(status, { "Content-Type": "application/xml" });
+		response.end(`<Error><Code>${code}</Code><Message>${code}</Message></Error>`);
+	};
+	// Only checks that the SDK authenticates its requests; this stub does not verify signatures.
+	if (!request.headers.authorization?.startsWith("AWS4-HMAC-SHA256 ")) return fail(403, "AccessDenied");
+	if (request.method === "PUT") {
+		const chunks: Buffer[] = [];
+		for await (const chunk of request) chunks.push(Buffer.from(chunk));
+		const acl = request.headers["x-amz-acl"];
+		if (acl && acl !== "bucket-owner-full-control") return fail(400, "AccessControlListNotSupported");
+		objects.set(path, {
+			data: Buffer.concat(chunks),
+			contentType: request.headers["content-type"] ?? "application/octet-stream",
+		});
+		response.writeHead(200, { ETag: '"test-etag"' });
+		return response.end();
+	}
+	if (request.method === "DELETE") {
+		objects.delete(path);
+		response.writeHead(204);
+		return response.end();
+	}
+	const object = objects.get(path);
+	if (!object) return fail(404, "NoSuchKey");
+	response.writeHead(200, { "Content-Type": object.contentType, "Content-Length": object.data.length });
+	response.end(object.data);
+});
+
+let storage: ReturnType<typeof import("@reactive-resume/api/features/storage").getStorageService>;
+let handleUpload: typeof import("./uploads").handleUpload;
+
+beforeAll(async () => {
+	await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+	const address = server.address();
+	if (!address || typeof address === "string") throw new Error("Missing stub TCP address");
+	envMock.S3_ENDPOINT = `http://127.0.0.1:${address.port}`;
+	storage = (await import("@reactive-resume/api/features/storage")).getStorageService();
+	({ handleUpload } = await import("./uploads"));
+});
+
+beforeEach(() => {
+	objects.clear();
+	requests.length = 0;
+});
+
+afterAll(async () => {
+	server.closeAllConnections();
+	await new Promise<void>((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())));
+});
+
+it("keeps the ACL-disabled storage health check healthy", async () => {
+	expect(await storage.healthcheck()).toMatchObject({ status: "healthy", type: "s3" });
+	expect(requests.map(({ method }) => method)).toEqual(["PUT", "DELETE"]);
+	expect(objects.size).toBe(0);
+});
+
+it("stores images without ACLs and serves them through the signed application proxy", async () => {
+	const key = "uploads/user-1/pictures/photo.png";
+	const data = new Uint8Array([137, 80, 78, 71]);
+	await storage.write({ key, data, contentType: "image/png" });
+	expect(requests[0]?.headers["x-amz-acl"]).toBeUndefined();
+	const direct = await fetch(`${envMock.S3_ENDPOINT}/${envMock.S3_BUCKET}/${key}`);
+	expect(direct.status).toBe(403);
+	const response = await handleUpload(new Request(`${envMock.APP_URL}/api/${key}`));
+	expect(response.status).toBe(200);
+	expect(response.headers.get("Content-Type")).toBe("image/png");
+	expect(new Uint8Array(await response.arrayBuffer())).toEqual(data);
+	expect(requests.at(-1)?.headers.authorization).toMatch(/^AWS4-HMAC-SHA256 /);
+});
+
+it("stores private attachments without ACLs while keeping them outside the public proxy", async () => {
+	const key = "uploads/user-1/agent/thread-1/private.txt";
+	const data = new TextEncoder().encode("private attachment");
+	await storage.write({ key, data, contentType: "text/plain", private: true });
+	expect(requests[0]?.headers["x-amz-acl"]).toBeUndefined();
+	const requestCount = requests.length;
+	const response = await handleUpload(new Request(`${envMock.APP_URL}/api/${key}`));
+	expect(response.status).toBe(404);
+	expect(requests).toHaveLength(requestCount);
+	const direct = await fetch(`${envMock.S3_ENDPOINT}/${envMock.S3_BUCKET}/${key}`);
+	expect(direct.status).toBe(403);
+	expect((await storage.read(key))?.data).toEqual(data);
+});

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

@@ -2,7 +2,7 @@ import fs from "node:fs/promises";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const mocks = vi.hoisted(() => ({
-	env: { APP_URL: "https://rxresu.me" },
+	env: { APP_URL: "https://rxresu.me", ROOT_RESUME_ID: undefined as string | undefined },
 	serveStatic: vi.fn((_options?: unknown) => vi.fn()),
 	getPublicResumeSocialMeta: vi.fn(),
 }));
@@ -45,6 +45,7 @@ const staticOptions = mocks.serveStatic.mock.calls[0]?.[0] as StaticOptions | un
 describe("web app fallback classification", () => {
 	beforeEach(() => {
 		vi.clearAllMocks();
+		mocks.env.ROOT_RESUME_ID = undefined;
 		vi.mocked(fs.readFile).mockResolvedValue("<html>app</html>");
 		mocks.getPublicResumeSocialMeta.mockResolvedValue(null);
 	});
@@ -66,7 +67,7 @@ describe("web app fallback classification", () => {
 					<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."
+						content="Reactive Resume is a free and open-source resume builder that makes it easy to create, update, and share your resume."
 					>
 				</head>
 				<body><div id="app"></div></body>
@@ -89,6 +90,47 @@ describe("web app fallback classification", () => {
 		expect(await dashboardResponse.text()).not.toContain('rel="canonical"');
 	});
 
+	describe("the ATS checker page", () => {
+		const shell = `<html><head><title>Reactive Resume — A free and open-source resume builder</title><meta name="description" content="Marketing copy."></head><body></body></html>`;
+
+		it("serves an indexable shell rather than a 404", async () => {
+			vi.mocked(fs.readFile).mockResolvedValue(shell);
+
+			const response = await handleWebApp(new Request("https://example.com/ats-checker"));
+
+			expect(response.status).toBe(200);
+			expect(response.headers.get("Content-Type")).toBe("text/html; charset=UTF-8");
+			expect(response.headers.get("X-Robots-Tag")).toBeNull();
+		});
+
+		it("replaces the shell metadata with the checker's own", async () => {
+			vi.mocked(fs.readFile).mockResolvedValue(shell);
+
+			const html = await (await handleWebApp(new Request("https://example.com/ats-checker"))).text();
+
+			expect(html).toContain("<title>ATS Checker - Reactive Resume</title>");
+			expect(html).toContain('<link rel="canonical" href="https://rxresu.me/ats-checker">');
+			expect(html).toContain('<meta property="og:url" content="https://rxresu.me/ats-checker">');
+			expect(html).toContain('<meta property="og:image" content="https://rxresu.me/opengraph/ats-checker.png">');
+			expect(html).toContain('id="ats-checker-structured-data"');
+			expect(html).not.toContain("Marketing copy.");
+		});
+
+		it("answers HEAD without a body", async () => {
+			const response = await handleWebApp(new Request("https://example.com/ats-checker", { method: "HEAD" }));
+
+			expect(response.status).toBe(200);
+			expect(await response.text()).toBe("");
+		});
+
+		it("does not treat the checker path as a public resume owner", async () => {
+			const response = await handleWebApp(new Request("https://example.com/ats-checker/anything"));
+
+			expect(response.status).toBe(404);
+			expect(mocks.getPublicResumeSocialMeta).not.toHaveBeenCalled();
+		});
+	});
+
 	describe("public resume social cards", () => {
 		const shell = `<html><head><title>Reactive Resume — A free and open-source resume builder</title><meta name="description" content="Marketing copy."></head><body></body></html>`;
 
@@ -110,9 +152,9 @@ describe("web app fallback classification", () => {
 			expect(html).toContain('<link rel="canonical" href="https://rxresu.me/jane/resume">');
 			expect(html).toContain('<meta property="og:type" content="profile">');
 			expect(html).toContain('<meta property="og:title" content="Jane Doe — Staff Engineer">');
-			expect(html).toContain('<meta property="og:image" content="https://rxresu.me/templates/jpg/azurill.jpg">');
+			expect(html).toContain('<meta property="og:image" content="https://rxresu.me/opengraph/banner.jpg">');
 			expect(html).toContain('<meta name="twitter:card" content="summary_large_image">');
-			expect(html).toContain('<meta name="twitter:image" content="https://rxresu.me/templates/jpg/azurill.jpg">');
+			expect(html).toContain('<meta name="twitter:image" content="https://rxresu.me/opengraph/banner.jpg">');
 		});
 
 		it("escapes user-authored values so resume content cannot break out of the attribute", async () => {
@@ -248,3 +290,28 @@ describe("web app fallback classification", () => {
 		expect(await unknownResponse.text()).toBe("");
 	});
 });
+
+describe("configured root shell", () => {
+	it.each(["GET", "HEAD"])("serves no-store noindex headers for %s", async (method) => {
+		mocks.env.ROOT_RESUME_ID = "private-or-missing-id";
+		const response = await handleWebApp(new Request("https://attacker.example/", { method }));
+		expect(response.headers.get("X-Robots-Tag")).toBe("noindex, follow");
+		expect(response.headers.get("Cache-Control")).toBe("private, no-store");
+	});
+	it("uses configured canonical root without leaking ID or marketing metadata", async () => {
+		mocks.env.ROOT_RESUME_ID = "private-or-missing-id";
+		vi.mocked(fs.readFile).mockResolvedValue(
+			'<html><head><title>Marketing title</title><meta name="description" content="Marketing copy."></head><body></body></html>',
+		);
+		const html = await (
+			await handleWebApp(
+				new Request("https://attacker.example/?id=other", {
+					headers: { host: "attacker.example", "x-forwarded-host": "evil.example" },
+				}),
+			)
+		).text();
+		expect(html).toContain('<link rel="canonical" href="https://rxresu.me/" data-root-resume-shell>');
+		expect(html).toContain('<meta name="robots" content="noindex, follow" data-root-resume-shell>');
+		expect(html).not.toMatch(/private-or-missing-id|attacker|evil|Marketing|application\/ld\+json|timelapse/);
+	});
+});

apps/server/src/static/web.ts

@@ -20,6 +20,13 @@ function resolveWebDistPath() {
 const staticRoot = resolveWebDistPath();
 const indexHtmlPath = `${staticRoot}/index.html`;
 const noindexShellPrefixes = ["/auth", "/dashboard", "/builder", "/agent", "/templates"];
+/**
+ * Marketing pages the SPA owns that search engines should index.
+ *
+ * Without an entry here the fallback below returns 404 for the path in production — the dev Vite
+ * server serves the shell for anything, so this failure only ever shows up once deployed.
+ */
+const indexableAppPaths = new Set(["/ats-checker"]);
 const reservedPublicResumeSegments = new Set([
 	"api",
 	"mcp",
@@ -30,6 +37,7 @@ const reservedPublicResumeSegments = new Set([
 	"builder",
 	"agent",
 	"templates",
+	"ats-checker",
 ]);
 
 function isAssetPath(pathname: string): boolean {
@@ -62,38 +70,36 @@ const BASE_SECURITY_HEADERS = {
 const ROOT_TITLE = "Reactive Resume — A free and open-source resume builder";
 // Keep under ~120 characters so Google's mobile SERP snippet is not truncated at 3 lines.
 const ROOT_DESCRIPTION =
-	"Free, open-source resume builder. Create, update, and share a professional resume in minutes — no ads, no paywall.";
+	"Free, open-source resume builder. Create, update, and share your resume, with no ads and no paywall.";
 const ROOT_POSTER_PATH = "/videos/timelapse-v1.webp";
 const ROOT_FAQ_ITEMS = [
 	{
 		question: "Is Reactive Resume really free?",
 		answer:
-			"Yes! Reactive Resume is completely free to use, with no hidden costs, premium tiers, or subscription fees. It's open-source and will always remain free.",
+			"Yes. Reactive Resume is free to use, with no hidden costs, premium tiers, or subscription fees. It's open source, and it will stay 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.",
+			"Your data is stored securely and never shared with third parties. If you want full control over it, you can self-host Reactive Resume on your own servers.",
 	},
 	{
 		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.",
+		answer: "Yes. One click exports your resume to PDF, with your formatting and styling intact.",
 	},
 	{
 		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.",
+			"Yes. Pick your language on the settings page, or with the language switcher in the top right corner. If your language is missing, or the existing translation could be better, 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.",
+			"Reactive Resume is open source, private, and free. It shows no ads, doesn't track what you do, and doesn't lock 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!",
+		answer: "Share it with a public URL, put a password on that URL, or download the PDF and send it yourself.",
 	},
 ] as const;
 
@@ -160,6 +166,43 @@ function createRootSeoMarkup(canonicalUrl: string) {
 	`;
 }
 
+const ATS_CHECKER_TITLE = "ATS Checker - Reactive Resume";
+// Keep under ~120 characters so Google's mobile SERP snippet is not truncated at 3 lines.
+const ATS_CHECKER_DESCRIPTION =
+	"Check whether software can read your resume PDF. Runs entirely in your browser, so your file is never uploaded.";
+
+function createAtsCheckerSeoMarkup(origin: string) {
+	const canonicalUrl = `${origin}/ats-checker`;
+	const imageUrl = `${origin}/opengraph/ats-checker.png`;
+	const structuredData = {
+		"@context": "https://schema.org",
+		"@type": "WebApplication",
+		name: "ATS Checker",
+		url: canonicalUrl,
+		description: ATS_CHECKER_DESCRIPTION,
+		applicationCategory: "BusinessApplication",
+		operatingSystem: "Web",
+		isAccessibleForFree: true,
+		offers: { "@type": "Offer", price: "0", priceCurrency: "USD" },
+		isPartOf: { "@type": "WebSite", name: "Reactive Resume", url: `${origin}/` },
+	};
+
+	return `
+		<link rel="canonical" href="${canonicalUrl}">
+		<meta property="og:type" content="website">
+		<meta property="og:site_name" content="Reactive Resume">
+		<meta property="og:title" content="${ATS_CHECKER_TITLE}">
+		<meta property="og:description" content="${ATS_CHECKER_DESCRIPTION}">
+		<meta property="og:url" content="${canonicalUrl}">
+		<meta property="og:image" content="${imageUrl}">
+		<meta name="twitter:card" content="summary_large_image">
+		<meta name="twitter:title" content="${ATS_CHECKER_TITLE}">
+		<meta name="twitter:description" content="${ATS_CHECKER_DESCRIPTION}">
+		<meta name="twitter:image" content="${imageUrl}">
+		<script id="ats-checker-structured-data" type="application/ld+json">${JSON.stringify(structuredData)}</script>
+	`;
+}
+
 // Resume names, headlines, and summaries are user-authored, so they must never reach the served
 // HTML unescaped.
 const escapeAttribute = (value: string) =>
@@ -181,7 +224,7 @@ async function createPublicResumeSeoMarkup(pathname: string, origin: string) {
 	if (!meta) return null;
 
 	const canonicalUrl = `${origin}/${username}/${slug}`;
-	const imageUrl = `${origin}/templates/jpg/${meta.template}.jpg`;
+	const imageUrl = `${origin}/opengraph/banner.jpg`;
 	const pageTitle = escapeAttribute(`${meta.name} - Reactive Resume`);
 	const title = escapeAttribute(meta.title);
 	const description = escapeAttribute(meta.description);
@@ -215,7 +258,17 @@ export const serveWebDistStatic = serveStatic({
 });
 
 function getFallbackResponseHeaders(pathname: string) {
-	if (pathname === "/") return { "Content-Type": "text/html; charset=UTF-8", ...BASE_SECURITY_HEADERS };
+	if (pathname === "/" && env.ROOT_RESUME_ID?.trim()) {
+		return {
+			"Content-Type": "text/html; charset=UTF-8",
+			"X-Robots-Tag": "noindex, follow",
+			"Cache-Control": "private, no-store",
+			...BASE_SECURITY_HEADERS,
+		};
+	}
+	if (pathname === "/" || indexableAppPaths.has(pathname)) {
+		return { "Content-Type": "text/html; charset=UTF-8", ...BASE_SECURITY_HEADERS };
+	}
 	if (isNoindexShellPath(pathname) || isPublicResumePath(pathname)) {
 		return {
 			"Content-Type": "text/html; charset=UTF-8",
@@ -254,10 +307,29 @@ export async function handleWebApp(request: Request) {
 	const html = await fs.readFile(indexHtmlPath, "utf-8");
 	const canonicalUrl = new URL("/", env.APP_URL).toString();
 
+	if (pathname === "/" && env.ROOT_RESUME_ID?.trim()) {
+		// Root configuration never discloses a target in the HTML shell. The public API
+		// gates data and browser metadata; shell requests must not count extra views.
+		const shell = html
+			.replace(/<title>[^<]*<\/title>/, "<title>Reactive Resume</title>")
+			.replace(/<meta\s+name="description"[^>]*>/, '<meta name="description" content="">');
+		const markup = `<link rel="canonical" href="${escapeAttribute(canonicalUrl)}" data-root-resume-shell><meta name="robots" content="noindex, follow" data-root-resume-shell>`;
+		return new Response(shell.replace("</head>", `${markup}</head>`), { headers });
+	}
+
 	if (pathname === "/") {
 		return new Response(html.replace("</head>", `${createRootSeoMarkup(canonicalUrl)}</head>`), { headers });
 	}
 
+	if (pathname === "/ats-checker") {
+		const origin = new URL(env.APP_URL).origin;
+		const withTitle = html
+			.replace(/<title>[^<]*<\/title>/, `<title>${ATS_CHECKER_TITLE}</title>`)
+			.replace(/<meta\s+name="description"[^>]*>/, `<meta name="description" content="${ATS_CHECKER_DESCRIPTION}">`);
+
+		return new Response(withTitle.replace("</head>", `${createAtsCheckerSeoMarkup(origin)}</head>`), { headers });
+	}
+
 	if (isPublicResumePath(pathname)) {
 		const resumeSeo = await createPublicResumeSeoMarkup(pathname, new URL(env.APP_URL).origin);
 		if (resumeSeo) {

apps/server/turbo.json

@@ -2,8 +2,12 @@
 	"extends": ["//"],
 	"tags": ["app:server", "runtime:server", "role:adapter"],
 	"tasks": {
+		"test": { "env": ["OAUTH_TEST_DATABASE_URL"] },
+		"test:coverage": { "env": ["OAUTH_TEST_DATABASE_URL"] },
+		"test:agent": { "env": ["OAUTH_TEST_DATABASE_URL"] },
 		"test:ci": {
-			"cache": false
+			"cache": false,
+			"env": ["OAUTH_TEST_DATABASE_URL"]
 		}
 	}
 }

apps/server/vitest.config.ts

@@ -1,6 +1,6 @@
 import { fileURLToPath } from "node:url";
 // @boundaries-ignore root shared Vitest config
-import { createVitestProjectConfig } from "../../vitest.shared";
+import { createVitestProjectConfig } from "../../vitest.shared.mts";
 
 export default createVitestProjectConfig({
 	name: "server",