@jay-framework/jay-stack-cli 0.24.2 → 0.24.3

package/agent-kit-template/developer/dev-server-service.md

@@ -96,15 +96,15 @@ These APIs are also exposed via the editor protocol (Socket.IO) for design board
 // Server emits:   { type: 'routeParamsBatch', route: '...', params: [], hasMore: false }
 ```
 
-### Freeze Changed Event
+### Frozen Page Refresh (Dev)
 
-The `freezeChanged` socket event is emitted when jay-html or CSS files change. Design board applications should listen for this to refresh their frozen views:
+In development, **full-page** frozen views (`?_jay_freeze=<id>` in iframe or tab) self-reload when jay-html or CSS changes — same `jay:page-reload` Hot Module Replacement (HMR) path as live pages. No host application wiring required. Saved ViewState is preserved across reload.
 
-```typescript
-socket.on('freezeChanged', () => {
-  // Re-fetch frozen page fragments
-});
-```
+Fragment format (`format=fragment` for shadow DOM embedders) does **not** auto-reload; those hosts must re-fetch the fragment.
+
+### Freeze Changed Event (Fragment Hosts)
+
+The `freezeChanged` socket event was described for design board fragment refresh but is **not** emitted by the current dev server. Fragment embedders should re-fetch on file changes themselves, or wait for a future fetch-and-swap protocol. Dev full-page frozen views do not need this event.
 
 ## Iframe / Embed Mode
 

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

@@ -87,7 +87,7 @@ The script body is YAML. Values are passed to the component as props alongside r
 </script>
 ```
 
-> **Note:** `<script type="application/jay-params">` is deprecated. Move param values into the headless component's script tag body.
+> **Note:** `<script type="application/jay-params">` is no longer supported — it is silently ignored by the route scanner and reported as an error by `jay-stack validate`. Move param values into the headless component's script tag body.
 
 ## Page Files
 

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

@@ -2,6 +2,16 @@
 
 Actions provide RPC-style server endpoints for client-to-server communication.
 
+> **Actions are compiler-free and live on the `.` entry.** They run in production, so their handlers
+> must not import the compiler (`@jay-framework/compiler-*`). A handler that needs the compiler is
+> either a [CLI command](commands-guide.md) or a **`devOnly` action** (see below) — not a regular
+> action. `validate-plugin`'s leak scan fails a compiler import in `dist/index.js`.
+>
+> **`devOnly` actions** (`actions[].devOnly: true`) — browser-callable handlers for settings/admin
+> pages that may use the compiler and are **excluded from production**. Their handlers live in the
+> `./tools` entry (`lib/tools.ts`), and the dev server registers them normally. See the settings-page
+> pattern in [plugin-routes.md](plugin-routes.md).
+
 ## makeJayAction — Mutations (POST)
 
 ```typescript

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

@@ -75,6 +75,21 @@ commands:
     command: commands/upload-public.jay-command
 ```
 
+### 4. Export from `./tools`
+
+Commands are the **tools** primitive — they load only from the `./tools` entry (`lib/tools.ts`), which
+may use the compiler. Re-export each command handler there, and add the `./tools` export to
+`package.json`:
+
+```typescript
+// lib/tools.ts (./tools) — toolchain-only, compiler allowed
+export { uploadPublic } from './commands/upload-public.js';
+```
+
+Do **not** re-export commands from `lib/index.ts` — the serve entry must stay compiler-free. (An
+operation that must be callable from a browser page is an [action](actions-guide.md), not a command;
+if it also needs the compiler, mark the action `devOnly`.)
+
 ## `CONSOLE_CONTEXT` Service
 
 A framework-provided service with project info and a logger:

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

