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

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/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/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/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