docs(studio): keep README focused on project onboarding
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/Prometeu/Studio/pipeline/head There was a failure building this commit

This commit is contained in:
2026-11-19 17:58:22 +00:00
parent 71fb80efc3
commit 23522f7589
3 changed files with 284 additions and 308 deletions
+70 -307
View File
@@ -1,337 +1,100 @@
# 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: compiler pipeline integration, asset packing, runtime/debug orchestration, and project-local Studio state. 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`: Spring Boot non-web composition, concrete adapters, packaging, and JavaFX entry point (`p.studio.app.StudioLauncher`).
- `prometeu-studio-api`: toolkit-neutral Studio contracts and operation surfaces.
- `prometeu-studio-core`: JavaFX-free project, session, assets, shipper, runtime, and execution services.
- `prometeu-studio-ui-javafx-2`: the default human-facing frontend and presentation foundation.
- `prometeu-studio-ui-javafx`: retained previous adapter and compatibility qualification surfaces.
- `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/lessons/`: published engineering lessons and supporting assets.
- `test-projects/`: sample workspaces used for local development and tests.
Engineering discussions, decisions, plans and execution evidence are maintained in
the enclosing [Prometeu Engineering workspace](../README.md) using
[AI Engineering](../.ai-engineering/README.md).
## Current Product Shape
The normal and installed application opens the new project chooser. Open an existing
project, choose a qualified runtime installation, then use Play, Pause, Resume and
Stop. Close the project before opening another. A save-capable game requires an
existing development save image or an explicitly disposable session.
Play prepares compiler/assets into the cartridge directory and starts an owned
native runtime process whose frames appear inside Studio. Zoom is x1/x2/x4 in
logical pixels with scrolling. Minimizing or switching applications pauses;
returning requires manual Resume. Closing stops the game, subject to save protection.
Play does not create a PMC or a distributable build.
This first frontend slice does not mount editors, Assets/DEV/Shipper workspaces,
AI prompts/configuration or breakpoint debugging. Their existing service contracts,
headless runtime and MCP adapters remain separately tested. The previous DEV guide
below describes retained adapter behavior, not controls available in the new UI.
See the [integrated Play contract](docs/specs/studio/14.%20Integrated%20Play%20Specification.md).
## External Coding Agents (MCP)
The following authorization workflow belongs to the previous DEV adapter. The new
Play UI does not yet expose a grant/configuration surface. This omission does not
change the deterministic headless protocol, task authority, MCP tool schemas or
installed stdio connector; their process and adapter qualification gates remain.
Studio includes its own `mcp --project <absolute-root>` mode. Configure the native
client once; project grants and desktop restarts no longer require copying ports
or tokens. The initial integration targets Codex on macOS.
1. Install/stage Studio with its bundled Java runtime (see below). New projects
prepare the local client entry during scaffolding. Opening an existing project
also prepares its enabled integration automatically; Studio starts the shared
MCP server itself. **DEV → Prepare assistant** retries preparation after resolving
a reported setup conflict. Opening a project does not grant agent control.
2. Open the coding client in the project directory. Trust the project and reload
MCP once if the client requests it. Studio does not alter client approval policy.
Tools can initialize/list even before the desktop is open or access is granted.
3. Open the project in Studio and grant control in DEV (save first if prompted).
Active Debug prevents granting. The connector discovers access automatically.
4. The agent acquires a task, consults project/language/SDK references, edits saved
project files with its native tools and validates through LSP/build. SDK and
external libraries remain read-only.
5. Recover uncertain operations by operationId/clientRequestId lookup within the
same task; never replay build/advance blindly. Explicitly release control when
done. Human reclaim also revokes access; stop direct external file edits separately.
The client invokes the same Studio artifact over stdio. It forwards to Studio's
project-scoped loopback service using protected, transient
`.studio/mcp/connection.json`. The permanent `.codex/config.toml` entry contains
installed Java/classpath/root arguments, not credentials. Both local outputs are
ignored by Git. Unrelated client settings are preserved; tracked or conflicting
Studio entries require deliberate resolution. `.studio/setup.json` preserves
neutral integration intent and existing runtime/editor settings.
After desktop restart, grant again in DEV. Keep the same client session and
configuration; old task identities and operation receipts are not restored.
DEV displays connection separately from project authority. No project-local
launcher, Python transport script or embedded chat is required.
### Reading external source code
VS Code F12 opens SDK/core and admitted libraries as read-only documents, with
hover, continued F12 and syntax highlighting. SDK/core stay bundled; no editorial
copies are created. After a source revision changes or a session ends, navigate
again instead of reusing old positions.
For MCP, use `studio_language_query` with `operation: "definition"`, then pass a
returned `prometeu-source:` URI to `operation: "readExternalSource"`. The response
contains `descriptor` and `text`; hover and definition accept the same URI within
the owning task. Another task cannot reuse it. MCP does not require VS Code open.
External or mixed edit proposals are refused in full. Library installation/cache
management is outside this feature. See the [extension guide](tools/vscode-extension/README.md).
### Installation and IntelliJ development
Build and stage the complete distribution, including its Java runtime:
```bash
./gradlew :prometeu-app:stageStudioInstallation
```
The macOS default is `~/Library/Application Support/Prometeu/Studio/current`.
Staging validates a new version before atomically changing `current`, retaining
older versions for rollback and running processes. Native client registration
uses absolute paths and argument arrays, independent of shell PATH:
```text
command: <installation>/current/runtime/bin/java
args: ["-cp", "<installation>/current/lib/*", "p.studio.app.StudioLauncher", "mcp", "--project", "<absolute-project-root>"]
```
For development, use an isolated installation:
```bash
./gradlew :prometeu-app:stageStudioInstallation -PstudioInstallationRoot=/absolute/dev-installation
```
In IntelliJ, run/debug `p.studio.app.StudioLauncher` with the `prometeu-app`
runtime classpath and VM option `-Dstudio.installationRoot=/absolute/dev-installation`.
The desktop and client-owned connector are separate JVMs. To debug the latter,
add the development-only VM argument
`-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=127.0.0.1:5005`
before `-cp` in the local MCP entry, restart that MCP process, then use IntelliJ's
**Remote JVM Debug** on localhost:5005. Do not commit this local configuration.
Because manual edits to the managed entry are protected, restore its original
content before using preparation again. Regular registration never enables JDWP.
The packaged automated gate checks bundled Java, upgrade/rollback, project paths
with spaces, minimal environment, scaffold/preparation and JavaFX startup:
```bash
./gradlew :prometeu-app:installedConnectorTest
```
The current production tools cover context, references, task control, LSP,
build/pack, operation lookup/cancellation and headless execution (17 tools).
Headless requires a runtime installation configured for the project; missing or
incompatible installations fail explicitly. DEV is an
observation panel, not manual Play/input for the agent's session; **Debug** retains
the human testing workflow. Edits are preserved on cancellation; Git/review/recovery
remain the developer's responsibility.
See the [MCP contract](docs/specs/studio/11.%20MCP%20Tools%20and%20Project%20Knowledge%20Contract.md)
for schemas, authorization, limits and delivery boundaries.
### Troubleshooting automation
| Symptom | Action |
| --- | --- |
| Waiting for access / desktop restarted | Open the project and grant again in DEV. Keep the existing client configuration. |
| Stale connection / incompatible catalog | Grant fresh access, or update the installed Studio when versions differ. Do not edit transient credentials. |
| Preparation conflict | Preserve the existing client settings; resolve a tracked/user-owned/edited Studio table explicitly, then prepare again. |
| Acquisition rejected or project busy | Grant control in DEV first; stop manual Debug before granting. Query an existing operation instead of starting another; serialize headless calls. |
| `RUNTIME_UNAVAILABLE` or handshake incompatibility | Check the project's configured runtime installation and its packaged headless command. Studio does not download a substitute. |
| `NO_FRAME_AVAILABLE` | Advance at least one frame before requesting a capture. |
| Advance/page limit rejected | Respect advertised limits and use reference pagination. Runtime's default maximum is 600 frames per advance; requests are not silently clamped. |
| Unknown language or missing reference | Inspect project context and the declared manifest language; use only advertised capabilities/reference IDs. PBS is a creation default, not an unknown-language fallback. |
| Returning control reports cleanup failure | Stop the external client's direct editing separately, then retry DEV reclaim after owned-process cleanup. Do not bypass the lock or restore stale editor buffers. |
Language and SDK references are bundled locally; reading them does not require a
compiler checkout or network download. SDK/external-library changes remain outside
the game-authoring task, even when a reference exposes a limitation.
The real headless process adapter and task-service composition can be verified
using an extracted runtime distribution:
```bash
./gradlew :prometeu-app:headlessProcessTest -PstudioRuntimeInstall=/absolute/path/to/runtime
```
This gate builds an installed PBS example, launches the actual runtime, checks
canonical PNGs and explicit reset/reboot, cancels an advance and verifies process
cleanup. It also runs the actual app composition through saved-file LSP queries,
rebuilds and corrective loops after compile errors and guest faults. It does not
download a runtime or substitute a protocol fixture.
To verify the complete HTTP-to-runtime-to-DEV image path, run this separate gate
in a desktop environment:
```bash
./gradlew :prometeu-app:headlessMcpDesktopTest -PstudioRuntimeInstall=/absolute/path/to/runtime --max-workers=2
```
It opens the real DEV view, grants control, uses an HTTP MCP client to query LSP,
edit/build the installed PBS example and execute a fixed input timeline. PNG bytes,
frame identities, state and fault are compared with a separate direct-JSONL runtime
process; every decoded ImageView pixel and its visible identity/stale label are
checked. Reset, fresh-session repetition and rebuild are included. This automated
client is not the external coding-agent acceptance gate.
The same suite also exercises cancellation, disconnect/reconnect, revocation,
project/app closure, crash and forced shutdown, corrective builds, and return to
the real manual Debug host. These scenarios require a POSIX desktop (validated
on macOS ARM64) and free port 7777. Only processes created by the test are killed
or suspended. After a forced-shutdown error, an explicit second reclaim can
acknowledge completed cleanup; control stays locked until cleanup is confirmed.
### Follow-ups after the AI-first implementation
The following findings are recorded for investigation after implementation; they
are not considered fixed by the passing integration tests:
- **PBS/LSP SDK navigation:** the historical probe of the former `Input.pad()`
API returned no location; the current input API is `Pad`/`Button` and `Touch`. Project-source navigation and indexed SDK reference
reads work. Investigate SDK symbol resolution separately; an empty definition
result is not evidence of missing runtime support or permission to edit the SDK.
- **Build tooling:** the validation environment's JDK 25 triggers Kotlin's target-24
fallback and Java/Kotlin target compatibility warnings in `buildSrc`. The targeted
regression passes, but the toolchain/target alignment needs separate review.
Cross-platform desktop coverage remains a validation boundary, not a confirmed
product defect. Baseline HTTP desktop acceptance covers macOS ARM64 and Codex CLI only. The integrated stdio flow completed its separate acceptance gates through automated validation and user-confirmed native-client, graphical-launch and IntelliJ checks; see [LSN-0077](discussion/lessons/DSC-0070-studio-persistent-mcp-connector/LSN-0077-integrated-mcp-stable-setup-and-ephemeral-access.md) for evidence provenance.
The first real Codex CLI acceptance run exercised editing, LSP, build/pack, input,
1,110 frames, native MCP images and explicit release. The developer confirmed the
DEV result and successfully ran the edited game using manual Debug Play afterward.
Additional follow-ups from that run: clearer errors for oversized
reference pages, guidance for sequential headless queries after `BUSY`, and easier
discovery of framebuffer dimensions. Capture before the first completed frame
correctly returns `NO_FRAME_AVAILABLE`; it is not a runtime defect. Noninteractive
clients must also provide an approval path for MCP work calls; the acceptance used
Codex's approval review with a project-scoped workspace-write sandbox.
The completed baseline's architecture, acceptance evidence and post-implementation
follow-ups are consolidated in [LSN-0076](discussion/lessons/DSC-0068-studio-headless-runtime-ai-first/LSN-0076-ai-first-studio-through-shared-authority-and-headless-evidence.md).
It combines a JavaFX application with compiler integration, asset packing, project
services and runtime orchestration in a multi-module Java/Gradle build.
## Requirements
- JDK 25 for local compilation/tests and the bundled product runtime (Gradle 9.3.1)
- Gradle wrapper (`./gradlew`) included in the repository
- JDK 25 for compilation, tests and the bundled application runtime
- The included Gradle wrapper (Gradle 9.3.1)
- A desktop environment capable of running JavaFX
- A qualified native Prometeu runtime installation for running games
## Common Commands
## Getting Started
Run the full project graph listing:
```bash
./gradlew projects
```
Run the desktop application:
Run these commands from the Studio repository root:
```bash
./gradlew :prometeu-app:run
```
The new UI is the default. `:prometeu-studio-ui-javafx-2:run` and `:gallery` remain
separate foundation demonstrations, without a backend or a project.
Open an existing project from the project chooser and select a qualified runtime
installation. Use Play, Pause, Resume and Stop to run the game inside Studio.
Games with saves require an existing development save image or an explicitly
disposable session. Close the project before opening another.
Opt-in integrated Play qualification (desktop/installed native runtime required):
The default frontend is `prometeu-studio-ui-javafx-2`. It provides project opening
and integrated Play; editors, Assets/DEV/Shipper workspaces and MCP grant controls
are outside its current UI. Play prepares a cartridge directory for execution;
distribution/export is a separate concern.
```sh
./gradlew :prometeu-app:studioPlayProcessTest -PstudioRuntimeInstall=/absolute/runtime-install
./gradlew :prometeu-app:studioPlayDesktopTest -PstudioRuntimeInstall=/absolute/runtime-install
```
See the [development guide](docs/development.md) for installation, runtime
qualification, IntelliJ setup, MCP integration and integration test commands.
The [integrated Play specification](docs/specs/studio/14.%20Integrated%20Play%20Specification.md)
defines execution, input and save behavior.
Add `-PstudioPlayStress=true` for the 30-second presentation/FX-delay/20-cycle gate.
The headless visual evidence pilot uses a disposable copy of `test-projects/pong`.
Integration fixtures belong to this repository; no external port checkout is
required. A runtime's three executable identities must match a distributed
capacity profile; rebuilding a native binary does not automatically requalify it.
Build the native umbrella distribution with `../runtime/scripts/local-dist.sh`.
It packages `prometeu`, `prometeu-runtime` (desktop/Studio Play) and
`prometeu-headless` (deterministic automation). Select the extracted
`../runtime/dist-staging/stable/prometeu-cli-<target>` directory in Studio.
An unchanged dispatcher can belong to several releases: Studio selects a profile
only when all three executable hashes match the same qualified bundle.
After changing a native binary, qualify the actual installation before building
or launching Studio with its updated catalog:
```sh
make -C ../tooling venv
../tooling/.venv/bin/python ../tooling/scripts/qualify.py \
--studio . \
--runtime ../runtime/dist-staging/stable/prometeu-cli-aarch64-apple-darwin
```
This command executes the native glyph/scene 16/17 boundary test afresh, verifies
the evidence and executable identities, then publishes an exact capacity profile
under `prometeu-app/src/main/resources/asset-capacity`. Review/include those
resources when distributing Studio. It neither builds a replacement runtime nor
relaxes the execution guard. A failed qualification publishes no catalog entry.
The native build stays independent of the JVM; qualification is an explicit
consumer verification step, separate from pressing Play.
Run the test suite:
## Build and Test
```bash
./gradlew build
./gradlew test
```
`test` runs unit tests and excludes JUnit `@Tag("integration")`. Integration
includes process/network/desktop qualification and real application or provider
composition, including fixture subprocesses. Existing integration suites remain
in this repository; `../tooling` prepares their environment and orchestrates
selected integration commands and builds. They are currently excluded from the
runtime and Studio pipelines; the opt-in commands above are separate checks.
Consolidated JaCoCo uses only the unit `test.exec` files.
Generate the aggregated coverage report:
```bash
./gradlew jacocoTestReport
```
## Repository Reading Guide
`test` runs unit tests and excludes JUnit `@Tag("integration")`. The aggregated
JaCoCo report uses unit test results. Process, network and desktop checks have
[separate opt-in commands](docs/development.md#integration-checks).
If you are new to the codebase, this order is usually the fastest path:
Stage a complete installation with its bundled Java runtime:
1. Start at `prometeu-app` to see application bootstrap.
2. Read `prometeu-studio-api` and `prometeu-studio-core` for Studio contracts and application services.
3. Read `prometeu-studio-ui-javafx` for the current shell, workspaces, and human-facing flows.
4. Read `prometeu-app` for Spring composition and provider gateways.
5. Read `prometeu-packer` for asset and packaging boundaries.
6. Read `prometeu-compiler` when you need compiler or PBS language behavior.
```bash
./gradlew :prometeu-app:stageStudioInstallation
```
## Specs And Architecture
The default installation root is
`~/Library/Application Support/Prometeu/Studio`; `current` selects its active
version. See [installation and development](docs/development.md#installation-and-intellij-development)
for an isolated development installation.
Important reference surfaces:
## Repository Structure
| Area | Responsibility |
| --- | --- |
| `prometeu-app` | Spring Boot composition, concrete adapters, packaging and the `p.studio.app.StudioLauncher` entry point |
| `prometeu-studio-api` | Toolkit-neutral Studio contracts and operations |
| `prometeu-studio-core` | JavaFX-free project, session, asset, shipper and execution services |
| `prometeu-studio-ui-javafx-2` | Default frontend and presentation foundation |
| `prometeu-studio-ui-javafx` | Previous frontend retained for adapter compatibility checks |
| `prometeu-compiler` | Compiler core, build pipeline, frontend APIs and PBS frontend |
| `prometeu-packer` | Asset packing APIs and implementation |
| `prometeu-infra` | Shared infrastructure |
| `test-projects` | Sample projects and integration fixtures |
| `docs` | Technical guides, specifications and architecture references |
| `discussion/lessons` | Published engineering lessons and their assets |
Run `./gradlew projects` to list the complete module graph.
Start with `prometeu-app` for application bootstrap, then read
`prometeu-studio-api` and `prometeu-studio-core` for contracts and services.
The [JavaFX 2 module guide](prometeu-studio-ui-javafx-2/README.md) covers the current
frontend. Follow the compiler and packer modules for their respective pipelines.
<a id="external-coding-agents-mcp"></a>
## Documentation
- [Development guide](docs/development.md): installation, MCP, troubleshooting and integration checks
- [Specification guide](docs/specs/README.md): domain ownership and reading order
- [General compiler](docs/specs/compiler/README.md): shared compiler specifications
- [PBS](docs/specs/compiler-languages/pbs/README.md): language and SDK specifications
- [Studio](docs/specs/studio/README.md): shell, workspaces and integration contracts
- [Packer](docs/specs/packer/README.md): packer specifications
- `docs/vm-arch/`: VM and ISA architecture references
- [Studio](docs/specs/studio/README.md): application, services and integration contracts
- [Compiler](docs/specs/compiler/README.md): shared compiler contracts
- [PBS](docs/specs/compiler-languages/pbs/README.md): language and SDK
- [Packer](docs/specs/packer/README.md): asset and packaging contracts
- [VM architecture](docs/vm-arch/README.md): VM/ISA references and provenance
- [VS Code extension](tools/vscode-extension/README.md): language tooling and external source navigation
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.
Engineering discussions, decisions, plans, build/acceptance results and pending
investigations belong to the enclosing
[Prometeu Engineering workspace](../README.md) in
[AI Engineering](../.ai-engineering/README.md). See [AGENTS.md](AGENTS.md) before
contributing.
+213
View File
@@ -0,0 +1,213 @@
# Studio Development Guide
Run commands from the Studio repository root unless stated otherwise.
This guide covers installation, native runtime qualification, external tooling
and opt-in integration checks. See the [project README](../README.md) for the
application overview and basic build commands.
## Native Runtime Installation and Qualification
Build the native umbrella distribution with `../runtime/scripts/local-dist.sh`.
It packages `prometeu`, `prometeu-runtime` (desktop/Studio Play) and
`prometeu-headless` (deterministic automation). Select the extracted
`../runtime/dist-staging/stable/prometeu-cli-<target>` directory in Studio.
An unchanged dispatcher can belong to several releases: Studio selects a profile
only when all three executable hashes match the same qualified bundle.
After changing a native binary, qualify the actual installation before building
or launching Studio with its updated catalog:
```sh
make -C ../tooling venv
../tooling/.venv/bin/python ../tooling/scripts/qualify.py \
--studio . \
--runtime ../runtime/dist-staging/stable/prometeu-cli-aarch64-apple-darwin
```
This command executes the native glyph/scene 16/17 boundary test afresh, verifies
the evidence and executable identities, then publishes an exact capacity profile
under `prometeu-app/src/main/resources/asset-capacity`. Review/include those
resources when distributing Studio. It neither builds a replacement runtime nor
relaxes the execution guard. A failed qualification publishes no catalog entry.
The native build stays independent of the JVM; qualification is an explicit
consumer verification step, separate from pressing Play.
## Installation and IntelliJ Development
Build and stage the complete distribution, including its Java runtime:
```bash
./gradlew :prometeu-app:stageStudioInstallation
```
The macOS default is `~/Library/Application Support/Prometeu/Studio/current`.
Staging validates a new version before atomically changing `current`, retaining
older versions for rollback and running processes. Native client registration
uses absolute paths and argument arrays, independent of shell PATH:
```text
command: <installation>/current/runtime/bin/java
args: ["-cp", "<installation>/current/lib/*", "p.studio.app.StudioLauncher", "mcp", "--project", "<absolute-project-root>"]
```
For development, use an isolated installation:
```bash
./gradlew :prometeu-app:stageStudioInstallation -PstudioInstallationRoot=/absolute/dev-installation
```
In IntelliJ, run/debug `p.studio.app.StudioLauncher` with the `prometeu-app`
runtime classpath and VM option `-Dstudio.installationRoot=/absolute/dev-installation`.
The desktop and client-owned connector are separate JVMs. To debug the latter,
add the development-only VM argument
`-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=127.0.0.1:5005`
before `-cp` in the local MCP entry, restart that MCP process, then use IntelliJ's
**Remote JVM Debug** on localhost:5005. Do not commit this local configuration.
Because manual edits to the managed entry are protected, restore its original
content before using preparation again. Regular registration never enables JDWP.
## External Coding Agents (MCP)
The following authorization workflow belongs to the previous DEV adapter. The new
Play UI does not yet expose a grant/configuration surface. Headless protocol,
task authority, MCP tool schemas and the installed stdio connector retain their
existing entry points.
Studio includes its own `mcp --project <absolute-root>` mode. Configure the native
client once; project grants and desktop restarts no longer require copying ports
or tokens. The initial integration targets Codex on macOS.
1. Install/stage Studio with its bundled Java runtime (see installation above).
New projects prepare the local client entry during scaffolding. Opening an existing project
also prepares its enabled integration automatically; Studio starts the shared
MCP server itself. **DEV → Prepare assistant** retries preparation after resolving
a reported setup conflict. Opening a project does not grant agent control.
2. Open the coding client in the project directory. Trust the project and reload
MCP once if the client requests it. Studio does not alter client approval policy.
Tools can initialize/list even before the desktop is open or access is granted.
3. Open the project in Studio and grant control in DEV (save first if prompted).
Active Debug prevents granting. The connector discovers access automatically.
4. The agent acquires a task, consults project/language/SDK references, edits saved
project files with its native tools and validates through LSP/build. SDK and
external libraries remain read-only.
5. Recover uncertain operations by operationId/clientRequestId lookup within the
same task; never replay build/advance blindly. Explicitly release control when
done. Human reclaim also revokes access; stop direct external file edits separately.
The client invokes the same Studio artifact over stdio. It forwards to Studio's
project-scoped loopback service using protected, transient
`.studio/mcp/connection.json`. The permanent `.codex/config.toml` entry contains
installed Java/classpath/root arguments, not credentials. Both local outputs are
ignored by Git. Unrelated client settings are preserved; tracked or conflicting
Studio entries require deliberate resolution. `.studio/setup.json` preserves
neutral integration intent and existing runtime/editor settings.
After desktop restart, grant again in DEV. Keep the same client session and
configuration; old task identities and operation receipts are not restored.
DEV displays connection separately from project authority. No project-local
launcher, Python transport script or embedded chat is required.
### Reading external source code
VS Code F12 opens SDK/core and admitted libraries as read-only documents, with
hover, continued F12 and syntax highlighting. SDK/core stay bundled; no editorial
copies are created. After a source revision changes or a session ends, navigate
again instead of reusing old positions.
For MCP, use `studio_language_query` with `operation: "definition"`, then pass a
returned `prometeu-source:` URI to `operation: "readExternalSource"`. The response
contains `descriptor` and `text`; hover and definition accept the same URI within
the owning task. Another task cannot reuse it. MCP does not require VS Code open.
External or mixed edit proposals are refused in full. Library installation/cache
management is outside this feature. See the [extension guide](../tools/vscode-extension/README.md).
The production tools cover context, references, task control, LSP,
build/pack, operation lookup/cancellation and headless execution.
Headless requires a runtime installation configured for the project; missing or
incompatible installations fail explicitly. DEV is an
observation panel, not manual Play/input for the agent's session; **Debug** retains
the human testing workflow. Edits are preserved on cancellation; Git/review/recovery
remain the developer's responsibility.
See the [MCP contract](specs/studio/11.%20MCP%20Tools%20and%20Project%20Knowledge%20Contract.md)
for schemas, authorization, limits and delivery boundaries.
### Troubleshooting automation
| Symptom | Action |
| --- | --- |
| Waiting for access / desktop restarted | Open the project and grant again in DEV. Keep the existing client configuration. |
| Stale connection / incompatible catalog | Grant fresh access, or update the installed Studio when versions differ. Do not edit transient credentials. |
| Preparation conflict | Preserve the existing client settings; resolve a tracked/user-owned/edited Studio table explicitly, then prepare again. |
| Acquisition rejected or project busy | Grant control in DEV first; stop manual Debug before granting. Query an existing operation instead of starting another; serialize headless calls. |
| `RUNTIME_UNAVAILABLE` or handshake incompatibility | Check the project's configured runtime installation and its packaged headless command. Studio does not download a substitute. |
| `NO_FRAME_AVAILABLE` | Advance at least one frame before requesting a capture. |
| Advance/page limit rejected | Respect advertised limits and use reference pagination. Runtime's default maximum is 600 frames per advance; requests are not silently clamped. |
| Unknown language or missing reference | Inspect project context and the declared manifest language; use only advertised capabilities/reference IDs. PBS is a creation default, not an unknown-language fallback. |
| Returning control reports cleanup failure | Stop the external client's direct editing separately, then retry DEV reclaim after owned-process cleanup. Do not bypass the lock or restore stale editor buffers. |
Language and SDK references are bundled locally; reading them does not require a
compiler checkout or network download. SDK/external-library changes remain outside
the game-authoring task, even when a reference exposes a limitation.
## Integration Checks
Unit tests run through `./gradlew test`. Process, network, desktop and actual
application/provider composition checks use separate integration tasks, including
fixture subprocesses. These suites remain in Studio; `../tooling` prepares their
environment and orchestrates selected commands.
Integration checks are excluded from the runtime and Studio pipelines.
### Installed Studio Connector
```bash
./gradlew :prometeu-app:installedConnectorTest
```
Checks bundled Java, upgrade/rollback, project paths with spaces, minimal
environment, scaffolding/preparation and JavaFX startup.
### Integrated Play
Requires a desktop environment and an installed native runtime:
```bash
./gradlew :prometeu-app:studioPlayProcessTest -PstudioRuntimeInstall=/absolute/runtime-install
./gradlew :prometeu-app:studioPlayDesktopTest -PstudioRuntimeInstall=/absolute/runtime-install
```
Add `-PstudioPlayStress=true` for the 30-second presentation/FX-delay/20-cycle
check. Fixtures use a disposable copy of `test-projects/pong`. No external port
checkout is required. Changed native executables require renewed qualification
as described above.
### Headless Runtime and Application Composition
Use an extracted runtime distribution:
```bash
./gradlew :prometeu-app:headlessProcessTest -PstudioRuntimeInstall=/absolute/path/to/runtime
```
Exercises the real runtime, installed PBS examples, canonical PNGs, reset/reboot,
cancellation and process cleanup, plus saved-file LSP/build corrective loops.
The task requires the supplied runtime installation.
### MCP and DEV Desktop Integration
This check exercises the retained DEV adapter. It requires a POSIX desktop and
free port 7777:
```bash
./gradlew :prometeu-app:headlessMcpDesktopTest -PstudioRuntimeInstall=/absolute/path/to/runtime --max-workers=2
```
The HTTP client drives LSP, build and a fixed input timeline; output and visible
DEV pixels are compared with a separate direct-JSONL runtime process. Scenarios
include reset, cancellation, disconnect/reconnect, revocation, project/app closure,
crash, forced shutdown and return to manual Debug. Only test-owned processes are
terminated or suspended. After a forced-shutdown error, a second explicit reclaim
can acknowledge completed cleanup; control stays locked until cleanup is confirmed.
These commands describe available checks. Record actual runs, environment,
results, acceptance evidence and pending investigations in the owning AIE Work.
@@ -140,7 +140,7 @@ umbrella distribution produced by `runtime/scripts/local-dist.sh`, including rea
Pong Play and the deterministic headless process. Capacity qualification identifies
the dispatcher and both native backends as one exact bundle; multiple releases may
share an unchanged dispatcher. The explicit qualification command is documented in
the [Studio README](../../../README.md).
the [development guide](../../development.md#native-runtime-installation-and-qualification).
Earlier presentation performance measurements used debug native binaries.
Windows/Linux, release performance, physical HiDPI pixel alignment, and human