Authoring

data-tour

panel

docs/tour/panels/yourPanelKey.md

markdown
<!-- tour {"panel":"yourPanelKey","order":75} -->

# Your Panel Name

## Overview

Use {{panelTitle}} to manage this workflow in {{platformName}}.

## Walkthrough

- Identify the main view and its filters.
- Explain one practical workflow, using a hypothetical example.
- Review the effect of saving changes before applying them.

## Takeaway

Know where to return in {{brandName}} for this task.

panel

order

The title and all three prose headings are required. Put each walkthrough bullet on one line. Add an Actions section for a real interactive walkthrough, as described below. Both modes visit every main tab; Brief uses each step's short explanation, while Extended uses its detailed explanation and any extra detail steps. The same content is returned to the AI trainer and published as a readable docs page.

Structured actions#

Add this section after Takeaway. The array order is the teaching order. Each step ends with a highlight. A step may first activate an explicitly approved view switch, then highlight the resulting content. Keep a tab highlight when no separate content container is appropriate.

json
[
  {
    "id": "overview",
    "title": "Overview",
    "brief": "Review activity in {{platformName}}.",
    "extended": "Start with the activity summary, then compare the visible reporting period before interpreting the totals.",
    "actions": [
      {
        "type": "activate",
        "resource": {
          "target": "example.tab.overview",
          "source": "src/components/admin/ExamplePanel.tsx"
        }
      },
      {
        "type": "highlight",
        "resource": {
          "target": "example.overview",
          "source": "src/components/admin/ExamplePanel.tsx"
        }
      }
    ]
  }
]

json

## Actions

resource.source

resource.target

Bind the view switch and content in the panel:

tsx
<button
  type="button"
  data-tour="example.tab.overview"
  data-tour-action="activate"
  data-tour-active={tab === 'overview'}
  onClick={() => setTab('overview')}
>
  Overview
</button>
{tab === 'overview' && (
  <section data-tour="example.overview">...</section>
)}

data-tour-action="activate"

data-tour-active="true"

activate

destination: { "target": "example.workspace", "source": "src/components/admin/ExamplePanel.tsx" }

data-tour-destination="example.workspace"

data-tour="example.workspace" data-tour-active="true"

Mapped tabs can use a template:

tsx
data-tour={`example.tab.${tab.id}`}

data-tour-private

Optional step fields:

mode: "extended"

optional: "Reason this view may be absent"

Required steps that cannot resolve stop with a retryable error. The learner can explicitly skip a highlight or the rest of a panel. The model cannot skip unresolved required steps or enter the question break while steps remain. Outcomes distinguish shown, unavailable and learner-skipped steps. Changing panels or modes cancels pending actions. Highlights follow scrolling, resizing, nested scroll panes and same-origin developer iframe content, then clean up on navigation or tour exit.

For a new feature in an already instrumented panel, editing its Markdown is enough. If the new feature has no binding yet, add the attribute at the source control or container and reference it from the document. A guide without Actions remains a written orientation until its walkthrough is authored.

Supported text placeholders:

{{brandName}}

{{platformName}}

{{panelTitle}}

{{sectionTitle}}

Use placeholders instead of hardcoding CanYaPay, BasaltSurge, or a partner name. Brand names are supplied per session, including the spoken welcome. Keep exact UI labels unchanged. Avoid business-specific data, credentials, account values, or instructions that ask the trainer to bypass its tools or permissions.

New documents appear automatically in Docs → Workspace Tour → Panel Guides. A new sidebar panel without a document still receives a basic orientation, so missing content does not remove an accessible panel from the route. Duplicate panel keys, invalid metadata, unknown placeholders, and missing sections fail validation with the document path.

node --test src/lib/admin-tour/tour.test.cjs