---
id: PLN-0134
ticket: system-run-cart
title: Wire Home Game List Launch Flow
status: done
created: 2026-07-03
ref_decisions: [DEC-0036]
tags: []
---

## Briefing

After `PLN-0133`, SystemOS can discover a local Game library but Home still
does not present or launch those entries. This plan wires the discovered
library into Prometeu Hub/Home and routes a selected game to firmware
`LoadCartridge`.

## Objective

Make Home display a minimal clickable games list and launch the selected Game
through a system-owned firmware/SystemOS path, without reintroducing userland
`run_cart`.

## Dependencies

- Source decision: `DEC-0036`.
- `PLN-0132` for documented contract.
- `PLN-0133` for `--games-root` plumbing and the internal library entry model.
- Existing Prometeu Hub Home profile and firmware state transitions.

## Scope

- Provide the discovered games library to Prometeu Hub/Home.
- Render a minimal Home list showing `title`, `app_id`, and `app_version`.
- Add Home hit-testing/click handling for game entries.
- Extend the system profile action model with a system-owned game launch action.
- Handle that action in firmware/SystemOS by loading the selected cartridge via
  the existing cartridge loader and entering `LoadCartridge`.
- On load failure, log/record the error and keep or return the machine to Home.
- Preserve existing native shell launch behavior.

## Non-Goals

- No polished launcher UI.
- No icons, screenshots, search, filtering, or marketplace metadata.
- No return-to-Home while a Game is running.
- No Game A -> Home -> Game B foreground orchestration.
- No `.pmc` launch support.
- No guest syscall.
- No direct-boot behavior changes.

## Execution Method

1. Extend the SystemOS/Hub action type currently represented by
   `SystemProfileAction::LaunchNativeShell` with a game-launch action that
   carries a stable reference to the selected library entry or cartridge path.
2. Update the Prometeu Hub state in
   [crates/console/prometeu-system/src/programs/prometeu_hub.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/programs/prometeu_hub.rs)
   or its local modules to accept the discovered game entries.
3. Render the Home games list with stable dimensions and simple clickable rows.
   Rows must display only `title`, `app_id`, and `app_version` for v1.
4. Add hit-testing so selecting a row emits the game-launch action immediately.
5. Update
   [crates/console/prometeu-firmware/src/firmware/steps/firmware_step_hub_home.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-firmware/src/firmware/steps/firmware_step_hub_home.rs)
   to consume the new action.
6. In the firmware action handler:
   - call the existing cartridge loader for the selected path;
   - on success, return `FirmwareState::LoadCartridge(...)`;
   - on failure, log/record the error and remain in the Home path.
7. Ensure shell launch still works exactly as before.
8. Add unit or integration tests for:
   - Home list presentation data;
   - click-to-action emission;
   - firmware action handling success;
   - firmware action handling failure.

## Acceptance Criteria

- Starting the host with `--games-root <dir>` exposes valid Game entries in
  Home.
- The Home list displays `title`, `app_id`, and `app_version`.
- Clicking a listed Game routes through a system action and enters
  `LoadCartridge`.
- The launch path does not use a guest syscall and does not mention
  `system.run_cart`.
- Invalid or failing launch paths remain in Home and record an error.
- Existing native shell Home actions continue to work.
- Direct `--run` remains separate and unchanged.

## Tests

- Run `cargo test -p prometeu-system` for Hub action and presentation behavior.
- Run `cargo test -p prometeu-firmware` for firmware transition behavior.
- Run `cargo test -p prometeu-host-desktop-winit` if runner integration changes.
- Run `discussion validate`.

## Affected Artifacts

- `crates/console/prometeu-system/src/programs/prometeu_hub.rs`
- `crates/console/prometeu-system/src/services/`
- `crates/console/prometeu-firmware/src/firmware/steps/firmware_step_hub_home.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
- `discussion/workflow/plans/PLN-0134-wire-home-game-list-launch-flow.md`