feat(ui): add Attack Paths product tour (driver.js PoC)

.github/workflows/ui-tests.yml

@@ -131,6 +131,10 @@ jobs:
         if: steps.check-changes.outputs.any_changed == 'true'
         run: pnpm run healthcheck
 
+      - name: Check product-tour alignment
+        if: steps.check-changes.outputs.any_changed == 'true'
+        run: pnpm run tour:check
+
       - name: Run pnpm audit
         if: steps.check-changes.outputs.any_changed == 'true'
         run: pnpm run audit

AGENTS.md

@@ -51,6 +51,7 @@ Use these skills for detailed patterns on-demand:
 | `django-migration-psql` | Django migration best practices for PostgreSQL | [SKILL.md](skills/django-migration-psql/SKILL.md) |
 | `postgresql-indexing` | PostgreSQL indexing, EXPLAIN, monitoring, maintenance | [SKILL.md](skills/postgresql-indexing/SKILL.md) |
 | `prowler-attack-paths-query` | Create Attack Paths openCypher queries | [SKILL.md](skills/prowler-attack-paths-query/SKILL.md) |
+| `prowler-tour` | Keep product-tour definitions aligned with the UI | [SKILL.md](skills/prowler-tour/SKILL.md) |
 | `gh-aw` | GitHub Agentic Workflows (gh-aw) | [SKILL.md](skills/gh-aw/SKILL.md) |
 | `skill-creator` | Create new AI agent skills | [SKILL.md](skills/skill-creator/SKILL.md) |
 
@@ -67,10 +68,12 @@ When performing these actions, ALWAYS invoke the corresponding skill FIRST:
 | Adding new providers | `prowler-provider` |
 | Adding privilege escalation detection queries | `prowler-attack-paths-query` |
 | Adding services to existing providers | `prowler-provider` |
+| Adding, updating, or removing a tour definition (*.tour.ts) | `prowler-tour` |
 | After creating/modifying a skill | `skill-sync` |
 | App Router / Server Actions | `nextjs-16` |
 | Auditing check-to-requirement mappings as a cloud auditor | `prowler-compliance` |
 | Building AI chat features | `ai-sdk-5` |
+| Changing button labels or section headings on a tour-covered page | `prowler-tour` |
 | Committing changes | `prowler-commit` |
 | Configuring MCP servers in agentic workflows | `gh-aw` |
 | Create PR that requires changelog entry | `prowler-changelog` |
@@ -89,6 +92,7 @@ When performing these actions, ALWAYS invoke the corresponding skill FIRST:
 | Creating/updating compliance frameworks | `prowler-compliance` |
 | Debug why a GitHub Actions job is failing | `prowler-ci` |
 | Debugging gh-aw compilation errors | `gh-aw` |
+| Editing a UI file containing data-tour-id attributes | `prowler-tour` |
 | Fill .github/pull_request_template.md (Context/Description/Steps to review/Checklist) | `prowler-pr` |
 | Fixing bug | `tdd` |
 | Fixing compliance JSON bugs (duplicate IDs, empty Section, stale refs) | `prowler-compliance` |
@@ -105,6 +109,8 @@ When performing these actions, ALWAYS invoke the corresponding skill FIRST:
 | Modifying gh-aw workflow frontmatter or safe-outputs | `gh-aw` |
 | Refactoring code | `tdd` |
 | Regenerate AGENTS.md Auto-invoke tables (sync.sh) | `skill-sync` |
+| Renaming or removing a data-tour-id attribute value | `prowler-tour` |
+| Restructuring routes or layouts covered by a tour | `prowler-tour` |
 | Review PR requirements: template, title conventions, changelog gate | `prowler-pr` |
 | Review changelog format and conventions | `prowler-changelog` |
 | Reviewing JSON:API compliance | `jsonapi` |

