Added

• Self-evolving C# snippet library: cs snippets list / show / search / use / add / update / deprecate / prune / stats. Snippets are project-local markdown
  files at .unity-cli/snippets~/<id>.md containing a static Run(...) method;
  the CLI wraps each submission in a unique static class __Snip_<hash> for
  symbol isolation across REPL sessions. Validation gate runs each new snippet's
  example through the REPL (read-only auto-validated; mutates requires
  --no-validate and is recorded as unverified). Usage tracking auto-deprecates
  snippets after 5 consecutive failures spanning ≥ 7 days. Cold detection is
  informational only; prune --cold is opt-in.
• unity-cli-snippets skill: operator's manual for the snippet library, with
  hard decision order (command → snippet → ad-hoc) and distill criteria.
• cs snippets doctor [--revalidate]: anti-rot health check — integrity
  drift (orphan files, missing files, corrupt bodies), staleness (broken /
  cold / unverified), removal candidates, and opt-in live revalidation of
  read-only snippets to catch Unity API drift after upgrades. Paired with
  the unity-cli-snippets-audit skill (triage table; destructive cleanup
  always requires user confirmation).
• cs setup automatically adds .unity-cli/snippets-stats.json to the project
  .gitignore to avoid PR churn from routine usage tracking. The audit file
  (snippets-audit.json) remains committed as project state.

Changed

• cs --json (slim mode) now parses data.resultJson automatically when the
  underlying response carries it as a JSON string. cs list-commands --json
  consumers should read data.commands directly (previously they had to
  json.loads(data) first). The old shape is still emitted under --verbose.

Fixed

• cs catalog sync now reads commandNamespace and arguments from the
  wire response. Previously it looked for namespace and args, which the
  service does not emit — so every synced custom-command entry ended up with
  an empty namespace, a broken id like ".action", and an empty args
  list, and the next sync's diff would falsely flag all prior entries as
  removed. Both legacy field names are still accepted for forward
  compatibility.
• cs list-commands --type {builtin,custom} now actually filters when the
  underlying response carries resultJson as a parsed dict. Previously the
  filter wrote to data.commands but left data.resultJson unchanged, and
  _slim_result then surfaced the unfiltered resultJson, so all three
  --type values returned the same list.
• /unity-cli-sync-catalog description corrected: it audits the built-in
  tables in unity-cli-command/SKILL.md against the live Editor and is
  intended for plugin maintainers, not for refreshing the per-project custom
  command cache (use /unity-cli-refresh-commands for that).
