Troubleshooting

Help icon doesn't appear on a page.

Three possibilities:

1. Module is disabled — toggle it ON at /admin/modules.
2. The page hasn't declared a page_key to the help shell — open the page in DevTools and look at the help icon's request. If pageKey is empty, the page wiring is missing.
3. No tutorial exists for that page_key in your locale (and no en fallback exists either). Create one at /admin/help-tutorials.

Tutorial opens blank.

The row exists but its steps JSONB is empty. Edit the row and add at least one step.

"New" dot never goes away after opening the panel.

The POST /admin/help-tutorials/{pageKey}/read request failed silently. Check the network tab. Most common cause: cookies / session expired between page load and click — the request 401s and the dot stays.

Seed didn't run on a fresh tenant.

The auto-seed fires on the FIRST GET /admin/help-tutorials/{pageKey} for a missing row. If your tenant was provisioned but no admin has opened a tutorial-aware page, the table is empty by design. Force it with POST /admin/help-tutorials/seed.

I edited a default tutorial but the change doesn't appear.

Hard reload the admin (the help shell caches the response). If still wrong, the tutorial is being served from a different language than you edited — confirm the language query parameter in the request.

403 when saving from /admin/help-tutorials.

Wave 11 split editing onto manage_help ∨ manage_settings. Grant either privilege to your usergroup.

I want to nuke all reads and re-show tutorials platform-wide.

DELETE FROM help_tutorial_reads; (per tenant). The next page load will re-show all "new" dots. Useful after a big UX change to draw operators back into the help panel.

Tutorials still appear after disabling the module.

The frontend uses useModuleEnabled to decide whether to render the help icon. If a page renders the icon unconditionally that's a wiring bug — file an issue with the route name. The backend /admin/help-tutorials/* routes already 403 with module_disabled regardless.

Where do I find the seeded defaults?

backend/internal/core/admin/help_tutorials.go. defaultTutorialsEN() holds the default set; it is the only seed source (English content).