Release 1.5.0

.github/workflows/validate.yml

@@ -102,7 +102,11 @@ jobs:
 
   documentation-quality-ai:
     name: Documentation quality AI
-    runs-on: [self-hosted, macOS, ARM64, ci-scope-broker, ci-scope-heavy]
+    # ci-scope-job-doc-ai disambiguates this from unity-package-smoke below:
+    # two same-run jobs with byte-identical runs-on let GitHub's scheduler
+    # hand a connecting runner EITHER one, not necessarily the one the broker
+    # leased it for (NexusUnity PR #145, 2026-07-04).
+    runs-on: [self-hosted, macOS, ARM64, ci-scope-broker, ci-scope-heavy, ci-scope-job-doc-ai]
     needs: static-validation
     env:
       NEXUS_DOC_AI_MAX_PARALLEL: "1"
@@ -188,7 +192,9 @@ jobs:
 
   unity-package-smoke:
     name: Unity package smoke
-    runs-on: [self-hosted, macOS, ARM64, ci-scope-broker, ci-scope-heavy]
+    # ci-scope-job-unity-smoke disambiguates this from documentation-quality-ai
+    # above — see that job's comment.
+    runs-on: [self-hosted, macOS, ARM64, ci-scope-broker, ci-scope-heavy, ci-scope-job-unity-smoke]
     needs: static-validation
     steps:
       - name: Check out repository

.gitignore

@@ -119,7 +119,9 @@ repro/
 # Local agent and analysis artifacts
 .agents/
 .codex/
+.gemini/
 .hermes/
+.serena/
 .soma/
 graphify-out/
 graphify-out/cache/
@@ -133,3 +135,4 @@ graphify-out/.graphify_*
 LINT_REPORT.txt
 temp_verify/
 *.tmp
+AUDIT_FINDINGS.md*

AGENTS.md

@@ -0,0 +1,45 @@
+# Agent Instructions: NexusUnity
+
+## Repository Scope
+
+This directory is the canonical Nexus Unity package repository.
+
+Use this directory for all Nexus Unity package work:
+
+- Branches, commits, pushes, pull requests, and issue fixes.
+- Package source, bridge source, tests, changelog, README, and documentation.
+- GitHub issue/PR work for `ForkHorizon/NexusUnity`.
+
+The parent Unity project is only the local test harness:
+
+`/Users/daliys/Daliys/UnityProjects/UnityTestForNexus`
+
+Use the parent project to run the Unity Editor, MCP server, scenes, `unity_lint_project`, and live package validation. Do not modify parent project files unless the user explicitly asks for harness work.
+
+## Branching
+
+- Base branch: `development`.
+- Verify the real branch names before creating history.
+- Do not auto-push.
+
+## Required Package Updates
+
+When package behavior or public API changes, keep these aligned:
+
+- `CHANGELOG.md`
+- `README.md`
+- `DOCUMENTATION.MD`
+- `API_REFERENCE.MD` when tool contracts or public API shapes change
+- Relevant tests under `Tests~/` or `Editor/tests/`
+
+## Validation
+
+Fast package validation:
+
+```bash
+PYTHONDONTWRITEBYTECODE=1 scripts/prepush-validate.sh --static-only
+```
+
+For Unity-facing behavior, also use the running test harness through MCP tools such as `unity_wait`, `unity_lint_project`, and `unity_editor_controller`.
+
+Clean generated Python caches before validation if needed; `__pycache__` or `*.pyc` files are not part of package changes.

API_REFERENCE.MD

@@ -1,6 +1,6 @@
 # Nexus Unity API Reference
 
-Version: `1.4.2`
+Version: `1.5.0`
 
 Nexus Unity exposes two supported public API surfaces:
 
@@ -14,18 +14,24 @@ Raw requests use unprefixed method names:
 ```bash
 curl -s http://127.0.0.1:8081/ \
   -H 'Content-Type: application/json' \
+  -H "X-Nexus-Unity-Token: $NEXUS_UNITY_AUTH_TOKEN" \
   -d '{"jsonrpc":"2.0","method":"get_server_status","params":{},"id":1}'
 ```
 
