@jay-framework/jay-stack-cli 0.25.5 → 0.26.0

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

@@ -15,7 +15,15 @@ return phaseOutput(
 );
 ```
 
-CarryForward is available in the next phase via `props.carryForward` but is not part of the ViewState.
+CarryForward is passed to the next phase as a **positional argument**, not a field on `props`,
+and is not part of the ViewState. The fast render receives it as its **second parameter**
+(before services): `withFastRender(async (props, carryForward, ...services) => …)`. The
+interactive phase receives it as its **fourth** parameter, after `props`, `refs` and the fast
+ViewState signals.
+
+For query-param pages, use this to precompute the no-params default in the slow phase and
+forward it to the fast phase instead of querying on every request — see
+[query-param-pages.md](query-param-pages.md).
 
 ### Response Headers (fast phase only)
 
@@ -31,6 +39,25 @@ return phaseOutput(
 
 Use this when the page renders per-user data that must not be cached by CDN or browser. Can be combined with `headTags` in the same options object.
 
+### Freshness — `ttl` and `grace` (slow phase only)
+
+A slow render runs at build time, so its data ages. Return `ttl` (and optionally `grace`) — both in **seconds** — to tell the production server when the data goes stale:
+
+```typescript
+return phaseOutput(
+  { name: product.name, price: product.price },
+  { productId: product.id },
+  { ttl: 300, grace: 6 * 60 * 60 }, // fresh for 5 minutes, usable for 6 hours
+);
+```
+
+- **`ttl`** — the data is `fresh` for `ttl` seconds after it was rendered. After that it is `stale`: the server serves it immediately (`Cache-Control: no-store`) and re-runs the slow render in the background. No `ttl` → the data never goes stale (today's behavior). Minimum effective `ttl` is 10 seconds.
+- **`grace`** — absolute age after which the data is `expired`: the server waits (up to `JAY_STALE_WAIT_MS`, default 2000) for the refresh before answering. Default `max(12h, ttl)`.
+- Responses carry `jay-freshness: fresh | stale | expired, <age>ms`.
+- A page with several slow parts (page, keyed headless components, headless instances) gets the **minimum positive** `ttl` and the minimum positive `grace` across all of them; `0` / `null` are ignored.
+- With `RenderPipeline`, return `ttl` / `grace` from the `toPhaseOutput` callback next to `viewState` and `carryForward`.
+- Pick a `ttl` that matches how quickly the underlying data changes, not how fast you want pages to be: every `ttl` expiry costs one slow render per instance.
+
 ### Cookies (fast phase only)
 
 The fast phase receives `props.cookies` — a `Record<string, string>` parsed from the HTTP `Cookie` header:

package/agent-kit-template/devops/INSTRUCTIONS.md

@@ -125,6 +125,16 @@ A cloud platform that boots the dev server but neither installs the CLI nor inje
 working site with a non-functional `/aiditor` — the single most common surprise. Install both, or
 document that visual editing is unavailable there.
 
+### Verbose diagnostics (`-v`)
+
+`jay-stack dev -v` (verbose) additionally **writes each rendered page's generated client HTML** to
+`<buildFolder>/debug/client-entry/<route>.html` (e.g. `build/dev/debug/client-entry/products-[slug].html`).
+This is a write-only debugging aid — inspect it when a page renders wrong, hydration mismatches, or a
+client bundle looks off; it mirrors exactly what the browser receives before Vite transforms it. It is
+**off by default** (no per-request disk writes in normal dev) and **best-effort** (a failed debug write
+never fails the page request). The filename is the route path only — the query string is dropped — so a
+proxy that carries a long auth token as a query param can't blow past the OS filename limit (DL#229).
+
 ### Health / shutdown (containers)
 
 Run with `--test-mode` to expose `GET /_jay/health` (readiness probe) and `POST /_jay/shutdown` (graceful
@@ -132,9 +142,10 @@ stop) — the sanctioned hooks for container healthchecks and lifecycle, instead
 
 ## Guides
 
-| File                                       | Topic                                                      |
-| ------------------------------------------ | ---------------------------------------------------------- |
-| [production-build.md](production-build.md) | Build pipeline, output structure, frontend/backend split   |
-| [serving-modes.md](serving-modes.md)       | Self-hosted, CDN, BaaS (fetch handler), CLI flags          |
-| [fetch-handler.md](fetch-handler.md)       | Fetch handler, ArtifactStore interface, BaaS custom stores |
-| [invalidation.md](invalidation.md)         | Rebuild, renderer server, cleanup                          |
+| File                                       | Topic                                                       |
+| ------------------------------------------ | ----------------------------------------------------------- |
+| [production-build.md](production-build.md) | Build pipeline, output structure, frontend/backend split    |
+| [serving-modes.md](serving-modes.md)       | Self-hosted, CDN, BaaS (fetch handler), CLI flags           |
+| [fetch-handler.md](fetch-handler.md)       | Fetch handler, ArtifactStore interface, BaaS custom stores  |
+| [invalidation.md](invalidation.md)         | Rebuild, renderer server, cleanup                           |
+| [source-editing.md](source-editing.md)     | Enable + use the source-editing inspector (AIditor, DL#219) |

package/agent-kit-template/devops/fetch-handler.md

@@ -106,9 +106,30 @@ interface ArtifactStore {
   loadModule(modulePath: string, local?: boolean): Promise<any>;
   getAssetPath(relativePath: string): string;
   getBuildDir(): string;
+
+  // Instances — the manifest holds routes only; the store owns the instance index
+  getInstance(
+    route: RouteEntry,
+    params: Record<string, string>,
+  ): Promise<InstanceEntry | undefined>;
+  listInstances(route: RouteEntry, options?: { fresh?: boolean }): AsyncIterable<InstanceRef>;
+
+  // Optional — implement to enable stale refresh and render-on-miss (omit for a read-only store)
+  writeCacheData?(
+    route: RouteEntry,
+    params: Record<string, string>,
+    entry: CacheEntry,
+  ): Promise<void>;
+  removeInstance?(route: RouteEntry, params: Record<string, string>): Promise<void>;
+  readCacheDataFresh?(relativePath: string): Promise<CacheEntry>;
 }
 ```
 
