@grafana/create-plugin 7.12.3 → 7.14.0

package/src/commands/add.command.ts

@@ -1,10 +1,21 @@
-import defaultAdditions from '../codemods/additions/additions.js';
+import defaultAdditions, { hasPromptStep, isScriptAddition } from '../codemods/additions/additions.js';
+import { buildAdditionTodosWarning, prepareAgenticAddition, runAgenticStep } from '../codemods/agentic/index.js';
+import { buildDirectiveBlock, buildNextStepsLine, getPromptPath } from '../codemods/agentic/prompts.js';
+import { buildVerifyWarning, runVerifyScripts } from '../codemods/agentic/verify.js';
+import { Context } from '../codemods/context.js';
 import { runCodemod } from '../codemods/runner.js';
-import { getPackageManagerExecCmd, getPackageManagerFromUserAgent } from '../utils/utils.packageManager.js';
+import {
+  getPackageManagerExecCmd,
+  getPackageManagerFromUserAgent,
+  getPackageManagerWithFallback,
+} from '../utils/utils.packageManager.js';
 import { performPreCodemodChecks } from '../utils/utils.checks.js';
+import { findAdditionTodos, isGitDirectoryClean } from '../utils/utils.git.js';
 import minimist from 'minimist';
 import { output } from '../utils/utils.console.js';
 
