@jay-framework/jay-stack-cli 0.25.0 → 0.25.2

package/dist/index.js

@@ -12,7 +12,7 @@ import { checkValidationErrors, JAY_CONTRACT_EXTENSION as JAY_CONTRACT_EXTENSION
 import fs$2 from "node:fs/promises";
 import * as path from "node:path";
 import path__default from "node:path";
-import { scanPlugins, sortPluginsByDependencies, getServiceRegistry, actionRegistry, resolveServices, ActionRegistry, discoverPluginsWithInit, executePluginServerInits, runInitCallbacks, registerService } from "@jay-framework/stack-server-runtime";
+import { scanPlugins, sortPluginsByDependencies, getServiceRegistry, actionRegistry, resolveServices, headMetaToHeadTags, ActionRegistry, discoverPluginsWithInit, executePluginServerInits, runInitCallbacks, registerService } from "@jay-framework/stack-server-runtime";
 import { createRequire } from "module";
 import jsBeautify from "js-beautify";
 import "node:crypto";
@@ -21,10 +21,11 @@ import fs__default from "node:fs";
 import { createRequire as createRequire$1 } from "node:module";
 import { isJayAction, isJayStreamAction, isJayCliCommand, CONSOLE_CONTEXT } from "@jay-framework/fullstack-component";
 import { parse, NodeType, HTMLElement } from "node-html-parser";
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import chalk from "chalk";
 import { glob } from "glob";
 import postcss from "postcss";
+import { scanRoutes, JayRouteParamType } from "@jay-framework/stack-route-scanner";
 import { fileURLToPath } from "node:url";
 import { select, confirm, input } from "@inquirer/prompts";
 const DEFAULT_CONFIG = {
@@ -49,7 +50,8 @@ function loadConfig(projectRoot) {
         ...DEFAULT_CONFIG.devServer,
         ...userConfig.devServer
       },
-      site: userConfig.site
+      site: userConfig.site,
+      validations: userConfig.validations
     };
   } catch (error) {
     getLogger().warn(`Failed to parse .jay YAML config file, using defaults: ${error}`);
@@ -198,6 +200,13 @@ const generateContractDefinitionFiles$1 = /* @__PURE__ */ Object.freeze(/* @__PU
   __proto__: null,
   generateContractDefinitionFiles
 }, Symbol.toStringTag, { value: "Module" }));
+function setWellKnownHeaders(res, filePath) {
+  if (filePath.includes(`${path$1.sep}.well-known${path$1.sep}`)) {
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    if (filePath.endsWith(".md")) res.setHeader("Content-Type", "text/markdown; charset=utf-8");
+    if (filePath.endsWith(".gz")) res.setHeader("Content-Type", "application/gzip");
+  }
+}
 async function startDevServer(options = {}) {
   const projectPath = options.projectPath || process.cwd();
   if (projectPath !== process.cwd()) {
@@ -213,7 +222,7 @@ async function startDevServer(options = {}) {
   const httpServer = http.createServer(app);
   const devServerPort = await getPort({ port: resolvedConfig.devServer.portRange });
   const log = getLogger();
-  const { server, viteServer, routes, service } = await mkDevServer({
+  const { server, viteServer, routes, service, errorPageHandler } = await mkDevServer({
     pagesRootFolder: path$1.resolve(resolvedConfig.devServer.pagesBase),
     projectRootFolder: process.cwd(),
     publicBaseUrlPath: "/",
@@ -231,18 +240,20 @@ async function startDevServer(options = {}) {
     });
   }
   if (fs$1.existsSync(publicPath)) {
-    app.use(express.static(publicPath));
+    app.use(express.static(publicPath, { dotfiles: "allow", setHeaders: setWellKnownHeaders }));
   } else {
     log.important(`⚠️  Public folder not found: ${resolvedConfig.devServer.publicFolder}`);
   }
+  const pageRouter = express.Router();
   routes.forEach((route) => {
-    app.get(route.path, route.handler);
+    pageRouter.get(route.path, route.handler);
   });
   service.attachRouteRegistrar((added) => {
     added.forEach((route) => {
-      app.get(route.path, route.handler);
+      pageRouter.get(route.path, route.handler);
     });
   });
+  app.use(pageRouter);
   void (async () => {
     await generatePageDefinitionFiles(
       routes.map((route) => route.fsRoute.jayHtmlPath),
@@ -297,6 +308,7 @@ async function startDevServer(options = {}) {
       }, options.timeout * 1e3);
     }
   }
+  app.use(errorPageHandler(404));
   process.on("SIGTERM", shutdown);
   process.on("SIGINT", shutdown);
 }
@@ -3003,6 +3015,61 @@ async function validateAiditorSettings(context, result) {
     });
   }
 }
+async function compileValidateRouteJayHtml(absoluteJayHtmlPath, pluginRoot) {
+  const content = fs$1.readFileSync(absoluteJayHtmlPath, "utf-8");
+  const dirname = path$1.dirname(absoluteJayHtmlPath);
+  const filename = path$1.basename(absoluteJayHtmlPath, JAY_EXTENSION$1);
+  const errors = [];
+  try {
+    const parsedFile = await parseJayFile(
+      content,
+      filename,
+      dirname,
+      {},
+      JAY_IMPORT_RESOLVER,
+      pluginRoot
+    );
+    for (const validation of parsedFile.validations) {
+      errors.push(validation);
+    }
+    if (!parsedFile.val || parsedFile.validations.length > 0) {
+      return errors;
+    }
+    const generatedFile = generateElementFile(parsedFile.val, RuntimeMode$1.MainTrusted);
+    for (const validation of generatedFile.validations) {
+      errors.push(validation);
+    }
+    const serverElementFile = generateServerElementFile(parsedFile.val);
+    for (const validation of serverElementFile.validations) {
+      errors.push(`[SSR] ${validation}`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    errors.push(message);
+  }
+  return errors;
+}
+async function validateRouteJayHtmlTemplates(context, result) {
+  const routes = context.manifest.routes;
+  if (!routes || !Array.isArray(routes)) return;
+  for (const route of routes) {
+    if (!route.jayHtml) continue;
+    const absolutePath = path$1.resolve(context.pluginPath, route.jayHtml);
+    if (!fs$1.existsSync(absolutePath)) {
+      continue;
+    }
+    const compileErrors = await compileValidateRouteJayHtml(absolutePath, context.pluginPath);
+    const relPath = path$1.relative(context.pluginPath, absolutePath);
+    for (const message of compileErrors) {
+      result.errors.push({
+        type: "jay-html-compile",
+        message: `Route "${route.path}" jayHtml failed to compile: ${message}`,
+        location: relPath,
+        suggestion: "Fix the template syntax or run `jay-stack validate -p <dir>` on the source page during development. See agent-kit/designer/jay-html-template-syntax.md"
+      });
+    }
+  }
+}
 async function validatePlugin(options = {}) {
   const pluginPath = options.pluginPath || process.cwd();
   if (options.local) {
@@ -3072,6 +3139,7 @@ async function validatePluginPackage(pluginPath, options) {
   await validateAddMenuCatalog(context, result);
   await validateAiditorSettings(context, result);
   validateNoCompilerLeak(context, result);
+  await validateRouteJayHtmlTemplates(context, result);
   result.valid = result.errors.length === 0;
   return result;
 }
@@ -3926,6 +3994,20 @@ async function validatePackageJson(context, result) {
         suggestion: 'Add "./plugin.yaml": "./plugin.yaml" to exports field'
       });
     }
+    if (context.manifest.commands) {
+      for (const cmd of context.manifest.commands) {
+        if (!cmd.command) continue;
+        const exportKey = `./${cmd.command}`;
+        if (!packageJson.exports || !packageJson.exports[exportKey]) {
+          result.errors.push({
+            type: "export-mismatch",
+            message: `command metadata file "${cmd.command}" not exported in package.json (required for plugin resolution)`,
+            location: packageJsonPath,
+            suggestion: `Add "${exportKey}": "${exportKey}" to exports field`
+          });
+        }
+      }
+    }
     const agentKitDir = path$1.join(context.pluginPath, "agent-kit");
     if (fs$1.existsSync(agentKitDir) && fs$1.statSync(agentKitDir).isDirectory()) {
       const filesArray = packageJson.files;
@@ -4745,6 +4827,627 @@ function scopeInnerBody(block) {
 function normalizeCssBody(body) {
   return body.replace(/\s+/g, " ").replace(/\s*([{}:;,])\s*/g, "$1").replace(/;}/g, "}").trim();
 }
