Guide layer parity — the Tour guide.jsx actually designed (wayfinder map)

[maximsan]

Destination

A locked rebuild spec + build tickets for the app's guide layer, matching prototype/guide.jsx: the four-step Today tour (card callouts with "N of 4", Skip, dots, Next/Done; animated dim-and-highlight frame; no intro overlay; no tab navigation), the event-driven micro-tips (coach cards), and the Settings → Help → App Guide home. Urgent — the shipped tour is off-design; it stays on in the interim with stopgap controls (see Notes).

Notes

• Root cause on record: the prototype's guide layer landed 2026-08-22 00:05 in guide.jsx; the first Tour map (Tour — Learn-tab walking tour (wayfinder map) #191) was charted later that day without searching the prototype for a tour, and specified an invented design (intro overlay, spotlight package, own copy) that Tour: the tourSeen flag and its fate-sharing rules #251–Tour: replay from Profile #253 then faithfully built. Guardrail for this map: every spec statement cites guide.jsx / app.jsx; a prototype change re-opens the citing ticket.
• The design source: prototype/guide.jsx (TOUR_STEPS, TodayTour, micro-tips, App Guide) with state + triggers in prototype/app.jsx, behind the guide tweak.
• What survives from the old build: the tourSeen flag, its write-on-answer moment, fate-sharing with onboardingCompleted, device-local/no-snapshot rule — design-agnostic mechanics, decided on the old map and still good.
• Interim: the tour was not switched off in the end — Tour: the missing controls — Skip, end on tab change, App Guide in Settings was rewritten 28 Aug by product-owner ruling (pre-launch, one user, nobody to protect) and shipped Skip on every card, end-on-tab-change, and Settings → Help & Support → App Guide with Replay Today introduction, all on the existing tour. Only the frame-and-card look and dropping showcaseview wait for the rebuild.
• Grilling tickets consult the grilling + domain-modeling skills; decisions resolve per docs/agents/issue-tracker.md.

Decisions so far

• Can showcaseview draw the guide.jsx callout-and-frame design? — No: the accent ring and cutout radius are mutually exclusive, the 320ms frame move does not exist, and its singleton root-overlay entry cannot die with the screen — build the layer by hand as an in-tree Stack child of the shell and drop the dependency.
• The guide layer's home: App Guide in Settings, replay, and the on/off control — collapsed into the rebuild: the design answers all three parts — App Guide is a nav row under Settings → Help & Support (settings.jsx:590), replay lives on the App Guide screen as Replay Today introduction (guide.jsx:167), and there is no on/off toggle in the design, so none is built.
• Assemble the guide-layer spec and cut the rebuild tickets — nothing left to assemble: the design specifies the layer completely, so the spec and the build are one ticket, the rebuild.
• Micro-tips: triggers, copy, and persistence — all seven ship with the design's copy and triggers; the seen list follows tourSeen (device-local, survives Reset, dies with Delete) rather than the design's progress scope; built by Micro-tips: seven one-time cards, takeable now.

Not yet specified

• Whether the old Profile "Replay the tour" row survives, moves, or dies — decided by The guide layer's home and built by Tour: the missing controls: replay lives on the App Guide screen.
• Reduced-motion treatment of the animated highlight frame — sharpens in the rebuild ticket.
• Whether micro-tip dismissal state shares the tourSeen storage shape — decided by Micro-tips: triggers, copy, and persistence: it does.

Out of scope

• App-wide visual drift (colors, screen layouts, tab naming, the off-ruling "Go Premium" card) — owned by the design-parity map created alongside this one.
• The Today screen's own redesigned layout (CONTINUE LEARNING, PRACTICE accordion) — the tour anchors whatever the screen is; making the screen match the design is the drift map's work.