Documentation Plugins Interactive learning Upgrade notes

Upgrade notes

This section contains the headline changes for each Interactive learning release, including breaking changes and migration steps. For the full per-release detail, see the project CHANGELOG.

Version 3.0: Coda sandbox terminal moves to its own plugin

Breaking change for anyone using the Coda terminal. If you have never enabled it, nothing changes for you.

What changed

The sandbox VM and terminal backend has moved out of Interactive learning into a separate app plugin, grafana-coda-app. Interactive learning keeps the terminal panel and the guide block types (terminal, terminal-connect, challenge) and now talks to that plugin over a documented, versioned API.

This makes the sandbox terminal usable by any Grafana plugin rather than only Interactive learning, and reduces Interactive learning’s own backend to a single purpose.

Action required

If you use the Coda terminal:

1. Install and enable the Coda app plugin (grafana-coda-app).
2. Set it up by following its own operator guide, which is the authority on the Coda side and covers the two Grafana settings the plugin cannot register without, the session role floor, enrollment, and verification.
3. Leave Enable Coda terminal switched on in Interactive learning’s settings. That is the only Coda setting Interactive learning still owns.

Three things catch people migrating an already-working terminal. All three are Coda-side, and the operator guide covers each in full — they are named here because the previous version of this note got them wrong.

You need a new enrollment key, and saving is the whole registration. Grafana stores encrypted plugin settings per plugin and never exposes their values back, so the existing refresh token cannot be migrated — by Interactive learning or by anyone else. Ask your Coda administrator for a key issued for this Grafana instance. On the Coda plugin’s Configuration tab, fill in the API URL, relay URL and enrollment key and select Save settings. Saving redeems the key; there is no button to press afterwards.

Do not press Register now during setup. It always forces re-registration, so pressing it after a successful save re-submits a key that has just been spent. Coda answers 401 and you are told your key was rejected moments after it worked. Your stack is not broken by this — the plugin only replaces its stored credential on success, and a redemption Coda refuses revokes nothing — but the diagnosis is a false alarm that has cost people a replacement key. Register now is a recovery control, not a setup step.

Check the session role floor if your learners are Viewers. The Coda plugin requires a Grafana basic role of Editor or above to start a sandbox, set by its minimumSessionRole setting and defaulting to Editor. Interactive learning’s embedded backend had no role check at all, so this is a behaviour change introduced by the move: a stack whose learners sign in as Viewers can complete every step above and still get 403 role_forbidden on every sandbox. There is no control for it on the configuration page — see the operator guide for the two routes that work. On Coda plugin 1.1.1 and earlier, set it after your last configuration-page save: those versions sent only the settings the page owned, so every save erased minimumSessionRole and silently returned the floor to Editor. Coda plugin 1.2.0 and later echo back the keys the page does not own, so the order no longer matters.

Until the Coda app plugin is installed and registered, Interactive learning hides the terminal panel and the terminal block types. Guides containing those blocks still load; the affected steps report that the sandbox is unavailable rather than failing. Interactive learning’s configuration page names whichever step is still outstanding.

Interactive learning no longer reads codaApiUrl, codaRelayUrl, codaRegistered, or the enrollment key and refresh token it used to store — all five moved to the Coda app plugin. enableCodaTerminal stays, and still controls whether Interactive learning shows terminal UI at all.

Note that “no longer read” is not “deleted”. Values already in Interactive learning’s plugin settings stay there, and nothing in the plugin clears them: Grafana never exposes an encrypted setting’s value back, so there is no supported way to read one in order to blank it. That retention is also what makes a downgrade work, so it is deliberate rather than an oversight. Two consequences worth knowing:

• The old refresh token may still be live Coda-side. Whether it is, and whether redeeming a new enrollment key invalidates it, is a question for your Coda administrator — nothing in Interactive learning can answer it. If you want the old credential revoked, ask for that explicitly.
• Once you no longer need the downgrade path, an administrator can clear the leftovers by deleting Interactive learning’s plugin settings through the Grafana API. There is no button for it on the configuration page.

Version 2.9: Floating panel and popout step

Released April 2026.

What changed

• Floating panel mode — Users can pop the docs panel out of the sidebar into a free-floating, resizable, draggable window. Click the Pop out button at the top of the panel to detach, drag it anywhere, resize from any edge, or minimize to a pill. Click again or drag back to the right edge to dock it.
• Popout step type — Guide authors can now build a popout action into a guide step so the panel automatically docks or undocks at the right moment. Useful when a guide step needs the right sidebar for something else (for example, Grafana Assistant). Configured from the block editor with a single dropdown (floating or sidebar).

Action required

None — both features ship enabled and require no configuration.

Version 2.8: Block editor available without dev mode

Released April 2026.

What changed

• Block editor moved out of dev mode — Editors and admins can now access the block editor through a dedicated Editor tab in the docs panel, without enabling dev mode. The Editor tab is permission-gated and only appears for users with editor or admin role.
• Combobox formfill fix — Form-fill steps that target a Grafana combobox now open the dropdown before entering tokens, fixing intermittent step-completion failures.
• Kiosk session ID tracking — Kiosk mode now emits session IDs for analytics.

Action required

If your team has documentation referencing “enable dev mode to access the block editor,” update it — dev mode is no longer required.

Version 2.7: Package engine integration