+const ADD_FEATURES_DOCS_URL = 'https://grafana.com/developers/plugin-tools/how-to-guides/add-features-to-a-plugin';
+
 export const add = async (argv: minimist.ParsedArgs) => {
   const subCommand = argv._[1];
 
@@ -22,18 +33,88 @@ export const add = async (argv: minimist.ParsedArgs) => {
       throw new Error(`Unknown addition: ${subCommand}\n\nAvailable additions: ${additionsList.join(', ')}`);
     }
 
-    // filter out minimist internal properties (_ and $0) before passing to codemod
-    const { _, $0, ...codemodOptions } = argv;
-    const context = await runCodemod(addition, codemodOptions);
+    // filter out minimist internal properties (_ and $0) and the agent flag before passing to codemod
+    const { _, $0, agent: agentFlag, ...codemodOptions } = argv;
+
+    // resolved before any codemod work so a missing agent cannot leave a half-applied addition.
+    // undefined when this addition carries no agent instructions
+    const resolution = await prepareAgenticAddition(addition, agentFlag);
+
+    // captured before the codemod flushes, so we know whether --force let unrelated changes through
+    const treeWasDirty = resolution?.mode === 'enabled' ? !(await isGitDirectoryClean()) : false;
+
+    let context: Context | undefined;
+    if (isScriptAddition(addition)) {
+      context = await runCodemod(addition, codemodOptions);
+    }
 
-    const message = context.getMessage();
+    const message = context?.getMessage();
     if (message) {
       output[message.level]({ title: message.title, body: message.body });
-    } else {
-      output.success({
-        title: `Successfully added ${addition.name} to your plugin.`,
+    }
+
+    if (!resolution || !hasPromptStep(addition)) {
+      if (!message) {
+        output.success({
+          title: `Successfully added ${addition.name} to your plugin.`,
+        });
+      }
+      return;
+    }
+
+    if (resolution.mode === 'enabled') {
+      const result = await runAgenticStep({
+        addition,
+        agent: resolution.agent,
+        context,
+        basePath: process.cwd(),
+        treeWasDirty,
       });
+
+      const summaryBody = result.kind === 'applied' ? [result.summary] : [];
+      const { packageManagerName } = getPackageManagerWithFallback();
+      const verifyWarning = buildVerifyWarning(
+        addition.name,
+        packageManagerName,
+        runVerifyScripts({ scripts: addition.verify ?? [], cwd: process.cwd(), packageManagerName })
+      );
+
+      if (verifyWarning) {
+        output.warning({ title: verifyWarning.title, body: [...summaryBody, ...verifyWarning.body] });
+      } else {
+        output.success({
+          title: `Successfully added ${addition.name} to your plugin.`,
+          body: summaryBody.length > 0 ? summaryBody : undefined,
+        });
+      }
+
+      const todosWarning = buildAdditionTodosWarning(
+        addition.name,
+        await findAdditionTodos(addition.name, process.cwd())
+      );
+      if (todosWarning) {
+        output.warning(todosWarning);
+      }
+      return;
+    }
+
+    // opted out, or already running inside an agent: the agent step is handed onwards
+    const deferredAddition = {
+      name: addition.name,
+      description: addition.description,
+      instructionsPath: getPromptPath(addition.prompt),
+      verifyScripts: addition.verify ?? [],
+    };
+
+    if (resolution.mode === 'inside-agent') {
+      output.logSingleLine(buildDirectiveBlock(deferredAddition));
+      return;
     }
+
+    output.warning({
+      title: `${addition.name} includes AI-agent instructions that were not applied.`,
+      body: [buildNextStepsLine(deferredAddition)],
+    });
   } catch (error) {
     if (error instanceof Error) {
       output.error({
@@ -56,6 +137,8 @@ async function showAdditionsHelp() {
       '',
       'Available additions:',
       ...output.bulletList(additionsList),
+      '',
+      `Learn more: ${output.formatUrl(ADD_FEATURES_DOCS_URL)}`,
     ],
   });
 }

package/src/utils/utils.cli.ts

@@ -13,10 +13,15 @@ export const argv = minimist(args, {
     hasBackend: 'backend',
     pluginName: 'plugin-name',
     orgName: 'org-name',
+    docsPath: 'docs-path',
   },
   // tell minimist to parse boolean flags as true/false to prevent minimist from interpreting
   // them as the command name if passed first. e.g. `create-plugin --force update`
   boolean: ['force', 'experimental-updates'],
+  // --agent is tri-state: absent, bare (pick an agent), or a value (an agent id or a path to a binary).
+  // parsing it as a string keeps bare --agent as '' rather than true, so all three are distinguishable.
+  // --no-agent still arrives as false.
+  string: ['agent', 'docsPath'],
 });
 
 export const commandName = argv._[0] || 'generate';

package/src/utils/utils.git.test.ts

@@ -0,0 +1,57 @@
+import { exec } from 'node:child_process';
+import { findAdditionTodos } from './utils.git.js';
+
+vi.mock('node:child_process', () => ({ exec: vi.fn() }));
+
+type ExecCallback = (error: Error | null, result?: { stdout: string; stderr: string }) => void;
+
+function mockExec(outcome: { stdout: string } | { error: Error }) {
+  vi.mocked(exec).mockImplementation(((_command: string, _options: unknown, callback: ExecCallback) => {
+    if ('error' in outcome) {
+      callback(outcome.error);
+    } else {
+      callback(null, { stdout: outcome.stdout, stderr: '' });
+    }
+  }) as unknown as typeof exec);
+}
+
+describe('findAdditionTodos', () => {
+  afterEach(() => {
+    vi.mocked(exec).mockReset();
+  });
+
+  it('should search tracked and untracked files for the addition marker', async () => {
+    mockExec({ stdout: '' });
+
+    await findAdditionTodos('rspack', '/plugin');
+
+    expect(exec).toHaveBeenCalledWith(
+      'git grep -n --untracked -F "TODO(rspack)"',
+      { cwd: '/plugin' },
+      expect.any(Function)
+    );
+  });
+
+  it('should return the file, line and text of each marker', async () => {
+    mockExec({
+      stdout: [
+        'rspack.config.ts:12:  // TODO(rspack): CorsWorkerPlugin needs a RuntimeModule port',
+        'build/utils.ts:3:// TODO(rspack): swc plugin ABI: mismatch',
+        '',
+      ].join('\n'),
+    });
+
+    const todos = await findAdditionTodos('rspack', '/plugin');
+
+    expect(todos).toEqual([
+      { file: 'rspack.config.ts', line: 12, text: '// TODO(rspack): CorsWorkerPlugin needs a RuntimeModule port' },
+      { file: 'build/utils.ts', line: 3, text: '// TODO(rspack): swc plugin ABI: mismatch' },
+    ]);
+  });
+
+  it('should return no markers when git grep finds nothing or fails', async () => {
+    mockExec({ error: Object.assign(new Error('Command failed'), { code: 1 }) });
+
+    await expect(findAdditionTodos('rspack', '/plugin')).resolves.toEqual([]);
+  });
+});

package/src/utils/utils.git.ts

@@ -41,3 +41,28 @@ export async function gitCommitNoVerify(commitMsg: string) {
     }
   }
 }
