From 4c3597a2fb6f7f8db5db4ec6b53d8e1b671e185f Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Tue, 29 Sep 2026 13:33:40 +0100 Subject: [PATCH] record external agent acceptance and packaging validation --- README.md | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 79707f09..e0ca6bb4 100644 --- a/README.md +++ b/README.md @@ -63,6 +63,22 @@ 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 | +| --- | --- | +| Connection rejected after Studio restarts | Copy DEV's configuration again: the token and OS-assigned endpoint are session-local. Do not publish the token. | +| 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: @@ -110,8 +126,18 @@ are not considered fixed by the passing integration tests: 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 and real external-client acceptance are remaining -validation boundaries, not confirmed product defects. +Cross-platform desktop coverage remains a validation boundary, not a confirmed +product defect. Desktop acceptance so far covers macOS ARM64 and Codex CLI only. + +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. ## Requirements