@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/skills/unity-pipeline/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: unity-pipeline
+description: Control a Unity Editor or Player via the unity-pipeline package. Compile, run tests, eval, method-reload code, enter Play Mode, capture screenshots.
+---
+
+# Unity Pipeline (agent control)
+
+Invoke commands with `unity command <group> <name> [args]`. `unity command` lists the command
+groups, `unity command <group>` one group's commands, and `--query <term>` filters by name,
+description or tag. Two servers exist: **Editor** (`7800-7849`, auto-starts with the editor) and
+**Runtime** (`7900-7949`, only in a dev Player build).
+
+## 1. Install & verify
+
+```bash
+unity pipeline install            # install into current project (or --project-path)
+unity pipeline list               # confirm the editor instance + server are reachable
+unity status --until-ready        # wait until the editor server is ready
+unity command editor status       # confirm the editor server answers
+```
+
+An Editor that was already open picks up the package only on its next refresh, usually when its
+window regains focus. Until then `unity status` reports `STATUS_PIPELINE_LOAD_PENDING`; if that
+persists, ask the user to switch to the Unity Editor window, then re-run `unity status --until-ready`.
+
+## 2. Autonomous edit loop (Editor)
+
+This is the core agent workflow: keep the editor alive, change code, recompile, test.
+
+```bash
+# 1. Keep the editor ticking even when unfocused/minimized. REQUIRED before headless work —
+#    Unity otherwise throttles or stalls update/compile when it isn't the active app.
+unity command editor set_auto_tick --enabled true
+
+# 2. Edit C# source files on disk normally.
+
+# 3. Recompile (async: triggers a domain reload, then poll until done).
+unity command script recompile
+unity command script recompile_status    # repeat until "completed" or "up_to_date"
+#   Tolerate connection errors while the domain reload is in flight — that is expected.
+#   If script recompile_status reports failed=true, read its "errors" array and fix before testing.
+
+# 4. (Optional) List available tests without running them.
+unity command test list --mode editor            # mode: all | editor | playmode
+
+# 5. Run tests (filter to keep it fast).
+unity command test run --mode editor --filter MyFixture.MyTest
+```
+
+`filter-type`: `testName` | `assembly` | `category`. For long runs use `--async-tests true` and
+poll `unity command test status` (abort with `test cancel`). When a selected test *fails*, `test run`
+may return an opaque result: re-run a narrower `--filter`, or inspect the Test Runner / logs.
+
+**Reading exit codes.** They separate "rewrite the invocation" from "the Editor failed", which
+is the distinction this loop depends on:
+
+| Exit | Meaning | What to do |
+|------|---------|------------|
+| `2` | Bad arguments — a misspelled flag, a wrong type, too many positionals. Nothing ran. | Fix the command line and retry. The error names the problem and often suggests the right flag. |
+| `6` | The command ran and failed, or no Editor could be reached. | Read the error. If it says no Pipeline instance was found, the Editor isn't reachable: wait with `unity status --until-ready` (or check `unity pipeline list` for Safe Mode), then retry. Otherwise retrying the same invocation will not help. |
+
+Do not retry an exit 2 unchanged, and do not rewrite a command line on an exit 6.
+
+## 3. Runtime method reload
+
+Change gameplay code in a **running** game with no domain reload. The game must be live:
+enter Editor Play Mode (`unity command editor.playmode start`) or run a dev Player. The runtime Pipeline driver (enabled via Project Settings > Pipeline > Runtime) auto-discovers tagged methods on `Awake` (no manual
+registration). Mono only — Editor Play Mode and Mono desktop dev builds, not IL2CPP. The token
+is auto-injected for local requests.
+
+### `script.methodreload reload`
+
+Edit the method body directly; no separate file, no boilerplate.
+
+1. **Before entering Play Mode**, tag the method `[MethodReload]` on the MonoBehaviour and recompile.
+   The reload hook is compiled into the method, so tagging it while the game runs has no effect:
+   exit Play Mode, recompile, and enter it again.
+2. With the game running, edit the method body on disk.
+3. Apply (re-run to iterate):
+   ```bash
+   unity command script.methodreload reload --filename Assets/Spinner.cs
+   ```
+   Add `--pdb` to debug it: it emits a portable PDB mapped to your source so breakpoints bind
+   (attach the IDE + enable Editor Attaching; compiles unoptimized). Without it, no symbols.
+
+Constraints: `void` instance methods only; **public** members only.
+
+`unity command script.methodreload status` shows active overrides. `reload` options: `--timeout
+<seconds>` (default 60; the CLI's `--timeout` is the command's own), `--assembly-dir <dir>` (persist
+DLLs instead of in-memory); `script.methodreload cleanup --assembly-dir <dir>` clears old DLLs.
+
+## 4. Bulk construction: `script run` (the builder pattern)
+
+For bulk work — creating many objects, wiring fields, generating content — put the code in a
+**versioned project script** and run a named static entry point with `script run`. No domain
+reload, no code carried through the protocol; iterating costs an in-memory compile (< ~2s), not
+a 15–20s recompile.
+
+```bash
+# 1. Write the builder OUTSIDE Assets/ (so the write triggers no asset import / domain reload),
+#    e.g. AgentScripts/Build.cs:  public static class Build { public static int All() { ... } }
+# 2. Run it — relative paths resolve against the project root (the parent of Assets/):
+unity command script run --file AgentScripts/Build.cs --entry Build.All
+# 3. Iterate: edit the file, re-run. Useful extras:
+unity command script run --file AgentScripts/Build.cs --dry-run true   # compile-only check: diagnostics, nothing loaded or executed
+unity command script run --file AgentScripts/Build.cs --entry Build.All --args '[3, "Green"]'
+```
+
+Rules of thumb:
+
+- **Code goes in files on disk.** Never ship multi-line escaped C# strings through `script eval`:
+  write the file, then run it with `script run` (a named entry point, with arguments) or
+  `script eval --file` (a script: `using` lines, declarations, `await`; see §5).
+- Compiles see the project's **active editor defines** (`UNITY_EDITOR`, version/platform symbols);
+  `--defines` appends extra symbols on top.
+- Entry points may be `async Task`/`Task<T>` — they are awaited asynchronously (the editor keeps
+  pumping, so awaits resuming on Unity's context work naturally) and `Task<T>.Result` is returned.
+  The wait is bounded by `--timeout` (seconds, default 60); on expiry the task keeps running detached.
+- Runtime exceptions come back with `file:line` mapped to your source (a source-mapped PDB is
+  always emitted for executing runs; they compile unoptimized).
+- `--mode hotpatch` instead applies `[MethodReload]` in-place method replacements (delegates to
+  `script.methodreload reload`); `entry`/`args`/`dry-run` are rejected there and `references`/`defines` don't apply.
+
+## 5. C# eval (Editor or dev Player)
+
+`script eval` syntax (inline, `--file`, `--runtime`, `--auto-import`, `--internals`) plus `Wait.*` and its error codes: [csharp-eval.md](references/csharp-eval.md).
+
+## 6. Play Mode vs. Multiplayer Play Mode (MPPM) scenarios
+
+Single-player Play Mode, MPPM Play Mode Scenarios with virtual-player clones, and Multiplayer Roles. Read before entering Play Mode in a multiplayer project: [multiplayer-play-mode.md](references/multiplayer-play-mode.md).
+
+## 7. Screen capture (Editor)
+
+Capture a view to a PNG to check a visual result.
+
+```bash
+unity command capture game_view --output-path Screenshots/hud.png   # what the Game window shows, incl. overlay UI
+unity command capture scene_view --max-resolution 512             # the scene only (camera render), inline, longest edge capped
+unity command capture scene_view --source screen --output-path Screenshots/scene.png   # the Scene window with grid, gizmos, toolbars
+unity command capture editor_window --window Inspector --output-path Screenshots/inspector.png   # any open Editor window
+```
+
+Without `--output-path` the image comes back inline (base64); `--include-inline-image true` gives
+both. A relative path resolves from the project root (no `.meta` outside `Assets/`). `game_view`
+opens a Game view if none is showing, in batchmode too. `game_view --source camera --camera <name>`
+renders one camera; overlay UI is drawn on URP/HDRP (`--overlay auto|true|false`), not on Built-in.
+`editor_window` and `scene_view --source screen` briefly front a background tab and don't work in
+batchmode. `capture screenshot` is deprecated. On 6000.7+, `capture editor_element` /
+`runtime_element` capture one UI Toolkit element by `--selector`.
+
+## Gotchas
+
+- **A stuck command may mean a modal dialog is open**, not a hang — a dialog blocks the main
+  thread until dismissed. If a command runs long, check `unity command editor status` (answers
+  instantly even when blocked); `status: "blocked_by_dialog"` means stop retrying and tell the
+  human what's blocking (its `dialog.title`/`message`/`buttons`) — it can't be clicked over CLI.
+- **Player-only commands need a dev Player.** `console write`, `runtime set_time_scale`, `runtime status`, etc. hit
+  the Runtime server, which does not run in the Editor.
+- **Target a specific instance** when more than one is running: `--project-path <path>` selects an
+  Editor, `--runtime <process name>` or `--runtime-path <port file>` selects a dev Player.
+
+## Final checks
+
+1. Check that the project has zero console errors:
+   ```bash
+   unity command console status              # groundTruth.consoleErrors must be 0, compilationFailed false
+   unity command console get --level error   # read any errors it reports
+   ```
+2. If you changed runtime behaviour, enter Play Mode (`unity command editor.playmode start`), exercise
+   the change, and read back the `Debug.Log` lines you added with `unity command console get`. Confirm
+   they show the fix works, then stop Play Mode and remove those lines unless the user wants them kept.
+3. If the fix doesn't work, go back and reread the relevant [Topic map](#topic-map) pages before you
+   try again, rather than retrying from memory.
+
+## Final report
+
+End with a short report to the user:
+
+- What you changed, by file, and the commands that verified it (test results, console status).
+- Side effects: auto tick left on, Play Mode or a scenario still running, files written outside
+  `Assets/` (such as `AgentScripts/` or screenshots), method-reload overrides still active.
+- Anything the user must do or decide next, such as a failure you could not fix or a dialog only
+  they can dismiss.
+
+## Topic map
+
+The Pipeline package ships its documentation in its `Documentation~` folder. For a registry install
+that is `<project>/Library/PackageCache/com.unity.pipeline@*/Documentation~/`; the same pages are
+published at `https://docs.unity3d.com/Packages/com.unity.pipeline@<VERSION>/`. Only read what you need.
+
+Prefer the local copy: it matches the installed package. For the live pages, fetch the exact URL
+rather than searching; `<VERSION>` is the major.minor of `com.unity.pipeline` in
+`Packages/packages-lock.json`, e.g. `@0.9`.
+
+| Topic | Page |
+|-------|------|
+| Connecting to an Editor or Player, ports, `--project-path` | `connectivity.md` |
+| Dev Player and Runtime server setup | `runtime-setup.md` |
+| Method reload (`[MethodReload]`, `script.methodreload`) | `method-reload.md` |
+| `script run`, `script eval`, `script recompile` | `commands/scripts.md` |
+| Compiling and running tests | `commands/build-and-compilation.md` |
+| `editor status`, `editor set_auto_tick`, modal dialogs | `commands/editor-lifecycle-and-observability.md` |
+| Play Mode scenarios, virtual players, clones | `commands/multiplayer-play-mode.md` |
+| Screen capture | `commands/capture.md` |
+| `console get` / `console status`, Runtime commands | `commands/runtime.md` |

package/skills/unity-pipeline/references/csharp-eval.md

@@ -0,0 +1,23 @@
+# 5. C# eval (Editor or dev Player)
+
+`script eval` compiles C# as a script: `using` lines, top-level methods and types, and `await`. The
+value of `return x;` or of a trailing expression is the result. It targets the Editor by default;
+add `--runtime <process name>` to run it in a dev Player. Put anything longer than a line or two in
+a file.
+
+```bash
+unity command script eval --caller plugin --skill unity-pipeline "return 2 + 2;"
+unity command script eval --caller plugin --skill unity-pipeline "return UnityEngine.Time.timeScale;" --runtime MyGame
+# A .cs file on disk. Keep it outside Assets/, where Unity would compile it as project source:
+unity command script eval --caller plugin --skill unity-pipeline --file AgentScripts/Scratch.cs
+unity command script eval --caller plugin --skill unity-pipeline --file AgentScripts/Scratch.cs --dry-run          # compile only
+unity command script eval --caller plugin --skill unity-pipeline "return EditorSceneManager.GetActiveScene().name;" --auto-import   # adds missing usings
+unity command script eval --caller plugin --skill unity-pipeline "return UnityEditor.LogEntries.GetCount();" --internals             # Editor internal APIs
+```
+
+- `await Wait.Until(() => condition)` waits without blocking the Editor; `Wait.For(asyncOperation)`
+  and `Wait.ForImport(assetPath)` cover operations and imports. Submit a long wait with `--detach`,
+  then `unity job wait <job-id>`.
+- A failed eval exits 6 with an `errorCode`: `COMPILATION_ERROR` (each error with its line and
+  column), `RUNTIME_EXCEPTION` (exception and stack trace), `TIMEOUT` or `INVALID_COMMAND_ARGS`.
+- `script eval_file` is deprecated; use `script eval --file`.

package/skills/unity-pipeline/references/multiplayer-play-mode.md

@@ -0,0 +1,103 @@
+# 6. Play Mode vs. Multiplayer Play Mode (MPPM) scenarios
+
+These are two different things — do not conflate them.
+
+## Single-player: normal Play Mode (main Editor only)
+
+```bash
+unity command editor.playmode start    # enter Play Mode
+unity command editor.playmode pause    # toggle pause
+unity command editor.playmode stop     # exit Play Mode
+```
+
+`editor.playmode start` runs the main Editor's **open scene** in Play Mode: **one** instance, never
+MPPM virtual players, even if configured. Use it for single-instance testing and method reload.
+
+## Multiplayer: Play Mode Scenarios (main Editor + virtual players)
+
+A **Play Mode Scenario** is an asset (an `OrchestratedScenario`, e.g.
+`Assets/Settings/PlayMode/2Players.asset`) describing the main Editor plus one or more virtual
+players. Each virtual player (clone) is a **separate Unity project** at
+`<project>/Library/VP/<vpId>` with its **own Library, port, and Pipeline server** — not a second
+window of the main Editor. Run a scenario with the scenario commands (they drive MPPM's
+`PlayModeScenarioManager`, which enters Play Mode itself), never with `editor.playmode start`,
+which fights MPPM's play-mode guard:
+
+```bash
+unity command editor.playmode list_scenarios         # discover scenario assets
+unity command editor.playmode list_players # players the active scenario declares
+unity command editor.playmode set_active_scenario --path Assets/Settings/PlayMode/2Players.asset
+unity command editor.playmode start_scenario        # run the active scenario
+unity command editor.playmode get_scenario_status       # live scenario + play-mode state
+unity command editor.playmode stop_scenario         # stop it
+```
+
+Authoring the asset (Edit Mode):
+
+```bash
+unity command editor.playmode create_scenario --name MyScenario # auto-adds the Main Editor player
+unity command editor.playmode add_player --path Assets/Settings/PlayMode/MyScenario.asset --type clone --name "Player 2"
+unity command editor.playmode remove_player --id <playerId> --path Assets/Settings/PlayMode/MyScenario.asset --confirm true  # id: GUID on 6000.5+, player name on 6000.3/6000.4
+```
+
+MPPM has four player slots, and slot 0 (`Player 1`) is always the Main Editor. A scenario therefore
+holds at most **3 clones** (`Player 2`–`Player 4`): a 4-player scenario is the Main Editor plus 3 clones,
+and a fourth clone is refused. For more players, add built players with `--type local`.
+
+The `editor.playmode` scenario commands need **Unity 6000.3+** *and* the `com.unity.multiplayer.playmode`
+package. Without both they are compiled out and calling one fails as an unknown command, so run
+`unity command editor.playmode` and check that `start_scenario` and the other scenario commands are listed
+before using them. The group itself always exists: `editor.playmode list_instances` needs neither
+and always works. You may only `editor.playmode set_active_scenario` while state is **Idle**.
+
+Player editors launch **asynchronously**, so after `editor.playmode start_scenario` poll
+`editor.playmode get_scenario_status`. Its `players` array has one entry per player the scenario declares — not
+MPPM's fixed four slots — and each entry carries both `state` (`NotLaunched` / `Launching` /
+`Launched` / `UnexpectedlyStopped`) and, once that player's Editor is up, `reachable: true` with the
+`port` and `projectPath` you need to drive it. Wait for `reachable`, then address it with
+`--project-path`. Watch `state` to tell a slow launch (`Launching`) from a dead one
+(`UnexpectedlyStopped`) — a missing descriptor alone cannot distinguish those.
+
+## Discovering and driving the clones
+
+The CLI folds a project's own clones into its main Editor, so a running scenario adds no
+ambiguity by itself. But with another Unity project open, `unity command` with no `--project-path`
+picks the Editor whose project contains the current directory (and fails as ambiguous outside
+both). When more than one project is open, pass `--project-path <mainProject>` to the main Editor
+commands above. Each clone runs its own server, so address one by its project directory:
+
+```bash
+# List every running instance (main + clones): role, port, pid, vpId, projectPath
+unity command editor.playmode list_instances
+
+# Talk to a clone directly, using the projectPath that listed it
+unity command --project-path <mainProject>/Library/VP/<vpId> editor status
+# Each clone is its own Editor: keep it ticking before running tests on it
+unity command --project-path <mainProject>/Library/VP/<vpId> editor set_auto_tick --enabled true
+unity command --project-path <mainProject>/Library/VP/<vpId> test run --mode playmode
+```
+
+`unity pipeline list` also reports clones, named by player ("Player 2") against the project they're
+playing. There is no forwarding command — talk to the clone. That way you get its full command
+surface and its own status, and nothing queues behind the main Editor.
+
+## Multiplayer Roles (client / server stripping)
+
+Multiplayer Roles decide what is stripped from a client or a server: the Editor runs as one role in
+Play Mode, and each GameObject or component is kept for some roles and stripped from the others.
+Use the `multiplayer.role` commands rather than reflecting over `EditorMultiplayerRolesManager` in
+`script eval`:
+
+```bash
+unity command settings.multiplayer_roles get                    # enabled? safety checks, server stripping
+unity command settings.multiplayer_roles set --settings '{"enabled":true}' --confirm true  # nothing is stripped until roles are enabled
+unity command multiplayer.role get_active                       # Editor role, and whether roles are enabled
+unity command multiplayer.role set_active --role server         # role the Editor plays as (Edit Mode only)
+unity command multiplayer.role set_game_object --target <go> --role server                       # the GameObject
+unity command multiplayer.role set_component --target <go> --type AudioSource --role client      # one of its components
+unity command multiplayer.role set_component --target <component handle> --role client          # a component by handle
+unity command multiplayer.role set_build --role server          # role the active build profile builds for
+```
+
+`role` is `client`, `server` or `client_and_server`. The group needs **Unity 6000.6+**; on older
+Editors it is compiled out, so run `unity command multiplayer.role` to check it is listed.

