docs(desktop): define v1 runtime state

[Whiteks1]

Closes #442.

Summary

• Defines Desktop v1 as a functional operator workstation with explicit transitional boundaries.
• Documents that legacy remains the default release runtime where complete operator flow still requires it.
• Documents React as the validated selectable runtime and canonical future direction, but not yet the default release path.
• Classifies desktop(cleanup): post-v1 legacy shell retirement boundary #412 as blocked/re-scope cleanup and feat(desktop): add minimal hypothesis builder #266 as post-v1 unless recut narrowly.

Out of scope

• No code changes.
• No runtime default switch.
• No smoke changes.
• No legacy renderer removal.
• No Launch expansion.
• No ML / N.1 work.

Validation

• git diff --check

Summary by Sourcery

Document the Desktop v1 runtime and release boundary, clarifying the relationship between the legacy and React runtimes and how they factor into the v1 operator workstation release state.

Documentation:

• Define the Desktop v1 release boundary across product, architecture, and target-architecture docs, describing legacy as the default runtime and React as the validated future runtime.
• Clarify that Desktop v1 can ship without making React the default runtime or deleting the legacy shell renderer, and that research_ui remains a transitional API boundary rather than a product surface owner.
• Record the v1-related classification of issues desktop(v1): close controlled migration and define v1 release state #442, desktop(cleanup): post-v1 legacy shell retirement boundary #412, and feat(desktop): add minimal hypothesis builder #266, marking cleanup and hypothesis-builder work as post-v1 or requiring re-scoping.
• Update the desktop README to explain the Desktop v1 runtime state and how to start legacy vs React runtimes for operators.

[sourcery-ai]

Reviewer's Guide

Documents the Desktop v1 runtime/release boundary across desktop docs, ADRs, and README, clarifying that legacy remains the default runtime, React is a validated selectable runtime and future direction, and that certain cleanup/feature issues are post-v1 or require re-scoping.

State diagram for Desktop v1 release boundary and post-v1 work

stateDiagram-v2
  [*] --> Desktop_v0_1

  state Desktop_v0_1 {
    [*] --> Legacy_default
    Legacy_default: Legacy runtime is v0_1 release surface
  }

  Desktop_v0_1 --> Desktop_v1: Define_v1_boundary_issue_442

  state Desktop_v1 {
    direction LR
    Legacy_default_v1: Legacy remains default release runtime
    React_selectable_v1: React is validated selectable runtime
    Transitional_APIs_v1: research_ui is transitional API and reachability boundary

    Legacy_default_v1 --> React_selectable_v1
    React_selectable_v1 --> Transitional_APIs_v1
  }

  Desktop_v1 --> Post_v1_cleanup: Remaining_migration_work

  state Post_v1_cleanup {
    direction TB
    React_default_runtime: Make React the default runtime
    Legacy_renderer_removal: Remove legacy shell renderer
    Launch_boundary_resolution: Resolve remaining Launch_operator_flow boundary

    React_default_runtime --> Legacy_renderer_removal
    Launch_boundary_resolution --> React_default_runtime
  }

  Desktop_v1 --> Blocked_re_scoped_issues: Issues_with_preconditions

  state Blocked_re_scoped_issues {
    direction TB
    Issue_412: Broad_legacy_deletion_blocked_until_preconditions
    Issue_266: Post_v1_or_recut_into_smaller_release_alignment_slice
  }

Loading

File-Level Changes

