# Boot Profiles

Domain: firmware boot flow
Function: normative

This chapter defines how PROMETEU chooses what to execute at startup.

## 1 Boot Target

The current firmware-side boot target concept is:

```rust
enum BootTarget {
  Hub,
  Cartridge { path: String, debug: bool, debug_port: u16 },
}
```

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

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`:

1. firmware loads the requested cartridge;
2. cartridge metadata is read;
3. launch behavior follows cartridge `app_mode`;
4. bytecode execution starts through the cartridge boot protocol defined by the cartridge contract, not by textual entry metadata.

## 3 Launch Resolution by App Mode

For a cartridge boot target:

- `Game` cartridges transition into the game-running pipeline;
- `System` cartridges transition into a Runtime/Hub pipeline dedicated to
  system UI and app hosting.

This preserves the distinction between machine firmware state and app execution mode.

The `System` route must not be treated as the game pipeline running inside a
window. It is a separate runtime profile path oriented around Hub ownership and
WindowManager integration. The initial implementation may be minimal, but the
routing boundary is normative: `System` does not enter `GameRunning` as its
profile pipeline.

## 4 Host CLI Relationship

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.

Host CLI, debugger, and equivalent single-game launch flows are the supported
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.

The foreground/home contract defines `Game -> Home/Shell -> same Game` after a
Game is already running. It does not change direct `--run`, debugger direct
boot, or `--games-root` Home library startup semantics. Home/SystemOS requests
are host/system controls, not guest cartridge boot APIs.

## 5 Firmware State Relationship

Boot target selection feeds into firmware states such as:

- `Reset`
- `SplashScreen`
- `LaunchHub`
- `HubHome`
- `LoadCartridge`
- `GameRunning`
- `AppCrashes`

Additional firmware states may represent dedicated `System` profile execution.
Such states are part of the Runtime/Hub route and do not change the `Game`
pipeline contract.

Boot target is not itself a firmware state. It is an input to the firmware state machine.

## 6 Debug Boot

When booting a cartridge in debug mode:

- firmware/runtime uses the cartridge target path;
- debugger-related startup behavior is enabled;
- execution still follows the same cartridge/app-mode resolution path.

Debug mode changes orchestration, not the cartridge contract.

## 7 Smoke Validation

The local Home library path should be smoke tested in release mode for realistic
interactive speed:

```sh
cargo run --release -p prometeu-host-desktop-winit -- --games-root test-cartridges
```

Direct single-cartridge boot remains a separate validation path:

```sh
cargo run --release -p prometeu-host-desktop-winit -- --run test-cartridges/stress-console
```

## 8 Relationship to Other Specs

- [`12-firmware-pos-and-prometeuhub.md`](12-firmware-pos-and-prometeuhub.md) defines the firmware state machine that consumes boot targets.
- [`13-cartridge.md`](13-cartridge.md) defines cartridge structure.
- [`10-debug-inspection-and-profiling.md`](10-debug-inspection-and-profiling.md) defines the observability/debugging layer.