@aefree/pi-unity 0.9.0

package/CHANGELOG.md

@@ -0,0 +1,173 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project follows semantic versioning for public package releases.
+
+## [0.9.0] - 2026-08-04
+
+### Added
+
+- Added `unity_pipeline_recompile` and `unity_pipeline_run_tests` for exact-copy connected compilation and focused tests with lifecycle guards, bounded polling, identity checks, and compact terminal evidence.
+- Added `unity_pipeline_eval` for bounded project-specific C# evaluation and `unity_pipeline_inspect` for package-owned structured Pipeline inspections.
+- Added the `unity-interactive-playmode-authoring` skill for temporary live runtime tuning followed by deliberate persistence of accepted values.
+- Added the `unity-debugging` skill for evidence-first diagnosis of Unity Editor, runtime, package, asset, lifecycle, callback, and feature-activation problems.
+- Added an optional schema-open Unity artifact profile for solution and memory Markdown with optional `engine`, `unity_version`, `unity_packages`, `render_pipeline`, and `platforms` metadata.
+- Added an optional Unity file-discovery filter that recommends excluding generated directories for broad roots while preserving explicit searches inside generated roots.
+
+### Changed
+
+- Replaced `unity-connected-workflows` with `unity-pipeline-workflows`, routing connected operations through typed tools and documenting safe PlayMode lifecycle, cancellation, timeout, test-evidence, and Game View focus behavior.
+- Tightened Unity test evidence so zero-test, unknown-total, malformed, missing-result, and failing runs are never reported as passing.
+- Made project-artifacts and file-discovery composition optional through their public capability contracts and global registry rendezvous, allowing independently installed Pi packages to compose without sibling paths or shared module roots.
+- Updated optional integration metadata to use `@aefree/pi-project-artifacts` and `@aefree/pi-file-discovery` as optional peers, while classifying the statically imported `typebox` as a runtime dependency.
+- Updated package validation to Node.js 22.19 or later with a registry-clean lockfile, local `tsx`, reproducible `npm ci` workflows, and a consumer-focused npm archive.
+
+### Removed
+
+- Removed the `capturing-screenshots-unity` skill and its bundled capture assets; graphics-required launches remain available through the explicit `useGraphics` controls.
+- Retired the workflow-guidance contributor and intermediate migration/capture surfaces; reusable procedures now remain in their owning skills, and optional integrations contribute metadata without selecting schemas or rewriting project documents.
+
+### Fixed
+
+- Made multi-integration registration transactional so failures roll back every earlier registration for that session scope.
+- Fixed clean-install tests to exercise optional integrations through installed package contracts rather than sibling repository source paths.
+- Fixed macOS guidance-audit path handling, cross-platform line-ending assertions, and cancellation propagation through connected capability and process operations.
+
+## [0.8.2] - 2026-07-24
+
+### Changed
+
+- Marked Pi-bundled core dependencies as optional peers so Pi git installs do not create redundant per-package `node_modules` directories.
+
+## [0.8.1] - 2026-07-23
+
+### Changed
+
+- Clarified test routing across tool prompts, README guidance, and the batchmode skill: an already-open exact project copy with reachable `run_tests`/`test_status` Pipeline commands should run connected tests without closing the Editor; batchmode is reserved for deliberately isolated/report-producing cases.
+- Documented that an asynchronous connected `run_tests` initiation may report zero tests while still running and that zero-test validation belongs to terminal `test_status` results.
+- Strengthened Unity guidance migration scope handling so nested-workspace audits include inherited instructions by default or explicitly disclose excluded ancestor candidates, while keeping ancestor edits authorization-gated.
+- Added a behavioral regression case for auditing inherited coordination-root guidance without editing it.
+
+### Fixed
+
+- Instruct migration agents to preserve clear known-safe prohibitions and report likely heuristic defects instead of weakening wording merely to obtain a zero-finding audit.
+- Recognize prohibitions placed between `-runTests` and `-quit`, such as “`-runTests` commands must not include `-quit`,” instead of reporting them as unsafe commands.
+
+## [0.8.0] - 2026-07-23
+
+### Added
+
+- Added Unity CLI and Pipeline capability reporting to `unity_project_status`, including exact-project-copy instance matching, locally declared package versions, and live advertised command discovery.
+- Added the read-only `unity_guidance_audit` tool plus an `auditing-unity-agent-guidance` skill, migration policy, detection catalog, and mixed-harness template for modernizing AGENTS.md, CLAUDE.md, Copilot, and Cursor Unity workflows.
+- Added `unity-connected-workflows` guidance for exact-copy Pipeline recompilation and focused asynchronous tests, including nested JSON, domain reload, zero-test, and artifact limitations.
+- Added an isolated behavioral eval for `auditing-unity-agent-guidance` with 12 real-problem-derived positive/negative prompts, deterministic outcome checks, skill-versus-baseline runs, repeat trials, and efficiency evidence. Eval fixtures and reports stay in OS-temporary directories by default, with defense-in-depth ignores for explicitly persisted reports.
+- Documented the observed Pipeline startup side effect that persists `Application.runInBackground = true` into `ProjectSettings/ProjectSettings.asset`.
+
+### Changed
+
+- Reframed `unity-batchmode-tests` as the isolated/report-producing route instead of the default for an already-open reachable Pipeline Editor, and prefer the standalone `unity test` command over forwarding `-runTests` through `unity run`.
+- Expanded guidance auditing to detect unconditional lockfile deletion, arbitrary PID termination, manifest-only Pipeline reachability assumptions, and unbounded command/test discovery.
+
+### Fixed
+
+- Parse the current Unity CLI's nested `pipelineServer.isReachable` and `pipelineServer.apiUrl` fields so unreachable instances do not trigger command discovery.
+- Updated guarded graceful Editor exit to use the current `unity command eval` surface and attempt it only when the exact running project advertises `eval` and the discovered Editor/Pipeline process identity remains unchanged immediately before dispatch. Shutdown now waits for the configured graceful timeout and accepts a nonzero CLI response only when process verification confirms the Editor exited, since the Pipeline server can disconnect before returning a valid response.
+- Propagated cancellation through capability probes and multi-process termination so cancellation prevents later lifecycle actions.
+
+## [0.7.1] - 2026-07-10
+
+### Changed
+
+- Migrated Pi extension imports and peer dependencies to the `@earendil-works` package scope.
+
+### Fixed
+
+- Recognize Windows-style absolute Unity project paths with Windows path semantics when status output is validated on another operating system.
+
+## [0.7.0] - 2026-07-09
+
+### Added
+
+- Added `unity_run_test_batch` for one-platform Unity Test Framework batches with normalized filter/category arrays, collision-safe absolute XML/log paths under project `Logs`, and the existing guarded Unity launcher on Windows and macOS.
+- Added Windows CI alongside the existing macOS package validation workflow.
+
+### Changed
+
+- Added Unity validation scope and stop guidance so explicit PlayMode skips are honored, compile/EditMode and optional PlayMode evidence are distinguished, and unchanged infrastructure failures are inspected once using exact current-run artifact paths rather than retried in launch loops.
+- Refactored generic batchmode and test-batch execution through one project-mutex, process-authorization, lockfile, launcher, and artifact-reporting path; cancellation now stops before forced-close fallback, while any completed closure is journaled into subsequent errors.
+
+### Fixed
+
+- Prevent Unity Test Framework runs with zero executed tests or requested but missing/unparseable result XML from being labeled passed, and make artifact inspection fail clearly when no requested evidence is available.
+- Keep raw Unity XML/log/stdout/stderr evidence on disk instead of duplicating unbounded content into session details; retain paths, byte counts, parsed results, and bounded excerpts.
+- Signal failed Unity batches and failed artifact inspections through thrown tool errors instead of unsupported `isError` return fields.
+
+## [0.6.0] - 2026-07-09
+
+### Changed
+
+- Hardened same-project Unity process matching to parse only exact `-projectPath` arguments, use platform-correct path identity, and avoid treating unrelated Unity CLI status fields as project paths.
+- Revalidate the Unity executable, project argument, PID, and command line immediately before guarded OS-level termination so recycled PIDs are skipped.
+- Added macOS CI coverage for tests and package validation.
+- Updated `unity_launch_batchmode` to add `-nographics` by default, with an explicit `useGraphics` opt-in for screenshots, visual capture, render checks, or graphics-dependent PlayMode tests.
+- Updated Unity batchmode skill and README guidance to steer agents toward no-graphics validation unless the requested work requires graphics.
+
+## [0.5.0] - 2026-06-28
+
+### Added
+
+- Added `piUnity.allowCloseRunningUnityProcess` settings support so `unity_launch_batchmode` can close same-project blocking Unity processes only when explicitly enabled and requested with `closeBlockingUnityProcess`.
+- Added `piUnity.closeRunningUnityProcessOnlyForTests` and `piUnity.closeRunningUnityProcessTimeoutMs` safeguards for constrained Unity process closure.
+
+### Changed
+
+- Updated guarded process closing to request graceful Editor exit through `unity eval 'UnityEditor.EditorApplication.Exit(0);'` before falling back to OS-level process termination.
+- Updated guarded process closing to clean up the exact resolved project's stale `Temp/UnityLockfile` only when pi-unity closed the matching Unity process in the same batchmode call and verifies no matching process remains.
+- Updated Windows process termination to retry `taskkill` with `/F` only when Windows reports that force is required.
+- Updated `unity_project_status`, README, and batchmode skill guidance to surface the new guarded process-closing settings.
+- Updated the interactive Unity project picker so up/down navigation wraps between the first and last workspace options.
+
+## [0.4.0] - 2026-06-27
+
+### Added
+
+- Added `unity_inspect_artifacts` to summarize existing Unity Test Framework XML results and Unity logs without launching Unity.
+
+### Changed
+
+- Updated Unity batchmode skill guidance to prefer `unity_inspect_artifacts` over ad hoc shell parsing after Unity failures.
+
+## [0.3.0] - 2026-06-27
+
+### Added
+
+- Added `unity_project_status` to inspect Unity native lockfile state, Unity CLI status, and running project processes without launching Unity.
+
+### Changed
+
+- In Unity CLI launcher mode, `unity_launch_batchmode` now delegates stale native `Temp/UnityLockfile` handling to `unity run` after verifying no running project process is active, while keeping direct Editor executable launches blocked by native lockfiles.
+- Tightened screenshot skill guidance so agents load it only when screenshot evidence is requested or required by project/review workflow.
+
+## [0.2.0] - 2026-06-16
+
+### Added
+
+- Added Unity CLI integration so `unity_open_editor` prefers `unity open` and `unity_launch_batchmode` prefers `unity run` when the installed `unity` command is available.
+- Added Unity CLI status parsing for safer same-project busy checks before launching GUI or batchmode Unity.
+- Added `UNITY_CLI_PATH` support for overriding the Unity CLI executable.
+- Added `launcher` selection (`auto`, `unity-cli`, `editor-executable`) so workflows can bypass Unity CLI when forwarded arguments differ from direct Editor executable behavior.
+- Added Unity CLI argument normalization that strips direct-Editor flags managed by `unity run` (`-batchmode`, `-projectPath`, `-quit`) before forwarding user args.
+- Added unit coverage for Unity CLI command construction, forwarded-argument normalization, and status parsing.
+
+### Changed
+
+- Kept direct Unity Editor executable launch as a fallback when Unity CLI is unavailable or cannot resolve the environment.
+- Updated Unity batchmode skill and README guidance to document the Unity CLI preferred path and fallback behavior.
+
+## [0.1.0] - 2026-04-27
+
+### Added
+
+- Initial Pi Unity package with Unity Editor GUI launch, batchmode execution, Unity Test Framework summary parsing, project discovery, single-project process safeguards, and screenshot workflow guidance.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron Freedman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,197 @@
+# Pi Unity
+
+Pi skill and tool package for reusable Unity workflows.
+
+## Contents
+
+- skill: `unity-debugging`
+- skill: `unity-pipeline-workflows`
+- skill: `unity-batchmode-tests`
+- skill: `unity-interactive-playmode-authoring`
+- skill: `auditing-unity-agent-guidance`
+- tool: `unity_guidance_audit`
+- tool: `unity_project_status`
+- tool: `unity_pipeline_recompile`
+- tool: `unity_pipeline_run_tests`
+- tool: `unity_pipeline_eval`
+- tool: `unity_pipeline_inspect`
+- tool: `unity_inspect_artifacts`
+- tool: `unity_open_editor`
+- tool: `unity_launch_batchmode`
+- tool: `unity_run_test_batch`
+- commands: `/unity-open`, `/unity-playmode-exit`
+
+## Skill boundaries
+
+Each packaged skill owns a distinct kind of Unity work:
+
+- `unity-debugging` owns reusable diagnostic strategy across Editor, runtime, package, asset, lifecycle, callback, and feature-activation problems.
+- `unity-pipeline-workflows` owns connected compilation and focused test execution through an already-running exact-copy Pipeline Editor.
+- `unity-batchmode-tests` owns isolated or report-producing Unity Test Framework execution.
+- `unity-interactive-playmode-authoring` owns explicit temporary inspection and tuning of live runtime state, followed by deliberate persistence when requested.
+- `auditing-unity-agent-guidance` owns review and migration of project-local Unity automation instructions.
+
+Operation-specific failure handling remains with the owning operational skill. `unity-debugging` owns reusable diagnostic strategy, not every troubleshooting instruction associated with Unity operations.
+
+## Install
+
+From GitHub:
+
+```bash
+pi install git:git@github.com:aefreedman/pi-unity.git
+```
+
+Local development install:
+
+```bash
+pi install <path-to-pi-unity>
+```
+
+Project-local install:
+
+```bash
+pi install -l <path-to-pi-unity>
+```
+
+## Notes
+
+- Pi discovers packaged skills from `skills/` and extensions from `index.ts`.
+- `unity-debugging` provides general-purpose, evidence-first Unity diagnosis. For inactive features it routes agents through exact-version documentation, documented feature gates, and observable activation signals before project code, reflection, assembly searches, or Unity internals. Its UI Toolkit example checks the Game View Live Reload setting before callback diagnosis.
+- `@aefree/pi-project-artifacts` and `@aefree/pi-file-discovery` are independent optional peer integrations. When their Pi tools are active, pi-unity uses the capability contracts' global registry rendezvous to register a Unity solution-artifact profile candidate and/or generated-directory file-discovery filter. It never resolves optional peers from pi-unity's own module root, so separately installed Git/local packages compose correctly. Core Unity tools load without them; an advertised malformed registry contract fails visibly. Registrations are scoped, reverse-load-order safe, transactional across active integrations, and a delayed old-session shutdown cannot remove another scope's current records. Project artifacts remains schema-open: the Unity profile contributes applicability, definitions, validation, and confidence only; Unity metadata remains raw-filterable when this provider is absent. Provider development follows the [project-artifacts profile-provider contract](https://github.com/aefreedman/pi-project-artifacts/blob/main/docs/artifact-profile-providers.md).
+- The Unity filter recommends excluding `Library`, `Temp`, `Logs`, `obj`, `Build`, `Builds`, `UserSettings`, and `.vs` from broad project-root discovery. Broad exclusions declare `filterDecision: "applied"` with decision code `unity_broad_generated_directories_applied`; an exact generated or `Library/PackageCache/...` root is searched with the explicit `filterDecision: "bypassed"` code `unity_exact_generated_root_bypassed`, rather than a compatibility sentinel glob. File-discovery filter failures degrade discovery filtering rather than authorizing or blocking inspection; the canonical file-discovery package remains Unity-neutral.
+- The optional artifact profile describes `engine`, `unity_version`, `unity_packages`, `render_pipeline`, and `platforms` for solution and memory artifacts. Every field is optional; present fields receive type/enum validation while undeclared project metadata remains open. Artifact paths already distinguish solutions from memories, and evolving project vocabulary belongs in generic `tags`, `module`, or `component` fields rather than a Unity-owned document taxonomy. The profile contributes only when the workspace has Unity `ProjectVersion.txt` evidence, so a conventional artifact path never selects it by itself.
+- `unity_guidance_audit` performs a bounded, read-only scan of AGENTS.md, CLAUDE.md, Copilot, and Cursor guidance for outdated Unity CLI/Pipeline, batchmode, test, lifecycle, and exact-project-copy instructions. The `auditing-unity-agent-guidance` skill owns contextual migration and user-authorized edits.
+- `unity_open_editor` launches the full Unity Editor GUI.
+- `unity_open_editor` prefers the installed `unity open` CLI when available, falling back to direct editor executable launch.
+- `unity_project_status` reports native Unity lockfile state, Unity CLI status output, running Unity processes, the locally declared `com.unity.pipeline` version, exact-project-copy Pipeline instances, and bounded live advertised commands without launching Unity. Pipeline discovery has distinct `absent`, `timeout`, and `unavailable` states; a timeout is startup uncertainty rather than proof of absence. Rendered process command lines redact access tokens and credential-like values.
+- `unity_inspect_artifacts` summarizes existing Unity Test Framework XML results and Unity logs without launching Unity, reducing ad hoc shell parsing after failures.
+- Planning and test routing preserve the exact project copy: a reachable Pipeline Editor is a positive connected inspection surface, and the project should run connected tests without closing the Editor or replacing it with a second Editor. Other connected operations use that same exact copy. `unity_pipeline_eval` rechecks canonical identity and advertised `eval` immediately before dispatch and is the general REPL escape hatch for project-specific properties and questions that registered commands did not anticipate. `unity_pipeline_inspect` exposes the package-owned purpose-built inspection commands when their structured results fit the question. Tooling should bound the request and result, preserve exact-copy evidence, and distinguish reads from mutations—not maintain a brittle API-property allowlist or pretend arbitrary C# can be proven read-only from syntax alone.
+- `unity-pipeline-workflows` routes focused connected work through `unity_pipeline_recompile` and `unity_pipeline_run_tests`. Each performs exact-copy preflight, advertised-command checks, lifecycle inspection, identity-aware bounded internal polling, and compact output in one model-visible call. `unity_pipeline_recompile` never preemptively sends `editor_stop`: while Play Mode is active it honors Unity's Script Changes While Playing policy (continue, stop-and-recompile, or defer) when future `editor_status` payloads expose it, and reports unavailable policy as uncertainty. Connected tests retain a separate explicit lifecycle guard. Pipeline `no_tests`/idle status is treated as safe pre-dispatch inactivity rather than uncertainty. Timeouts are uncertain and do not cancel, retry, close Unity, or switch to batchmode. Connected tests do not inherently produce NUnit XML.
+- `unity_run_test_batch` is the preferred isolated/report-producing Unity Test Framework entry point, not a reason to close a reachable Pipeline Editor. Choose it for a closed project, intentional CI isolation, category/multiple filters unsupported by the single connected test-name filter, or required NUnit XML/log artifacts. It runs exactly one EditMode or PlayMode batch, combines filter/category arrays into one launch, creates collision-safe absolute XML/log paths under the project `Logs` directory, omits `-quit`, and uses the same guarded launcher as `unity_launch_batchmode`.
+- `unity_launch_batchmode` prefers the installed `unity run` CLI when available, falling back to direct editor executable batchmode launch; use it when custom raw Editor arguments are required.
+- `unity_launch_batchmode` adds `-nographics` by default to avoid unnecessary graphics initialization and reduce focus stealing; set `useGraphics: true` only for screenshots, visual capture, render checks, or graphics-dependent PlayMode tests.
+- Unity GUI, generic batchmode, and test-batch tools expose `launcher` (`auto`, `unity-cli`, or `editor-executable`) so workflows can force direct Editor execution when Unity CLI argument handling differs from `Unity.exe`/`Unity`. Every launch route keeps same-project process verification and a per-project mutex; unknown process state blocks launch. Direct Editor execution blocks native lockfiles, while Unity CLI may handle a stale lockfile only after pi-unity verifies no matching project process.
+- In Unity CLI mode, `unity_launch_batchmode` forwards args after `unity run <project> --` and strips direct-Editor flags managed by the CLI (`-batchmode`, `-projectPath`, `-quit`).
+- `unity_run_test_batch`, `unity_launch_batchmode`, and `unity_inspect_artifacts` require parsed Unity Test Framework results to report a known positive executed-test count and no failures before treating them as passing evidence. Zero-test, unknown-total, missing-result, malformed-result, and failing batches are non-passing; full artifacts remain on disk while session details retain bounded excerpts and byte counts.
+- Validation guidance treats explicit user/project PlayMode skips as authoritative, distinguishes baseline compile/EditMode evidence from optional PlayMode evidence, and stops unchanged relaunch loops after hangs or infrastructure failures in favor of one inspection of the exact current-run artifact paths.
+- `unity_launch_batchmode` uses Unity CLI status and direct process scans before launch. In Unity CLI mode, stale native `Temp/UnityLockfile` detection is delegated to `unity run`; direct Editor executable mode still blocks on the native lockfile for safety. A Pi-side project mutex prevents duplicate packaged batchmode calls from spawning Unity concurrently.
+- `unity_launch_batchmode` can close a same-project blocking Unity process only when isolated execution was deliberately selected, the tool call sets `closeBlockingUnityProcess: true`, and Pi settings enable `piUnity.allowCloseRunningUnityProcess`. Do not use this to replace reachable connected Pipeline testing. The tool re-scans and selects matching Unity processes itself; it never accepts a model-supplied PID.
+- After a guarded same-call close, `unity_launch_batchmode` may remove the exact resolved project's stale `Temp/UnityLockfile` only after verifying no matching Unity process remains. It still refuses general lockfile deletion outside that guarded continuation.
+- When using `closeBlockingUnityProcess: true`, prefer `launcher: "auto"` or `launcher: "unity-cli"`; force `launcher: "editor-executable"` only when direct Editor execution is explicitly required.
+- If a Unity launch is blocked by a lockfile, run `unity_project_status` before asking a user to remove anything.
+- `/unity-open` is the user-facing GUI launcher helper.
+- The package resolves Unity project copies from a direct project root, a coordination root containing multiple copies, or another nearby folder. Pipeline routing validates canonical project-path identity after CLI discovery so similarly named copies are not treated as interchangeable; connected commands always receive the exact resolved project path.
+- Installing and starting `com.unity.pipeline@0.3.1-exp.1` is a broader project mutation than adding its manifest entry: its server startup assigns `Application.runInBackground = true`, which Unity persists as `PlayerSettings.runInBackground` in `ProjectSettings/ProjectSettings.asset`. Review that tracked change alongside `manifest.json` and `packages-lock.json`.
+- Unity install probing is OS-aware and avoids machine-specific assumptions by using the project's `ProjectSettings/ProjectVersion.txt`, the optional `unity` CLI, standard per-OS install locations, and optional `UNITY_EDITOR_PATH` overrides.
+- Unity allows only one process per project folder; GUI and batchmode both count.
+- The `unity-batchmode-tests` skill is intended for Unity Test Framework CLI runs.
+- Keep skill-specific references and helper assets under the skill directory beside `SKILL.md`.
+
+## Connected Pipeline and `eval` policy
+
+Registered Pipeline commands are ergonomic shortcuts for anticipated workflows. Advertised `eval` covers the operations and inspections that were not anticipated: it compiles C# with Roslyn, runs it on the connected Editor's main thread, and returns the result. This is a live REPL into the exact running project, not merely a restricted planning expression evaluator.
+
+Use the registered `unity_pipeline_eval` tool with bounded C# `code`, for example:
+
+```text
+{ code: "return UnityEditor.EditorSettings.scriptChangesDuringPlay;" }
+{ code: "var s = UnityEngine.Application.dataPath; return s.Length;" }
+```
+
+Use `unity_pipeline_inspect` for purpose-built connected reads such as `editor_status` or `get_scene_hierarchy`; eval is intentionally owned only by `unity_pipeline_eval`.
+
+Because `eval` reaches the same engine and Editor APIs as project code, its security token and exact-copy identity are meaningful trust boundaries. A static snippet allowlist is not: ordinary property getters can call code, while apparently simple expressions can still have side effects. Pi-unity therefore treats declared task intent as the boundary: regular inspection through `unity_pipeline_eval` is allowed; mutations must match the user's request; lifecycle, destructive, persistent-setting, asset, scene-save, package, build, and test changes require the same explicit authorization they would through a typed command. Typed tools remain preferred when they provide better validation, polling, compact evidence, or recovery semantics, but they are assistance rather than exclusive gateways. Results and diagnostics remain bounded, and an uncertain dispatch is never silently retried through another route.
+
+## Settings
+
+`pi-unity` reads optional package-specific settings from global `~/.pi/agent/settings.json` and, for trusted projects, project `.pi/settings.json`:
+
+```json
+{
+  "piUnity": {
+    "allowCloseRunningUnityProcess": false,
+    "closeRunningUnityProcessOnlyForTests": true,
+    "closeRunningUnityProcessTimeoutMs": 30000
+  }
+}
+```
+
+- `allowCloseRunningUnityProcess` defaults to `false`. When enabled, `unity_launch_batchmode` may close only Unity processes that target the resolved project and only when the tool call explicitly sets `closeBlockingUnityProcess: true`.
+- `closeRunningUnityProcessOnlyForTests` defaults to `true`, limiting process closure to Unity Test Framework launches (`-runTests`).
+- `closeRunningUnityProcessTimeoutMs` defaults to `30000` and is clamped between 1000 and 120000 milliseconds.
+
+Autonomous Play Mode exit is a separate session-scoped toggle and defaults to disallowed. Use `/unity-playmode-exit allow` only to authorize package-owned typed lifecycle operations that may exit Play Mode, `/unity-playmode-exit disallow` to restore the default, or `/unity-playmode-exit status` to inspect it. `unity_pipeline_recompile` never sends `editor_stop` and does not override Unity's Script Changes While Playing preference: a known continue/defer policy needs no exit authorization, a known stop-and-recompile policy does, and a missing policy is conservatively treated as potentially exiting. `unity_pipeline_run_tests` retains its separate verified `editor_stop` lifecycle path when authorized. The choice is recorded in the current session branch so it survives reload/resume, but it is not a global or project setting. Output/details identify explicit agent exit separately from Unity-policy-driven or unavailable-policy behavior; pi-unity never enters Play Mode autonomously.
+
+## Skill evaluation
+
+The `auditing-unity-agent-guidance` skill has an opt-in behavioral eval under `evals/auditing-unity-agent-guidance/`. It runs isolated fixtures through Pi, checks triggering, filesystem outcomes, instruction fidelity, and tool-call efficiency, and can compare skill-enabled runs with a no-skill baseline. Because it invokes an agent and may incur provider costs, it is not part of `npm test`.
+
+```bash
+npm run eval:guidance-skill -- --cases audit_legacy_instructions,migrate_mixed_harness_guidance,unrelated_typescript_review
+npm run eval:guidance-skill -- --condition both --trials 3
+```
+
+See `evals/auditing-unity-agent-guidance/README.md` for the rubric.
+
+## Package layout
+
+```text
+pi-unity/
+  index.ts
+  src/
+    unity-core.ts
+    unity-batchmode.ts
+    unity-cli.ts
+    unity-launch.ts
+    unity-processes.ts
+    unity-project-lock.ts
+    unity-projects.ts
+  skills/
+    unity-debugging/
+      SKILL.md
+    auditing-unity-agent-guidance/
+      SKILL.md
+      references/
+      assets/
+    unity-pipeline-workflows/
+      SKILL.md
+    unity-batchmode-tests/
+      SKILL.md
+  tests/
+```
+
+## Optional artifact metadata
+
+When `@aefree/pi-project-artifacts` is also active in a Unity workspace, solution and memory Markdown may use the following profile-enriched fields:
+
+```yaml
+---
+engine: unity
+unity_version: "6000.0"
+unity_packages:
+  - com.unity.inputsystem
+render_pipeline: urp
+platforms:
+  - windows
+  - android
+---
+```
+
+Supported `render_pipeline` values are `builtin`, `urp`, `hdrp`, `custom`, and `agnostic`. Keep `unity_version` quoted because Unity versions are identifiers rather than numeric values. Omit inapplicable fields instead of adding placeholders. These fields improve exact retrieval and diagnostics but are not required for indexing or raw filtering.
+
+## Testing
+
+```bash
+npm test
+npm pack --dry-run
+```
+
+The package declares optional peer integrations for `@aefree/pi-project-artifacts` and `@aefree/pi-file-discovery`; install only the integrations needed for artifact profiles or file-discovery filtering. The standalone Unity tools and skills do not require them. The package archive contains no copied dependency tree, sibling `file:` path, or workspace link.
+
+## Release status
+
+A registry-clean `package-lock.json` is committed, optional development packages resolve from the public registry, and the manifest is prepared for public scoped publication. Publishing remains a separate manual operation requiring npm authentication and explicit authorization.
+
+## License
+
+MIT. See `LICENSE`.