nccgs 1.0.0

package/.claude/skills/unity-package-management/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: unity-package-management
+description: Use when adding, removing, upgrading, or discovering Unity (UPM) packages programmatically from outside the Editor — headless or CI package installs via the C# UnityEditor.PackageManager.Client API, verifying package ids/versions against the Unity registry, or choosing which packages a game needs by genre, platform, and monetization. The Unity CLI does not manage UPM packages, so this skill covers that gap. Triggers on "install a Unity package", "add com.unity.*", "set up packages headless/CI", "which packages for a <genre> game".
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+---
+
+# Unity Package Management (headless, via the C# Client API)
+
+Add, remove, upgrade, and discover UPM (Unity Package Manager) packages programmatically with
+`UnityEditor.PackageManager.Client`, driven headless from the terminal or CI. Do **not**
+hand-edit `Packages/manifest.json` — the Client API resolves dependencies and compatible
+versions correctly, whereas manual edits routinely break resolution.
+
+This complements the **`unity-cli`** skill (editor install, project creation, build/test): the
+CLI has **no** package-management command, so all package work goes through the Editor's C# API.
+
+## When to use
+
+- Add / remove / upgrade one or more packages in an existing or freshly-created project.
+- Set up a project's packages non-interactively in CI.
+- Verify a package id exists, or find its available versions, before depending on it.
+- Decide which packages a game actually needs — see
+  [references/select-packages.md](references/select-packages.md).
+
+## Choosing what to install
+
+Install what the project actually needs, not everything; prefer packages the chosen template
+already provides (URP templates already include the render pipeline, Input System, etc.). The
+genre / look / platform / monetization → package mapping, plus how to search the registry, is
+in [references/select-packages.md](references/select-packages.md). Produce a **deduplicated
+list of package ids** and read it back to the user before installing.
+
+## The `-quit` problem — why NOT `unity run` for installs
+
+`Client.Add` / `Client.AddAndRemove` are **asynchronous**: they return a `Request` that only
+completes on later `EditorApplication.update` ticks (the UPM child process marshals its result
+back on the Editor's main-loop pump, so a blocking `while (!req.IsCompleted)` busy-wait
+deadlocks it). The Editor must **stay alive** after `-executeMethod` returns, until the request
+finishes.
+
+`unity run` **cannot** be used for the installer: its default path injects `-quit` (see the reserved
+flags in the **`unity-cli`** skill). With `-quit`, the Editor quits the instant the method
+returns — before UPM resolves — so packages never install and the callback never runs.
+
+**Solution:** launch the **Editor binary directly** in `-batchmode` **without** `-quit`. The
+Editor stays alive, `EditorApplication.update` keeps ticking, the poll callback runs, and it
+calls `EditorApplication.Exit(code)` itself when done — which both quits and sets the process
+exit code.
+
+## The installer script
+
+Write this to `Assets/Editor/ProjectBootstrap/PackageInstaller.cs`. It must live under an
+`Editor/` folder (or an Editor-only assembly) because it uses `UnityEditor`.
+
+```csharp
+using System.Linq;
+using UnityEditor;
+using UnityEditor.PackageManager;
+using UnityEditor.PackageManager.Requests;
+using UnityEngine;
+
+namespace ProjectBootstrap
+{
+    // Installs (and optionally removes) a fixed set of packages via the PackageManager
+    // Client API, headless-safe.
+    public static class PackageInstaller
+    {
+        // EDIT this list to match the package selection (see references/select-packages.md).
+        static readonly string[] PackagesToAdd =
+        {
+            "com.unity.inputsystem",
+            "com.unity.cinemachine",
+            "com.unity.render-pipelines.universal",
+            // "com.unity.package@1.2.3"  // pin a version with @ when a minimum is required
+        };
+
+        // Optionally drop packages in the same resolution pass (e.g. a template default you don't want).
+        static readonly string[] PackagesToRemove = { };
+
+        const double TimeoutSeconds = 600; // UPM resolution + downloads can be slow
+
+        static AddAndRemoveRequest _request;
+        static double _deadline;
+
+        // Invoke with: -executeMethod ProjectBootstrap.PackageInstaller.Install  (NO -quit)
+        public static void Install()
+        {
+            if (PackagesToAdd.Length == 0 && PackagesToRemove.Length == 0)
+            {
+                Debug.Log("[PackageInstaller] Nothing to do.");
+                EditorApplication.Exit(0);
+                return;
+            }
+
+            Debug.Log($"[PackageInstaller] Adding: {string.Join(", ", PackagesToAdd)}");
+            _request = Client.AddAndRemove(packagesToAdd: PackagesToAdd, packagesToRemove: PackagesToRemove);
+            _deadline = EditorApplication.timeSinceStartup + TimeoutSeconds;
+            EditorApplication.update += Poll;
+        }
+
+        static void Poll()
+        {
+            if (_request == null) return;
+
+            if (!_request.IsCompleted)
+            {
+                if (EditorApplication.timeSinceStartup > _deadline)
+                {
+                    EditorApplication.update -= Poll;
+                    Debug.LogError("[PackageInstaller] Timed out waiting for UPM.");
+                    EditorApplication.Exit(2);
+                }
+                return;
+            }
+
+            EditorApplication.update -= Poll;
+
+            if (_request.Status == StatusCode.Success)
+            {
+                var names = _request.Result.Select(p => $"{p.name}@{p.version}");
+                Debug.Log($"[PackageInstaller] Resolved: {string.Join(", ", names)}");
+                EditorApplication.Exit(0);
+            }
+            else
+            {
+                Debug.LogError($"[PackageInstaller] Failed: {_request.Error?.message}");
+                EditorApplication.Exit(1);
+            }
+        }
+    }
+}
+```
+
+`AddAndRemove` installs the whole set in a single UPM resolution pass — faster and less
+error-prone than one `Client.Add` per package.
+
+**Add / remove / upgrade with one script:**
+- **Add**: list the id in `PackagesToAdd`.
+- **Remove**: list the id in `PackagesToRemove`.
+- **Upgrade / pin**: add the id with `@<version>` (e.g. `com.unity.cinemachine@2.9.7`). Without
+  a version, resolution picks the latest compatible release.
+
+## Discovering / verifying packages
+
+To confirm an id exists or list its versions before adding it, search the registry. The
+in-Editor `Client.SearchAll()` / `Client.Search("<id>")` calls are also async, so they use the
+**same poll-and-`Exit` pattern and the same headless run** as the installer. Write
+`Assets/Editor/ProjectBootstrap/PackageSearch.cs`:
+
+```csharp
+using System.Linq;
+using UnityEditor;
+using UnityEditor.PackageManager;
+using UnityEditor.PackageManager.Requests;
+using UnityEngine;
+
+namespace ProjectBootstrap
+{
+    public static class PackageSearch
+    {
+        const double TimeoutSeconds = 120;
+        static SearchRequest _request;
+        static double _deadline;
+
+        // Invoke with: -executeMethod ProjectBootstrap.PackageSearch.SearchAll  (NO -quit)
+        public static void SearchAll()
+        {
+            _request = Client.SearchAll();                 // or Client.Search("com.unity.cinemachine")
+            _deadline = EditorApplication.timeSinceStartup + TimeoutSeconds;
+            EditorApplication.update += Poll;
+        }
+
+        static void Poll()
+        {
+            if (_request == null) return;
+            if (!_request.IsCompleted)
+            {
+                if (EditorApplication.timeSinceStartup > _deadline)
+                {
+                    EditorApplication.update -= Poll;
+                    Debug.LogError("[PackageSearch] Timed out.");
+                    EditorApplication.Exit(2);
+                }
+                return;
+            }
+            EditorApplication.update -= Poll;
+
+            if (_request.Status == StatusCode.Success)
+            {
+                foreach (var p in _request.Result.OrderBy(p => p.name))
+                    Debug.Log($"[PackageSearch] {p.name}@{p.versions.latestCompatible}  {p.displayName}");
+                Debug.Log($"[PackageSearch] {_request.Result.Length} packages found.");
+                EditorApplication.Exit(0);
+            }
+            else
+            {
+                Debug.LogError($"[PackageSearch] Failed: {_request.Error?.message}");
+                EditorApplication.Exit(1);
+            }
+        }
+    }
+}
+```
+
+`_request.Result` is a `PackageInfo[]`; each entry exposes `name`, `displayName`, `description`,
+and `versions` (`.latest`, `.latestCompatible`, `.all`). For a terminal-only check without the
+Editor (a **known** id, not free-text search), query the registry directly — see
+[references/select-packages.md](references/select-packages.md#discovering-and-verifying-packages).
+
+## Run it headless (direct Editor invocation, no `-quit`)
+
+Resolve the Editor binary from the version, then run it in batch mode. The script owns quitting
+via `EditorApplication.Exit`, so do **not** pass `-quit`:
+
+```bash
+VERSION="<version>"          # e.g. 6000.0.47f1 (or an installed version)
+PROJECT="<project-path>"
+METHOD="ProjectBootstrap.PackageInstaller.Install"   # or ...PackageSearch.SearchAll
+
+# Install directory of that editor (Hub layout), via the unity CLI
+ED=$(unity editors path "$VERSION" --format json | python3 -c "import sys,json;print(json.load(sys.stdin)['data']['path'])")
+
+# Resolve the executable per-OS (handles both "dir containing Unity.app" and the ".app" itself)
+case "$(uname)" in
+  Darwin) if [ -d "$ED/Unity.app" ]; then UNITY_BIN="$ED/Unity.app/Contents/MacOS/Unity";
+          elif [[ "$ED" == *.app ]]; then UNITY_BIN="$ED/Contents/MacOS/Unity";
+          else UNITY_BIN="$ED/Unity"; fi ;;
+  Linux)  UNITY_BIN="$ED/Editor/Unity" ;;
+  *)      UNITY_BIN="$ED/Editor/Unity.exe" ;;   # Windows (Git Bash / MSYS); use Editor\Unity.exe in PowerShell
+esac
+
+"$UNITY_BIN" -batchmode -projectPath "$PROJECT" -executeMethod "$METHOD" -logFile -
+echo "Exit code: $?"   # 0 = success, 1 = UPM error, 2 = timeout
+```
+
+`-logFile -` streams the Editor log (including the `[PackageInstaller]` / `[PackageSearch]`
+lines) to stdout so you can watch resolution progress and read any UPM error. If
+`unity editors path` output shape differs on your build, get the directory from
+`unity editors --installed --format json` instead.
+
+## Verify
+
+```bash
+# Every requested id should appear as a dependency
+cat "<project-path>/Packages/manifest.json"
+```
+
+Confirm the run exited `0` and each package from the list is present in `manifest.json`. If a
+package fails to resolve, `_request.Error.message` is logged; read it and check the id/version
+against the registry. The Editor's own log (including the `[PackageInstaller]` lines) is the
+stdout you streamed with `-logFile -` above — read it there, not via `unity logs` (which shows
+the CLI's own log, not the Editor's).
+
+## Import & save headlessly (generate `.meta` files)
+
+After a script or tool writes new `.cs`/asset files, Unity must **import** them so it generates
+the `.meta` file each asset needs — and every `.cs`/asset MUST be committed together with its
+`.meta`. Merely opening the project once (`unity open "<project-path>"`) imports and generates
+them; use this method when you need it **headless** (in a script or CI).
+
+Unlike the package installer, this is **synchronous** — it finishes before returning — so it's
+safe to run via `unity run` (its injected `-quit` is harmless; the method also calls
+`EditorApplication.Exit` for a clean exit code). Write
+`Assets/Editor/ProjectBootstrap/ProjectSaver.cs`:
+
+```csharp
+using UnityEditor;
+using UnityEngine;
+
+namespace ProjectBootstrap
+{
+    public static class ProjectSaver
+    {
+        // Invoke with: -executeMethod ProjectBootstrap.ProjectSaver.SaveAll
+        public static void SaveAll()
+        {
+            AssetDatabase.Refresh(ImportAssetOptions.ForceUpdate);
+            AssetDatabase.SaveAssets();
+            Debug.Log("[ProjectSaver] Assets imported and saved.");
+            EditorApplication.Exit(0);
+        }
+    }
+}
+```
+
+```bash
+unity run "<project-path>" --editor-version <version> \
+  -- -executeMethod ProjectBootstrap.ProjectSaver.SaveAll
+```
+
+## Notes
+
+- These editor scripts are a bootstrap convenience. Leave them in
+  `Assets/Editor/ProjectBootstrap/` (they do nothing unless invoked) or delete them after
+  setup — your call; mention it to the user.
+- All scripts live under `Editor/` because they use `UnityEditor`; they never ship in a build.
+- Monetization / backend packages (`com.unity.purchasing`, `com.unity.services.levelplay`, the
+  UGS packages) install through this same mechanism, but do the actual **integration** via the
+  dedicated skills: **implement-in-app-purchases**, **levelplay-unity-integration**,
+  **build-live-game**.

package/.claude/skills/unity-package-management/references/select-packages.md

@@ -0,0 +1,108 @@
+# Selecting packages
+
+Turn a game concept — genre, look, target platforms, monetization — into a concrete package
+list, then install it via the C# PackageManager Client API (see the main `SKILL.md`).
+
+**Principle:** install what the concept actually needs, not everything. A hyper-casual 2D
+prototype needs far less than a 3D multiplayer RPG. Prefer packages already provided by the
+chosen template (URP templates already include the render pipeline, Input System, etc.) — only
+add what's missing. Don't pin exact versions unless a minimum is required; `Client.Add` without
+a version resolves the latest compatible release.
+
+The tables below are a starting point, not the whole registry. **Search the registry** to
+discover packages beyond this list, confirm an id exists, or check available versions before
+installing — see [Discovering and verifying packages](#discovering-and-verifying-packages).
+
+## Discovering and verifying packages
+
+Two ways to search, depending on whether the Editor is involved:
+
+**In-Editor — the PackageManager Client API (preferred).** `Client.SearchAll()` returns every
+package available in the project's configured registries (the Unity registry plus any scoped
+registries), each with all its versions and metadata — this is what the Package Manager
+window's search filters over. `Client.Search("<id>")` inspects a single package. Use the
+ready-to-run `PackageSearch` script in the main `SKILL.md` to discover candidates and verify
+ids/versions before building the install list.
+
+**Terminal — query the npm-compatible registry directly** (no Editor needed) to confirm a
+**known** id exists and list its versions:
+
+```bash
+# Full metadata for one package: versions{}, dist-tags.latest, description, dependencies.
+# -f makes curl fail (non-zero) on HTTP errors — e.g. a 404 for a bad id — instead of piping
+# an error page into python; -L follows redirects.
+curl -fsSL https://packages.unity.com/com.unity.cinemachine | python3 -m json.tool | head -40
+
+# Just the latest published version
+curl -fsSL https://packages.unity.com/com.unity.cinemachine \
+  | python3 -c "import sys,json;print(json.load(sys.stdin)['dist-tags']['latest'])"
+```
+
+Note: the registry supports fetching a **known** package id, but **not** free-text search over
+HTTP (the npm `-/v1/search` endpoint is not available — it 404s). For keyword discovery, use
+`Client.SearchAll()` in-Editor, the Package Manager window, or the
+[Unity package documentation](https://docs.unity3d.com/Manual/pack-keys.html).
+
+## Foundation (almost every project)
+
+| Need | Package | Notes |
+|---|---|---|
+| Modern input | `com.unity.inputsystem` | Preferred over the legacy Input Manager. |
+| Text / UI | `com.unity.ugui` | uGUI + TextMeshPro (bundled). UI Toolkit ships with the Editor. |
+| Camera framing | `com.unity.cinemachine` | Great for almost any 3D and many 2D games. |
+| Testing | `com.unity.test-framework` | Enables `unity test`; usually already present. |
+| Large/streamed assets | `com.unity.addressables` | Add when the game has many assets or needs content updates. |
+
+## Render pipeline (pick one; usually set by the template)
+
+| Choice | Package | Use when |
+|---|---|---|
+| **URP** (Universal) | `com.unity.render-pipelines.universal` | Default for most 2D/3D, mobile, and WebGL. Broadest platform reach. |
+| **HDRP** (High-Definition) | `com.unity.render-pipelines.high-definition` | High-fidelity PC/console only. Not for mobile/WebGL. |
+| **Built-in** | (none) | Simplest/legacy; fine for tiny prototypes. |
+
+## By dimension & look
+
+| Look | Packages |
+|---|---|
+| **2D** (any) | `com.unity.2d.feature` (sprites, tilemap, animation, pixel-perfect bundle) |
+| **2D pixel-perfect** | `com.unity.2d.pixel-perfect` (included in the 2D feature set) |
+| **3D navigation** | `com.unity.ai.navigation` (NavMesh for AI/pathfinding) |
+| **Cutscenes / sequencing** | `com.unity.timeline` |
+| **No-code logic** | `com.unity.visualscripting` |
+
+## By genre (starting points, combine with the above)
+
+| Genre | Typical additions |
+|---|---|
+| Platformer / action | URP, Input System, Cinemachine, 2D feature (if 2D), AI Navigation (if 3D) |
+| Puzzle / match / card | URP or 2D feature, Input System, uGUI/TextMeshPro, Timeline (juice) |
+| Top-down / twin-stick | URP, Input System, Cinemachine, AI Navigation |
+| RPG / adventure | URP, Input System, Cinemachine, AI Navigation, Addressables, Timeline |
+| Racing / physics | URP, Input System, Cinemachine; Physics is built in |
+| Idle / hyper-casual | 2D feature or URP, Input System, uGUI/TextMeshPro (keep it lean) |
+| Multiplayer (any) | `com.unity.netcode.gameobjects` + Multiplayer Services → see **build-live-game** |
+
+## By target platform
+
+Platform support is mostly Editor **modules** (installed with `unity install --module …`, see
+the **`unity-cli`** skill), not packages. Package-wise:
+
+| Platform | Consider |
+|---|---|
+| Mobile (iOS/Android) | Keep dependencies lean; URP over HDRP; Addressables for download size; monetization below |
+| WebGL | URP (not HDRP); small footprint; avoid heavy packages |
+| Desktop / Console | URP or HDRP depending on fidelity target |
+
+## By monetization — install now, integrate via the dedicated skill
+
+| Goal | Package | Integration skill |
+|---|---|---|
+| In-app purchases | `com.unity.purchasing` | **implement-in-app-purchases** |
+| Ads / mediation | `com.unity.services.levelplay` | **levelplay-unity-integration** |
+| Accounts, cloud save, economy, remote config, leaderboards, analytics | see the UGS package table | **build-live-game** |
+
+Install the package(s) here so the manifest is complete, but do the actual wiring by invoking
+the matching skill. For the full UGS package/version matrix (`com.unity.services.core`,
+`authentication`, `cloudsave`, `cloudcode`, `economy`, `remote-config`, `analytics`, etc.),
+read the **build-live-game** skill.

package/.claude/skills/urp-postprocessing/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: urp-postprocessing
+description: Sets up, configures, and debugs URP post-processing effects using the Volume framework. Use when the user asks about bloom, tonemapping, color adjustments, depth of field, vignette, motion blur, or other Volume overrides in a URP project.
+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 `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 `eval` command. Discover its parameter shape
+from `unity command --format json` rather than assuming one — the inline form is
+`unity command eval --code '<snippet>'`, and some Pipeline versions also register
+`eval_file` for running a snippet from a file. **Check the catalog before reaching for
+`eval_file`; it is frequently absent.** `unity command` defaults to a 30 second timeout.
+
+### Passing C# to `eval`
+
+`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 `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
+// `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 `eval` cannot
+carry them** — qualify the types instead (see "Passing C# to `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).
+```