skills/prowler-tour/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: prowler-tour
+description: >
+  Keeps product-tour definitions aligned with the UI features they describe.
+  Trigger: When modifying UI components that have associated tours, editing tour
+  definition files, or renaming data-tour-id attributes.
+license: Apache-2.0
+metadata:
+  author: prowler-cloud
+  version: "1.0"
+  scope: [root, ui]
+  auto_invoke:
+    - "Editing a UI file containing data-tour-id attributes"
+    - "Adding, updating, or removing a tour definition (*.tour.ts)"
+    - "Renaming or removing a data-tour-id attribute value"
+    - "Changing button labels or section headings on a tour-covered page"
+    - "Restructuring routes or layouts covered by a tour"
+allowed-tools: Read, Glob, Grep
+---
+
+# prowler-tour
+
+**Report-only.** This skill never edits tour files or UI files; it inspects
+the change, reports drift it finds between tours and the covered UI, and
+recommends actions for the developer to apply.
+
+## Early-exit rule
+
+Run this check first. Most UI edits are not tour-related — exit cheaply.
+
+1. Glob `ui/lib/tours/*.tour.ts`.
+2. For each tour, check whether any `coversFiles` glob pattern matches any
+   file in the current change.
+3. If no tour matches, respond **exactly**:
+
+   > No tour affected — skipping alignment check
+
+   and exit. Do not proceed to the checklist.
+4. If at least one tour matches, continue to "Drift checklist" for that tour.
+
+## Drift checklist
+
+For each affected tour, evaluate every item. Skip items that obviously do
+not apply, but list explicitly which items were checked.
+
+1. **Orphan selectors** — every step's `target` (which composes to
+   `data-tour-id="<tour-id>-<step.target>"`) must resolve to a real element
+   in the codebase. Grep `ui/` for the expected attribute value; report
+   any step whose target is missing.
+2. **Renamed selectors** — a `data-tour-id` attribute was edited in this
+   change. Match it back to any tour step referencing the old value.
+3. **Outdated copy** — a popover `title`/`description` references a button
+   label, heading, or term that no longer exists on the covered page.
+4. **Obsolete steps** — a step describes a section, panel, or workflow
+   that was removed.
+5. **Missing steps** — a new feature was added on the covered surface
+   without a corresponding step (e.g. a new panel, a new primary action,
+   a new wizard stage).
+6. **Reordered flow** — the user's path through the feature changed (e.g.
+   query builder moved before scan selection) and the step order no
+   longer reflects it.
+
+## Version-bump decision tree
+
+Apply per tour after listing drift:
+
+- **NO bump** when the change is cosmetic. Examples: fix a typo, soften
+  copy, rename a `data-tour-id` selector while keeping the same step,
+  swap one screenshot for another, tighten wording.
+- **BUMP `version`** when the user-visible flow changes materially.
+  Examples: a new step was added or removed; the order changed; an
+  anchored target was retargeted to a different panel; the tour now
+  covers a new feature on the surface.
+
+When in doubt, ask: "Would a user who already saw the previous version
+miss something useful by not seeing this one?" If yes, bump.
+
+## Output format
+
+When emitting a report, follow the exact structure in
+`references/output-format.md`. The structure is mandatory because the
+report is consumed downstream and tolerates no field reordering.
+
+## What this skill MUST NOT do
+
+- Do not edit `*.tour.ts` files. This skill is report-only.
+- Do not edit UI files to add or rename `data-tour-id` attributes.
+- Do not invent new tours. Authoring a new tour is a separate, deliberate
+  decision — the developer makes it, not the skill.
+- Do not flag drift in tours whose `coversFiles` do not match any file
+  in the current change. Stick to the early-exit rule.
+
+## See also
+
+- `references/output-format.md` — exact report template (read when
+  emitting a report).
+- `references/tours-architecture.md` — code map for the tour abstraction
+  under `ui/lib/tours/`.
+- `assets/tour-template.ts` — boilerplate for authoring a new `*.tour.ts`.

skills/prowler-tour/assets/tour-template.ts

@@ -0,0 +1,51 @@
+// @ts-nocheck -- template only; resolves once copied into `ui/lib/tours/`
+/**
+ * Tour template — copy this file to `ui/lib/tours/<your-id>.tour.ts` and
+ * fill in the placeholders. See `references/tours-architecture.md` for the
+ * design context.
+ *
+ * Conventions:
+ *   - Declare via `defineTour({...})` (NOT `: TourDefinition`) so TS
+ *     preserves the literal union of `target` values. `useDriverTour` uses
+ *     that union to validate `stepHandlers` keys and `waitForStep` args.
+ *   - `id` is kebab-case and unique across all tours.
+ *   - Anchored steps reference DOM via `data-tour-id="<id>-<step.target>"`;
+ *     the hook composes the CSS selector automatically.
+ *   - `coversFiles` lists the globs that describe the tour's surface; the
+ *     `prowler-tour` skill consumes this to decide whether to evaluate
+ *     drift on a given change.
+ *   - Material flow changes bump `version`; cosmetic edits do not.
+ */
+import {
+  defineTour,
+  TOUR_STEP_ALIGNMENTS,
+  TOUR_STEP_SIDES,
+} from "@/lib/tours/tour-types";
+
+export const yourTour = defineTour({
+  id: "your-tour-id",
+  version: 1,
+  coversFiles: [
+    // List the UI files this tour describes, using globs under `ui/`.
+    // Example: "ui/app/(prowler)/your-feature/**"
+  ],
+  steps: [
+    {
+      // Modal step — no anchor. Use for intros, outros, and any step
+      // that does not point at a specific DOM element.
+      title: "Welcome",
+      description: "Short, plain-English description.",
+    },
+    {
+      // Anchored step. The hook resolves
+      // `[data-tour-id="your-tour-id-step-name"]` lazily, so the element
+      // can be conditionally rendered as long as it exists when the step
+      // becomes active.
+      target: "step-name",
+      side: TOUR_STEP_SIDES.BOTTOM,
+      align: TOUR_STEP_ALIGNMENTS.START,
+      title: "Where the action is",
+      description: "Tell the user what to look at here and why.",
+    },
+  ],
+});

