From 3d1e0bc204d407b422b4dea6b024db39a805f22e Mon Sep 17 00:00:00 2001
From: bQUARKz <bquarkz@gmail.com>
Date: Sun, 19 Apr 2026 09:25:00 +0100
Subject: [PATCH] readme

---
 README.md | 101 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 100 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 5af8c4aa..a3b6427a 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,100 @@
-# Prometeu Studio
\ No newline at end of file
+# Prometeu Studio
+
+Prometeu Studio is the desktop development environment for the Prometeu toolchain.
+
+This repository packages the Studio shell together with the embedded services it depends on: project VFS, language tooling, compiler pipeline integration, and asset packing. The current implementation is a Java/JavaFX multi-module Gradle build.
+
+## What Lives Here
+
+The root project is a monorepo with these main areas:
+
+- `prometeu-app`: JavaFX application entry point (`p.studio.App`).
+- `prometeu-studio`: Studio UI, workspaces, project session lifecycle, play/stop flow, and debugger-facing surfaces.
+- `prometeu-vfs`: project document access and save/open contracts.
+- `prometeu-lsp`: language-service integration used by the editor workflow.
+- `prometeu-packer`: embedded packer APIs and implementation used by Studio.
+- `prometeu-compiler`: compiler core, build pipeline, frontend APIs, and the PBS frontend.
+- `prometeu-infra`: shared infrastructure used across modules.
+- `docs/`: normative specifications and architectural references.
+- `discussion/`: workflow artifacts for agendas, decisions, plans, and lessons.
+- `test-projects/`: sample workspaces used for local development and tests.
+
+## Current Product Shape
+
+The Studio shell currently organizes the product around four workspaces:
+
+- Assets
+- Code editor
+- Debug
+- Shipper
+
+At runtime, the app boots an embedded packer, creates a project document VFS, wires LSP services, and opens the Studio launcher window. Project creation currently scaffolds a Prometeu workspace with `prometeu.json`, `src/`, `assets/`, `build/`, `cartridge/`, `.workspace/`, and local Studio metadata.
+
+## Requirements
+
+- JDK 21 or newer recommended for local development
+- Gradle wrapper (`./gradlew`) included in the repository
+- A desktop environment capable of running JavaFX
+
+## Common Commands
+
+Run the full project graph listing:
+
+```bash
+./gradlew projects
+```
+
+Run the desktop application:
+
+```bash
+./gradlew :prometeu-app:run
+```
+
+Run the test suite:
+
+```bash
+./gradlew test
+```
+
+Generate the aggregated coverage report:
+
+```bash
+./gradlew jacocoTestReport
+```
+
+## Repository Reading Guide
+
+If you are new to the codebase, this order is usually the fastest path:
+
+1. Start at `prometeu-app` to see application bootstrap.
+2. Read `prometeu-studio` for the shell, workspaces, and user-facing flows.
+3. Read `prometeu-vfs`, `prometeu-lsp`, and `prometeu-packer` for service boundaries.
+4. Read `prometeu-compiler` when you need compiler or PBS language behavior.
+
+## Specs And Architecture
+
+Important reference surfaces:
+
+- `docs/specs/compiler/`: shared compiler specifications
+- `docs/specs/packer/`: packer specifications
+- `docs/vm-arch/`: VM and ISA architecture references
+
+These documents are the long-term normative source for behavior and contracts. When code and docs diverge, fix the divergence explicitly instead of relying on tribal knowledge.
+
+## Discussion Workflow
+
+This repository uses a disciplined discussion workflow under `discussion/`:
+
+- `discussion/workflow/agendas/`
+- `discussion/workflow/decisions/`
+- `discussion/workflow/plans/`
+- `discussion/lessons/`
+- `discussion/index.ndjson`
+
+The expected execution flow is:
+
+```text
+agenda -> decision -> plan -> implement -> lesson
+```
+
+Do not create new workflow artifacts in legacy `docs/**/agendas`, `docs/**/decisions`, `docs/**/pull-requests`, or `docs/**/learn` paths.