---
id: PLN-0132
ticket: system-run-cart
title: Specify Games Root Home Launch Contract
status: done
created: 2026-07-03
ref_decisions: [DEC-0036]
tags: []
---

## Briefing

`DEC-0036` establishes a new system-owned game library launch path:
the host receives `--games-root <dir>`, SystemOS/Home lists valid Game
directory cartridges from that root, and selecting one starts the cartridge
through firmware loading rather than a guest syscall.

This plan updates the normative specs before code is changed.

## Objective

Document the v1 games-root and Home launch contract in the canonical runtime
specs so implementation plans cannot drift back into userland `run_cart` or
general app-library semantics.

## Dependencies

- Source decision: `DEC-0036`.
- Prior decision: `DEC-0035`, which removed userland `system.run_cart` and
  preserved direct `--run` boot.
- This plan must be completed before `PLN-0133`, `PLN-0134`, and `PLN-0135`.

## Scope

- Update the runtime specs to define `--games-root <dir>` as the v1 local games
  library root.
- Specify that discovery scans only immediate child directories.
- Specify that v1 library discovery includes only valid directory cartridges
  with `app_mode: Game`.
- Specify that `.pmc`, recursive discovery, Shell/System apps, marketplace
  metadata, rich presentation, search, and non-game apps are out of scope.
- Specify the internal library entry contract: loaded manifest data, `title`,
  `app_id`, `app_version`, internal cartridge path, and discovery metadata.
- Specify that Home v1 may display only `title`, `app_id`, and `app_version`.
- Specify that selecting a Home game emits a system-owned launch request that
  transitions through firmware/SystemOS into `LoadCartridge`.
- Specify that invalid candidates are logged and omitted.
- Specify that launch failure remains or returns to Home and logs the failure.
- Reaffirm that direct `--run <cart>` boot remains independent and unchanged.

## Non-Goals

- No Rust implementation.
- No Home UI changes.
- No `.pmc` discovery or packaged-cartridge spec changes.
- No recursive library layout.
- No return-to-Home behavior for a running Game.
- No Game A -> Home -> Game B orchestration.
- No guest syscall or userland ABI addition.

## Execution Method

1. Update [docs/specs/runtime/14-boot-profiles.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/specs/runtime/14-boot-profiles.md) with:
   - direct `--run` boot remaining a single-cartridge boot profile;
   - `--games-root <dir>` as a SystemOS/Home library profile;
   - the distinction between direct boot, Home launch, and future game-switch
     orchestration.
2. Update [docs/specs/runtime/12-firmware-pos-and-prometeuhub.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/specs/runtime/12-firmware-pos-and-prometeuhub.md) with:
   - Home's responsibility to display the local games library;
   - the system-owned launch action boundary;
   - failure handling that leaves the machine in Home and records an error.
3. Update [docs/specs/runtime/13-cartridge.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/specs/runtime/13-cartridge.md) with:
   - directory-cartridge discovery requirements for library candidates;
   - Game-only filtering by manifest `app_mode`;
   - invalid candidate omission and diagnostics.
4. Update [docs/specs/runtime/16-host-abi-and-syscalls.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/specs/runtime/16-host-abi-and-syscalls.md) only if needed to reinforce that no guest syscall owns cartridge launch.
5. Keep all spec text in English.

## Acceptance Criteria

- The specs define `--games-root <dir>` and do not describe it as a generic app
  root.
- The specs state that v1 scans immediate child directories only.
- The specs state that only valid Game directory cartridges enter the Home list.
- The specs state that Home launch is system-owned and enters `LoadCartridge`.
- The specs preserve `--run <cart>` as a separate direct boot path.
- The specs explicitly exclude `.pmc`, recursive discovery, return-to-Home, and
  game-switch orchestration from this implementation slice.
- No spec reintroduces userland `run_cart`.

## Tests

- Run `discussion validate`.
- Run targeted text checks for `--games-root`, `LoadCartridge`, and absence of
  `system.run_cart` as an active public launch mechanism in edited specs.

## Affected Artifacts

- `docs/specs/runtime/12-firmware-pos-and-prometeuhub.md`
- `docs/specs/runtime/13-cartridge.md`
- `docs/specs/runtime/14-boot-profiles.md`
- `docs/specs/runtime/16-host-abi-and-syscalls.md`
- `discussion/workflow/plans/PLN-0132-specify-games-root-home-launch-contract.md`