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

package/agent-kit-template/contracts/GUIDE.md

@@ -60,11 +60,11 @@ See [syntax.md](syntax.md) for the full YAML format: tag types, phases, data typ
 
 Start with the simplest example that matches your use case, then add complexity as needed:
 
-| Example                                                | Complexity     | Key patterns                                                |
-| ------------------------------------------------------ | -------------- | ----------------------------------------------------------- |
-| [mini-cart](examples/mini-cart.md)                     | Trivial        | Variant + interactive refs                                  |
-| [cart-indicator](examples/cart-indicator.md)           | Simple         | Flat data, variants, phase choices                          |
-| [category-list](examples/category-list.md)             | Medium         | Props, repeated sub-contracts                               |
-| [product-card](examples/product-card.md)               | Medium-complex | Linked sub-contracts, variants, multiple ref types          |
-| [product-page](examples/product-page.md)               | Complex        | Params, nested repeated sub-contracts, linked sub-contracts |
-| [composing-contracts](examples/composing-contracts.md) | Pattern        | How contracts link together into a hierarchy                |
+| Example                                                                                                                                                         | Complexity     | Key patterns                                                |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ----------------------------------------------------------- |
+| [mini-cart](https://github.com/jay-framework/jay/blob/main/packages/jay-stack/stack-cli/agent-kit-template/contracts/examples/mini-cart.md)                     | Trivial        | Variant + interactive refs                                  |
+| [cart-indicator](https://github.com/jay-framework/jay/blob/main/packages/jay-stack/stack-cli/agent-kit-template/contracts/examples/cart-indicator.md)           | Simple         | Flat data, variants, phase choices                          |
+| [category-list](https://github.com/jay-framework/jay/blob/main/packages/jay-stack/stack-cli/agent-kit-template/contracts/examples/category-list.md)             | Medium         | Props, repeated sub-contracts                               |
+| [product-card](https://github.com/jay-framework/jay/blob/main/packages/jay-stack/stack-cli/agent-kit-template/contracts/examples/product-card.md)               | Medium-complex | Linked sub-contracts, variants, multiple ref types          |
+| [product-page](https://github.com/jay-framework/jay/blob/main/packages/jay-stack/stack-cli/agent-kit-template/contracts/examples/product-page.md)               | Complex        | Params, nested repeated sub-contracts, linked sub-contracts |
+| [composing-contracts](https://github.com/jay-framework/jay/blob/main/packages/jay-stack/stack-cli/agent-kit-template/contracts/examples/composing-contracts.md) | Pattern        | How contracts link together into a hierarchy                |

package/agent-kit-template/contracts/linked-contracts.md

@@ -72,4 +72,4 @@ The linked contract must have a tag matching the `trackBy` field.
 
 ## See Also
 
-- [composing-contracts example](examples/composing-contracts.md) — Real-world composition hierarchy from wix-stores
+- [composing-contracts example](https://github.com/jay-framework/jay/blob/main/packages/jay-stack/stack-cli/agent-kit-template/contracts/examples/composing-contracts.md) — Real-world composition hierarchy from wix-stores

package/agent-kit-template/designer/cli-commands.md

@@ -69,8 +69,15 @@ jay-stack validate -v
 
 # JSON output
 jay-stack validate --json
+
+# Tier 2: deeper checks against an existing build (needs `jay-stack build` first)
+jay-stack validate --tier-2
 ```
 
+The default run is **Tier 1** (fast, template-only). `--tier-2` adds deep checks against a build's output
+(dynamic-slug links, rendered-content links, per-instance meta) — see
+[validation-tier-2-guide.md](validation-tier-2-guide.md).
+
 Example output:
 
 ```

package/agent-kit-template/designer/contracts-and-plugins.md

@@ -327,4 +327,4 @@ For repeated lists, add a **boolean variant** (e.g. `hasItems`, `hasCategories`)
 <div if="hasCategories" forEach="categories" trackBy="_id">...</div>
 ```
 
-Alternatively, expose a **number** data tag (`itemCount`) and use numeric comparison: `if="itemCount===0"`. See [jay-html-template-syntax.md](jay-html-template-syntax.md#expression-limits-important) and [contracts/examples/category-list.md](../contracts/examples/category-list.md).
+Alternatively, expose a **number** data tag (`itemCount`) and use numeric comparison: `if="itemCount===0"`. See [jay-html-template-syntax.md](jay-html-template-syntax.md#expression-limits-important) and [contracts/examples/category-list.md](https://github.com/jay-framework/jay/blob/main/packages/jay-stack/stack-cli/agent-kit-template/contracts/examples/category-list.md).

package/agent-kit-template/designer/jay-html-template-syntax.md

@@ -240,7 +240,7 @@ Jay-html expressions resolve **contract or page tag names only**. They are **not
 | Empty list hint | `hasItems: boolean` variant  | `if="!hasItems"`     |
 | Count-based UI  | `itemCount: number` data tag | `if="itemCount===0"` |
 
-See [contracts/examples/category-list.md](../contracts/examples/category-list.md) (`hasCategories`).
+See [contracts/examples/category-list.md](https://github.com/jay-framework/jay/blob/main/packages/jay-stack/stack-cli/agent-kit-template/contracts/examples/category-list.md) (`hasCategories`).
 
 ### Common Errors
 

package/agent-kit-template/designer/validation-guide.md

@@ -27,6 +27,13 @@ So a warning about an `<img>` might come from a full-stack component's template,
 - **Errors** block the build. They must be fixed — there is no way to suppress them.
 - **Warnings** must be either fixed or explicitly suppressed. Do not ignore warnings — each one has a clear resolution path (add the missing attribute, or suppress via `<script type="application/jay-validations">`).
 
+**Broken internal links are errors** (DL#210). `validate` resolves every `<a href>` against the project's
+**static routes + public assets**. An href that resolves to nothing is an error: a placeholder (`href="#"` or
+empty), a typo, or a link to a page/asset that does not exist. Links that match a **dynamic** route pattern
+(e.g. `/blog/[slug]`) are **not** checked here — the concrete slug list isn't known at validate time — so they
+never false-error. External URLs, `mailto:`/`tel:`, in-page `#fragments`, and `{binding}` hrefs are skipped.
+Fix the path, use `<button>` for JS-driven anchors, or suppress per-page (see the `jay-stack` table below).
+
 One design-system rule is a **hard error**, not a warning: `REGION-CSS-NO-REF` (DL#209) — a `<jay:X>` region
 whose `template=` ships CSS but which has no `ref=`. Without a `ref` the CSS has no scope anchor, so `sync`
 silently drops it; the fix is to add a `ref` (see `design-system-guide.md` → _The shape of a region's CSS_).
@@ -126,6 +133,7 @@ The core `jay-stack validate` emits four warnings that nudge you to reuse UI thr
 | `REGION-OVERRIDE-NON-CONTENT` | `jay-validations="REGION-OVERRIDE-NON-CONTENT"` on the import                                                                   |
 | `COMPONENT-NO-TEMPLATE`       | `jay-stack: allow-no-template: [Contract]`                                                                                      |
 | `NO-DESIGN-SYSTEM`            | `jay-stack: allow-no-design-system: true`                                                                                       |
+| Broken internal link (DL#210) | `jay-stack: allow-broken-links: true` (per-page — skips all link checks for that page)                                          |
 
 ```html
 <script type="application/jay-validations">
@@ -167,12 +175,28 @@ By default the scorecard prints **one-line totals** for the whole project:
 Run with `-v` / `--verbose` to expand the **per-page** breakdown (coverage per file, which tags are unused,
 per-template reuse counts, and `⚠ low` flags on pages under 50% coverage).
 
+## Two validation tiers
+
+Validation comes in two tiers. This guide covers **Tier 1**, the always-on gate.
+
+**Tier 1 — always on (`jay-stack validate`)** is the fast, template-only gate. It reads your `.jay-html` files and
+route scan only — **no build needed** — so it's cheap enough for the hot agent loop and runs on every `validate`.
+Everything described in this guide is Tier 1. For links, Tier 1 (DL#210) resolves every hand-authored `<a href>`
+against the project's static routes + public assets and **errors** on broken internal links (typos, missing
+pages), degenerate `#` / empty placeholder links, and self-links. Links matching a **dynamic** route pattern
+(`/design-log/[...slug]`) are deferred — the concrete slug set isn't known without a build.
+
+**Tier 2 — opt-in, against a build (`jay-stack validate --tier-2`)** adds deeper checks that need a build:
+dynamic-slug links, broken links in rendered content, and per-instance meta/SEO. It's documented separately to
+keep this guide focused — see **`validation-tier-2-guide.md`**. Run it pre-deploy / in CI.
+
 ## Running Validation
 
 ```bash
-jay-stack validate              # validate all pages (+ one-line scorecard totals)
-jay-stack validate -v           # add per-page tag coverage + scorecard detail
-jay-stack validate --strict     # treat warnings as errors
+jay-stack validate                     # Tier 1: all pages (+ one-line scorecard totals)
+jay-stack validate -v                  # add per-page tag coverage + scorecard detail
+jay-stack validate --strict            # treat warnings as errors
+jay-stack validate --tier-2            # also run Tier 2 — see validation-tier-2-guide.md
 ```
 
 Validation runs automatically during `jay-stack build`. Warnings don't block the build; errors do (with `--strict`).

package/agent-kit-template/designer/validation-tier-2-guide.md

@@ -0,0 +1,64 @@
+# Tier 2 Validation — Deep Checks Against a Build
+
+`jay-stack validate` runs **Tier 1**: the fast, template-only gate (links, placeholders, coverage) that needs no
+build. See `validation-guide.md` for Tier 1.
+
+**Tier 2** (`jay-stack validate --tier-2`) adds deeper checks that are only possible once a build exists. This
+guide covers Tier 2 end to end.
+
+## What Tier 2 is
+
+Deep validation against an **existing build's output** (DL#211). It reads
+`build/v<version>/backend/route-manifest.json` plus the per-instance `*.cache.json` slow-render results. It does
+**not** run any render, so it's cheap — but it **requires a prior `jay-stack build`**. If no build is found, Tier 2
+reports a single actionable error (run `jay-stack build` first, or drop `--tier-2`).
+
+Run it **pre-deploy / in CI**, not in the hot authoring loop.
+
+```bash
+jay-stack validate --tier-2                      # validate against the highest build/v* output
+jay-stack validate --t2                          # short alias
+jay-stack validate --tier-2 --build-dir <dir>    # point at a specific build backend dir or build root
+```
+
+Tier 2 findings print under their own `📦 Tier 2 — build-output validation (--tier-2)` section, separate from the
+Tier 1 `📦 jay-stack (core)` section.
+
+## The three checks
+
+All run against the concrete URLs the build actually produced (routes × instances).
+
+1. **Deferred dynamic-slug links** (ERROR) — the template links Tier 1 could only defer (because they matched a
+   dynamic pattern like `/design-log/[...slug]`) are resolved against the real URL set. A link to a dynamic route
+   with a slug the build never generated (e.g. `/design-log/wix/index`) is caught here.
+
+2. **Broken links in rendered content** (WARNING) — `<a href>` found _inside_ the slow-rendered ViewState
+   (markdown bodies, descriptions) that resolve to a URL the build does not produce. Relative hrefs are resolved
+   against the instance's own URL. These are **warnings**, not errors, because content often doubles as repo/GitHub
+   docs where repo-relative links like `../pkg/foo.ts` are legitimately correct.
+
+3. **Per-instance meta/SEO** (mostly WARNING) — resolves each route's `headMeta` template against each instance's
+   slow ViewState and validates the concrete `<title>` / `<meta name="description">`:
+   - Empty title/description, a title > 60 chars, or a description > 160 chars → **warning**.
+   - A leftover unresolved `{binding}` (a field never produced at any phase) → **error**.
+   - Note (DL#189): a field bound to the fast/interactive phase is legitimately empty at slow render, so
+     **emptiness is only ever a warning, never an error**.
+
+If the build is older than your current source files, a **staleness warning** is emitted ("validated against a
+build from &lt;timestamp&gt;; source has changed since") suggesting a rebuild.
+
+## Suppressing Tier 2 findings
+
+Per-page, via the same `<script type="application/jay-validations">` block used for Tier 1, under the `jay-stack:`
+key:
+
+- `allow-broken-links: true` — suppresses link findings (both template and rendered-content links) for that page.
+- `allow-meta-issues: true` — suppresses meta/SEO findings for that page.
+
+```html
+<script type="application/jay-validations">
+  jay-stack:
+    allow-broken-links: true
+    allow-meta-issues: true
+</script>
+```

package/dist/{index-l6QVpvnY.js → index-BQbkAEhi.js}

@@ -411,6 +411,102 @@ function buildPagePartsConfig(pageParts, pageServerModule, pageExportName, build
     }))
   };
 }
+function crossProductParams(parts) {
+  if (parts.length === 0) return [];
+  if (parts.length === 1) return parts[0].values;
+  const logger = getLogger();
+  for (let i = 0; i < parts.length; i++) {
+    for (let j = i + 1; j < parts.length; j++) {
+      for (const key of parts[i].keys) {
+        if (parts[j].keys.has(key)) {
+          logger.warn(
+            `[Build] Multiple loadParams provide key "${key}" — using first provider`
+          );
+        }
+      }
+    }
+  }
+  let result = parts[0].values;
+  for (let i = 1; i < parts.length; i++) {
+    const next = parts[i].values;
+    const combined = [];
+    for (const a of result) {
+      for (const b of next) {
+        combined.push({ ...a, ...b });
+      }
+    }
+    result = combined;
+  }
+  return result;
+}
+function paramsMatchInferred(params, inferredParams, optionalSegments) {
+  return Object.entries(inferredParams).every(([k, v]) => {
+    if (optionalSegments?.has(k)) return true;
+    return params[k] === v;
+  });
+}
+function computeSpecificity(route) {
+  const dynamicCount = (route.rawRoute.match(/\[/g) || []).length;
+  const inferredCount = route.inferredParams ? Object.keys(route.inferredParams).length : 0;
+  const unresolvedCount = Math.max(0, dynamicCount - inferredCount);
+  return 0 - unresolvedCount;
+}
+function buildUrl(route, params) {
+  return route.rawRoute.replace(/\[\[(\w+)\]\]/g, (_, name) => {
+    const value = params[name];
+    if (!value) return "";
+    if (route.inferredParams?.[name] === value) return "";
+    return value;
+  }).replace(/\[(\w+)\]/g, (_, name) => params[name] || "").replace(/\/\/+/g, "/").replace(/\/$/, "") || "/";
+}
+function materializeRouteParams(routes, loadParamsResults) {
+  const entries = [];
+  for (const route of routes) {
+    const specificity = computeSpecificity(route);
+    if (!route.hasDynamicParams) {
+      const params = route.inferredParams || {};
+      entries.push({ route, params, url: route.rawRoute, specificity });
+      continue;
+    }
+    const allParams = loadParamsResults.get(route) || [];
+    for (const params of allParams) {
+      if (route.inferredParams && !paramsMatchInferred(params, route.inferredParams, route.optionalSegments)) {
+        continue;
+      }
+      let mergedParams = params;
+      if (route.inferredParams) {
+        mergedParams = { ...params };
+        for (const [k, v] of Object.entries(route.inferredParams)) {
+          if (!(k in mergedParams)) {
+            mergedParams[k] = v;
+          }
+        }
+      }
+      const url = buildUrl(route, mergedParams);
+      entries.push({ route, params: mergedParams, url, specificity });
+    }
+  }
+  return entries;
+}
+function dedupeByUrl(entries) {
+  const logger = getLogger();
+  const byUrl = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const existing = byUrl.get(entry.url);
+    if (!existing) {
+      byUrl.set(entry.url, entry);
+    } else if (entry.specificity > existing.specificity) {
+      byUrl.set(entry.url, entry);
+    }
+  }
+  const deduped = [...byUrl.values()];
+  if (deduped.length < entries.length) {
+    logger.info(
+      `[Build] Deduplication: ${entries.length} materialized → ${deduped.length} unique URLs`
+    );
+  }
+  return deduped;
+}
 function hashParams(params, suffix) {
   const sorted = Object.keys(params).sort().reduce(
     (acc, key) => {
@@ -472,10 +568,11 @@ async function buildInstance(route, params, pageModule, ctx, routeServerElementP
   );
   await fs.writeFile(pagePartsConfigPath, JSON.stringify(config, null, 2));
   logger.info(`[Build] Page parts config: ${routeDir}/page-parts.json`);
+  const pageUrl = buildUrl(route, params);
   const slowPhase = new DevSlowlyChangingPhase();
   const slowResult = await slowPhase.runSlowlyForPage(
     params,
-    { params },
+    { language: "en", url: pageUrl },
     pageParts.parts,
     pageParts.discoveredInstances,
     pageParts.headlessInstanceComponents,
@@ -501,7 +598,7 @@ async function buildInstance(route, params, pageModule, ctx, routeServerElementP
       {
         pageViewState: slowViewState,
         pageParams: params,
-        pageProps: { language: "en", url: "" }
+        pageProps: { language: "en", url: pageUrl }
       }
     );
     if (slowResult2) {
@@ -764,7 +861,12 @@ async function compileServerElement(jayHtmlContent, jayHtmlFilename, jayHtmlDir,
     cssFile = cssFilename;
   }
   getLogger().info(`[Build] Compiled server element: ${path__default.basename(outputPath)}`);
-  return { cssFile, cssImports, headMeta: parsedJayFile.headMeta };
+  return {
+    cssFile,
+    cssImports,
+    headMeta: parsedJayFile.headMeta,
+    scripts: parsedJayFile.scripts
+  };
 }
 async function compileRouteServerElement(jayHtmlPath, outputPath, projectRoot, tsConfigFilePath, minifyCss = true) {
   const jayHtmlContent = await fs.readFile(jayHtmlPath, "utf-8");
@@ -974,102 +1076,6 @@ async function buildInstanceClient(hydrateEntryPath, instanceId, outputDir, proj
   logger.info(`[Build] Client bundle: ${result.jsFile}`);
   return result;
 }
-function crossProductParams(parts) {
-  if (parts.length === 0) return [];
-  if (parts.length === 1) return parts[0].values;
-  const logger = getLogger();
-  for (let i = 0; i < parts.length; i++) {
-    for (let j = i + 1; j < parts.length; j++) {
-      for (const key of parts[i].keys) {
-        if (parts[j].keys.has(key)) {
-          logger.warn(
-            `[Build] Multiple loadParams provide key "${key}" — using first provider`
-          );
-        }
-      }
-    }
-  }
-  let result = parts[0].values;
-  for (let i = 1; i < parts.length; i++) {
-    const next = parts[i].values;
-    const combined = [];
-    for (const a of result) {
-      for (const b of next) {
-        combined.push({ ...a, ...b });
-      }
-    }
-    result = combined;
-  }
-  return result;
-}
-function paramsMatchInferred(params, inferredParams, optionalSegments) {
-  return Object.entries(inferredParams).every(([k, v]) => {
-    if (optionalSegments?.has(k)) return true;
-    return params[k] === v;
-  });
-}
-function computeSpecificity(route) {
-  const dynamicCount = (route.rawRoute.match(/\[/g) || []).length;
-  const inferredCount = route.inferredParams ? Object.keys(route.inferredParams).length : 0;
-  const unresolvedCount = Math.max(0, dynamicCount - inferredCount);
-  return 0 - unresolvedCount;
-}
-function buildUrl(route, params) {
-  return route.rawRoute.replace(/\[\[(\w+)\]\]/g, (_, name) => {
-    const value = params[name];
-    if (!value) return "";
-    if (route.inferredParams?.[name] === value) return "";
-    return value;
-  }).replace(/\[(\w+)\]/g, (_, name) => params[name] || "").replace(/\/\/+/g, "/").replace(/\/$/, "") || "/";
-}
-function materializeRouteParams(routes, loadParamsResults) {
-  const entries = [];
-  for (const route of routes) {
-    const specificity = computeSpecificity(route);
-    if (!route.hasDynamicParams) {
-      const params = route.inferredParams || {};
-      entries.push({ route, params, url: route.rawRoute, specificity });
-      continue;
-    }
-    const allParams = loadParamsResults.get(route) || [];
-    for (const params of allParams) {
-      if (route.inferredParams && !paramsMatchInferred(params, route.inferredParams, route.optionalSegments)) {
-        continue;
-      }
-      let mergedParams = params;
-      if (route.inferredParams) {
-        mergedParams = { ...params };
-        for (const [k, v] of Object.entries(route.inferredParams)) {
-          if (!(k in mergedParams)) {
-            mergedParams[k] = v;
-          }
-        }
-      }
-      const url = buildUrl(route, mergedParams);
-      entries.push({ route, params: mergedParams, url, specificity });
-    }
-  }
-  return entries;
-}
-function dedupeByUrl(entries) {
-  const logger = getLogger();
-  const byUrl = /* @__PURE__ */ new Map();
-  for (const entry of entries) {
-    const existing = byUrl.get(entry.url);
-    if (!existing) {
-      byUrl.set(entry.url, entry);
-    } else if (entry.specificity > existing.specificity) {
-      byUrl.set(entry.url, entry);
-    }
-  }
-  const deduped = [...byUrl.values()];
-  if (deduped.length < entries.length) {
-    logger.info(
-      `[Build] Deduplication: ${entries.length} materialized → ${deduped.length} unique URLs`
-    );
-  }
-  return deduped;
-}
 async function discoverPluginClientPackages(projectRoot) {
   const projectRequire = createRequire(path__default.join(projectRoot, "package.json"));
   const seen = /* @__PURE__ */ new Set();
@@ -1404,6 +1410,9 @@ async function buildVersion(options) {
           entry.noIndex = true;
         }
       }
+      if (seResult.scripts?.length) {
+        entry.scripts = seResult.scripts;
+      }
       logger.important(`[Build] Route server element: ${routeDir}`);
     } catch (err) {
       logger.error(`[Build] Route server element FAILED ${route.rawRoute}: ${err.message}`);

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 = {
@@ -4745,6 +4746,428 @@ 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 {};
+  }
+}
+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;
+}
 async function findJayFiles(dir) {
   return await glob(`${dir}/**/*${JAY_EXTENSION$1}`);
 }
@@ -6235,6 +6658,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 +6703,89 @@ 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
+    })
+  );
+  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
+      })
+    );
+  }
+  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 +6793,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 +6820,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 +6996,22 @@ 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
   });
   printJayValidationResult(result, options);
   if (!result.valid) {
@@ -6574,7 +7158,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-BQbkAEhi.js");
   await buildVersion({
     version: ctx.version,
     projectRoot: ctx.resolvedPath,
@@ -7694,9 +8278,17 @@ 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*)"
+).action(async (options) => {
   try {
-    await runValidate(options.path, options);
+    await runValidate(options.path, { ...options, tier2: options.tier2 || options.t2 });
   } catch (error) {
     if (options.json) {
       getLogger().important(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/jay-stack-cli",
-  "version": "0.25.0",
+  "version": "0.25.1",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -25,17 +25,18 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.5.2",
-    "@jay-framework/compiler-inline-composition": "^0.25.0",
-    "@jay-framework/compiler-jay-html": "^0.25.0",
-    "@jay-framework/compiler-shared": "^0.25.0",
-    "@jay-framework/dev-server": "^0.25.0",
-    "@jay-framework/fullstack-component": "^0.25.0",
-    "@jay-framework/logger": "^0.25.0",
-    "@jay-framework/plugin-validator": "^0.25.0",
-    "@jay-framework/production-build": "^0.25.0",
-    "@jay-framework/production-server": "^0.25.0",
-    "@jay-framework/stack-server-build": "^0.25.0",
-    "@jay-framework/stack-server-runtime": "^0.25.0",
+    "@jay-framework/compiler-inline-composition": "^0.25.1",
+    "@jay-framework/compiler-jay-html": "^0.25.1",
+    "@jay-framework/compiler-shared": "^0.25.1",
+    "@jay-framework/dev-server": "^0.25.1",
+    "@jay-framework/fullstack-component": "^0.25.1",
+    "@jay-framework/logger": "^0.25.1",
+    "@jay-framework/plugin-validator": "^0.25.1",
+    "@jay-framework/production-build": "^0.25.1",
+    "@jay-framework/production-server": "^0.25.1",
+    "@jay-framework/stack-route-scanner": "^0.25.1",
+    "@jay-framework/stack-server-build": "^0.25.1",
+    "@jay-framework/stack-server-runtime": "^0.25.1",
     "chalk": "^4.1.2",
     "commander": "^14.0.0",
     "express": "^5.0.1",
@@ -46,7 +47,7 @@
     "yaml": "^2.3.4"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.25.0",
+    "@jay-framework/dev-environment": "^0.25.1",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.21",
     "nodemon": "^3.0.3",