npm - @jay-framework/jay-stack-cli - Versions diffs - 0.17.3 → 0.18.0 - Mend

@jay-framework/jay-stack-cli 0.17.3 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (23) hide show

package/agent-kit-template/designer/jay-html-components.md +2 -0
package/agent-kit-template/designer/jay-html-syntax.md +1 -1
package/agent-kit-template/designer/project-structure.md +5 -0
package/agent-kit-template/developer/cli-commands.md +5 -1
package/agent-kit-template/developer/component-refs.md +7 -3
package/agent-kit-template/developer/project-structure.md +5 -0
package/agent-kit-template/developer/render-results.md +37 -0
package/agent-kit-template/developer/routing.md +25 -0
package/agent-kit-template/devops/INSTRUCTIONS.md +24 -0
package/agent-kit-template/devops/fetch-handler.md +185 -0
package/agent-kit-template/devops/invalidation.md +77 -0
package/agent-kit-template/devops/production-build.md +80 -0
package/agent-kit-template/devops/serving-modes.md +118 -0
package/agent-kit-template/plugin/INSTRUCTIONS.md +2 -0
package/agent-kit-template/plugin/actions-guide.md +2 -10
package/agent-kit-template/plugin/commands-guide.md +121 -0
package/agent-kit-template/plugin/component-refs.md +7 -3
package/agent-kit-template/plugin/component-structure.md +26 -2
package/agent-kit-template/plugin/plugin-structure.md +27 -0
package/agent-kit-template/plugin/render-results.md +37 -0
package/agent-kit-template/plugin/webhooks-guide.md +124 -0
package/dist/index.js +732 -456
package/package.json +11 -11

package/agent-kit-template/designer/jay-html-components.md CHANGED Viewed

@@ -89,6 +89,8 @@ Inside `<jay:...>`, bindings resolve to **that instance's** contract tags (not t
 Headfull components own their UI and can be made full-stack by adding a `contract` attribute.
+Headfull FS components must be placed in `src/components/` — each component in its own subdirectory with `.ts`, `.jay-html`, and `.jay-contract` files. The production build only discovers server-side component modules from `src/components/` and `src/plugins/`. Placing them inside page directories will work in dev mode but fail in production.
 ### Import Declaration
 ```html

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

@@ -14,7 +14,7 @@ Entry point at `src/pages/`. Can import all component types.
 ### Headfull FS
-Reusable component with its own template + contract + three-phase rendering (slow/fast/interactive). Lives alongside the page in a components directory. Can nest other headfull FS and instance headless in its own `<head>`. Cannot use keyed headless.
+Reusable component with its own template + contract + three-phase rendering (slow/fast/interactive). Must live in `src/components/` (not inside page directories) so the production build can discover and compile them. Can nest other headfull FS and instance headless in its own `<head>`. Cannot use keyed headless.
 ### Headless

package/agent-kit-template/designer/project-structure.md CHANGED Viewed

@@ -14,6 +14,11 @@ my-project/
 │   ├── project.conf.yaml       # Project metadata (name, etc.)
 │   └── <plugin-name>.yaml      # Plugin-specific config files
 ├── src/
+│   ├── components/              # Headfull full-stack components (shared across pages)
+│   │   └── site-header/
+│   │       ├── site-header.ts
+│   │       ├── site-header.jay-html
+│   │       └── site-header.jay-contract
 │   ├── pages/                   # Pages (directory-based routing)
 │   │   ├── page.jay-html        # Homepage → /
 │   │   ├── page.jay-contract    # Homepage contract (optional)

package/agent-kit-template/developer/cli-commands.md CHANGED Viewed

@@ -64,7 +64,7 @@ Validate all `.jay-html` and `.jay-contract` files.
 jay-stack validate
 # Validate a specific path
-jay-stack validate src/pages/products/
+jay-stack validate -p src/pages/products/
 # Verbose (per-file status)
 jay-stack validate -v
@@ -167,6 +167,10 @@ If not found, lists available actions:
    Available actions: searchProducts, getProductBySlug, getCategories
 ```
+## Production Commands
+For `jay-stack build`, `jay-stack serve`, and `jay-stack rebuild`, see the [DevOps guides](../devops/INSTRUCTIONS.md).
 ## jay-stack dev
 Start the development server.

