interactive-tutorials

Imported from grafana/interactive-tutorials (AGENTS.md). Install upstream with npx skills add grafana/interactive-tutorials. Copyright stays with the author.

• Security issues should be reported via Grafana's security issue reporting page and not directly in this repository.

Interactive Guides Repository

This repository contains interactive Grafana guides in JSON format. Each guide lives in its own directory with a content.json file defining the guide structure and a manifest.json file whose targeting.match controls where the guide is recommended. (index.json is frozen and no longer edited per guide -- a CI check fails any PR that changes it.)

Full reference documentation lives in docs/. AI-oriented references live in .cursor/.

Critical Rules

1. Use navmenu-open for any step targeting navigation menu elements
2. Use stable selectors -- prefer data-testid, button text, and semantic attributes over CSS classes
3. No markdown titles in guides -- the guide title is rendered by the app frame; a leading ## Title duplicates it
4. No multistep singletons -- a multistep with one step must be a plain interactive block
5. Include exists-reftarget for selector-targeting steps -- the repo convention is to list exists-reftarget in the requirements array for any block or step with a reftarget.
6. Use sections, not markdown headers -- group steps with section blocks, not ## headings
7. Include page requirements -- page-specific actions need on-page:/path
8. Verify state changes -- use verify after save/create operations
9. Keep prose brief -- guides render in a sidebar; be direct and action-oriented
10. Action-focused content -- "Save your configuration" not "The save button can be clicked"
11. Connect requirements and objectives -- if section 1 creates a resource, section 2 should require it
12. Tooltips -- under 250 characters, one sentence, don't name the highlighted element
13. doIt: false for secrets -- never automate filling passwords, tokens, or API keys
14. Section bookends -- each section needs a 1-sentence "what you'll do" intro markdown block immediately before the section and a 1-sentence "what you learned" summary markdown block immediately after it. Do not put those bookends inside the section -- Pathfinder often numbers in-section markdown as a step. You may omit the intro when a pre-section markdown line already covers the goal (for example "To ..., complete the following steps:").
15. Bold only GUI names -- "Click Save & test" not "Click the Save & test button"
16. skippable: true for conditional steps -- use for permission-gated steps and optional/conditional fields
17. No focus-before-formfill -- highlight on an input with doIt: true is a no-op; use formfill instead, or set doIt: false
18. schemaVersion is optional -- if included, use "schemaVersion": "1.1.0"; the schema defaults to "1.1.0" when omitted
19. popout requires targetvalue -- popout actions MUST set targetvalue to exactly "sidebar" or "floating"; the schema rejects any other value, and popout is not allowed inside guided blocks
20. Use openGuide, not ?doc= -- to chain a follow-up guide after a navigate step, set openGuide: "bundled:<guide-id>" on the interactive block; the legacy ?doc= query param is back-compat only
21. Use supported lazy discovery -- for targets absent until scrolling, use a standalone interactive block with lazyRender: true, exists-reftarget, and a verified scrollContainer (often #pageContent with the Grafana sidebar open). Its individual Show me / Do it handles discovery. Current guided steps and Do section do not run that discovery; see guided-interactions.md.

Task Routing

Reference Documentation (docs/)

Historical Context

Shared Content (shared/)

Commands

Committing and pushing

Branch protection on this repository enforces verified commit signatures as a push rule. An unsigned commit is not rejected when you make it — it is rejected by the remote at push time, with GH013: Repository rule violations found naming each offending SHA. Fixing it after the fact means rewriting the commit, which changes its SHA and can leave local tooling holding a diverged ref.

So: leave commit.gpgsign enabled and never disable it for a commit here (no -c commit.gpgsign=false, no --no-gpg-sign). Check before pushing with git log --pretty='%h %G? %s' main..HEAD — every commit must show G.

Maintaining this file

Keep this file for knowledge useful to almost every future agent session in this project. Do not repeat what the codebase already shows; point to the authoritative file or command instead. Prefer rewriting or pruning existing entries over appending new ones. When updating this file, preserve this bar for all agents and keep entries concise.