skills/prowler-tour/references/output-format.md

@@ -0,0 +1,31 @@
+# Tour Alignment Report — output format
+
+The report is consumed downstream. Field names, order, and headings are
+load-bearing — do not rename, reorder, or omit them.
+
+## Template
+
+```text
+## Tour Alignment Report
+**Tour:** `<tour-id>@v<version>`
+**Files touched:** <comma-separated list of files in the change>
+
+### Drift detected
+- <one bullet per drift item; include file:line where available>
+
+### Recommended actions
+1. <numbered, actionable steps the developer should take>
+
+### Version bump verdict
+- <BUMP | NO bump> — <one-line rationale>
+```
+
+## Rules
+
+- One report per affected tour. If multiple tours are affected, separate
+  reports with a `---` line.
+- If no drift is detected for an affected tour, still emit the report:
+  put "No drift detected." under "Drift detected" and "None required."
+  under "Recommended actions". The verdict line is still mandatory.
+- The verdict is exactly one of `BUMP` or `NO bump` — see the
+  version-bump decision tree in `SKILL.md`.

skills/prowler-tour/references/tours-architecture.md

@@ -0,0 +1,44 @@
+# Tours Architecture
+
+The product-tour abstraction lives under [`ui/lib/tours/`](../../../ui/lib/tours/).
+This skill operates on tour definitions that follow this architecture.
+
+## Code map
+
+| File | Purpose |
+|---|---|
+| `ui/lib/tours/tour-types.ts` | Public type surface: `TourDefinition`, `TourStep`, `TourId`, `TourCompletionRecord`, completion-state const map. Also exports `defineTour(...)` — the required authoring helper that preserves literal step `target`s so `useDriverTour` can type-check `stepHandlers` keys and `waitForStep` arguments. |
+| `ui/lib/tours/tour-config.ts` | `baseDriverConfig`, `getDriverConfig(theme, overrides?)`, overlay-color map. |
+| `ui/lib/tours/store/tour-completion-store.ts` | Persistence interface — the swap point for future API adapters. |
+| `ui/lib/tours/store/local-storage-adapter.ts` | The only adapter in the PoC. Key format: `prowler.tour.<id>.v<version>`. |
+| `ui/lib/tours/use-driver-tour.ts` | React hook. Initializes driver.js, derives `overlayColor` from `useTheme()`, persists completion. |
+| `ui/lib/tours/<id>.tour.ts` | One file per tour. Declared via `defineTour({...})` (not `: TourDefinition`) and imported by the page that opts the user in. |
+| `ui/styles/tours.css` | `.driver-popover.prowler-theme` — every color resolved via `var(--...)` from `globals.css`. |
+
+## Selector convention
+
+Tour steps anchor via `data-tour-id="<tour-id>-<step.target>"`. The hook
+composes the CSS selector at runtime; tour authors only provide the step
+name in `step.target`. Class-based, ID-based, structural selectors are
+forbidden — they couple tours to styling decisions that legitimately
+change.
+
+## Identity and versioning
+
+A tour is `{ id, version }`. The localStorage key composes both. A
+**material content change** bumps `version`; cosmetic edits do not. The
+decision tree lives in the parent SKILL.md.
+
+## Persistence scope
+
+Per-user, cross-tenant. A user who completed `attack-paths@v1` in tenant
+A does not see the tour again in tenant B, even if they can access the
+feature there. The future `UserTourState` model (documented in
+`design.md`, not built) is FK to `User`, not `Membership`.
+
+## Drift = #1 risk
+
+Without the maintenance skill + the optional CI gate
+(`ui/scripts/check-tour-alignment.mjs`), tours decay silently as the
+covered UI evolves. The parent SKILL.md enumerates the six drift
+categories the skill checks for.

ui/AGENTS.md

@@ -14,40 +14,46 @@
 > - [`playwright`](../skills/playwright/SKILL.md) - Page Object Model, selectors
 > - [`vitest`](../skills/vitest/SKILL.md) - Unit testing with React Testing Library
 > - [`tdd`](../skills/tdd/SKILL.md) - TDD workflow (MANDATORY for UI tasks)