+- `readCacheData` must throw `CacheNotFoundError` (exported from `/serve`) when the instance has no data.
+- `getInstance` returns `undefined` only for a real "does not exist" — other errors must throw (they are not a 404).
+- `writeCacheData` upserts the data at the path derived by `deriveCachePath(route.pattern, params)` and keeps the index consistent (the item itself is the index entry). Race handling should be idempotent (adopt a concurrent winner), not a lock.
+- `listInstances` may serve a TTL-cached listing (`SwrCache`, default 10 minutes); `fresh: true` re-reads. Page through the backend's own page-size limit.
+
 `loadModule` handles all module loading — server elements, page components, headless components. The `local` flag indicates whether the path is relative to the build directory (`true`) or an npm package (`false`). For filesystem deployments, local modules resolve from `basePath` and npm modules use bare `import()`. BaaS implementations resolve all modules from their pre-bundled registry, ignoring the `local` flag.
 
 For serve-only imports (no build-time dependencies), use `@jay-framework/production-server/serve`.

package/agent-kit-template/devops/invalidation.md

@@ -29,7 +29,7 @@ jay-stack rebuild --route /products/[slug] --params '{"slug":"blue-widget"}'
 
 ### How it works
 
-1. Reads the route manifest to find affected routes/instances
+1. Reads the route manifest to find affected routes, and the artifact store's instance listing for their instances
 2. Re-runs slow render with fresh data
 3. Re-compiles server element and client bundle
 4. Updates the instance entry in the manifest
@@ -69,9 +69,4 @@ The manifest tracks which contracts each route uses. When a webhook says "produc
 
 ## Build Output After Rebuild
 
-Rebuilt instances write new files to both `frontend/` and `backend/`:
-
-- `backend/pre-rendered/` — updated jay-html, cache, server element
-- `frontend/pages/` — updated client bundle, CSS
-
-Old files are not deleted immediately — they're tracked in `cleanup-manifest.json`. This avoids breaking in-flight requests that still reference old bundles.
+A rebuilt instance overwrites its `backend/pre-rendered/{route}/page[_hash].cache.json` in place (atomically, at the same derived path), so no manifest update and no orphaned files are involved. Route-level bundles in `frontend/` are not rebuilt by an instance rebuild.

package/agent-kit-template/devops/production-build.md

@@ -34,7 +34,7 @@ build/v{n}/
 │           └── logo.png
 │
 ├── backend/                         # Server-only artifacts (→ container)
-│   ├── route-manifest.json          # All routes, instances, action registry
+│   ├── route-manifest.json          # Routes (no instances), action registry
 │   ├── build-metadata.json          # Version, timestamp, instance count
 │   ├── server/                      # Compiled server code
 │   │   ├── init.js
@@ -63,11 +63,16 @@ The build is **environment-agnostic**. The same output serves any deployment mod
 
 `backend/route-manifest.json` contains:
 
