diff --git a/docs/adr/0002-structured-style-rules-for-react-pdf.md b/docs/adr/0002-structured-style-rules-for-react-pdf.md
deleted file mode 100644
index d23322736..000000000
--- a/docs/adr/0002-structured-style-rules-for-react-pdf.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# Structured Style Rules for React PDF
-
-Reactive Resume no longer renders final PDFs through browser HTML/CSS, so end-user custom CSS would create a misleading contract: React PDF accepts style objects on renderer components, not arbitrary browser selectors. Resume appearance customization is therefore modeled as structured Style Rules in resume metadata, targeting semantic section and rich-text slots that the PDF package translates into safe React PDF styles.
-
-This preserves user-controlled section styling while keeping PDF rendering portable across preview, export, public resume views, templates, and server generation. Raw CSS, raw React PDF style objects, section-item targeting, and direct PDF-preview selection are intentionally out of v1; they can be revisited only if the product needs that power enough to accept the additional validation and layout-breakage risk.
diff --git a/docs/changelog/index.mdx b/docs/changelog/index.mdx
index cb88d9587..5f2bf63a3 100644
--- a/docs/changelog/index.mdx
+++ b/docs/changelog/index.mdx
@@ -4,6 +4,43 @@ description: "Release notes for Reactive Resume covering new features, resume bu
rss: true
---
+
+## Highlights
+
+- **More AI provider choices.** The AI settings page now supports Mistral AI, Cohere, xAI Grok, Groq, DeepSeek, Together.ai, Fireworks, Cerebras, and Perplexity, with provider defaults filled in for each. Ollama is now labeled as Ollama Cloud to make the hosted integration clearer.
+- **Cleaner cover-letter exports.** Cover-letter PDF, DOCX, and Markdown downloads now export the letter without resume header chrome by default, and PDF downloads include a new toggle for adding the resume header back when needed. [8570c1c70](https://github.com/amruthpillai/reactive-resume/commit/8570c1c70)
+- **More accurate public resume statistics.** Rapid repeat views from the same client are now de-duplicated before incrementing public resume view counts. [97ab3c973](https://github.com/amruthpillai/reactive-resume/commit/97ab3c973)
+
+## AI & Integrations
+
+- Added first-class AI SDK support for Mistral AI, Cohere, xAI, Groq, DeepSeek, Together.ai, Fireworks, Cerebras, and Perplexity across saved provider settings and AI service calls.
+- Made AI provider connection tests work with OpenAI-compatible models that do not support structured output, with a clearer error when a model returns too much text during the test.
+- Published Reactive Resume MCP registry metadata so MCP clients and directories can discover the hosted remote server. [73daf22b2](https://github.com/amruthpillai/reactive-resume/commit/73daf22b2)
+
+## Resume Builder & Exports
+
+- Fixed cover-letter-only exports across PDF, DOCX, and Markdown so they no longer include resume contact details or a redundant cover-letter heading. [8570c1c70](https://github.com/amruthpillai/reactive-resume/commit/8570c1c70)
+- Added an **Include resume header** option for cover-letter PDF downloads.
+- Improved the layout page header so the **Full Width** and **Delete Page** controls fit better in narrow builder sidebars.
+- Simplified the current-template card by removing its hover live preview; template switching still opens the full template gallery.
+
+## Reliability & Self-Hosting
+
+- Added report-only CSP, frame blocking, `nosniff`, and stricter referrer headers to web app shell responses, and tightened public upload headers to rely on same-site resource policy instead of an unconditional CORS header. [9bde7d544](https://github.com/amruthpillai/reactive-resume/commit/9bde7d544)
+- Limited application bulk update and delete requests to 200 selected items per operation to avoid oversized bulk actions. [c9b3fa5c1](https://github.com/amruthpillai/reactive-resume/commit/c9b3fa5c1)
+- Resume lock and password mutations now return `NOT_FOUND` when the resume is missing instead of silently succeeding. [e47cf6e77](https://github.com/amruthpillai/reactive-resume/commit/e47cf6e77)
+- Reduced repeated work in the font picker by computing the font family options once per app process. [7e0657946](https://github.com/amruthpillai/reactive-resume/commit/7e0657946)
+- Refreshed workspace dependencies, including AI SDK provider packages, Lingui, oRPC, Hono, Tiptap, and test tooling.
+
+## Documentation & Localization
+
+- Tightened SEO titles and descriptions across the documentation site. [5270a2a9a](https://github.com/amruthpillai/reactive-resume/commit/5270a2a9a)
+- Corrected the README feature list to describe structured Style Rules instead of custom CSS. [66078609a](https://github.com/amruthpillai/reactive-resume/commit/66078609a)
+- Synced Crowdin translation catalogs and added locale strings for the new AI providers and cover-letter export option. [b87a9d828](https://github.com/amruthpillai/reactive-resume/commit/b87a9d828), [25021507a](https://github.com/amruthpillai/reactive-resume/commit/25021507a)
+
+**Full Changelog**: [v5.2.2...v5.2.3](https://github.com/amruthpillai/reactive-resume/compare/v5.2.2...v5.2.3)
+
+
## Highlights
diff --git a/docs/superpowers/handoffs/2026-05-14-monorepo-architecture-reorg.md b/docs/superpowers/handoffs/2026-05-14-monorepo-architecture-reorg.md
deleted file mode 100644
index ca2823f58..000000000
--- a/docs/superpowers/handoffs/2026-05-14-monorepo-architecture-reorg.md
+++ /dev/null
@@ -1,241 +0,0 @@
-# Monorepo Architecture Reorg Handoff
-
-This handoff is the coordination entrypoint for the Reactive Resume architecture reorganization. It intentionally references the implementation plan instead of duplicating it.
-
-## Primary Plan
-
-- Plan: `docs/superpowers/plans/2026-05-14-monorepo-architecture-reorg.md`
-- Worklog: `docs/superpowers/worklogs/2026-05-14-monorepo-architecture-reorg.md`
-- Branch at start: `feat/explore-hono-orpc-migration`
-
-## Current Operating Rules
-
-- Preserve existing unrelated local changes:
- - `apps/server/package.json`
- - `package.json`
- - `packages/api/package.json`
- - `packages/env/package.json`
- - `packages/utils/package.json`
- - `pnpm-lock.yaml`
-- Do not use `git reset --hard` or destructive checkout commands.
-- Use green internal commits if committing is requested/appropriate.
-- Use root `AGENTS.md` as the final normative architecture source of truth.
-- Do not create local package READMEs for architecture rules unless a package has unavoidable operational constraints.
-
-## Suggested Skills for Future Agents
-
-- `subagent-driven-development` for executing one task slice with review gates.
-- `executing-plans` for sequential execution from the plan.
-- `documentation-writer` for `AGENTS.md`, ADR, and public architecture docs.
-- `handoff` when pausing or delegating a task outside Codex.
-- `turborepo` when editing `turbo.json`, package tags, or task graph rules.
-- `context7-mcp` if checking current docs for library/framework behavior.
-
-## Delegation Guidance
-
-External agents should be handed exactly one task from the plan plus this handoff path. They should report:
-
-- Status: `DONE`, `DONE_WITH_CONCERNS`, `BLOCKED`, or `NEEDS_CONTEXT`
-- Files changed
-- Tests/commands run
-- Any plan deviations
-- Follow-up tasks needed
-
-## Task Ownership Status
-
-- Task 0 Coordination Artifacts: done
-- Task 1 Pure Resume Domain Package: done
-- Task 2 DOCX Package: done
-- Task 3 PDF Package Browser/Server Generation Surface: done
-- Task 4 MCP Package and Shared Tool Contracts: done
-- Task 5 API Feature Reorganization: done
-- Task 6 Server Adapter Reorganization: done
-- Task 7 Domain-First Web Reorganization: done
-- Task 8 Dialog Registry Rework: done
-- Task 9 Boundary Enforcement: done
-- Task 10 Documentation and Source of Truth: done
-- Task 11 Final Validation and Handoff: done
-
-## Architecture Decisions Already Locked
-
-- `@reactive-resume/schema` is Zod/types only.
-- `@reactive-resume/resume` owns pure resume-domain behavior.
-- `@reactive-resume/ai` owns model contracts, not DB-backed agent runtime.
-- Agent runtime remains in `packages/api/features/agent`.
-- MCP uses an in-process oRPC `RouterClient`.
-- MCP tools move to canonical unprefixed snake_case names, no old aliases.
-- `@reactive-resume/pdf` owns PDF generation helpers but not PDF.js viewer UI.
-- `apps/web` uses domain-first features and generic-only `src/components`.
-- `packages/db` remains centralized.
-
-## Latest Task 1 Result
-
-- Created `@reactive-resume/resume` with source-consumed exports:
- - `@reactive-resume/resume/patch`
- - `@reactive-resume/resume/icons`
-- Moved JSON Patch behavior/tests and social network icon mapping/tests out of `@reactive-resume/utils`.
-- Updated consumers in `packages/ai`, `packages/api`, `packages/db`, `packages/import`, and `apps/web`.
-- Removed old utils exports for `./resume/patch` and `./network-icons`.
-- Removed `fast-json-patch` from `@reactive-resume/utils` and `@reactive-resume/ai`; it now belongs to `@reactive-resume/resume`.
-- Task 2 later removed `@reactive-resume/schema` from `@reactive-resume/utils` after moving DOCX code into `@reactive-resume/docx`.
-
-## Latest Task 2 Result
-
-- Created `@reactive-resume/docx` with source-consumed root export `@reactive-resume/docx`.
-- Moved the DOCX builder, HTML conversion, link utilities, section renderers, and colocated tests from `packages/utils/src/resume/docx` to `packages/docx/src`.
-- Updated web DOCX export callers and the export-section test mock to import from `@reactive-resume/docx`.
-- Removed the old `@reactive-resume/utils/resume/docx` export and removed `docx` plus `@reactive-resume/schema` from `@reactive-resume/utils`.
-- Validation passed for `@reactive-resume/docx` tests/typecheck, `@reactive-resume/utils` typecheck, `web` typecheck, focused web export test command, and focused Biome check.
-
-## Latest Task 3 Notes
-
-- Added `@reactive-resume/pdf/browser` and `@reactive-resume/pdf/server` exports.
-- `createResumePdfBlob({ data, template, resolveSectionTitle })` delegates to `pdf().toBlob()`.
-- `createResumePdfFile({ data, filename, template, resolveSectionTitle })` delegates to `renderToBuffer()` and preserves the existing `File` response body shape.
-- Lingui locale loading stays in the web-local wrappers under `apps/web/src/features/resume/export`; those wrappers resolve section titles and pass `resolveSectionTitle` into the package helpers.
-- The PDF.js viewer/canvas components remain in web. `apps/web/src/features/resume/preview/preview.browser.tsx` now calls the web-local blob wrapper instead of importing `@react-pdf/renderer` directly.
-- The authenticated PDF export path now reaches `@reactive-resume/pdf/server` through `packages/api/src/features/resume/export.ts`; `apps/server` consumes the explicit API feature export instead of owning PDF rendering logic directly.
-- Validation passed for `@reactive-resume/pdf` tests/typecheck, `web` typecheck, `server` typecheck, focused web PDF export/viewer tests, and focused Biome check.
-
-## Latest Task 4 Notes
-
-- Created `@reactive-resume/mcp` with source-consumed exports for the compact public surface plus direct subpaths for server card, tool names, tools, prompts, and resources.
-- Moved MCP tools, prompts, resources, server-card generation, tool annotations, and colocated tests from `apps/web/src/routes/mcp/-helpers` to `packages/mcp/src`.
-- `apps/server/src/mcp/handler.ts` and `apps/server/src/openapi/metadata.ts` now import from `@reactive-resume/mcp`; server-side MCP execution still uses the injected in-process oRPC `RouterClient`.
-- Canonical MCP tool names are unprefixed snake_case. Key renames: `read_resume` replaces the old get-resume tool name, and `apply_resume_patch` replaces the old patch tool name. No `reactive_resume_*` aliases remain.
-- Added `@reactive-resume/ai/tools/resume-tool-contracts` and reused its JSON Patch operations schema from MCP while keeping MCP-specific `id` context in the MCP input schema.
-- Validation passed for `@reactive-resume/mcp` tests/typecheck, `server` typecheck, `@reactive-resume/ai` typecheck, focused Biome check, and the app-to-app import scan.
-
-## Latest Task 5 Notes
-
-- `packages/api/src` is now organized by feature/capability under `packages/api/src/features`.
-- The root router still exports the same top-level API contract from `packages/api/src/routers/index.ts`, but it imports feature routers from `features/*/router`.
-- Agent modules now live under `features/agent`, with separate procedure modules for threads, messages, attachments, and actions; run-state lives in `runs.ts`, tool construction in `tools.ts`, and the remaining shared orchestration stays in `service.ts`.
-- Resume modules now live under `features/resume`, with capability procedure modules for CRUD, tags, statistics, analysis, events, sharing, and export. Access helpers and resume update events are feature-owned.
-- The authenticated PDF download procedure moved to `packages/api/src/features/resume/export.ts` and calls `@reactive-resume/pdf/server`.
-- `@reactive-resume/api` no longer exports `./services/*` or `./helpers/*`; explicit exports now cover routers, context, flags type, resume runtime/export, and storage runtime.
-- `apps/server` imports storage and the PDF procedure from explicit API feature exports. `apps/web` API imports remain type-only.
-- Follow-up risk: `features/agent/service.ts` and `features/resume/service.ts` are still large DB-backed facades. They are feature-owned now, but further splitting should be handled as behavior-preserving follow-up work with targeted tests around run lifecycle, patch transactions, notifications, and storage cleanup.
-- Validation passed for API tests/typecheck, server typecheck, web typecheck, MCP typecheck, focused Biome, and old service/helper import/export scans.
-
-## Latest Task 6 Notes
-
-- `apps/server/src` now reads as a runtime adapter app:
- - `http`: route composition, auth/health HTTP handlers, common header/cookie helpers
- - `rpc`: oRPC fetch handler and request-locale extraction
- - `mcp`: MCP auth, per-request server setup, and streamable HTTP transport handler
- - `openapi`: OpenAPI handler plus OAuth/OpenID/MCP well-known metadata
- - `static`: upload serving, `/schema.json`, and `apps/web/dist` static/SPA fallback serving
- - `startup`: database migrations and local-storage path checks
-- `apps/server/src/index.ts` now only re-exports `createApp`, runs startup checks, computes the port, and starts the Hono server.
-- The route order and public paths from the previous `index.ts` were preserved, including `/api/rpc`, `/api/openapi`, `/api/auth/*`, `/api/health`, `/uploads/*`, `/schema.json`, `/auth/oauth`, `/mcp`, `/.well-known/*`, and the web-dist fallback.
-- Server-side API imports remain on explicit runtime exports only; no `@reactive-resume/api/services/*` or `apps/web/src` imports were introduced.
-- Validation passed for server test/typecheck during implementation. Final Task 6 validation commands should still be listed in the worklog/final response after the executing agent's last run.
-
-## Latest Task 7 Slice 1 Notes
-
-- Resume-owned web code now starts under `apps/web/src/features/resume`:
- - `builder/draft.ts` owns the builder resume draft store/hooks.
- - `preview/*` owns the builder preview shell, PDF.js canvas renderer, shared preview helpers/tests, and dashboard thumbnail PDF rendering helpers.
- - `export/pdf-document*.tsx` owns web-local PDF document/blob/file wrappers around `@reactive-resume/pdf`.
- - `public/*` owns the public resume view, public PDF.js viewer, CSS, and tests.
-- The old generic resume component folder and public-route private component folder were removed after their files moved.
-- Direct `pdfjs-dist` imports are expected only under `apps/web/src/features/resume`; do not move them into `packages/pdf`.
-- The public resume route remains responsible for loader/error/head composition, keeps `ssr: "data-only"`, and lazy-loads `@/features/resume/public/public-resume`.
-- The builder preview route keeps `ssr: false` and lazy-loads the preview page composition.
-- Remaining Task 7 work should continue moving non-resume web domains out of generic `components`/routes. Task 8 still owns dialog registry decomposition beyond import updates caused by the draft-store move.
-
-## Latest Task 7 Slice 2 Notes
-
-- App-shell code now starts under feature folders:
- - `apps/web/src/features/command-palette` owns the command palette implementation and tests.
- - `apps/web/src/features/theme` owns the theme provider, combobox, toggle button, and tests.
- - `apps/web/src/features/locale` owns the locale combobox and tests.
- - `apps/web/src/features/user` owns the user dropdown.
-- Auth route UI now lives under `apps/web/src/features/auth`; route files under `apps/web/src/routes/auth` keep redirects/search validation and compose the feature pages.
-- Settings page UI now lives under `apps/web/src/features/settings`; route files under `apps/web/src/routes/dashboard/settings` keep dashboard header composition and redirects. `job-search.tsx` remains route-only because it is already just a redirect shim.
-- The old `@/components/{command-palette,theme,locale,user}` import paths should not be reintroduced; current consumers import from `@/features/*`.
-- `apps/web/src/components` now contains remaining generic primitive/screen folders only.
-- Task 8 still owns dialog registry decomposition; this slice did not decompose dialog definitions.
-
-## Latest Task 8 Notes
-
-- `apps/web/src/dialogs/store.ts` remains the single global dialog runtime and still exports `useDialogStore` plus `DialogProps` for existing callers.
-- Dialog schemas now compose through `apps/web/src/dialogs/schemas.ts` from domain-owned schema entries in `dialogs/auth/schema.ts`, `dialogs/api-key/schema.ts`, and `dialogs/resume/schema.ts`.
-- Dialog rendering now composes through `apps/web/src/dialogs/renderers.tsx` from domain-owned renderer registries in `dialogs/auth/registry.tsx`, `dialogs/api-key/registry.tsx`, and `dialogs/resume/registry.tsx`.
-- `apps/web/src/dialogs/manager.tsx` only imports the dialog shell, `renderDialog`, and the global store; it no longer imports every dialog implementation directly.
-- No settings/auth-specific dialog tests existed beyond the shared dialog store and resume template tests.
-
-## Latest Task 9 Notes
-
-- `turbo.json` now has executable `boundaries` config:
- - Global dependencies deny `web` and `server`, preventing package-to-app and app-to-app dependency edges.
- - Root test tools are explicit `implicitDependencies`: `vitest`, `@testing-library/jest-dom`, `@testing-library/react`, and `@testing-library/user-event`.
- - Tag rules cover app, server, browser, universal, domain, and UI layers.
-- Workspace `turbo.json` files now exist for both apps and every package. Each extends root config with `extends: ["//"]` and declares tags used by the root boundaries.
-- Every workspace `vitest.config.ts` keeps its legitimate root shared config import with `// @boundaries-ignore root shared Vitest config` immediately above `import { createVitestProjectConfig } from "../../vitest.shared";`.
-- `biome.json` now enables `style.noRestrictedImports` for forbidden cross-workspace source/path imports:
- - `@reactive-resume/*/src/**`
- - `apps/**`
- - `packages/**`
-- `biome.json` also registers `tooling/grit/no-cross-workspace-src-imports.grit`, which flags import/export/dynamic import sources that reach into another workspace's `src` tree.
-- `apps/web/tsconfig.json` no longer maps `@reactive-resume/ui/*` directly to `../../packages/ui/src/*`; the web app uses `@reactive-resume/ui` package exports instead.
-- Files changed by Task 9:
- - `turbo.json`
- - `apps/*/turbo.json`
- - `packages/*/turbo.json`
- - `biome.json`
- - `tooling/grit/no-cross-workspace-src-imports.grit`
- - `apps/web/tsconfig.json`
- - `apps/server/vitest.config.ts`
- - `apps/web/vitest.config.ts`
- - `packages/*/vitest.config.ts`
- - `docs/superpowers/worklogs/2026-05-14-monorepo-architecture-reorg.md`
- - `docs/superpowers/handoffs/2026-05-14-monorepo-architecture-reorg.md`
-- Validation passed:
- - `pnpm exec turbo boundaries`
- - `pnpm exec biome check biome.json turbo.json tooling/grit/no-cross-workspace-src-imports.grit apps/web/tsconfig.json apps/server/turbo.json apps/web/turbo.json packages/*/turbo.json`
- - `pnpm --filter web typecheck`
- - `pnpm --filter @reactive-resume/api typecheck`
- - `pnpm --filter server typecheck`
-- Remaining risks:
- - The Turbo tag set is intentionally coarse and may need finer per-package rules as future browser/server package classes settle.
- - The GritQL plugin only inspects code import/export sources; keep the package export-map and tsconfig scans in the final validation list.
- - The root shared Vitest config remains an intentional boundary ignore; moving it behind a package export would be a separate test-infra cleanup.
-
-## Latest Task 10 Notes
-
-- `AGENTS.md` is now the operational source of truth for package roles, runtime tags, import rules, placement decisions, and validation commands.
-- `docs/contributing/architecture.mdx` is now a public contributor overview of the current monorepo layout instead of the removed single-`src` architecture.
-- `docs/adr/0001-workspace-boundaries.md` records the rationale for domain-first packages, explicit export maps, `turbo boundaries`, and Biome/Grit import enforcement.
-- MCP user docs already list canonical unprefixed tool names from Task 4. AI Agent tool docs already list `read_resume` and `apply_resume_patch`; no Task 10 changes were needed there.
-- Follow-up documentation audit on 2026-05-15 reconciled AGENTS and public docs with the final `apps/server` Hono adapter shape, current Node/pnpm prerequisites, Base UI wording, provider-native web research behavior, and the current env schema.
-- Docs validation available in-repo is limited:
- - Stale-text scan passed except expected `ORPCClient` diagram labels.
- - Biome ignored Markdown/MDX and reported that no files were processed for the docs paths.
- - No dedicated docs build/check script exists in `package.json`.
-
-## Latest Task 11 Notes
-
-- Final cleanup after `pnpm knip`:
- - Removed stale app dependencies from `apps/server/package.json` and `apps/web/package.json`.
- - Deleted the unused web server PDF wrapper at `apps/web/src/features/resume/export/pdf-document.server.tsx`.
- - Removed unnecessary exported markers from internal helper functions/constants.
- - Added `pdfExportRateLimit` to `packages/api/src/features/resume/export.ts`.
- - Removed unused jobs rate-limit middleware entries that no current router uses.
-- Final validation commands passed:
- - `pnpm install --lockfile-only`
- - `pnpm install`
- - `pnpm exec biome check .`
- - `pnpm exec turbo boundaries`
- - `pnpm knip`
- - `pnpm typecheck`
- - `pnpm test`
- - `pnpm build`
-- `pnpm knip` still prints a non-failing configuration hint: `src/server.ts apps/web knip.json Refine entry pattern (no matches)`.
-- Useful review anchors:
- - Architecture rules: `AGENTS.md`, `docs/contributing/architecture.mdx`, `docs/adr/0001-workspace-boundaries.md`.
- - Boundary enforcement: `turbo.json`, workspace `turbo.json` files, `biome.json`, `tooling/grit/no-cross-workspace-src-imports.grit`.
- - API feature tree: `packages/api/src/features`.
- - Server adapter tree: `apps/server/src/{http,rpc,mcp,openapi,static,startup}`.
- - Web feature tree: `apps/web/src/features`.
diff --git a/docs/superpowers/plans/2026-05-14-monolith-and-split-deployment-architecture.md b/docs/superpowers/plans/2026-05-14-monolith-and-split-deployment-architecture.md
deleted file mode 100644
index 6e9ac79dd..000000000
--- a/docs/superpowers/plans/2026-05-14-monolith-and-split-deployment-architecture.md
+++ /dev/null
@@ -1,1143 +0,0 @@
-# Monolith and Split Deployment Architecture Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-> **Status note:** This is a historical proposal, not the current architecture source of truth. Before executing any task from this plan, verify paths and route ownership against `AGENTS.md`, `docs/contributing/architecture.mdx`, and the current `apps/server/src/{http,rpc,mcp,openapi,static,startup}` tree.
-
-**Goal:** Preserve the existing one-image Docker contract for open-source self-hosters while enabling the same codebase to run as an edge/static frontend plus Node backend for hosted and VPS split deployments.
-
-**Architecture:** Reactive Resume should have one route ownership model and multiple deployment compositions. The OSS Docker image remains a monolith: one image, one port, backend routes plus static SPA fallback. Hosted/split deployments serve the built SPA statically from Cloudflare/S3/NGINX/Caddy and route only backend-owned paths to the Node server, where unknown frontend routes return `404`.
-
-**Tech Stack:** Hono, Better Auth, Vite, Turborepo, Docker, optional NGINX/Caddy/CDN routing, Zod JSON Schema generation.
-
----
-
-## Decisions Locked By This Plan
-
-- Keep the official Docker image as a complete monolith.
-- Do not make NGINX a required wrapper for the official OSS image.
-- Use Hono static serving as the Docker/self-host fallback.
-- Prefer edge/static frontend plus Node backend for hosted Reactive Resume.
-- Do not pursue Cloudflare Worker backend support in this phase.
-- Keep backend logic Node-first and platform-independent where practical, but do not contort PDF, database, storage, or auth runtime code for Worker compatibility yet.
-- Move custom OAuth bridge behavior under `/api/auth/oauth`.
-- Keep `/.well-known/*` backend-owned because OAuth/MCP metadata is runtime-owned.
-- Make `/schema.json` frontend/static-owned by generating it during build/source preparation.
-- In split backend mode, unknown non-backend routes return `404`.
-
-## Deployment Modes
-
-### Mode 1: Docker Monolith
-
-**Audience:** OSS users and current Docker image consumers.
-
-```txt
-Request -> Node/Hono server
- /api/* -> backend
- /api/auth/oauth -> custom OAuth bridge
- /mcp, /mcp/* -> backend
- /.well-known/* -> backend
- /uploads/* -> backend unless object storage owns this later
- /schema.json -> static file from apps/web/dist
- static assets -> static file from apps/web/dist
- non-file GET/HEAD -> apps/web/dist/index.html
- file-looking miss -> 404
-```
-
-### Mode 2: Split VPS
-
-**Audience:** Advanced self-hosters or the project owner's VPS migration path.
-
-```txt
-Request -> NGINX/Caddy
- static files -> apps/web/dist
- SPA fallback -> apps/web/dist/index.html
- backend routes -> proxy to Node
-
-Request -> Node/Hono backend-only app
- backend routes -> backend
- unknown routes -> 404
-```
-
-### Mode 3: Hosted Edge Frontend + Node Backend
-
-**Audience:** Cloud hosted Reactive Resume.
-
-```txt
-Request -> Cloudflare/S3/CDN
- static files -> edge object/static hosting
- SPA fallback -> edge index.html
- backend routes -> proxy/fetch to Node backend
-
-Request -> Node backend
- backend routes -> backend
- unknown routes -> 404
-```
-
----
-
-## Route Ownership Contract
-
-### Backend-Owned Routes
-
-```txt
-/api/*
-/api/auth/oauth
-/mcp
-/mcp/*
-/.well-known/*
-/uploads/*
-```
-
-`/uploads/*` remains backend-owned while local filesystem uploads are supported. If uploads move fully to S3/R2 public or signed URLs later, this can become object-storage-owned.
-
-### Frontend/Static-Owned Routes
-
-```txt
-/schema.json
-/assets/*
-/templates/*
-/favicon.ico
-/favicon.svg
-/manifest.webmanifest
-/robots.txt
-/sitemap.xml
-/fonts/*
-/icon/*
-/logo/*
-/opengraph/*
-/photos/*
-/pwa-*.png
-/sounds/*
-/videos/*
-```
-
-### Frontend SPA-Owned Routes
-
-```txt
-/auth/*
-/dashboard/*
-/builder/*
-/agent/*
-/$username/$slug
-all other non-file GET/HEAD frontend routes
-```
-
-In Docker monolith mode, Node serves the SPA fallback. In split modes, the static frontend host serves the SPA fallback and Node returns `404` for unknown non-backend routes.
-
----
-
-## File Structure
-
-- Create `packages/server`
- - Owns route ownership constants and shared Hono app composition.
- - Exposes `createBackendApp()` and `createMonolithApp()`.
-- Modify `apps/server/src/index.ts`
- - Becomes a thin Node entrypoint around `@reactive-resume/server/node`.
- - Selects monolith/backend-only mode through explicit env/config.
-- Modify `apps/server/src/handlers/*`
- - Move or re-export handlers into `packages/server` only after package boundaries are clear.
- - Keep this as a later task if direct movement is too large.
-- Modify `packages/auth/src/config.ts`
- - Change OAuth provider `loginPage` and `consentPage` to `/api/auth/oauth`.
-- Modify `apps/server/src/handlers/auth.ts`
- - Change callback preservation to `/api/auth/oauth`.
-- Create `packages/scripts/schema/generate.ts`
- - Generates both package and web-public schema artifacts.
-- Create `apps/web/public/schema.json`
- - Static schema artifact for Vite, Docker monolith, S3, and edge hosting.
-- Modify `apps/web/package.json`
- - Runs schema generation before build.
-- Modify `apps/web/vite.config.ts`
- - Remove dev proxies that become unnecessary after route/static ownership cleanup.
-- Modify `Dockerfile`
- - Preserve one-image behavior.
- - Make runtime default to monolith mode.
-- Create `docs/deployment/architecture.mdx`
- - Explains monolith vs split modes.
-- Create `docs/deployment/split-vps.mdx`
- - Shows NGINX/Caddy examples.
-- Create `docs/deployment/edge-frontend-node-backend.mdx`
- - Shows Cloudflare/S3/CDN static frontend plus Node backend.
-- Create or update `AGENTS.md`
- - Records route ownership and deployment-mode rules as normative architecture guidance.
-
----
-
-## Task 1: Document The Deployment Contract First
-
-**Files:**
-- Create: `docs/deployment/architecture.mdx`
-- Create: `docs/deployment/split-vps.mdx`
-- Create: `docs/deployment/edge-frontend-node-backend.mdx`
-- Modify: `AGENTS.md`
-
-- [ ] **Step 1: Write `docs/deployment/architecture.mdx`**
-
-Create the document with these sections:
-
-```mdx
-# Deployment Architecture
-
-Reactive Resume supports multiple deployment compositions from one codebase.
-
-## Default: Docker Monolith
-
-The official Docker image remains a complete application image. It exposes one port and serves backend routes, static assets, and SPA fallback from the same Node process.
-
-This is the compatibility contract for open-source self-hosters.
-
-## Split Frontend And Backend
-
-Split deployments serve `apps/web/dist` from a static host and route backend-owned paths to the Node server.
-
-The Node server does not serve SPA fallback in backend-only mode. Unknown non-backend routes return `404`.
-
-## Route Ownership
-
-Backend-owned:
-
-- `/api/*`
-- `/api/auth/oauth`
-- `/mcp`
-- `/mcp/*`
-- `/.well-known/*`
-- `/uploads/*`
-
-Frontend/static-owned:
-
-- `/schema.json`
-- `/assets/*`
-- `/templates/*`
-- `/favicon.ico`
-- `/favicon.svg`
-- `/manifest.webmanifest`
-- `/robots.txt`
-- `/sitemap.xml`
-- `/fonts/*`
-- `/icon/*`
-- `/logo/*`
-- `/opengraph/*`
-- `/photos/*`
-- `/pwa-*.png`
-- `/sounds/*`
-- `/videos/*`
-
-Frontend SPA-owned:
-
-- `/auth/*`
-- `/dashboard/*`
-- `/builder/*`
-- `/agent/*`
-- public resume pages
-- all other non-file frontend routes
-
-## Runtime Modes
-
-- `monolith`: backend routes plus static SPA serving.
-- `backend-only`: backend routes only; unknown routes return `404`.
-```
-
-- [ ] **Step 2: Write `docs/deployment/split-vps.mdx`**
-
-Include this minimal NGINX shape:
-
-```nginx
-server {
- listen 80;
- server_name example.com;
-
- root /srv/reactive-resume/web;
- index index.html;
-
- location ^~ /api/ {
- proxy_pass http://127.0.0.1:3000;
- proxy_set_header Host $host;
- proxy_set_header X-Forwarded-Proto $scheme;
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
- }
-
- location = /mcp {
- proxy_pass http://127.0.0.1:3000;
- proxy_set_header Host $host;
- proxy_set_header X-Forwarded-Proto $scheme;
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
- }
-
- location ^~ /mcp/ {
- proxy_pass http://127.0.0.1:3000;
- proxy_set_header Host $host;
- proxy_set_header X-Forwarded-Proto $scheme;
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
- }
-
- location ^~ /.well-known/ {
- proxy_pass http://127.0.0.1:3000;
- proxy_set_header Host $host;
- proxy_set_header X-Forwarded-Proto $scheme;
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
- }
-
- location ^~ /uploads/ {
- proxy_pass http://127.0.0.1:3000;
- proxy_set_header Host $host;
- proxy_set_header X-Forwarded-Proto $scheme;
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
- }
-
- location / {
- try_files $uri $uri/ /index.html;
- }
-}
-```
-
-Add a note that `APP_URL` must be the public origin.
-
-- [ ] **Step 3: Write `docs/deployment/edge-frontend-node-backend.mdx`**
-
-Include:
-
-```mdx
-# Edge Frontend With Node Backend
-
-Build `apps/web/dist` and upload it to the static host. Route backend-owned paths to the Node backend.
-
-Backend route patterns:
-
-- `/api/*`
-- `/mcp`
-- `/mcp/*`
-- `/.well-known/*`
-- `/uploads/*`
-
-The frontend host owns `/schema.json` and SPA fallback.
-
-The Node backend should run in backend-only mode so unknown frontend routes return `404`.
-```
-
-- [ ] **Step 4: Update `AGENTS.md`**
-
-Add a short normative section:
-
-```md
-### Deployment route ownership
-
-The official Docker image is a monolith and must keep serving the full application from one image and one port.
-
-Split deployments are supported by serving `apps/web/dist` statically and routing backend-owned paths to Node. In backend-only mode, Node returns `404` for unknown frontend routes.
-
-Do not add new backend routes outside `/api/*`, `/mcp`, `/.well-known/*`, or explicitly documented exceptions without updating the route ownership docs.
-```
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add docs/deployment/architecture.mdx docs/deployment/split-vps.mdx docs/deployment/edge-frontend-node-backend.mdx AGENTS.md
-git commit -m "docs: define monolith and split deployment contract"
-```
-
----
-
-## Task 2: Create Route Ownership Primitives
-
-**Files:**
-- Create: `packages/server/package.json`
-- Create: `packages/server/tsconfig.json`
-- Create: `packages/server/vitest.config.ts`
-- Create: `packages/server/src/routes/ownership.ts`
-- Create: `packages/server/src/routes/ownership.test.ts`
-
-- [ ] **Step 1: Write the failing ownership tests**
-
-Create `packages/server/src/routes/ownership.test.ts`:
-
-```ts
-import { describe, expect, it } from "vitest";
-import { getRouteOwner } from "./ownership";
-
-describe("getRouteOwner", () => {
- it.each([
- ["/api/rpc", "backend"],
- ["/api/auth/oauth", "backend"],
- ["/mcp", "backend"],
- ["/mcp/tools", "backend"],
- ["/.well-known/oauth-protected-resource", "backend"],
- ["/uploads/avatar.png", "backend"],
- ["/schema.json", "static"],
- ["/assets/app.js", "static"],
- ["/templates/jpg/azurill.jpg", "static"],
- ["/auth/login", "spa"],
- ["/dashboard", "spa"],
- ["/builder/abc", "spa"],
- ["/agent/thread", "spa"],
- ["/amruth/resume", "spa"],
- ])("classifies %s as %s", (pathname, owner) => {
- expect(getRouteOwner(pathname)).toBe(owner);
- });
-
- it.each(["/missing.js", "/unknown.css", "/image.png"])("classifies file-looking misses as static", (pathname) => {
- expect(getRouteOwner(pathname)).toBe("static");
- });
-});
-```
-
-- [ ] **Step 2: Add package scaffolding**
-
-Create `packages/server/package.json`:
-
-```json
-{
- "name": "@reactive-resume/server",
- "version": "0.0.0",
- "type": "module",
- "private": true,
- "exports": {
- "./routes/ownership": "./src/routes/ownership.ts"
- },
- "scripts": {
- "typecheck": "tsgo --noEmit",
- "test": "vitest run --passWithNoTests"
- },
- "devDependencies": {
- "@reactive-resume/config": "workspace:*",
- "@typescript/native-preview": "7.0.0-dev.20260514.1",
- "typescript": "^6.0.3"
- }
-}
-```
-
-Create `packages/server/tsconfig.json`:
-
-```json
-{
- "extends": "@reactive-resume/config/tsconfig.base.json"
-}
-```
-
-Create `packages/server/vitest.config.ts`:
-
-```ts
-import { createVitestProjectConfig } from "@reactive-resume/config/vitest";
-
-export default createVitestProjectConfig({
- name: "@reactive-resume/server",
-});
-```
-
-- [ ] **Step 3: Run the failing tests**
-
-```bash
-pnpm --filter @reactive-resume/server test -- src/routes/ownership.test.ts
-```
-
-Expected: fails because `ownership.ts` does not exist.
-
-- [ ] **Step 4: Implement route ownership**
-
-Create `packages/server/src/routes/ownership.ts`:
-
-```ts
-export type RouteOwner = "backend" | "static" | "spa";
-
-const backendExactRoutes = new Set(["/mcp"]);
-const backendPrefixes = ["/api/", "/mcp/", "/.well-known/", "/uploads/"];
-const staticExactRoutes = new Set([
- "/schema.json",
- "/favicon.ico",
- "/favicon.svg",
- "/manifest.webmanifest",
- "/robots.txt",
- "/sitemap.xml",
-]);
-const staticPrefixes = [
- "/assets/",
- "/templates/",
- "/fonts/",
- "/icon/",
- "/logo/",
- "/opengraph/",
- "/photos/",
- "/sounds/",
- "/videos/",
-];
-
-function looksLikeFile(pathname: string) {
- const lastSegment = pathname.split("/").pop() ?? "";
- return lastSegment.includes(".");
-}
-
-export function getRouteOwner(pathname: string): RouteOwner {
- if (backendExactRoutes.has(pathname)) return "backend";
- if (backendPrefixes.some((prefix) => pathname.startsWith(prefix))) return "backend";
- if (staticExactRoutes.has(pathname)) return "static";
- if (staticPrefixes.some((prefix) => pathname.startsWith(prefix))) return "static";
- if (/^\/pwa-\d+x\d+\.png$/.test(pathname)) return "static";
- if (looksLikeFile(pathname)) return "static";
- return "spa";
-}
-
-export function isBackendRoute(pathname: string) {
- return getRouteOwner(pathname) === "backend";
-}
-
-export function isStaticRoute(pathname: string) {
- return getRouteOwner(pathname) === "static";
-}
-```
-
-- [ ] **Step 5: Verify route ownership tests**
-
-```bash
-pnpm --filter @reactive-resume/server test -- src/routes/ownership.test.ts
-pnpm --filter @reactive-resume/server typecheck
-```
-
-Expected: both pass.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add packages/server
-git commit -m "feat(server): add route ownership contract"
-```
-
----
-
-## Task 3: Move Custom OAuth Bridge To `/api/auth/oauth`
-
-**Files:**
-- Modify: `apps/server/src/handlers/auth.test.ts`
-- Create: `apps/server/src/index.test.ts`
-- Modify: `apps/server/src/index.ts`
-- Modify: `apps/server/src/handlers/auth.ts`
-- Modify: `packages/auth/src/config.ts`
-- Modify: `apps/web/vite.config.ts`
-
-- [ ] **Step 1: Update the handler test first**
-
-In `apps/server/src/handlers/auth.test.ts`, change the request URL and expected callback path:
-
-```ts
-const response = await handleOAuth(
- new Request(
- "http://localhost:3001/api/auth/oauth?client_id=test-client&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&state=abc&exp=123&sig=456",
- ),
-);
-
-expect(callbackUrl.pathname).toBe("/api/auth/oauth");
-```
-
-- [ ] **Step 2: Add a route precedence test**
-
-Create `apps/server/src/index.test.ts`:
-
-```ts
-import { beforeEach, describe, expect, it, vi } from "vitest";
-
-const mocks = vi.hoisted(() => ({
- handleAuth: vi.fn(),
- handleOAuth: vi.fn(),
-}));
-
-vi.mock("./handlers/auth", () => ({
- handleAuth: mocks.handleAuth,
- handleOAuth: mocks.handleOAuth,
-}));
-
-vi.mock("./handlers/health", () => ({ handleHealth: () => Response.json({ ok: true }) }));
-vi.mock("./handlers/mcp", () => ({ handleMcp: () => new Response("mcp") }));
-vi.mock("./handlers/metadata", () => ({
- handleMcpServerCard: () => Response.json({}),
- handleOAuthAuthorizationServer: () => Response.json({}),
- handleOAuthProtectedResource: () => Response.json({}),
- handleOpenIdConfiguration: () => Response.json({}),
- handleWellKnownFallback: () => new Response("OK"),
-}));
-vi.mock("./handlers/openapi", () => ({ handleOpenApi: () => Response.json({}) }));
-vi.mock("./handlers/rpc", () => ({ handleRpc: () => Response.json({}) }));
-vi.mock("./handlers/uploads", () => ({ handleUpload: () => new Response("upload") }));
-
-describe("createApp route ownership", () => {
- beforeEach(() => {
- mocks.handleAuth.mockReset();
- mocks.handleOAuth.mockReset();
- mocks.handleAuth.mockResolvedValue(Response.json({ route: "auth" }));
- mocks.handleOAuth.mockResolvedValue(Response.json({ route: "oauth" }));
- });
-
- it("routes /api/auth/oauth to the custom OAuth bridge before the Better Auth catch-all", async () => {
- const { createApp } = await import("./index");
- const response = await createApp().request("http://localhost:3001/api/auth/oauth?client_id=test");
-
- await expect(response.json()).resolves.toEqual({ route: "oauth" });
- expect(mocks.handleOAuth).toHaveBeenCalledTimes(1);
- expect(mocks.handleAuth).not.toHaveBeenCalled();
- });
-
- it("keeps other /api/auth/* requests on the Better Auth handler", async () => {
- const { createApp } = await import("./index");
- const response = await createApp().request("http://localhost:3001/api/auth/session");
-
- await expect(response.json()).resolves.toEqual({ route: "auth" });
- expect(mocks.handleAuth).toHaveBeenCalledTimes(1);
- expect(mocks.handleOAuth).not.toHaveBeenCalled();
- });
-});
-```
-
-- [ ] **Step 3: Run failing tests**
-
-```bash
-pnpm --filter server test -- src/handlers/auth.test.ts src/index.test.ts
-```
-
-Expected: tests fail because the implementation still uses `/auth/oauth`.
-
-- [ ] **Step 4: Update server route order**
-
-In `apps/server/src/index.ts`, register the custom route before Better Auth catch-all:
-
-```ts
-app.get("/api/auth/oauth", (c) => handleOAuth(c.req.raw));
-app.on(["GET", "POST"], "/api/auth/*", (c) => handleAuth(c.req.raw));
-```
-
-Remove:
-
-```ts
-app.get("/auth/oauth", (c) => handleOAuth(c.req.raw));
-```
-
-- [ ] **Step 5: Update callback preservation**
-
-In `apps/server/src/handlers/auth.ts`, change:
-
-```ts
-loginUrl.searchParams.set("callbackURL", `/auth/oauth?${oauthParams.toString()}`);
-```
-
-to:
-
-```ts
-loginUrl.searchParams.set("callbackURL", `/api/auth/oauth?${oauthParams.toString()}`);
-```
-
-- [ ] **Step 6: Update Better Auth OAuth provider pages**
-
-In `packages/auth/src/config.ts`, change:
-
-```ts
-oauthProvider({
- loginPage: "/api/auth/oauth",
- consentPage: "/api/auth/oauth",
-```
-
-- [ ] **Step 7: Remove old dev proxy**
-
-In `apps/web/vite.config.ts`, remove the `"/auth/oauth"` proxy entry. `/api/auth/oauth` is covered by the existing `"/api"` proxy.
-
-- [ ] **Step 8: Verify and commit**
-
-```bash
-pnpm --filter server test -- src/handlers/auth.test.ts src/index.test.ts
-pnpm --filter server typecheck
-pnpm --filter @reactive-resume/auth typecheck
-```
-
-Expected: all pass.
-
-```bash
-git add apps/server/src/handlers/auth.test.ts apps/server/src/index.test.ts apps/server/src/index.ts apps/server/src/handlers/auth.ts packages/auth/src/config.ts apps/web/vite.config.ts
-git commit -m "fix(auth): move OAuth bridge under api auth routes"
-```
-
----
-
-## Task 4: Make `/schema.json` Static
-
-**Files:**
-- Create: `packages/scripts/schema/generate.ts`
-- Create: `packages/scripts/schema/generate.test.ts`
-- Modify: `packages/scripts/package.json`
-- Modify: `apps/web/package.json`
-- Create: `apps/web/public/schema.json`
-- Modify: `apps/web/vite.config.ts`
-- Modify: `apps/server/src/index.ts`
-- Modify: `apps/server/src/handlers/metadata.ts`
-
-- [ ] **Step 1: Write generator test first**
-
-Create `packages/scripts/schema/generate.test.ts`:
-
-```ts
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { describe, expect, it } from "vitest";
-import { generateResumeSchemaJson } from "./generate";
-
-describe("generateResumeSchemaJson", () => {
- it("writes identical resume JSON Schema to every target", async () => {
- const directory = await fs.mkdtemp(path.join(os.tmpdir(), "resume-schema-"));
- const firstTarget = path.join(directory, "schema-a.json");
- const secondTarget = path.join(directory, "nested", "schema-b.json");
-
- await generateResumeSchemaJson([firstTarget, secondTarget]);
-
- const first = await fs.readFile(firstTarget, "utf-8");
- const second = await fs.readFile(secondTarget, "utf-8");
-
- expect(JSON.parse(first)).toEqual(JSON.parse(second));
- expect(JSON.parse(first)).toHaveProperty("properties.basics");
- expect(first.endsWith("\n")).toBe(true);
- });
-});
-```
-
-- [ ] **Step 2: Add script package entries**
-
-In `packages/scripts/package.json`, add:
-
-```json
-"schema:generate": "tsx schema/generate.ts",
-"test": "vitest run --passWithNoTests"
-```
-
-Add missing dev dependencies:
-
-```json
-"@reactive-resume/schema": "workspace:*",
-"vitest": "^4.1.6",
-"zod": "^4.4.3"
-```
-
-- [ ] **Step 3: Run failing generator test**
-
-```bash
-pnpm --filter @reactive-resume/scripts test -- schema/generate.test.ts
-```
-
-Expected: fails because `generate.ts` does not exist.
-
-- [ ] **Step 4: Implement generator**
-
-Create `packages/scripts/schema/generate.ts`:
-
-```ts
-import fs from "node:fs/promises";
-import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import z from "zod";
-import { resumeDataSchema } from "@reactive-resume/schema/resume/data";
-
-const defaultTargets = [
- new URL("../../schema/schema.json", import.meta.url),
- new URL("../../../apps/web/public/schema.json", import.meta.url),
-];
-
-function toPath(target: string | URL) {
- return target instanceof URL ? fileURLToPath(target) : target;
-}
-
-export async function generateResumeSchemaJson(targets: Array = defaultTargets) {
- const schema = z.toJSONSchema(resumeDataSchema);
- const contents = `${JSON.stringify(schema, null, "\t")}\n`;
-
- await Promise.all(
- targets.map(async (target) => {
- const targetPath = toPath(target);
- await fs.mkdir(path.dirname(targetPath), { recursive: true });
- await fs.writeFile(targetPath, contents);
- }),
- );
-}
-
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
- await generateResumeSchemaJson();
-}
-```
-
-- [ ] **Step 5: Wire generation into web build**
-
-In `apps/web/package.json`, add:
-
-```json
-"prebuild": "pnpm --filter @reactive-resume/scripts schema:generate"
-```
-
-Keep:
-
-```json
-"build": "rm -rf dist && vite build"
-```
-
-- [ ] **Step 6: Remove backend runtime schema route**
-
-In `apps/server/src/index.ts`, remove the `handleSchemaJson` import and:
-
-```ts
-app.get("/schema.json", () => handleSchemaJson());
-```
-
-In `apps/server/src/handlers/metadata.ts`, remove:
-
-```ts
-import z from "zod";
-import { resumeDataSchema } from "@reactive-resume/schema/resume/data";
-```
-
-and delete `handleSchemaJson()`.
-
-- [ ] **Step 7: Remove web dev proxy for schema**
-
-In `apps/web/vite.config.ts`, remove the `"/schema.json"` proxy entry.
-
-- [ ] **Step 8: Generate and verify**
-
-```bash
-pnpm --filter @reactive-resume/scripts schema:generate
-pnpm --filter @reactive-resume/scripts test -- schema/generate.test.ts
-pnpm --filter @reactive-resume/scripts typecheck
-pnpm --filter server typecheck
-pnpm --filter web build
-test -f apps/web/dist/schema.json
-cmp packages/schema/schema.json apps/web/public/schema.json
-```
-
-Expected: all commands pass.
-
-- [ ] **Step 9: Commit**
-
-```bash
-git add packages/scripts/schema packages/scripts/package.json apps/web/package.json apps/web/public/schema.json apps/web/vite.config.ts apps/server/src/index.ts apps/server/src/handlers/metadata.ts packages/schema/schema.json
-git commit -m "feat(web): serve resume schema as static asset"
-```
-
----
-
-## Task 5: Split Server App Composition Into Backend-Only And Monolith
-
-**Files:**
-- Create: `apps/server/src/app.ts`
-- Create: `apps/server/src/app.test.ts`
-- Modify: `apps/server/src/index.ts`
-- Modify: `apps/server/package.json`
-
-- [ ] **Step 1: Add tests for deployment mode behavior**
-
-Create `apps/server/src/app.test.ts`:
-
-```ts
-import { describe, expect, it, vi } from "vitest";
-
-vi.mock("./handlers/auth", () => ({
- handleAuth: () => Response.json({ route: "auth" }),
- handleOAuth: () => Response.json({ route: "oauth" }),
-}));
-vi.mock("./handlers/health", () => ({ handleHealth: () => Response.json({ ok: true }) }));
-vi.mock("./handlers/mcp", () => ({ handleMcp: () => new Response("mcp") }));
-vi.mock("./handlers/metadata", () => ({
- handleMcpServerCard: () => Response.json({}),
- handleOAuthAuthorizationServer: () => Response.json({}),
- handleOAuthProtectedResource: () => Response.json({}),
- handleOpenIdConfiguration: () => Response.json({}),
- handleWellKnownFallback: () => new Response("OK"),
-}));
-vi.mock("./handlers/openapi", () => ({ handleOpenApi: () => Response.json({}) }));
-vi.mock("./handlers/rpc", () => ({ handleRpc: () => Response.json({}) }));
-vi.mock("./handlers/uploads", () => ({ handleUpload: () => new Response("upload") }));
-
-describe("server app deployment modes", () => {
- it("returns 404 for frontend routes in backend-only mode", async () => {
- const { createBackendApp } = await import("./app");
- const response = await createBackendApp().request("http://localhost:3001/dashboard");
-
- expect(response.status).toBe(404);
- });
-
- it("keeps backend routes available in backend-only mode", async () => {
- const { createBackendApp } = await import("./app");
- const response = await createBackendApp().request("http://localhost:3001/api/auth/oauth");
-
- expect(response.status).toBe(200);
- await expect(response.json()).resolves.toEqual({ route: "oauth" });
- });
-});
-```
-
-- [ ] **Step 2: Run failing tests**
-
-```bash
-pnpm --filter server test -- src/app.test.ts
-```
-
-Expected: fails because `app.ts` does not exist.
-
-- [ ] **Step 3: Extract backend app composition**
-
-Create `apps/server/src/app.ts`:
-
-```ts
-import fs from "node:fs/promises";
-import { fileURLToPath } from "node:url";
-import { serveStatic } from "@hono/node-server/serve-static";
-import { Hono } from "hono";
-import { handleAuth, handleOAuth } from "./handlers/auth";
-import { handleHealth } from "./handlers/health";
-import { handleMcp } from "./handlers/mcp";
-import {
- handleMcpServerCard,
- handleOAuthAuthorizationServer,
- handleOAuthProtectedResource,
- handleOpenIdConfiguration,
- handleWellKnownFallback,
-} from "./handlers/metadata";
-import { handleOpenApi } from "./handlers/openapi";
-import { handleRpc } from "./handlers/rpc";
-import { handleUpload } from "./handlers/uploads";
-
-const staticRoot = fileURLToPath(new URL("../../web/dist", import.meta.url));
-const indexHtmlPath = fileURLToPath(new URL("../../web/dist/index.html", import.meta.url));
-
-function registerBackendRoutes(app: Hono) {
- app.all("/api/rpc", (c) => handleRpc(c.req.raw));
- app.all("/api/rpc/*", (c) => handleRpc(c.req.raw));
- app.all("/api/openapi", (c) => handleOpenApi(c.req.raw));
- app.all("/api/openapi/*", (c) => handleOpenApi(c.req.raw));
- app.get("/api/auth/oauth", (c) => handleOAuth(c.req.raw));
- app.on(["GET", "POST"], "/api/auth/*", (c) => handleAuth(c.req.raw));
- app.get("/api/health", () => handleHealth());
- app.get("/api/uploads/*", (c) => handleUpload(c.req.raw));
- app.get("/uploads/*", (c) => handleUpload(c.req.raw));
- app.all("/mcp", (c) => handleMcp(c.req.raw));
- app.all("/mcp/*", (c) => handleMcp(c.req.raw));
- app.get("/.well-known/mcp/server-card.json", () => handleMcpServerCard());
- app.get("/.well-known/oauth-authorization-server", (c) => handleOAuthAuthorizationServer(c.req.raw));
- app.get("/.well-known/oauth-authorization-server/*", (c) => handleOAuthAuthorizationServer(c.req.raw));
- app.get("/.well-known/openid-configuration", (c) => handleOpenIdConfiguration(c.req.raw));
- app.get("/.well-known/oauth-protected-resource", () => handleOAuthProtectedResource());
- app.get("/.well-known/oauth-protected-resource/*", () => handleOAuthProtectedResource());
- app.get("/.well-known/*", () => handleWellKnownFallback());
- app.on(["HEAD"], "/.well-known/*", () => handleWellKnownFallback());
-}
-
-export function createBackendApp() {
- const app = new Hono();
- registerBackendRoutes(app);
- app.all("/*", () => new Response("Not Found", { status: 404 }));
- return app;
-}
-
-export function createMonolithApp() {
- const app = new Hono();
- registerBackendRoutes(app);
-
- app.use("/*", serveStatic({ root: staticRoot, precompressed: true }));
- app.get("/*", async (c) => {
- const pathname = new URL(c.req.url).pathname;
- if (pathname.split("/").pop()?.includes(".")) return c.text("Not Found", 404);
-
- const html = await fs.readFile(indexHtmlPath, "utf-8");
- return c.html(html);
- });
- app.on(["HEAD"], "/*", async (c) => {
- const pathname = new URL(c.req.url).pathname;
- if (pathname.split("/").pop()?.includes(".")) return c.body(null, 404);
-
- return c.body(null, 200, { "Content-Type": "text/html; charset=UTF-8" });
- });
-
- return app;
-}
-```
-
-- [ ] **Step 4: Make index choose mode**
-
-In `apps/server/src/index.ts`, replace inline app creation with:
-
-```ts
-import { pathToFileURL } from "node:url";
-import { serve } from "@hono/node-server";
-import { env } from "@reactive-resume/env/server";
-import { createBackendApp, createMonolithApp } from "./app";
-import { runStartupChecks } from "./lib/startup";
-
-export function createApp() {
- return process.env.SERVER_MODE === "backend-only" ? createBackendApp() : createMonolithApp();
-}
-
-async function main() {
- await runStartupChecks();
-
- const port =
- process.env.NODE_ENV === "production" ? Number.parseInt(process.env.PORT ?? "3000", 10) : env.SERVER_PORT;
- const app = createApp();
-
- serve(
- {
- fetch: app.fetch,
- port,
- },
- (info) => {
- console.info(`🚀 Up and running on http://localhost:${info.port}`);
- },
- );
-}
-
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
- await main();
-}
-```
-
-- [ ] **Step 5: Verify**
-
-```bash
-pnpm --filter server test -- src/app.test.ts src/index.test.ts
-pnpm --filter server typecheck
-```
-
-Expected: pass.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add apps/server/src/app.ts apps/server/src/app.test.ts apps/server/src/index.ts apps/server/package.json
-git commit -m "feat(server): split backend and monolith app modes"
-```
-
----
-
-## Task 6: Preserve Docker Monolith Contract
-
-**Files:**
-- Modify: `Dockerfile`
-- Modify: `compose.yml`
-- Modify: `compose.dev.yml` only if needed
-- Modify: `docs/deployment/architecture.mdx`
-
-- [ ] **Step 1: Make Docker default explicit**
-
-In `Dockerfile`, add:
-
-```dockerfile
-ENV NODE_ENV="production" \
- SERVER_MODE="monolith" \
- PORT=3000 \
- LOCAL_STORAGE_PATH=/app/data
-```
-
-- [ ] **Step 2: Document backend-only override**
-
-In `docs/deployment/architecture.mdx`, add:
-
-```mdx
-## Server Mode
-
-`SERVER_MODE=monolith` is the default Docker mode.
-
-`SERVER_MODE=backend-only` disables static serving and SPA fallback. Use this behind an external static host or edge frontend.
-```
-
-- [ ] **Step 3: Verify Docker build path at least compiles**
-
-Run:
-
-```bash
-pnpm build
-```
-
-Expected: build passes. If full repo build is too noisy due unrelated dirty work, run:
-
-```bash
-pnpm --filter web build
-pnpm --filter server build
-```
-
-Expected: both pass.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add Dockerfile docs/deployment/architecture.mdx
-git commit -m "chore(docker): keep monolith server mode as default"
-```
-
----
-
-## Task 7: Final Verification And Stale Reference Search
-
-**Files:** no new files.
-
-- [ ] **Step 1: Run focused tests**
-
-```bash
-pnpm --filter @reactive-resume/server test
-pnpm --filter server test -- src/handlers/auth.test.ts src/index.test.ts src/app.test.ts
-pnpm --filter @reactive-resume/scripts test -- schema/generate.test.ts
-```
-
-Expected: all pass.
-
-- [ ] **Step 2: Run focused typechecks**
-
-```bash
-pnpm --filter @reactive-resume/server typecheck
-pnpm --filter server typecheck
-pnpm --filter @reactive-resume/scripts typecheck
-pnpm --filter @reactive-resume/auth typecheck
-pnpm --filter web typecheck
-```
-
-Expected: all pass.
-
-- [ ] **Step 3: Verify static schema build**
-
-```bash
-pnpm --filter @reactive-resume/scripts schema:generate
-pnpm --filter web build
-test -f apps/web/dist/schema.json
-cmp packages/schema/schema.json apps/web/public/schema.json
-```
-
-Expected: all pass.
-
-- [ ] **Step 4: Search stale route references**
-
-```bash
-rg '"/auth/oauth"|/auth/oauth|handleSchemaJson|app\\.get\\("/schema\\.json"|SERVER_MODE|backend-only|monolith' apps packages docs Dockerfile AGENTS.md
-```
-
-Expected:
-- No runtime `/auth/oauth` references remain.
-- No `handleSchemaJson` references remain.
-- `SERVER_MODE`, `backend-only`, and `monolith` appear only in app composition, Docker, and docs.
-
-- [ ] **Step 5: Run non-mutating formatting/lint check on touched files**
-
-Use the repo's Biome config without writing:
-
-```bash
-pnpm exec biome check apps/server/src apps/web/vite.config.ts packages/auth/src/config.ts packages/scripts packages/server docs/deployment AGENTS.md Dockerfile
-```
-
-Expected: no errors. If formatting errors appear, run Biome write only on touched source/doc files, then rerun this non-mutating check.
-
----
-
-## Self-Review
-
-- Spec coverage:
- - Preserve single Docker image: Tasks 1 and 6.
- - Enable edge/S3/static frontend plus Node backend: Tasks 1, 2, 5, and 6.
- - Keep backend Node-first: Tasks 5 and 6.
- - Return 404 from backend for unknown split-mode routes: Task 5.
- - Move `/auth/oauth` to `/api/auth/oauth`: Task 3.
- - Make `/schema.json` static: Task 4.
- - Keep `/.well-known/*` backend-owned: Tasks 1 and 5.
-- Placeholder scan:
- - No TBD/TODO/fill-in steps remain.
-- Type consistency:
- - Route ownership terms are consistently `backend`, `static`, and `spa`.
- - Server modes are consistently `monolith` and `backend-only`.
- - The OAuth bridge route is consistently `/api/auth/oauth`.
- - Static schema targets are consistently `packages/schema/schema.json` and `apps/web/public/schema.json`.
diff --git a/docs/superpowers/plans/2026-05-14-monorepo-architecture-reorg.md b/docs/superpowers/plans/2026-05-14-monorepo-architecture-reorg.md
deleted file mode 100644
index db1fef39d..000000000
--- a/docs/superpowers/plans/2026-05-14-monorepo-architecture-reorg.md
+++ /dev/null
@@ -1,277 +0,0 @@
-# Monorepo Architecture Reorganization Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use `subagent-driven-development` or `executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-> **Status note:** This implementation plan has been executed and may contain historical intermediate paths. Use `AGENTS.md`, `docs/contributing/architecture.mdx`, `docs/adr/0001-workspace-boundaries.md`, and `docs/superpowers/handoffs/2026-05-14-monorepo-architecture-reorg.md` for current architecture guidance.
-
-**Goal:** Reorganize Reactive Resume into clear domain/package boundaries so server, web, API, MCP, PDF, resume-domain logic, and documentation are easier to debug and enforce.
-
-**Architecture:** This is one PR with green internal commits. Packages expose role-based explicit public surfaces, web routes become thin shells over domain features, API code is colocated by feature/capability, and boundary rules prevent app-to-app source imports and private package source imports.
-
-**Tech Stack:** pnpm 11, Turborepo 2, TypeScript/tsgo, Vite, React 19, TanStack Router, oRPC, Drizzle, React PDF, PDF.js, MCP SDK, Biome/GritQL, Vitest.
-
----
-
-## Non-Negotiable Decisions
-
-- Root `AGENTS.md` is the single normative architecture source of truth.
-- `docs/adr/0001-workspace-boundaries.md` records rationale only; it must not duplicate the full operational rule set.
-- `docs/contributing/architecture.mdx` is a descriptive overview, not a second source of truth.
-- Keep one PR and green internal commits; no compatibility wrappers or old import-path shims.
-- Preserve existing unrelated user changes in manifests and lockfile. Do not reset or revert them.
-- Keep `apps/server` and `apps/web` split. `apps/server` may serve `apps/web/dist`; app-to-app `src` imports are banned.
-- `apps/web` may import `packages/api` types only. Runtime imports from `packages/api` in web are banned.
-- `apps/server` may import explicit runtime exports from `packages/api`.
-- Tests remain colocated with moved code.
-
-## Task 0: Coordination Artifacts
-
-**Files:**
-- Modify: `docs/superpowers/plans/2026-05-14-monorepo-architecture-reorg.md`
-- Modify: `docs/superpowers/handoffs/2026-05-14-monorepo-architecture-reorg.md`
-- Modify: `docs/superpowers/worklogs/2026-05-14-monorepo-architecture-reorg.md`
-
-- [ ] Keep this plan updated when implementation discoveries force refinements.
-- [ ] Keep the handoff file focused on current task ownership and next-agent startup context.
-- [ ] Keep the worklog append-only with commands, validation results, blockers, and changed ownership decisions.
-
-## Task 1: Pure Resume Domain Package
-
-**Goal:** Create `@reactive-resume/resume` for pure resume-domain behavior, keeping `@reactive-resume/schema` validation-only and `@reactive-resume/utils` generic.
-
-**Files:**
-- Create: `packages/resume/package.json`
-- Create: `packages/resume/tsconfig.json`
-- Create: `packages/resume/vitest.config.ts`
-- Move/create: `packages/resume/src/patch.ts`
-- Move/create: `packages/resume/src/icons.ts`
-- Move tests from `packages/utils/src/resume/patch.test.ts`
-- Move tests for `packages/utils/src/network-icons.test.ts`
-- Modify importers/callers currently using `@reactive-resume/utils/resume/patch`
-- Modify importers/callers currently using `@reactive-resume/utils/network-icons`
-- Modify `packages/utils/package.json`
-- Modify root workspace manifests/lockfile as needed
-
-- [x] Create the new package using the repo's source-consumed package pattern.
-- [x] Move JSON Patch schema/types/application/comparison/error into `@reactive-resume/resume/patch`.
-- [x] Move social network to icon-name mapping into `@reactive-resume/resume/icons`.
-- [x] Update all runtime and test imports.
-- [x] Remove `@reactive-resume/schema` dependency from `@reactive-resume/utils`.
-- [x] Run `pnpm --filter @reactive-resume/resume test`.
-- [x] Run `pnpm --filter @reactive-resume/resume typecheck`.
-- [x] Run targeted typechecks for known consumers: `@reactive-resume/api`, `@reactive-resume/ai`, `web`.
-
-## Task 2: DOCX Package
-
-**Goal:** Create `@reactive-resume/docx` as the dedicated DOCX export package.
-
-**Files:**
-- Create: `packages/docx/package.json`
-- Create: `packages/docx/tsconfig.json`
-- Create: `packages/docx/vitest.config.ts`
-- Move: `packages/utils/src/resume/docx/*` to `packages/docx/src/*`
-- Modify web export callers currently using `@reactive-resume/utils/resume/docx`
-- Modify package dependencies/lockfile
-
-- [x] Create `@reactive-resume/docx` with explicit export `"."` or `"./builder"` as appropriate.
-- [x] Move DOCX implementation and tests unchanged except import paths.
-- [x] Update web callers to import DOCX export from `@reactive-resume/docx`.
-- [x] Remove DOCX dependencies from `@reactive-resume/utils` if no longer used there.
-- [x] Run `pnpm --filter @reactive-resume/docx test`.
-- [x] Run `pnpm --filter @reactive-resume/docx typecheck`.
-- [x] Run focused web export tests/typecheck.
-
-## Task 3: PDF Package Browser/Server Generation Surface
-
-**Goal:** Keep `@reactive-resume/pdf` focused on document/template/font rendering and pure generation adapters. Do not move PDF.js viewer UI into the PDF package.
-
-**Files:**
-- Create: `packages/pdf/src/browser.tsx`
-- Create: `packages/pdf/src/server.tsx`
-- Modify: `packages/pdf/package.json`
-- Modify: web PDF generation callers currently using `apps/web/src/libs/resume/pdf-document.tsx`
-- Modify: `apps/server`/API PDF download code after Task 5
-
-- [x] Add data-plus-options generation APIs:
- - `createResumePdfBlob({ data, template, resolveSectionTitle })`
- - `createResumePdfFile({ data, filename, template, resolveSectionTitle })`
-- [x] Keep Lingui locale loading in `apps/web`; pass `resolveSectionTitle` into PDF helpers.
-- [x] Keep `ResumeDocument` as the underlying render surface.
-- [x] Add/update tests for the browser/server helpers where practical.
-- [x] Run `pnpm --filter @reactive-resume/pdf test`.
-- [x] Run `pnpm --filter @reactive-resume/pdf typecheck`.
-
-## Task 4: MCP Package and Shared Tool Contracts
-
-**Goal:** Extract MCP implementation from web route helpers into `@reactive-resume/mcp`; share model-facing tool contracts from `@reactive-resume/ai`.
-
-**Files:**
-- Create: `packages/mcp/package.json`
-- Create: `packages/mcp/tsconfig.json`
-- Create: `packages/mcp/vitest.config.ts`
-- Move: `apps/web/src/routes/mcp/-helpers/*` to `packages/mcp/src/*`
-- Create/modify: `packages/ai/src/tools/resume-tool-contracts.ts`
-- Modify: `packages/ai/package.json`
-- Modify: `apps/server/src/handlers/mcp.ts`
-- Modify: `apps/server/src/handlers/metadata.ts`
-- Remove old web helper imports
-
-- [x] Move MCP tools/prompts/resources/metadata card generation and tests into `@reactive-resume/mcp`.
-- [x] Keep MCP execution through an injected/in-process oRPC `RouterClient`.
-- [x] Rename MCP tools to canonical unprefixed snake_case names such as `list_resumes`, `read_resume`, `apply_resume_patch`.
-- [x] Do not keep old `reactive_resume_*` aliases.
-- [x] Use shared base tool contracts from `@reactive-resume/ai`, with MCP-specific schema extensions for explicit context fields such as `resumeId`.
-- [ ] Update MCP docs/card version and cache-refresh guidance later in documentation tasks.
-- [x] Run `pnpm --filter @reactive-resume/mcp test`.
-- [x] Run `pnpm --filter @reactive-resume/mcp typecheck`.
-- [x] Run `pnpm --filter server typecheck`.
-
-## Task 5: API Feature Reorganization
-
-**Goal:** Move `packages/api/src` from technical layers into feature/capability modules with explicit public exports.
-
-**Files:**
-- Reorganize under `packages/api/src/features/*`
-- Modify: `packages/api/src/routers/index.ts`
-- Modify: `packages/api/package.json`
-- Modify consumers in `apps/server`, `apps/web` type imports, and packages
-
-- [x] Split `features/agent` into `threads`, `messages`, `attachments`, `actions`, `runs`, and `tools`.
-- [x] Split `features/resume` by capability: `crud`, `tags`, `statistics`, `analysis`, `access`, `events`, `sharing`, `export`.
-- [x] Move authenticated PDF download procedure into `features/resume/export`; it calls `@reactive-resume/pdf/server`.
-- [x] Keep Drizzle schema centralized in `packages/db`; API features consume schema but do not own table definitions.
-- [x] Remove `./services/*` and `./helpers/*` wildcard exports.
-- [x] Add explicit runtime exports required by `apps/server`.
-- [x] Preserve `apps/web` API imports as type-only.
-- [x] Run `pnpm --filter @reactive-resume/api test`.
-- [x] Run `pnpm --filter @reactive-resume/api typecheck`.
-- [x] Run `pnpm --filter server typecheck`.
-- [x] Run `pnpm --filter web typecheck`.
-
-## Task 6: Server Adapter Reorganization
-
-**Goal:** Make `apps/server` read as a runtime adapter app.
-
-**Files:**
-- Reorganize `apps/server/src` into `http`, `rpc`, `mcp`, `openapi`, `static`, `startup`
-- Modify: `apps/server/src/index.ts`
-- Modify: `apps/server/package.json` if imports/dependencies change
-
-- [x] Move handlers into adapter folders.
-- [x] Keep server logic thin: auth/session/HTTP transport/static serving/startup.
-- [x] Use explicit API runtime exports only.
-- [x] Keep serving `apps/web/dist` allowed.
-- [x] Run `pnpm --filter server test`.
-- [x] Run `pnpm --filter server typecheck`.
-
-## Task 7: Domain-First Web Reorganization
-
-**Goal:** Move web code into domain/workflow feature trees so routes become thin shells.
-
-**Files:**
-- Create/reorganize under `apps/web/src/features/resume/*`
-- Create/reorganize under `apps/web/src/features/{command-palette,theme,locale,user,auth,settings,dialogs}/*`
-- Modify route imports and tests
-
-- [x] Move resume domain code into workflow folders:
- - `builder`
- - `preview`
- - `public`
- - `dialogs`
- - `sections`
- - `templates`
- - `export`
- - `pdf-viewer`
-- [x] Move PDF.js viewer/canvas UI into web resume feature, not `@reactive-resume/pdf`.
-- [x] Keep route files responsible for URL params, loaders, redirects, SSR settings, and composition.
-- [x] Leave `apps/web/src/components` with generic app-level primitives/screens only.
-- [x] Move app shell concerns into separate features: command palette, theme, locale, user.
-- [x] Move auth workflows into `features/auth` and settings sections into `features/settings`.
-- [x] Run focused moved tests.
-- [x] Run `pnpm --filter web typecheck`.
-
-Slice 1 notes:
-
-- Moved resume builder draft state, builder preview, PDF.js canvas preview, dashboard thumbnail PDF rendering helpers, public resume PDF viewer, and web-local PDF document wrappers under `apps/web/src/features/resume/*`.
-- Removed `apps/web/src/components/resume` and `apps/web/src/routes/$username/-components`; the public resume route now lazy-loads from `features/resume/public`.
-- Kept PDF.js viewer/canvas code in `apps/web/src/features/resume` and left `@reactive-resume/pdf` limited to PDF generation helpers.
-- Broader Task 7 remains open for non-resume web feature moves and deeper dialog registry work owned by Task 8.
-
-Slice 2 notes:
-
-- Moved command palette, theme, locale, and user shell components/tests from `apps/web/src/components/*` to `apps/web/src/features/{command-palette,theme,locale,user}` and updated consumers.
-- Moved auth route UI, layout, and social auth component into `apps/web/src/features/auth`, leaving auth route files as guard/search/composition wrappers.
-- Moved settings page UI and authentication/integration subcomponents into `apps/web/src/features/settings`, leaving settings route files as dashboard-header/composition wrappers; `job-search` stayed route-only because it is already a redirect shim.
-- `apps/web/src/components` now contains only the remaining generic primitive/screen folders.
-- Task 8 still owns dialog registry decomposition; this slice only updated imports around existing dialog usage.
-
-## Task 8: Dialog Registry Rework
-
-**Goal:** Keep one central dialog runtime but make domain modules own their dialog definitions/renderers.
-
-**Files:**
-- Modify/create under `apps/web/src/features/dialogs`
-- Modify/create domain dialog registry modules under relevant features
-- Modify root dialog manager import
-
-- [x] Replace the single giant discriminated union/manager import hub with composable domain registries.
-- [x] Keep one global dialog store/runtime.
-- [x] Each domain exports its schema entries and renderers.
-- [x] Preserve existing dialog behavior and tests.
-- [x] Run dialog-focused tests.
-- [x] Run `pnpm --filter web typecheck`.
-
-## Task 9: Boundary Enforcement
-
-**Goal:** Make architectural rules executable.
-
-**Files:**
-- Modify: `turbo.json`
-- Modify: `biome.json`
-- Create: `tooling/grit/no-cross-workspace-src-imports.grit`
-- Modify package manifests/tsconfigs to remove forbidden direct source path aliases
-
-- [x] Add `turbo boundaries` package/runtime rules.
-- [x] Add a Biome GritQL plugin/rule for forbidden cross-workspace `src` imports and path aliases.
-- [x] Enforce subpath runtime tags: root exports environment-neutral; browser/server code behind explicit subpaths.
-- [x] Allow wildcard exports only for role-approved leaf libraries such as UI components/hooks.
-- [x] Run `pnpm exec turbo boundaries`.
-- [x] Run a focused Biome boundary check.
-
-## Task 10: Documentation and Source of Truth
-
-**Goal:** Document the final architecture without duplicating rules in multiple places.
-
-**Files:**
-- Modify: `AGENTS.md`
-- Create: `docs/adr/0001-workspace-boundaries.md`
-- Modify: `docs/contributing/architecture.mdx`
-- Modify: `docs/guides/using-the-mcp-server.mdx` if MCP tool names change
-- Modify: `docs/guides/ai-agent-tools.mdx` if shared tool naming changes
-
-- [x] Update root `AGENTS.md` with the normative workspace map, import rules, package roles, runtime tags, validation commands, and placement decision tree.
-- [x] Add ADR rationale for boundaries and rejected alternatives.
-- [x] Refresh public architecture docs as overview only.
-- [x] Update MCP docs to mention canonical unprefixed tool names and client refresh/cache-clear guidance.
-- [x] Avoid local package READMEs for architecture rules unless unavoidable.
-- [x] Run docs-related checks available in the repo.
-
-## Task 11: Final Validation and Handoff
-
-**Goal:** Finish with a validated branch and external-agent-ready handoff.
-
-**Files:**
-- Modify: `docs/superpowers/handoffs/2026-05-14-monorepo-architecture-reorg.md`
-- Modify: `docs/superpowers/worklogs/2026-05-14-monorepo-architecture-reorg.md`
-
-- [x] Run focused checks listed in earlier tasks.
-- [ ] Run final repo checks:
- - `pnpm install --lockfile-only`
- - `pnpm exec biome check .`
- - `pnpm exec turbo boundaries`
- - `pnpm knip`
- - `pnpm typecheck`
- - `pnpm test`
- - `pnpm build`
-- [x] Update the handoff with completed tasks, remaining risks, commands run, and useful file paths.
-- [x] Dispatch final review if subagents are available.
diff --git a/docs/superpowers/plans/2026-05-15-docker-nightly-release-tags.md b/docs/superpowers/plans/2026-05-15-docker-nightly-release-tags.md
deleted file mode 100644
index 51c1e6d6a..000000000
--- a/docs/superpowers/plans/2026-05-15-docker-nightly-release-tags.md
+++ /dev/null
@@ -1,214 +0,0 @@
-# Docker Nightly and Release Tags Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox syntax for tracking.
-
-**Goal:** Update the Docker image workflow so pushes to `main` publish amd64-only nightly tags, while manual runs and pushed version tags publish release tags with the existing multi-arch behavior.
-
-**Architecture:** Keep the existing digest-build and manifest-merge pipeline in `.github/workflows/docker-build.yml`. Add event-based mode expressions so nightly and release publishing share setup, registry auth, digest upload/download, signing, and inspection while differing only in triggers, platform inclusion, final tags, and redeploy behavior.
-
-**Tech Stack:** GitHub Actions, Docker Buildx, `docker/metadata-action@v6`, `docker/build-push-action@v7`, `docker buildx imagetools`, Cosign.
-
----
-
-### Task 1: Add Workflow Triggers and Mode Outputs
-
-**Files:**
-- Modify: `.github/workflows/docker-build.yml`
-
-- [x] **Step 1: Update workflow triggers**
-
-Change the workflow `on` block to include:
-
-```yaml
-on:
- workflow_dispatch:
- push:
- branches:
- - main
- tags:
- - "v*"
-```
-
-Expected behavior:
-- `push` to `main` runs the workflow.
-- `push` to tags matching `v*` runs the workflow.
-- PR events do not run the workflow.
-- Manual runs still run the workflow.
-
-- [x] **Step 2: Add a mode job**
-
-Add a `mode` job before `build`:
-
-```yaml
- mode:
- runs-on: ubuntu-latest
- outputs:
- nightly: ${{ steps.mode.outputs.nightly }}
- release: ${{ steps.mode.outputs.release }}
- matrix: ${{ steps.mode.outputs.matrix }}
- steps:
- - name: Determine publishing mode
- id: mode
- run: |
- if [[ "${{ github.event_name }}" == "push" && "${{ github.ref }}" == "refs/heads/main" ]]; then
- echo "nightly=true" >> "$GITHUB_OUTPUT"
- echo "release=false" >> "$GITHUB_OUTPUT"
- echo 'matrix={"include":[{"platform":"linux/amd64","runner":"ubuntu-latest","arch":"amd64"}]}' >> "$GITHUB_OUTPUT"
- else
- echo "nightly=false" >> "$GITHUB_OUTPUT"
- echo "release=true" >> "$GITHUB_OUTPUT"
- echo 'matrix={"include":[{"platform":"linux/amd64","runner":"ubuntu-latest","arch":"amd64"},{"platform":"linux/arm64","runner":"ubuntu-24.04-arm","arch":"arm64"}]}' >> "$GITHUB_OUTPUT"
- fi
-```
-
-This job centralizes the event decision so later jobs do not duplicate the full expression.
-
-### Task 2: Generate the Platform Matrix from Mode
-
-**Files:**
-- Modify: `.github/workflows/docker-build.yml`
-
-- [x] **Step 1: Make `build` depend on `mode`**
-
-Set:
-
-```yaml
- needs: mode
-```
-
-on the `build` job.
-
-- [x] **Step 2: Replace the static build matrix with the mode output**
-
-Set the build strategy matrix to the JSON emitted by the `mode` job:
-
-```yaml
- matrix: ${{ fromJSON(needs.mode.outputs.matrix) }}
-```
-
-Expected behavior:
-- Nightly runs create only the `amd64` matrix entry.
-- Release/manual/tag runs create both `amd64` and `arm64` matrix entries.
-
-### Task 3: Generate Conditional Final Tags
-
-**Files:**
-- Modify: `.github/workflows/docker-build.yml`
-
-- [x] **Step 1: Make `merge` depend on `mode` and `build`**
-
-Set:
-
-```yaml
- needs:
- - mode
- - build
-```
-
-on the `merge` job.
-
-- [x] **Step 2: Update final Docker metadata tags**
-
-In the merge job's Docker metadata step, replace the unconditional release tag list with conditional tags:
-
-```yaml
- tags: |
- type=sha,prefix=sha-
- type=raw,value=nightly,enable=${{ needs.mode.outputs.nightly == 'true' }}
- type=raw,value=nightly-{{date 'YYYYMMDDHHmmss' tz='UTC'}},enable=${{ needs.mode.outputs.nightly == 'true' }}
- type=raw,value=latest,enable=${{ needs.mode.outputs.release == 'true' }}
- type=raw,value=v${{ steps.version.outputs.version }},enable=${{ needs.mode.outputs.release == 'true' }}
- type=raw,value=v${{ steps.semver.outputs.major }}.${{ steps.semver.outputs.minor }},enable=${{ needs.mode.outputs.release == 'true' }}
- type=raw,value=v${{ steps.semver.outputs.major }},enable=${{ needs.mode.outputs.release == 'true' }}
-```
-
-Expected behavior:
-- Nightly runs publish `nightly`, `nightly-{UTC timestamp}`, and SHA tags.
-- Release/manual/tag runs publish `latest`, version aliases, and SHA tags.
-
-### Task 4: Make Post-Publish Steps Mode-Aware
-
-**Files:**
-- Modify: `.github/workflows/docker-build.yml`
-
-- [x] **Step 1: Emit canonical image references from the manifest step**
-
-In `Create manifest list and push`, compute the canonical final tag from mode:
-
-```bash
-if [[ "${{ needs.mode.outputs.nightly }}" == "true" ]]; then
- FINAL_TAG="nightly"
-else
- FINAL_TAG="v${{ steps.version.outputs.version }}"
-fi
-```
-
-Use `$FINAL_TAG` for both GHCR and Docker Hub digest lookup.
-
-- [x] **Step 2: Inspect the canonical final tag**
-
-Update `Inspect image` to inspect:
-
-```bash
-docker buildx imagetools inspect ghcr.io/${{ env.IMAGE }}:${{ steps.manifest.outputs.final_tag }}
-docker buildx imagetools inspect docker.io/${{ env.IMAGE }}:${{ steps.manifest.outputs.final_tag }}
-```
-
-- [x] **Step 3: Keep redeploy release-only**
-
-Add this condition to `Redeploy Stack`:
-
-```yaml
- if: ${{ needs.mode.outputs.release == 'true' }}
-```
-
-Expected behavior:
-- Nightly publishes images, signs them, and inspects them.
-- Nightly does not redeploy the stack.
-- Release/manual/tag publishes images, signs them, inspects them, and redeploys.
-
-### Task 5: Validate Workflow Logic
-
-**Files:**
-- Test: `.github/workflows/docker-build.yml`
-
-- [x] **Step 1: Parse YAML**
-
-Run:
-
-```bash
-ruby -e 'require "yaml"; YAML.load_file(".github/workflows/docker-build.yml"); puts "yaml ok"'
-```
-
-Expected output:
-
-```text
-yaml ok
-```
-
-- [x] **Step 2: Review the workflow diff**
-
-Run:
-
-```bash
-git diff -- .github/workflows/docker-build.yml docs/superpowers/plans/2026-05-15-docker-nightly-release-tags.md
-```
-
-Confirm these requirements in the diff:
-- `push` to `main` is enabled.
-- pushed tags matching `v*` are enabled.
-- no `pull_request` trigger exists.
-- the matrix output contains only amd64 when `nightly == 'true'`.
-- nightly tags are enabled only for nightly mode.
-- release tags are enabled only for release mode.
-- redeploy is release-only.
-
-- [x] **Step 3: Check working tree scope**
-
-Run:
-
-```bash
-git status --short .github/workflows/docker-build.yml docs/superpowers/plans/2026-05-15-docker-nightly-release-tags.md
-```
-
-Expected output includes only the workflow and this plan among files changed by this implementation.
diff --git a/docs/superpowers/plans/2026-05-15-manifest-only-pwa.md b/docs/superpowers/plans/2026-05-15-manifest-only-pwa.md
deleted file mode 100644
index 0cf76183f..000000000
--- a/docs/superpowers/plans/2026-05-15-manifest-only-pwa.md
+++ /dev/null
@@ -1,117 +0,0 @@
-# Manifest-Only PWA Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Remove Reactive Resume's service-worker and Workbox PWA behavior while keeping install metadata.
-
-**Architecture:** Keep the manifest link and install meta tags in the web root route. Keep manifest data in
-`apps/web/public/manifest.webmanifest`, keep head meta tags in `apps/web/src/libs/pwa.ts`, and remove the
-service-worker registration export plus the `vite-plugin-pwa` build plugin.
-
-**Tech Stack:** TanStack Start, Vite, TypeScript, pnpm, Vitest, Workbox removal.
-
----
-
-### Task 1: Remove service-worker wiring
-
-**Files:**
-- Modify: `apps/web/index.html`
-- Modify: `apps/web/vite.config.ts`
-- Modify: `apps/web/src/libs/pwa.ts`
-- Modify: `apps/web/src/routes/__root.tsx`
-- Delete: `apps/web/src/libs/pwa.test.ts`
-
-- [x] **Step 1: Remove `vite-plugin-pwa` imports and plugin usage**
-
-In `apps/web/vite.config.ts`, remove:
-
-```ts
-import { VitePWA } from "vite-plugin-pwa";
-import { pwaManifest } from "./src/libs/pwa";
-```
-
-Delete the local `pwa()` helper and remove `pwa()` from the `plugins` array.
-
-- [x] **Step 2: Add install metadata to static HTML**
-
-In `apps/web/index.html`, add the manifest link, icon links, theme color, and Apple/mobile install meta tags inside
-`` so install metadata is present without plugin HTML injection.
-
-- [x] **Step 3: Remove dead manifest export and runtime service-worker registration**
-
-In `apps/web/src/libs/pwa.ts`, remove the `pwaManifest` and `pwaServiceWorkerRegistrationScript` exports so the
-module only owns head meta tags.
-
-In `apps/web/src/routes/__root.tsx`, change the PWA import to:
-
-```ts
-import { pwaHeadMetaTags } from "@/libs/pwa";
-```
-
-Remove the `scripts` entry that injects `pwaServiceWorkerRegistrationScript` in production.
-
-- [x] **Step 4: Delete obsolete PWA unit test**
-
-Delete `apps/web/src/libs/pwa.test.ts`, because the remaining PWA surface is static manifest/head metadata.
-
-### Task 2: Remove unused dependency graph
-
-**Files:**
-- Modify: `apps/web/package.json`
-- Modify: `pnpm-lock.yaml`
-
-- [x] **Step 1: Remove direct web dependency**
-
-Remove this dependency from `apps/web/package.json`:
-
-```json
-"vite-plugin-pwa": "^1.3.0"
-```
-
-- [x] **Step 2: Refresh lockfile narrowly**
-
-Run:
-
-```sh
-pnpm install --lockfile-only --offline --ignore-scripts
-```
-
-Expected: the lockfile no longer contains `vite-plugin-pwa` or unused Workbox packages required only by that
-plugin. If the offline lockfile refresh is unavailable, edit the lockfile narrowly and verify with git diff.
-
-### Task 3: Validate manifest-only behavior
-
-**Files:**
-- Inspect: `apps/web/.output` or `apps/web/dist`
-
-- [x] **Step 1: Run focused checks**
-
-Run:
-
-```sh
-pnpm --filter web typecheck
-pnpm --filter web build
-```
-
-Expected: both commands complete successfully.
-
-- [x] **Step 2: Inspect build output for service-worker artifacts**
-
-Run:
-
-```sh
-find apps/web/.output apps/web/dist -name 'sw.js' -o -name 'workbox-*' -o -name 'registerSW.js'
-```
-
-Expected: no service-worker or Workbox files are printed. If one output directory does not exist, the command may
-print a find warning for that path; inspect the directory that exists.
-
-- [x] **Step 3: Inspect source for removed service-worker registration**
-
-Run:
-
-```sh
-rg -n "serviceWorker|register\\(\"/sw\\.js\"|VitePWA|vite-plugin-pwa|workbox" apps/web/src apps/web/vite.config.ts apps/web/package.json
-```
-
-Expected: no matches for the removed PWA service-worker path.
diff --git a/docs/superpowers/plans/2026-05-15-unsafe-oauth-redirect-uri.md b/docs/superpowers/plans/2026-05-15-unsafe-oauth-redirect-uri.md
deleted file mode 100644
index c126df788..000000000
--- a/docs/superpowers/plans/2026-05-15-unsafe-oauth-redirect-uri.md
+++ /dev/null
@@ -1,222 +0,0 @@
-# Unsafe OAuth Redirect URI Flag Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Replace `OAUTH_DYNAMIC_CLIENT_REDIRECT_HOSTS` with `FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI`, preserving safe defaults and allowing any parseable redirect URI only when the flag is enabled.
-
-**Architecture:** Keep OAuth redirect URI policy centralized in `packages/utils/src/url-security.node.ts`. Pass the new env flag from both Better Auth hook validation and the server auth preflight so both paths make identical decisions. Update env/docs references and tests in the same slice.
-
-**Tech Stack:** TypeScript, Zod env schema, Better Auth hook middleware, Vitest, Turborepo env filtering, MDX docs.
-
----
-
-## File Structure
-
-- Modify `packages/utils/src/url-security.node.ts`: Change the OAuth redirect validator from allowlist-based to mode-based.
-- Modify `packages/utils/src/url-security.node.test.ts`: Update safe-mode tests and add unsafe-mode coverage.
-- Modify `packages/env/src/server.ts`: Remove the old allowlist env var and add `FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI`.
-- Modify `packages/auth/src/config.ts`: Remove host-list parsing and pass `{ allowUnsafe: env.FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI }`.
-- Modify `apps/server/src/http/auth.ts`: Remove host-list parsing and pass the same flag to the validator.
-- Modify `apps/server/src/http/auth.test.ts`: Update env mock shape and preserve existing local edits.
-- Modify `turbo.json`, `.env.example`, and MDX docs: Replace old env references with the new flag and warnings.
-
-### Task 1: URL Policy Tests And Validator
-
-**Files:**
-- Modify: `packages/utils/src/url-security.node.test.ts`
-- Modify: `packages/utils/src/url-security.node.ts`
-
-- [ ] **Step 1: Write the failing safe/unsafe OAuth redirect tests**
-
-Use this shape in `packages/utils/src/url-security.node.test.ts`:
-
-```ts
-describe("isAllowedOAuthRedirectUri", () => {
- const trustedOrigins = ["https://app.example.com"];
-
- it("returns false for malformed URI", () => {
- expect(isAllowedOAuthRedirectUri("nope", trustedOrigins)).toBe(false);
- });
-
- it("returns true for any parseable URI when unsafe mode is enabled", () => {
- const options = { allowUnsafe: true };
-
- expect(isAllowedOAuthRedirectUri("myapp://callback", trustedOrigins, options)).toBe(true);
- expect(isAllowedOAuthRedirectUri("http://example.com/cb", trustedOrigins, options)).toBe(true);
- expect(isAllowedOAuthRedirectUri("https://192.168.1.1/cb", trustedOrigins, options)).toBe(true);
- expect(isAllowedOAuthRedirectUri("https://u:p@app.example.com/cb#x", trustedOrigins, options)).toBe(true);
- expect(isAllowedOAuthRedirectUri("not a url", trustedOrigins, options)).toBe(false);
- });
-});
-```
-
-- [ ] **Step 2: Run the focused utils test and verify it fails**
-
-Run: `pnpm --filter @reactive-resume/utils test -- src/url-security.node.test.ts`
-
-Expected before implementation: TypeScript/test failure because `isAllowedOAuthRedirectUri` still requires the removed allowlist argument.
-
-- [ ] **Step 3: Implement mode-based OAuth redirect validation**
-
-Use this signature in `packages/utils/src/url-security.node.ts`:
-
-```ts
-type OAuthRedirectUriOptions = {
- allowUnsafe?: boolean;
-};
-
-export function isAllowedOAuthRedirectUri(
- input: string,
- trustedOrigins: string[],
- options?: OAuthRedirectUriOptions,
-) {
- const parsed = parseUrl(input);
- if (!parsed) return false;
- if (options?.allowUnsafe) return true;
- if (parsed.username || parsed.password) return false;
- if (parsed.hash) return false;
-
- const origin = parsed.origin.toLowerCase();
- const hostname = normalizeHostname(parsed.hostname);
-
- if (parsed.protocol === "http:") return isOAuthLoopbackRedirectHost(hostname);
- if (parsed.protocol !== "https:") return false;
- if (isPrivateOrLoopbackHost(hostname)) return false;
-
- return trustedOrigins.includes(origin);
-}
-```
-
-- [ ] **Step 4: Run the focused utils test and verify it passes**
-
-Run: `pnpm --filter @reactive-resume/utils test -- src/url-security.node.test.ts`
-
-Expected after implementation: all tests in `url-security.node.test.ts` pass.
-
-### Task 2: Env And Runtime Wiring
-
-**Files:**
-- Modify: `packages/env/src/server.ts`
-- Modify: `packages/auth/src/config.ts`
-- Modify: `apps/server/src/http/auth.ts`
-- Modify: `apps/server/src/http/auth.test.ts`
-- Modify: `turbo.json`
-
-- [ ] **Step 1: Update env schema and Turbo env list**
-
-In `packages/env/src/server.ts`, remove:
-
-```ts
-OAUTH_DYNAMIC_CLIENT_REDIRECT_HOSTS: z.string().optional(),
-```
-
-Add with feature flags:
-
-```ts
-FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI: z.stringbool().default(false),
-```
-
-In `turbo.json`, remove `"OAUTH_DYNAMIC_CLIENT_REDIRECT_HOSTS"` and add `"FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI"` beside the other flags.
-
-- [ ] **Step 2: Wire the flag into Better Auth config**
-
-In `packages/auth/src/config.ts`, remove `parseAllowedHostList` usage and call:
-
-```ts
-if (
- !isAllowedOAuthRedirectUri(uri, TRUSTED_ORIGINS, {
- allowUnsafe: env.FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI,
- })
-) {
- throw new APIError("BAD_REQUEST", {
- message: "redirect_uri is not allowed for dynamic client registration",
- });
-}
-```
-
-- [ ] **Step 3: Wire the flag into server preflight**
-
-In `apps/server/src/http/auth.ts`, remove `parseAllowedHostList` usage and call:
-
-```ts
-!isAllowedOAuthRedirectUri(redirectUri, oauthTrustedOrigins, {
- allowUnsafe: env.FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI,
-})
-```
-
-Update the test env mock in `apps/server/src/http/auth.test.ts`:
-
-```ts
-env: {
- SERVER_PORT: 3001,
- APP_URL: "http://localhost:3000",
- FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI: false,
-},
-```
-
-- [ ] **Step 4: Run focused typechecks**
-
-Run:
-
-```sh
-pnpm --filter @reactive-resume/auth typecheck
-pnpm --filter server typecheck
-```
-
-Expected: both commands exit 0.
-
-### Task 3: Docs And Env Examples
-
-**Files:**
-- Modify: `.env.example`
-- Modify: `docs/self-hosting/docker.mdx`
-- Modify: `docs/self-hosting/sso.mdx`
-- Modify: `docs/getting-started/quickstart.mdx`
-
-- [ ] **Step 1: Replace old env docs with the new flag**
-
-Remove all `OAUTH_DYNAMIC_CLIENT_REDIRECT_HOSTS` references.
-
-Add this warning wherever feature flags are documented:
-
-```md
-`FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI`: Allows dynamic OAuth client registration to use any parseable redirect URI, including custom schemes, private hosts, and non-loopback `http://` URLs. Keep disabled unless this is a trusted self-hosted deployment. Enabling it on public or multi-tenant instances can enable phishing or token exfiltration.
-```
-
-- [ ] **Step 2: Verify the removed env is gone from product code and docs**
-
-Run: `rg -n "OAUTH_DYNAMIC_CLIENT_REDIRECT_HOSTS" . --glob "!docs/superpowers/**"`
-
-Expected: no matches outside the approved design and implementation plan documents.
-
-Run: `rg -n "FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI" .`
-
-Expected: matches in env schema, Turbo config, docs, tests, and runtime validation paths.
-
-### Task 4: Final Verification
-
-**Files:**
-- Verify all modified files.
-
-- [ ] **Step 1: Run focused tests**
-
-Run:
-
-```sh
-pnpm --filter @reactive-resume/utils test -- src/url-security.node.test.ts
-pnpm --filter server test -- src/http/auth.test.ts
-```
-
-Expected: both commands exit 0.
-
-- [ ] **Step 2: Run focused typechecks and boundaries**
-
-Run:
-
-```sh
-pnpm --filter @reactive-resume/auth typecheck
-pnpm --filter server typecheck
-pnpm exec turbo boundaries
-```
-
-Expected: all commands exit 0.
diff --git a/docs/superpowers/plans/2026-06-20-e2e-tests.md b/docs/superpowers/plans/2026-06-20-e2e-tests.md
deleted file mode 100644
index d5cb80dc9..000000000
--- a/docs/superpowers/plans/2026-06-20-e2e-tests.md
+++ /dev/null
@@ -1,670 +0,0 @@
-# E2E Tests Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Build a Playwright E2E test setup that runs deterministic core Reactive Resume flows with ephemeral accounts/data locally and on GitHub Actions for every PR.
-
-**Architecture:** Add a root-level Playwright harness that targets the production server after `pnpm build`. Use hybrid fixtures: one browser-driven auth smoke spec, and helper-created authenticated browser state plus ephemeral database cleanup for resume flows. Keep initial PR-gated coverage to auth, sample resume creation, builder autosave, JSON export/import, and public sharing.
-
-**Tech Stack:** Playwright, TypeScript, pnpm, Turbo, GitHub Actions, PostgreSQL service container, Better Auth HTTP endpoints, Drizzle/Postgres cleanup helpers.
-
----
-
-## File structure
-
-- Create `playwright.config.ts`: Playwright projects, reporters, artifact policy, base URL, and production `webServer`.
-- Create `tests/e2e/README.md`: local setup and CI behavior.
-- Create `tests/e2e/fixtures/data.ts`: unique test identity and resume value generation.
-- Create `tests/e2e/fixtures/auth.ts`: browser UI auth helpers and API-backed authenticated storage state helpers.
-- Create `tests/e2e/fixtures/db.ts`: user cleanup by email/username prefix.
-- Create `tests/e2e/fixtures/resume.ts`: UI helpers for creating sample resumes and accessing builder sections.
-- Create `tests/e2e/fixtures/test.ts`: typed Playwright fixture composition.
-- Create `tests/e2e/specs/auth.spec.ts`: browser registration/login smoke flow.
-- Create `tests/e2e/specs/resume-lifecycle.spec.ts`: dashboard create sample resume and builder autosave flow.
-- Create `tests/e2e/specs/json-export-import.spec.ts`: deterministic JSON backup/restore flow.
-- Create `tests/e2e/specs/public-sharing.spec.ts`: public sharing flow with anonymous browser context.
-- Create `.github/workflows/e2e.yml`: PR/push workflow with Postgres, build, Playwright install, E2E run, and report uploads.
-- Modify `package.json`: add Playwright dependency and E2E scripts.
-- Modify `turbo.json`: register E2E task if routed through package scripts.
-- Modify targeted UI files only if accessible locators are not sufficient.
-
-## Task 1: Add Playwright dependency and scripts
-
-**Files:**
-- Modify: `package.json`
-- Modify: `pnpm-lock.yaml`
-- Modify: `turbo.json`
-
-- [ ] **Step 1: Add Playwright with the package manager**
-
-Run: `pnpm add -D @playwright/test`
-
-Expected: `package.json` and `pnpm-lock.yaml` include `@playwright/test`.
-
-- [ ] **Step 2: Add root scripts**
-
-Change root `package.json` scripts to include:
-
-```json
-{
- "test:e2e": "playwright test",
- "test:e2e:ui": "playwright test --ui",
- "test:e2e:ci": "playwright test"
-}
-```
-
-- [ ] **Step 3: Register the Turbo task**
-
-Add this task entry to `turbo.json`:
-
-```json
-"test:e2e": {
- "cache": false
-}
-```
-
-- [ ] **Step 4: Verify script discovery**
-
-Run: `pnpm exec playwright --version`
-
-Expected: Playwright prints a version and exits successfully.
-
-- [ ] **Step 5: Commit**
-
-Run:
-
-```bash
-git add package.json pnpm-lock.yaml turbo.json
-git commit -m "test: add playwright e2e scripts"
-git push -u origin feat/e2e-test-plan-2b10
-```
-
-## Task 2: Add Playwright configuration
-
-**Files:**
-- Create: `playwright.config.ts`
-
-- [ ] **Step 1: Create the config**
-
-Create `playwright.config.ts`:
-
-```ts
-import { defineConfig, devices } from "@playwright/test";
-
-const port = Number.parseInt(process.env.PORT ?? "3000", 10);
-const baseURL = process.env.APP_URL ?? `http://127.0.0.1:${port}`;
-const isCI = process.env.CI === "true" || process.env.CI === "1";
-
-export default defineConfig({
- testDir: "./tests/e2e/specs",
- fullyParallel: true,
- forbidOnly: isCI,
- retries: isCI ? 2 : 0,
- workers: isCI ? 2 : undefined,
- reporter: isCI
- ? [
- ["list"],
- ["github"],
- ["junit", { outputFile: "test-results/e2e-junit.xml" }],
- ]
- : [["list"], ["html", { open: "never" }]],
- use: {
- baseURL,
- trace: "retain-on-failure",
- screenshot: "only-on-failure",
- video: "retain-on-failure",
- },
- projects: [
- {
- name: "chromium",
- use: { ...devices["Desktop Chrome"] },
- },
- ],
- webServer: {
- command: "pnpm start",
- url: `${baseURL}/api/health`,
- reuseExistingServer: !isCI,
- timeout: 120_000,
- env: {
- ...process.env,
- PORT: String(port),
- },
- },
-});
-```
-
-- [ ] **Step 2: Verify config loads**
-
-Run: `pnpm exec playwright test --list`
-
-Expected: Playwright lists zero tests at this point without config errors.
-
-- [ ] **Step 3: Commit**
-
-Run:
-
-```bash
-git add playwright.config.ts
-git commit -m "test: configure playwright"
-git push -u origin feat/e2e-test-plan-2b10
-```
-
-## Task 3: Add E2E fixtures
-
-**Files:**
-- Create: `tests/e2e/fixtures/data.ts`
-- Create: `tests/e2e/fixtures/db.ts`
-- Create: `tests/e2e/fixtures/auth.ts`
-- Create: `tests/e2e/fixtures/resume.ts`
-- Create: `tests/e2e/fixtures/test.ts`
-
-- [ ] **Step 1: Add test data helpers**
-
-Create `tests/e2e/fixtures/data.ts`:
-
-```ts
-import type { TestInfo } from "@playwright/test";
-
-const sanitize = (value: string) => value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
-
-export type E2EAccount = {
- name: string;
- username: string;
- email: string;
- password: string;
-};
-
-export function createRunSlug(testInfo: TestInfo) {
- const worker = testInfo.workerIndex;
- const title = sanitize(testInfo.titlePath.join("-")).slice(0, 40);
- const suffix = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
- return `e2e-${worker}-${title}-${suffix}`;
-}
-
-export function createAccount(testInfo: TestInfo): E2EAccount {
- const slug = createRunSlug(testInfo).replaceAll("-", "_").slice(0, 48);
- return {
- name: "E2E Test User",
- username: slug,
- email: `${slug}@example.test`,
- password: "Password123!",
- };
-}
-
-export function createResumeName(testInfo: TestInfo) {
- return `E2E Resume ${createRunSlug(testInfo)}`;
-}
-```
-
-- [ ] **Step 2: Add database cleanup**
-
-Create `tests/e2e/fixtures/db.ts`:
-
-```ts
-import { eq, or } from "drizzle-orm";
-import { db, getPool } from "@reactive-resume/db/client";
-import { user } from "@reactive-resume/db/schema";
-
-export async function deleteE2EUser(account: { email: string; username: string }) {
- await db.delete(user).where(or(eq(user.email, account.email), eq(user.username, account.username)));
-}
-
-export async function closeE2EDatabase() {
- await getPool().end();
- globalThis.__pool = undefined;
- globalThis.__drizzle = undefined;
-}
-```
-
-- [ ] **Step 3: Add auth helpers**
-
-Create `tests/e2e/fixtures/auth.ts`:
-
-```ts
-import type { Browser, Page } from "@playwright/test";
-import type { E2EAccount } from "./data";
-
-export async function registerViaUi(page: Page, account: E2EAccount) {
- await page.goto("/auth/register");
- await page.getByLabel("Name").fill(account.name);
- await page.getByLabel("Username").fill(account.username);
- await page.getByLabel("Email Address").fill(account.email);
- await page.getByLabel("Password").fill(account.password);
- await page.getByRole("button", { name: "Sign up" }).click();
- await page.getByRole("link", { name: /continue/i }).click();
- await page.waitForURL(/\/dashboard/);
-}
-
-export async function loginViaUi(page: Page, account: E2EAccount) {
- await page.goto("/auth/login");
- await page.getByLabel(/email|username/i).fill(account.email);
- await page.getByLabel("Password").fill(account.password);
- await page.getByRole("button", { name: "Sign in" }).click();
- await page.waitForURL(/\/dashboard/);
-}
-
-export async function createAuthenticatedPage(browser: Browser, account: E2EAccount) {
- const context = await browser.newContext();
- const page = await context.newPage();
- await registerViaUi(page, account);
- return page;
-}
-```
-
-- [ ] **Step 4: Add resume UI helpers**
-
-Create `tests/e2e/fixtures/resume.ts`:
-
-```ts
-import type { Page, TestInfo } from "@playwright/test";
-import { expect } from "@playwright/test";
-import { createResumeName } from "./data";
-
-export async function createSampleResumeFromDashboard(page: Page, testInfo: TestInfo) {
- const resumeName = createResumeName(testInfo);
- await page.goto("/dashboard/resumes");
- await page.getByText("Create a new resume").click();
- await page.getByRole("dialog", { name: "Create a new resume" }).getByLabel("Name").fill(resumeName);
- await page.getByRole("button", { name: "Create resume with options" }).click();
- await page.getByRole("menuitem", { name: "Create a Sample Resume" }).click();
- await expect(page.getByText(resumeName)).toBeVisible();
- await page.getByText(resumeName).click();
- await page.waitForURL(/\/builder\/.+/);
- return resumeName;
-}
-
-export async function openRightSidebarSection(page: Page, name: string) {
- await page.getByRole("button", { name }).click();
-}
-```
-
-- [ ] **Step 5: Add fixture composition**
-
-Create `tests/e2e/fixtures/test.ts`:
-
-```ts
-import { test as base, expect } from "@playwright/test";
-import type { E2EAccount } from "./data";
-import { createAccount } from "./data";
-import { deleteE2EUser } from "./db";
-import { registerViaUi } from "./auth";
-
-type Fixtures = {
- account: E2EAccount;
- authPage: import("@playwright/test").Page;
-};
-
-export const test = base.extend({
- account: async ({}, use, testInfo) => {
- const account = createAccount(testInfo);
- await use(account);
- await deleteE2EUser(account);
- },
- authPage: async ({ browser, account }, use) => {
- const context = await browser.newContext();
- const page = await context.newPage();
- await registerViaUi(page, account);
- await use(page);
- await context.close();
- },
-});
-
-export { expect };
-```
-
-- [ ] **Step 6: Run type-aware feedback**
-
-Run: `pnpm exec tsc --noEmit --allowImportingTsExtensions false --moduleResolution bundler --target es2022 --module esnext tests/e2e/fixtures/*.ts`
-
-Expected: If direct `tsc` is too narrow for workspace exports, use `pnpm typecheck` after Task 6 instead.
-
-- [ ] **Step 7: Commit**
-
-Run:
-
-```bash
-git add tests/e2e/fixtures
-git commit -m "test: add e2e fixtures"
-git push -u origin feat/e2e-test-plan-2b10
-```
-
-## Task 4: Add core E2E specs
-
-**Files:**
-- Create: `tests/e2e/specs/auth.spec.ts`
-- Create: `tests/e2e/specs/resume-lifecycle.spec.ts`
-- Create: `tests/e2e/specs/json-export-import.spec.ts`
-- Create: `tests/e2e/specs/public-sharing.spec.ts`
-
-- [ ] **Step 1: Add auth smoke spec**
-
-Create `tests/e2e/specs/auth.spec.ts`:
-
-```ts
-import { test, expect } from "../fixtures/test";
-import { loginViaUi, registerViaUi } from "../fixtures/auth";
-
-test("registers and logs in with email credentials", async ({ page, account }) => {
- await registerViaUi(page, account);
- await expect(page.getByRole("heading", { name: "Resumes" })).toBeVisible();
- await page.getByRole("button", { name: /user menu|account|profile/i }).click();
- await page.getByRole("menuitem", { name: /logout|sign out/i }).click();
- await loginViaUi(page, account);
- await expect(page.getByRole("heading", { name: "Resumes" })).toBeVisible();
-});
-```
-
-- [ ] **Step 2: Add resume lifecycle spec**
-
-Create `tests/e2e/specs/resume-lifecycle.spec.ts`:
-
-```ts
-import { test, expect } from "../fixtures/test";
-import { createSampleResumeFromDashboard } from "../fixtures/resume";
-
-test("creates a sample resume and persists a basics edit", async ({ authPage: page }, testInfo) => {
- await createSampleResumeFromDashboard(page, testInfo);
- const updatedName = `E2E Edited ${Date.now()}`;
- await page.getByRole("button", { name: "Basics" }).click();
- await page.getByLabel("Name").fill(updatedName);
- await page.reload();
- await page.getByRole("button", { name: "Basics" }).click();
- await expect(page.getByLabel("Name")).toHaveValue(updatedName);
-});
-```
-
-- [ ] **Step 3: Add JSON export/import spec**
-
-Create `tests/e2e/specs/json-export-import.spec.ts`:
-
-```ts
-import { test, expect } from "../fixtures/test";
-import { createSampleResumeFromDashboard } from "../fixtures/resume";
-
-test("exports and imports a resume JSON backup", async ({ authPage: page }, testInfo) => {
- const resumeName = await createSampleResumeFromDashboard(page, testInfo);
- await page.getByRole("button", { name: "Export" }).click();
- const downloadPromise = page.waitForEvent("download");
- await page.getByRole("button", { name: /^JSON$/ }).click();
- const download = await downloadPromise;
- expect(download.suggestedFilename()).toMatch(/\.json$/);
- const path = await download.path();
- expect(path).toBeTruthy();
- if (!path) throw new Error("Expected Playwright to provide a downloaded JSON path.");
- await page.goto("/dashboard/resumes");
- await page.getByText("Import an existing resume").click();
- await page.getByRole("combobox").click();
- await page.getByRole("option", { name: "Reactive Resume (JSON)" }).click();
- await page.getByText("Click here to select a file to import").setInputFiles(path);
- await page.getByRole("button", { name: "Import" }).click();
- await page.waitForURL(/\/builder\/.+/);
- await expect(page.getByText(resumeName)).toBeVisible();
-});
-```
-
-- [ ] **Step 4: Add public sharing spec**
-
-Create `tests/e2e/specs/public-sharing.spec.ts`:
-
-```ts
-import { test, expect } from "../fixtures/test";
-import { createSampleResumeFromDashboard } from "../fixtures/resume";
-
-test("publishes a resume and renders it for an anonymous visitor", async ({ browser, authPage: page }, testInfo) => {
- await createSampleResumeFromDashboard(page, testInfo);
- await page.getByRole("button", { name: "Sharing" }).click();
- await page.getByLabel("Allow Public Access").click();
- const publicUrl = await page.getByLabel("URL").inputValue();
- const anonymous = await browser.newPage();
- await anonymous.goto(publicUrl);
- await expect(anonymous.getByRole("button", { name: /download/i })).toBeVisible();
- await anonymous.close();
-});
-```
-
-- [ ] **Step 5: Run list mode**
-
-Run: `pnpm test:e2e -- --list`
-
-Expected: Four Chromium tests are listed.
-
-- [ ] **Step 6: Commit**
-
-Run:
-
-```bash
-git add tests/e2e/specs
-git commit -m "test: add core e2e specs"
-git push -u origin feat/e2e-test-plan-2b10
-```
-
-## Task 5: Add documentation
-
-**Files:**
-- Create: `tests/e2e/README.md`
-
-- [ ] **Step 1: Add E2E README**
-
-Create `tests/e2e/README.md`:
-
-```md
-# E2E Tests
-
-Reactive Resume uses Playwright for PR-gated browser coverage of deterministic core flows.
-
-## Local setup
-
-Start PostgreSQL:
-
-`sudo docker compose -f compose.dev.yml up -d postgres`
-
-Generate local test secrets:
-
-`export AUTH_SECRET=$(openssl rand -hex 32)`
-
-`export ENCRYPTION_SECRET=$(openssl rand -hex 32)`
-
-Run database migrations:
-
-`APP_URL=http://localhost:3000 PORT=3000 DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres FLAG_DISABLE_SIGNUPS=false FLAG_DISABLE_EMAIL_AUTH=false FLAG_DISABLE_API_RATE_LIMIT=true LOCAL_STORAGE_PATH=/workspace/data/e2e pnpm db:migrate`
-
-Build the production app:
-
-`APP_URL=http://localhost:3000 PORT=3000 DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres FLAG_DISABLE_SIGNUPS=false FLAG_DISABLE_EMAIL_AUTH=false FLAG_DISABLE_API_RATE_LIMIT=true LOCAL_STORAGE_PATH=/workspace/data/e2e pnpm build`
-
-Run tests:
-
-`APP_URL=http://localhost:3000 PORT=3000 DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres FLAG_DISABLE_SIGNUPS=false FLAG_DISABLE_EMAIL_AUTH=false FLAG_DISABLE_API_RATE_LIMIT=true LOCAL_STORAGE_PATH=/workspace/data/e2e pnpm test:e2e`
-
-## Coverage
-
-- Email/password auth smoke.
-- Dashboard sample resume creation.
-- Builder basics edit and autosave persistence.
-- JSON export/import.
-- Public sharing for anonymous visitors.
-
-PDF, DOCX, OAuth, passkeys, 2FA, password reset, and AI flows are intentionally outside the initial PR gate.
-```
-
-- [ ] **Step 2: Commit**
-
-Run:
-
-```bash
-git add tests/e2e/README.md
-git commit -m "docs: document e2e workflow"
-git push -u origin feat/e2e-test-plan-2b10
-```
-
-## Task 6: Add GitHub Actions workflow
-
-**Files:**
-- Create: `.github/workflows/e2e.yml`
-
-- [ ] **Step 1: Add workflow**
-
-Create `.github/workflows/e2e.yml`:
-
-```yaml
-name: E2E Tests
-
-on:
- pull_request:
- push:
- branches: ["main"]
-
-permissions:
- contents: read
-
-env:
- FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
- APP_URL: http://localhost:3000
- PORT: "3000"
- DATABASE_URL: postgresql://postgres:postgres@localhost:5432/postgres
- FLAG_DISABLE_SIGNUPS: "false"
- FLAG_DISABLE_EMAIL_AUTH: "false"
- FLAG_DISABLE_API_RATE_LIMIT: "true"
- LOCAL_STORAGE_PATH: /tmp/reactive-resume-e2e-storage
-
-jobs:
- e2e:
- runs-on: ubuntu-latest
- timeout-minutes: 30
-
- services:
- postgres:
- image: postgres:16
- env:
- POSTGRES_DB: postgres
- POSTGRES_USER: postgres
- POSTGRES_PASSWORD: postgres
- ports:
- - 5432:5432
- options: >-
- --health-cmd "pg_isready -U postgres -d postgres"
- --health-interval 10s
- --health-timeout 5s
- --health-retries 5
-
- steps:
- - name: Checkout Repository
- uses: actions/checkout@v6
- with:
- persist-credentials: false
-
- - name: Install pnpm
- uses: pnpm/action-setup@v6
-
- - name: Setup Node
- uses: actions/setup-node@v6
- with:
- node-version: "24"
- cache: "pnpm"
-
- - name: Install Dependencies
- run: pnpm install --frozen-lockfile
-
- - name: Install Playwright Browser
- run: pnpm exec playwright install --with-deps chromium
-
- - name: Generate Test Secrets
- run: |
- echo "AUTH_SECRET=$(openssl rand -hex 32)" >> "$GITHUB_ENV"
- echo "ENCRYPTION_SECRET=$(openssl rand -hex 32)" >> "$GITHUB_ENV"
-
- - name: Prepare Storage
- run: mkdir -p "$LOCAL_STORAGE_PATH"
-
- - name: Run Database Migrations
- run: pnpm db:migrate
-
- - name: Build
- run: pnpm build
-
- - name: Run E2E Tests
- run: pnpm test:e2e:ci
-
- - name: Upload Playwright Report
- if: always()
- uses: actions/upload-artifact@v7
- with:
- name: playwright-report
- path: |
- playwright-report
- test-results
- if-no-files-found: ignore
- retention-days: 7
-```
-
-- [ ] **Step 2: Commit**
-
-Run:
-
-```bash
-git add .github/workflows/e2e.yml
-git commit -m "ci: run e2e tests on pull requests"
-git push -u origin feat/e2e-test-plan-2b10
-```
-
-## Task 7: Verify and stabilize
-
-**Files:**
-- Modify any E2E files that fail due to actual labels or app behavior.
-- Modify targeted UI files only if no stable accessible locator exists.
-
-- [ ] **Step 1: Run non-mutating checks**
-
-Run: `pnpm exec biome check package.json turbo.json playwright.config.ts tests/e2e .github/workflows/e2e.yml`
-
-Expected: No Biome errors.
-
-- [ ] **Step 2: Run typecheck**
-
-Run: `pnpm typecheck`
-
-Expected: Typecheck passes for all workspaces.
-
-- [ ] **Step 3: Start PostgreSQL**
-
-Run: `sudo docker compose -f compose.dev.yml up -d postgres`
-
-Expected: Postgres container is healthy.
-
-- [ ] **Step 4: Build production app**
-
-Run:
-
-```bash
-export AUTH_SECRET=$(openssl rand -hex 32)
-export ENCRYPTION_SECRET=$(openssl rand -hex 32)
-APP_URL=http://localhost:3000 PORT=3000 DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres FLAG_DISABLE_SIGNUPS=false FLAG_DISABLE_EMAIL_AUTH=false FLAG_DISABLE_API_RATE_LIMIT=true LOCAL_STORAGE_PATH=/workspace/data/e2e pnpm build
-```
-
-Expected: web and server production builds complete.
-
-- [ ] **Step 5: Run E2E suite**
-
-Run:
-
-```bash
-APP_URL=http://localhost:3000 PORT=3000 DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres FLAG_DISABLE_SIGNUPS=false FLAG_DISABLE_EMAIL_AUTH=false FLAG_DISABLE_API_RATE_LIMIT=true LOCAL_STORAGE_PATH=/workspace/data/e2e pnpm test:e2e
-```
-
-Expected: All Chromium specs pass.
-
-- [ ] **Step 6: Commit stabilization changes**
-
-Run:
-
-```bash
-git add .
-git commit -m "test: stabilize e2e suite"
-git push -u origin feat/e2e-test-plan-2b10
-```
-
-## Self-review
-
-- Spec coverage: Tasks cover Playwright setup, production-build target, hybrid fixtures, ephemeral data cleanup, core deterministic flows, CI workflow, and documentation.
-- Placeholder scan: No placeholder steps remain; each task names exact files, commands, and expected outcomes.
-- Type consistency: Fixture types are introduced before specs use them, and all helper names match across tasks.
diff --git a/docs/superpowers/plans/2026-07-07-applications-rest-mcp-parity.md b/docs/superpowers/plans/2026-07-07-applications-rest-mcp-parity.md
deleted file mode 100644
index 318614494..000000000
--- a/docs/superpowers/plans/2026-07-07-applications-rest-mcp-parity.md
+++ /dev/null
@@ -1,1372 +0,0 @@
-# Application Tracker REST and MCP Parity Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Expose every shipped Application Tracker capability through public REST/OpenAPI, Reactive Resume MCP tools, and the bundled `resume-builder` skill.
-
-**Architecture:** Reuse the existing `packages/api/src/features/applications` oRPC procedures and `applicationService` as the single business layer. Add the one missing public REST capability, application document attach/remove, then register MCP tools that call the injected in-process oRPC `RouterClient` rather than importing database code.
-
-**Tech Stack:** TypeScript, oRPC, Zod v4, Drizzle, Vitest, MCP TypeScript SDK, existing Reactive Resume storage service, Biome.
-
-## Global Constraints
-
-- Campaign tracking is out of scope.
-- Fixed stages remain `saved`, `applied`, `screening`, `interview`, `offer`, `rejected`.
-- Public REST endpoints live under `/api/openapi` and are generated from oRPC route metadata.
-- Generic storage routes stay tagged `Internal`; public application document upload/remove belongs under the Applications tag.
-- Application documents are PDFs only.
-- Document uploads keep the existing 10MB storage limit.
-- MCP tool names use canonical unprefixed `snake_case`.
-- MCP handlers use the injected in-process oRPC `RouterClient`.
-- No new dependencies.
-- Do not refactor the Application Tracker UI.
-
----
-
-## File Structure
-
-- Modify `packages/api/src/dto/application.ts`: add document kind/upload/delete DTO schemas.
-- Modify `packages/api/src/dto/application.test.ts`: test document DTO constraints.
-- Modify `packages/api/src/features/applications/service.ts`: add `attachDocument` and `removeDocument` service methods, reusing existing ownership and storage cleanup helpers.
-- Modify `packages/api/src/features/applications/service.test.ts`: cover document attachment/removal behavior and storage cleanup.
-- Modify `packages/api/src/features/applications/crud.ts`: add public REST document routes.
-- Modify `packages/api/src/features/applications/router.ts`: expose document route procedures under `applications`.
-- Modify `packages/mcp/src/mcp-tool-names.ts`: add application MCP tool names.
-- Modify `packages/mcp/src/tool-meta.ts`: add application tool input schemas and metadata.
-- Modify `packages/mcp/src/tool-annotations.ts`: add annotations for new tools.
-- Modify `packages/mcp/src/tools.ts`: register application tool handlers.
-- Modify `packages/mcp/src/tool-annotations.test.ts`, `packages/mcp/src/mcp-server-card.test.ts`, and `packages/mcp/src/tools.test.ts`: cover registration and handler behavior.
-- Modify `skills/resume-builder/SKILL.md`: tell agents application MCP tools exist.
-- Modify `docs/guides/using-the-mcp-server.mdx`: document application tools and examples.
-- Modify `docs/use-cases/api-mcp-resume-automation.mdx`: expand use case from resume-only automation to resume plus application tracking.
-- Modify `docs/spec.json`: refresh OpenAPI output after API route changes.
-
----
-
-### Task 1: Public REST Document Attach/Remove
-
-**Files:**
-- Modify: `packages/api/src/dto/application.ts`
-- Modify: `packages/api/src/dto/application.test.ts`
-- Modify: `packages/api/src/features/applications/service.ts`
-- Modify: `packages/api/src/features/applications/service.test.ts`
-- Modify: `packages/api/src/features/applications/crud.ts`
-- Modify: `packages/api/src/features/applications/router.ts`
-
-**Interfaces:**
-- Consumes: existing `applicationService.update(input)` and existing storage helpers in `packages/api/src/features/storage/service.ts`.
-- Produces:
- - `applicationDto.attachDocument.input`: `{ id: string; kind: "resume" | "cover-letter"; file: File }`
- - `applicationDto.removeDocument.input`: `{ id: string; kind: "resume" | "cover-letter" }`
- - `applicationService.attachDocument(input: { id: string; userId: string; kind: ApplicationDocumentKind; fileName: string; data: Uint8Array; contentType: string }): Promise`
- - `applicationService.removeDocument(input: { id: string; userId: string; kind: ApplicationDocumentKind }): Promise`
- - `crudRouter.attachDocument`
- - `crudRouter.removeDocument`
-
-- [ ] **Step 1: Add failing DTO tests**
-
-Append to `packages/api/src/dto/application.test.ts`:
-
-```ts
-describe("applicationDto document uploads", () => {
- it("accepts PDF application documents", () => {
- const file = new File(["%PDF-1.4"], "resume.pdf", { type: "application/pdf" });
-
- const parsed = applicationDto.attachDocument.input.parse({
- id: "application-1",
- kind: "resume",
- file,
- });
-
- expect(parsed.kind).toBe("resume");
- expect(parsed.file.name).toBe("resume.pdf");
- });
-
- it("rejects non-PDF application documents", () => {
- const file = new File(["hello"], "cover.txt", { type: "text/plain" });
-
- expect(() =>
- applicationDto.attachDocument.input.parse({
- id: "application-1",
- kind: "cover-letter",
- file,
- }),
- ).toThrow();
- });
-
- it("rejects unknown application document kinds", () => {
- const file = new File(["%PDF-1.4"], "resume.pdf", { type: "application/pdf" });
-
- expect(() =>
- applicationDto.attachDocument.input.parse({
- id: "application-1",
- kind: "portfolio",
- file,
- }),
- ).toThrow();
- });
-});
-```
-
-- [ ] **Step 2: Run DTO test to verify it fails**
-
-Run:
-
-```bash
-pnpm --filter @reactive-resume/api test -- src/dto/application.test.ts
-```
-
-Expected: FAIL because `applicationDto.attachDocument` is undefined.
-
-- [ ] **Step 3: Add document DTO schemas**
-
-In `packages/api/src/dto/application.ts`, add near the top-level constants:
-
-```ts
-const MAX_APPLICATION_DOCUMENT_BYTES = 10 * 1024 * 1024;
-
-const applicationDocumentKindSchema = z.enum(["resume", "cover-letter"]);
-
-const applicationDocumentFileSchema = z
- .file()
- .max(MAX_APPLICATION_DOCUMENT_BYTES, "File size must be less than 10MB")
- .mime(["application/pdf"], "Application documents must be PDF files.");
-```
-
-Add to `applicationDto`:
-
-```ts
- attachDocument: {
- input: z.object({
- id: z.string(),
- kind: applicationDocumentKindSchema,
- file: applicationDocumentFileSchema,
- }),
- output: applicationSchema.omit({ userId: true }),
- },
-
- removeDocument: {
- input: z.object({
- id: z.string(),
- kind: applicationDocumentKindSchema,
- }),
- output: applicationSchema.omit({ userId: true }),
- },
-```
-
-Also export the kind type at the end of the file:
-
-```ts
-export type ApplicationDocumentKind = z.infer;
-```
-
-- [ ] **Step 4: Run DTO tests to verify they pass**
-
-Run:
-
-```bash
-pnpm --filter @reactive-resume/api test -- src/dto/application.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 5: Add failing service tests**
-
-Modify the hoisted mocks in `packages/api/src/features/applications/service.test.ts`:
-
-```ts
-const storageDeleteMock = vi.hoisted(() => vi.fn());
-const uploadFileMock = vi.hoisted(() => vi.fn());
-```
-
-Replace the storage service mock with:
-
-```ts
-vi.mock("../storage/service", () => ({
- getStorageService: () => ({ delete: storageDeleteMock }),
- uploadFile: uploadFileMock,
-}));
-```
-
-Add to `beforeEach`:
-
-```ts
- uploadFileMock.mockReset();
- uploadFileMock.mockResolvedValue({ url: "/api/uploads/user-1/pictures/new.pdf", key: "uploads/user-1/pictures/new.pdf" });
-```
-
-Append tests:
-
-```ts
-describe("applicationService.attachDocument", () => {
- it("uploads a PDF resume document and stores it on the application", async () => {
- const set = vi.fn(() => ({ where: () => ({ returning: () => Promise.resolve([{ ...existing }]) }) }));
- dbMock.update.mockReturnValue({ set });
-
- await applicationService.attachDocument({
- id: "app-1",
- userId: "user-1",
- kind: "resume",
- fileName: "sent-resume.pdf",
- contentType: "application/pdf",
- data: new Uint8Array([1, 2, 3]),
- });
-
- expect(uploadFileMock).toHaveBeenCalledWith({
- userId: "user-1",
- contentType: "application/pdf",
- data: new Uint8Array([1, 2, 3]),
- });
- expect(set).toHaveBeenCalledWith(
- expect.objectContaining({
- resumeFileUrl: "/api/uploads/user-1/pictures/new.pdf",
- resumeFileName: "sent-resume.pdf",
- }),
- );
- });
-
- it("rejects non-PDF documents before upload", async () => {
- await expect(
- applicationService.attachDocument({
- id: "app-1",
- userId: "user-1",
- kind: "cover-letter",
- fileName: "cover.txt",
- contentType: "text/plain",
- data: new Uint8Array([1]),
- }),
- ).rejects.toMatchObject({ code: "BAD_REQUEST" });
-
- expect(uploadFileMock).not.toHaveBeenCalled();
- });
-});
-
-describe("applicationService.removeDocument", () => {
- it("clears and deletes an owned cover letter document", async () => {
- const set = vi.fn(() => ({ where: () => ({ returning: () => Promise.resolve([{ ...existing }]) }) }));
- dbMock.update.mockReturnValue({ set });
-
- await applicationService.removeDocument({ id: "app-1", userId: "user-1", kind: "cover-letter" });
-
- expect(set).toHaveBeenCalledWith(
- expect.objectContaining({
- coverLetterUrl: null,
- coverLetterName: null,
- }),
- );
- expect(storageDeleteMock).toHaveBeenCalledWith("uploads/user-1/pictures/cover.pdf");
- });
-});
-```
-
-- [ ] **Step 6: Run service tests to verify they fail**
-
-Run:
-
-```bash
-pnpm --filter @reactive-resume/api test -- src/features/applications/service.test.ts
-```
-
-Expected: FAIL because `applicationService.attachDocument` and `applicationService.removeDocument` are undefined.
-
-- [ ] **Step 7: Add service implementation**
-
-In `packages/api/src/features/applications/service.ts`, update imports:
-
-```ts
-import type { ApplicationDocumentKind } from "../../dto/application";
-import { getStorageService, uploadFile } from "../storage/service";
-```
-
-Add this helper near `deleteApplicationAttachments`:
-
-```ts
-function documentFields(kind: ApplicationDocumentKind) {
- return kind === "resume"
- ? ({
- url: "resumeFileUrl",
- name: "resumeFileName",
- } as const)
- : ({
- url: "coverLetterUrl",
- name: "coverLetterName",
- } as const);
-}
-```
-
-Add methods to `applicationService` after `update`:
-
-```ts
- attachDocument: async (input: {
- id: string;
- userId: string;
- kind: ApplicationDocumentKind;
- fileName: string;
- data: Uint8Array;
- contentType: string;
- }) => {
- if (input.contentType !== "application/pdf") {
- throw new ORPCError("BAD_REQUEST", { message: "Application documents must be PDF files." });
- }
-
- const existing = await requireOwned(input.id, input.userId);
- const fields = documentFields(input.kind);
- const uploaded = await uploadFile({
- userId: input.userId,
- data: input.data,
- contentType: input.contentType,
- });
-
- try {
- const updated = await applicationService.update({
- id: input.id,
- userId: input.userId,
- [fields.url]: uploaded.url,
- [fields.name]: input.fileName,
- });
-
- await deleteApplicationAttachments(input.userId, [
- {
- resumeFileUrl: fields.url === "resumeFileUrl" ? existing.resumeFileUrl : null,
- coverLetterUrl: fields.url === "coverLetterUrl" ? existing.coverLetterUrl : null,
- },
- ]);
-
- return updated;
- } catch (error) {
- await getStorageService().delete(uploaded.key).catch(() => false);
- throw error;
- }
- },
-
- removeDocument: async (input: { id: string; userId: string; kind: ApplicationDocumentKind }) => {
- const existing = await requireOwned(input.id, input.userId);
- const fields = documentFields(input.kind);
- const updated = await applicationService.update({
- id: input.id,
- userId: input.userId,
- [fields.url]: null,
- [fields.name]: null,
- });
-
- await deleteApplicationAttachments(input.userId, [
- {
- resumeFileUrl: fields.url === "resumeFileUrl" ? existing.resumeFileUrl : null,
- coverLetterUrl: fields.url === "coverLetterUrl" ? existing.coverLetterUrl : null,
- },
- ]);
-
- return updated;
- },
-```
-
-- [ ] **Step 8: Run service tests to verify they pass**
-
-Run:
-
-```bash
-pnpm --filter @reactive-resume/api test -- src/features/applications/service.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 9: Add REST routes**
-
-In `packages/api/src/features/applications/crud.ts`, add methods before `stats`:
-
-```ts
- attachDocument: protectedProcedure
- .route({
- method: "POST",
- path: "/applications/{id}/documents/{kind}",
- tags: ["Applications"],
- operationId: "attachApplicationDocument",
- summary: "Attach an application document",
- description:
- "Uploads and attaches a PDF document to an application. Kind must be either resume or cover-letter. Requires authentication.",
- successDescription: "The updated application.",
- requestBodyHint: "form-data",
- })
- .input(applicationDto.attachDocument.input)
- .use(resumeMutationRateLimit)
- .output(applicationDto.attachDocument.output)
- .handler(async ({ input, context }) => {
- const buffer = await input.file.arrayBuffer();
- return applicationService.attachDocument({
- id: input.id,
- userId: context.user.id,
- kind: input.kind,
- fileName: input.file.name,
- contentType: input.file.type,
- data: new Uint8Array(buffer),
- });
- }),
-
- removeDocument: protectedProcedure
- .route({
- method: "DELETE",
- path: "/applications/{id}/documents/{kind}",
- tags: ["Applications"],
- operationId: "removeApplicationDocument",
- summary: "Remove an application document",
- description:
- "Removes a resume or cover-letter PDF from an application and clears the stored document fields. Requires authentication.",
- successDescription: "The updated application.",
- })
- .input(applicationDto.removeDocument.input)
- .use(resumeMutationRateLimit)
- .output(applicationDto.removeDocument.output)
- .handler(async ({ input, context }) => {
- return applicationService.removeDocument({ id: input.id, userId: context.user.id, kind: input.kind });
- }),
-```
-
-In `packages/api/src/features/applications/router.ts`, add:
-
-```ts
- attachDocument: crudRouter.attachDocument,
- removeDocument: crudRouter.removeDocument,
-```
-
-- [ ] **Step 10: Run API typecheck**
-
-Run:
-
-```bash
-pnpm --filter @reactive-resume/api typecheck
-```
-
-Expected: PASS.
-
-- [ ] **Step 11: Commit REST/API task**
-
-Run:
-
-```bash
-git add packages/api/src/dto/application.ts packages/api/src/dto/application.test.ts packages/api/src/features/applications/service.ts packages/api/src/features/applications/service.test.ts packages/api/src/features/applications/crud.ts packages/api/src/features/applications/router.ts
-git commit -m "feat: add application document API"
-```
-
-Expected: commit succeeds.
-
----
-
-### Task 2: MCP Tool Names, Metadata, and Annotations
-
-**Files:**
-- Modify: `packages/mcp/src/mcp-tool-names.ts`
-- Modify: `packages/mcp/src/tool-meta.ts`
-- Modify: `packages/mcp/src/tool-annotations.ts`
-- Modify: `packages/mcp/src/tool-annotations.test.ts`
-- Modify: `packages/mcp/src/mcp-server-card.test.ts`
-
-**Interfaces:**
-- Consumes: `applicationStatusSchema` and `contactSchema` from `@reactive-resume/schema/applications/data`.
-- Produces: new `MCP_TOOL_NAME` values and `TOOL_META` entries used by `registerTools` in Task 3.
-
-- [ ] **Step 1: Add failing MCP metadata tests**
-
-In `packages/mcp/src/tool-annotations.test.ts`, add after the canonical read/patch names test:
-
-```ts
- it("uses canonical application tool names", () => {
- expect(MCP_TOOL_NAME.listApplications).toBe("list_applications");
- expect(MCP_TOOL_NAME.readApplication).toBe("read_application");
- expect(MCP_TOOL_NAME.createApplication).toBe("create_application");
- expect(MCP_TOOL_NAME.attachApplicationDocument).toBe("attach_application_document");
- expect(MCP_TOOL_NAME.autofillApplicationFromJob).toBe("autofill_application_from_job");
- });
-```
-
-In the read-only annotation test list, add:
-
-```ts
- MCP_TOOL_NAME.listApplications,
- MCP_TOOL_NAME.readApplication,
- MCP_TOOL_NAME.listApplicationTags,
- MCP_TOOL_NAME.getApplicationStats,
-```
-
-Add tests before the open-world test:
-
-```ts
- it("marks application delete tools as destructive", () => {
- for (const name of [MCP_TOOL_NAME.deleteApplication, MCP_TOOL_NAME.bulkDeleteApplications]) {
- const annotations = TOOL_ANNOTATIONS[name];
- expect(annotations.readOnlyHint, name).toBe(false);
- expect(annotations.destructiveHint, name).toBe(true);
- }
- });
-
- it("marks only job-posting autofill as open-world", () => {
- expect(TOOL_ANNOTATIONS[MCP_TOOL_NAME.autofillApplicationFromJob].openWorldHint).toBe(true);
- });
-```
-
-In `packages/mcp/src/mcp-server-card.test.ts`, add:
-
-```ts
- it("advertises application tracker tools", () => {
- const names = card.tools.map((tool) => tool.name);
-
- expect(names).toContain("list_applications");
- expect(names).toContain("create_application");
- expect(names).toContain("attach_application_document");
- expect(names).toContain("tailor_resume_for_application");
- });
-```
-
-- [ ] **Step 2: Run MCP metadata tests to verify they fail**
-
-Run:
-
-```bash
-pnpm --filter @reactive-resume/mcp test -- src/tool-annotations.test.ts src/mcp-server-card.test.ts
-```
-
-Expected: FAIL because the new MCP tool names do not exist.
-
-- [ ] **Step 3: Add MCP tool names**
-
-In `packages/mcp/src/mcp-tool-names.ts`, add these properties to `MCP_TOOL_NAME`:
-
-```ts
- listApplications: "list_applications",
- readApplication: "read_application",
- listApplicationTags: "list_application_tags",
- getApplicationStats: "get_application_stats",
- createApplication: "create_application",
- updateApplication: "update_application",
- addApplicationNote: "add_application_note",
- deleteApplication: "delete_application",
- bulkUpdateApplications: "bulk_update_applications",
- bulkDeleteApplications: "bulk_delete_applications",
- importApplications: "import_applications",
- attachApplicationDocument: "attach_application_document",
- removeApplicationDocument: "remove_application_document",
- autofillApplicationFromJob: "autofill_application_from_job",
- scoreApplicationMatch: "score_application_match",
- tailorResumeForApplication: "tailor_resume_for_application",
- draftApplicationMessage: "draft_application_message",
-```
-
-- [ ] **Step 4: Add MCP metadata schemas**
-
-In `packages/mcp/src/tool-meta.ts`, add imports:
-
-```ts
-import { applicationStatusSchema, contactSchema } from "@reactive-resume/schema/applications/data";
-```
-
-Add shared schemas near `resumeIdSchema`:
-
-```ts
-const applicationIdSchema = z.string().min(1).describe(`Application ID. Use \`${T.listApplications}\` to find valid IDs.`);
-const applicationDocumentKindSchema = z.enum(["resume", "cover-letter"]);
-const pdfBase64Schema = z
- .string()
- .min(1)
- .describe("Base64-encoded PDF bytes. Only application/pdf documents are accepted.");
-
-const applicationEditableSchema = {
- company: z.string().min(1).optional().describe("Company name."),
- role: z.string().min(1).optional().describe("Role or job title."),
- status: applicationStatusSchema.optional().describe("Pipeline stage."),
- archived: z.boolean().optional().describe("Whether the application is hidden from active views."),
- location: z.string().nullable().optional(),
- salary: z.string().nullable().optional(),
- source: z.string().nullable().optional(),
- sourceUrl: z.string().url().nullable().optional(),
- jobDescription: z.string().max(20_000).nullable().optional(),
- notes: z.string().nullable().optional(),
- resumeId: z.string().nullable().optional(),
- resumeFileUrl: z.string().nullable().optional(),
- resumeFileName: z.string().nullable().optional(),
- coverLetterUrl: z.string().nullable().optional(),
- coverLetterName: z.string().nullable().optional(),
- followUpAt: z.coerce.date().nullable().optional(),
- followUpNote: z.string().nullable().optional(),
- contacts: z.array(contactSchema).optional(),
- tags: z.array(z.string()).optional(),
-} as const;
-
-const createApplicationSchema = z.object({
- ...applicationEditableSchema,
- company: z.string().min(1).describe("Company name."),
- role: z.string().min(1).describe("Role or job title."),
-});
-```
-
-Add these `TOOL_META` entries after resume tools or in a separate Applications block:
-
-```ts
- [T.listApplications]: {
- title: "List Applications",
- description:
- "List job applications for the authenticated account. Use this before reading or updating existing applications.",
- inputSchema: z.object({
- status: applicationStatusSchema.optional(),
- tags: z.array(z.string()).optional().default([]),
- includeArchived: z.boolean().optional().default(false),
- }),
- annotations: TOOL_ANNOTATIONS[T.listApplications],
- },
- [T.readApplication]: {
- title: "Read Application",
- description: "Read one full job application, including contacts, document URLs, follow-up details, and timeline.",
- inputSchema: z.object({ id: applicationIdSchema }),
- annotations: TOOL_ANNOTATIONS[T.readApplication],
- },
- [T.listApplicationTags]: {
- title: "List Application Tags",
- description: "Return every distinct tag used across job applications.",
- inputSchema: z.object({}),
- annotations: TOOL_ANNOTATIONS[T.listApplicationTags],
- },
- [T.getApplicationStats]: {
- title: "Get Application Stats",
- description: "Return aggregate application counts by pipeline stage and source for insights.",
- inputSchema: z.object({}),
- annotations: TOOL_ANNOTATIONS[T.getApplicationStats],
- },
- [T.createApplication]: {
- title: "Create Application",
- description: "Create a tracked job application. Company and role are required.",
- inputSchema: createApplicationSchema,
- annotations: TOOL_ANNOTATIONS[T.createApplication],
- },
- [T.updateApplication]: {
- title: "Update Application",
- description: "Update application fields, move stages, archive/unarchive, edit contacts, follow-up, tags, or linked resume.",
- inputSchema: z.object({ id: applicationIdSchema, ...applicationEditableSchema }),
- annotations: TOOL_ANNOTATIONS[T.updateApplication],
- },
- [T.addApplicationNote]: {
- title: "Add Application Note",
- description: "Append a free-text note to an application's timeline.",
- inputSchema: z.object({ id: applicationIdSchema, text: z.string().min(1) }),
- annotations: TOOL_ANNOTATIONS[T.addApplicationNote],
- },
- [T.deleteApplication]: {
- title: "Delete Application",
- description: "Permanently delete one job application and its owned uploaded documents.",
- inputSchema: z.object({ id: applicationIdSchema }),
- annotations: TOOL_ANNOTATIONS[T.deleteApplication],
- },
- [T.bulkUpdateApplications]: {
- title: "Bulk Update Applications",
- description: "Move, archive/unarchive, or add tags to multiple applications.",
- inputSchema: z.object({
- ids: z.array(z.string()).min(1),
- status: applicationStatusSchema.optional(),
- archived: z.boolean().optional(),
- addTags: z.array(z.string()).optional(),
- }),
- annotations: TOOL_ANNOTATIONS[T.bulkUpdateApplications],
- },
- [T.bulkDeleteApplications]: {
- title: "Bulk Delete Applications",
- description: "Permanently delete multiple applications.",
- inputSchema: z.object({ ids: z.array(z.string()).min(1) }),
- annotations: TOOL_ANNOTATIONS[T.bulkDeleteApplications],
- },
- [T.importApplications]: {
- title: "Import Applications",
- description: "Bulk-create application rows parsed from CSV or another source. Maximum 500 items.",
- inputSchema: z.object({ items: z.array(createApplicationSchema).min(1).max(500) }),
- annotations: TOOL_ANNOTATIONS[T.importApplications],
- },
- [T.attachApplicationDocument]: {
- title: "Attach Application Document",
- description: "Attach a sent resume or cover-letter PDF to an application using base64-encoded PDF bytes.",
- inputSchema: z.object({
- id: applicationIdSchema,
- kind: applicationDocumentKindSchema,
- fileName: z.string().min(1),
- contentType: z.literal("application/pdf"),
- dataBase64: pdfBase64Schema,
- }),
- annotations: TOOL_ANNOTATIONS[T.attachApplicationDocument],
- },
- [T.removeApplicationDocument]: {
- title: "Remove Application Document",
- description: "Remove a sent resume or cover-letter PDF from an application.",
- inputSchema: z.object({ id: applicationIdSchema, kind: applicationDocumentKindSchema }),
- annotations: TOOL_ANNOTATIONS[T.removeApplicationDocument],
- },
- [T.autofillApplicationFromJob]: {
- title: "Autofill Application From Job",
- description: "Use AI to extract company, role, location, salary, and job description from a job URL or pasted posting.",
- inputSchema: z.object({
- sourceUrl: z.string().url().optional(),
- jobDescription: z.string().max(20_000).optional(),
- }),
- annotations: TOOL_ANNOTATIONS[T.autofillApplicationFromJob],
- },
- [T.scoreApplicationMatch]: {
- title: "Score Application Match",
- description: "Score the linked resume against the application's job description and persist match metadata.",
- inputSchema: z.object({ id: applicationIdSchema }),
- annotations: TOOL_ANNOTATIONS[T.scoreApplicationMatch],
- },
- [T.tailorResumeForApplication]: {
- title: "Tailor Resume For Application",
- description: "Create and link a tailored copy of the application's linked resume.",
- inputSchema: z.object({ id: applicationIdSchema }),
- annotations: TOOL_ANNOTATIONS[T.tailorResumeForApplication],
- },
- [T.draftApplicationMessage]: {
- title: "Draft Application Message",
- description: "Draft either a cover letter or recruiter follow-up from application and resume context.",
- inputSchema: z.object({ id: applicationIdSchema, kind: z.enum(["cover-letter", "follow-up"]) }),
- annotations: TOOL_ANNOTATIONS[T.draftApplicationMessage],
- },
-```
-
-- [ ] **Step 5: Add annotations**
-
-In `packages/mcp/src/tool-annotations.ts`, add:
-
-```ts
-const READ_OPEN_WORLD_NON_IDEMPOTENT: ToolAnnotations = {
- readOnlyHint: true,
- destructiveHint: false,
- idempotentHint: false,
- openWorldHint: true,
-};
-```
-
-Add mappings:
-
-```ts
- [MCP_TOOL_NAME.listApplications]: READ_IDEMPOTENT,
- [MCP_TOOL_NAME.readApplication]: READ_IDEMPOTENT,
- [MCP_TOOL_NAME.listApplicationTags]: READ_IDEMPOTENT,
- [MCP_TOOL_NAME.getApplicationStats]: READ_IDEMPOTENT,
- [MCP_TOOL_NAME.createApplication]: WRITE_NON_IDEMPOTENT,
- [MCP_TOOL_NAME.updateApplication]: WRITE_IDEMPOTENT,
- [MCP_TOOL_NAME.addApplicationNote]: WRITE_NON_IDEMPOTENT,
- [MCP_TOOL_NAME.deleteApplication]: WRITE_DESTRUCTIVE,
- [MCP_TOOL_NAME.bulkUpdateApplications]: WRITE_IDEMPOTENT,
- [MCP_TOOL_NAME.bulkDeleteApplications]: WRITE_DESTRUCTIVE,
- [MCP_TOOL_NAME.importApplications]: WRITE_NON_IDEMPOTENT,
- [MCP_TOOL_NAME.attachApplicationDocument]: WRITE_NON_IDEMPOTENT,
- [MCP_TOOL_NAME.removeApplicationDocument]: WRITE_IDEMPOTENT,
- [MCP_TOOL_NAME.autofillApplicationFromJob]: READ_OPEN_WORLD_NON_IDEMPOTENT,
- [MCP_TOOL_NAME.scoreApplicationMatch]: WRITE_NON_IDEMPOTENT,
- [MCP_TOOL_NAME.tailorResumeForApplication]: WRITE_NON_IDEMPOTENT,
- [MCP_TOOL_NAME.draftApplicationMessage]: READ_NON_IDEMPOTENT,
-```
-
-Update the existing "declares no tools as open-world by default" test to skip `MCP_TOOL_NAME.autofillApplicationFromJob`:
-
-```ts
- for (const [name, annotations] of Object.entries(TOOL_ANNOTATIONS)) {
- if (name === MCP_TOOL_NAME.autofillApplicationFromJob) continue;
- expect(annotations.openWorldHint).toBe(false);
- }
-```
-
-- [ ] **Step 6: Run MCP metadata tests**
-
-Run:
-
-```bash
-pnpm --filter @reactive-resume/mcp test -- src/tool-annotations.test.ts src/mcp-server-card.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 7: Commit metadata task**
-
-Run:
-
-```bash
-git add packages/mcp/src/mcp-tool-names.ts packages/mcp/src/tool-meta.ts packages/mcp/src/tool-annotations.ts packages/mcp/src/tool-annotations.test.ts packages/mcp/src/mcp-server-card.test.ts
-git commit -m "feat: describe application MCP tools"
-```
-
-Expected: commit succeeds.
-
----
-
-### Task 3: MCP Application Tool Handlers
-
-**Files:**
-- Modify: `packages/mcp/src/tools.ts`
-- Modify: `packages/mcp/src/tools.test.ts`
-
-**Interfaces:**
-- Consumes: `MCP_TOOL_NAME` values and `TOOL_META` entries from Task 2.
-- Consumes: API procedures exposed from Task 1.
-- Produces: registered MCP handlers for every application tool.
-
-- [ ] **Step 1: Add failing handler tests**
-
-In `packages/mcp/src/tools.test.ts`, change `ToolHandler` to accept any object:
-
-```ts
-type ToolHandler = (input: Record) => Promise<{
- content: Array<{ type: "text"; text: string }>;
- isError?: boolean;
-}>;
-```
-
-Extend `clientMock` with:
-
-```ts
- applications: {
- list: vi.fn(),
- getById: vi.fn(),
- tags: vi.fn(),
- stats: vi.fn(),
- create: vi.fn(),
- update: vi.fn(),
- addNote: vi.fn(),
- delete: vi.fn(),
- bulkUpdate: vi.fn(),
- bulkDelete: vi.fn(),
- import: vi.fn(),
- attachDocument: vi.fn(),
- removeDocument: vi.fn(),
- ai: {
- autofill: vi.fn(),
- matchScore: vi.fn(),
- tailorResume: vi.fn(),
- draftMessage: vi.fn(),
- },
- },
-```
-
-Add tests:
-
-```ts
- it("registers application tracker tools", () => {
- const { server, registered } = makeFakeServer();
- registerTools(server as never, clientMock as never, new Headers());
-
- const names = registered.map((item) => item.name);
- expect(names).toContain("list_applications");
- expect(names).toContain("create_application");
- expect(names).toContain("attach_application_document");
- expect(names).toContain("draft_application_message");
- });
-
- it("lists applications as JSON", async () => {
- clientMock.applications.list.mockResolvedValueOnce([{ id: "app-1", company: "Acme", role: "Engineer" }]);
- const { server, registered } = makeFakeServer();
- registerTools(server as never, clientMock as never, new Headers());
-
- const tool = registered.find((item) => item.name === "list_applications")!;
- const result = await tool.handler({ includeArchived: true, tags: ["remote"] });
-
- expect(clientMock.applications.list).toHaveBeenCalledWith({ includeArchived: true, tags: ["remote"] });
- expect(JSON.parse(result.content[0]!.text)).toEqual([{ id: "app-1", company: "Acme", role: "Engineer" }]);
- });
-
- it("creates applications through the router client", async () => {
- clientMock.applications.create.mockResolvedValueOnce("app-1");
- const { server, registered } = makeFakeServer();
- registerTools(server as never, clientMock as never, new Headers());
-
- const tool = registered.find((item) => item.name === "create_application")!;
- const result = await tool.handler({ company: "Acme", role: "Engineer", status: "saved" });
-
- expect(clientMock.applications.create).toHaveBeenCalledWith({
- company: "Acme",
- role: "Engineer",
- status: "saved",
- });
- expect(JSON.parse(result.content[0]!.text)).toEqual({ id: "app-1" });
- });
-
- it("attaches a base64 PDF document through the router client", async () => {
- clientMock.applications.attachDocument.mockResolvedValueOnce({ id: "app-1", resumeFileName: "resume.pdf" });
- const { server, registered } = makeFakeServer();
- registerTools(server as never, clientMock as never, new Headers());
-
- const tool = registered.find((item) => item.name === "attach_application_document")!;
- const result = await tool.handler({
- id: "app-1",
- kind: "resume",
- fileName: "resume.pdf",
- contentType: "application/pdf",
- dataBase64: Buffer.from("%PDF-1.4").toString("base64"),
- });
-
- const call = clientMock.applications.attachDocument.mock.calls[0]?.[0] as { file: File };
- expect(call.file).toBeInstanceOf(File);
- expect(call.file.name).toBe("resume.pdf");
- expect(call.file.type).toBe("application/pdf");
- expect(JSON.parse(result.content[0]!.text)).toEqual({ id: "app-1", resumeFileName: "resume.pdf" });
- });
-
- it("rejects non-PDF application document attachments before calling the client", async () => {
- const { server, registered } = makeFakeServer();
- registerTools(server as never, clientMock as never, new Headers());
-
- const tool = registered.find((item) => item.name === "attach_application_document")!;
- const result = await tool.handler({
- id: "app-1",
- kind: "resume",
- fileName: "resume.txt",
- contentType: "text/plain",
- dataBase64: Buffer.from("hello").toString("base64"),
- });
-
- expect(result.isError).toBe(true);
- expect(clientMock.applications.attachDocument).not.toHaveBeenCalled();
- });
-```
-
-- [ ] **Step 2: Run handler tests to verify they fail**
-
-Run:
-
-```bash
-pnpm --filter @reactive-resume/mcp test -- src/tools.test.ts
-```
-
-Expected: FAIL because application tools are not registered.
-
-- [ ] **Step 3: Add JSON and File helpers**
-
-In `packages/mcp/src/tools.ts`, add an import:
-
-```ts
-import { Buffer } from "node:buffer";
-```
-
-Add helper near `text()`:
-
-```ts
-function json(value: unknown): CallToolResult {
- return text(JSON.stringify(value, null, 2));
-}
-
-function fileFromBase64(input: { fileName: string; contentType: string; dataBase64: string }): File {
- if (input.contentType !== "application/pdf") throw new Error("Application documents must be PDF files.");
-
- const bytes = Buffer.from(input.dataBase64, "base64");
- if (bytes.length === 0) throw new Error("Application document cannot be empty.");
-
- return new File([bytes], input.fileName, { type: input.contentType });
-}
-```
-
-- [ ] **Step 4: Register read/discovery handlers**
-
-In `registerTools`, after resume statistics or in a clearly labelled Applications block, add:
-
-```ts
- server.registerTool(
- T.listApplications,
- TOOL_META[T.listApplications],
- withErrorHandling("listing applications", async (params) => {
- return json(await client.applications.list(params as { status?: never; tags?: string[]; includeArchived?: boolean }));
- }),
- );
-
- server.registerTool(
- T.readApplication,
- TOOL_META[T.readApplication],
- withErrorHandling("reading application", async ({ id }: { id: string }) => {
- return json(await client.applications.getById({ id }));
- }),
- );
-
- server.registerTool(
- T.listApplicationTags,
- TOOL_META[T.listApplicationTags],
- withErrorHandling("listing application tags", async () => {
- return json(await client.applications.tags());
- }),
- );
-
- server.registerTool(
- T.getApplicationStats,
- TOOL_META[T.getApplicationStats],
- withErrorHandling("getting application stats", async () => {
- return json(await client.applications.stats());
- }),
- );
-```
-
-- [ ] **Step 5: Register write handlers**
-
-Add:
-
-```ts
- server.registerTool(
- T.createApplication,
- TOOL_META[T.createApplication],
- withErrorHandling("creating application", async (params) => {
- const id = await client.applications.create(params as never);
- return json({ id });
- }),
- );
-
- server.registerTool(
- T.updateApplication,
- TOOL_META[T.updateApplication],
- withErrorHandling("updating application", async (params) => {
- return json(await client.applications.update(params as never));
- }),
- );
-
- server.registerTool(
- T.addApplicationNote,
- TOOL_META[T.addApplicationNote],
- withErrorHandling("adding application note", async ({ id, text: noteText }: { id: string; text: string }) => {
- return json(await client.applications.addNote({ id, text: noteText }));
- }),
- );
-
- server.registerTool(
- T.deleteApplication,
- TOOL_META[T.deleteApplication],
- withErrorHandling("deleting application", async ({ id }: { id: string }) => {
- await client.applications.delete({ id });
- return text(`Deleted application (${id}).`);
- }),
- );
-
- server.registerTool(
- T.bulkUpdateApplications,
- TOOL_META[T.bulkUpdateApplications],
- withErrorHandling("bulk updating applications", async (params) => {
- return json(await client.applications.bulkUpdate(params as never));
- }),
- );
-
- server.registerTool(
- T.bulkDeleteApplications,
- TOOL_META[T.bulkDeleteApplications],
- withErrorHandling("bulk deleting applications", async ({ ids }: { ids: string[] }) => {
- return json(await client.applications.bulkDelete({ ids }));
- }),
- );
-
- server.registerTool(
- T.importApplications,
- TOOL_META[T.importApplications],
- withErrorHandling("importing applications", async (params) => {
- return json(await client.applications.import(params as never));
- }),
- );
-```
-
-- [ ] **Step 6: Register document handlers**
-
-Add:
-
-```ts
- server.registerTool(
- T.attachApplicationDocument,
- TOOL_META[T.attachApplicationDocument],
- withErrorHandling(
- "attaching application document",
- async ({
- id,
- kind,
- fileName,
- contentType,
- dataBase64,
- }: {
- id: string;
- kind: "resume" | "cover-letter";
- fileName: string;
- contentType: string;
- dataBase64: string;
- }) => {
- const file = fileFromBase64({ fileName, contentType, dataBase64 });
- return json(await client.applications.attachDocument({ id, kind, file }));
- },
- ),
- );
-
- server.registerTool(
- T.removeApplicationDocument,
- TOOL_META[T.removeApplicationDocument],
- withErrorHandling(
- "removing application document",
- async ({ id, kind }: { id: string; kind: "resume" | "cover-letter" }) => {
- return json(await client.applications.removeDocument({ id, kind }));
- },
- ),
- );
-```
-
-- [ ] **Step 7: Register AI handlers**
-
-Add:
-
-```ts
- server.registerTool(
- T.autofillApplicationFromJob,
- TOOL_META[T.autofillApplicationFromJob],
- withErrorHandling("autofilling application from job", async (params) => {
- return json(await client.applications.ai.autofill(params as { sourceUrl?: string; jobDescription?: string }));
- }),
- );
-
- server.registerTool(
- T.scoreApplicationMatch,
- TOOL_META[T.scoreApplicationMatch],
- withErrorHandling("scoring application match", async ({ id }: { id: string }) => {
- return json(await client.applications.ai.matchScore({ id }));
- }),
- );
-
- server.registerTool(
- T.tailorResumeForApplication,
- TOOL_META[T.tailorResumeForApplication],
- withErrorHandling("tailoring resume for application", async ({ id }: { id: string }) => {
- return json(await client.applications.ai.tailorResume({ id }));
- }),
- );
-
- server.registerTool(
- T.draftApplicationMessage,
- TOOL_META[T.draftApplicationMessage],
- withErrorHandling("drafting application message", async ({ id, kind }: { id: string; kind: "cover-letter" | "follow-up" }) => {
- return json(await client.applications.ai.draftMessage({ id, kind }));
- }),
- );
-```
-
-- [ ] **Step 8: Run MCP handler tests**
-
-Run:
-
-```bash
-pnpm --filter @reactive-resume/mcp test -- src/tools.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 9: Run MCP typecheck**
-
-Run:
-
-```bash
-pnpm --filter @reactive-resume/mcp typecheck
-```
-
-Expected: PASS.
-
-- [ ] **Step 10: Commit MCP handler task**
-
-Run:
-
-```bash
-git add packages/mcp/src/tools.ts packages/mcp/src/tools.test.ts
-git commit -m "feat: add application MCP tools"
-```
-
-Expected: commit succeeds.
-
----
-
-### Task 4: Skill, MCP Docs, and OpenAPI Spec
-
-**Files:**
-- Modify: `skills/resume-builder/SKILL.md`
-- Modify: `docs/guides/using-the-mcp-server.mdx`
-- Modify: `docs/use-cases/api-mcp-resume-automation.mdx`
-- Modify: `docs/spec.json`
-
-**Interfaces:**
-- Consumes: MCP tool names from Task 2 and route changes from Task 1.
-- Produces: user-facing docs and skill guidance that describe application tracking through MCP.
-
-- [ ] **Step 1: Update the resume-builder skill**
-
-In `skills/resume-builder/SKILL.md`, add after the Workflow section heading and before "Step 1":
-
-```md
-### MCP Application Tracking
-
-Reactive Resume MCP can manage job applications as well as resumes. When the user wants to track applications through an agent, use the application tools instead of asking them to open the web UI.
-
-- Use `list_applications` before changing existing records.
-- Use `create_application` for one new opportunity or `import_applications` for spreadsheet/CSV rows.
-- Use `update_application` to move stages, archive/unarchive, edit contacts, set follow-ups, link a resume, or update job details.
-- Use `add_application_note` to log timeline activity.
-- Use `attach_application_document` and `remove_application_document` for sent resume or cover-letter PDFs.
-- Use `score_application_match`, `tailor_resume_for_application`, and `draft_application_message` for Application Copilot workflows after a linked resume and job description exist.
-- Review AI-generated cover letters and follow-ups before sending them.
-```
-
-- [ ] **Step 2: Update the MCP server guide tool table**
-
-In `docs/guides/using-the-mcp-server.mdx`, extend the Available Tools table with:
-
-```md
-| `list_applications` | List tracked job applications. Supports stage, tag, and archived filters |
-| `read_application` | Read one full application record with contacts, follow-up details, documents, and timeline |
-| `list_application_tags` | List every distinct tag used across applications |
-| `get_application_stats` | Get aggregate application counts by stage and source |
-| `create_application` | Create a tracked job application |
-| `update_application` | Update fields, move stage, archive/unarchive, edit contacts/follow-ups/tags, or link a resume |
-| `add_application_note` | Append a note to an application's activity timeline |
-| `delete_application` | Permanently delete one application and its owned uploaded documents |
-| `bulk_update_applications` | Move, archive/unarchive, or add tags to multiple applications |
-| `bulk_delete_applications` | Permanently delete multiple applications |
-| `import_applications` | Bulk-create parsed application rows, up to 500 items |
-| `attach_application_document` | Attach a sent resume or cover-letter PDF from base64-encoded PDF bytes |
-| `remove_application_document` | Remove a sent resume or cover-letter PDF |
-| `autofill_application_from_job` | Use AI to extract job details from a URL or pasted job description |
-| `score_application_match` | Score the linked resume against the application job description |
-| `tailor_resume_for_application` | Create and link a tailored resume copy for an application |
-| `draft_application_message` | Draft a cover letter or recruiter follow-up from application and resume context |
-```
-
-- [ ] **Step 3: Add application MCP usage examples**
-
-In the Usage Examples section of `docs/guides/using-the-mcp-server.mdx`, add a subsection after Browsing:
-
-```md
-### Tracking Applications
-
-- "Create an application for Senior Frontend Engineer at Acme, stage saved, source LinkedIn."
-- "List my archived applications tagged remote."
-- "Move my Acme application to interview and add a note that the technical screen is next Tuesday."
-- "Attach this resume PDF to the Acme application."
-- "Score the resume linked to this application against the job description."
-- "Create a tailored resume copy for this application."
-- "Draft a follow-up message for the recruiter."
-```
-
-Add a troubleshooting row:
-
-```md
-| "Application documents must be PDF files" | `attach_application_document` only accepts `contentType: "application/pdf"` and base64-encoded PDF bytes |
-```
-
-- [ ] **Step 4: Update the API/MCP automation use case**
-
-Replace the first paragraph in `docs/use-cases/api-mcp-resume-automation.mdx` with:
-
-```md
-Reactive Resume supports automation through authenticated API access and an MCP server that lets compatible tools work with resumes and job applications. Agents can list, read, create, import, duplicate, and patch resumes, then track applications, move opportunities through stages, add notes and follow-ups, attach sent documents, and run Application Copilot actions.
-```
-
-Add to "Common automation workflows":
-
-```md
-- Track job applications end to end from an MCP client.
-- Import existing application rows from a spreadsheet parser.
-- Move applications through stages and log timeline notes.
-- Attach the resume or cover-letter PDF sent for an application.
-- Score a linked resume against a job description and create a tailored resume copy.
-- Draft cover letters and recruiter follow-ups from saved application context.
-```
-
-- [ ] **Step 5: Refresh docs/spec.json**
-
-Start the dev server in one terminal:
-
-```bash
-dotenvx run -f .env.local -- pnpm dev
-```
-
-In another terminal, after the server reports it is listening on port 3000, run:
-
-```bash
-curl -fsS http://localhost:3000/api/openapi/spec.json -o docs/spec.json
-```
-
-Expected: `docs/spec.json` contains `/applications` paths:
-
-```bash
-rg -n '"/applications|attachApplicationDocument|removeApplicationDocument' docs/spec.json
-```
-
-Expected: matches for the application paths and document operations.
-
-- [ ] **Step 6: Run docs/skill checks**
-
-Run:
-
-```bash
-rg -n "list_applications|attach_application_document|tailor_resume_for_application" skills/resume-builder/SKILL.md docs/guides/using-the-mcp-server.mdx docs/use-cases/api-mcp-resume-automation.mdx
-rg -n '"/applications|attachApplicationDocument|removeApplicationDocument' docs/spec.json
-```
-
-Expected: all commands print matching lines.
-
-- [ ] **Step 7: Commit docs task**
-
-Run:
-
-```bash
-git add skills/resume-builder/SKILL.md docs/guides/using-the-mcp-server.mdx docs/use-cases/api-mcp-resume-automation.mdx docs/spec.json
-git commit -m "docs: document application MCP automation"
-```
-
-Expected: commit succeeds.
-
----
-
-### Task 5: Final Validation and Boundary Check
-
-**Files:**
-- No planned source edits.
-
-**Interfaces:**
-- Consumes: all previous task outputs.
-- Produces: verified implementation ready for review.
-
-- [ ] **Step 1: Run focused tests**
-
-Run:
-
-```bash
-pnpm --filter @reactive-resume/api test -- src/dto/application.test.ts src/features/applications/service.test.ts
-pnpm --filter @reactive-resume/mcp test -- src/tools.test.ts src/tool-annotations.test.ts src/mcp-server-card.test.ts
-```
-
-Expected: PASS.
-
-- [ ] **Step 2: Run focused typechecks**
-
-Run:
-
-```bash
-pnpm --filter @reactive-resume/api typecheck
-pnpm --filter @reactive-resume/mcp typecheck
-```
-
-Expected: PASS.
-
-- [ ] **Step 3: Run boundary check**
-
-Run:
-
-```bash
-pnpm exec turbo boundaries
-```
-
-Expected: PASS.
-
-- [ ] **Step 4: Run non-mutating Biome check on touched files**
-
-Run:
-
-```bash
-pnpm exec biome check packages/api/src/dto/application.ts packages/api/src/dto/application.test.ts packages/api/src/features/applications/service.ts packages/api/src/features/applications/service.test.ts packages/api/src/features/applications/crud.ts packages/api/src/features/applications/router.ts packages/mcp/src/mcp-tool-names.ts packages/mcp/src/tool-meta.ts packages/mcp/src/tool-annotations.ts packages/mcp/src/tools.ts packages/mcp/src/tool-annotations.test.ts packages/mcp/src/mcp-server-card.test.ts packages/mcp/src/tools.test.ts skills/resume-builder/SKILL.md docs/guides/using-the-mcp-server.mdx docs/use-cases/api-mcp-resume-automation.mdx docs/spec.json
-```
-
-Expected: PASS. If Biome reports formatting fixes, run the same command with `--write`, inspect the diff, and commit only formatting changes.
-
-- [ ] **Step 5: Inspect final diff**
-
-Run:
-
-```bash
-git status --short
-git log --oneline -5
-```
-
-Expected: worktree is clean after the task commits, and recent commits are the REST/API, MCP metadata, MCP handler, and docs commits from this plan.
diff --git a/docs/superpowers/specs/2026-05-11-react-pdf-html-prose-spacing-design.md b/docs/superpowers/specs/2026-05-11-react-pdf-html-prose-spacing-design.md
deleted file mode 100644
index 00ed00b11..000000000
--- a/docs/superpowers/specs/2026-05-11-react-pdf-html-prose-spacing-design.md
+++ /dev/null
@@ -1,55 +0,0 @@
-# React PDF HTML Prose Spacing Design
-
-## Context
-
-Resume rich-text fields are rendered in PDF through `packages/pdf/src/templates/shared/rich-text.tsx`, which wraps normalized HTML with `react-pdf-html`. Each template currently supplies body-derived styles such as `richParagraph`, `richListItemRow`, `richListItemMarker`, and `richListItemContent`. Those styles intentionally keep rich text aligned with the template typography.
-
-The current PDF rich-text spacing differs from what users see in Tailwind Typography prose. Paragraphs and list items are effectively flattened by zero margins, while browser prose gives paragraphs and list items vertical rhythm and trims the outside edges of the rich-text flow.
-
-## Goals
-
-- Add vertical spacing to `react-pdf-html` paragraphs and list items in the shared `RichText` path.
-- Match Tailwind Typography `prose-sm` spacing proportions without importing Tailwind's browser font size into PDF output.
-- Preserve each resume template's body font size and line height for rich text and adjacent non-rich-text PDF elements.
-- Remove the outer top margin from the first renderable rich-text block and the outer bottom margin from the last renderable rich-text block.
-- Keep the change shared and template-compatible unless a future template needs an explicit exception.
-
-## Non-Goals
-
-- Do not change web editor `.wysiwyg` styles.
-- Do not change template body or heading font sizes.
-- Do not add a new PDF typography system.
-- Do not restyle headings, blockquotes, tables, or other HTML tags beyond paragraph and list item spacing.
-
-## Recommended Approach
-
-Use Tailwind Typography `prose-sm` spacing ratios and derive the final PDF spacing from the current template body font size. Tailwind Typography's `prose-sm` paragraph spacing is `16 / 14` of the body size, and list item spacing is `4 / 14` of the body size. The PDF renderer should use those ratios against the resolved body font size already present in the template styles.
-
-This keeps rich-text content visually consistent with Tailwind Typography while respecting the resume template's PDF typography scale.
-
-## Implementation Shape
-
-The shared `RichText` component should:
-
-1. Continue normalizing input through `normalizeRichTextHtml`.
-2. Inspect the normalized HTML to identify renderable top-level prose blocks relevant to this change: paragraphs and list items.
-3. Apply derived paragraph spacing to `p` through the `react-pdf-html` stylesheet.
-4. Apply derived list item spacing to the custom `li` renderer row container.
-5. Trim `marginTop` on the first relevant rich-text element and `marginBottom` on the last relevant rich-text element.
-6. Merge spacing after template styles where needed so old `margin: 0` template defaults do not suppress the new shared prose rhythm.
-
-For list items, the spacing belongs on the custom `li` row container. Marker and content styles should continue coming from template slots so bullets, numbers, font size, and line height remain template-owned.
-
-## Testing
-
-Add focused tests around the shared rich-text spacing behavior. Coverage should include:
-
-- A single paragraph has both outer margins trimmed.
-- Multiple paragraphs keep internal paragraph spacing and trim only the first top and last bottom edge.
-- Multiple list items get list-item vertical spacing with first top and last bottom trimmed.
-- Mixed paragraph/list content trims the first and last relevant elements across element types.
-- Rich-text font sizing remains template-derived rather than hard-coded to Tailwind's browser `14px`.
-
-## Open Decisions
-
-No open decisions remain. The approved behavior is to use Tailwind Typography spacing ratios derived from the resume template body font size.
diff --git a/docs/superpowers/specs/2026-05-15-docker-nightly-release-tags-design.md b/docs/superpowers/specs/2026-05-15-docker-nightly-release-tags-design.md
deleted file mode 100644
index 3f6d343a9..000000000
--- a/docs/superpowers/specs/2026-05-15-docker-nightly-release-tags-design.md
+++ /dev/null
@@ -1,94 +0,0 @@
-# Docker Nightly and Release Tagging Design
-
-## Goal
-
-Update `.github/workflows/docker-build.yml` so the existing Docker build pipeline supports two publishing modes without duplicating the workflow:
-
-- Nightly publishing on pushes to the default branch, `main`.
-- Release publishing only on manual workflow runs or pushed Git tags.
-
-## Trigger Rules
-
-The workflow should run for:
-
-- `workflow_dispatch`, which publishes release tags.
-- `push` to `main`, which publishes nightly tags only.
-- `push` to Git tags matching `v*`, which publishes release tags.
-
-Pull request events should not publish Docker images. This avoids exposing registry credentials to PR contexts and keeps nightly publishing tied to commits that have actually landed on `main`.
-
-## Publishing Modes
-
-### Nightly Mode
-
-Nightly mode applies when:
-
-- `github.event_name == "push"`
-- `github.ref == "refs/heads/main"`
-
-Nightly mode should push these tags to both GHCR and Docker Hub:
-
-- `nightly`
-- `nightly-{timestamp}`
-
-The timestamp should be generated by the workflow at publish time in UTC using `YYYYMMDDHHmmss`, for example `nightly-20260515143000`.
-
-Nightly builds should use only the `linux/amd64` platform. They should not build or publish `linux/arm64`.
-
-### Release Mode
-
-Release mode applies when:
-
-- The workflow is run manually with `workflow_dispatch`.
-- A Git tag is pushed.
-
-Release mode should preserve the existing release tag behavior:
-
-- `latest`
-- `v{VERSION}` from root `package.json`
-- `v{MAJOR}.{MINOR}`
-- `v{MAJOR}`
-
-Release builds should preserve the current multi-platform behavior:
-
-- `linux/amd64`
-- `linux/arm64`
-
-## Workflow Shape
-
-Keep a single `.github/workflows/docker-build.yml` file. The current workflow already has the useful structure:
-
-1. Build per-platform images and push them by digest.
-2. Upload digest artifacts.
-3. Merge digests into final manifest tags.
-4. Sign and inspect final images.
-5. Redeploy the stack.
-
-The implementation should add a small mode-detection step or expression-based conditions rather than creating a second near-identical workflow.
-
-The build matrix should include both architectures, but the arm64 build should be skipped during nightly mode. This keeps release behavior unchanged while making nightly pushes cheaper and faster.
-
-The merge job should generate final tags conditionally:
-
-- Nightly mode emits `nightly` and `nightly-{timestamp}`.
-- Release mode emits `latest` and version aliases.
-
-The merge job should inspect and sign whichever final manifest tag is authoritative for the current mode:
-
-- Nightly mode can inspect/sign `nightly`.
-- Release mode can inspect/sign `v{VERSION}`.
-
-## Deployment
-
-The existing `Redeploy Stack` step should remain release-only. Nightly pushes should publish images but should not redeploy the running stack.
-
-## Validation
-
-Validate the change by reviewing the workflow syntax and checking that:
-
-- A `push` to `main` resolves to a single `linux/amd64` build and nightly tags.
-- A `workflow_dispatch` run resolves to both architectures and release tags.
-- A pushed Git tag resolves to both architectures and release tags.
-- No PR event can publish images.
-
-If local workflow lint tooling is unavailable, inspect the YAML and relevant GitHub Actions expressions directly.
diff --git a/docs/superpowers/specs/2026-05-15-manifest-only-pwa-design.md b/docs/superpowers/specs/2026-05-15-manifest-only-pwa-design.md
deleted file mode 100644
index 43dfeda93..000000000
--- a/docs/superpowers/specs/2026-05-15-manifest-only-pwa-design.md
+++ /dev/null
@@ -1,99 +0,0 @@
-# Manifest-Only PWA Design
-
-Date: 2026-05-15
-
-## Goal
-
-Reduce Reactive Resume's PWA implementation to install metadata only.
-
-The site should remain installable on supported phones and desktops through the web app manifest, icons,
-screenshots, and mobile app meta tags. The PWA implementation should not generate, register, or rely on a
-service worker, and it should not provide offline support, app-shell precaching, runtime caching, or fallback
-navigation.
-
-## Non-Goals
-
-- Do not add offline support.
-- Do not add a no-op service worker.
-- Do not add runtime caching rules for app assets, API responses, uploaded files, generated PDFs, or routes.
-- Do not change product UI, routing, auth, resume editing, public resume pages, or PDF generation behavior.
-- Do not change normal browser or HTTP caching behavior owned by the browser or server.
-
-## Architecture
-
-Keep install metadata in `apps/web/public/manifest.webmanifest`. That static manifest remains the source of truth
-for app name, description, theme color, background color, icons, screenshots, categories, scope, and start URL.
-
-Keep mobile install/open-as-app meta tags in `apps/web/src/libs/pwa.ts`. That module continues to own:
-
-- `pwaHeadMetaTags`
-- app name and theme color used by those head meta tags
-
-Add the same manifest, icon, and mobile install hints directly to `apps/web/index.html` so install metadata is
-present in the initial HTML without relying on `vite-plugin-pwa` HTML injection or client-side route head updates.
-
-Remove the service-worker part of the current architecture:
-
-- Remove `VitePWA` usage from `apps/web/vite.config.ts`.
-- Remove the `vite-plugin-pwa` dependency from `apps/web/package.json` and the lockfile.
-- Remove the now-unused `pwaManifest` and `pwaServiceWorkerRegistrationScript` exports from `apps/web/src/libs/pwa.ts`.
-- Stop injecting the production `navigator.serviceWorker.register("/sw.js", { scope: "/" })` script from
- `apps/web/src/routes/__root.tsx`.
-
-The root route keeps the existing manifest link:
-
-```tsx
-{ rel: "manifest", href: "/manifest.webmanifest", crossOrigin: "use-credentials" }
-```
-
-The root route also keeps the PWA-related head meta tags, including `theme-color` and Apple mobile web app tags,
-because those are part of the install/open-as-app experience rather than offline behavior.
-
-## Data Flow
-
-Browsers discover install metadata by reading the root document head and fetching `/manifest.webmanifest`.
-
-Manifest-linked assets continue to be served as static public assets from `apps/web/public`, including:
-
-- favicon assets
-- PWA icons
-- maskable icon
-- Apple touch icon
-- installation screenshots
-
-No service worker is emitted by the web build, no service worker is registered at runtime, and no Workbox
-precache manifest is produced.
-
-## Error Handling
-
-There is no PWA-controlled offline fallback.
-
-When the network is unavailable, the app behaves like a normal website: navigations, API calls, uploaded assets,
-and generated downloads fail according to the browser and server behavior already in place. This is intentional
-because installability is the only remaining PWA goal.
-
-## Testing
-
-Remove `apps/web/src/libs/pwa.test.ts`.
-
-The file currently tests both install metadata and service-worker registration behavior. After this change, the
-remaining PWA surface is static manifest/head metadata with no behavior-specific module contract worth preserving
-as a dedicated unit test.
-
-Implementation should still verify by inspection and build output that:
-
-- `apps/web/dist/index.html` includes the manifest link and mobile install meta tags
-- the root route keeps the manifest link
-- PWA head meta tags remain present
-- no service-worker registration script is exported or injected by the root route
-- no `sw.js` or Workbox precache output is emitted by the web build
-
-Focused validation after implementation:
-
-```sh
-pnpm --filter web typecheck
-pnpm --filter web build
-```
-
-If the package dependency removal changes the lockfile, verify the lockfile remains scoped to removing
-`vite-plugin-pwa` and its now-unused Workbox dependency graph.
diff --git a/docs/superpowers/specs/2026-05-15-unsafe-oauth-redirect-uri-design.md b/docs/superpowers/specs/2026-05-15-unsafe-oauth-redirect-uri-design.md
deleted file mode 100644
index 03b0323b6..000000000
--- a/docs/superpowers/specs/2026-05-15-unsafe-oauth-redirect-uri-design.md
+++ /dev/null
@@ -1,95 +0,0 @@
-# Unsafe OAuth Redirect URI Flag Design
-
-Date: 2026-05-15
-
-## Goal
-
-Replace `OAUTH_DYNAMIC_CLIENT_REDIRECT_HOSTS` with a single explicit escape hatch:
-`FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI`.
-
-By default, dynamic OAuth client registration keeps the existing safe behavior: redirect URIs are allowed only when they target the app origin or local loopback callback hosts. When the flag is enabled, trusted self-hosted deployments may register any parseable redirect URI, including private network URLs, non-loopback `http://` URLs, and custom schemes such as `myapp://callback`.
-
-## Non-Goals
-
-- Do not change whether dynamic OAuth client registration is enabled.
-- Do not change MCP OAuth audience handling, login, consent, token issuance, or public client registration defaults.
-- Do not reuse `FLAG_ALLOW_UNSAFE_AI_BASE_URL`; OAuth redirect handling is a separate trust boundary.
-- Do not keep a curated redirect-host allowlist after this change.
-
-## Architecture
-
-The existing redirect URI policy remains centralized in `@reactive-resume/utils/url-security.node`.
-
-Introduce a mode-based OAuth redirect validator API, for example:
-
-```ts
-isAllowedOAuthRedirectUri(input, trustedOrigins, { allowUnsafe })
-```
-
-Safe mode keeps the current rules:
-
-- Reject malformed URIs.
-- Reject embedded credentials.
-- Reject URI fragments.
-- Allow `http://localhost`, `http://127.0.0.1`, and `http://[::1]` callbacks.
-- Allow `https://` callbacks whose origin matches `APP_URL`.
-- Reject other public HTTPS hosts, private HTTPS hosts, non-loopback HTTP hosts, and non-HTTP schemes.
-
-Unsafe mode deliberately weakens the redirect URI trust check:
-
-- Allow any URI accepted by the platform URL parser.
-- Allow custom schemes such as `myapp://callback`.
-- Allow private and loopback hosts on any supported URL scheme.
-- Allow non-loopback `http://` URLs.
-
-Unsafe mode should still reject strings that are not parseable as URLs. It does not preserve the current credentials or fragment restrictions, because the requested behavior is absolute unsafe: any parseable URI scheme is accepted.
-
-## Data Flow
-
-`packages/env/src/server.ts` defines `FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI` as a `z.stringbool().default(false)` feature flag and removes `OAUTH_DYNAMIC_CLIENT_REDIRECT_HOSTS`.
-
-`packages/auth/src/config.ts` uses the flag in the Better Auth `hooks.before` validation for `/oauth2/register`.
-
-`apps/server/src/http/auth.ts` uses the same flag in the server-level registration preflight before forwarding the request to Better Auth.
-
-Both validation paths must make the same allow or reject decision for the same redirect URI. The server preflight remains useful because it returns OAuth-shaped registration errors before the request enters Better Auth, while the Better Auth hook remains a defense-in-depth check.
-
-## Documentation
-
-Remove `OAUTH_DYNAMIC_CLIENT_REDIRECT_HOSTS` from:
-
-- `packages/env/src/server.ts`
-- `turbo.json`
-- `.env.example`
-- Docker and self-hosting docs
-- Quickstart docs
-
-Add `FLAG_ALLOW_UNSAFE_OAUTH_REDIRECT_URI` to the feature flag sections and env examples with a warning that it is only appropriate for trusted self-hosted deployments. The warning should call out that enabling it permits arbitrary OAuth redirect URIs and can enable phishing or token exfiltration if used on public or multi-tenant instances.
-
-## Error Handling
-
-Rejected safe-mode redirects continue to return the existing error shape:
-
-- Better Auth hook: `BAD_REQUEST` with `redirect_uri is not allowed for dynamic client registration`.
-- Server preflight: `400` with `invalid_redirect_uri`.
-
-Unsafe mode only returns those errors when the redirect URI cannot be parsed as a URL or a non-string entry is supplied in `redirect_uris`.
-
-## Testing
-
-Update focused tests in the relevant packages:
-
-- URL policy tests cover safe mode preserving current allowed and rejected cases.
-- URL policy tests cover unsafe mode allowing custom schemes, private hosts, non-loopback `http://`, credentials, and fragments when the URI is parseable.
-- Auth/server tests cover the env mock shape after removing `OAUTH_DYNAMIC_CLIENT_REDIRECT_HOSTS`.
-- Documentation and env references no longer mention the removed variable.
-
-Run focused validation after implementation:
-
-```sh
-pnpm --filter @reactive-resume/utils test -- src/url-security.node.test.ts
-pnpm --filter server test -- src/http/auth.test.ts
-pnpm --filter @reactive-resume/auth typecheck
-pnpm --filter server typecheck
-pnpm exec turbo boundaries
-```
diff --git a/docs/superpowers/specs/2026-05-19-agent-snapshot-rollback-design.md b/docs/superpowers/specs/2026-05-19-agent-snapshot-rollback-design.md
deleted file mode 100644
index c4e6198f8..000000000
--- a/docs/superpowers/specs/2026-05-19-agent-snapshot-rollback-design.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# Agent Snapshot Rollback Design
-
-## Context
-
-The AI Agent currently stores inverse JSON Patch operations for every applied resume patch. That lets the UI offer a revert action, but it rejects some valid JSON Patch operations because the server must be able to invert them before applying the patch.
-
-## Goal
-
-Use persisted resume snapshots for agent rollback so valid JSON Patch operations can be applied without first generating inverse operations.
-
-## Design
-
-Agent patch actions store the original JSON Patch operations for audit/debugging and a `snapshotData` copy of the resume data from immediately before the patch was applied. The database column is `snapshot_data`.
-
-When `apply_resume_patch` runs, the server reads the current working resume, stores `resume.data` as `snapshotData`, applies the model-generated JSON Patch through the existing resume patch validator, and records the resulting `appliedUpdatedAt`.
-
-The existing action revert endpoint becomes snapshot rollback. Rolling back an action restores that action's `snapshotData`, which means the resume returns to the state before that patch. If the selected action is older than the latest applied action, every applied patch action at or after the selected action is marked `rolled_back` so the chat remains auditable and the UI can show which actions were undone.
-
-Rollback keeps the version guard. The restore is allowed only when the current resume version still matches the latest applied patch action for that resume/thread. If the builder or another process changed the resume after the latest agent patch, rollback marks the selected action `conflicted` and does not replace the resume JSON.
-
-Existing rows that only have `inverse_operations` are legacy non-revertible actions after the migration. The migration removes `inverse_operations` and adds nullable `snapshot_data`.
-
-## UI
-
-The latest applied patch can be undone with the existing action button. Older applied patches can also be restored, but the label should make the destructive effect clear: rolling back to an older action discards that action and later applied agent patches. Actions with status `rolled_back` display as rolled back and cannot be rolled back again.
-
-## Testing
-
-Service tests cover storing `snapshotData`, restoring a snapshot, marking later applied actions as `rolled_back`, conflict handling, and rejecting legacy actions without `snapshotData`. Schema tests cover the `snapshotData` column replacing `inverseOperations`.
diff --git a/docs/superpowers/specs/2026-05-26-custom-styles-header-targets-design.md b/docs/superpowers/specs/2026-05-26-custom-styles-header-targets-design.md
deleted file mode 100644
index ea6fbc0e8..000000000
--- a/docs/superpowers/specs/2026-05-26-custom-styles-header-targets-design.md
+++ /dev/null
@@ -1,129 +0,0 @@
-# Custom Styles Header Targets Design
-
-## Context
-
-Reactive Resume now stores user-defined custom styling as structured style rules in `metadata.styleRules`. The current rule system targets semantic section content and rich-text slots, then resolves those rules in `packages/pdf` through the shared section-style context.
-
-The resume header is not currently part of that section-style context. Profile pictures, `basics.name`, `basics.headline`, and contact items are rendered directly inside each template header. That means users can style normal sections but cannot target the highest-visibility identity and contact content.
-
-## Goals
-
-- Make the profile picture targetable by Custom Styles.
-- Make the resume title and subtitle targetable by Custom Styles.
-- Make contact items targetable as a grouped v1 surface.
-- Keep the feature inside the existing `metadata.styleRules` model.
-- Preserve existing template header layouts and template-owned base styles.
-- Keep contact styling grouped in v1 instead of targeting email, phone, location, website, or custom fields separately.
-
-## Non-Goals
-
-- Do not add per-contact-type targeting in v1.
-- Do not expose picture source, upload, crop, or visibility settings through style rules.
-- Do not redesign template headers or normalize every header into one layout.
-- Do not add a second metadata object for header-specific custom styles.
-- Do not make `sectionItem` targeting part of this work.
-
-## Approved Approach
-
-Extend the existing structured Style Rules system with a new header target and header-specific slots.
-
-Add a new target scope:
-
-- `header`
-
-Add header slots:
-
-- `picture`
-- `title`
-- `subtitle`
-- `contactList`
-- `contactItem`
-- `contactText`
-- `contactLink`
-- `contactIcon`
-
-The header target applies only to the resume header/basic-info area. Global rules can also apply to matching header slots, which lets users define broad defaults such as "all contact text red." Header-targeted rules override global header-slot rules.
-
-## UI Behavior
-
-The Custom Styles panel should add `Header` to the target scope selector.
-
-Slot availability should depend on target scope:
-
-- `Header`: show only header slots.
-- `Section type` and `Specific section`: show section and rich-text slots only.
-- `All sections`: show all semantic slot groups, including the header group, because global rules apply anywhere the selected slot exists.
-
-Header labels should be user-facing and concrete:
-
-- `Picture`
-- `Title`
-- `Subtitle`
-- `Contact list`
-- `Contact item`
-- `Contact text`
-- `Contact link`
-- `Contact icon`
-
-Applied rule labels should remain readable, for example `Header: Contact text` or `All sections: Contact text`.
-
-## Rendering Design
-
-Keep section rendering as-is with `SectionStyleProvider`.
-
-Add a header/basic-info resolver path next to the section-style path. The resolver should use the same style intent translation and safety constraints as section slots, but it should resolve against header context instead of section context.
-
-Template header elements should compose styles in this order:
-
-1. Template defaults.
-2. Global rules for the selected header slot.
-3. Header-targeted rules for the selected header slot.
-4. Renderer safety styles where applicable.
-
-Each template keeps its current layout and structure. The integration only layers resolved custom styles onto existing elements:
-
-- `picture`: the profile `Image`.
-- `title`: `basics.name`.
-- `subtitle`: `basics.headline`.
-- `contactList`: the contact list container.
-- `contactItem`: each contact item wrapper or row.
-- `contactText`: text inside contact items.
-- `contactLink`: linked contact wrappers such as email, phone, website, and linked custom fields.
-- `contactIcon`: icons inside contact items.
-
-Grouped contact styling means email, phone, location, website, and custom fields share the same contact slots. Templates with special wrapper structures, such as Rhyhorn separators, should keep those wrappers and apply the closest matching grouped slot.
-
-## Data Flow
-
-1. The web UI writes header rules into `resume.data.metadata.styleRules`.
-2. The schema validates `header` targets and header slots.
-3. PDF rendering resolves header slots through the shared style-rule resolver.
-4. Template headers compose resolved styles with their existing styles.
-5. Preview, export, and public PDF paths receive the behavior automatically because they all render from resume metadata.
-
-## Testing
-
-Add focused coverage in three layers:
-
-- Schema tests:
- - Accept `header` targets.
- - Accept header slots.
- - Reject unsupported slots and unsupported raw layout properties.
- - Preserve grouped contact style rules in `metadata.styleRules`.
-- PDF resolver tests:
- - Resolve global header-slot rules.
- - Resolve header-targeted rules.
- - Let header-targeted rules override global header-slot rules.
- - Ignore disabled header rules.
- - Keep section rules from applying to header slots.
-- Web UI tests:
- - `Header` appears as a target scope.
- - Header target limits slot options to header slots.
- - Header rules can be created, updated, toggled, displayed, managed, and deleted.
- - Applied rules display readable labels such as `Header: Contact text`.
-
-Template rendering tests should focus on the common resolver/contact behavior and one or two representative templates rather than snapshotting every template header. The implementation still needs to wire the new slots into each template header.
-
-## Open Decisions
-
-No open decisions remain. Contact styling is grouped for v1, and the approved target model is a new `header` scope plus header-specific slots inside the existing `metadata.styleRules` system.
diff --git a/docs/superpowers/specs/2026-06-19-e2e-tests-design.md b/docs/superpowers/specs/2026-06-19-e2e-tests-design.md
deleted file mode 100644
index 11fc70616..000000000
--- a/docs/superpowers/specs/2026-06-19-e2e-tests-design.md
+++ /dev/null
@@ -1,262 +0,0 @@
-# E2E Tests Design
-
-## Context
-
-Reactive Resume is a pnpm/Turborepo monorepo with two deployable apps:
-
-- `apps/web`: TanStack Start / React / Vite user interface.
-- `apps/server`: Hono / Node.js server that owns API, auth, MCP, static uploads, OpenAPI, and production web serving.
-
-The product is a resume builder. The highest-value browser journeys are:
-
-1. Create an account and authenticate.
-2. Create a resume from the dashboard.
-3. Open the builder and edit resume basics.
-4. Persist builder edits through autosave.
-5. Export and import structured resume JSON.
-6. Enable public sharing and view the resume as an anonymous visitor.
-
-The repository currently has broad Vitest coverage but no Playwright or Cypress harness. GitHub Actions currently runs autofix/lint behavior on PRs and Docker image publishing on pushes/tags, but no PR-gated E2E workflow.
-
-Context7 was requested for current framework guidance, but the configured Context7 quota was exhausted in this environment. The implementation plan should re-check current Playwright docs when Context7 access is available.
-
-## Goals
-
-- Add a working Playwright E2E setup.
-- Run E2E tests against the production build path, not only Vite dev mode.
-- Use ephemeral accounts and data for each run.
-- Cover deterministic core UX flows on every PR.
-- Keep CI runtime and flake risk low enough for a default PR gate.
-- Leave room to add PDF, DOCX, OAuth, passkey, 2FA, and AI flows later without bloating the initial gate.
-
-## Non-goals
-
-- Do not add PDF or DOCX download validation to the initial PR gate.
-- Do not automate OAuth, passkeys, 2FA, or password reset in the first suite.
-- Do not include AI Agent, AI import, or resume analysis flows in the first suite.
-- Do not add a cross-browser matrix initially.
-- Do not assert pixel-perfect PDF/canvas rendering.
-
-## Recommended approach
-
-Use a root-level Playwright harness that runs Chromium against a production build:
-
-1. CI installs dependencies and Playwright Chromium.
-2. CI starts PostgreSQL.
-3. CI sets test environment variables.
-4. CI builds the app with `pnpm build`.
-5. Playwright starts the production server with `pnpm start`.
-6. E2E specs exercise browser flows against `APP_URL`.
-
-Use hybrid fixtures:
-
-- The auth smoke test registers and logs in through the browser UI.
-- Non-auth specs create ephemeral users and authenticated browser state through test helpers.
-- Resume setup can use helper APIs or direct database helpers when the setup itself is not the behavior under test.
-- Each test uses unique data and cleans up its own ephemeral user.
-
-This keeps the suite close to user reality while avoiding repeated slow setup in every test.
-
-## File layout
-
-Add:
-
-- `playwright.config.ts`
-- `tests/e2e/README.md`
-- `tests/e2e/fixtures/test.ts`
-- `tests/e2e/fixtures/auth.ts`
-- `tests/e2e/fixtures/db.ts`
-- `tests/e2e/fixtures/resume.ts`
-- `tests/e2e/specs/auth.spec.ts`
-- `tests/e2e/specs/resume-lifecycle.spec.ts`
-- `tests/e2e/specs/json-export-import.spec.ts`
-- `tests/e2e/specs/public-sharing.spec.ts`
-- `.github/workflows/e2e.yml`
-
-Update:
-
-- root `package.json` scripts
-- `turbo.json` tasks, if root scripts are routed through Turbo
-- lockfile after adding Playwright
-- contributing docs if a short root README is not enough
-
-## Playwright configuration
-
-The initial config should:
-
-- Use Chromium only.
-- Read `baseURL` from `APP_URL`, defaulting to `http://localhost:3000`.
-- Use traces, screenshots, and videos on failure.
-- Use a local-friendly reporter plus a CI reporter/artifact format.
-- Start `pnpm start` through `webServer`.
-- Reuse an existing local server outside CI when possible.
-- Prefer role, label, and accessible-name locators.
-- Add targeted `data-testid` attributes only when accessibility locators are not stable enough.
-
-Recommended root scripts:
-
-- `test:e2e`: run Playwright.
-- `test:e2e:ui`: run Playwright UI mode.
-- `test:e2e:ci`: run Playwright with CI reporter settings.
-
-## Environment and infrastructure
-
-Minimum E2E environment:
-
-- `APP_URL=http://localhost:3000`
-- `PORT=3000`
-- `DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres`
-- `AUTH_SECRET=`
-- `FLAG_DISABLE_SIGNUPS=false`
-- `FLAG_DISABLE_EMAIL_AUTH=false`
-- `FLAG_DISABLE_API_RATE_LIMIT=true`
-- `LOCAL_STORAGE_PATH=`
-
-S3, Redis, SMTP, and AI provider variables are not required for the initial deterministic suite.
-
-PostgreSQL should be isolated for CI runs. The simplest PR workflow can use a GitHub Actions Postgres service container and a clean database per job. Local development can use `compose.dev.yml` to start Postgres.
-
-## Ephemeral data strategy
-
-Each worker/test should generate unique identities:
-
-- Email: `e2e---@example.test`
-- Username: `e2e___`
-- Resume names/slugs prefixed with `e2e-`
-
-Cleanup should delete the ephemeral user and rely on database cascade relationships for related resumes, sessions, accounts, API keys, and related records.
-
-Use helper setup where it improves speed and stability:
-
-- Create authenticated storage state for non-auth specs.
-- Create seeded resumes for tests that are about builder/export/sharing behavior rather than resume creation.
-- Keep one browser-driven auth spec to ensure registration/login still works end to end.
-
-## Initial PR-gated specs
-
-### Auth smoke
-
-Flow:
-
-1. Visit `/auth/register`.
-2. Register a unique user through the UI.
-3. Continue to `/dashboard`.
-4. Log out.
-5. Log in with the same credentials.
-6. Assert the dashboard resumes page loads.
-
-Purpose:
-
-- Proves email/password auth, session cookies, redirects, and dashboard access work.
-
-### Resume lifecycle
-
-Flow:
-
-1. Start authenticated as an ephemeral user.
-2. Visit `/dashboard/resumes`.
-3. Create a sample resume through the UI.
-4. Open the resume in the builder.
-5. Edit the basics name field.
-6. Wait for autosave.
-7. Reload the builder.
-8. Assert the edited value persisted.
-
-Purpose:
-
-- Proves dashboard create, builder load, form editing, API update, and autosave persistence.
-
-### JSON export and import
-
-Flow:
-
-1. Start authenticated with a sample resume.
-2. Open the builder.
-3. Export JSON.
-4. Assert a JSON download is created and parseable.
-5. Return to dashboard.
-6. Import the downloaded JSON through the import dialog.
-7. Assert the imported resume opens in the builder.
-
-Purpose:
-
-- Proves deterministic backup/restore without AI or binary rendering dependencies.
-
-### Public sharing
-
-Flow:
-
-1. Start authenticated with a sample resume.
-2. Open builder sharing settings.
-3. Enable public access.
-4. Read the generated public URL.
-5. Open a fresh unauthenticated browser context.
-6. Visit the public URL.
-7. Assert the public resume viewer renders expected resume content.
-
-Purpose:
-
-- Proves sharing state updates, public routing, anonymous access, and public resume rendering.
-
-## CI workflow
-
-Add `.github/workflows/e2e.yml`:
-
-- Trigger on `pull_request` and pushes to `main`.
-- Use Node 24.
-- Use pnpm via Corepack or `pnpm/action-setup`.
-- Cache pnpm dependencies through `actions/setup-node`.
-- Start PostgreSQL service.
-- Install dependencies with `pnpm install --frozen-lockfile`.
-- Install Playwright Chromium.
-- Run `pnpm build`.
-- Run `pnpm test:e2e:ci`.
-- Upload Playwright reports, traces, screenshots, and videos on failure.
-
-The workflow should avoid secrets. All test credentials should be generated during the run.
-
-## Selector strategy
-
-Prefer stable user-facing locators:
-
-- Roles: buttons, links, dialogs, textboxes, comboboxes.
-- Labels: form inputs and switches.
-- URLs: route assertions after navigation.
-
-Add `data-testid` only where necessary:
-
-- Builder canvas/PDF viewer surfaces that lack accessible names.
-- Download/import controls if file input access is otherwise too implementation-dependent.
-- Toast-independent save-state assertions if no visible stable status exists.
-
-Keep test IDs narrow and product-neutral.
-
-## Reliability considerations
-
-- Autosave currently debounces changes by 500ms. Tests should wait for persisted state through reload or API-visible state, not arbitrary sleeps.
-- Public resume viewer uses browser PDF/canvas behavior. Assert meaningful content or viewer presence, not pixels.
-- JSON export/import is deterministic and should be the first export/import loop.
-- Disable API rate limiting in test env to avoid worker-order flakes.
-- Pin locale to the default English path or use role/label selectors robust to translations where practical.
-- Keep the initial suite serial only where shared worker state forces it; otherwise allow Playwright worker isolation.
-
-## Future expansion
-
-After the initial suite is stable:
-
-1. Add PDF download validation as a separate optional or nightly job.
-2. Add DOCX download validation if the PDF job proves stable.
-3. Add password-protected public sharing.
-4. Add dashboard management flows: duplicate, lock, delete, tag filtering, list/grid view.
-5. Add settings flows: profile update, API key creation/deletion.
-6. Add AI flows only with mocked providers or a deterministic local provider.
-7. Add browser matrix only after the Chromium gate has low flake rates.
-
-## Success criteria
-
-- `pnpm test:e2e` runs locally against a built app and Postgres.
-- `pnpm test:e2e:ci` runs in GitHub Actions on every PR.
-- Tests create no persistent shared seed data.
-- Tests clean up ephemeral users and related data.
-- The initial suite covers auth, dashboard creation, builder autosave, JSON export/import, and public sharing.
-- CI uploads useful artifacts for diagnosing failures.
diff --git a/docs/superpowers/specs/2026-07-05-applications-tracker-design.md b/docs/superpowers/specs/2026-07-05-applications-tracker-design.md
deleted file mode 100644
index 490489c05..000000000
--- a/docs/superpowers/specs/2026-07-05-applications-tracker-design.md
+++ /dev/null
@@ -1,94 +0,0 @@
-# Applications Tracker — Roadmap & Status
-
-**Status legend:** ✅ done · 🟡 in progress · ⬜ not started · 🧊 deferred (intentional, revisit when needed)
-
-A job-application tracker built inside Reactive Resume. Each application points at the live
-resume the user sent (`resumeId`), which is why it lives in-product rather than a generic
-tracker. Built from the claude.ai/design prototype "Applications Tracker.dc.html".
-
-Owner dirs: `packages/db/src/schema/applications.ts`, `packages/schema/src/applications/`,
-`packages/api/src/features/applications/`, `apps/web/src/features/applications/`,
-`apps/web/src/routes/dashboard/applications/`.
-
----
-
-## Phase 0 — Core slice ✅ (shipped)
-
-The working vertical slice: data model, CRUD, board, add/detail panels. Zero new deps.
-
-- ✅ DB: `application` table (user FK cascade, `resumeId` FK set-null, JSONB `contacts`/`activity`, follow-up + AI-reservation columns). Migration `20260705090711_third_hercules`.
-- ✅ Schema: `applicationStatusSchema`, `STAGES` (value/label/color), `contactSchema`, `activityEventSchema`, `aiMetadataSchema`.
-- ✅ API: oRPC `applications.{list,getById,create,update,addNote,delete}` — `protectedProcedure`, `userId`-scoped via one `requireOwned`; `update` auto-logs stage-change activity.
-- ✅ Web: sidebar nav item; `/dashboard/applications` route (empty state ↔ board).
-- ✅ Board: dnd-kit drag across 6 fixed stages, optimistic move + rollback toast.
-- ✅ Add slide-over: manual entry + link a live Reactive Resume; native date follow-up.
-- ✅ Detail slide-over: key facts, stage stepper, linked resume, contacts, follow-up, activity timeline + add-note, archive/delete.
-- ✅ Unit test: activity-logging path (`service.test.ts`). Typecheck / boundaries / biome clean.
-
-**Known small gaps — now closed (✅):**
-- ✅ Lingui messages extracted (`pnpm --filter web lingui:extract`) so the new ``/`t` strings are translatable.
-- ✅ Board caps rendered cards per column (`COLUMN_PAGE_SIZE = 50`) with a "Show N more" button, so a stage with hundreds of applications doesn't mount hundreds of draggable nodes. Server-side paging still unneeded (list payload is small).
-- ✅ Contacts are editable from the Detail panel (`ContactsEditor`): add name/role/label, remove, persisted via API `update`'s existing `contacts` field.
-
----
-
-## Phase 1 — Table view + Insights ✅ (shipped)
-
-- ✅ **Table view** — paginated table (25/page), row selection + bulk actions (move stage, add tag, archive, delete). Added a wrapped `Checkbox` in `packages/ui`; hand-rolled table (no `@tanstack/react-table` dep). Board/Table/Insights toggle via URL `view` search param.
-- ✅ **Insights view** — stat tiles, pipeline funnel (conversion per stage), source bars, and a shareable **funnel-flow SVG** with PNG export (canvas, no chart lib — kept the zero-dep property). Server aggregation `applications.stats` (per-stage/per-source counts); funnel/tiles derived client-side via `computeInsights()` (unit-tested).
-- ✅ Tags: `tags text[]` column + filter UI + bulk "add tag" + `applications.tags` distinct list.
-- ✅ Archived-toggle so archived rows can be reached and unarchived (closes the archive loop).
-
-## Phase 2 — Campaigns + import + uploads ✅ (shipped)
-
-- ✅ **Campaigns** — the `campaign` text field is now first-class: set on create (with a native `