package/agent-kit-template/developer/component-refs.md CHANGED Viewed

@@ -31,9 +31,13 @@ refs.submitButton.onClick(() => {
   /* ... */
 });
-// exec$ gives direct access to the element and current ViewState
-refs.submitButton.exec$((element, viewState) => {
-  element.disabled = viewState.isSubmitting;
+// exec$ gives direct access to the element and current ViewState.
+// Only use exec$ inside event handlers — never at top-level component
+// creation or in effects, because elements don't exist yet at that point.
+refs.submitButton.onclick(() => {
+  refs.submitButton.exec$((element, viewState) => {
+    element.disabled = viewState.isSubmitting;
+  });
 });
 ```

package/agent-kit-template/developer/project-structure.md CHANGED Viewed

@@ -14,6 +14,11 @@ my-project/
 │   ├── project.conf.yaml       # Project metadata (name, etc.)
 │   └── <plugin-name>.yaml      # Plugin-specific config files
 ├── src/
+│   ├── components/              # Headfull full-stack components (shared across pages)
+│   │   └── site-header/
+│   │       ├── site-header.ts
+│   │       ├── site-header.jay-html
+│   │       └── site-header.jay-contract
 │   ├── pages/                   # Pages (directory-based routing)
 │   │   ├── page.jay-html        # Homepage → /
 │   │   ├── page.jay-contract    # Homepage contract (optional)

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

@@ -17,6 +17,43 @@ return phaseOutput(
 CarryForward is available in the next phase via `props.carryForward` but is not part of the ViewState.
+### Response Headers (fast phase only)
+The third parameter accepts `responseHeaders` to set HTTP headers on the page response:
+```typescript
+return phaseOutput(
+  { memberName: member.name },
+  {},
+  { responseHeaders: { 'Cache-Control': 'no-store' } },
+);
+```
+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.
+### Cookies (fast phase only)
+The fast phase receives `props.cookies` — a `Record<string, string>` parsed from the HTTP `Cookie` header:
+```typescript
+.withFastRender(async (props, memberService) => {
+    const token = props.cookies['session-token'];
+    if (!token) return redirect3xx(302, '/login');
+    const member = await memberService.validate(token);
+    if (!member) return redirect3xx(302, '/login');
+    return phaseOutput(
+        { memberName: member.name },
+        {},
+        { responseHeaders: { 'Cache-Control': 'no-store' } },
+    );
+})
+```
+- `props.cookies` is `Record<string, string>` — empty `{}` when no cookies
+- Not available in the slow phase (compile error) — same as `props.query`
 ## Error Results
 Return errors to stop rendering and show an error page:

package/agent-kit-template/developer/routing.md CHANGED Viewed

@@ -160,6 +160,31 @@ URL query parameters (`?page=2&sort=price`) are available in the **fast render p
 - Not available in the slow phase (compile error) — slow results are cached by path params only
 - In the interactive phase, use `new URLSearchParams(window.location.search)` directly
+## Cookies
+HTTP cookies are available in the **fast render phase only** via `props.cookies`:
+```typescript
+.withFastRender(async (props, carryForward, memberService) => {
+    const token = props.cookies['session-token'];
+    if (!token) return redirect3xx(302, '/login');
+    const member = await memberService.validate(token);
+    if (!member) return redirect3xx(302, '/login');
+    return phaseOutput(
+        { memberName: member.name },
+        {},
+        { responseHeaders: { 'Cache-Control': 'no-store' } },
+    );
+})
+```
+- `props.cookies` is `Record<string, string>` — empty `{}` when no cookies
+- Not available in the slow phase (compile error) — same as query params
+- In the interactive phase, use `document.cookie` directly
+- To set response headers (e.g. `Cache-Control: no-store`), use `responseHeaders` in `phaseOutput()` options
 ## Plugin Routes
 Plugins can provide their own pages via `routes` in `plugin.yaml`. These are backoffice tools, admin dashboards, or editors with boxed designs that don't need per-site customization.

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

@@ -0,0 +1,24 @@
+# Jay Stack DevOps — Agent Kit
+This folder contains guides for building, deploying, and operating jay-stack projects in production.
+## What Does the DevOps Role Do?
+The devops role handles the production lifecycle: building artifacts, configuring deployment environments, serving in different modes (self-hosted, CDN, BaaS), and managing content invalidation. This is distinct from the developer role (creates page logic), designer role (creates UI), and plugin role (creates headless components).
+## Workflow
+1. **Build** — `jay-stack build` to compile all pages into production artifacts
+2. **Deploy** — upload `frontend/` to CDN, deploy `backend/` to server container. Plugins can provide deploy commands via `jay-stack run <plugin>/deploy`
+3. **Serve** — start the production server with environment-appropriate flags
+4. **Invalidate** — rebuild specific pages when data changes
+5. **Admin** — run plugin CLI commands via `jay-stack run <plugin>/<command>` (media upload, data sync, cache purge)
+## 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                          |

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

@@ -0,0 +1,185 @@
+# Fetch Handler Package
+## Overview
+`@jay-framework/jay-fetch-handler` exports a standard `(Request) → Response` function for BaaS platforms (Wix, Cloudflare Workers) where an HTTP server is not needed — the platform provides the HTTP layer and calls the fetch function directly.
+## Installation
+```bash
+npm install @jay-framework/jay-fetch-handler
+```
+## API
+```typescript
+import { createJayFetchHandler } from '@jay-framework/jay-fetch-handler';
+const handler = createJayFetchHandler(options);
+// handler: (request: Request) => Promise<Response>
+```
+### Options
+```typescript
+interface JayFetchHandlerOptions {
+  // Artifact source (one required)
+  backendDir?: string; // Path to build/v{n}/backend/ (creates FilesystemArtifactStore)
+  artifactStore?: ArtifactStore; // Custom store for non-filesystem backends (DL#143)
+  staticBaseUrl?: string; // Base URL for browser assets (default: '/')
+  frontendDir?: string; // When set, serves static files from this directory
+  // Pre-imported modules — for bundled entry.mjs (DL#143)
+  plugins?: PreImportedPlugin[];
+  actionModules?: Array<{ module: Record<string, unknown>; name: string }>;
+}
+```
+| Option          | Required | Description                                                                                                                          |
+| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `backendDir`    | \*       | Path to the backend build directory. Creates a `FilesystemArtifactStore` internally                                                  |
+| `artifactStore` | \*       | Custom `ArtifactStore` implementation (e.g., cloud storage). Use instead of `backendDir`                                             |
+| `staticBaseUrl` | No       | URL prefix for import maps, CSS links, and client bundles. Set to your CDN URL for external hosting. Default: `/`                    |
+| `frontendDir`   | No       | When provided, the handler serves static files from this directory. Omit for CDN deployments where static files are hosted elsewhere |
+| `plugins`       | No       | Pre-imported plugin init modules. Bypasses filesystem discovery — use for bundled deployments                                        |
+| `actionModules` | No       | Pre-imported action modules. Bypasses filesystem discovery — use for bundled deployments                                             |
+\* One of `backendDir` or `artifactStore` is required.
+## Usage — Self-Hosted
+```typescript
+import { createJayFetchHandler } from '@jay-framework/jay-fetch-handler';
+const handler = createJayFetchHandler({
+  backendDir: './build/v1/backend',
+  staticBaseUrl: '/',
+  frontendDir: './build/v1/frontend',
+});
+```
+## Usage — CDN Mode
+```typescript
+const handler = createJayFetchHandler({
+  backendDir: './build/v1/backend',
+  staticBaseUrl: 'https://static.parastorage.com/services/my-app/1.0.0/',
+});
+export default { fetch: handler };
+```
+The BaaS runtime calls `handler(request)` for each incoming HTTP request.
+## Usage — BaaS with Custom Artifact Store
+For deployments where backend files are not on the local filesystem (e.g., stored in a cloud database), provide a custom `ArtifactStore` and pre-imported modules:
+```typescript
+import { createJayFetchHandler } from '@jay-framework/jay-fetch-handler';
+import { WixDataArtifactStore } from '@jay-framework/wix-baas-adapter';
+import { init as wixStoresInit } from '@jay-framework/wix-stores';
+import * as wixStoresModule from '@jay-framework/wix-stores';
+const handler = createJayFetchHandler({
+  artifactStore: new WixDataArtifactStore({
+    collectionId: 'jay-backend-files',
+    cacheDir: '/tmp/jay-backend',
+  }),
+  staticBaseUrl: 'https://static.parastorage.com/services/my-app/1.0.0/',
+  plugins: [{ name: 'wix-stores', init: wixStoresInit }],
+  actionModules: [{ module: wixStoresModule, name: 'wix-stores' }],
+});
+export default { fetch: handler };
+```
+The `ArtifactStore` interface:
+```typescript
+interface ArtifactStore {
+  readManifest(): Promise<RouteManifest>;
+  readCacheData(relativePath: string): Promise<CacheEntry>;
+  readPagePartsConfig(relativePath: string): Promise<any>;
+  loadServerElement(relativePath: string): Promise<ServerElementModule>;
+  loadModule(modulePath: string, local?: boolean): Promise<any>;
+  getAssetPath(relativePath: string): string;
+  getBuildDir(): string;
+}
+```
+`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`.
+## Usage — Cloudflare Workers
+```typescript
+import { createJayFetchHandler } from '@jay-framework/jay-fetch-handler';
+const handler = createJayFetchHandler({
+  backendDir: './backend',
+  staticBaseUrl: 'https://cdn.example.com/assets/',
+});
+export default { fetch: handler };
+```
+## Usage — Standalone with HTTP Server
+```typescript
+import { createJayFetchHandler } from '@jay-framework/jay-fetch-handler';
+import http from 'node:http';
+import { Readable } from 'node:stream';
+const handler = createJayFetchHandler({
+  backendDir: './build/v1/backend',
+  staticBaseUrl: '/',
+  frontendDir: './build/v1/frontend',
+});
+http
+  .createServer(async (req, res) => {
+    const url = new URL(req.url, `http://${req.headers.host}`);
+    const headers = new Headers();
+    for (const [k, v] of Object.entries(req.headers)) {
+      if (v) headers.set(k, Array.isArray(v) ? v.join(', ') : v);
+    }
+    const init: RequestInit = { method: req.method, headers };
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+      init.body = Readable.toWeb(req) as ReadableStream;
+      (init as any).duplex = 'half';
+    }
+    const request = new Request(url, init);
+    const response = await handler(request);
+    const resHeaders: Record<string, string> = {};
+    response.headers.forEach((v, k) => {
+      resHeaders[k] = v;
+    });
+    res.writeHead(response.status, resHeaders);
+    if (response.body) {
+      const reader = response.body.getReader();
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        res.write(value);
+      }
+    }
+    res.end();
+  })
+  .listen(4000);
+```
+This is what `jay-stack serve` does internally. Use the CLI for standard deployments; use the handler directly when you need custom server logic.
+## Behavior
+The handler processes requests in this order:
+1. **Actions** — `/_jay/actions/*` routes to the action registry
+2. **Static files** — if `frontendDir` is set, checks `frontend/`, then `frontend/public/`
+3. **Page requests** — matches against the route manifest, runs fast-phase SSR, streams HTML
+Initialization (loading manifest, running `init.ts`, registering actions) happens lazily on the first request.

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

@@ -0,0 +1,77 @@
+# Invalidation & Rebuild
+## When to Rebuild
+Page instances are pre-rendered at build time with slow-phase data. When that data changes (product updated, content edited), the affected instances need to be rebuilt without a full build.
+## jay-stack rebuild
+Three targeting modes:
+```bash
+# By contract — rebuild all routes using this contract
+jay-stack rebuild --contract product-page
+# By route — rebuild all instances of a route pattern
+jay-stack rebuild --route /products/[slug]
+# By URL — resolve to route+params, rebuild that one instance
+jay-stack rebuild --url /products/blue-widget
+```
+Narrow it down with `--params`:
+```bash
+# Rebuild one specific instance
+jay-stack rebuild --contract product-page --params '{"slug":"blue-widget"}'
+jay-stack rebuild --route /products/[slug] --params '{"slug":"blue-widget"}'
+```
+### How it works
+1. Reads the route manifest to find affected routes/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
+5. Touches `build-metadata.json` to trigger main server manifest reload
+6. Old files are tracked in `cleanup-manifest.json` for later cleanup
+### Cleanup
+After rebuilds, orphaned files (old client bundles, old server elements) accumulate. Clean them up:
+```bash
+jay-stack cleanup
+```
+## Renderer Server
+For automated invalidation, run the renderer server alongside the main server:
+```bash
+# Main server — pages and actions
+jay-stack serve --role main --port 4000
+# Renderer server — listens for webhooks, triggers rebuilds
+jay-stack serve --role renderer --port 4001
+```
+The renderer server:
+- Listens for data change webhooks from external systems (CMS, e-commerce)
+- Determines which routes are affected (via contract name → route resolution)
+- Runs `rebuild` for each affected instance
+- The main server detects the updated `build-metadata.json` and reloads the manifest
+### Contract-based resolution
+The manifest tracks which contracts each route uses. When a webhook says "product-page data changed", the renderer finds all routes that use the `product-page` contract and rebuilds their instances.
+## 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.

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

@@ -0,0 +1,80 @@
+# Production Build
+## Building
+```bash
+jay-stack build
+jay-stack build --version 2
+jay-stack build --no-minify    # debugging
+jay-stack build -v             # verbose output
+```
+Version defaults to the `version` field in `package.json` (e.g., `"1.2.3"` → build version `10203`). Override with `--version`.
+## Build Output Structure
+The build produces two directories under `build/v{n}/`:
+```
+build/v{n}/
+├── frontend/                        # Browser-facing assets (→ CDN or static serving)
+│   ├── shared/                      # Framework + plugin client chunks
+│   │   ├── runtime-{hash}.js
+│   │   ├── component-{hash}.js
+│   │   └── shared-manifest.json
+│   ├── pages/                       # Per-page client bundles + CSS
+│   │   ├── index/
+│   │   │   ├── page-{hash}.js
+│   │   │   └── page.css
+│   │   └── products/[slug]/
+│   │       ├── page_{hash}-{hash}.js
+│   │       └── page_{hash}.css
+│   └── public/                      # Copied from project ./public
+│       └── images/
+│           └── logo.png
+│
+├── backend/                         # Server-only artifacts (→ container)
+│   ├── route-manifest.json          # All routes, instances, action registry
+│   ├── build-metadata.json          # Version, timestamp, instance count
+│   ├── server/                      # Compiled server code
+│   │   ├── init.js
+│   │   ├── pages/{route}/page.js
+│   │   ├── components/{name}/{name}.js
+│   │   ├── plugins/{name}/{name}.js
+│   │   └── actions/{name}.actions.js
+│   └── pre-rendered/                # SSR artifacts per instance
+│       └── {route}/
+│           ├── page.jay-html            # Pre-rendered HTML template
+│           ├── page.cache.json          # Slow ViewState + carryForward
+│           ├── page.server-element.js   # Streaming SSR module
+│           └── page-parts.json          # Component wiring config
+```
+## Frontend vs Backend
+| Directory   | Contains                                                                   | Deploy to                 |
+| ----------- | -------------------------------------------------------------------------- | ------------------------- |
+| `frontend/` | JS bundles, CSS, images — everything the browser loads                     | CDN or static file server |
+| `backend/`  | Server modules, pre-rendered HTML, manifests — everything the server reads | Container / server        |
+The build is **environment-agnostic**. The same output serves any deployment mode. `staticBaseUrl` (where browser assets are hosted) is a serve-time parameter, not baked into the build.
+## Manifest
+`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/`)
+- **actions** — server module paths, action names
+- **sharedManifest** — maps package names to hashed filenames in `frontend/shared/`
+## Project Structure Requirements
+For production builds to work correctly:
+- **Headfull FS components** must be in `src/components/` (not inside page directories)
+- **Headless plugins** must be in `src/plugins/`
+- **Actions** must be in `src/actions/` with `*.actions.ts` naming
+- **Init** must be at `src/init.ts`
+The build discovers server-side modules from `src/pages/`, `src/components/`, `src/plugins/`, and `src/actions/`. Files outside these directories are not compiled for server use.

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

@@ -0,0 +1,118 @@
+# Serving Modes
+## Overview
+The production server supports three deployment modes, all using the same build output:
+| Mode             | Static files                   | Server                                                      | Use case                             |
+| ---------------- | ------------------------------ | ----------------------------------------------------------- | ------------------------------------ |
+| **Self-hosted**  | Server serves from `frontend/` | `jay-stack serve`                                           | Local testing, standalone deployment |
+| **CDN**          | Uploaded to external CDN       | `jay-stack serve --static-base-url <url> --no-serve-static` | Production with CDN                  |
+| **BaaS (fetch)** | Uploaded to CDN                | `createJayFetchHandler()`                                   | Wix, Cloudflare Workers              |
+## Self-Hosted (Default)
+The server serves both pages and static files. No external CDN needed.
+```bash
+jay-stack build
+jay-stack serve --port 4000
+```
+Static files are served from `build/v{n}/frontend/` at these URL prefixes:
+- `/shared/` — framework client chunks
+- `/pages/` — per-page client bundles and CSS
+- `/` — public folder assets (images, fonts, JSON)
+## CDN Mode
+Static files are hosted on an external CDN. The server only handles page requests and actions.
+```bash
+jay-stack build
+# Upload frontend/ to CDN
+# e.g., aws s3 sync build/v1/frontend/ s3://my-bucket/app/1.0.0/
+# Start server with CDN URL
+jay-stack serve --port 4000 \
+  --static-base-url https://cdn.example.com/app/1.0.0/ \
+  --no-serve-static
+```
+The server generates import maps, CSS links, and client bundle URLs prefixed with `--static-base-url`. It does not serve static files itself.
+## BaaS Mode (Custom Artifact Store)
+For platforms where backend files are not on the local filesystem (e.g., stored in a cloud database), use `createJayFetchHandler` with a custom `ArtifactStore` and pre-imported modules:
+```typescript
+import { createJayFetchHandler } from '@jay-framework/jay-fetch-handler';
+const handler = createJayFetchHandler({
+  artifactStore: customStore, // Custom ArtifactStore implementation
+  staticBaseUrl: 'https://cdn.example.com/app/1.0.0/',
+  plugins: [
+    // Pre-imported plugin init modules
+    { name: 'my-plugin', init: myPluginInit },
+  ],
+  actionModules: [
+    // Pre-imported action modules
+    { module: myPluginModule, name: 'my-plugin' },
+  ],
+});
+export default { fetch: handler };
+```
+Pre-imported modules bypass filesystem discovery — the entry file bundles everything with esbuild. See [fetch-handler.md](fetch-handler.md) for the `ArtifactStore` interface and full BaaS example.
+For serve-only imports without build-time dependencies, use `@jay-framework/production-server/serve`.
+## CLI Flags
+### jay-stack serve
+| Flag                      | Default             | Description                                                 |
+| ------------------------- | ------------------- | ----------------------------------------------------------- |
+| `--port <n>`              | `3000`              | Server port                                                 |
+| `--version <n>`           | from package.json   | Build version to serve                                      |
+| `--role <role>`           | `main`              | `main` (pages + actions) or `renderer` (webhooks + rebuild) |
+| `--static-base-url <url>` | `/`                 | Base URL for all browser-facing assets                      |
+| `--no-serve-static`       | (serves by default) | Disable serving static files from `frontend/`               |
+| `--test-mode`             | off                 | Enable `/_jay/health` and `/_jay/shutdown` endpoints        |
+| `-v, --verbose`           | off                 | Verbose logging                                             |
+### jay-stack build
+| Flag            | Default           | Description                      |
+| --------------- | ----------------- | -------------------------------- |
+| `--version <n>` | from package.json | Build version number             |
+| `--no-minify`   | minified          | Disable minification (debugging) |
+| `-v, --verbose` | off               | Verbose logging                  |
+## Test Mode
+When `--test-mode` is enabled, the server exposes:
+| Endpoint         | Method | Response                                                   |
+| ---------------- | ------ | ---------------------------------------------------------- |
+| `/_jay/health`   | GET    | `{"status":"ready","port":4000,"uptime":5.2}`              |
+| `/_jay/shutdown` | POST   | `{"status":"shutting_down"}` — gracefully stops the server |
+Use for smoke tests and CI pipelines. The dev server (`jay-stack dev --test-mode`) has the same endpoints.
+## Two-Server Architecture
+For data-driven sites, run two servers:
+```bash
+# Main server — handles page requests
+jay-stack serve --role main --port 4000
+# Renderer server — handles webhooks and rebuilds
+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).

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

@@ -29,9 +29,11 @@ A plugin provides headless components (data + interactions, no UI) that project
 | [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 usage                                         |
 | [dev-server-service.md](dev-server-service.md)   | Dev server service API: routes, params, freeze management               |
 | `../references/<plugin>/`                        | Plugin reference data                                                   |