• cs exec --mode runtime now actually runs on the player. Previously the
  CLI's ConsoleSession.exec unconditionally called execute_editor_request,
  so runtime-mode snippets were POSTed to the editor's "editor" endpoint
  (via compile_ip:compile_port) without targetIP/targetPort, silently
  executing in the local Editor instead of the player and ignoring --ip
  entirely. The exec path now mirrors the REPL: in runtime mode it calls
  execute_runtime_request, which POSTs to "compile" with
  targetIP/targetPort so the Editor compiles and forwards to the player.
  command / batch / complete continue to route through the editor by
  design (matching the REPL's behavior — most commands are editor-only).

Changed

• cs setup now pins the package to the latest vMAJOR.MINOR.* tag in the
  remote that matches the plugin's version, instead of writing a bare URL
  (which Unity resolved to HEAD of the default branch). This eliminates the
  drift that produced plugin X.Y.x ≠ package X.Z.x warnings shortly
  after a package release. Discovery uses git ls-remote --tags; on no
  match or network failure, setup falls back to HEAD with a one-line
  warning. Pass --no-pin to opt out, or --source URL#tag to pin
  explicitly.
• cs setup --method local now git checkouts the resolved tag in the
  local clone (fresh or existing). The clone ends in detached HEAD; if you
  intend to develop in the clone, run git checkout main afterward.

Fixed

• cs setup no longer prints a misleading Pinning to vX.Y.Z line (and
  no longer hits the network) on no-op runs where the package is already
  installed and --update was not passed. Pin resolution is now lazy.
• Release workflow now passes --title "vX.Y.Z" to gh release create so
  the rendered release title is just the tag, not the GitHub web fallback
  of {tag}: {commit subject}.

Added

• cs exec --file PATH reads C# code from a file. Useful for long or
  multi-line snippets where shell quoting would otherwise be painful.
  UTF-8 BOM is stripped automatically (handles files saved by Visual
  Studio / Rider / Unity).
• Empty / unreadable files are rejected with a clean parser error
  instead of silently sending empty code to Roslyn.

Fixed

• Shared flags (--project, --ip, --port, --mode, --timeout,
  --json, ...) placed before the subcommand are no longer reset to
  their defaults by the subparser. Both cs --project X status and
  cs status --project X now behave the same.

Workflow

• Release notes are sourced from this file. The release.yml workflow
  looks up the section matching the pushed tag and falls back to
  --generate-notes when no matching section is present.
• The Codex companion plugin now publishes its own GitHub Release for
  every vX.Y.Z-codex tag, mirroring the main release. Previously the
  -codex tag was created but no Release was attached, because tags
  pushed by GITHUB_TOKEN cannot trigger other workflows.

Full Changelog: v1.3.1...v1.4.1

What's New in v1.3.1

Refresh System Overhaul

The cs refresh command has been completely reworked to fix compilation reliability issues and add targeted import support.

Two-Mode Refresh

Targeted mode is ideal for agent workflows where the caller knows exactly which files changed. It is O(N) where N = number of changed files, regardless of project size.

Full mode now uses SetForegroundWindow (Windows P/Invoke) to bring Unity to the foreground before calling Refresh(). This ensures the OS file-watcher queue is flushed, making Refresh() reliable even when Unity runs in the background.

Root Causes Fixed (C# Package Side)

These fixes are in com.zh1zh1.csharpconsole v1.3.1, consumed by this plugin:

--wait Timeout

• Cap raised from 300s to 600s (10 minutes) to accommodate large projects with long compilation times
• Default in /unity-cli-refresh slash command raised from 60s to 120s
• The C# state machine has no compilation timeout — it waits indefinitely for isCompiling to finish

Setup UX Improvements

• Local setup always checks for updates: cs setup --method local now runs git pull --ff-only every time instead of silently returning "Already installed"
• Version alignment check on setup: Both local and git methods now compare plugin vs package version after confirming installation. Prints ⚠ version mismatch when misaligned
• Slash commands offer immediate action: /unity-cli-setup and /unity-cli-status now directly ask whether to update when a version mismatch is detected, instead of passively reporting it

Port Management

• Constants extracted: DEFAULT_EDITOR_PORT = 14500, DEFAULT_RUNTIME_PORT = 15500 centralized in cli/init.py
• Auto-detection: Reads Temp/CSharpConsole/refresh_state.json to discover the actual editor port (supports dynamic port allocation)
• Runtime mode fix: compile_ip/compile_port now correctly route refresh/compile operations to the editor service when --mode runtime

Connection Reliability

• Broader error handling: Retry logic now catches OSError (stdlib base class) instead of just ConnectionRefusedError, covering all socket-level failures including those from bundled requests library
• TOCTOU fix: detect_port() no longer does redundant exists() check before read_text() — eliminated race condition
• Deferred port detection: detect_port() only reads disk when the result is actually needed

Command Catalog Update

9 new prefab asset commands added to SKILL.md (total: 46 to 59 commands):

Housekeeping

• Removed completed design docs from git history (docs directory purged via git filter-repo)
• .gitignore now excludes docs directory

Companion Package

Requires com.zh1zh1.csharpconsole v1.3.1 for the refresh reliability fixes.

Full changelog: v1.2.0...v1.3.1

Full Changelog: v1.1.4...v1.2.0

Full Changelog: v1.1.3...v1.1.4

Title: v1.1.1 — Codex installer safety & package path management

Release notes:

What's Changed

Codex Installer

• Rollback-safe plugin update: clone to temp directory before replacing existing plugin, preventing data loss on clone failure

Package Path Management

• Cache rekeyed by agent working directory, supporting multiple Unity projects without cache collisions
• Setup validates clone completeness via package.json check and cleans up partial clones on retry
• Post-setup commands resolve package path explicitly with clear error when package is missing

Bug Fixes

• Only retry HTTP POST on ConnectionRefusedError (request never reached server), avoiding duplicate execution of non-idempotent commands
• Fix ConsoleSession.emit crash when outputting non-JSON text results
• Add .pkg-cache.json to .gitignore