+
+export interface AdditionTodo {
+  file: string;
+  line: number;
+  text: string;
+}
+
+const GIT_GREP_LINE_PATTERN = /^(.+?):(\d+):(.*)$/;
+
+// Finds the `TODO(<additionName>)` markers an addition's instructions ask the agent to leave for
+// anything it could not apply. --untracked covers files the addition created
+export async function findAdditionTodos(additionName: string, cwd: string): Promise<AdditionTodo[]> {
+  try {
+    const { stdout } = await exec(`git grep -n --untracked -F "TODO(${additionName})"`, { cwd });
+
+    return stdout
+      .split('\n')
+      .map((line) => GIT_GREP_LINE_PATTERN.exec(line))
+      .filter((match): match is RegExpExecArray => match !== null)
+      .map(([, file, line, text]) => ({ file, line: Number(line), text: text.trim() }));
+  } catch (error) {
+    // git grep exits 1 when nothing matches. that, and git being unavailable, both mean nothing to report
+    return [];
+  }
+}

package/src/utils/utils.handlebars.ts

@@ -41,6 +41,14 @@ export const kebabToPascalKebab = (str: string) => {
     .join('-');
 };
 
+// for text inside a double-quoted YAML scalar, e.g. `title: "{{{yamlEscape pluginName}}}"`
+export const yamlEscape = (str: string) => {
+  if (typeof str !== 'string') {
+    return '';
+  }
+  return str.replaceAll('\\', '\\\\').replaceAll('"', '\\"');
+};
+
 // Register our helpers and partials with handlebars.
 registerHandlebarsHelpers();
 registerHandlebarsPartials();
