# 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.