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

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/INSTRUCTIONS.md

@@ -46,6 +46,7 @@ There is no standalone "interactive" phase. Any tag with `type: interactive` (re
 | [design-system-guide.md](design-system-guide.md)           | Design-system elements — **create** (author template + contract, `jay-content` slots) and **use** (flatten with `template=`, drift, `override` facets, `sync`) |
 | [jay-html-styling.md](jay-html-styling.md)                 | Styling: inline, external, dynamic style bindings, class bindings                                                                                              |
 | [routing.md](routing.md)                                   | Directory-based routing: page structure, dynamic routes, route priority                                                                                        |
+| [error-pages-guide.md](error-pages-guide.md)               | Error pages: reserved `404`/`5xx` status folders, the `error` headless, bindings, exact→family resolution                                                      |
 | [navigation-patterns.md](navigation-patterns.md)           | Active menu/sidebar patterns using `jay.url.path`, `===`, and `^=` operators                                                                                   |
 | [contracts-and-plugins.md](contracts-and-plugins.md)       | Reading contracts, plugin.yaml, .jay-action files, and the materialized indexes                                                                                |
 | [Contract Authoring Guide](../contracts/GUIDE.md)          | Writing contracts: syntax, page/component/linked contracts, examples                                                                                           |

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/error-pages-guide.md

@@ -0,0 +1,109 @@
+# Error Pages
+
+Error pages render your site's chrome when a request fails — a 404 for an unknown URL, a 5xx for a
+server error — instead of a bare plain-text message. You author them exactly like any other page,
+in a reserved top-level folder named for the HTTP status they cover.
+
+## Where they live
+
+Create error pages in `src/pages/` in a folder whose name is an HTTP **status token**:
+
+```
+src/pages/
+  404/page.jay-html      # exact: 404 Not Found
+  5xx/page.jay-html      # family: any 500–599
+  502/page.jay-html      # exact: 502 Bad Gateway (optional, overrides 5xx for 502)
+```
+
+A status token is either:
+
+- **Exact** — three digits, `100`–`599` (e.g. `404`, `502`).
+- **Family** — a leading digit then `xx` (e.g. `4xx`, `5xx`), covering that whole class.
+
+v1 renders only **4xx** and **5xx**. Reserve others with a folder, but they are not served yet.
+
+These folders are **not navigable routes** — visiting `/404` or `/5xx` directly returns a normal 404,
+and they never appear in the sitemap or internal-link checks. The error page is selected by the
+response **status**, not by its URL.
+
+## Resolution: exact → family → plain text
+
+For a given status, Jay picks the most specific page:
+
+1. **Exact** match — `pages/502/` for a 502.
+2. **Family** fallback — `pages/5xx/` for a 502 when there's no `pages/502/`.
+3. **Plain text** — if neither exists, a built-in plain-text response.
+
+So a single `pages/5xx/` covers every server error, and you add `pages/502/` only where you want
+bespoke copy. Minimum recommended set: **`404` and `5xx`** (the `validate` command warns if either is
+missing — see below).
+
+## Authoring an error page
+
+Import the built-in `error` headless contract and bind its fields. No plugin install is needed —
+`jay-stack`/`error` is built in:
+
+```html
+<html>
+  <head>
+    <script
+      type="application/jay-headless"
+      plugin="jay-stack"
+      contract="error"
+      key="error"
+    ></script>
+    <script type="application/jay-data">
+      data:
+    </script>
+    <title>{error.title}</title>
+    <meta name="description" content="{error.message}" />
+  </head>
+  <body>
+    <main class="error-page">
+      <h1>{error.status} — {error.title}</h1>
+      <p>{error.message}</p>
+      <ul forEach="error.details" trackBy="key">
+        <li>{key}: {value}</li>
+      </ul>
+      <a href="/">Go home</a>
+    </main>
+  </body>
+</html>
+```
+
+### Available bindings
+
+| Binding           | Type               | Meaning                                                   |
+| ----------------- | ------------------ | --------------------------------------------------------- |
+| `{error.status}`  | number             | The HTTP status (e.g. `404`, `503`).                      |
+| `{error.title}`   | string             | Short headline — supplied by logic or a sensible default. |
+| `{error.message}` | string             | Longer explanation — supplied or defaulted.               |
+| `{error.code}`    | string             | App-specific error code; `''` when none.                  |
+| `error.details`   | `{ key, value }[]` | Key/value pairs for `forEach` — empty when none.          |
+
+`error.title` and `error.message` always have a value: when the developer's code supplies none, Jay
+fills a per-status default (e.g. `404 → "Page Not Found"`). You can rely on them being present.
+
+## No fast/slow data phase
+
+An error page is a **pass-through** of the injected `error` data — it runs **no** author fast or slow
+phase and cannot fetch its own request-time data (rendering an error page must never itself fail). Its
+static chrome (layout, nav, copy) is still pre-rendered at build. Keep the page to static markup plus
+the `error.*` bindings.
+
+## Validation
+
+`jay-stack validate` warns when the minimum pages (`404` and `5xx`) are absent — a `4xx` family page
+counts as covering `404`. If your site intentionally accepts the plain-text fallback, suppress the
+nudge in `.jay`:
+
+```yaml
+validations:
+  allow-no-error-pages: true
+```
+
+## See also
+
+- Developer side — returning enriched errors (`notFound`, `serverError5xx`, title/details):
+  `../developer/error-pages-guide.md`.
+- Template syntax (`forEach`, bindings, expression limits): `jay-html-template-syntax.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/routing.md

@@ -39,6 +39,13 @@ Static routes match before dynamic routes (most specific first):
 3. **`[[param]]`** — optional param
 4. **`[...param]`** — catch-all — lowest priority
 
+## Reserved Status Folders (Error Pages)
+
+Top-level folders named for an HTTP **status token** — `404`, `5xx`, `502`, `4xx`, … — are reserved
+for **error pages**, not navigable routes. They are selected by response status (not URL), never
+appear in the sitemap, and visiting `/404` directly returns a normal 404. See
+[error-pages-guide.md](error-pages-guide.md).
+
 ## Static Route Overrides
 
 A static route can override a dynamic route for a specific URL — giving one particular page a custom layout while the dynamic route handles everything else:

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/agent-kit-template/developer/INSTRUCTIONS.md

@@ -35,6 +35,7 @@ The developer sets up the project, configures plugins, creates page-level compon
 | [component-refs.md](component-refs.md)                       | Refs, collection refs, element types                                                 |
 | [component-data.md](component-data.md)                       | Immutable data, JSON Patch, patching                                                 |
 | [render-results.md](render-results.md)                       | phaseOutput, RenderPipeline, errors, redirects                                       |
+| [error-pages-guide.md](error-pages-guide.md)                 | Returning enriched errors (title/code/details) and which error page renders          |
 | [seo-guide.md](seo-guide.md)                                 | SEO head tags: title, meta, OG, canonical via phaseOutput                            |
 | [cli-commands.md](cli-commands.md)                           | CLI commands: setup, validate, dev, agent-kit                                        |
 | `../references/<plugin>/`                                    | Plugin reference data                                                                |

package/agent-kit-template/developer/error-pages-guide.md

@@ -0,0 +1,86 @@
+# Error Pages (Developer Side)
+
+When a page or plugin render returns an error result, Jay renders the matching **error page** (see the
+designer guide for authoring them) with the error data injected as the `error` ViewState. This guide
+covers how to return enriched errors from `page.ts` so they surface well on the rendered page.
+
+## Returning errors
+
+Return an error result from any render phase to stop rendering and show an error page:
+
+```typescript
+import {
+  notFound,
+  badRequest,
+  unauthorized,
+  forbidden,
+  serverError5xx,
+  clientError4xx,
+} from '@jay-framework/fullstack-component';
+
+if (!product) return notFound('The product you are looking for may have been removed.');
+
+if (!input.query) return badRequest('Query is required');
+
+if (!session) return unauthorized('Please log in');
+
+if (!canAccess) return forbidden('Access denied');
+
+return clientError4xx(429, 'Rate limit exceeded');
+
+return serverError5xx(503, 'The inventory service is temporarily unavailable');
+```
+
+An **uncaught exception** in a render phase becomes a 500 and renders the `5xx` page — the stack is
+logged, never shown.
+
+## Enriching the error page
+
+Every error constructor takes an optional options bag after the message: `{ title?, code?, details? }`.
+These map directly onto the `error.*` bindings the error page can render.
+
+```typescript
+return notFound('The product you are looking for may have been removed.', {
+  title: 'Product not found',
+});
+// → error.title = "Product not found", error.message = "The product…"
+
+return serverError5xx(504, 'Upstream timed out', {
+  title: 'This is taking too long',
+  code: 'UPSTREAM_TIMEOUT',
+  details: { upstream: 'inventory-service', waitedMs: '10000' },
+});
+// → renders pages/504 if present, else pages/5xx;
+//   error.details lists the key/value pairs via forEach="error.details".
+```
+
+| Field     | Binding           | Notes                                                       |
+| --------- | ----------------- | ----------------------------------------------------------- |
+| status    | `{error.status}`  | The numeric status you pass (`notFound` → 404).             |
+| message   | `{error.message}` | First positional arg; defaulted per status when omitted.    |
+| `title`   | `{error.title}`   | Short headline; defaulted per status when omitted.          |
+| `code`    | `{error.code}`    | App-specific code; `''` on the page when omitted.           |
+| `details` | `error.details`   | `Record<string, unknown>` → stringified `{ key, value }[]`. |
+
+## Which page renders
+
+Resolution is by status, most specific first: exact (`pages/504/`) → family (`pages/5xx/`) → built-in
+plain text. So `serverError5xx(503, …)` renders `pages/503/` if it exists, otherwise `pages/5xx/`.
+`notFound(…)` renders `pages/404/`, or `pages/4xx/` as a family fallback.
+
+## RenderPipeline
+
+The pipeline factory methods mirror the constructors and accept the same options bag:
+
+```typescript
+const P = RenderPipeline.for<SlowViewState, CarryForward>();
+
+return P.try(() => db.getProduct(props.slug))
+  .map((product) => product ?? P.notFound('Product not found', { title: 'Product not found' }))
+  .toPhaseOutput((product) => ({ viewState: { title: product.name }, carryForward: {} }));
+```
+
+## See also
+
+- Full render-result reference (success, redirects, pipeline): `render-results.md`.
+- Authoring the error page markup and bindings: `../designer/error-pages-guide.md`.

package/agent-kit-template/developer/render-results.md

@@ -87,6 +87,22 @@ return clientError4xx(429, 'Rate limit exceeded');
 return serverError5xx(500, 'Database connection failed');
 ```
 
+Each error constructor takes an optional options bag — `{ title?, code?, details? }` — after the
+message. These surface as `error.title` / `error.code` / `error.details` on the error page:
+
+```typescript
+return notFound('This product may have been removed.', { title: 'Product not found' });
+
+return serverError5xx(504, 'Upstream timed out', {
+  title: 'This is taking too long',
+  details: { upstream: 'inventory-service', waitedMs: '10000' },
+});
+```
+
+The matching **error page** (`src/pages/404/`, `src/pages/5xx/`, …) renders these fields. See
+[error-pages-guide.md](error-pages-guide.md) for the full field reference and status resolution, and
+`../designer/error-pages-guide.md` for authoring the page markup.
+
 ## Redirects
 
 ```typescript

package/agent-kit-template/developer/seo-guide.md

@@ -53,10 +53,69 @@ interface HeadTag {
 // Canonical URL
 { tag: 'link', attrs: { rel: 'canonical', href: 'https://example.com/products/slug' } }
 
-// JSON-LD structured data
+// JSON-LD structured data — prefer the jsonLd() helper (see below) over hand-building this tag
 { tag: 'script', attrs: { type: 'application/ld+json' }, children: JSON.stringify(structuredData) }
 ```
 
+## Structured Data (JSON-LD)
+
+JSON-LD tells search engines and AI agents what a page _is_ (a product, article, recipe…). There are three ways to emit it — pick by where the data lives:
+
+| Where the data lives                        | How to emit                                                             | Who writes it       |
+| ------------------------------------------- | ----------------------------------------------------------------------- | ------------------- |
+| Site-wide identity (org name, logo, social) | `.jay` `site.*` config — auto-emitted as `Organization` + `WebSite`     | Developer (config)  |
+| Per-page dynamic data (product, article)    | `jsonLd(data)` from `page.ts`, returned in `headTags`                   | Developer (page.ts) |
+| Static, hand-authored for one page          | `<script type="application/ld+json">` directly in the jay-html `<head>` | Designer (jay-html) |
+
+### 1. Site-wide (`.jay` config)
+
+Set site identity once; the production build auto-emits `Organization` + `WebSite` JSON-LD into every page's `<head>`:
+
+```yaml
+# .jay
+site:
+  baseUrl: https://example.com # also drives sitemap.xml
+  name: Example Inc # required to emit Organization/WebSite JSON-LD
+  logo: /logo.png # relative paths are resolved against baseUrl
+  description: What we do
+  sameAs:
+    - https://twitter.com/example
+    - https://github.com/example
+```
+
+Without `site.name`, no site-level JSON-LD is emitted (validation warns). Site-level JSON-LD is a **production** artifact (like `sitemap.xml`) — the dev server does not inject it.
+
+### 2. Per-page (`jsonLd()` helper)
+
+Use the `jsonLd()` helper from `@jay-framework/fullstack-component` for dynamic, per-page structured data — it builds the correct `HeadTag` and the framework escapes it breakout-safe:
+
+```typescript
+import { jsonLd } from '@jay-framework/fullstack-component';
+
+return phaseOutput(viewState, carryForward, {
+  headTags: [
+    { tag: 'title', children: `${product.name} | Store` },
+    jsonLd({
+      '@context': 'https://schema.org',
+      '@type': 'Product',
+      name: product.name,
+      description: product.description,
+      offers: { '@type': 'Offer', price: product.price, priceCurrency: 'USD' },
+    }),
+  ],
+});
+```
+
+### 3. Static (jay-html `<head>`)
+
+A `<script type="application/ld+json">` written directly in a jay-html `<head>` is **first-class** — no `jay-script="allow"` needed, no inline-script warning. The body is emitted breakout-safe. See the designer SEO guide.
+
+### Validation
+
+- `jay-stack validate` errors if a template `application/ld+json` block is not valid JSON or is missing `@context`/`@type`.
+- `jay-stack validate` warns if `.jay` `site.name` is absent (no site-level JSON-LD).
+- Never HTML-escape a JSON-LD body yourself — the framework escapes `<`, `>`, `&` as `\uXXXX` so the JSON stays valid and cannot break out of the `<script>`.
+
 ## Mapping Generic SEO Data
 
 If the data source provides a generic structure (array of tags with type/props/children), map it:
@@ -91,3 +150,53 @@ return phaseOutput(viewState, carryForward, { headTags });
 
 - Head tags from components inside `forEach` are ignored
 - The framework handles HTML escaping automatically
+
+## Agent-Discovery Files (DL#214)
+
+A Jay production build emits the conventional files agents and crawlers look for. Most are generated from the route manifest + `.jay` `site` config — you mostly configure `site.*`; one file (`ard.json`) you author.
+
+### Generated automatically (override by placing your own file in `public/`)
+
+| File           | When generated                  | Source                                                                   |
+| -------------- | ------------------------------- | ------------------------------------------------------------------------ |
+| `/sitemap.xml` | `site.baseUrl` set              | route manifest                                                           |
+| `/llms.txt`    | `site.name` set                 | `site.name`/`site.description` + per-page `<title>`/`<meta description>` |
+| `/robots.txt`  | always (if you didn't ship one) | default allow-all + `Sitemap:` line when `site.baseUrl` set              |
+
+`llms.txt` is a markdown index of the site for LLMs: an H1 (`site.name`), a summary (`site.description`), and per-section links with each page's title + description. An author file at `public/llms.txt` / `public/robots.txt` always wins — the build never clobbers it.
+
+### `/.well-known/*` — just works in `public/`
+
+Drop any `.well-known` file (agent/tool manifests, `security.txt`, etc.) into `public/.well-known/` and it is served at `/.well-known/*` in **both** dev and production. (The dev server opts into serving dotdirs; production already did.)
+
+### `/.well-known/ard.json` — you author this
+
+Agentic Resource Discovery ([ARD v0.91](https://agenticresourcediscovery.org/spec)) lets agents discover a site's resources/APIs. The framework does **not** generate it — `jay-stack validate` warns when it's absent and validates its shape when present. Author `public/.well-known/ard.json`:
+
+```json
+{
+  "entries": [
+    {
+      "identifier": "urn:air:acme:weather:node",
+      "displayName": "Weather Data Node",
+      "type": "application/mcp-server-card+json",
+      "url": "https://api.acme.com/mcp/weather.json",
+      "representativeQueries": ["weather in Paris", "forecast for tomorrow"],
+      "description": "Live weather data and forecasts",
+      "tags": ["weather", "forecast"]
+    }
+  ]
+}
+```
+
+Each entry **requires**: `identifier` (URN `urn:air:<publisher>:<namespace>:<name>`), `displayName`, `type` (an IANA media type), and **exactly one** of `url` or `data`. `representativeQueries` (2–5) is strongly recommended — agents use it to find your resource. `ard.json` is pinned to v0.91 ("Proposal" status — expect the schema to move).
+
+**Predecessor alias:** ARD renamed `ai-catalog.json` → `ard.json`. For older clients, also write a copy at `public/.well-known/ai-catalog.json`. `ard.json` is canonical; validation warns if only the alias exists or the two differ.
+
+**No agent resources?** If the site exposes nothing agent-callable, suppress the presence nudge instead of authoring an empty file — add to `.jay` (it governs the project-level `ard.json`, so it lives in project config, not a page's `application/jay-validations` script):
+
+```yaml
+# .jay
+validations:
+  allow-no-ard: true
+```

package/agent-kit-template/plugin/validation.md

@@ -42,6 +42,15 @@ jay-stack validate-plugin -v
 - Contract files referenced in `plugin.yaml` exist
 - Component export names are valid strings (not file paths)
 - Action metadata files (`.jay-action`) exist
+- Each `routes[].jayHtml` file **parses and compiles** (same generate stage as `jay-stack validate` — catches invalid template expressions before the dev server)
+
+During plugin development, also compile-check **source** templates (paths under `lib/`, not only `dist/`):
+
+```bash
+jay-stack validate -p lib/pages/my-route --compile-only
+```
+
+`--compile-only` skips project rules (broken links, DOM lint, design system) so it is safe inside a plugin package `validate` script alongside `validate-plugin`.
 
 ### Capability-aware structure