@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/skills/migrate-birp-to-urp/references/quality-settings-map.md

@@ -0,0 +1,69 @@
+# Quality Settings Map
+
+Use this map to explain where common Built-in quality settings end up after URP migration.
+
+## Official References
+
+- [Convert Built-in quality settings to URP](https://docs.unity3d.com/Manual/urp/birp-onboarding/quality-presets.html)
+- [Find Built-in quality settings in URP](https://docs.unity3d.com/Manual/urp/birp-onboarding/quality-settings-location.html)
+- [Universal Render Pipeline asset](https://docs.unity3d.com/Manual/urp/urp-asset-and-renderer.html)
+- [Change how lights fade to match the Built-In Render Pipeline](https://docs.unity3d.com/Manual/urp/birp-onboarding/birp-light-falloff-in-urp.html)
+
+## Common Mappings
+
+| Built-in concept | URP location |
+| --- | --- |
+| Render Pipeline Asset | `Project Settings > Quality > Rendering > Render Pipeline Asset` |
+| Default pipeline assignment | `Project Settings > Graphics > Render Pipeline Asset` |
+| MSAA | `URP Asset > Quality > Anti-aliasing (MSAA)` |
+| Camera anti-aliasing | `Camera > Rendering > Anti-aliasing` |
+| Main light shadows | `URP Asset > Lighting > Main Light > Cast Shadows` |
+| Additional light shadows | `URP Asset > Lighting > Additional Lights > Cast Shadows` |
+| Main light shadow resolution | `URP Asset > Lighting > Main Light > Shadow Resolution` |
+| Additional light shadow atlas and tiers | `URP Asset > Lighting > Additional Lights > Shadow Atlas Resolution` and `Shadow Resolution Tiers` |
+| Shadow distance | `URP Asset > Shadows > Max Distance` |
+| Shadow cascades | `URP Asset > Shadows > Cascade Count` and split controls |
+| HDR | `URP Asset > Quality > HDR` |
+| Depth texture | `URP Asset > Rendering > Depth Texture` |
+| Opaque texture | `URP Asset > Rendering > Opaque Texture` |
+| Real-time reflection probes | `Project Settings > Quality > Rendering > Real-time Reflection Probes` |
+| Resolution scaling | `Project Settings > Quality > Rendering > Resolution Scaling Fixed DPI Factor` and `URP Asset > Quality > Render Scale` |
+| LOD cross fade | `URP Asset > Quality > LOD Cross Fade` |
+| Baked GI / lightmaps | Scene Lighting Settings, `LightmapSettings`, Lighting Data asset; verify visually and rebake under URP when parity matters |
+| Reflection probe bake data | Scene reflection probes; refresh/rebake after URP lighting and post-processing settings are finalized |
+
+## Guidance
+
+- Many settings that used to live only in Built-in quality settings are split between Project Settings and the URP asset.
+- Treat the official URP values as a starting point, not a promise of identical performance or visuals.
+- After migration, verify the user's important quality levels explicitly instead of assuming Low and High presets still behave the same way.
+- A Quality level with no custom render pipeline asset may fall back to Graphics settings. That can be acceptable, but state this explicitly instead of claiming that Quality was fully assigned.
+- For full-project migrations, prefer assigning the intended URP asset to all relevant runtime Quality levels unless the project deliberately relies on Graphics settings fallback.
+- When validating on disk, look for each Quality level's saved `customRenderPipeline` entry. `{fileID: 0}` means that level has no explicit pipeline asset, even if Graphics Settings has a URP asset.
+- If using scripts or serialized project settings to assign Quality assets, verify by re-querying after saving. Do not trust a guessed serialized field name or a command log that says assignment happened.
+- In Unity versions without a direct per-index setter, use the converter-style assignment pattern: store `QualitySettings.GetQualityLevel()`, call `QualitySettings.SetQualityLevel(index)`, set `QualitySettings.renderPipeline = urpAsset`, repeat for each target level, restore the original level, then verify saved `customRenderPipeline` references. Do not invent APIs such as `QualitySettings.SetRenderPipelineAssetAt`.
+- Light falloff and overall scene brightness can differ between Built-in and URP. Treat that as a tuning step, not automatically a failed migration.
+- Baked GI, lightmaps, light probes, and reflection probes are visual-parity risks. Preserve existing baked data as reference, but recommend a URP rebake/refresh when the scene depends on baked lighting.
+- If a migrated scene is extremely bright or washed out, check for double post-processing first: retained PPv2 components/layers plus an active URP Volume can stack exposure, bloom, tonemapping, or color grading during validation.
+- If a migrated scene is too dark, too flat, or still high contrast after material and PPv2 migration, treat exposure balance as part of visual validation. Verify URP post-processing wiring first, then tune Volume exposure/tonemapping/lift-gamma-gain, ambient fill, additional-light limits, and shadow settings with representative captures.
+- If clearing baked data makes the scene stop being washed out, classify the old Built-in lightmaps or Lighting Data as stale active data. Preserve them as reference, but clear active baked data and rebake under URP before final tuning.
+- If a new Lighting Settings asset is created for URP baked GI, verify the saved scene references it after saving/reloading. A `.lighting` asset with baked GI enabled is not active if the scene still points to the old Enlighten/realtime-GI settings asset.
+- Do not claim baked lighting parity from compile success, material conversion, or URP asset assignment alone.
+
+## Validation Checklist
+
+After migration or troubleshooting:
+
+1. Confirm the correct URP asset is assigned in Graphics settings.
+2. Confirm each relevant Quality level points to the expected URP asset.
+   - If it does not, report whether this is intentional fallback behavior or an incomplete migration item.
+3. Compare shadow distance, cascades, and shadow resolution against the user's expected look.
+4. If fullscreen effects depend on them, verify whether depth texture and opaque texture are enabled.
+5. If the user reports blurrier or sharper visuals, review MSAA, render scale, and camera anti-aliasing.
+6. If lighting looks "off," review light falloff, post-processing, active PPv2/URP volumes, and ambient/environment settings before rewriting content.
+7. For baked-lighting scenes, inspect Lighting Settings, `LightmapSettings`, baked/mixed lights, light probes, reflection probes, and Lighting Data assets.
+8. If old lightmaps are causing severe overexposure, clear active baked data before final URP validation.
+9. If visual parity matters, rebake lighting under URP and refresh reflection probes after URP renderer, Quality, and Volume settings are finalized.
+10. After assigning new Lighting Settings, save the scene and verify the scene reference, not only the settings asset contents.
+11. If the final capture is too dark or too bright, verify renderer `PostProcessData`, camera `renderPostProcessing`, camera volume layer mask, active Volume weight/priority/layer, and saved VolumeProfile overrides before changing lighting.
+12. When exposure balance is required, prefer bounded changes to `ColorAdjustments.postExposure`, contrast, saturation, `Tonemapping`, `LiftGammaGain`, Bloom, ambient sky color/intensity, additional-light count, and shadow settings. If extreme values are only compensating for missing GI or an unfinished bake, report lighting parity as partial.

package/skills/new-unity-project/SECURITY.md

@@ -0,0 +1,26 @@
+# Security notes: new-unity-project
+
+This skill has the agent install Unity Editors and packages, create a cloud-linked project, run C#
+inside the user's Editor (the visual baseline), write one small bootstrap script into the project,
+and append one line to the project's CLAUDE.md or AGENTS.md. Automated skill scanners flag several
+of these as powerful capabilities. They are intentional, and limited by the safeguards below.
+
+## Accepted risks
+
+| Risk | Capability | Why it is accepted |
+|---|---|---|
+| `SEC_POWER_CAP` | Runs C# in the user's Editor | It only reaches the Editor the user already has open, on their own machine, as that user; the commands sit behind the Pipeline capability gate. No code fetched from a remote source is run — the agent runs C# it writes from this skill's and its delegated skills' own recipes. |
+| `SEC_FILE_WRITE` | Writes one bootstrap script (Step 6) and appends one line to CLAUDE.md/AGENTS.md (Step 9) | Both writes land inside the project the skill just created and both are surfaced before they run: in paved mode as notice with an opt-out on the assumptions manifest ("say the word to change any of these"), in guided mode as per-step asks that are true consent. Both are reversible on a word, and the scope section caps the skill at exactly one bootstrap script. |
+| `SEC_INSTALL` | Installs Editors, modules, packages, and (with the user's yes) agent skills | Installs go through the Unity CLI's own commands and the PackageManager API — never `curl \| sh`, never hand-edited manifests. Skill installs always ask first (Before Step 1). Versions and the package list are declared before installing. |
+| `SEC_CLOUD` | Creates a cloud-linked Unity project with diagnostics per the CLI's defaults | The link is `projects create`'s own default behavior, narrated to the user from the create result. Sign-in is a human gate: it runs only after the user's yes, and the user completes it in the browser. `--bare` and the link opt-outs are honored on the user's word. |
+
+## Mitigations
+
+- **The manifest is the notice-and-opt-out surface** in paved mode: every assumption — the file
+  writes and the cloud-link narration included — prints in one block before the create launches,
+  and any line reverses on a word. Consent in the strict sense comes from guided mode's per-step
+  asks; paved mode's bar is that nothing runs unannounced and nothing is irreversible.
+- **Human gates are never consumed.** Sign-in, license activation (including accepting the Unity Personal EULA) and publishing each run only after the user says yes to a question the agent asks and waits on.
+- **Only the user's own Editor and account.** Everything runs on this machine as this user.
+- **No remote code.** All executed C# comes from this skill's text and its delegated skills.
+- **Named commands first.** Where a dedicated `unity` command covers a step, the skill uses it.

package/skills/new-unity-project/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: new-unity-project
+description: Guides creating a new Unity project, from concept, platforms, and monetization to source control and packages. Use when the user asks to start a new game or prototype. Runs an opinionated paved path by default.
+allowed-tools:
+  - Bash
+  - Write
+  - Edit
+---
+
+# New Unity Project
+
+A flow from an idea to a running, version-controlled Unity project. This skill owns the **flow** —
+mode, defaults, ordering, background installs, handoffs.
+
+**Delegates to (read these for the actual commands — don't reinvent them):**
+- **`unity-cli`** — install, auth/license, Editor install, creation, source control, open. Its
+  "Bootstrap a new project from scratch" workflow is the backbone here.
+- **`unity-package-management`** — packages with the Pipeline `package` commands (C# script fallback).
+- **`urp-postprocessing`**, **`ui`**, **`2d-pixel-perfect`** — visual-baseline mechanics (Step 7).
+- **`craft-game-floors`** — the craft floors (look, feel, audio, shell, live floor, the done gate),
+  loaded at Step 6 and carried through the build.
+- **`implement-in-app-purchases`**, **`levelplay-unity-integration`**, **`build-live-game`** —
+  monetization / backend *integration* (invoked at the end).
+
+## Mode: paved by default, guided on request
+
+Run **paved** unless the user asks for the interview — in words ("ask me questions", "guide me")
+or by pushing back on the manifest; mode is decided once per session. The paved contract:
+**parse the prompt first** · **fill gaps from the Defaults table** · **print the manifest** before
+the create launches · **proceed**, asking only on pushback or an unruled fork ·
+**never consume a human gate** — sign-in, license activation and publishing each need the user's
+yes, asked as a question you wait on (see Sign-in and license). A **bare/minimal** ask gets
+`--bare`, skips the floors, and states the cost (identity, saves, ranks unwired). Bare runs Steps
+1–4, installs only the packages the user named in Step 5, skips Steps 6 and 7, then commits (Step 8)
+and hands off monetization (Step 9) without the forward baton.
+
+In **guided** mode, ask only the current step's questions and wait. The paved additions (identity,
+floors, baton) are asked at their steps there, never assumed.
+
+## Sign-in and license (before your first question)
+
+Run `unity auth status --format json` and `unity license status --format json` first. If either
+shows the user signed out or without an active license, ask **one** question that covers both,
+with your client's multiple-choice question tool (plain text only without one), and wait for the
+answer. Send it together with the delegated-skills offer (below) and any Step 1 question, so the
+user answers once. Offer the free
+**Unity Personal** license as the default choice, with the other license types (a subscription the
+account already has, a serial, a floating server) as alternatives. The Personal choice itself says
+that picking it accepts the Unity Personal EULA
+(https://unity.com/legal/editor-terms-of-service/software), so the user sees it before answering.
+
+- Never tell the user to sign in or activate a license themselves, and never hand them commands to
+  run. You run them, after they say yes.
+- On yes, sign in only where the choice needs an account: Personal and an existing subscription
+  activate the signed-in user's licenses, and a cloud-linked project needs one too. Run
+  `unity auth login` then (it opens the browser; the user only completes the sign-in page, so tell
+  them that page is coming), in the background or with its output unfiltered, and pass on the
+  sign-in link it prints in case the browser doesn't open: a pipe through `tail` holds the link
+  back until sign-in ends. Then `unity license activate --personal --accept-eula` for Personal.
+  Serial and floating activation need no account: `unity license activate --floating`, or the
+  serial through `UNITY_LICENSE_SERIAL` and a bare `unity license activate`, so it stays off argv.
+- Declining stops the run before the create only when nothing can license the Editor. A user who
+  declines sign-in but has, or activates, a serial or floating license still gets a local project:
+  create with `--no-cloud` and say the cloud link and player accounts are off.
+
+## The Defaults table
+
+Every row reverses on a word; change a row only with a run-earned receipt.
+
+| Decision | Paved opinion |
+|---|---|
+| Editor version | `--editor-version latest`, explicit |
+| Template | URP; 3D unless the prompt says 2D (`--template 3d` or `2d`) |
+| Platforms | Desktop only; add modules when the prompt implies them ("mobile game" → ios/android) |
+| Monetization | None at creation; noted for later |
+| Version control | Local git + Unity .gitignore |
+| Player identity | Anonymous accounts — create's when its result shows them, else wired in Step 6 |
+| Craft floors | Always on, via the `craft-game-floors` skill: look, camera, lighting, feedback, audio, shell, live floor, done gate |
+
+Cloud link and diagnostics are **not** a row: create applies its own defaults — narrate them from
+the result, don't re-decide.
+
+## The assumptions manifest
+
+Print exactly one block at the end of Step 2, before the create launches. It **predicts** what
+create will do (the URP template per `--template 3d|2d`, never a guessed id):
+
+> **Paved assumptions:** Unity <editor> · <URP template, 2D/3D> · <platforms> · <monetization> ·
+> anonymous player accounts (create's, else one bootstrap script) · <version control> ·
+> cloud-linked with diagnostics (create's defaults, narrated from the result) · floor packages
+> (Cinemachine; identity + live services when cloud-linked) · craft floors on via `craft-game-floors` ·
+> a one-line handoff note for the project's CLAUDE.md, written only on your yes.
+> Say the word to change any of these; otherwise I'm proceeding.
+
+One block, every assumption present, each reversible, nothing implied; Step 3 reconciles the
+result against it.
+
+## Before Step 1: check the delegated skills are loaded
+
+Look for `unity-cli`, `unity-package-management`, `urp-postprocessing`, `ui`, `build-live-game`
+and `craft-game-floors` in your client's skills. If any is missing, say which and what it does, and offer the install routes
+in [references/skill-setup.md](references/skill-setup.md), in the same question as sign-in and
+license when that one goes out — never install without a yes. Don't
+stall: a decline gets the fallback at its step, gap named in the report. `unity skill show` prints
+`unity-cli` without installing; without `unity-package-management`, Step 5 can't run — say so
+before Step 2.
+
+## The flow — and where the parallelism is
+
+1. **Concept** (paved: parsed from the prompt). 2. **Platforms & monetization** — print the
+manifest (paved), then **start the create in the background**: `projects create --install-editor`
+installs the Editor + modules (minutes), then creates the project; keep talking meanwhile.
+3. **(joins)** reconcile the result against the manifest. 4. **Source control.** 5. **Packages.**
+6. **Player identity, then the craft floors** — confirm create's identity or wire it; load
+`craft-game-floors`. 7. **Visual baseline** on the craft skill's art bible. 8. **Save & first commit.**
+9. **Hand off** + the forward baton.
+
+The multi-minute Editor install overlaps the user's answers, so setup feels instant.
+
+## Step 1 — Concept
+
+Paved runs parse the prompt into a 2–4 line brief; guided runs ask for it. Read [step 1 — concept](references/step-1-concept.md) before the template choice or any guided question: it lists the brief's fields and what the brief later drives.
+
+## Step 2 — Platforms & monetization, then start installing
+
+Two decisions, then the manifest prints, then the create starts in the background. Read [step 2 — platforms, monetization, and the create](references/step-2-platforms-and-create.md) before you launch a project: it has the exact `unity projects create` flags, the template rules, and the module mapping.
+
+## Step 3 — Join: project ready, result reconciled
+
+Read [step 3 — join and reconcile](references/step-3-join-and-reconcile.md) when the background create returns: it names the result fields, the manifest reconciliation, the cloud-link 403 retry, and the missing-module follow-up.
+
+## Step 4 — Source control
+
+Read [step 4 — source control](references/step-4-source-control.md) before attaching a repo: it holds the `link vcs` flags, why `--no-initial-commit`, and the Unity Version Control option.
+
+## Step 5 — Packages
+
+Never hand-edit `manifest.json`. Read [step 5 — packages](references/step-5-packages.md) before installing: it has the paved package set, the bare-run exception, and the render-pipeline warning.
+
+## Step 6 — Player identity, then the craft floors
+
+Read [step 6 — player identity and the craft floors](references/step-6-identity-and-floors.md) once packages land: it decides identity from the create result, never wires auth twice, and says when to load `craft-game-floors`.
+
+## Step 7 — Visual baseline
+
+Read [step 7 — visual baseline](references/step-7-visual-baseline.md) before opening the Editor and before any gameplay work: it carries the Pipeline-install-before-open order, the 6000.5.0–6000.5.2 blocker, and all six baseline items with their URP/Built-in caveats. A `--bare` run skips it.
+
+## Step 8 — Save & first commit
+
+Read [step 8 — save and first commit](references/step-8-first-commit.md) to commit with the VCS from Step 4: it has the git sequence, the `.meta` requirement, and the mirrored-skills question.
+
+## Step 9 — Hand off
+
+Read [step 9 — hand off](references/step-9-handoff.md) at the end: it routes monetization to the matching integration skill, gives the forward-baton wording, and lists what the report must contain.
+
+## Scope — what this skill does NOT do
+
+- **No gameplay scaffolding.** A running, wired project with a visual floor; the game is the next
+  conversation (with `craft-game-floors`). One exception: Step 6's single bootstrap script.
+- **No command reference.** Syntax lives in `unity-cli` / `unity-package-management`.
+- **No re-deciding create's defaults** — narrate them from the result. The Defaults table is this
+  file's only opinions; the guided interview survives untouched.
+
+## Checklist
+
+Read [the checklist](references/checklist.md) before reporting, and do not report an item you have not checked.
+
+## Common mistakes
+
+Read [common mistakes](references/common-mistakes.md) when something looks done but is wrong — blocked creates, double-wired auth, pink shaders, committed `Library/`.
+

package/skills/new-unity-project/references/checklist.md

@@ -0,0 +1,18 @@
+# Checklist
+
+- [ ] Delegated skills checked before Step 1 (incl. `craft-game-floors`): a missing one offered, or named
+      in the report
+- [ ] Mode decided once; in paved, the manifest printed before the create launches
+- [ ] Brief captured; platforms + monetization recorded
+- [ ] Background create with `--install-editor` + modules, URP template (`--template 3d`/`2d`)
+      unless Built-in was requested; `--bare` only on the user's ask; result reconciled
+- [ ] Source control attached (Step 4), or local git + Unity `.gitignore`
+- [ ] Packages via `package add` (or the C# script pre-open); `manifest.json` verified; no
+      render-pipeline package atop the template
+- [ ] Identity confirmed from the result or wired in Step 6 (stated cost on a failed link)
+- [ ] `craft-game-floors` loaded (or its absence named); `unity-pipeline` read once the Editor was ready
+- [ ] Baseline applied: Volume + camera post on, quality tier, UI stack (no `OnGUI`), URP shaders,
+      capture checked (skipped on `--bare`; on 6000.5.0–6000.5.2, Editor updated first)
+- [ ] `.meta` files exist; first commit made; `Library/` excluded
+- [ ] Forward baton offered and written only on a yes (none on `--bare`); handoff done if applicable
+

package/skills/new-unity-project/references/common-mistakes.md

@@ -0,0 +1,15 @@
+# Common mistakes
+
+- **Blocking on the create** instead of backgrounding it: with `--install-editor` it waits for the
+  whole Editor install.
+- **Acting before the manifest prints** (paved), or burying an assumption outside it — if it isn't
+  in the manifest, it isn't assumed.
+- **Wiring auth twice** — if create's result shows identity, Step 6's wiring is a skip.
+- **Hand-editing `manifest.json`** instead of the package commands or the skill's script.
+- **Doing a required sub-skill's job from memory** when it isn't loaded, without telling the user
+  or offering the install.
+- **Committing `Library/`/`Temp/`/`obj/`/`Build/`**, or scripts without their `.meta` files.
+- **Missing Editor modules** — a mobile target needs `android`/`ios`; WebGL needs `webgl`.
+- **Picking `com.unity.template.2d` / `.3d` by name** — Built-in templates; use `--template 3d`/`2d`.
+- **Skipping the visual baseline** — flat template defaults, `OnGUI` HUDs, and
+  `Shader.Find("Standard")` under URP.

package/skills/new-unity-project/references/skill-setup.md

@@ -0,0 +1,66 @@
+# Skill setup — getting the delegated skills loaded
+
+> Reference for the `new-unity-project` skill: the install routes for its delegated skills, and the
+> `unity-pipeline` guide's location inside the Pipeline package. The body's "Before Step 1" check says
+> *when* to use this; this file says *how*.
+
+## Install routes, by client
+
+If a delegated skill is missing, tell the user which one and what it does for them. Offer to install
+the Unity skills before you start, and don't install without a yes, because it changes their agent
+setup:
+
+- **Claude Code, with none of the Unity skills installed:** `unity setup claude --format json`
+  installs the Unity plugin, which carries all of them. It would duplicate any you already have. An
+  older CLI doesn't know `unity setup`, so use the next route then. A fresh install loads in the next
+  session, or after `/reload-plugins`. Until then, read the skills from the `skillsPath` it reports.
+- **Any other case, including a partial set:** run `unity skill install <client>`, where
+  `unity skill install --list` names the clients and where each one installs. It installs the Unity
+  skills from the Unity-Technologies/skills repository at the commit this CLI pins, and checks each
+  one against that pin before it writes anything. To add only the missing skills, name each with
+  `--skill`, which repeats and takes a comma list (`--skill ui,localization`). The source is fixed in
+  the CLI, so don't look for a flag to point it elsewhere. Offline, it installs only the two skills
+  built into the CLI (`unity-cli` and `new-unity-project`), names the ones it couldn't install, and
+  exits 0: run it again once the machine is online.
+- **Codex, Grok Build or GitHub Copilot CLI whose plugin can't be installed:** `unity setup <agent>`
+  offers the same repo skills instead when the agent's CLI is missing or its plugin install fails.
+  With the user's yes, `unity setup <agent> --yes --format json` installs them without a prompt and
+  reports `installedVia: "skills"`, the `skillsPath` and the `skillsToLoad` it installed. The same
+  works for `unity setup claude`.
+- **An older CLI** installs only `unity-cli` and `new-unity-project`. There, tell the user to copy
+  each missing skill's folder from github.com/Unity-Technologies/skills (under `skills`) into their
+  client's skills folder.
+
+A newly installed skill may not load until the client restarts. If it still isn't listed, ask where
+the installer put it and read the skill file from there.
+
+## The `unity-pipeline` guide (read it once the Editor is ready)
+
+It is the Pipeline package's own guide, and no client loads it from the package folder. If it is
+missing from your skills, read its skill file directly. It sits under
+`.claude/skills/unity-pipeline/` in the package: `Packages/com.unity.pipeline/` if the project embeds
+the package, otherwise the `Library/PackageCache/com.unity.pipeline@*` folder. List
+`Library/PackageCache` for the exact name, since the suffix is often a hash, not the version.
+
+To have your client load it in later sessions, `unity skill install <client> --local` can mirror it,
+but only for a client with a project scope (`unity skill install --list` shows which, and Claude
+Desktop has none). It also writes a project copy of `unity-cli` beside it. The `unity-cli` skill
+suggests running it once, but here, wait until the user asks, and run it from the project folder
+after the open. In Claude Code with the Unity plugin installed it stops short, because the plugin
+already carries `unity-cli`. There, with the user's yes, copy the `unity-pipeline` folder into the
+project's `.claude/skills/` instead. Where no mirror is possible, read the package copy again in each
+session.
+
+## Pipeline failure codes and the stuck-Editor recovery
+
+| Symptom | Cause | Resolution |
+|---|---|---|
+| `PIPELINE_MANIFEST_WRITE_FAILED` on `unity pipeline install` | the project is open in an Editor | ask the user to close the Editor, re-run the install |
+| `STATUS_PIPELINE_LOAD_PENDING` right after an install against an open project | the open Editor loads the package when its window regains focus | ask the user to switch to the Editor window |
+| `STATUS_PIPELINE_LOAD_PENDING` that never clears after an open | the Pipeline server can run while its port file never lands (package/editor pairing issues) — focus is not the cause | read `Logs/Editor.log` for `Pipeline:` lines to confirm, then recover below |
+| Pipeline never connects on Unity 6000.5.0 to 6000.5.2 (create reported `PIPELINE_EDITOR_UNSUPPORTED`) | the package can't start its server on those Editors | don't recover below, reopening won't help: ask the user to update to 6000.5.3f1 or later, run `unity pipeline install` with the project closed (create left the package out), then open it with `unity open "<project-path>" --editor-version <updated-version>` (a plain `unity open` uses the saved 6000.5.x Editor); on 6000.7 or later `unity open` refuses the move, so run `unity projects upgrade "<project-path>" --to <updated-version> --yes`, adding `--no-cloud` when the user declined the cloud link at create |
+
+**Stuck-Editor recovery** (check the project's Editor version first; never on 6000.5.0 to
+6000.5.2, see the table): ask the user first — unsaved work is lost — then
+`unity close <project> --force`, which terminates by PID and works without Pipeline connectivity,
+and reopen the project.

package/skills/new-unity-project/references/step-1-concept.md

@@ -0,0 +1,13 @@
+# Step 1 — Concept
+
+**Paved:** the prompt is the spec — parse genre, dimension (2D/3D), look, scope, and name into a
+2–4 line brief; fill gaps from the Defaults table; no read-back.
+
+**Guided:** ask with your client's multiple-choice tool (`AskUserQuestion` in Claude Code,
+`ask_user` in Copilot CLI, `askQuestions` in VS Code); without one, plain text.
+Cover **genre / core loop** · **dimension & look** (2D or 3D; pixel, low-poly, stylized,
+realistic) · **gameplay** (the one-sentence "what the player does moment to moment") · **scope**
+(prototype vs. multi-scene; single- or multiplayer). Settle a **project name**, write the brief,
+read it back. The brief drives the template (Step 2), packages (Step 5) and the baseline (Step 7):
+note the palette / mood words and pixel-art looks.
+

package/skills/new-unity-project/references/step-2-platforms-and-create.md

@@ -0,0 +1,31 @@
+# Step 2 — Platforms & monetization, then start installing
+
+Two decisions (paved: filled from the Defaults table, then **print the manifest**):
+
+- **Target platforms**: Desktop, Mobile (iOS/Android), WebGL, Console — they map to Editor
+  **modules** (`--module`) and argue for leaner packages on mobile/WebGL.
+- **Monetization**: none / premium / IAP / ads / mix — this only decides the Step 9 handoff.
+
+Default to an explicit `--editor-version latest` unless the user names a version — without the
+flag, create prefers a stored default or an older installed Editor.
+
+Confirm prerequisites, then **start the create as a background task** (`unity-cli` has module
+names and auth / license setup):
+
+```bash
+unity --version   # sign-in and license: settled before your first question (see above)
+
+# Start in the BACKGROUND. Module names per platform are in the unity-cli skill.
+# --bare only on the user's ask (see Mode).
+unity projects create "<Name>" --path <dir> --editor-version latest \
+  --template <3d|2d> --install-editor --module <platform-modules> --accept-eula --format json
+```
+
+The command waits for the install, then creates the project, so its one result covers both. If you
+have nothing left to ask, it's fine to just wait.
+
+**Template:** `--template 3d` / `2d` resolve to the version's URP templates
+(`com.unity.template.urp-blank`, `com.unity.template.universal-2d`), the default for every game.
+Built-in templates (`com.unity.template.3d`/`.2d` as full ids) are deprecated from 6.5, removed in
+6.7 — pass one only when the user explicitly asks for Built-in.
+

package/skills/new-unity-project/references/step-3-join-and-reconcile.md

@@ -0,0 +1,16 @@
+# Step 3 — Join: project ready, result reconciled
+
+Wait for the background create and read its JSON result: `data.path` is the project,
+`data.version` the Editor, `data.editorInstalled` whether this run installed it.
+
+**Paved: reconcile the result against the manifest**, narrating divergence — the cloud-link
+soft-fail included (`cloudLinked: false`, warnings, project intact; Step 6 keys off it). A 403 on
+the link is often the saved default org refusing new projects — retry
+`unity projects link cloud <path> --cloud-org <an org the user owns>` before concluding
+no-identity. A result carrying a `steps` field reconciles step-by-step from it.
+
+`--module` only applies when the run installs the Editor: on `data.editorInstalled: false`, add
+the platform modules with `unity install-modules -e <version> -m <platform-modules> --accept-eula`
+(skips what's already there). If create failed, surface the error (`unity-cli` troubleshooting)
+and stop — a failed install creates no project, and nothing downstream works without an Editor.
+

package/skills/new-unity-project/references/step-4-source-control.md

@@ -0,0 +1,9 @@
+# Step 4 — Source control
+
+**Paved:** local git + Unity `.gitignore`. **Guided:** ask — Git (GitHub / GitLab; `--git-lfs` for
+asset-heavy games), **Unity Version Control** (`--vcs uvcs` — large binaries natively, no LFS), or
+purely local. Attach with `unity projects link vcs "<project-path>" --vcs …
+--git-token-from-stdin --no-initial-commit` (tokens on stdin) — **`--no-initial-commit`** keeps
+the CLI from committing the bare project before packages and `.meta` files exist; the real first
+commit is Step 8. Exact flags: the `unity-cli` workflow.
+

package/skills/new-unity-project/references/step-5-packages.md

@@ -0,0 +1,18 @@
+# Step 5 — Packages
+
+Map the brief to a package list and install via **`unity-package-management`** (**never**
+hand-edit `manifest.json`): `package add` once the Editor is open with `com.unity.pipeline`
+(Step 7); its C# installer script when packages must land pre-open (the `-quit` gotcha applies).
+That skill has the genre/platform/monetization → package mapping. A `--bare` run installs only the
+packages the user named, through the C# installer script (bare has no `com.unity.pipeline`, so
+`package add` can't run; never `unity pipeline install` to get it, which undoes the bare ask), and
+stops there. Otherwise paved
+adds the floors' needs: Cinemachine for any gameplay camera (2D rigs included);
+`com.unity.services.authentication` when Step 6 wires identity; and the live floor's services set
+on cloud-linked projects — in this pass, not at shell time. Cloud save and remote config come from
+create: when its `steps` report `cloudSave` and `remoteConfig` as `done` or `present`, skip them and
+add only what is left (leaderboards). The template already provides the
+render pipeline — never add `com.unity.render-pipelines.universal` on a Built-in template
+(materials go pink) or vice versa. Read the list back before installing (paved: print it now);
+verify `manifest.json` after.
+

package/skills/new-unity-project/references/step-6-identity-and-floors.md

@@ -0,0 +1,20 @@
+# Step 6 — Player identity, then the craft floors
+
+**Identity — the create result is the switch** (a `--bare` run skips this whole step: bare
+projects still cloud-link unless `--no-cloud`, and the unwired cost was stated at Mode time):
+identity addressed in the result → confirm it in the reconciliation and **skip**, never wire auth
+twice. No identity and the project cloud-linked →
+wire it: services init plus anonymous sign-in kicked off at bootstrap in **one small bootstrap
+script**, never blocked on (mechanics: **`build-live-game`**, auth section — checked in Before
+Step 1; missing and declined → skip the wiring, gap named); each service dependency is a named
+plan line, declining removes only that line. Cloud link failed or skipped →
+skip with the cost stated (saves and ranks stay local) — never wire services init against a
+project with no cloud id. Invisible to players, upgradeable later — the root the live floor
+builds on.
+
+**A `--bare` run skips the floors too** (the Mode section's stated cost). Otherwise **load the
+`craft-game-floors` skill** (checked in Before Step 1) and follow its floors through the
+build — art bible first, then camera, lighting, feedback, audio, shell, live floor, its done gate.
+Its values supersede the inline fallbacks below whenever present, version skew included. Missing
+and declined → fallbacks, gap named in the report.
+

package/skills/new-unity-project/references/step-7-visual-baseline.md

@@ -0,0 +1,75 @@
+# Step 7 — Visual baseline
+
+A fresh template renders correctly but looks like a default; left there, agents reach for `OnGUI`
+and guess shader names. Apply this floor **before** any gameplay work. A `--bare` run skips this
+whole step (no Pipeline install, no baseline): go to Step 8, which opens the project.
+
+**On Unity 6000.5.0 to 6000.5.2, stop here.** The Pipeline package can't start its server on those
+Editors (create reports `PIPELINE_EDITOR_UNSUPPORTED`), so nothing below can connect, and reopening
+won't help. Create also left the package out on those Editors. Ask the user to update to
+6000.5.3f1 or later, then continue below with the project still closed: the Pipeline install comes
+first, then the open names the updated Editor, `unity open "<project-path>" --editor-version
+<updated-version>` — a plain `unity open` reopens with the project's saved 6000.5.x Editor. If the
+update is 6000.7 or later, `unity open` refuses that move (`PROJECT_UPGRADE_REQUIRED`): run
+`unity projects upgrade "<project-path>" --to <updated-version> --yes` instead. It asks
+nothing: add `--no-cloud` when the user declined the cloud link at create, since an unlinked
+project otherwise exits `CLOUD_CHOICE_REQUIRED`, and no cloud flag when create linked it.
+
+**First, `unity pipeline install --project-path "<project-path>"`, before opening the
+Editor.** Running C# in the Editor and `unity command capture screenshot` below both need the
+project's `com.unity.pipeline` package. Create adds it by default on newer CLIs (this install then
+changes nothing); older CLIs leave the project without it, and Step 5's `-batchmode` installer
+never touches it. Install-before-open is the supported order; without the package, everything below fails to
+connect (it mimics `unity-cli`'s Safe Mode failure). The failure codes
+(`PIPELINE_MANIFEST_WRITE_FAILED`, a stuck `STATUS_PIPELINE_LOAD_PENDING`) and the stuck-Editor
+recovery are tabled in [references/skill-setup.md](../references/skill-setup.md).
+
+**Then** `unity open "<project-path>"`, wait until `unity status` reports the Editor ready, and
+apply each item below by running C# in it — **`unity-cli` owns those commands**; don't re-derive
+them here.
+
+Once the Editor is ready, read the `unity-pipeline` guide if your skills don't list it —
+locations and mirroring routes: [references/skill-setup.md](../references/skill-setup.md).
+
+**Items 1, 2, 5 and 6 assume a URP template**, the Step 2 default. If the user explicitly chose
+Built-in, don't run them as written — `UniversalAdditionalCameraData`, `Light2D`, the
+`urp-postprocessing` volume framework and `Universal Render Pipeline/*` shaders don't exist there;
+post-processing means the legacy Post Processing Stack, the shader names are `Standard` /
+`Unlit/Color`, and items 3–4 apply as written. Don't reach for `migrate-birp-to-urp` — the user
+asked for Built-in.
+
+1. **Post-processing.** Global Volume — `craft-game-floors`'s scene-lighting values when loaded (they
+   supersede these); fallback: Tonemapping (ACES), Bloom intensity 0.5–1 @ threshold 0.9, Vignette
+   ≈ 0.25; set `renderPostProcessing = true` on the main camera's `UniversalAdditionalCameraData`.
+   **REQUIRED SUB-SKILL:** `urp-postprocessing` — its templates create the volume and check HDR and
+   the layer mask; if it isn't loaded, do both yourself from these values.
+2. **Camera and light.** 2D → orthographic, solid background from the brief's palette, a `Light2D`
+   of type Global if the template scene has none (Sprite-Lit shaders render black without one).
+   3D → perspective, main-light shadows on; `craft-game-floors`'s lighting pass replaces the template's
+   default light story when loaded, else keep the template's directional light and skybox.
+3. **Quality tier.** Read `QualitySettings.names` first — tier names differ per template — then
+   `QualitySettings.SetQualityLevel` to the one matching the primary target: the highest tier for
+   desktop, the lowest for mobile/WebGL. Leave color space Linear and the Input System as the
+   template set them.
+4. **UI stack.** HUD and menus use a uGUI Canvas + TextMeshPro or UI Toolkit — **never `OnGUI`**.
+   **REQUIRED SUB-SKILL:** `ui` picks between them for the project. If it isn't loaded, choose
+   between them from the brief and say which you chose, and why, in your final report.
+5. **Materials and shaders.** Under URP use `Universal Render Pipeline/Lit`, `…/Unlit`,
+   `…/2D/Sprite-Lit-Default` or `…/2D/Sprite-Unlit-Default`. `Standard` and `Unlit/Color` render
+   pink or washed out under URP. Prefer `GraphicsSettings.currentRenderPipeline.defaultMaterial`
+   / `.default2DMaterial` over `Shader.Find`, and treat a `null` from `Shader.Find` as an error.
+   `currentRenderPipeline`, not `defaultRenderPipeline`: a quality tier can carry its own pipeline
+   asset, and item 3 above just set the tier.
+6. **Pixel art only.** Point filter mode on sprites and a Pixel Perfect Camera — see
+   `2d-pixel-perfect`. If missing, do both yourself and note the skill-setup install route in the
+   report.
+
+Save the scene, then confirm both of these — **not with `unity logs`**, which reads the CLI's own
+log and reports clean whatever the scene looks like:
+
+- No render-pipeline or shader errors Editor-side. Read the Editor console through `unity-cli`,
+  or read `Editor.log` directly — that skill's "Recovering from Safe Mode" section has the
+  per-platform paths.
+- `unity command capture screenshot --output-path baseline.png` looks lit and tonemapped rather than flat
+  gray.
+

package/skills/new-unity-project/references/step-8-first-commit.md

@@ -0,0 +1,21 @@
+# Step 8 — Save & first commit
+
+The project is already open from Step 7, so `.meta` files exist (`unity open "<project-path>"`
+only if not — headless/CI uses the "Import & save headlessly" method in
+`unity-package-management`). Commit **with whichever VCS you set up in Step 4**:
+
+- **Git (GitHub / GitLab / local):**
+  ```bash
+  cd "<project-path>"
+  git add -A
+  git status                    # Library/ Temp/ obj/ Build/ must NOT be staged
+  git commit -m "Initial Unity project: <Name>"
+  ```
+  Every `.cs`/asset is committed together with its `.meta`.
+- **Unity Version Control (UVCS):** check in through the workspace from Step 4 — no `git` step;
+  generated folders stay excluded by the ignore rules.
+
+If Step 7 mirrored skills into the project, ask whether to include them. If Step 4 linked
+**without** `--no-initial-commit`, the CLI already committed the bare project — add a follow-up
+commit rather than double-committing.
+

package/skills/new-unity-project/references/step-9-handoff.md

@@ -0,0 +1,23 @@
+# Step 9 — Hand off
+
+Based on Step 2 monetization, invoke the matching skill for the actual integration:
+- IAP → **implement-in-app-purchases**
+- Ads → **levelplay-unity-integration**
+- Accounts / cloud save / economy / remote config / leaderboards → **build-live-game**
+
+If the matching skill isn't loaded, point the next steps at the skill-setup install route rather
+than integrating from memory.
+
+**Offer the forward baton** (declared on the manifest; not on a `--bare` run): one idempotent line
+for the project's `CLAUDE.md` or `AGENTS.md` — "When building gameplay, feel, audio, shell, or live
+features, load the `craft-game-floors` skill; if it isn't installed, ask the user whether to run
+`unity skill install <client>` (ask: never run it without a yes)." That file steers every later
+agent session in the project, so **ask before writing it**, even in paved mode, and show the line.
+On a yes, append it and commit the note — appended after Step 8, it otherwise never reaches clones.
+On a no, put the line in the report for the user to add. Later sessions reach the floors through
+it without this skill re-triggering.
+
+Report the project path, Editor version, pipeline and template, packages, the manifest with its
+reconciliation, identity state, the baseline applied, any missing skill, `craft-game-floors`'s done gate
+as the build's finish line, and next steps.
+