-Call `list_tools` at runtime for full JSON schemas. MCP bridge aliases use the `unity_` prefix for the same raw method when directly routed.
+Call `list_tools` at runtime for full JSON schemas. Generated MCP configs set `NEXUS_UNITY_AUTH_TOKEN` for the Python bridge; rerun Auto Setup after restarting Unity if the token is stale. MCP bridge aliases use the `unity_` prefix for the same raw method when directly routed.
 
 Schema compatibility notes:
 
 - `unity_write_and_compile` is the supported code-edit macro. Older references to `unity_apply_code_change` are stale and should be replaced.
 - `update_component` accepts the preferred `properties` object and the legacy `json_data` string form.
 - `create_scene` accepts optional `path` and `open_if_exists`, so agents can create or reopen a deterministic scene asset in one call.
 - `create_primitive` accepts optional `name`, `parent_id`, `position`, `rotation`, `scale`, and `material_path` for visible non-origin object creation.
+- Vector3 fields accept either `{ "x": 0, "y": 1, "z": 0 }` or `[0, 1, 0]`.
 - `set_transform` accepts `position`, `rotation` / `eulerAngles`, and `scale` / `localScale`.
+- `get_game_object` returns `transform.position`, `transform.rotation`, `transform.scale`, and compact `components` data for cheap read-back verification.
+- Fast-path health calls (`get_server_status`, `attach_existing_session`, `wait_for_asset_import_idle`, and `wait_for_editor_idle`) use cached editor state because they may run on the listener thread.
+- After script writes, readiness probes remain busy until the scheduled asset refresh window has passed.
+- During Play Mode transitions, readiness probes remain busy until Unity finishes entering or exiting Play Mode.
 - `create_material` accepts optional `path`, `base_color` / `color`, and `emission_color` so callers can create visible materials in a chosen folder.
 - `write_file` and `write_files_batch` create missing parent directories after path validation.
 - `invoke_method.arguments` is an optional JSON array of positional arguments.
@@ -151,14 +157,11 @@ Schema compatibility notes:
 - `ui_click` / `unity_ui_click`
 - `ui_input_text` / `unity_ui_input_text`
 
-## MCP Bridge Tools
-
-The MCP bridge is the recommended AI-client surface. It exposes 14 tools and two static read-only resources through `resources/list`.
+`batch_execute` accepts at most 50 requests and rejects nested `batch_execute` calls.
 
-### MCP Resources
+## MCP Bridge Tools
 
-- `unity://docs/api-reference`: API reference metadata.
-- `unity://docs/setup`: setup guide metadata.
+The MCP bridge is the recommended AI-client surface. It exposes 14 tools and two static read-only resources through `resources/list` and `resources/read`.
 
 ### `unity_scene_manager`
 Actions: `create`, `open`, `save`, `list`. Aliases: `create_scene`, `open_scene`, `save_scene`, `list_scenes`.
@@ -168,7 +171,7 @@ Actions: `create`, `open`, `save`, `list`. Aliases: `create_scene`, `open_scene`
 ### `unity_hierarchy_manager`
 Actions: `create_empty`, `create_primitive`, `create_hierarchy`, `destroy`, `duplicate`, `rename`, `set_name`, `set_transform`, `set_active`, `set_parent`, `set_sibling_index`.
 
-Aliases: `create`, `create_gameobject`, and `create_game_object` map to `create_empty`. `create_primitive` accepts `name`, `parent_id`, `position`, `rotation`, `scale`, and `material_path`.
+Aliases: `create`, `create_gameobject`, and `create_game_object` map to `create_empty`. `create_primitive` accepts `name`, `parent_id`, `position`, `rotation`, `scale`, and `material_path`; Vector3 fields accept either object or array form.
 
 ### `unity_component_manager`
 Actions: `add`, `remove`, `inspect`, `get_schema`, `update_properties`, `set_property`, `set_enabled`.