Change	Details	Files
Define and document Desktop v1 release/runtime boundary in the product surfaces inventory and backlog classification.	Update last-updated metadata for the product surfaces doc. Introduce a "Desktop v1 release boundary" section that formalizes the notion of Desktop v1 as a functional operator workstation with explicit transitional boundaries between legacy and React runtimes. Clarify that release-critical operator flows may still rely on legacy-backed paths and that making React the default runtime or deleting the legacy shell renderer is not required for v1. Replace the previous "Next implementation slices" section with a "Desktop v1 classification" section that tags desktop(v1): close controlled migration and define v1 release state #442 as documentation-only, desktop(cleanup): post-v1 legacy shell retirement boundary #412 as needing re-scope/split, and feat(desktop): add minimal hypothesis builder #266 as post-v1 unless narrowed.	desktop/docs/PRODUCT_SURFACES.md
Clarify Desktop v1 as a release-state boundary in the shell architecture ADR, with explicit runtime expectations and issue classification.	Add a dated clarification section describing Desktop v1 as a release-state boundary rather than a new implementation slice. Document that npm start remains the default release runtime and npm run start:react is a validated selectable React runtime, with React as the canonical future shell direction. Spell out that making React the default runtime is post-v1, and that desktop(cleanup): post-v1 legacy shell retirement boundary #412 cannot be treated as broad legacy deletion and feat(desktop): add minimal hypothesis builder #266 remains post-v1 unless significantly re-scoped.	docs/adr-desktop-shell-architecture.md
Align the desktop target architecture doc with the v1 release boundary definition and its implications for legacy, React, research_ui, and issue status.	Add a dated update section defining Desktop v1 as a functional operator workstation with transitional boundaries, mirroring the core v1 runtime positioning. Document that v1 can ship without deleting the legacy shell renderer or making React the default runtime, while React remains the canonical future direction. Reiterate that research_ui is a transitional API boundary and classify desktop(cleanup): post-v1 legacy shell retirement boundary #412 and feat(desktop): add minimal hypothesis builder #266 as post-v1 or requiring re-scoping to fit the v1 boundary.	docs/desktop-target-architecture.md
Expose the Desktop v1 runtime state in the desktop README and adjust the high-level goals section to match the clarified v1 boundary.	Add a "Desktop v1 Runtime State" section that describes legacy as the default release runtime, React as a validated selectable runtime and future direction, and the npm start / npm run start:react commands for each. Clarify that research_ui is a transitional API and reachability boundary, not the target shell or canonical workspace surface, while emphasizing that v1 can ship as a usable operator workstation during ongoing migration. Update the later bullet list to state that React default runtime, broad legacy removal, and full Launch ownership are post-v1 unless explicitly resolved by later issues.	desktop/README.md

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#442	Document the Desktop v1 release boundary and runtime state (legacy vs React) in the Desktop docs and README, making clear that v1 is a functional operator workstation with transitional boundaries.	✅
#442	Clarify the role and constraints of issue #412 (desktop(cleanup): retire legacy shell renderer) for v1, explicitly stating that legacy shell removal is not required for v1 and that #412 must be re-scoped / treated as blocked until its preconditions are satisfied.	✅
#442	Classify issue #266 (feat(desktop): add minimal hypothesis builder) as post-v1 work unless recut into a much smaller, release-aligned slice, separating it from Desktop v1 closure.	✅

Possibly linked issues

• desktop(v1): close controlled migration and define v1 release state #442: They are the same: the PR precisely documents Desktop v1 release state and issue classifications requested in desktop(v1): close controlled migration and define v1 release state #442.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've left some high level feedback:

• The v1 runtime definition text is repeated with very similar wording across multiple docs; consider centralizing the canonical wording in one place and referencing it elsewhere to reduce future drift.
• There are small inconsistencies in issue formatting (e.g., #442 vs #442) across files; standardizing how issues are referenced would make the guidance easier to scan and maintain.
• In places where you describe what is 'not required' for v1 (e.g., legacy removal, React default), it may help to explicitly call out what does constitute the minimal v1 acceptance criteria to avoid interpretive gaps for future slices.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The v1 runtime definition text is repeated with very similar wording across multiple docs; consider centralizing the canonical wording in one place and referencing it elsewhere to reduce future drift.
- There are small inconsistencies in issue formatting (e.g., `#442` vs #442) across files; standardizing how issues are referenced would make the guidance easier to scan and maintain.
- In places where you describe what is 'not required' for v1 (e.g., legacy removal, React default), it may help to explicitly call out what *does* constitute the minimal v1 acceptance criteria to avoid interpretive gaps for future slices.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}