+const SUPPRESS_KEY = "allow-broken-links";
+const SUPPRESS_HINT = 'suppress with jay-stack:\n  allow-broken-links: true\nin a <script type="application/jay-validations"> block';
+function normalizePath(p) {
+  let s2 = p.split("#")[0].split("?")[0];
+  s2 = s2.replace(/\/{2,}/g, "/");
+  if (s2.length > 1) s2 = s2.replace(/\/+$/, "");
+  return s2 === "" ? "/" : s2;
+}
+function escapeRegExp(s2) {
+  return s2.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function routeToConcreteUrl(route) {
+  const parts = [];
+  for (const seg of route.segments) {
+    if (typeof seg === "string") {
+      parts.push(seg);
+    } else {
+      const v = route.inferredParams?.[seg.name];
+      if (v === void 0) return null;
+      parts.push(v);
+    }
+  }
+  return normalizePath("/" + parts.join("/"));
+}
+function routeToRegex(route) {
+  let pattern = "";
+  for (const seg of route.segments) {
+    if (typeof seg === "string") {
+      pattern += "/" + escapeRegExp(seg);
+    } else if (seg.type === JayRouteParamType.optional) {
+      pattern += "(?:/[^/]+)?";
+    } else if (seg.type === JayRouteParamType.catchAll) {
+      pattern += "(?:/[^/]+)+";
+    } else {
+      pattern += "/[^/]+";
+    }
+  }
+  if (pattern === "") pattern = "/";
+  return new RegExp("^" + pattern + "$");
+}
+async function buildRouteOracle(pagesBase) {
+  let routes = [];
+  try {
+    ({ routes } = await scanRoutes(pagesBase, {
+      jayHtmlFilename: "page.jay-html",
+      compFilename: "page.ts"
+    }));
+  } catch {
+    routes = [];
+  }
+  const staticUrls = /* @__PURE__ */ new Set();
+  const dynamicMatchers = [];
+  const selfUrlByPath = /* @__PURE__ */ new Map();
+  for (const route of routes) {
+    const concrete = routeToConcreteUrl(route);
+    if (concrete !== null) {
+      staticUrls.add(concrete);
+      if (route.jayHtmlPath) selfUrlByPath.set(path$1.resolve(route.jayHtmlPath), concrete);
+    }
+    if (route.segments.some((s2) => typeof s2 !== "string")) {
+      dynamicMatchers.push(routeToRegex(route));
+    }
+  }
+  return { staticUrls, dynamicMatchers, selfUrlByPath };
+}
+async function collectPublicAssets(publicFolder) {
+  const assets = /* @__PURE__ */ new Set();
+  async function walk(dir, prefix) {
+    let entries;
+    try {
+      entries = await promises.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        await walk(path$1.join(dir, entry.name), rel);
+      } else {
+        assets.add("/" + rel);
+      }
+    }
+  }
+  await walk(publicFolder, "");
+  return assets;
+}
+function originOf(baseUrl) {
+  try {
+    return new URL(baseUrl).origin;
+  } catch {
+    return void 0;
+  }
+}
+function classifyHref(raw, baseUrl) {
+  if (raw.includes("{")) return { kind: "skip" };
+  const t = raw.trim();
+  if (t === "" || t === "#") return { kind: "degenerate" };
+  if (t.startsWith("#")) return { kind: "skip" };
+  if (/^(mailto:|tel:|javascript:|data:|sms:|ftp:)/i.test(t)) return { kind: "skip" };
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(t) || t.startsWith("//")) {
+    const sameOrigin = baseUrl ? originOf(baseUrl) : void 0;
+    if (sameOrigin) {
+      try {
+        const u2 = new URL(t.startsWith("//") ? "https:" + t : t);
+        if (u2.origin === sameOrigin)
+          return { kind: "check", targetPath: normalizePath(u2.pathname) };
+      } catch {
+      }
+    }
+    return { kind: "skip" };
+  }
+  if (t.startsWith("/")) return { kind: "check", targetPath: normalizePath(t) };
+  return { kind: "skip" };
+}
+function checkInternalLinks(options) {
+  const { parsedFiles, oracle, assetUrls, baseUrl, projectRoot } = options;
+  const findings = [];
+  for (const { relativePath, parsed } of parsedFiles) {
+    if (parsed.validationOverrides?.["jay-stack"]?.[SUPPRESS_KEY] === true) continue;
+    const ownUrl = oracle.selfUrlByPath.get(path$1.resolve(projectRoot ?? ".", relativePath));
+    for (const anchor of parsed.body.querySelectorAll("a[href]")) {
+      const raw = anchor.getAttribute("href");
+      if (raw === void 0 || raw === null) continue;
+      const verdict = classifyHref(raw, baseUrl);
+      if (verdict.kind === "skip") continue;
+      if (verdict.kind === "degenerate") {
+        findings.push({
+          file: relativePath,
+          message: `Anchor has a placeholder href "${raw}" — it links nowhere and ships as a dead link.`,
+          suggestion: `Point the link at a real page, use <button> for a JS-driven action, or ${SUPPRESS_HINT}.`
+        });
+        continue;
+      }
+      const target = verdict.targetPath;
+      if (ownUrl !== void 0 && target === ownUrl) {
+        findings.push({
+          file: relativePath,
+          message: `Link points to the page's own route "${target}" — a self-link goes nowhere.`,
+          suggestion: `Remove the link, use "#" within-page navigation, or point it at a different page.`
+        });
+        continue;
+      }
+      if (oracle.staticUrls.has(target)) continue;
+      if (assetUrls.has(target)) continue;
+      if (oracle.dynamicMatchers.some((re) => re.test(target))) continue;
+      findings.push({
+        file: relativePath,
+        message: `Broken internal link "${raw}" — no page or public asset produces the URL "${target}".`,
+        suggestion: `Create a placeholder page/route for "${target}", or remove the link. Otherwise ${SUPPRESS_HINT}.`
+      });
+    }
+  }
+  return findings;
+}
+const META_SUPPRESS_HINT = 'suppress with jay-stack:\n  allow-meta-issues: true\nin the page <script type="application/jay-validations"> block';
+const LINK_SUPPRESS_HINT = 'suppress with jay-stack:\n  allow-broken-links: true\nin the page <script type="application/jay-validations"> block';
+const UNRESOLVED_BINDING = /\{[A-Za-z_$][\w$]*(?:\.[\w$]+)*\}/;
+const TITLE_MAX = 60;
+const DESCRIPTION_MAX = 160;
+function buildUrlFromManifest(pattern, params) {
+  return pattern.replace(/\[\[(\w+)\]\]/g, (_, name) => params[name] || "").replace(/\[\.\.\.(\w+)\]/g, (_, name) => params[name] || "").replace(/\[(\w+)\]/g, (_, name) => params[name] || "").replace(/\/\/+/g, "/").replace(/\/$/, "") || "/";
+}
+function routeInstanceUrl(route, instance) {
+  return normalizePath(buildUrlFromManifest(route.pattern, instance.params));
+}
+async function discoverBuildBackendDir(projectRoot, explicit) {
+  if (explicit) {
+    const abs = path$1.resolve(projectRoot, explicit);
+    if (await fileExists(path$1.join(abs, "route-manifest.json"))) return abs;
+    const nested = path$1.join(abs, "backend");
+    if (await fileExists(path$1.join(nested, "route-manifest.json"))) return nested;
+    const fromRoot = await highestVersionBackend(abs);
+    if (fromRoot) return fromRoot;
+    return null;
+  }
+  return highestVersionBackend(path$1.join(projectRoot, "build"));
+}
+async function highestVersionBackend(buildRoot) {
+  let entries;
+  try {
+    entries = (await promises.readdir(buildRoot, { withFileTypes: true })).filter((e2) => e2.isDirectory() && /^v/.test(e2.name)).map((e2) => e2.name);
+  } catch {
+    return null;
+  }
+  if (entries.length === 0) return null;
+  entries.sort(compareVersionDesc);
+  for (const name of entries) {
+    const backend = path$1.join(buildRoot, name, "backend");
+    if (await fileExists(path$1.join(backend, "route-manifest.json"))) return backend;
+  }
+  return null;
+}
+function compareVersionDesc(a, b) {
+  const pa = a.replace(/^v/, "").split(".").map(Number);
+  const pb = b.replace(/^v/, "").split(".").map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const da = pa[i] || 0;
+    const db = pb[i] || 0;
+    if (da !== db) return db - da;
+  }
+  return 0;
+}
+async function fileExists(p) {
+  try {
+    await promises.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function loadBuildManifest(backendDir) {
+  let manifest;
+  try {
+    manifest = JSON.parse(
+      await promises.readFile(path$1.join(backendDir, "route-manifest.json"), "utf8")
+    );
+  } catch {
+    return null;
+  }
+  let metadata = null;
+  try {
+    metadata = JSON.parse(
+      await promises.readFile(path$1.join(backendDir, "build-metadata.json"), "utf8")
+    );
+  } catch {
+    metadata = null;
+  }
+  return { manifest, metadata };
+}
+function buildBuildOracle(manifest, backendDir) {
+  const urls = /* @__PURE__ */ new Set();
+  const instances = [];
+  for (const route of manifest.routes) {
+    const hasDynamic = route.segments.some((s2) => s2.type !== "static");
+    if (route.instances.length === 0) {
+      if (!hasDynamic) urls.add(normalizePath(route.pattern));
+      continue;
+    }
+    for (const instance of route.instances) {
+      const url = routeInstanceUrl(route, instance);
+      urls.add(url);
+      instances.push({
+        url,
+        cacheAbsPath: path$1.resolve(backendDir, instance.cachePath),
+        pattern: route.pattern,
+        headMeta: route.headMeta
+      });
+    }
+  }
+  return { urls, instances };
+}
+async function loadSlowViewState(cacheAbsPath) {
+  try {
+    const cache = JSON.parse(await promises.readFile(cacheAbsPath, "utf8"));
+    return cache.slowViewState ?? {};
+  } catch {
+    return {};
+  }
+}
+async function loadCarryForward(cacheAbsPath) {
+  try {
+    const cache = JSON.parse(await promises.readFile(cacheAbsPath, "utf8"));
+    return cache.carryForward ?? {};
+  } catch {
+    return {};
+  }
+}
+function jsonLdBodyError(body) {
+  const text = body?.trim();
+  if (!text) return "Empty JSON-LD block — add structured data or remove the tag.";
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (e2) {
+    return `Invalid JSON: ${e2.message}`;
+  }
+  const objs = Array.isArray(parsed) ? parsed : [parsed];
+  for (const obj of objs) {
+    if (!obj || typeof obj !== "object") {
+      return "JSON-LD must be an object (or array of objects) with @context and @type.";
+    }
+    if (!("@context" in obj) || !("@type" in obj)) {
+      return "JSON-LD is missing @context or @type.";
+    }
+  }
+  return null;
+}
+function isLdJsonHeadTag(tag) {
+  return tag?.tag?.toLowerCase?.() === "script" && tag?.attrs?.type === "application/ld+json";
+}
+function checkBuildJsonLd(manifest) {
+  const findings = [];
+  for (const tag of manifest.siteHeadTags ?? []) {
+    if (!isLdJsonHeadTag(tag)) continue;
+    const err = jsonLdBodyError(tag.children);
+    if (err) {
+      findings.push({
+        file: ".jay (site.*)",
+        message: `Site JSON-LD: ${err}`,
+        severity: "error",
+        source: "build-output"
+      });
+    }
+  }
+  for (const route of manifest.routes) {
+    for (const script of route.scripts ?? []) {
+      if (script.attributes?.type !== "application/ld+json") continue;
+      const err = jsonLdBodyError(script.inline);
+      if (err) {
+        findings.push({
+          file: route.pattern,
+          message: `Template JSON-LD: ${err}`,
+          severity: "error",
+          source: "build-output"
+        });
+      }
+    }
+  }
+  return findings;
+}
+function checkInstanceJsonLd(args) {
+  const { instanceUrl, carryForward } = args;
+  const findings = [];
+  const slowHeadTags = carryForward?.__slowHeadTags;
+  if (!Array.isArray(slowHeadTags)) return findings;
+  for (const source of slowHeadTags) {
+    if (!Array.isArray(source)) continue;
+    for (const tag of source) {
+      if (!isLdJsonHeadTag(tag)) continue;
+      const err = jsonLdBodyError(tag?.children);
+      if (err) {
+        findings.push({
+          file: instanceUrl,
+          message: `Component JSON-LD: ${err}`,
+          severity: "error",
+          source: "build-output"
+        });
+      }
+    }
+  }
+  return findings;
+}
+function checkTemplateLinksAgainstBuild(args) {
+  const { parsedFiles, buildUrls, assetUrls, dynamicMatchers, baseUrl } = args;
+  const findings = [];
+  for (const { relativePath, parsed } of parsedFiles) {
+    if (parsed.validationOverrides?.["jay-stack"]?.["allow-broken-links"] === true) continue;
+    for (const anchor of parsed.body.querySelectorAll("a[href]")) {
+      const raw = anchor.getAttribute("href");
+      if (raw === void 0 || raw === null) continue;
+      const verdict = classifyHref(raw, baseUrl);
+      if (verdict.kind !== "check") continue;
+      const target = verdict.targetPath;
+      if (buildUrls.has(target) || assetUrls.has(target)) continue;
+      if (!dynamicMatchers.some((re) => re.test(target))) continue;
+      findings.push({
+        file: relativePath,
+        message: `Broken link "${raw}" — matches a dynamic route but "${target}" is not among the URLs this build produces.`,
+        suggestion: `Create the slug/page, fix the path, or remove the link. Otherwise ${LINK_SUPPRESS_HINT}.`,
+        severity: "error",
+        source: "build-output"
+      });
+    }
+  }
+  return findings;
+}
+function resolveContentHref(raw, instanceUrl, baseUrl) {
+  const t = raw.trim();
+  if (t === "" || t === "#" || t.startsWith("#")) return { kind: "skip" };
+  if (t.includes("{")) return { kind: "skip" };
+  if (t.startsWith("/") || t.startsWith("//") || /^[a-z][a-z0-9+.-]*:/i.test(t)) {
+    const v = classifyHref(t, baseUrl);
+    return v.kind === "check" ? v : { kind: "skip" };
+  }
+  try {
+    const u2 = new URL(t, "https://_local_" + (instanceUrl === "/" ? "/" : instanceUrl));
+    return { kind: "check", targetPath: normalizePath(u2.pathname) };
+  } catch {
+    return { kind: "skip" };
+  }
+}
+function collectContentHrefs(viewState) {
+  const hrefs = [];
+  const seen = /* @__PURE__ */ new Set();
+  const walk = (node) => {
+    if (node == null) return;
+    if (typeof node === "string") {
+      if (node.includes("<a ")) {
+        const root = parse(node);
+        for (const a of root.querySelectorAll("a[href]")) {
+          const h = a.getAttribute("href");
+          if (h) hrefs.push(h);
+        }
+      }
+      return;
+    }
+    if (typeof node !== "object") return;
+    if (seen.has(node)) return;
+    seen.add(node);
+    if (Array.isArray(node)) {
+      for (const item of node) walk(item);
+    } else {
+      for (const v of Object.values(node)) walk(v);
+    }
+  };
+  walk(viewState);
+  return hrefs;
+}
+function checkContentLinks(args) {
+  const { instanceUrl, slowViewState, buildUrls, assetUrls, baseUrl } = args;
+  const findings = [];
+  const reported = /* @__PURE__ */ new Set();
+  for (const raw of collectContentHrefs(slowViewState)) {
+    const verdict = resolveContentHref(raw, instanceUrl, baseUrl);
+    if (verdict.kind !== "check") continue;
+    const target = verdict.targetPath;
+    if (buildUrls.has(target) || assetUrls.has(target)) continue;
+    if (reported.has(target)) continue;
+    reported.add(target);
+    findings.push({
+      file: instanceUrl,
+      message: `Broken link "${raw}" in rendered content of ${instanceUrl} — resolves to "${target}", which this build does not produce.`,
+      // Content links come from authored markdown/CMS data that often doubles as repo docs (where a
+      // repo-relative "../pkg/foo.ts" is correct), so this is a warning, not a build-failing error —
+      // unlike hand-authored template links (Check 1), which are site-only and stay errors.
+      suggestion: `Fix the link in the source content, point it at an absolute URL, or ${LINK_SUPPRESS_HINT}.`,
+      severity: "warning",
+      source: "build-output"
+    });
+  }
+  return findings;
+}
+function checkInstanceMeta(args) {
+  const { instanceUrl, headMeta, slowViewState } = args;
+  if (!headMeta) return [];
+  const findings = [];
+  const tags = headMetaToHeadTags(headMeta, slowViewState);
+  const addLeftover = (what, value) => findings.push({
+    file: instanceUrl,
+    message: `<${what}> for ${instanceUrl} resolves to "${value}" — an unresolved binding was not produced by slow render.`,
+    suggestion: `Ensure the field is produced by the slow phase, or make the ${what} static.`,
+    severity: "error",
+    source: "build-output"
+  });
+  const addWarn = (message) => findings.push({
+    file: instanceUrl,
+    message,
+    suggestion: `Fix the content or ${META_SUPPRESS_HINT}.`,
+    severity: "warning",
+    source: "build-output"
+  });
+  for (const tag of tags) {
+    if (tag.tag === "title") {
+      const value = tag.children ?? "";
+      if (UNRESOLVED_BINDING.test(value)) addLeftover("title", value);
+      else if (value.trim() === "") addWarn(`<title> for ${instanceUrl} is empty.`);
+      else if (value.length > TITLE_MAX)
+        addWarn(
+          `<title> for ${instanceUrl} is ${value.length} chars (recommend ≤ ${TITLE_MAX}).`
+        );
+    } else if (tag.tag === "meta" && tag.attrs?.name === "description") {
+      const value = tag.attrs.content ?? "";
+      if (UNRESOLVED_BINDING.test(value)) addLeftover('meta name="description"', value);
+      else if (value.trim() === "")
+        addWarn(`<meta name="description"> for ${instanceUrl} is empty.`);
+      else if (value.length > DESCRIPTION_MAX)
+        addWarn(
+          `<meta name="description"> for ${instanceUrl} is ${value.length} chars (recommend ≤ ${DESCRIPTION_MAX}).`
+        );
+    }
+  }
+  return findings;
+}
+function isBuildStale(metadata, newestSourceMtimeMs) {
+  if (!metadata?.buildTimestamp) return false;
+  const built = Date.parse(metadata.buildTimestamp);
+  if (Number.isNaN(built)) return false;
+  return newestSourceMtimeMs > built;
+}
+async function newestSourceMtime(dirs) {
+  let newest = 0;
+  const walk = async (dir) => {
+    let entries;
+    try {
+      entries = await promises.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name === "node_modules" || entry.name === ".git") continue;
+      const full = path$1.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full);
+      } else {
+        try {
+          const st = await promises.stat(full);
+          if (st.mtimeMs > newest) newest = st.mtimeMs;
+        } catch {
+        }
+      }
+    }
+  };
+  for (const dir of dirs) await walk(dir);
+  return newest;
+}
+const URN_PATTERN = /^urn:air:[^:\s]+:[^:\s]+:[^:\s]+$/;
+const MEDIA_TYPE_PATTERN = /^[a-z]+\/[A-Za-z0-9.+-]+$/;
+const ARD_SUGGEST = "See developer/seo-guide.md (ARD v0.91) for the schema and a worked example.";
+function validateArdDocument(doc) {
+  const findings = [];
+  if (!doc || typeof doc !== "object") {
+    return [
+      {
+        message: "ard.json must be a JSON object with an `entries` array.",
+        severity: "error",
+        suggestion: ARD_SUGGEST
+      }
+    ];
+  }
+  const entries = doc.entries;
+  if (!Array.isArray(entries)) {
+    return [
+      {
+        message: "ard.json is missing the required `entries` array.",
+        severity: "error",
+        suggestion: ARD_SUGGEST
+      }
+    ];
+  }
+  entries.forEach((entry, i) => {
+    const at = `ard.json entries[${i}]`;
+    if (!entry || typeof entry !== "object") {
+      findings.push({ message: `${at} must be an object.`, severity: "error" });
+      return;
+    }
+    if (typeof entry.identifier !== "string" || !URN_PATTERN.test(entry.identifier)) {
+      findings.push({
+        message: `${at}.identifier must match urn:air:<publisher>:<namespace>:<name>.`,
+        severity: "error",
+        suggestion: ARD_SUGGEST
+      });
+    }
+    if (typeof entry.displayName !== "string" || entry.displayName.trim() === "") {
+      findings.push({
+        message: `${at}.displayName is required.`,
+        severity: "error"
+      });
+    }
+    if (typeof entry.type !== "string" || !MEDIA_TYPE_PATTERN.test(entry.type)) {
+      findings.push({
+        message: `${at}.type must be an IANA media type (e.g. application/mcp-server-card+json).`,
+        severity: "error"
+      });
+    }
+    const hasUrl = entry.url !== void 0;
+    const hasData = entry.data !== void 0;
+    if (hasUrl === hasData) {
+      findings.push({
+        message: `${at} must have exactly one of \`url\` or \`data\`.`,
+        severity: "error"
+      });
+    }
+    const rq = entry.representativeQueries;
+    if (rq === void 0) {
+      findings.push({
+        message: `${at} is missing representativeQueries (2–5 recommended) — agents may not surface this resource.`,
+        severity: "warning",
+        suggestion: ARD_SUGGEST
+      });
+    } else if (!Array.isArray(rq) || rq.length < 2 || rq.length > 5) {
+      findings.push({
+        message: `${at}.representativeQueries should list 2–5 example queries.`,
+        severity: "warning"
+      });
+    }
+  });
+  return findings;
+}
+async function checkArdFiles(projectRoot) {
+  const wellKnown = path$1.resolve(projectRoot, "public/.well-known");
+  const ardPath = path$1.join(wellKnown, "ard.json");
+  const aliasPath = path$1.join(wellKnown, "ai-catalog.json");
+  const ardRaw = await readIfExists(ardPath);
+  const aliasRaw = await readIfExists(aliasPath);
+  if (ardRaw === null && aliasRaw === null) {
+    return { findings: [], absent: true };
+  }
+  const findings = [];
+  if (ardRaw === null && aliasRaw !== null) {
+    findings.push({
+      message: "Only public/.well-known/ai-catalog.json found — ARD renamed this to ard.json. Add ard.json (keep ai-catalog.json as a copy for older clients).",
+      severity: "warning",
+      suggestion: ARD_SUGGEST
+    });
+  } else if (ardRaw !== null && aliasRaw !== null && ardRaw.trim() !== aliasRaw.trim()) {
+    findings.push({
+      message: "public/.well-known/ard.json and ai-catalog.json differ — the alias should be a copy of ard.json.",
+      severity: "warning"
+    });
+  }
+  const canonicalRaw = ardRaw ?? aliasRaw;
+  let parsed;
+  try {
+    parsed = JSON.parse(canonicalRaw);
+  } catch (e2) {
+    findings.push({
+      message: `${ardRaw !== null ? "ard.json" : "ai-catalog.json"} is not valid JSON: ${e2.message}`,
+      severity: "error"
+    });
+    return { findings, absent: false };
+  }
+  findings.push(...validateArdDocument(parsed));
+  return { findings, absent: false };
+}
+async function readIfExists(p) {
+  try {
+    return await promises.readFile(p, "utf8");
+  } catch {
+    return null;
+  }
+}
 async function findJayFiles(dir) {
   return await glob(`${dir}/**/*${JAY_EXTENSION$1}`);
 }
