veritas-kanban/docs/CLICK-THROUGH-TUTORIALS.md

Click-through Tutorials Roadmap

For future VERITAS

This roadmap tracks issue #693: product-native click-through tutorials for Veritas Kanban. The goal is not a one-off onboarding modal. The goal is a reusable guided-tour system that works in the macOS desktop app and web/PWA surfaces, respects product modes, remains keyboard/screen-reader accessible, and can be extended as v5 features grow.

Goals

• Teach the first useful workflow in under five minutes.
• Reduce “where do I click next?” friction for new desktop and web users.
• Support Board Only, Team/Remote, and Advanced product modes without showing irrelevant agent/admin steps.
• Use real UI surfaces instead of screenshots where possible.
• Keep tutorials resumable, skippable, resettable, and safe for demo data.
• Give support/docs a stable tour ID vocabulary for screenshots, videos, and bug reports.

Non-goals

• Do not block app access behind mandatory training.
• Do not build a marketing carousel.
• Do not rely on brittle DOM selectors with no product-owned anchor IDs.
• Do not teach every feature in one mega-tour.
• Do not expose admin/security steps to users who lack permission.

Recommended implementation shape

1. Tour registry

Add a registry that describes tours as data:

interface GuidedTourDefinition {
  id: string;
  title: string;
  description: string;
  productModes: ProductMode[];
  requiredPermissions?: string[];
  entryCommand?: string;
  steps: GuidedTourStep[];
}

interface GuidedTourStep {
  id: string;
  title: string;
  body: string;
  target?: string; // data-tour-id value
  placement?: 'top' | 'right' | 'bottom' | 'left' | 'center';
  route?: string;
  actionHint?: string;
  completion?: 'next-click' | 'target-click' | 'route-visible' | 'manual';
}

Use data-tour-id anchors on stable product elements instead of CSS selectors. Missing anchors should fail gracefully by showing a centered step with a “Go there” action when possible.

2. Tour runtime

Add a small guided-tour runtime responsible for:

• tour state: not started, active, completed, dismissed;
• current tour/step persistence in local storage initially;
• route-aware step navigation;
• focus trap and escape handling;
• reduced-motion support;
• spotlight/overlay rendering;
• analytics event hooks, if enabled;
• reset/replay from Help/Command Palette.

A lightweight in-house runtime is preferable to adopting a heavy tour library unless we need complex positioning. If a library is considered later, evaluate bundle cost, accessibility, keyboard handling, React 19 compatibility, and Mantine integration first.

3. Tour launcher surfaces

Expose tours from:

• desktop menu command: Help → Tutorials / Setup & Diagnostics adjacent;
• Command Palette: “Start board basics tour,” “Start agent workflow tour,” etc.;
• first-run desktop onboarding final step;
• empty states: board, templates, agents, workflows;
• Help/keyboard shortcut dialog.

4. Product-mode awareness

Tours should filter by current features.productMode.selectedMode:

Mode	Default tours
Board Only	Board basics, task detail, search/filter, backup/export
Team/Remote	Board basics, comments/activity, access model, notifications
Advanced	Board basics, agents, workflows, evidence/timeline, maintenance

Existing users default to Advanced, but tutorials should not assume the user wants every advanced surface.

Initial tour set

Tour 1 — Board basics

Audience: everyone.

Steps:

1. Board columns and task cards.
2. Create a task.
3. Open task detail.
4. Move status.
5. Add comment/checklist-style progress.
6. Use search/filter.
7. Finish with “replay from Help anytime.”

Tour 2 — From task to agent work

Audience: Advanced mode; hidden unless agents are enabled or user has agent permissions.

Steps:

1. Open a task.
2. Add enough context for an agent.
3. Select/run an agent or workflow.
4. Watch run timeline/status.
5. Review evidence/output.
6. Mark done with validation notes.

Tour 3 — Desktop first-run safety

Audience: macOS desktop.

Steps:

1. Local server/profile location.
2. Recovery key/password reminder.
3. Settings → Maintenance health.
4. Backup/import/export.
5. Update channel/status.

Tour 4 — Workflows and templates

Audience: Advanced mode.

Steps:

1. Templates vs workflows.
2. Apply a task template.
3. Open workflow authoring.
4. Run a sample workflow.
5. Inspect run/evidence timeline.

Tour 5 — Admin/security essentials

Audience: owner/admin only.

Steps:

1. Product modes.
2. Agent/provider settings.
3. Tool policies and enforcement.
4. Shared resources/skills.
5. Maintenance center/debug bundle.

Accessibility requirements

• Every tour action must be keyboard reachable.
• Esc dismisses the current tour with confirmation or an undo snackbar.
• Focus returns to the launching control after exit.
• Screen readers receive step title, body, position, and target context.
• Spotlight/overlay cannot be the only instruction; text must be sufficient.
• Respect prefers-reduced-motion.
• Maintain color contrast in dark and light themes.

Persistence and privacy

Initial persistence can be local-only:

{
  "guidedTours": {
    "completed": { "board-basics": "2026-06-08T00:00:00.000Z" },
    "dismissed": { "agent-workflow": "2026-06-08T00:00:00.000Z" },
    "active": null
  }
}

Do not sync tutorial progress to a remote server unless there is a clear multi-device UX need and the user/account model can explain it.

Implementation backlog

1. Add tour anchor IDs to board, task card, create task, task detail, search/filter, settings, maintenance, agents, workflows, and command palette surfaces.
2. Create guided-tour registry with product-mode and permission filters.
3. Create guided-tour runtime/provider with overlay, focus handling, persistence, and route-aware navigation.
4. Add Command Palette + Help launchers for available tours.
5. Wire desktop menu command to open the tutorial launcher.
6. Implement Board basics tour and tests first.
7. Implement Desktop first-run safety tour integrated with existing desktop onboarding.
8. Implement Advanced agent/workflow tours after anchor/runtime stability.
9. Add Playwright or component tests for launch, next/back, skip, missing anchor fallback, keyboard escape, and product-mode filtering.
10. Update docs/screenshots/video script once the runtime is stable.

Suggested task split

• guided-tour-anchors: add data-tour-id anchors and tests around critical surfaces.
• guided-tour-runtime: provider, overlay, persistence, keyboard/a11y behavior.
• guided-tour-launchers: Command Palette, Help dialog, desktop menu command.
• tour-board-basics: first product tour, docs, and tests.
• tour-desktop-safety: desktop setup/maintenance/update tour.
• tour-agent-workflow: advanced task-to-agent tour.

Acceptance criteria for #693

• A checked-in roadmap/design doc exists.
• The issue has a concrete implementation sequence.
• Follow-up issues/tasks can be created without rediscovering product constraints.
• The first implementation PR can start with Board basics rather than architecture debate.