flowchart TD
  Start["VS Code command turbine.onboarding.start"] --> Ensure["SandboxScaffold.ensureSandbox"]
  Ensure --> List["TurbineClient.listTours"]
  List --> Service["TourService.list_tours"]
  Service --> Catalog["Typed Onboarding Tour catalog"]
  Catalog --> Resolve["OnboardingTargetResolver.resolve"]
  Resolve --> Dto["StepDto with target and resolvedTarget"]
  Dto --> Panel["TourEngine shows picker or step"]
  Panel --> Reveal{"Resolved target kind"}
  Reveal -->|"editor_range"| Editor["openAndReveal sandbox file"]
  Reveal -->|"ui_target"| Ui["highlight or focus VS Code/browser UI target"]
  Panel --> Watch["watchStep for predicate or timed unlock"]
  Panel --> Action{"Action step?"}
  Action -->|"read"| Timer["unlock Next after unlock_after_ms"]
  Action -->|"action"| Run["runStep or VS Code action adapter"]
  Run --> Domain["Validate, Run Quality, Generate API, Seed Results"]
  Run --> Local["Start server, open Swagger, open dashboard, cleanup"]
  Domain --> Result["RunStepResult or action status"]
  Local --> Result
  Result --> Next["unlock Next"]
sequenceDiagram
  participant V as VS_Code
  participant E as TourEngine
  participant L as LSP_Client
  participant S as TourService
  participant C as TourCatalog
  participant R as ActionRunner
  participant T as TargetResolver

  V->>E: turbine.onboarding.start
  E->>V: ensure Onboarding Sandbox
  E->>L: onboarding/listTours
  L->>S: list_tours(sandbox_root)
  S->>C: load typed tours
  S->>T: resolve each target
  T-->>S: resolved editor range or UI target
  S-->>L: ListToursResult
  L-->>E: tours
  E->>V: render step and reveal target
  E->>L: onboarding/watchStep
  V->>E: action button
  E->>L: onboarding/runStep
  L->>R: dispatch action for step
  R-->>L: RunStepResult or status
  L-->>E: result
  E->>V: unlock next and update panel
classDiagram
  class Tour {
    +str id
    +str title
    +tuple steps
  }

  class Step {
    +str id
    +str title
    +str body_markdown
    +HighlightTarget target
    +StepKind kind
    +StepAction action
    +int unlock_after_ms
  }

  class StepAction {
    +StepActionKind kind
    +str label
    +str contract_file
    +str dataset
    +str check_name
    +str datasource
  }

  class TourService {
    +list_tours(sandbox_root) ListToursResult
    +watch_step(tour_id, step_id, translate_uri, sandbox_root) None
    +build_step_edits(tour_id, step_id, sandbox_root) FileEdits
  }

  class OnboardingActionRunner {
    +run(step, services) RunStepResult
  }

  class OnboardingTargetResolver {
    +resolve(sandbox_root, target) ResolvedHighlight
  }

  Tour "1" --> "*" Step
  Step "0..1" --> StepAction
  TourService --> Tour
  TourService --> OnboardingTargetResolver
  OnboardingActionRunner --> StepAction