# PROMETEU

PROMETEU is an **educational and experimental ecosystem** inspired by classic consoles, focusing on **teaching programming, system architecture, and hardware concepts through software**.

> PROMETEU is a simple, explicit, and educational virtual machine.

---

## 🎯 Project Goals

- **Simulate simple "logical hardware"**: Create a low entry barrier for understanding how computers work.
- **Deterministic Loop**: Ensure the same code produces the same result on any platform.
- **Total Portability**: The core does not depend on an operating system, allowing it to run from modern computers to dedicated hardware.
- **First-Class Tools**: Offer deep debugging and inspection as a central part of the experience.

---

## 🧠 Design Philosophy

- **No magic**: everything is explicit.
- **No implicit heuristics**: the system doesn't "guess intentions".
- **Deterministic**: same input → same result.
- **Hardware-first**: APIs model peripherals, not modern frameworks.
- **Portable by definition**: if it doesn't work on all platforms, it doesn't exist.

---

## 📦 Monorepo Structure

This repository is organized as a Rust workspace and contains several components:

- **[crates/](./crates)**: Software implementation in Rust.
  - **[prometeu](./crates/prometeu)**: Unified command-line interface (CLI).
  - **[prometeu-core](./crates/prometeu-core)**: The logical core, VM, and internal OS.
  - **[prometeu-runtime-desktop](crates/prometeu-runtime-desktop)**: Host for execution on Desktop systems.
- **[docs/](./docs)**: Technical documentation and system specifications.
- **[devtools-protocol/](./devtools-protocol)**: Definition of the communication protocol for development tools.
- **[test-cartridges/](./test-cartridges)**: Cartridge examples and test suites.

---

## 🛠️ Requirements

- **Rust**: Version defined in `rust-toolchain.toml`.
- **Installation**: Use [rustup](https://rustup.rs/) to install the required toolchain.

---

## ▶️ Quick Start

To compile the full project:

```bash
cargo build
```

To run an example cartridge:

```bash
./target/debug/prometeu run test-cartridges/color-square
```

For more details on how to use the CLI, see the **[prometeu](./crates/prometeu)** README.

---

## 🚧 Project Status

⚠️ **Early stage (bootstrap)**

Currently, the focus is on stabilizing the core architecture and debugging protocol. Nothing here should be considered a stable API yet.

---

## 📜 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## ✨ Final Note

PROMETEU is both a technical and pedagogical project. The idea is not to hide complexity, but to **expose the right complexity**, at the right level, so it can be understood, studied, and explored.