psukesh · kenowagb · Jul 25, 2026 · Jul 25, 2026
diff --git a/AI/CHANGELOG.md b/AI/CHANGELOG.md
diff --git a/AI/COMPONENT_INDEX.md b/AI/COMPONENT_INDEX.md
@@ -19,6 +19,7 @@ Each component has a self-contained doc that lists its own files, tokens, animat
 | Song Carousel | [components/SongCarousel.md](./components/SongCarousel.md) | Component | `Assets/UI/Style1/SongCarousel/` | Stable | 1.0.0 | carousel, songs, selection, scroll |
 | **Title Screen** | [components/TitleScreen.md](./components/TitleScreen.md) | Component | `Assets/Menu/TitleScreen/` | Beta | 0.2.2 | title, menu, 1P, 2P, vs-bot, tutorial, pushdown-automata |
 | **Player vs Bot** | [components/PlayerVsBot.md](./components/PlayerVsBot.md) | Integration | `Assets/Bot/` | Beta | 0.2.0 | bot, difficulty, two-player, session, tier-names |
+| **Tutorial** | [components/Tutorial.md](./components/Tutorial.md) | Integration | `Assets/Tutorial/` | Beta | 0.6.0 | tutorial, bst, tree, style1, menu-flow, metronome, sample-play, authored-scene, guide-style |
 | **Song Select** | [components/SongSelect.md](./components/SongSelect.md) | Component | `Assets/Menu/SongSelect/` | Beta | 0.1.0 | song-select, carousel, difficulty, 2P, transition |
 | Style 1 Button *(primitive)* | [components/Style1Button.md](./components/Style1Button.md) | Primitive | `Assets/UI/Style1/` | Stable | 1.0.0 | button, nav, press, hover |
 | UI Component Gallery *(tool / board)* | [components/ComponentGallery.md](./components/ComponentGallery.md) | Tool | `Assets/UI/Style1/ComponentGallery/` | Stable | 1.1.0 | board, gallery, showcase, catalog |

