diff --git a/.claude/agents/headless-developer.md b/.claude/agents/headless-developer.md
new file mode 100644
index 0000000..c849116
--- /dev/null
+++ b/.claude/agents/headless-developer.md
@@ -0,0 +1,171 @@
+---
+name: headless-developer
+description: Use this agent for headless WordPress setup and decoupled-frontend integration. Specializes in installing and configuring WPGraphQL, wiring CORS and preview links via the flavian-headless mu-plugin, scaffolding Next.js frontends, and troubleshooting GraphQL/REST endpoints. Examples - <example>Context: User wants to start a headless project. user: 'Set up headless WordPress with a Next.js frontend.' assistant: 'I'll use headless-developer to run setup-headless.sh, scaffold a Next.js app under frontend/, and wire the preview secret.' <commentary>Headless setup is multi-step and easy to half-finish — the agent runs the canonical scripts and verifies endpoints.</commentary></example> <example>Context: Preview is broken. user: 'My draft posts redirect to a 401 page from the WP preview button.' assistant: 'I'll use headless-developer to verify the preview secret on both sides and trace the /api/preview route.' <commentary>Preview failures usually mean secret drift between wp_options and .env.local — the agent knows where to look.</commentary></example> <example>Context: User wants a custom GraphQL field. user: 'Expose a custom field via WPGraphQL.' assistant: 'I'll use headless-developer to register the field with register_graphql_field and verify it via GraphiQL.' <commentary>WPGraphQL has a specific extension API that's easy to misuse.</commentary></example>
+tools: Read, Write, Bash, Grep, Glob, TodoWrite, TaskOutput, AskUserQuestion
+model: opus
+permissionMode: bypassPermissions
+---
+
+You are a headless WordPress specialist. You set up the decoupled stack
+(WP as a content API + a separate frontend), configure WPGraphQL and the
+`flavian-headless` mu-plugin, scaffold Next.js frontends, and debug the
+seams between the two — CORS, preview tokens, draft-mode, image origins.
+
+## Primary Responsibilities
+
+### 1. Headless WordPress bootstrap
+
+Use the canonical installer rather than hand-rolling steps:
+
+```bash
+./scripts/wordpress-install/setup-headless.sh \
+  --frontend-url http://localhost:3000
+```
+
+What it does (idempotent):
+
+1. Verifies WordPress is installed in the container.
+2. Installs and activates `wp-graphql`, plus optional `wp-graphql-jwt-authentication` and `wp-graphql-content-blocks`.
+3. Sets `flavian_headless_mode=1` and `flavian_headless_frontend_url` in `wp_options` (this activates the mu-plugin's hooks).
+4. Generates a 32-byte hex preview secret, stores it as `flavian_headless_preview_secret`.
+5. Sets pretty permalinks (`/%postname%/`) and flushes rewrites.
+6. Pings `/graphql` and `/wp-json/wp/v2/` and prints status codes.
+7. Prints the `.env.local` values for the frontend (URL, GraphQL URL, secret).
+
+For a fresh stack from zero:
+
+```bash
+docker compose up -d
+docker compose --profile headless up headless-installer
+```
+
+### 2. The mu-plugin
+
+`mu-plugins/flavian-headless.php` is the contract between WP and the frontend. It is only active when `flavian_headless_mode` is on. It:
+
+| Hook | Effect |
+|---|---|
+| `init` (CORS) | Sends `Access-Control-Allow-*` headers when the request `Origin` matches `flavian_headless_frontend_url` or `http://localhost:3000`. Handles OPTIONS preflights. |
+| `preview_post_link` | Rewrites the admin "Preview" URL to `<frontend>/api/preview?secret=...&id=...&slug=...&type=...`. |
+| `post_link` / `page_link` | In `is_admin()`, rewrites the canonical URL so editors land on the frontend, not the WP renderer. |
+| `rest_endpoints` | Removes `/wp/v2/users` to stop user enumeration. |
+| `rest_api_init` | Registers a `preview_secret_match` REST field on `post` that returns true when the request's `preview_secret` query matches the stored one (editor-context only). |
+
+When adding new headless behavior, prefer extending this mu-plugin over creating a new plugin — keeping the contract in one file makes the seam debuggable.
+
+### 3. Frontend scaffolding
+
+```bash
+bash scripts/scaffold-frontend.sh <slug> --name "Display Name"
+```
+
+Generates `frontend/<slug>/` from `.claude/templates/frontend/nextjs/`. The template is a Next.js 14 App Router app with:
+
+- A thin `fetch`-based GraphQL client (`src/lib/wp-client.ts`) — no Apollo or urql by default, swap in if normalized caching is needed.
+- `src/lib/queries.ts` — `POSTS_LIST_QUERY`, `POST_BY_SLUG_QUERY`, `POST_BY_ID_QUERY`. The slug + id queries support `asPreview: Boolean`.
+- `src/app/api/preview/route.ts` — validates `WORDPRESS_PREVIEW_SECRET`, confirms the post exists via `POST_BY_ID_QUERY`, then `draftMode().enable()` + redirects to `/posts/<slug>`.
+- `src/app/api/exit-preview/route.ts` — `draftMode().disable()` + redirect home.
+
+After scaffolding:
+
+```bash
+cd frontend/<slug>
+cp .env.local.example .env.local
+# paste the values printed by setup-headless.sh
+pnpm install && pnpm dev
+```
+
+### 4. Preview mode debugging
+
+When previews break, walk this checklist in order — the failure is almost always one of the first three:
+
+1. **Secret drift.** `wp option get flavian_headless_preview_secret --allow-root` in the WP container must equal `WORDPRESS_PREVIEW_SECRET` in `frontend/<slug>/.env.local`. If they diverge, regenerate one side or copy across.
+2. **CORS preflight failure.** Open the browser network panel on the preview click. If the OPTIONS request to `/graphql` returns no `Access-Control-Allow-Origin`, `flavian_headless_mode` is off OR the frontend URL option doesn't match the actual origin.
+3. **draftMode not propagating.** Next.js `draftMode().isEnabled` is per-request. Make sure the GraphQL client (`wp-client.ts`) is reading it and passing `asPreview: true` to the query — and that the query has `asPreview` declared in its variables list.
+4. **WPGraphQL missing the `asPreview` argument.** Older WPGraphQL versions had partial preview support. `wp plugin update wp-graphql` fixes most stale-data cases.
+5. **JWT auth misconfigured.** If using the JWT plugin, `GRAPHQL_JWT_AUTH_SECRET_KEY` must be defined in `wp-config.php`. The installer prints the value but cannot write to wp-config from inside a container without breaking permissions — add it manually.
+
+### 5. Custom GraphQL fields
+
+Use WPGraphQL's `register_graphql_field` (and `register_graphql_object_type` for new types) rather than extending the REST API and proxying it. Place new fields in a small, focused mu-plugin or a `inc/graphql/` directory in the active theme. Always:
+
+1. Declare the type explicitly (`'type' => 'String'` not implicit).
+2. Resolve via a callback that takes `$post` / `$source` — never query inside the resolver if the data is already on the source object.
+3. Verify in GraphiQL (`/wp-admin/admin.php?page=graphiql-ide`) before wiring the frontend.
+
+## Standard Workflows
+
+### A. First-time headless setup
+
+```
+1. Confirm WordPress is installed in the container.
+2. docker compose --profile headless up headless-installer
+3. Copy the printed env values.
+4. bash scripts/scaffold-frontend.sh <slug>
+5. cd frontend/<slug>; cp .env.local.example .env.local; paste values
+6. pnpm install && pnpm dev → open http://localhost:3000
+7. In WP admin, create a draft post and click Preview; confirm it lands on
+   /posts/<slug> with the draft-mode banner visible.
+```
+
+### B. Adding a new content type to the frontend
+
+```
+1. Register the CPT in WordPress with show_in_graphql=true.
+2. Verify the new GraphQL root field appears in GraphiQL.
+3. Add a query in src/lib/queries.ts.
+4. Add a route under src/app/.
+5. If editors need previews, extend the mu-plugin's preview_post_link
+   handler if its current rewrite logic doesn't cover the new type.
+```
+
+### C. Promoting to staging/production
+
+```
+1. Disable HEADLESS_INSTALL_JWT for environments without a wp-config.php
+   you control — fall back to application passwords.
+2. Update flavian_headless_frontend_url to the production frontend origin
+   (do not rely on the localhost default).
+3. Regenerate flavian_headless_preview_secret per environment; never reuse
+   the dev secret.
+4. Set the frontend's WORDPRESS_URL / WORDPRESS_GRAPHQL_URL to the public
+   WP origin (not the docker-internal hostname).
+5. Verify CORS by hitting /graphql with a curl that sets Origin to the
+   production frontend URL.
+```
+
+## Integration
+
+**Invoked by:**
+- Manual user request to set up headless WP, scaffold a frontend, debug a preview, or expose a custom GraphQL field.
+- Trigger keywords: "headless", "WPGraphQL", "Next.js", "preview mode", "decoupled", "GraphQL", "draft mode", "CORS".
+
+**Works with:**
+- `wp-environment-manager` — provisions the WordPress container before this agent runs setup.
+- `plugin-developer` — for custom WPGraphQL schema extensions packaged as a plugin.
+- `security-audit-agent` — review the mu-plugin's CORS allowlist before any deploy.
+- `deployment-agent` — ships the frontend (separately from WP) and the mu-plugin.
+
+**Outputs:**
+- Configured headless WP with WPGraphQL + mu-plugin active
+- A `frontend/<slug>/` Next.js app wired to the preview secret
+- Verified preview round-trip and CORS handshake
+
+## Rules
+
+- **NEVER commit `.env.local` or the preview secret.** The installer prints the secret once; if lost, regenerate via `wp option update flavian_headless_preview_secret <new>` and update the frontend.
+- **NEVER widen the CORS allowlist to `*`.** Mirror the configured frontend origin only. If you need a second origin (preview deploys, staging), add it explicitly in the mu-plugin's `$allowed` array.
+- **ALWAYS verify both endpoints respond after install:** REST (`/wp-json/wp/v2/posts`) and GraphQL (`/graphql`). The installer does this; if a step fails, surface the HTTP code, don't continue silently.
+- **PREFER WPGraphQL over the REST API** for new frontend reads. REST is fine for write-side operations (creating posts, uploads) where WPGraphQL's mutation surface is thinner.
+- **NEVER assume preview works without testing it end-to-end.** A working `/api/preview` route does not mean editors see drafts — verify by opening the admin, creating a draft, and clicking Preview.
+
+## Error Recovery
+
+| Symptom | Likely cause | Action |
+|---|---|---|
+| `/graphql` returns 404 | WPGraphQL not active or permalinks not pretty | `wp plugin activate wp-graphql && wp rewrite flush --hard` |
+| Preview redirects to `/api/preview` and 401s | Secret drift between wp_options and `.env.local` | Compare both; copy or regenerate |
+| Frontend fetches return CORS errors in the browser | `flavian_headless_mode` off, or origin mismatch | `wp option get flavian_headless_mode`; `wp option get flavian_headless_frontend_url` |
+| Draft post shows published content in preview | `draftMode()` is enabled but `asPreview` not passed to query | Audit the call site in the route handler |
+| GraphQL returns `null` for `asPreview` queries | User isn't authenticated as the post's author | Use JWT or application passwords; anonymous preview is not supported by design |
+| `wp option update` fails inside container | Container missing `wp-cli` or running as wrong user | Use the helper: `docker compose exec -T wordpress wp ... --allow-root` |
diff --git a/.claude/templates/frontend/nextjs/.env.local.example.tmpl b/.claude/templates/frontend/nextjs/.env.local.example.tmpl
new file mode 100644
index 0000000..ffef3f4
--- /dev/null
+++ b/.claude/templates/frontend/nextjs/.env.local.example.tmpl
@@ -0,0 +1,12 @@
+# WordPress origin (server-side only — used by the GraphQL client + Image host)
+WORDPRESS_URL=http://localhost:8080
+
+# GraphQL endpoint
+WORDPRESS_GRAPHQL_URL=http://localhost:8080/graphql
+
+# Preview secret — must match flavian_headless_preview_secret in wp_options.
+# Printed by scripts/wordpress-install/setup-headless.sh.
+WORDPRESS_PREVIEW_SECRET=replace-me
+
+# Public site URL (used in canonical tags / preview link generation)
+NEXT_PUBLIC_SITE_URL=http://localhost:3000
diff --git a/.claude/templates/frontend/nextjs/.gitignore.tmpl b/.claude/templates/frontend/nextjs/.gitignore.tmpl
new file mode 100644
index 0000000..bb9346e
--- /dev/null
+++ b/.claude/templates/frontend/nextjs/.gitignore.tmpl
@@ -0,0 +1,8 @@
+node_modules/
+.next/
+out/
+.env.local
+.env.*.local
+*.log
+.DS_Store
+.vercel
diff --git a/.claude/templates/frontend/nextjs/README.md.tmpl b/.claude/templates/frontend/nextjs/README.md.tmpl
new file mode 100644
index 0000000..86e31b9
--- /dev/null
+++ b/.claude/templates/frontend/nextjs/README.md.tmpl
@@ -0,0 +1,35 @@
+# {{APP_NAME}}
+
+Next.js 14 (App Router) frontend for the Flavian headless WordPress setup. Generated by `scripts/scaffold-frontend.sh`.
+
+## Quick start
+
+```bash
+cp .env.local.example .env.local
+# Edit .env.local with the values printed by setup-headless.sh
+
+pnpm install   # or npm/yarn
+pnpm dev
+```
+
+Open <http://localhost:3000>.
+
+## Routes
+
+| Path | What it does |
+|---|---|
+| `/` | Lists the 10 most recent published posts via GraphQL. |
+| `/posts/[slug]` | Renders a single post by slug. |
+| `/api/preview` | Validates `secret` + `id` query, enables Next.js draft mode, redirects to the post route. |
+| `/api/exit-preview` | Disables draft mode and bounces back to `/`. |
+
+## Preview flow
+
+1. Editor clicks **Preview** on a draft post in WP admin.
+2. WordPress (via `mu-plugins/flavian-headless.php`) rewrites the preview URL to `http://localhost:3000/api/preview?secret=...&id=...`.
+3. This route validates the secret against `WORDPRESS_PREVIEW_SECRET` and calls `draftMode().enable()`.
+4. Subsequent fetches read draft content because the GraphQL client conditionally sends `preview: true`.
+
+## GraphQL client
+
+`src/lib/wp-client.ts` is a thin `fetch` wrapper — no Apollo or urql to keep the bundle small. Swap it out if you need normalized caching.
diff --git a/.claude/templates/frontend/nextjs/next.config.mjs.tmpl b/.claude/templates/frontend/nextjs/next.config.mjs.tmpl
new file mode 100644
index 0000000..8988f10
--- /dev/null
+++ b/.claude/templates/frontend/nextjs/next.config.mjs.tmpl
@@ -0,0 +1,18 @@
+/** @type {import('next').NextConfig} */
+const wpHost = (() => {
+  try {
+    return new URL(process.env.WORDPRESS_URL ?? 'http://localhost:8080').hostname;
+  } catch {
+    return 'localhost';
+  }
+})();
+
+export default {
+  reactStrictMode: true,
+  images: {
+    remotePatterns: [
+      { protocol: 'http', hostname: wpHost },
+      { protocol: 'https', hostname: wpHost },
+    ],
+  },
+};
diff --git a/.claude/templates/frontend/nextjs/package.json.tmpl b/.claude/templates/frontend/nextjs/package.json.tmpl
new file mode 100644
index 0000000..b31aac6
--- /dev/null
+++ b/.claude/templates/frontend/nextjs/package.json.tmpl
@@ -0,0 +1,25 @@
+{
+  "name": "{{APP_SLUG}}",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "next": "^14.2.5",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.10",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "eslint": "^8.57.0",
+    "eslint-config-next": "^14.2.5",
+    "typescript": "^5.5.3"
+  }
+}
diff --git a/.claude/templates/frontend/nextjs/src/app/api/exit-preview/route.ts.tmpl b/.claude/templates/frontend/nextjs/src/app/api/exit-preview/route.ts.tmpl
new file mode 100644
index 0000000..0208647
--- /dev/null
+++ b/.claude/templates/frontend/nextjs/src/app/api/exit-preview/route.ts.tmpl
@@ -0,0 +1,7 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { draftMode } from 'next/headers';
+
+export async function GET(req: NextRequest) {
+  draftMode().disable();
+  return NextResponse.redirect(new URL('/', req.nextUrl.origin));
+}
diff --git a/.claude/templates/frontend/nextjs/src/app/api/preview/route.ts.tmpl b/.claude/templates/frontend/nextjs/src/app/api/preview/route.ts.tmpl
new file mode 100644
index 0000000..ed6eabe
--- /dev/null
+++ b/.claude/templates/frontend/nextjs/src/app/api/preview/route.ts.tmpl
@@ -0,0 +1,41 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { draftMode } from 'next/headers';
+import { wpQuery } from '@/lib/wp-client';
+import { POST_BY_ID_QUERY } from '@/lib/queries';
+
+/**
+ * GET /api/preview?secret=...&id=...
+ *
+ * Called by WordPress when an editor clicks "Preview" on a draft. Validates
+ * the shared secret, enables Next.js draft mode, and redirects to the post's
+ * canonical frontend route — which will then re-fetch draft content because
+ * draftMode() is now true.
+ */
+export async function GET(req: NextRequest) {
+  const secret = req.nextUrl.searchParams.get('secret');
+  const id = req.nextUrl.searchParams.get('id');
+  const slugParam = req.nextUrl.searchParams.get('slug');
+
+  if (secret !== process.env.WORDPRESS_PREVIEW_SECRET) {
+    return new NextResponse('Invalid preview secret', { status: 401 });
+  }
+  if (!id) {
+    return new NextResponse('Missing id parameter', { status: 400 });
+  }
+
+  // Confirm the post actually exists before enabling draft mode — protects
+  // against /api/preview?secret=...&id=999999 enabling draft mode for free.
+  let slug = slugParam ?? '';
+  try {
+    const data = await wpQuery<{ post: { slug: string } | null }>(POST_BY_ID_QUERY, { id });
+    if (!data.post) {
+      return new NextResponse('Post not found', { status: 404 });
+    }
+    slug = data.post.slug || slug;
+  } catch (err) {
+    return new NextResponse(`Preview lookup failed: ${(err as Error).message}`, { status: 500 });
+  }
+
+  draftMode().enable();
+  return NextResponse.redirect(new URL(`/posts/${slug}`, req.nextUrl.origin));
+}
diff --git a/.claude/templates/frontend/nextjs/src/app/globals.css.tmpl b/.claude/templates/frontend/nextjs/src/app/globals.css.tmpl
new file mode 100644
index 0000000..4624cc5
--- /dev/null
+++ b/.claude/templates/frontend/nextjs/src/app/globals.css.tmpl
@@ -0,0 +1,58 @@
+:root {
+  --container: 720px;
+  --fg: #111;
+  --muted: #666;
+  --accent: #0066cc;
+}
+
+* { box-sizing: border-box; }
+
+body {
+  margin: 0;
+  font-family: system-ui, -apple-system, BlinkMacSystemFont, sans-serif;
+  color: var(--fg);
+  line-height: 1.6;
+}
+
+.container {
+  max-width: var(--container);
+  margin: 0 auto;
+  padding: 2rem 1rem;
+}
+
+.preview-bar {
+  background: #ffefc1;
+  color: #5a4500;
+  padding: 0.5rem 1rem;
+  text-align: center;
+  font-size: 0.9rem;
+}
+
+.preview-bar a {
+  color: var(--accent);
+  margin-left: 0.5rem;
+}
+
+.post-list {
+  list-style: none;
+  padding: 0;
+}
+
+.post-list li {
+  border-bottom: 1px solid #eee;
+  padding: 1.5rem 0;
+}
+
+.post-list h2 {
+  margin: 0 0 0.25rem;
+}
+
+.post-list a {
+  color: inherit;
+  text-decoration: none;
+}
+
+time {
+  color: var(--muted);
+  font-size: 0.875rem;
+}
diff --git a/.claude/templates/frontend/nextjs/src/app/layout.tsx.tmpl b/.claude/templates/frontend/nextjs/src/app/layout.tsx.tmpl
new file mode 100644
index 0000000..0a61a09
--- /dev/null
+++ b/.claude/templates/frontend/nextjs/src/app/layout.tsx.tmpl
@@ -0,0 +1,25 @@
+import type { Metadata } from 'next';
+import { draftMode } from 'next/headers';
+import './globals.css';
+
+export const metadata: Metadata = {
+  title: '{{APP_NAME}}',
+  description: 'Headless WordPress frontend',
+};
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  const { isEnabled: isDraft } = draftMode();
+
+  return (
+    <html lang="en">
+      <body>
+        {isDraft && (
+          <div className="preview-bar">
+            Draft mode is on. <a href="/api/exit-preview">Exit preview</a>
+          </div>
+        )}
+        <main className="container">{children}</main>
+      </body>
+    </html>
+  );
+}
diff --git a/.claude/templates/frontend/nextjs/src/app/page.tsx.tmpl b/.claude/templates/frontend/nextjs/src/app/page.tsx.tmpl
new file mode 100644
index 0000000..bdf0e5d
--- /dev/null
+++ b/.claude/templates/frontend/nextjs/src/app/page.tsx.tmpl
@@ -0,0 +1,36 @@
+import Link from 'next/link';
+import { wpQuery } from '@/lib/wp-client';
+import { POSTS_LIST_QUERY } from '@/lib/queries';
+
+type PostsListResponse = {
+  posts: {
+    nodes: Array<{
+      id: string;
+      title: string;
+      slug: string;
+      date: string;
+      excerpt: string;
+    }>;
+  };
+};
+
+export default async function HomePage() {
+  const data = await wpQuery<PostsListResponse>(POSTS_LIST_QUERY);
+
+  return (
+    <>
+      <h1>{{APP_NAME}}</h1>
+      <ul className="post-list">
+        {data.posts.nodes.map(post => (
+          <li key={post.id}>
+            <Link href={`/posts/${post.slug}`}>
+              <h2>{post.title}</h2>
+            </Link>
+            <time dateTime={post.date}>{new Date(post.date).toLocaleDateString()}</time>
+            <div dangerouslySetInnerHTML={{ __html: post.excerpt }} />
+          </li>
+        ))}
+      </ul>
+    </>
+  );
+}
diff --git a/.claude/templates/frontend/nextjs/src/app/posts/[slug]/page.tsx.tmpl b/.claude/templates/frontend/nextjs/src/app/posts/[slug]/page.tsx.tmpl
new file mode 100644
index 0000000..1170856
--- /dev/null
+++ b/.claude/templates/frontend/nextjs/src/app/posts/[slug]/page.tsx.tmpl
@@ -0,0 +1,34 @@
+import { notFound } from 'next/navigation';
+import { draftMode } from 'next/headers';
+import { wpQuery } from '@/lib/wp-client';
+import { POST_BY_SLUG_QUERY } from '@/lib/queries';
+
+type PostResponse = {
+  post: {
+    title: string;
+    date: string;
+    content: string;
+  } | null;
+};
+
+export default async function PostPage({ params }: { params: { slug: string } }) {
+  const { isEnabled: isDraft } = draftMode();
+  const data = await wpQuery<PostResponse>(POST_BY_SLUG_QUERY, {
+    slug: params.slug,
+    asPreview: isDraft,
+  });
+
+  if (!data.post) {
+    notFound();
+  }
+
+  return (
+    <article>
+      <h1>{data.post.title}</h1>
+      <time dateTime={data.post.date}>
+        {new Date(data.post.date).toLocaleDateString()}
+      </time>
+      <div dangerouslySetInnerHTML={{ __html: data.post.content }} />
+    </article>
+  );
+}
diff --git a/.claude/templates/frontend/nextjs/src/lib/queries.ts.tmpl b/.claude/templates/frontend/nextjs/src/lib/queries.ts.tmpl
new file mode 100644
index 0000000..41c4681
--- /dev/null
+++ b/.claude/templates/frontend/nextjs/src/lib/queries.ts.tmpl
@@ -0,0 +1,48 @@
+export const POSTS_LIST_QUERY = /* GraphQL */ `
+  query PostsList {
+    posts(first: 10, where: { status: PUBLISH }) {
+      nodes {
+        id
+        databaseId
+        title
+        slug
+        date
+        excerpt
+        featuredImage {
+          node {
+            sourceUrl
+            altText
+          }
+        }
+      }
+    }
+  }
+`;
+
+export const POST_BY_SLUG_QUERY = /* GraphQL */ `
+  query PostBySlug($slug: ID!, $asPreview: Boolean = false) {
+    post(id: $slug, idType: SLUG, asPreview: $asPreview) {
+      id
+      databaseId
+      title
+      slug
+      date
+      content
+      featuredImage {
+        node {
+          sourceUrl
+          altText
+        }
+      }
+    }
+  }
+`;
+
+export const POST_BY_ID_QUERY = /* GraphQL */ `
+  query PostById($id: ID!) {
+    post(id: $id, idType: DATABASE_ID, asPreview: true) {
+      slug
+      status
+    }
+  }
+`;
diff --git a/.claude/templates/frontend/nextjs/src/lib/wp-client.ts.tmpl b/.claude/templates/frontend/nextjs/src/lib/wp-client.ts.tmpl
new file mode 100644
index 0000000..a4247b1
--- /dev/null
+++ b/.claude/templates/frontend/nextjs/src/lib/wp-client.ts.tmpl
@@ -0,0 +1,32 @@
+import { draftMode } from 'next/headers';
+
+const endpoint = process.env.WORDPRESS_GRAPHQL_URL ?? 'http://localhost:8080/graphql';
+
+type GraphQLResponse<T> = { data?: T; errors?: Array<{ message: string }> };
+
+export async function wpQuery<T>(
+  query: string,
+  variables: Record<string, unknown> = {},
+): Promise<T> {
+  const { isEnabled: isDraft } = draftMode();
+
+  const res = await fetch(endpoint, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ query, variables }),
+    next: isDraft ? { revalidate: 0 } : { revalidate: 60 },
+  });
+
+  if (!res.ok) {
+    throw new Error(`WPGraphQL ${res.status}: ${await res.text()}`);
+  }
+
+  const json = (await res.json()) as GraphQLResponse<T>;
+  if (json.errors?.length) {
+    throw new Error(json.errors.map(e => e.message).join('; '));
+  }
+  if (!json.data) {
+    throw new Error('WPGraphQL response had no data field');
+  }
+  return json.data;
+}
diff --git a/.claude/templates/frontend/nextjs/tsconfig.json.tmpl b/.claude/templates/frontend/nextjs/tsconfig.json.tmpl
new file mode 100644
index 0000000..8e358bd
--- /dev/null
+++ b/.claude/templates/frontend/nextjs/tsconfig.json.tmpl
@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": { "@/*": ["./src/*"] }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}
diff --git a/.env.example b/.env.example
index 688532c..db5a874 100644
--- a/.env.example
+++ b/.env.example
@@ -20,3 +20,9 @@ WC_INSTALL_SAMPLE_DATA=true
 WC_DEFAULT_THEME=flavian-shop
 WC_DEFAULT_CURRENCY=USD
 WC_DEFAULT_COUNTRY=US:CA
+
+# Headless WordPress installer (compose profile: headless)
+# Run: docker compose --profile headless up headless-installer
+HEADLESS_FRONTEND_URL=http://localhost:3000
+HEADLESS_INSTALL_JWT=true
+HEADLESS_INSTALL_BLOCKS=true
diff --git a/CLAUDE.md b/CLAUDE.md
index 70aacc1..5ecd39c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -279,9 +279,9 @@ This project uses a lean, WordPress-optimized plugin configuration with 6 plugin
 
 ---
 
-### Custom Agents (51 Total)
+### Custom Agents (52 Total)
 
-51 specialized agents: 26 WordPress-focused development agents plus 25 generic cross-domain agents (meta/ops, business, marketing/social, engineering). Key WordPress agents include `frontend-developer`, `plugin-developer`, `test-writer-fixer`, `ui-designer`, `figma-fse-converter`, `canva-fse-converter`, `security-audit-agent`, `deployment-agent`, `woocommerce-agent`. Key generic agents include `agent-expert`, `backend-architect`, `migration-specialist`, `content-creator`, `devops-automator`.
+52 specialized agents: 27 WordPress-focused development agents plus 25 generic cross-domain agents (meta/ops, business, marketing/social, engineering). Key WordPress agents include `frontend-developer`, `plugin-developer`, `test-writer-fixer`, `ui-designer`, `figma-fse-converter`, `canva-fse-converter`, `security-audit-agent`, `deployment-agent`, `woocommerce-agent`, `headless-developer`. Key generic agents include `agent-expert`, `backend-architect`, `migration-specialist`, `content-creator`, `devops-automator`.
 
 Agents are invoked automatically based on task context.
 
@@ -463,7 +463,7 @@ Result: themes/[theme-name]/ ready for WordPress
 - All plugins serve WordPress development
 
 **Agent Philosophy:**
-- 51 custom agents available (26 WordPress-focused + 25 generic cross-domain)
+- 52 custom agents available (27 WordPress-focused + 25 generic cross-domain)
 - Agents invoked contextually by Claude Code
 - No action required - automatic selection
 
@@ -548,6 +548,18 @@ gh auth status                # Check authentication
 ```
 Configs live in `.claude/config/deployment/<env>.yml` (gitignored). Templates: `*.example.yml`.
 
+**Headless WordPress (decoupled frontends):**
+```bash
+# One-shot install: WPGraphQL + CORS + preview secret
+docker compose --profile headless up headless-installer
+
+# Scaffold a Next.js 14 frontend under frontend/<slug>/
+bash scripts/scaffold-frontend.sh my-app --name "My Site"
+```
+Mu-plugin: `mu-plugins/flavian-headless.php` (toggled by `flavian_headless_mode` option).
+Frontend templates: `.claude/templates/frontend/nextjs/`.
+Full guide: `docs/headless-wordpress/README.md`.
+
 **WooCommerce (e-commerce scaffold):**
 ```bash
 # One-shot install via compose profile
@@ -587,4 +599,4 @@ Defaults configurable via `.env`: `WC_INSTALL_SAMPLE_DATA`, `WC_DEFAULT_THEME`,
 ---
 
 **Last Updated:** 2026-05-06
-**Architecture Status:** ✅ Lean, WordPress-optimized configuration (6 plugins + 51 agents)
\ No newline at end of file
+**Architecture Status:** ✅ Lean, WordPress-optimized configuration (6 plugins + 52 agents)
\ No newline at end of file
diff --git a/docker-compose.yml b/docker-compose.yml
index 4e280ba..14b3a45 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -92,6 +92,40 @@ services:
         [ -n "$$WC_DEFAULT_COUNTRY"  ] && ARGS="$$ARGS --country $$WC_DEFAULT_COUNTRY"
         bash /scripts/setup-woocommerce.sh $$ARGS
 
+  # One-shot headless WordPress installer.
+  #
+  # Run with the 'headless' compose profile to install WPGraphQL, configure
+  # CORS + preview routing, and print the env values your frontend needs:
+  #
+  #   docker compose --profile headless up headless-installer
+  #
+  # The container exits when setup-headless.sh completes. Re-running is safe —
+  # every step is idempotent.
+  headless-installer:
+    image: docker:cli
+    container_name: flavian-headless-installer
+    profiles: ["headless"]
+    depends_on:
+      wordpress:
+        condition: service_healthy
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - ./scripts/wordpress-install:/scripts:ro
+    working_dir: /scripts
+    environment:
+      HEADLESS_FRONTEND_URL: ${HEADLESS_FRONTEND_URL:-http://localhost:3000}
+      HEADLESS_INSTALL_JWT:  ${HEADLESS_INSTALL_JWT:-true}
+      HEADLESS_INSTALL_BLOCKS: ${HEADLESS_INSTALL_BLOCKS:-true}
+    entrypoint: ["/bin/sh", "-c"]
+    command:
+      - |
+        set -e
+        apk add --no-cache bash docker-cli-compose >/dev/null
+        ARGS="--frontend-url $$HEADLESS_FRONTEND_URL"
+        [ "$$HEADLESS_INSTALL_JWT"    = "false" ] && ARGS="$$ARGS --no-jwt"
+        [ "$$HEADLESS_INSTALL_BLOCKS" = "false" ] && ARGS="$$ARGS --no-blocks"
+        bash /scripts/setup-headless.sh $$ARGS
+
   # Optional: phpMyAdmin for database management
   phpmyadmin:
     image: phpmyadmin:latest
diff --git a/docs/headless-wordpress/README.md b/docs/headless-wordpress/README.md
new file mode 100644
index 0000000..3c9f9c8
--- /dev/null
+++ b/docs/headless-wordpress/README.md
@@ -0,0 +1,73 @@
+# Headless WordPress
+
+Run WordPress as a content API (REST + WPGraphQL) and consume it from a decoupled frontend. The MVP ships a Next.js 14 (App Router) scaffold; Nuxt and Astro are tracked as follow-ups.
+
+## What's in the box
+
+| Piece | Path | Purpose |
+|---|---|---|
+| Installer script | `scripts/wordpress-install/setup-headless.sh` | Installs WPGraphQL, sets pretty permalinks, generates the preview secret, prints the values your frontend needs. |
+| Compose profile | `docker-compose.yml` → `headless-installer` | Wraps the installer in a one-shot container. Run with `docker compose --profile headless up headless-installer`. |
+| Mu-plugin | `mu-plugins/flavian-headless.php` | CORS, preview-URL rewriting, REST hardening, REST `preview_secret_match` field. Toggled by `flavian_headless_mode` option. |
+| Scaffold script | `scripts/scaffold-frontend.sh` | Generates `frontend/<slug>/` from `.claude/templates/frontend/nextjs/`. |
+| Agent | `.claude/agents/headless-developer.md` | Domain expert; invoke for headless workflows. |
+
+## Five-minute setup
+
+```bash
+# 1. Bring up WordPress (if not already running)
+docker compose up -d
+
+# 2. Install WPGraphQL + configure headless mode
+docker compose --profile headless up headless-installer
+# → prints WORDPRESS_PREVIEW_SECRET and JWT secret
+
+# 3. Scaffold a Next.js frontend
+bash scripts/scaffold-frontend.sh my-app --name "My Site"
+
+# 4. Configure and run the frontend
+cd frontend/my-app
+cp .env.local.example .env.local
+# paste the values from step 2 into .env.local
+pnpm install && pnpm dev
+# → http://localhost:3000
+```
+
+## How preview mode works
+
+1. Editor clicks **Preview** on a draft in `/wp-admin`.
+2. `flavian-headless.php` hooks `preview_post_link` and rewrites the URL to:
+   ```
+   http://localhost:3000/api/preview?secret=<hex>&id=<post-id>&slug=<slug>&type=post
+   ```
+3. The Next.js `/api/preview` route validates `secret` against `WORDPRESS_PREVIEW_SECRET`, confirms the post exists via `POST_BY_ID_QUERY`, then calls `draftMode().enable()` and redirects to `/posts/<slug>`.
+4. The post page detects `draftMode().isEnabled` and passes `asPreview: true` to the GraphQL query, which returns the unpublished revision.
+5. The `<body>` shows a "Draft mode is on" banner with an exit link to `/api/exit-preview`.
+
+## Endpoints
+
+- **REST**: `http://localhost:8080/wp-json/wp/v2/`
+- **GraphQL**: `http://localhost:8080/graphql`
+- **GraphiQL IDE**: `http://localhost:8080/wp-admin/admin.php?page=graphiql-ide`
+
+## Disabling headless mode
+
+```bash
+docker compose exec wordpress wp option update flavian_headless_mode 0 --allow-root
+```
+
+The mu-plugin's hooks short-circuit when the option is off, so WordPress reverts to standard behavior immediately — no plugin deactivation needed.
+
+## Troubleshooting
+
+See the **Error Recovery** table in `.claude/agents/headless-developer.md` for the canonical list. The three failures that cover ~90% of issues:
+
+1. **Secret drift** between `wp_options.flavian_headless_preview_secret` and `frontend/<app>/.env.local`'s `WORDPRESS_PREVIEW_SECRET`.
+2. **CORS preflight rejection** — `flavian_headless_mode` is off, or `flavian_headless_frontend_url` doesn't match the actual frontend origin.
+3. **`asPreview` not propagating** — the GraphQL client must read `draftMode().isEnabled` and forward it as a variable; the query must declare `asPreview: Boolean = false`.
+
+## Follow-ups
+
+- Nuxt scaffold (`.claude/templates/frontend/nuxt/`)
+- Astro scaffold (`.claude/templates/frontend/astro/`)
+- Webhook-based ISR revalidation on post publish
diff --git a/frontend/README.md b/frontend/README.md
new file mode 100644
index 0000000..7e28772
--- /dev/null
+++ b/frontend/README.md
@@ -0,0 +1,11 @@
+# Frontend apps
+
+Decoupled frontend apps for the headless WordPress setup live here. Scaffold a new one with:
+
+```bash
+bash scripts/scaffold-frontend.sh my-app
+```
+
+Each scaffolded app is self-contained: its own `package.json`, `.env.local`, and dependencies under `node_modules/` (gitignored at repo root).
+
+See `docs/headless-wordpress/README.md` for the end-to-end setup.
diff --git a/mu-plugins/flavian-headless.php b/mu-plugins/flavian-headless.php
new file mode 100644
index 0000000..1d72e04
--- /dev/null
+++ b/mu-plugins/flavian-headless.php
@@ -0,0 +1,233 @@
+<?php
+/**
+ * Plugin Name: Flavian Headless Support
+ * Description: CORS, preview URL rewriting, and REST API hardening for the headless WP setup. Only active when the flavian_headless_mode option is on.
+ * Version:     0.1.0
+ * Author:      Flavian
+ * License:     GPL-2.0-or-later
+ *
+ * Configured by scripts/wordpress-install/setup-headless.sh.
+ *
+ * @package Flavian\Headless
+ */
+
+namespace Flavian\Headless;
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Cached check so the toggle doesn't hit the options table on every hook.
+ *
+ * @return bool
+ */
+function is_enabled(): bool {
+	static $enabled = null;
+	if ( null === $enabled ) {
+		$enabled = (bool) get_option( 'flavian_headless_mode', false );
+	}
+	return $enabled;
+}
+
+/**
+ * Configured frontend origin without a trailing slash.
+ *
+ * @return string
+ */
+function frontend_url(): string {
+	$url = (string) get_option( 'flavian_headless_frontend_url', '' );
+	return '' !== $url ? rtrim( $url, '/' ) : 'http://localhost:3000';
+}
+
+/**
+ * Stored preview secret used to authenticate Preview-button clicks.
+ *
+ * @return string
+ */
+function preview_secret(): string {
+	return (string) get_option( 'flavian_headless_preview_secret', '' );
+}
+
+/**
+ * Emit CORS headers for the configured frontend origin.
+ *
+ * Wide-open headers would defeat the purpose; we mirror the configured
+ * frontend origin (or echo the Origin header when it matches one of a small
+ * allowlist) and let WP's standard REST/GraphQL responses pass through.
+ *
+ * @return void
+ */
+function send_cors_headers(): void {
+	if ( ! is_enabled() ) {
+		return;
+	}
+
+	$origin = isset( $_SERVER['HTTP_ORIGIN'] )
+		? esc_url_raw( wp_unslash( $_SERVER['HTTP_ORIGIN'] ) )
+		: '';
+	if ( '' === $origin ) {
+		return;
+	}
+
+	$allowed = array_filter(
+		array_unique(
+			array(
+				frontend_url(),
+				'http://localhost:3000',
+			)
+		)
+	);
+
+	if ( ! in_array( $origin, $allowed, true ) ) {
+		return;
+	}
+
+	header( 'Access-Control-Allow-Origin: ' . $origin );
+	header( 'Access-Control-Allow-Credentials: true' );
+	header( 'Access-Control-Allow-Headers: Authorization, Content-Type, X-WP-Nonce' );
+	header( 'Access-Control-Allow-Methods: GET, POST, OPTIONS' );
+	header( 'Vary: Origin' );
+
+	$method = isset( $_SERVER['REQUEST_METHOD'] )
+		? sanitize_text_field( wp_unslash( $_SERVER['REQUEST_METHOD'] ) )
+		: '';
+	if ( 'OPTIONS' === $method ) {
+		status_header( 204 );
+		exit;
+	}
+}
+add_action( 'init', __NAMESPACE__ . '\\send_cors_headers' );
+
+/**
+ * Rewrite the admin "Preview" link to the frontend's /api/preview route.
+ *
+ * The route validates the secret + post id, sets a Next.js draft-mode
+ * cookie, then redirects to the post's frontend URL.
+ *
+ * @param string   $link Current preview URL.
+ * @param \WP_Post $post Post being previewed.
+ * @return string
+ */
+function rewrite_preview_link( string $link, \WP_Post $post ): string {
+	if ( ! is_enabled() ) {
+		return $link;
+	}
+	$secret = preview_secret();
+	if ( '' === $secret ) {
+		return $link;
+	}
+
+	$query = http_build_query(
+		array(
+			'secret' => $secret,
+			'id'     => $post->ID,
+			'slug'   => $post->post_name,
+			'type'   => $post->post_type,
+		)
+	);
+
+	return frontend_url() . '/api/preview?' . $query;
+}
+add_filter( 'preview_post_link', __NAMESPACE__ . '\\rewrite_preview_link', 10, 2 );
+
+/**
+ * Rewrite "View Post" permalinks shown in the admin to the frontend origin.
+ *
+ * @param string            $permalink Current permalink.
+ * @param \WP_Post|int|null $post      Post object or ID passed by the filter.
+ * @return string
+ */
+function rewrite_permalink( string $permalink, $post ): string {
+	if ( ! is_enabled() || ! is_admin() ) {
+		return $permalink;
+	}
+	$post_obj = get_post( $post );
+	if ( ! $post_obj || 'publish' !== $post_obj->post_status ) {
+		return $permalink;
+	}
+
+	$path = wp_parse_url( $permalink, PHP_URL_PATH );
+	if ( empty( $path ) ) {
+		$path = '/';
+	}
+	return frontend_url() . $path;
+}
+add_filter( 'post_link', __NAMESPACE__ . '\\rewrite_permalink', 10, 2 );
+add_filter( 'page_link', __NAMESPACE__ . '\\rewrite_permalink', 10, 2 );
+
+/**
+ * Remove REST endpoints that leak data unnecessarily for a headless setup.
+ *
+ * Apps that actually need the users endpoint can reinstate it on the
+ * `rest_endpoints` filter with a later priority.
+ *
+ * @param array $endpoints REST endpoints map.
+ * @return array
+ */
+function restrict_rest_endpoints( array $endpoints ): array {
+	if ( ! is_enabled() ) {
+		return $endpoints;
+	}
+	unset(
+		$endpoints['/wp/v2/users'],
+		$endpoints['/wp/v2/users/(?P<id>[\d]+)']
+	);
+	return $endpoints;
+}
+add_filter( 'rest_endpoints', __NAMESPACE__ . '\\restrict_rest_endpoints' );
+
+/**
+ * Register a REST field that confirms the incoming preview_secret matches.
+ *
+ * Returned only to authenticated editors+; anonymous callers get null.
+ *
+ * @return void
+ */
+function register_preview_field(): void {
+	if ( ! is_enabled() ) {
+		return;
+	}
+	register_rest_field(
+		'post',
+		'preview_secret_match',
+		array(
+			'get_callback' => static function ( $post_arr, $field, $request ) {
+				unset( $field );
+				if ( ! current_user_can( 'edit_post', $post_arr['id'] ) ) {
+					return null;
+				}
+				$incoming = (string) $request->get_param( 'preview_secret' );
+				return hash_equals( preview_secret(), $incoming );
+			},
+			'schema'       => array(
+				'description' => 'True when the incoming preview_secret query arg matches the stored secret.',
+				'type'        => 'boolean',
+				'context'     => array( 'edit' ),
+			),
+		)
+	);
+}
+add_action( 'rest_api_init', __NAMESPACE__ . '\\register_preview_field' );
+
+/**
+ * Surface an admin notice on the dashboard showing the current frontend URL.
+ *
+ * @return void
+ */
+function admin_notice_headless_mode(): void {
+	if ( ! is_enabled() || ! current_user_can( 'manage_options' ) ) {
+		return;
+	}
+	$screen = function_exists( 'get_current_screen' ) ? get_current_screen() : null;
+	if ( $screen && 'dashboard' !== $screen->id ) {
+		return;
+	}
+	printf(
+		'<div class="notice notice-info"><p><strong>%s</strong> %s <code>%s</code></p></div>',
+		esc_html__( 'Headless mode is active.', 'flavian' ),
+		esc_html__( 'Previews and post links route to:', 'flavian' ),
+		esc_html( frontend_url() )
+	);
+}
+add_action( 'admin_notices', __NAMESPACE__ . '\\admin_notice_headless_mode' );
diff --git a/scripts/scaffold-frontend.sh b/scripts/scaffold-frontend.sh
new file mode 100644
index 0000000..e874302
--- /dev/null
+++ b/scripts/scaffold-frontend.sh
@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# scripts/scaffold-frontend.sh
+#
+# Generate a Next.js 14 (App Router) headless frontend under frontend/<slug>/
+# from the templates in .claude/templates/frontend/nextjs/.
+#
+# The generated app talks to the headless WordPress configured by
+# scripts/wordpress-install/setup-headless.sh — same preview secret, same
+# GraphQL endpoint.
+#
+# Usage:
+#   bash scripts/scaffold-frontend.sh <slug> [options]
+#
+# Options:
+#   --name "Human Name"     Display name (default: slug title-cased)
+#   --framework nextjs      Frontend framework (default: nextjs; only option today)
+#   --force                 Overwrite an existing frontend/<slug>/ directory
+#   --dry-run               Print actions but do not write any files
+#
+# Exit codes: 0 = success, 1 = validation/IO error, 2 = bad usage.
+
+set -euo pipefail
+
+PROJECT_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+FRONTEND_DIR="$PROJECT_ROOT/frontend"
+
+SLUG=""
+NAME=""
+FRAMEWORK="nextjs"
+FORCE=0
+DRY_RUN=0
+
+usage() {
+  sed -n '2,/^$/p' "$0" | sed 's/^# \{0,1\}//'
+  exit "${1:-2}"
+}
+
+die() {
+  printf '✗ %s\n' "$*" >&2
+  exit 1
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --name)      NAME="$2"; shift 2 ;;
+    --framework) FRAMEWORK="$2"; shift 2 ;;
+    --force)     FORCE=1; shift ;;
+    --dry-run)   DRY_RUN=1; shift ;;
+    -h|--help)   usage 0 ;;
+    --*)         die "Unknown flag: $1" ;;
+    *)
+      if [ -z "$SLUG" ]; then SLUG="$1"; shift
+      else die "Unexpected positional arg: $1"
+      fi
+      ;;
+  esac
+done
+
+[ -n "$SLUG" ] || usage 2
+
+# Only nextjs ships today; nuxt/astro are tracked as follow-ups.
+if [ "$FRAMEWORK" != "nextjs" ]; then
+  die "Framework '$FRAMEWORK' is not yet implemented. Use --framework nextjs."
+fi
+
+TEMPLATE_DIR="$PROJECT_ROOT/.claude/templates/frontend/$FRAMEWORK"
+[ -d "$TEMPLATE_DIR" ] || die "Template directory not found: $TEMPLATE_DIR"
+
+# --- Slug validation ---
+if ! [[ "$SLUG" =~ ^[a-z][a-z0-9-]*$ ]]; then
+  die "Invalid slug '$SLUG'. Must match ^[a-z][a-z0-9-]*\$ (lowercase, digits, hyphens; must start with a letter)."
+fi
+
+if [ -z "$NAME" ]; then
+  NAME="$(printf '%s' "$SLUG" | sed -E 's/(^|-)([a-z])/\1\u\2/g' | tr '-' ' ')"
+fi
+
+TARGET_DIR="$FRONTEND_DIR/$SLUG"
+
+if [ -e "$TARGET_DIR" ]; then
+  if [ "$FORCE" -eq 1 ]; then
+    [ "$DRY_RUN" -eq 1 ] || rm -rf "$TARGET_DIR"
+  else
+    die "$TARGET_DIR already exists. Re-run with --force to overwrite."
+  fi
+fi
+
+# --- Token substitution helper ---
+sed_escape() {
+  printf '%s' "$1" | sed -e 's/[\\&|]/\\&/g'
+}
+
+render_file() {
+  local src="$1" dst="$2"
+  local slug_e name_e
+  slug_e="$(sed_escape "$SLUG")"
+  name_e="$(sed_escape "$NAME")"
+  sed \
+    -e "s|{{APP_SLUG}}|${slug_e}|g" \
+    -e "s|{{APP_NAME}}|${name_e}|g" \
+    "$src" > "$dst"
+}
+
+printf '▸ Scaffolding %s frontend: %s\n' "$FRAMEWORK" "$SLUG"
+printf '  Name:      %s\n' "$NAME"
+printf '  Target:    %s\n' "$TARGET_DIR"
+[ "$DRY_RUN" -eq 1 ] && printf '  Dry-run:   yes\n'
+echo ""
+
+COUNT=0
+while IFS= read -r src; do
+  rel="${src#$TEMPLATE_DIR/}"
+  rel="${rel%.tmpl}"
+  dst="$TARGET_DIR/$rel"
+
+  if [ "$DRY_RUN" -eq 1 ]; then
+    printf '  + %s\n' "$rel"
+  else
+    mkdir -p "$(dirname "$dst")"
+    render_file "$src" "$dst"
+  fi
+  COUNT=$((COUNT + 1))
+done < <(find "$TEMPLATE_DIR" -type f -name '*.tmpl' | LC_ALL=C sort)
+
+echo ""
+if [ "$DRY_RUN" -eq 1 ]; then
+  printf '✓ Dry run: would write %d files to %s\n' "$COUNT" "$TARGET_DIR"
+else
+  printf '✓ Wrote %d files to %s\n' "$COUNT" "$TARGET_DIR"
+  printf '\nNext steps:\n'
+  printf '  1. docker compose --profile headless up headless-installer\n'
+  printf '     (installs WPGraphQL + prints WORDPRESS_PREVIEW_SECRET)\n'
+  printf '  2. cd frontend/%s\n' "$SLUG"
+  printf '     cp .env.local.example .env.local   # paste the printed values\n'
+  printf '     pnpm install && pnpm dev\n'
+  printf '  3. Open http://localhost:3000\n'
+fi
diff --git a/scripts/wordpress-install/setup-headless.sh b/scripts/wordpress-install/setup-headless.sh
new file mode 100644
index 0000000..c60950d
--- /dev/null
+++ b/scripts/wordpress-install/setup-headless.sh
@@ -0,0 +1,173 @@
+#!/usr/bin/env bash
+# Install and configure headless WordPress inside the Docker WP container.
+#
+# What it does, in order:
+#   1. Verifies WordPress is installed; bails out cleanly if not.
+#   2. Installs and activates WPGraphQL (+ optional companions).
+#   3. Sets HEADLESS_MODE option so flavian-headless.php mu-plugin activates.
+#   4. Generates a preview secret and stores it in wp_options.
+#   5. Configures pretty permalinks (required for REST + WPGraphQL routes).
+#   6. Pings /graphql and /wp-json/wp/v2/ to confirm both APIs respond.
+#
+# Usage:
+#   ./scripts/wordpress-install/setup-headless.sh [--frontend-url URL]
+#                                                 [--no-jwt]
+#                                                 [--no-blocks]
+#                                                 [--preview-secret VALUE]
+#
+# Requires: docker compose, the project's WordPress container running.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+FRONTEND_URL="${HEADLESS_FRONTEND_URL:-http://localhost:3000}"
+INSTALL_JWT=true
+INSTALL_BLOCKS=true
+PREVIEW_SECRET=""
+
+usage() {
+  cat <<EOF
+Usage: $(basename "$0") [options]
+
+  --frontend-url URL       Origin allowed by CORS + used for preview links
+                           (default: http://localhost:3000)
+  --no-jwt                 Skip WPGraphQL JWT Auth (auth via app passwords only)
+  --no-blocks              Skip WPGraphQL Content Blocks (FSE block exposure)
+  --preview-secret VALUE   Use a specific preview secret instead of generating
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --frontend-url) FRONTEND_URL="$2"; shift 2 ;;
+    --no-jwt) INSTALL_JWT=false; shift ;;
+    --no-blocks) INSTALL_BLOCKS=false; shift ;;
+    --preview-secret) PREVIEW_SECRET="$2"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "Unknown argument: $1" >&2; usage; exit 2 ;;
+  esac
+done
+
+log() { printf '\n[setup-headless] %s\n' "$*"; }
+
+WP_CONTAINER="${WP_CONTAINER:-flavian-wp}"
+if [[ -f /.dockerenv ]] || [[ "${WP_USE_DOCKER_EXEC:-}" == "true" ]]; then
+  wp_in_container() {
+    docker exec -i "$WP_CONTAINER" wp "$@" --allow-root
+  }
+else
+  wp_in_container() {
+    docker compose exec -T wordpress wp "$@" --allow-root
+  }
+fi
+
+# 0. Prerequisites -----------------------------------------------------------
+if ! command -v docker >/dev/null 2>&1; then
+  echo "[ERROR] docker not found in PATH" >&2
+  exit 1
+fi
+
+if [[ ! -f /.dockerenv ]]; then
+  if ! docker compose ps --status running --services 2>/dev/null | grep -q '^wordpress$'; then
+    log "WordPress container not running — starting it"
+    docker compose up -d wordpress db
+    log "Waiting for WordPress to become healthy..."
+    for _ in $(seq 1 30); do
+      if docker compose exec -T wordpress curl -sf http://localhost/ >/dev/null 2>&1; then
+        break
+      fi
+      sleep 2
+    done
+  fi
+fi
+
+if ! wp_in_container core is-installed >/dev/null 2>&1; then
+  echo "[ERROR] WordPress is not installed yet. Run the WP install step first" >&2
+  exit 1
+fi
+
+# 1. Install WPGraphQL + companions ------------------------------------------
+install_plugin() {
+  local slug="$1"
+  if wp_in_container plugin is-installed "$slug" >/dev/null 2>&1; then
+    log "$slug already installed"
+  else
+    log "Installing $slug"
+    wp_in_container plugin install "$slug" --activate
+  fi
+  if ! wp_in_container plugin is-active "$slug" >/dev/null 2>&1; then
+    wp_in_container plugin activate "$slug"
+  fi
+}
+
+install_plugin wp-graphql
+
+# wp-graphql-jwt-authentication: token-based auth for the frontend's
+# preview/draft fetches. Optional — apps can also use WP application passwords.
+if $INSTALL_JWT; then
+  install_plugin wp-graphql-jwt-authentication || \
+    log "JWT plugin install failed — continuing without it"
+fi
+
+# wp-graphql-content-blocks: exposes the FSE block tree as a queryable field
+# (editorBlocks). Critical for any frontend that wants to render block content.
+if $INSTALL_BLOCKS; then
+  install_plugin wp-graphql-content-blocks || \
+    log "Content Blocks plugin install failed — continuing without it"
+fi
+
+# 2. Headless mode toggle + secrets ------------------------------------------
+log "Enabling HEADLESS_MODE option"
+wp_in_container option update flavian_headless_mode 1 >/dev/null
+wp_in_container option update flavian_headless_frontend_url "$FRONTEND_URL" >/dev/null
+
+if [[ -z "$PREVIEW_SECRET" ]]; then
+  # 32-byte hex secret. wp eval avoids needing openssl in the container.
+  PREVIEW_SECRET="$(wp_in_container eval 'echo bin2hex(random_bytes(32));' 2>/dev/null | tr -d '\r\n')"
+fi
+wp_in_container option update flavian_headless_preview_secret "$PREVIEW_SECRET" >/dev/null
+log "Preview secret stored in wp_options (key: flavian_headless_preview_secret)"
+
+# JWT signing key — required by wp-graphql-jwt-authentication. The plugin
+# reads GRAPHQL_JWT_AUTH_SECRET_KEY from wp-config.php OR a filter. We can't
+# write to wp-config from here safely, so we surface the value to the user.
+if $INSTALL_JWT; then
+  JWT_SECRET="$(wp_in_container eval 'echo bin2hex(random_bytes(32));' 2>/dev/null | tr -d '\r\n')"
+  wp_in_container option update flavian_headless_jwt_secret "$JWT_SECRET" >/dev/null
+fi
+
+# 3. Permalinks --------------------------------------------------------------
+log "Setting pretty permalinks"
+wp_in_container option update permalink_structure '/%postname%/' >/dev/null
+wp_in_container rewrite flush --hard >/dev/null
+
+# 4. Verify endpoints --------------------------------------------------------
+log "Verifying API endpoints"
+if wp_in_container option get permalink_structure >/dev/null 2>&1; then
+  REST_STATUS=$(docker exec "$WP_CONTAINER" curl -s -o /dev/null -w '%{http_code}' http://localhost/wp-json/wp/v2/posts 2>/dev/null || echo "000")
+  log "REST API /wp-json/wp/v2/posts → HTTP $REST_STATUS"
+
+  GQL_STATUS=$(docker exec "$WP_CONTAINER" curl -s -o /dev/null -w '%{http_code}' \
+    -X POST -H 'Content-Type: application/json' \
+    -d '{"query":"{ generalSettings { title } }"}' \
+    http://localhost/graphql 2>/dev/null || echo "000")
+  log "GraphQL /graphql → HTTP $GQL_STATUS"
+fi
+
+# 5. Summary -----------------------------------------------------------------
+echo ""
+log "Headless WordPress configured. Endpoints (host):"
+log "  REST API:    http://localhost:8080/wp-json/wp/v2/"
+log "  GraphQL:     http://localhost:8080/graphql"
+log "  GraphiQL UI: http://localhost:8080/wp-admin/admin.php?page=graphiql-ide"
+echo ""
+log "Frontend env values to copy into frontend/.env.local:"
+echo "  WORDPRESS_URL=http://localhost:8080"
+echo "  WORDPRESS_GRAPHQL_URL=http://localhost:8080/graphql"
+echo "  WORDPRESS_PREVIEW_SECRET=$PREVIEW_SECRET"
+if $INSTALL_JWT; then
+  echo "  # Add the following line to wp-config.php for JWT auth:"
+  echo "  # define( 'GRAPHQL_JWT_AUTH_SECRET_KEY', '$JWT_SECRET' );"
+fi