README update

README.md

@@ -1,7 +1,7 @@
 # PROMETEU Runtime
 
 PROMETEU is an educational and experimental fantasy handheld / fantasy console.
-This repository contains the Rust runtime workspace for the machine: VM-facing components, virtual peripherals, host integration, CLI entrypoints, development utilities, specs, and discussion artifacts.
+This repository contains the Rust runtime workspace for the machine: VM-facing components, virtual peripherals, firmware/system services, host integration, CLI entrypoints, development utilities, specs, and discussion artifacts.
 
 The VM is only one subsystem of the machine. The canonical docs in this repository intentionally distinguish:
 
@@ -41,21 +41,29 @@ This repository is a Rust workspace rooted at [Cargo.toml](Cargo.toml) with memb
 - `crates/dev`
 
 The main user-facing dispatcher binary is `prometeu`, built from `crates/tools/prometeu-cli`.
+The same package also builds `prometeu-runtime`, which embeds the current desktop host runtime.
 
 Current CLI surface:
 
 - `prometeu run <cart>`
 - `prometeu debug <cart> --port <port>`
-- `prometeu build <project-dir>`
-- `prometeu pack <cart-dir>`
-- `prometeu verify ...`
 
-Not every command is fully implemented in every distribution path yet. Today, the runtime flow is the most concrete and the dispatcher forwards execution to specialized binaries when they are available.
+The dispatcher forwards runtime execution to `prometeu-runtime`.
+For lower-level local runs, `prometeu-runtime` also accepts:
+
+- `--run <cart>`
+- `--debug <cart> --port <port>`
+- `--fs-root <path>`
+- `--cap <path>`
+
+Other ecosystem commands, such as build, pack, and verification tooling, are not part of the current dispatcher surface in this workspace.
 
 ## Requirements
 
 - Rust toolchain from [rust-toolchain.toml](rust-toolchain.toml)
 - `rustup` for toolchain installation and management
+- `cargo-llvm-cov` for coverage targets such as `make coverage` and `make ci-domains`
+- a local graphical environment for desktop runtime commands
 
 ## Quick Start
 
@@ -77,7 +85,41 @@ Run the current stress cartridge fixture:
 cargo run -q -p prometeu-cli --bin prometeu -- run test-cartridges/stress-console
 ```
 
-The desktop runtime opens a native window through the host layer, so this last command is intended for a local graphical environment.
+Run the embedded runtime binary directly:
+
+```bash
+cargo run -q -p prometeu-cli --bin prometeu-runtime -- --run test-cartridges/stress-console
+```
+
+Regenerate and run the stress cartridge fixture:
+
+```bash
+./scripts/run-stress.sh
+```
+
+The desktop runtime opens a native window through the host layer, so runtime commands are intended for a local graphical environment.
+
+## Validation
+
+Format, lint, and test the workspace:
+
+```bash
+make test
+```
+
+Run the CI-oriented non-domain gate:
+
+```bash
+make ci
+```
+
+Run the CI-oriented domain coverage gate:
+
+```bash
+make ci-domains
+```
+
+The debugger socket tests bind localhost sockets and are marked ignored in Rust test metadata; `make test` includes them through the dedicated `test-debugger-socket` target.
 
 ## Coverage Governance
 
@@ -137,7 +179,7 @@ The project is still in active architectural and implementation convergence.
 
 - the machine contract is being clarified through the specs and discussion workflow;
 - the workspace already contains concrete runtime and host code;
-- some CLI subcommands still act as dispatcher placeholders for binaries that are not always present in a local build or distribution.
+- the CLI dispatcher currently exposes the runtime paths that are backed by binaries in this workspace.
 
 Treat APIs, file formats, and execution flows as evolving unless the relevant spec explicitly defines them as stable.