2026-07-03 20:43:03 +00:00
7 changed files with 743 additions and 2 deletions
--- a/discussion/index.ndjson
+++ b/discussion/index.ndjson
@ -1,4 +1,4 @@
-{"type":"meta","next_id":{"DSC":44,"AGD":45,"DEC":36,"PLN":132,"LSN":51,"CLSN":1}}
+{"type":"meta","next_id":{"DSC":44,"AGD":46,"DEC":37,"PLN":136,"LSN":51,"CLSN":1}}
 {"type":"discussion","id":"DSC-0043","status":"open","ticket":"system-os-cartridge-switch-orchestrator","title":"SystemOS Cartridge Switch Orchestrator","created_at":"2026-07-03","updated_at":"2026-07-03","tags":["runtime","os","lifecycle","game","cartridge","architecture"],"agendas":[{"id":"AGD-0044","file":"AGD-0044-systemos-cartridge-switch-orchestrator.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03"}],"decisions":[],"plans":[],"lessons":[]}
 {"type":"discussion","id":"DSC-0039","status":"abandoned","ticket":"render-pipeline-family-and-future-3d","title":"Render Pipeline Family and Future 3D","created_at":"2026-06-04","updated_at":"2026-06-04","tags":["gfx","renderer","runtime","architecture","pipeline"],"agendas":[{"id":"AGD-0039","file":"AGD-0039-render-pipeline-family-and-future-3d.md","status":"abandoned","created_at":"2026-06-04","updated_at":"2026-06-04","_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."}],"decisions":[],"plans":[],"lessons":[],"_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."}
 {"type":"discussion","id":"DSC-0040","status":"done","ticket":"vm-render-parallel-execution-boundary","title":"VM and Render Parallel Execution Boundary","created_at":"2026-06-04","updated_at":"2026-06-06","tags":["runtime","renderer","vm","concurrency","architecture","perf"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0048","file":"discussion/lessons/DSC-0040-vm-render-parallel-execution-boundary/LSN-0048-render-workers-need-a-closed-packet-contract.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-06"}]}
@ -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"}],"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"}],"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"]}],"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-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":[]}
--- a/discussion/workflow/agendas/AGD-0045-systemos-library-root-home-game-launch.md
+++ b/discussion/workflow/agendas/AGD-0045-systemos-library-root-home-game-launch.md
@ -0,0 +1,161 @@
+---
+id: AGD-0045
+ticket: system-run-cart
+title: SystemOS Library Root and Home Game Launch
+status: accepted
+created: 2026-07-03
+resolved:
+decision:
+tags: [runtime, os, hub, cartridge, launcher, library, game, architecture]
+---
+
+## Contexto
+
+A `DEC-0035` fechou que `system.run_cart` nao deve existir como syscall
+userland e que boot direto por host/CLI/debug deve permanecer.
+
+Isso resolveu a autoridade negativa, mas ainda nao resolveu a experiencia
+desejada para o SO: apontar o runtime para um diretorio raiz de biblioteca,
+fazer a Home listar os cartuchos encontrados ali e permitir que o usuario clique
+em um jogo para carrega-lo.
+
+O objetivo pratico e um "Switch feio": uma lista simples na Home, sem UX final,
+sem marketplace e sem catalogo rico, mas capaz de provar que o SO, e nao o
+guest, escolhe e carrega um cartucho a partir de uma biblioteca local.
+
+## Problema
+
+Hoje temos dois caminhos separados:
+
+- boot direto por `--run <cart>` funciona e carrega um cartucho unico;
+- Hub/Home existe, mas mostra acoes fixas de Shell nativo e nao lista jogos de
+  uma biblioteca real.
+
+Sem uma biblioteca de cartuchos visivel para o SO, o usuario nao consegue
+iniciar jogos a partir da Home. Isso deixa a agenda `system-run-cart` incompleta
+do ponto de vista de produto: removemos o `run_cart` userland, mas ainda falta a
+alternativa correta, que e o SO iniciar cartuchos por acao de usuario.
+
+## Pontos Criticos
+
+- O root da biblioteca deve ser fornecido pelo host como `--games-root <dir>`.
+- O scan inicial deve cobrir subdiretorios imediatos com `manifest.json`.
+- O loader de diretorio existente deve continuar sendo a autoridade para validar
+  cartucho completo; a biblioteca pode ler metadados minimos para listagem.
+- A Home pode mostrar uma lista feia/clicavel; polimento visual fica fora.
+- O clique em um Game deve iniciar `LoadCartridge` pelo firmware/SystemOS, nao
+  por syscall guest.
+- V1 nao precisa tratar retorno de um Game para Home, porque isso pertence a
+  `AGD-0041`.
+- `.pmc`, outros tipos de app, catalogo remoto, marketplace, icones, busca e
+  metadados ricos ficam fora.
+
+## Opcoes
+
+### Opcao A - Biblioteca apenas para listagem
+
+- **Abordagem:** adicionar `--games-root`, escanear manifestos e mostrar jogos
+  na Home, mas sem permitir launch ainda.
+- **Pro:** baixa complexidade; prova descoberta/catalogo local.
+- **Contra:** nao entrega o objetivo principal de carregar jogo pela Home.
+- **Manutenibilidade:** boa, mas valor funcional limitado.
+
+### Opcao B - Home lista biblioteca e carrega Game quando nao ha Game ativo
+
+- **Abordagem:** adicionar `--games-root`, escanear cartuchos locais, renderizar
+  lista simples na Home e permitir clique para carregar um Game via
+  `LoadCartridge`. A primeira versao cobre Home inicial/sem Game residente.
+- **Pro:** entrega o fluxo desejado sem abrir troca completa entre jogos.
+- **Contra:** exige passar biblioteca/acao selecionada entre host, Hub,
+  firmware e loader.
+- **Manutenibilidade:** boa se a fronteira ficar clara: biblioteca descobre,
+  Hub escolhe, firmware carrega.
+
+### Opcao C - Biblioteca mais troca completa entre jogos
+
+- **Abordagem:** Home lista biblioteca e tambem permite `Game A -> Home ->
+  Game B` ja no primeiro passo.
+- **Pro:** cobre a experiencia final.
+- **Contra:** mistura biblioteca com pausa, fechamento, cleanup e falha de load;
+  depende de `AGD-0041` e `AGD-0044`.
+- **Manutenibilidade:** baixa para v1.
+
+## Sugestao / Recomendacao
+
+Recomendo a Opcao B.
+
+O v1 deve permitir:
+
+- host recebe `--games-root <dir>`;
+- o SO/Hub recebe uma lista de cartuchos descobertos;
+- a Home mostra uma lista simples/clicavel de jogos;
+- clicar em um Game carrega o cartucho via firmware `LoadCartridge`;
+- boot direto por `--run <cart>` continua separado e intacto;
+- nenhum guest/app chama `run_cart`;
+- o escopo v1 acontece na Home inicial; retorno de Game para Home fica para
+  `AGD-0041`, e troca `Game A -> Home -> Game B` fica para `AGD-0044`.
+
+Detalhes aceitos para v1:
+
+- scan apenas de subdiretorios imediatos;
+- somente cartuchos `app_mode: Game`;
+- `.pmc` fica para futuro;
+- cartuchos invalidos sao logados e omitidos da lista;
+- o modelo interno deve ser uma entry de biblioteca expansivel, nao apenas um
+  summary de UI. A entry pode manter o manifest carregado em memoria, path
+  interno necessario para launch e metadados operacionais como instante de
+  descoberta/instalacao. A UI v1 mostra apenas `title`, `app_id` e
+  `app_version`, mas futuros metadados ingeridos pela biblioteca poderao ser
+  usados pelo catalogo e pela propria UI;
+- clique carrega imediatamente, sem confirmacao;
+- falha de load volta para Home e registra log/erro.
+
+Essa agenda deve produzir a alternativa correta ao `run_cart` userland: uma
+acao de sistema, iniciada pela Home, que carrega cartucho escolhido pelo usuario
+a partir de uma biblioteca local.
+
+## Perguntas em Aberto
+
+- [x] O argumento deve se chamar `--games-root`.
+- [x] A biblioteca deve escanear apenas subdiretorios imediatos.
+- [x] A listagem v1 deve incluir apenas `app_mode: Game`.
+- [x] O scan deve logar cartuchos invalidos e omiti-los da lista.
+- [x] O Hub/SystemOS deve receber uma entry de biblioteca expansivel, capaz de
+  manter o manifest carregado, path interno para launch e metadados
+  operacionais como timestamp de descoberta/instalacao. A UI v1 so precisa
+  mostrar `title`, `app_id` e `app_version`.
+- [x] O clique deve carregar imediatamente, sem confirmacao.
+- [x] Se um cartucho falha ao carregar, o sistema volta para Home e registra
+  erro/log.
+- [x] Retorno de Game para Home nao pertence a esta agenda; fica para
+  `AGD-0041`.
+- [x] O teste minimo deve provar o fluxo `games-root -> Home list -> click ->
+  LoadCartridge -> GameRunning`?
+
+## Criterio para Encerrar
+
+A agenda pode virar decisao quando estiver claro:
+
+- nome e semantica do argumento de host para root da biblioteca;
+- escopo do scan e metadados minimos;
+- fronteira entre biblioteca, Hub, firmware e loader;
+- politica v1 para cartuchos invalidos;
+- regra v1 para launch quando nao ha Game ativo;
+- fronteira explicita com `AGD-0041` e `AGD-0044`;
+- testes minimos para discovery e launch pela Home.
+
+## Discussao
+
+- 2026-07-03: Agenda criada como continuacao da `DSC-0004` apos a `DEC-0035`.
+  A decisao anterior removeu `run_cart` userland; esta agenda define o caminho
+  correto para o SO/Home carregar jogos a partir de uma biblioteca local.
+- 2026-07-03: Respostas aceitas: usar `--games-root`, escanear apenas
+  subdiretorios imediatos, listar somente Games, deixar `.pmc` e outros apps
+  para depois, logar/omitir invalidos, usar summary com `title`, `app_id` e
+  `app_version`, carregar imediatamente no clique, e deixar retorno para Home
+  sob responsabilidade da `AGD-0041`.
+- 2026-07-03: Modelo de dados refinado: a biblioteca deve produzir entries
+  expansíveis, nao somente summaries de UI. Cada entry pode manter manifest em
+  memoria, path interno de launch e metadados operacionais como timestamp de
+  descoberta/instalacao; a UI v1 escolhe quais campos mostrar, mas o modelo
+  deve permitir que metadados futuros sejam ingeridos e usados pelo catalogo/UI.
--- a/discussion/workflow/decisions/DEC-0036-systemos-games-root-and-home-game-launch.md
+++ b/discussion/workflow/decisions/DEC-0036-systemos-games-root-and-home-game-launch.md
@ -0,0 +1,156 @@
+---
+id: DEC-0036
+ticket: system-run-cart
+title: SystemOS Games Root and Home Game Launch
+status: accepted
+created: 2026-07-03
+ref_agenda: AGD-0045
+tags: []
+---
+
+## Status
+
+Accepted.
+
+## Contexto
+
+`DEC-0035` removed `system.run_cart` from the userland guest ABI and preserved
+direct host/CLI/debug cartridge boot. That decision intentionally did not
+deliver the Home/SO product flow: pointing PROMETEU at a local games directory,
+listing available games in Home, and launching a selected game by user action.
+
+This decision defines the first system-owned replacement for userland
+`run_cart`: a local games-root library discovered by the host/SystemOS and
+exposed through a simple Home UI.
+
+## Decisao
+
+PROMETEU MUST support a host-provided games library root through
+`--games-root <dir>`.
+
+The games root is a directory containing game cartridge directories as immediate
+children. V1 MUST scan only immediate child directories. Recursive discovery is
+out of scope.
+
+The v1 games library MUST include only cartridges whose manifest declares
+`app_mode: Game`. Shell/System apps, `.pmc` packages, remote catalogs,
+marketplace/distribution metadata, rich icons, search, and non-game apps are out
+of scope.
+
+The library MUST produce expandable internal entries, not UI-only summaries.
+Each entry MUST retain enough internal data to launch the cartridge and to grow
+as a catalog model. At minimum, each entry MUST include:
+
+- loaded manifest data;
+- `title`;
+- `app_id`;
+- `app_version`;
+- internal cartridge path;
+- operational discovery metadata, including a timestamp or equivalent discovery
+  marker.
+
+The Home UI v1 SHOULD display only `title`, `app_id`, and `app_version`. It MAY
+hide path and operational metadata.
+
+Invalid cartridge candidates MUST be logged and omitted from the Home game list.
+
+Selecting a listed Game in Home MUST immediately request a system-owned launch
+through firmware/SystemOS, resulting in `LoadCartridge` for that cartridge. This
+MUST NOT use a guest syscall and MUST NOT reintroduce userland `run_cart`.
+
+If launch fails, the machine MUST return to or remain in Home and record an
+error/log. A polished error UI is out of scope.
+
+Booting directly with `--run <cart>` MUST remain separate and unchanged.
+
+Returning from a running Game to Home is outside this decision and belongs to
+`AGD-0041`. Switching from `Game A -> Home -> Game B` after a game is already
+active belongs to `DSC-0043 / AGD-0044`.
+
+## Rationale
+
+The previous `run_cart` surface was wrong because it made cartridge launch look
+like an app/userland capability. The desired behavior is still valid, but the
+authority must live in the system: Home presents available games and the
+firmware/SystemOS loads the selected cartridge.
+
+Using `--games-root` keeps the v1 product model honest: this is a local game
+library, not a general app root. Other app types can be introduced later without
+forcing the first launcher model to pretend it is a full marketplace.
+
+Immediate child scanning keeps discovery deterministic and testable. `.pmc` and
+recursive layouts can be added after the directory-cartridge path is proven.
+
+An expandable entry model avoids prematurely freezing the UI shape as the data
+model. The UI is intentionally simple, but the catalog model needs room for
+future metadata such as package origin, installation/discovery timestamps, rich
+presentation fields, and packaged cartridge details.
+
+## Invariantes / Contrato
+
+- `--games-root <dir>` is the v1 host argument for a local games library.
+- The games root is Game-only in v1.
+- Discovery scans immediate child directories only.
+- Directory candidates without valid Game cartridge metadata are logged and
+  omitted.
+- Library entries are internal catalog records, not direct UI DTOs.
+- The UI v1 displays a simple clickable list and may show only `title`,
+  `app_id`, and `app_version`.
+- The internal entry retains cartridge path and loaded manifest data for launch.
+- Home selection is a system action that enters firmware/SystemOS loading. It is
+  not a guest syscall.
+- `--run <cart>` direct boot remains independent from `--games-root`.
+- Return-to-Home and game-to-game switching are not implemented by this
+  decision.
+
+## Impactos
+
+- **Host:** add a `--games-root <dir>` argument and pass the resolved root into
+  runtime/firmware/SystemOS initialization.
+- **SystemOS / Hub:** add a local game library model and expose entries to Home.
+  Home must render a minimal clickable list and emit a system-owned launch
+  action for a selected entry.
+- **Firmware:** consume the Home launch action and transition to
+  `LoadCartridge` with the selected cartridge path.
+- **Loader:** continue to validate complete directory cartridges. Discovery may
+  read manifest metadata, but full launch still uses the existing loader.
+- **Runtime / VM:** no userland ABI is added. No guest syscall participates in
+  launch.
+- **Specs / Docs:** document `--games-root`, Game-only v1 discovery, and the
+  distinction between direct boot, games library launch, and future game
+  switching.
+- **Tests:** cover discovery, invalid omission/logging, Home action emission,
+  and the end-to-end path from games root selection to `GameRunning`.
+
+## Alternativas Descartadas
+
+- **List only, no launch:** rejected because it does not satisfy the product
+  goal of starting games from Home.
+- **General app root:** rejected for v1 because Shell/System apps need separate
+  lifecycle and UI contracts.
+- **Recursive discovery:** rejected for v1 to keep semantics deterministic.
+- **`.pmc` discovery:** rejected for v1 because packed cartridge loading is a
+  separate open agenda.
+- **Game-to-game switch now:** rejected because it depends on foreground and
+  cartridge-switch orchestration work in `AGD-0041` and `AGD-0044`.
+
+## Referencias
+
+- Source agenda: `AGD-0045`
+- Userland run-cart removal: `DEC-0035`
+- Foreground/Home return scope: `AGD-0041`
+- Future cartridge switch orchestration: `DSC-0043 / AGD-0044`
+
+## Propagacao Necessaria
+
+- Add or update runtime specs for games-root discovery and Home launch.
+- Add host CLI argument plumbing for `--games-root`.
+- Add a catalog/library entry model.
+- Add Hub/Home list rendering and click handling.
+- Add firmware/SystemOS action routing to `LoadCartridge`.
+- Add tests for discovery, invalid candidates, action emission, and
+  `games-root -> Home click -> GameRunning`.
+
+## Revision Log
+
+- 2026-07-03: Initial draft from `AGD-0045`.
--- a/discussion/workflow/plans/PLN-0132-specify-games-root-home-launch-contract.md
+++ b/discussion/workflow/plans/PLN-0132-specify-games-root-home-launch-contract.md
@ -0,0 +1,103 @@
+---
+id: PLN-0132
+ticket: system-run-cart
+title: Specify Games Root Home Launch Contract
+status: open
+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`
--- a/discussion/workflow/plans/PLN-0133-implement-games-root-library-discovery.md
+++ b/discussion/workflow/plans/PLN-0133-implement-games-root-library-discovery.md
@ -0,0 +1,118 @@
+---
+id: PLN-0133
+ticket: system-run-cart
+title: Implement Games Root Library Discovery
+status: open
+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`
--- a/discussion/workflow/plans/PLN-0134-wire-home-game-list-launch-flow.md
+++ b/discussion/workflow/plans/PLN-0134-wire-home-game-list-launch-flow.md
@ -0,0 +1,104 @@
+---
+id: PLN-0134
+ticket: system-run-cart
+title: Wire Home Game List Launch Flow
+status: open
+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`
--- a/discussion/workflow/plans/PLN-0135-validate-games-root-launch-end-to-end.md
+++ b/discussion/workflow/plans/PLN-0135-validate-games-root-launch-end-to-end.md
@ -0,0 +1,99 @@
+---
+id: PLN-0135
+ticket: system-run-cart
+title: Validate Games Root Launch End To End
+status: open
+created: 2026-07-03
+ref_decisions: [DEC-0036]
+tags: []
+---
+
+## Briefing
+
+`PLN-0132` through `PLN-0134` specify, discover, display, and launch games
+from a local games root. This plan closes the slice by adding end-to-end
+validation evidence and manual smoke instructions for the product behavior the
+user wants: point the SO at a directory, click a listed game, and boot it.
+
+## Objective
+
+Prove the complete `--games-root -> Home list -> click -> LoadCartridge ->
+GameRunning` path while preserving direct `--run` boot and the absence of
+userland `run_cart`.
+
+## Dependencies
+
+- Source decision: `DEC-0036`.
+- `PLN-0132`, `PLN-0133`, and `PLN-0134` must be complete.
+- Existing test cartridge fixtures, especially `test-cartridges/stress-console`.
+
+## Scope
+
+- Add automated integration coverage for the full games-root Home launch path
+  where the existing host/firmware test seams allow it.
+- Add or document a minimal local games-root fixture using existing directory
+  cartridges.
+- Validate invalid-candidate omission at the end-to-end boundary.
+- Validate direct `--run` still works after games-root wiring.
+- Capture manual smoke-test commands for release-mode functional verification.
+
+## Non-Goals
+
+- No new product UI polish.
+- No screenshot automation unless the existing test harness already supports it
+  cleanly.
+- No return-to-Home after a running Game.
+- No Game A -> Home -> Game B orchestration.
+- No `.pmc` validation.
+- No broad performance tuning beyond confirming release-mode smoke behavior.
+
+## Execution Method
+
+1. Add an integration-style firmware or host test that constructs a games root
+   with a valid Game directory cartridge and boots to Hub/Home with that root.
+2. Drive the Home selection path through the same action path used by user
+   input, not by calling the cartridge loader directly.
+3. Assert that the machine reaches `LoadCartridge` or `GameRunning`, depending
+   on the most stable observable state available in the test harness.
+4. Add a negative case with an invalid candidate and assert it is omitted or
+   reported as a diagnostic without appearing in Home.
+5. Add a regression assertion that no public guest syscall named
+   `system.run_cart` is required by this path.
+6. Re-run direct boot tests or add a small regression test proving
+   `--run test-cartridges/stress-console` remains independent from
+   `--games-root`.
+7. Record manual smoke commands in the relevant spec or developer-facing doc:
+   - `cargo run --release -p prometeu-host-desktop-winit -- --games-root test-cartridges`
+   - `cargo run --release -p prometeu-host-desktop-winit -- --run test-cartridges/stress-console`
+
+## Acceptance Criteria
+
+- Automated tests cover a valid games-root Home launch path.
+- Automated tests cover invalid candidate omission or diagnostics at the
+  end-to-end boundary.
+- Automated or documented validation proves direct `--run` still works.
+- Manual smoke instructions use release mode for realistic interactive speed.
+- Validation evidence shows no guest syscall participates in launch.
+- `discussion validate` passes.
+
+## Tests
+
+- Run `cargo test -p prometeu-system`.
+- Run `cargo test -p prometeu-firmware`.
+- Run `cargo test -p prometeu-host-desktop-winit`.
+- Run `cargo test -p prometeu-hal syscalls` to keep the removed syscall surface
+  guarded.
+- Manually smoke test:
+  `cargo run --release -p prometeu-host-desktop-winit -- --games-root test-cartridges`.
+- Manually smoke test:
+  `cargo run --release -p prometeu-host-desktop-winit -- --run test-cartridges/stress-console`.
+- Run `discussion validate`.
+
+## Affected Artifacts
+
+- `crates/console/prometeu-system/`
+- `crates/console/prometeu-firmware/`
+- `crates/host/prometeu-host-desktop-winit/`
+- `crates/console/prometeu-hal/src/syscalls/tests.rs`
+- Runtime specs or developer docs containing smoke commands
+- `discussion/workflow/plans/PLN-0135-validate-games-root-launch-end-to-end.md`