-- **routes** — pattern, segments, server module path, instances with params
-- **instances** — `preRenderedPath` and `serverElementPath` (relative to `backend/`), `clientBundlePath` and `clientCssPath` (relative to `frontend/`)
+- **routes** — pattern, segments, server module path, route-level `serverElementPath`, `routeClientBundlePath` and `routeCssPath`. The manifest holds **routes only** — it does not list instances.
 - **actions** — server module paths, action names
 - **sharedManifest** — maps package names to hashed filenames in `frontend/shared/`
 
+## Instances
+
+An instance (one set of route params) is identified by its data file, `backend/pre-rendered/{route}/page[_{hash}].cache.json`. The path is derived from the route pattern and the params (`_` + first 8 hex of the md5 of the sorted-params JSON), and the file carries `route`, `params` and the freshness fields (`renderedAt`, `ttl`, `grace`) itself — it is its own index entry.
+
+The `ArtifactStore` lists a route's instances (sitemap, llms.txt, rebuild) from those files, so new instances created after the build — by [render-on-miss](serving-modes.md#fresh-data-and-new-items) or a rebuild — appear without touching the manifest.
+
 ## Project Structure Requirements
 
 For production builds to work correctly:

package/agent-kit-template/devops/serving-modes.md

@@ -116,3 +116,28 @@ jay-stack serve --role renderer --port 4001
 ```
 
 The renderer server listens for data change webhooks and rebuilds affected page instances. The main server picks up the updated artifacts automatically (it re-reads the manifest when `build-metadata.json` changes).
+
+## Fresh Data and New Items
+
+The main server keeps slow-render data fresh and serves items that did not exist at build time. Each server instance does this independently against its own artifact store (a shared store, such as Wix's data collection, is refreshed once for everyone).
+
+**Stale-while-revalidate.** When slow render returns `ttl` / `grace` (seconds, see the developer `render-results.md` guide), the server classifies each instance as `fresh`, `stale` or `expired`:
+
+| State     | Served                                                                       | Headers                                                    |
+| --------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `fresh`   | Stored data; `max-age` / `s-maxage` clamped to the remaining TTL             | `jay-freshness: fresh, <age>ms`                            |
+| `stale`   | Stored data immediately, refresh runs in the background                      | `Cache-Control: no-store`, `jay-freshness: stale, <age>ms` |
+| `expired` | Waits up to `JAY_STALE_WAIT_MS` (2000) for the refresh, else the stored data | as `stale`, or `fresh` if the refresh finished             |
+
+Old data is never cached by CDNs (`no-store`) so a refresh becomes visible at once; validators (`ETag` gets `-<renderedAt>` appended, `Last-Modified`) are kept so crawlers and browsers can still revalidate cheaply.
+
+**Render on miss.** A URL that matches a route but has no instance (e.g. a product published after the build) is slow-rendered on the first request, stored, and served. If the slow render answers `notFound()` the request is a real 404 (remembered in memory for 10 minutes); if it cannot render right now the server answers `503` with `Retry-After: 2`.
+
+**Limits.** Concurrent requests for the same instance share one slow render. At most `JAY_SLOW_RENDER_CONCURRENCY` (default 5) slow renders run at once across refreshes and misses; there is no queue — a refresh that finds all slots busy serves the old data, a miss answers 503. A failed refresh backs off before retrying.
+
+| Variable                      | Default | Meaning                                                |
+| ----------------------------- | ------- | ------------------------------------------------------ |
+| `JAY_SLOW_RENDER_CONCURRENCY` | `5`     | Max concurrent slow renders (refresh + render-on-miss) |
+| `JAY_STALE_WAIT_MS`           | `2000`  | Max wait for the refresh of an `expired` instance      |
+| `JAY_MISS_TIMEOUT_MS`         | `8000`  | Max wait of a render-on-miss before 503                |
+| `JAY_FRESHNESS_HEADER`        | on      | Set to `off` to omit the `jay-freshness` header        |

package/agent-kit-template/devops/source-editing.md

@@ -0,0 +1,89 @@
+# Source Editing — DevOps / AIditor Integration Guide
+
+**Audience:** AIditor (or a similar visual editor) and the devops integrating it. How to turn on Jay's
+source-editing inspector and use it to map a rendered pixel back to its `.jay-html` source (DL#219).
+
+**This is dev-only.** The inspector is served only by the dev server, and only when enabled. It never
+affects a production build.
+
+---
+
+## 1. Enable it
+
+In the project's `.jay` file:
+
+```yaml
+devServer:
+  sourceEditing: true
+```
+
+When on, the dev server injects `jay-dev-*` markers into rendered pages (`jay-dev-src` line ranges on every
+element, `jay-dev-item` on `forEach` roots, `jay-dev-region*` on region roots). Off by default — the markers
+change rendered output, so enable only for source-editing sessions, never in production.
+
+## 2. Open a page in embed mode
+
+Load the page in an `<iframe>` with the `_jay_embed` query param:
+
+```
+http://localhost:<port>/<route>?_jay_embed
+```
+
+Embed mode registers the inspector's `message` listener (shared with the freeze protocol). The page posts
+`jay:route` to the parent on load.
+
+## 3. Ask "what is this?" — the postMessage protocol
+
+Send a point or a rectangle (iframe-relative CSS pixels); receive the resolved source location.
+
+```
+// parent → iframe
+{ type: 'jay:inspectPoint', requestId, x, y }
+{ type: 'jay:inspectRect',  requestId, x, y, width, height }
+
+// iframe → parent
+{ type: 'jay:inspectResult', requestId,
+  file,                 // project-relative page jay-html path (where the lines live)
+  route, routePattern,  // derive route params from these
+  node: {               // the element actually hit / chosen; null if nothing marked
+    lines: { from, to },    // 1-based line range in `file`
+    tag,                    // e.g. 'li', 'span'
+    html,                   // one-level HTML of the element (open tag + authored attrs + inline text;
+                            //   grandchildren elided) — the single content field
+    rect: { x, y, width, height },  // on-screen box, for overlaying a highlight
+    contentFromBinding?: true,      // set when the element is generated from a bound value (html-string)
+  } | null,
+  stack: [              // enclosing data scopes, innermost → outermost (plain wrappers omitted)
+    { kind: 'forEach', lines, itemId },        // itemId = runtime trackBy record id
+    { kind: 'region',  lines, name, props? },  // name = contract; props = static primitive props
+  ] }
+```
+
+**`inspectRect`** (drag selection) uses the rect rule: among marked elements the box encloses (overlap over
+the element's own area ≥ 0.8), the **largest** is chosen; if none, it falls back to the box center.
+
+## 4. Decide how to edit (the decision rule)
+
+- **Static content** (no `contentFromBinding`, not inside a region): the text/attribute is authored in the
+  jay-html — edit `file` at `node.lines`.
+- **Bound content** (`contentFromBinding`, or inside a `region`/`forEach` frame): the value comes from data,
+  not the markup. Read the binding at `node.lines` (e.g. `{post.content}`), then resolve its source:
+  - `stack` region frame → the `name` is the contract; map it via `agent-kit/plugins-index.yaml` to the
+    plugin's **editing guide** (see the plugin **source-editing** guide).
+  - `forEach` frame `itemId` identifies the record; route params (`route`/`routePattern`) identify the page
+    instance.
+  - Editing a bound value means editing its source (e.g. a markdown `.md` file, or a plugin's data via its
+    `devOnly` action), not the rendered markup.
+
+The inspector returns **locators, not resolved bindings** — it stays client-only, and the agent reads the
+jay-html + agent-kit to resolve. (The dev server does not resolve contracts; see DL#219 §2.)
+
+## 5. Try it
+
+The smoke-test example ships a live harness: run `yarn dev` in `examples/jay-stack/smoke-test` and open
+`http://localhost:3300/what-is-this.html` — hover/drag over any page and watch the `jay:inspectResult`.
+
+---
+
+See also: the developer **configuration** guide (the `.jay` `sourceEditing` field) and the plugin
+**source-editing** guide (making a plugin's contracts editable).

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

@@ -34,30 +34,31 @@ The plugin participates in four CLI commands, each running different hooks:
 
 ## Guides
 
-| File                                                   | Topic                                                                   |
-| ------------------------------------------------------ | ----------------------------------------------------------------------- |
-| [Contract Authoring Guide](../contracts/GUIDE.md)      | Writing contracts: syntax, page/component/linked contracts, examples    |
-| [contracts-guide.md](contracts-guide.md)               | Plugin-specific contract concerns                                       |
-| [plugin-structure.md](plugin-structure.md)             | plugin.yaml, package layout, exports                                    |
-| [component-structure.md](component-structure.md)       | makeJayStackComponent, builder API, three-phase rendering               |
-| [design-system-guide.md](design-system-guide.md)       | Shipping a template designers flatten; upgrades via `jay-stack sync`    |
-| [component-state.md](component-state.md)               | createSignal, createMemo, createEffect, createDerivedArray, createEvent |
-| [component-refs.md](component-refs.md)                 | Refs, collection refs, element types                                    |
-| [component-data.md](component-data.md)                 | Immutable data, JSON Patch, createPatchableSignal                       |
-| [component-context.md](component-context.md)           | Context hooks: provide, reactive, global                                |
-| [render-results.md](render-results.md)                 | phaseOutput, RenderPipeline, errors, redirects                          |
-| [actions-guide.md](actions-guide.md)                   | makeJayAction, makeJayQuery, .jay-action files                          |
-| [webhooks-guide.md](webhooks-guide.md)                 | makeWebhook, data change invalidation, renderer server                  |
-| [services-guide.md](services-guide.md)                 | createJayService, makeJayInit                                           |
-| [plugin-routes.md](plugin-routes.md)                   | Plugin-provided pages: routes, jay-html templates, page components      |
-| [seo-guide.md](seo-guide.md)                           | SEO head tags: title, meta, OG, canonical via phaseOutput               |
-| [commands-guide.md](commands-guide.md)                 | makeCliCommand, .jay-command files, CONSOLE_CONTEXT, jay-stack run      |
-| [validation.md](validation.md)                         | jay-stack validate-plugin, writing custom jay-html validators           |
-| [setup-guide.md](setup-guide.md)                       | Setup handlers, agent-kit handlers, references generation               |
-| [add-menu-guide.md](add-menu-guide.md)                 | AIditor add-menu items: schema, interaction, browse, presentation       |
-| [aiditor-settings-guide.md](aiditor-settings-guide.md) | AIditor Project settings tabs: template, materialization, devOnly route |
-| [dev-server-service.md](dev-server-service.md)         | Dev server service API: routes, params, freeze management               |
-| `../references/<plugin>/`                              | Plugin reference data                                                   |
+| File                                                   | Topic                                                                        |
+| ------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| [Contract Authoring Guide](../contracts/GUIDE.md)      | Writing contracts: syntax, page/component/linked contracts, examples         |
+| [contracts-guide.md](contracts-guide.md)               | Plugin-specific contract concerns; outcomes as variants, text as defaults    |
+| [plugin-structure.md](plugin-structure.md)             | plugin.yaml, package layout, exports                                         |
+| [component-structure.md](component-structure.md)       | makeJayStackComponent, builder API, three-phase rendering                    |
+| [design-system-guide.md](design-system-guide.md)       | Shipping a template designers flatten; upgrades via `jay-stack sync`         |
+| [component-state.md](component-state.md)               | createSignal, createMemo, createEffect, createDerivedArray, createEvent      |
+| [component-refs.md](component-refs.md)                 | Refs, collection refs, element types                                         |
+| [component-data.md](component-data.md)                 | Immutable data, JSON Patch, createPatchableSignal                            |
+| [component-context.md](component-context.md)           | Context hooks: provide, reactive, global                                     |
+| [render-results.md](render-results.md)                 | phaseOutput, RenderPipeline, errors, redirects                               |
+| [actions-guide.md](actions-guide.md)                   | makeJayAction, makeJayQuery, .jay-action files                               |
+| [webhooks-guide.md](webhooks-guide.md)                 | makeWebhook, data change invalidation, renderer server                       |
+| [services-guide.md](services-guide.md)                 | createJayService, makeJayInit                                                |
+| [plugin-routes.md](plugin-routes.md)                   | Plugin-provided pages: routes, jay-html templates, page components           |
+| [seo-guide.md](seo-guide.md)                           | SEO head tags: title, meta, OG, canonical via phaseOutput                    |
+| [commands-guide.md](commands-guide.md)                 | makeCliCommand, .jay-command files, CONSOLE_CONTEXT, jay-stack run           |
+| [validation.md](validation.md)                         | jay-stack validate-plugin, writing custom jay-html validators                |
+| [setup-guide.md](setup-guide.md)                       | Setup handlers, agent-kit handlers, references generation                    |
+| [add-menu-guide.md](add-menu-guide.md)                 | AIditor add-menu items: schema, interaction, browse, presentation            |
+| [aiditor-settings-guide.md](aiditor-settings-guide.md) | AIditor Project settings tabs: template, materialization, devOnly route      |
+| [source-editing.md](source-editing.md)                 | Make a plugin's contracts editable: editingGuide/readonly, coverage (DL#219) |
+| [dev-server-service.md](dev-server-service.md)         | Dev server service API: routes, params, freeze management                    |
+| `../references/<plugin>/`                              | Plugin reference data                                                        |
 
 ## Key Principles
 

package/agent-kit-template/plugin/actions-guide.md

@@ -49,6 +49,7 @@ makeJayAction('name')
   .withMethod('PUT') // Override HTTP method (default: POST for actions)
   .withCaching({ maxAge: 60 }) // Enable caching (queries only)
   .withFiles() // Accept file uploads (multipart/form-data)
+  .withRequest() // Receive the caller's cookies as argument 2 (see below)
   .withHandler(async (input, svc1, svc2) => {
     // Define handler
     return result;
@@ -133,6 +134,62 @@ refs.uploadBtn.onClick(async () => {
 });
 ```
 
+## .withRequest() — Reading the Caller's Cookies
+
+Opt in with `.withRequest()` and the handler receives an `ActionRequest` as its **second** argument, before the services:
+
+```typescript
+import { makeJayAction, ActionError } from '@jay-framework/fullstack-component';
+
+export const updateAccount = makeJayAction('account.update')
+  .withServices(ACCOUNT_SERVICE)
+  .withRequest()
+  .withHandler(async (input: { name: string }, request, account) => {
+    const session = request.cookies.session; // server-trusted, includes HttpOnly cookies
+    if (!session) throw new ActionError('UNAUTHORIZED', 'Not signed in');
+    return account.update(session, input.name);
+  });
+```
+
+Without `.withRequest()`, the handler is `(input, ...services)` as before. The client call is always `action(input)`.
+
+Rules:
+
+- **Identity comes from `request.cookies`, never from `input`.** Input is client-controlled and spoofable.
+- **No `.withCaching()`.** A cookie-reading handler is per-user. Combining both throws when the action is defined. Every response of a `.withRequest()` action is sent with `Cache-Control: private, no-store`.
+- **A GET query (`makeJayQuery`) must not mutate.** Only non-GET actions are protected by the same-origin check.
+- **Non-GET calls must come from the same origin.** A cross-site browser request (by `Sec-Fetch-Site`, or `Origin` when that header is absent) is rejected with 403 `CROSS_ORIGIN_REQUEST` before the handler runs. Jay's client always calls same-origin. Requests with neither header (server-to-server, curl) are allowed.
+- **Direct server-side calls get no cookies.** Calling a `.withRequest()` action directly (from another handler, a render phase, or the CLI) passes `{ cookies: {} }`. To act for the same caller, put the logic in a shared function and pass `request` to it explicitly.
+
+### Setting cookies (login, refresh, logout)
+
+Page JS cannot write an HttpOnly credential, so credential cookies are set by an action:
+
+```typescript
+export const login = makeJayAction('account.login')
+  .withServices(AUTH_SERVICE)
+  .withRequest()
+  .withHandler(async (input: { email: string; password: string }, request, auth) => {
+    const token = await auth.signIn(input.email, input.password);
+    request.setCookie('session', token, { maxAge: 60 * 60 * 24 * 30 });
+    return { ok: true };
+  });
+
+export const logout = makeJayAction('account.logout')
+  .withRequest()
+  .withHandler(async (input: {}, request) => {
+    request.clearCookie('session'); // same path/domain as when it was set
+    return { ok: true };
+  });
+```
+
+- **Defaults:** `httpOnly: true`, `sameSite: 'Lax'`, `path: '/'`, and `secure` when the request is https (including `x-forwarded-proto: https`). Options: `httpOnly`, `secure`, `sameSite` (`'Strict' | 'Lax' | 'None'`; `'None'` forces `secure`), `path`, `domain`, `maxAge` (seconds), `expires`.
+- **Cookies are sent only on success.** If the handler throws (including `ActionError`), cookies it set are discarded. To clear a cookie on failure, return a success value that says so.
+- **`clearCookie` must use the same `path` and `domain`** the cookie was set with, or the browser keeps the original.
+- Setting the same name twice keeps the last write. Cookie names must be RFC 6265 tokens.
+- **Streams cannot set cookies.** `makeJayStream(...).withRequest()` gives a read-only `StreamActionRequest` (`request.cookies` only), because headers are sent before the generator runs.
+- **Direct calls cannot set cookies.** There is no HTTP response; the cookie is discarded with a warning.
+
 ## ActionError
 
 Throw typed errors from action handlers:

package/agent-kit-template/plugin/contracts-guide.md

@@ -122,6 +122,48 @@ For dynamic/materialized contracts linking to static contracts in a plugin packa
 
 `trackBy` must reference a `data` tag with `string` or `number` type within the same sub-contract.
 
+## Outcomes and User-Visible Text
+
+The page owns every word the visitor reads. A plugin reports **what happened**; the page decides **how it reads** (wording, language, layout). So any outcome a page may want to render differently — an error, a failure kind, a success, an empty or unavailable state — must be a **variant**, never only a string.
+
+- **One kind of outcome** → a `boolean` variant (`hasError`, `isSubmitted`).
+- **Several kinds** → an `enum` variant with one member per kind the page may word differently, plus a neutral member (`NONE`, `IDLE`) for "nothing to report".
+- **Text is optional default copy.** A `data` string next to the variant (`errorMessage`, `statusMessage`) is fine as an English default. Never make it the only signal: a page must not have to test for a non-empty string, or match its text, to know what happened.
+- **Keep codes stable and locale-neutral.** Name members by meaning (`NETWORK`, `PERMISSION`), not by message. **Appending** a member is safe; inserting, renaming, removing, or reordering one is a breaking change.
+
+```yaml
+# ✅ Outcome as variants; text is a default the page may ignore
+- {
+    tag: submitState,
+    type: variant,
+    dataType: 'enum (IDLE | SUBMITTING | SUCCEEDED | FAILED)',
+    phase: fast+interactive,
+  }
+- {
+    tag: submitFailure,
+    type: variant,
+    dataType: 'enum (NONE | VALIDATION | REJECTED | NETWORK)',
+    phase: fast+interactive,
+  }
+- {
+    tag: statusMessage,
+    type: data,
+    dataType: string,
+    phase: fast+interactive,
+    description: English default text,
+  }
+
+# ❌ Outcome only as text — the page can't localize or redesign it without parsing English
+- { tag: statusMessage, type: data, dataType: string, phase: fast+interactive }
+```
+
+```html
+<!-- The page writes its own copy, in its own language -->
+<p if="form.submitFailure === NETWORK">Problème de connexion, réessayez.</p>
+```
+
+Emit enum values from the enum the contract compiles to (or a mirror of it in the same order); the runtime value is the member's index. Document each member's meaning in the plugin's agent-kit.
+
 ## Async Data
 
 Wrap any tag in `Promise<T>` with `async: true`:

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

@@ -31,6 +31,25 @@ return phaseOutput(
 
 Use this when the component renders per-user data that must not be cached by CDN or browser. Can be combined with `headTags` in the same options object.
 
+### Freshness — `ttl` and `grace` (slow phase only)
+
+A slow render runs at build time, so its data ages. Return `ttl` (and optionally `grace`) — both in **seconds** — to tell the production server when the data goes stale:
+
+```typescript
+return phaseOutput(
+  { name: product.name, price: product.price },
+  { productId: product.id },
+  { ttl: 300, grace: 6 * 60 * 60 }, // fresh for 5 minutes, usable for 6 hours
+);
+```
+
+- **`ttl`** — the data is `fresh` for `ttl` seconds after it was rendered. After that it is `stale`: the server serves it immediately (`Cache-Control: no-store`) and re-runs the slow render in the background. No `ttl` → the data never goes stale (today's behavior). Minimum effective `ttl` is 10 seconds.
+- **`grace`** — absolute age after which the data is `expired`: the server waits (up to `JAY_STALE_WAIT_MS`, default 2000) for the refresh before answering. Default `max(12h, ttl)`.
+- Responses carry `jay-freshness: fresh | stale | expired, <age>ms`.
+- A page with several slow parts (page, keyed headless components, headless instances) gets the **minimum positive** `ttl` and the minimum positive `grace` across all of them; `0` / `null` are ignored.
+- With `RenderPipeline`, return `ttl` / `grace` from the `toPhaseOutput` callback next to `viewState` and `carryForward`.
+- Pick a `ttl` that matches how quickly the underlying data changes, not how fast you want pages to be: every `ttl` expiry costs one slow render per instance.
+
 ### Cookies (fast phase only)
 
 The fast phase receives `props.cookies` — a `Record<string, string>` parsed from the HTTP `Cookie` header:

package/agent-kit-template/plugin/source-editing.md

@@ -0,0 +1,70 @@
+# Source Editing — Plugin Contributor Guide
+
+**Audience:** Plugin authors (and AI agents) making a plugin's contracts **editable at the source** (DL#219).
+
+**Related:** [actions-guide.md](actions-guide.md) (`devOnly` actions), [plugin-routes.md](plugin-routes.md)
+(`devOnly` routes), and the devops **source-editing** guide (the inspector protocol the AIditor uses).
+
+---
+
+## Why
+
+When a page binds content to your contract — e.g. `<h1>{productPage.productName}</h1>` — the source-editing
+inspector resolves that pixel to the contract, but it can't know **how** your data is edited: which record,
+what the write path is, or where an editor UI lives. Only your plugin knows. So each contract declares its
+**editing story**, and `jay-stack validate` warns when one is missing.
+
+## Declare the editing story (required for coverage)
+
+In `plugin.yaml`, each contract declares **one** of:
+
+```yaml
+contracts:
+  - name: product-page
+    contract: ./product-page.jay-contract
+    component: productPage
+    editingGuide: ./editing/product-page.md # how an agent edits this contract's bound data
+  - name: stock-badge
+    contract: ./stock-badge.jay-contract
+    component: stockBadge
+    readonly: true # this contract's data isn't editable in place
+```
+
+- **`editingGuide`** — relative path to a markdown guide shipped by the plugin.
+- **`readonly: true`** — the contract's data is derived/not editable in place (e.g. a computed badge).
+
+`jay-stack validate` emits a `source-editing-coverage` warning for any contract that declares neither (and
+checks the `editingGuide` file exists).
+
+## What the editing guide contains
+
+The guide is the **single entry point** an agent follows to edit content bound to your contract. It should tell
+the agent what to do with the identity the inspector provides:
+
+- The inspector's `stack` gives the **record identity** — a `forEach` frame's `itemId` (trackBy), a `region`
+  frame's static `props`, plus the page's route params (`route`/`routePattern`).
+- From that, instruct the agent to either:
+  - **Write the source** — call a `devOnly` action that persists the change (see actions-guide.md), or
+  - **Open an editor** — call a `devOnly` action that returns a URL and open it, or
+  - offer **several options** and let the agent choose.
+
+Action names are ordinary (nothing is reserved). Example mapping for a stores plugin:
+
+| Contract         | Record key (from inspect result) | Guide instructs                           |
+| ---------------- | -------------------------------- | ----------------------------------------- |
+| `product-page`   | `slug` (route param)             | `getEditUrl(slug)` → fetch slug→productId |
+| `product-search` | `productId` (`forEach` `itemId`) | `getEditUrl(productId)`                   |
+
+## Discovery
+
+`plugin.yaml` is the source of truth: an agent that resolves a region to your contract reads `editingGuide`
+from the plugin's `plugin.yaml` and then reads the guide file. Keep the guide concise and imperative — it is
+read by an agent at edit time. (Surfacing `editingGuide` into `agent-kit/plugins-index.yaml` alongside the
+contract entry, so it's one hop from the index, is a planned enhancement.)
+
+## Checklist
+
+1. Add `editingGuide:` (or `readonly: true`) to each contract in `plugin.yaml`.
+2. Write the guide at that path — the decision rule above: identity → write action / URL action.
+3. Expose the write/URL path as a `devOnly` action (actions-guide.md).
+4. Run `jay-stack validate` — resolve any `source-editing-coverage` warnings.

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

@@ -251,3 +251,39 @@ export const validate: JayHtmlValidatorFn = (ctx) => {
   return findings;
 };
 ```
+
+## Project-Level Validators (DL#232)
+
+A per-file validator sees one jay-html file at a time. A **project-level validator** runs **once per
+project** — for concerns that are not a single file: a config file, a `.well-known` file, a policy
+file, cross-file consistency. Declare them under `projectValidators` (same `./tools` handler rules as
+`validators`):
+
+```yaml
+projectValidators:
+  - name: seo-site
+    handler: validateProject # export name from the ./tools entry
+    description: robots.txt, site identity, and ARD checks
+```
+
+The handler receives only `{ projectRoot }` (and the plugin's own `settings`) — **not** parsed config
+or parsed jay-html. A validator that needs `.jay` config reads it itself via `projectRoot`:
+
+```typescript
+import type { ProjectValidatorFn, ProjectValidationFinding } from '@jay-framework/compiler-shared';
+
+export const validateProject: ProjectValidatorFn = async (ctx) => {
+  const findings: ProjectValidationFinding[] = [];
+  // ctx.projectRoot — absolute project root path
+  // ctx.settings    — the plugin's own settings (optional)
+  return findings;
+};
+```
+
+Each `ProjectValidationFinding` has `severity` (`'error'` | `'warning'`), `file` (project-relative,
+or `.jay`), `message`, and optional `suggestion`. Project validators run **after** the per-file pass
+and are **skipped under `--compile-only`**. Findings surface with `source: plugin:<plugin>/<name>`.
+
+Built-in example: `@jay-framework/seo-validator` ships a `seo-site` project validator (robots.txt,
+`site.baseUrl`, `site.name`, and ARD `/.well-known/ard.json`) — these moved out of core `validate`
+into the plugin via this hook (DL#232), so a project only gets them when it installs seo-validator.