@soloworks/smking-next 0.21.5 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @soloworks/smking-next
 
+## 0.22.0 — 2026-07-25
+
+- AEO requests now skip the configured `SMKING_CMS_PATH`, preventing duplicate
+  SEO and JSON-LD on Page Zero Blog pages.
+- AEO-only installs report `cms_base_path: null`; the wizard writes the Blog
+  path explicitly whenever Blog is selected.
+- `smking-next doctor` accepts `--surfaces=aeo`, `cms`, or both and verifies
+  `transpilePackages`, Blog runtime, catch-all, preview, webhook, and secrets.
+
+## 0.21.6 — 2026-07-20
+
+**Next.js metadata can now be authoritative instead of duplicated.**
+
+- Added `withSmkingMetadata()` for the App Router `generateMetadata` export.
+  Ready Page Zero SEO fields override the matching host fields while unrelated
+  host metadata stays intact.
+- Added `<SmkingAEO includeSeo={false} />` so JSON-LD and hidden AEO content
+  remain rendered without emitting duplicate title and meta elements.
+
 ## 0.21.5 — 2026-07-20
 
 **AEO path discovery now works on Vercel without replacing host proxy responses.**

package/README.md

@@ -8,7 +8,9 @@ AI-native SEO (AEO) for Next.js. One server component injects JSON-LD, OG tags,
 
 ## Install
 
-**Don't follow this README to install.** Your Page Zero dashboard generates a per-site install prompt with the real `SMKING_API_KEY`, `SMKING_BASE_URL`, and (if you use CMS) `SMKING_WEBHOOK_SECRET` baked in, plus copy-pasteable layout / route shims. The prompt is the source of truth and stays in sync with the SDK version.
+Your Page Zero dashboard generates the source-of-truth install prompt with the
+real environment values, selected surfaces, Blog path, route shims, and
+version-aligned verification command.
 
 Two ways to get it:
 
@@ -20,18 +22,29 @@ npx @soloworks/smking-wizard@latest
 # install panel into your editor / coding agent.
 ```
 
-The wizard owns: `pnpm add @soloworks/smking-next`, `<SmkingAEO />` mount in `app/layout.tsx`, env writes, `app/api/smking/webhook/route.ts` shim, and doctor verification.
+The wizard can install **AEO + SEO**, **Blog only**, or both. It owns package
+installation, selected layout mounts, environment writes, Blog routes, the
+surface-aware doctor, and the real production build.
 
-## How metadata wins / loses
+## Authoritative metadata
 
-Both `<SmkingAEO />` and your own `generateMetadata` emit head tags. Next.js + React 19 head dedup applies last-write-wins:
+Use `withSmkingMetadata()` from the real root layout's `generateMetadata`
+export, then mount `<SmkingAEO includeSeo={false} />` for JSON-LD and hidden
+AEO fragments. This produces one authoritative title and description instead
+of relying on render order.
 
-- **No `generateMetadata`** → Page Zero's `<title>` / `og:*` are used.
-- **You write `generateMetadata` in a layout / page** → your tags override Page Zero's for that route segment.
-
-This is the pattern: Page Zero provides the AEO/SEO baseline, and you override per-page when needed. No HOF, no codemod.
+```tsx
+export async function generateMetadata(): Promise<Metadata> {
+  return withSmkingMetadata(hostMetadata, {
+    apiKey: process.env.SMKING_API_KEY!,
+  });
+}
 
-For client pages (`'use client'`) that need dynamic metadata, write a sibling `layout.tsx` with `generateMetadata` — standard Next.js workflow, unrelated to smking.
+<SmkingAEO
+  apiKey={process.env.SMKING_API_KEY!}
+  includeSeo={false}
+/>
+```
 
 ## How outage tolerance works
 
@@ -53,7 +66,9 @@ interface SmkingAEOProps {
   apiKey: string; // required
   baseUrl?: string; // override SMKING_BASE_URL env
   path?: string; // explicit path; auto-resolved from headers() otherwise
+  url?: string; // explicit absolute request URL when path is overridden
   revalidate?: number; // ISR seconds; default 3600 (1h)
+  includeSeo?: boolean; // false when using withSmkingMetadata()
 }
 ```
 
