docs: Codex resource-server key and the Unity 6.5 AI-package livelock

Two reported documentation gaps:

- resources/read takes a server key separate from the mcpforunity:// URI.
  Codex exposes tools as mcp__unityMCP__* but wants server: "unityMCP" on a
  resource read, which the server instructions never mentioned. Distinct
  from the name-vs-URI mistake #1302 fixed.
- com.unity.ai.assistant can livelock AssetDatabase::InitialRefresh on Unity
  6000.5.x, before any MCP assembly loads, which presents as an MCP
  connection failure. Documents the packages-lock.json deletion people miss.

Fixes #1220
Fixes #1219

Author: Scriptwonder

Server/src/main.py

@@ -319,6 +319,7 @@ def _build_instructions(project_scoped_tools: bool) -> str:
 - Resources are addressed by URI, never by name. A resource's name and URI are NOT interchangeable: names use underscores (e.g. editor_state) while URIs use slashes (e.g. mcpforunity://editor/state). Do NOT build a URI by swapping separators in the name — you will 404.
 - These instructions always spell resources as full mcpforunity:// URIs — read one exactly as written. If you only have a name (from resources/list or another tool's output), look its URI up in resources/list rather than guessing it.
 - Resource payloads are wrapped: the content lives under a top-level `data` object, so field paths are `data.<section>.<field>` (e.g. `data.advice.ready_for_tools`), not bare top-level fields.
+- The mcpforunity:// URI names the resource, not the server. Some clients take a separate server key on a resource read — in Codex, tools are exposed as mcp__unityMCP__* but resources/read wants server: "unityMCP". If a read fails with an unknown-server error, list resources first and use the key exactly as returned.
 
 Script Management:
 - After creating or modifying scripts (by your own tools or the `manage_script` tool) use `read_console` to check for compilation errors before proceeding

website/docs/guides/troubleshooting.md

@@ -146,6 +146,42 @@ Unity AI Assistant bundles `System.Collections.Immutable` v10, while MCP for Uni
 
 ---
 
+## Unity 6.5: Editor hangs on load and the bridge never connects
+
+If Unity 6000.5.x spins at ~100% CPU on startup and never opens the Editor window, check `Packages/manifest.json` for `com.unity.ai.assistant` (and `com.unity.ai.inference`, `com.unity.asset-manager-for-unity`).
+
+**Symptoms:**
+- The Editor never finishes loading, so MCP for Unity never arms its bridge — which looks like an MCP connection failure
+- Stack traces sit inside `AssetDatabase::InitialRefresh` → `SourceAssetScanner::Refresh` → `GuidDB::ValidateChangedGUIDs`
+
+**Cause:**
+The pre-release AI packages can livelock `AssetDatabase::InitialRefresh`. This happens before any MCP for Unity assembly is loaded, so no MCP code is involved.
+
+**Fix:** remove those packages from `manifest.json`, **delete `Packages/packages-lock.json`** (it re-resolves them otherwise), then clear `Library/`. Disabling the package is not enough — the AI packages re-add each other.
+
+This is a Unity bug (UUM-132096), not an MCP for Unity one.
+
+*Reported by [@100yenadmin](https://github.com/CoplayDev/unity-mcp/issues/1219).*
+
+---
+
+## Codex: `resources/read failed: unknown MCP server`
+
+The `mcpforunity://` URI names the *resource*, not the server. Some clients take a separate server key on a resource read.
+
+In Codex, tools are exposed as `mcp__unityMCP__*`, but `resources/read` wants the discovery key on its own:
+
+```
+server: "unityMCP"
+uri: "mcpforunity://custom-tools"
+```
+
+If a read fails with an unknown-server error, list resources first and use the key exactly as returned.
+
+*Reported by [@drewclifton](https://github.com/CoplayDev/unity-mcp/issues/1220).*
+
+---
+
 ## "No Unity Instances Found"
 
 :::tip When in doubt, restart your client