feat: First-Run Clarity — guided tour, tooltips, and starter questions

.codeyam/scenarios/accessibility-large-text-tour.json

@@ -0,0 +1,54 @@
+{
+  "name": "Accessibility - Large Text Tour",
+  "id": "085146b6-3a6b-480d-bb82-c9ed005a4efd",
+  "url": "/",
+  "dimensions": [
+    "iPhone 16"
+  ],
+  "mocks": {},
+  "deviceState": {
+    "preferences": {
+      "rbWorkoutType": "",
+      "rbDistanceMiles": 4.3,
+      "rbCoachType": "walk",
+      "rbGoalSteps": 10000,
+      "rbShowKeyProviderPicker": false,
+      "rbStartScreen": "tour",
+      "rbActiveEnergyKcal": 210,
+      "rbMinutesSinceMovement": 18,
+      "otterpaceTodayTourSeen": false,
+      "rbShowHistory": false,
+      "rbTheme": "default",
+      "rbStartTab": "today",
+      "rbAskSeedQuestion": "",
+      "rbDate": "2026-06-22",
+      "rbCoachConnected": true,
+      "rbCoachPreviewScroll": "",
+      "rbShowJournalEditor": false,
+      "rbShowCoachDataPreview": false,
+      "rbSteps": 9180,
+      "rbCoachHeadline": "So close, 820 to go!",
+      "rbContentSize": "accessibility3",
+      "rbDaysRunThisWeek": 2,
+      "rbLongestRunMiles": 4.2,
+      "rbConnected": true,
+      "rbOpenHint": "",
+      "rbShowWeeklyReview": false,
+      "rbPreviewMode": "",
+      "rbCoachSafety": false,
+      "rbShowSettings": false,
+      "rbWeeklyMileage": 12.4,
+      "rbCoachBody": "You're 820 steps from 10K and it's nearly 9:30pm. One short podcast lap around the block and today's goal is yours.",
+      "otterpaceRacePromptDismissed": true,
+      "rbLoadTrend": "steady",
+      "rbBuddyMood": "cheering",
+      "rbRestDaysThisWeek": 2,
+      "rbTourStep": 1,
+      "rbRacesJSON": "",
+      "rbShowRacePrompt": false,
+      "rbActiveMinutes": 54
+    }
+  },
+  "scenarioType": "application",
+  "pageFilePath": "Sources/AppCore/TodayView.swift"
+}

.codeyam/scenarios/ask-coach-starter-day-one.json

@@ -0,0 +1,54 @@
+{
+  "name": "Ask Coach - Starter Day One",
+  "id": "112f41b9-0c03-499e-93f4-32480f7b7afb",
+  "url": "/",
+  "dimensions": [
+    "iPhone 16"
+  ],
+  "mocks": {},
+  "deviceState": {
+    "preferences": {
+      "rbActiveEnergyKcal": 210,
+      "rbShowWeeklyReview": false,
+      "rbWorkoutType": "",
+      "rbShowCoachDataPreview": false,
+      "rbAskSeedQuestion": "",
+      "rbRestDaysThisWeek": 2,
+      "rbWeeklyMileage": 0.0,
+      "rbTourStep": 0,
+      "rbLongestRunMiles": 0.0,
+      "rbSteps": 1200,
+      "rbCoachBody": "You're at 6,400 steps with easy movement in the bank. A short evening walk would top you off without adding training stress.",
+      "rbCoachHeadline": "Nice steady day",
+      "rbMinutesSinceMovement": 25,
+      "rbShowKeyProviderPicker": false,
+      "rbStartScreen": "",
+      "rbBuddyMood": "ready",
+      "rbGoalSteps": 10000,
+      "rbRacesJSON": "",
+      "rbStartTab": "coach",
+      "rbShowSettings": false,
+      "rbDaysRunThisWeek": 0,
+      "rbActiveMinutes": 6,
+      "otterpaceRacePromptDismissed": true,
+      "rbCoachPreviewScroll": "",
+      "rbCoachSafety": false,
+      "rbDistanceMiles": 0.5,
+      "rbShowJournalEditor": false,
+      "otterpaceTodayTourSeen": true,
+      "rbCoachConnected": true,
+      "rbConnected": true,
+      "rbContentSize": "",
+      "rbCoachType": "walk",
+      "rbOpenHint": "",
+      "rbPreviewMode": "",
+      "rbDate": "2026-06-22",
+      "rbLoadTrend": "steady",
+      "rbShowHistory": false,
+      "rbShowRacePrompt": false,
+      "rbTheme": "default"
+    }
+  },
+  "scenarioType": "application",
+  "pageFilePath": "Sources/AppCore/AskCoachView.swift"
+}

.codeyam/scenarios/ask-coach-starter-race-week.json

