@grafana/create-plugin 7.14.0 → 7.15.0

package/src/codemods/additions/scripts/docs.ts

@@ -19,6 +19,8 @@ import {
 } from '../../utils.agents.js';
 import { type BumpActionRefsResult, bumpActionRefs } from '../../utils.workflows.js';
 import { getPackageManagerExecCmd } from '../../../utils/utils.packageManager.js';
+import * as recast from 'recast';
+import * as babelTsParser from 'recast/parsers/babel-ts.js';
 
 // an allowlist, because the value becomes a path on disk and is embedded unescaped in a YAML workflow
 const DOCS_PATH_RE = /^[a-zA-Z0-9](?:[a-zA-Z0-9_-]|\/[a-zA-Z0-9_-])*$/;
@@ -57,7 +59,7 @@ type Options = v.InferOutput<typeof schema>;
 const PLUGIN_DOCS_CLI_VERSION = '^0.8.0';
 
 // each type needs a template set under `templates/docs/<type>/`
-const SUPPORTED_PLUGIN_TYPES = ['panel'] as const;
+const SUPPORTED_PLUGIN_TYPES = ['panel', 'datasource', 'app'] as const;
 type SupportedPluginType = (typeof SUPPORTED_PLUGIN_TYPES)[number];
 
 export default function docs(context: Context, options: Options): Context {
@@ -68,6 +70,8 @@ export default function docs(context: Context, options: Options): Context {
     // `templates/docs` is left out of TEMPLATE_PATHS so `generate` ignores it
     templateDir: join(TEMPLATES_DIR, 'docs', pluginType),
     commonTemplateDir: join(TEMPLATES_DIR, 'docs', 'common'),
+    featurePages: FEATURE_PAGES_BY_TYPE[pluginType],
+    pageStubs: pluginType === 'app' ? getAppFeaturePageStubs : undefined,
   });
 }
 
@@ -76,9 +80,23 @@ interface PluginJson {
   name?: string;
   id?: string;
   docsPath?: string;
+  annotations?: boolean;
+  alerting?: boolean;
+  includes?: PluginInclude[];
+  roles?: unknown;
+  iam?: unknown;
   [key: string]: unknown;
 }
 
+interface PluginInclude {
+  type?: string;
+  name?: string;
+  path?: string;
+  role?: string;
+  action?: string;
+  defaultNav?: boolean;
+}
+
 export interface DocsSetupOptions {
   context: Context;
   /** Falls back to the docsPath in `src/plugin.json`, then to `catalog-docs`. */
@@ -87,6 +105,35 @@ export interface DocsSetupOptions {
   templateDir: string;
   /** Templates shared by every plugin type, under `templates/docs/common/`. */
   commonTemplateDir: string;
+  /** Pages scaffolded only when `src/plugin.json` declares the feature they document. */
+  featurePages?: FeaturePage[];
+  /** Pages rendered from one template per entry, such as a page for each app page in `src/plugin.json`. */
+  /** Gets each feature page's `templateFlag`, so the stubs agree with the pages scaffolded for those features. */
+  pageStubs?: (pluginJson: PluginJson, featureFlags: Record<string, boolean>) => PageStubs;
+}
+
+interface FeaturePage {
+  /** Page name without `.md`. Plugin-docs-cli also accepts it as a folder of that name. */
+  page: string;
+  templateFlag: string;
+  hasFeature: (pluginJson: PluginJson, context: Context) => boolean;
+}
+
+interface PageStubs {
+  /** Rendered into the template data of every page, so the fixed pages can link to the stubs. */
+  data: Record<string, unknown>;
+  stubs: PageStub[];
+  /** Entries in `src/plugin.json` that get no page, as `name (path)`. */
+  skipped: string[];
+}
+
+interface PageStub {
+  templatePath: string;
+  /** Relative to the docs folder. */
+  file: string;
+  /** Set for a page of the app, which a re-run finds in either layout and as a file or a folder. */
+  slug?: string;
+  data: Record<string, unknown>;
 }
 
 export function setupDocsScaffolding(opts: DocsSetupOptions): Context {
@@ -128,6 +175,13 @@ export function setupDocsScaffolding(opts: DocsSetupOptions): Context {
   }
 
   const templateData = getTemplateDataFromContext(context);
+  const featurePages = (opts.featurePages ?? []).map(({ page, templateFlag, hasFeature }) => ({
+    page,
+    templateFlag,
+    isEnabled: hasFeature(pluginJson, context),
+  }));
+  const featureFlags = Object.fromEntries(featurePages.map(({ templateFlag, isEnabled }) => [templateFlag, isEnabled]));
+  const pageStubs = opts.pageStubs?.(pluginJson, featureFlags) ?? { data: {}, stubs: [], skipped: [] };
   const { packageManagerName, packageManagerVersion } = templateData;
   const createPluginCmd = `${getPackageManagerExecCmd(packageManagerName, packageManagerVersion)}@latest`;
   const data = {
@@ -136,6 +190,8 @@ export function setupDocsScaffolding(opts: DocsSetupOptions): Context {
     docsPath,
     createPluginCmd,
     lockFile: LOCK_FILES[packageManagerName],
+    ...featureFlags,
+    ...pageStubs.data,
   };
 
   addDependenciesToPackageJson(context, {}, { '@grafana/plugin-docs-cli': PLUGIN_DOCS_CLI_VERSION });
@@ -144,12 +200,24 @@ export function setupDocsScaffolding(opts: DocsSetupOptions): Context {
 
   // pages are only rendered into a folder without any, so pages the author deleted stay deleted
   const hasPages = hasDocsPages(context, docsPath);
+  const disabledPageFiles = featurePages.filter(({ isEnabled }) => !isEnabled).map(({ page }) => `${page}.md`);
   addTemplateFolder(context, {
     folderPath: join(templateDir, 'docs'),
     targetPath: docsPath,
     data,
-    include: (file) => !hasPages || SCAFFOLD_META_FILES.includes(file),
+    include: (file) => SCAFFOLD_META_FILES.includes(file) || (!hasPages && !disabledPageFiles.includes(file)),
   });
+  const report: PageReport = {
+    missingPageStubs: scaffoldPageStubs({ context, docsPath, stubs: pageStubs.stubs, data, hasPages }),
+    // a feature turned on after the first scaffold gets no page, so point the author at it instead
+    missingFeaturePages: hasPages
+      ? featurePages
+          .filter(({ page, isEnabled }) => isEnabled && !pageExists(context, docsPath, [page]))
+          .map(({ page }) => `${page}.md`)
+      : [],
+    // a re-run has no pages to compare against, so it only reports what the first scaffold left out
+    skippedPages: hasPages ? [] : pageStubs.skipped,
+  };
 
   // left alone when it exists, since the author may have customized it
   const workflowPath = '.github/workflows/validate-docs.yml';
@@ -166,24 +234,78 @@ export function setupDocsScaffolding(opts: DocsSetupOptions): Context {
   ensureConfigAgentFiles(context, TEMPLATE_PATHS.common, CONFIG_AGENT_FILES, data);
   appendDocsPointerToInstructions(context, docsPath);
 
-  // deferred so it prints after the runner's change list, and only when something changed
-  if (context.hasChanges()) {
+  // deferred so it prints after the runner's change list, and only when there is something to report
+  if (context.hasChanges() || report.missingFeaturePages.length > 0 || report.missingPageStubs.length > 0) {
     context.setMessage(
-      buildNextStepsMessage({ docsPath, packageManagerName, createPluginCmd, pluginActions, linkedRootFiles })
+      buildNextStepsMessage({ docsPath, packageManagerName, createPluginCmd, pluginActions, linkedRootFiles, report })
     );
   }
 
   return context;
 }
 
+interface PageReport {
+  /** Feature pages that plugin.json declares and the docs folder doesn't have, as `<page>.md`. */
+  missingFeaturePages: string[];
+  /** Pages from `pageStubs` that the docs folder doesn't have, as paths. */
+  missingPageStubs: string[];
+  /** Entries in plugin.json that got no page on the first scaffold, with the reason. */
+  skippedPages: string[];
+}
+
+// a page counts as there as a file or as a folder, so authors can turn a page into a folder
+function pageExists(context: Context, docsPath: string, pageNames: string[]): boolean {
+  return pageNames.some(
+    (name) => context.doesFileExist(`${docsPath}/${name}.md`) || context.doesFileExist(`${docsPath}/${name}`)
+  );
+}
+
+/**
+ * Renders each stub into a docs folder that has no pages yet. When the folder has pages it adds nothing and
+ * returns the stubs it doesn't have, so a page the author deleted stays deleted.
+ */
+function scaffoldPageStubs(opts: {
+  context: Context;
+  docsPath: string;
+  stubs: PageStub[];
+  data: Record<string, unknown>;
+  hasPages: boolean;
+}): string[] {
+  const { context, docsPath, stubs, data, hasPages } = opts;
+  const missingPages: string[] = [];
+  const missingIndexes: string[] = [];
+  for (const stub of stubs) {
+    const filePath = `${docsPath}/${stub.file}`;
+    if (hasPages) {
+      // the author may have moved the pages between the root and features/ since the first scaffold
+      if (stub.slug !== undefined) {
+        if (!pageExists(context, docsPath, [stub.slug, `features/${stub.slug}`])) {
+          missingPages.push(filePath);
+        }
+      } else if (!context.doesFileExist(filePath)) {
+        missingIndexes.push(filePath);
+      }
+    } else if (context.doesFileExist(filePath)) {
+      additionsDebug(`${filePath} already exists, skipping`);
+    } else {
+      context.addFile(filePath, renderTemplate(stub.templatePath, false, { ...data, ...stub.data }));
+    }
+  }
+  // the message names the first one, and a page tells the author more than a folder index
+  const missing = [...missingPages, ...missingIndexes];
+  return missing;
+}
+
 function buildNextStepsMessage(opts: {
   docsPath: string;
   packageManagerName: string;
   createPluginCmd: string;
   pluginActions: BumpActionRefsResult;
   linkedRootFiles: string[];
+  report: PageReport;
 }): ContextMessage {
   const { docsPath, packageManagerName, createPluginCmd, pluginActions, linkedRootFiles } = opts;
+  const { missingFeaturePages, missingPageStubs, skippedPages } = opts.report;
   const run = (script: string) => output.formatCode(`${packageManagerName} run ${script}`);
 
   const steps: NextStep[] = [
@@ -219,6 +341,24 @@ function buildNextStepsMessage(opts: {
       detail: `Docs need ${REQUIRED_ACTION_REFS[action]} or later.`,
     });
   }
+  for (const page of missingFeaturePages) {
+    warnings.push({
+      title: `src/plugin.json declares the feature ${docsPath}/${page} documents, but the page doesn't exist`,
+      detail: `If it needs docs, add the page as described under Optional pages in ${docsPath}/AGENTS.md. If you deleted it on purpose, ignore this.`,
+    });
+  }
+  if (missingPageStubs.length > 0) {
+    warnings.push({
+      title: `src/plugin.json has pages with no docs page, such as ${missingPageStubs[0]}`,
+      detail: `If they need docs, add them as described under Optional pages in ${docsPath}/AGENTS.md. If you deleted them on purpose, ignore this.`,
+    });
+  }
+  if (skippedPages.length > 0) {
+    warnings.push({
+      title: `Left out of the docs: ${skippedPages.join(', ')}`,
+      detail: `If they need docs, add them as described under Optional pages in ${docsPath}/AGENTS.md.`,
+    });
+  }
   for (const file of linkedRootFiles) {
     warnings.push({
       title: `Added a pointer to ${AGENT_INSTRUCTIONS_PATH} at the end of ${file}`,
@@ -251,11 +391,6 @@ export function assertSupportedPluginType(context: Context, additionName = 'docs
   }
 
   const supported = SUPPORTED_PLUGIN_TYPES.join(', ');
-  if (type === 'app' || type === 'datasource') {
-    throw new Error(
-      `create-plugin add ${additionName} does not support '${type}' plugins yet. Supported so far: ${supported}.`
-    );
-  }
   throw new Error(
     `create-plugin add ${additionName} needs a plugin type of ${supported} in src/plugin.json, but found '${type ?? 'unset'}'.`
   );
@@ -269,6 +404,215 @@ function isSupportedPluginType(type: string | undefined): type is SupportedPlugi
 const CONFIG_AGENT_FILES = ['instructions.md', 'e2e-testing.md'];
 // the scaffold's files that aren't pages, so they're added on every run
 const SCAFFOLD_META_FILES = ['README.md', 'AGENTS.md', 'CLAUDE.md'];
+const DASHBOARDS_PAGE: FeaturePage = {
+  page: 'dashboards',
+  templateFlag: 'hasDashboards',
+  hasFeature: (p) => getIncludes(p).some((i) => i.type === 'dashboard'),
+};
+const FEATURE_PAGES_BY_TYPE: Record<SupportedPluginType, FeaturePage[]> = {
+  panel: [],
+  datasource: [
+    { page: 'annotations', templateFlag: 'hasAnnotations', hasFeature: (p) => p.annotations === true },
+    { page: 'alerting', templateFlag: 'hasAlerting', hasFeature: (p) => p.alerting === true },
+    DASHBOARDS_PAGE,
+  ],
+  app: [
+    { page: 'configure', templateFlag: 'hasConfigPage', hasFeature: hasAppConfigPage },
+    DASHBOARDS_PAGE,
+    {
+      page: 'permissions',
+      templateFlag: 'hasPermissions',
+      hasFeature: (p) =>
+        p.roles !== undefined ||
+        p.iam !== undefined ||
+        getIncludes(p).some((i) => (i.role !== undefined && i.role !== 'Viewer') || i.action !== undefined),
+    },
+  ],
+};
+
+function getIncludes(pluginJson: PluginJson): PluginInclude[] {
+  return Array.isArray(pluginJson.includes)
+    ? pluginJson.includes.filter((i): i is PluginInclude => typeof i === 'object' && i !== null)
+    : [];
+}
+
+// app page paths may use the %PLUGIN_ID% placeholder that the build replaces
+function isAppPath(path: string | undefined, pluginId: string | undefined, prefix: string): boolean {
+  return [pluginId, '%PLUGIN_ID%'].some(
+    (id) => id && (path === `${prefix}${id}` || path?.startsWith(`${prefix}${id}/`))
+  );
+}
+
+const APP_MODULE_FILES = ['src/module.ts', 'src/module.tsx', 'src/module.js', 'src/module.jsx'];
+
+function hasAppConfigPage(pluginJson: PluginJson, context: Context): boolean {
+  return (
+    APP_MODULE_FILES.some((file) => callsAddConfigPage(context.getFile(file))) ||
+    getIncludes(pluginJson).some((i) => i.type === 'page' && isAppPath(i.path, pluginJson.id, '/plugins/'))
+  );
+}
+
+function callsAddConfigPage(source: string | undefined): boolean {
+  if (!source) {
+    return false;
+  }
+  // babel-ts parses JSX as well as TypeScript, since app modules are often .tsx
+  let ast: recast.types.ASTNode;
+  try {
+    ast = recast.parse(source, { parser: babelTsParser });
+  } catch (error) {
+    additionsDebug(`Failed to parse the app module, so it can't tell whether it has a config page: ${error}`);
+    return false;
+  }
+  let isFound = false;
+  recast.visit(ast, {
+    visitCallExpression(path) {
+      const { callee } = path.node;
+      if (
+        callee.type === 'MemberExpression' &&
+        callee.property.type === 'Identifier' &&
+        callee.property.name === 'addConfigPage'
+      ) {
+        isFound = true;
+        return false;
+      }
+      this.traverse(path);
+      return undefined;
+    },
+  });
+  return isFound;
+}
+
+// the example pages templates/app/src/plugin.json ships, which only document the scaffold
+const TEMPLATE_DEFAULT_PAGES: Record<string, string> = {
+  'Page One': '/one',
+  'Page Two': '/two',
+  'Page Three': '/three',
+  'Page Four': '/four',
+};
+
+const CONFIG_PAGE_SLUGS = ['configuration', 'configure'];
+
+interface AppFeaturePage {
+  name: string;
+  slug: string;
+  path: string;
+  role?: string;
+}
+
+// pages under /plugins/ are the config page and pages under /d/ link to a bundled dashboard, so neither gets a page
+function getAppFeaturePages(
+  pluginJson: PluginJson,
+  hasConfigPage: boolean
+): { pages: AppFeaturePage[]; configPage?: AppFeaturePage; skipped: string[] } {
+  const pages: AppFeaturePage[] = [];
+  let configPage: AppFeaturePage | undefined;
+  const skipped: string[] = [];
+  const appPages = getIncludes(pluginJson)
+    .filter((i) => i.type === 'page' && typeof i.name === 'string' && isAppPath(i.path, pluginJson.id, '/a/'))
+    .sort((a, b) => Number(b.defaultNav === true) - Number(a.defaultNav === true));
+  const takenSlugs = new Set(getReservedPageSlugs());
+  for (const include of appPages) {
+    const name = include.name as string;
+    const path = (include.path as string).replaceAll('%PLUGIN_ID%', pluginJson.id ?? '');
+    const defaultPath = TEMPLATE_DEFAULT_PAGES[name];
+    if (defaultPath !== undefined && path.endsWith(defaultPath)) {
+      additionsDebug(`${name} is an example page from the create-plugin app template, skipping`);
+      skipped.push(`${name} (${include.path}, an example page from the create-plugin app template)`);
+      continue;
+    }
+    const slug = slugify(name);
+    if (!slug) {
+      additionsDebug(`${name} has no letters or digits for a file name, skipping`);
+      skipped.push(`${name} (${include.path}, its name has no letters or digits for a file name)`);
+      continue;
+    }
+    // Viewer is the lowest role, so a page that needs only that has nothing to tell the reader
+    const role = typeof include.role === 'string' && include.role !== 'Viewer' ? include.role : undefined;
+    // an in-app page named like the config page takes its place, the way data sources name it
+    if (!hasConfigPage && !configPage && CONFIG_PAGE_SLUGS.includes(slug)) {
+      configPage = { name, slug: 'configure', path, role };
+      continue;
+    }
+    if (takenSlugs.has(slug)) {
+      additionsDebug(`${name} would be written to ${slug}.md, which another page uses, skipping`);
+      skipped.push(`${name} (${include.path}, its file name is used by another page)`);
+      continue;
+    }
+    takenSlugs.add(slug);
+    pages.push({ name, slug, path, role });
+  }
+  return { pages, configPage, skipped };
+}
+
+function slugify(name: string): string {
+  return name
+    .normalize('NFKD')
+    .replace(/\p{M}/gu, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+// more app pages than this go in a features/ folder, so a small app has no folder with one page in it
+const MAX_FLAT_PAGES = 3;
+// the root pages that come before the app pages, which take the positions after it
+const FIRST_PAGE_POSITION = 3;
+const CONFIG_PAGE_POSITION = 2;
+const FIXED_PAGE_SLUGS = ['index', 'configure', 'dashboards', 'permissions', 'troubleshooting'];
+
+// file names an app page can't take, because another page or plugin-docs-cli uses them
+function getReservedPageSlugs(): string[] {
+  return [
+    ...FIXED_PAGE_SLUGS,
+    ...DOCS_CLI_META_FILES.map((file) => file.slice(0, -'.MD'.length).toLowerCase().replaceAll('_', '-')),
+  ];
+}
+
+function getAppFeaturePageStubs(pluginJson: PluginJson, featureFlags: Record<string, boolean>): PageStubs {
+  const { pages, configPage, skipped } = getAppFeaturePages(pluginJson, featureFlags.hasConfigPage === true);
+  const templateDir = join(TEMPLATES_DIR, 'docs', 'app');
+  const pageTemplate = join(templateDir, 'feature-page.md');
+  const stubs: PageStub[] = [];
+  if (configPage) {
+    stubs.push({
+      templatePath: pageTemplate,
+      file: 'configure.md',
+      slug: 'configure',
+      data: { page: { ...configPage, position: CONFIG_PAGE_POSITION } },
+    });
+  }
+
+  const isInFolder = pages.length > MAX_FLAT_PAGES;
+  const folder = isInFolder ? 'features/' : '';
+  if (isInFolder) {
+    stubs.push({
+      templatePath: join(templateDir, 'features-index.md'),
+      file: 'features/index.md',
+      data: { position: FIRST_PAGE_POSITION },
+    });
+  }
+  // plugin-docs-cli compares a folder's index.md with the pages inside it, so these start after it
+  const firstPosition = isInFolder ? FIRST_PAGE_POSITION + 1 : FIRST_PAGE_POSITION;
+  pages.forEach((page, i) => {
+    stubs.push({
+      templatePath: pageTemplate,
+      file: `${folder}${page.slug}.md`,
+      slug: page.slug,
+      data: { page: { ...page, position: firstPosition + i } },
+    });
+  });
+
+  return {
+    data: {
+      ...(configPage ? { hasConfigPage: true } : {}),
+      ...(pages.length > 0 ? { defaultFeaturePage: { ...pages[0], file: `${folder}${pages[0].slug}` } } : {}),
+    },
+    stubs,
+    skipped,
+  };
+}
+
 // mirrors isMetaFile in @grafana/plugin-docs-cli, so both tools agree on what counts as a page
 const DOCS_CLI_META_FILES = [
   'README.MD',

package/templates/docs/app/docs/AGENTS.md

@@ -0,0 +1,127 @@
+# 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
+
+`configure.md`, the app pages, `dashboards.md` and `permissions.md` exist only when the app has that feature,
+as described under [Optional pages](#optional-pages). An app with up to three pages has one file for each at
+the root. With more, the pages move into a `features/` folder.
+
+Files may have moved since the plugin was scaffolded, so trace them from `src/module.ts(x)`.
+`new AppPlugin()` names the root page component in `setRootPage` and each config page component in
+`addConfigPage`. The root page component routes each path in `src/plugin.json` to the component that
+renders it. `src/plugin.json` only lists the pages in the app's navigation, so look for tabs and drilldowns
+in those components too.
+
+| Page                 | Source of truth                                                                                                                                                                                                               |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `index.md`           | `dependencies` in `src/plugin.json`, the setup sections of the README and `provisioning/`. Update the links when pages are added or removed.                                                                                  |
+| `configure.md`       | The components passed to `addConfigPage` and the settings type, including `jsonData` and `secureJsonData`, or the in-app page named Configuration when the app has no `addConfigPage`. With a backend, also how it reads them |
+| `features/index.md`  | Nothing - it is a curated router for the pages in `features/`, if the folder exists. Update it when pages are added or removed.                                                                                               |
+| App pages            | The component the root page routes the page's path to. Screenshots from `info.screenshots` in `src/plugin.json` whose name matches the page                                                                                   |
+| `dashboards.md`      | `includes` entries of type `dashboard` in `src/plugin.json` and their JSON files                                                                                                                                              |
+| `permissions.md`     | `roles`, `iam` and the `role` and `action` of each `includes` entry in `src/plugin.json`                                                                                                                                      |
+| `troubleshooting.md` | Error and empty-state messages in source, known issues in the README or other docs and reported issues. Never guess failures                                                                                                  |
+
+## Optional pages
+
+Add one of these pages when the app 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                                                                                                                                                                                    |
+| ---------------------------------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `addConfigPage` in `src/module.ts(x)`                                  | `configure.md`   | Opening the config page, every setting and provisioning the app.                                                                                                                         |
+| An app page named Configuration, when there is no `addConfigPage`      | `configure.md`   | What the page is for and how to use it, as for any app page.                                                                                                                             |
+| An `includes` entry of type `page` with a path under `/a/{{pluginId}}` | App page         | What the page is for and how to use it. Copy an existing app page, and link it from `index.md`. With a fourth page, move them all into `features/` and list them in `features/index.md`. |
+| An `includes` entry of type `dashboard`                                | `dashboards.md`  | What each bundled dashboard shows and how to import it.                                                                                                                                  |
+| `roles` or `iam` in `src/plugin.json`                                  | `permissions.md` | What each role grants, default assignments and what the app can access.                                                                                                                  |
+
+When an app page grows too long, turn it into a folder of the same name with an `index.md` and
+split it into pages there. Keep every page within three folder levels of this one.
+
+## What not to write
+
+Never write installation instructions, such as installing the plugin with `grafana-cli`, from a zip file or
+in Docker. The Installation tab on the plugin page covers them, and these docs start from a plugin that is
+already installed. When the README has an installation section, leave it out of the pages.
+
+## 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
+## Connect your data
+
+<!-- section-brief
+Fill this in: The steps to get the data the app shows into Grafana.
+
+If the app needs no data of its own, remove this section entirely.
+-->
+```
+
+Some sections also have fixed text, with a brief that builds on it:
+
+```markdown
+## Open the configuration page
+
+To open the {{{pluginName}}} configuration page:
+
+1. Click **Administration** > **Plugins and data** > **Plugins** in the left-side menu.
+
+<!-- section-brief
+Fill this in: After the list above, add a sentence that names the tab to click.
+-->
+```
+
+Text outside a brief is written for every app 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/app/docs/CLAUDE.md

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

package/templates/docs/app/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
+```