diff --git a/.gitignore b/.gitignore index f688fd3..26622bc 100644 --- a/.gitignore +++ b/.gitignore @@ -66,7 +66,3 @@ AGENTS.md .python-version .venv - -discussion/* -!discussion/lessons/ -!discussion/lessons/** diff --git a/README.md b/README.md index ca4a821..a6e2b47 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,14 @@ # 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, firmware/system services, 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 engineering lessons. The VM is only one subsystem of the machine. The canonical docs in this repository intentionally distinguish: - machine-level specs; - VM/runtime internal architecture; - implementation crates; -- discussion workflow and lessons learned. +- engineering lessons learned. ## What This Repository Contains @@ -19,7 +19,7 @@ The VM is only one subsystem of the machine. The canonical docs in this reposito - `docs/specs/runtime/`: canonical PROMETEU machine specs - `docs/vm-arch/`: canonical VM/runtime architecture and ISA references - `devtools/`: debugger protocol material -- `discussion/`: agendas, decisions, plans, and lessons for architectural work +- `discussion/lessons/`: published engineering lessons and supporting assets - `test-cartridges/`: cartridge fixtures used for validation and manual runs ## Canonical Documentation @@ -29,7 +29,11 @@ Use these entrypoints instead of inferring the model from isolated source files: - [Machine specs](docs/specs/runtime/README.md): authoritative contract for the PROMETEU machine, peripherals, firmware, cartridge format, timing, and host ABI - [VM architecture](docs/vm-arch/ARCHITECTURE.md): authoritative internal architecture for VM/runtime invariants - [ISA reference](docs/vm-arch/ISA_CORE.md): bytecode-level instruction set authority -- [Discussion workflow](discussion/index.ndjson): architectural agenda, decision, and execution traceability +- [Engineering lessons](discussion/lessons/): published results and rationale + +Engineering discussions, decisions, plans and execution evidence are maintained in +the enclosing [Prometeu Engineering workspace](../README.md) using +[AI Engineering](../.ai-engineering/README.md). ## Workspace Layout @@ -183,7 +187,7 @@ Improving the global percentage alone is not sufficient review evidence when the The project is still in active architectural and implementation convergence. -- the machine contract is being clarified through the specs and discussion workflow; +- the machine contract is being clarified through the specs and AI Engineering; - the workspace already contains concrete runtime and host code; - the CLI dispatcher currently exposes the runtime paths that are backed by binaries in this workspace.