+> - [`prowler-tour`](../skills/prowler-tour/SKILL.md) - Keep product-tour definitions aligned with the UI
 
 ## Auto-invoke Skills
 
 When performing these actions, ALWAYS invoke the corresponding skill FIRST:
 
-| Action                                                         | Skill               |
-| -------------------------------------------------------------- | ------------------- |
-| Add changelog entry for a PR or feature                        | `prowler-changelog` |
-| App Router / Server Actions                                    | `nextjs-16`         |
-| Building AI chat features                                      | `ai-sdk-5`          |
-| Committing changes                                             | `prowler-commit`    |
-| Create PR that requires changelog entry                        | `prowler-changelog` |
-| Creating Zod schemas                                           | `zod-4`             |
-| Creating a git commit                                          | `prowler-commit`    |
-| Creating/modifying Prowler UI components                       | `prowler-ui`        |
-| Fixing bug                                                     | `tdd`               |
-| Implementing feature                                           | `tdd`               |
-| Modifying component                                            | `tdd`               |
-| Refactoring code                                               | `tdd`               |
-| Review changelog format and conventions                        | `prowler-changelog` |
-| Testing hooks or utilities                                     | `vitest`            |
-| Update CHANGELOG.md in any component                           | `prowler-changelog` |
-| Using Zustand stores                                           | `zustand-5`         |
-| Working on Prowler UI structure (actions/adapters/types/hooks) | `prowler-ui`        |
-| Working on task                                                | `tdd`               |
-| Working with Prowler UI test helpers/pages                     | `prowler-test-ui`   |
-| Working with Tailwind classes                                  | `tailwind-4`        |
-| Writing Playwright E2E tests                                   | `playwright`        |
-| Writing Prowler UI E2E tests                                   | `prowler-test-ui`   |
-| Writing React component tests                                  | `vitest`            |
-| Writing React components                                       | `react-19`          |
-| Writing TypeScript types/interfaces                            | `typescript`        |
-| Writing Vitest tests                                           | `vitest`            |
-| Writing unit tests for UI                                      | `vitest`            |
+| Action                                                            | Skill               |
+| ----------------------------------------------------------------- | ------------------- |
+| Add changelog entry for a PR or feature                           | `prowler-changelog` |
+| Adding, updating, or removing a tour definition (\*.tour.ts)      | `prowler-tour`      |
+| App Router / Server Actions                                       | `nextjs-16`         |
+| Building AI chat features                                         | `ai-sdk-5`          |
+| Changing button labels or section headings on a tour-covered page | `prowler-tour`      |
+| Committing changes                                                | `prowler-commit`    |
+| Create PR that requires changelog entry                           | `prowler-changelog` |
+| Creating Zod schemas                                              | `zod-4`             |
+| Creating a git commit                                             | `prowler-commit`    |
+| Creating/modifying Prowler UI components                          | `prowler-ui`        |
+| Editing a UI file containing data-tour-id attributes              | `prowler-tour`      |
+| Fixing bug                                                        | `tdd`               |
+| Implementing feature                                              | `tdd`               |
+| Modifying component                                               | `tdd`               |
+| Refactoring code                                                  | `tdd`               |
+| Renaming or removing a data-tour-id attribute value               | `prowler-tour`      |
+| Restructuring routes or layouts covered by a tour                 | `prowler-tour`      |
+| Review changelog format and conventions                           | `prowler-changelog` |
+| Testing hooks or utilities                                        | `vitest`            |
+| Update CHANGELOG.md in any component                              | `prowler-changelog` |
+| Using Zustand stores                                              | `zustand-5`         |
+| Working on Prowler UI structure (actions/adapters/types/hooks)    | `prowler-ui`        |
+| Working on task                                                   | `tdd`               |
+| Working with Prowler UI test helpers/pages                        | `prowler-test-ui`   |
+| Working with Tailwind classes                                     | `tailwind-4`        |
+| Writing Playwright E2E tests                                      | `playwright`        |
+| Writing Prowler UI E2E tests                                      | `prowler-test-ui`   |
+| Writing React component tests                                     | `vitest`            |
+| Writing React components                                          | `react-19`          |
+| Writing TypeScript types/interfaces                               | `typescript`        |
+| Writing Vitest tests                                              | `vitest`            |
+| Writing unit tests for UI                                         | `vitest`            |
 
 ---
 

ui/CHANGELOG.md

@@ -7,6 +7,7 @@ All notable changes to the **Prowler UI** are documented in this file.
 ### 🚀 Added
 
 - New Scan Jobs view with specific In Progress, Completed, Scheduled tabs [(#11258)](https://github.com/prowler-cloud/prowler/pull/11258)
+- In-product tour for the Attack Paths workflow [(#11383)](https://github.com/prowler-cloud/prowler/pull/11383)
 
 ### 🔄 Changed