agentskeptic 0.2.1 → 1.0.1

package/scripts/discovery-acquisition.lib.cjs

@@ -1,9 +1,7 @@
 "use strict";
 
-const { readFileSync } = require("node:fs");
+const { existsSync, readFileSync, readdirSync } = require("node:fs");
 const { join } = require("node:path");
-const Ajv = require("ajv");
-const addFormats = require("ajv-formats");
 
 const PLACEHOLDER_KEYS = [
   ["{{ORIGIN}}", "ORIGIN"],
@@ -20,8 +18,7 @@ const PLACEHOLDER_KEYS = [
  */
 function discoveryPaths(root) {
   return {
-    jsonPath: join(root, "config", "discovery-acquisition.json"),
-    schemaPath: join(root, "config", "discovery-acquisition.schema.json"),
+    jsonPath: join(root, "config", "marketing.json"),
   };
 }
 
@@ -33,6 +30,36 @@ function loadDiscoveryAcquisition(root) {
   return JSON.parse(readFileSync(jsonPath, "utf8"));
 }
 
+/**
+ * @param {string} root
+ * @returns {{ guides: string[]; examples: string[]; compare: string[] }}
+ */
+function listMarkdownSurfaceRoutesGrouped(root) {
+  const base = join(root, "website", "content", "surfaces");
+  /** @type {{ guides: string[]; examples: string[]; compare: string[] }} */
+  const out = { guides: [], examples: [], compare: [] };
+  for (const seg of /** @type {const} */ (["guides", "examples", "compare"])) {
+    const dir = join(base, seg);
+    if (!existsSync(dir)) continue;
+    for (const f of readdirSync(dir)) {
+      if (!f.endsWith(".md")) continue;
+      const raw = readFileSync(join(dir, f), "utf8");
+      const m = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+      if (!m) throw new Error(`markdown-surfaces: missing frontmatter in ${seg}/${f}`);
+      const rm = m[1].match(/^route:\s*(.+)$/m);
+      if (!rm) throw new Error(`markdown-surfaces: missing route in ${seg}/${f}`);
+      const route = rm[1].trim().replace(/^['"]|['"]$/g, "");
+      if (seg === "guides") out.guides.push(route);
+      else if (seg === "examples") out.examples.push(route);
+      else out.compare.push(route);
+    }
+  }
+  out.guides.sort((a, b) => a.localeCompare(b, "en", { sensitivity: "base" }));
+  out.examples.sort((a, b) => a.localeCompare(b, "en", { sensitivity: "base" }));
+  out.compare.sort((a, b) => a.localeCompare(b, "en", { sensitivity: "base" }));
+  return out;
+}
+
 /**
  * @param {Record<string, unknown>} discovery
  * @param {string} originNormalized
@@ -85,71 +112,6 @@ function escapeMdLinkText(s) {
   return s.replace(/\\/g, "\\\\").replace(/\[/g, "\\[").replace(/\]/g, "\\]");
 }
 
-/**
- * @param {Record<string, unknown>} discovery
- */
-function validateIndexableGuides(discovery) {
-  const guides = /** @type {{ path: string; navLabel: string; problemAnchor: string }[]} */ (
-    discovery.indexableGuides
-  );
-  if (!Array.isArray(guides)) {
-    throw new Error("discovery-acquisition: indexableGuides must be an array");
-  }
-  const paths = guides.map((g) => String(g.path));
-  const uniq = new Set(paths);
-  if (uniq.size !== paths.length) {
-    throw new Error("discovery-acquisition: indexableGuides paths must be unique");
-  }
-  const demandMoments = /** @type {string[]} */ (discovery.demandMoments);
-  for (let k = 0; k < guides.length; k++) {
-    const pa = String(guides[k].problemAnchor);
-    if (pa.includes("`")) {
-      throw new Error("discovery-acquisition: problemAnchor must not contain backtick");
-    }
-    if (k >= 1) {
-      const dm = String(demandMoments[k - 1]);
-      if (!dm.includes(pa)) {
-        throw new Error(
-          `discovery-acquisition: indexableGuides[${k}].problemAnchor must be a substring of demandMoments[${k - 1}]`,
-        );
-      }
-    }
-  }
-}
-
-/**
- * @param {Record<string, unknown>} discovery
- */
-function validateIndexableExamples(discovery) {
-  const ex = /** @type {{ path: string; navLabel: string; problemAnchor: string; embedKey: string }[]} */ (
-    discovery.indexableExamples
-  );
-  if (!Array.isArray(ex)) {
-    throw new Error("discovery-acquisition: indexableExamples must be an array");
-  }
-  if (ex.length !== 2) {
-    throw new Error("discovery-acquisition: indexableExamples must have length exactly 2");
-  }
-  if (ex[0].path !== "/examples/wf-complete" || ex[1].path !== "/examples/wf-missing") {
-    throw new Error(
-      "discovery-acquisition: indexableExamples paths must be /examples/wf-complete then /examples/wf-missing",
-    );
-  }
-  if (ex[0].embedKey !== "wf_complete" || ex[1].embedKey !== "wf_missing") {
-    throw new Error(
-      "discovery-acquisition: indexableExamples embedKey order must be wf_complete then wf_missing",
-    );
-  }
-  for (let i = 0; i < ex.length; i++) {
-    const row = ex[i];
-    const nl = String(row.navLabel);
-    const pa = String(row.problemAnchor);
-    if (nl.includes("`") || pa.includes("`")) {
-      throw new Error(`discovery-acquisition: indexableExamples[${i}] must not contain backtick`);
-    }
-  }
-}
-
 /**
  * @param {string} baseLlms
  * @param {Record<string, unknown>} discovery
@@ -162,18 +124,24 @@ function appendDiscoveryLlmsAppendix(baseLlms, discovery, canonicalOrigin) {
   const bullets = (/** @type {string[]} */ arr) => arr.map((x) => `- ${x}`).join("\n");
 
   let out = String(baseLlms).replace(/\s*$/, "") + "\n";
-  const guides = /** @type {{ path: string }[] | undefined} */ (discovery.indexableGuides);
-  if (Array.isArray(guides) && guides.length > 0) {
+  const root = join(__dirname, "..");
+  const grouped = listMarkdownSurfaceRoutesGrouped(root);
+  if (grouped.guides.length > 0) {
     out += "\n## Indexable guides\n";
-    for (const g of guides) {
-      out += `- ${origin}${String(g.path)}\n`;
+    for (const path of grouped.guides) {
+      out += `- ${origin}${path}\n`;
     }
   }
-  const examples = /** @type {{ path: string }[] | undefined} */ (discovery.indexableExamples);
-  if (Array.isArray(examples) && examples.length > 0) {
+  if (grouped.examples.length > 0) {
     out += "\n## Indexable examples\n";
-    for (const ex of examples) {
-      out += `- ${origin}${String(ex.path)}\n`;
+    for (const path of grouped.examples) {
+      out += `- ${origin}${path}\n`;
+    }
+  }
+  if (grouped.compare.length > 0) {
+    out += "\n## Indexable comparisons\n";
+    for (const path of grouped.compare) {
+      out += `- ${origin}${path}\n`;
     }
   }
   const demo = discovery.shareableTerminalDemo;
@@ -186,9 +154,15 @@ function appendDiscoveryLlmsAppendix(baseLlms, discovery, canonicalOrigin) {
   out += bullets(llms.notFor) + "\n";
   out += "\n## Related queries\n";
   out += bullets(llms.relatedQueries) + "\n";
-  const moments = /** @type {string[]} */ (discovery.demandMoments);
+  const rows = /** @type {{ moment: string; primaryRoute: string; relatedRoutes?: string[] }[]} */ (
+    discovery.problemIndex
+  );
   out += "\n## When this hurts (search-shaped)\n";
-  out += bullets(moments) + "\n";
+  for (const row of rows) {
+    const paths = [row.primaryRoute, ...(Array.isArray(row.relatedRoutes) ? row.relatedRoutes : [])];
+    const links = paths.map((p) => `${origin}${String(p).startsWith("/") ? String(p) : `/${String(p)}`}`);
+    out += `- ${row.moment} — ${links.join(" · ")}\n`;
+  }
   out += "\n## Problem framing (shareable)\n";
   out += `- Full page: ${origin}${slug}\n`;
   out += "\n## Visitor problem (canonical answer)\n\n";
@@ -200,20 +174,12 @@ function appendDiscoveryLlmsAppendix(baseLlms, discovery, canonicalOrigin) {
  * @param {string} root
  */
 function validateDiscoveryAcquisition(root) {
-  const { jsonPath, schemaPath } = discoveryPaths(root);
+  const { jsonPath } = discoveryPaths(root);
+  const { validateMarketing } = require("./validate-marketing.cjs");
+  validateMarketing(root);
   const discovery = JSON.parse(readFileSync(jsonPath, "utf8"));
-  const schema = JSON.parse(readFileSync(schemaPath, "utf8"));
-  const ajv = new Ajv({ allErrors: true, strict: true });
-  addFormats(ajv);
-  const validate = ajv.compile(schema);
-  if (!validate(discovery)) {
-    const msg = ajv.errorsText(validate.errors, { separator: "\n" });
-    throw new Error(`discovery-acquisition: schema validation failed:\n${msg}`);
-  }
-  const anchorsPath = join(root, "config", "public-product-anchors.json");
-  const anchors = JSON.parse(readFileSync(anchorsPath, "utf8"));
-  const { normalize } = require("./public-product-anchors.cjs");
-  const origin = normalize(anchors.productionCanonicalOrigin);
+  const { normalize } = require("./origin.cjs");
+  const origin = normalize(String(discovery.productionCanonicalOrigin));
   buildDiscoveryFoldBody(discovery, origin);
   const demo = discovery.shareableTerminalDemo;
   if (demo && String(demo.transcript).includes("```")) {
@@ -221,8 +187,6 @@ function validateDiscoveryAcquisition(root) {
       "discovery-acquisition: shareableTerminalDemo.transcript must not contain markdown fence ```",
     );
   }
-  validateIndexableGuides(discovery);
-  validateIndexableExamples(discovery);
   return discovery;
 }
 
@@ -231,7 +195,6 @@ module.exports = {
   buildDiscoveryFoldBody,
   appendDiscoveryLlmsAppendix,
   validateDiscoveryAcquisition,
-  validateIndexableGuides,
-  validateIndexableExamples,
   discoveryPaths,
+  listMarkdownSurfaceRoutesGrouped,
 };

package/scripts/discovery-payload.lib.cjs

@@ -105,8 +105,37 @@ function buildDiscoveryPayload(root) {
   const discoveryLib = require("./discovery-acquisition.lib.cjs");
   discoveryLib.validateDiscoveryAcquisition(root);
   const discovery = discoveryLib.loadDiscoveryAcquisition(root);
-  const anchorsPath = join(root, "config", "public-product-anchors.json");
-  const anchors = JSON.parse(readFileSync(anchorsPath, "utf8"));
+  const grouped = discoveryLib.listMarkdownSurfaceRoutesGrouped(root);
+  const padAnchor = (path) =>
+    `Markdown-backed discovery surface content for ${path} — read-only SQL verification context.`;
+  const indexableGuidesFromMd = grouped.guides.map((path) => ({
+    path,
+    navLabel: path.replace(/^\/guides\//, ""),
+    problemAnchor: padAnchor(path),
+  }));
+  const embedKeyForExamplePath = (examplePath) => {
+    const tail = String(examplePath).replace(/^\/examples\//, "");
+    switch (tail) {
+      case "wf-complete":
+        return "wf_complete";
+      case "wf-missing":
+        return "wf_missing";
+      case "langgraph-checkpoint-trust":
+        return "langgraph_checkpoint_trust";
+      default:
+        throw new Error(`discovery-payload: unknown example path for embedKey: ${examplePath}`);
+    }
+  };
+  const indexableExamplesFromMd = grouped.examples.map((path) => ({
+    path,
+    navLabel: path.replace(/^\/examples\//, ""),
+    problemAnchor: padAnchor(path),
+    embedKey: embedKeyForExamplePath(path),
+  }));
+  const pm = /** @type {{ productionCanonicalOrigin: string; identityOneLiner: string; gitRepositoryUrl: string; npmPackageUrl: string }} */ (
+    discovery
+  );
+  const anchors = pm;
   const canonicalOrigin = normalizeOrigin(anchors.productionCanonicalOrigin);
   const integrateUrl = `${canonicalOrigin}/integrate`;
   const learnHubUrl = `${canonicalOrigin}/guides`;
@@ -114,6 +143,7 @@ function buildDiscoveryPayload(root) {
   const { owner, repo } = parseGithubRepoFromUrl(anchors.gitRepositoryUrl);
   const llmsRaw = `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${DISCOVERY_LLM_BRANCH}/llms.txt`;
   const llmsBlob = `https://github.com/${owner}/${repo}/blob/${DISCOVERY_LLM_BRANCH}/llms.txt`;
+  const integratorVerificationSsotRaw = `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${DISCOVERY_LLM_BRANCH}/docs/integrator-verification.md`;
   const openapiRaw = `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${DISCOVERY_LLM_BRANCH}/schemas/openapi-commercial-v1.yaml`;
   const llms = /** @type {{ intentPhrases: string[]; notFor: string[]; relatedQueries: string[] }} */ (
     discovery.llms
@@ -133,6 +163,7 @@ function buildDiscoveryPayload(root) {
       npm: String(anchors.npmPackageUrl),
       llmsRaw,
       llmsBlob,
+      integratorVerificationSsotRaw,
     },
     appendix: {
       slug: String(discovery.slug),
@@ -140,9 +171,11 @@ function buildDiscoveryPayload(root) {
       intentPhrases: llms.intentPhrases.map(String),
       notFor: llms.notFor.map(String),
       relatedQueries: llms.relatedQueries.map(String),
-      demandMoments: /** @type {string[]} */ (discovery.demandMoments).map(String),
-      indexableGuides: /** @type {unknown} */ (discovery.indexableGuides),
-      indexableExamples: /** @type {unknown} */ (discovery.indexableExamples),
+      problemIndex: /** @type {unknown} */ (
+        Array.isArray(discovery.problemIndex) ? JSON.parse(JSON.stringify(discovery.problemIndex)) : []
+      ),
+      indexableGuides: /** @type {unknown} */ (indexableGuidesFromMd),
+      indexableExamples: /** @type {unknown} */ (indexableExamplesFromMd),
       shareableTerminalDemo: {
         title: String(demo.title),
         transcript: String(demo.transcript),
@@ -155,13 +188,13 @@ function buildDiscoveryPayload(root) {
  * @param {Record<string, unknown>} payload
  */
 function discoveryObjectFromAppendix(payload) {
-  const ap = /** @type {{ slug: string; visitorProblemAnswer: string; intentPhrases: string[]; notFor: string[]; relatedQueries: string[]; demandMoments: string[]; indexableGuides?: { path: string; navLabel: string; problemAnchor: string }[]; indexableExamples?: { path: string; navLabel: string; problemAnchor: string; embedKey: string }[]; shareableTerminalDemo?: { title: string; transcript: string } }} */ (
+  const ap = /** @type {{ slug: string; visitorProblemAnswer: string; intentPhrases: string[]; notFor: string[]; relatedQueries: string[]; problemIndex: { moment: string; primaryRoute: string; relatedRoutes?: string[] }[]; indexableGuides?: { path: string; navLabel: string; problemAnchor: string }[]; indexableExamples?: { path: string; navLabel: string; problemAnchor: string; embedKey: string }[]; shareableTerminalDemo?: { title: string; transcript: string } }} */ (
     payload.appendix
   );
   const out = {
     slug: ap.slug,
     visitorProblemAnswer: ap.visitorProblemAnswer,
-    demandMoments: ap.demandMoments,
+    problemIndex: ap.problemIndex,
     llms: {
       intentPhrases: ap.intentPhrases,
       notFor: ap.notFor,
@@ -214,6 +247,7 @@ function renderLlmsTextFromPayload(payload) {
     "",
     "## Primary links",
     `- Canonical site: ${links.site}`,
+    `- Integrator verification SSOT (Python + LangGraph tables): ${links.integratorVerificationSsotRaw}`,
     `- First-run integration: ${integrateUrl}`,
     `- Learn: ${learnHubUrl}`,
     `- OpenAPI (canonical): ${openapiSelfCanonical}`,

package/scripts/emit-primary-marketing.cjs

@@ -0,0 +1,326 @@
+"use strict";
+
+const { readFileSync, writeFileSync, mkdirSync } = require("node:fs");
+const { join, dirname } = require("node:path");
+const { normalize, assertNextPublicOriginParity, MARKETING_PATH } = require("./origin.cjs");
+
+const ROOT = join(__dirname, "..");
+
+const OPENAPI_IN = join(ROOT, "schemas", "openapi-commercial-v1.in.yaml");
+const OPENAPI_OUT = join(ROOT, "schemas", "openapi-commercial-v1.yaml");
+const OPENAPI_PUBLIC = join(ROOT, "website", "public", "openapi-commercial-v1.yaml");
+const LLMS_PUBLIC = join(ROOT, "website", "public", "llms.txt");
+const LLMS_REPO_ROOT = join(ROOT, "llms.txt");
+const README_PATH = join(ROOT, "README.md");
+const PKG_PATH = join(ROOT, "package.json");
+
+const README_START = "<!-- public-product-anchors:start -->";
+const README_END = "<!-- public-product-anchors:end -->";
+const DISCOVERY_README_START = "<!-- discovery-acquisition-fold:start -->";
+const DISCOVERY_README_END = "<!-- discovery-acquisition-fold:end -->";
+const DISCOVERY_README_TITLE_START = "<!-- discovery-readme-title:start -->";
+const DISCOVERY_README_TITLE_END = "<!-- discovery-readme-title:end -->";
+
+const TOKENS = [
+  "__IDENTITY_ONE_LINER__",
+  "__DISTRIBUTION_CONTACT_URL__",
+  "__DISTRIBUTION_INTEGRATE_URL__",
+  "__DISTRIBUTION_REPO_URL__",
+  "__DISTRIBUTION_NPM_URL__",
+  "__OPENAPI_SELF_URL__",
+  "__SERVERS_ORIGIN__",
+];
+
+/**
+ * @param {string} haystack
+ * @param {string} needle
+ */
+function countOccurrences(haystack, needle) {
+  let n = 0;
+  let i = 0;
+  while (true) {
+    const j = haystack.indexOf(needle, i);
+    if (j === -1) break;
+    n++;
+    i = j + needle.length;
+  }
+  return n;
+}
+
+function validateOpenapiTemplate() {
+  const template = readFileSync(OPENAPI_IN, "utf8");
+  for (const tok of TOKENS) {
+    const c = countOccurrences(template, tok);
+    if (c !== 1) {
+      throw new Error(`openapi template: token ${tok} must appear exactly once, found ${c}`);
+    }
+  }
+}
+
+function escapeYamlDoubleQuotedOneLiner(s) {
+  return String(s).replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+/**
+ * @param {Record<string, unknown>} anchors
+ */
+function distributionSsotBlobUrl(anchors) {
+  const u = String(anchors.gitRepositoryUrl);
+  const m = u.match(/github\.com\/([^/]+)\/([^/#?]+)/i);
+  if (!m) throw new Error("emit-primary-marketing: cannot derive SSOT blob URL from gitRepositoryUrl");
+  const repo = m[2].replace(/\.git$/i, "");
+  return `https://github.com/${m[1]}/${repo}/blob/main/docs/public-distribution.md`;
+}
+
+/**
+ * @param {string} line
+ * @param {string} origin
+ * @param {string} slug
+ */
+function expandCliFooterLine(line, origin, slug) {
+  const acquisitionUrl = `${origin}${slug}`;
+  const integrateUrl = `${origin}/integrate`;
+  let out = String(line)
+    .replace(/\{\{ORIGIN\}\}/g, origin)
+    .replace(/\{\{ACQUISITION_URL\}\}/g, acquisitionUrl)
+    .replace(/\{\{INTEGRATE_URL\}\}/g, integrateUrl);
+  if (out.includes("{{")) {
+    throw new Error(`emit-primary-marketing: unresolved placeholder in cliFollowupLines: ${line}`);
+  }
+  return out;
+}
+
+/**
+ * @param {Record<string, unknown>} anchors
+ * @param {Record<string, unknown>} discovery
+ */
+function writePublicDistributionGenerated(anchors, discovery) {
+  const ssotUrl = distributionSsotBlobUrl(anchors);
+  const origin = normalize(anchors.productionCanonicalOrigin);
+  const slug = String(discovery.slug);
+  const cliLines = /** @type {string[]} */ (discovery.cliFollowupLines);
+  const expanded = cliLines.map((l) => expandCliFooterLine(l, origin, slug));
+  expanded.push(`Distribution contract (SSOT): ${ssotUrl}`);
+  if (expanded.length > 6) {
+    throw new Error(
+      `emit-primary-marketing: distribution footer exceeds 6 lines (${expanded.length}); shorten cliFollowupLines`,
+    );
+  }
+  const returnParts = expanded.map((line) => `${JSON.stringify(`${line}\n`)}`);
+  const pkgRaw = readFileSync(PKG_PATH, "utf8");
+  const pkgJson = JSON.parse(pkgRaw);
+  const cliSemver = String(pkgJson.version ?? "").trim();
+  if (!cliSemver) {
+    throw new Error("emit-primary-marketing: package.json missing version");
+  }
+  const body = `// Generated by npm run emit-primary-marketing — do not hand edit.
+
+export const PUBLIC_DISTRIBUTION_SSOT_BLOB_URL = ${JSON.stringify(ssotUrl)};
+
+export const PUBLIC_CANONICAL_SITE_ORIGIN = ${JSON.stringify(origin)};
+
+export const AGENTSKEPTIC_CLI_SEMVER = ${JSON.stringify(cliSemver)};
+
+export function formatDistributionFooter(): string {
+  return ${returnParts.join("\n    + ")};
+}
+`;
+  writeFileSync(join(ROOT, "src", "publicDistribution.generated.ts"), body, "utf8");
+}
+
+/**
+ * @param {Record<string, unknown>} anchors
+ * @param {Record<string, unknown>} discovery
+ */
+function writeAgentsMd(anchors, discovery) {
+  const url = distributionSsotBlobUrl(anchors);
+  const origin = normalize(anchors.productionCanonicalOrigin);
+  const slug = String(discovery.slug);
+  const acquisitionUrl = `${origin}${slug}`;
+  const dp = require("./discovery-payload.lib.cjs");
+  const { owner, repo } = dp.parseGithubRepoFromUrl(String(anchors.gitRepositoryUrl));
+  const branch = dp.DISCOVERY_LLM_BRANCH;
+  const llmsRaw = `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${branch}/llms.txt`;
+  const openapiRaw = `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${branch}/schemas/openapi-commercial-v1.yaml`;
+  const body = `# AGENTS
+
+Normative **public distribution** and anchor sync: [\`docs/public-distribution.md\`](docs/public-distribution.md) (same content as ${url}).
+
+## Machine-readable product entrypoints
+
+- Committed \`llms.txt\` at repo root (same bytes as site \`/llms.txt\` after prebuild sync).
+- Raw GitHub \`llms.txt\`: ${llmsRaw}
+- OpenAPI YAML (repo raw): ${openapiRaw}
+- Acquisition page (canonical): ${acquisitionUrl}
+`;
+  writeFileSync(join(ROOT, "AGENTS.md"), body, "utf8");
+}
+
+function syncPrimaryMarketing() {
+  const discoveryLib = require("./discovery-acquisition.lib.cjs");
+  discoveryLib.validateDiscoveryAcquisition(ROOT);
+  const pm = discoveryLib.loadDiscoveryAcquisition(ROOT);
+  const anchors = pm;
+  const discovery = pm;
+
+  validateOpenapiTemplate();
+
+  const escaped = escapeYamlDoubleQuotedOneLiner(anchors.identityOneLiner);
+  const canonicalOrigin = normalize(anchors.productionCanonicalOrigin);
+  const openapiSelfCanonical = `${canonicalOrigin}/openapi-commercial-v1.yaml`;
+
+  const envUrl = process.env.NEXT_PUBLIC_APP_URL;
+  const effectivePublicOrigin =
+    typeof envUrl === "string" && envUrl.trim() ? envUrl.trim() : anchors.productionCanonicalOrigin;
+  const publicOriginNormalized = normalize(effectivePublicOrigin);
+  const openapiSelfEffective = `${publicOriginNormalized}/openapi-commercial-v1.yaml`;
+
+  const integrateUrl = `${canonicalOrigin}/integrate`;
+
+  const template = readFileSync(OPENAPI_IN, "utf8");
+  let mid = template;
+  mid = mid.replace("__IDENTITY_ONE_LINER__", escaped);
+  mid = mid.replace("__DISTRIBUTION_CONTACT_URL__", canonicalOrigin);
+  mid = mid.replace("__DISTRIBUTION_INTEGRATE_URL__", integrateUrl);
+  mid = mid.replace("__DISTRIBUTION_REPO_URL__", anchors.gitRepositoryUrl);
+  mid = mid.replace("__DISTRIBUTION_NPM_URL__", anchors.npmPackageUrl);
+
+  const repoYaml = mid
+    .replace("__SERVERS_ORIGIN__", canonicalOrigin)
+    .replace("__OPENAPI_SELF_URL__", openapiSelfCanonical);
+  writeFileSync(OPENAPI_OUT, repoYaml, "utf8");
+
+  mkdirSync(dirname(OPENAPI_PUBLIC), { recursive: true });
+  const publicYaml = mid
+    .replace("__SERVERS_ORIGIN__", publicOriginNormalized)
+    .replace("__OPENAPI_SELF_URL__", openapiSelfEffective);
+  writeFileSync(OPENAPI_PUBLIC, publicYaml, "utf8");
+
+  const discoveryPayload = require("./discovery-payload.lib.cjs");
+  const discoveryPayloadObj = discoveryPayload.buildDiscoveryPayload(ROOT);
+  const llmsNormalized = discoveryPayload.renderLlmsTextFromPayload(discoveryPayloadObj);
+
+  mkdirSync(dirname(LLMS_PUBLIC), { recursive: true });
+  writeFileSync(LLMS_PUBLIC, llmsNormalized, "utf8");
+  writeFileSync(LLMS_REPO_ROOT, llmsNormalized, "utf8");
+
+  const pkgRaw = readFileSync(PKG_PATH, "utf8");
+  const pkg = JSON.parse(pkgRaw);
+  pkg.description = String(discovery.pageMetadata.description);
+  pkg.repository = { type: "git", url: anchors.gitRepositoryGitUrl };
+  pkg.homepage = `${canonicalOrigin}${String(discovery.slug)}`;
+  pkg.bugs = { url: anchors.bugsUrl };
+  pkg.keywords = anchors.keywords;
+  writeFileSync(PKG_PATH, JSON.stringify(pkg, null, 2) + "\n", "utf8");
+
+  let readme = readFileSync(README_PATH, "utf8");
+  if (!readme.includes(DISCOVERY_README_TITLE_START) || !readme.includes(DISCOVERY_README_TITLE_END)) {
+    throw new Error("README.md must contain discovery-readme-title markers");
+  }
+  const titleBody = `# ${String(discovery.readmeTitle)}`;
+  const titleBlock = `${DISCOVERY_README_TITLE_START}\n${titleBody}\n${DISCOVERY_README_TITLE_END}`;
+  const titleRe = new RegExp(
+    `${DISCOVERY_README_TITLE_START.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${DISCOVERY_README_TITLE_END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`,
+  );
+  if (!titleRe.test(readme)) {
+    throw new Error("README: could not match discovery-readme-title region");
+  }
+  readme = readme.replace(titleRe, titleBlock);
+
+  if (!readme.includes(DISCOVERY_README_START) || !readme.includes(DISCOVERY_README_END)) {
+    throw new Error("README.md must contain discovery-acquisition-fold markers");
+  }
+  const foldBody = discoveryLib.buildDiscoveryFoldBody(discovery, canonicalOrigin);
+  const discBlock = `${DISCOVERY_README_START}\n${foldBody}\n${DISCOVERY_README_END}`;
+  const discRe = new RegExp(
+    `${DISCOVERY_README_START.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${DISCOVERY_README_END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`,
+  );
+  if (!discRe.test(readme)) {
+    throw new Error("README: could not match discovery-acquisition-fold region");
+  }
+  readme = readme.replace(discRe, discBlock);
+
+  if (!readme.includes(README_START) || !readme.includes(README_END)) {
+    throw new Error("README.md must contain public-product-anchors markers");
+  }
+  const pl = discoveryPayloadObj.links;
+  const inner = [
+    anchors.identityOneLiner,
+    "",
+    `- **Repository:** ${anchors.gitRepositoryUrl}`,
+    `- **npm package:** ${anchors.npmPackageUrl}`,
+    `- **Canonical site:** ${canonicalOrigin}`,
+    `- **Integrate:** ${integrateUrl}`,
+    `- **OpenAPI (canonical):** ${openapiSelfCanonical}`,
+    `- **llms.txt (agents, site):** ${canonicalOrigin}/llms.txt`,
+    `- **llms.txt (repo, raw):** ${pl.llmsRaw}`,
+    `- **llms.txt (repo, blob):** ${pl.llmsBlob}`,
+    "",
+  ].join("\n");
+  const block = `${README_START}\n${inner}\n${README_END}`;
+  const re = new RegExp(
+    `${README_START.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${README_END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`,
+  );
+  if (!re.test(readme)) {
+    throw new Error("README: could not match public-product-anchors region");
+  }
+  readme = readme.replace(re, block);
+  writeFileSync(README_PATH, readme, "utf8");
+
+  writePublicDistributionGenerated(anchors, discovery);
+  writeAgentsMd(anchors, discovery);
+}
+
+function validateForCheck() {
+  const discoveryLib = require("./discovery-acquisition.lib.cjs");
+  discoveryLib.validateDiscoveryAcquisition(ROOT);
+  validateOpenapiTemplate();
+  const pm = JSON.parse(readFileSync(MARKETING_PATH, "utf8"));
+  const required = [
+    "identityOneLiner",
+    "productionCanonicalOrigin",
+    "gitRepositoryUrl",
+    "gitRepositoryGitUrl",
+    "npmPackageUrl",
+    "bugsUrl",
+    "keywords",
+  ];
+  for (const k of required) {
+    if (pm[k] === undefined || pm[k] === null) {
+      throw new Error(`marketing: missing ${k}`);
+    }
+  }
+  if (!Array.isArray(pm.keywords) || pm.keywords.length === 0) {
+    throw new Error("marketing: keywords must be a non-empty array");
+  }
+}
+
+function main() {
+  validateForCheck();
+  if (process.argv.includes("--check")) {
+    return;
+  }
+  syncPrimaryMarketing();
+}
+
+/** @deprecated use syncPrimaryMarketing */
+const syncPublicProductAnchors = syncPrimaryMarketing;
+/** @deprecated use validateForCheck */
+const validateAnchors = validateForCheck;
+
+module.exports = {
+  validateAnchors,
+  syncPublicProductAnchors,
+  syncPrimaryMarketing,
+  assertNextPublicOriginParity,
+  normalize,
+};
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (e) {
+    console.error(e instanceof Error ? e.message : e);
+    process.exit(1);
+  }
+}