docs(plugin-docs-cli): document validation rules for plugin authors

[sunker]

What this PR does / why we need it:

This PR adds docs/validation-rules.md, a reference table of every rule plugin-docs-cli's validate/serve commands check, written for the plugin author reading it rather than someone reading the source. It's linked from README.md, and AGENTS.md/CLAUDE.md instruct agents to keep the table in sync with src/validation/rules/*.ts going forward.

Which issue(s) this PR fixes:

Fixes #

Special notes for your reviewer:

These docs document some rules that are not in the source code in this pr- they're being added in this PR though.

[Copilot]

🟡 Changes recommended

The new validation rules reference contains broken Markdown table formatting and documents several rule IDs/behaviors that do not match the current plugin-docs-cli implementation.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds author-facing documentation for @grafana/plugin-docs-cli validation behavior, and wires it into the package docs and agent guidance so future rule changes keep the reference up to date.

Changes:

• Add docs/validation-rules.md, a rule-by-rule reference for plugin authors.
• Link the new reference from packages/plugin-docs-cli/README.md.
• Add package-specific agent guidance (AGENTS.md) and a CLAUDE.md pointer.

File summaries

File	Description
packages/plugin-docs-cli/README.md	Links to the new validation rules reference from the CLI README.
packages/plugin-docs-cli/docs/validation-rules.md	Introduces a categorized table of validation rules and their severities.
packages/plugin-docs-cli/CLAUDE.md	Points Claude guidance to the package AGENTS.md.
packages/plugin-docs-cli/AGENTS.md	Documents the expectation to keep the rule reference in sync with src/validation/rules/*.ts / src/validation/types.ts.

Review details

Suppressed comments (6)

packages/plugin-docs-cli/docs/validation-rules.md:43

• This table currently includes frontmatter-title-length and frontmatter-description-length, but those rule IDs don't exist in src/validation/types.ts (and there are no corresponding checks in src/validation/rules/frontmatter.ts). The extra leading || also creates an unintended empty column in Markdown.

| Rule                             | What it checks                                                                                                                                                 | Severity     |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `frontmatter-block-exists`       | The page must start with a frontmatter block.                                                                                                                  | Error        |

packages/plugin-docs-cli/docs/validation-rules.md:58

• This table has an extra leading || on each line, which creates an unintended empty column in Markdown. Also, max-total-images-size and no-orphaned-images are not "pre-publish only" in the CLI implementation; they run whenever validation is executed in strict mode (which is the default for validate).

| Rule                      | What it checks                                                                                                           | Severity                            |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------- |
| `no-svg-files`            | SVG images aren't allowed - they can contain embedded scripts, which is a security risk. Use PNG or WebP instead.        | Error                               |

packages/plugin-docs-cli/docs/validation-rules.md:70

• This table has an extra leading || on each line, which creates an unintended empty column in Markdown.

| Rule                 | What it checks                                                                                                                        | Severity  |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `no-raw-html`        | Raw HTML tags aren't allowed in the page body (except `br`, `wbr`, `hr`, `details` and `summary`) - use markdown syntax instead.      | Warning † |

packages/plugin-docs-cli/docs/validation-rules.md:81

• This table has an extra leading || on each line, which creates an unintended empty column in Markdown.

| Rule                      | What it checks                                                                                                             | Severity  |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------- |
| `image-refs-relative`     | An image reference must be a relative path (e.g. `img/foo.png`), not an absolute one (e.g. `/img/foo.png`).                | Error     |

packages/plugin-docs-cli/docs/validation-rules.md:90

• This table includes min-content-length, but that rule ID doesn't exist in src/validation/types.ts (and there is no corresponding implementation under src/validation/rules). The extra leading || also creates an unintended empty column in Markdown.

| Rule                     | What it checks                                                                                                                                                                                               | Severity                            |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------- |
| `min-content-length`     | A page's body should have at least 150 characters of real content. A heads-up, not a hard requirement - catches pages that are still effectively blank. Only checked as part of the pre-publish check.       | Suggestion (pre-publish check only) |

packages/plugin-docs-cli/docs/validation-rules.md:101

• This table has an extra leading || on each line, which creates an unintended empty column in Markdown.

| Rule                  | What it checks                                                                                 | Severity |
| --------------------- | ---------------------------------------------------------------------------------------------- | -------- |
| `manifest-valid`      | Every generated page entry has a title and a slug, and the manifest as a whole is well-formed. | Error    |

• Files reviewed: 4/4 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

The new validation-rules reference contains rule IDs that don’t exist in the CLI’s Rule map/implementation and includes a Markdown table formatting error.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (2)

packages/plugin-docs-cli/docs/validation-rules.md:49

• These two rows document frontmatter-title-length and frontmatter-description-length, but those rule IDs are not present in the Rule map (src/validation/types.ts) and don’t appear anywhere in the validation code. This makes the reference table inaccurate for plugin authors (and contradicts AGENTS.md’s guidance to keep rule IDs in sync).

| `frontmatter-title-length`       | `title` should be 60 characters or shorter - search engines truncate longer titles in search results.                                                          | Suggestion † |
| `frontmatter-description-length` | `description` should be between 20 and 160 characters - long enough to be useful, short enough that search engines don't cut it off.                           | Suggestion † |

packages/plugin-docs-cli/docs/validation-rules.md:87

• This row documents a min-content-length rule, but that rule ID is not present in the Rule map (src/validation/types.ts) and doesn’t appear anywhere in the validation code. The table should only list rules that the CLI actually runs.

| `min-content-length`     | A page's body should have at least 150 characters of real content. A heads-up, not a hard requirement - catches pages that are still effectively blank. Only checked as part of the pre-publish check.       | Suggestion (pre-publish check only) |

• Files reviewed: 4/4 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

The new validation rules doc currently documents rule IDs/behavior that do not match the implemented rule set and strict-mode execution semantics.

Review details

Suppressed comments (4)

Previously missed (4) — in code that hasn't changed since the last review.

packages/plugin-docs-cli/docs/validation-rules.md:49

• frontmatter-title-length and frontmatter-description-length are documented as validation rules, but there is no corresponding Rule ID in src/validation/types.ts and no implementation under src/validation/rules/*. This contradicts the doc's goal of being a complete reference of the rules that validate/serve actually run.
  packages/plugin-docs-cli/docs/validation-rules.md:60
• max-total-images-size and no-orphaned-images are described as "pre-publish check only", but they currently run whenever validation is executed in strict mode (i.e., the default validate command). The doc should describe them as strict/validate-only, not pre-publish-only.
  packages/plugin-docs-cli/docs/validation-rules.md:87
• min-content-length is documented as a rule, but there is no corresponding Rule ID in src/validation/types.ts and no implementation under src/validation/rules/*. Either add the rule in code or remove it from this reference list.
  packages/plugin-docs-cli/docs/validation-rules.md:18
• The CLI emits info (not "Suggestion") as its third severity level (see src/validation/types.ts and src/validation/format.ts). To avoid confusing plugin authors, clarify that "Suggestion" corresponds to info in the CLI output (or rename it to "Info").

• Files reviewed: 4/4 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

The new validation rules reference contains documented rules/behavior that don’t match the actual implemented rule set and strict-mode execution semantics.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 2
• Review effort level: Lite

[leventebalogh]

LGTM 👍

[leventebalogh]

Hmm, isn't this contradicting with the max-data-uri-size rule?

[sunker]

Very true! I removed the rule in this PR, hope that was ok.

[leventebalogh]

Should we also add a cheap automated test that checks if the rule ids in the doc match to what we have in the code? (I guess the outcome of the instructions for the agents can be indeterministic and might cause drift?)

[sunker]

Yes good idea. I added a test for it in src/validation/docs-sync.test.ts, which compares the rule IDs in this doc against Rule in types.ts in both directions. It immediately found three rules that were already implemented but missing here, which are now added. 👍

[sunker]

Thanks for good feedback, this is ready for another round of review.