discussion/index.ndjson

@@ -14,7 +14,7 @@
 {"type":"discussion","id":"DSC-0001","status":"done","ticket":"legacy-runtime-learn-import","title":"Import legacy runtime learn into discussion lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["migration","tech-debt"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0001-prometeu-learn-index.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0002-historical-asset-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0003-historical-audio-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0004-historical-cartridge-boot-protocol-and-manifest-authority.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0005-historical-game-memcard-slots-surface-and-semantics.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0006-historical-gfx-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0007-historical-retired-fault-and-input-decisions.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0008-historical-vm-core-and-assets.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0009","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0009-mental-model-asset-management.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0010-mental-model-audio.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0011-mental-model-gfx.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0012-mental-model-input.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0013-mental-model-observability-and-debugging.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0014-mental-model-portability-and-cross-platform.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0015-mental-model-save-memory-and-memcard.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0016-mental-model-status-first-and-fault-thinking.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0017-mental-model-time-and-cycles.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0018","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0018-mental-model-touch.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
 {"type":"discussion","id":"DSC-0002","status":"done","ticket":"runtime-edge-test-plan","title":"Agenda - Runtime Edge Test Plan","created_at":"2026-03-27","updated_at":"2026-04-21","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0037","file":"discussion/lessons/DSC-0002-runtime-edge-test-plan/LSN-0037-domain-gates-must-be-owned-by-the-repository.md","status":"done","created_at":"2026-04-21","updated_at":"2026-04-21"}]}
 {"type":"discussion","id":"DSC-0003","status":"open","ticket":"packed-cartridge-loader-pmc","title":"Agenda - Packed Cartridge Loader PMC","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0002","file":"AGD-0002-packed-cartridge-loader-pmc.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
-{"type":"discussion","id":"DSC-0004","status":"in_progress","ticket":"system-run-cart","title":"Agenda - System Run Cart","created_at":"2026-03-27","updated_at":"2026-07-03","tags":[],"agendas":[{"id":"AGD-0003","file":"AGD-0003-system-run-cart.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-07-03"},{"id":"AGD-0045","file":"AGD-0045-systemos-library-root-home-game-launch.md","status":"accepted","created_at":"2026-07-03","updated_at":"2026-07-03"}],"decisions":[{"id":"DEC-0035","file":"DEC-0035-remove-userland-system-run-cart-and-preserve-direct-boot.md","status":"accepted","created_at":"2026-07-03","updated_at":"2026-07-03","ref_agenda":"AGD-0003"},{"id":"DEC-0036","file":"DEC-0036-systemos-games-root-and-home-game-launch.md","status":"accepted","created_at":"2026-07-03","updated_at":"2026-07-03","ref_agenda":"AGD-0045"}],"plans":[{"id":"PLN-0129","file":"PLN-0129-remove-userland-run-cart-abi-surface.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0035"]},{"id":"PLN-0130","file":"PLN-0130-remove-runtime-run-cart-stub-dispatch.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0035"]},{"id":"PLN-0131","file":"PLN-0131-preserve-direct-cartridge-boot-coverage.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0035"]},{"id":"PLN-0132","file":"PLN-0132-specify-games-root-home-launch-contract.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0036"]},{"id":"PLN-0133","file":"PLN-0133-implement-games-root-library-discovery.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0036"]},{"id":"PLN-0134","file":"PLN-0134-wire-home-game-list-launch-flow.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0036"]},{"id":"PLN-0135","file":"PLN-0135-validate-games-root-launch-end-to-end.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0036"]}],"lessons":[]}
+{"type":"discussion","id":"DSC-0004","status":"in_progress","ticket":"system-run-cart","title":"Agenda - System Run Cart","created_at":"2026-03-27","updated_at":"2026-07-03","tags":[],"agendas":[{"id":"AGD-0003","file":"AGD-0003-system-run-cart.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-07-03"},{"id":"AGD-0045","file":"AGD-0045-systemos-library-root-home-game-launch.md","status":"accepted","created_at":"2026-07-03","updated_at":"2026-07-03"}],"decisions":[{"id":"DEC-0035","file":"DEC-0035-remove-userland-system-run-cart-and-preserve-direct-boot.md","status":"accepted","created_at":"2026-07-03","updated_at":"2026-07-03","ref_agenda":"AGD-0003"},{"id":"DEC-0036","file":"DEC-0036-systemos-games-root-and-home-game-launch.md","status":"accepted","created_at":"2026-07-03","updated_at":"2026-07-03","ref_agenda":"AGD-0045"}],"plans":[{"id":"PLN-0129","file":"PLN-0129-remove-userland-run-cart-abi-surface.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0035"]},{"id":"PLN-0130","file":"PLN-0130-remove-runtime-run-cart-stub-dispatch.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0035"]},{"id":"PLN-0131","file":"PLN-0131-preserve-direct-cartridge-boot-coverage.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0035"]},{"id":"PLN-0132","file":"PLN-0132-specify-games-root-home-launch-contract.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0036"]},{"id":"PLN-0133","file":"PLN-0133-implement-games-root-library-discovery.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0036"]},{"id":"PLN-0134","file":"PLN-0134-wire-home-game-list-launch-flow.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0036"]},{"id":"PLN-0135","file":"PLN-0135-validate-games-root-launch-end-to-end.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0036"]}],"lessons":[]}
 {"type":"discussion","id":"DSC-0005","status":"open","ticket":"system-fault-semantics-and-control-surface","title":"Agenda - System Fault Semantics and Control Surface","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0004","file":"AGD-0004-system-fault-semantics-and-control-surface.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
 {"type":"discussion","id":"DSC-0006","status":"open","ticket":"vm-owned-random-service","title":"Agenda - VM-Owned Random Service","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0005","file":"AGD-0005-vm-owned-random-service.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
 {"type":"discussion","id":"DSC-0007","status":"open","ticket":"app-home-filesystem-surface-and-semantics","title":"Agenda - App Home Filesystem Surface and Semantics","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0006","file":"AGD-0006-app-home-filesystem-surface-and-semantics.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}

discussion/workflow/plans/PLN-0132-specify-games-root-home-launch-contract.md

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

docs/specs/runtime/12-firmware-pos-and-prometeuhub.md

@@ -39,6 +39,10 @@ The VM does not own the machine lifecycle. Firmware does.
   `Hub`, `Task(TaskId)`, and `Overlay`.
 - **Shell task window**: a `WindowManager` window whose owner is
   `WindowOwner::Task(TaskId)`.
+- **Games root**: a host-provided local directory used by Hub/Home to discover
+  Game directory cartridges.
+- **Library entry**: an internal catalog record retained by Hub/SystemOS for a
+  discovered cartridge.
 
 ## 3 POS Responsibilities
 
@@ -65,9 +69,20 @@ PrometeuHub is responsible for:
 - reading cartridge metadata needed for launch decisions;
 - deciding launch behavior based on `AppMode`;
 - managing the system window surface for system-mode apps.
+- presenting the host-provided local games library when `--games-root <dir>` is
+  configured;
+- emitting system-owned launch actions for selected Home entries.
 
 The Hub does not execute bytecode directly. It always delegates execution setup to POS.
 
+For v1, the local games library is Game-only. Hub/Home must not expose Shell or
+System cartridges from the games root. The internal library entry must retain
+the loaded manifest data, `title`, `app_id`, `app_version`, the cartridge path,
+and discovery metadata such as a timestamp or equivalent discovery marker.
+
+The Home UI may display only `title`, `app_id`, and `app_version`. Path and
+operational metadata may remain internal.
+
 ## 5 App Modes
 
 ### Game
@@ -154,6 +169,16 @@ If VM initialization fails, firmware transitions to the crash path.
 
 POS selects the cartridge and its execution context, but the cartridge's initial callable is not chosen by firmware metadata. Execution starts from the cartridge boot protocol defined in [`13-cartridge.md`](13-cartridge.md), currently `func_id = 0`.
 
+When Home launches a discovered Game entry, the request is a system-owned action
+from PrometeuHub to POS/firmware. Firmware must load the selected cartridge
+through the normal cartridge loader and transition to `LoadCartridge` on
+success. This path must not use a guest syscall and must not reintroduce
+userland `run_cart`.
+
+If the selected cartridge cannot be loaded, firmware must leave or return the
+machine in the Hub/Home flow and record the failure through diagnostics or
+logging. A polished Home error surface is not required by v1.
+
 ## 8 Firmware States
 
 The current firmware state model includes:

docs/specs/runtime/13-cartridge.md

@@ -175,10 +175,30 @@ Runtime loading policy:
 
 This is the working runtime/dev form used by the current loader.
 
+Directory cartridges are also the only form discovered by the v1 local Home
+games library. When a host provides `--games-root <dir>`, discovery scans only
+immediate child directories under that root. Each child directory is a candidate
+cartridge.
+
+For the v1 Home games library:
+
+- a candidate must have a valid `manifest.json`;
+- the manifest must declare `app_mode: "Game"`;
+- the library retains the loaded manifest data, `title`, `app_id`,
+  `app_version`, the internal cartridge path, and discovery metadata;
+- invalid candidates are logged or reported as diagnostics and omitted from the
+  Home list;
+- valid non-Game cartridges are omitted from the Game library.
+
+Discovery reads metadata for cataloging. It does not replace the normal
+cartridge loader used when firmware starts the selected cartridge.
+
 ### Packaged `.pmc` form
 
 This form is recognized conceptually by the loader boundary, but its actual load path is not implemented yet.
 
+Packaged `.pmc` cartridges are not discovered by the v1 Home games library.
+
 The cartridge spec therefore distinguishes:
 
 - supported current load form;

docs/specs/runtime/14-boot-profiles.md

@@ -18,6 +18,9 @@ enum BootTarget {
 
 This is a firmware/host orchestration contract, not a guest-visible ABI.
 
+The local Home games library is not a separate firmware boot target. It is host
+configuration consumed by the Hub profile after boot.
+
 ## 2 Boot Modes
 
 ### Hub
@@ -27,6 +30,10 @@ When the boot target is `Hub`:
 - firmware boots into the Hub flow;
 - no cartridge is auto-launched.
 
+If the host also provides `--games-root <dir>`, the Hub may discover and render
+valid Game cartridges from that root. Selecting one is a system-owned Home
+action that requests cartridge loading after the Hub is already running.
+
 ### Cartridge
 
 When the boot target is `Cartridge`:
@@ -59,6 +66,7 @@ Typical host-facing boot intents are:
 - default start -> enter Hub;
 - run cartridge -> boot with cartridge target;
 - debug cartridge -> boot with cartridge target plus debug mode parameters.
+- games-root start -> enter Hub with a local Game library for Home.
 
 The CLI is an entry surface for boot target selection; the firmware contract remains the same underneath.
 
@@ -67,6 +75,30 @@ direct cartridge boot surfaces. Direct boot is not requested by guest bytecode
 through a `system.run_cart` syscall or any other app-callable cartridge boot
 ABI.
 
+`--run <cart>` and `--debug <cart>` are direct cartridge boot profiles. They
+select one cartridge before normal Hub/Home interaction and remain independent
+from the local library.
+
+`--games-root <dir>` is a Hub/Home library configuration. It does not
+auto-launch a cartridge and does not create a guest-visible launch API.
+
+The v1 games root contract is:
+
+- the root contains directory cartridges as immediate child directories;
+- recursive discovery is not performed;
+- only valid cartridges whose manifest declares `app_mode: "Game"` are listed;
+- Shell/System apps, packaged `.pmc` cartridges, remote catalogs, marketplace
+  metadata, search, icons, and rich presentation are outside this profile;
+- invalid candidates are logged and omitted from the Home list;
+- Home entries may display only `title`, `app_id`, and `app_version`;
+- selecting a Home entry requests firmware/SystemOS loading for that cartridge
+  and transitions through `LoadCartridge`;
+- launch failure leaves or returns the machine to Home and records an error.
+
+Game-to-game switching after a game is already active is not part of this boot
+profile. That orchestration belongs to the foreground/home and cartridge switch
+contracts.
+
 ## 5 Firmware State Relationship
 
 Boot target selection feeds into firmware states such as: