@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/skills/migrate-birp-to-urp/references/migration-workflow.md

@@ -0,0 +1,265 @@
+# Built-in to URP Migration Workflow
+
+Use this workflow to follow the official Unity migration flow and identify when to slow down, branch, or stop.
+
+## Table of Contents
+
+- [Official References](#official-references)
+- [Safety First](#safety-first)
+- [Project Preparation](#project-preparation)
+- [Phased Migration Model](#phased-migration-model)
+- [Standard 3D Path: Built-in Render Pipeline to URP](#standard-3d-path-built-in-render-pipeline-to-urp)
+- [What Each Converter Does](#what-each-converter-does)
+- [Targeted Material-Only Path](#targeted-material-only-path)
+- [2D Path: Built-in Render Pipeline 2D to URP 2D](#2d-path-built-in-render-pipeline-2d-to-urp-2d)
+- [2D Lighting Note](#2d-lighting-note)
+- [Baked Lighting, Lightmaps, And Reflection Probes](#baked-lighting-lightmaps-and-reflection-probes)
+- [Manual Follow-Up Hot Spots](#manual-follow-up-hot-spots)
+- [When To Stop And Escalate](#when-to-stop-and-escalate)
+
+## Official References
+
+- [Upgrading from the Built-in Render Pipeline to URP](https://docs.unity3d.com/Manual/urp/upgrading-from-birp.html)
+- [Convert assets using the Render Pipeline Converter](https://docs.unity3d.com/Manual/urp/features/rp-converter.html)
+- [Upgrade material assets to URP or HDRP](https://docs.unity3d.com/Manual/upgrade-material.html)
+- [URP asset](https://docs.unity3d.com/Manual/urp/urp-asset-and-renderer.html)
+- [Prepare and upgrade sprites for 2D lighting in URP](https://docs.unity3d.com/Manual/urp/PrepShader.html)
+- [Set up a render pipeline](https://docs.unity3d.com/Manual/render-pipelines-set-up.html)
+- [Update believable visuals in URP and HDRP](https://docs.unity3d.com/Manual/BestPracticeMakingBelievableVisuals0.html)
+
+## Safety First
+
+- Render Pipeline Converter changes are one-way. Run conversion only after the user has confirmed a backup, branch, or rollback point.
+- Installing URP and assigning a URP asset can also leave the project in a partial magenta state before materials are converted. If rollback safety is not confirmed, stop before package install or Graphics/Quality assignment, not after.
+- If the user has confirmed rollback safety or says this is a disposable copy, treat that confirmation as covering the full migration pass. Do not ask again before each converter unless a new risky decision appears.
+- Inspect warnings before and after conversion instead of treating converter output as success by default.
+- If the project is also moving to a new Unity version, the safer order is: engine upgrade first, render-pipeline migration second.
+
+## Project Preparation
+
+Before conversion:
+
+1. Inspect whether the project is truly still on Built-in or already partially on URP.
+2. Identify likely migration hot spots:
+   - custom shaders
+   - Asset Store rendering packages
+   - Post-processing Stack v2
+   - image effects or camera callbacks
+   - replacement shaders or special camera rendering paths
+   - multiple quality levels with different graphics expectations
+   - baked lighting, lightmaps, light probes, and reflection probes
+3. If rendering plug-ins or packages are clearly Built-in-specific, do not assume they will survive the migration unchanged.
+
+Do this even when the user gives a short prompt like "upgrade this project to URP." The skill, not the user, is responsible for discovering these common migration surfaces.
+
+## Phased Migration Model
+
+Use phases for real project upgrades. A generic "migrate this project to URP" prompt starts or resumes the next phase; it does not require finishing every fragile subsystem in one response.
+
+| Phase | Goal | Completion gate |
+| --- | --- | --- |
+| Phase 0: Inspect and plan | Detect pipeline state, representative scene, rollback safety, PPv2, materials, Quality levels, lighting/probes, custom render code | Findings are reported and rollback safety is confirmed before mutation |
+| Phase 1: URP setup and materials | Install/reuse URP, create/assign URP asset/renderer, assign Graphics/Quality, convert supported opaque and particle/effect materials | Saved Graphics/Quality and material shader assignments verify correctly |
+| Phase 2: Post-processing and cameras | Convert PPv2 to persistent URP Volumes/profiles, wire cameras, disable legacy PPv2 for validation, classify unsupported PPv2 effects | Saved URP profile has non-null expected overrides, scene references it, legacy PPv2 is disabled or clearly preserved for comparison |
+| Phase 3: Lighting and probes | Resolve stale Built-in lighting data, configure URP lighting/probe settings, rebake/refresh where feasible | Saved scene lighting/probe state is verified, or the phase is explicitly partial/blocked |
+| Phase 4: Final validation | Save/reload/re-query, capture representative scenes, check Console, report complete/incomplete/manual items | Every success gate passes before using "complete" |
+
+At the end of each phase, report:
+
+- `Completed`: saved-state evidence for that phase.
+- `Incomplete`: specific failed checks and whether they are repairable.
+- `Manual follow-up`: unsupported or intentionally deferred items.
+- `Next phase`: the exact phase to run next.
+
+Continue into the next phase only when Unity remains stable, the next phase does not introduce a new costly/risky operation, and the user has already authorized that scope. Prefer a clear phase boundary over a rushed final answer.
+
+## Standard 3D Path: Built-in Render Pipeline to URP
+
+Use this path for normal 3D Built-in projects moving to URP.
+
+For a generic "migrate/upgrade to URP" request, treat the following as part of the standard phased path unless inspection proves they are absent: URP asset/renderer setup, Graphics and Quality assignment, material conversion, particle/VFX material verification, PPv2-to-URP Volume verification, baked-lighting/lightmap/probe verification, representative scene capture, saved-state re-query, and a final complete/incomplete/manual report.
+
+Do not downgrade common migration surfaces into manual follow-up just because the user used a short prompt. Discover PPv2, stale baked lighting, lightmaps, reflection probes, particle materials, and Quality-level assignments. A generic migration can be called complete only after these surfaces are either verified in saved project state or precisely reported as unsupported/manual edge cases. Until then, report the current phase as complete or partial instead of reporting the whole migration as complete.
+
+Before step 1, confirm rollback safety. If no backup, branch, archive, or disposable copy is confirmed, do not install URP or assign a URP asset. Explain that those steps can immediately make supported Built-in materials render magenta until material conversion runs.
+
+Before and after pipeline assignment, deliberately open or inspect the representative scene(s). Do not infer that baked lighting, PPv2, reflection probes, or lightmaps are absent from a default/test scene.
+
+1. Ensure URP is installed.
+   - Package installation is a phase boundary. It may trigger package refresh, compilation, and domain reload.
+   - Do not rely on a single `PackageManager.Client.Add` tool call to complete the rest of the migration. If the chat/tool call stops or returns `null`, wait for Unity to finish compiling, then resume by inspecting the partial project state.
+   - If `Packages/manifest.json` already contains `com.unity.render-pipelines.universal`, do not reinstall URP; continue from asset setup and validation.
+2. Create the URP asset and renderer asset if they do not already exist.
+3. Assign the URP asset in Graphics settings. Assign it in relevant Quality levels as well.
+   - If the Console reports "Default Renderer is missing", do not stop at setup. Re-query the saved URP asset's renderer list/default index, validate a fresh scene/camera render after save/reload, and either repair the renderer asset or mark the migration partial.
+4. Open `Window > Rendering > Render Pipeline Converter`.
+5. Select `Built-in Render Pipeline to URP`.
+6. Initialize converters and inspect the result set.
+7. Run the converters that apply to the project:
+   - `Rendering Settings`
+   - `Material Upgrade`
+   - `Animation Clip Converter`
+   - `Read-only Material Converter`
+   - `Post-processing Stack v2 Converter`
+8. Re-open representative scenes and validate before doing broad cleanup.
+9. Verify saved assets after conversion. Do not rely only on converter or command logs.
+   - If the migration changed scene objects, camera components, PPv2 enable states, active Lighting Settings, or reflection probes, save the open scene as well as project assets. `AssetDatabase.SaveAssets()` does not prove scene changes persisted.
+10. For Quality levels, verify saved `customRenderPipeline` entries or re-query `QualitySettings.GetRenderPipelineAssetAt(i)`. A tool log that says Quality levels were assigned is not enough.
+11. If a script must assign Quality-level URP assets, follow URP's converter pattern: cache the current quality level, call `QualitySettings.SetQualityLevel(index)` for each target level, set `QualitySettings.renderPipeline = urpAsset`, restore the original level, save, and verify the saved `customRenderPipeline` entries. Do not use guessed APIs such as `QualitySettings.SetRenderPipelineAssetAt`.
+12. If representative scenes use baked lighting, verify the baked-lighting state separately. Do not treat a clean compile or material conversion as proof that lightmaps and probes look correct in URP.
+13. Before the final response, run a success gate:
+   - Saved Graphics and relevant Quality levels point at the intended URP asset.
+   - The saved URP asset has a valid default renderer and current validation is not blocked by renderer errors.
+   - Saved material assets, including particles/fog/smoke/VFX materials, use URP-compatible shaders or are listed as unresolved custom/package shader cases. Materials that had source textures/colors still have mapped URP textures/colors; white/gray untextured output is not a successful material conversion.
+   - If PPv2 existed, the saved URP Volume profile has persistent non-null `components` entries and the scene references the URP `Volume`; `components: []` means incomplete.
+   - If baked/mixed lighting, Enlighten/realtime-GI settings, Lighting Data, lightmaps, light probes, or reflection probes existed, lighting/probe repair has been attempted or the migration is explicitly partial because that phase is still running/incomplete.
+   - If a new URP `.lighting` asset was created, the saved scene's `m_LightingSettings` reference points to that asset after save/reload. Creating the asset and calling `Lightmapping.lightingSettings = target` is not sufficient evidence.
+   - A representative scene was inspected or captured after saving/reloading.
+   - If the representative capture is materially too dark, blown out, or high contrast, post-processing wiring and exposure/tonemapping/ambient balance have been verified and adjusted, or visual parity is explicitly partial.
+   - The final status wording matches the gate result. Say "complete" only when every required item passes. Say "partial" when URP setup/material conversion succeeded but PPv2, baked lighting, probes, or saved-state validation still need repair.
+
+If only Phase 1 is complete, say "Phase 1 complete" and list Phase 2/3/4 as next work. Do not label the whole migration complete from Phase 1 evidence.
+
+## What Each Converter Does
+
+- `Rendering Settings`: creates URP assets and maps Built-in settings to URP equivalents.
+- `Material Upgrade`: converts supported Built-in materials. It does not solve custom shader compatibility.
+- Particle and VFX materials need explicit verification. If they still point at built-in particle shaders or built-in shader IDs after conversion, migrate them to URP particle shaders such as `Universal Render Pipeline/Particles/Unlit` where appropriate.
+- Do not blindly force particle, fog, smoke, steam, decal, additive, VFX, or transparent effect materials to `Universal Render Pipeline/Lit`. Preserve transparent/additive behavior where possible, and validate off-screen/inactive particle systems by asset inspection rather than only by the current camera.
+- `Animation Clip Converter`: runs after material conversion and helps when animation clips affect material properties or Post-processing Stack v2 properties.
+- `Read-only Material Converter`: handles built-in read-only materials such as `Default-Diffuse` and can take longer because it indexes the project.
+- `Post-processing Stack v2 Converter`: converts PPv2 volumes, profiles, and related camera data to URP equivalents and can also take longer because it indexes the project.
+
+## Post-Processing Verification
+
+PPv2 conversion is successful only if the saved project state proves it.
+
+After any PPv2 migration attempt:
+
+1. Re-open or re-query the converted scene.
+2. Inspect old `PostProcessVolume`, `PostProcessLayer`, and `PostProcessProfile` usage.
+3. Inspect the resulting URP `VolumeProfile` asset. A profile with `components: []` is empty and should not be reported as migrated. A profile with `components` entries that point to `{fileID: 0}` is also invalid and should not be reported as migrated.
+   - If the profile was created by script, `VolumeProfile.Add<T>()` must be paired with `AssetDatabase.AddObjectToAsset(component, profile)` for persistent assets. Mark both the component and profile dirty, save assets, reload it from `AssetDatabase`, and verify the non-null component count persisted.
+   - If the saved profile contains `{fileID: 0}` entries where Bloom, Tonemapping, Vignette, or Depth Of Field should be, treat that as broken persistence. Repair or recreate the profile before claiming PPv2 parity.
+4. Confirm representative cameras have URP camera data and post-processing enabled when the visual target depends on it.
+5. Confirm the scene has the intended URP `Volume` setup, or explicitly document that the PPv2 setup still needs manual migration.
+   - If the scene still serializes only the old PPv2 `sharedProfile` and no URP `Volume` references the new `VolumeProfile`, PPv2 migration is incomplete even if a URP profile asset exists.
+   - If a scene URP `Volume` references a profile with `components: []`, the scene has empty URP post-processing plumbing, not migrated post-processing. Repair the profile or mark PPv2 as incomplete.
+6. If PPv2 effects include Screen Space Reflections, call out that URP has no direct equivalent in the same built-in PPv2 form. Recommend reflection probes, screen-space reflection alternatives, or a custom/third-party solution when required.
+7. For common mappable PPv2 effects, create persistent URP overrides instead of leaving a vague manual parity task. Typical mappings include Bloom -> `UnityEngine.Rendering.Universal.Bloom`, Color Grading/exposure -> `ColorAdjustments` plus `Tonemapping`, Vignette -> `Vignette`, and Depth Of Field -> `DepthOfField`.
+8. It is acceptable to mark unsupported or structurally different effects as manual follow-up, such as PPv2 Screen Space Reflections or Ambient Occlusion that should be handled through reflection probes, SSAO renderer features, or custom/third-party rendering.
+9. If old PPv2 components remain as a reference while a URP Volume is active, disable the old PPv2 layer/component during URP visual validation to avoid double post-processing. Do not delete it until the saved URP replacement has been verified and the user approves cleanup.
+10. Do not uninstall PPv2 or remove `PostProcessLayer` / `PostProcessVolume` components until the saved URP replacement has been verified, unless the user explicitly accepts effect loss or manual follow-up.
+
+If a command log says effects were added but the saved profile is empty, report the result as a failed or incomplete post-processing migration and do not claim success. If legacy PPv2 is still active while an empty URP profile exists, do not claim URP post-processing is active; state that the old PPv2 setup is preserved but the URP replacement is incomplete.
+
+## Material And Particle Verification
+
+After material conversion:
+
+1. Re-query material shader assignments on disk or through `AssetDatabase`.
+2. Confirm standard opaque materials use URP-compatible shaders, usually `Universal Render Pipeline/Lit`.
+3. Confirm particle, fog, smoke, steam, decal, VFX, and transparent effect materials are not left on Built-in particle shaders.
+4. Do not rely only on "no magenta in the current camera" as proof. Some particle systems may be off-screen, inactive, or visually subtle.
+5. If a material is custom, package-owned, or effect-heavy, classify it as manual follow-up instead of forcing it to URP Lit.
+6. For vegetation, grass, tree, terrain-detail, SpeedTree, billboard, leaf-card, and wind-driven materials, verify more than the shader name. Preserve alpha cutoff/clipping, face/culling intent, textures, tint, normals, and expected wind/billboard behavior where possible. If foliage becomes solid opaque cards, static when it was wind-driven, or visually loses its specialized behavior, report the foliage set as partial/manual instead of calling material conversion complete.
+7. For any converter or manual shader-assignment fallback, prove source material data survived from a pre-conversion snapshot. Cache `_MainTex`, `_Color`, normal, metallic/specular, emission, alpha/cutoff, texture tiling/offset, and source shader before conversion, then verify representative converted assets have non-null `_BaseMap`/expected textures and non-default color values when the source did.
+8. Do not run a "repair" that copies `_MainTex` to `_BaseMap` after conversion unless the value comes from the pre-conversion snapshot. Once a shader has changed, `_MainTex` may already be null/default; copying it later can silently preserve the broken state.
+9. Do not edit immutable package materials under `Packages/` or `Library/PackageCache`. If those assets appear in the conversion set, classify them as package-owned/read-only and use a local material copy or scoped custom replacement instead.
+10. If a representative capture shows broad white/gray untextured objects after conversion, or if snapshot comparison shows source materials had albedo textures but converted materials have null `_BaseMap`, treat the material phase as incomplete even if the materials are no longer magenta.
+
+If rollback safety was already confirmed, continue repairing ordinary material, renderer, PPv2, lighting, or probe failures instead of asking the user whether to continue. Ask only when a new destructive cleanup choice, unsupported custom shader strategy, long-running phase boundary, or repeated validation failure requires the user's decision.
+
+## Partial Migration Resume Checklist
+
+If a migration stops after installing URP, after a domain reload, after a phase boundary, or after a long-running bake:
+
+1. Re-check whether URP is now installed in `Packages/manifest.json`.
+2. Check whether a URP asset and renderer asset exist and are valid.
+3. Verify Graphics settings and every relevant Quality level point to the intended URP asset.
+4. Re-query material shader assignments, including particle/fog/smoke/VFX materials. If supported Built-in shader GUIDs or names still dominate after URP is assigned, material conversion is the immediate next incomplete phase; do not stop at "URP setup complete" when the scene is still magenta.
+5. Inspect PPv2 state and URP Volume profiles. Empty `components: []` profiles are incomplete.
+6. Inspect baked lighting/lightmap state. If old lightmaps blow out the scene, preserve them as reference, clear active baked data, rebake under URP, and refresh reflection probes.
+   - If a new URP-compatible Lighting Settings asset exists, verify the saved scene actually references it. A scene that still references the old Enlighten/realtime-GI `.lighting` asset is not fully repaired.
+   - If old `LightingData.asset` remains assigned and old reflection-probe EXRs are unchanged, do not say lighting or probes were refreshed. Report them as preserved reference data or partial until a URP bake/probe refresh completes.
+7. If a previous run ended at "would you like me to continue?" but rollback safety was already confirmed, resume from the first incomplete item instead of restarting or asking again.
+8. Capture a representative scene and report exactly which items are complete, incomplete, or manual follow-up.
+9. Name the next phase instead of restarting. For example: "Resume at Phase 2: Post-processing and cameras" or "Resume at Phase 3: Lighting and probes."
+
+## Targeted Material-Only Path
+
+Use this only when the user wants selected materials converted instead of a full migration.
+
+1. Confirm the project is already on URP.
+2. Select the Built-in materials in the Project window.
+3. Use `Edit > Rendering > Materials > Convert Selected Built-in Materials to URP`.
+4. If a material still errors in the Inspector or stays magenta, treat it as a shader triage case rather than retrying blindly.
+5. Validate one or two representative scenes after conversion because selected material upgrades can still create visual drift.
+
+## 2D Path: Built-in Render Pipeline 2D to URP 2D
+
+Use this path when the project is primarily 2D and the target is URP 2D.
+
+1. Ensure URP is installed.
+2. Create and assign a 2D Renderer asset.
+3. Open `Window > Rendering > Render Pipeline Converter`.
+4. Select `Built-in Render Pipeline 2D to URP 2D`.
+5. Use `Material and Material Reference Upgrade`.
+6. If the user wants 2D lighting, verify that sprites and materials are using URP-compatible lit materials after conversion.
+
+## 2D Lighting Note
+
+For 2D lighting in URP, Unity can assign `Sprite-Lit-Default` when sprites are dragged into the scene. Existing project materials still need to be upgraded if they should react to 2D lights.
+
+## Baked Lighting, Lightmaps, And Reflection Probes
+
+Baked lighting does not become visually correct just because the project compiles after URP setup.
+
+For scenes with baked or mixed lighting:
+
+1. Preserve existing Lighting Data, lightmaps, light probes, and reflection probes as reference data until visual parity is accepted.
+2. Inventory `Lightmapping.lightingSettings`, scene `LightmapSettings`, baked/mixed lights, light probes, reflection probes, and the scene's Lighting Data asset.
+3. Check whether the migrated scene is overexposed or too dark because both old PPv2 and new URP Volume effects are active. For URP validation, disable legacy PPv2 components/layers but do not delete them.
+4. Review URP Volume exposure, tonemapping, bloom, and color adjustments before changing light intensities.
+5. If the scene is still too dark, blown out, or high contrast after PPv2/URP Volume migration, run an exposure-balance check before the final report. Verify renderer `PostProcessData`, camera `renderPostProcessing`, `volumeLayerMask`, active Volume weight/priority/layer, and non-empty saved Volume overrides before changing values. Then tune exposure, tonemapping, lift/gamma/gain, bloom, ambient fill, additional-light limits, and shadows in bounded steps with captures between attempts.
+6. If clearing baked data makes the scene stop being blown out, treat the previous lightmaps/Lighting Data as stale active data for URP. Keep them as reference/rollback evidence, but do not tune final URP lighting against them.
+7. If parity matters, clear/rebake lighting under URP and refresh reflection probes after URP assets, renderer features, volumes, and quality settings are finalized when the user has permitted changes. If the bake is too long or interrupted, report a partial migration and resume from this phase later rather than claiming completion.
+8. When assigning new URP-compatible `LightingSettings`, remember that the active lighting-settings reference is scene state. Mark the settings and active scene dirty, save the scene, reload or re-query, and verify the saved scene references the intended asset before reporting it as active. `AssetDatabase.SaveAssets()` alone does not prove the scene's `m_LightingSettings` reference changed.
+9. If the saved scene still references the old Enlighten/realtime-GI `.lighting` asset, the lighting phase is incomplete even if a new URP lighting settings asset exists on disk.
+10. Report baked lighting as one of: preserved as reference, stale active bake cleared, visually checked and acceptable, rebaked/refreshed under URP, exposure-balanced with remaining bake risk, or manual follow-up. Do not report it as fully migrated from compile success alone.
+11. Do not claim visual parity is preserved while old Built-in `LightingData.asset` and old reflection-probe EXRs remain active without a URP rebake/probe refresh or explicit saved-state visual verification.
+12. Do not claim reflection probes were refreshed from intent alone. Verify successful probe-render output, changed probe assets, or a saved-state visual check. Unchanged old EXR files mean probe refresh is still partial/manual.
+
+## Manual Follow-Up Hot Spots
+
+Even when the converter succeeds, these areas often still need attention:
+
+- custom shaders and package shaders
+- PPv2 and fullscreen image effects
+- replacement-shader camera workflows
+- baked lighting, lightmaps, light probes, reflection probes, and shadow tuning
+- quality-level assignments
+- 2D lit materials and sprite workflows
+- visual parity around tone mapping, exposure, and light falloff
+
+For real project upgrades, explicitly verify:
+
+- material shader assignments on disk
+- particle/VFX material shader assignments
+- Graphics settings and each relevant Quality level
+- URP renderer features that were added
+- persistent URP Volume profile components
+- representative scene camera data and active legacy post-processing components
+- baked-lighting state and whether a URP rebake/probe refresh is still required
+
+## When To Stop And Escalate
+
+Stop and explain the blocker instead of guessing when:
+
+- custom shaders drive important visuals
+- complex shader situations such as surface shaders, `GrabPass`, replacement shaders, or fullscreen camera callbacks are involved
+- package-owned shaders are involved and the safe fix is unclear
+- converter results contain unresolved warnings or failures
+- baked lighting is important to the scene and no URP bake/visual parity check has been performed; for a generic full migration, this means the migration is partial, not complete
+- the project mixes 2D and 3D requirements and the target renderer choice is unclear
+- the user has not confirmed rollback safety for irreversible conversion

package/skills/migrate-birp-to-urp/references/parity-validation-and-troubleshooting.md

@@ -0,0 +1,114 @@
+# 9. Quality, Lighting, and Visual Parity Review
+
+Use [references/quality-settings-map.md](quality-settings-map.md) when the user mentions visual mismatch, shadows, performance, or quality settings.
+
+1. **Review Graphics settings and each active Quality level.**
+   - If a Quality level has no custom URP asset, state whether that level intentionally falls back to Graphics settings or still needs explicit assignment.
+   - Do not claim all quality levels are migrated unless each relevant level has been inspected.
+   - If using serialized project settings, the saved field is commonly `customRenderPipeline`; writing a guessed field such as `renderPipelineAsset` is not enough unless the saved asset proves the assignment.
+   - If assigning through script, use the same pattern as URP's Render Settings converter: cache `QualitySettings.GetQualityLevel()`, call `QualitySettings.SetQualityLevel(index)` for each target level, assign `QualitySettings.renderPipeline = urpAsset`, then restore the original quality level and verify on disk.
+2. **Check URP asset settings** that commonly affect parity:
+   - shadows
+   - shadow distance and cascades
+   - MSAA
+   - render scale
+   - HDR, opaque texture, and depth texture settings when effects depend on them
+3. **Do not promise identical lighting automatically.**
+   - Built-in and URP can differ in light falloff, baked GI appearance, shadow tuning, reflection probe response, tonemapping, exposure, and post-processing behavior.
+4. **For baked lighting scenes,** treat existing lightmaps and Lighting Data as reference material, not guaranteed-final URP output.
+   - Inventory `Lightmapping.lightingSettings`, scene `LightmapSettings`, baked/mixed lights, light probes, reflection probes, and any existing `LightingDataAsset`.
+   - Preserve baked data until the user has a visual reference or rollback point, but do not keep stale Built-in lightmaps active as the final URP lighting solution if they blow out or distort the scene.
+   - If the scene looks blown out, too dark, or mismatched, first isolate post-processing/exposure by disabling legacy PPv2 during URP validation, then review URP Volume exposure/tonemapping/bloom before changing lights.
+   - If clearing baked data makes the scene stop being blown out, identify the old lightmaps/Lighting Data as stale or incompatible active data. Then rebake under URP with the final URP asset, renderer, Volume, and Quality settings instead of tuning lights against the stale bake.
+   - If creating or assigning URP-compatible `LightingSettings`, mark the lighting settings and active scene dirty, save the scene, reload or re-query, and verify the saved scene references the intended `.lighting` asset. `AssetDatabase.SaveAssets()` alone does not save the scene's `Lightmapping.lightingSettings` reference. Do not report "Baked GI enabled" if the saved scene still points at an Enlighten/realtime-GI settings asset.
+   - When visual parity is part of the request and old `LightingData.asset` / reflection-probe EXRs remain from the Built-in bake, treat them as reference data until rebaked/refreshed under URP. Do not claim visual parity is preserved from old bake data alone.
+   - Recommend clearing/rebaking lighting and refreshing reflection probes when visual parity matters. Do not claim baked lighting was successfully migrated unless a representative scene has been visually checked after URP setup, and preferably after a URP bake.
+5. **For 2D lighting projects,** ensure sprites and tilemaps use URP-compatible lit materials where required.
+6. **For performance regressions,** inspect whether the issue is coming from:
+   - heavier URP asset settings
+   - post-processing
+   - extra shadow cost
+   - custom shader ports or non-batched shaders
+7. **When changing URP asset settings,** re-read the saved asset or query the property after saving before reporting values such as MSAA, additional-light limits, HDR, depth texture, or opaque texture.
+# 10. Validation
+
+After setup, conversion, or troubleshooting, validate the result:
+
+1. **Capture the scene:** Capture the Scene View or a specific camera on a representative scene — see [references/capturing-the-editor.md](capturing-the-editor.md).
+2. **Evaluate the result:**
+   - no magenta materials unless unresolved custom shader blockers remain
+   - main lighting and shadows behave as expected
+   - baked GI/lightmaps, light probes, and reflection probes are acceptable or explicitly marked for rebake/refresh
+   - cameras render expected content
+   - post-processing or fullscreen effects still behave correctly
+   - sprites, tilemaps, or 2D lights work when relevant
+3. **Verify persistent project data, not only visual output.**
+   - Inspect saved URP assets, renderer assets, scene references, material shader GUIDs/names, Quality settings, and Volume profiles.
+   - Confirm the representative scene, not a default/test scene, was opened or otherwise inspected before concluding that baked lighting, PPv2, or reflection probes are absent.
+   - For material migration, include particle/VFX materials in the verification. Remaining built-in particle shader IDs or legacy particle shader names mean material migration is incomplete.
+   - For PPv2 migrations, saved URP `VolumeProfile` assets must contain the expected override components before reporting them as migrated.
+   - If a tool log reports mapped post-processing but the saved profile reloads with `components: []`, override the tool log and report the migration as failed/incomplete.
+   - For baked-lighting scenes, inspect Lighting Settings, Lighting Data/lightmap references, light probes, and reflection probes. Compilation success does not prove baked lighting parity. If old lightmaps cause overexposure, clear active baked data and rebake under URP before judging parity. After assigning new lighting settings, verify the saved scene reference, not only the existence of the new `.lighting` asset.
+   - If old `LightingData.asset` remains assigned and reflection-probe EXRs were not regenerated or explicitly accepted after visual inspection, classify lighting/probes as preserved or partial rather than refreshed.
+4. **Check Console output** with `Unity.GetConsoleLogs` for shader, render pipeline, or renderer-feature errors.
+5. **Fix the highest-impact issue first,** then validate again.
+6. **Repeat for at most 3 iterations** before reporting remaining blockers or asking the user how they want to proceed.
+# 11. Troubleshooting Decision Tree
+
+If the user reports a migration problem, follow this diagnostic flow:
+
+## Project still behaves like Built-in after "migration"
+1. Check whether a URP asset is assigned in Graphics settings.
+2. Check whether the relevant Quality levels also point to a URP asset.
+3. Verify that the active render pipeline is actually URP before troubleshooting anything else.
+
+## Migration stopped after installing URP
+1. Treat this as a package-refresh/domain-reload boundary, not a failed full migration by itself.
+2. Re-check `Packages/manifest.json` and package state. If URP is installed, do not reinstall it.
+3. Inspect for partial assets such as URP assets, renderer assets, converted materials, empty Volume profiles, and scene component changes.
+4. If URP is installed/assigned but Built-in materials still dominate or the scene is magenta, material conversion is the immediate next incomplete item. Do not call URP setup complete and stop there if rollback safety has already been confirmed.
+5. Continue from the first incomplete verification item: Graphics/Quality assignment, renderer asset validity, material conversion, PPv2-to-URP Volume migration, baked-lighting rebake, then final validation.
+6. If the previous chat/export has no final response, report it as incomplete evidence and continue in a fresh chat/turn.
+
+## Materials are magenta / bright pink
+1. Check Console and Inspector for shader errors.
+2. Confirm whether the material uses a supported Built-in shader, a custom shader, or a package-owned shader.
+3. If it is a supported Built-in shader, review the converter path or targeted material conversion first.
+4. If the project is already on URP and many supported Built-in materials remain, treat this as incomplete material conversion, not as final visual parity work.
+5. If it is a custom or package shader, move into [references/custom-shader-triage.md](custom-shader-triage.md) and, when needed, [references/complex-shader-situations.md](complex-shader-situations.md).
+
+## Scene is much darker, brighter, or just "wrong"
+1. Compare Scene View and Game View captures.
+2. Check for double post-processing first: retained PPv2 `PostProcessVolume` / `PostProcessLayer` plus an active URP `Volume` can overexpose or otherwise distort validation captures.
+3. Review shadows, ambient/environment lighting, tone mapping, skybox, exposure, bloom, and post-processing.
+4. Inspect baked lighting state: Lighting Settings, Lighting Data asset, lightmap references, mixed/baked lights, light probes, and reflection probes.
+5. Review quality-level assignments and URP asset settings before rewriting content.
+6. If clearing baked data fixes severe overexposure, treat the old lightmaps as stale active data: keep them only as reference/rollback evidence, then rebake under URP.
+7. If the scene depends on baked lighting, recommend a URP rebake and reflection-probe refresh before claiming visual parity.
+8. Remember that Built-in and URP light falloff can differ; treat that as a tuning task, not proof that conversion failed.
+
+## Post-processing or fullscreen effects disappeared
+1. Check whether PPv2 was converted and whether the target camera and volume setup are still valid.
+2. Inspect saved URP `VolumeProfile` assets. Empty profiles mean PPv2 effects were not actually migrated.
+3. Check whether old `PostProcessVolume` / `PostProcessLayer` components remain active in scenes.
+4. Search for `OnRenderImage`, custom blit code, or replacement-shader camera effects.
+5. Port the effect using a URP-compatible approach rather than trying to preserve the Built-in callback path unchanged.
+
+## Transparent / refraction / distortion effects broke
+1. Inspect whether the shader relied on `GrabPass` or a similar Built-in screen-copy workflow.
+2. If so, use [references/complex-shader-situations.md](complex-shader-situations.md) and choose a Scene Color / Renderer Feature / custom-pass approach.
+
+## 2D lights are not affecting sprites
+1. Confirm the project is actually using the 2D Renderer.
+2. Confirm existing sprite materials were upgraded to URP-compatible lit materials where needed.
+3. Do not assume dragged-in new sprites prove old project materials are correct.
+
+## Performance regressed after migration
+1. Review render scale, shadows, additional lights, MSAA, post-processing, opaque/depth textures, and other URP asset settings.
+2. Check whether custom shader ports lost batching compatibility or introduced extra passes.
+3. Tune settings before assuming the only answer is a rollback.
+
+## Custom shader compiles but visuals are still wrong
+1. Determine whether the issue is simple parameter drift or a structural incompatibility.
+2. If the shader came from a surface shader, `GrabPass`, replacement-shader workflow, or custom lighting path, treat it as a complex migration case.
+3. Validate one representative material before rolling the approach out project-wide.

package/skills/migrate-birp-to-urp/references/preflight-and-urp-setup.md

@@ -0,0 +1,195 @@
+# Detecting the active render pipeline
+
+```csharp
+var rp = UnityEngine.Rendering.GraphicsSettings.defaultRenderPipeline;
+var qrp = UnityEngine.QualitySettings.renderPipeline;
+return $"graphics={(rp == null ? "NULL (Built-in)" : rp.GetType().Name + ":" + rp.name)}, "
+     + $"activeQualityLevel={(qrp == null ? "inherits Graphics" : qrp.GetType().Name + ":" + qrp.name)}";
+```
+
+A `UniversalRenderPipelineAsset` means URP; `HDRenderPipelineAsset` means HDRP; `NULL` on both
+means Built-in. **Check the per-quality-level assignment too** — a project can be switched in
+Graphics settings while a Quality level still points at a different asset, or at none:
+
+```csharp
+var names = UnityEngine.QualitySettings.names;
+var rows = new System.Collections.Generic.List<string>();
+for (int i = 0; i < names.Length; i++)
+{
+    var a = UnityEngine.QualitySettings.GetRenderPipelineAssetAt(i);
+    rows.Add($"{i}:{names[i]}={(a == null ? "inherits Graphics" : a.name)}");
+}
+return string.Join(", ", rows);
+```
+
+If `GetRenderPipelineAssetAt` is unavailable in the project's Unity version, read
+`ProjectSettings/QualitySettings.asset` instead rather than switching levels at runtime —
+`SetQualityLevel` mutates project state.
+# Critical Default
+
+For simple requests like "migrate this Built-in project to URP" or "move this project to URP", start or resume the safe migration workflow rather than jumping straight to conversion.
+
+A generic upgrade prompt must not require the user to mention every migration risk. Inspect and handle common Built-in dependencies such as PPv2, baked lighting/lightmaps, reflection probes, particle/fog/smoke materials, Quality levels, camera post-processing, and representative scene validation.
+
+Default result is phase-based:
+
+1. Detect whether the project is Built-in, partially migrated, already URP, or HDRP.
+2. Classify the request as standard 3D URP, URP 2D, selected-material conversion, planning-only, or troubleshooting.
+3. Inspect migration risks before recommending changes: opaque materials, particle/VFX materials, custom shaders, post-processing, camera effects, baked lighting/lightmaps/reflection probes, Quality levels, and representative scenes.
+4. Stop before any pipeline-mutating work until the user confirms a rollback point such as a branch, backup, archive, or disposable copy. Pipeline-mutating work includes installing URP, assigning a URP asset in Graphics/Quality settings, running converters, and editing materials or scenes.
+5. Choose the next migration phase, execute that phase, save/re-query its outputs, and report its phase status.
+6. Treat custom shaders, `GrabPass`, Surface Shaders, `OnRenderImage`, replacement shaders, and package-owned shaders as scoped follow-up work, not automatic converter work.
+7. Validate representative scenes, Console output, camera rendering, lighting/baked GI state, materials, post-processing persistence, and quality-level assignments before declaring full migration success.
+
+Default phases:
+
+- Phase 0: Inspect and plan. Detect pipeline state, representative scenes, rollback safety, PPv2, material/shader risks, Quality levels, lighting/lightmap/probe state, and custom render code.
+- Phase 1: URP setup and supported material conversion. Install/reuse URP, create/assign URP assets in Graphics/Quality, convert supported opaque and particle/effect materials, and verify no supported materials remain on Built-in shaders.
+- Phase 2: Post-processing and camera migration. Create persistent URP Volume profiles, wire scene Volumes/camera post-processing, disable legacy PPv2 for URP validation, and classify unsupported PPv2 effects such as SSR.
+- Phase 3: Lighting, lightmaps, and reflection probes. Resolve stale Built-in lighting state, configure URP lighting/probe settings, rebake/refresh when feasible, or clearly mark lighting/probes partial.
+- Phase 4: Final validation and report. Save/reload/re-query project state, capture representative scenes, check Console, and report complete/incomplete/manual items.
+
+One turn may complete multiple phases if the project is small and Unity remains stable, but do not force all phases into one response. Prefer an honest phase boundary over an over-claimed "complete" result.
+
+Ask configuration questions only when the project state or user intent leaves a real decision unresolved. If the user says "do not modify files", stay in audit/planning mode and do not perform conversion or asset edits.
+
+## Generic Upgrade Contract
+
+When the user gives a generic migration request and permits changes, drive the next phase from the project state:
+
+1. Do not ask the user to enumerate known Built-in features before inspection. Discover them.
+2. If PPv2, baked lighting, reflection probes, particle/fog/smoke materials, or multiple Quality levels exist, include them in the migration automatically.
+3. Prefer phase completion over all-in-one completion. Each phase should save/re-query its own outputs and end with `Phase complete`, `Phase partial`, or `Blocked`.
+4. If Unity compilation, package installation, domain reload, or a long lighting bake interrupts the pass, report the interruption as a phase boundary and resume from saved partial state in the next turn rather than starting over.
+5. Do not rely on the user writing a detailed checklist prompt to get correct behavior. The detailed checklist is for benchmarking or stress testing; normal user prompts should still trigger this phased contract.
+6. A generic migration request gives permission to inspect and plan, but it does not prove rollback safety. If no rollback point is confirmed, stop before package install or URP assignment and ask for confirmation. Do not leave the project in a magenta partial state just to reach the backup question.
+7. If rollback safety is already confirmed or the user says the project is a disposable copy, continue within the current phase without asking again for routine work.
+8. At the end of a phase, give a concise next-phase prompt or say what phase should run next. Ask for confirmation before the next phase only when it introduces a new costly or risky operation, such as a long lighting bake, deletion/cleanup of legacy assets, or a custom shader rewrite.
+9. If rollback safety was confirmed and ordinary work inside the active phase remains incomplete, do not ask "would you like me to continue?" Continue repairing that phase until its gate passes, a tool/domain-reload boundary interrupts execution, or a genuinely new risky decision appears.
+
+## Generic Migration Success Gate
+
+Before saying a generic migration is "successful", "complete", or "fully migrated", verify saved project state, not just tool logs:
+
+1. Graphics settings and every relevant Quality level point to the intended URP asset.
+2. The URP asset has a valid default renderer in saved state, and current Console output does not contain unresolved render-pipeline errors such as "Default Renderer is missing". If a renderer error appears after assignment, re-query the saved renderer list/default index, clear stale Console output when possible, trigger a fresh scene/camera validation, and continue repair instead of stopping at "URP setup complete".
+3. Supported Built-in materials, including particle/fog/smoke materials, have URP-compatible shaders or are explicitly listed as unresolved custom/package shader cases. Textured/colorized source materials must preserve their source maps/colors; a URP shader assignment with missing `_BaseMap` or all-white `_BaseColor` is incomplete if the source `_MainTex` or `_Color` had content. Particle, fog, smoke, steam, decal, VFX, additive, and transparent effect materials should not be blindly forced to `Universal Render Pipeline/Lit`; prefer URP particle/effect shaders such as `Universal Render Pipeline/Particles/Unlit` when appropriate.
+4. If the source scene used PPv2, a saved URP `VolumeProfile` exists with persistent non-null override components, the representative scene references it through a URP `Volume`, and legacy PPv2 is disabled for URP visual validation. A saved profile with `components: []`, `{fileID: 0}` component refs, or a scene that still only references the old `PostProcessProfile` is incomplete.
+5. If the representative scene uses baked/mixed lighting, an Enlighten/realtime-GI Lighting Settings asset, a Lighting Data asset, lightmaps, light probes, or reflection probes, do not leave routine lighting/probe repair as manual follow-up during a generic full migration. Attempt URP-compatible Lighting Settings assignment, clear/rebake or resume a bake when needed, refresh reflection probes when feasible, then save/reload and verify the scene references the intended lighting state. Creating a `.lighting` asset and calling `Lightmapping.lightingSettings = target` plus `AssetDatabase.SaveAssets()` is not enough; mark/save the scene, reload/re-query, and compare the saved scene `m_LightingSettings` reference or asset GUID. If a long bake or tool interruption prevents this, call the migration partial and resume from that phase.
+6. A representative scene has been opened or selected deliberately before migration validation; do not infer baked-lighting or PPv2 absence from a default/test scene. The scene has been captured or inspected after saving/reloading, and Console output has been checked for render-pipeline, shader, or renderer-feature errors.
+7. Final wording must match the gate result. Use "complete" only when every gate passes. Use "partial" when URP is set up but PPv2 Volume persistence, legacy PPv2 disablement, lighting bake/probe refresh, or saved-state validation remains. Do not start the final response with "successfully migrated" if any required gate is partial.
+
+Complete-report checklist:
+
+- If the old PPv2 profile contains active `DepthOfField`, the new URP profile must contain a saved `DepthOfField` override or the final report must call it omitted/manual.
+- If the old PPv2 profile contains active `AmbientOcclusion`, configure a URP SSAO renderer feature when feasible, or mark AO as manual/partial.
+- If the old PPv2 profile contains active `ScreenSpaceReflections`, list SSR as unsupported/manual unless a URP renderer-feature/custom replacement was actually added and validated.
+- If the scene still serializes the old Lighting Settings GUID or a non-zero old `m_LightingDataAsset`, lighting is partial.
+- If the scene has reflection probes and the URP asset still serializes `m_ReflectionProbeBlending: 0` or `m_ReflectionProbeBoxProjection: 0`, reflections are partial unless intentionally disabled and reported.
+- If any checklist item is false, do not use "complete", "fully migrated", or "fully functional on URP" in the final answer.
+
+Unsupported features can remain manual, but name them precisely. Examples include PPv2 Screen Space Reflections needing a URP renderer-feature/custom/third-party replacement, complex custom shader ports, `GrabPass`, replacement shaders, or package-owned rendering code. If any success-gate item fails, continue repairing when allowed or report a partial migration with incomplete items; do not present the project as fully migrated.
+
+Regression guard summary:
+
+- Use the detailed [Execution Regression Checklist](implementation-patterns.md#execution-regression-checklist) for actual migration or repair work.
+- Verify saved scene references before status claims: URP Volume/profile, Quality assignments, Lighting Settings/Data, URP asset/renderer, and reflection-probe settings.
+- Preserve material source data from a pre-conversion snapshot, then restore `_BaseMap`, `_BaseColor`, texture scale/offsets, and relevant maps after shader changes.
+- Validate representative visuals for PPv2, foliage, particles/effects, baked lighting, probes, and exposure before final wording.
+- Report exact phase status. `Phase complete` is allowed for a passed phase; project-level `complete` is allowed only when every success gate passes.
+# 0. Pre-Flight: Pipeline Detection and Reference Loading
+
+Before doing anything else, you **must determine the active render pipeline and migration mode**:
+
+1. **Detect Pipeline:** Run the render-pipeline detection snippet from the execution-path section above.
+   - If `currentRenderPipeline` or `defaultRenderPipelineAsset` references a `UniversalRenderPipelineAsset` -> **URP**.
+   - If no render pipeline asset is assigned -> **Built-in**.
+   - If it references an `HDRenderPipelineAsset` -> **HDRP**. Explain that this skill only covers Built-in to URP migration. Basic comparison advice is fine, but do not drive an HDRP migration with this skill.
+2. **Load Base Reference:** Read [references/migration-workflow.md](migration-workflow.md).
+3. **Load Shader References When Relevant:** If the request mentions materials, shaders, magenta materials, rendering errors, image effects, or custom rendering, also read:
+   - [references/custom-shader-triage.md](custom-shader-triage.md)
+   - [references/complex-shader-situations.md](complex-shader-situations.md) when inspection or project-file search finds advanced shader/effect patterns
+4. **Load Quality Reference When Relevant:** If the request mentions shadows, lighting, baked lighting, lightmaps, reflection probes, quality settings, visual mismatch, or performance after migration, also read [references/quality-settings-map.md](quality-settings-map.md).
+5. **Load Implementation Patterns When Executing:** If the request permits actual migration changes, post-processing conversion, baked-lighting/probe repair, or resume from a partial migration, also read [references/implementation-patterns.md](implementation-patterns.md).
+6. **Classify the Request** as one of:
+   - Full-project Built-in to URP migration
+   - Built-in 2D to URP 2D migration
+   - Selected material-only conversion
+   - Planning / explanation only
+   - Troubleshooting after a previous migration
+7. **If the project is already on URP,** switch to troubleshooting mode instead of re-running setup blindly.
+8. **Proceed** only after the pipeline and migration path are clear.
+# 1. Assess Current Migration State
+
+Before making any changes, **inspect what already exists**:
+
+1. **Inspect pipeline state and assignment points:**
+   - Run both render-pipeline detection snippets from the execution-path section above — the Graphics-settings one and the per-quality-level one.
+   - If the project has Quality levels, inspect which Render Pipeline Asset each level uses before assuming the project is fully switched.
+2. **Inventory migration surfaces:** Use `script eval` with `UnityEditor.AssetDatabase.FindAssets` or equivalent asset queries to inventory:
+   - materials, including particle/VFX materials that often use built-in particle shaders
+   - vegetation materials, including grass, tree, terrain-detail, SpeedTree, billboard, leaf-card, cutout, and wind-driven foliage materials
+   - shaders
+   - scenes and important prefabs
+   - URP assets and renderer assets, if any
+   - post-processing profiles / volume profiles
+   - Lighting Settings assets, Lighting Data assets, lightmaps, light probes, reflection probes, and mixed/baked lights
+3. **Scan for rendering risk markers:** Use available project-file search, `AssetDatabase.FindAssets`, or a short `script eval` file scan to search the project for rendering-specific patterns such as:
+   - `PostProcessLayer`, `PostProcessVolume`, `UnityEngine.Rendering.PostProcessing`
+   - `OnRenderImage(`, `RenderWithShader`, `SetReplacementShader`
+   - `#pragma surface`, `GrabPass`, `CGPROGRAM`
+   - `CommandBuffer`, custom shader include paths, or package shader namespaces
+   - vegetation markers such as `Nature/`, `SpeedTree`, `TreeCreator`, `Grass`, `Foliage`, `_Cutoff`, `_AlphaClip`, `_Cull`, billboard, or wind keywords
+4. **If PPv2 is installed but grep finds nothing,** inspect open scenes and profile assets through Unity APIs by component/type. Scene YAML and serialized package references can be missed by text search.
+5. **Determine project shape:** Decide whether the project is primarily 3D, primarily 2D, or mixed.
+6. **Report Findings:** Summarize the current state before proposing conversion. Example:
+   - "The project is still on Built-in, has no URP asset assigned, contains PPv2 references, and includes several custom shaders using surface-shader syntax."
+# 2. Gather Requirements
+
+Determine what the user actually wants. If the request is ambiguous, ask.
+
+Use these defaults for common requests:
+
+| User says | Default interpretation |
+|-----------|------------------------|
+| "Upgrade this project to URP" | Full-project migration |
+| "Move this 2D project to URP" | Built-in 2D to URP 2D migration |
+| "Convert these materials" | Targeted material conversion |
+| "My materials turned pink" | Post-migration shader/material troubleshooting |
+| "Lighting looks wrong after URP" | Quality and visual parity troubleshooting |
+| "Do not change anything yet" | Planning / audit only |
+
+## Information to Gather
+
+- **Scope:** full project, selected materials, or troubleshooting only
+- **Target renderer:** standard URP or URP 2D
+- **Validation targets:** which scenes, prefabs, or cameras matter most to the user
+- **Risk tolerance:** whether limited manual follow-up is acceptable
+- **Rendering dependencies:** custom shaders, Asset Store shaders, PPv2, baked lighting/lightmaps/probes, image effects, command buffers, replacement shaders, or multiple Quality levels
+- **Execution permission:** planning only vs actual project changes
+# 3. Safety Gate
+
+Before any pipeline-mutating step:
+
+1. **Confirm rollback safety.**
+   - NEVER install URP, assign a URP asset, run the Render Pipeline Converter, edit materials, or edit migration scene state before the user confirms a backup, branch, archive, disposable copy, or rollback point.
+   - If rollback safety is missing, do not partially switch the project to URP. Stop in planning mode and ask for the rollback confirmation first.
+2. **Separate engine-upgrade risk from pipeline-upgrade risk.**
+   - If the project is also moving to a new Unity version, recommend doing the engine upgrade first and the pipeline migration second. Do not treat both as a single blind operation.
+3. **If rollback safety is confirmed,** treat it as covering the whole migration pass. Do not ask again before each converter; proceed through setup, material conversion, PPv2 migration, lighting/probe work, save/reload verification, and final reporting unless a new risky decision appears.
+4. **If the user already authorized a full disposable migration,** do not ask for permission to continue after routine setup or recoverable errors. Continue with the next incomplete migration phase. Ask only when a new destructive cleanup decision appears, a package/domain reload stops execution, or repeated repair attempts hit the validation iteration limit.
+4. **If the project is already partially migrated,** identify whether rollback safety was previously confirmed. If yes, resume from the first incomplete item. If no, report the partial state and ask before making additional changes.
+# 5. URP Setup Workflow
+
+Follow this exact setup order:
+
+1. **Ensure URP is installed.**
+   - Installing URP can trigger package refresh, compilation, and domain reload. Treat this as a phase boundary.
+   - Do not spin-wait indefinitely inside an `script eval` call on `UnityEditor.PackageManager.Client.Add`. Request installation, then verify through `Packages/manifest.json`, package listing, or the presence of URP types/assets after Unity finishes refreshing.
+   - If the package install causes the `script eval` call to time out or return nothing, resume in a fresh turn after Unity finishes compiling. Do not restart the whole migration or reinstall URP; inspect the partial state and continue from there.
+2. **Create the required URP asset and renderer asset** if they do not already exist.
+3. **Assign the URP asset in Graphics settings** and in all relevant Quality levels.
+4. **For 2D projects,** create and assign the correct 2D Renderer asset before conversion.
+5. **If a URP asset already exists,** inspect and reuse it when appropriate instead of creating duplicates automatically.
+6. **Do not continue** until URP is actually the active render pipeline for the target configuration.
+