@@ -4,6 +4,13 @@ For the full contract syntax, decision tree, and examples, see the shared [Contr
 
 This file covers plugin-specific contract concerns. Contracts (`.jay-contract` files) are the source of truth for a component's data shape. Define the contract before implementing the component.
 
+> **Interactive components need a `./client` export.** If a component built from this contract declares
+> an interactive phase (`.withInteractive(...)`) — or the plugin declares `contexts` — the package
+> must expose a `./client` export (`./dist/index.client.js`) for browser hydration. `validate-plugin`
+> detects interactivity by scanning the built server bundle and errors if `./client` is missing.
+> Server-only (slow/fast) component plugins need no `./client`. See
+> [plugin-structure.md](plugin-structure.md).
+
 ## Basic Structure
 
 ```yaml

package/agent-kit-template/plugin/dev-server-service.md

@@ -107,15 +107,15 @@ These APIs are also exposed via the editor protocol (Socket.IO) for design board
 // Server emits:   { type: 'routeParamsBatch', route: '...', params: [], hasMore: false }
 ```
 
-### Freeze Changed Event
+### Frozen Page Refresh (Dev)
 
-The `freezeChanged` socket event is emitted when jay-html or CSS files change. Design board applications should listen for this to refresh their frozen views:
+In development, **full-page** frozen views (`?_jay_freeze=<id>` in iframe or tab) self-reload when jay-html or CSS changes — same `jay:page-reload` Hot Module Replacement (HMR) path as live pages. No host application wiring required. Saved ViewState is preserved across reload.
 
-```typescript
-socket.on('freezeChanged', () => {
-  // Re-fetch frozen page fragments
-});
-```
+Fragment format (`format=fragment` for shadow DOM embedders) does **not** auto-reload; those hosts must re-fetch the fragment.
+
+### Freeze Changed Event (Fragment Hosts)
+
+The `freezeChanged` socket event was described for design board fragment refresh but is **not** emitted by the current dev server. Fragment embedders should re-fetch on file changes themselves, or wait for a future fetch-and-swap protocol. Dev full-page frozen views do not need this event.
 
 ## Iframe / Embed Mode
 

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

@@ -149,7 +149,7 @@ There is no enforced convention — just pick a prefix that's unique and descrip
 
 ## Dev-only routes
 
-Some plugin pages are **dev-server tooling** — internal dashboards, QA fixtures, builder settings UIs. Mark them with `devOnly: true` so consumers of `listRoutes()` can distinguish them from public site pages. Production builds do not yet exclude `devOnly` routes — that is planned for a future framework release.
+Some plugin pages are **dev-server tooling** — internal dashboards, QA fixtures, builder settings UIs. Mark them with `devOnly: true` so they are served by the dev server, distinguishable via `listRoutes()`, and **excluded from production builds** (not compiled, not in the route manifest).
 
 ```yaml
 routes:
@@ -168,7 +168,48 @@ routes:
 | `listRoutes()` / `RouteInfo`   | Includes route with `devOnly: true`                                  |
 | Page navigation UIs            | **Consumer choice** — tools may filter `devOnly` routes from pickers |
 | Routes loaded by explicit path | **Unaffected** — embed/host tools pass a known route URL             |
-| Production build               | **Deferred** — future task excludes dev-only routes                  |
+| Production build               | **Excluded** — the route is not compiled or bundled                  |
+| Component entry (compiler)     | Resolved from **`./tools`** when the page uses the compiler          |
+
+## Settings pages (devOnly route + devOnly actions)
+
+A common pattern: a `devOnly` route whose interactive form calls plugin server handlers to run
+analysis, rebuild a catalog, etc. Because a settings page runs in the browser it invokes handlers via
+the **action RPC** — so these handlers must be **actions**, not CLI commands. When the handler uses the
+compiler (e.g. it parses jay-html), mark the action **`devOnly: true`**: its handler then lives in
+`./tools` (compiler allowed) and is excluded from production alongside the route.
+
+```yaml
+routes:
+  - path: /my-plugin/settings
+    jayHtml: ./dist/pages/settings/page.jay-html
+    component: mySettingsPage
+    devOnly: true
+actions:
+  - name: runAnalysis
+    action: run-analysis.jay-action
+    devOnly: true # handler in ./tools, may use the compiler, excluded from production
+  - name: fontFallback
+    action: font-fallback.jay-action # normal production action — compiler-free, stays on `.`
+```
+
+```typescript
+// lib/tools.ts (./tools) — compiler allowed, never in the production serve bundle
+export { runAnalysis } from './actions/run-analysis.js'; // uses the compiler
+export { mySettingsPage } from './pages/settings/page.js';
+
+// lib/index.ts (.) — compiler-free serve entry
+export { fontFallback } from './actions/font-fallback.js';
+```
+
+- The dev server registers **all** actions (devOnly from `./tools`, regular from `.`) and serves the
+  route end-to-end with the compiler present.
+- Production build **excludes** the `devOnly` route (not compiled) and **skips** `devOnly` actions
+  (not registered/dispatchable). A compiler-using action left **without** `devOnly` would leak the
+  compiler into `dist/index.js` and fail the leak scan — that is the signal to mark it `devOnly` (or
+  reclassify it as a command).
+- `devOnly` is orthogonal to compiler use: a compiler-free admin action can still be `devOnly` purely
+  to keep it out of production.
 
 ### Standalone access
 

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

@@ -2,6 +2,53 @@
 
 A plugin provides headless components, contracts, and actions. It can be a standalone npm package or inline within a project.
 
+## Capabilities & the runtime/tools split
+
+A plugin package runs code in two very different phases, and they must **not** share one module graph:
+
+- **Serve-time (runtime)** — headless components, production routes, **server actions**, the client
+  bundle, global `init`. Loaded on the production request path. **Must stay compiler-free** — the
+  serve bundle ships to production.
+- **Tools-time** — validators, **CLI commands**, agent-kit generators, `setup` handlers, and
+  `devOnly` route components/actions. Run only under the Jay toolchain (`jay-stack
+validate`/`agent-kit`/`setup`/`run`, dev server). These **may** use the compiler.
+
+**Actions vs commands** — the load-bearing distinction:
+
+- **Actions** are the _serving_ primitive: request-time handlers that run in production. They live on
+  the `.` entry and **must be compiler-free**.
+- **CLI commands** are the _tools_ primitive: invoked under the toolchain. They live on `./tools` and
+  **may use the compiler**.
+
+Rule of thumb: **if a handler needs the compiler, it is a command (or a `devOnly` action), not a
+regular action.**
+
+### Capability → required export
+
+Derive a plugin's required `package.json` exports from the capabilities it declares:
+
+| Capability (plugin.yaml)    | Needs `./client`?          | Handler/export loaded from      |
+| --------------------------- | -------------------------- | ------------------------------- |
+| `contracts`                 | only if interactive phase  | `.` (+ `./<contract>` per item) |
+| `dynamic_contracts`         | only if interactive phase  | `.`                             |
+| `routes`                    | only if interactive phase  | `.` (or `./tools` if `devOnly`) |
+| `contexts`                  | ✅ always (client by def.) | `.`, `./client`                 |
+| `actions`                   | ❌                         | `.` (or `./tools` if `devOnly`) |
+| `services`, `init` / global | ❌                         | `.`                             |
+| `validators`                | ❌                         | **`./tools`**                   |
+| `commands`                  | ❌                         | **`./tools`**                   |
+| `agentkit` / `setup`        | ❌                         | **`./tools`**                   |
+
+Rules `jay-stack validate-plugin` enforces:
+
+- **≥1 capability.** A plugin declaring none is flagged (a `global: true` plugin counts iff it exports
+  a resolvable `init`/`setup` handler).
+- **`./tools` required** iff any tools capability (`validators`, `commands`, `agentkit`, `setup`) or a
+  `devOnly` action is declared.
+- **`./client` required** iff a provided component has an interactive phase, or `contexts` is declared.
+  Server-only and tools-only plugins need no `./client`.
+- **Leak scan:** `dist/index.js` (the `.` entry) must contain no `@jay-framework/compiler-` import.
+
 ## plugin.yaml
 
 The plugin manifest declares all contracts, actions, services, contexts, and configuration:
@@ -125,6 +172,10 @@ tags:
 
 - `name` — Action name (used with `jay-stack action <plugin>/<action>`)
 - `action` — Path to `.jay-action` metadata file
+- `devOnly` — (optional, boolean) When `true`, the action's handler lives in `./tools` (compiler
+  allowed), is served by the dev server, and is **excluded from production builds**. Use for
+  settings-page / admin handlers. A non-`devOnly` action's handler must be compiler-free on `.`. See
+  [plugin-routes.md](plugin-routes.md) for the settings-page pattern.
 
 ### Webhook Entry Fields
 
@@ -177,6 +228,9 @@ services:
 - `css` — (optional) Path to the page's CSS file
 - `component` — Path to the page component (relative to plugin root, or exported member name for NPM)
 - `description` — What this page does
+- `devOnly` — (optional, boolean) When `true`, the route is dev-server tooling (e.g. a settings UI):
+  served by the dev server, **excluded from production builds**. A `devOnly` route whose page
+  component uses the compiler resolves its component from `./tools`.
 
 Plugin routes are served by the dev server alongside project routes. If a project defines the same route path, the project's page takes precedence.
 
@@ -193,7 +247,7 @@ Commands are CLI operations run via `jay-stack run`. Use `makeCliCommand()` to c
 - `handler` — Export name (NPM plugins) or relative path (local plugins) to the validator function
 - `description` — (optional) What this validator checks
 
-**NPM plugins:** `handler` is the export name from the package entry point (e.g., `validateMediaOptimization`). The function must be exported from `lib/index.ts`.  
+**NPM plugins:** `handler` is the export name from the **`./tools`** entry (e.g., `validateMediaOptimization`). The function must be exported from `lib/tools.ts` — **never re-export a validator (or any compiler-using handler) from `lib/index.ts`**, or the compiler leaks into the serve bundle.  
 **Local plugins:** `handler` is a relative path to the module (e.g., `./validators/media-validator`). The module must export a `validate` function.
 
 Validators run during `jay-stack validate` against every parsed jay-html file in the project. See [validation.md](validation.md) for implementation details.
@@ -204,7 +258,7 @@ Validators run during `jay-stack validate` against every parsed jay-html file in
 - `agentkit` — Export name (NPM) or relative path (local) for `jay-stack agent-kit`. Generates discovery data: add-menu catalogs, reference files, skills, thumbnails.
 - `description` — (optional, top-level) Human-readable description of what setup validates
 
-**NPM plugins:** `setup` and `agentkit` are export names from the package entry point.  
+**NPM plugins:** `setup` and `agentkit` are export names from the **`./tools`** entry (`lib/tools.ts`) — they are tools-time handlers and may use the compiler.  
 **Local plugins:** relative paths to the handler modules.
 
 `jay-stack validate-plugin` checks that declared handlers exist and are correctly exported.
@@ -263,21 +317,29 @@ my-project/
 
 See `examples/jay-stack/fake-shop` for a working example.
 
-## Dual Entry Points
+## Entry Points
 
-Jay plugins are fullstack — they run on both server and client. The build produces two bundles:
+Jay plugins run in three contexts. The build produces up to three bundles:
 
-- **Server** (`dist/index.js`) — actions, services, SSR rendering, `init()`. Built with `vite build --ssr`.
-- **Client** (`dist/index.client.js`) — components for hydration, context tokens, `init()`. Built with `vite build`.
+- **Server / serve** (`dist/index.js`, `.`) — actions, services, SSR rendering, `init()`. Loaded on
+  the production request path. **Compiler-free.** Built with `vite build --ssr`.
+- **Client** (`dist/index.client.js`, `./client`) — components for hydration, context tokens,
+  `init()`. Built with `vite build`.
+- **Tools** (`dist/tools.js`, `./tools`) — validators, commands, agent-kit/setup handlers, and any
+  `devOnly` route component/action. **Compiler-allowed** (toolchain-only, never in a serve bundle).
+  Built alongside the server bundle (`vite build --ssr`).
 
-Create two entry files:
+Create the entry files:
 
-| File                  | Exports                                                    |
-| --------------------- | ---------------------------------------------------------- |
-| `lib/index.ts`        | Actions, services, components (SSR), init, service markers |
-| `lib/index.client.ts` | Components (hydration), context markers, init              |
+| File                  | Exports                                                                                                |
+| --------------------- | ------------------------------------------------------------------------------------------------------ |
+| `lib/index.ts`        | Actions, services, components (SSR), init, service markers — **compiler-free**                         |
+| `lib/index.client.ts` | Components (hydration), context markers, init                                                          |
+| `lib/tools.ts`        | Validators, commands, agent-kit/setup handlers, `devOnly` route components + actions — **compiler OK** |
 
-Actions and service providers are server-only. Components appear in **both** entries.
+Actions and service providers are server-only. Components appear in **both** `index.ts` and
+`index.client.ts`. **`index.ts` must never import `tools.ts`** — that is what keeps the compiler out of
+the serve bundle. A validator-only or tools-only plugin may have a near-empty `index.ts`.
 
 ## Build Scripts
 
@@ -289,7 +351,7 @@ Actions and service providers are server-only. Components appear in **both** ent
     "build:client": "vite build",
     "build:server": "vite build --ssr",
     "build:copy-assets": "cp lib/*.jay-contract* dist/",
-    "build:types": "tsup lib/index.ts lib/index.client.ts --dts-only --format esm",
+    "build:types": "tsup lib/index.ts lib/index.client.ts lib/tools.ts --dts-only --format esm",
     "validate": "jay-stack-cli validate-plugin",
     "clean": "rimraf dist"
   }
@@ -313,7 +375,12 @@ export default defineConfig(({ isSsrBuild }) => ({
     emptyOutDir: false,
     lib: {
       entry: isSsrBuild
-        ? { index: resolve(__dirname, 'lib/index.ts') }
+        ? {
+            index: resolve(__dirname, 'lib/index.ts'),
+            // Tools entry (compiler-allowed, toolchain-only). Omit if the plugin has no
+            // validators/commands/agentkit/setup/devOnly surfaces.
+            tools: resolve(__dirname, 'lib/tools.ts'),
+          }
         : { 'index.client': resolve(__dirname, 'lib/index.client.ts') },
       formats: ['es'],
     },
@@ -325,6 +392,9 @@ export default defineConfig(({ isSsrBuild }) => ({
         '@jay-framework/stack-server-runtime',
         '@jay-framework/reactive',
         '@jay-framework/runtime',
+        // Externalize the compiler namespace: any leak into `.` then shows up as a literal
+        // import string in dist/index.js, which validate-plugin's leak scan catches.
+        /^@jay-framework\/compiler-/,
       ],
     },
   },
@@ -349,6 +419,10 @@ For NPM packages, declare exports for both server and client entry points:
       "types": "./dist/index.client.d.ts",
       "default": "./dist/index.client.js"
     },
+    "./tools": {
+      "types": "./dist/tools.d.ts",
+      "default": "./dist/tools.js"
+    },
     "./plugin.yaml": "./plugin.yaml",
     "./my-contract.jay-contract": "./dist/my-contract.jay-contract"
   },
@@ -356,7 +430,19 @@ For NPM packages, declare exports for both server and client entry points:
 }
 ```
 
-The `./client` export is required — the framework uses it for browser-side hydration code. The `.` export handles server-side rendering and action execution.
+- The `.` export handles server-side rendering and action execution — it must be **compiler-free**.
+- The `./client` export is required **only** when a component has an interactive phase or the plugin
+  declares `contexts` (browser-side hydration / client contexts).
+- The `./tools` export is required **only** when the plugin declares a tools capability (`validators`,
+  `commands`, `agentkit`, `setup`) or a `devOnly` action — those handlers load exclusively from
+  `./tools`.
+
+### compiler-\* dependencies
+
+If `./tools` uses the compiler (`@jay-framework/compiler-jay-html`, `compiler-shared`), declare those
+packages as **`peerDependencies`** (provided by the toolchain at tools time) plus **`devDependencies`**
+(so the plugin's own build/test resolve them). Never put them in `dependencies` — that would pull the
+compiler into runtime installs.
 
 ## Plugin-Contributed Agent-Kit Guides
 

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

@@ -23,7 +23,7 @@ agentkit: generateMyAgentKit # export name (NPM) or ./path (local) — optional
 description: Validate credentials and install config # optional, top-level
 ```
 
-**NPM plugins:** `setup` and `agentkit` are export names from the package entry point (`lib/index.ts`).  
+**NPM plugins:** `setup` and `agentkit` are export names from the **`./tools`** entry (`lib/tools.ts`). They are tools-time handlers (may use the compiler) and load only from `./tools` — do not re-export them from `lib/index.ts`, or the compiler can leak into the serve bundle.  
 **Local plugins:** relative paths to handler modules (e.g. `agentkit: ./agentkit` — export `agentkit` or `default` from that module).
 
 `jay-stack validate-plugin` checks that declared handlers exist and are correctly exported.
@@ -266,13 +266,16 @@ See [aiditor-settings-guide.md](aiditor-settings-guide.md) for the full checklis
 
 ## Exporting Handlers
 
-For NPM plugins, export handlers from the package entry point:
+For NPM plugins, export setup/agent-kit handlers from the **`./tools`** entry (they may use the
+compiler and must stay out of the serve bundle):
 
 ```typescript
-// lib/index.ts
+// lib/tools.ts (./tools) — compiler allowed, toolchain-only
 export { setupMyPlugin } from './setup.js';
 export { generateMyAgentKit } from './agentkit.js';
-// ... other exports (components, actions, services)
+
+// lib/index.ts (.) — serve entry, compiler-free
+// ... components, actions, services, init (NOT setup/agentkit)
 ```
 
 For local plugins, use relative paths in `plugin.yaml` and export `agentkit` or `default` from the handler module.

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

@@ -43,6 +43,24 @@ jay-stack validate-plugin -v
 - Component export names are valid strings (not file paths)
 - Action metadata files (`.jay-action`) exist
 
+### Capability-aware structure
+
+`validate-plugin` derives required exports from the capabilities the plugin declares (see the
+capability matrix in [plugin-structure.md](plugin-structure.md)):
+
+- **≥1 capability** — a plugin declaring none is warned (a `global: true` plugin counts iff it exports
+  a resolvable `init`/`setup` handler).
+- **`./tools` required** iff any tools capability (`validators`, `commands`, `agentkit`, `setup`) or a
+  `devOnly` action is declared — those handlers load only from `./tools`. Validator/setup/agentkit
+  handler names are checked against the **`./tools`** entry, not `.`.
+- **`./client` required** iff a component has an interactive phase (detected by scanning the built
+  server `.` bundle for the interactive mark) or `contexts` is declared. Server-only and tools-only
+  plugins need no `./client`.
+- **Leak scan** — the serve entry `dist/index.js` must contain no `@jay-framework/compiler-` import.
+  A compiler-using handler re-exported from `index.ts` fails this check; move it to `lib/tools.ts`.
+- **`devOnly`** — `actions[].devOnly` / `routes[].devOnly` must be booleans; a `devOnly` action
+  requires the `./tools` export.
+
 ### Type Generation
 
 - Contracts compile to valid TypeScript types
@@ -133,20 +151,20 @@ Plugins can provide custom jay-html validation rules that run during `jay-stack
 ```yaml
 validators:
   - name: media-optimization
-    handler: validateMediaOptimization # export name from package entry point
+    handler: validateMediaOptimization # export name from the ./tools entry
     description: Ensures media URLs use resize parameters
 ```
 
 **Handler format:**
 
-- **NPM plugins** — `handler` is an export name from the package entry point (e.g., `validateMediaOptimization`). The function must be exported from `lib/index.ts`.
+- **NPM plugins** — `handler` is an export name from the **`./tools`** entry (e.g., `validateMediaOptimization`). The function must be exported from `lib/tools.ts`. **Never re-export a validator from `lib/index.ts`** — validators use compiler APIs (`walkElements`, `parseTemplateParts`, …), and re-exporting from the serve entry pulls the compiler into the production bundle (caught by the leak scan).
 - **Local plugins** (`src/plugins/`) — `handler` is a relative path to the module (e.g., `./validators/media-validator`). The module must export a `validate` function.
 
-`jay-stack validate-plugin` checks that the handler exists and is correctly exported.
+`jay-stack validate-plugin` checks that the handler exists and is correctly exported from `./tools`.
 
 ### Writing a Validator
 
-Export the validator function from the package entry point (for NPM) or from the handler module (for local):
+Export the validator function from the **`./tools`** entry (`lib/tools.ts`, for NPM) or from the handler module (for local):
 
 ```typescript
 import type { JayHtmlValidatorFn, JayHtmlValidationFinding } from '@jay-framework/compiler-shared';

package/dist/{index-CatrpDqC.js → index-B9vCxAZ1.js}

@@ -8,7 +8,7 @@ import fs from "node:fs/promises";
 import { createRequire } from "node:module";
 import { runLoadParams, scanPlugins, DevSlowlyChangingPhase, slowRenderInstances } from "@jay-framework/stack-server-runtime";
 import { parseJayFile, JAY_IMPORT_RESOLVER, injectHeadfullFSTemplates, assignCoordinatesToJayHtml, discoverHeadlessInstances, generateElementHydrateFile, generateServerElementFile } from "@jay-framework/compiler-jay-html";
-import { checkValidationErrors, RuntimeMode } from "@jay-framework/compiler-shared";
+import { normalizeActionEntry, checkValidationErrors, RuntimeMode } from "@jay-framework/compiler-shared";
 import crypto, { createHash } from "node:crypto";
 import * as productionServer from "@jay-framework/production-server";
 import { generateSitemap } from "@jay-framework/production-server";
@@ -599,16 +599,18 @@ async function discoverActions(actionPaths, serverOutputDir, buildDir, projectRo
       plugins.push({ name: plugin.manifest.name, packageName });
       const pluginActions = plugin.manifest.actions;
       if (pluginActions && pluginActions.length > 0) {
-        actions.push({
-          serverModule: "",
-          packageName,
-          isPlugin: true,
-          actionNames: pluginActions.map(
-            (a) => typeof a === "string" ? a : a.name
-          )
-        });
+        const productionActions = pluginActions.map(normalizeActionEntry).filter((a) => !a.devOnly);
+        const devOnlyCount = pluginActions.length - productionActions.length;
+        if (productionActions.length > 0) {
+          actions.push({
+            serverModule: "",
+            packageName,
+            isPlugin: true,
+            actionNames: productionActions.map((a) => a.name)
+          });
+        }
         getLogger().info(
-          `[Build] Plugin actions from ${packageName}: ${pluginActions.length}`
+          `[Build] Plugin actions from ${packageName}: ${productionActions.length}` + (devOnlyCount > 0 ? ` (excluded ${devOnlyCount} devOnly)` : "")
         );
       }
     }
@@ -1256,7 +1258,13 @@ async function buildVersion(options) {
     clientInits
   };
   const pluginRoutes = await scanPluginRoutes(options.projectRoot, routes);
-  const allRoutes = [...routes, ...pluginRoutes];
+  const excludedDevOnly = [...routes, ...pluginRoutes].filter((route) => route.devOnly);
+  if (excludedDevOnly.length > 0) {
+    logger.info(
+      `[Build] Excluding ${excludedDevOnly.length} devOnly route(s) from production: ` + excludedDevOnly.map((r) => r.rawRoute).join(", ")
+    );
+  }
+  const allRoutes = [...routes, ...pluginRoutes].filter((route) => !route.devOnly);
   const routeEntries = allRoutes.map((route) => {
     let serverModule = "";
     if (route.compPath) {

package/dist/index.js

@@ -21,7 +21,7 @@ import { createRequire as createRequire$1 } from "node:module";
 import { isJayAction, isJayStreamAction, isJayCliCommand, CONSOLE_CONTEXT } from "@jay-framework/fullstack-component";
 import { Command } from "commander";
 import chalk from "chalk";
-import { loadPluginManifest as loadPluginManifest$1, JAY_EXTENSION, RuntimeMode as RuntimeMode$1, GenerateTarget, JAY_CONTRACT_EXTENSION, findDynamicContract } from "@jay-framework/compiler-shared";
+import { loadPluginManifest as loadPluginManifest$1, normalizeActionEntry as normalizeActionEntry$1, JAY_EXTENSION, RuntimeMode as RuntimeMode$1, GenerateTarget, JAY_CONTRACT_EXTENSION, findDynamicContract } from "@jay-framework/compiler-shared";
 import { glob } from "glob";
 import { fileURLToPath } from "node:url";
 import { select, confirm, input } from "@inquirer/prompts";
@@ -393,7 +393,7 @@ function normalizeActionEntry(entry) {
   if (typeof entry === "string") {
     return { name: entry };
   }
-  return { name: entry.name, action: entry.action };
+  return { name: entry.name, action: entry.action, devOnly: entry.devOnly };
 }
 function loadPluginManifest(pluginDir) {
   const pluginYamlPath = path$1.join(pluginDir, "plugin.yaml");
@@ -650,9 +650,18 @@ async function registerNpmPluginActions(packageName, pluginConfig, pluginDir, re
     } else {
       pluginModule = await import(packageName);
     }
+    let toolsModule;
+    const loadToolsModule = async () => {
+      if (!toolsModule) {
+        const toolsEntry = `${packageName}/tools`;
+        toolsModule = viteServer ? await viteServer.ssrLoadModule(toolsEntry) : await import(toolsEntry);
+      }
+      return toolsModule;
+    };
     for (const entry of pluginConfig.actions) {
-      const { name: actionName, action: actionPath } = normalizeActionEntry(entry);
-      const actionExport = pluginModule[actionName];
+      const { name: actionName, action: actionPath, devOnly } = normalizeActionEntry(entry);
+      const sourceModule = devOnly ? await loadToolsModule() : pluginModule;
+      const actionExport = sourceModule[actionName];
       if (actionExport && isJayAction(actionExport)) {
         registry.register(actionExport);
         const registeredName = actionExport.actionName;
@@ -724,6 +733,13 @@ async function discoverPluginActions(pluginPath, projectRoot, registry = actionR
       return [];
     }
   }
+  const resolveLocalToolsModulePath = () => {
+    for (const candidate of ["tools.ts", "tools.js"]) {
+      const candidatePath = path.join(pluginPath, candidate);
+      if (fs.existsSync(candidatePath)) return candidatePath;
+    }
+    return null;
+  };
   try {
     let pluginModule;
     if (viteServer) {
@@ -731,9 +747,23 @@ async function discoverPluginActions(pluginPath, projectRoot, registry = actionR
     } else {
       pluginModule = await import(modulePath);
     }
+    let toolsModule;
+    const loadToolsModule = async () => {
+      if (toolsModule) return toolsModule;
+      const toolsPath = resolveLocalToolsModulePath();
+      if (!toolsPath) {
+        getLogger().warn(
+          `[Actions] Plugin "${pluginName}" declares a devOnly action but has no tools.ts/tools.js module`
+        );
+        return void 0;
+      }
+      toolsModule = viteServer ? await viteServer.ssrLoadModule(toolsPath) : await import(toolsPath);
+      return toolsModule;
+    };
     for (const entry of pluginConfig.actions) {
-      const { name: actionName, action: actionPath } = normalizeActionEntry(entry);
-      const actionExport = pluginModule[actionName];
+      const { name: actionName, action: actionPath, devOnly } = normalizeActionEntry(entry);
+      const sourceModule = devOnly ? await loadToolsModule() : pluginModule;
+      const actionExport = sourceModule?.[actionName];
       if (actionExport && isJayAction(actionExport)) {
         registry.register(actionExport);
         const registeredName = actionExport.actionName;
@@ -1359,10 +1389,11 @@ async function loadCommandHandler(command, viteServer) {
       module = await import(modulePath);
     }
   } else {
+    const toolsEntry = `${command.packageName}/tools`;
     if (viteServer) {
-      module = await viteServer.ssrLoadModule(command.packageName);
+      module = await viteServer.ssrLoadModule(toolsEntry);
     } else {
-      module = await import(command.packageName);
+      module = await import(toolsEntry);
     }
   }
   for (const [, exported] of Object.entries(module)) {
@@ -1496,14 +1527,15 @@ async function loadHandler(plugin, handlerName, viteServer) {
       `Handler "${handlerName}" not found in "${plugin.pluginPath}". Available exports: ${Object.keys(module).join(", ")}`
     );
   } else {
+    const toolsEntry = `${plugin.packageName}/tools`;
     if (viteServer) {
-      module = await viteServer.ssrLoadModule(plugin.packageName);
+      module = await viteServer.ssrLoadModule(toolsEntry);
     } else {
-      module = await import(plugin.packageName);
+      module = await import(toolsEntry);
     }
     if (typeof module[handlerName] !== "function") {
       throw new Error(
-        `Handler "${handlerName}" not found as export in "${plugin.packageName}". Available exports: ${Object.keys(module).join(", ")}`
+        `Handler "${handlerName}" not found as export in "${toolsEntry}". Available exports: ${Object.keys(module).join(", ")}`
       );
     }
     return module[handlerName];
@@ -1600,7 +1632,7 @@ function initLogger(verbose) {
 async function runBuild(projectPath, options) {
   initLogger(options.verbose);
   const ctx = await resolveProductionContext(projectPath, options.version);
-  const { buildVersion } = await import("./index-CatrpDqC.js");
+  const { buildVersion } = await import("./index-B9vCxAZ1.js");
   await buildVersion({
     version: ctx.version,
     projectRoot: ctx.resolvedPath,
@@ -2902,6 +2934,7 @@ async function validatePluginPackage(pluginPath, options) {
   }
   await validateAddMenuCatalog(context, result);
   await validateAiditorSettings(context, result);
+  validateNoCompilerLeak(context, result);
   result.valid = result.errors.length === 0;
   return result;
 }
@@ -3075,13 +3108,28 @@ async function validateSchema(context, result) {
       }
     }
   }
-  if (!manifest.contracts && !manifest.dynamic_contracts) {
-    result.warnings.push({
-      type: "schema",
-      message: "Plugin has no contracts or dynamic_contracts defined",
-      location: "plugin.yaml",
-      suggestion: 'Add either "contracts" or "dynamic_contracts" to expose functionality'
-    });
+  const hasCapability = Boolean(
+    manifest.contracts || manifest.dynamic_contracts || manifest.actions || manifest.validators || manifest.routes || manifest.services || manifest.contexts || manifest.init || manifest.setup || manifest.agentkit || manifest.commands
+  );
+  if (!hasCapability) {
+    if (manifest.global === true) {
+      const hasGlobalEntry = !context.isNpmPackage || checkExportExists("init", context, ".") || checkExportExists("setup", context, ".");
+      if (!hasGlobalEntry) {
+        result.errors.push({
+          type: "export-mismatch",
+          message: 'Plugin declares "global: true" but exports no init/setup handler to run on each page',
+          location: "plugin.yaml",
+          suggestion: 'Export an "init" (or "setup") handler from the package entry, or declare a capability'
+        });
+      }
+    } else {
+      result.warnings.push({
+        type: "schema",
+        message: "Plugin declares no capabilities (contracts, dynamic_contracts, actions, validators, routes, services, contexts, init, setup, agentkit, commands)",
+        location: "plugin.yaml",
+        suggestion: "Declare at least one capability. See agent-kit/plugin/plugin-structure.md"
+      });
+    }
   }
   if (manifest.services) {
     if (!Array.isArray(manifest.services)) {
@@ -3145,14 +3193,22 @@ async function validateSchema(context, result) {
   }
   if (manifest.actions) {
     for (const entry of manifest.actions) {
-      const exportName = typeof entry === "string" ? entry : entry.name;
+      if (typeof entry === "object" && entry.devOnly !== void 0 && typeof entry.devOnly !== "boolean") {
+        result.errors.push({
+          type: "schema",
+          message: `Action "${entry.name}" devOnly must be a boolean`,
+          location: "plugin.yaml actions"
+        });
+      }
+      const { name: exportName, devOnly } = normalizeActionEntry$1(entry);
       if (exportName) {
         validateHandlerRef(
           exportName,
           `Action "${exportName}"`,
           "plugin.yaml actions",
           context,
-          result
+          result,
+          devOnly ? "./tools" : "."
         );
       }
     }
@@ -3197,7 +3253,8 @@ async function validateSchema(context, result) {
             `Route "${route.path}" component`,
             `plugin.yaml routes`,
             context,
-            result
+            result,
+            route.devOnly ? "./tools" : "."
           );
         }
         if (route.jayHtml) {
@@ -3251,7 +3308,8 @@ async function validateSchema(context, result) {
             `Validator "${validator.name}" handler`,
             "plugin.yaml validators",
             context,
-            result
+            result,
+            "./tools"
           );
         }
       });
@@ -3271,7 +3329,8 @@ async function validateSchema(context, result) {
         "Setup handler",
         "plugin.yaml setup",
         context,
-        result
+        result,
+        "./tools"
       );
     }
   }
@@ -3281,22 +3340,23 @@ async function validateSchema(context, result) {
       "Agent-kit handler",
       "plugin.yaml agentkit",
       context,
-      result
+      result,
+      "./tools"
     );
   }
 }
-function checkExportExists(exportName, context) {
+function checkExportExists(exportName, context, exportKey = ".") {
   const packageJsonPath = path$1.join(context.pluginPath, "package.json");
   if (!fs$1.existsSync(packageJsonPath)) return true;
   let mainPath;
   try {
     const packageJson = JSON.parse(fs$1.readFileSync(packageJsonPath, "utf-8"));
-    if (packageJson.exports?.["."]) {
-      const entry = packageJson.exports["."];
+    if (packageJson.exports?.[exportKey]) {
+      const entry = packageJson.exports[exportKey];
       const entryPath = typeof entry === "string" ? entry : entry.default || entry.import;
       if (entryPath) mainPath = path$1.join(context.pluginPath, entryPath);
     }
-    if (!mainPath && packageJson.main) {
+    if (!mainPath && exportKey === "." && packageJson.main) {
       mainPath = path$1.join(context.pluginPath, packageJson.main);
     }
   } catch {
@@ -3318,7 +3378,63 @@ function checkExportExists(exportName, context) {
 function isRelativePath(value) {
   return value.startsWith("./") || value.startsWith("../");
 }
-function validateHandlerRef(value, label, location, context, result) {
+function resolveEntryFile(context, exportKey) {
+  const packageJsonPath = path$1.join(context.pluginPath, "package.json");
+  if (!fs$1.existsSync(packageJsonPath)) return void 0;
+  try {
+    const packageJson = JSON.parse(fs$1.readFileSync(packageJsonPath, "utf-8"));
+    const entry = packageJson.exports?.[exportKey];
+    const entryPath = typeof entry === "string" ? entry : entry?.default || entry?.import || void 0;
+    const resolved = entryPath || (exportKey === "." ? packageJson.main : void 0) ? path$1.join(context.pluginPath, entryPath || packageJson.main) : void 0;
+    return resolved && fs$1.existsSync(resolved) ? resolved : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function hasComponentCapability(context) {
+  const m = context.manifest;
+  return Boolean(m.contracts || m.dynamic_contracts || m.routes);
+}
+function needsToolsEntry(manifest) {
+  if (manifest.validators || manifest.commands || manifest.agentkit || manifest.setup) {
+    return true;
+  }
+  if (manifest.actions) {
+    return manifest.actions.some((entry) => normalizeActionEntry$1(entry).devOnly === true);
+  }
+  return false;
+}
+function detectInteractivePhase(context) {
+  if (!context.isNpmPackage) return "unknown";
+  const entryFile = resolveEntryFile(context, ".");
+  if (!entryFile) return "unknown";
+  try {
+    const content = fs$1.readFileSync(entryFile, "utf-8");
+    return content.includes("withInteractiveMark(");
+  } catch {
+    return "unknown";
+  }
+}
+function validateNoCompilerLeak(context, result) {
+  if (!context.isNpmPackage) return;
+  const entryFile = resolveEntryFile(context, ".");
+  if (!entryFile) return;
+  let content;
+  try {
+    content = fs$1.readFileSync(entryFile, "utf-8");
+  } catch {
+    return;
+  }
+  if (content.includes("@jay-framework/compiler-")) {
+    result.errors.push({
+      type: "compiler-leak",
+      message: 'Serve entry "." (dist/index.js) imports "@jay-framework/compiler-…" — the compiler must not reach the production serve bundle',
+      location: entryFile,
+      suggestion: 'Move the compiler-using handler (validator, agentkit, setup, or a devOnly action) to lib/tools.ts (the "./tools" export) and remove its re-export from lib/index.ts. A compiler-using action is really a command or a devOnly action (DL#179/#180).'
+    });
+  }
+}
+function validateHandlerRef(value, label, location, context, result, exportKey = ".") {
   if (context.isNpmPackage) {
     if (isRelativePath(value)) {
       result.errors.push({
@@ -3327,12 +3443,13 @@ function validateHandlerRef(value, label, location, context, result) {
         location,
         suggestion: `Export the function from the package entry point and use the export name instead of a path`
       });
-    } else if (!checkExportExists(value, context)) {
+    } else if (!checkExportExists(value, context, exportKey)) {
+      const entryFile = exportKey === "./tools" ? "lib/tools.ts" : exportKey === "./client" ? "lib/index.client.ts" : "lib/index.ts";
       result.errors.push({
         type: "export-mismatch",
-        message: `${label} "${value}" is not exported from the package`,
+        message: `${label} "${value}" is not exported from the "${exportKey}" entry`,
         location,
-        suggestion: `Add "export { ${value} } from '...'" to the package entry point`
+        suggestion: `Add "export { ${value} } from '...'" to ${entryFile} (the "${exportKey}" export)`
       });
     }
   } else if (isRelativePath(value)) {
@@ -3606,11 +3723,30 @@ async function validatePackageJson(context, result) {
         });
       }
       if (!packageJson.exports["./client"]) {
-        result.warnings.push({
+        const interactivity = detectInteractivePhase(context);
+        const needsClient = context.manifest.contexts !== void 0 || interactivity === true;
+        if (needsClient) {
+          result.errors.push({
+            type: "export-mismatch",
+            message: 'package.json exports missing "./client" entry point, but the plugin ' + (context.manifest.contexts !== void 0 ? "declares contexts (client-side by definition)" : "provides an interactive component"),
+            location: packageJsonPath,
+            suggestion: 'Add "./client": "./dist/index.client.js" to exports. The client bundle provides components for hydration and client-side contexts. Build with: vite build (client) + vite build --ssr (server)'
+          });
+        } else if (interactivity === "unknown" && hasComponentCapability(context)) {
+          result.warnings.push({
+            type: "export-mismatch",
+            message: 'package.json exports missing "./client" entry point; could not determine whether any component is interactive (build the plugin before validating)',
+            location: packageJsonPath,
+            suggestion: 'If any component declares an interactive phase, add "./client": "./dist/index.client.js"'
+          });
+        }
+      }
+      if (!packageJson.exports["./tools"] && needsToolsEntry(context.manifest)) {
+        result.errors.push({
           type: "export-mismatch",
-          message: 'package.json exports missing "./client" entry point',
+          message: 'package.json exports missing "./tools" entry point, but the plugin declares tools capabilities (validators, commands, agentkit, setup, or devOnly actions)',
           location: packageJsonPath,
-          suggestion: 'Add "./client": "./dist/index.client.js" to exports. The client bundle provides components for hydration and client-side contexts. Build with: vite build (client) + vite build --ssr (server)'
+          suggestion: 'Add "./tools": "./dist/tools.js" to exports and re-export those handlers from lib/tools.ts'
         });
       }
       if (context.manifest.contracts) {
@@ -4413,7 +4549,7 @@ async function runPluginValidators(projectRoot, parsedFiles, errors, warnings) {
           const handlerPath = path$1.resolve(plugin.pluginPath, validatorDef.handler);
           handlerModule = await import(handlerPath);
         } else {
-          handlerModule = await import(plugin.packageName);
+          handlerModule = await import(`${plugin.packageName}/tools`);
         }
         validatorFn = plugin.isLocal ? handlerModule.validate ?? handlerModule.default : handlerModule[validatorDef.handler];
         if (typeof validatorFn !== "function") {
@@ -4601,9 +4737,10 @@ async function validateJayFiles(options = {}) {
       }
       parsedFiles.push({ relativePath, parsed: parsedFile.val });
       if (content.includes("application/jay-params")) {
-        warnings.push({
+        errors.push({
           file: relativePath,
-          message: '<script type="application/jay-params"> is deprecated. Move the values into the YAML body of the headless component that uses them. See agent-kit/developer/routing.md for details.'
+          message: '<script type="application/jay-params"> is no longer supported and is ignored. Move the values into the YAML body of the headless component that uses them. See agent-kit/developer/routing.md for details.',
+          stage: "parse"
         });
       }
       const pageExportError = checkPageComponentExport(jayFile);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/jay-stack-cli",
-  "version": "0.24.2",
+  "version": "0.24.3",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -25,16 +25,16 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.5.2",
-    "@jay-framework/compiler-jay-html": "^0.24.2",
-    "@jay-framework/compiler-shared": "^0.24.2",
-    "@jay-framework/dev-server": "^0.24.2",
-    "@jay-framework/fullstack-component": "^0.24.2",
-    "@jay-framework/logger": "^0.24.2",
-    "@jay-framework/plugin-validator": "^0.24.2",
-    "@jay-framework/production-build": "^0.24.2",
-    "@jay-framework/production-server": "^0.24.2",
-    "@jay-framework/stack-server-build": "^0.24.2",
-    "@jay-framework/stack-server-runtime": "^0.24.2",
+    "@jay-framework/compiler-jay-html": "^0.24.3",
+    "@jay-framework/compiler-shared": "^0.24.3",
+    "@jay-framework/dev-server": "^0.24.3",
+    "@jay-framework/fullstack-component": "^0.24.3",
+    "@jay-framework/logger": "^0.24.3",
+    "@jay-framework/plugin-validator": "^0.24.3",
+    "@jay-framework/production-build": "^0.24.3",
+    "@jay-framework/production-server": "^0.24.3",
+    "@jay-framework/stack-server-build": "^0.24.3",
+    "@jay-framework/stack-server-runtime": "^0.24.3",
     "chalk": "^4.1.2",
     "commander": "^14.0.0",
     "express": "^5.0.1",
@@ -45,7 +45,7 @@
     "yaml": "^2.3.4"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.24.2",
+    "@jay-framework/dev-environment": "^0.24.3",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.21",
     "nodemon": "^3.0.3",