chore: import upstream snapshot with attribution

docs/asset-gen-manual-verification.md

@@ -0,0 +1,82 @@
+# AI Asset Generation — Manual Verification Checklist
+
+The `asset_gen` tools call real third-party APIs and write real files into a licensed
+Unity Editor, so they **cannot be covered headlessly**. Run this checklist by hand with
+genuine provider keys and an interactive Editor before shipping.
+
+## Prerequisites
+
+- [ ] A licensed Unity Editor with the package installed and the bridge connected.
+- [ ] Enable the group: `manage_tools` → enable `asset_gen` (it is off by default).
+- [ ] Open **Window → MCP for Unity → Asset Gen** tab to enter provider keys
+      (stored in the OS secure store — Keychain / Windows Credential Manager / libsecret).
+
+## Tripo (default 3D, text→3D)
+
+- [ ] Enter the Tripo key in the **Asset Gen** tab.
+- [ ] `generate_model(provider=tripo, mode=text, prompt="a low-poly oak tree", format=fbx)`.
+- [ ] Poll `generate_model(action=status, job_id=<id>)` until it reports done.
+- [ ] Confirm an FBX appears under `Assets/Generated/Models/`.
+- [ ] Confirm it imports cleanly **with materials**.
+
+## glTFast / GLB
+
+- [ ] Install **glTFast** from the **Dependencies** tab.
+- [ ] `generate_model(provider=tripo, mode=text, prompt="...", format=glb)`, poll status.
+- [ ] Confirm the GLB imports correctly (no missing-importer error).
+
+## fal.ai (default 2D image)
+
+- [ ] Enter the fal key.
+- [ ] `generate_image(provider=fal, prompt="a pixel-art coin", transparent=true)`.
+- [ ] Confirm a PNG sprite under `Assets/Generated/Images/` with **alpha** preserved
+      and **correct sRGB** color.
+
+## OpenRouter (2D image)
+
+- [ ] Enter the OpenRouter key.
+- [ ] `generate_image(provider=openrouter, prompt="...")`.
+- [ ] Confirm the inline-image path works (image bytes decode and import as a sprite).
+
+## Sketchfab (3D import)
+
+- [ ] Enter the Sketchfab token.
+- [ ] `import_model(action=search, query="wooden chair")`, then
+      `import_model(action=import, uid=<from search>)`.
+- [ ] Confirm the downloaded zip extracts and the model imports.
+- [ ] Confirm the **path-traversal guard** holds (no files written outside the target dir).
+
+## Meshy (3D)
+
+- [ ] Enter the Meshy key.
+- [ ] `generate_model(provider=meshy, mode=text, prompt="...")`, poll status.
+- [ ] Confirm the model imports.
+
+## Image input & provider params (verify the post-review fixes)
+
+These paths are covered by unit tests at the request-shaping layer only — confirm them against
+**real provider APIs** (the unit tests can't validate that the provider accepts the shape).
+
+- [ ] **Meshy text→3D textures:** `generate_model(provider=meshy, mode=text, prompt="...", texture=true)`
+      → confirm the result is **textured** (Meshy runs a preview then a refine task internally).
+- [ ] **Local image→3D (Meshy):** `generate_model(provider=meshy, mode=image, image_path=Assets/refs/x.png)`
+      → confirm it imports a model derived from the local image.
+- [ ] **Local image→image (fal):** `generate_image(provider=fal, mode=image, image_path=Assets/refs/x.png, prompt="make it night")`
+      → confirm fal's `/edit` endpoint accepts the request and returns an edited image.
+- [ ] **Local image→image (OpenRouter):** `generate_image(provider=openrouter, mode=image, image_path=..., prompt="...")`
+      → confirm the reference image influences the result.
+- [ ] **fal output size:** `generate_image(provider=fal, width=512, height=512, prompt="...")`
+      → confirm the returned image is 512×512.
+- [ ] **Tripo local image is rejected clearly:** `generate_model(provider=tripo, mode=image, image_path=...)`
+      → confirm the job fails with a clear "Tripo requires a hosted image_url" message (no silent text fallback).
+- [ ] **Sketchfab search filters/paging:** `import_model(action=search, query="chair", categories=furniture-home, count=12, cursor=<from prior cursors.next>)`
+      → confirm filtering works and `cursors.next` advances the page.
+- [ ] **Transparency is import-only:** `generate_image(transparent=true)` sets the Unity alpha-is-transparency
+      flag but does NOT produce a transparent background (fal/FLUX limitation) — confirm the expectation.
+
+## Multi-agent / security spot-check
+
+- [ ] Confirm no key value ever appears in MCP tool output.
+- [ ] Confirm no key value appears in logs.
+- [ ] Confirm no key value appears in the job `status` payload.
+- [ ] Confirm no key value is committed to git.

docs/development/README-DEV-zh.md

@@ -0,0 +1,139 @@
+# MCP for Unity - 开发者指南
+
+| [English](README-DEV.md) | [简体中文](README-DEV-zh.md) |
+|---------------------------|------------------------------|
+
+## 贡献代码
+
+**从 `beta` 分支创建 PR**。`main` 分支仅用于稳定版本发布。
+
+在提出重大新功能之前，请先联系讨论——可能已有人在开发，或者该功能曾被讨论过。请通过 issue 或 discussion 进行协调。
+
+## 本地开发环境设置
+
+### 1. 将 Unity 指向本地 Server
+
+开发 Python server 时，最快的迭代方式：
+
+1. 打开 Unity，进入 **Window > MCP for Unity**
+2. 打开 **Settings > Advanced Settings**
+3. 将 **Server Source Override** 设置为本地 `Server/` 目录路径
+4. 启用 **Dev Mode (Force fresh server install)** - 这会在 uvx 命令中添加 `--refresh`，确保每次启动 server 时都使用最新代码
+
+### 2. 切换包源
+
+使用 `mcp_source.py` 快速切换 Unity 项目的 MCP 包源：
+
+```bash
+python mcp_source.py
+```
+
+选项：
+1. **Upstream main** - 稳定版本 (CoplayDev/unity-mcp)
+2. **Upstream beta** - 开发分支 (CoplayDev/unity-mcp#beta)
+3. **Remote branch** - 你的 fork 当前分支
+4. **Local workspace** - 指向本地 MCPForUnity 文件夹的 file: URL
+
+切换后，在 Unity 中打开 Package Manager 并 Refresh 以重新解析依赖。
+
+## 工具选择与 Meta-Tool
+
+MCP for Unity 将工具组织为**分组**（Core、VFX & Shaders、Animation、UI Toolkit、Scripting Extensions、Testing）。你可以选择性地启用或禁用工具，以控制哪些能力暴露给 AI 客户端——减少上下文窗口占用，让 AI 专注于相关工具。
+
+### 使用编辑器中的 Tools 标签页
+
+打开 **Window > MCP for Unity**，切换到 **Tools** 标签页。每个工具分组显示为可折叠面板，包含：
+
+- **单个工具开关** — 点击单个工具的开关来启用或禁用。
+- **分组复选框** — 每个分组折叠面板的标题旁内嵌一个复选框，可一次性启用或禁用该分组内所有工具，且不会触发折叠面板的展开或收起。
+- **Enable All / Disable All** — 全局按钮，切换所有工具的启用状态。
+- **Rescan** — 重新从程序集发现工具（在添加新的 `[McpForUnityTool]` 类后使用）。
+- **Reconfigure Clients** — 一键重新注册工具到服务器并重新配置所有检测到的 MCP 客户端，无需返回 Clients 标签页即可应用更改。
+
+### 更改如何传播
+
+工具可见性的变更根据传输模式有所不同：
+
+**HTTP 模式**（推荐）：
+
+1. 切换工具会调用 `ReregisterToolsAsync()`，通过 WebSocket 将更新后的启用工具列表发送到 Python 服务器。
+2. 服务器通过 `mcp.enable()`/`mcp.disable()` 按分组更新内部工具可见性。
+3. 服务器向所有已连接的客户端会话发送 `tools/list_changed` MCP 通知。
+4. 已连接的客户端（Claude Desktop、VS Code 等）自动接收更新后的工具列表。
+
+**Stdio 模式**：
+
+1. 开关状态在本地保存，但无法推送到服务器（没有 WebSocket 连接）。
+2. 服务器启动时所有分组均启用。更改开关后，让 AI 执行 `manage_tools`，`action` 设为 `'sync'`——这会从 Unity 拉取当前工具状态并同步服务器可见性。
+3. 也可以重启服务器来应用更改。
+
+### `manage_tools` Meta-Tool
+
+服务器暴露一个内置的 `manage_tools` 工具（始终可见，不受分组限制），AI 可以直接调用：
+
+| Action | 描述 |
+|--------|------|
+| `list_groups` | 列出所有工具分组及其工具和启用/禁用状态 |
+| `activate` | 按名称启用一个工具分组（例如 `group="vfx"`） |
+| `deactivate` | 按名称禁用一个工具分组 |
+| `sync` | 从 Unity 拉取当前工具状态并同步服务器可见性（stdio 模式必需） |
+| `reset` | 恢复默认工具可见性 |
+
+### 何时需要重新配置
+
+切换工具启用/禁用后，MCP 客户端需要获知这些变更：
+
+- **HTTP 模式**：变更通过 `tools/list_changed` 自动传播。大多数客户端会立即更新。如果客户端未更新，请在 Tools 标签页点击 **Reconfigure Clients**，或前往 Clients 标签页点击 Configure。
+- **Stdio 模式**：服务器进程需要被告知变更。可以让 AI 调用 `manage_tools(action='sync')`，或重启 MCP 会话。点击 **Reconfigure Clients** 以使用更新后的配置重新注册所有客户端。
+
+## 运行测试
+
+所有新功能都应包含测试覆盖。
+
+### Python 测试 (502 个测试)
+
+位于 `Server/tests/`：
+
+```bash
+cd Server
+uv run pytest tests/ -v
+```
+
+### Unity C# 测试 (605 个测试)
+
+位于 `TestProjects/UnityMCPTests/Assets/Tests/`。
+
+**使用 CLI**（需要 Unity 运行且 MCP bridge 已连接）：
+
+```bash
+cd Server
+
+# 运行 EditMode 测试（默认）
+uv run python -m cli.main editor tests
+
+# 运行 PlayMode 测试
+uv run python -m cli.main editor tests --mode PlayMode
+
+# 异步运行并轮询结果（适用于长时间测试）
+uv run python -m cli.main editor tests --async
+uv run python -m cli.main editor poll-test <job_id> --wait 60
+
+# 仅显示失败的测试
+uv run python -m cli.main editor tests --failed-only
+```
+
+**直接使用 MCP 工具**（从任意 MCP 客户端）：
+
+```
+run_tests(mode="EditMode")
+run_tests(mode="PlayMode", init_timeout=120000)  # PlayMode 由于域重载可能需要更长的初始化时间
+get_test_job(job_id="<id>", wait_timeout=60)
+```
+
+### 代码覆盖率
+
+```bash
+cd Server
+uv run pytest tests/ --cov --cov-report=html
+open htmlcov/index.html
+```

docs/i18n/README-zh.md

@@ -0,0 +1,214 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="../images/logo-header-dark.png">
+    <img alt="MCP for Unity" src="../images/logo-header-light.png" width="400">
+  </picture>
+</p>
+
+<div align="center">
+
+[English](../../README.md) <img src="../images/connector.svg" alt="↔" height="14"> [简体中文](README-zh.md) &nbsp;&nbsp;&nbsp;|&nbsp;&nbsp;&nbsp; [Discord](https://discord.gg/y4p8KfzrN4) <img src="../images/connector.svg" alt="↔" height="14"> [Wiki](https://coplaydev.github.io/unity-mcp/)
+
+#### 由 [Aura](https://www.tryaura.dev/) 荣誉赞助并维护 —— 面向 Unreal 与 Unity 的 AI 助手。
+##### 别错过 [Godot AI](https://github.com/hi-godot/godot-ai) 🤖，MCP for Unity 团队推出的全新开源项目！
+
+</div>
+
+<p align="center">MCP for Unity 通过 <a href="https://modelcontextprotocol.io/introduction">Model Context Protocol</a> 把 Claude、Cursor、VS Code、本地大模型等 AI 助手接入 Unity 编辑器，让它们直接帮你管理资源、搭场景、写脚本、跑测试，把开发流程里的重复活儿都包了。</p>
+
+<p align="center">
+  <img alt="MCP for Unity building a scene" src="../images/building_scene.gif">
+</p>
+
+---
+
+<details>
+<summary><strong>最近更新</strong></summary>
+
+* **[v10.0.0](https://github.com/CoplayDev/unity-mcp/releases/tag/v10.0.0)**（2026-06-30）
+* **[v9.7.3](https://github.com/CoplayDev/unity-mcp/releases/tag/v9.7.3)**（2026-06-15）
+* **[v9.7.1](https://github.com/CoplayDev/unity-mcp/releases/tag/v9.7.1)**（2026-05-24）
+* **[v9.7.0](https://github.com/CoplayDev/unity-mcp/releases/tag/v9.7.0)**（2026-05-22）
+* **[v9.6.8](https://github.com/CoplayDev/unity-mcp/releases/tag/v9.6.8)**（2026-04-27）
+
+完整更新历史见 [发布说明](https://coplaydev.github.io/unity-mcp/releases)。
+
+</details>
+
+---
+
+## 它能做什么
+
+用自然语言从任意 MCP 客户端操作 Unity 编辑器：搭场景、建 GameObject、写改 C# 脚本、调材质和着色器、跑测试、看性能、出包。47 个 MCP 工具入口，任意客户端可用，免费、MIT 开源。
+
+**[查看完整工具目录 →](https://coplaydev.github.io/unity-mcp/reference/tools/)**
+
+---
+
+## 快速开始
+
+**环境要求：** Unity **2021.3 LTS → 6.x** · Python **3.10+**（用 [`uv`](https://docs.astral.sh/uv/) 管理）。兼容**任意 MCP 客户端**——Claude Desktop 与 Claude Code、Cursor、VS Code、Windsurf、Cline、Gemini CLI 等等。
+
+1. **安装** —— 在 Unity 里打开 Package Manager，从 git URL 添加：
+   `https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main` &nbsp;_（如需固定本次发布，可用 `#v10.0.0`；也可以用 `openupm add com.coplaydev.unity-mcp`）_
+2. **配置客户端** —— `Window → MCP for Unity → Configure All Detected Clients`，一键搞定所有检测到的客户端。
+3. **发个提示试试** —— *"在原点放一个立方体，加个 Rigidbody。"* 立方体几秒就出现在场景里了。
+
+<details>
+<summary><strong>手动配置</strong></summary>
+
+如果自动配置不生效，把下面的内容加到你的 MCP 客户端配置文件里：
+
+**HTTP（默认 —— 适用于 Claude Desktop、Cursor、Windsurf）：**
+```json
+{
+  "mcpServers": {
+    "unityMCP": {
+      "url": "http://localhost:8080/mcp"
+    }
+  }
+}
+```
+
+**VS Code：**
+```json
+{
+  "servers": {
+    "unityMCP": {
+      "type": "http",
+      "url": "http://localhost:8080/mcp"
+    }
+  }
+}
+```
+
+<details>
+<summary>Stdio 配置（uvx）</summary>
+
+**macOS/Linux：**
+```json
+{
+  "mcpServers": {
+    "unityMCP": {
+      "command": "uvx",
+      "args": ["--from", "mcpforunityserver", "mcp-for-unity", "--transport", "stdio"]
+    }
+  }
+}
+```
+
+**Windows：**
+```json
+{
+  "mcpServers": {
+    "unityMCP": {
+      "command": "C:/Users/YOUR_USERNAME/AppData/Local/Microsoft/WinGet/Links/uvx.exe",
+      "args": ["--from", "mcpforunityserver", "mcp-for-unity", "--transport", "stdio"]
+    }
+  }
+}
+```
+</details>
+</details>
+
+---
+
+<details>
+<summary><strong>多个 Unity 实例</strong></summary>
+
+MCP for Unity 支持同时开多个 Unity 编辑器实例。想把操作定向到某个实例：
+
+1. 让大模型读一下 `unity_instances` 资源
+2. 用 `set_active_instance` 传入 `Name@hash`（比如 `MyProject@abc123`）
+3. 之后所有工具调用都会走这个实例
+</details>
+
+<details>
+<summary><strong>Roslyn 脚本验证（进阶）</strong></summary>
+
+想用能查出未定义命名空间、类型和方法的 **Strict** 验证：
+
+1. 装 [NuGetForUnity](https://github.com/GlitchEnzo/NuGetForUnity)
+2. `Window > NuGet Package Manager` → 安装 `Microsoft.CodeAnalysis` v5.0
+3. 再装 `SQLitePCLRaw.core` 和 `SQLitePCLRaw.bundle_e_sqlite3` v3.0.2
+4. 在 `Player Settings > Scripting Define Symbols` 里加上 `USE_ROSLYN`
+5. 重启 Unity
+
+  <details>
+  <summary>手动安装 DLL（NuGetForUnity 用不了时）</summary>
+
+  1. 从 [NuGet](https://www.nuget.org/packages/Microsoft.CodeAnalysis.CSharp/) 下载 `Microsoft.CodeAnalysis.CSharp.dll` 及其依赖
+  2. 把 DLL 放进 `Assets/Plugins/`
+  3. 确认 .NET 兼容性设置正确
+  4. 在 Scripting Define Symbols 里加上 `USE_ROSLYN`
+  5. 重启 Unity
+  </details>
+</details>
+
+<details>
+<summary><strong>故障排除</strong></summary>
+
+* **Unity Bridge 连不上：** 看一下 `Window > MCP for Unity` 的状态，重启 Unity
+* **服务器起不来：** 确认 `uv --version` 能跑，并看看终端报错
+* **客户端连不上：** 确认 HTTP 服务在运行，且 URL 和你的配置一致
+
+**详细配置指南：**
+* [Fix Unity MCP and Cursor, VSCode & Windsurf](https://github.com/CoplayDev/unity-mcp/wiki/1.-Fix-Unity-MCP-and-Cursor,-VSCode-&-Windsurf) —— uv/Python 安装、PATH 问题
+* [Fix Unity MCP and Claude Code](https://github.com/CoplayDev/unity-mcp/wiki/2.-Fix-Unity-MCP-and-Claude-Code) —— Claude CLI 安装
+* [Common Setup Problems](https://github.com/CoplayDev/unity-mcp/wiki/3.-Common-Setup-Problems) —— macOS dyld 错误、常见问题
+
+还是搞不定？[提个 Issue](https://github.com/CoplayDev/unity-mcp/issues) 或者 [来 Discord 问](https://discord.gg/y4p8KfzrN4)
+</details>
+
+<details>
+<summary><strong>参与贡献</strong></summary>
+
+开发环境配置见 [README-DEV.md](../development/README-DEV.md)，自定义工具见 [CUSTOM_TOOLS.md](../reference/CUSTOM_TOOLS.md)。
+
+1. Fork → 开 issue → 建分支（`feature/your-idea`）→ 改 → 提 PR
+</details>
+
+<details>
+<summary><strong>遥测与隐私</strong></summary>
+
+匿名、注重隐私的遥测（不收集代码、项目名或任何个人数据），用 `DISABLE_TELEMETRY=true` 就能关掉。详见 [TELEMETRY.md](../reference/TELEMETRY.md)。
+</details>
+
+---
+
+**许可证：** MIT —— 见 [LICENSE](../../LICENSE) | **需要帮助？** [Discord](https://discord.gg/y4p8KfzrN4) | [Issues](https://github.com/CoplayDev/unity-mcp/issues)
+
+---
+
+## Star 历史
+
+[![Star History Chart](https://api.star-history.com/svg?repos=CoplayDev/unity-mcp&type=Date)](https://www.star-history.com/#CoplayDev/unity-mcp&Date)
+
+<details>
+<summary><strong>论文引用</strong></summary>
+如果 MCP for Unity 对你的研究有帮助，欢迎引用我们！
+
+```bibtex
+@inproceedings{10.1145/3757376.3771417,
+author = {Wu, Shutong and Barnett, Justin P.},
+title = {MCP-Unity: Protocol-Driven Framework for Interactive 3D Authoring},
+year = {2025},
+isbn = {9798400721366},
+publisher = {Association for Computing Machinery},
+address = {New York, NY, USA},
+url = {https://doi.org/10.1145/3757376.3771417},
+doi = {10.1145/3757376.3771417},
+series = {SA Technical Communications '25}
+}
+```
+</details>
+
+## Aura 的 Unity AI 工具
+
+Aura 出品两款 Unity AI 工具：
+- **MCP for Unity** —— MIT 许可证，免费开源。
+- **Aura for Unity** —— 面向游戏开发者的高级 Unity/Unreal AI 助手。
+
+## 免责声明
+
+本项目是一个免费开源的 Unity 编辑器工具，与 Unity Technologies 无关。

docs/images/connector.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 16" fill="none" role="img" aria-label="connected">
+  <line x1="3" y1="8" x2="29" y2="8" stroke="#22D3EE" stroke-width="1.4" stroke-opacity="0.6"/>
+  <g stroke="#22D3EE" stroke-width="2.2" stroke-linecap="round">
+    <line x1="12" y1="4.5" x2="12" y2="11.5"/>
+    <line x1="16" y1="4.5" x2="16" y2="11.5"/>
+    <line x1="20" y1="4.5" x2="20" y2="11.5"/>
+  </g>
+  <circle cx="3" cy="8" r="2.6" fill="#60A5FA"/>
+  <circle cx="29" cy="8" r="2.6" fill="#2DD4BF"/>
+</svg>

docs/wiki/V10.md

@@ -0,0 +1,285 @@
+# MCP for Unity v10 Release Notes
+
+These notes cover v10: the full major-version change from
+v9.0.0, the new AI asset generation/import surface, secure provider-key storage,
+Blender/local-file handoff, and the README/docs/brand refresh.
+
+For this comparison, **v9 means `v9.0.0`**, not the last v9 patch. The `v9.7.3`
+tag is still useful for the release-to-release changelog, but it already
+contains much of the v9 tool expansion.
+
+## What changed since v9.0.0
+
+At `v9.0.0`, MCP for Unity exposed 29 MCP tool entrypoints around the core Unity
+Editor loop: scenes, GameObjects, components, scripts, prefabs, assets,
+materials, shaders, VFX, console reads, editor refresh, async tests, custom
+tools, and batch execution.
+
+The v10 release exposes 47 MCP tool entrypoints across 10 groups:
+`core`, `animation`, `asset_gen`, `docs`, `probuilder`, `profiling`,
+`scripting_ext`, `testing`, `ui`, and `vfx`.
+
+| Area | `v9.0.0` baseline | v10 release |
+| --- | --- | --- |
+| Tool catalog | 29 MCP tool entrypoints, with most tools registered directly into one visible surface. | 47 MCP tool entrypoints across grouped domains. |
+| Tool visibility | No decorator-level group metadata and no `manage_tools` workflow for user-controlled visibility. | Tool registry has named groups; `core` is enabled by default and non-core groups are opt-in. |
+| Editor automation domains | Core scene/object/component/script/asset/prefab/material/shader/VFX/test/editor operations. | Adds build orchestration, camera/Cinemachine control, render pipeline and graphics operations, package management, physics, animation, UI Toolkit, profiling, ProBuilder, and procedural texture generation. |
+| Asset creation/import | Existing asset management and VFX/shader/script tools could create or modify project content, but external generation providers were not part of the product surface. | Adds the `asset_gen` group for Tripo/Meshy model generation, fal.ai/OpenRouter image generation, Sketchfab import, and local FBX/OBJ/glTF handoff from tools such as Blender. |
+| API lookup and docs | API discovery depended on external docs or local project inspection. | Adds `unity_docs` and `unity_reflect`, plus generated tool/resource reference docs. |
+| Safety model | Core tool execution, custom tools, async test polling, and instance routing were present. | Adds group-gated high-power tools, secure provider-key storage in Unity, project-scoped import hardening, archive/path validation, and more test coverage around transport, tool registry, provider adapters, and Unity compatibility. |
+| Editor UI and docs | The window focused on connection/client setup and the docs grew around accumulated features. | Adds tool/resource visibility flows, Asset Gen setup, glTFast dependency guidance, refreshed README/docs navigation, icons/social assets, and consistent "MCP for Unity" product naming. |
+
+Added MCP tool entrypoints since `v9.0.0`: `execute_code`,
+`generate_image`, `generate_model`, `import_model`, `import_model_file`,
+`manage_animation`, `manage_build`, `manage_camera`, `manage_graphics`,
+`manage_packages`, `manage_physics`, `manage_probuilder`, `manage_profiler`,
+`manage_texture`, `manage_tools`, `manage_ui`, `unity_docs`, and
+`unity_reflect`.
+
+## What v10 is about
+
+1. **A larger grouped tool surface** - the catalog grows from 29 to 47 MCP tool
+   entrypoints, with high-power domains split into opt-in groups.
+2. **Asset generation and import** - first-class MCP tools for generating 3D
+   models, generating 2D images, importing marketplace models, and handing off
+   local files from tools like Blender.
+3. **Safer agent operations** - provider keys stay in the Unity Editor, tools
+   are opt-in by group, long-running jobs are explicit and pollable, and file
+   writes are constrained to project assets.
+4. **Clearer product surface** - refreshed README, docs site, branding, and
+   distribution metadata.
+5. **Release confidence** - Python tests, Unity compile checks, docs builds, and
+   compatibility shims for the wide Unity support window.
+
+## AI Asset Generation
+
+The headline v10 feature is the new `asset_gen` tool group. It is disabled by
+default like other non-core tool groups, and can be enabled with `manage_tools`.
+
+| Tool | Purpose |
+| --- | --- |
+| `generate_model` | Generate 3D models from text or image prompts through providers such as Tripo and Meshy. |
+| `generate_image` | Generate 2D images through providers such as fal.ai and OpenRouter. |
+| `import_model` | Search and import downloadable Sketchfab models. |
+| `import_model_file` | Import a local model file already on disk, such as an FBX/OBJ/glTF exported from Blender. |
+
+Generation and import jobs are asynchronous. A request returns a `job_id`, and
+the client polls `action="status"` until the job completes or fails.
+
+### Providers
+
+- 3D generation: Tripo (default) and Meshy.
+- 3D import: Sketchfab.
+- 2D image generation: fal.ai (default) and OpenRouter.
+
+### Setup
+
+1. Open **Window > MCP for Unity > Asset Gen** and enter provider API keys.
+2. Enable the tools with `manage_tools`; the `asset_gen` group is off by
+   default.
+3. Install **glTFast** from the Dependencies tab for GLB output/import. FBX
+   import does not require glTFast.
+
+Provider keys are stored in the OS secure store and are not written to project
+assets or `EditorPrefs`.
+
+### Usage examples
+
+Generation runs through MCP tools or the `asset-gen` CLI, not from the Unity
+GUI. Long-running jobs return a `job_id`; call `action="status"` with that
+`job_id` until the job completes.
+
+```text
+generate_model action=generate provider=tripo mode=text prompt="a low-poly oak tree" format=fbx
+generate_model action=generate provider=meshy mode=image image_path=Assets/refs/chair.png
+generate_image action=generate provider=fal mode=text prompt="a pixel-art coin"
+import_model action=search query="wooden chair"
+import_model action=import uid=<uid from search>
+```
+
+### Provider caveats
+
+- `image_url` points at a hosted image.
+- `image_path` points at a local file, commonly under `Assets/`.
+- Meshy image-to-3D and fal/OpenRouter image-to-image support local
+  `image_path` inputs by sending the image inline as a base64 data URI.
+- Tripo image-to-3D currently needs a hosted `image_url`.
+- `transparent` sets the Unity texture import flag only; fal/FLUX does not
+  provide transparent-background generation.
+- `width` and `height` are forwarded to fal; OpenRouter's chat API has no size
+  control.
+
+## Provider keys
+
+Asset providers are bring-your-own-key. Keys are entered in the Unity Editor's
+Asset Gen tab and stored in the operating system secure store:
+
+- macOS: Keychain
+- Windows: Credential Manager
+- Linux: libsecret / Secret Service compatible tooling
+
+Keys are not written to project assets, `EditorPrefs`, generated docs, or MCP
+tool parameters. The MCP client can request a generation job, but it does not
+receive provider credentials.
+
+## Local image inputs
+
+v10 distinguishes hosted image inputs from local project images:
+
+- `image_url` points at an externally hosted image.
+- `image_path` points at a local file, commonly under `Assets/`.
+
+Meshy image-to-3D and fal/OpenRouter image-to-image can accept local image files
+by sending the image data inline as a base64 data URI. Tripo image-to-3D still
+requires a hosted `image_url` until an upload flow is wired.
+
+## Blender handoff
+
+The `import_model_file` tool creates a clean boundary between DCC generation and
+Unity import:
+
+1. The modeling tool creates or exports the asset.
+2. MCP for Unity imports the file with `import_model_file`.
+3. The Unity agent uses existing scene, material, prefab, and build tools to wire
+   the asset into the project.
+
+With BlenderMCP connected, a modeling workflow can export the current Blender
+model and import it through `import_model_file` (FBX by default). BlenderMCP
+handles modeling or generation; MCP for Unity handles import and scene
+placement. The Asset Gen tab shows a best-effort "Blender app detected" status,
+but BlenderMCP itself is configured in the AI client and is not detectable from
+Unity.
+
+This is a handoff, not MCP for Unity controlling Blender directly.
+
+## Safety model
+
+### Opt-in tool group
+
+`asset_gen` is not part of the default core tool set. Users must explicitly
+enable it with `manage_tools`.
+
+### Project-scoped imports
+
+Generated and imported assets resolve into the Unity project's `Assets/` folder,
+with traversal and unsafe paths rejected. Archives are extracted through
+allowlisted import paths and extensions rather than blindly writing every file
+a provider returns.
+
+### No hidden spend
+
+Generation calls go to third-party providers using the user's own API keys.
+
+- MCP for Unity does not bundle provider credits.
+- Provider pricing, rate limits, and content policies are controlled by the
+  provider.
+- Enable the tool group only when you intend to call generation or import
+  providers.
+
+## Docs and brand refresh
+
+v10 also updates the project front door:
+
+- README trimmed into a clearer front door.
+- Docs site reorganized around Getting Started, Guides, Reference,
+  Architecture, Contributing, Migrations, and Releases.
+- Tool reference pages are generated from the tool registry.
+- Distribution and analytics docs are explicit about what is measured and what
+  is not.
+- Branding now consistently uses **MCP for Unity** in user-facing UI and docs.
+
+## Compatibility posture
+
+v10 continues the existing compatibility promise:
+
+- Unity 2021.3 LTS remains the package floor.
+- Unity 6.x stays in the supported matrix.
+- Known Unity API changes route through compatibility helpers under
+  `MCPForUnity/Runtime/Helpers/`.
+- Contributors touching shims or version-gated APIs run
+  `tools/check-unity-versions.sh` against installed Unity Hub editors.
+
+## Upgrade notes from v9
+
+1. Update the Unity package to v10. Use the `main` branch for the latest stable
+   release, or pin `v10.0.0` when you need this exact release. Use `beta` only
+   for post-v10 preview builds.
+2. Reconfigure MCP clients if the package prompts you to.
+3. Install optional dependencies only when needed. GLB import uses glTFast; FBX
+   import does not require that package.
+4. Enable `asset_gen` explicitly with `manage_tools` before calling asset
+   generation tools.
+5. Add provider keys in Unity, not in MCP client config files.
+6. Keep generated assets under review before committing them.
+
+## What is intentionally not in v10
+
+- No hosted MCP for Unity asset-generation credits.
+- No guarantee that every provider supports every input mode.
+- No automatic BlenderMCP configuration from Unity.
+- No promise that provider-generated assets are production-ready without artist
+  review.
+- No change to the rule that non-core tool groups start disabled.
+
+## Final comparison
+
+**Major-version comparison**: https://github.com/CoplayDev/unity-mcp/compare/v9.0.0...v10.0.0
+
+**v9.7.3 patch comparison**: https://github.com/CoplayDev/unity-mcp/compare/v9.7.3...v10.0.0
+
+## Troubleshooting
+
+### `asset_gen` tools do not appear
+
+The `asset_gen` group is disabled by default. Enable it with `manage_tools`:
+
+```text
+manage_tools action=activate group=asset_gen
+```
+
+If the tools still do not appear, refresh/reconnect the MCP server in the client.
+Some clients cache tool lists until the server is restarted or refreshed.
+
+### Provider key missing
+
+Generation providers are bring-your-own-key. Add keys in Unity's **Asset Gen**
+tab. Do not place provider keys in MCP client config files, prompts, project
+assets, or generated docs.
+
+### GLB import fails or has missing geometry/materials
+
+GLB/glTF import depends on **glTFast**. Install it from the Dependencies tab or
+via Package Manager before importing GLB assets. FBX imports do not require
+glTFast.
+
+### Tripo image-to-3D rejects `image_path`
+
+Tripo image-to-3D currently needs a hosted `image_url`. Local `image_path` inputs
+are supported by Meshy image-to-3D and fal/OpenRouter image-to-image, where the
+image can be sent inline as a base64 data URI.
+
+### Generated or imported files are larger than expected
+
+Provider output can include large binary assets. Review generated files before
+committing them, keep generated output under `Assets/Generated/` when possible,
+and avoid committing experimental provider output that is not needed by the
+project.
+
+### Archive import is rejected
+
+Archive extraction is intentionally constrained. Provider archives may be
+rejected when they contain unsupported extensions, traversal paths, scripts, or
+files outside the import allowlist. Import the model again with a supported
+format or inspect the archive before bringing it into the Unity project.
+
+## Related docs
+
+- Tool groups: https://coplaydev.github.io/unity-mcp/guides/tool-groups
+- Asset generation tools: https://coplaydev.github.io/unity-mcp/reference/tools/asset_gen/
+- generate_model: https://coplaydev.github.io/unity-mcp/reference/tools/asset_gen/generate_model
+- generate_image: https://coplaydev.github.io/unity-mcp/reference/tools/asset_gen/generate_image
+- import_model: https://coplaydev.github.io/unity-mcp/reference/tools/asset_gen/import_model
+- import_model_file: https://coplaydev.github.io/unity-mcp/reference/tools/asset_gen/import_model_file
+- Tool reference: https://coplaydev.github.io/unity-mcp/reference/tools/
+- Unity compatibility shims: https://coplaydev.github.io/unity-mcp/architecture/unity-compat
+- Project roadmap: https://coplaydev.github.io/unity-mcp/architecture/project-roadmap