@jay-framework/jay-stack-cli 0.22.2 → 0.23.0

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

@@ -31,7 +31,7 @@ There is no standalone "interactive" phase. Any tag with `type: interactive` (re
 4. **Read actions** — read `.jay-action` files (paths from plugins-index) to see action descriptions, input schemas, and output schemas. This tells you what data each action accepts and returns.
 5. **Read references** — check `references/<plugin>/` for pre-generated discovery data (product catalogs, collection schemas, etc.). These are generated by `jay-stack agent-kit` and contain real data from the site.
 6. **Discover data** — run `jay-stack params <plugin>/<contract>` for SSG route params, `jay-stack action <plugin>/<action>` for data discovery. Use reference files (step 5) first when available — they're faster than running CLI commands.
-7. **Create pages** — write `.jay-html` files under `src/pages/` following directory-based routing. For static override routes (a static page that overrides a dynamic route for a specific URL), declare params with `<script type="application/jay-params">`.
+7. **Create pages** — write `.jay-html` files under `src/pages/` following directory-based routing. For static override routes (a static page that overrides a dynamic route for a specific URL), declare params with `<script type="application/jay-params">`. Jay-html `if` and `{…}` bind to **tag names only** — no `.length`, method calls, or bracket indexing; derive booleans and counts in `page.ts` (see [jay-html-template-syntax.md](jay-html-template-syntax.md#expression-limits-important)).
 8. **Validate** — run `jay-stack validate` to check for errors.
 9. **Test** — run `jay-stack dev --test-mode` and verify pages render.
 
@@ -41,14 +41,16 @@ There is no standalone "interactive" phase. Any tag with `type: interactive` (re
 | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
 | [project-structure.md](project-structure.md)               | Project layout, styling patterns (CSS themes, design tokens), configuration files               |
 | [jay-html-syntax.md](jay-html-syntax.md)                   | Jay-HTML overview: philosophy, component types, nesting rules, links to sub-files               |
-| [jay-html-template-syntax.md](jay-html-template-syntax.md) | Template markup: data binding, conditions (boolean, enum, numeric, &&/\|\|), loops, refs        |
+| [jay-html-template-syntax.md](jay-html-template-syntax.md) | Template markup: data binding, conditions, expression limits (no `.length`), loops, refs        |
 | [jay-html-components.md](jay-html-components.md)           | Component imports: headless (key/instance), headfull FS, nesting patterns                       |
 | [jay-html-styling.md](jay-html-styling.md)                 | Styling: inline, external, dynamic style bindings, class bindings                               |
 | [routing.md](routing.md)                                   | Directory-based routing: page structure, dynamic routes, route priority                         |
+| [navigation-patterns.md](navigation-patterns.md)           | Active menu/sidebar patterns using `jay.url.path`, `===`, and `^=` operators                    |
 | [contracts-and-plugins.md](contracts-and-plugins.md)       | Reading contracts, plugin.yaml, .jay-action files, and the materialized indexes                 |
 | [Contract Authoring Guide](../contracts/GUIDE.md)          | Writing contracts: syntax, page/component/linked contracts, examples                            |
 | [script-tags.md](script-tags.md)                           | Script tag policy: use page.ts for behavior, jay-script="allow" for third-party scripts         |
 | [cli-commands.md](cli-commands.md)                         | CLI commands: setup, validate, params, action, dev server                                       |
+| [validation-guide.md](validation-guide.md)                 | Understanding validation output: static analysis, component warnings, how to act on findings    |
 | `../references/<plugin>/`                                  | Pre-generated discovery data: product catalogs, collection schemas (from `jay-stack agent-kit`) |
 
 ## When to Use Headfull Components

package/agent-kit-template/designer/contracts-and-plugins.md

@@ -279,3 +279,23 @@ Schemas use a compact type notation:
 | `{tag: sel, type: interactive, elementType: HTMLSelectElement}`  | `<select ref="sel">...</select>`              |
 | `{tag: items, type: sub-contract, repeated: true, trackBy: id}`  | `<div forEach="items" trackBy="id">...</div>` |
 | `{tag: detail, type: sub-contract}`                              | `{detail.fieldName}`                          |
+
+### Empty list / empty state
+
+For repeated lists, add a **boolean variant** (e.g. `hasItems`, `hasCategories`) for empty-state UI. Do **not** use JavaScript property access in jay-html — `if="items.length===0"` fails at runtime because jay-html looks for a tag named `items.length`, not the array's length.
+
+```yaml
+# ✅ In the contract
+- tag: hasCategories
+  type: variant
+  dataType: boolean
+  description: Whether there are any categories
+```
+
+```html
+<!-- ✅ In jay-html -->
+<p if="!hasCategories">No categories yet.</p>
+<div if="hasCategories" forEach="categories" trackBy="_id">...</div>
+```
+
+Alternatively, expose a **number** data tag (`itemCount`) and use numeric comparison: `if="itemCount===0"`. See [jay-html-template-syntax.md](jay-html-template-syntax.md#expression-limits-important) and [contracts/examples/category-list.md](../contracts/examples/category-list.md).

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

@@ -39,6 +39,8 @@ Access data and refs with the key prefix:
 
 Key-based imports are only available in **pages** (not in headfull FS components).
 
+**Important:** Do NOT use `<jay:keyName>` for key-based imports. The key is for ViewState access (`{key.field}`), not for inline elements. `<jay:>` tags use the **contract name**, not the key.
+
 ### Pattern 2: Instance-Based (jay: prefix)
 
 Multiple instances with props and inline templates. Use when you need **multiple instances** or need to pass **props**.
@@ -99,6 +101,16 @@ Use `{path}` syntax to bind props to values from the page's ViewState. The bindi
 
 Inside `<jay:...>`, bindings resolve to **that instance's** contract tags (not the parent).
 
+### Choosing between patterns
+
+| Need                                                   | Pattern        | Key?            | Tag?                                         |
+| ------------------------------------------------------ | -------------- | --------------- | -------------------------------------------- |
+| One component per page, data across the whole template | Key-based      | `key="product"` | No `<jay:>` — use `{product.field}` bindings |
+| Multiple instances, each with own props and template   | Instance-based | No key          | `<jay:contract-name prop="...">`             |
+| One instance but with custom inline template           | Instance-based | No key          | `<jay:contract-name>`                        |
+
+**Never combine both:** a component imported with `key` cannot also be used as `<jay:>`. These are mutually exclusive patterns.
+
 ### Prop binding summary
 
 | Syntax                            | Resolves to          | Example                   |
@@ -160,18 +172,44 @@ Each headfull component lives in its own subdirectory under `src/components/` wi
 <jay:SharedHeader logoUrl="/logo.png" />
 ```
 
+> **Route params:** Headfull and instance-based headless components do not receive route params directly. To pass a route param, expose it through the page's ViewState and bind it as a prop: `<jay:SideNav activePage="{activePage}" />`. See [routing.md](routing.md) for the full pattern.
+
 ### Component Structure
 
-A headfull component has its own `.jay-html` file with the same structure as a page:
+Each headfull component needs three files in its subdirectory under `src/components/`:
+
+**`.jay-contract`** — declares props. Tags are optional (use `tags: []` or omit for structural components):
+
+```yaml
+# components/site-header/site-header.jay-contract
+name: SiteHeader
+props:
+  - name: logoUrl
+    type: string
+    required: true
+```
+
+**`.ts`** — component code. Must use `makeJayStackComponent` with `.withProps()` matching the contract props:
+
+```typescript
+// components/site-header/site-header.ts
+import { makeJayStackComponent, phaseOutput } from '@jay-framework/fullstack-component';
+import type { SiteHeaderContract, SiteHeaderProps } from './site-header.jay-html';
+
+export const siteHeader = makeJayStackComponent<SiteHeaderContract>()
+  .withProps<SiteHeaderProps>()
+  .withFastRender(async (props) => phaseOutput({ logoUrl: props.logoUrl }, {}));
+```
+
+For a structural component with only props and no data logic, `.withFastRender` passes props through as ViewState.
+
+**`.jay-html`** — the template:
 
 ```html
-<!-- components/header/header.jay-html -->
+<!-- components/site-header/site-header.jay-html -->
 <html>
   <head>
-    <script type="application/jay-data">
-      data:
-          logoUrl: string
-    </script>
+    <script type="application/jay-data" contract="./site-header.jay-contract"></script>
   </head>
   <body>
     <header>

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

@@ -6,6 +6,8 @@ Jay-HTML is standard HTML with data bindings. There is no custom component frame
 
 The design tool can freely read and rewrite jay-html files as long as contract bindings stay intact. Bindings (`{expression}`, `if`, `forEach`, `ref`) are the only extension to HTML. Everything else — CSS, structure, semantics, accessibility — is native.
 
+**Common mistake:** expressions are not JavaScript — `if="items.length===0"` fails because jay-html resolves tag names, not property access. Use a boolean tag like `hasItems` or a number tag like `itemCount` instead. See [jay-html-template-syntax.md](jay-html-template-syntax.md#expression-limits-important).
+
 ## Component Types
 
 ### Page

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

@@ -140,15 +140,119 @@ Use parentheses for complex expressions:
 <button if="count <= 0 || isLoading" disabled>Checkout</button>
 ```
 
+### String Comparison
+
+For string-typed tags, the right side of `===`/`!==` resolves as a **field reference**. Use quotes for string literals:
+
+```html
+<!-- Field-to-field comparison -->
+<a if="url === currentPath" class="active">Current page</a>
+
+<!-- Literal comparison (use quotes) -->
+<div if="status === 'pending'">Pending approval</div>
+```
+
+For enum-typed tags, the right side remains a variant literal (no quotes needed) — see Enum Variant above.
+
+### Starts With (`^=`)
+
+Check if a string starts with a prefix — useful for section-level highlighting in navigation:
+
+```html
+<a if="jay.url.path ^= '/docs/designer'" class="section-active">Designer</a>
+<a if="currentPath ^= sectionUrl" class="active">{label}</a>
+```
+
+Works with both field references and quoted literals.
+
+### Built-in Bindings (`jay.`)
+
+The `jay.` prefix provides framework values in page templates:
+
+| Binding        | Value                          | Example                  |
+| -------------- | ------------------------------ | ------------------------ |
+| `jay.params.X` | Route param from `[X]` segment | `jay.params.slug`        |
+| `jay.url.path` | Current URL pathname           | `/docs/designer/routing` |
+
+Available at all render phases (slow, fast, interactive). Use in text bindings, prop bindings, and conditionals:
+
+```html
+<h1>Current: {jay.url.path}</h1>
+<jay:Sidebar activePage="{jay.params.slug}" currentPath="{jay.url.path}" />
+<a if="jay.url.path ^= '/docs'" class="docs-active">Docs</a>
+```
+
+`jay.` bindings are available in **page templates only** — headfull components receive this data via props.
+
+### Choosing the Right Condition Type
+
+The contract determines how conditions work. Choose the data type based on the use case:
+
+| Use case                      | Contract type    | Condition syntax     | Example                    |
+| ----------------------------- | ---------------- | -------------------- | -------------------------- |
+| Show/hide a section           | `boolean`        | `if="flag"`          | `if="inStock"`             |
+| Switch between known states   | `variant` (enum) | `if="tag === value"` | `if="status === active"`   |
+| Compare against another field | `string`         | `if="a === b"`       | `if="url === currentPath"` |
+| Compare against a literal     | `string`         | `if="a === 'text'"`  | `if="role === 'admin'"`    |
+| Match URL prefix              | `string`         | `if="a ^= b"`        | `if="path ^= '/docs'"`     |
+| Threshold / range             | `number`         | `if="a > n"`         | `if="count > 0"`           |
+
+**Boolean** — best for simple on/off states. The contract declares `type: variant, dataType: boolean`. Most conditions are booleans.
+
+**Enum** — best when there's a fixed set of known values (e.g., `active | inactive | pending`). The compiler validates that the value exists in the enum. Use for mutually exclusive states where each value maps to different UI.
+
+**String** — best for dynamic comparison where values aren't known at contract time (URLs, slugs, user input). The right side of `===` resolves as a field reference; use quotes for literals. Also supports `^=` for prefix matching.
+
 ### Rules Summary
 
 - Boolean: `if="flag"` / `if="!flag"`
-- Enum: `if="tag===value"` / `if="tag!==value"` (no quotes around value)
+- Enum: `if="tag === value"` / `if="tag !== value"` (no quotes around value)
+- String field: `if="url === currentPath"` (bare identifier = field)
+- String literal: `if="url === '/about'"` (quoted = literal)
+- Starts with: `if="path ^= prefix"` / `if="path ^= '/docs'"`
 - Numeric: `if="count > 0"`, `if="price <= budget"`
 - Field comparison: `if="available >= required"`
 - Logical: `if="a && b"`, `if="a || b"`, `if="(a || b) && c"`
 - Negation: `!` prefix on booleans
 
+### Expression limits (important)
+
+Jay-html expressions resolve **contract or page tag names only**. They are **not** JavaScript — even when the syntax looks similar (`===`, `&&`, `> 0`).
+
+❌ **Invalid** — property access, indexing, or method calls:
+
+```html
+<p if="items.length===0">No items</p>
+<!-- looks for a tag named "items.length" -->
+<span>{user.name.split(' ')[0]}</span>
+<!-- no method calls or bracket indexing -->
+```
+
+✅ **Valid** — expose derived state in the contract or in `page.ts` ViewState:
+
+```html
+<p if="!hasItems">No items</p>
+<span if="itemCount > 0">You have {itemCount} items</span>
+```
+
+| Need            | Contract / ViewState tag     | Jay-HTML             |
+| --------------- | ---------------------------- | -------------------- |
+| Empty list hint | `hasItems: boolean` variant  | `if="!hasItems"`     |
+| Count-based UI  | `itemCount: number` data tag | `if="itemCount===0"` |
+
+See [contracts/examples/category-list.md](../contracts/examples/category-list.md) (`hasCategories`).
+
+### Common Errors
+
+Invalid expressions produce a visible `[INVALID: expression]` marker in the page instead of crashing. The validation message includes the parse error and a pointer to this guide.
+
+| Error                          | Cause                                                                | Fix                                                      |
+| ------------------------------ | -------------------------------------------------------------------- | -------------------------------------------------------- |
+| `Expected "." or identifier`   | Curly braces in non-expression context (e.g., CSS in body `<style>`) | Move `<style>` to `<head>` or use body styles per DL#164 |
+| `unexpected operator "^="`     | Using `^=` with an older framework version                           | Update framework or use `===` instead                    |
+| `Unknown enum value "X"`       | Comparing against a value not in the enum                            | Check the contract for valid enum values                 |
+| `the data field [X] not found` | Referencing a field not in the contract                              | Check the contract tags for available fields             |
+
 ## Loops (forEach / trackBy)
 
 Iterate over repeated sub-contracts:

package/agent-kit-template/designer/navigation-patterns.md

@@ -0,0 +1,73 @@
+# Navigation Patterns
+
+## Active Menu Item
+
+Use conditional class bindings with `===` to highlight the current page:
+
+```html
+<nav>
+  <div forEach="menuItems" trackBy="url">
+    <a href="{url}" class="nav-link {url === currentPath ? active}">{label}</a>
+  </div>
+</nav>
+```
+
+The `{url === currentPath ? active}` adds the `active` class when the menu item's URL matches the current path.
+
+## Active Section
+
+Use `^=` (starts with) for section-level highlighting. A link to `/docs/designer` should be active when the URL is `/docs/designer/routing`:
+
+```html
+<nav>
+  <div forEach="sections" trackBy="url">
+    <a href="{url}" class="section-link {currentPath ^= url ? active}">{label}</a>
+  </div>
+</nav>
+```
+
+## Two-Level Sidebar
+
+Combine section matching and page matching for a sidebar with expandable sections:
+
+```html
+<nav>
+  <div forEach="sections" trackBy="url">
+    <a href="{url}" class="section {currentPath ^= url ? active}">{label}</a>
+    <div if="currentPath ^= url" forEach="pages" trackBy="url">
+      <a href="{url}" class="page {url === currentPath ? active}">{label}</a>
+    </div>
+  </div>
+</nav>
+```
+
+- Section links use `^=` — active when any child page is current
+- Page links within the section use `===` — active on exact match
+- The `if="currentPath ^= url"` on the pages container shows child pages only for the active section
+
+## Passing URL Data to Components
+
+In page templates, use `jay.` bindings to pass URL information to nested components without needing a `page.ts`:
+
+```html
+<jay:Sidebar currentPath="{jay.url.path}" activeRole="{jay.params.role}" />
+```
+
+Inside the component template, use the props as ViewState fields:
+
+```html
+<!-- sidebar.jay-html -->
+<a href="/docs/designer" class="role-link {currentPath ^= '/docs/designer' ? active}">Designer</a>
+<a href="/docs/developer" class="role-link {currentPath ^= '/docs/developer' ? active}"
+  >Developer</a
+>
+```
+
+## Operators
+
+| Operator | Meaning     | Use for                     |
+| -------- | ----------- | --------------------------- |
+| `===`    | Exact match | Current page highlighting   |
+| `^=`     | Starts with | Section/parent highlighting |
+
+Both work with field references (bare identifier) and quoted string literals (`'/docs'`).

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

@@ -144,6 +144,61 @@ src/pages/products/[slug]/page.jay-html
 
 Multiple components on the same page can each declare params. The route directory must provide all required params across all components. For example, if the page contract requires `lang` and a headless component requires `slug`, the page should live at `src/pages/[lang]/products/[slug]/page.jay-html`.
 
+### Passing Route Params to Nested Components
+
+Route params flow automatically to keyed headless components that declare them as `params` in their contract. Instance-based headless components and headfull components do not receive route params directly — they receive props from the template.
+
+#### Direct binding with `jay.params` (no page.ts needed)
+
+Use `jay.params.X` to bind route params directly to nested component props:
+
+```html
+<!-- src/pages/docs/[role]/[slug]/page.jay-html -->
+<jay:DocsSidebar activeRole="{jay.params.role}" activePage="{jay.params.slug}" />
+```
+
+No `page.ts`, no page contract needed for param passing. `jay.params` is available at all render phases. Use `jay.url.path` for the full URL pathname:
+
+```html
+<jay:Sidebar currentPath="{jay.url.path}" />
+```
+
+See [jay-html-template-syntax.md](jay-html-template-syntax.md) for the full list of `jay.` bindings and [navigation-patterns.md](navigation-patterns.md) for active menu patterns.
+
+#### Passing via page.ts (when you need data transformation)
+
+When route params need processing before reaching the component (e.g., fetching data, computing derived values), use the `page.ts` passthrough pattern:
+
+**1. Page contract exposes the param as ViewState:**
+
+```yaml
+# page.jay-contract
+name: Page
+params:
+  slug: string
+tags:
+  - tag: activePage
+    type: data
+    dataType: string
+    phase: slow
+```
+
+**2. `page.ts` passes the param into ViewState:**
+
+```typescript
+.withSlowlyRender(async (props) =>
+  phaseOutput({ activePage: props.slug }, {})
+)
+```
+
+**3. Template binds ViewState to the nested component prop:**
+
+```html
+<jay:SideNav activePage="{activePage}" />
+```
+
+The same pattern works with keyed headless data — if a keyed component already provides the value, bind directly: `<jay:SideNav activePage="{product.slug}" />`.
+
 ### Discovering Param Values
 
 For SSG with dynamic routes, the plugin component provides a `loadParams` generator that yields all valid param combinations. Use it to discover what routes will be generated:
@@ -153,7 +208,7 @@ jay-stack params wix-stores/product-page
 # Output: [{"slug": "blue-shirt"}, {"slug": "red-hat"}, ...]
 ```
 
-Params are always strings (URL params).
+Params are always strings (URL params). Routes are **case-sensitive** — a slug of `My-Page` produces the URL `/my-page` only if the param value is exactly `my-page`. Use lowercase for all param values and filenames that become URL segments.
 
 ## Query Parameters
 

package/agent-kit-template/designer/validation-guide.md

@@ -0,0 +1,88 @@
+# Understanding Validation Output
+
+## How Validation Works
+
+`jay-stack validate` runs static analysis on `.jay-html` files. It parses each template and checks it against rules from installed validator plugins (SEO, a11y, design-system).
+
+**Key concept: static analysis sees the template, not the rendered page.** The validator checks what's written in the `.jay-html` file — it cannot see:
+
+- Dynamic content from `{bindings}` (e.g., `{post.content}` may contain images and headings)
+- Data fetched at render time from services
+- Content generated by other tools or scripts
+
+## What the Validator Sees
+
+The validator processes each `.jay-html` file with:
+
+- **Page template** — your HTML, bindings, and inline styles
+- **Headfull component content** — `<jay:SiteHeader />`, `<jay:DocsSidebar />` etc. are expanded into the page before validation
+- **Headless component tags** — `<jay:product-widget>` inline templates are visible
+- **Linked CSS files** — `<link rel="stylesheet" href="...">` referenced from `<head>` are read and validated (e.g., for CSS `@import` of external URLs)
+- **Inline `<style>` blocks** — CSS in `<head>` is parsed for rule violations
+
+So a warning about an `<img>` might come from a headfull component's template, not your page template. A CSS warning might come from a linked stylesheet.
+
+## How to Read Warnings
+
+Each warning has:
+
+- **Message** — what was found and why it matters
+- **Suggestion** — how to fix it
+- **Element** — which HTML element triggered it (some include the full tag with attributes)
+
+### Acting on Warnings
+
+1. **Check if the element is in your template** — search your `.jay-html` file for the element. If it's not there, it comes from a headfull component.
+
+2. **For headfull component warnings** — fix them in the component's `.jay-html` file (e.g., `src/components/site-header/site-header.jay-html`), not in the page that imports it.
+
+3. **For dynamic content warnings** — if the warning is about content inside a `{binding}` (like `{post.content}`), you can't fix it in the template. The content is generated at render time. These are usually false positives.
+
+4. **Don't loop** — if a warning can't be fixed in any template file, it's a validator limitation. Move on.
+
+## Common Scenarios
+
+### "Image without loading attribute" from a component
+
+The image is in a headfull component (e.g., sidebar icons). Fix it in the component's `.jay-html`, not the page.
+
+### "Heading level skipped" with dynamic content
+
+Your page has `<h1>` and a component has `<h3>`, but the dynamic content (markdown) provides `<h2>` at render time. If the heading hierarchy is correct in the rendered page, fix the component to use the right level — don't restructure the page.
+
+### "No fetchpriority=high" on a text-only page
+
+Your page has no large images in the template. Small icons (under 200px) don't need fetchpriority. This warning only fires for large images.
+
+### Warnings on component files
+
+Components are fragments — they don't need `<h1>`, `<main>`, `<title>`, or `<meta>`. These page-level rules are skipped for files in `src/components/`. If you still see them, check the file path.
+
+## Suppressing Warnings
+
+Each warning's suggestion tells you exactly what to add or change to suppress it. The general suppression mechanisms are:
+
+### Add the missing attribute
+
+Most warnings are suppressed by adding the attribute the rule checks for. The suggestion tells you which attribute and what values are accepted. For example, `loading="lazy"` or `loading="eager"` both suppress the image loading warning.
+
+### Design system: inline comment
+
+For design-system token warnings, add `/* design-system: allow */` as a comment on the same CSS line:
+
+```css
+padding: 96px 0; /* design-system: allow */
+```
+
+### When you can't suppress
+
+If a warning comes from dynamic content (`{post.content}`) or a generated file, you can't suppress it in the template. This is a validator limitation — the warning is a false positive. Don't loop trying to fix it.
+
+## Running Validation
+
+```bash
+jay-stack validate              # validate all pages
+jay-stack validate --strict     # treat warnings as errors
+```
+
+Validation runs automatically during `jay-stack build`. Warnings don't block the build; errors do (with `--strict`).

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

@@ -153,7 +153,18 @@ jay-stack params wix-stores/product-page
 # Output: [{"slug": "blue-shirt"}, {"slug": "red-hat"}, ...]
 ```
 
-Params are always strings (URL params).
+Params are always strings (URL params). Routes are **case-sensitive** — use lowercase for all param values and filenames that become URL segments.
+
+### When page.ts is not needed for params
+
+The designer can bind route params directly to nested component props using `jay.params` in the template — no `page.ts` or page contract needed:
+
+```html
+<jay:DocsSidebar activeRole="{jay.params.role}" activePage="{jay.params.slug}" />
+<jay:Sidebar currentPath="{jay.url.path}" />
+```
+
+Only create a `page.ts` for params when you need to **transform** them (fetch data, compute derived values, combine with service calls). If the page just passes params through to components, `jay.params` is sufficient.
 
 ## Query Parameters
 

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

@@ -13,7 +13,7 @@ A plugin provides headless components (data + interactions, no UI) that project
 3. **Define actions** with `.jay-action` metadata
 4. **Optionally add routes** — pages for admin tools and dashboards
 5. **Optionally add validators** — custom jay-html validation rules
-6. **Optionally add setup/agentkit handlers** — config templating, add-menu generation
+6. **Optionally add setup/agentkit handlers** — config templating, add-menu generation, AIditor Project settings tabs
 7. **Set up `plugin.yaml`** — list contracts, actions, services, contexts, routes, validators, setup, agentkit
 8. **Configure build** — dual entry points (server + client), vite.config.ts, package.json exports
 9. **Validate** with `jay-stack validate-plugin`
@@ -26,7 +26,7 @@ The plugin participates in four CLI commands, each running different hooks:
 | --------------------------- | ------------------ | ---------------------------------------------------------------------------------- |
 | `jay-stack validate-plugin` | Plugin development | Checks plugin.yaml structure, contracts, exports, handler references               |
 | `jay-stack setup <plugin>`  | Project setup      | `setup` — creates config files, validates credentials                              |
-| `jay-stack agent-kit`       | Before development | `agentkit` — generates add-menu items, reference data, skills, thumbnails          |
+| `jay-stack agent-kit`       | Before development | `agentkit` — generates add-menu items, settings tabs, reference data, skills       |
 | `jay-stack validate`        | During development | `validators[].handler` — runs your validation rules against project jay-html files |
 
 **`validate-plugin`** validates YOUR plugin's structure. Run it during plugin development.  
@@ -34,27 +34,29 @@ 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               |
-| [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, references handlers, add-menu generation                |
-| [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                                       |
+| [plugin-structure.md](plugin-structure.md)             | plugin.yaml, package layout, exports                                    |
+| [component-structure.md](component-structure.md)       | makeJayStackComponent, builder API, three-phase rendering               |
+| [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                                                   |
 
 ## Key Principles