diff --git a/CHANGELOG.md b/CHANGELOG.md
index b774b8d..c89b47f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,33 @@ All notable repository and VS Code/Cursor extension changes are documented in th
The Unity UPM package has its own changelog at `Packages/com.rankupgames.unity-cursor-toolkit/CHANGELOG.md`.
+## Unreleased
+
+### Documentation
+
+- Replaced retired dynamic Marketplace badges with a stable install badge that
+ links to the existing Marketplace item.
+- Added one documentation index, a canonical Unity 7 readiness plan, and
+ evidence-gated WS1 through WS8 implementation plans.
+- Clarified the difference between declared, validated, shipped, planned, and
+ historical compatibility statements across all public README surfaces.
+
+## [0.6.7081326] - 2026-08-13
+
+Release CI assigned `0.6.7081326` to the published distribution artifacts. The
+source `package.json` keeps its base development version between releases.
+
+### Added
+
+- The Unity toolbar copy action now captures the main-camera application view,
+ overwrites one stable PNG in `Application.temporaryCachePath`, and appends
+ the absolute path to the copied console and profiler context.
+
+### Security
+
+- Updated the locked `js-yaml` transitive dependency to `4.3.1` to resolve the
+ remaining high-severity development dependency advisory.
+
## [0.6.1052826] - 2026-05-28
### Added
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 93700a7..6bdc3d8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -40,9 +40,23 @@ The first `cd unity-cursor-toolkit` enters the repository root. The second enter
Changes to `unity-assets/` C# files must:
-- Compile in Unity 2019+
+- Preserve the package's declared Unity 2019.4 baseline
- Wrap editor-only code in `#if UNITY_EDITOR` / `#endif`
+The declared baseline is not a tested compatibility claim. Record the exact
+Unity Editor version and platform for each proof run. For CoreCLR or Unity 7
+work, update `docs/UNITY_7_READINESS.md`, the affected file under `docs/tasks/`,
+and public compatibility wording together.
+
+## Documentation Status
+
+- Use the status terms in `docs/README.md`.
+- Keep both package documentation mirrors byte-identical.
+- Do not advertise Unity 7 or CoreCLR support until the readiness gates have
+ exact-version evidence.
+- Keep research and experiment results dated. Recheck external product facts
+ before using them for implementation or marketing.
+
## Code Style
- TypeScript strict mode
diff --git a/CursorUnityTool/Packages/com.rankupgames.unity-cursor-toolkit/CHANGELOG.md b/CursorUnityTool/Packages/com.rankupgames.unity-cursor-toolkit/CHANGELOG.md
index 1329451..57b631a 100644
--- a/CursorUnityTool/Packages/com.rankupgames.unity-cursor-toolkit/CHANGELOG.md
+++ b/CursorUnityTool/Packages/com.rankupgames.unity-cursor-toolkit/CHANGELOG.md
@@ -14,6 +14,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Added the `editor_validation` MCP tool and menu command for project-file regeneration plus script compile requests.
- Added the audited Unity-Unterm fork as a toolkit-internal terminal, Claude Code, code editor, completion, and debugger feature for Unity 6000.3 on macOS and Windows.
- Added Unity-Unterm launch aliases under `Tools > Unity Cursor Toolkit > Unterm`.
+- Added a native toolbar copy action that captures the current main-camera
+ application view, overwrites one stable temporary PNG on every click, and
+ appends its absolute path to the copied console and profiler context.
+
+### Documentation
+
+- Added the canonical Unity 7 readiness plan and evidence-gated WS1 through
+ WS8 workstreams.
+- Clarified that Unity 2019.4 and Unity 6000.3 are declared baselines, while
+ CoreCLR transition and Unity 7 support need exact-version proof.
### Security
diff --git a/CursorUnityTool/Packages/com.rankupgames.unity-cursor-toolkit/Documentation~/README.md b/CursorUnityTool/Packages/com.rankupgames.unity-cursor-toolkit/Documentation~/README.md
index 728e354..f30394c 100644
--- a/CursorUnityTool/Packages/com.rankupgames.unity-cursor-toolkit/Documentation~/README.md
+++ b/CursorUnityTool/Packages/com.rankupgames.unity-cursor-toolkit/Documentation~/README.md
@@ -6,6 +6,7 @@ Editor tools for Cursor/VS Code and MCP-capable AI agents integrating with Unity
- **Hot Reload**: TCP server that triggers asset refresh when code changes are detected
- **Console Forwarding**: Streams Unity console output to Cursor/VS Code
+- **Copy Snapshot**: Copies profiler/console context and overwrites one stable temporary main-camera screenshot on each click
- **MCP Bridge**: Model Context Protocol tool dispatch for AI-assisted Unity editing
- **Editor Validation**: Regenerates Unity project files and requests script compilation from Cursor/VS Code
- **Runtime Game Commands**: Project-owned coroutine workflows callable through MCP without UI automation
@@ -50,9 +51,27 @@ Add to your `Packages/manifest.json`:
## Requirements
- Unity 2019.4 or later for the core toolkit
-- Unity 6000.3 or later on macOS or Windows for the bundled Unity-Unterm features
+- Declared Unity 6000.3 or later requirement on macOS or Windows for the
+ bundled Unity-Unterm features; the local sample proof is Unity 6000.3.9f1 on
+ macOS, and Windows proof is pending
- Cursor or VS Code with the Unity Cursor Toolkit extension
+## Unity Version Support and Unity 7 Readiness
+
+- Core package metadata declares Unity 2019.4 or later.
+- Unity-Unterm declares Unity 6000.3 or later on macOS or Windows. The local
+ sample proof is Unity 6000.3.9f1 on macOS; Windows proof is pending.
+- Mono debugging and IL-patch hot reload are legacy-runtime paths. They must be
+ capability-gated before a CoreCLR-only Editor is claimed.
+- Unity 7 is a planned, evidence-gated target. The CoreCLR audit, migration
+ assistant, replacement debugger, compatibility matrix, and first-party
+ CLI/Pipeline composition are not yet complete.
+
+The canonical status and acceptance gates are in the
+[Unity 7 readiness plan](https://github.com/rankupgames/unity-cursor-toolkit/blob/main/docs/UNITY_7_READINESS.md).
+Detailed work is in the
+[WS1–WS8 task index](https://github.com/rankupgames/unity-cursor-toolkit/blob/main/docs/tasks/README.md).
+
Do not install the standalone `dev.tnayuki.unterm` package beside this toolkit. Both packages contain the same editor types and native plugin identity, so that combination is unsupported.
Open the bundled tools from **Tools > Unity Cursor Toolkit > Unterm**, then choose **New Terminal**, **Claude Code**, **Code Editor**, **Debugger**, or **Settings**. Unity-Unterm MCP access remains disabled until it is explicitly enabled for the current project in Preferences.
@@ -102,10 +121,14 @@ Commands run on Unity's main thread as coroutines. They should call existing gam
See the repository docs:
-- `docs/AI_AGENTS.md`
-- `docs/GAME_COMMANDS.md`
-- `docs/MCP_CLIENTS.md`
-- `docs/FEATURE_ROADMAP.md`
+- [AI agent guide](https://github.com/rankupgames/unity-cursor-toolkit/blob/main/docs/AI_AGENTS.md)
+- [Runtime game commands](https://github.com/rankupgames/unity-cursor-toolkit/blob/main/docs/GAME_COMMANDS.md)
+- [MCP client setup](https://github.com/rankupgames/unity-cursor-toolkit/blob/main/docs/MCP_CLIENTS.md)
+- [Feature roadmap](https://github.com/rankupgames/unity-cursor-toolkit/blob/main/docs/FEATURE_ROADMAP.md)
+- [Unity 7 readiness](https://github.com/rankupgames/unity-cursor-toolkit/blob/main/docs/UNITY_7_READINESS.md)
+- [WS1–WS8 task index](https://github.com/rankupgames/unity-cursor-toolkit/blob/main/docs/tasks/README.md)
+- [Package changelog](../CHANGELOG.md)
+- [Package license](../LICENSE.md)
## Editor Validation
diff --git a/CursorUnityTool/Packages/com.rankupgames.unity-cursor-toolkit/Editor/ApplicationScreenshotCapture.cs b/CursorUnityTool/Packages/com.rankupgames.unity-cursor-toolkit/Editor/ApplicationScreenshotCapture.cs
new file mode 100644
index 0000000..a77cb9f
--- /dev/null
+++ b/CursorUnityTool/Packages/com.rankupgames.unity-cursor-toolkit/Editor/ApplicationScreenshotCapture.cs
@@ -0,0 +1,79 @@
+/*
+ * Author: Miguel A. Lopez
+ * Company: Rank Up Games LLC
+ * Project: Unity Cursor Toolkit
+ * Description: Captures the current application camera view for editor diagnostics.
+ */
+
+#if UNITY_EDITOR
+using System;
+using System.IO;
+
+using UnityEngine;
+
+namespace UnityCursorToolkit
+{
+ ///
+ /// Captures the current application view from the main camera to one stable temp file.
+ ///
+ internal static class ApplicationScreenshotCapture
+ {
+ private const string ScreenshotFileName = "unity-cursor-toolkit-application.png";
+
+ internal static string ScreenshotPath => Path.Combine(Application.temporaryCachePath, ScreenshotFileName);
+
+ internal static bool TryCapture(out string path, out string error)
+ {
+ path = ScreenshotPath;
+ error = null;
+
+ Camera camera = Camera.main;
+ if (camera == null)
+ {
+ error = "No main camera found";
+ return false;
+ }
+
+ int width = Math.Max(1, Screen.width);
+ int height = Math.Max(1, Screen.height);
+ RenderTexture previousTarget = camera.targetTexture;
+ RenderTexture previousActive = RenderTexture.active;
+ RenderTexture renderTexture = null;
+ Texture2D texture = null;
+
+ try
+ {
+ renderTexture = RenderTexture.GetTemporary(width, height, 24);
+ camera.targetTexture = renderTexture;
+ camera.Render();
+
+ RenderTexture.active = renderTexture;
+ texture = new Texture2D(width, height, TextureFormat.RGB24, false);
+ texture.ReadPixels(new Rect(0, 0, width, height), 0, 0);
+ texture.Apply();
+ File.WriteAllBytes(path, texture.EncodeToPNG());
+ return true;
+ }
+ catch (Exception exception)
+ {
+ error = exception.Message;
+ return false;
+ }
+ finally
+ {
+ camera.targetTexture = previousTarget;
+ RenderTexture.active = previousActive;
+ if (texture != null)
+ {
+ UnityEngine.Object.DestroyImmediate(texture);
+ }
+ if (renderTexture != null)
+ {
+ RenderTexture.ReleaseTemporary(renderTexture);
+ }
+ }
+ }
+ }
+}
+
+#endif // UNITY_EDITOR
diff --git a/CursorUnityTool/Packages/com.rankupgames.unity-cursor-toolkit/Editor/ApplicationScreenshotCapture.cs.meta b/CursorUnityTool/Packages/com.rankupgames.unity-cursor-toolkit/Editor/ApplicationScreenshotCapture.cs.meta
new file mode 100644
index 0000000..aaa8598
--- /dev/null
+++ b/CursorUnityTool/Packages/com.rankupgames.unity-cursor-toolkit/Editor/ApplicationScreenshotCapture.cs.meta
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 5f0a4b7cdb8445b08c94c335f47c0b1d
+MonoImporter:
+ externalObjects: {}
+ serializedVersion: 2
+ defaultReferences: []
+ executionOrder: 0
+ icon: {instanceID: 0}
+ userData:
+ assetBundleName:
+ assetBundleVariant:
diff --git a/CursorUnityTool/Packages/com.rankupgames.unity-cursor-toolkit/Editor/ConsoleLogCopyTool.cs b/CursorUnityTool/Packages/com.rankupgames.unity-cursor-toolkit/Editor/ConsoleLogCopyTool.cs
index 8cf6000..d393381 100644
--- a/CursorUnityTool/Packages/com.rankupgames.unity-cursor-toolkit/Editor/ConsoleLogCopyTool.cs
+++ b/CursorUnityTool/Packages/com.rankupgames.unity-cursor-toolkit/Editor/ConsoleLogCopyTool.cs
@@ -2,7 +2,7 @@
* Author: Miguel A. Lopez
* Company: Rank Up Games LLC
* Project: Unity Cursor Toolkit
- * Description: Editor tool to copy all Unity console log entries to the clipboard.
+ * Description: Editor tool to copy Unity console/profiler context and a temporary application screenshot path.
* Adds a button to the main toolbar and a menu item under Tools.
* Created: 2026-04-13
* Last Modified: 2026-04-19
@@ -41,7 +41,7 @@ static MainToolbarButton CreateMainToolbarCopyLogsButton()
{
Texture2D _icon = EditorGUIUtility.IconContent("Clipboard").image as Texture2D;
return new MainToolbarButton(
- new MainToolbarContent(_icon, "Copy all console logs to clipboard"),
+ new MainToolbarContent(_icon, "Copy profiler session, console transcript, and application screenshot path"),
() => CopyConsoleLogs());
}
#endif
@@ -55,8 +55,19 @@ static MainToolbarButton CreateMainToolbarCopyLogsButton()
internal static void CopyConsoleLogs()
{
var _entries = GetConsoleLogEntries();
+ string clipboardContent = ProfilerSessionRecorder.BuildClipboardSnapshot(_entries, ProfilerSnapshotSettings.Current.IncludeRawFrameArrays);
+ string screenshotPath;
+ string screenshotError;
+ if (ApplicationScreenshotCapture.TryCapture(out screenshotPath, out screenshotError))
+ {
+ clipboardContent += "\n\nApplication screenshot: " + screenshotPath;
+ }
+ else
+ {
+ Debug.LogWarning("(ConsoleLogCopyTool - CopyConsoleLogs) Application screenshot was not captured: " + screenshotError);
+ }
- GUIUtility.systemCopyBuffer = ProfilerSessionRecorder.BuildClipboardSnapshot(_entries, ProfilerSnapshotSettings.Current.IncludeRawFrameArrays);
+ GUIUtility.systemCopyBuffer = clipboardContent;
if (string.IsNullOrEmpty(_entries))
{
Debug.Log("(ConsoleLogCopyTool - CopyConsoleLogs) Console is empty; copied current profiler session snapshot to clipboard");
diff --git a/Packages/com.rankupgames.unity-cursor-toolkit/CHANGELOG.md b/Packages/com.rankupgames.unity-cursor-toolkit/CHANGELOG.md
index 1329451..57b631a 100644
--- a/Packages/com.rankupgames.unity-cursor-toolkit/CHANGELOG.md
+++ b/Packages/com.rankupgames.unity-cursor-toolkit/CHANGELOG.md
@@ -14,6 +14,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Added the `editor_validation` MCP tool and menu command for project-file regeneration plus script compile requests.
- Added the audited Unity-Unterm fork as a toolkit-internal terminal, Claude Code, code editor, completion, and debugger feature for Unity 6000.3 on macOS and Windows.
- Added Unity-Unterm launch aliases under `Tools > Unity Cursor Toolkit > Unterm`.
+- Added a native toolbar copy action that captures the current main-camera
+ application view, overwrites one stable temporary PNG on every click, and
+ appends its absolute path to the copied console and profiler context.
+
+### Documentation
+
+- Added the canonical Unity 7 readiness plan and evidence-gated WS1 through
+ WS8 workstreams.
+- Clarified that Unity 2019.4 and Unity 6000.3 are declared baselines, while
+ CoreCLR transition and Unity 7 support need exact-version proof.
### Security
diff --git a/Packages/com.rankupgames.unity-cursor-toolkit/Documentation~/README.md b/Packages/com.rankupgames.unity-cursor-toolkit/Documentation~/README.md
index 728e354..f30394c 100644
--- a/Packages/com.rankupgames.unity-cursor-toolkit/Documentation~/README.md
+++ b/Packages/com.rankupgames.unity-cursor-toolkit/Documentation~/README.md
@@ -6,6 +6,7 @@ Editor tools for Cursor/VS Code and MCP-capable AI agents integrating with Unity
- **Hot Reload**: TCP server that triggers asset refresh when code changes are detected
- **Console Forwarding**: Streams Unity console output to Cursor/VS Code
+- **Copy Snapshot**: Copies profiler/console context and overwrites one stable temporary main-camera screenshot on each click
- **MCP Bridge**: Model Context Protocol tool dispatch for AI-assisted Unity editing
- **Editor Validation**: Regenerates Unity project files and requests script compilation from Cursor/VS Code
- **Runtime Game Commands**: Project-owned coroutine workflows callable through MCP without UI automation
@@ -50,9 +51,27 @@ Add to your `Packages/manifest.json`:
## Requirements
- Unity 2019.4 or later for the core toolkit
-- Unity 6000.3 or later on macOS or Windows for the bundled Unity-Unterm features
+- Declared Unity 6000.3 or later requirement on macOS or Windows for the
+ bundled Unity-Unterm features; the local sample proof is Unity 6000.3.9f1 on
+ macOS, and Windows proof is pending
- Cursor or VS Code with the Unity Cursor Toolkit extension
+## Unity Version Support and Unity 7 Readiness
+
+- Core package metadata declares Unity 2019.4 or later.
+- Unity-Unterm declares Unity 6000.3 or later on macOS or Windows. The local
+ sample proof is Unity 6000.3.9f1 on macOS; Windows proof is pending.
+- Mono debugging and IL-patch hot reload are legacy-runtime paths. They must be
+ capability-gated before a CoreCLR-only Editor is claimed.
+- Unity 7 is a planned, evidence-gated target. The CoreCLR audit, migration
+ assistant, replacement debugger, compatibility matrix, and first-party
+ CLI/Pipeline composition are not yet complete.
+
+The canonical status and acceptance gates are in the
+[Unity 7 readiness plan](https://github.com/rankupgames/unity-cursor-toolkit/blob/main/docs/UNITY_7_READINESS.md).
+Detailed work is in the
+[WS1–WS8 task index](https://github.com/rankupgames/unity-cursor-toolkit/blob/main/docs/tasks/README.md).
+
Do not install the standalone `dev.tnayuki.unterm` package beside this toolkit. Both packages contain the same editor types and native plugin identity, so that combination is unsupported.
Open the bundled tools from **Tools > Unity Cursor Toolkit > Unterm**, then choose **New Terminal**, **Claude Code**, **Code Editor**, **Debugger**, or **Settings**. Unity-Unterm MCP access remains disabled until it is explicitly enabled for the current project in Preferences.
@@ -102,10 +121,14 @@ Commands run on Unity's main thread as coroutines. They should call existing gam
See the repository docs:
-- `docs/AI_AGENTS.md`
-- `docs/GAME_COMMANDS.md`
-- `docs/MCP_CLIENTS.md`
-- `docs/FEATURE_ROADMAP.md`
+- [AI agent guide](https://github.com/rankupgames/unity-cursor-toolkit/blob/main/docs/AI_AGENTS.md)
+- [Runtime game commands](https://github.com/rankupgames/unity-cursor-toolkit/blob/main/docs/GAME_COMMANDS.md)
+- [MCP client setup](https://github.com/rankupgames/unity-cursor-toolkit/blob/main/docs/MCP_CLIENTS.md)
+- [Feature roadmap](https://github.com/rankupgames/unity-cursor-toolkit/blob/main/docs/FEATURE_ROADMAP.md)
+- [Unity 7 readiness](https://github.com/rankupgames/unity-cursor-toolkit/blob/main/docs/UNITY_7_READINESS.md)
+- [WS1–WS8 task index](https://github.com/rankupgames/unity-cursor-toolkit/blob/main/docs/tasks/README.md)
+- [Package changelog](../CHANGELOG.md)
+- [Package license](../LICENSE.md)
## Editor Validation
diff --git a/README.md b/README.md
index 8f69bb5..1cb4c03 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,15 @@
# Unity Cursor Toolkit
-[](https://marketplace.visualstudio.com/items?itemName=rankupgames.unity-cursor-toolkit)
-[](https://marketplace.visualstudio.com/items?itemName=rankupgames.unity-cursor-toolkit)
+[](https://marketplace.visualstudio.com/items?itemName=rankupgames.unity-cursor-toolkit)
[](https://open-vsx.org/extension/rankupgames/unity-cursor-toolkit)
[](https://open-vsx.org/extension/rankupgames/unity-cursor-toolkit)
[](https://github.com/rankupgames/unity-cursor-toolkit/actions)
[](https://opensource.org/licenses/MIT)
-A VS Code / Cursor extension that bridges your editor and the Unity Editor -- hot reload, live console, MCP server for AI agents, Mono debugging, and stable TCP connectivity.
+A VS Code / Cursor extension and Unity package for live console context, safe
+MCP automation, debugging, hot reload, and remote Unity workflows. The package
+declares Unity 2019.4 as its core baseline; Unity 7 is an explicit,
+evidence-gated readiness target.
## Disclaimer
@@ -21,7 +23,7 @@ Save-to-refresh with debounced file watching and compilation feedback in the sta
### Live Console
-Real-time streaming, severity filtering, text search across messages and stack traces, safe clickable `Assets/...` stack traces, copy/export, send-to-AI-chat, and a ring buffer (10k entries, configurable). Console snapshots can include the current Unity profiler session so agents get logs, frame trends, hot frames, and hot paths together.
+Real-time streaming, severity filtering, text search across messages and stack traces, safe clickable `Assets/...` stack traces, copy/export, send-to-AI-chat, and a ring buffer (10k entries, configurable). Console snapshots can include the current Unity profiler session so agents get logs, frame trends, hot frames, and hot paths together. The native Unity copy button also captures the current main-camera application view to one stable temporary PNG, overwrites it on every click, and appends its absolute path to the copied context.
### Connection
@@ -79,12 +81,28 @@ Agent safety defaults:
- Use `unity_context` with `action: "scan"` to refresh `.umetacontext/index.json`, then use `summary`, `query`, and `read` to inspect assets, GUIDs, serialized objects, components, and references without broad file reads.
- Use `game_command` with `action: "list"` to discover project-authored runtime workflows before scheduling them.
-See [AI Agent Guide](docs/AI_AGENTS.md), [Runtime Game Commands](docs/GAME_COMMANDS.md), [Feature Roadmap](docs/FEATURE_ROADMAP.md), and [llms.txt](llms.txt) for agent-facing context.
+See the [documentation index](docs/README.md), [AI Agent Guide](docs/AI_AGENTS.md), [Runtime Game Commands](docs/GAME_COMMANDS.md), [Unity 7 Readiness Plan](docs/UNITY_7_READINESS.md), [Feature Roadmap](docs/FEATURE_ROADMAP.md), and [llms.txt](llms.txt) for agent-facing context.
## Requirements
- VS Code or Cursor 1.60+
-- Unity 2019.4+
+- Unity 2019.4+ as the declared core package baseline; see the evidence table
+ below
+
+## Unity Version Support and Unity 7 Readiness
+
+| Editor family | Current position |
+| --- | --- |
+| Unity 2019.4 through 2022 LTS | Declared core package range; preserve the Mono debugger and legacy hot-reload path and add exact-version evidence |
+| Current Unity 6 releases | Unity-Unterm declares Unity 6000.3+ on macOS or Windows; the local sample baseline is Unity 6000.3.9f1 on macOS |
+| CoreCLR transition releases | Capability gates, reload fixes, migration checks, and a debugger replacement are planned and not yet complete |
+| Unity 7 | Readiness target only; do not treat this README as a compatibility certification |
+
+The plan is one stable agent interface across Editor generations, with an
+explicit backend and capability set for every operation. See the
+[Unity 7 Readiness Plan](docs/UNITY_7_READINESS.md), the dated
+[landscape assessment](docs/UNITY_7_LANDSCAPE_ASSESSMENT.md), and the
+[WS1–WS8 task index](docs/tasks/README.md).
## Unity Package Installation
@@ -194,7 +212,7 @@ The VSIX package is intentionally limited to runtime extension assets: compiled
| `unity-cursor-toolkit.stopConnection` | Stop the connection |
| `unity-cursor-toolkit.console.clear` | Clear the console panel |
| `unity-cursor-toolkit.console.sendToChat` | Send console output to AI chat |
-| `unity-cursor-toolkit.console.copy` | Copy console output to clipboard |
+| `unity-cursor-toolkit.console.copy` | Copy console/profiler context to the clipboard |
| `unity-cursor-toolkit.console.snapshot` | Take a console/profiler snapshot |
| `unity-cursor-toolkit.console.export` | Export console logs to file |
| `unity-cursor-toolkit.resolveMeta` | Resolve `.meta` file for a path (for AI) |
@@ -237,7 +255,7 @@ unity-cursor-toolkit/
│ └── MCP/ # MCP bridge, scene/asset/editor tools
├── CursorUnityTool/ # Unity test project
├── zed/ # Zed editor integration (MCP)
-├── docs/ # Agent and MCP setup docs
+├── docs/ # Product guides, Unity 7 readiness, research, and workstreams
├── AGENTS.md # Coding-agent repo instructions
├── llms.txt # AI-readable documentation index
├── .github/workflows/ # CI and release pipelines
@@ -269,4 +287,5 @@ See [SECURITY.md](SECURITY.md) for vulnerability reporting.
## License
-MIT License -- Copyright (c) 2025 Rank Up Games LLC. See [LICENSE](LICENSE) for details.
+MIT License -- Copyright (c) 2025 Rank Up Games LLC. See
+[LICENSE](unity-cursor-toolkit/LICENSE) for details.
diff --git a/docs/AI_AGENTS.md b/docs/AI_AGENTS.md
index 03660d8..2856166 100644
--- a/docs/AI_AGENTS.md
+++ b/docs/AI_AGENTS.md
@@ -2,10 +2,25 @@
Unity Cursor Toolkit is designed to give agents direct Unity Editor context without requiring users to paste console logs, scene state, or `.meta` files manually.
+## Unity Version and Backend Status
+
+The core package declares Unity 2019.4 or later. Current operations use the
+toolkit bridge or an explicitly requested batchmode Editor. Standalone Unity
+CLI, Pipeline, CoreCLR-specific behavior, and Unity 7 support are planned or
+evidence-gated backends; agents must not claim they are shipped until the
+capability response and recorded matrix prove them.
+
+Never silently switch to another Editor version or backend. Report the selected
+Editor, backend, and capability set in plans and results. See
+`docs/UNITY_7_READINESS.md` and `docs/tasks/README.md`.
+
## What Agents Can Do
- Read recent Unity console output with `read_console`.
- Capture current console/profiler context with `profiler_snapshot`.
+- Use the Unity toolbar copy action when a human wants clipboard context plus a
+ current main-camera application screenshot path. Each click overwrites the
+ same temporary PNG.
- Read compact whole-console session transcripts with `profiler_snapshot` using `action: "readConsoleTranscript"` after capturing or listing a session id.
- Scan, summarize, query, and read the local Unity asset/object/reference graph with `unity_context`.
- Inspect project state with `project_info`.
@@ -98,3 +113,5 @@ These prompts are intentionally conservative: inspect first, summarize state, th
- Unity Test Runner tools: list tests, run EditMode/PlayMode tests, and return structured failures.
- Build report tools: parse build output, surface warnings/errors, and compare artifact sizes.
- Package Manager tools: list packages, inspect versions, and propose dependency changes with dry-run output.
+- CoreCLR and Unity 7 work is tracked in `docs/UNITY_7_READINESS.md`; do not
+ present unchecked workstream tasks as available tools.
diff --git a/docs/EDITOR_WINDOW_STREAMING_PLAN.md b/docs/EDITOR_WINDOW_STREAMING_PLAN.md
index 989bac7..0a88d3f 100644
--- a/docs/EDITOR_WINDOW_STREAMING_PLAN.md
+++ b/docs/EDITOR_WINDOW_STREAMING_PLAN.md
@@ -1,5 +1,10 @@
# Editor Window Streaming Plan
+Status: **experimental plan with dated evidence**. Recorded results must keep
+their exact Editor version and platform. They do not prove Unity 7 support. See
+the [Unity 7 readiness plan](UNITY_7_READINESS.md) and
+[WS7](tasks/WS7_REMOTE_SHELL.md) for current gates.
+
Goal: stop re-rendering cameras with our own HTML toolbar and instead stream the *real* Unity editor windows -- Scene View (with its actual toolbar, gizmos, handles, tools), Game View, Inspector, Package Manager, and any custom `EditorWindow` -- into Cursor panels, with Unity running invisibly in the background and auto-launched by the extension.
This builds on the working v0 loop (camera -> RenderTexture -> JPEG -> `viewportFrame` -> webview), which stays as the batchmode/headless fallback.
@@ -86,9 +91,12 @@ On Windows, there are more native-window tricks, but they split by surface:
- SSHFS/NFS project mount for casual browsing: fine for `Assets/`, exclude `Library/Temp` (lock + perf).
- Preferred per existing docs: `.umetacontext` summaries + narrow file fetch instead of bulk mounts.
-## 7. Spike harness (included in this commit)
+## 7. Spike Harness And Recorded Proof
-The riskiest assumptions are (1) `GrabPixels` exists and produces non-blank captures of SceneView/Inspector/PackageManager/custom windows on Unity 6.3, hidden; (2) `SendEvent` actually drives SceneView orbit. The spike proves both in one shot, with Unity closed beforehand:
+The spike tests whether `GrabPixels` produces non-blank captures of
+SceneView, Inspector, Package Manager, and custom windows, and whether
+`SendEvent` drives SceneView orbit. The recorded macOS sample used Unity
+6000.3.9f1. Other Editor versions and Windows remain separate gates.
```bash
# close Unity first (runner refuses if Temp/UnityLockfile is held)
@@ -105,15 +113,15 @@ Interpreting results:
## 8. Milestones with test gates
-| # | Deliverable | Test gate |
-| --- | --- | --- |
-| M0 | Spike passes on Unity 6.3 | `run-editor-window-capture-spike.js` exit 0 |
-| M1 | `EditorWindowStreamTool`: GrabPixels sessions for scene/game targets, in-band frames, RT reuse, loopback bind | `probe:editor-window-stream` proves scene/game `captureMode:"editorWindow"` frames with in-band data; existing node tests stay green |
-| M2 | Real input: pointer/wheel/key -> `SendEvent`, coordinate normalization; delete HTML toolbar clones from panels | Scripted asserts: orbit changes rotation, click changes `Selection`, W/E/R switches `Tools.current`; local p50 input->frame < 100ms |
-| M3 | Editor Session Manager: auto-launch hidden, no-throttle prefs, health/relaunch, Stop command | Cold start -> first frame < 60s with no visible Unity window; kill -9 recovery |
-| M4 | Inspector + Package Manager + custom-window targets; `manage_scene select` bridge; aux popup overlay capture | Click cube in hierarchy -> inspector panel shows it < 300ms; object picker popup streams |
-| M5 | Remote: token auth, in-band frames over SSH tunnel; Remote-SSH validated; WebRTC decision spike | Stream from a second machine; no unauthenticated LAN listener (scan) |
-| M6 | Perf: AsyncGPUReadback, frame-hash skip, dynamic res | 1280x720@30 game + 720p@12 scene simultaneously < ~25% of one core Unity-side |
+| # | Deliverable | Status | Test gate |
+| --- | --- | --- | --- |
+| M0 | Editor-window capture spike | Validated on the macOS sample; Windows pending | `run-editor-window-capture-spike.js` exit 0 with exact Editor/platform evidence |
+| M1 | `EditorWindowStreamTool`: GrabPixels sessions for scene/game targets, in-band frames, RT reuse, loopback bind | Shipped with macOS sample proof | `probe:editor-window-stream` proves scene/game `captureMode:"editorWindow"` frames with in-band data; existing node tests stay green |
+| M2 | Real input: pointer/wheel/key -> `SendEvent`, coordinate normalization; delete HTML toolbar clones from panels | Partial | Scripted asserts: orbit changes rotation, click changes `Selection`, W/E/R switches `Tools.current`; local p50 input-to-frame < 100ms |
+| M3 | Editor Session Manager: auto-launch hidden, no-throttle preferences, health/relaunch, Stop command | Experimental and partial | Cold start to first frame < 60s with no visible Unity window; an agent-owned proof instance exits unexpectedly and recovers without risking a user Editor |
+| M4 | Inspector + Package Manager + custom-window targets; `manage_scene select` bridge; auxiliary popup overlay capture | Partial | Click cube in hierarchy -> Inspector panel shows it < 300ms; object picker popup streams |
+| M5 | Remote: token auth, in-band frames over SSH tunnel; Remote-SSH validation; transport decision spike | Planned | Stream from a second machine; no unauthenticated LAN listener |
+| M6 | Performance: AsyncGPUReadback, frame-hash skip, dynamic resolution | Planned | 1280x720@30 game plus 720p@12 scene simultaneously within the measured budget |
## 9. Decision log
@@ -123,15 +131,19 @@ Interpreting results:
- Hierarchy stays native; everything pixel-streamed keeps a semantic command side-channel so agents are not click-bots.
- Windows editor hosts are first-class for the spike and hidden-editor lane; Windows player embedding/VDD capture remain the preferred no-editor remote path.
-## 10. Current Implementation Evidence
+## 10. Implemented Paths And Historical Evidence
+
+Evidence in this section is tied to its recorded date, Editor, platform,
+extension artifact, and test count. Re-run the named proof before a current or
+Unity 7 compatibility claim.
- `viewport_stream` now supports `captureMode: "editorWindow"` for `view: "scene"`, `view: "game"`, `view: "inspector"`, `view: "packageManager"`, and custom `view: "window:"`. Unity captures the actual `EditorWindow` HostView backbuffer with `GUIView.GrabPixels`, broadcasts JPEG data in-band on `viewportFrame.data`, and keeps the legacy camera capture path as `captureMode: "camera"`.
- The editor-window capture helper now reuses `RenderTexture`/`Texture2D` resources and downscales to the requested stream dimensions before JPEG encoding. This avoids the previous full-window allocation churn where Inspector/Package Manager streamed at `2024x2040` every frame.
- Cursor panels are first-class for Scene View, Game View, Inspector, Package Manager, and arbitrary custom EditorWindows. The extension contributes `Unity Toolkit: Open Scene View`, `Unity Toolkit: Open Game View`, `Unity Toolkit: Open Inspector`, `Unity Toolkit: Open Package Manager`, and `Unity Toolkit: Open Custom EditorWindow`; Quick Actions expose all five. Custom windows prompt for a full type name and stream through `view: "window:"`.
- The same Cursor shell now exposes the legitimate no-editor player lane separately: `Unity Toolkit: Open Player Scene View` and `Unity Toolkit: Open Player Game View`. Those panels request `host:"player"` with `captureMode:"camera"` and attach to a running Viewport Service player without triggering hidden-editor launch. They are not real editor UI; they are the player/runtime adapter called out in `docs/UNITY_WITHOUT_EDITOR_EXPERIMENTS.md`. Installed Cursor visual proof on macOS rendered both player panels live from the Viewport Service with the editor not running.
- macOS player perf proof for that lane is recorded at `experiments/player-viewport-service/results/2026-06-10-6000.3.9f1-macos-game-1280x720-30fps.json`: `1280x720@30` game stream, `866` frames, `28.89fps` effective, `6572ms` port-ready startup, `11692ms` first frame from launch, average stream RSS `199.5 MB`, average stream CPU `40.3%`, no leftover listener/process after cleanup.
-- Repeatable fulfillment audit: `npm --prefix unity-cursor-toolkit run audit:unity-without-editor` writes the current acceptance state. Latest result `experiments/unity-without-editor-audit/results/2026-06-10-current.json` is `PARTIAL`: legal/macOS editor-window/player evidence passes, Windows installed-host proof remains pending. When an executed Windows run writes `experiments/windows-unity-without-editor/results/**/windows-proof-summary.json`, the audit validates the summary plus E1/E2/installed-Cursor/E3 artifacts before passing the Windows gate; dry-runs stay pending.
-- Isolated installed-Cursor smoke: `npm --prefix unity-cursor-toolkit run smoke:installed-cursor-viewports` packages the VSIX, installs it into temp Cursor user-data/extensions dirs, and verifies `rankupgames.unity-cursor-toolkit@0.6.1052828` plus the viewport command surface. Latest command-surface result: `experiments/installed-cursor-smoke/results/2026-06-10-isolated-install.json`. The same runner now supports opt-in automated editor frame proof with `--viewport-proof-out`, which opens editor Scene/Game panels from the packaged extension and waits for live editorWindow frame hashes. Latest automated proof: `experiments/installed-cursor-smoke/results/2026-06-10-installed-editor-scene-game-auto-proof.json`.
+- Repeatable fulfillment audit: `npm --prefix unity-cursor-toolkit run audit:unity-without-editor` writes an acceptance snapshot. The archived 2026-06-10 result `experiments/unity-without-editor-audit/results/2026-06-10-current.json` is `PARTIAL`: legal/macOS editor-window/player evidence passes, while Windows installed-host proof remains pending. An executed Windows summary and its artifacts are required before the audit can pass that gate.
+- Isolated installed-Cursor smoke: `npm --prefix unity-cursor-toolkit run smoke:installed-cursor-viewports` packages the VSIX, installs it into temporary Cursor directories, and verifies the viewport command surface. The archived proof used distribution artifact `rankupgames.unity-cursor-toolkit@0.6.1052828`; it is not the current source package version. Archived results are `experiments/installed-cursor-smoke/results/2026-06-10-isolated-install.json` and `experiments/installed-cursor-smoke/results/2026-06-10-installed-editor-scene-game-auto-proof.json`.
- Installed-Cursor editor UI proof: `experiments/installed-cursor-smoke/results/2026-06-10-installed-editor-scene-game-ui.json` records Cursor command-palette availability, official Unity editor process launch, bridge `55500`, live `Unity Scene View` frame `1108x720 #307`, and live `Unity Game View` frame `1279x704 #126`. Screenshot: `experiments/installed-cursor-smoke/screenshots/2026-06-10-installed-cursor-editor-scene-game.png`.
- Automated installed-Cursor editor frame proof: `experiments/installed-cursor-smoke/results/2026-06-10-installed-editor-scene-game-auto-proof.json` records packaged extension activation in Cursor `3.6.31`, bridge `55500`, Scene `host:"editor"`/`captureMode:"editorWindow"` frame `1108x720 #1` with SHA-256 `c72f842fdd99e6abc258476683807f5cb37872178bd2560632c5d6d3264c07b8`, and Game `host:"editor"`/`captureMode:"editorWindow"` frame `1280x704 #1` with SHA-256 `bae3b7998f95fa743ced83402f9403cb041b9ae9bdb1359a6df63d1d32361f0d`.
- Windows gate runner: `npm --prefix unity-cursor-toolkit run proof:windows-unity-without-editor` now orchestrates the required Windows evidence run for E1 DLL mount, E2 hidden `GUIView.GrabPixels` spike, packaged installed-Cursor Scene/Game frame-hash proof, E3 Windows player build/probe, and E3 player perf, and writes `windows-proof-summary.json` incrementally so failed attempts still leave usable evidence. This is a runner only until it is executed on a Windows Unity host.
@@ -145,7 +157,9 @@ Interpreting results:
- Stability note from the live proof: before the resource-clamp patch, concurrent full-resolution editor-window streams triggered a Unity native segfault in the graphics/profiler path and left a stale `Temp/UnityLockfile`. After the patch, the five-surface probe completed without crashing, but Unity still logged profiler buffering pressure during validation; sustained multi-window streaming still needs longer soak tests and adaptive FPS/resolution before product completion.
- Connection hardening: Cursor now rejects open TCP ports that do not answer toolkit JSON `pong`, which prevents false attachment to Unity's built-in editor/player listener on `55504`.
- Fresh installed-VSIX retest after panel cleanup: stale disposed webviews no longer throw when Scene/Game panels are closed and reopened from Unity Quick Actions; Scene/Game streams reopened cleanly and kept toolkit status/meta text in the bottom status bar instead of overlaying HUD text on captured Unity pixels.
-- `npm run validate` passes after the implementation: TypeScript compile, unused checks, 162 runtime tests, 9 simplified-context tests, 7 remote-shell tests, and npm audit.
+- Validation on 2026-08-13 passed TypeScript compile and unused checks, 205
+ runtime tests, 10 simplified-context tests, 10 remote-shell tests, vendored
+ Unity-Unterm validation, and npm audit with zero findings.
- Repeatable bridge check: open the Unity project with the toolkit bridge running, then run `npm --prefix unity-cursor-toolkit run probe:editor-window-stream`.
Remaining before calling the cross-platform/product program done: run the same installed-extension visual proof on a Windows editor host, record hidden repaint/input behavior under PowerShell/user32 hiding, then complete player perf and Windows build/run/probe numbers for deployed/license-less hosts.
diff --git a/docs/FEATURE_ROADMAP.md b/docs/FEATURE_ROADMAP.md
index 20ea4dd..777a4a3 100644
--- a/docs/FEATURE_ROADMAP.md
+++ b/docs/FEATURE_ROADMAP.md
@@ -1,36 +1,87 @@
# Feature Roadmap
-This roadmap focuses on features that make Unity Cursor Toolkit more useful for human developers and safer for AI agents.
+Last reviewed: 2026-08-13
-## MCP Readiness
+This roadmap separates shipped capabilities from planned work. Unity 7 is an
+evidence-gated target. The canonical compatibility status and release gates are
+in [Unity 7 Readiness](UNITY_7_READINESS.md).
-- Ship the standalone stdio MCP server as the primary cross-client integration path.
-- Keep tool schemas stable and additive; prefer aliases over breaking argument changes.
-- Add richer structured outputs for project info, scene hierarchy, build reports, test results, and profiler snapshots.
-- Add install snippets and client-specific setup docs for Cursor, Claude Code, VS Code, Zed, Windsurf, and other MCP clients.
-- Expand resources and prompts so agents can discover context without calling mutating tools first.
+## Shipped Foundations
+
+- Standalone stdio MCP server for VS Code/Cursor, Claude Code, Zed, and other
+ MCP clients.
+- Stable additive tool schemas, resources, prompts, read-only mode, and dry-run
+ previews.
+- Live console and profiler sessions, compact transcripts, context indexing,
+ safe `.meta` resolution, and project information.
+- Runtime `game_command` workflows through an attached Editor or explicit
+ editor-batchmode host.
+- Scene, asset, component, material, play-mode, build, lifecycle, screenshot,
+ and editor-validation tools.
+- Native Unity copy action that overwrites one temporary main-camera screenshot
+ and appends its absolute path to copied profiler/console context.
+- Experimental hidden-editor, remote-shell, and viewport proof lanes.
+
+## Unity 7 Preparation
+
+| Priority | Work | Status | Plan |
+| --- | --- | --- | --- |
+| P0 | CoreCLR package and vendored-code audit | Ready to start | [WS1](tasks/WS1_CORECLR_AUDIT.md) |
+| P0 | CoreCLR Migration Assistant | Planned; depends on WS1 | [WS2](tasks/WS2_MIGRATION_ASSISTANT.md) |
+| P0 | CoreCLR debugger feasibility and integration | Spike pending; depends on WS1 | [WS3](tasks/WS3_CORECLR_DEBUGGER.md) |
+| P0 | Version/capability matrix and backend-origin policy | Planning active | [WS4](tasks/WS4_MCP_REPOSITION_BACKCOMPAT.md) |
+| P1 | Static-state detector for reload changes | Planned; depends on WS1 | [WS5](tasks/WS5_STATICS_DETECTOR.md) |
+| P1 | Stable cross-version Test Runner bridge | Parity spike ready | [WS6](tasks/WS6_TEST_RUNNER_BRIDGE.md) |
+| P1 | Remote rendered-shell productization | Experimental background work | [WS7](tasks/WS7_REMOTE_SHELL.md) |
+| P0 | Pinned Unity CLI/Pipeline adoption and Unity 7 watch | Baseline ready; integration not shipped | [WS8](tasks/WS8_UNITY7_WATCH.md) |
+
+No row in this table is a Unity 7 support claim. Each workstream has explicit
+evidence and compatibility acceptance criteria.
+
+## MCP and Product Direction
+
+- Keep one stable public interface across legacy Unity, current Unity 6, the
+ CoreCLR transition, and Unity 7.
+- Report the selected backend, origin, Editor version, and capability set.
+- Compose toolkit, Unity CLI, Pipeline, and Assistant surfaces only after their
+ schemas and mutation boundaries are reviewed.
+- Add origin-qualified names and aliases without removing current public
+ arguments.
+- Add richer structured results for builds, tests, profiler snapshots, package
+ operations, and compatibility diagnostics.
## Unity Automation
-- Runtime command registry: expose project-owned coroutine workflows through MCP without UI automation.
-- Prefab tools: inspect overrides, instantiate prefabs, apply/revert changes, and support variants.
-- Selection tools: get current selection, select by instance ID, frame selected objects, and ping assets.
-- Test Runner tools: list tests, run EditMode/PlayMode tests, and return structured failures.
-- Build report tools: trigger builds, read build summaries, compare size deltas, and surface warnings.
-- Package Manager tools: list packages, inspect versions, and prepare dependency changes.
-- Profiler tools: capture FPS, memory, GC allocations, and slow frame summaries.
+- Prefab and selection tools with Undo-aware mutations.
+- Test Runner list/run/progress/results through a stable cross-version schema.
+- Build reports with warnings, failures, size deltas, and backend identity.
+- Package Manager inspection and reviewed dependency preparation.
+- CoreCLR migration reports and static-state transition diagnostics.
+- Exact-version Editor/module resolution through a pinned CLI adapter where
+ eligible, with no implicit upgrade or `latest` substitution.
+
+## Remote and Rendered Workflows
+
+- Per-version smoke tests for internal Editor-window capture and input paths.
+- Measured CoreCLR hidden-editor and player-viewport baselines.
+- Low-latency transport selection beyond the current debug path.
+- One-command remote-shell preflight, launch, attach, and safe teardown.
+- Fleet design only after the single-editor path and licensing model are proven.
-## Safety And Trust
+## Safety and Trust
-- Expand read-only mode to every new tool before exposing write behavior.
-- Keep `dryRun: true` support on all mutating tools.
-- Prefer Unity Undo-backed mutations on the C# side so user-visible edits can be reverted in the Editor.
-- Label destructive operations with `destructiveHint` and mention exact target assets/objects in outputs.
-- Add path validation and workspace containment anywhere tools touch disk.
+- Extend read-only mode to every new backend before write behavior is exposed.
+- Keep `dryRun: true` on mutating tools and backend-selection plans.
+- Never silently fall back to another Editor, host, or backend after failure.
+- Prefer Unity Undo-backed edits for user-visible state.
+- Label destructive operations and report exact targets.
+- Validate paths and prevent credential, token, and machine-path leakage.
+- Treat arbitrary code execution from any backend as a policy-escape risk.
-## Near-Term Ranking
+## Near-Term Execution
-1. Unity Test Runner tools, because tests are the highest-signal feedback loop for agents.
-2. Prefab and selection tools, because most scene-editing workflows need object targeting and reversibility.
-3. Build reports, because they turn a high-cost operation into inspectable structured output.
-4. Profiler snapshots, because performance debugging is valuable but needs more Unity-side implementation work.
+1. WS1 CoreCLR inventory and capability handshake.
+2. WS8 pinned CLI baseline and WS6 test parity spike in parallel.
+3. WS2 rule set and WS3 debugger feasibility after the WS1 capability model.
+4. WS4 compatibility matrix, documentation positioning, and backend policy.
+5. WS5 static-state detection and WS7 per-version shell smoke evidence.
diff --git a/docs/GAME_COMMANDS.md b/docs/GAME_COMMANDS.md
index db1065b..c4e4c42 100644
--- a/docs/GAME_COMMANDS.md
+++ b/docs/GAME_COMMANDS.md
@@ -2,6 +2,11 @@
Runtime game commands let a Unity project expose project-owned gameplay workflows to MCP agents without UI automation. The command lives in the game code, runs on Unity's main thread, and can wait across frames or network responses through a coroutine.
+Compatibility status: the package declares Unity 2019.4 or later. Local proof
+must name the exact Editor and platform. CoreCLR transition and Unity 7 coverage
+are planned under the [Unity 7 readiness plan](UNITY_7_READINESS.md); do not
+silently substitute a newer Editor when an exact project version is missing.
+
Use this for flows such as login steps, server selection, menu navigation, mission setup, debug-only content unlocks, or deterministic test setup that should follow the same internal handlers a player-triggered UI path uses.
## Unity Package Side
diff --git a/docs/MCP_CLIENTS.md b/docs/MCP_CLIENTS.md
index 6e5a5b8..8613a6f 100644
--- a/docs/MCP_CLIENTS.md
+++ b/docs/MCP_CLIENTS.md
@@ -14,6 +14,13 @@ The standalone MCP server path is:
/unity-cursor-toolkit/out/mcp/server.js
```
+The server uses the current toolkit bridge. Package metadata declares a Unity
+2019.4+ baseline, but that declaration is not a per-version certification.
+Unity CLI, Pipeline, CoreCLR-specific behavior, and Unity 7 are tracked in
+`docs/UNITY_7_READINESS.md`. Client configuration stays stable, but future
+backend selection must be explicit and must report its origin; it must not
+silently replace the project's declared Editor.
+
Inside VS Code/Cursor, run **Unity Toolkit: Copy MCP Client Config** to copy ready-to-edit snippets for Cursor, Claude Code, VS Code, and Zed.
## Environment Variables
diff --git a/docs/OFFICIAL_MCP_OVERLAP.md b/docs/OFFICIAL_MCP_OVERLAP.md
new file mode 100644
index 0000000..517e0c9
--- /dev/null
+++ b/docs/OFFICIAL_MCP_OVERLAP.md
@@ -0,0 +1,325 @@
+# Official Unity MCP overlap analysis
+
+Status: dated capability capture. Assistant MCP capture completed 2026-08-02;
+standalone Unity CLI and Pipeline implications added 2026-08-07; documentation
+status reviewed 2026-08-13. Ticket TASK-6.1, scope TASK-6 (WS4). Re-run the
+capture before current-version comparisons or marketing claims. Canonical
+Unity 7 status: `UNITY_7_READINESS.md`.
+
+This document records what the official Unity MCP server exposes, what Unity
+Cursor Toolkit exposes, and which behavior is commoditized by the official
+package. It is the input for the repositioning pass (TASK-6.6) and the proxy
+spike (TASK-6.4). Refresh it whenever the official package ships a new minor
+version; the capture procedure at the end is reproducible.
+
+Both inventories in this document are observed, not read off marketing pages.
+Raw captures live in `.agent/runs/TASK-6.1/artifacts/`.
+
+Scope clarification: the original capture compares the AI Assistant MCP
+(`com.unity.ai.assistant`) with Unity Cursor Toolkit. The 2026-08-07 update
+incorporates Unity's already-published separate standalone `unity` CLI and
+`com.unity.pipeline` package with its own MCP adapter. Those are not the same
+product or transport as the Assistant MCP.
+The full CLI/Pipeline inventory and adoption plan lives in
+`UNITY_CLI_AND_PIPELINE_ASSESSMENT.md`; this document preserves the dated
+Assistant capture and records the resulting positioning correction.
+
+## Captured versions
+
+| Side | Identity | Version | Minimum editor |
+| --- | --- | --- | --- |
+| Official | `com.unity.ai.assistant` from `https://packages.unity.com` | `2.17.0-pre.1` (registry `latest` on 2026-08-02, tarball shasum `284c75a8…`) | `6000.0.60f1` |
+| Official | MCP relay binary, installed to `~/.unity/relay/` by the editor | ships inside the package | same |
+| Official | Standalone Unity CLI | `1.0.0-beta.3` (released 2026-07-23) | Independent binary; manages multiple Editor versions |
+| Official | `com.unity.pipeline` | `0.4.0-exp.1` documentation captured 2026-08-07 | Unity 6.0+ |
+| Toolkit | `unity-cursor-toolkit` VS Code / Cursor extension | `0.6.1052826` | VS Code engine `^1.60.0` |
+| Toolkit | `com.rankupgames.unity-cursor-toolkit` Unity package | `1.1.0` | `2019.4` |
+
+The toolkit version and inventory above belong to the dated source capture.
+The extension source keeps a base package version, while release CI can assign
+a different distribution version. Check release artifacts separately; this
+document does not replace historical inventory values with current metadata.
+
+Capture editor: Unity `6000.5.2f1` on macOS arm64, isolated empty project,
+`-batchmode -nographics`. The official inventory was read from the package's own
+public registry API (`McpToolRegistry.GetAllToolsForSettings()`), so it reflects
+what the bridge would advertise, including per-tool enabled state.
+
+## Observed inventories
+
+The official server registered 54 tools, of which 7 are enabled by default. The
+toolkit server advertised 20 tools, 6 resources and 4 prompts, all enabled.
+These numbers are not comparable and are recorded only as capture facts: the
+official surface splits one capability across many narrow tools (14 separate
+`Unity_Profiler_*` tools), while the toolkit dispatches on an `action`
+parameter inside a smaller number of tools. Do not use either number in
+positioning material.
+
+Official tools, by group (full names, schemas and descriptions in
+`official-mcp-tool-inventory.json`):
+
+- Scripting: `Unity_CreateScript`, `Unity_DeleteScript`, `Unity_ManageScript`,
+ `Unity_ManageScript_capabilities`, `Unity_ApplyTextEdits`,
+ `Unity_ScriptApplyEdits`, `Unity_ValidateScript`, `Unity_GetSha`,
+ `Unity_ManageShader`, `Unity_RunCommand`.
+- Scene and objects: `Unity_ManageScene`, `Unity_ManageGameObject`.
+- Assets: `Unity_ManageAsset`, `Unity_ImportExternalModel`,
+ `Unity_FindProjectAssets`, `Unity_AudioClip_Edit`, and nine
+ `Unity_AssetGeneration_*` tools.
+- Editor: `Unity_ManageEditor`, `Unity_ManageMenuItem`, `Unity_GetProjectData`,
+ `Unity_GetUserGuidelines`, `Unity_PackageManager_GetData`,
+ `Unity_PackageManager_ExecuteAction`.
+- Capture: `Unity_Camera_Capture`, `Unity_SceneView_Capture2DScene`,
+ `Unity_SceneView_CaptureMultiAngleSceneView`.
+- Console: `Unity_GetConsoleLogs`, `Unity_ReadConsole`.
+- Files and search: `Unity_Grep` (bundled ripgrep over `Assets`),
+ `Unity_ListResources`, `Unity_ReadResource`, `Unity_FindInFile`.
+- Profiler analysis: 14 `Unity_Profiler_*` tools.
+
+Enabled by default: `Unity_RunCommand`, `Unity_GetConsoleLogs`,
+`Unity_Camera_Capture`, `Unity_SceneView_Capture2DScene`,
+`Unity_SceneView_CaptureMultiAngleSceneView`,
+`Unity_AssetGeneration_GenerateAsset`, `Unity_AssetGeneration_GetModels`.
+Everything else, including all scene, GameObject, asset-management and profiler
+tools, is registered but off until a user enables it in Project Settings.
+
+Toolkit tools: `manage_scene`, `manage_gameobject`, `manage_component`,
+`manage_asset`, `manage_material`, `play_mode`, `editor_lifecycle`,
+`execute_menu_item`, `screenshot`, `project_info`, `editor_validation`,
+`game_command`, `profiler_snapshot`, `build_trigger`, `batch_execute`,
+`unity_context`, `viewport_stream`, `read_console`, `clear_console`,
+`resolve_meta`. Plus resources `unity://project/info`,
+`unity://scene/hierarchy`, `unity://console/recent`, `unity://console/errors`,
+`unity://tools/catalog`, `unity://context/summary`, and four workflow prompts.
+
+## Overlap classification
+
+### Commoditized — the official package now covers this
+
+Treat these as table stakes. They are no longer a reason to choose the toolkit,
+and messaging should not lead with them.
+
+| Capability | Official | Toolkit |
+| --- | --- | --- |
+| Read console messages with filters and stack traces | `Unity_GetConsoleLogs`, `Unity_ReadConsole` | `read_console`, `clear_console` |
+| Scene and hierarchy manipulation | `Unity_ManageScene` | `manage_scene` |
+| GameObject create, find, modify, destroy | `Unity_ManageGameObject` | `manage_gameobject`, `manage_component` |
+| Asset create, move, delete, import | `Unity_ManageAsset`, `Unity_ImportExternalModel` | `manage_asset`, `manage_material` |
+| Editor state and play mode control | `Unity_ManageEditor` | `play_mode`, `editor_lifecycle` |
+| Menu item invocation | `Unity_ManageMenuItem` | `execute_menu_item` |
+| Project metadata for agents | `Unity_GetProjectData` | `project_info`, `unity://project/info` |
+| Visual capture of a camera or scene view | `Unity_Camera_Capture`, `Unity_SceneView_*` | `screenshot` |
+| Compile and script validation feedback | `Unity_ValidateScript`, `Unity_ManageScript` | `editor_validation` |
+
+### Parity in name, different in shape
+
+Same words, materially different behavior. These need care in messaging: claim
+the difference, not the category.
+
+- **Profiler.** Official has the broader analysis vocabulary — 14 tools for
+ counter summaries, frame-range top-time, GC allocation breakdowns and sample
+ drill-down. They all read `ProfilerDriver` state, meaning whatever capture is
+ already loaded in the editor's Profiler window; nothing in the official MCP
+ surface starts, stops, saves or loads a capture, and every profiler tool is
+ disabled by default. The toolkit's `profiler_snapshot` owns the capture
+ lifecycle instead (`current`, `saveSession`, `listSessions`, `readSession`,
+ `clearSessions`, `discoverCounters`) and fuses the capture with a compact
+ whole-console transcript (`readConsoleTranscript`). The honest claim is
+ agent-driven capture and console-fused timelines, not deeper profiler
+ analysis.
+- **Script editing.** Official ships a full editing suite plus
+ `Unity_RunCommand`, which compiles and executes arbitrary C# in the editor.
+ The toolkit has no equivalent and should not grow one casually: an
+ unrestricted code-execution tool is exactly the surface the toolkit's safety
+ rails exist to constrain. Note this in the proxy spike (TASK-6.4) —
+ `Unity_RunCommand` is enabled by default upstream and bypasses any per-tool
+ policy a proxy would apply to the narrower mutating tools.
+- **Project search.** Official bundles ripgrep behind `Unity_Grep` plus
+ resource read tools. The toolkit's `unity_context` answers a different
+ question: it queries a tracked asset/meta/object graph at
+ `.umetacontext/index.json` by GUID, class id, scene, prefab and dependency
+ edges, rather than searching file text.
+
+### Unique to the toolkit in the dated Assistant-only comparison
+
+The points below compare the toolkit with the captured Assistant package only.
+They do not by themselves establish uniqueness against the standalone CLI or
+Pipeline; the correction immediately after this section owns that broader
+comparison.
+
+These were the differentiators in the dated Assistant-only comparison. Recheck
+them before current positioning.
+
+- **Declared version span.** The Unity package metadata targets `2019.4`; the official package
+ requires `6000.0.60f1` or newer. Studios pinned to 2019/2020/2022 LTS cannot
+ run the captured official MCP package. This is a declared range comparison,
+ not toolkit certification across every Editor in that range.
+- **No Unity Cloud AI dependency for the interface itself.** The toolkit's
+ server is a plain Node stdio process. The official bridge ships inside the
+ Assistant package, and its asset-generation tools — two of the seven
+ enabled-by-default tools — call Unity Cloud AI and consume organization AI
+ points.
+- **Deployment envelope.** The toolkit MCP server runs standalone
+ (`node out/mcp/server.js`) with no VS Code host, and `game_command` supports
+ `host=editorBatchmode`, launching a headless editor run for a command. The
+ official bridge lives inside a running editor process; batch mode is
+ supported only as a connection-approval convenience
+ (**Auto-approve in Batch Mode**), not as a headless execution model.
+- **Safety controls at the protocol boundary.** `UNITY_CURSOR_TOOLKIT_MCP_READ_ONLY=1`
+ refuses mutating calls before any Unity traffic, `dryRun=true` returns the
+ command that would run, and every tool advertises `readOnlyHint`,
+ `destructiveHint` and `idempotentHint` annotations. The official MCP module
+ has no dry-run, no read-only mode and no destructive annotations; its
+ controls are per-tool enable/disable in Project Settings, first-connection
+ client approval, and a validation-level dropdown scoped to
+ `Unity_ManageScript`.
+- **Remote and streamed operation.** `viewport_stream` serves an MJPEG viewport
+ with input injection (`start`, `stop`, `status`, `input`) against a host and
+ port. The official capture tools return single images from the local editor.
+- **Structured project context.** `unity_context` over `.umetacontext`,
+ `resolve_meta` for raw `.meta` reads, and the `unity://` resource set give
+ agents addressable project state rather than tool calls alone.
+- **Batching.** `batch_execute` runs a sequence with fail-stop semantics and
+ propagates dry-run and destructive classification through the batch.
+- **Agent workflow prompts.** Four MCP prompts encode read-only-first
+ investigation and safe-edit planning.
+
+### Unique to the official package
+
+Record these honestly; they are the reasons a Unity 6 team might use the
+official server alongside or instead of the toolkit.
+
+- Arbitrary C# compile-and-execute (`Unity_RunCommand`).
+- A complete script authoring and patching suite with capability negotiation.
+- Generative asset creation backed by Unity Cloud AI.
+- Package Manager query and mutation tools.
+- Bundled ripgrep search over `Assets`.
+- Profiler analysis breadth over an already-loaded capture.
+- Multi-client support against one editor, with a per-client approval registry.
+- Shader and audio-clip authoring tools.
+
+## Standalone Unity CLI and Pipeline correction
+
+The 2026-08-02 Assistant comparison remains valid for that specific package,
+but it is no longer a complete comparison against Unity's official agent and
+automation stack.
+
+The standalone `unity` CLI now provides first-party commands for:
+
+- Installing, listing, upgrading, and removing Editors and build modules.
+- Resolving and opening projects with the version declared by the project.
+- Creating, cloning, linking, sizing, and closing projects and templates.
+- Running local batch builds, headless commands, and Edit/Play Mode tests with
+ structured output and differentiated exit codes.
+- Authentication, licensing, Unity Cloud identity, diagnostics, logs, cache,
+ proxy support, and machine-readable JSON/NDJSON automation.
+- Discovering connected Editors, listing their command schemas, executing
+ commands, and starting an MCP server for agent clients.
+
+The separate `com.unity.pipeline` package adds a broad Unity 6+ command catalog
+covering assets/files, scenes, GameObjects/components, prefabs, scripts,
+animation, materials/shaders, baking, search/selection, screenshots,
+compilation, builds, tests, project settings, packages, Editor lifecycle,
+performance, development Players, C# evaluation, and hot reload. Project code
+can add typed commands with `[CliCommand]`.
+
+This changes four earlier conclusions:
+
+1. **Headless execution is no longer toolkit-only in the broad sense.** The
+ toolkit still has a distinct remote/batch deployment envelope and legacy
+ span, but official `unity build`, `unity run`, and `unity test` now cover
+ common local batch workflows.
+2. **First-party MCP is no longer only the Assistant relay.** `unity mcp`
+ exposes Pipeline commands as MCP tools without routing through the Assistant
+ package inventory captured above.
+3. **Build/test basics are commoditized on Unity 6+.** Toolkit investment must
+ target legacy compatibility, safety policy, streaming/progress, structured
+ composition, project-specific workflows, remote operation, and gaps proven
+ by a parity matrix.
+4. **Proxy work must distinguish origins.** Assistant MCP, Pipeline MCP, and
+ toolkit tools have different transports, schemas, version ranges, and safety
+ properties. A single catalog needs origin metadata and an explicit policy
+ for arbitrary C# evaluation and other broad mutations.
+
+The planned differentiators remain the declared 2019.4+ version span, explicit
+read-only/dry-run policy, remote viewport and virtualized shell, structured
+project context, profiler-capture lifecycle, and composition across local,
+remote, interactive, batch, and CI workflows.
+
+## Assistant MCP deployment, account and package requirements
+
+| Dimension | AI Assistant MCP | Unity Cursor Toolkit |
+| --- | --- | --- |
+| Editor range | Unity 6 (`6000.0.60f1`) and later | Unity `2019.4` and later |
+| Unity-side install | `com.unity.ai.assistant`, 531 MB unpacked, pulls `com.unity.nuget.newtonsoft-json`, `com.unity.mathematics`, `com.unity.nuget.mono-cecil`, `com.unity.2d.sprite`, UIElements and UnityWebRequest modules | `com.rankupgames.unity-cursor-toolkit` 1.1.0, depends on `com.unity.modules.jsonserialize` and `com.unity.nuget.newtonsoft-json` |
+| Client-side install | Relay binary auto-installed to `~/.unity/relay/`; clients launch it with `--mcp`; four prebuilt platform binaries only | VS Code / Cursor extension, or the compiled Node stdio server directly |
+| Editor process required | Yes — the bridge runs in the editor and the relay discovers a live editor instance | Yes for editor-backed tools; `game_command host=editorBatchmode` launches a headless editor itself |
+| Account requirements | Tool *registration* observed with no AI sign-in; asset-generation tools require Unity Cloud AI and consume organization AI points | None beyond a licensed Unity editor |
+| Connection model | IPC (named pipe / Unix socket) between relay and editor; first direct connection needs manual approval in Project Settings; AI-gateway connections auto-approved; batch mode can auto-approve | stdio to the toolkit server; the toolkit server talks to the editor bridge |
+| Targeting multiple editors | `--project-path` / `--instance-id`, or `UNITY_PROJECT_PATH` / `UNITY_INSTANCE_ID` | project root resolution plus `host` parameters on remote-capable tools |
+| Default exposure | 7 of 54 tools enabled, including arbitrary code execution and credit-consuming generation | all 20 tools enabled, with read-only mode and dry-run available |
+
+## Implications
+
+For repositioning (TASK-6.6):
+
+1. Lead with the version span. It is the one difference the official package
+ cannot close for existing LTS projects.
+2. Lead with the deployment envelope: standalone server, remote and legacy
+ batch execution, remote viewport streaming, and one policy layer over both
+ toolkit and first-party CLI/Pipeline commands. Do not claim generic local
+ headless execution as unique now that `unity build/run/test` exist.
+3. Lead with the safety model: read-only mode, dry-run, and per-tool
+ destructive annotations, contrasted against a default-on
+ compile-and-execute-C# tool.
+4. Do not compare tool counts in either direction, and do not claim profiler
+ superiority in the abstract — claim agent-driven capture and console-fused
+ timelines.
+
+For the proxy spike (TASK-6.4):
+
+1. The relay is a separate process launched with `--mcp`, so proxying is a
+ process-composition problem, not an in-editor integration one.
+2. Wrapping must classify official tools by hand: the official surface carries
+ no read-only or destructive metadata to inherit.
+3. `Unity_RunCommand` is the hard case. It is enabled by default and can do
+ anything the editor can, so a wrapper either blocks it, or the toolkit's
+ read-only guarantee stops meaning anything for proxied sessions.
+4. Any Assistant or Pipeline proxy is Unity 6 only, so it must be additive and
+ must not weaken the 2019.4 path.
+5. Evaluate Pipeline composition separately from Assistant relay composition.
+ Prefer structured `unity` CLI JSON/NDJSON and documented exit codes over
+ scraping human output or reaching into the local HTTP descriptor directly.
+6. Treat `eval`/`eval_file` in Pipeline and `Unity_RunCommand` in Assistant as
+ equivalent policy escape hatches: block or isolate them when advertising a
+ read-only proxied session.
+
+## Reproducing this capture
+
+Official side:
+
+1. `curl https://packages.unity.com/com.unity.ai.assistant` and read
+ `dist-tags.latest`, then download and shasum-verify the tarball.
+2. Scaffold an empty project outside this repository pinning that exact
+ version and a Unity 6 editor.
+3. Add an editor script that serializes
+ `Unity.AI.MCP.Editor.ToolRegistry.McpToolRegistry.GetAllToolsForSettings()`.
+4. Run the editor with `-batchmode -nographics -executeMethod … -quit`.
+
+Toolkit side:
+
+1. `npm ci --no-audit --no-fund && npm run compile` in `unity-cursor-toolkit/`.
+2. Pipe `initialize`, `tools/list`, `resources/list`, `prompts/list` into
+ `node out/mcp/server.js`.
+3. Repeat the mutating call with `UNITY_CURSOR_TOOLKIT_MCP_READ_ONLY=1` to
+ confirm the refusal path.
+
+Full commands and environment details are in
+`.agent/runs/TASK-6.1/artifacts/official-mcp-eval-setup.txt`.
+
+CLI/Pipeline sources:
+
+- https://docs.unity.com/en-us/unity-cli/unity-cli-reference
+- https://docs.unity.com/en-us/unity-cli/release-notes
+- https://docs.unity.com/en-us/unity-production-pipeline/local-tools-cli/unity-pipeline-package
+- https://docs.unity3d.com/Packages/com.unity.pipeline@0.4/manual/index.html
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..7187b30
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,54 @@
+# Documentation
+
+This directory contains the current user guides, architecture notes, research
+snapshots, experiments, and implementation workstreams for Unity Cursor
+Toolkit.
+
+## Product Guides
+
+- [AI agent guide](AI_AGENTS.md)
+- [MCP client setup](MCP_CLIENTS.md)
+- [Runtime game commands](GAME_COMMANDS.md)
+- [Feature roadmap](FEATURE_ROADMAP.md)
+- [Remote Unity streaming](REMOTE_UNITY_STREAMING.md)
+
+## Unity 7 Readiness
+
+- [Unity 7 readiness plan](UNITY_7_READINESS.md) — canonical public status,
+ compatibility targets, gates, and execution order
+- [Unity 6.6 to Unity 7 landscape assessment](UNITY_7_LANDSCAPE_ASSESSMENT.md)
+ — dated research and product analysis
+- [Unity CLI and Pipeline assessment](UNITY_CLI_AND_PIPELINE_ASSESSMENT.md) —
+ dated first-party automation inventory and adoption plan
+- [Official Unity MCP overlap](OFFICIAL_MCP_OVERLAP.md) — dated capability
+ capture and positioning analysis
+- [Workstream task index](tasks/README.md) — WS1 through WS8 execution plans
+
+Unity 7 is a planned, evidence-gated target. The package currently declares
+Unity 2019.4 or later for its core features. The bundled Unity-Unterm features
+require Unity 6000.3 or later on macOS or Windows. Do not treat a roadmap item,
+assessment, or unchecked workstream task as proof of Unity 7 support.
+
+## Experiments and Operations
+
+- [Unity without Editor experiments](UNITY_WITHOUT_EDITOR_EXPERIMENTS.md)
+- [Editor window streaming plan](EDITOR_WINDOW_STREAMING_PLAN.md)
+- [Remote Unity streaming](REMOTE_UNITY_STREAMING.md)
+- `docs/prompts/` contains reproducible proof prompts.
+- Incident reports record past failures and their safeguards. They are not
+ current setup guides.
+
+## Status Language
+
+- **Shipped**: present in released code and covered by current validation.
+- **Declared**: named in package metadata or documentation; this is not proof.
+- **Validated**: supported by recorded evidence on the named Editor/platform.
+- **Planned**: designed but not implemented or proven.
+- **Pending** or **Unverified**: required evidence does not exist yet.
+- **Watch**: re-evaluate when a material Unity preview or release changes the
+ assumptions.
+- **Historical evidence**: a dated test or incident record that must not be
+ promoted to a current support claim.
+
+Every compatibility claim must name the Editor version and evidence. General
+phrases such as “Unity 7 ready” must not be used until the readiness gates pass.
diff --git a/docs/REMOTE_UNITY_STREAMING.md b/docs/REMOTE_UNITY_STREAMING.md
index 4ebff57..fb718f0 100644
--- a/docs/REMOTE_UNITY_STREAMING.md
+++ b/docs/REMOTE_UNITY_STREAMING.md
@@ -1,5 +1,10 @@
# Remote Unity Native Shell And Streaming
+Status: **experimental implementation and historical evidence**. Existing
+proofs use named Unity 6000.3.9f1 environments. Windows and Unity 7 validation
+remain pending. See the [Unity 7 readiness plan](UNITY_7_READINESS.md) and
+[WS7](tasks/WS7_REMOTE_SHELL.md).
+
## Goal
Build a VS Code Remote SSH-style experience for Unity: the local Mac keeps a native-feeling app shell, while Unity processing, project files, asset indexing, builds, tests, and rendering run on a remote workstation or VM. The local app should feel like opening a local Unity tool, but the heavy work happens over the network.
diff --git a/docs/UNITY_7_LANDSCAPE_ASSESSMENT.md b/docs/UNITY_7_LANDSCAPE_ASSESSMENT.md
new file mode 100644
index 0000000..50b1f7b
--- /dev/null
+++ b/docs/UNITY_7_LANDSCAPE_ASSESSMENT.md
@@ -0,0 +1,220 @@
+# Unity 6.6 -> Unity 7 Landscape Assessment
+
+Status: dated research snapshot and planning input. Written 2026-07-23 from
+the cited announcements, upgrade guide, official Unity MCP docs, and a repo
+audit. Updated 2026-08-07 for the standalone CLI and Pipeline documentation;
+documentation status reviewed 2026-08-13. Recheck external facts before an
+implementation or marketing decision. This assessment does not certify Unity 7
+support. Canonical readiness status: `UNITY_7_READINESS.md`. Companion docs:
+`UNITY_CLI_AND_PIPELINE_ASSESSMENT.md`, `OFFICIAL_MCP_OVERLAP.md`,
+`UNITY_WITHOUT_EDITOR_EXPERIMENTS.md`, `REMOTE_UNITY_STREAMING.md`,
+`EDITOR_WINDOW_STREAMING_PLAN.md`, `FEATURE_ROADMAP.md`.
+
+## 1. Dated landscape capture
+
+The items below describe what the cited sources said on the capture dates. They
+are not a current release calendar or compatibility matrix.
+
+- **Unity 6.5** shipped June 2026 (current Supported release).
+- **Unity 6.6+**: Fast Enter Play Mode becomes the default for new projects.
+- **CoreCLR transition preview**: a captured upgrade source described
+ experimental CoreCLR desktop-player work around the Unity 6.7 train. Recheck
+ the exact Editor channel and support policy before a proof run.
+- **Unity 6.8 target**: the captured roadmap described a CoreCLR-only scripting
+ runtime and mandatory Fast Enter Play Mode. The captured upgrade guide listed
+ these expected consequences:
+ - No full domain reload: statics survive play-mode transitions and recompiles.
+ - `AppDomain.CurrentDomain.DomainUnload` never fires; use `[AfterCodeReloadSerialization]` / `[BeforeCodeUnloading]` lifecycle attributes.
+ - `AppDomain.CurrentDomain.GetAssemblies()` deprecated -> `UnityEngine.Assemblies.CurrentAssemblies.GetLoadedAssemblies()`.
+ - Several `Assembly.Load` overloads (incl. `Assembly.Load(byte[])`) incompatible with code reload -> `CurrentAssemblies.LoadFromPath()`.
+ - `Assembly.Location` returns empty string -> `Assembly.GetLoadedAssemblyPath()` (UnityEngine.CoreModule, 6.8+).
+ - `UnityEditor.Scripting.ManagedDebugger` unsupported -> `System.Diagnostics.Debugger`.
+ - Statics management: `[AutoStaticsCleanup]` for automatic reset, or custom cleanup bound to lifecycle events.
+- **Unity 7 announcement snapshot**: the captured announcement gave an early
+ beta and release window and described these targets:
+ - Zero-rebuild upgrade path from Unity 6 (no rebuilding, no new language, nothing broken).
+ - Partial domain reload: only changed assemblies reload -> near-instant play mode.
+ - **Free official MCP** connecting coding agents to Unity.
+ - Continued expansion of CLI/public APIs for validation, builds, deployment,
+ and production-pipeline workflows.
+ - Surface Cache GI, AI-assisted graphics optimization, Unity Vector (ads AI).
+- **Official Unity MCP capture**: on 2026-08-02, the captured
+ `com.unity.ai.assistant` package exposed an MCP relay and the inventory in
+ `OFFICIAL_MCP_OVERLAP.md`.
+- **Standalone Unity CLI capture**: on 2026-08-07, the experimental CLI was
+ available independently of Unity 7. The
+ experimental `unity` binary is separate from Hub and the Editor, manages
+ multiple Editor versions, resolves projects through `ProjectVersion.txt`,
+ and exposes Editor/module/project management, local build/run/test,
+ licensing, diagnostics, connected-Editor commands, and MCP. Captured release:
+ `1.0.0-beta.3` from 2026-07-23.
+- **Unity Pipeline capture**: on 2026-08-07, documentation described
+ `com.unity.pipeline`
+ (`0.4.0-exp.1` in the captured docs). It requires Unity 6.0+ and provides an
+ authenticated loopback API plus a large command catalog for live Editors and
+ development Players. See `UNITY_CLI_AND_PIPELINE_ASSESSMENT.md` for the full
+ inventory, security model, WIA reference snapshot, and adoption plan.
+- **Hub CLI status at capture time**: the cited documentation deprecated it
+ from Hub 3.18.0 and directed new automation toward the standalone CLI. Unity
+ Build Automation remained a separate cloud service in that snapshot.
+
+## 2. Virtualized shell assessment and inferences
+
+- The current architecture still needs an Editor process to render Editor
+ windows. The dated CLI, Pipeline, and Assistant inventory did not include a
+ remote rendered-window and input shell. Recheck this comparison before
+ product positioning.
+- **Inference:** Editor architecture continuity may let the internal
+ `GUIView.GrabPixels` and `SendEvent` path survive into Unity 7. It remains an
+ internal API and needs an exact-version smoke test.
+- **Hypothesis:** a CoreCLR Editor can change startup and steady-state cost.
+ Re-run E2 on the selected transition Editor and use measurements, not an
+ assumed improvement.
+- Licensing and EULA conclusions are limited to the dated source review. The
+ W0/W3/W4 lanes and the never-safe list in
+ `UNITY_WITHOUT_EDITOR_EXPERIMENTS.md` remain the planning boundary.
+
+## 3. What is threatened
+
+1. **Mono debugger (port 56000): transition risk.** The current protocol is
+ Mono-specific. WS3 must recheck permitted CoreCLR debugger options and prove
+ attach behavior before a replacement is selected.
+2. **Hot reload / IL patching: transition risk.** The captured CoreCLR guide
+ identifies the current `Assembly.Load(byte[])` path as incompatible. WS1
+ must gate or replace the path on the exact selected Editor.
+3. **MCP basics: commoditized** by official Assistant and Pipeline surfaces.
+ Do not compete on tool count; compete on version span, remote/rendered
+ workflows, project-specific orchestration, structured context, and safety.
+ See `OFFICIAL_MCP_OVERLAP.md` and
+ `UNITY_CLI_AND_PIPELINE_ASSESSMENT.md`.
+
+### Repo audit findings (CoreCLR-breaking API sites, non-third-party)
+
+- `AppDomain.CurrentDomain.GetAssemblies()`: `Editor/MCP/EditorValidationTool.cs:608`, `Editor/MCP/EditorWindowViewportCapture.cs:312`, `Editor/MCP/MCPBridge.cs:44`, `Editor/HotReload/ILPatcher.cs:266,428,523`
+- `Assembly.Load(dllBytes)`: `Editor/HotReload/ILPatcher.cs:381`
+- Vendored Unterm hits: `UntermExecuteCodeTools.cs`, `UntermMcpServer.cs`, `UntermToolGroup.cs`, `UntermExternalCodeEditor.cs` (audit or upstream fixes to the vendor).
+- `AssemblyReloadEvents` usage (`HotReloadHandler.cs:114`, `ProfilerSnapshot.cs`, `EditorWindowViewportCapture.cs:27`) — verify semantics under partial reload; the event model changes even if the API survives.
+
+## 4. Current features, rated
+
+Scale: value today / viability through 6.8 -> Unity 7 / differentiation vs official Unity stack, each out of 10.
+
+| Feature | Today | 6.8/U7 | Diff. | Verdict |
+| --- | --- | --- | --- | --- |
+| Hot Reload (IL patching) | 8 | 3 | 4 | Sunset-by-version |
+| Live Console (+ profiler fusion) | 8 | 8 | 7 | Keep, invest |
+| Connection layer (TCP state machine) | 9 | 9 | n/a | Keep — it's the platform |
+| Status Bar / Play Mode Control | 7 | 7 | 5 | Maintain |
+| MCP Server | 9 | 6 | 5 -> 8 | Reposition (ops layer) |
+| Mono Debugger | 8 | 1 | 9 | Replace with CoreCLR attach |
+| Meta File Management | 6 | 6 | 6 | Maintain |
+| Unity C# package | 9 | 5 as-is | n/a | CoreCLR audit now |
+| Unterm (in-editor terminal) | 7 | 6 | 7 | Audit, keep |
+| Virtualized shell (W0/W3/W4) | 7 | 9 | 10 | Invest — flagship |
+
+Notes:
+
+- **Hot Reload**: strongest today, weakest tomorrow. Gate by version: full IL patching for 2019.4-6.5; on 6.8+ becomes a thin wrapper over Unity's native reload. This is the backwards-compat story (section 7).
+- **Live Console**: unaffected by announced changes; profiler-fused snapshots are not matched by the official MCP console tool. Safest asset.
+- **MCP Server**: tool count and common local headless build/run/test workflows
+ are commoditized. The remaining envelope is legacy-version support,
+ remote/project-specific orchestration, rendered streaming, no AI Assistant
+ dependency, explicit read-only/dry-run policy, `.umetacontext`, and a stable
+ interface across backends.
+- **Mono Debugger**: a current legacy-runtime differentiator and a
+ high-urgency transition risk. WS3 owns the replacement feasibility proof.
+- **Virtualized shell**: low "today" only because experimental/unshipped; highest strategic score of anything owned.
+
+## 5. New offers, rated
+
+Impact / effort / urgency out of 10 (urgency = cost of being late).
+
+| Offer | Impact | Effort | Urgency | Call |
+| --- | --- | --- | --- | --- |
+| CoreCLR compatibility audit + fixes | 7 | 2 | 9 | Do first |
+| CoreCLR debugger for Cursor (netcoredbg) | 9 | 6 | 8 | Do second |
+| MCP ops-layer reposition + official-MCP proxy | 8 | 4 | 7 | Do in parallel |
+| Integrate standalone CLI + Pipeline now; watch Unity 7 deltas | 8 | 5 | 8 | Active — APIs published |
+| Remote shell productization | 9 | 8 | 5 | Invest steadily |
+| Unterm CoreCLR audit | 5 | 2 | 6 | Fold into audit |
+
+First three = survival tier (each defends a feature that otherwise dies or commoditizes). Last three = growth tier.
+
+Official-surface composition detail: evaluate `com.unity.ai.assistant` relay and
+standalone CLI/Pipeline composition separately, then expose origin-qualified
+Assistant, Pipeline, and toolkit catalogs through one policy layer. The safety
+claim is valid only if arbitrary C# execution and every other mutating command
+cannot bypass read-only/dry-run enforcement.
+
+## 6. Additional new ideas
+
+1. **CoreCLR Migration Assistant** (impact 9, effort 4, urgency 9). Projects
+ that adopt the selected CoreCLR transition release need a repeatable scan.
+ Turn the local audit into an MCP tool and extension command only after its
+ rules are rechecked against current primary documentation.
+2. **Statics-bug detector for Fast Enter Play Mode** (impact 7, effort 3,
+ urgency 8). Snapshot static fields across play-mode transitions and report
+ what carried state. Recheck default reload behavior on each tested Editor.
+3. **Test orchestration bridge** (impact 6, effort 3). Start with a parity spike
+ against `unity test`, which already runs EditMode/PlayMode tests headlessly
+ with filters and NUnit output. Build only the missing value: legacy Editor
+ support, progress streaming, toolkit safety policy, richer structured
+ results, remote targeting, and one stable MCP schema across backends.
+4. **Editor fleet orchestration** (impact 7, effort 7, later). Post-remote-shell upsell: N hidden/remote editors leased by agents for parallel work; validation farms for the Unity 7 "asset validation without editor access" workflow. Pairs with Unity Licensing Server / build-server seats (see licensing table in `UNITY_WITHOUT_EDITOR_EXPERIMENTS.md`).
+
+## 7. The backwards-compatibility offer
+
+Headline product line, not a footnote. **Impact 8, effort 3, urgency 6** — mostly positioning + CI matrix on top of what exists.
+
+Target: **one agent interface from the declared Unity 2019.4 baseline through
+the exact future Editor matrix that passes the readiness gates.**
+
+Why it works:
+
+- Official live-Editor agent surfaces are split across the Assistant package
+ and Unity 6+ Pipeline package. The standalone CLI can manage multiple Editor
+ generations, but Pipeline live control does not cover legacy projects.
+- This toolkit already runs on 2019.4+, needs no Unity AI packages, and provides
+ one stable live-agent interface across legacy and current projects. That
+ cross-version continuity—not an unverified claim that no official CLI can
+ touch an older project—is the durable offer.
+- The intended version split becomes an evidence-backed feature matrix:
+ - Legacy Editors retain the Mono debugger and legacy hot-reload path where
+ the exact matrix passes.
+ - Eligible CoreCLR Editors select only capabilities proved by WS1 and WS3.
+ - The MCP, console, and connection interface stays stable while results name
+ the selected backend and Editor.
+- Compounds with the Migration Assistant: the install serving a 2021 LTS team today walks them across CoreCLR tomorrow. Capture before the transition, keep after — exactly the window where official tooling would otherwise absorb them.
+
+Concrete work: version-gated capability detection in the C# package, an
+exact-version Editor/platform matrix, and README plus Marketplace wording that
+matches recorded evidence.
+
+## 8. Priority order
+
+1. CoreCLR package audit + fixes
+2. CoreCLR Migration Assistant
+3. CoreCLR debugger for Cursor (netcoredbg)
+4. MCP ops-layer reposition + backwards-compat positioning
+5. Statics-bug detector (FEPM)
+6. Test runner bridge
+7. Remote shell productization (re-baseline E2 on CoreCLR; internal-API smoke tests per Unity version; validate player viewport service on 6.7 CoreCLR player)
+8. Standalone Unity CLI + Pipeline adoption now; Unity 7-specific delta watch
+ and editor fleet orchestration follow after the local integration is proven
+
+## 9. Sources
+
+- https://unity.com/news/unity-7-roadmap-revealed-at-unite-seoul
+- https://www.gamedeveloper.com/programming/unity-unveils-unity-7-roadmap-with-update-path-that-won-t-break-your-build
+- https://discussions.unity.com/t/path-to-coreclr-2026-upgrade-guide/1714279
+- https://discussions.unity.com/t/coreclr-scripting-and-serialization-update-june-2026/1723299
+- https://docs.unity3d.com/Packages/com.unity.ai.assistant@2.7/manual/integration/unity-mcp-overview.html
+- https://unity.com/blog/unity-ai-mcp-how-to-get-started
+- https://discussions.unity.com/t/unity-6-5-is-now-available/1723176
+- https://docs.unity3d.com/6000.7/Documentation/Manual/scripting-backends-coreclr.html
+- https://www.creativebloq.com/3d/video-game-design/unity-7s-most-surprising-advance-isnt-a-feature-upgrade
+- https://docs.unity.com/en-us/unity-cli
+- https://docs.unity.com/en-us/unity-cli/unity-cli-reference
+- https://docs.unity.com/en-us/unity-cli/release-notes
+- https://docs.unity.com/en-us/unity-production-pipeline/local-tools-cli/unity-pipeline-package
+- https://docs.unity3d.com/Packages/com.unity.pipeline@0.4/manual/index.html
diff --git a/docs/UNITY_7_READINESS.md b/docs/UNITY_7_READINESS.md
new file mode 100644
index 0000000..f159080
--- /dev/null
+++ b/docs/UNITY_7_READINESS.md
@@ -0,0 +1,101 @@
+# Unity 7 Readiness Plan
+
+Last reviewed: 2026-08-13
+
+Status: **planning and preparation**. Unity 7 compatibility is not yet a
+shipped or validated product claim.
+
+This document is the canonical summary for Unity 7 preparation. The detailed
+research remains in `UNITY_7_LANDSCAPE_ASSESSMENT.md`,
+`UNITY_CLI_AND_PIPELINE_ASSESSMENT.md`, and `OFFICIAL_MCP_OVERLAP.md`. The
+implementation checklists live under `docs/tasks/`.
+
+## Current Support Baseline
+
+| Area | Current status | Evidence boundary |
+| --- | --- | --- |
+| Core Unity package | Declares Unity 2019.4 or later | Package metadata; this is not a per-version validation claim |
+| VS Code/Cursor extension and standalone MCP server | Shipped | `npm run validate` and release CI |
+| Bundled Unity-Unterm tools | Declares Unity 6000.3 or later on macOS and Windows | Local sample baseline is Unity 6000.3.9f1 on macOS; Windows proof is pending |
+| Mono debugger and IL patch hot reload | Current legacy-runtime path | Must be gated before a CoreCLR-only Editor is claimed |
+| Unity 6.8/CoreCLR | Preparation planned | WS1 through WS3 are not complete |
+| Unity 7 | Target only | No compatibility claim until the gates below pass |
+
+The repository declares a broad current baseline, but it does not yet have a
+complete per-version certification matrix. “Declared,” “validated,” and
+“Unity 7 ready” are separate states.
+
+## Target Compatibility Model
+
+| Editor family | Intended toolkit path | Readiness state |
+| --- | --- | --- |
+| Unity 2019.4 through 2022 LTS | Existing toolkit bridge, Mono debugger, and legacy hot reload | Declared range; preserve and add exact-version matrix evidence |
+| Current Unity 6 releases | Existing bridge plus declared Unity-Unterm features | Unity 6000.3.9f1 macOS sample exists; expand exact-version and platform proof |
+| CoreCLR transition releases | Capability-gated reload, lifecycle, and debugger behavior | Planned in WS1 through WS3 |
+| Unity 7 previews and release | Same public agent interface with version-selected backends | Watch and validate; not yet claimed |
+
+The target is one stable agent interface across Editor generations. Backend
+selection must be explicit and capability-driven. The toolkit must not silently
+substitute another Editor version or backend after a failure.
+
+## Workstreams
+
+1. **WS1 — CoreCLR package audit.** Remove or gate incompatible assembly,
+ reload, static-state, and IL-patching paths. Add handshake capabilities.
+2. **WS2 — CoreCLR Migration Assistant.** Scan user projects for transition
+ risks and return documented replacements through the extension and MCP.
+3. **WS3 — CoreCLR debugger.** Prove a permitted CoreCLR attach path for
+ Cursor and other non-Microsoft clients while preserving Mono attach for
+ older Editors.
+4. **WS4 — Stable operations layer.** Keep public schemas compatible, expose
+ backend origin, and compose toolkit and first-party surfaces without
+ weakening read-only or dry-run policy.
+5. **WS5 — Static-state detector.** Detect state that survives Fast Enter Play
+ Mode and no-domain-reload transitions.
+6. **WS6 — Test Runner bridge.** Provide one test schema across legacy bridge,
+ standalone CLI, Pipeline, local, and remote execution paths.
+7. **WS7 — Remote shell.** Protect the rendered-window and input-control path
+ with per-version smoke tests and measured CoreCLR baselines.
+8. **WS8 — Unity CLI, Pipeline, and Unity 7 watch.** Adopt pinned first-party
+ backends where they are eligible and track only genuine Unity 7 deltas.
+
+See [the task index](tasks/README.md) for dependencies and detailed acceptance
+criteria.
+
+## Readiness Gates
+
+Unity 7 support can be advertised only after all applicable gates have recorded
+evidence for an exact preview or release build:
+
+- The package imports and compiles without unsupported API warnings.
+- Connection handshake, console streaming, profiler capture, copy snapshot,
+ play mode, screenshots, MCP discovery, and safe mutations pass.
+- Hot reload selects a supported path and never uses incompatible IL loading.
+- Debug attach selects Mono or CoreCLR from capabilities and passes breakpoint,
+ stepping, and locals checks.
+- Static state and reload lifecycle behavior have explicit cleanup tests.
+- EditMode and PlayMode tests return structured results through the selected
+ backend.
+- CLI/Pipeline use exact versions, pinned dependencies, typed failures, bounded
+ cancellation, and visible backend identity.
+- Read-only mode and `dryRun` cannot be bypassed through any composed backend.
+- The legacy 2019.4 and 2022 LTS smoke paths still pass.
+- The README, package docs, Marketplace copy, `llms.txt`, and capability matrix
+ match the recorded results.
+
+## Immediate Execution Order
+
+1. Start WS1 inventory and capability detection.
+2. Run the WS8 pinned CLI baseline and WS6 test parity spike in parallel.
+3. Use WS1 evidence to start WS2 and the WS3 debugger feasibility spike.
+4. Build the WS4 compatibility matrix and backend-origin model.
+5. Add WS5 and WS7 version-specific smoke coverage.
+6. Re-run the complete matrix for each material Unity 7 preview.
+
+## Research and Claim Policy
+
+The assessments contain dated external-product and roadmap snapshots. Recheck
+those sources before implementation or marketing decisions. If current evidence
+conflicts with an assessment, update the assessment and this summary together.
+An unchecked task is not a shipped feature, and a passing compile is not a full
+compatibility claim.
diff --git a/docs/UNITY_CLI_AND_PIPELINE_ASSESSMENT.md b/docs/UNITY_CLI_AND_PIPELINE_ASSESSMENT.md
new file mode 100644
index 0000000..6febca9
--- /dev/null
+++ b/docs/UNITY_CLI_AND_PIPELINE_ASSESSMENT.md
@@ -0,0 +1,490 @@
+# Unity CLI and Pipeline assessment
+
+Status: dated research snapshot and implementation input. Captured 2026-08-07
+against the cited CLI, Pipeline package, Editor command-line, Build Automation,
+UGS CLI, and Unity Version Control documentation; documentation status reviewed
+2026-08-13. Recheck versions and availability before installation or product
+claims. Canonical readiness status: `UNITY_7_READINESS.md`. This is the detailed source for the
+CLI-related decisions in `UNITY_7_LANDSCAPE_ASSESSMENT.md`,
+`OFFICIAL_MCP_OVERLAP.md`, and WS4/WS6/WS8.
+
+## Decision summary
+
+- Unity's new standalone `unity` CLI is available now. It is not a Unity 7-only
+ feature and WS8 is no longer blocked on a future beta publication event.
+- The CLI is an experimental, separately installed binary. The current release
+ captured here is `1.0.0-beta.3`, released 2026-07-23.
+- The CLI is not tied to one Editor. It installs, discovers, selects, opens,
+ runs, tests, and builds with multiple Editor versions. Project commands can
+ resolve the version declared in `ProjectSettings/ProjectVersion.txt`.
+- Live Editor and development-Player control is a separate layer provided by
+ `com.unity.pipeline`. The current package documentation resolves to
+ `0.4.0-exp.1` and requires Unity Editor 6.0 or later.
+- The traditional Editor command line remains useful and is version-specific:
+ the exact `Unity`/`Unity.exe` binary and matching versioned manual still own
+ `-batchmode`, `-executeMethod`, low-level import, graphics, profiler, and
+ licensing flags.
+- The legacy Hub CLI is deprecated beginning with Hub 3.18.0. New toolkit work
+ should target the standalone `unity` CLI, not add more Hub CLI integration.
+- `unity build` is a local Editor batch-mode build. Unity Build Automation is a
+ separate cloud service controlled through its Dashboard, Editor package, and
+ REST API.
+- The toolkit should become a safe, version-spanning orchestration layer over
+ explicit backends: its existing bridge for legacy Editors, Unity Pipeline for
+ Unity 6+, and local Editor batch execution where a headless job is required.
+ Backend selection must be capability-driven and visible, never a silent
+ compatibility fallback.
+- None of the planned CLI/Pipeline adapter work is a shipped backend until its
+ WS8 evidence and compatibility gates pass.
+
+## Command-line surface map
+
+| Surface | Invocation | Primary role | Version coupling and status |
+| --- | --- | --- | --- |
+| Standalone Unity CLI | `unity ...` | Editor/module/project management, local builds/tests, licensing, connected Editors, MCP, diagnostics | Independent experimental binary; captured at `1.0.0-beta.3`; manages multiple Editor versions |
+| Unity Pipeline package | `com.unity.pipeline`, driven by `unity command` | Authenticated local control of a running Editor or development Player | Requires Editor 6.0+; captured docs are `0.4.0-exp.1` |
+| Direct Unity Editor CLI | Exact `Unity`/`Unity.exe` plus Editor flags | Batch mode, custom static methods, builds, tests, imports, diagnostics | Strictly coupled to the launched Editor version and platform |
+| Unity Player arguments | Built application plus Player flags | Headless Player, display/GPU selection, logging, debugging | Coupled to the build's Editor version and target platform |
+| Legacy Hub CLI | Hub executable plus `-- --headless` | Legacy Editor/module installation | Deprecated from Hub 3.18.0 |
+| Unity Build Automation | Dashboard, Editor package, REST API | Cloud CI builds, scheduling, status/history, cancellation, artifacts | Separate service and support matrix; not the local `unity build` command |
+| UGS CLI | `ugs ...` | Deploy and manage Unity Gaming Services resources | Standalone and Editor-independent |
+| Unity Version Control CLI | `cm ...` | Repositories, workspaces, branches, merges, locks, reviews, administration | Standalone and Editor-independent |
+
+## Version-selection rules
+
+1. Treat `ProjectSettings/ProjectVersion.txt` as the default Editor authority
+ for an existing project.
+2. Use exact Editor versions for CI and durable automation. Aliases such as
+ `latest`, `lts`, `6`, or `6.5` are useful interactively but can move without
+ a project change.
+3. An installed build-support module belongs to one Editor installation. A
+ module installed for `6000.3.9f1` does not prove the same module exists for
+ `6000.5.2f1`.
+4. Opening a project with a newer Editor is an upgrade operation, not ordinary
+ launch behavior. The toolkit must not substitute a newer installed Editor
+ when the declared version is missing.
+5. `com.unity.pipeline` requires Unity 6.0+. Legacy projects continue through
+ the toolkit's existing bridge and direct version-matched Editor execution.
+6. Individual Pipeline commands can have narrower requirements. For example,
+ UI Toolkit element capture is documented as requiring `6000.7+` even though
+ the base package supports Unity 6.0+.
+7. For direct Editor flags, use the manual for the exact Editor stream. Stable
+ flag names exist across versions, but supported flags and behavior change.
+
+## Standalone `unity` CLI capabilities
+
+Unity says `unity --help` is authoritative for the installed beta. The web
+reference can trail newly shipped commands and flags.
+
+### Editors, modules, Hub, and releases
+
+- `install`: install a specific Editor version or an alias such as `lts`,
+ `latest`, a major stream, or the configured default; optionally install
+ modules and child components in the same operation.
+- `install-modules`: add one or more modules to an installed Editor.
+- `uninstall`: remove an installed Editor version.
+- `editors`: list releases, installed Editors, and running Editors; register a
+ manually installed Editor, inspect its path and metadata, set a default, and
+ upgrade an installed Editor within its supported stream.
+- `editor`: manage one Editor installation, including module removal.
+- `modules` and `releases`: inspect module catalogs and Unity release feeds.
+- `install-path`: read or change the Editor installation directory.
+- `hub`: install Unity Hub when its desktop UI is still required.
+- `cache`: inspect or clean downloaded Editor/module content.
+
+### Projects, templates, builds, execution, and tests
+
+- `open`: open a project in a compatible Editor. `unity ./Project` is shorthand
+ for `unity open ./Project`.
+- `projects`: list, create, clone, register, open, pin, size, close, link, and
+ unlink projects. Clone workflows cover GitHub, GitLab, and Unity Version
+ Control with branch, commit, or changeset selection.
+- `templates`: list, inspect, create, edit, delete, and relocate project
+ templates.
+- `build`: run a local project build in Editor batch mode with CI-oriented
+ output and exit behavior. The current surface includes Editor selection,
+ build target/output selection, Android signing, APK/AAB/Android Studio
+ export, version codes, symbols, target SDK settings, Git-derived versioning,
+ and dirty-worktree rejection unless explicitly allowed.
+- `run`: run a project in batch mode, stream logs, return the Editor exit code,
+ or launch a registered `[CliCommand]` headlessly with `--command`.
+- `test`: run Edit Mode and Play Mode tests, filter the selection, choose the
+ Editor version/path and architecture, write NUnit XML, enforce a timeout, and
+ return operation-failed exit code `6` when tests fail.
+
+### Accounts, licensing, and Unity Cloud identity
+
+- `auth`: browser-based sign-in, status, and sign-out.
+- `license`: list, inspect, activate, and return Personal, serial, floating, and
+ offline licenses; inspect floating-license servers.
+- `cloud`: inspect sign-in state and list/select Unity Cloud organizations and
+ projects.
+
+### Connected Editors and agents
+
+- `pipeline`: install, upgrade, list versions of, and inspect the Unity Pipeline
+ package in projects.
+- `status`: show connected Editor state including port, project path, Editor
+ version, and process id.
+- `list`: query a connected Editor for every registered command, description,
+ group, and parameter schema.
+- `command` / `cmd`: list or execute commands on a selected connected Editor or
+ development Player.
+- `mcp`: start a stdio MCP server that exposes connected Editor commands as MCP
+ tools; assisted configuration exists for supported agent clients.
+
+### Automation and diagnostics
+
+- Human, TSV, JSON, and streaming NDJSON output. Piped output defaults to TSV;
+ automation should select a format explicitly.
+- Differentiated exit codes: success, general failure, usage error,
+ authentication/authorization failure, missing configuration, operation
+ failure, Ctrl+C, and SIGTERM.
+- Non-interactive execution, quiet/no-banner output, confirmations, project and
+ organization defaults, proxy configuration, watch modes, and environment
+ variable equivalents.
+- `shell`: a warm interactive process with history, completion, project/org
+ session context, and an NDJSON request/response protocol for agents.
+- `completion`: shell completion for bash, zsh, fish, and PowerShell.
+- `doctor`, `diagnose`, `logs`, and `env`: environment health, proxy diagnostics,
+ log reading/tailing, and resolved path/version inspection.
+- `config`, `analytics`, `bug`, `language`, and `changelog`: settings, consent,
+ bug reporting, localization, and release information.
+- `upgrade`, rollback support where available, and `self-uninstall` for CLI
+ lifecycle management.
+- External command discovery through executables named `unity-`.
+
+## Unity Pipeline capabilities
+
+`com.unity.pipeline` runs an authenticated local HTTP API in a Unity Editor or
+development Player. The CLI discovers an instance and turns registered
+commands into terminal and MCP tools.
+
+### Assets and files
+
+- Create ScriptableObject/Object assets.
+- Import external files.
+- Move, copy, rename, delete, and find assets.
+- Read or change importer settings and reimport.
+- Create folders and read/write project text files.
+
+### Scenes, GameObjects, components, and prefabs
+
+- Create, open, save, list, and activate scenes.
+- Inspect scene hierarchy and update scenes in Build Settings.
+- Create, batch-create, find, transform, parent, activate, tag, layer, rename,
+ and delete GameObjects.
+- Add, remove, inspect, and modify serialized component properties.
+- Create and instantiate prefabs, create variants, apply/revert overrides,
+ unpack instances, and edit prefab contents.
+
+### Scripts, animation, materials, and shaders
+
+- Create and attach C# scripts; inspect and set serialized fields.
+- Create AnimationClips and curves.
+- Create and inspect Animator Controllers, parameters, layers, states, and
+ transitions.
+- Create Timelines, tracks, and clips.
+- Inspect and change material shaders, properties, and keywords.
+- List shaders and introspect shader properties.
+
+### Baking, search, selection, and capture
+
+- Start, poll, cancel, configure, and clear lighting bakes.
+- Start, poll, cancel, configure, and clear NavMesh and occlusion bakes.
+- Bake AI Navigation `NavMeshSurface` components.
+- Read or set Editor selection and run Unity Search queries.
+- Capture Game view, Scene view, and supported UI Toolkit elements.
+
+### Compilation, builds, and tests
+
+- Start a Player build and poll its structured build report.
+- Switch build target, poll the switch, and list available targets.
+- Read/write build settings and list Unity 6 Build Profile assets.
+- Force script recompilation and poll completion.
+- List tests, run filtered tests, poll results, and cancel a run.
+
+### Project settings and packages
+
+- Read and change Audio, Graphics, legacy Input, Physics, Player, Quality,
+ Tags/Layers, and Time settings.
+- List and search UPM packages.
+- Add, remove, resolve, and poll package operations.
+
+### Editor and development-Player lifecycle
+
+- Enter, pause, and exit Play Mode; inspect and focus the Editor.
+- Execute or list Editor menu items.
+- Capture screenshots and read/clear console logs.
+- Read render, memory, and frame performance statistics.
+- Set and inspect the authoring-root sandbox.
+- Connect to a development Player to inspect status, quit, set target frame
+ rate/time scale, simulate Input System key/pointer events, write/read logs,
+ evaluate C#, and apply hot-reload files.
+- Add project-specific typed commands with `[CliCommand]` and `[CliArg]`.
+
+## Pipeline transport and safety
+
+- Editor and Player servers bind to IPv4 loopback (`127.0.0.1`) and localhost,
+ never a routable interface.
+- Editor production ports are `7800`-`7849`; development Player production
+ ports are `7900`-`7949`.
+- Every request requires a startup-generated bearer token. The descriptor file
+ containing discovery state and the token is user-restricted under the
+ project's ignored `Library/Pipeline/` path.
+- Requests with an `Origin` header are rejected to prevent browser-origin
+ access to the local service.
+- Mutating authoring commands use `confirm`/`dry_run`, Undo grouping, and an
+ authoring-root path sandbox where applicable.
+- This remains a privileged interface. C# evaluation, package mutation, asset
+ deletion, project-setting changes, and build execution can perform broad
+ mutations. The toolkit's read-only mode, destructive metadata, audit trail,
+ and explicit confirmation model remain differentiators worth applying when
+ proxying or wrapping Pipeline commands.
+
+## Traditional Editor CLI capabilities that remain relevant
+
+- Create or open projects and clone from templates.
+- Run `-batchmode`, `-nographics`, and controlled quit behavior.
+- Execute project-defined static Editor methods with `-executeMethod`.
+- Select build targets/profiles or call custom `BuildPipeline` code.
+- Run Edit Mode, Play Mode, and Player tests with filters and NUnit output.
+- Enable code coverage.
+- Import/export `.unitypackage` files and configure Package Manager behavior.
+- Verify deterministic asset importing and control asset import overrides.
+- Configure Unity Accelerator/Cache Server behavior.
+- Control logs, stack traces, job-worker counts, API updating, and VCS session
+ settings.
+- Select graphics APIs/GPUs and configure debugging, shader validation, Metal,
+ and Profiler behavior.
+- Activate, return, or manually install licenses.
+- Perform recovery operations such as a full Library rebuild.
+
+The toolkit should retain direct Editor CLI support for legacy versions and for
+project-specific `-executeMethod` entry points that have not been registered as
+Pipeline `[CliCommand]` commands.
+
+## Other first-party automation surfaces
+
+### Build Automation
+
+Unity Build Automation is cloud CI, not an alternate spelling of `unity build`.
+Its REST API can trigger a configured build, inspect attempt status and build
+history, cancel attempts, and retrieve related results. Automatic builds can
+also run from repository changes or schedules. The Unity 6 Build Automation
+Editor package integrates cloud targets with Build Profiles.
+
+### UGS CLI
+
+The separate `ugs` CLI manages environments and service configuration for
+Access, CCD, Cloud Code, Cloud Save, Economy, Game Server Hosting, Leaderboards,
+Lobby, Matchmaker, Player Authentication, Remote Config, Scheduler, Schema
+Registry, and Triggers. It is a service-deployment surface, not Editor control.
+
+### Unity Version Control CLI
+
+The separate `cm` CLI owns repository/workspace creation, add/checkin/checkout,
+branch/merge/diff, labels, shelvesets, locks, reviews, replication, users/ACLs,
+triggers, history, queries, archives, and administration.
+
+## Toolkit product implications
+
+### What is newly commoditized
+
+- Multi-version Editor installation, discovery, module management, project
+ opening, local batch builds, tests, licensing, and diagnostics now have a
+ first-party terminal surface.
+- On Unity 6+, Pipeline now covers broad asset/scene/object/prefab/script/
+ animation/material/baking/project-setting/package/build/test operations.
+- Unity now provides its own stdio MCP adapter over Pipeline commands, separate
+ from the AI Assistant MCP assessed in `OFFICIAL_MCP_OVERLAP.md`.
+
+### What the toolkit should keep leading with
+
+- One stable interface across Unity 2019.4 through current Unity 6/7 streams.
+- Explicit safety policy: read-only mode, dry-run, destructive annotations,
+ auditability, and controlled proxy exposure.
+- Remote and headless deployment, viewport streaming, and virtualized shell.
+- Structured `.umetacontext`, project resources, profiler-capture lifecycle,
+ console-fused timelines, and version-aware workflows.
+- Composition: unify the standalone Unity CLI, Pipeline, AI Assistant MCP,
+ legacy toolkit bridge, remote hosts, and CI into one capability-advertised
+ agent interface.
+
+### Proposed integration architecture
+
+1. Add a TypeScript `UnityCliAdapter` that invokes `unity` without a shell,
+ passes argument arrays, consumes explicit JSON/NDJSON, captures stderr, and
+ maps documented exit codes to typed results.
+2. Resolve projects and Editors through project metadata and CLI discovery.
+ Do not embed OS-specific Unity installation paths in durable code.
+3. Add a `UnityPipelineAdapter` that discovers connected Editors by project,
+ lists schemas, invokes commands, and refuses commands not admitted by the
+ toolkit policy layer.
+4. Keep the legacy TCP bridge as an explicit backend for pre-Unity-6 projects
+ and unique toolkit operations. Report the selected backend in status and
+ every operation result.
+5. Compose MCP tool catalogs with origin metadata (`toolkit`, `pipeline`,
+ `assistant`) and stable aliases. Never expose duplicate unqualified names or
+ weaken existing public toolkit schemas.
+6. Convert project-specific automation to shared non-exiting services, then
+ expose thin wrappers for both traditional `-executeMethod` and Pipeline
+ `[CliCommand]`. A command that calls `EditorApplication.Exit` is unsuitable
+ for invocation in a user-facing connected Editor.
+7. Preserve local builds/tests as local operations. Add cloud Build Automation
+ only through an explicit separate adapter and typed API contract.
+
+## Setup and adoption plan
+
+### Phase 0: install and baseline the standalone CLI
+
+No Unity project mutation is required for this phase.
+
+```bash
+brew install --cask unity-cli
+
+unity --version
+unity doctor
+unity editors -i --format json
+unity auth status
+unity env --format json
+```
+
+- Record the exact CLI version and installation method.
+- For CI, pin or freeze the verified CLI release rather than following the
+ beta channel implicitly.
+- Treat `unity --help` and each subcommand's `--help` as the installed-version
+ contract.
+- Test CLI output and exit-code parsing before adding a toolkit adapter.
+
+### Phase 1: prove Editor selection and local jobs
+
+```bash
+unity open ./PathToProject
+unity test --help
+unity build --help
+unity run --help
+```
+
+- Confirm `open` selects the version from `ProjectVersion.txt`.
+- Confirm missing exact Editors/modules fail closed in non-interactive mode.
+- Run one filtered Edit Mode test with an NUnit output path.
+- Run one non-signing development build on an installed target module.
+- Capture human, JSON, and NDJSON behavior plus all exit codes encountered.
+
+### Phase 2: isolated Pipeline package spike
+
+The Pipeline install mutates a project's package manifest and lockfile. Perform
+it in an explicit spike project or reviewed branch, pin the package version,
+and verify its registry publication timestamp satisfies the repository's
+seven-day package age gate before installation.
+
+```bash
+unity auth login
+unity pipeline list-versions
+unity pipeline install --package-version 0.4.0-exp.1
+unity pipeline list
+unity status
+unity list
+unity command editor_status
+```
+
+- Review package-manifest and lockfile changes.
+- Verify recompilation and domain-reload behavior.
+- Exercise read-only discovery, console, test-listing, and build-target listing.
+- Exercise one mutation with `dry_run` before confirmation and prove Undo.
+- Start `unity mcp`, list tools from an MCP client, and prove project targeting
+ when multiple Editors are open.
+- Verify the server remains loopback-only and token-authenticated.
+
+### Phase 3: toolkit integration
+
+- Implement the CLI adapter and typed exit-code model.
+- Add CLI presence/version/status to the toolkit doctor/status surface.
+- Reuse `unity test` for the Unity 6+ local/batch path after parity proof; keep
+ the existing bridge path for legacy Editors and toolkit-specific streaming.
+- Reuse `unity build` where its surface covers the requested build; retain
+ project-defined build services for custom Addressables/data/codegen flows.
+- Add Pipeline catalog discovery and policy classification.
+- Decide whether `unity mcp` is composed as a child process or Pipeline commands
+ are invoked directly through the CLI adapter. Record the security tradeoff.
+- Add compatibility tests across one legacy Editor, 2022 LTS, the current Unity
+ 6 project version, and the next Unity 6/7 preview stream.
+
+### Phase 4: product and CI rollout
+
+- Publish a backend/capability matrix rather than a feature-count comparison.
+- Add structured diagnostics that state CLI version, project Editor version,
+ installed target modules, Pipeline version, connected instance, and selected
+ backend without exposing tokens or credentials.
+- Add clean-checkout tests for CLI absence, wrong version, missing Editor,
+ missing target module, authentication failure, Pipeline absence, multiple
+ running Editors, test failure, build failure, interruption, and timeout.
+- Keep official CLI/Pipeline support additive until the compatibility matrix
+ proves it can replace a specific toolkit path.
+
+## WIA Prime Forces reference snapshot
+
+This is dated integration evidence, not a toolkit invariant.
+
+Observed on 2026-08-07:
+
+- WIA declares Unity `6000.3.9f1` with revision `7a9955a4f2fa`.
+- Editors `6000.3.9f1` and `6000.5.2f1` are installed on the inspected Mac.
+- The WIA Editor installation has Android, iOS, and Windows playback/build
+ support directories. The separate `6000.5.2f1` installation has a different
+ module set, proving modules must be checked per exact Editor.
+- The standalone `unity` CLI is not on `PATH`.
+- `com.unity.pipeline` is not present in WIA's package manifest or lockfile.
+- WIA already has custom batch entry points for compile validation, Android/iOS
+ builds, variants, build profiles, signing inputs, game-data validation/export,
+ Addressables, and Odin IL2CPP AOT work.
+- WIA's current test runner defaults to a hardcoded macOS Editor path and can
+ generate missing SpacetimeDB bindings from sibling or freshly cloned source.
+ That runner must be made machine-agnostic and artifact-driven before it is a
+ canonical example: resolve the declared Editor through the CLI/configuration
+ and fail closed when the required generated-binding artifact is missing.
+
+Recommended WIA proof order:
+
+1. Install and baseline the standalone CLI without changing the project.
+2. Prove exact `6000.3.9f1` selection and module discovery.
+3. Prove a filtered Edit Mode test and compile-validation job.
+4. Repair the existing test wrapper's Editor resolution and binding bootstrap.
+5. Add pinned Pipeline in a reviewed spike branch and expose non-exiting WIA
+ commands over shared build services.
+6. Connect `unity mcp` to an agent client only after the tool catalog and
+ mutation policy have been reviewed.
+
+## Workstream corrections
+
+- WS4 must compare and compose three official surfaces, not only AI Assistant
+ MCP: AI Assistant MCP, standalone Unity CLI MCP, and Pipeline commands.
+- WS6 should start with a parity spike against `unity test`. Do not build a
+ second Unity 6 test launcher until the required legacy, streaming, filtering,
+ or safety gaps are measured.
+- WS8 changes from "wait for Unity 7" to active CLI/Pipeline adoption. The
+ remaining watch item is the Unity 7-specific delta, not CLI availability.
+- WS7 remains differentiated: Pipeline provides semantic control and still
+ does not replace a remote rendered Editor-window shell.
+
+## Sources
+
+- Unity CLI overview: https://docs.unity.com/en-us/unity-cli
+- Unity CLI use/install guide: https://docs.unity.com/en-us/unity-cli/use-unity-cli
+- Unity CLI reference: https://docs.unity.com/en-us/unity-cli/unity-cli-reference
+- Unity CLI release notes: https://docs.unity.com/en-us/unity-cli/release-notes
+- Hub CLI overview and deprecation: https://docs.unity.com/en-us/hub/cli-overview
+- Hub CLI reference: https://docs.unity.com/en-us/hub/hub-cli-reference
+- Unity Pipeline setup: https://docs.unity.com/en-us/unity-production-pipeline/local-tools-cli/unity-pipeline-package
+- Unity Pipeline command index: https://docs.unity3d.com/Packages/com.unity.pipeline@0.4/manual/index.html
+- Unity Pipeline connectivity: https://docs.unity3d.com/Packages/com.unity.pipeline@0.4/manual/connectivity.html
+- Unity Pipeline mutation safety: https://docs.unity3d.com/Packages/com.unity.pipeline@0.4/manual/safety-and-mutations.html
+- Unity 6.3 Editor CLI: https://docs.unity3d.com/6000.3/Documentation/Manual/EditorCommandLineArguments.html
+- Unity 6.3 Test Framework CLI: https://docs.unity3d.com/6000.3/Documentation/Manual/test-framework/reference-command-line.html
+- Unity 6.3 Player CLI: https://docs.unity3d.com/6000.3/Documentation/Manual/PlayerCommandLineArguments.html
+- Unity Build Automation: https://docs.unity.com/en-us/build-automation
+- Build Automation API: https://docs.unity.com/en-us/build-automation/build-automation-api
+- Build Automation API-triggered jobs: https://docs.unity.com/en-us/build-automation/run-builds/run-builds-automatically
+- UGS CLI: https://docs.unity.com/en-us/services/ugs-cli-introduction
+- Unity Version Control CLI: https://docs.unity.com/en-us/unity-version-control/uvcs-cli/version-control-cli
diff --git a/docs/UNITY_WITHOUT_EDITOR_EXPERIMENTS.md b/docs/UNITY_WITHOUT_EDITOR_EXPERIMENTS.md
index 08ec8df..78ebd1f 100644
--- a/docs/UNITY_WITHOUT_EDITOR_EXPERIMENTS.md
+++ b/docs/UNITY_WITHOUT_EDITOR_EXPERIMENTS.md
@@ -1,5 +1,10 @@
# Unity Without The Editor: DLL Mounting, Facade Bindings, License Passthrough, And No-Editor Rendering
+Status: **historical experiment record**. Keep measured results tied to their
+recorded Editor, platform, and date. Re-run the applicable gates before a
+CoreCLR or Unity 7 claim. Current status is in the
+[Unity 7 readiness plan](UNITY_7_READINESS.md).
+
Question this doc answers: can we trigger Scene View / editor rendering **without running the Unity editor process at all** -- for example by mounting Unity's DLLs into our own host process -- and can we do it with our own license entitlements so every action stays licensed?
Companion: `docs/EDITOR_WINDOW_STREAMING_PLAN.md` (streaming the real editor, hidden). Agent handoff prompt: `docs/prompts/unity-without-editor-agent-prompt.md`. Experiment scaffold: `experiments/editor-dll-mount-probe/`.
@@ -90,7 +95,13 @@ Caveat: this table is engineering's reading of the ToS, not legal advice. Before
4. E5 picks the licensing model for remote: per-VM serial vs floating server (pools >2 VMs => floating server).
5. E4/E6 only graduate if a concrete UX need appears (native shell embedding, instant attach).
-## 6. Current status
+## 6. Recorded Status
+
+Last reviewed: 2026-08-13. The proof entries below are historical evidence,
+not a current cross-platform or Unity 7 compatibility statement. Distribution
+artifact `0.6.1052828` appears in the archived installed-Cursor proofs; the
+source package uses its own base version and release CI can assign a different
+distribution version.
- [x] Research + lanes ranked (this doc)
- [x] E1 scaffold committed: `experiments/editor-dll-mount-probe/`
@@ -122,7 +133,7 @@ This section tracks the handoff prompt as an acceptance checklist, not just as a
| E4: UaaL/native-shell probe | Fulfilled as macOS desk check; Windows hands-on deferred | The feasibility note below records Windows `UnityPlayer.dll` / `-parentHWND` as a future GO path when a Windows host exists, and macOS native embedding as NO-GO; streaming remains the macOS answer. |
| E5: license automation | Fulfilled for dry-run/local CLI wrapper | `unity-cursor-toolkit/scripts/unity-license.js` provides dry-run-first `activate`, `return`, and `status` commands, masks `UNITY_EMAIL`, `UNITY_PASSWORD`, and `UNITY_SERIAL`, and requires `--execute` before running Unity. Production VM pool rollout still needs the chosen org licensing backend. |
| E6: instant attach | Skipped per spec | E3 is green on macOS and warm editor attach is already sub-second against a running bridge. Reopen only if cold instant-attach becomes a product requirement. |
-| Repeatable fulfillment audit | Partial by design | `npm --prefix unity-cursor-toolkit run audit:unity-without-editor` checks legal guardrails, E1/E2/E3/E5 artifacts, Cursor command wiring, isolated installed-Cursor smoke, installed-Cursor live editor UI proof, automated installed-Cursor editor frame proof, Unity capture implementation, player perf, the Windows proof runner, and the remaining Windows gate. If `experiments/windows-unity-without-editor/results/**/windows-proof-summary.json` exists from an executed Windows run, the audit validates the summary, Windows preflight artifact, E1 verdict, E2 capture/input result, E2 measure JSON, installed-Cursor Scene/Game frame-hash proof JSON, E3 probe transcript, and E3 `1280x720@30` perf JSON before passing `windows-proof`; dry-runs stay pending. Latest result: `experiments/unity-without-editor-audit/results/2026-06-10-current.json` -> 12 pass, 1 pending, 0 fail. |
+| Repeatable fulfillment audit | Partial by design | `npm --prefix unity-cursor-toolkit run audit:unity-without-editor` checks legal guardrails, E1/E2/E3/E5 artifacts, Cursor command wiring, isolated installed-Cursor smoke, installed-Cursor live editor UI proof, automated installed-Cursor editor frame proof, Unity capture implementation, player perf, the Windows proof runner, and the remaining Windows gate. If `experiments/windows-unity-without-editor/results/**/windows-proof-summary.json` exists from an executed Windows run, the audit validates the summary and required artifacts before passing `windows-proof`; dry-runs stay pending. Archived 2026-06-10 result: `experiments/unity-without-editor-audit/results/2026-06-10-current.json` -> 12 pass, 1 pending, 0 fail. |
| Final recommendation section | Preliminary recommendation written | Local default is L0 hidden editor; deployed/license-less lane is L2 player service; remote real-editor hosts need their own licensed editor seats. Final sign-off is blocked only by the executed Windows proof; cold/soak/E7 are opt-in follow-ups. |
### E1 results -- Unity 6000.3.9f1 / macOS
diff --git a/docs/prompts/unity-without-editor-agent-prompt.md b/docs/prompts/unity-without-editor-agent-prompt.md
index d74d22d..d232282 100644
--- a/docs/prompts/unity-without-editor-agent-prompt.md
+++ b/docs/prompts/unity-without-editor-agent-prompt.md
@@ -1,6 +1,10 @@
# Agent Prompt: "Unity Without The Editor" Experiment Series
-Copy everything below into a fresh AI coding agent session opened at the repo root (`unity-cursor-toolkit/`, branch `feat/simplified-context-engine` or its successor).
+Status: reusable experiment prompt with historical evidence. Last reviewed:
+2026-08-13. Recheck exact versions and current results before execution.
+
+Copy everything below into a fresh AI coding agent session opened at the
+repository root on the active approved work branch.
---
@@ -46,7 +50,10 @@ Current working state (verified):
- A spike harness for real-EditorWindow capture exists: `CursorUnityTool/Assets/Editor/UCTEditorWindowCaptureSpike.cs` + `unity-cursor-toolkit/scripts/run-editor-window-capture-spike.js` (`npm run spike:editor-windows`). Reuse its conventions (result JSON to the OS temp directory, Node runner polls, `resolveUnityPath()` from `ProjectSettings/ProjectVersion.txt`, env override `UNITY_CURSOR_TOOLKIT_UNITY_PATH`).
- Bundled Unity project: `CursorUnityTool/` (Unity 6000.3.9f1, URP, has `SampleScene` with Main Camera, Directional Light, Global Volume, Cube; Input System package installed).
- E1 macOS result is archived under `experiments/editor-dll-mount-probe/results/`; it confirms pure-managed Unity code can run outside the editor but editor/engine icalls fail. Windows E1 remains pending.
-- Extension validation: `npm run validate` from `unity-cursor-toolkit/` currently passes with 169 runtime tests, 9 simplified-context tests, 9 remote-shell tests, compile/unused checks, and npm audit. Keep it green.
+- Extension validation on 2026-08-13 passed 205 runtime tests, 10
+ simplified-context tests, 10 remote-shell tests, compile and unused checks,
+ vendored Unity-Unterm validation, and npm audit with zero findings. Re-run it
+ in the executing branch.
Environment: macOS (Apple Silicon) and Windows editor hosts are both in scope. Default Unity Hub paths: `/Applications/Unity/Hub/Editor//Unity.app/Contents/MacOS/Unity` on macOS and `C:\Program Files\Unity\Hub\Editor\\Editor\Unity.exe` on Windows. `dotnet` 8 SDK may need installing. The Unity editor must be CLOSED for runners that launch the bundled project (they check `CursorUnityTool/Temp/UnityLockfile`).
diff --git a/docs/tasks/README.md b/docs/tasks/README.md
new file mode 100644
index 0000000..4a55d6d
--- /dev/null
+++ b/docs/tasks/README.md
@@ -0,0 +1,34 @@
+# Workstream Task Index (Unity 6.6 to Unity 7)
+
+Last reviewed: 2026-08-13
+
+These are committed implementation plans. An unchecked task is not a shipped
+feature or support claim. Canonical public status and compatibility gates:
+`docs/UNITY_7_READINESS.md`. Source assessments:
+`docs/UNITY_7_LANDSCAPE_ASSESSMENT.md` and
+`docs/UNITY_CLI_AND_PIPELINE_ASSESSMENT.md` (updated 2026-08-07). Each
+workstream doc breaks the offer into small tasks sized for a single focused
+session; tasks are ordered so each leaves the repo shippable.
+
+| # | Workstream | Doc | Impact/Effort/Urgency | Status |
+| --- | --- | --- | --- | --- |
+| WS1 | CoreCLR package audit + fixes | `WS1_CORECLR_AUDIT.md` | 7/2/9 | Ready to start (P0) |
+| WS2 | CoreCLR Migration Assistant | `WS2_MIGRATION_ASSISTANT.md` | 9/4/9 | Planned; blocked by WS1 |
+| WS3 | CoreCLR debugger for Cursor | `WS3_CORECLR_DEBUGGER.md` | 9/6/8 | Feasibility spike pending |
+| WS4 | MCP ops-layer reposition + backwards compat | `WS4_MCP_REPOSITION_BACKCOMPAT.md` | 8/4/7 | Planning active; evidence pending |
+| WS5 | Statics-bug detector (Fast Enter Play Mode) | `WS5_STATICS_DETECTOR.md` | 7/3/8 | Planned; blocked by WS1 |
+| WS6 | Test runner bridge | `WS6_TEST_RUNNER_BRIDGE.md` | 6/4/5 | CLI parity spike ready |
+| WS7 | Remote shell productization | `WS7_REMOTE_SHELL.md` | 9/8/5 | Experimental background work |
+| WS8 | Standalone Unity CLI + Pipeline adoption; Unity 7 delta watch | `WS8_UNITY7_WATCH.md` | 8/5/8 | Baseline ready; adapter not shipped |
+
+Recommended execution order: WS1 -> WS2 -> WS3, with WS4 and the WS8
+baseline/parity spikes in parallel; then WS5 and the WS6 gap implementation;
+WS7 continues as steady background work. Unity 7-specific WS8 delta checks stay
+event-driven, but standalone CLI/Pipeline adoption is active now.
+
+Cross-cutting dependencies: WS1 task 2 (version/capability detection) is used by
+WS2, WS3, WS4, WS5, and WS8 backend selection. WS8's `UnityCliAdapter` and
+Pipeline capability capture inform WS4 composition and WS6 test execution.
+
+When a task starts, attach exact Editor/package/CLI versions and evidence paths.
+Update this index and `docs/UNITY_7_READINESS.md` when a status changes.
diff --git a/docs/tasks/WS1_CORECLR_AUDIT.md b/docs/tasks/WS1_CORECLR_AUDIT.md
new file mode 100644
index 0000000..712201e
--- /dev/null
+++ b/docs/tasks/WS1_CORECLR_AUDIT.md
@@ -0,0 +1,36 @@
+# WS1 — CoreCLR Package Audit + Fixes
+
+Status: **Ready to start (P0)**
+
+Last reviewed: 2026-08-13
+
+Support impact: preparation only; CoreCLR and Unity 7 are not yet validated.
+
+Goal: the Unity package (and vendored Unterm) runs clean on Unity 6.8 CoreCLR, day one. Highest urgency, lowest effort.
+
+Known breaking sites (from 2026-07 grep audit):
+
+- `AppDomain.CurrentDomain.GetAssemblies()` — `Editor/MCP/EditorValidationTool.cs:608`, `Editor/MCP/EditorWindowViewportCapture.cs:312`, `Editor/MCP/MCPBridge.cs:44`, `Editor/HotReload/ILPatcher.cs:266,428,523`
+- `Assembly.Load(byte[])` — `Editor/HotReload/ILPatcher.cs:381`
+- `AssemblyReloadEvents` semantics under partial reload — `Editor/HotReloadHandler.cs:114`, `Editor/ProfilerSnapshot.cs:159-160,402`, `Editor/MCP/EditorWindowViewportCapture.cs:27`
+- Vendored Unterm — `UntermExecuteCodeTools.cs`, `UntermMcpServer.cs`, `UntermToolGroup.cs`, `UntermExternalCodeEditor.cs`
+
+Both package copies must stay in sync: `Packages/com.rankupgames.unity-cursor-toolkit` and `CursorUnityTool/Packages/com.rankupgames.unity-cursor-toolkit`.
+
+## Tasks
+
+- [ ] 1. **Re-run and freeze the inventory.** Grep the full breaking-API list (`DomainUnload`, `AppDomain.`, `Assembly.Load`, `Assembly.Location`, `ManagedDebugger`, `AssemblyReloadEvents`) across both package copies incl. ThirdParty; save the site list to `experiments/coreclr-package-audit/results/inventory.md`. (Half day; also seeds the WS2 rule set.)
+- [ ] 2. **Add version/capability gate.** Version define (`UNITY_6000_8_OR_NEWER` via `versionDefines` in the asmdef) plus a small `RuntimeCapabilities` helper (isCoreCLR, hasDomainReload). Expose through the connection handshake so the extension side can gate features too. (Half day. Unblocks WS2/WS3/WS4/WS5.)
+- [ ] 3. **Assembly enumeration wrapper.** One helper (`AssemblyEnumerator.GetLoaded()`) that uses `UnityEngine.Assemblies.CurrentAssemblies.GetLoadedAssemblies()` on 6.8+ and `AppDomain` otherwise; replace the 6 first-party call sites. (Half day.)
+- [ ] 4. **Gate the IL patcher.** On CoreCLR, disable `Assembly.Load(byte[])` patching path with a clear capability error ("native reload active; IL patching not required on 6.8+") — fail loud, not silent. Extension status bar reflects the mode. (Half day.)
+- [ ] 5. **Reload-lifecycle audit.** Verify what `AssemblyReloadEvents` fires under 6.8 partial reload; migrate `HotReloadHandler`/`ProfilerSnapshot`/`EditorWindowViewportCapture` cleanup to the surviving hooks (`[BeforeCodeUnloading]` on 6.8+ behind the version gate). (1 day; needs task 8's editor install.)
+- [ ] 6. **Statics correctness pass.** Inventory package statics (connection state, ring buffers, caches) for no-domain-reload survival; add explicit reset bound to reload/play-mode hooks where staleness matters. (1 day.)
+- [ ] 7. **Unterm vendor fixes.** Patch the 4 vendored files with the same wrapper/gates; upstream the diff to the Unity-Unterm repo so the next vendor refresh doesn't regress. (Half day.)
+- [ ] 8. **Smoke test on an eligible CoreCLR Editor.** Select an available CoreCLR preview or release, record its exact version and platform, then run connect/console/MCP/play-mode/screenshot flows. Save pass/fail evidence in `experiments/coreclr-package-audit/results/`. (1 day including install.)
+- [ ] 9. **Release gate.** Sync both package copies, CHANGELOG, and Third Party Notices if Unterm changed. Advertise only the exact Editor and platform matrix that passed the readiness gates. (Half day.)
+
+## Done when
+
+Package connects and passes the task-8 smoke matrix on the recorded CoreCLR
+Editor with zero unsupported-API warnings, and the recorded legacy matrix is
+unchanged.
diff --git a/docs/tasks/WS2_MIGRATION_ASSISTANT.md b/docs/tasks/WS2_MIGRATION_ASSISTANT.md
new file mode 100644
index 0000000..605ca73
--- /dev/null
+++ b/docs/tasks/WS2_MIGRATION_ASSISTANT.md
@@ -0,0 +1,29 @@
+# WS2 — CoreCLR Migration Assistant
+
+Status: **Planned; blocked by WS1 tasks 1 and 2 (P0)**
+
+Last reviewed: 2026-08-13
+
+Support impact: no migration tool is shipped until the scanner and negative
+tests pass.
+
+Goal: scan any user's Unity project for 6.8/CoreCLR-breaking patterns, report each site with the documented replacement, and let agents fix them via MCP. The "install because of the transition" feature. Time-boxed relevance 2026-2028.
+
+Depends on: WS1 task 1 (inventory seeds the rule set), WS1 task 2 (version gate).
+
+Rule sources: Path to CoreCLR upgrade guide — statics no longer reset, `DomainUnload` never fires, deprecated `AppDomain.CurrentDomain.GetAssemblies()`, banned `Assembly.Load` overloads, empty `Assembly.Location`, `ManagedDebugger` removal; replacements `[AutoStaticsCleanup]`, `[BeforeCodeUnloading]`/`[AfterCodeReloadSerialization]`, `CurrentAssemblies.GetLoadedAssemblies()`, `CurrentAssemblies.LoadFromPath()`, `Assembly.GetLoadedAssemblyPath()`, `System.Diagnostics.Debugger`.
+
+## Tasks
+
+- [ ] 1. **Rule set as data.** `coreclr-migration-rules.json`: id, match pattern, severity (breaks / behavior-change / deprecated), explanation, documented replacement, docs URL. Committed config, not hardcoded in logic. (Half day.)
+- [ ] 2. **Regex scanner v1 (extension side).** TypeScript scanner over `Assets/` + `Packages/` C# files applying the rule set; structured findings (file, line, rule id, snippet). Skip generated/Library. New module `unity-cursor-toolkit/src/migration/`. (1 day.)
+- [ ] 3. **Extension command + report.** "Unity Toolkit: CoreCLR Migration Scan" -> markdown report (grouped by severity, per-site replacement guidance) opened in the editor + saved under the project. (Half day.)
+- [ ] 4. **MCP tool.** `coreclr_migration` with `action: "scan" | "report" | "rules"`; findings as structured JSON so agents can iterate site-by-site. Respect read-only mode (scan is read-only anyway). Register in `src/mcp/server.ts` + `toolMetadata.ts`, and standalone server. (Half day.)
+- [ ] 5. **Statics inventory (Unity side).** C# reflection pass listing static fields in user assemblies with no reset/cleanup attribute — the "will carry state after 6.8" list. Exposed through the existing bridge as part of the scan payload. (1 day.)
+- [ ] 6. **Semantic pass v2 (optional, later).** Roslyn-based analysis for cases regex can't judge (e.g. which `Assembly.Load` overload). Only if v1 false-positive rate is annoying. (2 days; defer.)
+- [ ] 7. **Agent workflow docs.** Section in `docs/AI_AGENTS.md`: scan -> prioritize -> fix loop with dry-run guidance; prompt template. (Half day.)
+- [ ] 8. **Marketing.** README + marketplace description: "CoreCLR migration assistant built in — get ready for Unity 6.8/7." (Half day, with WS4 repositioning pass.)
+
+## Done when
+
+Scanning this repo's own `CursorUnityTool` project reproduces the known WS1 inventory findings via both the command and the MCP tool, with correct replacement guidance per site.
diff --git a/docs/tasks/WS3_CORECLR_DEBUGGER.md b/docs/tasks/WS3_CORECLR_DEBUGGER.md
new file mode 100644
index 0000000..f9177a2
--- /dev/null
+++ b/docs/tasks/WS3_CORECLR_DEBUGGER.md
@@ -0,0 +1,30 @@
+# WS3 — CoreCLR Debugger for Cursor
+
+Status: **Feasibility spike pending (P0)**
+
+Last reviewed: 2026-08-13
+
+Depends on: WS1 capability detection. No CoreCLR debugger is currently shipped.
+
+Goal: prove and, if permitted, add a CoreCLR attach path while preserving the
+Mono soft debugger for legacy Editors. Recheck debugger support and license
+constraints against current primary sources before implementation.
+
+Depends on: WS1 task 2 (capability handshake tells the extension which runtime is on the other end). Existing code: `unity-cursor-toolkit/src/debug/{debugAdapter,launchJsonGenerator,index}.ts` (Mono, port 56000).
+
+## Tasks
+
+- [ ] 1. **Feasibility spike.** Select an eligible CoreCLR Editor and player, record their exact versions and platform, then test a permitted DAP debugger. Confirm breakpoints, stepping, and locals; save findings and exact flags in `experiments/coreclr-debug-probe/results/`. This is the kill-or-commit gate for the workstream. (1-2 days.)
+- [ ] 2. **Attach discovery.** Decide how the extension finds the target: PID via the toolkit handshake (`project_info` already knows the editor process) vs. process-name scan. Prefer handshake-provided PID. (Half day.)
+- [ ] 3. **Binary acquisition.** Download per-platform netcoredbg release on first use (verify checksum, cache under extension global storage); no bundling in the VSIX. Offline: fail loud with manual-install docs. (1 day.)
+- [ ] 4. **Debug adapter integration.** Register `unity-coreclr` debug type; `debugAdapter.ts` spawns netcoredbg in DAP mode and proxies; keep `unity-mono` type intact. (1-2 days.)
+- [ ] 5. **launch.json generation.** `launchJsonGenerator.ts` emits Mono config for <= 6.5 projects, CoreCLR config for 6.8+, both when undetermined — keyed off `ProjectVersion.txt` + handshake capability. (Half day.)
+- [ ] 6. **Editor-side prep.** Verify Code Optimization mode (Debug) requirement on CoreCLR editor; add a toolkit command/MCP action to flip it, mirroring the docs. (Half day.)
+- [ ] 7. **Player debugging.** Extend attach to Development CoreCLR players once 6.7's experimental player stabilizes; document limits. (1 day; can trail the release.)
+- [ ] 8. **Docs + matrix.** README debugger section becomes a version matrix (Mono <= 6.5 / CoreCLR >= 6.8); Cursor-specific setup walkthrough since that's the differentiator. (Half day.)
+
+## Done when
+
+In Cursor, on the recorded CoreCLR Editor: set a breakpoint in package code,
+attach through the toolkit debug configuration, hit it, inspect locals, and
+step. The recorded Mono legacy path must still pass unchanged.
diff --git a/docs/tasks/WS4_MCP_REPOSITION_BACKCOMPAT.md b/docs/tasks/WS4_MCP_REPOSITION_BACKCOMPAT.md
new file mode 100644
index 0000000..d784a70
--- /dev/null
+++ b/docs/tasks/WS4_MCP_REPOSITION_BACKCOMPAT.md
@@ -0,0 +1,58 @@
+# WS4 — MCP Ops-Layer Reposition + Backwards-Compat Product Line
+
+Status: **Planning active; compatibility and composition evidence pending (P0)**
+
+Last reviewed: 2026-08-13
+
+Depends on: WS1 capability detection and WS8 backend captures. The Unity 7
+version span is a target, not a current certification.
+
+Goal: stop competing with official Unity automation on tool count; win on
+version span, remote deployment, rendered viewport/shell, structured context,
+and enforceable safety policy. Evaluate composition of first-party automation
+and the toolkit bridge behind one explicit capability model. The target is one
+agent interface from the declared 2019.4 baseline through validated future
+Unity versions; the headline must name only the matrix that has passed.
+
+Depends on: WS1 task 2 (capability handshake). Existing code:
+`unity-cursor-toolkit/src/mcp/*` and
+`Packages/com.rankupgames.unity-cursor-toolkit/Editor/MCP/*` (mirrored in the
+sample Unity project package copy).
+
+## Tasks
+
+- [ ] 1. **Three-surface overlap analysis.** Preserve the dated Assistant MCP
+ capture, then enumerate standalone `unity` CLI and `com.unity.pipeline`
+ commands separately. Classify every overlapping capability by origin,
+ minimum Editor, transport, headless/live behavior, and mutation risk. Inputs:
+ `docs/OFFICIAL_MCP_OVERLAP.md` and
+ `docs/UNITY_CLI_AND_PIPELINE_ASSESSMENT.md`. (1 day.)
+- [ ] 2. **Capability matrix doc.** Feature x Unity-version table (2019.4 / 2020-2022 LTS / 6.0-6.5 / 6.8+ / U7) generated from the handshake capability set — becomes README + marketplace content and the CI matrix definition. (Half day.)
+- [ ] 3. **Version-gated feature detection tidy-up.** Extension consumes handshake capabilities everywhere it currently assumes (hot reload mode, debugger type, reload semantics); one code path per capability, no version sniffing scattered around. (1 day.)
+- [ ] 4. **Official-surface composition spikes.** Evaluate Assistant relay and
+ Pipeline composition separately. For Pipeline, prefer documented `unity`
+ CLI JSON/NDJSON and exit codes; for both origins, attach source metadata,
+ classify schemas by hand, and block/isolate arbitrary C# execution in
+ read-only sessions. Kill-or-commit each path independently. (2 days.)
+- [ ] 5. **CI compatibility matrix.** GitHub Actions jobs, or local runner scripts where licenses constrain CI, exercise package activation, handshake, and console/MCP smoke on the declared baseline, a legacy LTS Editor, the current sample baseline, and the exact CoreCLR Editor selected by WS1. (1-2 days.)
+- [ ] 6. **Repositioning pass.** README, marketplace listing, `llms.txt`,
+ `docs/AI_AGENTS.md`: lead with version span, remote/virtualized workflows,
+ safety policy, and composition. Do not claim generic local headless builds or
+ tests as unique now that `unity build/run/test` exist. Fold in WS2 task 8
+ marketing. No feature-count comparisons. (1 day.)
+- [ ] 7. **Catalog namespace and policy design.** Define stable origin-qualified
+ names/aliases for toolkit, Pipeline, and Assistant tools; resolve collisions;
+ preserve existing public schemas; and prove read-only mode cannot be bypassed
+ through `eval`, `eval_file`, or `Unity_RunCommand`. (1 day.)
+- [ ] 8. **Legacy-LTS outreach content (optional).** Short doc/post targeting
+ studios pinned on 2020-2022 LTS: official Assistant/Pipeline live-Editor
+ command catalogs require Unity 6+, while the toolkit supplies its own
+ agent-control, streaming, and safety surface for legacy LTS. Do not claim the
+ standalone CLI cannot manage an older Editor without version-matrix proof.
+ (Half day; marketing judgment call.)
+
+## Done when
+
+Marketplace listing and README lead with the safety/version-span/remote story;
+CI proves the span; Assistant and Pipeline composition decisions are made with
+separate spike evidence; origin-qualified catalogs cannot weaken read-only mode.
diff --git a/docs/tasks/WS5_STATICS_DETECTOR.md b/docs/tasks/WS5_STATICS_DETECTOR.md
new file mode 100644
index 0000000..9df3409
--- /dev/null
+++ b/docs/tasks/WS5_STATICS_DETECTOR.md
@@ -0,0 +1,28 @@
+# WS5 — Statics-Bug Detector (Fast Enter Play Mode)
+
+Status: **Planned; blocked by WS1 capability detection (P1)**
+
+Last reviewed: 2026-08-13
+
+Support impact: no static-state detector is currently shipped.
+
+Goal: detect static state carried across play-mode and runtime transitions.
+Recheck the exact Unity transition behavior against the selected Editor before
+implementation. Output: “these N statics carried state into play mode.”
+
+Depends on: WS1 task 2 (capability gate; on eligible CoreCLR Editors this also
+acts as a no-domain-reload staleness detector). Complements WS2 task 5 (static
+inventory).
+
+## Tasks
+
+- [ ] 1. **Snapshotter (Unity side).** Reflection scan of static fields in user assemblies (assembly allowlist; skip Unity/system) capturing a cheap fingerprint per field (hash of value / count for collections / null-ness). Opt-in via toolkit settings. (1-2 days.)
+- [ ] 2. **Transition hooks.** Capture on `ExitingEditMode` / `EnteredPlayMode` / `ExitingPlayMode` / `EnteredEditMode`; diff consecutive snapshots; classify carried vs reset. (1 day.)
+- [ ] 3. **Perf guardrails.** Budget cap (max fields/time per snapshot), incremental scan, and hard off-switch; measure overhead on CursorUnityTool and record numbers. Fail closed: over budget -> skip snapshot + warn, never stall play mode. (1 day.)
+- [ ] 4. **Report surface.** Findings into the live console stream as structured warnings + a "Statics Report" view in the console panel (field, declaring type, transition, before/after fingerprint). (1 day.)
+- [ ] 5. **MCP tool.** `statics_report` (read-only): latest diff as JSON so agents can chase heisenbugs. Register in both extension and standalone servers. (Half day.)
+- [ ] 6. **Docs.** Short guide: enabling FEPM safely, reading the report, common fixes (`[RuntimeInitializeOnLoadMethod]` resets; on 6.8+, `[AutoStaticsCleanup]`). (Half day.)
+
+## Done when
+
+A deliberately-buggy sample static in CursorUnityTool is flagged on the first play-mode round trip with FEPM on, with overhead numbers recorded and the MCP tool returning the same finding.
diff --git a/docs/tasks/WS6_TEST_RUNNER_BRIDGE.md b/docs/tasks/WS6_TEST_RUNNER_BRIDGE.md
new file mode 100644
index 0000000..6e77c30
--- /dev/null
+++ b/docs/tasks/WS6_TEST_RUNNER_BRIDGE.md
@@ -0,0 +1,67 @@
+# WS6 — Test Runner Bridge
+
+Status: **Standalone CLI parity spike ready (P1)**
+
+Last reviewed: 2026-08-13
+
+Depends on: WS8 CLI baseline for the typed backend. The unified test tools are
+not currently shipped.
+
+Goal: provide one stable test-orchestration surface in VS Code/Cursor and MCP
+across legacy and current Unity versions. Reuse the standalone CLI's
+`unity test` path on Unity 6+ where parity is proven; implement only the gaps
+needed for legacy Editors, progress streaming, remote targeting, richer results,
+and toolkit safety policy.
+
+Existing plumbing to reuse: connection/command bridge
+(`Packages/com.rankupgames.unity-cursor-toolkit/Editor/MCP/MCPBridge.cs`,
+`unity-cursor-toolkit/src/core/commandSender.ts`) and batch-mode path
+(`unity-cursor-toolkit/src/mcp/gameCommandBatchmode.ts` as the pattern).
+
+New first-party input: `unity test` runs Edit Mode and Play Mode tests in Editor
+batch mode, supports filters, Editor selection, NUnit XML output and timeouts,
+and returns CLI operation-failed exit code `6` for test failures. See
+`docs/UNITY_CLI_AND_PIPELINE_ASSESSMENT.md`.
+
+## Tasks
+
+- [ ] 1. **Standalone CLI parity spike.** Install a pinned verified CLI and run
+ list/filter/EditMode/PlayMode/failure/timeout cases through `unity test` on a
+ Unity 6 project. Capture stdout, stderr, NUnit shape, JSON/NDJSON behavior,
+ exit codes, cancellation, and progress visibility. Produce a measured gap
+ table before writing a second launcher. (1 day.)
+- [ ] 2. **Typed CLI adapter path.** Add test invocation through the WS8
+ `UnityCliAdapter`: argument arrays without a shell, explicit output format,
+ bounded timeout, structured exit mapping, and no credential/path leakage.
+ Reject missing exact Editor or module state. (1 day.)
+- [ ] 3. **Legacy/streaming TestRunnerApi path.** Wrap
+ `UnityEditor.TestTools.TestRunner.Api.TestRunnerApi` only for Editors the CLI
+ path cannot support or for proven capabilities it lacks: list tests, stream
+ progress, run filters, and collect structured status/duration/message/stack.
+ (1-2 days.)
+- [ ] 4. **Unified protocol and MCP schema.** Expose stable `list_tests` and
+ `run_tests` requests independent of backend. Include selected backend and
+ Editor version in results. `dryRun` resolves the selection without running;
+ read-only mode allows listing and blocks stateful PlayMode runs unless the
+ policy explicitly admits them. (1 day.)
+- [ ] 5. **Remote and interactive execution.** Route to an explicitly selected
+ local CLI, connected Pipeline Editor, toolkit bridge, or remote host based on
+ advertised capabilities. Never silently switch backends after failure.
+ Stream long-running progress so PlayMode jobs do not look hung. (1 day.)
+- [ ] 6. **VS Code surface.** Command palette entry + results in an output
+ channel/simple tree; full Test Explorer API integration deferred until
+ demand. (1 day.)
+- [ ] 7. **Negative and compatibility matrix.** Cover missing CLI, wrong/missing
+ Editor, locked project, no discovered tests, malformed NUnit, test failure,
+ timeout, cancellation, PlayMode policy refusal, and legacy/Unity 6 parity.
+ Record exact counts and skipped suites. (1 day.)
+- [ ] 8. **Docs.** `docs/AI_AGENTS.md` section: agent loop = edit -> filtered
+ `run_tests` -> read failures -> fix, including backend reporting and dry-run
+ guidance. (Half day.)
+
+## Done when
+
+An agent over MCP can list tests, run a filtered EditMode subset headlessly,
+receive structured pass/fail with stack traces, and see which backend/Editor ran
+it. A PlayMode run streams progress and completes. Unity 6 CLI and legacy
+bridge paths satisfy the same public schema without silent backend fallback.
diff --git a/docs/tasks/WS7_REMOTE_SHELL.md b/docs/tasks/WS7_REMOTE_SHELL.md
new file mode 100644
index 0000000..4e779c4
--- /dev/null
+++ b/docs/tasks/WS7_REMOTE_SHELL.md
@@ -0,0 +1,32 @@
+# WS7 — Remote Shell Productization
+
+Status: **Experimental background work (P1)**
+
+Last reviewed: 2026-08-13
+
+Support impact: proof lanes exist, but Unity 7 and production remote-shell
+compatibility are not validated.
+
+Goal: move the virtualized shell from experiment to a supported product. The
+dated first-party inventory does not replace the rendered-window and input
+plane, but that comparison must be rechecked before positioning claims.
+Governing docs: `docs/UNITY_WITHOUT_EDITOR_EXPERIMENTS.md`,
+`docs/REMOTE_UNITY_STREAMING.md`, `docs/EDITOR_WINDOW_STREAMING_PLAN.md`.
+Existing code: `src/remote-shell/`, `src/viewport/`, `experiments/*`.
+
+Steady-background pace; each task independently valuable.
+
+## Tasks
+
+- [ ] 1. **Internal-API smoke tests.** Automated per-version check that `GUIView.GrabPixels` + `SendEvent` reflection paths still resolve and produce frames; wire into the WS4 CI matrix so a Unity release breaking W0 is caught the week it ships, not by users. (1 day.)
+- [ ] 2. **Re-baseline E2 on CoreCLR.** Re-run the hidden-editor cost baseline (time-to-first-frame, RSS, and idle/streaming CPU) on the exact CoreCLR Editor selected by WS1; update `experiments/hidden-editor-cost-baseline/results/`. Measure the result without assuming an improvement. (1 day.)
+- [ ] 3. **Player viewport on a CoreCLR player.** Validate the E3 player viewport service against an eligible exact-version CoreCLR desktop player and record deltas. (1 day.)
+- [ ] 4. **Transport plan v1.** Design doc + spike replacing MJPEG debug path with a real low-latency transport (H.264/WebCodecs or equivalent); decide encoder strategy per platform. Spike only — pick, measure latency, write down the decision. (2 days.)
+- [ ] 5. **Launch UX hardening.** `remote-shell init/launch` manifest flow: clearer errors, preflight checks (SSH reachability, sidecar version, license state), and a doctor command. (1-2 days.)
+- [ ] 6. **W0 hidden-editor attach UX.** One command from VS Code/Cursor: auto-launch hidden licensed editor for the open project, stream target window, teardown on disconnect. The M3 plan from `EDITOR_WINDOW_STREAMING_PLAN.md` broken to its own checklist when started. (Multi-day; split before starting.)
+- [ ] 7. **Licensing/BYOL doc.** User-facing doc of the W0-W4 licensing posture (own seat, BYOL for remote hosts, licensing-server lane for fleets) distilled from the experiments doc; flag the "counsel before hosted-for-third-parties" caveat. (Half day.)
+- [ ] 8. **Fleet design doc (later).** Editor fleet orchestration (N leased hidden/remote editors, validation-farm workflow) — design only, after task 6 ships. Gate: do not build before single-editor UX is solid. (1 day design.)
+
+## Done when
+
+CI guards the reflection paths across the version matrix; CoreCLR baselines are recorded; a user can go from workspace to streamed hidden-editor window with one command on macOS.
diff --git a/docs/tasks/WS8_UNITY7_WATCH.md b/docs/tasks/WS8_UNITY7_WATCH.md
new file mode 100644
index 0000000..e3061ec
--- /dev/null
+++ b/docs/tasks/WS8_UNITY7_WATCH.md
@@ -0,0 +1,98 @@
+# WS8 — Standalone Unity CLI + Pipeline Adoption and Unity 7 Watch
+
+Status: **Baseline and parity work ready; adapter and composition not shipped (P0)**
+
+Last reviewed: 2026-08-13
+
+Support impact: the dated CLI/Pipeline assessment is research input, not an
+enabled production backend.
+
+Goal: adopt the standalone Unity CLI and `com.unity.pipeline` now, make the
+toolkit the safest version-spanning client of those first-party surfaces, and
+keep only Unity 7-specific deltas in watch status.
+
+The 2026-08-07 assessment found enough information to start a pinned baseline;
+it did not prove a production backend. That dated snapshot recorded `unity`
+`1.0.0-beta.3` and Pipeline documentation for `com.unity.pipeline`
+`0.4.0-exp.1`. Recheck availability, version requirements, and package age
+before installation. Canonical inventory, security analysis, WIA snapshot, and setup plan:
+`docs/UNITY_CLI_AND_PIPELINE_ASSESSMENT.md`.
+
+Depends on: WS1 task 2 for project capability detection. Feeds WS4 official
+surface composition and WS6 test orchestration.
+
+## Tasks
+
+- [ ] 1. **Pinned CLI baseline.** Install the standalone CLI through an
+ approved distribution method; record exact version, channel, checksum or
+ package-manager identity, and publication date. Run `unity --version`,
+ `unity doctor`, `unity env --format json`, `unity editors -i --format json`,
+ and `unity auth status`. Do not modify a Unity project in this task. (Half day.)
+- [ ] 2. **CLI contract capture.** Save `unity --help` plus help for `editors`,
+ `open`, `build`, `run`, `test`, `pipeline`, `command`, `list`, `status`, and
+ `mcp`. Capture human/TSV/JSON/NDJSON output and documented exit-code behavior.
+ Treat installed help as authority for the beta. (Half day.)
+- [ ] 3. **Editor and project resolution proof.** Against an isolated sample and
+ WIA, prove `ProjectVersion.txt` selects the exact Editor, modules are checked
+ per installation, and non-interactive missing-Editor/module cases fail
+ closed. Do not permit an implicit upgrade or `latest` substitution. (Half day.)
+- [ ] 4. **Local test/build/run parity.** Run one filtered Edit Mode test, one
+ Play Mode test, one non-signing development build, and one registered
+ headless command. Record logs, structured results, exit codes, interruption,
+ timeout, dirty-worktree behavior, and what project-specific build steps are
+ not covered. Coordinate the test matrix with WS6. (1 day.)
+- [ ] 5. **`UnityCliAdapter`.** Implement a TypeScript adapter that invokes the
+ binary without a shell, passes argument arrays, selects JSON/NDJSON
+ explicitly, separates stdout/stderr, maps exit codes to typed results, and
+ applies bounded cancellation. Add CLI version/presence to doctor/status.
+ Do not hardcode Editor installation paths. (1-2 days.)
+- [ ] 6. **Pipeline package eligibility gate.** Query available versions and
+ registry publication timestamps; select a version at least seven days old,
+ pin it, and document the approval. Reject unsupported pre-Unity-6 projects
+ before package mutation. (Half day.)
+- [ ] 7. **Isolated Pipeline install.** In a disposable project or reviewed
+ branch, run `unity pipeline install --package-version `, review the
+ manifest/lock diff, wait for compilation, and prove `pipeline list`,
+ `status`, `list`, and `command editor_status`. Record package/reload impact.
+ (1 day.)
+- [ ] 8. **Pipeline safety matrix.** Prove loopback-only binding, bearer-token
+ discovery, multi-Editor project targeting, `dry_run`/`confirm`, Undo, and
+ authoring-root constraints. Classify every advertised command as read-only,
+ mutating, destructive, or policy-escape; isolate `eval`/`eval_file`, package
+ changes, deletion, build, and project-setting mutation. (1 day.)
+- [ ] 9. **Pipeline adapter and MCP composition.** Add explicit Pipeline command
+ discovery/execution behind toolkit policy. Decide with evidence whether to
+ compose `unity mcp` as a child process or invoke `unity command` directly.
+ Origin-qualify tools, preserve public aliases, and prove toolkit read-only
+ mode cannot be bypassed. Coordinate with WS4. (1-2 days.)
+- [ ] 10. **WIA integration cleanup.** Replace hardcoded Editor discovery in the
+ WIA test runner with declared-version/CLI resolution; remove sibling/clone
+ generation of missing SpacetimeDB bindings in favor of the explicit portable
+ artifact and fail-closed error. Preserve custom CIBuilder behavior for data,
+ Addressables, Odin AOT, variants, signing, and build profiles. (1 day.)
+- [ ] 11. **Compatibility and failure matrix.** Cover CLI absent, wrong version,
+ missing Editor, missing module, auth failure, Pipeline absent/unsupported,
+ multiple Editors, locked project, compile/test/build failure, malformed
+ output, timeout, cancellation, and read-only policy refusal across legacy,
+ 2022 LTS, current Unity 6, and preview Unity. (1-2 days.)
+- [ ] 12. **Docs and positioning.** Update README, marketplace copy,
+ `docs/AI_AGENTS.md`, and `llms.txt` with installation, backend status,
+ capability matrix, security boundaries, and recovery. Present CLI/Pipeline
+ as composed first-party backends, not toolkit-owned inventions. (1 day.)
+- [ ] 13. **Unity 7 delta watch.** Track only features not present in the current
+ CLI/Pipeline releases: new Unity 7 commands/APIs, CoreCLR-only behavior,
+ production-pipeline services, and editor-fleet primitives. Re-run WS4 overlap
+ and this workstream's matrices on each material beta. (Ongoing.)
+- [ ] 14. **Fleet design follow-on.** After single-project local/remote
+ integration is stable, design leased Editor instances, licensing, scheduling,
+ and validation-farm orchestration. Design only until a measured user need and
+ supported licensing model exist. (Later.)
+
+## Done when
+
+The toolkit reports and uses a pinned standalone CLI without hardcoded Editor
+paths; resolves exact project Editors and modules; runs structured build/test
+jobs; safely discovers and invokes a pinned Pipeline package on Unity 6+; keeps
+legacy projects on an explicit supported backend; and exposes a composed MCP
+catalog whose origin and mutation policy are unambiguous. Unity 7 watch notes
+then contain only genuine deltas beyond this shipped baseline.
diff --git a/llms.txt b/llms.txt
index 23a206f..ccf38ce 100644
--- a/llms.txt
+++ b/llms.txt
@@ -2,7 +2,10 @@
> Unity Editor bridge for VS Code, Cursor, and MCP-capable AI agents.
-Unity Cursor Toolkit provides hot reload, live console streaming, play mode controls, Mono debugger attach support, `.meta` resolution, and MCP tools for Unity Editor automation.
+Unity Cursor Toolkit provides live console and profiler context, hot reload,
+play mode controls, debugger attach support, `.meta` resolution, and MCP tools
+for Unity Editor automation. The core package declares Unity 2019.4 or later.
+Unity 7 is a planned, evidence-gated target, not a current support claim.
## Start Here
@@ -11,6 +14,11 @@ Unity Cursor Toolkit provides hot reload, live console streaming, play mode cont
- MCP client setup: docs/MCP_CLIENTS.md
- Runtime game command guide: docs/GAME_COMMANDS.md
- Feature roadmap: docs/FEATURE_ROADMAP.md
+- Documentation index: docs/README.md
+- Unity 7 readiness plan: docs/UNITY_7_READINESS.md
+- Unity 7 landscape assessment: docs/UNITY_7_LANDSCAPE_ASSESSMENT.md
+- Unity CLI and Pipeline assessment: docs/UNITY_CLI_AND_PIPELINE_ASSESSMENT.md
+- Unity 7 workstreams: docs/tasks/README.md
- Extension README: unity-cursor-toolkit/README.md
- Unity package docs: Packages/com.rankupgames.unity-cursor-toolkit/Documentation~/README.md
- Zed setup: zed/README.md
@@ -44,4 +52,7 @@ Useful environment variables:
- Use `project_info`, `read_console`, `resolve_meta`, and `manage_scene` with `action: "getHierarchy"` before mutating.
- Use `game_command` with `action: "list"` before scheduling project-owned runtime workflows.
- Use `dryRun: true` on mutating tools to inspect the normalized Unity command without executing it.
+- Report the exact Editor, backend, and capability set. Do not infer Unity 7
+ readiness from the declared 2019.4+ package baseline or from an unchecked
+ roadmap task.
- Mutating tools include scene load/save/create, GameObject edits, component edits, asset edits, material edits, play mode, menu execution, runtime game command scheduling/canceling, build trigger, and batch execution.
diff --git a/remote_workspace/README.md b/remote_workspace/README.md
index ca259fc..bd74a17 100644
--- a/remote_workspace/README.md
+++ b/remote_workspace/README.md
@@ -1,8 +1,17 @@
# Unity VDD Shell Workspace
+Status: experimental remote-rendering workspace. It is part of the Unity 7
+readiness program because first-party semantic control does not replace a
+rendered Editor-window and input plane. Unity 7 compatibility is not yet
+validated. See [Unity 7 readiness](../docs/UNITY_7_READINESS.md) and
+[WS7](../docs/tasks/WS7_REMOTE_SHELL.md).
+
Run `Unity Shell: Init Manifest` from VS Code/Cursor to create the local `unity-shell.json` manifest from the checked-in example. The real manifest is ignored because it contains machine-specific SSH targets and remote paths.
-The MVP assumes a Windows host with a VDD monitor, FFmpeg, a Unity Windows Player build, and the remote PowerShell sidecar copied to the manifest's `remoteSidecarPath`.
+The MVP assumes a Windows host with a VDD monitor, FFmpeg, an exact-version
+Unity Windows Player build, and the remote PowerShell sidecar copied to the
+manifest's `remoteSidecarPath`. Do not substitute a newer Editor for the
+project's declared version during proof runs.
For the Unity-without-editor Windows proof gate, also set:
diff --git a/unity-cursor-toolkit/CHANGELOG.md b/unity-cursor-toolkit/CHANGELOG.md
index ff23b21..464cf74 100644
--- a/unity-cursor-toolkit/CHANGELOG.md
+++ b/unity-cursor-toolkit/CHANGELOG.md
@@ -11,6 +11,13 @@ All notable changes to the Unity Cursor Toolkit VS Code/Cursor extension are doc
- Added the discoverable `editor_validation` MCP tool for project-file regeneration, compile requests, and pollable validation status.
- Added focused coverage for context indexing, batchmode command planning, and standalone MCP read-only behavior.
+### Documentation
+
+- Replaced retired dynamic Marketplace badges with a stable install badge that
+ links to the existing Marketplace item.
+- Added the canonical Unity 7 readiness plan and synchronized public status
+ wording with the Unity package and workstream documents.
+
### Fixed
- Hardened TCP attach so open Unity-related ports must answer the toolkit `ping`/`pong` handshake before the extension marks them connected.
diff --git a/unity-cursor-toolkit/README.md b/unity-cursor-toolkit/README.md
index f8bef69..3a547d9 100644
--- a/unity-cursor-toolkit/README.md
+++ b/unity-cursor-toolkit/README.md
@@ -1,6 +1,27 @@
# Unity Cursor Toolkit Extension
-VS Code / Cursor extension for Unity hot reload, live console streaming, MCP tool routing, context indexing, runtime game commands, play mode controls, `.meta` resolution, Mono debugger attach support, and standalone MCP access for AI agents.
+[](https://marketplace.visualstudio.com/items?itemName=rankupgames.unity-cursor-toolkit)
+[](https://open-vsx.org/extension/rankupgames/unity-cursor-toolkit)
+
+VS Code / Cursor extension for Unity live console and profiler context, MCP
+tool routing, context indexing, runtime game commands, play mode controls,
+`.meta` resolution, debugger attach, hot reload, and standalone MCP access for
+AI agents.
+
+## Current Support and Unity 7
+
+- The companion Unity package declares Unity 2019.4 or later for core features.
+- Bundled Unity-Unterm features require Unity 6000.3 or later on macOS or
+ Windows.
+- Mono debugging and IL-patch hot reload remain the current legacy-runtime
+ paths.
+- CoreCLR capability gates, migration assistance, a replacement debugger, and
+ Unity 7 compatibility evidence are planned work. Unity 7 support is not yet a
+ shipped claim.
+
+Read the repository's [Unity 7 readiness plan](../docs/UNITY_7_READINESS.md),
+[documentation index](../docs/README.md), and
+[workstream task index](../docs/tasks/README.md).
## Development
@@ -35,6 +56,11 @@ Use the `game_command` MCP tool to list, schedule, poll, or cancel runtime workf
Use the `unity_context` MCP tool to refresh `.umetacontext/index.json` with `action: "scan"`, then inspect compact project context with `summary`, `query`, and `read`.
+The Unity toolbar copy action builds compact profiler and console context,
+captures the current main-camera application view, overwrites one stable PNG in
+`Application.temporaryCachePath`, and appends the absolute image path to the
+clipboard text.
+
## Packaging
```bash
diff --git a/zed/README.md b/zed/README.md
index e85bbfb..887094c 100644
--- a/zed/README.md
+++ b/zed/README.md
@@ -8,6 +8,14 @@ Zed does not run VS Code extensions natively. Instead, Zed connects to Unity Cur
- Built companion extension output at `unity-cursor-toolkit/out/mcp/server.js`
- Node.js available on your PATH
+## Unity Version Status
+
+The Unity package declares Unity 2019.4 or later for core features. The same
+standalone MCP server and public tool schemas are intended to remain stable as
+projects move through Unity 6, CoreCLR, and Unity 7. Unity 7 compatibility is a
+planned, evidence-gated target and is not yet certified. See the
+[Unity 7 readiness plan](../docs/UNITY_7_READINESS.md).
+
## Setup
Build the server:
@@ -39,7 +47,7 @@ Replace `` with the absolute path to the built extension dire
## Available Tools
-Once connected, the MCP server exposes tools for:
+Once connected, the MCP server exposes tools including:
- `read_console` -- fetch Unity console logs with filtering
- `clear_console` -- clear the Unity console
@@ -56,6 +64,10 @@ Once connected, the MCP server exposes tools for:
The server also exposes MCP resources for project info, scene hierarchy, recent console output, console errors, and the tool catalog. Prompts are available for diagnosing errors, inspecting scenes, preparing builds, and planning safe scene edits.
+The server reports the selected backend and Unity project information where
+available. Future CLI, Pipeline, and Unity 7 backends must remain explicit; the
+toolkit will not silently switch Editors or backends after a failure.
+
## How It Works
The MCP server communicates with Unity over the same TCP socket (ports 55500-55504) used by the VS Code/Cursor extension. The Unity-side package is identical regardless of which editor or MCP client you use.