Skip to content
Capell CMS

Welcome Tour Overview

capell-app/welcome-tour keeps guided admin onboarding outside the core admin package.

Responsibilities

Section titled “Responsibilities”
  • Registers jibaymcs/filament-tour only when this package is installed.
  • Provides WelcomeTourDashboard, a dashboard subclass that uses the Filament tour trait.
  • Registers default tour steps from configurable translation keys.
  • Adds package settings for enabling the tour and editing the step list.
  • Adds a user resource bridge for per-user tour visibility.

Installation Audit

Section titled “Installation Audit”
  • Composer package: capell-app/welcome-tour
  • Hard dependencies: capell-app/admin
  • Third-party dependency: jibaymcs/filament-tour
  • Database impact: package settings migration for the welcome-tour settings group
  • Public frontend impact: none

In the isolated harness, the package installed successfully and replaced the baseline dashboard route with Capell\WelcomeTour\Filament\Pages\WelcomeTourDashboard at /admin.

The verified pass added and captured Capell\WelcomeTour\Filament\Pages\WelcomeTourSettingsPage at /admin/extensions/welcome-tour/settings. The shared Settings page only renders first-party groups, so Welcome Tour needs its own extension settings page.

Admin Surfaces

Section titled “Admin Surfaces”
  • Dashboard route: /admin, rendered by WelcomeTourDashboard
  • Welcome tour overlay on the dashboard when enabled and visible for the current user
  • Settings page: /admin/extensions/welcome-tour/settings, with enabled toggle and editable step repeater
  • User edit form extension: Show welcome tour toggle when the host users table has dismissed_hints

Configuration

Section titled “Configuration”

The default step configuration lives in config/capell-welcome-tour.php. Each step supports:

  • key
  • title
  • description
  • element
  • icon
  • icon_color
  • sort
  • visible

Use translation keys for title and description when the text should be site-localized. Descriptions are rendered as escaped text, not trusted HTML. Default steps do not target admin selectors; set element only after verifying the target remains stable and accessible.

Screenshot Coverage

Section titled “Screenshot Coverage”

See screenshots.json for the screenshot contract. The verified capture covers the dashboard, first-step overlay, extension settings page, and user-level toggle.

Disposable Harness Notes

Section titled “Disposable Harness Notes”
  • Install only the core Capell stack and capell-app/welcome-tour for screenshots.
  • Remove capell-app/login-audit, tapp/filament-authentication-log, and the direct rappasoft/laravel-authentication-log dependency from copied baseline harnesses. The authentication-log listener can fire on admin login even when Login Audit is not the target package.
  • If the copied harness user model imports AuthenticationLoggable, remove that trait in the disposable app after removing the authentication-log dependency.
  • Publish and run 2026_05_10_190836_01_add_welcome_tour_settings.php before capturing settings. The settings page can render only after the welcome-tour.enabled and welcome-tour.steps settings exist.
  • The user edit toggle is expected when the host users table has dismissed_hints; otherwise that screenshot remains optional for hosts without the bridge column.

Verification

Section titled “Verification”
  • vendor/bin/pest packages/welcome-tour/tests --configuration=phpunit.xml
  • php artisan route:list | rg 'welcome|settings|extension|Welcome|Settings|Extension' in the disposable harness
  • Browser capture at /admin, /admin/extensions/welcome-tour/settings, and /admin/users/1/edit