Skip to content
Capell CMS

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

Section titled “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)

Section titled “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)

Section titled “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

Section titled “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

Section titled “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

Section titled “6. Prioritized Roadmap”
ItemBucketEffortImpactSection 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.DoneMHigh§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.DoneSHigh§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.DoneSMed§2
Done 2026-06-05: README now reflects real src/Data classes and package-specific extension points. Evidence: README.md.DoneSMed§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.DoneSMed§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.DoneSMed§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.DoneSMed§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.DoneSHigh§5
Recapture real Capell Welcome Tour dashboard, overlay, settings, and user-toggle screenshots before marketplace promotion. Deferred until styled runner recapture; no implementation blockerLaterSHigh§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.DoneMHigh§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.DoneMHigh§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.DoneLHigh§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.DoneMMed§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.DoneLMed§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.DoneMMed§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.DoneMMed§4

Completion Review

Section titled “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.