First-run onboarding: contextual coach-marks + How-to-Play card + dev replay toggle

Teaches the deep, interlocking loop — especially the inverted win condition
(you win by CLEARING EXPEDITIONS, not by surviving base sieges; DR-042/DR-043).

- OnboardingSystem: client-only observe-only PresentationSystemGroup overlay
  (own UIDocument @ sortingOrder 60), soft-gated 10-beat coach-mark sequence
  with a world-space ▶ pointer; never mutates sim / never destroys a ghost.
- OnboardingStepMath: pure, unit-tested step machine (snapshot + IsSatisfied +
  scheme-aware prompts + pointer kinds + persisted-mask helpers).
- HowToPlayPanel: tabbed reference card (Controls / The Loop / Build / Threats /
  Win-Lose), reachable from the main menu and the pause overlay.
- Per-client client-local state in GameSettings (TutorialHints + OnboardingMask
  bitmask, additive) — a Join client keeps its own; a host save-wipe never
  re-teaches. Settings toggle + menu "Replay Tutorial".
- Dev "Force Each Launch" toggle (GameSettings.ForceOnboardingEachLaunch):
  SettingsService.Boot wipes the mask + forces hints on in-memory every launch
  so the tutorial always replays fresh.
- HudSystem suppresses its own location hint while onboarding is active
  (single prompt voice), via OnboardingState + [UpdateAfter(OnboardingSystem)].

Validated green: 20/20 EditMode; Play smoke confirmed overlay render, clean
U+25B6 pointer glyph, no system sort-cycle, and the force-wipe end-to-end.

Docs: DR-043 + session log; reusable lesson archived in the build-gotchas note.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Assets/_Project/Scripts/Client/Settings/GameSettings.cs

@@ -12,7 +12,7 @@ namespace ProjectM.Client
     [Serializable]
     public struct GameSettings
     {
-        public const int CurrentVersion = 1;
+        public const int CurrentVersion = 2;
 
         public int Version;
 
@@ -30,6 +30,13 @@ namespace ProjectM.Client
         public float Music;
         public float Sfx;
 
+        // ---- Onboarding (client-local first-run state; NEVER replicated — a Join client keeps its own,
+        // unlike the host-only SaveData) ----
+        public int TutorialHints;   // 0 = first-run coach-marks off, 1 = on
+        public int OnboardingMask;  // bitmask of completed coach-mark steps (0 = nothing seen; bit i = step i done)
+        public int ForceOnboardingEachLaunch; // DEV: 1 = wipe OnboardingMask + force hints on at every launch so the
+                                              // first-run coach-marks always replay fresh (additive; 0-default off)
+
         /// <summary>Sensible defaults derived from the current display + active quality level.</summary>
         public static GameSettings Defaults()
         {
@@ -47,6 +54,9 @@ namespace ProjectM.Client
                 Master = 1f,
                 Music = 1f,
                 Sfx = 1f,
+                TutorialHints = 1,
+                OnboardingMask = 0,
+                ForceOnboardingEachLaunch = 0,
             };
         }
 
@@ -65,6 +75,9 @@ namespace ProjectM.Client
             s.Master = Mathf.Clamp01(s.Master);
             s.Music = Mathf.Clamp01(s.Music);
             s.Sfx = Mathf.Clamp01(s.Sfx);
+            s.TutorialHints = s.TutorialHints != 0 ? 1 : 0;
+            s.ForceOnboardingEachLaunch = s.ForceOnboardingEachLaunch != 0 ? 1 : 0;
+            // OnboardingMask is an opaque bitmask — deliberately NOT clamped.
             return s;
         }
     }