@@ -63,6 +71,7 @@ function registerHandlebarsHelpers() {
     properCase: pascalCase,
     pascalCase: pascalCase,
     if_eq: ifEq,
+    yamlEscape: yamlEscape,
   };
 
   Object.keys(helpers).forEach((helperName) =>

package/src/utils/utils.packageManager.test.ts

@@ -0,0 +1,23 @@
+import { vi } from 'vitest';
+import { getPackageManagerWithFallback } from './utils.packageManager.js';
+import { getPackageJson } from './utils.packagejson.js';
+
+vi.mock(import('./utils.packagejson.js'), () => ({
+  getPackageJson: vi.fn(),
+}));
+
+vi.mock(import('@libs/find-up'), () => ({
+  findUpSync: () => undefined,
+}));
+
+describe('getPackageManagerWithFallback', () => {
+  it('reads the packageManager field', () => {
+    vi.mocked(getPackageJson).mockReturnValue({ packageManager: 'pnpm@10.4.1' } as never);
+    expect(getPackageManagerWithFallback()).toEqual({ packageManagerName: 'pnpm', packageManagerVersion: '10.4.1' });
+  });
+
+  it('ignores a packageManager field without a version', () => {
+    vi.mocked(getPackageJson).mockReturnValue({ packageManager: 'yarn' } as never);
+    expect(getPackageManagerWithFallback()).toEqual({ packageManagerName: 'npm', packageManagerVersion: '10.9.0' });
+  });
+});

package/src/utils/utils.packageManager.ts

@@ -170,8 +170,9 @@ function getPackageManagerFromLockFile(): PackageManager | undefined {
 
 function getPackageManagerFromPackageJson(): PackageManager | undefined {
   const packageJson = getPackageJson();
-  if (packageJson?.packageManager) {
-    const [packageManagerName, packageManagerVersion] = packageJson.packageManager.split('@');
+  // without a version there's nothing to pick the install command by, so the lockfile decides
+  const [packageManagerName, packageManagerVersion] = packageJson?.packageManager?.split('@') ?? [];
+  if (packageManagerName && packageManagerVersion) {
     return { packageManagerName, packageManagerVersion };
   }
 

package/src/utils/utils.templates.ts

@@ -11,13 +11,14 @@ import {
   getPackageManagerFromUserAgent,
   getPackageManagerInstallCmd,
   getPackageManagerWithFallback,
+  type PackageManager,
 } from './utils.packageManager.js';
 import { normalizeId, renderHandlebarsTemplate } from './utils.handlebars.js';
 
 import { CURRENT_APP_VERSION } from './utils.version.js';
 import { debug } from './utils.cli.js';
 import fs from 'node:fs';
-import { getConfig } from './utils.config.js';
+import { type FeatureFlags, getConfig } from './utils.config.js';
 import { getExportFileName } from '../utils/utils.files.js';
 import { getPluginJson } from './utils.plugin.js';
 import { glob } from 'glob';
@@ -92,12 +93,53 @@ export function renderTemplateFromFile(templateFile: string, data?: any) {
   return renderHandlebarsTemplate(fs.readFileSync(templateFile).toString(), data);
 }
 
+/**
+ * Builds the template data for an existing plugin from its plugin.json, package manager and feature flags.
+ * Pure, so codemods can pass in values read from their Context instead of from disk.
+ */
+export function buildTemplateData({
+  pluginJson,
+  packageManager,
+  features,
+}: {
+  pluginJson: Record<string, any>;
+  packageManager: PackageManager;
+  features: FeatureFlags;
+}): TemplateData {
+  const { packageManagerName, packageManagerVersion } = packageManager;
+  return {
+    ...EXTRA_TEMPLATE_VARIABLES,
+    pluginId: pluginJson.id,
+    pluginName: pluginJson.name,
+    hasBackend: pluginJson.backend,
+    orgName: pluginJson.info?.author?.name,
+    pluginType: pluginJson.type,
+    packageManagerName,
+    packageManagerVersion,
+    packageManagerInstallCmd: getPackageManagerInstallCmd(packageManagerName, packageManagerVersion),
+    isAppType: isAppType(pluginJson.type),
+    isNPM: isNPM(packageManagerName),
+    version: CURRENT_APP_VERSION,
+    bundleGrafanaUI: features.bundleGrafanaUI ?? DEFAULT_FEATURE_FLAGS.bundleGrafanaUI,
+    scenesVersion: '^8.17.0',
+    pluginExecutable: pluginJson.executable,
+    useExperimentalRspack: Boolean(features.useExperimentalRspack),
+    frontendBundler: features.useExperimentalRspack ? 'rspack' : 'webpack',
+  };
+}
+
+function isAppType(pluginType: string) {
+  return pluginType === PLUGIN_TYPES.app || pluginType === PLUGIN_TYPES.scenes;
+}
+
+function isNPM(packageManagerName: string) {
+  return packageManagerName === 'npm';
+}
+
 export function getTemplateData(cliArgs?: GenerateCliArgs): TemplateData {
   const { features } = getConfig();
   const currentVersion = CURRENT_APP_VERSION;
   const bundleGrafanaUI = features.bundleGrafanaUI ?? DEFAULT_FEATURE_FLAGS.bundleGrafanaUI;
-  const isAppType = (pluginType: string) => pluginType === PLUGIN_TYPES.app || pluginType === PLUGIN_TYPES.scenes;
-  const isNPM = (packageManagerName: string) => packageManagerName === 'npm';
   const frontendBundler = features.useExperimentalRspack ? 'rspack' : 'webpack';
 
   let templateData: TemplateData;
@@ -128,28 +170,11 @@ export function getTemplateData(cliArgs?: GenerateCliArgs): TemplateData {
     // Updating or migrating a plugin
     // (plugin.json and package.json files are only present if it's an existing plugin)
   } else {
-    const pluginJson = getPluginJson();
-    const { packageManagerName, packageManagerVersion } = getPackageManagerWithFallback();
-
-    templateData = {
-      ...EXTRA_TEMPLATE_VARIABLES,
-      pluginId: pluginJson.id,
-      pluginName: pluginJson.name,
-      hasBackend: pluginJson.backend,
-      orgName: pluginJson.info.author.name,
-      pluginType: pluginJson.type,
-      packageManagerName: packageManagerName,
-      packageManagerVersion: packageManagerVersion,
-      packageManagerInstallCmd: getPackageManagerInstallCmd(packageManagerName, packageManagerVersion),
-      isAppType: isAppType(pluginJson.type),
-      isNPM: isNPM(packageManagerName),
-      version: currentVersion,
-      bundleGrafanaUI,
-      scenesVersion: '^8.17.0',
-      pluginExecutable: pluginJson.executable,
-      useExperimentalRspack: Boolean(features.useExperimentalRspack),
-      frontendBundler,
-    };
+    templateData = buildTemplateData({
+      pluginJson: getPluginJson(),
+      packageManager: getPackageManagerWithFallback(),
+      features,
+    });
   }
 
   templatesDebugger('\nTemplate data:\n' + JSON.stringify(templateData, null, 2));

package/templates/app-sdk/.config/app-sdk/generate-kinds.mjs

@@ -21,7 +21,7 @@ import { chmodSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs
 import { join, resolve } from 'node:path';
 import { arch, platform, tmpdir } from 'node:os';
 
-const VERSION = 'v0.60.3';
+const VERSION = 'v0.60.16';
 const REPO = 'grafana/grafana-app-sdk';
 const BIN = 'grafana-app-sdk';
 

package/templates/common/.config/webpack/webpack.config.ts

@@ -6,7 +6,7 @@
  */
 
 import CopyWebpackPlugin from 'copy-webpack-plugin';
-import ESLintPlugin from 'eslint-webpack-plugin';
+import DiagnosticsPlugin from 'diagnostics-webpack-plugin';
 import ForkTsCheckerWebpackPlugin from 'fork-ts-checker-webpack-plugin';
 import path from 'path';
 import ReplaceInFileWebpackPlugin from 'replace-in-file-webpack-plugin';
@@ -208,10 +208,9 @@ const config = async (env: Env): Promise<Configuration> => {
           },
           typescript: { configFile: path.join(process.cwd(), 'tsconfig.json') },
         }),
-        new ESLintPlugin({
-          extensions: ['.ts', '.tsx'],
-          lintDirtyModulesOnly: Boolean(env.development), // don't lint on start, only lint changed files
-          failOnError: Boolean(env.production),
+        new DiagnosticsPlugin({
+          lintOnStart: false, // don't lint on start, only lint changed files
+          checks: [{ use: 'eslint', extensions: ['ts', 'tsx'] }],
         }),
       ] : []),
     ],

package/templates/common/_package.json

@@ -17,7 +17,7 @@
   "license": "Apache-2.0",
   "devDependencies": {
     "@grafana/eslint-config": "^10.0.0",
-    "@grafana/plugin-e2e": "^3.14.0",
+    "@grafana/plugin-e2e": "^3.15.0",
     "@grafana/sign-plugin": "^3.3.3",
     "@grafana/tsconfig": "^2.2.0",
     "@playwright/test": "^1.62.1",{{#if useExperimentalRspack}}
@@ -29,7 +29,7 @@
     "@swc/jest": "^0.2.0",
     "@testing-library/jest-dom": "^6.6.0",
     "@testing-library/react": "^16.3.0",
-    "@types/jest": "^29.5.0",
+    "@types/jest": "^30.0.0",
     "@types/node": "^24.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",{{#if useExperimentalRspack}}
@@ -37,21 +37,22 @@
     "@typescript-eslint/eslint-plugin": "^8.38.0",
     "@typescript-eslint/parser": "^8.38.0",{{#unless useExperimentalRspack}}
     "copy-webpack-plugin": "^14.0.0",{{/unless}}
-    "css-loader": "^7.1.0",
+    "css-loader": "^7.1.0",{{#unless useExperimentalRspack}}
+    "diagnostics-webpack-plugin": "^1.0.1",{{/unless}}
     "eslint": "^9.32.0",
     "eslint-config-prettier": "^10.1.0",
     "eslint-plugin-jsdoc": "^52.0.0",
     "eslint-plugin-react": "^7.37.0",
-    "eslint-plugin-react-hooks": "^7.1.0",
-    "eslint-webpack-plugin": "^5.0.0",{{#unless useExperimentalRspack}}
+    "eslint-plugin-react-hooks": "^7.1.0",{{#if useExperimentalRspack}}
+    "eslint-webpack-plugin": "^5.0.0",{{/if}}{{#unless useExperimentalRspack}}
     "fork-ts-checker-webpack-plugin": "^9.1.0",{{/unless}}
     "glob": "^11.1.0",
     "identity-obj-proxy": "^3.0.0",
     "imports-loader": "^5.0.0",
     "intersection-observer": "^0.12.2",
-    "jest": "^29.7.0",
+    "jest": "^30.5.0",
     "jest-canvas-mock": "^2.5.2",
-    "jest-environment-jsdom": "^29.7.0",
+    "jest-environment-jsdom": "^30.5.0",
     "prettier": "^3.6.0",
     "replace-in-file-webpack-plugin": "^1.0.0",{{#if useExperimentalRspack}}
     "rspack-plugin-virtual-module": "^1.0.0",{{/if}}
@@ -64,7 +65,7 @@
     "ts-node": "^10.9.0",{{#if useExperimentalRspack}}
     "ts-checker-rspack-plugin": "^1.2.0",{{/if}}
     "typescript": "5.9.2",
-    "webpack": "^5.101.0"{{#unless useExperimentalRspack}},
+    "webpack": "^5.106.0"{{#unless useExperimentalRspack}},
     "webpack-cli": "^6.0.0",
     "webpack-livereload-plugin": "^3.0.2",
     "webpack-subresource-integrity": "^5.1.0",

package/templates/docs/common/workflows/validate-docs.yml

@@ -0,0 +1,52 @@
+name: Validate documentation
+
+on:
+  push:
+    branches:
+      - main
+      - master
+    paths:
+      - '{{docsPath}}/**'
+      - 'src/plugin.json'
+      - 'package.json'
+{{#if lockFile}}
+      - '{{lockFile}}'
+{{/if}}
+  pull_request:
+    branches:
+      - main
+      - master
+    paths:
+      - '{{docsPath}}/**'
+      - 'src/plugin.json'
+      - 'package.json'
+{{#if lockFile}}
+      - '{{lockFile}}'
+{{/if}}
+
+jobs:
+  validate:
+    name: Validate plugin docs
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+{{#if_eq packageManagerName "pnpm"}}
+      # pnpm action uses the packageManager field in package.json to
+      # understand which version to install.
+      - uses: pnpm/action-setup@v6
+{{/if_eq}}
+      - name: Setup Node.js environment
+        uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+          cache: '{{packageManagerName}}'
+
+      - name: Install dependencies
+        run: {{packageManagerInstallCmd}}
+
+      - name: Validate plugin documentation
+        run: {{packageManagerName}} run docs:validate

package/templates/docs/panel/docs/AGENTS.md

@@ -0,0 +1,107 @@
+# Plugin docs
+
+This folder is the documentation for **{{{pluginName}}}**, published at
+`grafana.com/grafana/plugins/{{pluginId}}/docs/`.
+
+## Guides
+
+Read these before you write or change any page. This docs format is new and your training
+data does not cover it, so do not rely on what you know about other docs tools.
+
+Run `{{packageManagerName}} run docs:validate` and open the guide on its last line, `Docs guides:`. It's
+the guides' `index.md`, which says which guide to read for what, and the other guides sit next to it.
+The guides match the version of the validator this plugin uses. The line is a local path, usually
+`node_modules/@grafana/plugin-docs-cli/docs/index.md`, or a URL when the package isn't on disk, such as
+with Yarn Plug'n'Play.
+
+The guides name scripts such as `docs:validate`. This plugin uses **{{packageManagerName}}**, so run them
+with `{{packageManagerName}} run`, as in the commands below.
+
+## Pages and their source
+
+When you change code, update the page that documents it:
+
+| Page                 | Source of truth                                                                        |
+| -------------------- | -------------------------------------------------------------------------------------- |
+| `index.md`           | Nothing - it is a curated router. Update it when pages are added or removed.           |
+| `options.md`         | `setPanelOptions` and `useFieldConfig` in `src/module.ts`                              |
+| `data-formats.md`    | The panel component's data handling, plus any field pickers in `src/module.ts`         |
+| `examples.md`        | `provisioning/dashboards/*.json` if present, otherwise the panel's own option defaults |
+| `troubleshooting.md` | Error and empty-state messages in source, known and reported issues. Never guess.      |
+
+Never guess failures in `troubleshooting.md`. Each symptom must come from an error, warning or empty-state
+message in source, a known issue in the README or other docs or a reported issue.
+
+## Optional pages
+
+Add one of these pages when the plugin has the matching feature. Use the filename given here, give the page
+a `sidebar_position` that puts it where it belongs and link it from `index.md`.
+
+| Trigger                                                                            | Page               | Scope                                                        |
+| ---------------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------ |
+| `setPresetsSupplier(...)` in source                                                | `presets.md`       | The presets the panel ships, when each applies, screenshots. |
+| RBAC role declarations in `src/plugin.json`                                        | `permissions.md`   | What each role grants, default assignments.                  |
+| Substantial accessibility considerations (keyboard shortcuts, screen reader notes) | `accessibility.md` | Keyboard interaction, ARIA, contrast, motion preferences.    |
+
+## Section briefs
+
+Each section of a scaffolded page has a brief telling you what belongs there. A brief is an HTML comment
+that starts with `section-brief`. Search the docs folder for `section-brief` to find what is left to write:
+
+```markdown
+## Options
+
+<!-- section-brief
+Fill this in: Describe every option the plugin registers, one row per option.
+
+If the plugin has no options, remove this section entirely.
+-->
+```
+
+Some sections also have fixed text, with a brief that builds on it:
+
+```markdown
+## Basic example
+
+A panel excerpt in dashboard JSON has this shape:
+
+<!-- section-brief
+Fill this in: Complete the excerpt above with the options the example needs.
+-->
+```
+
+Text outside a brief is written for every panel and is part of the scaffold. Keep it, and change it
+only where it's wrong for this plugin, such as a menu path or a step that differs.
+
+Everything inside a brief is the instruction. A brief covers the section it sits under, unless it says
+otherwise: it may tell you to extend the fixed text above it, to replace it with several sections or to
+remove the page. When a brief says to remove a section, remove its heading and fixed text too.
+
+To fill a section:
+
+1. Read the brief.
+2. Read the source the page documents, from the table above, then write the section.
+3. Delete the whole comment, from `<!-- section-brief` to `-->`.
+
+Briefs are not shown in the preview or the catalog, so a section you haven't written looks like a bare
+heading. `docs:validate` lists every section that still has only its brief.
+
+## Validate
+
+```bash
+{{packageManagerName}} run docs:validate
+```
+
+Run `docs:validate` after every page you write or change and fix what it reports. A docs task is done when
+it reports no warnings and no suggestions about section briefs. In particular, an `empty-section` or
+`unfilled-section-brief` suggestion means a section is still unwritten or a brief is still in place. Neither
+fails validation, so a passing exit code alone does not mean the docs are done.
+
+## Preview
+
+```bash
+{{packageManagerName}} run docs:serve    # local preview at http://localhost:3001, reloads on save
+```
+
+`docs:serve` keeps running until you stop it. Start it in the background if you need to look at the
+rendered pages, and stop it when you are done.

package/templates/docs/panel/docs/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md