---
id: PLN-0133
ticket: system-run-cart
title: Implement Games Root Library Discovery
status: done
created: 2026-07-03
ref_decisions: [DEC-0036]
tags: []
---

## Briefing

`DEC-0036` requires a host-provided games root and an expandable internal
library model before Home can render or launch games. This plan implements the
library discovery and host plumbing only; UI launch wiring is handled by
`PLN-0134`.

## Objective

Add a tested games-root discovery model that scans immediate child directory
cartridges, filters to valid Game manifests, records diagnostics for invalid
candidates, and carries enough metadata for Home rendering and later launch.

## Dependencies

- Source decision: `DEC-0036`.
- `PLN-0132` should be completed first so code follows the documented contract.
- Existing cartridge manifest and directory loader behavior in the console
  crates.
- Existing host CLI and `HostRunner` boot setup.

## Scope

- Add `--games-root <PATH>` to the desktop host CLI.
- Pass the optional games root into the host runner / firmware initialization
  path without changing direct `--run` or `--debug` boot behavior.
- Add a SystemOS-owned games library model for directory cartridge discovery.
- Scan only immediate child directories of the root.
- Read and retain manifest data for each valid candidate.
- Include only candidates whose manifest declares `app_mode: Game`.
- Retain internal cartridge path and operational discovery metadata on each
  entry.
- Emit diagnostics for invalid, unreadable, or non-Game candidates and omit
  them from the returned entries.
- Keep discovery independent from full cartridge launch: discovery reads
  metadata; launch still uses the existing loader in `PLN-0134`.

## Non-Goals

- No Home list rendering.
- No click handling or `LoadCartridge` transition.
- No `.pmc` discovery.
- No recursive scan.
- No Shell/System app catalog.
- No marketplace metadata, icons, search, sorting UI, or polished errors.
- No new guest syscall.

## Execution Method

1. Introduce a library/discovery module in the SystemOS side, preferably under
   `crates/console/prometeu-system/src/services/` unless the existing module
   layout has a more local owner.
2. Define an internal entry type with at least:
   - loaded cartridge manifest data;
   - `title`;
   - `app_id`;
   - `app_version`;
   - internal cartridge path;
   - discovery metadata, using `SystemTime` or another explicit discovery
     marker.
3. Define discovery diagnostics that can be logged by the caller and asserted in
   tests.
4. Implement a scanner that:
   - accepts an optional root path;
   - returns an empty library when no root is configured;
   - iterates only immediate child directories;
   - parses `manifest.json` using structured manifest types, not ad hoc string
     matching;
   - filters to `app_mode: Game`;
   - sorts entries deterministically for stable Home presentation and tests.
5. Add `--games-root <PATH>` to
   [crates/host/prometeu-host-desktop-winit/src/lib.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/lib.rs)
   and pass the path into
   [crates/host/prometeu-host-desktop-winit/src/runner.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/runner.rs).
6. Store or expose the discovered library to firmware/SystemOS in a way that
   `PLN-0134` can consume without re-scanning inside the Home click path.
7. Add focused unit tests using temporary cartridge roots with:
   - one valid Game directory cartridge;
   - one valid non-Game cartridge;
   - one invalid directory;
   - one nested directory that must not be discovered.

## Acceptance Criteria

- `--games-root <PATH>` is accepted by the desktop host CLI.
- Absence of `--games-root` leaves existing Hub boot behavior unchanged.
- Direct `--run <cart>` and `--debug <cart>` behavior remains unchanged.
- Discovery returns only immediate valid Game directory cartridges.
- Each library entry retains manifest data, path, title, app id, app version,
  and discovery metadata.
- Invalid candidates are represented in diagnostics and excluded from entries.
- Discovery does not fully load or boot cartridge programs.

## Tests

- Add and run focused games-library discovery tests in the owning console crate.
- Run `cargo test -p prometeu-system` if the library lives in
  `prometeu-system`.
- Run `cargo test -p prometeu-host-desktop-winit` for CLI/runner plumbing.
- Run `discussion validate`.

## Affected Artifacts

- `crates/console/prometeu-system/src/services/`
- `crates/console/prometeu-system/src/lib.rs` or module exports as needed
- `crates/host/prometeu-host-desktop-winit/src/lib.rs`
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
- `discussion/workflow/plans/PLN-0133-implement-games-root-library-discovery.md`