@grafana/create-plugin 7.13.0 → 7.14.0

package/src/codemods/utils.test.ts

@@ -196,6 +196,12 @@ describe('utils', () => {
       const context = new Context(tmpDir);
       expect(() => readJsonFile(context, 'file.json')).toThrowError();
     });
+
+    it.each(['[]', 'null', '"text"'])('should throw when the file contains %s instead of an object', (content) => {
+      const context = new Context(tmpDir);
+      context.addFile('file.json', content);
+      expect(() => readJsonFile(context, 'file.json')).toThrowError('does not contain a JSON object');
+    });
   });
 
   describe('getTemplateDataFromContext', () => {
@@ -263,6 +269,23 @@ describe('utils', () => {
       expect(context.getFile('docs/nested/setup.md')).toBe('pnpm some-name\n');
     });
 
+    it('skips files that include rejects, matching on the output path relative to the target', () => {
+      const context = new Context(tmpDir);
+      const folderPath = templateFolder({ 'README.md': 'readme\n', 'nested/page.md.hbs': 'page\n', npmrc: 'x' });
+      const seen: string[] = [];
+      const added = addTemplateFolder(context, {
+        folderPath,
+        targetPath: 'docs',
+        data,
+        include: (file) => {
+          seen.push(file);
+          return file === 'README.md';
+        },
+      });
+      expect(seen.sort()).toEqual(['.npmrc', 'README.md', 'nested/page.md']);
+      expect(added).toEqual(['docs/README.md']);
+    });
+
     it('strips .hbs and maps config file names like generate does', () => {
       const context = new Context(tmpDir);
       const folderPath = templateFolder({ 'page.md.hbs': 'x', npmrc: 'y' });

package/src/codemods/utils.ts

@@ -1,4 +1,4 @@
-import { dirname, join } from 'node:path';
+import { dirname, join, posix } from 'node:path';
 import { createRequire } from 'node:module';
 import { Context } from './context.js';
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
@@ -180,11 +180,16 @@ export function readJsonFile<T extends object = any>(context: Context, path: str
   if (!context.doesFileExist(path)) {
     throw new Error(`Cannot find ${path}`);
   }
+  let parsed: unknown;
   try {
-    return JSON.parse(context.getFile(path) || '');
+    parsed = JSON.parse(context.getFile(path) || '');
   } catch (e) {
     throw new Error(`Cannot parse ${path}: ${e}`);
   }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`${path} does not contain a JSON object.`);
+  }
+  return parsed as T;
 }
 
 export function addDependenciesToPackageJson(
@@ -346,6 +351,8 @@ function sortObjectByKeys<T extends Record<string, any>>(obj: T): T {
 
 export const migrationsDebug = debug.extend('migrations');
 export const additionsDebug = debug.extend('additions');
+// for helpers that migrations and additions share
+export const codemodsDebug = debug.extend('codemods');
 
 export function renderTemplate(
   templatePath: string,
@@ -374,12 +381,23 @@ export function getTemplateDataFromContext(context: Context): TemplateData {
 
 /**
  * Renders every file under `folderPath` into `targetPath`, the way `generate` scaffolds a template folder:
- * `.hbs` is stripped and config file names are mapped. Files that already exist are left alone.
+ * `.hbs` is stripped and config file names are mapped. Files that already exist are left alone, and so are
+ * files `include` rejects, given each file's output path relative to `targetPath` with `/` separators.
  * Returns the paths it added.
  */
 export function addTemplateFolder(
   context: Context,
-  { folderPath, targetPath, data }: { folderPath: string; targetPath: string; data: Record<string, unknown> }
+  {
+    folderPath,
+    targetPath,
+    data,
+    include = () => true,
+  }: {
+    folderPath: string;
+    targetPath: string;
+    data: Record<string, unknown>;
+    include?: (relativeFile: string) => boolean;
+  }
 ): string[] {
   if (!existsSync(folderPath)) {
     throw new Error(
@@ -389,11 +407,15 @@ export function addTemplateFolder(
 
   const added: string[] = [];
   // relative to `cwd`, so glob characters in the install path (such as Windows backslashes) can't break the pattern
-  for (const relativeFile of glob.sync('**', { cwd: folderPath, dot: true, nodir: true })) {
+  for (const relativeFile of glob.sync('**', { cwd: folderPath, dot: true, nodir: true, posix: true })) {
     const file = join(folderPath, relativeFile);
-    const filePath = join(targetPath, dirname(relativeFile), getExportFileName(file));
+    const outputFile = posix.join(posix.dirname(relativeFile), getExportFileName(file));
+    if (!include(outputFile)) {
+      continue;
+    }
+    const filePath = join(targetPath, outputFile);
     if (context.doesFileExist(filePath)) {
-      additionsDebug(`${filePath} already exists, skipping`);
+      codemodsDebug(`${filePath} already exists, skipping`);
       continue;
     }
     context.addFile(filePath, renderHandlebarsTemplate(readFileSync(file, 'utf-8'), data));

package/src/codemods/utils.workflows.test.ts

@@ -0,0 +1,153 @@
+import { Context } from './context.js';
+import { bumpActionRefs } from './utils.workflows.js';
+
+const WORKFLOW = '.github/workflows/release.yml';
+const BUILD_PLUGIN = 'grafana/plugin-actions/build-plugin';
+const PACKAGE_PLUGIN = 'grafana/plugin-actions/package-plugin';
+const MINIMUMS = { [BUILD_PLUGIN]: 'build-plugin/v1.2.0', [PACKAGE_PLUGIN]: 'package-plugin/v1.3.3' };
+
+// a release workflow with one step per `uses` value
+function workflowWith(...uses: string[]): string {
+  return `name: Release\njobs:\n  release:\n    runs-on: ubuntu-latest\n    steps:\n${uses.map((u) => `      - uses: ${u}\n`).join('')}`;
+}
+
+function bump(workflow: string, minimums: Record<string, string> = MINIMUMS) {
+  const context = new Context('/virtual');
+  context.addFile(WORKFLOW, workflow);
+  const result = bumpActionRefs(context, WORKFLOW, minimums);
+  return { result, content: context.getFile(WORKFLOW) };
+}
+
+describe('bumpActionRefs', () => {
+  it.each([
+    ['a prefixed tag', 'build-plugin/v1.0.2'],
+    ['a bare tag', 'v1.0.0'],
+  ])('raises %s to the minimum', (_, ref) => {
+    const { content, result } = bump(workflowWith(`${BUILD_PLUGIN}@${ref}`));
+    expect(content).toBe(workflowWith(`${BUILD_PLUGIN}@build-plugin/v1.2.0`));
+    expect(result).toEqual({ found: [BUILD_PLUGIN], unrecognized: [] });
+  });
+
+  it.each([
+    ['a floating minor tag', 'build-plugin/v1.1', 'build-plugin/v1.2'],
+    ['a bare floating minor tag', 'v1.0', 'build-plugin/v1.2'],
+    ['a floating major tag', 'v0', 'build-plugin/v1'],
+  ])('raises %s and keeps it floating', (_, ref, raised) => {
+    const { content } = bump(workflowWith(`${BUILD_PLUGIN}@${ref}`));
+    expect(content).toBe(workflowWith(`${BUILD_PLUGIN}@${raised}`));
+  });
+
+  it.each(['build-plugin/v1.2.0', 'build-plugin/v2.0.0', 'build-plugin/v1.2', 'build-plugin/v1', 'v1', 'v2', 'main'])(
+    'leaves %s alone',
+    (ref) => {
+      const workflow = workflowWith(`${BUILD_PLUGIN}@${ref}`);
+      const { content, result } = bump(workflow);
+      expect(content).toBe(workflow);
+      expect(result).toEqual({ found: [BUILD_PLUGIN], unrecognized: [] });
+    }
+  );
+
+  it.each([
+    ['a branch', 'some-feature-branch'],
+    ['a commit SHA', 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'],
+    ["another action's tag", 'package-plugin/v1.0.0'],
+    ['a tag with a longer prefix', 'foo/build-plugin/v1.0.0'],
+  ])('leaves %s alone and reports it', (_, ref) => {
+    const workflow = workflowWith(`${BUILD_PLUGIN}@${ref}`);
+    const { content, result } = bump(workflow);
+    expect(content).toBe(workflow);
+    expect(result).toEqual({ found: [BUILD_PLUGIN], unrecognized: [BUILD_PLUGIN] });
+  });
+
+  it('bumps each use independently, to its own action minimum', () => {
+    const { content, result } = bump(
+      workflowWith(
+        `${BUILD_PLUGIN}@v1.0.0`,
+        `${BUILD_PLUGIN}@build-plugin/v2.0.0`,
+        `${PACKAGE_PLUGIN}@package-plugin/v1.3.2`
+      )
+    );
+    expect(content).toBe(
+      workflowWith(
+        `${BUILD_PLUGIN}@build-plugin/v1.2.0`,
+        `${BUILD_PLUGIN}@build-plugin/v2.0.0`,
+        `${PACKAGE_PLUGIN}@package-plugin/v1.3.3`
+      )
+    );
+    expect(result.found).toEqual([BUILD_PLUGIN, PACKAGE_PLUGIN]);
+  });
+
+  it('bumps a quoted ref and keeps the quotes and any trailing comment', () => {
+    const { content } = bump(workflowWith(`'${BUILD_PLUGIN}@v1.0.0' # pinned`));
+    expect(content).toBe(workflowWith(`'${BUILD_PLUGIN}@build-plugin/v1.2.0' # pinned`));
+  });
+
+  it('only bumps `uses` values, not incidental mentions', () => {
+    const mention = `# see ${BUILD_PLUGIN}@v1.0.0 for reference\nenv:\n  NOTE: ${BUILD_PLUGIN}@v1.0.0\n`;
+    const { content } = bump(`${mention}${workflowWith(`${BUILD_PLUGIN}@v1.0.0`)}`);
+    expect(content).toBe(`${mention}${workflowWith(`${BUILD_PLUGIN}@build-plugin/v1.2.0`)}`);
+  });
+
+  it('keeps comments, blank lines and the rest of the workflow unchanged', () => {
+    const before = [
+      '# release on tag',
+      'name: Release',
+      '',
+      'on:',
+      '  push:',
+      "    tags: ['v*']",
+      '',
+      'jobs:',
+      '  release:',
+      '    runs-on: ubuntu-latest',
+      '    steps:',
+      '      - uses: actions/checkout@v6 # keep me',
+      `      - uses: ${BUILD_PLUGIN}@v1.0.0`,
+      '        with:',
+      '          policy_token: ${{ secrets.TOKEN }}',
+      '',
+    ].join('\n');
+    const { content } = bump(before);
+    expect(content).toBe(before.replace(`${BUILD_PLUGIN}@v1.0.0`, `${BUILD_PLUGIN}@build-plugin/v1.2.0`));
+  });
+
+  it('leaves an indented commented-out block exactly as it was', () => {
+    const before = workflowWith(
+      `${BUILD_PLUGIN}@v1.0.0\n        #with:\n          # save the token in your repository secrets\n          #policy_token: \${{ secrets.TOKEN }}`
+    );
+    const { content } = bump(before);
+    expect(content).toBe(before.replace(`${BUILD_PLUGIN}@v1.0.0`, `${BUILD_PLUGIN}@build-plugin/v1.2.0`));
+  });
+
+  it('leaves a workflow it cannot parse alone', () => {
+    const workflow = `jobs: [\n  uses: ${BUILD_PLUGIN}@v1.0.0\n`;
+    const { content, result } = bump(workflow);
+    expect(content).toBe(workflow);
+    expect(result).toEqual({ found: [], unrecognized: [] });
+  });
+
+  it('does not match an action whose name only starts with the given one', () => {
+    const workflow = workflowWith(`${BUILD_PLUGIN}-extra@v1.0.0`);
+    const { content, result } = bump(workflow);
+    expect(content).toBe(workflow);
+    expect(result.found).toEqual([]);
+  });
+
+  it('reports nothing found when the workflow uses none of the actions', () => {
+    const { content, result } = bump('name: Release\n');
+    expect(content).toBe('name: Release\n');
+    expect(result).toEqual({ found: [], unrecognized: [] });
+  });
+
+  it('reports nothing found when the workflow does not exist', () => {
+    const context = new Context('/virtual');
+    expect(bumpActionRefs(context, WORKFLOW, MINIMUMS)).toEqual({ found: [], unrecognized: [] });
+    expect(context.doesFileExist(WORKFLOW)).toBe(false);
+  });
+
+  it('throws when a minimum is not a version tag', () => {
+    expect(() => bump(workflowWith(`${BUILD_PLUGIN}@v1.0.0`), { [BUILD_PLUGIN]: 'main' })).toThrow(
+      "The minimum ref 'main' for grafana/plugin-actions/build-plugin is not a version tag."
+    );
+  });
+});

package/src/codemods/utils.workflows.ts

@@ -0,0 +1,140 @@
+import { isScalar, parseDocument, visit } from 'yaml';
+import type { Context } from './context.js';
+import { codemodsDebug } from './utils.js';
+
+export interface BumpActionRefsResult {
+  /** The actions used in the workflow. */
+  found: string[];
+  /** The actions pinned to something other than a version tag, such as a branch or a commit SHA. */
+  unrecognized: string[];
+}
+
+/**
+ * Raises each `uses: <action>@<ref>` in a workflow to at least the given minimum ref, the way
+ * addDependenciesToPackageJson raises dependency versions. A ref is never lowered.
+ *
+ * Refs are compared as `vX[.Y[.Z]]` tags, optionally prefixed with the action's own name as monorepo
+ * tags are (`build-plugin/v1.2.0`). A shorter tag floats, so `v1` already runs the latest 1.x and is
+ * left alone, and a floating tag that is too low is raised at its own precision (`v1.1` to `v1.2`).
+ * Other refs are left as-is and reported, except `main`, which always runs the latest release.
+ *
+ * The parser finds each `uses` value, then only that value's source text is replaced, so comments and
+ * formatting elsewhere stay byte-for-byte the same.
+ */
+export function bumpActionRefs(
+  context: Context,
+  workflowPath: string,
+  minimumRefs: Record<string, string>
+): BumpActionRefsResult {
+  const minimums = new Map(
+    Object.entries(minimumRefs).map(([action, minimumRef]) => {
+      const minimum = parseTag(action, minimumRef);
+      if (!minimum) {
+        throw new Error(`The minimum ref '${minimumRef}' for ${action} is not a version tag.`);
+      }
+      return [action, minimum];
+    })
+  );
+
+  const content = context.getFile(workflowPath);
+  if (!content) {
+    codemodsDebug(`Could not find ${workflowPath}. Skipping action bumps.`);
+    return { found: [], unrecognized: [] };
+  }
+
+  const doc = parseDocument(content);
+  if (doc.errors.length > 0) {
+    codemodsDebug(`Failed to parse ${workflowPath}: ${doc.errors[0].message}. Skipping action bumps.`);
+    return { found: [], unrecognized: [] };
+  }
+
+  const found = new Set<string>();
+  const unrecognized = new Set<string>();
+  const edits: Array<{ start: number; end: number; text: string }> = [];
+
+  visit(doc, {
+    Pair: (_, pair) => {
+      if (!isScalar(pair.key) || pair.key.value !== 'uses' || !isScalar(pair.value)) {
+        return;
+      }
+      const uses = pair.value;
+      if (typeof uses.value !== 'string' || !uses.value.includes('@')) {
+        return;
+      }
+      const separator = uses.value.lastIndexOf('@');
+      const action = uses.value.slice(0, separator);
+      const ref = uses.value.slice(separator + 1);
+      const minimum = minimums.get(action);
+      if (!minimum) {
+        return;
+      }
+
+      found.add(action);
+      if (ref === 'main') {
+        return;
+      }
+      const tag = parseTag(action, ref);
+      if (!tag) {
+        codemodsDebug(`${workflowPath} pins ${action}@${ref}, which is not a version tag. Leaving it as-is.`);
+        unrecognized.add(action);
+        return;
+      }
+      if (meetsMinimum(tag.version, minimum.version)) {
+        codemodsDebug(`${workflowPath} already pins ${action}@${ref}. Skipping.`);
+        return;
+      }
+      if (!uses.range) {
+        return;
+      }
+      const [start, end] = uses.range;
+      edits.push({ start, end, text: content.slice(start, end).replace(`@${ref}`, `@${raisedRef(tag, minimum)}`) });
+    },
+  });
+
+  if (edits.length > 0) {
+    // apply from the end so earlier offsets stay valid
+    const updated = edits
+      .sort((a, b) => b.start - a.start)
+      .reduce((acc, { start, end, text }) => `${acc.slice(0, start)}${text}${acc.slice(end)}`, content);
+    context.updateFile(workflowPath, updated);
+  }
+  return { found: [...found], unrecognized: [...unrecognized] };
+}
+
+interface Tag {
+  /** The text before `v`, such as `build-plugin/`, or empty for a bare tag. */
+  prefix: string;
+  /** One to three numbers, fewer for a floating tag. */
+  version: number[];
+}
+
+// reads `vX[.Y[.Z]]`, or `<name>/vX[.Y[.Z]]` where name is the action's last path segment
+function parseTag(action: string, ref: string): Tag | undefined {
+  const match = /^(?:([^/]+)\/)?v(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(ref);
+  if (!match || (match[1] !== undefined && match[1] !== action.split('/').at(-1))) {
+    return undefined;
+  }
+  return {
+    prefix: match[1] === undefined ? '' : `${match[1]}/`,
+    version: match
+      .slice(2)
+      .filter((part) => part !== undefined)
+      .map(Number),
+  };
+}
+
+// compares only the numbers the tag has, since a floating tag runs the latest release below it
+function meetsMinimum(version: number[], minimum: number[]): boolean {
+  for (const [i, part] of version.entries()) {
+    const minimumPart = minimum[i] ?? 0;
+    if (part !== minimumPart) {
+      return part > minimumPart;
+    }
+  }
+  return true;
+}
+
+function raisedRef(tag: Tag, minimum: Tag): string {
+  const version = Array.from({ length: tag.version.length }, (_, i) => minimum.version[i] ?? 0);
+  return `${minimum.prefix}v${version.join('.')}`;
+}

package/src/utils/utils.cli.ts

@@ -13,6 +13,7 @@ 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`
@@ -20,7 +21,7 @@ export const argv = minimist(args, {
   // --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'],
+  string: ['agent', 'docsPath'],
 });
 
 export const commandName = argv._[0] || 'generate';

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/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/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

package/templates/docs/panel/docs/README.md

@@ -0,0 +1,20 @@
+# {{{pluginName}}} documentation
+
+This folder is the documentation for **{{{pluginName}}}**. It's published on the Documentation tab of
+`grafana.com/grafana/plugins/{{pluginId}}/` with each plugin release. This README isn't published.
+
+To learn how plugin docs work and how to write them, read the
+[Add documentation to your plugin](https://grafana.com/developers/plugin-tools/how-to-guides/plugin-docs) guide.
+
+## Next steps
+
+1. Write the pages. Each section has a note that says what belongs there. **Or** let an AI agent draft them from your source code and README: commit your changes, then run `{{createPluginCmd}} add docs-content`. Review its work either way.
+2. Add screenshots, videos and figures where they help readers. Save them inside this folder, for example in `img/`, and link to them with a relative path. `docs:validate` checks their formats and sizes.
+3. Run `{{packageManagerName}} run docs:serve` to preview the docs. It also lists every section left to fill.
+
+## Commands
+
+```bash
+{{packageManagerName}} run docs:serve     # local preview at http://localhost:3001
+{{packageManagerName}} run docs:validate  # check your docs, including sections left to fill
+```

package/templates/docs/panel/docs/data-formats.md

@@ -0,0 +1,27 @@
+---
+title: Data formats
+description: "Learn what data formats the {{{yamlEscape pluginName}}} panel accepts."
+sidebar_position: 2
+---
+
+This document explains the data the {{{pluginName}}} panel needs from a query, so you can build a matching query or check your test data.
+
+## Supported data shape
+
+<!-- section-brief
+Fill this in: Describe the data frame shape {{{pluginName}}} expects: time series with N numeric fields, table with specific columns, single numeric value, geographic coordinates, log lines, etc. Be specific about field types and structure, because this is the contract dashboard authors rely on when building queries for the panel. Name the required field types (time, number, string, boolean) and any minimum/maximum field counts. After each shape, add a `#### Example` table whose headers are the field names the panel reads, with 3-5 rows of realistic values, so a reader can build a matching query or test data.
+-->
+
+## Field mapping
+
+<!-- section-brief
+Fill this in: Explain which incoming field plays which role in the visualization - for example "the first time-typed field is the x-axis, all numeric fields become series". If {{{pluginName}}} lets users explicitly pick field roles in the editor, document those controls here. Remove the section if mapping is fully automatic and not user-configurable.
+-->
+
+## Check what your query returns
+
+To see the data the panel receives, open the panel editor, click **Query inspector** and select the **Data** tab. You can also turn on **Table view** at the top of the panel editor to see the data as a table.
+
+## Reshape data that doesn't match
+
+If a query returns data in a different shape, you can reshape it without changing the query. Select the **Transform data** tab in the panel editor and add a transformation. For more information, refer to [Transform data](https://grafana.com/docs/grafana/latest/panels-visualizations/query-transform-data/transform-data/).