@jay-framework/jay-stack-cli 0.25.4 → 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

@@ -35,24 +35,28 @@ When running `jay-stack-cli setup` without `--interactive`, plugins that need us
 
 ```yaml
 setup-needs-answer:
-  plugin: wix-server-client
-  key: api-key
+  plugin: '@jay-framework/some-plugin'
+  key: apiKey
   type: input
   message: 'Enter your API key'
+  choices: # present only for select-type questions
+    - us: United States
 ```
 
-To provide the answer, create a YAML file and re-run:
+To provide the answer, create a YAML file keyed by the `key` field and re-run:
 
 ```yaml
 # answers.yaml
-api-key: 'IST.abc123...'
+apiKey: 'your-answer'
 ```
 
 ```bash
 jay-stack-cli setup --answers answers.yaml
 ```
 
-Repeat until all plugins report `configured`. The flow is iterative — each run may reveal the next question.
+Repeat until all plugins report `configured`. The flow is iterative — each run may reveal the next question. The `key` is the stable join field between a question and its answer.
+
+> **Exception — Wix login is not answerable via a file.** The Wix plugins' credential setup shells out to the Wix CLI for a browser-based OAuth login (`npx @wix/cli login`). In non-interactive mode it reports `needs-config` ("requires interactive mode") rather than a `setup-needs-answer:` — there is no key you can put in `answers.yaml`. A human must run `jay-stack-cli setup --interactive` in a real terminal once; after that the app secret, client ID, and site ID are fetched/derived automatically. `wix-deploy` also needs a live Wix CLI session at deploy time (`jay-stack run wix-deploy/deploy`) — re-run `npx @wix/cli login` if it reports the session is missing.
 
 ### Setup order
 
@@ -64,11 +68,84 @@ jay-stack-cli agent-kit          # 2. Generate contracts and discovery data
 jay-stack-cli build              # 3. Production build
 ```
 
+## Running in cloud / remote environments
+
+Running the dev server behind a cloud preview proxy (sandboxes, Codespaces, Gitpod, etc.) has three
+non-obvious requirements.
+
+### 1. Allow the proxy's host (Vite host check)
+
+The dev server runs Vite in middleware mode, and Vite's host check 403s any request whose `Host` header
+isn't `localhost` ("Blocked request. This host is not allowed."). Allow the external host via `.jay`:
+
+```yaml
+# .jay
+devServer:
+  allowedHosts:
+    - .mysandbox.dev # Vite host-suffix syntax — matches any subdomain
+  # or, to disable the check entirely (dev only):
+  # allowedHosts: true
+```
+
+Platforms that already set Vite's `__VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS` env var (comma-separated
+hosts, or `true`) need **no** `.jay` change — the dev server reads and merges it. Do **not** add a
+`src/pages/vite.config.ts` to work around this; use the config above (DL#220).
+
+> HMR over a proxy may additionally need Vite's `server.hmr` client settings — not required for serving
+> pages, only for live reload through the proxy.
+
+### 2. Binding and port
+
+`jay-stack-cli dev` takes **no** `--port` / `--host` flags. The Express server binds all interfaces, so
+the container is reachable as-is; set the port in `.jay` (`devServer.portRange`, e.g. `[3000, 3000]` to
+pin it).
+
+### 3. Credentials are read from files, not env vars
+
+Plugins read credentials from files written by `setup`, not from `process.env`. Wix, for example, uses
+`config/.wix.yaml` (backend services) and `wix.config.json` (deploy target) — both gitignored. A
+container that only has secrets as env vars must **materialize them into those files before** starting
+the dev server (e.g. a startup script that writes `config/.wix.yaml` from `WIX_*` env vars). Putting
+`WIX_*` under a compose `environment:` block does **not** configure the plugins.
+
+### 4. AIditor (visual editor) in a container
+
+The `/aiditor` route runs an agent **server-side** via the Claude Agent SDK, so the environment running
+the dev server — not the user's laptop — must have Claude Code available:
+
+- **Install the `claude` CLI in the image.** It is not part of the Node base image.
+- **Provide `ANTHROPIC_API_KEY` as a secret/env var.** `claude login` is interactive and cannot complete
+  headless, so in a container the API key is the only viable auth. (Locally, `claude login` also works.)
+- **It's dev-only.** The `/aiditor` route is served by the dev server; it is excluded from production
+  deploy (`--exclude-plugins aiditor`). If you don't need visual editing in a given environment, you can
+  ignore it — the rest of the site scaffolds, builds, runs, and deploys without it; only the `/aiditor`
+  route's agent stays inert when the CLI/key are absent.
+
+A cloud platform that boots the dev server but neither installs the CLI nor injects the key will serve a
+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
+stop) — the sanctioned hooks for container healthchecks and lifecycle, instead of signal-guessing.
+
 ## 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: