@grafana/create-plugin 7.13.0 → 7.15.0

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

package/templates/docs/app/docs/configure.md

@@ -0,0 +1,65 @@
+---
+title: Configure
+description: "Change the {{{yamlEscape pluginName}}} settings in Grafana or provision them as code."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - app
+  - configuration
+  - provisioning
+sidebar_position: 2
+---
+
+This document explains how to configure {{{pluginName}}} after you enable it.
+
+## Before you begin
+
+Before you configure the app, ensure you have:
+
+- **Grafana permissions:** The `Organization administrator` role. Only organization administrators can configure apps.
+- **The app enabled:** Follow [Enable the app](./index.md#enable-the-app).
+
+## Open the configuration page
+
+To open the {{{pluginName}}} configuration page:
+
+1. Click **Administration** > **Plugins and data** > **Plugins** in the left-side menu.
+1. Enter `{{{pluginName}}}` in the search bar.
+1. Select **{{{pluginName}}}**.
+
+<!-- section-brief
+Fill this in: After the list above, add one sentence that names the tab to click, using the `title` of the page passed to `addConfigPage` in `src/module.ts(x)`, such as "Then click the **Configuration** tab." Keep it a sentence rather than another step of the list. If the app adds more than one config page, name each tab and what it holds.
+-->
+
+## Configure settings
+
+<!-- section-brief
+Fill this in: An H3 for each section of the config page, named and ordered as the page shows them, such as Connection, Authentication or Features. Under each H3, a table with this shape:
+
+| Setting | Description | Required |
+| ------- | ----------- | -------- |
+
+Use the field labels from the config page, in bold. If the config page has no settings of its own, such as when it only turns the app on or off, say so in one sentence and document what its buttons do instead of a table. Find the settings in the components passed to `addConfigPage` and the settings type, including `jsonData` and `secureJsonData`. In a description, say when a field only appears for some choice and when it affects another setting. Use a `> [!NOTE]` callout for a setting that's only available in Grafana Cloud or Grafana Enterprise.
+
+End with the button that saves the settings and what the reader sees when it works.
+-->
+
+## Provision the app
+
+You can provision {{{pluginName}}} as code with a Grafana provisioning file. For more information, refer to [Provision Grafana](https://grafana.com/docs/grafana/latest/administration/provisioning/#plugins).
+
+<!-- section-brief
+Fill this in: A YAML example with this shape, using the real `jsonData` and `secureJsonData` keys from the settings type and placeholders for every value the reader must supply, such as `<API_URL>`:
+
+```yaml
+apiVersion: 1
+
+apps:
+  - type: {{pluginId}}
+    org_id: 1
+    disabled: false
+    jsonData: {}
+    secureJsonData: {}
+```
+
+Follow it with a table of the keys it uses and what each one sets, and list each placeholder with what to replace it with. If `provisioning/plugins/` has a file for the app, base the example on it.
+-->

package/templates/docs/app/docs/dashboards.md

@@ -0,0 +1,29 @@
+---
+title: Dashboards
+description: "Import and use the dashboards that ship with {{{yamlEscape pluginName}}}."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - app
+  - dashboards
+sidebar_position: 6
+---
+
+{{{pluginName}}} ships with ready-made dashboards that you can import and use as they are, or as a starting point for your own. For general information about dashboards, refer to [Dashboards](https://grafana.com/docs/grafana/latest/dashboards/).
+
+## Import a dashboard
+
+To import a dashboard that ships with {{{pluginName}}}:
+
+1. Click **Administration** > **Plugins and data** > **Plugins** in the left-side menu.
+1. Enter `{{{pluginName}}}` in the search bar.
+1. Select **{{{pluginName}}}**.
+1. Click the **Dashboards** tab.
+1. Click **Import** next to the dashboard.
+
+Imported dashboards don't update when you upgrade the plugin. When a plugin upgrade ships a newer version of a dashboard, click **Update** next to it. This overwrites any changes you made to it.
+
+## Included dashboards
+
+<!-- section-brief
+Fill this in: One H3 per dashboard in the `includes` list of `src/plugin.json` whose `type` is `dashboard`, using its `name`. For each one, describe what it shows and what data or settings it needs to work, based on the panels and queries in its JSON file. When the app ships many dashboards, group related ones under a shared H3 and list them, rather than repeating the same description.
+-->

package/templates/docs/app/docs/index.md

@@ -0,0 +1,70 @@
+---
+title: Introduction
+description: "Set up {{{yamlEscape pluginName}}} and find what to read next in the docs."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - app
+  - setup
+sidebar_position: 1
+---
+
+<!-- section-brief
+Fill this in: Write a short orientation for someone who already has {{{pluginName}}} installed and landed here from the Documentation tab. One or two sentences on what this section covers and how it's organized. Do not restate what the app does or its feature list - that's the README's job on the Overview tab, and this reader has already seen it there. Do not list every page in this folder either - the sidebar already does that; use prose to say what to read first and why.
+-->
+
+## Before you begin
+
+Before you set up the app, ensure you have:
+
+- **Grafana permissions:** The `Organization administrator` role. Only organization administrators can enable and configure apps.
+
+<!-- section-brief
+Fill this in: Keep the list above. Add a bullet in the same **Label:** form for each other thing the reader needs: the Grafana version from `dependencies.grafanaDependency` in `src/plugin.json`, each plugin in `dependencies.plugins` linked to its catalog page at `https://grafana.com/grafana/plugins/<id>/`, and anything `src/plugin.json` doesn't declare, such as an external service, a telemetry pipeline or a license. Never cover installing the plugin itself, because the Installation tab on the plugin page owns it.
+-->
+
+## Enable the app
+
+To enable {{{pluginName}}}:
+
+1. Click **Administration** > **Plugins and data** > **Plugins** in the left-side menu.
+1. Enter `{{{pluginName}}}` in the search bar.
+1. Select **{{{pluginName}}}**.
+1. Click **Enable**.
+
+<!-- section-brief
+Fill this in: If `src/plugin.json` sets `"autoEnabled": true`, the app is enabled when it's installed, so remove this section. Otherwise keep the steps above and remove only this brief.
+-->
+{{#if hasConfigPage}}
+
+After you enable the app, refer to [Configure](./configure.md) for its settings.
+{{/if}}
+
+## Connect your data
+
+<!-- section-brief
+Fill this in: The steps to get the data the app shows into Grafana, such as adding a data source, setting up an agent, setting environment variables or configuring a telemetry exporter. Take them from the README's setup sections and from what the app queries in source. Give each step the commands or settings to copy, and say how the reader can tell the data has arrived. Change the heading if necessary to name the task, such as "Add a data source". Never include steps to install the plugin itself, because the Installation tab on the plugin page owns them.
+
+If the app works without any setup of its own, remove this section entirely.
+-->
+
+## Common tasks
+
+<!-- section-brief
+Fill this in: List the jobs someone lands here to do, phrased as tasks rather than page titles, each linked to the page that answers it. For a typical app this might look like:
+
+{{#if hasConfigPage}}
+- [Change the app settings](./configure.md)
+{{/if}}
+{{#if defaultFeaturePage}}
+- [Find your way around {{{defaultFeaturePage.name}}}](./{{defaultFeaturePage.file}}.md)
+{{/if}}
+{{#if hasDashboards}}
+- [Import the dashboards that ship with the app](./dashboards.md)
+{{/if}}
+{{#if hasPermissions}}
+- [Give users access to the app](./permissions.md)
+{{/if}}
+- [Fix setup and data errors](./troubleshooting.md)
+
+Adapt this to {{{pluginName}}}'s actual entry points - add, remove or reword tasks so each one matches a real job a user comes here to do. This is a curated set of jobs, not a mechanical list of every file in this folder.
+-->

package/templates/docs/app/docs/permissions.md

@@ -0,0 +1,45 @@
+---
+title: Permissions
+description: "The roles {{{yamlEscape pluginName}}} adds and the access it needs."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - app
+  - permissions
+  - RBAC
+sidebar_position: 7
+---
+
+This document explains who can use each part of {{{pluginName}}} and what the app can access. For general information, refer to [Role-based access control for app plugins](https://grafana.com/docs/grafana/latest/administration/roles-and-permissions/access-control/rbac-for-app-plugins/).
+
+## Roles
+
+<!-- section-brief
+Fill this in: A table with one row per entry in `roles` in `src/plugin.json`:
+
+| Role | Description | Granted by default to |
+| ---- | ----------- | --------------------- |
+
+Use the role's display name, or its name if it has none, and take the defaults from `grants`. After the table, say what each role lets a user do in the app, in terms of its pages and actions rather than the raw permission names.
+
+If `src/plugin.json` has no `roles`, remove this section and Assign a role below.
+-->
+
+## Page access
+
+<!-- section-brief
+Fill this in: A table of the app pages that need more than the `Viewer` role, with the role or permission each one needs, from the `role` and `action` of each `includes` entry in `src/plugin.json`. Link each page to its docs page.
+
+If no `includes` entry sets `role` or `action`, remove this section.
+-->
+
+## What the app can access
+
+<!-- section-brief
+Fill this in: A table of the permissions in `iam.permissions` in `src/plugin.json`, with the action, the scope and why the app needs it, based on what the backend does with that access. Administrators read this before they install the app, so be precise.
+
+If `src/plugin.json` has no `iam`, remove this section.
+-->
+
+## Assign a role
+
+To assign a role to a user, team or service account, refer to [Assign RBAC roles](https://grafana.com/docs/grafana/latest/administration/roles-and-permissions/access-control/assign-rbac-roles/).

package/templates/docs/app/docs/troubleshooting.md

@@ -0,0 +1,65 @@
+---
+title: Troubleshooting
+description: "Troubleshoot common {{{yamlEscape pluginName}}} setup, data and access errors."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - app
+  - troubleshooting
+sidebar_position: 8
+---
+
+This page explains how to fix common issues when you set up or use {{{pluginName}}}. For setup instructions, refer to the [Introduction](./index.md).
+
+<!-- section-brief
+Fill this in: Never guess failures. Each symptom must come from an error or empty-state message in source, a known issue in the README or other docs or a reported issue. When source holds only a few real failures, a short page is right, so don't pad it.
+
+Replace this brief with one H2 per category that has real failures, in this order:
+
+- `## Setup errors`: the app won't enable, or its settings don't save or don't connect.
+- `## Missing data`: pages that load but show no data, linking to the setup steps in the [Introduction](./index.md).
+{{#if hasPermissions}}
+- `## Permission errors`: users who can't see a page or an action, linking to [Permissions](./permissions.md).
+{{/if}}
+- `## Performance issues`: slow pages, timeouts or rate limits, and the settings that help.
+
+Add an H2 for another part of the app with real failures, named after that part.
+
+Open each H2 with one sentence on when its errors occur. Add an H3 per symptom, named after the error message in quotes, such as `### "Failed to load services"`, then **Symptoms:** and a **Possible causes and solutions:** table, or a numbered **Solutions:** list for a single cause.
+-->
+
+## Get more detail about an error
+
+For errors in the app, open the developer tools in your browser and check the console.
+{{#if hasBackend}}
+
+In self-managed Grafana, you can also find more detail in the Grafana server logs:
+
+1. Set the log level to `debug` in the Grafana configuration file:
+
+   ```ini
+   [log]
+   level = debug
+   ```
+
+1. Restart Grafana and reproduce the error.
+1. Look for log lines with `logger=plugin.{{{pluginId}}}`.
+1. Set the log level back to `info` when you're done, to keep the logs small.
+{{/if}}
+
+## Get additional help
+
+If this page doesn't solve your problem:
+
+- Search the [Grafana community forums](https://community.grafana.com/).
+- If your Grafana Cloud or Grafana Enterprise plan includes support, contact Grafana Support.
+
+<!-- section-brief
+Fill this in: Add links to the plugin's issue tracker and the docs of any service the app depends on to the list above.
+-->
+
+When you report an issue, include:
+
+- The Grafana and plugin versions.
+- The error message, with sensitive information removed.
+- The steps to reproduce the issue.
+- The app page where it happens and the relevant app settings, with credentials removed.

package/templates/docs/app/feature-page.md

@@ -0,0 +1,26 @@
+---
+title: "{{{yamlEscape page.name}}}"
+description: "Use the {{{yamlEscape page.name}}} page in {{{yamlEscape pluginName}}}."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - "{{{yamlEscape page.name}}}"
+sidebar_position: {{page.position}}
+---
+
+<!-- section-brief
+Fill this in: One or two sentences on what the {{{page.name}}} page is for and when someone opens it. The app shows it at `{{{page.path}}}`. Pair it with a screenshot of the page if `info.screenshots` in `src/plugin.json` has one.
+-->
+{{#if page.role}}
+
+## Before you begin
+
+- **Grafana permissions:** At least the `{{page.role}}` role.
+
+<!-- section-brief
+Fill this in: Keep the bullet above. Add a bullet in the same **Label:** form only for something the reader needs before they can use this page and wouldn't guess, such as a feature flag that must be on or data that must exist. Never repeat setup from the Introduction or from another page, and don't link back to them. If this section would only point at another page, it adds nothing, so remove it, including its heading and the bullet above.
+-->
+{{/if}}
+
+<!-- section-brief
+Fill this in: Replace this brief with one H2 per task someone does on the {{{page.name}}} page, named after the task, such as "Filter by service" or "Compare two time ranges". Under each, give the steps with the UI labels in bold, and say what each part of the page shows when it helps the task. Find the tasks in the component that renders `{{{page.path}}}`, including its tabs and drilldowns, which `src/plugin.json` doesn't list. Describe UI that only appears behind a feature flag or a condition as "when X is enabled".
+-->

package/templates/docs/app/features-index.md

@@ -0,0 +1,12 @@
+---
+title: Features
+description: "What each part of {{{yamlEscape pluginName}}} is for."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - app
+sidebar_position: {{position}}
+---
+
+<!-- section-brief
+Fill this in: One line per page in this folder, in the order the app's navigation shows them, each linked to its page and saying what the reader does there. This is a router, so keep the detail on the pages themselves.
+-->