@@ -197,10 +200,14 @@ Conditions: `compilation`, `play_mode`, `import`, `editor_idle`.
 ### `unity_playerprefs_manager`
 Actions: `get`, `set`, `delete`, `list`.
 
+Deleting every PlayerPrefs entry requires `action: "delete"`, `key: "all"`, and `confirm: true`; this operation is not undoable.
+
 ### `unity_write_and_compile`
 Writes one or more files, waits for Unity compilation/import work, and returns compiler errors.
 
-This is the public MCP bridge macro for code edits. Use it instead of old internal or stale documentation references to `unity_apply_code_change`.
+This is the public MCP bridge macro for code edits. Pass `confirm: true` when writing `.cs` files because Unity compilation is triggered. Use it instead of old internal or stale documentation references to `unity_apply_code_change`.
+
+Raw `attach_script`, `write_file`, and `write_files_batch` calls also require `confirm: true` before writing `.cs` files.
 
 ### `unity_invoke_method`
 Invokes a C# method on a component through reflection.

CHANGELOG.md

@@ -4,6 +4,34 @@ All notable public changes to Nexus Unity are documented here.
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-07-12
+
+### Changed
+- Relicensed Nexus Unity from `GPL-3.0-only` to the `MIT` license to remove copyleft friction for commercial Unity studios. All prior contributors consented to the relicense.
+
+### Fixed
+- Updated Claude Code and Gemini CLI setup commands for their current option ordering and explicit project-scoped stdio registration; Gemini setup no longer bypasses tool approvals with `--trust`.
+- Antigravity setup now writes its workspace configuration to `.agents/mcp_config.json` instead of the legacy global Gemini config path.
+- Cline setup now writes its shared MCP settings to `~/.cline/data/settings/cline_mcp_settings.json` instead of the retired VS Code extension storage path.
+- Claude Code setup now skips the CLI add command when removal of a stale project registration fails, logs the actionable failure, and falls back directly to `.mcp.json`.
+- The local HTTP/WebSocket control plane now requires a per-session auth token before JSON-RPC dispatch; generated MCP configs pass the token through the Python bridge.
+- `add_component` now returns a clear `GameObject not found` error for stale instance IDs instead of throwing a raw Unity null reference.
+- `batch_execute` now caps batches at 50 requests and rejects nested batch execution.
+- `create_primitive` now validates parent, transform, and material inputs before creating the GameObject, and Vector3 inputs accept `[x, y, z]` arrays as well as `{x, y, z}` objects.
+- `get_game_object` now returns transform state and a compact component list so agents can verify basic write operations with the cheap read-back call.
+- Script writes now keep readiness probes in a busy/importing state while the scheduled asset refresh is pending, avoiding premature follow-up write calls during Unity domain reload.
+- Script-writing RPC methods now require `confirm: true` before creating or overwriting `.cs` files and triggering Unity compilation.
+- MCP bridge static resources can now be read through `resources/read` after discovery through `resources/list`.
+- Play mode transitions now keep readiness probes busy so agents do not issue follow-up writes while Unity is still entering or exiting Play Mode.
+- `delete_player_pref` now rejects missing or empty keys, and only clears all PlayerPrefs when called with `key: "all"` and `confirm: true`.
+- Invalid `NEXUS_UNITY_TIMEOUT_SECONDS` values now fall back to the default bridge timeout instead of crashing the Python bridge at import time.
+- Python bridge type helpers no longer require Python 3.11-only typing features.
+- Path security tests now exercise JSON-RPC traversal rejection for representative file and asset tools.
+- `get_test_results` now reads messages only from scoped NUnit result nodes and falls back to the test result instead of unrelated nested messages.
+- `unity_scene_manager` schema aliases now preserve action-specific required parameters.
+- Fast-path health JSON-RPC methods now use cached editor state instead of direct Unity API reads on the listener thread.
+- MCP CLI installers now pass executable paths and project paths as process arguments instead of shell command strings.
+
 ## [1.4.2] - 2026-06-13
 
 ### Added