Released March 2026.

What changed

• Package engine integration — The full package pipeline (composite resolver, package-aware fetching, milestone resolution) is wired into the recommendation panel. Recommendations from the recommender are resolved through this pipeline, falling back to bundled and CDN-served packages as needed.
• Package completion tracking — Per-package completion state and navigation links between related packages are persisted across sessions and surfaced in the docs panel.
• Package pill icon — Recommendations backed by a package now show a distinct pill icon, so users can tell at a glance whether a card is a single guide or a learning path.
• Recommender URL auto-selection — The plugin now picks the right recommender API URL automatically based on the Grafana instance’s hostname (production / ops / development). Administrators can still override the URL in plugin settings.

Action required

If you author path or journey packages, the manifest field that lists child guides is milestones.

Version 2.6: Kiosk mode without dev mode

Released March 2026.

What changed

• Kiosk mode no longer requires dev mode — Administrators can enable kiosk mode through the enableKioskMode toggle in plugin settings. The kiosk button appears in the sidebar header for all users on instances where it’s enabled.
• Open guide after navigate step — A navigate step can now open a guide in the sidebar after the SPA navigation completes (using a new openGuide field). Backward-compatible: existing ?doc= query parameters in target URLs are detected automatically.
• Selector picker scoping fixes — The element picker no longer picks form controls outside the immediate hover area, preventing surprising selector results when authoring guides with the block editor.
• Plugin settings data-loss fix — Saving any single configuration tab no longer wipes settings from other tabs. This was a Cloud-deployment regression triggered by version updates.

Action required

If you previously enabled kiosk mode through dev mode, you can now enable it directly from the plugin settings page. The settings UI exposes the enableKioskMode toggle in the Interactive Features tab.

Version 2.5: Selector resilience engine

Released February 2026.

What changed

• Selector resilience engine — Single-pass selector resolution has been replaced with a multi-strategy pipeline:
  • resolveWithRetry() exponential backoff (200 ms / 600 ms / 1.8 s).
  • :text() exact match for short button labels (under 20 characters), eliminating false positives.
  • data-testid prefix matching when exact match fails (uniqueness-guarded).
  • panel: domain selector prefix to resolve Grafana panels by title.
  • Unified resolver with confidence scoring.
• Selector Health badge — An inline indicator (green / yellow / red dot, stability score, match count) on every selector field in the block editor.
• Test selector button — Evaluates the selector against the live DOM and flash-highlights the matched elements with numbered overlays.
• Shift+Click hover capture — Hold Shift during recording to capture a hover step without clicking through.
• Alt+Click form capture — Hold Alt during recording to force-capture any element as a form-fill, with the typed value picked up on blur.
• Auto-populate requirements — Recorded steps auto-populate exists-reftarget and navmenu-open requirements when relevant.

Action required

None — existing guides benefit from the resilient resolver without any changes. If you authored guides relying on substring matches for short button labels, you may notice fewer false positives.

Version 2.4: Kiosk mode and Coda Alloy scenarios

Released January–February 2026.

What changed

• Kiosk mode — A full-screen overlay that presents interactive guide tiles over Grafana, configured through the Interactive Features tab. Initially gated behind dev mode, then opened up in v2.6.
• Custom guide deep links — ?doc=api:<resourceName> opens a custom guide stored as a backend resource.
• Navigate handler path validation — Internal navigation paths are validated against denied routes (/logout, /profile/password, /admin/*, /api/*). Admin users can still navigate to admin-only paths since RBAC is enforced server-side.
• Alloy scenario VM template — vm-aws-alloy-scenario template for the Coda terminal, with animated progress bar during provisioning, quota cleanup, and persistent VM options for auto-reconnect on refresh.

Action required

None — these features ship enabled and require no configuration. The navigate path validation is a defense-in-depth measure and does not affect well-formed guides.

Earlier upgrades

For releases before v2.4, see the CHANGELOG. Notable earlier highlights:

• v2.3.6 — pathfinder.enabled global kill-switch feature flag for Cloud-wide rollout control. Workshop ECDSA P-256 presenter authentication for Live sessions.
• v2.3.0 — terminal-connect block type for guides; block editor lifecycle redesigned around a single smart primary button (Save as draft → Update draft → Publish → Update).
• v2.2.1 — Draft and publish lifecycle for library guides in the block editor.
• v2.2.0 — code-block block type with syntax highlighting, copy-to-clipboard, and step completion.

Version 1.1.83: New content delivery infrastructure

Starting with version 1.1.83, interactive guides are served from a dedicated content delivery network (CDN) instead of GitHub raw URLs:

Why

• Improved reliability — Dedicated infrastructure for serving interactive content.
• Better performance — Optimized CDN delivery for faster content loading.
• Simplified architecture — No backend proxy routes for content fetching.

Migration steps

1. Update the Interactive learning plugin to version 1.1.83 or later.
2. Restart your Grafana instance.
3. Verify guides load correctly by opening the Interactive learning sidebar.

For content creators: no changes required to your content. The CDN serves the same JSON format used previously. GitHub raw URLs (raw.githubusercontent.com) are still supported in dev mode for testing.

Getting help

If you encounter issues after upgrading, verify you’re on 1.1.83 or later, check the browser console for specific errors, and report issues on the GitHub repository.