@@ -0,0 +1,59 @@
+{
+  "name": "Ask Coach - Starter Race Week",
+  "id": "2fb21e0e-358b-44d6-97d8-581d39892f8b",
+  "url": "/",
+  "dimensions": [
+    "iPhone 16"
+  ],
+  "mocks": {},
+  "deviceState": {
+    "preferences": {
+      "rbCoachHeadline": "Nice steady day",
+      "rbMinutesSinceMovement": 40,
+      "rbOpenHint": "",
+      "rbStartScreen": "",
+      "rbShowCoachDataPreview": false,
+      "rbShowKeyProviderPicker": false,
+      "rbGoalSteps": 10000,
+      "rbCoachBody": "You're at 6,400 steps with easy movement in the bank. A short evening walk would top you off without adding training stress.",
+      "rbTourStep": 0,
+      "rbStartTab": "coach",
+      "rbBuddyMood": "ready",
+      "rbShowHistory": false,
+      "rbAskSeedQuestion": "",
+      "rbShowRacePrompt": false,
+      "rbCoachType": "walk",
+      "rbWorkoutType": "run",
+      "rbContentSize": "",
+      "rbCoachPreviewScroll": "",
+      "rbWeeklyMileage": 12.4,
+      "rbDaysRunThisWeek": 2,
+      "rbWorkoutDistanceMiles": 4.2,
+      "otterpaceTodayTourSeen": true,
+      "rbSteps": 6400,
+      "rbLoadTrend": "steady",
+      "rbActiveEnergyKcal": 210,
+      "rbCoachConnected": true,
+      "rbDistanceMiles": 3.1,
+      "rbLongestRunMiles": 4.2,
+      "rbCoachSafety": false,
+      "rbPreviewMode": "",
+      "rbShowWeeklyReview": false,
+      "rbDate": "2026-06-22",
+      "rbRestDaysThisWeek": 2,
+      "otterpaceRacePromptDismissed": true,
+      "rbTheme": "default",
+      "rbWorkoutDate": "2026-06-21",
+      "rbShowSettings": false,
+      "rbWorkoutPace": "10:28/mi",
+      "rbWorkoutSource": "healthkit",
+      "rbConnected": true,
+      "rbRacesJSON": "[{\"id\":\"11111111-1111-1111-1111-111111111111\",\"name\":\"October Trail Half\",\"distanceMiles\":13.1,\"date\":\"2026-10-10\",\"location\":\"Bend, OR\"}]",
+      "rbWorkoutDurationMinutes": 44,
+      "rbShowJournalEditor": false,
+      "rbActiveMinutes": 28
+    }
+  },
+  "scenarioType": "application",
+  "pageFilePath": "Sources/AppCore/AskCoachView.swift"
+}

.codeyam/scenarios/ask-coach-tutorial-intro.json

@@ -0,0 +1,59 @@
+{
+  "name": "Ask Coach - Tutorial Intro",
+  "id": "31f5b268-03d9-464b-8898-73bc5ad4f64e",
+  "url": "/",
+  "dimensions": [
+    "iPhone 16"
+  ],
+  "mocks": {},
+  "deviceState": {
+    "preferences": {
+      "rbWorkoutType": "run",
+      "rbTourStep": 0,
+      "rbDaysRunThisWeek": 2,
+      "rbMinutesSinceMovement": 40,
+      "rbStartScreen": "",
+      "rbStartTab": "coach",
+      "rbWorkoutDate": "2026-06-21",
+      "rbPreviewMode": "",
+      "rbShowJournalEditor": false,
+      "rbWorkoutSource": "healthkit",
+      "rbBuddyMood": "ready",
+      "rbCoachHeadline": "Nice steady day",
+      "rbCoachPreviewScroll": "",
+      "rbCoachSafety": false,
+      "rbDistanceMiles": 3.1,
+      "rbShowCoachDataPreview": false,
+      "rbCoachBody": "You're at 6,400 steps with easy movement in the bank. A short evening walk would top you off without adding training stress.",
+      "rbGoalSteps": 10000,
+      "rbShowRacePrompt": false,
+      "rbWorkoutPace": "10:28/mi",
+      "rbConnected": true,
+      "rbActiveEnergyKcal": 210,
+      "otterpaceTodayTourSeen": true,
+      "rbActiveMinutes": 28,
+      "rbAskSeedQuestion": "",
+      "rbShowWeeklyReview": false,
+      "rbOpenHint": "",
+      "rbShowKeyProviderPicker": false,
+      "rbDate": "2026-06-22",
+      "rbLongestRunMiles": 4.2,
+      "rbRacesJSON": "",
+      "rbShowSettings": false,
+      "rbSteps": 6400,
+      "rbWeeklyMileage": 12.4,
+      "rbContentSize": "",
+      "rbCoachConnected": true,
+      "rbCoachType": "walk",
+      "rbLoadTrend": "steady",
+      "otterpaceRacePromptDismissed": true,
+      "rbRestDaysThisWeek": 2,
+      "rbTheme": "default",
+      "rbWorkoutDistanceMiles": 4.2,
+      "rbShowHistory": false,
+      "rbWorkoutDurationMinutes": 44
+    }
+  },
+  "scenarioType": "application",
+  "pageFilePath": "Sources/AppCore/AskCoachView.swift"
+}

