@soloworks/smking-next 0.21.6 → 0.22.1

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @soloworks/smking-next
 
+## 0.22.1 — 2026-07-26
+
+- Sitemap fetches now carry a shared cache tag.
+- Signed AEO and CMS publish webhooks immediately invalidate the sitemap tag,
+  so newly published Blog pages do not wait for the one-day fallback TTL.
+
+## 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.**

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 + authoritative AEO/SEO layout
- *   integration + 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,23 +114,51 @@ 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) {
+function checkNextConfig() {
+  const configPath = [
+    "next.config.ts",
+    "next.config.mjs",
+    "next.config.js",
+    "next.config.cjs",
+  ].find((path) => existsSync(path));
+  if (!configPath) {
+    return {
+      name: "Next.js transpilePackages",
+      status: "fail",
+      detail:
+        "next.config.* not found; add @soloworks/smking-next to transpilePackages",
+    };
+  }
+  const content = readFileSync(configPath, "utf8");
+  if (
+    !content.includes("transpilePackages") ||
+    !content.includes("@soloworks/smking-next")
+  ) {
+    return {
+      name: "Next.js transpilePackages",
+      status: "fail",
+      detail: `${configPath} must include @soloworks/smking-next in transpilePackages`,
+    };
+  }
+  return {
+    name: "Next.js transpilePackages",
+    status: "pass",
+    detail: configPath,
+  };
+}
+
+function checkAeoLayout(appDir) {
   const layoutPath = findRootLayout(appDir);
   if (!layoutPath) {
     return {
@@ -212,177 +167,265 @@ function checkLayoutUsage(appDir) {
       detail: `no root layout owning <html> and <body> found under ${appDir}/`,
     };
   }
-
-  const content = readFileSync(layoutPath, "utf-8");
+  const content = readFileSync(layoutPath, "utf8");
   const missing = [];
   if (!content.includes("SmkingAEO")) missing.push("SmkingAEO");
   if (!content.includes("withSmkingMetadata(")) {
-    missing.push("withSmkingMetadata() in generateMetadata");
+    missing.push("withSmkingMetadata()");
   }
   if (!/includeSeo\s*=\s*\{\s*false\s*\}/.test(content)) {
     missing.push("includeSeo={false}");
   }
-  if (missing.length > 0) {
-    return {
-      name: "AEO + SEO in root layout",
-      status: "fail",
-      detail: `${layoutPath} is missing ${missing.join(", ")}. Use withSmkingMetadata() for authoritative Next.js metadata and render <SmkingAEO includeSeo={false} /> inside <body>.`,
-    };
+  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;
   }
-  return {
-    name: "AEO + SEO in root layout",
-    status: "pass",
-    detail: layoutPath,
-  };
+  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 };
 }
 
-/**
- * @returns {Promise<DoctorCheck>}
- */
-async function checkApiReachable() {
+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: "AEO + SEO 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.6",
+  "version": "0.22.1",
   "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/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/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/sitemap.ts

@@ -1,5 +1,7 @@
 import type { MetadataRoute } from "next";
 
+export const SMKING_SITEMAP_CACHE_TAG = "smking:sitemap";
+
 /**
  * Drop-in `app/sitemap.ts` default export. Fetches the canonical sitemap
  * served by Page Zero at `/api/v1/public/sitemap.xml?key=...`, parses
@@ -36,8 +38,12 @@ export default async function smkingSitemap(): Promise<MetadataRoute.Sitemap> {
       `${baseUrl}/api/v1/public/sitemap.xml?key=${encodeURIComponent(apiKey)}`,
       {
         // Daily revalidation — sitemap doesn't change second-to-second.
-        // Customer can override via env if their build cadence differs.
-        next: { revalidate: 86_400 },
+        // The signed publish webhook invalidates this tag immediately when
+        // AEO or CMS content changes; the TTL remains the fail-safe.
+        next: {
+          revalidate: 86_400,
+          tags: [SMKING_SITEMAP_CACHE_TAG],
+        },
         signal: AbortSignal.timeout(10_000),
       },
     );

package/src/lib/version.ts

@@ -1 +1 @@
-export const SDK_VERSION = "0.21.6";
+export const SDK_VERSION = "0.22.1";

package/src/lib/webhook-route.ts

@@ -1,6 +1,7 @@
 import { revalidateTag } from "next/cache";
 import { Buffer } from "node:buffer";
 import crypto from "node:crypto";
+import { SMKING_SITEMAP_CACHE_TAG } from "./sitemap";
 
 interface WebhookPayload {
   kind?: string;
@@ -153,6 +154,23 @@ export async function POST(request: Request): Promise<Response> {
     }
   }
 
+  // The canonical sitemap fetch has a daily TTL. A publish must evict it
+  // immediately or newly published CMS pages can stay absent for 24 hours.
+  // Limit this shared tag to content kinds that actually affect the sitemap;
+  // unknown future payloads keep their forward-compatible no-op behavior.
+  if (kind === "aeo" || kind === "cms_page") {
+    try {
+      revalidateTag(SMKING_SITEMAP_CACHE_TAG, "default");
+      revalidated++;
+    } catch (err) {
+      errors++;
+      console.warn(
+        "[@soloworks/smking-next/webhook] sitemap revalidateTag failed:",
+        err,
+      );
+    }
+  }
+
   return Response.json({ ok: true, kind, revalidated, errors });
 }