flowchart TD
    Activate["extension.ts activate"] --> StartComp["onboarding.start()"]
    StartComp --> StartPhase["phaseService.start()"]
    StartPhase --> StartHost["walkthroughHost.start()"]
    StartHost --> SubPhase["subscribe phase + tours"]
    SubPhase --> PublishKeys["publish 5 setContext keys"]
    Activate --> MaybeOpen["maybeOpenWalkthrough()"]
    MaybeOpen --> ReadFlag{"globalState walkthroughShown set?"}
    ReadFlag -- "yes" --> Skip["no-op"]
    ReadFlag -- "no" --> OpenCmd["executeCommand openWalkthrough"]
    OpenCmd --> WriteFlag["globalState.update walkthroughShown = true"]
    Skip --> Done["activation continues"]
    WriteFlag --> Done
    PhaseTick["phase or tour change"] --> Recompute["deriveWalkthroughKeys"]
    Recompute --> PublishKeys
    ResetCmd["turbine.onboarding.reset"] --> ResetActive["composition.resetActive"]
    ResetActive --> ClearFlag["host.reset clears flag + keys = false"]
    ResetActive --> PhaseRefresh["phaseService.refresh"]
    PhaseRefresh --> Recompute
sequenceDiagram
    actor User
    participant VS as vscode
    participant Ext as extension_ts
    participant Comp as OnboardingComposition
    participant Host as WalkthroughHost
    participant Phase as EditorPhaseService
    participant Tours as CompletedToursStore

    Note over User,Tours: First activation after install
    User->>VS: install + reload
    VS->>Ext: activate
    Ext->>Comp: start
    Comp->>Phase: start
    Comp->>Host: start
    Host->>Phase: subscribe onPhaseChange
    Host->>Tours: read list()
    Host->>VS: setContext five keys
    Ext->>Comp: maybeOpenWalkthrough
    Comp->>Host: maybeOpen
    Host->>VS: globalState.get walkthroughShown
    VS-->>Host: undefined
    Host->>VS: executeCommand openWalkthrough
    Host->>VS: globalState.update walkthroughShown true

    Note over User,Tours: Phase change ticks a step
    Phase-->>Host: onPhaseChange lsp-phase needs-turbine
    Host->>VS: setContext pyprojectExists true

    Note over User,Tours: Reset onboarding
    User->>VS: run reset command
    VS->>Comp: resetActive
    Comp->>Tours: clear
    Comp->>Host: reset
    Host->>VS: globalState.update walkthroughShown undefined
    Host->>VS: setContext five keys false
    Comp->>Phase: refresh
    Phase-->>Host: onPhaseChange
    Host->>VS: setContext re-derived values
classDiagram
    class WalkthroughHost {
        +start() void
        +maybeOpen() Promise~void~
        +reset() Promise~void~
        +dispose() void
    }
    class WalkthroughKeys {
        +folderOpen bool
        +uvInstalled bool
        +pyprojectExists bool
        +turbineInstalled bool
        +tourCompleted bool
    }
    class GlobalStateLike {
        <<interface>>
        +get(key) unknown
        +update(key, value) Thenable~void~
    }
    class CommandRunner {
        <<interface>>
        +execute(command, args) Thenable~unknown~
    }
    class PhaseSource {
        <<interface>>
        +current EditorPhase
        +onPhaseChange(listener) Disposable
    }
    class CompletedToursSource {
        <<interface>>
        +list() ReadonlyArray
    }
    class EditorPhase {
        <<union>>
    }
    class CompletedToursStore {
    }
    WalkthroughHost --> GlobalStateLike : globalState
    WalkthroughHost --> CommandRunner : commands
    WalkthroughHost --> PhaseSource : phase
    WalkthroughHost --> CompletedToursSource : completedTours
    WalkthroughHost ..> WalkthroughKeys : produces
    PhaseSource ..> EditorPhase : exposes
    CompletedToursStore ..|> CompletedToursSource