diff --git a/AI/INDEX.md b/AI/INDEX.md
@@ -45,6 +45,7 @@ Per-component docs tell you **which code files to read**. You can also **see and
 | **View / test a component live in Unity** | [components/README.md → Accessing in Unity](./components/README.md#accessing-a-component-in-unity) → that component's doc (**Editor & menus** / **Demo**) → [ComponentGallery.md](./components/ComponentGallery.md) if using the board | none — use `Rhythm → Create … Demo Scene` and/or `Rhythm → Setup UI Component Gallery` |
 | **Modify the title screen** | [components/TitleScreen.md](./components/TitleScreen.md) | files listed in that doc |
 | **Player vs Bot / bot difficulty** | [components/PlayerVsBot.md](./components/PlayerVsBot.md) → [TitleScreen.md](./components/TitleScreen.md) | `BotPlayerController`, `GameSession`, `TwoPlayerGameCoordinator` |
+| **BST tutorial / Tutorial? flow** | [components/Tutorial.md](./components/Tutorial.md) → [TitleScreen.md](./components/TitleScreen.md) | `TutorialController`, `TutorialRuntimeBootstrap`, `MenuSceneController` |
 | **Modify song select / carousel / difficulty** | [components/SongSelect.md](./components/SongSelect.md) | files listed in that doc |
 | **Modify an existing component** | that component's doc in [components/](./components/) | only the files in that doc's "Files" section |
 | **Touch layout / Awake / OnValidate / Initialize / scene UI** | [WORKFLOW.md → Runtime layout & wiring](./WORKFLOW.md#runtime-layout--wiring-mandatory) → [RULES.md](./RULES.md) R-25–R-32 | component doc Files + composition root if wiring |

diff --git a/AI/components/TitleScreen.md b/AI/components/TitleScreen.md
@@ -47,6 +47,7 @@
 - `IMenuInputProvider` / `UnityMenuInputProvider` — input abstraction
 - `GameSession` — persists `PlayerCount`, `SelectedGameMode`, `SelectedBotDifficulty`, `WantsTutorial`
 - [PlayerVsBot.md](./PlayerVsBot.md) — VS Bot difficulty sub-tree + session wiring
+- [Tutorial.md](./Tutorial.md) — Tutorial? after song select → tutorial → chosen level
 - PrimeTween, UniTask, TextMeshPro
 
 ---
@@ -72,23 +73,17 @@ PLAY  [SubTreeRoot = mode-select]
 └── CREDITS   [Disabled placeholder]
 
 mode-select sub-tree:
-  1P  [SubTreeRoot = tutorial-prompt for SinglePlayer]
+  1P  [OnConfirmLeaf → ApplyHumanGameMode(1) + ShowSongSelect]
   ├── VS Bot  [SubTreeRoot = bot-difficulty]
-  └── 2P      [SubTreeRoot = tutorial-prompt for PlayerVsPlayer]
-
-bot-difficulty sub-tree (after VS Bot) — same hanging-tree layout as mode select:
-  Medium  [SubTreeRoot = tutorial-prompt for BotDifficulty.Medium]
-  ├── Easy  [SubTreeRoot = tutorial for Easy]
-  └── Hard  [SubTreeRoot = tutorial for Hard]
-  (Perfect is kept in BotDifficultyConfig / enum but not shown in the menu yet)
-
-tutorial-prompt sub-tree (after choosing a mode / bot difficulty):
-  Tutorial?  [Disabled — question / title only]
-  ├── Yes    [OnConfirmLeaf → ApplyHumanGameMode / ApplyBotGameMode + StartTutorial]
-  └── No     [OnConfirmLeaf → ApplyHumanGameMode / ApplyBotGameMode + ShowSongSelect]
+  └── 2P      [OnConfirmLeaf → ApplyHumanGameMode(2) + ShowSongSelect]
+
+bot-difficulty sub-tree (after VS Bot):
+  Medium / Easy / Hard  [OnConfirmLeaf → ApplyBotGameMode + ShowSongSelect(2)]
 ```
 
-Back from Tutorial? pops to the previous level. Back from bot difficulty pops to mode select.
+Tutorial is offered on **song select** after song + difficulty are locked (`TutorialPromptState`). Yes → tutorial → GameScene with the chosen song. See [Tutorial.md](./Tutorial.md).
+
+Back from bot difficulty pops to mode select.
 `GameSession.SelectedGameMode`, `SelectedBotDifficulty`, and `PlayerCount` persist into GameScene.
 Player vs Bot reuses the existing two-screen layout (`PlayerCount = 2`) with `BotPlayerController` driving P2.
 

diff --git a/AI/components/Tutorial.md b/AI/components/Tutorial.md
@@ -0,0 +1,98 @@
+# Tutorial — BST insertion lesson
+
+> **Category:** Integration · **Folder:** `Assets/Tutorial/` · **Status:** Beta · **Version:** 0.6.0
+
+Uses the **real GameScene level stack** (`TreeRhythmController`, Score HUD, falling notes on `NotePathBehaviour`). Metronome ticks instead of song audio; side guide panels during the lesson.
+
+`Tutorial.unity` is **authored content**: the camera rig, synthwave background, note path, Score HUD and every `GameController` reference live in the scene file, matching GameScene. Nothing is generated or "repaired" at run time — `TutorialRuntimeBootstrap` only loads the lesson assets and flips the scene controller into tutorial mode, and reports missing pieces as errors.
+
+Guide look (panel size, type, colors, eyebrow labels) is editable on **`DefaultTutorialGuideStyle.asset`** — rebuild the hierarchy with the **Build Guide UI Layout** button on `TutorialController` after changing layout fields.
+
+---
+
+## Flow
+
+1. Title → mode → **Tutorial?** (Yes / No on the title BST via `BuildTutorialPromptAfterMode`) → **song select** → pick song + difficulty.
+2. Yes → `GameSession.WantsTutorial` → after difficulty lock-in, `MenuSceneController.StartTutorialFromSongSelect` → tutorial scene → **selected level**. No → countdown → GameScene.
+3. Human **2P**: P1 tutorial → scene reload → P2 tutorial (Player2 action map) → GameScene.
+4. Lesson steps: BST BASICS → INSERT 6 → GO RIGHT → GO LEFT → PLACE IT → auto **COMPLETE** → level (or P2 turn in 2P).
+
+> Note: `TutorialPromptState` / the Song Select UGUI Tutorial? panel exist in the tree but are **not** on the live path — the live Yes/No is the title BST prompt.
+
+---
+
+## Style inspection report
+
+| # | Item | Reused asset / reference |
+| --- | --- | --- |
+| 1 | **Gameplay look** | `Assets/Scenes/GameScene.unity` — same controller, HUD, note path, synthwave |
+| 2 | **Guide overlay** | Style1 side panels — look driven by `TutorialGuideStyle` |
+| 3 | **Rhythm** | `RhythmManager` + `RhythmVisualizerController` + `HitWindowConfig` |
+| 4 | **Metronome** | `TreeAnimationConfig.MetronomeClip` on `OnBeatPulse` (song skipped via metronome-only mode) |
+| 5 | **Tree / carrier** | `TreeRhythmController` navigator + previews (same as level) |
+
+---
+
+## UI hierarchy
+
+```
+GameScene-identical world: tree, LeftNotePath (+ NoteHitSpot timing bar), NoteContainer, ScoreHUD_P1
+Synthwave floor (+ mountains); sky disabled for tutorial
+TutorialGuideCanvas (sort 30)
+├── LeftGuidePanel  — headline + hint (left margin)
+└── RightGuidePanel — binding + continue prompt (right margin)
+```
+
+Center stays clear for gameplay. Side panels sit in the left/right margins. Score HUD is Overlay, top-left only (not full-screen).
+
+---
+
+## Files
+
+| File | Role |
+| --- | --- |
+| `Assets/Tutorial/TutorialRuntimeBootstrap.cs` | Loads lesson assets, puts the scene's `TreeRhythmController` in tutorial mode |
+| `Assets/Tutorial/TutorialPresentationGuards.cs` | Per-play guards: sky hidden, GameScene `NoteHitSpot` hit bar present |
+| `Assets/Tutorial/TutorialAssetPaths.cs` | Canonical asset paths used by editor-time setup only |
+| `Assets/Tutorial/TutorialBootstrapRefs.cs` | Play-mode-safe asset bundle (`Resources/TutorialBootstrapRefs.asset`) |
+| `Assets/Tutorial/TutorialController.cs` | Step orchestrator; drives `TreeRhythmController` tutorial mode |
+| `Assets/Tutorial/TutorialSceneController.cs` | Exit → GameScene (or P2 tutorial reload in 2P) |
+| `Assets/Tutorial/TutorialLayoutBuilder.cs` | Left/right side guide panels (reads `TutorialGuideStyle`) |
+| `Assets/Tutorial/TutorialUILayout.cs` | Cached guide refs |
+| `Assets/Tutorial/TutorialGuideStyle.cs` | Editable guide UI look — sizes, colors, labels |
+| `Assets/Tutorial/TutorialLessonConfig.cs` | Scripted steps + starting tree |
+| `Assets/Tutorial/TutorialSampleSession.cs` | Seeds `GameSession` for direct Tutorial play |
+| `Assets/Tutorial/TutorialSampleBootstrap.cs` | Auto-applies sample session on Tutorial scene load |
+| `Assets/Tutorial/Editor/TutorialEditorTools.cs` | `Rhythm/Play Sample Tutorial`, `Rhythm/Setup Tutorial Scene`, `Rhythm/Validate Tutorial Scene` |
+| `Assets/ScriptableObjects/Tutorial/DefaultTutorialLesson.asset` | Default lesson |
+| `Assets/ScriptableObjects/Tutorial/DefaultTutorialGuideStyle.asset` | Default guide UI look |
+| `Assets/ScriptableObjects/Tutorial/TutorialMetronomeBeatmap.asset` | 60 BPM metronome beatmap (created by editor menu) |
+| `Assets/Menu/Data/MenuTutorialPromptTree.cs` | Builds Tutorial? / Yes / No BST tree after song lock-in |
+| `Assets/Menu/SongSelect/TutorialPromptState.cs` | Shows tree prompt via `MenuTreeController` |
+| `Assets/Scenes/Tutorial.unity` | Tutorial scene |
+
+**Shared dependencies:** `TreeRhythmController`, `RhythmVisualizerController`, `ScoreHUDController`, `Style1Palette`, `Style1Typography`, `GameSession`, `SceneTransitionManager`.
+
+---
+
+## Editor & menus
+
+| Menu | Action |
+| --- | --- |
+| `Rhythm → Play Sample Tutorial` | **Preview:** open Tutorial.unity and Play (lesson loops) |
+| `Rhythm → Setup Tutorial Scene` | Refresh lesson/beatmap/Resources assets, relink the driver, save, report wiring |
+| `Rhythm → Validate Tutorial Scene` | Read-only per-item wiring report (no changes) |
+
+None of these rebuild the scene's presentation. If `Tutorial.unity` is damaged, restore it from version control — it is authored content, not generated output.
+
+**Quick preview:** **`Rhythm → Play Sample Tutorial`** — no Menu flow needed. `TutorialSampleBootstrap` seeds a sample song session on `Awake`, runs the BST lesson with metronome + side panels, then restarts so you can iterate.
+
+**Full game flow:** Open **Menu.unity** → Play → mode → Tutorial? Yes → song → difficulty.
+
+---
+
+## Version · Tags
+
+**0.6.0** · tutorial, game-level, metronome, side-panels, style1, song-select-flow, bst-tree-prompt, sample-play, authored-scene, guide-style
+
+**Last updated:** 2026-07-25