@@ -72,17 +87,13 @@ if (aeo?.status === 'ready') {
 }
 ```
 
-### Webhook payload
-
-```json
-POST /api/smking-revalidate
-Authorization: Bearer <SMKING_WEBHOOK_TOKEN>
-Content-Type: application/json
-
-{ "paths": ["/products/abc", "/products/xyz"] }
-```
+### Publish webhook
 
-Response: `{ revalidated: number, errors: number }`. `errors > 0` means some tags couldn't be revalidated (others still succeeded — partial-success delivery).
+The source-of-truth install prompt creates
+`app/api/smking/webhook/route.ts`, which re-exports `POST` from
+`@soloworks/smking-next/webhook`. The handler verifies the
+`SMKING_WEBHOOK_SECRET` HMAC and invalidates the affected AEO or Blog cache
+tags.
 
 ## Mount the runtime once (v0.16.1+)
 
@@ -112,11 +123,15 @@ Optional `baseUrl` prop overrides `process.env.SMKING_BASE_URL`. Default: `https
 
 Without `<SmkingRuntime />`, `<SmkingCms>` content still renders but the Tailwind utility classes from the dashboard's cva variants resolve to dead strings — the page reaches the browser unstyled. The wizard installer auto-adds this mount; if you're upgrading manually from < v0.16.1, add the one line above.
 
-## CMS rendering (optional, v0.11.0+)
+## Page Zero Blog (optional)
 
-The base install only wires AEO. If you author content in the Page Zero dashboard CMS and want to render it on your Next.js site, use the `<SmkingCms slug="…" />` Server Component.
+If you publish Blog pages from the Page Zero dashboard, render them with the
+`<SmkingCms slug="…" />` Server Component.
 
-The SDK **does not have a "CMS root" config** — you choose any URL prefix (`/blog`, `/knowledge`, `/shop/articles`) and wire your own route. The component takes a `slug` prop, fetches the published page from `${SMKING_BASE_URL}/api/v1/public/page?slug=…`, and renders the Tiptap ProseMirror JSON as `<article class="smk-cms">…</article>` via `@tiptap/static-renderer/pm/react`. SEO `<title>` / `<meta>` / `og:*` / canonical hoist into `<head>` automatically via React 19.
+Choose a URL path such as `/blog`, `/knowledge`, or `/shop/articles` and set
+the same value as `SMKING_CMS_PATH`. The wizard writes it automatically.
+Root AEO requests skip that path so `<SmkingCms>` is the only source of SEO and
+JSON-LD on Blog pages.
 
 ### Optional catch-all route (handles the CMS root + nested slugs)
 

package/bin/install.mjs

