AIditor Add-Menu Items

Plugin Developer Agent Kit — documentation written for AI agents, readable by humans.

Plugins contribute items to the AIditor's Add Menu via YAML catalog files generated by the agent-kit handler.

The agent-kit handler writes to agent-kit/aiditor/add-menu/<plugin-name>.yaml. The AIditor discovers and loads all YAML files in this directory.

Required and recommended fields

items:
  - id: my-plugin:feature-name # required — unique, stable
    title: Feature Name # required — shown in the add menu
    category: My Plugin # required — top-level nav label
    prompt: | # required — injected verbatim into agent task
      Use headless component @my-org/my-plugin / contract feature-name.
      Read agent-kit/designer/feature-name.md for usage guide.
    pluginName: my-plugin # required — plugin attribution
    packageName: '@my-org/my-plugin' # required — visibility filter
    subCategory: Components # optional — second nav level

pluginName and packageName must always be set and must match the plugin's plugin.yaml name and npm package name respectively. AIditor uses them to filter items — only items whose packageName or pluginName matches an installed plugin are visible.

Interaction mode

Every item should declare how the user attaches it:

interaction:
  mode: reference # default — attach as context or @mention

interaction:
  mode: stage-place # click/drag onto live preview
  stagePromptTemplate: | # placed at the marker location
    Add a product card at this location using wix-stores/product-widget.

Use reference for data sources (contracts, categories). Use stage-place for visual elements the user places on the page (components, design tokens, effects).

Browse size

Controls card size in the browse grid:

    browse:
      size: small    # 4 per row — color swatches, small tokens
      size: medium   # 2 per row — default
      size: large    # 1 per row — full-width previews

Presentation (preview)

Optional visual preview in the browse grid:

    # Static image
    presentation:
      type: image
      src: thumbnails/my-plugin/feature.png

    # HTML fragment — must use @scope for CSS isolation
    presentation:
      type: html-fragment
      html: |
        <div>
          <style>@scope { .demo { color: blue; } }</style>
          <div class="demo">Preview content</div>
        </div>

Html-fragment rules:

• Single root <div>
• <style> with @scope { } (even if CSS is inline-only)
• No <script>, no on* handlers
• Keep under 8 KB

TypeScript type

Import AddMenuItem from @jay-framework/plugin-validator for type-safe item construction:

import type { AddMenuItem } from '@jay-framework/plugin-validator';

const items: AddMenuItem[] = [
  {
    id: 'my-plugin:feature',
    title: 'Feature',
    category: 'My Plugin',
    pluginName: 'my-plugin',
    packageName: '@my-org/my-plugin',
    interaction: { mode: 'stage-place', stagePromptTemplate: 'Add feature here.' },
    prompt: 'Use headless @my-org/my-plugin / contract feature.',
  },
];

YAML serialization

When writing YAML with js-yaml, use noRefs: true to prevent anchor/alias syntax (&ref_0 / *ref_0) which the AIditor does not support:

fs.writeFileSync(outputPath, yaml.dump({ items }, { lineWidth: 120, noRefs: true }), 'utf-8');

Full reference

See agent-kit/plugin/aiditor-add-menu.md (installed by jay-stack setup aiditor) for the full contributor guide including validation rules, browse packing, and surface-specific behavior.

---

About this document

This page is part of the Jay Stack Agent Kit — documentation generated from the framework source and written primarily for AI agents. The language and structure are optimized for machine consumption — expect precise, specification-style prose rather than narrative documentation. Learn more about the Agent Kit →