package/skills/urp-postprocessing/SECURITY.md

@@ -0,0 +1,16 @@
+# Security notes: urp-postprocessing
+
+This skill has the agent run C# inside the user's open Unity Editor through `unity command script eval`. Automated skill scanners flag that as a powerful capability. It is intentional, and it is limited by the safeguards below.
+
+## Accepted risks
+
+| Risk | Capability | Why it is accepted |
+|---|---|---|
+| `SEC_POWER_CAP` | Runs C# in the user's open Editor through `unity command script eval` | It only reaches the Editor the user already has open, on their own machine, as that user, so it grants nothing they couldn't do themselves. `script eval` sits behind the Pipeline capability gate. No code fetched from a remote source is run. Where a named `unity command` covers a step, the skill uses that instead of `script eval`. |
+
+## Mitigations
+
+- **Only the user's own Editor.** `unity command script eval` talks to the Editor open on this machine. It can't reach another machine or another user's Editor.
+- **Capability gate.** `script eval` is only available when the project's Pipeline package provides it.
+- **No remote code.** The agent runs C# it writes from this skill's own recipes. Nothing downloaded from outside is executed.
+- **Named commands first.** When a dedicated `unity command` covers a step, the skill uses it instead of `script eval`.

package/skills/urp-postprocessing/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: urp-postprocessing
+description: Sets up, configures, and debugs URP post-processing with the Volume framework. Use for bloom, tonemapping, color adjustments, depth of field, vignette, or other Volume overrides.
+required_packages:
+  com.unity.render-pipelines.universal: ">=14.0.0"
+---
+
+Help the user set up, configure, and debug post-processing effects using URP's Volume framework.
+
+**Goal: The user should have a working visual result with zero console errors after setup.**
+
+## 0. Prerequisite: an Editor you can run C# in
+
+Volume profiles, `VolumeParameter.overrideState`, and the camera's post-processing flags are
+Editor/runtime object state — the checks and edits below all run C# inside a live Editor.
+
+**The `unity-cli` skill owns getting you there** — installing the CLI, confirming a connected
+Editor, adding the project's `com.unity.pipeline` package, telling a genuinely absent Editor
+apart from one stuck in Safe Mode, and discovering the Editor's command catalog. Follow it
+first; don't re-derive any of it here. You need `script eval` in particular, not just a reachable
+Editor: its presence depends on the Pipeline package version, not on the CLI. If it's
+missing, say so and stop.
+
+Run C# through the connected Editor with the `script eval` command. Discover its parameter shape
+from `unity command --format json` rather than assuming one — the inline form is
+`unity command script eval --caller plugin --skill urp-postprocessing --code '<snippet>'`, and some Pipeline versions also register
+`script eval_file` for running a snippet from a file. **Check the catalog before reaching for
+`script eval_file`; it is frequently absent.** `unity command` defaults to a 30 second timeout.
+
+### Passing C# to `script eval`
+
+`script eval` compiles a **statement block, not a file**. Two consequences, both of which cause a
+compile error rather than a warning:
+
+- **No `using` directives.** The compiler reads `using UnityEngine;` as a resource-disposal
+  statement and rejects it (`CS0210`).
+- **Types must be fully qualified.** A bare `AssetDatabase` or `Volume` does not resolve
+  (`CS0246` / `CS0103`), and a bare `Object` is ambiguous with `object` (`CS0104`).
+
+Where a snippet below is written as a file — with usings, for readability, or because it is
+meant to be saved into the project — qualify the types before passing it to `script eval`.
+
+## 0. Pre-Flight Checks
+
+Before configuring any effect, **verify all checks**. Fix failures first.
+
+1. **URP is the active render pipeline** — If not, inform the user and stop.
+2. **HDR is enabled on the URP Asset** — Required for Tonemapping. Bloom works best with HDR; in SDR it still works but `threshold` must be < 1.
+3. **Camera has post-processing enabled** — `renderPostProcessing` must be `true` (defaults to `false`). Camera Stacking: only a `CameraRenderType.Base` camera (or the last `Overlay` in the stack) should enable post-processing. Also verify the Renderer's PostProcessData asset is not null — if it is, the post-process pass won't exist.
+4. **The Volume's GameObject layer is in the Camera's Volume Layer Mask** — `volumeLayerMask` defaults to layer 0 "Default" only. The Volume's `GameObject.layer` must be included, otherwise the camera ignores it.
+5. **Volume exists with `enabled = true`, a valid Profile, and at least one override** — The `Volume` component must be enabled, have a non-null `profile` (or `sharedProfile`), and at least one `VolumeComponent` with `overrideState = true` on its properties.
+
+### Pre-Flight Check Snippet
+
+Run this to verify the setup programmatically:
+
+```csharp
+// `script eval` compiles a statement block, not a file: no `using` directives are
+// allowed, so every type is fully qualified.
+var report = new System.Text.StringBuilder();
+
+// 1. Check URP is active — a hard stop, so throw: it fails the eval loudly
+var urpAsset = UnityEngine.Rendering.Universal.UniversalRenderPipeline.asset;
+if (urpAsset == null)
+    throw new System.Exception("URP is not the active render pipeline.");
+
+// 2. Check HDR
+if (!urpAsset.supportsHDR)
+    report.AppendLine("Warning: HDR is disabled on the URP Asset. Tonemapping won't work; Bloom requires threshold < 1.");
+
+// 3. Check camera post-processing
+var cam = UnityEngine.Camera.main;
+if (cam == null)
+    throw new System.Exception("No Main Camera found.");
+if (!cam.TryGetComponent<UnityEngine.Rendering.Universal.UniversalAdditionalCameraData>(out var camData))
+    throw new System.Exception("Missing UniversalAdditionalCameraData on camera. Is URP active?");
+if (!camData.renderPostProcessing)
+    report.AppendLine("Warning: Post-processing is disabled on the camera. Enable via camData.renderPostProcessing = true.");
+
+// 4. Check volume layer mask
+var volumes = UnityEngine.Object.FindObjectsByType<UnityEngine.Rendering.Volume>(UnityEngine.FindObjectsSortMode.None);
+foreach (var vol in volumes)
+{
+    if (!vol.enabled) { report.AppendLine($"Warning: Volume '{vol.name}' is disabled."); continue; }
+    if ((camData.volumeLayerMask & (1 << vol.gameObject.layer)) == 0)
+        report.AppendLine($"Warning: Volume '{vol.name}' on layer {vol.gameObject.layer} is not in camera's volumeLayerMask.");
+    // 5. Check profile and overrides
+    var profile = vol.sharedProfile;
+    if (profile == null) { report.AppendLine($"Warning: Volume '{vol.name}' has no profile assigned."); continue; }
+    if (profile.components.Count == 0)
+        report.AppendLine($"Warning: Volume '{vol.name}' profile has no overrides.");
+}
+
+// Return the findings: logs land in the Editor console, the returned value comes back to you
+return report.Length == 0 ? "Post-processing setup looks correct." : report.ToString();
+```
+
+## 1. Volume Setup
+
+Effects are added as **VolumeComponent overrides** on a **VolumeProfile** (a `ScriptableObject`).
+
+**Global Volume** (most common): GameObject with `Volume` component, `isGlobal = true`, `profile` assigned. Affects every camera whose `volumeLayerMask` includes the Volume's layer.
+
+**Local Volume (optional, but takes precedence)**: GameObject with trigger `Collider` + `Volume` component, `isGlobal = false`. Properties:
+- `priority` (float) — higher values override lower when volumes overlap.
+- `blendDistance` (float) — outer distance in world units to start blending from (0 = no blend, instant transition at collider boundary).
+- `weight` (float, 0–1) — scales the volume's overall influence.
+
+## 2. Post-Processing Effects
+
+All effects are `VolumeComponent` subclasses added as overrides on a `VolumeProfile` via `profile.Add<T>()`. Check existence with `profile.Has<T>()` or `profile.TryGet<T>(out var t)`. Remove with `profile.Remove<T>()`.
+
+Every property is a `VolumeParameter`. You **must** set `overrideState = true` before setting `value`, otherwise the Volume system ignores it.
+
+When configuring a specific effect, load the full API reference:
+- [references/effect-reference.md](references/effect-reference.md) — All VolumeComponent properties by effect (Bloom, Tonemapping, ColorAdjustments, DepthOfField, Vignette, MotionBlur, FilmGrain, ChromaticAberration, SplitToning, LensDistortion, WhiteBalance, PaniniProjection, LiftGammaGain, ShadowsMidtonesHighlights, ColorCurves, ChannelMixer)
+
+For code templates:
+- [references/code-templates.md](references/code-templates.md) — Global Volume setup, camera post-processing, and profile modification templates
+
+## 3. Anti-Hallucination Rules
+
+### Required Usings
+
+These apply when you write a `.cs` file into the project. **A snippet passed to `script eval` cannot
+carry them** — qualify the types instead (see "Passing C# to `script eval`" above).
+
+```csharp
+using UnityEngine.Rendering;           // Volume, VolumeProfile, VolumeComponent, VolumeParameter
+using UnityEngine.Rendering.Universal;  // Bloom, Tonemapping, ColorAdjustments, UniversalRenderPipeline, etc.
+```
+
+### Wrong → Correct API Mapping
+
+| WRONG | CORRECT |
+|-------|---------|
+| `PostProcessVolume` | `Volume` (from `UnityEngine.Rendering`) |
+| `PostProcessLayer` | `UniversalAdditionalCameraData.renderPostProcessing` (bool) |
+| `UnityEngine.Rendering.PostProcessing` | `UnityEngine.Rendering.Universal` |
+| `profile.GetSetting<T>()` | `profile.TryGet<T>(out var t)` (returns bool) |
+| `profile.AddSettings<T>()` | `profile.Add<T>()` (returns T; throws if already exists — check `profile.Has<T>()` first) |
+| `volume.sharedProfile` (to modify at runtime) | `volume.profile` (auto-clones the asset into an instance) |
+| `VolumeManager.instance.stack.GetComponent<T>()` | `volume.profile.TryGet<T>(out var t)` |
+
+### Key Facts
+- **`overrideState = true`** is required on every `VolumeParameter` you set. The volume system skips parameters where `overrideState` is `false`. This is the #1 scripting mistake.
+- **`sharedProfile`** = returns the asset directly (edits persist to disk). **`profile`** = auto-clones into an instance if needed (safe for runtime edits). Check with `volume.HasInstantiatedProfile()`.
+- **`profile.Add<T>(bool overrides = false)`** — pass `true` to auto-enable `overrideState` on all parameters of the added component.
+
+## 4. Debugging Checklist
+
+When post-processing isn't working, check in order:
+
+1. `cam.TryGetComponent<UniversalAdditionalCameraData>(out var data)` succeeds and `data.renderPostProcessing` is `true`?
+2. Volume exists in scene with a non-null `profile` (or `sharedProfile`) assigned?
+3. Overrides added via `profile.Add<T>()` AND `overrideState = true` on each property you set?
+4. Volume's `GameObject.layer` is included in camera's `data.volumeLayerMask`? (Default mask is layer 0 "Default" only.)
+5. `volume.isGlobal = true` (for global), or camera is inside the Volume's trigger `Collider` (for local)?
+6. Camera `data.renderType` is `CameraRenderType.Base`, not `Overlay`? (Overlay cameras composite onto the Base camera's output.)
+7. `UniversalRenderPipeline.asset.supportsHDR` is `true`? Required for Bloom and Tonemapping.
+8. Viewing in **Game view**? Scene view has a separate post-processing toggle in its toolbar.
+
+## 5. Common Recipes
+
+Format: Effect property=value. Bloom values are threshold/intensity/scatter.
+
+**Cinematic (Film):** Tonemapping mode=ACES, ColorAdjustments contrast=15 saturation=-10, Bloom threshold=0.9 intensity=0.5 scatter=0.7, Vignette intensity=0.3 smoothness=0.4, FilmGrain type=Medium1 intensity=0.2
+
+**Stylized/Vibrant:** Tonemapping mode=Neutral, ColorAdjustments saturation=20 contrast=10, Bloom threshold=0.8 intensity=1.5 scatter=0.6, SplitToning highlights=warm shadows=cool
+
+**Horror/Dark:** ColorAdjustments postExposure=-0.5 saturation=-30 contrast=20, Vignette intensity=0.5 smoothness=0.3 color=dark-red, FilmGrain type=Large01 intensity=0.4, ChromaticAberration intensity=0.15
+
+**Clean/Mobile:** Tonemapping mode=Neutral, ColorAdjustments postExposure=0.2, Bloom threshold=1.0 intensity=0.3 (subtle). Avoid FilmGrain, MotionBlur, DepthOfField on mobile.
+
+## 6. Final Confirmation
+
+After setup, report to user:
+
+```
+Post-Processing Setup Complete
+- Volume: [Global/Local] on "[GameObject Name]"
+- Profile: [Asset Path]
+- Effects: [List with key property=value pairs]
+- Camera: [Name] — renderPostProcessing=true, volumeLayerMask includes layer [N]
+
+View results in Game view (not Scene view).
+Undo all changes with Edit > Undo (Ctrl+Z).
+```