@@ -1,26 +1,7 @@
 #!/usr/bin/env node
 /**
- * `npx @soloworks/smking-next [install|doctor] [--json]`
- *
- * Two subcommands share this entry point. The file ships as plain ESM
- * (`.mjs`) since Node's `--experimental-strip-types` is excluded from
- * files under `node_modules` by design — so `bin/install.ts` (the
- * previous v0.12.0 layout) fails with "Type-Stripping is not supported
- * for files under node_modules" the moment a customer runs `npx
- * @soloworks/smking-next`. Source modules (`src/*.ts`) are still TS —
- * Next.js's bundler handles them at customer build time. Only this
- * standalone-executable bin script needed to drop TS.
- *
- * - **install** (default) — One-shot scaffold for the three takeover
- *   drop-in files (sitemap.ts / robots.ts / llms.txt route). Idempotent:
- *   already-existing files are skipped, never overwritten.
- *
- * - **doctor** — Self-check (env presence + <SmkingAEO /> usage + API
- *   reachable). `--json` flag emits structured output for the
- *   @smking/wizard install agent's `run_doctor` MCP tool.
- *
- * Conventional Next.js layout assumed: `app/` at repo root (or under
- * `src/app/` — detected). Both subcommands exit 1 on missing app/.
+ * `smking-next install` scaffolds missing AEO discovery routes.
+ * `smking-next doctor` verifies the surfaces selected by the installer.
  */
 import {
   existsSync,
@@ -31,13 +12,6 @@ import {
 } from "node:fs";
 import { join } from "node:path";
 
-// ── install (file scaffold) ─────────────────────────────────────
-
-/**
- * @typedef {{ path: string, content: string, label: string }} FileSpec
- */
-
-/** @type {FileSpec[]} */
 const FILES = [
   {
     path: "sitemap.ts",
@@ -57,11 +31,7 @@ const FILES = [
 ];
 
 function detectAppDir() {
-  const candidates = ["app", "src/app"];
-  for (const c of candidates) {
-    if (existsSync(c)) return c;
-  }
-  return null;
+  return ["app", "src/app"].find((path) => existsSync(path)) ?? null;
 }
 
 function runInstall() {
@@ -72,7 +42,6 @@ function runInstall() {
     );
     return 1;
   }
-  console.log(`📂 Using app directory: ${appDir}/\n`);
 
   let created = 0;
   let skipped = 0;
@@ -83,62 +52,28 @@ function runInstall() {
       skipped += 1;
       continue;
     }
-    const dir = fullPath.includes("/")
-      ? fullPath.substring(0, fullPath.lastIndexOf("/"))
-      : appDir;
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(fullPath, file.content, "utf-8");
+    mkdirSync(fullPath.slice(0, fullPath.lastIndexOf("/")), {
+      recursive: true,
+    });
+    writeFileSync(fullPath, file.content, "utf8");
     console.log(`✓  created: ${file.label}`);
     created += 1;
   }
-
-  console.log(
-    `\n${created} created, ${skipped} skipped. Set SMKING_API_KEY and SMKING_BASE_URL in your environment.`,
-  );
+  console.log(`\n${created} created, ${skipped} skipped.`);
   return 0;
 }
 
-// ── doctor (self-check) ─────────────────────────────────────────
-
-/**
- * Load `.env.local` + `.env` from cwd into `process.env`, matching the
- * Next.js convention so `npx @soloworks/smking-next doctor` sees the same
- * env vars the customer's `next dev` / `next build` would. Standalone
- * Node bin scripts don't get framework env loading for free — without
- * this, doctor would fail "SMKING_API_KEY not set" on every install where
- * the wizard wrote to `.env.local` instead of shell env.
- *
- * `process.loadEnvFile` is available Node 20.6+ (experimental → stable
- * in 21.7+). Next.js 16 requires Node 20+ so the customer environment is
- * guaranteed to have it. Existing process env wins (we don't overwrite —
- * matches Next.js precedence: shell env > .env.local > .env).
- *
- * Files load in reverse-precedence order (lowest first) so later files
- * win when both define the same key. Next.js's actual order: .env.local
- * > .env.development.local > .env.development > .env. We do the minimal
- * pair customers actually use.
- */
 function loadEnvFiles() {
   for (const file of [".env", ".env.local"]) {
     if (!existsSync(file)) continue;
     try {
       process.loadEnvFile(file);
     } catch {
-      // Older Node fallback or unreadable file — silently skip; doctor
-      // will report SMKING_API_KEY not set as it would have anyway.
+      // The following checks surface missing values.
     }
   }
 }
 
-/**
- * @typedef {{ name: string, status: "pass" | "fail" | "info", detail: string }} DoctorCheck
- */
-
-/**
- * @param {string} name
- * @param {string} [prefix]
- * @returns {DoctorCheck}
- */
 function checkEnv(name, prefix) {
   const value = process.env[name];
   if (!value) {
@@ -152,7 +87,7 @@ function checkEnv(name, prefix) {
     return {
       name: `${name} set`,
       status: "fail",
-      detail: `value must start with \`${prefix}\``,
+      detail: `value must start with ${prefix}`,
     };
   }
   return {
@@ -162,20 +97,12 @@ function checkEnv(name, prefix) {
   };
 }
 
-/**
- * Find the shallowest layout that owns html + body. This supports
- * internationalized roots such as app/[locale]/layout.tsx without
- * mistaking a nested section layout for the application root.
- * @param {string} appDir
- * @returns {string | null}
- */
 function findRootLayout(appDir) {
   const conventional = ["tsx", "jsx", "ts", "js"]
     .map((extension) => join(appDir, `layout.${extension}`))
     .find((path) => existsSync(path));
   if (conventional) return conventional;
 
-  /** @type {Array<{ path: string, depth: number }>} */
   const nested = [];
   function visit(directory, depth) {
     if (depth > 4) return;
@@ -187,194 +114,318 @@ function findRootLayout(appDir) {
         continue;
       }
       if (!/^layout\.(tsx|jsx|ts|js)$/.test(entry.name)) continue;
-      const content = readFileSync(path, "utf-8");
+      const content = readFileSync(path, "utf8");
       if (/<html(?:\s|>)/.test(content) && /<body(?:\s|>)/.test(content)) {
         nested.push({ path, depth });
       }
     }
   }
-
   visit(appDir, 0);
   nested.sort((a, b) => a.depth - b.depth || a.path.localeCompare(b.path));
   return nested[0]?.path ?? null;
 }
 
-/**
- * @param {string} appDir
- * @returns {DoctorCheck}
- */
-function checkLayoutUsage(appDir) {
-  const layoutPath = findRootLayout(appDir);
-  if (!layoutPath) {
+function checkNextConfig() {
+  const configPath = [
+    "next.config.ts",
+    "next.config.mjs",
+    "next.config.js",
+    "next.config.cjs",
+  ].find((path) => existsSync(path));
+  if (!configPath) {
     return {
-      name: "<SmkingAEO /> in root layout",
+      name: "Next.js transpilePackages",
       status: "fail",
-      detail: `no root layout owning <html> and <body> found under ${appDir}/`,
+      detail:
+        "next.config.* not found; add @soloworks/smking-next to transpilePackages",
     };
   }
-
-  const content = readFileSync(layoutPath, "utf-8");
-  if (!content.includes("SmkingAEO")) {
+  const content = readFileSync(configPath, "utf8");
+  if (
+    !content.includes("transpilePackages") ||
+    !content.includes("@soloworks/smking-next")
+  ) {
     return {
-      name: "<SmkingAEO /> in root layout",
+      name: "Next.js transpilePackages",
       status: "fail",
-      detail: `${layoutPath} does not import SmkingAEO. Add: import { SmkingAEO } from "@soloworks/smking-next"; then render <SmkingAEO apiKey={process.env.SMKING_API_KEY!} /> inside <body>.`,
+      detail: `${configPath} must include @soloworks/smking-next in transpilePackages`,
     };
   }
   return {
-    name: "<SmkingAEO /> in root layout",
+    name: "Next.js transpilePackages",
     status: "pass",
-    detail: layoutPath,
+    detail: configPath,
   };
 }
 
-/**
- * @returns {Promise<DoctorCheck>}
- */
-async function checkApiReachable() {
+function checkAeoLayout(appDir) {
+  const layoutPath = findRootLayout(appDir);
+  if (!layoutPath) {
+    return {
+      name: "AEO + SEO in root layout",
+      status: "fail",
+      detail: `no root layout owning <html> and <body> found under ${appDir}/`,
+    };
+  }
+  const content = readFileSync(layoutPath, "utf8");
+  const missing = [];
+  if (!content.includes("SmkingAEO")) missing.push("SmkingAEO");
+  if (!content.includes("withSmkingMetadata(")) {
+    missing.push("withSmkingMetadata()");
+  }
+  if (!/includeSeo\s*=\s*\{\s*false\s*\}/.test(content)) {
+    missing.push("includeSeo={false}");
+  }
+  return missing.length === 0
+    ? {
+        name: "AEO + SEO in root layout",
+        status: "pass",
+        detail: layoutPath,
+      }
+    : {
+        name: "AEO + SEO in root layout",
+        status: "fail",
+        detail: `${layoutPath} is missing ${missing.join(", ")}`,
+      };
+}
+
+function parseBlogPath() {
+  const prefix = process.env.SMKING_CMS_PATH;
+  if (
+    !prefix ||
+    prefix.length > 160 ||
+    !/^\/[A-Za-z0-9._~-]+(?:\/[A-Za-z0-9._~-]+)*$/.test(prefix)
+  ) {
+    return null;
+  }
+  const segments = prefix.slice(1).split("/");
+  if (
+    segments.some((segment) => segment === "." || segment === "..") ||
+    ["api", "_next", "smking-preview"].includes(segments[0].toLowerCase())
+  ) {
+    return null;
+  }
+  return { prefix, segments };
+}
+
+function checkBlog(appDir) {
+  const parsed = parseBlogPath();
+  if (!parsed) {
+    return [
+      {
+        name: "SMKING_CMS_PATH set",
+        status: "fail",
+        detail: "set a safe Blog path such as /blog",
+      },
+    ];
+  }
+
+  const secret = process.env.SMKING_WEBHOOK_SECRET;
+  const layoutPath = findRootLayout(appDir);
+  const layout = layoutPath ? readFileSync(layoutPath, "utf8") : "";
+  const blogDir = join(appDir, ...parsed.segments, "[[...slug]]");
+  const existsWithExtension = (base, name, extensions) =>
+    extensions.some((extension) => existsSync(join(base, `${name}.${extension}`)));
+
+  return [
+    {
+      name: "SMKING_CMS_PATH set",
+      status: "pass",
+      detail: parsed.prefix,
+    },
+    secret && /^[A-Fa-f0-9]{64}$/.test(secret)
+      ? {
+          name: "SMKING_WEBHOOK_SECRET set",
+          status: "pass",
+          detail: `${secret.slice(0, 8)}…`,
+        }
+      : {
+          name: "SMKING_WEBHOOK_SECRET set",
+          status: "fail",
+          detail: "must be a 64-character hex secret",
+        },
+    layoutPath &&
+    layout.includes("SmkingRuntime") &&
+    /<SmkingRuntime[^>]*apiKey\s*=/.test(layout)
+      ? {
+          name: "Blog runtime in root layout",
+          status: "pass",
+          detail: layoutPath,
+        }
+      : {
+          name: "Blog runtime in root layout",
+          status: "fail",
+          detail:
+            "mount <SmkingRuntime apiKey={process.env.SMKING_API_KEY!} /> in the root layout",
+        },
+    {
+      name: "Blog catch-all route",
+      status: existsWithExtension(blogDir, "page", [
+        "tsx",
+        "jsx",
+        "ts",
+        "js",
+      ])
+        ? "pass"
+        : "fail",
+      detail: `${blogDir}/page.*`,
+    },
+    {
+      name: "Blog preview route",
+      status: existsWithExtension(
+        join(appDir, "smking-preview"),
+        "route",
+        ["ts", "js"],
+      )
+        ? "pass"
+        : "fail",
+      detail: `${appDir}/smking-preview/route.*`,
+    },
+    {
+      name: "Blog publish webhook",
+      status: existsWithExtension(
+        join(appDir, "api", "smking", "webhook"),
+        "route",
+        ["ts", "js"],
+      )
+        ? "pass"
+        : "fail",
+      detail: `${appDir}/api/smking/webhook/route.*`,
+    },
+  ];
+}
+
+async function checkApi(surface) {
   const apiKey = process.env.SMKING_API_KEY;
   const baseUrl = process.env.SMKING_BASE_URL;
+  const label = surface === "cms" ? "Blog API reachable" : "AEO API reachable";
   if (!apiKey || !baseUrl) {
     return {
-      name: "API reachable",
+      name: label,
       status: "info",
-      detail: "skipped — SMKING_API_KEY or SMKING_BASE_URL not set",
+      detail: "skipped because base environment is incomplete",
     };
   }
-
-  // Probe the actual AEO endpoint, not the base URL root. Hitting root
-  // would pass for any live host (a typo'd domain, google.com); the
-  // endpoint either returns the AEO payload or a known auth/validation
-  // status — both confirm the route exists.
-  const endpoint = `${baseUrl.replace(/\/$/, "")}/api/v1/public/aeo`;
-  const url = `${endpoint}?key=${encodeURIComponent(apiKey)}&path=%2F`;
+  const endpoint =
+    surface === "cms"
+      ? `${baseUrl.replace(/\/$/, "")}/api/v1/public/page`
+      : `${baseUrl.replace(/\/$/, "")}/api/v1/public/aeo`;
+  const url =
+    surface === "cms"
+      ? `${endpoint}?key=${encodeURIComponent(apiKey)}&slug=__page_zero_doctor__`
+      : `${endpoint}?key=${encodeURIComponent(apiKey)}&path=%2F`;
   try {
-    const res = await fetch(url, {
-      signal: AbortSignal.timeout(3000),
+    const response = await fetch(url, {
+      signal: AbortSignal.timeout(3_000),
     });
-
-    if (res.ok) {
+    if (response.ok) {
       return {
-        name: "API reachable",
+        name: label,
         status: "pass",
-        detail: `${endpoint} → HTTP ${res.status}; API key accepted`,
-      };
-    }
-    if (res.status === 401) {
-      return {
-        name: "API reachable",
-        status: "fail",
-        detail: `HTTP 401 from ${endpoint} — SMKING_API_KEY rejected`,
+        detail: `${endpoint} → HTTP ${response.status}; API key accepted`,
       };
     }
-    if (res.status === 404) {
-      const payload = await res
+    if (response.status === 404) {
+      const payload = await response
         .clone()
         .json()
         .catch(() => null);
       if (payload?.status === "not_found") {
         return {
-          name: "API reachable",
+          name: label,
           status: "pass",
           detail: `${endpoint} → HTTP 404 not_found; API key accepted`,
         };
       }
-      return {
-        name: "API reachable",
-        status: "fail",
-        detail: `HTTP 404 from ${endpoint} — SMKING_BASE_URL likely points at the wrong host`,
-      };
-    }
-    if (res.status >= 500) {
-      return {
-        name: "API reachable",
-        status: "fail",
-        detail: `upstream HTTP ${res.status} from ${endpoint}`,
-      };
     }
     return {
-      name: "API reachable",
+      name: label,
       status: "fail",
-      detail: `${endpoint} returned unexpected HTTP ${res.status}`,
+      detail: `${endpoint} returned HTTP ${response.status}`,
     };
-  } catch (err) {
+  } catch (error) {
     return {
-      name: "API reachable",
+      name: label,
       status: "fail",
-      detail: `connection failed: ${err instanceof Error ? err.message : String(err)}`,
+      detail: `connection failed: ${error instanceof Error ? error.message : String(error)}`,
     };
   }
 }
 
-/**
- * @param {boolean} jsonOutput
- * @returns {Promise<number>}
- */
-async function runDoctor(jsonOutput) {
-  // Mirror Next.js env loading so doctor sees what `next dev` would.
-  // Customers run this from project root; .env.local is the wizard's
-  // write target for SMKING_API_KEY + SMKING_BASE_URL.
+async function runDoctor(jsonOutput, surfaces) {
   loadEnvFiles();
-
   const appDir = detectAppDir();
-  /** @type {DoctorCheck[]} */
   const checks = [
     checkEnv("SMKING_API_KEY", "pk_"),
     checkEnv("SMKING_BASE_URL", "http"),
-    appDir
-      ? checkLayoutUsage(appDir)
-      : {
-          name: "<SmkingAEO /> in root layout",
-          status: "info",
-          detail: "no app/ or src/app/ directory found — skipped",
-        },
-    await checkApiReachable(),
+    checkNextConfig(),
   ];
 
-  const hasFailure = checks.some((c) => c.status === "fail");
+  if (!appDir) {
+    checks.push({
+      name: "App Router",
+      status: "fail",
+      detail: "no app/ or src/app/ directory found",
+    });
+  } else {
+    if (surfaces.includes("aeo")) checks.push(checkAeoLayout(appDir));
+    else {
+      checks.push({
+        name: "AEO + SEO selection",
+        status: "info",
+        detail: "disabled by Blog-only install",
+      });
+    }
+    if (surfaces.includes("cms")) checks.push(...checkBlog(appDir));
+  }
+
+  if (surfaces.includes("aeo")) checks.push(await checkApi("aeo"));
+  if (surfaces.includes("cms")) checks.push(await checkApi("cms"));
 
-  // JSON mode: parseable structured output for @smking/wizard's run_doctor
-  // tool. Stable shape — do not break without bumping wizard version.
+  const summary = {
+    passed: checks.filter((check) => check.status === "pass").length,
+    failed: checks.filter((check) => check.status === "fail").length,
+    info: checks.filter((check) => check.status === "info").length,
+    ok: !checks.some((check) => check.status === "fail"),
+  };
   if (jsonOutput) {
-    const summary = {
-      passed: checks.filter((c) => c.status === "pass").length,
-      failed: checks.filter((c) => c.status === "fail").length,
-      info: checks.filter((c) => c.status === "info").length,
-      ok: !hasFailure,
-    };
     console.log(JSON.stringify({ checks, summary }));
-    return hasFailure ? 1 : 0;
-  }
-
-  for (const check of checks) {
-    const icon =
-      check.status === "pass" ? "✅" : check.status === "fail" ? "❌" : "ℹ️ ";
-    console.log(`${icon} ${check.name} — ${check.detail}`);
-  }
-  console.log();
-  if (hasFailure) {
-    console.log("❌ Page Zero: install incomplete — fix the items above.");
-    return 1;
+  } else {
+    for (const check of checks) {
+      const icon =
+        check.status === "pass" ? "✅" : check.status === "fail" ? "❌" : "ℹ️ ";
+      console.log(`${icon} ${check.name} — ${check.detail}`);
+    }
+    console.log(
+      summary.ok
+        ? "\n✅ Page Zero: install OK."
+        : "\n❌ Page Zero: install incomplete.",
+    );
   }
-  console.log("✅ Page Zero: install OK.");
-  return 0;
+  return summary.ok ? 0 : 1;
 }
 
-// ── Entry dispatcher ────────────────────────────────────────────
-
 async function main() {
   const subcommand = process.argv[2];
   const jsonOutput = process.argv.includes("--json");
-
-  if (subcommand === "doctor") {
-    return runDoctor(jsonOutput);
+  const surfacesArg = process.argv.find((arg) => arg.startsWith("--surfaces="));
+  const rawSurfaces = surfacesArg
+    ? surfacesArg.slice("--surfaces=".length).split(",")
+    : ["aeo"];
+  if (
+    rawSurfaces.length === 0 ||
+    rawSurfaces.some((surface) => surface !== "aeo" && surface !== "cms")
+  ) {
+    console.error("Use --surfaces=aeo, --surfaces=cms, or --surfaces=aeo,cms.");
+    return 1;
   }
+  const surfaces = [...new Set(rawSurfaces)];
+
+  if (subcommand === "doctor") return runDoctor(jsonOutput, surfaces);
   if (subcommand === "install" || subcommand === undefined) {
     return runInstall();
   }
-  console.error(
-    `Unknown subcommand: ${subcommand}. Available: install (default), doctor.`,
-  );
+  console.error(`Unknown subcommand: ${subcommand}. Use install or doctor.`);
   return 1;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soloworks/smking-next",
-  "version": "0.21.5",
+  "version": "0.22.0",
   "description": "AI-native SEO (AEO) for Next.js — auto-inject JSON-LD, FAQ, AI summary, and SEO metadata so AI crawlers (ChatGPT, Perplexity, Google AI) can cite your pages.",
   "license": "MIT",
   "homepage": "https://github.com/sillyleo/smking/tree/main/packages/smking-next",

package/src/components/smking-aeo.tsx

@@ -16,7 +16,14 @@ const SR_ONLY_STYLE: React.CSSProperties = {
   border: 0,
 };
 
-export interface SmkingAEOProps extends DiscoverParams {}
+export interface SmkingAEOProps extends DiscoverParams {
+  /**
+   * Keep the legacy React 19 metadata tags. Set false when the host uses
+   * `withSmkingMetadata()` from `generateMetadata`, which is the authoritative
+   * Next.js integration and avoids duplicate title/meta elements.
+   */
+  includeSeo?: boolean;
+}
 
 async function wantsOriginBypass(): Promise<boolean> {
   try {
@@ -82,6 +89,7 @@ export async function SmkingAEO(props: SmkingAEOProps) {
   const hasBodyFragments = Boolean(
     aeo.summaryHtml || aeo.faqHtml || seo?.ogImageUrl,
   );
+  const includeSeo = props.includeSeo ?? true;
 
   return (
     <>
@@ -93,21 +101,23 @@ export async function SmkingAEO(props: SmkingAEOProps) {
         />
       )}
 
-      {seo?.title && <title data-smking="aeo">{seo.title}</title>}
-      {description && (
+      {includeSeo && seo?.title && (
+        <title data-smking="aeo">{seo.title}</title>
+      )}
+      {includeSeo && description && (
         <meta name="description" content={description} data-smking="aeo" />
       )}
-      {seo?.ogTitle && (
+      {includeSeo && seo?.ogTitle && (
         <meta property="og:title" content={seo.ogTitle} data-smking="aeo" />
       )}
-      {seo?.ogDescription && (
+      {includeSeo && seo?.ogDescription && (
         <meta
           property="og:description"
           content={seo.ogDescription}
           data-smking="aeo"
         />
       )}
-      {seo?.ogImageUrl && (
+      {includeSeo && seo?.ogImageUrl && (
         <meta
           property="og:image"
           content={seo.ogImageUrl}

package/src/index.ts

@@ -3,6 +3,7 @@ export { SmkingCms } from "./components/smking-cms";
 export { SmkingRuntime } from "./components/smking-runtime";
 export { getAeoContent } from "./lib/client";
 export { getCmsPage } from "./lib/cms-client";
+export { withSmkingMetadata } from "./lib/metadata";
 export type {
   AeoResponse,
   AeoStatus,

package/src/lib/client.ts

@@ -3,7 +3,7 @@
 import type {} from "next";
 
 import type { AeoResponse, DiscoverParams } from "../types";
-import { normalizePath, resolveRequestPath } from "./path";
+import { isPathWithinPrefix, normalizePath, resolveRequestPath } from "./path";
 import { SDK_VERSION } from "./version";
 
 const DEFAULT_REVALIDATE_SECONDS = 3600;
@@ -91,6 +91,9 @@ export async function getAeoContent(
     }
   }
   path = normalizePath(path);
+  if (isPathWithinPrefix(path, process.env.SMKING_CMS_PATH)) {
+    return null;
+  }
 
   try {
     const res = await fetch(`${baseUrl}/api/v1/public/aeo`, {
@@ -110,11 +113,11 @@ export async function getAeoContent(
           sdk_version: SDK_VERSION,
           app_env: process.env.NODE_ENV ?? null,
           host: safeHostname(url),
-          // Site-level CMS base path → smking dashboard "View page" URLs.
-          // Default "/blog"; override with SMKING_CMS_PATH (wizard sets it).
-          cms_base_path: process.env.SMKING_CMS_PATH ?? "/blog",
+          // Site-level Blog mount → dashboard "View page" URLs. Null means
+          // Blog was not selected; the wizard always writes the value when it
+          // wires Blog, including the default /blog path.
+          cms_base_path: process.env.SMKING_CMS_PATH ?? null,
         },
-
       }),
       signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
       next: {

package/src/lib/metadata.ts

@@ -0,0 +1,40 @@
+import type { Metadata } from "next";
+
+import type { DiscoverParams } from "../types";
+import { getAeoContent } from "./client";
+
+/**
+ * Merge Page Zero's ready SEO fields over an existing App Router metadata
+ * object. Use this from the root layout's `generateMetadata` export so Next.js
+ * emits one authoritative title and description instead of duplicate tags.
+ */
+export async function withSmkingMetadata(
+  hostMetadata: Metadata,
+  params: DiscoverParams,
+): Promise<Metadata> {
+  const aeo = await getAeoContent(params);
+  if (!aeo || aeo.status !== "ready") return hostMetadata;
+
+  const seo = aeo.seo ?? null;
+  const title = seo?.title ?? null;
+  const description = seo?.ogDescription ?? aeo.metaDescription ?? null;
+  const ogTitle = seo?.ogTitle ?? title;
+  const ogDescription = seo?.ogDescription ?? aeo.metaDescription ?? null;
+  const ogImageUrl = seo?.ogImageUrl ?? null;
+
+  return {
+    ...hostMetadata,
+    ...(title ? { title } : {}),
+    ...(description ? { description } : {}),
+    ...(ogTitle || ogDescription || ogImageUrl
+      ? {
+          openGraph: {
+            ...(hostMetadata.openGraph ?? {}),
+            ...(ogTitle ? { title: ogTitle } : {}),
+            ...(ogDescription ? { description: ogDescription } : {}),
+            ...(ogImageUrl ? { images: [ogImageUrl] } : {}),
+          },
+        }
+      : {}),
+  };
+}

package/src/lib/path.ts

@@ -65,3 +65,20 @@ export function setRequestPathHeaders(
 export function normalizePath(path: string): string {
   return path.startsWith("/") ? path : "/" + path;
 }
+
+/**
+ * True when a request belongs to the configured Page Zero Blog mount.
+ * Segment-aware matching avoids treating `/blogger` as a child of `/blog`.
+ */
+export function isPathWithinPrefix(
+  path: string,
+  prefix: string | undefined,
+): boolean {
+  if (!prefix) return false;
+  const normalizedPath = normalizePath(path).replace(/\/+$/, "") || "/";
+  const normalizedPrefix = normalizePath(prefix).replace(/\/+$/, "") || "/";
+  return (
+    normalizedPath === normalizedPrefix ||
+    normalizedPath.startsWith(`${normalizedPrefix}/`)
+  );
+}

package/src/lib/version.ts

@@ -1 +1 @@
-export const SDK_VERSION = "0.21.5";
+export const SDK_VERSION = "0.22.0";