nccgs 1.0.0

package/.claude/skills/unity-cli/references/diagnostics-maintenance.md

@@ -0,0 +1,326 @@
+# Diagnostics & maintenance — unity-cli command reference
+
+Part of the **`unity-cli`** skill. See that skill's `SKILL.md` for CLI install, global flags,
+environment variables, exit codes, and common workflows. All global flags (`--format json`,
+`--non-interactive`, `--yes`, `--proxy`, …) apply to every command below.
+
+---
+
+### Logs — application logs
+
+```bash
+# Show last 20 log lines (default)
+unity logs
+
+# Show last 50 lines
+unity logs --tail 50
+
+# Follow in real-time (like tail -f)
+unity logs --follow
+
+# Filter by level
+unity logs --level error
+unity logs --level warn
+
+# Available levels: trace, debug, info, warn, error, fatal
+```
+
+The CLI writes its own `cli-log.json` (separate from the Hub's `info-log.json`) and records its version on every start. `unity logs`, `unity bug`, and `unity doctor` read the CLI's own log.
+
+> **Not the Unity Editor log.** `unity logs` shows the *CLI's* activity, **not** the Editor's
+> `Editor.log`. To read Editor-side output — for example the compile errors that force an Editor into
+> Safe Mode and block the Pipeline connection — read `Editor.log` directly (see
+> [integration-advanced.md → Recovering from Safe Mode](integration-advanced.md#recovering-from-safe-mode-connection-fails-because-of-compile-errors) for its per-platform path and the full recovery loop).
+
+---
+
+### Doctor — system diagnostics
+
+```bash
+# Full system report
+unity doctor --format json
+
+# Includes: platform info, auth status, installed editors, recent log lines, resolved proxy
+unity doctor --tail 50
+```
+
+`unity doctor` reports real session state (matching `unity auth status`) and surfaces the resolved proxy URL, its source, and auth source. It also runs environment health checks and reports pass/warn per check (in every output format): whether the `unity` binary's directory is actually on `PATH` (the top post-install pitfall on Windows, where a new terminal is needed), whether multiple `unity` binaries shadow each other on `PATH`, whether Windows long-path support is enabled, and whether a git credential helper is configured (`git-credential-helper`: advisory for the git-token flows in `projects clone`/`create`/`link vcs`; the row is omitted on machines without git).
+
+---
+
+### Doctor --ci — preflight before a long pipeline step
+
+```bash
+# First step of a CI job: fail in seconds instead of after a long build
+unity doctor --ci
+
+# Per-check results a workflow can branch on
+unity doctor --ci --format json
+
+# Failed checks become inline annotations on the pull request
+unity doctor --ci --format github
+```
+
+`--ci` replaces the diagnostic report with a **preflight**: it verifies the environment can actually finish a build or test run and exits non-zero when it cannot, so a pipeline fails fast rather than tens of minutes into a build. It checks an activatable license, the project's required editor, free disk space, and reachability of the Unity services endpoint, and folds the `PATH` / long-path / git-credential-helper checks in as advisory rows that never fail a job.
+
+Exit codes distinguish the two kinds of bad news, so a workflow can retry only what is worth retrying:
+
+| Exit | Meaning |
+|---|---|
+| `0` | Every blocking check passed. Warnings do not fail the preflight. |
+| `6` | A definitive failure — no license, the required editor is not installed, disk below the floor. Retrying will not help. |
+| `7` | The preflight could not reach a verdict because a required service was unreachable. Worth a retry. |
+
+A `6` outranks a `7` when both occur, so a real blocker is never reported as retryable.
+
+Every check carries a machine-readable `code` (`LICENSE_NONE`, `EDITOR_NOT_INSTALLED`, `DISK_SPACE_LOW`, `NETWORK_UNREACHABLE`, …) plus a remediation `hint`. In `--format json` the per-check results stay in `data` even on failure, with one coded entry per failure in `errors`. Output is redacted and carries no tokens and no absolute user paths, so it is safe to paste into a public CI log.
+
+`--ci` is always explicit — it is never inferred from `CI=true`, because a report that silently changed shape and exit code on a runner would be a trap. Note that the CLI already defaults to `--format tsv` whenever stdout is redirected, which in CI it usually is; that output leads with a `verdict` row.
+
+---
+
+### Diagnose proxy — proxy diagnostic report
+
+```bash
+# Print a redacted, paste-safe proxy diagnostic report for support
+unity diagnose proxy
+
+# Machine-readable
+unity diagnose proxy --json
+```
+
+Reports the resolved proxy and where it came from, PAC configuration, CA bundle, and credential-store and Kerberos checks — redacted so it's safe to paste into a support ticket. A copy is also written to the logs directory. For per-request proxy logging over the course of a repro, use the global `--log-proxy` flag (or `UNITY_LOG_PROXY=1`), which writes one redacted entry per outbound request to `proxy-request.json`.
+
+---
+
+### Environment
+
+```bash
+# Show environment paths
+unity env --format json
+
+# Returns: user data path, editor install path, download cache path, config path, CLI version, resolved proxy
+```
+
+---
+
+### Cache
+
+```bash
+# Show cache location and size
+unity cache info --format json
+
+# Clear download cache
+unity cache clean --yes
+```
+
+---
+
+### Cache key — deterministic key for CI cache steps
+
+`unity cache key` prints one hash derived from the inputs that actually invalidate a project's build cache: the editor version, the resolved package set, and (optionally) the build target. Use it as the `key:` of a CI cache step instead of hand-rolling the hashing.
+
+```bash
+# Print the key for the project in the current directory
+unity cache key
+
+# Scope it to a build target — a Library/ folder is platform-specific
+unity cache key --target Android
+
+# Any project path
+unity cache key ./MyProject
+```
+
+Whenever stdout is not an interactive terminal — a pipe, a redirect, or any CI runner — the key is the only thing written to it, so it drops straight into a shell substitution or a workflow expression. (On an interactive colour terminal the CLI's usual one-line banner still prints above it, as it does for every command; `--quiet` suppresses that.)
+
+Pass the project path if the workflow's working directory isn't the project:
+
+```yaml
+- id: cachekey
+  run: echo "key=$(unity cache key MyProject --target Android)" >> "$GITHUB_OUTPUT"
+- uses: actions/cache@v4
+  with:
+    path: MyProject/Library
+    key: Library-${{ steps.cachekey.outputs.key }}
+```
+
+What moves the key, and what doesn't:
+
+- **Changes** when the editor version (`ProjectSettings/ProjectVersion.txt`), the package set (`Packages/packages-lock.json`, falling back to `Packages/manifest.json`), or `--target` changes.
+- **Does not change** for unrelated edits — scenes, scripts, assets, or project settings other than the version file.
+- **Is identical across machines and operating systems** for the same inputs. Line endings and a UTF-8 BOM are normalized before hashing, so a Windows checkout with `core.autocrlf` and a Linux one agree. No paths, usernames, or timestamps enter the hash.
+
+`--format json` returns the key plus each component's raw value and hash, so one invocation can build a layered key with fallback levels:
+
+```bash
+unity cache key --target Android --format json
+```
+
+`--component <editor|packages|target>` prints just one component's hash for the fallback levels themselves. Under `--format json` it also sets `data.key` to that component, so `jq -r .data.key` means the same thing either way:
+
+```bash
+# Restore any cache built for this editor, whatever the packages were
+unity cache key --component editor
+```
+
+Runs without an editor and without network access. Exit 2 on an unknown `--target` or `--component` (a silently-accepted typo would produce a key nothing else matches); exit 6 when the directory isn't a Unity project. A project with neither package file still emits a key, with a warning that it doesn't cover the package set.
+
+---
+
+### Analytics — usage/telemetry consent
+
+The CLI defaults to **opt-out**. On the first interactive run a prompt is shown once before any data is collected; it now requires an explicit `y` or `n` — pressing Enter alone re-asks instead of silently recording the opt-out default, so an accidental keystroke can't lock in an answer. Ctrl-C skips the prompt and keeps the opt-out default. Non-interactive, CI, piped, and `--quiet` contexts silently keep the opt-out default.
+
+Running `unity analytics opt-in` or `opt-out` permanently answers the first-run prompt, so a choice recorded from a script (where the prompt never appears) isn't asked again on the next interactive run. To suppress the prompt *without* recording a choice — for a wrapper script on an interactive terminal that must never absorb it — set `UNITY_NO_CONSENT_PROMPT` (analytics stay off until you explicitly opt in).
+
+```bash
+# Show current consent status
+unity analytics status
+unity analytics status --format json
+
+# Opt in to anonymous usage data collection
+unity analytics opt-in
+
+# Opt out (the default)
+unity analytics opt-out
+```
+
+Consent is stored in the shared Hub privacy preferences, so opting out in the CLI also opts out in Hub, and vice versa. When opted **in**, the CLI records which commands run (registered command names only — never your arguments, paths, or project names), editor uninstalls, project open/create (editor version and template id only), CLI self-upgrade/uninstall outcomes, `unity shell` and `unity mcp` session usage, and `unity doctor` / `unity bug` results. When opted out (the default), no events are sent.
+
+Separately from analytics, the CLI reports **anonymous crashes and errors** via Sentry to help fix bugs (no IP address or hostname; home-directory paths and token-like values scrubbed before send), aligned with the Unity Hub. Opting in to analytics additionally attaches an anonymized machine id so crash-free-user rates can be computed; opted-out users stay fully anonymous. Set `UNITY_NO_CRASH_REPORT` to disable crash reporting entirely.
+
+---
+
+### Changelog
+
+Show the embedded release notes for the currently installed CLI version:
+
+```bash
+unity changelog
+unity changelog --format json
+```
+
+---
+
+### Language
+
+```bash
+# Show current language and available options
+unity language
+
+# Set language by code
+unity language --set en
+unity language --set ja
+unity language --set zh-hans
+
+# Alias
+unity lang --set ko
+```
+
+On a TTY with no flags, shows an interactive selection prompt. `--set` accepts common spellings of a language code — BCP-47 (`ja-JP`), locale (`ja_JP`), a bare language (`ja`), or a bare region (`jp`) — and resolves them case-insensitively when the match is unambiguous (`zh` still asks you to pick `zh_cn` or `zh_tw`). Display names and ordering come from the shared Hub language catalog. The regional variants Spanish (Latin America), French (Canada), and Portuguese (Portugal) are no longer offered; Spanish, French, and Portuguese (Brazil) remain.
+
+---
+
+### Completion — shell tab completion
+
+Generate and install shell completion scripts:
+
+```bash
+# Supported shells: bash, zsh, fish, powershell
+unity completion bash
+unity completion zsh
+unity completion fish
+unity completion powershell
+```
+
+---
+
+### Bug — report a bug
+
+Interactive bug reporter that collects system info and recent logs, then submits to Unity:
+
+```bash
+# Interactive — prompts for each field
+unity bug
+
+# Non-interactive — supply the report through flags (works from scripts, CI, piped shells)
+unity bug \
+  --title "Editor crashes on project open" \
+  --description "Opening MyGame hard-crashes the editor." \
+  --steps "Open the CLI" --steps "Run unity open MyGame" --steps "Editor window closes" \
+  --reproducibility always \
+  --email you@example.com \
+  --attachments ./crash.log ./notes.txt \
+  --share-project .
+```
+
+Prompts for title, description, email, and reproducibility level. As of `0.1.0-beta.8` it collects the same diagnostic system information as the Unity Hub bug reporter (including GPU details).
+
+The report can also be supplied entirely through flags — `--title`, `--description`, `--steps` (repeatable, one line per value), `--reproducibility <first-time|sometimes|always>`, and `--email` (defaults to your Unity account email when signed in; otherwise required). On a terminal, any flags you pass skip their prompts and the remaining fields still ask; a non-interactive run submits without prompting. A non-interactive run with missing or invalid fields fails fast with a usage error (exit 2) listing the exact flags to add.
+
+Use `--attachments <paths...>` (repeatable) to attach extra files — for example a crash log or a zipped copy of a subset of assets. Each path must be an existing, readable file; a folder is rejected (zip it yourself first), and a missing or unreadable path fails fast with a usage error (exit 2) naming the offending path.
+
+Use `--share-project <path>` (use `.` for the current directory) to attach a copy of the Unity project the bug is about — the same stripped-project packaging the Editor's bug reporter uses. It sends the source folders plus a slimmed `Library`, excluding the regenerable caches and build output (`Library` caches, `Temp`, `Build`, `Logs`, VCS/IDE metadata, `MemoryCaptures`, `CrashReports`), so you don't have to zip the project yourself. A path that isn't a Unity project fails fast with exit 2. The archive is streamed from disk during upload, so there's no size limit — even a multi-gigabyte project copy uploads without being buffered in memory.
+
+Interactively, when you don't pass `--attachments` or `--share-project`, the reporter asks whether to attach files and whether to include a project copy. Everything — attachments and the project copy — is bundled into the same archive as the auto-collected logs.
+
+---
+
+### Upgrade — update the CLI itself
+
+```bash
+# Check for available updates
+unity upgrade --check --format json
+
+# Show changelog for the new version
+unity upgrade --changelog
+
+# Upgrade (interactive confirmation)
+unity upgrade
+
+# Upgrade without prompts
+unity upgrade --yes
+
+# Install a specific version
+unity upgrade --target 0.2.0
+
+# Select update channel (stable or beta)
+unity upgrade --channel beta
+
+# Dry-run: show what would change
+unity upgrade --dry-run
+
+# Rollback to previous version
+unity upgrade --rollback
+```
+
+`unity upgrade` detects how the CLI was installed and upgrades accordingly:
+
+- **`curl | sh` install** — keeps upgrading itself in place.
+- **Linux AppImage** — updates in place: downloads the new `.AppImage` artifact, verifies its checksum against the release manifest, and atomically replaces the AppImage you launched (`--rollback` restores the previous one). The embedded zsync update info is preserved, so external updaters (AppImageUpdate, Gear Lever) keep working.
+- **Package-manager install** — points you at the owning manager instead of replacing the binary. The `.deb` and `.rpm` packages are published to Unity's apt and rpm repositories on every beta and GA release (rpm packages are GPG-signed), so a package-managed install stays current through the system package manager: `sudo apt update && sudo apt upgrade unity-cli` on Debian/Ubuntu, `sudo dnf upgrade unity-cli` on Fedora/RHEL.
+
+`--check`, `--changelog`, and `--dry-run` work everywhere. The background "update available" notice is package-manager-aware: when the release manifest says your install's package manager already carries the new version, the notice suggests that manager's exact upgrade command instead of `unity upgrade`; installs whose manager doesn't carry the release yet stay quiet.
+
+---
+
+### Self-uninstall — remove the CLI
+
+```bash
+# Uninstall the CLI (interactive confirmation)
+unity self-uninstall
+
+# Uninstall without prompts
+unity self-uninstall --yes
+
+# Also remove config and data files
+unity self-uninstall --purge --yes
+
+# Dry-run: show what would be removed
+unity self-uninstall --dry-run
+```
+
+> **`unity implode` was removed** in `0.1.0-beta.8` (it was previously a deprecated alias). Use `unity self-uninstall`.
+
+---
+

package/.claude/skills/unity-cli/references/editors-install.md

@@ -0,0 +1,327 @@
+# Editors, install & modules — unity-cli command reference
+
+Part of the **`unity-cli`** skill. See that skill's `SKILL.md` for CLI install, global flags,
+environment variables, exit codes, and common workflows. All global flags (`--format json`,
+`--non-interactive`, `--yes`, `--proxy`, …) apply to every command below.
+
+---
+
+### Editors — list, install, uninstall
+
+```bash
+# List all editors (installed + available releases)
+# Short alias: unity e. The bare `unity editors` is shorthand for the explicit `unity editors list` (matches projects/templates/modules)
+unity editors list --format json
+
+# List only installed editors
+# As of 0.1.0-beta.8 the --installed table includes an "Upgrade to" column flagging editors with a newer patch in their line
+unity editors --installed --format json
+
+# List only available releases
+unity editors --releases --format json
+
+# Filter by architecture
+unity editors --installed --architecture arm64 --format json
+
+# Show detailed module info
+unity editors --verbose
+
+# Watch mode — live-updates as editors are installed or removed
+unity editors --watch
+unity editors --installed --watch
+```
+
+`unity editors` honors `--format tsv` and `--format ndjson` for its default listing. Identifier columns keep their natural width even if the table exceeds the terminal — they are no longer silently truncated.
+
+#### editors running
+
+List the Unity Editor instances currently running and the project each has open, with the editor version and process id per instance:
+
+```bash
+unity editors running
+unity editors running --format json
+```
+
+Detection is cross-platform (process table plus each project's Pipeline lockfile), and the version falls back to a project's `ProjectSettings/ProjectVersion.txt` for editors without the Pipeline package. An empty list is a normal result (exit 0). Honors the global `--format human|json|tsv|ndjson` (and `--json`).
+
+#### editors add
+
+Register one or more existing editor installations by path:
+
+```bash
+unity editors add /path/to/Unity/Editor
+
+# Register multiple at once
+unity editors add /path/one /path/two
+
+# Skip macOS code-signature check (useful for unsigned or side-loaded builds)
+unity editors add /path/to/Unity/Editor --skip-signature-check
+```
+
+#### editors default
+
+```bash
+# Show current default editor
+unity editors default --format json
+
+# Set default by version, alias, or keyword
+unity editors default 6000.0.47f1
+unity editors default latest
+unity editors default lts
+
+# Clear the default
+unity editors default --unset
+```
+
+On a TTY with no arguments, shows an interactive selection prompt.
+
+#### editors path
+
+```bash
+# Print the install directory of an installed editor (local, offline — no release-feed fetch)
+unity editors path 6000.0.47f1
+unity editors path 6000.0.47f1 --architecture arm64 --json
+```
+
+Honors `--architecture` and `--format` / `--json`, and reports ambiguous matches so you can narrow by version or architecture.
+
+#### editors install-path
+
+```bash
+# Show the directory where editors are installed
+unity editors install-path
+
+# Set a new install path
+unity editors install-path --set /path/to/editors
+```
+
+Also available as the top-level `unity install-path` (with an additional `--get` flag). Distinct from `editors path`: `install-path` gets/sets the *root* install directory; `editors path` prints the install directory of *one* editor version.
+
+#### editors info
+
+```bash
+# Show release details for a specific version
+unity editors info 6000.0.47f1 --format json
+```
+
+#### editors upgrade
+
+New in `0.1.0-beta.8`. Upgrade an installed editor to the newest official (f-channel) patch in the same `major.minor` line (e.g. `2022.3.10f1` → `2022.3.62f1`), carrying the installed modules over. The `[editor]` argument accepts an exact version, a `major.minor` line, or the `latest` / `lts` / `default` aliases. Editors install side by side — the old version is kept unless `--replace` (alias `--remove-old`) is passed.
+
+```bash
+# Upgrade a specific editor (or the default / lts / latest) to the newest patch in its line
+unity editors upgrade 2022.3.10f1
+unity editors upgrade lts
+
+# Upgrade every installed editor that has a newer patch
+unity editors upgrade --all --yes --accept-eula
+
+# Report current → target without installing (--check is an alias for --dry-run)
+unity editors upgrade --all --dry-run --format json
+
+# Remove the old editor after a successful upgrade; skip carrying modules; add extra modules
+unity editors upgrade 2022.3.10f1 --replace --yes
+unity editors upgrade 2022.3.10f1 --no-modules
+unity editors upgrade 2022.3.10f1 --module android --module ios
+```
+
+#### editors prune
+
+Finds installed editors that **no registered project uses** and, optionally, uninstalls them. Report-only by default — it never deletes anything unless you pass `--remove`.
+
+```bash
+# Report only: which editors are unused, and how much they'd reclaim
+unity editors prune
+
+# Uninstall the unused editors (prompts to confirm)
+unity editors prune --remove
+
+# Non-interactive: --yes is REQUIRED alongside --remove in a script or CI
+unity editors prune --remove --yes
+
+# Machine output
+unity editors prune --format json
+```
+
+The report lists version, architecture, path, size, and status, then the total reclaimable size. With `--remove` in a non-interactive shell and no `-y, --yes`, it refuses rather than deleting unprompted. "Unused" is judged against the **project registry** (`unity projects list`), so an editor used only by a project you never registered counts as unused — register it first, or verify with `unity editors prune` before adding `--remove`.
+
+#### editors verify
+
+Structurally verifies an installed editor: checks that its files and modules are actually present on disk. It's the command to reach for when an editor launches oddly, a module seems half-installed, or a download was interrupted.
+
+```bash
+# Verify an installed editor
+unity editors verify 6000.1.0f1
+
+# Disambiguate when the same version is installed for two architectures
+unity editors verify 6000.1.0f1 --architecture arm64
+
+# Machine output
+unity editors verify 6000.1.0f1 --json
+```
+
+Reports each component as `ok`, `missing`, or `skipped`, and names the exact `unity install-modules` command to repair anything missing. A clean editor exits 0; missing or empty files fail the check. This is a **structural** check — it confirms files exist, not that they are uncorrupted or correctly signed. `--architecture` is inherited from the `editors` parent, so `unity editors --architecture arm64 verify <version>` works too.
+
+#### editors module / editor module
+
+Module management is exposed under **both** `editors module` and the `editor` (singular) command group. Both share the same subcommands:
+
+```bash
+# List modules for an installed editor
+unity editors module list 6000.0.47f1 --format json
+unity editor module list 6000.0.47f1 --architecture arm64 --format json
+
+# Add modules to an installed editor
+unity editors module add 6000.0.47f1 --module android --module ios
+unity editors module add 6000.0.47f1 --all          # Install every available module
+unity editors module add 6000.0.47f1 --module android --child-modules   # Include child modules
+unity editors module add 6000.0.47f1 --module android --accept-eula      # Accept EULAs automatically
+
+# Remove installed modules from an editor by id (-m/--module, repeatable)
+unity editors module remove 6000.0.47f1 --module android --module ios
+unity editor module remove 6000.0.47f1 -m android -a arm64   # disambiguate side-by-side installs
+unity editors module remove 6000.0.47f1 -m android --yes     # skip the confirm prompt (required non-interactively)
+
+# Refresh module list for a manually located editor
+unity editors module refresh 6000.0.47f1
+```
+
+`module remove` prompts to confirm before deleting the module files; `-y` / `--yes` skips the prompt and is required in non-interactive mode. Supports `-a` / `--architecture` to disambiguate side-by-side installs and the global `--format human|json|tsv|ndjson`.
+
+#### editor add (single path, with module-fetch control)
+
+The `editor add` subcommand is similar to `editors add` but targets a single path and supports skipping the module-fetch step:
+
+```bash
+unity editor add /path/to/Unity/Editor
+
+# Skip fetching module metadata (faster, but modules won't be listed until refreshed)
+unity editor add /path/to/Unity/Editor --no-fetch-modules
+```
+
+---
+
+### Install
+
+```bash
+# Install an editor (interactive version selection if omitted)
+unity install 6000.0.47f1
+
+# Install with specific modules
+unity install 6000.0.47f1 --module windows-mono --module android
+
+# Install a specific changeset by hash
+unity install 6000.0.47f1 --changeset abc123def456
+
+# Include child modules
+unity install 6000.0.47f1 --cm
+
+# Exclude child modules
+unity install 6000.0.47f1 --no-cm
+
+# Install and accept EULAs automatically (CI)
+unity install 6000.0.47f1 --yes --accept-eula
+
+# Force reinstall even if already present
+unity install 6000.0.47f1 --force
+
+# Resume an interrupted download (also recovers orphaned partials left by a crash or kill)
+unity install 6000.0.47f1 --resume
+
+# Dry-run: show what would be installed without doing it
+unity install 6000.0.47f1 --dry-run --format json
+
+# List the editor's available modules and exit without installing
+# (a drop-in alias for `unity modules list <version>`)
+unity install 6000.0.47f1 --list-components --format json
+
+# Space-separated module values after a single -m are equivalent to repeating -m
+unity install 6000.0.47f1 -m android ios          # space-separated
+unity install 6000.0.47f1 -m android -m ios       # repeated flag (same effect)
+
+# Windows: keep the install service unelevated. The Editor's NSIS installer is manifested
+# `highestAvailable`, so it runs unelevated for a STANDARD user (the supported unprivileged
+# install — it reports any dependencies an admin must finish) but still asks for elevation on
+# demand under an administrator account. In CI, where a prompt can't be answered, run the
+# agent elevated instead. Also via UNITY_NO_ELEVATE=1.
+unity install 6000.0.47f1 --no-elevate --yes --accept-eula
+```
+
+When installing an editor with several modules, a failed module no longer aborts the whole batch — `unity install` (and `unity install-modules`) continue with the remaining items and exit non-zero if any failed. Each editor and module is listed as installed (✓), failed (✗), or pending (·); the NDJSON `result` frame carries the same breakdown as an `items` array (each entry has `uid`, `name`, `kind`, `status`), so scripts can tell exactly which modules succeeded even on a non-zero exit.
+
+**NDJSON progress frames** for `unity install` and `unity install-modules` include a `phase: 'download' | 'install'` field so scripts can switch to an indeterminate spinner during the install phase (which is genuinely indeterminate — NSIS on Windows only reports success/failure). During the install phase, `pct` is locked at 50 and only jumps to 100 on completion. Module download/install progress is nested under the parent editor via `parentItemUid`, so consumers see one editor group with its modules rather than one group per module.
+
+On an interactive terminal, `unity install` also reports progress to the terminal application itself via the `OSC 9;4` escape sequence — on Windows Terminal the taskbar icon fills with download/install progress and spinners show as indeterminate, so you don't need to keep the window focused. It's emitted only on a TTY (never in piped or machine-consumed output), always cleared on exit, and ignored by terminals that don't support it.
+
+Module installers honor the per-module install command from the release manifest (e.g. Visual Studio on Windows uses `--passive`, not `/S`); the resolved command is surfaced in `unity modules list --json`. `unity install` self-heals a corrupted partial download by discarding the bad partial and re-downloading; a cross-process install lock prevents two concurrent installs of the same version from corrupting the unpack.
+
+### Uninstall
+
+```bash
+# Uninstall an editor version
+unity uninstall 6000.0.47f1 --yes
+
+# Uninstall a specific architecture
+unity uninstall 6000.0.47f1 --architecture arm64 --yes
+```
+
+---
+
+### Modules — add/list per editor
+
+```bash
+# List modules for an installed editor
+unity modules list 6000.0.47f1 --format json
+
+# Filter by architecture
+unity modules list 6000.0.47f1 --architecture arm64 --format json
+```
+
+`unity modules list` honors `--format ndjson` (empty results emit a clean, empty NDJSON stream).
+
+### install-modules
+
+```bash
+# List available modules without installing
+unity install-modules --editor-version 6000.0.47f1 --list
+
+# Install specific modules
+unity install-modules --editor-version 6000.0.47f1 --module android --module ios
+
+# Install all available modules
+unity install-modules --editor-version 6000.0.47f1 --all --yes
+
+# Include child modules (default behaviour)
+unity install-modules --editor-version 6000.0.47f1 --module android --cm
+
+# Exclude child modules
+unity install-modules --editor-version 6000.0.47f1 --module android --no-cm
+
+# Accept EULAs and dry-run
+unity install-modules --editor-version 6000.0.47f1 --all --accept-eula --dry-run
+
+# Reinstall modules that are already installed (a repair)
+unity install-modules --editor-version 6000.0.47f1 --module android --reinstall
+
+# -f/--force implies --reinstall, auto-includes child modules, and skips confirmation prompts
+unity install-modules --editor-version 6000.0.47f1 --module android --force
+
+# Tune the automatic retry for modules whose download/validation fails intermittently
+# (default retries twice with backoff; 0 disables). Also via UNITY_INSTALL_RETRIES.
+unity install-modules --editor-version 6000.0.47f1 --module android --retries 3
+unity install-modules --editor-version 6000.0.47f1 --module android --retries 0
+
+# Windows: skip the elevated (UAC) install helper (also via UNITY_NO_ELEVATE=1)
+unity install-modules --editor-version 6000.0.47f1 --module android --no-elevate
+```
+
+`--list` and `--all` are mutually exclusive. `--list` is also mutually exclusive with `--module`.
+
+A module whose download or validation fails intermittently — common for large modules such as Android SDK/NDK and OpenJDK — is retried automatically (up to twice with exponential backoff by default) instead of failing the whole run; already-installed modules are never re-downloaded, and retry attempts surface in both human and `--format ndjson` output.
+
+`--module android ios` (space-separated values after a single `--module`) and `--module android --module ios` (repeated flag) are equivalent — both install all listed modules.
+
+Module discovery works for editors registered via `unity editors add <path>` (located editors), not just editors installed by the Hub.
+
+---
+