# Welcome Tour — Improvement & Growth Plan > Package: capell-app/welcome-tour · Kind: package · Tier: free · Product group: Capell Foundation · Bundle: foundation · Status: Complete 2026-06-06 ## 1. Snapshot Welcome Tour ships an optional, admin-only guided onboarding overlay for Capell Admin, built on `jibaymcs/filament-tour`. It registers the tour plugin via `WelcomeTourPanelExtender`, replaces the dashboard with `WelcomeTourDashboard` (route `/admin`), and renders a multi-step tour built from settings with anchored defaults for the sidebar, topbar, Sites, Pages, and Media. Configured steps register once from `WelcomeTourServiceProvider::bootInstalledPackage()`, and `WelcomeTourDashboard::tours()` reads `CapellAdmin::getWelcomeTourSteps()` after `ResolveWelcomeTourStepsForUserAction` filters completed steps for resume. Per-user state lives in the package-owned `welcome_tour_user_states` table with dismissal, snooze, completed step keys, restart, and legacy `users.dismissed_hints` compatibility. The package also contributes `WelcomeTourChecklistWidget`, lifecycle events, role/first-run step targeting, literal-or-translated step copy, `WelcomeTourStepContributor` for sibling package dashboard/contextual steps, and `HasContextualWelcomeTour` for page/resource-scoped tours backed by configured Sites/Pages/Media defaults. Marketplace and Composer copy are benefit-led, keywords are expanded, and `capell.json` currently declares only the extension card because the prior PNGs were generic illustrated placeholders rather than styled Capell UI screenshots. ## 2. Improvements (existing functionality) - **Done/Shipped: make tour persistence resilient when `users.dismissed_hints` is absent.** The package-owned `welcome_tour_user_states` table stores dismissal, snooze, completed step keys, and restart state while preserving legacy `dismissed_hints` compatibility. — `database/migrations/2026_06_04_000001_create_welcome_tour_user_states_table.php`, `src/Actions/Users/CanShowWelcomeTourAction.php`, `SetUserWelcomeTourPreferenceAction.php` — M - **Done/Shipped: stop re-registering steps on every render; register once at boot.** `WelcomeTourServiceProvider::bootInstalledPackage()` registers configured steps and `WelcomeTourDashboard::tours()` reads registered steps only. — `src/Providers/WelcomeTourServiceProvider.php`, `src/Filament/Pages/WelcomeTourDashboard.php` — S - **Done/Shipped: drop the double-escape on descriptions.** `WelcomeTourStepRegistrar` now treats translated and literal descriptions as plain strings, and docs tell contributors not to pre-escape copy. — `src/Support/WelcomeTourStepRegistrar.php`, `docs/steps-and-settings.md` — S - **Done/Shipped: honour the `enabled`/`visible` settings consistently.** `ResolveWelcomeTourEnabledAction` centralizes the global enabled decision, and `CanShowWelcomeTourStepAction` handles role/first-run step targeting. — `src/Actions/ResolveWelcomeTourEnabledAction.php`, `src/Actions/CanShowWelcomeTourStepAction.php` — S - **Done/Shipped: provide real anchored steps out of the box.** Defaults now target the sidebar nav, topbar, Sites, Pages, and Media links so the shipped tour demonstrates anchored tooltips. — `config/capell-welcome-tour.php`, `docs/overview.md` — S - **Deferred: localize the dashboard tour ID / button copy fallbacks.** Button labels are translated and the first card can be configured through step settings; a separate per-tour title remains optional polish rather than a roadmap blocker. — `src/Filament/Pages/WelcomeTourDashboard.php`, `config/capell-welcome-tour.php` — S ## 3. Missing Features (gaps) `capabilities: []` is empty, so the manifest advertises nothing the package actually does — every item below is currently unrepresented. - **Done/Shipped: per-step completion / progress tracking.** `RecordWelcomeTourStepAction`, `ResolveWelcomeTourStepsForUserAction`, and the package-owned user state table record completed step keys and resume at the first incomplete step. - **Done/Shipped: onboarding checklist surface.** `WelcomeTourChecklistWidget` renders configured setup tasks and completion state on the dashboard. - **Done/Shipped: multiple / contextual tours beyond the dashboard.** `contextual_tours` now ships scoped Sites, Pages, and Media defaults; `HasContextualWelcomeTour` lets Filament pages/resources render those steps with independent per-tour progress; and `WelcomeTourStepContributor::contextualStep()` lets sibling packages add scoped guidance without taking over the dashboard. - **Done/Shipped: first-run vs role-based targeting.** `CanShowWelcomeTourStepAction` gates configured steps by role and user age. - **Done/Shipped: dismiss vs "remind me later" / re-trigger.** `SnoozeUserWelcomeTourAction`, `ResetUserWelcomeTourAction`, and dashboard actions provide snooze and restart paths. - **Done/Shipped: other-package step contribution helper.** `WelcomeTourStepContributor::dashboardStep()` gives sibling packages a consistent contribution helper. - **Done/Shipped: analytics / telemetry.** Welcome Tour emits lifecycle events for start, step completion, completion, snooze, and restart. ## 4. Issues / Risks - **Closed: per-user state silently broken without host column.** Package-owned `welcome_tour_user_states` persistence now stores dismissal/progress/snooze state independently of host `users.dismissed_hints`, with legacy compatibility retained. - **Closed: health check is a stub vs. its declared severity.** `WelcomeTourHealthCheck` now verifies plugin/extender availability, dashboard registration, settings/schema resolution, and dismissal storage; the manifest label matches those checks. - **Closed: README structure references nonexistent code.** README and docs now describe the real `src/Data` classes, package-owned persistence, dashboard widget, lifecycle events, and contribution helper. - **Dashboard takeover side effect.** `CapellAdmin::useDashboardPage(WelcomeTourDashboard::class)` (`src/Providers/WelcomeTourServiceProvider.php:67`) unconditionally replaces the admin dashboard whenever the package is installed — even for hosts that only wanted step registration. If another package also wants the dashboard, last-writer-wins with no conflict surfacing. - **Closed: settings copy required translation keys only.** Configured title/description values may now be literal strings or translation keys, reducing owner friction for one-off onboarding copy. Only English package translations ship, so translated defaults remain a future localization-pack concern rather than a functional blocker. - **Performance budget realism.** capell.json sets `adminQueryBudget: 40`; the only query is the `dismissed_hints` lookup per render, so this is comfortably met, but re-registering steps every render (§2 #2) is wasted CPU under the budget rather than a query cost. `frontendRenderBudgetMs: 0` is correct (admin-only, no public output). - **Closed: `CHANGELOG.md` is a placeholder.** The changelog now records the persistence, health, lifecycle, checklist, anchored-step, manifest, and marketplace slices. ## 5. Marketplace & Positioning Welcome Tour is foundation/bundled and free — correctly so. Its real job is **activation and retention**: a smooth first-run reduces early churn and support load, which is exactly the kind of soft value a free foundation package should contribute to the platform pitch ("Capell gets new admins productive on day one"). **Current copy (all three identical):** "Welcome Tour provides optional guided onboarding for the Capell admin panel." — accurate but self-referential ("Welcome Tour provides…"), feature-named rather than benefit-led, and gives no sense of configurability or per-user control. **Improved `marketplace.summary`:** "Guided, in-product onboarding for Capell Admin — configurable multi-step tours that introduce new editors to sites, pages, media, and settings, with per-user dismiss and resume." **Improved composer `description`:** "Configurable Filament onboarding tours and per-user welcome flow for the Capell admin panel." **Media gaps:** recapture real Capell dashboard, overlay, settings, and user-toggle screenshots before promoting product media. A short runner-compatible animation or generated video remains optional later media, but the non-runner GIF is not part of the canonical marketplace gallery. **Platform-pitch contribution:** position as the "day-one activation" piece of the Foundation bundle; pair it explicitly with Diagnostics (health) and Translation Manager (localized copy) in cross-sell. **Keywords/tags (8–12):** `capell`, `cms`, `laravel`, `filament`, `onboarding`, `user-onboarding`, `product-tour`, `guided-tour`, `walkthrough`, `tooltips`, `admin-ux`, `activation`. (Current set is only `capell, cms, laravel, onboarding`.) ## 6. Prioritized Roadmap | Item | Bucket | Effort | Impact | Section ref | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------ | ------ | ----------- | | Done 2026-06-05: package-owned `welcome_tour_user_states` persistence handles hosts without `users.dismissed_hints`; preference writes fall back to the package table and visibility reads dismissal/snooze state before legacy hints. Evidence: `database/migrations/2026_06_04_000001_create_welcome_tour_user_states_table.php`, `src/Actions/Users/SetUserWelcomeTourPreferenceAction.php`, `src/Actions/Users/CanShowWelcomeTourAction.php`, `tests/Feature/WelcomeTourTest.php`. | Done | M | High | §2, §4 | | Done 2026-06-05: real `WelcomeTourHealthCheck` verifies plugin/extender availability, dashboard registration, settings/schema resolution, and dismissal storage; manifest label now matches those checks. Evidence: `src/Health/WelcomeTourHealthCheck.php`, `capell.json`, `tests/Unit/WelcomeTourSchemaCoverageTest.php`. | Done | S | High | §4 | | Done 2026-06-05: configured steps register from `WelcomeTourServiceProvider::bootInstalledPackage()` and `WelcomeTourDashboard::tours()` only reads `CapellAdmin::getWelcomeTourSteps()`. Evidence: `src/Providers/WelcomeTourServiceProvider.php`, `src/Filament/Pages/WelcomeTourDashboard.php`, `tests/Feature/WelcomeTourTest.php`. | Done | S | Med | §2 | | Done 2026-06-05: README now reflects real `src/Data` classes and package-specific extension points. Evidence: `README.md`. | Done | S | Med | §4 | | Done 2026-06-05: step titles/descriptions are translated as plain strings and docs require a single escape rule at render boundary. Evidence: `src/Support/WelcomeTourStepRegistrar.php`, `docs/steps-and-settings.md`, `tests/Feature/WelcomeTourTest.php`. | Done | S | Med | §2 | | Done 2026-06-05: `capabilities[]` is populated with the shipped admin tour, per-user state, checklist, targeting, lifecycle event, and settings capabilities. Evidence: `capell.json`, `tests/Unit/WelcomeTourSchemaCoverageTest.php`. | Done | S | Med | §3 | | Done 2026-06-06: anchored default steps target the admin menu, topbar, Sites, Pages, and Media selectors. Evidence: `config/capell-welcome-tour.php`, `docs/overview.md`, `docs/steps-and-settings.md`, `tests/Feature/WelcomeTourTest.php`. | Done | S | Med | §2 | | Done 2026-06-06: marketplace summary, Composer description, and keywords are benefit-led and expanded. Evidence: `capell.json`, `composer.json`, `tests/Unit/WelcomeTourSchemaCoverageTest.php`. | Done | S | High | §5 | | Recapture real Capell Welcome Tour dashboard, overlay, settings, and user-toggle screenshots before marketplace promotion. Deferred until styled runner recapture; no implementation blocker | Later | S | High | §5 | | Done 2026-06-06: dashboard restart/snooze actions and per-user resume state are shipped. Evidence: `src/Filament/Pages/WelcomeTourDashboard.php`, `src/Actions/Users/*WelcomeTour*Action.php`, `CHANGELOG.md`. | Done | M | High | §3 | | Done 2026-06-06: per-step completion and resume tracking are shipped. Evidence: `src/Actions/Users/RecordWelcomeTourStepAction.php`, `src/Actions/Users/ResolveWelcomeTourStepsForUserAction.php`, `database/migrations/2026_06_04_000001_create_welcome_tour_user_states_table.php`. | Done | M | High | §3 | | Done 2026-06-06: onboarding checklist dashboard widget is shipped. Evidence: `src/Filament/Widgets/WelcomeTourChecklistWidget.php`, `src/Actions/BuildWelcomeTourChecklistAction.php`, `resources/views/filament/widgets/welcome-tour-checklist.blade.php`. | Done | L | High | §3 | | Done 2026-06-06: role and first-run targeting for configured steps are shipped. Evidence: `src/Actions/CanShowWelcomeTourStepAction.php`, `config/capell-welcome-tour.php`, `docs/steps-and-settings.md`. | Done | M | Med | §3 | | Done 2026-06-06: contextual tours on Pages/Media/Sites beyond dashboard-level contributed steps. Evidence: `config/capell-welcome-tour.php`, `src/Support/ContextualWelcomeTourRegistry.php`, `src/Filament/Concerns/HasContextualWelcomeTour.php`, `src/Support/WelcomeTourStepContributor.php`, `docs/steps-and-settings.md`. | Done | L | Med | §3 | | Done 2026-06-06: tour lifecycle events are shipped for start, step completion, completion, snooze, and restart. Evidence: `src/Events/`, `src/Filament/Pages/WelcomeTourDashboard.php`, `src/Actions/Users/RecordWelcomeTourStepAction.php`. | Done | M | Med | §3 | | Done 2026-06-06: settings accept literal step copy as well as translation keys. Evidence: `src/Support/WelcomeTourStepRegistrar.php`, `docs/steps-and-settings.md`, `docs/overview.md`. | Done | M | Med | §4 | ## Completion Review Completed 2026-06-06. Every prioritized roadmap row is closed, plan text now matches shipped behavior, and the remaining notes are future platform polish rather than active improvement-plan scope. Verification for the final slice used PHP lint, JSON validation, screenshot manifest validation, and whitespace checks; Pest/composer tests were intentionally skipped per instruction.