@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/skills/unity-cli/references/docs-workflow.md

@@ -0,0 +1,179 @@
+# Docs workflow: find, cite and match Unity documentation
+
+Part of the **`unity-cli`** skill. See that skill's `SKILL.md` for CLI install, global flags, environment
+variables and exit codes. The full flag list for `unity docs` and `unity docs toc` is in
+[diagnostics-maintenance.md](diagnostics-maintenance.md#docs--version-matched-unity-documentation); this file
+is the order an agent follows, with 2D examples.
+
+**Why use it:** the pages `unity docs` resolves match the Editor version of the project you are in. An API
+remembered from another Unity version is a common source of wrong code, 2D physics and Tilemap included.
+
+Relative links in this file resolve to the skill directory's `references/` folder, so `../SKILL.md` is the skill's main page.
+
+## Contents
+
+- The flow
+- Version flags
+- The page index cache
+- Rules for agents
+
+## The flow
+
+1. **Find the page with `docs toc`.** It lists real pages, so you never guess a name.
+2. **Resolve the address with `docs --url`.** It prints the docs.unity.com address and opens nothing.
+3. **Cite or read it.** Put the address in your answer or review comment, or print the page's Markdown with
+   `docs --content`. Without `--url` or `--content`, `unity docs` opens the page in the default browser
+   (only useful when a person is watching).
+4. **Cache the docs with `docs cache add`** before working offline, or when you will read many pages.
+5. **Pin the version** whenever the project is not the one you are standing in (see Version flags).
+
+For a package's manual (`com.unity.*`), use `docs --package` instead of steps 1 and 2.
+
+### 1. Find a page: `docs toc`
+
+```bash
+unity docs toc --format json                             # scripting API reference, this project's version
+unity docs toc --manual --format json                    # the manual
+unity docs toc --editor-version 6000.0 --format ndjson   # one page per line, for a version branch
+```
+
+Each entry has a `path` (`unityengine/rigidbody2d/addforce`) and an absolute `url`. Under `--format json`,
+`data` is `{version, requestedVersion, section, entries}`. `--format ndjson` writes one entry per line. The
+default human and `--format tsv` output show the path and URL as two columns. The index carries no page
+titles, only paths, so search the entries for the class or member name you want.
+
+Only the Engine scripting API and the manual have an index. `--cli`, `--hub` and `--cloud` publish none, so
+`toc` doesn't take them.
+
+### 2. Resolve the address: `docs --url`
+
+```bash
+unity docs --url Rigidbody2D                  # the class page
+unity docs --url Rigidbody2D.AddForce         # a member page
+unity docs --url Tilemap.SetTile              # another 2D member
+unity docs --url UnityEngine.SpriteRenderer   # a qualified name matches exactly
+unity docs --url --manual "2D physics"        # the manual is a search, so this returns a search address
+```
+
+A bare class name or `Class.member` matches the page whose path ends with it (preferring `UnityEngine`, then
+`UnityEditor`). A name two pages tie on goes to search rather than a guess. The lookup never fails the
+command: offline, a qualified name is built directly when a version is known (a project or
+`--editor-version`), and anything else goes to search.
+
+Add `--format json` to see how the address was found:
+
+```bash
+unity docs --url Rigidbody2D.AddForce --format json
+```
+
+`data` carries `url`, `opened` (false under `--url`), `version` (the docs version in the URL, `null` for a search or a home page),
+`requestedVersion` (the one you asked for) and `resolvedBy`: `index` (an exact page from the index),
+`direct` (built without the index) or `search` (a search page). When `resolvedBy` is `search`, the address is
+a list of results, not the page. For a scripting API page, run `docs toc` and pick a path. The manual has
+no name lookup, so `docs --url --manual` always returns search results: for a manual page, cite the `url` of
+the `docs toc --manual` entry you picked.
+
+### 3. Read a page: `docs --content`
+
+```bash
+unity docs --content Rigidbody2D.AddForce                      # the page's Markdown on stdout
+unity docs --content Rigidbody2D.AddForce --format json        # wrapped with url, version and source
+```
+
+The scripting API resolves by name as `--url` does. The manual has no name lookup, so `--content --manual`
+fails; read a cached manual page from its file instead (below).
+
+### Package manuals: `docs --package`
+
+```bash
+unity docs --package com.unity.2d.sprite --url                   # the manual for the version the project uses
+unity docs --package com.unity.inputsystem --url --format json   # adds package, packageVersion and resolvedBy
+```
+
+Package manuals live on docs.unity3d.com, not docs.unity.com. The version is the one in the project's
+`Packages/packages-lock.json`, a package built into the Editor uses its one manual version, and anything else
+(outside a project too) uses the newest release on the Unity registry. A name the registry doesn't list fails
+with `DOCS_PACKAGE_UNKNOWN`, and a registry that can't be reached with `NETWORK_UNREACHABLE`. `--package`
+takes no topic and can't be combined with another documentation set, `--search` or `--editor-version`.
+
+Without `--url`, a project that has the package's own `Documentation~` page opens that local Markdown
+first, offline, with no registry call; `--online` skips it. JSON then says `resolvedBy: local`,
+`source: local` and gives the file's `path`. `--url` always prints the online manual, so use it for links.
+
+### 4. Work offline: `docs cache`
+
+```bash
+unity docs cache add                                     # the manual, this project's version
+unity docs cache add --api --editor-version 6000.0       # the scripting API too (about 96,000 pages)
+unity docs cache --format json                      # what is cached, per version
+```
+
+`add` prints the folder it fills: one Markdown file per page, `<section>/<path>.md` under the version, with
+the section's listing in `<section>.txt` beside it. After that:
+
+- `docs --content` reads a cached page without a request (`source: cache` in json), and caches every page it
+  fetches online too.
+- `docs toc` and the name lookup behind `docs --url` and `--content` use the cached listing when
+  docs.unity.com can't be reached.
+- Manual pages are read from their files: `docs toc --manual` path `get-started/first-time-user/2dor3d` is
+  `manual/get-started/first-time-user/2dor3d.md` under the version's folder.
+
+A failed `add` (`DOCS_CACHE_INCOMPLETE`) resumes where it stopped when run again. Cached pages don't
+expire: run `add` again to refresh them, `docs cache clear --yes` to delete them. `unity cache clean`
+deletes them with the other downloads.
+
+### Other documentation sets
+
+`--cli`, `--hub` and `--cloud` look a topic up in the Unity CLI, Unity Hub or Unity Cloud documentation. Topic
+names are lowercase and hyphenated (`use-unity-cli`, `project-create`, `developer-data/collection-settings`).
+These sets are not versioned by Editor, so `--editor-version` with one of them is a usage failure, and so is
+passing two sets at once.
+
+```bash
+unity docs --url --cli use-unity-cli
+unity docs --url --hub project-create
+```
+
+## Version flags
+
+The documentation version is, in order:
+
+1. `--editor-version <version>`: a full version (`6000.0.26f1`) or a version branch (`6000.0`). An
+   unparseable value is a usage failure, not a silent fallback.
+2. The current project's `ProjectSettings/ProjectVersion.txt`. No Editor has to be installed.
+3. The newest version docs.unity.com hosts.
+
+A version the site doesn't host resolves to the nearest hosted version below it (or the oldest hosted one),
+with a one-line notice on stderr. Read `version` against `requestedVersion` in the JSON when the difference
+matters.
+
+Pin the version in two cases: you are not inside the project (a new 2D project you have yet to create, or a
+question about another Editor), or the project upgrades soon and you are checking an API against the target
+version.
+
+```bash
+unity docs --url Rigidbody2D.AddForce --editor-version 6000.0
+unity docs toc --editor-version 2022.3 --format ndjson
+```
+
+## The page index cache
+
+`docs toc` and the index lookup behind `docs --url` download the page index once a day and read it from a
+local cache after that, so repeat calls in a session are fast. With no connection and no fresh cache:
+
+- `docs toc` fails with `NETWORK_UNREACHABLE` (exit 7). A server error is `DOCS_TOC_FETCH_FAILED` and an
+  index that can't be read is `DOCS_TOC_INVALID`.
+- `docs --url` does not fail. It builds a qualified name directly when a version is known (a project or
+  `--editor-version`) and sends anything else to search.
+
+This daily cache holds the page index only. For page content offline, and an index that never expires, use
+`docs cache add` (step 4): with a cached version, `docs toc` lists it offline instead of failing.
+
+## Rules for agents
+
+- Resolve the address first and cite it. Don't quote an API from memory when a page for the project's
+  version exists.
+- Prefer `--format json` and read `resolvedBy`, so you can tell a real page from a search.
+- Don't open a browser from an unattended run: use `--url`.
+- Only use documentation addresses the CLI printed: `docs.unity.com` for the Engine, CLI, Hub and Cloud
+  docs, and `docs.unity3d.com/Packages/` for package manuals from `docs --package`.

package/skills/unity-cli/references/editor-targeting.md

@@ -0,0 +1,29 @@
+# More than one Editor open? Pass `--project-path`
+
+Every Editor-driving command takes `--project-path <path>`. **Pass it whenever more than one Editor may be running** — without it the CLI targets the Editor whose project contains the current directory, so the target follows the shell's cwd:
+
+```bash
+unity command editor.playmode start --project-path /path/to/MyProject
+```
+
+To pin one Editor when several share a project (worktrees, duplicate projects, Multiplayer Play Mode players), `unity command`, `list`, `job` and `mcp` also take `--port <number>`, `--pid <number>` or `--instance <name>` (the MPPM instance name or `vpId`); a pin that matches no running Editor exits 12 with `EDITOR_NOT_RUNNING`. A `unity status` instance's `project` field is what `--project-path` takes. For `unity command`/`list`/`job`/`mcp`, matching no running project fails with `AMBIGUOUS_EDITOR` and lists the candidates. [Details](integration-advanced.md#targeting-one-of-several-running-editors).
+
+**Working in several worktrees or agent sessions? One Editor per worktree.** Make each worktree with `unity vcs git worktree add <branch> --into <path>`, so you choose where it lands. `--into` is optional: `--format json` reports the real worktree and project paths, and only the human output masks the account name in a home-directory path. The Unity project is `<path>` when it sits at the repository root, and `<path>/<its folder>` when it doesn't. Open that project's own Editor with `unity open <project>`. Then pin every call that reaches the Editor to that project: pass `--project-path <full project path>`, or prefix the call with the variable, as in `UNITY_PROJECT_PATH=<full project path> unity command editor status`. Most agent tools run each command in a fresh shell, so an `export` or a bare assignment in one call never reaches the next one. Every command that takes `--project-path` reads the variable when you pass no path, and so does `unity open`. Only `close`, `projects unlink cloud`, `mcp configure` and `ci init` don't read it: pass the path to those. Without the variable, a bare `unity open` opens the project of the current directory, which is still your source checkout. Target that Editor by the same full path every time, including `unity status --until-ready --project-path <project>`. A path that exists matches only that project, while a bare name also matches a sibling whose path contains it. Never drive an Editor whose project is not your own checkout (or one of its Multiplayer Play Mode clones). An Editor open on a sibling worktree answers every command just like yours. A command sent there edits that checkout's scenes, and its Play mode, recompiles and imports run against that checkout's code. If your own Editor isn't open, open it. If it has gone away, tell the user rather than borrowing the one that is running.
+
+Requires the project's `com.unity.pipeline` package (Unity 6.0+) — add it once with `unity pipeline install`. Full details — launching a headless Editor to drive, `unity command` tool discovery, and authoring custom `[CliCommand]` tools — are in [integration-advanced.md](integration-advanced.md).
+
+The package also ships a deeper `unity-pipeline` agent skill, invisible to clients inside `Library/PackageCache` — in a project with the package, run `unity skill install <client> --local` once to mirror it beside this skill.
+
+> **Can't connect / commands time out? Check for Safe Mode first.** When a project has C# compile errors, the Editor boots into **Safe Mode**, where the Pipeline package doesn't load, so `unity command` and `unity recompile` can't connect at all (`unity status` doesn't connect for this: it reads the Editor's log and reports Safe Mode). Note what that means for `unity recompile` specifically: it reports errors you introduce into an Editor that is **already running**, but an Editor that *started* with broken code never loads the package, so there is nothing to ask and it exits `7` rather than reporting the errors. Don't fall back to blind file-editing: run `unity status` (it reports Safe Mode and lists the compile errors, `safeMode.compileErrors` under `--format json`), then fix the errors: the Editor leaves Safe Mode once they compile. Full recovery loop in [integration-advanced.md → Recovering from Safe Mode](integration-advanced.md#recovering-from-safe-mode-connection-fails-because-of-compile-errors).
+
+> **Running as a sandboxed coding agent and `unity status` reports no instances?** A restrictive sandbox can hide an Editor that is genuinely running from this CLI's view of it — don't treat that alone as proof the Editor is down. Full detail in [integration-advanced.md → Sandboxed agent tooling can hide a running Editor](integration-advanced.md#sandboxed-agent-tooling-can-hide-a-running-editor).
+
+> **A call timed out, or the Editor's lifecycle failed? Tell the user, don't silently work around it.** First rule out [Safe Mode](integration-advanced.md#recovering-from-safe-mode-connection-fails-because-of-compile-errors), a sandbox, and an Editor that is still importing or loading. Read `errors[0].code` under `--format json`, and give a slow import a longer `--timeout`. If it is still one of these, report it:
+>
+> - a command that times out
+> - an Editor that never reaches `ready` under `unity status --until-ready` (exit 6)
+> - a connection that drops mid-command
+> - an Editor that quits or restarts under you
+> - a `unity open` that never produces an Editor
+>
+> Don't quietly retry in a loop, switch to another Editor, or fall back to hand-editing scene and asset files. Say what you ran, what failed and what you already tried. Then offer to file it with `unity bug --area pipeline-package` (`--area editor` when the Editor itself quit or never started), and ask first: `unity bug` sends logs to Unity, so never run it on your own initiative.