Common use cases

Six concrete scenarios admins reach for Help Tutorials to solve. Each is a "you want to X → here's how" sketch — the deeper walkthroughs live in the next two sections.

1. Onboarding a new operator who landed on /admin/orders for the first time

You want the new hire to see a numbered checklist the moment they open the orders page — not a help link they have to discover.

→ Module is on, the orders tutorial already ships seeded, the help icon is bottom-right. With isAutoOpenEnabled() true (default for new logins), the panel auto-opens once on the first visit, the operator clicks Got it, and markPageAsRead("admin.orders") writes the page key to localStorage["help-tutorials-read"]. Next visit: no auto-open, but the icon remains for re-opening.

2. Adding a tutorial to a custom admin page you just shipped

You want every operator who lands on your new /admin/loyalty-tiers page to see a 4-step walkthrough.

→ Open /admin/help-tutorials, click + New Tutorial, enter page_key=admin.loyalty-tiers (must match what getPageKey("/admin/loyalty-tiers") returns), pick language English, write title + description, add 4 steps, save. Repeat for each other language your admins use. Tutorial appears on the next page load.

3. Annotating the three settings fields that actually matter on a 30-field settings panel

You want operators to ignore 27 of the 30 fields and focus on the 3 that change behaviour.

→ Edit the tutorial for that page, scroll to Settings Help, click + Add Setting three times. For each, enter field_name (must match the form input's name attribute), label, description, impact. When the operator opens the help panel on that page and clicks the Settings tab, they see only those three fields with the impact callouts.

4. Re-seeding tutorials after a fresh tenant provision

You provisioned a new tenant and the help icon shows on pages but the panel says "no tutorial".

→ Open /admin/help-tutorials, click Seed Defaults (the sparkles button, top-right next to + New). The toast shows created: N — the upsert filled gaps for the language of your admin session. You can re-run it any time; it never overwrites existing rows (ON CONFLICT DO NOTHING).

5. Disabling a noisy tutorial without losing the content

A tutorial keeps auto-opening for users who have asked you to suppress it. You don't want to delete it — you might re-enable later.

→ Edit the tutorial, flip the Active toggle to Draft (gray), save. The resolver skips is_active=false rows; the help icon still renders if the page has another active tutorial in a different language, otherwise the icon disappears. The row stays in the table.

6. Showing operators "what's new" after a UX overhaul

You just rebuilt the /admin/products page. You want every operator to see the new tutorial fresh — not skip past it because they already marked the old one as read.

→ Two ways:

• Selective: edit the tutorial, save (server-side updated_at bumps but the localStorage read-flag stays). Operators who already read it won't see auto-open. They'll have to click the help icon manually.
• Global re-prompt: Open the browser console on a test login and run localStorage.removeItem("help-tutorials-read"). Operators won't all do this themselves — for a true platform-wide reset, the support route is DELETE FROM help_tutorial_reads; per-tenant (note: this also clears the server-side read records, so the unread dot returns universally).