Admin walkthrough — primary flow

Authoring a new tutorial is the most common admin task. This is the full click-by-click path.

Where you start

Open /admin/help-tutorials from the sidebar. The page header shows the title Help Tutorials plus two buttons on the right:

• Seed Defaults (sparkles icon) — re-runs the default-set seeder.
• + New Tutorial (plus icon) — opens the editor modal in create mode.

Below the header sit two filter dropdowns:

• Status filter: All / Active / Draft.
• Language filter: All, plus one option per language enabled for the store (each shown by its own name, e.g. English, Español).

Below that is the tutorial list — a table with columns Page Key, Title, Language, Steps (count), Status badge, and a row-level Edit / Delete action.

Step 1 — Click "+ New Tutorial"

A modal opens titled Create tutorial. The modal is sized xl (wide), with a left-aligned Preview button in the footer and right-aligned Cancel + Save.

Step 2 — Fill the header fields

The first row has two side-by-side inputs:

• Page Key — placeholder admin.products. This is the route key the frontend's getPageKey() resolver returns for the page you're documenting. The hint underneath reminds you it must match exactly. Common patterns:
  • /admin/products → admin.products
  • /admin/products/[id]/edit → admin.products.edit (dynamic IDs are stripped)
  • /admin/settings/payment → admin.settings.payment
• Language — one of the store's enabled languages (e.g. English). Each language is a separate row keyed (page_key, language).

Below the row:

• Title — required, the heading shown at the top of the help panel.
• Description — 1-3 sentences. Renders in a green callout card above the steps.

Step 3 — Add steps

You see a Steps section header with a green + Add Step button on the right. The first step is pre-inserted. Each step is a card with:

• A drag-handle dot (visual only — drag is not yet implemented; use the up/down arrows).
• A #1 number badge (auto-incremented).
• A title input on the same row.
• Up/down arrows to reorder.
• A trash button to remove.
• A content textarea below for the step body.
• An image_url input below the textarea (optional — the panel embeds the image under the step text).

Click + Add Step for each subsequent step. The seeder convention is 5-7 steps per tutorial; if you need more, the topic is probably two tutorials.

Step 4 — Add per-field settings hints (optional)

Below Steps, the Settings Help section is empty by default. Click + Add Setting to insert a row. Each row has:

• Field Name — the form input's name attribute on the page being documented. Example: is_active.
• Label — the human label of that field.
• Description — what the field does.
• Impact — one line about consequences ("Disables checkout when off").

When the operator opens the help panel on that page, a Settings tab appears in the panel — click a field row and it expands to show description + a blue impact callout. Skip this section if the page is goal-driven and doesn't need per-field annotations.

Step 5 — Add a video URL (optional)

The Video URL input accepts a YouTube watch URL, a Vimeo URL, or a direct mp4. The panel's video tab embeds YouTube/Vimeo via getEmbedUrl(); anything else renders an external-link button. Leave blank if there's no video.

Step 6 — Toggle "Active"

The toggle at the bottom decides whether the resolver returns this tutorial. Green = Active (visible), gray = Draft (hidden). Defaults to Active on new tutorials.

Step 7 — Preview before saving

Click Preview (bottom-left of the footer). A side panel slides in from the right showing the tutorial exactly as operators will see it — the same <HelpPanel> component used at runtime. The preview reads from your editor state, not from the database, so unsaved changes appear.

If something's off, close the preview, edit, re-preview.

Step 8 — Save

Click Save. The frontend validates that Page Key and Title are non-empty, strips empty steps + empty settings entries, and calls POST /admin/help-tutorials (create) or PUT /admin/help-tutorials/{id} (edit). On success: toast Tutorial created, modal closes, list refreshes.

What changed in the DB

A row in help_tutorials with the fields you entered. The unique constraint (page_key, language) prevents accidental duplicates — if a row already exists for that page key in that language, the API returns a conflict and the toast surfaces the error.

Verify

Navigate to the admin page whose page_key you used. The help icon (lifesaver / question mark, bottom-right floating button) should glow green with a pulse dot — that's the unread indicator. Click it; the panel slides in from the right showing your tutorial.