.codeyam/scenarios/ask-coach-tutorial-locked.json

@@ -0,0 +1,54 @@
+{
+  "name": "Ask Coach - Tutorial Locked",
+  "id": "58a80956-eafa-4edd-886a-26db8afb5f0d",
+  "url": "/",
+  "dimensions": [
+    "iPhone 16"
+  ],
+  "mocks": {},
+  "deviceState": {
+    "preferences": {
+      "otterpaceRacePromptDismissed": true,
+      "rbMinutesSinceMovement": 40,
+      "rbTheme": "default",
+      "rbRestDaysThisWeek": 2,
+      "rbGoalSteps": 10000,
+      "rbSteps": 6400,
+      "rbCoachSafety": false,
+      "rbPreviewMode": "",
+      "rbAskSeedQuestion": "",
+      "rbStartTab": "coach",
+      "rbRacesJSON": "",
+      "rbLongestRunMiles": 4.2,
+      "rbCoachHeadline": "Nice steady day",
+      "rbDaysRunThisWeek": 2,
+      "rbShowRacePrompt": false,
+      "rbConnected": true,
+      "rbShowSettings": false,
+      "rbWeeklyMileage": 12.4,
+      "rbShowKeyProviderPicker": false,
+      "rbCoachPreviewScroll": "",
+      "rbLoadTrend": "steady",
+      "rbTourStep": 0,
+      "rbShowJournalEditor": false,
+      "rbCoachType": "walk",
+      "rbContentSize": "",
+      "rbDate": "2026-06-22",
+      "rbShowHistory": false,
+      "rbStartScreen": "",
+      "rbWorkoutType": "",
+      "rbShowWeeklyReview": false,
+      "rbBuddyMood": "ready",
+      "rbOpenHint": "",
+      "rbShowCoachDataPreview": false,
+      "rbActiveMinutes": 28,
+      "otterpaceTodayTourSeen": true,
+      "rbCoachConnected": false,
+      "rbDistanceMiles": 3.1,
+      "rbCoachBody": "You're at 6,400 steps with easy movement in the bank. A short evening walk would top you off without adding training stress.",
+      "rbActiveEnergyKcal": 210
+    }
+  },
+  "scenarioType": "application",
+  "pageFilePath": "Sources/AppCore/AskCoachView.swift"
+}

.codeyam/scenarios/today-day-one-no-data.json

@@ -0,0 +1,54 @@
+{
+  "name": "Today - Day One No Data",
+  "id": "e2de689a-0dd6-4af9-ac1b-1aa6d8026fed",
+  "url": "/",
+  "dimensions": [
+    "iPhone 16"
+  ],
+  "mocks": {},
+  "deviceState": {
+    "preferences": {
+      "rbPreviewMode": "",
+      "rbShowWeeklyReview": false,
+      "rbShowCoachDataPreview": false,
+      "rbShowKeyProviderPicker": false,
+      "rbStartScreen": "",
+      "rbCoachBody": "Nothing recorded yet today. Whenever you're ready, a short walk is a friendly first step toward your 10K.",
+      "rbSteps": 0,
+      "rbWeeklyMileage": 0.0,
+      "rbCoachConnected": true,
+      "rbDate": "2026-06-22",
+      "rbActiveEnergyKcal": 0,
+      "rbMinutesSinceMovement": 0,
+      "rbShowJournalEditor": false,
+      "rbBuddyMood": "ready",
+      "rbCoachSafety": false,
+      "rbShowSettings": false,
+      "rbCoachHeadline": "Welcome to Otterpace",
+      "rbRacesJSON": "",
+      "rbWorkoutType": "",
+      "rbConnected": true,
+      "rbCoachType": "move",
+      "rbRestDaysThisWeek": 0,
+      "rbTheme": "default",
+      "rbCoachPreviewScroll": "",
+      "rbActiveMinutes": 0,
+      "rbContentSize": "",
+      "rbDistanceMiles": 0.0,
+      "rbDaysRunThisWeek": 0,
+      "rbGoalSteps": 10000,
+      "rbLongestRunMiles": 0.0,
+      "otterpaceTodayTourSeen": true,
+      "rbLoadTrend": "recovering",
+      "rbOpenHint": "",
+      "rbShowHistory": false,
+      "rbShowRacePrompt": false,
+      "rbTourStep": 0,
+      "rbAskSeedQuestion": "",
+      "otterpaceRacePromptDismissed": true,
+      "rbStartTab": "today"
+    }
+  },
+  "scenarioType": "application",
+  "pageFilePath": "Sources/AppCore/TodayView.swift"
+}