redefine README.md

README.md

@@ -1,129 +1,66 @@
-# PROMETEU Runtime
+# PROMETEU
 
-PROMETEU é um **runtime educacional e experimental** inspirado em consoles clássicos,
+PROMETEU é um **ecossistema educacional e experimental** inspirado em consoles clássicos, com foco em **ensinar programação, arquitetura de sistemas e conceitos de hardware através de software**.
-com foco em **ensinar programação, arquitetura de sistemas e conceitos de hardware
-através de software**.
-
-Este repositório contém o **runtime do PROMETEU**, implementado em Rust, responsável por:
-
-- simular um “hardware lógico” simples
-- executar programas (futuros cartuchos) em um loop determinístico
-- abstrair plataformas modernas (desktop, mobile, etc.) de forma consistente
 
 > PROMETEU é uma máquina virtual simples, explícita e didática.
 
 ---
 
-## 🎯 Objetivos do Runtime
+## 🎯 Objetivos do Projeto
 
-- Executar um loop fixo (60 Hz)
+- **Simular um “hardware lógico” simples**: Criar uma barreira de entrada baixa para entender como computadores funcionam.
-- Manter um framebuffer de baixa resolução (estilo console)
+- **Loop Determinístico**: Garantir que o mesmo código produza o mesmo resultado em qualquer plataforma.
-- Fornecer periféricos simples e determinísticos:
+- **Portabilidade Total**: O núcleo não depende de sistema operacional, permitindo rodar de computadores modernos a hardware dedicado.
-  - GFX (framebuffer + double buffer)
+- **Ferramentas de Primeiro Nível**: Oferecer depuração e inspeção profunda como parte central da experiência.
-  - INPUT (D-Pad, botões)
-  - TOUCH (ponteiro absoluto, single-touch)
-- Garantir **portabilidade total** entre plataformas
-- Servir como base para ensino, game jams e experimentação
 
 ---
 
 ## 🧠 Filosofia de Design
 
-- **Sem magia**: tudo é explícito
+- **Sem magia**: tudo é explícito.
-- **Sem heurística implícita**: o runtime não “adivinha intenções”
+- **Sem heurística implícita**: o sistema não “adivinha intenções”.
-- **Determinístico**: mesmo input → mesmo resultado
+- **Determinístico**: mesmo input → mesmo resultado.
-- **Hardware-first**: APIs modelam periféricos, não frameworks modernos
+- **Hardware-first**: APIs modelam periféricos, não frameworks modernos.
-- **Portável por definição**: se não funciona em todas as plataformas, não existe
+- **Portável por definição**: se não funciona em todas as plataformas, não existe.
 
 ---
 
-## 📦 Estrutura do Projeto (Monorepo)
+## 📦 Estrutura do Monorepo
 
-Este repositório usa um **Cargo Workspace** (monorepo):
+Este repositório é organizado como um workspace Rust e contém diversos componentes:
 
-```
+- **[crates/](./crates)**: Implementação do software em Rust.
-runtime/
+  - **[prometeu](./crates/prometeu)**: Interface de linha de comando (CLI) unificada.
-  Cargo.toml              # Workspace root
+  - **[prometeu-core](./crates/prometeu-core)**: O núcleo lógico, VM e SO interno.
-  rust-toolchain.toml     # Versão do Rust (fixa)
+  - **[prometeu-runtime-desktop](./crates/prometeu-runtime-desktop)**: Host para execução em sistemas Desktop.
-  crates/
+- **[docs/](./docs)**: Documentação técnica e especificações do sistema.
-    prometeu/                      # CLI Dispatcher (ponto de entrada unificado)
+- **[devtools-protocol/](./devtools-protocol)**: Definição do protocolo de comunicação para ferramentas de desenvolvimento.
-    prometeu-core/                 # PROMETEU Core (hardware lógico)
+- **[test-cartridges/](./test-cartridges)**: Exemplos e suítes de teste de cartuchos.
-    prometeu-runtime-desktop/         # Host desktop (janela, input real, present)
-    cart-demo/            # Cartucho/demo hardcoded (temporário)
-```
-
-### crates/prometeu
-O binário principal que centraliza o acesso ao ecossistema:
-- `prometeu run <cart>`: Executa um cartucho
-- `prometeu debug <cart>`: Inicia em modo debug
-- `prometeu build/pack`: Comandos planejados para ferramentas de build e empacotamento
-
-### crates/prometeu-core
-Contém o **núcleo do PROMETEU**:
-- loop lógico
-- periféricos
-- framebuffer
-- nenhuma dependência de sistema operacional
-
-### crates/prometeu-runtime-desktop
-Implementação de host para desktop:
-- cria janela
-- traduz teclado/mouse/touch do SO para o core
-- apresenta o framebuffer na tela
-
-### crates/cart-demo
-Código de demonstração hardcoded.
-Será substituído futuramente por:
-- cartuchos
-- bytecode
-- scripts
-
----
-
-## 🖥️ Plataformas
-
-Atualmente:
-- Desktop (primeiro alvo)
-
-Planejado:
-- Mobile
-- Steam Deck
-- Hardware dedicado (experimental, longo prazo)
 
 ---
 
 ## 🛠️ Requisitos
 
