moving

docs/addiction-features/06-tour-replay.md

@@ -0,0 +1,80 @@
+# 06 — Tour Replay Button
+
+**Author:** CC (Block B design pass)
+**Date:** 2026-05-01
+**Status:** AWAITING_RATIFICATION
+**Estimate:** ~60 LOC + ~1-1.5h wall-clock
+**Touches:** apps/web (1 file: SettingsApp Advanced tab + useOnboarding hook)
+
+---
+
+## User story
+
+As a returning user (or one who skipped onboarding), I want a "Replay tour" button in Settings → Advanced so I can re-trigger the post-wizard coachmark sequence without having to wipe my onboarding state or use a DEV-only URL parameter.
+
+## Acceptance criteria
+
+1. Settings → Advanced section contains a "Replay onboarding tour" button.
+2. Clicking it: clears the `waggle:tooltips_done` localStorage flag AND the `tooltipsDismissed` field on `onboardingState`, then triggers a re-render so OnboardingTooltips mounts.
+3. Tour content: same 3 BASE_TIPS + CLOSING_TIP as the original tour, optionally including TEMPLATE_TIPS based on current active workspace's templateId.
+4. Button has a subtle confirmation toast ("Tour restarting…") so user knows the click registered.
+5. Optional: "Replay onboarding wizard" sibling button for full-flow restart (clears `waggle:onboarding` localStorage too — DEV/Power users only? PM call).
+
+## UI sketch
+
+```
+Settings App > Advanced tab:
+
+  Section: Help & Tutorials
+
+  [icon] Replay onboarding tour
+  Show the 4-slide coachmark tour again. Useful if you want a refresher
+  on Waggle's core gestures.
+  [ Replay tour ]
+
+  [icon] Replay onboarding wizard (advanced)
+  Restart the full 8-step setup. Will not delete any data — your
+  workspaces, memories, and preferences are preserved.
+  [ Replay wizard ]
+```
+
+## Data model
+
+No new tables. Pure localStorage manipulation:
+- Tour replay: `localStorage.removeItem('waggle:tooltips_done')` + update onboarding state `tooltipsDismissed: false`.
+- Wizard replay: clear `waggle:onboarding` storage entirely; reload page (or set `state.completed = false`).
+
+## Implementation notes
+
+- `useOnboarding` already has a `reset()` function (line 142-146) — use it for the wizard replay path.
+- Add a new `replayTour()` function: clear localStorage tour flag + setOnboardingState(prev => ({ ...prev, tooltipsDismissed: false })).
+- SettingsApp's Advanced tab exists; just add a section.
+- Toast affordance: existing `useToast` hook.
+
+## Estimate
+
+- `replayTour()` in useOnboarding: ~10 LOC
+- SettingsApp section: ~30 LOC
+- Tests (localStorage cleared, state flipped, render): ~20 LOC
+- **Total ~60 LOC, ~1-1.5h with verification.**
+
+## Risks + open questions
+
+1. **Tour vs wizard distinction** — users may not know the difference. Settings copy should make it clear: tour = post-launch coachmarks, wizard = full setup flow. Done above.
+2. **Wizard replay edge cases** — if user already has 5 workspaces and a year of memory, re-running wizard is confusing. Either: (a) hide wizard replay for non-DEV builds, (b) gate behind double-confirm, (c) skip the workspace-creation step on replay. Recommend (b) for v1.
+3. **Tour replay during ongoing tour** — defensive: if Tour is already mounted, click is no-op or restarts the tour from step 0.
+4. **Cross-tab sync** — multi-window users: replay click in one window should re-render Tour in all windows. Existing `waggle:onboarding-sync` event handles this for state; tour localStorage clear needs equivalent broadcast.
+
+## Out of scope (v1)
+
+- Per-workspace tour variants.
+- Custom tour authoring (Power users design their own coachmark sequences).
+- Onboarding wizard partial-replay (resume at step 5 only).
+- Analytics on which sections of tour users replay most often.
+
+## PM decisions needed
+
+- [ ] GO / MODIFY / SKIP
+- [ ] Include "Replay wizard" button alongside tour, or tour-only?
+- [ ] Confirm dialog for wizard replay (yes / skip)
+- [ ] Toast copy ("Tour restarting…" / "Coachmarks reset" / silent)