@@ -4946,6 +5649,17 @@ function resolveContractTag(contract, tagPath) {
   }
   return void 0;
 }
+function checkJsonLdScripts(jayHtml) {
+  const errors = [];
+  for (const script of jayHtml.scripts ?? []) {
+    if (script.attributes?.type !== "application/ld+json") continue;
+    const err = jsonLdBodyError(script.inline);
+    if (err) {
+      errors.push(`<script type="application/ld+json">: ${err} See designer/seo-guide.md.`);
+    }
+  }
+  return errors;
+}
 function checkRefElementTypes(jayHtml, file) {
   const imports = jayHtml.headlessImports;
   const keyMap = /* @__PURE__ */ new Map();
@@ -5873,14 +6587,12 @@ async function validateJayFiles(options = {}) {
   const reuseByTemplate = /* @__PURE__ */ new Map();
   const cataloguedContractFiles = /* @__PURE__ */ new Set();
   const pageJayHtmlFiles = await findJayFiles(scanDir);
-  const componentJayHtmlFiles = await findJayFiles(componentsDir).catch(() => []);
+  const componentJayHtmlFiles = options.compileOnly ? [] : await findJayFiles(componentsDir).catch(() => []);
   const jayHtmlFiles = [...pageJayHtmlFiles, ...componentJayHtmlFiles];
   const componentJayHtmlFileSet = new Set(componentJayHtmlFiles);
-  const componentContractFiles = await findContractFiles(componentsDir).catch(
-    () => []
-  );
+  const componentContractFiles = options.compileOnly ? [] : await findContractFiles(componentsDir).catch(() => []);
   for (const cf of componentContractFiles) cataloguedContractFiles.add(cf);
-  const contractFiles = [...await findContractFiles(scanDir), ...componentContractFiles];
+  const contractFiles = options.compileOnly ? [] : [...await findContractFiles(scanDir), ...componentContractFiles];
   const contractNameByFile = /* @__PURE__ */ new Map();
   if (options.verbose) {
     getLogger().info(chalk.gray(`Scanning directory: ${scanDir}`));
@@ -5947,6 +6659,35 @@ async function validateJayFiles(options = {}) {
         continue;
       }
       parsedFiles.push({ relativePath, parsed: parsedFile.val });
+      if (options.compileOnly) {
+        const generatedFile2 = generateElementFile(
+          parsedFile.val,
+          RuntimeMode$1.MainTrusted,
+          GenerateTarget.jay
+        );
+        for (const validation of generatedFile2.validations) {
+          errors.push({
+            file: relativePath,
+            message: validation,
+            stage: "generate"
+          });
+        }
+        const serverElementFile2 = generateServerElementFile(parsedFile.val);
+        for (const validation of serverElementFile2.validations) {
+          errors.push({
+            file: relativePath,
+            message: `[SSR] ${validation}`,
+            stage: "generate"
+          });
+        }
+        if (options.verbose) {
+          const failed = generatedFile2.validations.length > 0 || serverElementFile2.validations.length > 0;
+          getLogger().info(
+            failed ? chalk.red(`❌ ${relativePath}`) : chalk.green(`✓ ${relativePath}`)
+          );
+        }
+        continue;
+      }
       if (content.includes("application/jay-params")) {
         errors.push({
           file: relativePath,
@@ -6038,6 +6779,9 @@ async function validateJayFiles(options = {}) {
           suggestion: finding.suggestion
         });
       }
+      for (const message of checkJsonLdScripts(parsedFile.val)) {
+        errors.push({ file: relativePath, message, stage: "generate" });
+      }
       regionsSeen += collectRegionElements(parsedFile.val.body).length;
       templateImportsSeen += parsedFile.val.headlessImports.filter(
         (imp) => imp.template
@@ -6165,6 +6909,24 @@ async function validateJayFiles(options = {}) {
       }
     }
   }
+  if (options.compileOnly) {
+    return {
+      valid: errors.length === 0,
+      jayHtmlFilesScanned: jayHtmlFiles.length,
+      contractFilesScanned: contractFiles.length,
+      errors,
+      warnings,
+      coverage,
+      pluginValidators: [],
+      designSystemCoverage,
+      designSystemReuse: {
+        perTemplate: {},
+        catalogued: 0,
+        reusedMoreThanOnce: 0,
+        reusedOfCatalogued: 0
+      }
+    };
+  }
   const robotsTxtPath = path$1.resolve(projectRoot, "public/robots.txt");
   if (!fs$1.existsSync(robotsTxtPath)) {
     warnings.push({
@@ -6180,6 +6942,60 @@ async function validateJayFiles(options = {}) {
       suggestion: "Add to .jay config:\n  site:\n    baseUrl: https://your-domain.com"
     });
   }
+  if (!config.site?.name) {
+    warnings.push({
+      file: ".jay",
+      message: "site.name not configured — Organization/WebSite JSON-LD and llms.txt will not be emitted, reducing how well search engines and agents understand the site.",
+      suggestion: "Add to .jay config:\n  site:\n    name: Your Site Name\n    logo: /logo.png\n    description: What your site is about"
+    });
+  }
+  const allowNoArd = config.validations?.["allow-no-ard"] === true;
+  const ardResult = await checkArdFiles(projectRoot);
+  if (ardResult.absent) {
+    if (!allowNoArd) {
+      warnings.push({
+        file: "public/.well-known/ard.json",
+        message: "public/.well-known/ard.json not found — agents cannot discover this site’s resources/APIs via Agentic Resource Discovery.",
+        suggestion: "Author public/.well-known/ard.json (ARD v0.91), or suppress with `validations: { allow-no-ard: true }` in .jay if the site has no agent resources to advertise. See developer/seo-guide.md."
+      });
+    }
+  } else {
+    for (const finding of ardResult.findings) {
+      if (finding.severity === "error") {
+        errors.push({
+          file: "public/.well-known/ard.json",
+          message: finding.message,
+          stage: "generate",
+          suggestion: finding.suggestion
+        });
+      } else {
+        warnings.push({
+          file: "public/.well-known/ard.json",
+          message: finding.message,
+          suggestion: finding.suggestion
+        });
+      }
+    }
+  }
+  const allowNoErrorPages = config.validations?.["allow-no-error-pages"] === true;
+  if (!allowNoErrorPages) {
+    const scanResult = await scanRoutes(scanDir, {
+      jayHtmlFilename: "page.jay-html",
+      compFilename: "page.ts"
+    });
+    const errorPages = scanResult.errorPages ?? [];
+    const tokens = new Set(errorPages.map((ep) => ep.token));
+    const missing = [];
+    if (!tokens.has("404") && !tokens.has("4xx")) missing.push("404");
+    if (!tokens.has("5xx")) missing.push("5xx");
+    if (missing.length > 0) {
+      warnings.push({
+        file: "src/pages",
+        message: `No branded error page for ${missing.join(" and ")} — these responses fall back to plain text instead of your site's layout.`,
+        suggestion: "Add pages/404/page.jay-html and pages/5xx/page.jay-html importing the `error` headless contract, or suppress with `validations: { allow-no-error-pages: true }` in .jay. See designer/error-pages-guide.md."
+      });
+    }
+  }
   const allowNoTemplate = /* @__PURE__ */ new Set();
   let allowNoDesignSystem = false;
   for (const { parsed } of parsedFiles) {
@@ -6235,6 +7051,38 @@ async function validateJayFiles(options = {}) {
       (p) => (reuseByTemplate.get(p) ?? 0) >= 2
     ).length
   };
+  const linkOracle = await buildRouteOracle(scanDir);
+  const assetUrls = await collectPublicAssets(
+    path$1.resolve(projectRoot, resolvedConfig.devServer.publicFolder)
+  );
+  const linkFindings = checkInternalLinks({
+    parsedFiles,
+    oracle: linkOracle,
+    assetUrls,
+    baseUrl: config.site?.baseUrl,
+    projectRoot
+  });
+  for (const finding of linkFindings) {
+    errors.push({
+      file: finding.file,
+      message: finding.message,
+      stage: "generate",
+      source: "internal-links",
+      suggestion: finding.suggestion
+    });
+  }
+  if (options.tier2) {
+    await runBuildOutputValidation({
+      projectRoot,
+      buildDir: options.buildDir,
+      parsedFiles,
+      linkOracle,
+      assetUrls,
+      baseUrl: config.site?.baseUrl,
+      errors,
+      warnings
+    });
+  }
   const pluginValidators = await runPluginValidators(projectRoot, parsedFiles, errors, warnings);
   return {
     valid: errors.length === 0,
@@ -6248,6 +7096,92 @@ async function validateJayFiles(options = {}) {
     designSystemReuse
   };
 }
+async function runBuildOutputValidation(args) {
+  const { projectRoot, buildDir, parsedFiles, linkOracle, assetUrls, baseUrl, errors, warnings } = args;
+  const backendDir = await discoverBuildBackendDir(projectRoot, buildDir);
+  if (!backendDir) {
+    errors.push({
+      file: "build",
+      message: "Tier 2: no build found. Run `jay-stack build` first, or point --build-dir at a build.",
+      stage: "generate",
+      source: "build-output"
+    });
+    return;
+  }
+  const loaded = await loadBuildManifest(backendDir);
+  if (!loaded) {
+    errors.push({
+      file: backendDir,
+      message: `Tier 2: could not read route-manifest.json in ${backendDir}.`,
+      stage: "generate",
+      source: "build-output"
+    });
+    return;
+  }
+  const newest = await newestSourceMtime([
+    path$1.join(projectRoot, "src"),
+    path$1.join(projectRoot, "content")
+  ]);
+  if (isBuildStale(loaded.metadata, newest)) {
+    warnings.push({
+      file: "build",
+      message: `Tier 2: validated against a build from ${loaded.metadata?.buildTimestamp}; source has changed since.`,
+      source: "build-output",
+      suggestion: "Re-run `jay-stack build` for accurate results."
+    });
+  }
+  const oracle = buildBuildOracle(loaded.manifest, backendDir);
+  const findings = [];
+  findings.push(
+    ...checkTemplateLinksAgainstBuild({
+      parsedFiles,
+      buildUrls: oracle.urls,
+      assetUrls,
+      dynamicMatchers: linkOracle.dynamicMatchers,
+      baseUrl
+    })
+  );
+  findings.push(...checkBuildJsonLd(loaded.manifest));
+  for (const instance of oracle.instances) {
+    const slowViewState = await loadSlowViewState(instance.cacheAbsPath);
+    findings.push(
+      ...checkContentLinks({
+        instanceUrl: instance.url,
+        slowViewState,
+        buildUrls: oracle.urls,
+        assetUrls,
+        baseUrl
+      })
+    );
+    findings.push(
+      ...checkInstanceMeta({
+        instanceUrl: instance.url,
+        headMeta: instance.headMeta,
+        slowViewState
+      })
+    );
+    const carryForward = await loadCarryForward(instance.cacheAbsPath);
+    findings.push(...checkInstanceJsonLd({ instanceUrl: instance.url, carryForward }));
+  }
+  for (const finding of findings) {
+    if (finding.severity === "error") {
+      errors.push({
+        file: finding.file,
+        message: finding.message,
+        stage: "generate",
+        source: "build-output",
+        suggestion: finding.suggestion
+      });
+    } else {
+      warnings.push({
+        file: finding.file,
+        message: finding.message,
+        source: "build-output",
+        suggestion: finding.suggestion
+      });
+    }
+  }
+}
 function printJayValidationResult(result, options) {
   const logger = getLogger();
   if (options.json) {
@@ -6255,9 +7189,11 @@ function printJayValidationResult(result, options) {
     return;
   }
   logger.important("");
-  const coreErrors = result.errors.filter((e2) => e2.stage !== "plugin");
+  const coreErrors = result.errors.filter(
+    (e2) => e2.stage !== "plugin" && e2.source !== "build-output"
+  );
   const coreWarnings = result.warnings.filter((w) => !w.source);
-  logger.important(chalk.bold("📦 jay-stack (core)"));
+  logger.important(chalk.bold("📦 Tier 1 — jay-stack (core)"));
   if (coreErrors.length === 0) {
     logger.important(
       chalk.green(
@@ -6280,6 +7216,40 @@ function printJayValidationResult(result, options) {
       logger.important(chalk.blue(`     Suggestion: ${warning.suggestion}`));
     }
   }
+  const buildErrors = result.errors.filter((e2) => e2.source === "build-output");
+  const buildWarnings = result.warnings.filter((w) => w.source === "build-output");
+  if (buildErrors.length > 0 || buildWarnings.length > 0) {
+    logger.important("");
+    logger.important(chalk.bold("📦 Tier 2 — build-output validation (--tier-2)"));
+    for (const error of buildErrors) {
+      logger.important(chalk.red(`   ❌ ${error.file}`));
+      logger.important(chalk.gray(`      ${error.message}`));
+      if (error.suggestion) {
+        logger.important(chalk.blue(`      Suggestion: ${error.suggestion}`));
+      }
+    }
+    const buildWarnGroups = /* @__PURE__ */ new Map();
+    for (const warning of buildWarnings) {
+      const group = buildWarnGroups.get(warning.file) || [];
+      group.push(warning);
+      buildWarnGroups.set(warning.file, group);
+    }
+    for (const [file, groupWarns] of buildWarnGroups) {
+      logger.important(chalk.yellow(`   ⚠ ${file}`));
+      for (const warning of groupWarns) {
+        if (warning.message) {
+          logger.important(chalk.gray(`      ${warning.message}`));
+        }
+      }
+      const suggestions = [...new Set(groupWarns.map((w) => w.suggestion).filter(Boolean))];
+      if (suggestions.length > 0) {
+        logger.important(chalk.blue(`      Suggestions:`));
+        for (const s2 of suggestions) {
+          logger.important(chalk.blue(`        ${s2}`));
+        }
+      }
+    }
+  }
   const pluginErrors = result.errors.filter((e2) => e2.stage === "plugin");
   const pluginWarnings = result.warnings.filter((w) => !!w.source);
   for (const validatorName of result.pluginValidators) {
@@ -6422,12 +7392,23 @@ function printJayValidationResult(result, options) {
       )
     );
   }
+  if (!options.tier2) {
+    logger.important("");
+    logger.important(
+      chalk.gray(
+        "ℹ This was Tier 1 (template) validation. Tier 2 runs deeper checks against an existing build\n  (dynamic-slug links, rendered-content links, per-instance meta):\n    jay-stack validate --tier-2\n  See: agent-kit/designer/validation-tier-2-guide.md"
+      )
+    );
+  }
 }
 async function runValidate(scanPath, options) {
   const result = await validateJayFiles({
     path: scanPath,
     verbose: options.verbose,
-    json: options.json
+    json: options.json,
+    tier2: options.tier2,
+    buildDir: options.buildDir,
+    compileOnly: options.compileOnly
   });
   printJayValidationResult(result, options);
   if (!result.valid) {
@@ -6533,10 +7514,12 @@ async function resolveProductionContext(projectPath, versionOverride) {
   const jayConfigPath = path__default.join(resolvedPath, ".jay");
   let pagesBase = "./src/pages";
   let siteBaseUrl;
+  let site;
   try {
     const jayConfig = YAML.parse(await fs$2.readFile(jayConfigPath, "utf-8"));
     pagesBase = jayConfig?.devServer?.pagesBase || pagesBase;
     siteBaseUrl = jayConfig?.site?.baseUrl;
+    site = jayConfig?.site;
   } catch {
   }
   const version = versionOverride || await resolveVersionFromPackageJson(resolvedPath);
@@ -6546,7 +7529,8 @@ async function resolveProductionContext(projectPath, versionOverride) {
     buildRoot: path__default.join(resolvedPath, "build"),
     version,
     tsConfigFilePath: path__default.join(resolvedPath, "tsconfig.json"),
-    siteBaseUrl
+    siteBaseUrl,
+    site
   };
 }
 async function resolveVersionFromPackageJson(projectRoot) {
@@ -6574,7 +7558,7 @@ async function runBuild(projectPath, options) {
   }
   const ctx = await resolveProductionContext(projectPath, options.version);
   await generateDefinitionFiles(ctx);
-  const { buildVersion } = await import("./index-l6QVpvnY.js");
+  const { buildVersion } = await import("./index-B5oavmfA.js");
   await buildVersion({
     version: ctx.version,
     projectRoot: ctx.resolvedPath,
@@ -6583,7 +7567,8 @@ async function runBuild(projectPath, options) {
     concurrency: 4,
     tsConfigFilePath: ctx.tsConfigFilePath,
     minify: options.minify,
-    siteBaseUrl: ctx.siteBaseUrl
+    siteBaseUrl: ctx.siteBaseUrl,
+    site: ctx.site
   });
 }
 async function generateDefinitionFiles(ctx) {
@@ -6650,7 +7635,8 @@ async function runRebuild(projectPath, options) {
     version: ctx.version,
     target,
     tsConfigFilePath: ctx.tsConfigFilePath,
-    siteBaseUrl: ctx.siteBaseUrl
+    siteBaseUrl: ctx.siteBaseUrl,
+    site: ctx.site
   });
   if (result.errors.length > 0) {
     for (const err of result.errors) {
@@ -7694,9 +8680,24 @@ program.command("cleanup").description("Delete orphaned files from previous rebu
     process.exit(1);
   }
 });
-program.command("validate").description("Validate all .jay-html and .jay-contract files").option("-p, --path <path>", "Scan root (default: cwd)").option("-v, --verbose", "Show per-file validation status").option("--json", "Output results as JSON").action(async (options) => {
+program.command("validate").description("Validate all .jay-html and .jay-contract files").option("-p, --path <path>", "Scan root (default: cwd)").option("-v, --verbose", "Show per-file validation status").option("--json", "Output results as JSON").addOption(
+  new Option(
+    "--tier-2",
+    "Run Tier 2: deep validation against an existing build (dynamic-slug links, rendered content, per-instance meta)"
+  )
+).addOption(new Option("--t2", "Alias for --tier-2").hideHelp()).option(
+  "--build-dir <dir>",
+  "Build backend dir or build root for Tier 2 (default: highest build/v*)"
+).option(
+  "--compile-only",
+  "Parse and compile .jay-html only (no project rules — for plugin route source checks)"
+).action(async (options) => {
   try {
-    await runValidate(options.path, options);
+    await runValidate(options.path, {
+      ...options,
+      tier2: options.tier2 || options.t2,
+      compileOnly: options.compileOnly
+    });
   } catch (error) {
     if (options.json) {
       getLogger().important(
@@ -7758,6 +8759,7 @@ export {
   listContracts,
   loadConfig,
   materializeContracts,
+  setWellKnownHeaders,
   startDevServer,
   updateConfig
 };