-- Rust (via `rustup`)
+- **Rust**: Versão definida em `rust-toolchain.toml`.
-- Toolchain definido em `rust-toolchain.toml`
+- **Instalação**: Use o [rustup](https://rustup.rs/) para instalar a toolchain necessária.
-
-Instalação do Rust:
-
-```bash
-rustup-init
-```
 
 ---
 
-## ▶️ Como rodar
+## ▶️ Início Rápido
 
-Na raiz do repositório:
+Para compilar o projeto completo:
 
 ```bash
 cargo build
-./target/debug/prometeu run <caminho_do_cartucho>
 ```
 
-Ou diretamente via cargo:
+Para rodar um cartucho de exemplo:
 
 ```bash
-cargo run -p prometeu -- run <caminho_do_cartucho>
+./target/debug/prometeu run test-cartridges/color-square
 ```
 
-No início, o host apenas valida:
+Para mais detalhes sobre como usar a CLI, veja o README de **[prometeu](./crates/prometeu)**.
-- loop 60 Hz
-- execução do core
-- estrutura do runtime
 
 ---
 
@@ -131,12 +68,7 @@ No início, o host apenas valida:
 
 ⚠️ **Em estágio inicial (bootstrap)**
 
-O foco atual é:
+Atualmente o foco é na estabilização da arquitetura do core e do protocolo de depuração. Nada aqui deve ser considerado uma API estável ainda.
-- validar arquitetura
-- validar loop e periféricos
-- manter simplicidade máxima
-
-Nada aqui deve ser considerado API estável ainda.
 
 ---
 
@@ -148,9 +80,5 @@ Este projeto está licenciado sob a Licença MIT - veja o arquivo [LICENSE](LICE
 
 ## ✨ Nota Final
 
-PROMETEU é tanto um projeto técnico quanto pedagógico.
+PROMETEU é tanto um projeto técnico quanto pedagógico. A ideia não é esconder complexidade, mas **expor a complexidade certa**, no nível certo, para que ela possa ser entendida, estudada e explorada.
-
-A ideia não é esconder complexidade,
-mas **expor a complexidade certa**, no nível certo,
-para que ela possa ser entendida, estudada e explorada.
 

crates/prometeu-core/README.md

@@ -0,0 +1,14 @@
+# PROMETEU Core
+
+Este crate contém a biblioteca central que define o comportamento do hardware e software do PROMETEU.
+
+## Responsabilidades
+
+- **Hardware Lógico**: Definição de GFX, Input, Audio e Touch.
+- **Máquina Virtual**: Execução de bytecode customizado (PBC - Prometeu Byte Code).
+- **Virtual FS**: Gerenciamento de arquivos e acesso ao "cartucho".
+- **Firmware/OS**: O sistema operacional interno que gerencia o ciclo de vida das aplicações, splash screens e o Hub Home.
+
+## Arquitetura
+
+O core é projetado para ser determinístico e portátil. Ele não faz chamadas diretas ao sistema operacional do host; em vez disso, define traços (traits) que os hosts devem implementar (ex: `FsBackend`).

crates/prometeu-runtime-desktop/README.md

@@ -0,0 +1,18 @@
+# PROMETEU Desktop Runtime
+
+Esta é a implementação de host para plataformas desktop, permitindo que o PROMETEU rode em Windows, Linux e macOS.
+
+## Funcionalidades
+
+- **Renderização**: Utiliza a GPU via biblioteca `pixels` para apresentar o framebuffer de baixa resolução.
+- **Input**: Traduz eventos de teclado e controle (via `winit`) para os sinais de hardware do PROMETEU.
+- **Áudio**: Interface com o sistema de som do host (via `cpal`).
+- **Debugging**: Hospeda um servidor TCP que implementa o **DevTools Protocol**, permitindo conexões de IDEs ou debuggers externos.
+
+## Como rodar
+
+Geralmente executado via CLI principal (`prometeu`), mas pode ser chamado diretamente para testes:
+
+```bash
+cargo run -- --run path/to/cart
+```

crates/prometeu/README.md

@@ -0,0 +1,14 @@
+# PROMETEU CLI (Dispatcher)
+
+O binário `prometeu` atua como o front-end unificado para o ecossistema. Ele não implementa a lógica de execução ou compilação, mas sabe onde encontrar os binários que as implementam.
+
+## Comandos
+
+- `prometeu run <cart>`: Executa um cartucho usando o runtime disponível.
+- `prometeu debug <cart> [--port <p>]`: Inicia a execução em modo de depuração.
+- `prometeu build <projectDir>`: (Planejado) Chama o compilador `prometeuc`.
+- `prometeu pack <cartDir>`: (Planejado) Chama o empacotador `prometeup`.
+
+## Funcionamento
+
+O dispatcher localiza os binários irmãos (`prometeu-runtime`, `prometeuc`, etc.) no mesmo diretório onde ele próprio está instalado. Ele herda `stdin`, `stdout` e `stderr`, e propaga o código de saída do processo chamado.

devtools-protocol/README.md

@@ -6,6 +6,12 @@ Este documento descreve o protocolo de comunicação entre o Runtime do Prometeu
 
 O protocolo é baseado em JSON, enviado via uma conexão de transporte (geralmente TCP). Cada mensagem é um objeto JSON em uma única linha (JSONL).
 
+## Estrutura
+
+- **[protocol.json](./protocol.json)**: Definição formal do protocolo em formato JSON.
+- **[protocol.md](README.md)**: Documentação legível para humanos descrevendo os comandos, eventos e tipos.
+- **[examples/](./examples)**: Exemplos de fluxos de mensagens (handshake, breakpoints, etc.) em formato JSONL.
+
 ## Versionamento
 
 O protocolo possui uma versão explícita definida no campo `protocol_version`.

docs/README.md

@@ -0,0 +1,15 @@
+# PROMETEU Documentation
+
+Este diretório contém a documentação técnica e especificações do projeto PROMETEU.
+
+## Conteúdo
+
+### 📜 [Especificações (Specs)](./specs)
+Documentação detalhada sobre a arquitetura do sistema, formato de cartuchos, conjunto de instruções da VM e muito mais.
+- [Índice de Tópicos](./specs/topics/table-of-contents.md)
+
+### 🐞 [Debugger](./debugger)
+Documentação sobre as ferramentas de depuração e como integrar novas ferramentas ao ecossistema.
+
+### 🔌 [DevTools Protocol](../devtools-protocol)
+Definição do protocolo de comunicação utilizado para depuração e inspeção em tempo real.

test-cartridges/README.md

@@ -0,0 +1,26 @@
+# PROMETEU Test Cartridges
+
+Este diretório contém cartuchos de exemplo e suítes de teste para validar o comportamento do runtime e das ferramentas de desenvolvimento do PROMETEU.
+
+## Cartuchos Disponíveis
+
+### 🟩 [color-square](./color-square)
+Um cartucho simples que demonstra:
+- Inicialização do sistema.
+- Renderização de um quadrado colorido no framebuffer.
+- Loop básico de execução.
+
+## Estrutura de um Cartucho
+
+Um cartucho PROMETEU (em sua forma descompactada) geralmente consiste em:
+- `manifest.json`: Metadados do aplicativo (ID, título, versão, modo).
+- `program.pbc`: O bytecode compilado para a VM do PROMETEU.
+- `assets/`: Recursos como tiles, sprites e amostras de áudio.
+
+## Como usar
+
+Você pode rodar qualquer um destes cartuchos usando a CLI principal:
+
+```bash
+prometeu run test-cartridges/<nome_do_cartucho>
+```