docs: MaterialVariant и многофайловые скиллы во всей документации

Аудит после 7.10.0 и 7.11.0 нашёл девятнадцать мест, где документация врала или
молчала. Разбор по существу.

Самое важное — не человеческие доки, а текст, который читает МОДЕЛЬ.
В агентском скилле Rbx API про MaterialVariant не было ни слова, а список
создаваемых классов прямо утверждал, что любое другое имя даёт ошибку, — то есть
модели сообщалось, что MaterialVariant создать нельзя. Фича делалась ровно для
этой аудитории и оставалась ей невидима. Добавлены класс, сервис, свойство
детали и рабочий пример; обе копии текста (Resources/AgentSkills/RbxApi и
BuiltInRbxApiSkillText) правлены синхронно, побайтовое совпадение пинается
тестом.

Фраза про шесть упакованных CC0-наборов вместо тридцати шести протухла ещё в
7.9.0. В 7.10.0 я её правил и нашёл два файла из шести; остальные четыре —
ROADMAP, DOCS_INDEX, Assets/CoreAI/Docs/README и агентский текст — нашлись
только сейчас.

Changelog Unity-пакета отстал на два релиза, хотя ведётся версия в версию с
основным. Дописаны 7.10.0 и 7.11.0.

MaterialVariant добавлен в списки создаваемых классов и свойств детали
(RBX_API.md, RBX_API_SKILL.md, ROBLOX_API_ROADMAP.md), MaterialService — в
перечисления сервисов в трёх файлах, durability вариантов — в WORLD_PACKAGE.md.
По скиллам: FromFiles/FromTextParts/JoinInstructionParts в таблице API
AGENT_BUILDER.md, поле additionalInstructionAssets в SCRIPTABLE_OBJECTS.md.

Пункт бэклога про многофайловые скиллы переформулирован: сама многофайловость
сделана, в остатке только структурное чтение по секциям — заголовок обещал
работу, которой больше нет.

Проверено отдельно и подтвердилось как чистое: нигде не написано, что материалы
нельзя менять в рантайме, и нигде не утверждается, что скилл обязан быть
прочитан до вызова его тулов.

EditMode 3365 тестов, 3356 passed, 0 failed.

Author: NeoXider

Assets/CoreAI/Docs/AGENT_BUILDER.md

@@ -225,7 +225,10 @@ so the conversation stays clean. Returns `false` for a null store/skill or a bla
 | `ToolNames` | `string[]` of tool names |
 | `MergeToolNames(params SkillSet[])` | Merge names from multiple skills |
 | `FromFile(name, desc, path, tools)` | Create from file |
+| `FromFiles(name, desc, paths, tools)` | Create from several files, joined under `## name` headings |
 | `FromTextContent(name, desc, text, tools)` | Create from text |
+| `FromTextParts(name, desc, namedParts, tools)` | Create from several named parts, joined under `## name` headings |
+| `JoinInstructionParts(namedParts)` | Join named parts under `## name` headings |
 | `IJsonInvocableLlmTool` | Optional direct JSON invocation contract for skill proxy tools |
 
 ### Best practices — when to use skills vs direct tools

Assets/CoreAI/Docs/RBX_API.md

@@ -37,7 +37,7 @@ nil value".
 
 ## Classes
 
-`Instance.new` accepts: **`Part`**, **`Folder`**, **`Model`**, **`ClickDetector`**,
+`Instance.new` accepts: **`Part`**, **`Folder`**, **`Model`**, **`ClickDetector`**, **`MaterialVariant`**,
 **`RemoteEvent`**, **`UnreliableRemoteEvent`**, and **`RemoteFunction`**. `Camera` is not
 creatable — the world's one camera is `workspace.CurrentCamera`.
 The class ancestry (`BasePart`, `PVInstance`, `WorldRoot`, …) is data-driven through `ClassCatalog`,
@@ -46,11 +46,11 @@ so `IsA` works the way it does in Roblox.
 Services reachable via `game:GetService`: `RunService`, `UserInputService`, `Players`,
 `CollectionService`, `TweenService`, `SoundService`, `Lighting`, `Debris`, `HttpService`,
 `ReplicatedStorage`, `ServerStorage`, `ServerScriptService`, `ContextActionService`,
-`PathfindingService`, `MarketplaceService`, `DataStoreService`, and CoreAI's own `AIService`.
+`PathfindingService`, `MarketplaceService`, `DataStoreService`, `MaterialService`, and CoreAI's own `AIService`.
 
 ### Part properties
 
-`Name`, `Parent`, `Position`, `CFrame`, `Size`, `Color`, `Material`, `Orientation`, `Rotation`,
+`Name`, `Parent`, `Position`, `CFrame`, `Size`, `Color`, `Material`, `MaterialVariant` (string, `""` for none), `Orientation`, `Rotation`,
 `Anchored`, `Transparency`, `CanCollide`, and `Shape` (`Ball`, `Block`, `Cylinder`, `Wedge`,
 `CornerWedge` — each one materializes its own mesh). A `Part` materializes as a real GameObject as
 soon as its `Parent` is set into the world.

Assets/CoreAI/Docs/README.md

@@ -32,7 +32,7 @@ Russian files are kept only when the filename is explicitly marked `_RU`.
 | [LESSON_ORCHESTRATION.md](LESSON_ORCHESTRATION.md) | Lesson/practice hooks: runtime context, tool policy, tests |
 | [LLM_ROUTING.md](LLM_ROUTING.md) | Execution modes, portable routing contracts, usage sinks, timeouts |
 | [LUA_SANDBOX_SECURITY.md](LUA_SANDBOX_SECURITY.md) | Lua sandbox boundary, removed APIs, execution limits, binding rules, and escape-test checklist |
-| [RBX_API.md](RBX_API.md) | Roblox-style API a mod builds with: `Instance.new`, datatypes, services, `BasePart.Material` / `Part.Color`, saving and loading a world, samples |
+| [RBX_API.md](RBX_API.md) | Roblox-style API a mod builds with: `Instance.new`, datatypes, services, `BasePart.Material` / `MaterialVariant` / `Part.Color`, saving and loading a world, samples |
 | [LUA_GAME_API.md](LUA_GAME_API.md) | Game Lua API reference: capabilities, mods, world, Full, LLM tools |
 | [LUA_BEST_PRACTICES.md](LUA_BEST_PRACTICES.md) | Best practices and anti-patterns for Lua in games |
 | [LUA_NATIVE_APIS.md](LUA_NATIVE_APIS.md) | Lua native APIs vs CoreAI wrappers |
@@ -48,7 +48,7 @@ Russian files are kept only when the filename is explicitly marked `_RU`.
 |------|--------|
 | [Docs/CoreAIMods/WORLD_PACKAGE.md](../../../Docs/CoreAIMods/WORLD_PACKAGE.md) | The `.world` package format, validation limits, manual slots vs. the autosave ring, the confirm/reject load flow, runtime session replacement |
 | [PROCEDURAL_MATERIALS.md](../../CoreAIMods/Runtime/RbxApi/Unity/PROCEDURAL_MATERIALS.md) | Procedural shader catalog behind `Enum.Material` (all 45 items + the magenta diagnostic fallback) |
-| [TEXTURE_MATERIALS.md](../../CoreAIMods/Runtime/RbxApi/Unity/TEXTURE_MATERIALS.md) | The six CC0 texture-backed materials and their projection/tint rules |
+| [TEXTURE_MATERIALS.md](../../CoreAIMods/Runtime/RbxApi/Unity/TEXTURE_MATERIALS.md) | The thirty-six CC0 texture-backed materials and their projection/tint rules |
 
 ## Maintenance Notes
 

Assets/CoreAI/Runtime/Core/Features/AgentPrompts/BuiltInRbxApiSkillText.cs

@@ -94,7 +94,8 @@ by identity (`==`). Names AND numeric values are the real Roblox ones (e.g. KeyC
 ## 4. Instances
 
 - `Instance.new(""Class""[, parent])` — creatable classes are ""Part"", ""Folder"", ""Model"",
-  ""ClickDetector"", ""RemoteEvent"", ""UnreliableRemoteEvent"", ""RemoteFunction"". Any other name
+  ""ClickDetector"", ""RemoteEvent"", ""UnreliableRemoteEvent"", ""RemoteFunction"",
+  ""MaterialVariant"". Any other name
   errors (a Camera is not creatable — reach the world camera through `workspace.CurrentCamera`).
   The parent argument is deprecated (logs once); set `.Parent` after configuring instead.
 - `RemoteEvent`/`UnreliableRemoteEvent` fire one-way. `RemoteFunction:InvokeServer/InvokeClient`
@@ -107,7 +108,7 @@ MouseClick fires (no args) when the user clicks THAT part with the mouse and it
   `cd.MaxActivationDistance` studs (default 32). Only the part under the cursor fires.
 - `game:GetService(""Name"")` — the standard runtime has live tree-backed `Workspace`, `Lighting`,
   `ReplicatedStorage`, `ServerStorage`, `ServerScriptService`, `StarterPlayer`, `Players`,
-  `HttpService`, `UserInputService`, and `RunService` services.
+  `HttpService`, `UserInputService`, `RunService`, and `MaterialService` services.
 - The catalog's 13 registrations are: `HttpService` and `Players` (tree-backed), `RunService`
   (MVP2; fallback), `UserInputService` (MVP10; fallback), `TweenService` (MVP8),
   `CollectionService` (MVP8), `Debris` (MVP8), `DataStoreService` (MVP9),
@@ -145,14 +146,26 @@ needs WorldEdit.
 
 Read+write (writes need WorldEdit): `Position`, `Size`, `CFrame` (Vector3/Vector3/CFrame),
 `Color` (Color3), `Transparency` (0..1), `Anchored` (bool), `CanCollide` (bool),
-`Shape` (Enum.PartType), `Material` (Enum.Material), `Orientation` and `Rotation` (Vector3 of
+`Shape` (Enum.PartType), `Material` (Enum.Material), `MaterialVariant` (string, """" for none),
+`Orientation` and `Rotation` (Vector3 of
 degrees; Orientation is YXZ, Rotation is XYZ).
 Setting `Position` keeps the part's rotation; setting `CFrame` sets position AND rotation;
 setting `Orientation` or `Rotation` sets the rotation and keeps the position.
 `Shape` accepts `Enum.PartType.Ball`, `.Block`, `.Cylinder`, `.Wedge`, `.CornerWedge` — every
 one of them materializes its real mesh.
-`Material` accepts any of the 45 `Enum.Material` items and all 45 render. Brick, Wood,
-WoodPlanks, Grass, Cobblestone and Metal use textured PBR surfaces; the rest are procedural.
+`Material` accepts any of the 45 `Enum.Material` items and all 45 render. Thirty-six of them
+use textured PBR surfaces shipped inside the package; the rest are procedural.
+`MaterialVariant` is how you use YOUR OWN textures instead of the built-in ones: create a
+`MaterialVariant` under `MaterialService`, point it at your texture paths, then name it on a part.
+  local mv = Instance.new(""MaterialVariant"")
+  mv.Name = ""MossyBrick""; mv.BaseMaterial = Enum.Material.Brick
+  mv.ColorMap = ""MyGame/Textures/mossy_color""   -- a Resources path in your project
+  mv.NormalMap = ""MyGame/Textures/mossy_normal""; mv.StudsPerTile = 8
+  mv.Parent = game:GetService(""MaterialService"")
+  wall.MaterialVariant = ""MossyBrick""    -- swap on; wall.MaterialVariant = """" swaps back
+A map you leave empty is inherited from `BaseMaterial`, so recolouring a surface is three lines.
+Editing a live variant repaints every part already wearing it. Naming a variant that does not
+exist renders the plain `Material` — that is not an error.
 A material id outside the enum resolves to a magenta diagnostic material instead of failing
 quietly, so a wrong value is visible at once.
 `Color` is an independent Roblox-style tint. A part whose `Color` was never assigned shows the

Assets/CoreAiUnity/CHANGELOG.md

@@ -4,6 +4,39 @@ Unity host: **CoreAI.Source** build, EditMode / PlayMode tests, Editor menus, do
 
 ## [Unreleased]
 
+## [7.11.0] - 2026-09-04
+
+### Fixed
+
+- **Замена списка тулов роли молча отключала все её скиллы.** `SetToolsForRole` возвращал
+  `read_skill` и `call_skill_tool` только из зарегистрированного живого каталога, а он появляется
+  лишь при включённом авторстве скиллов — у агента, собранного обычным `WithSkill(...)`, оба прокси
+  исчезали, и ни один тул скилла больше не вызывался. Ничего при этом не падало: пропавший тул
+  возвращается обычным результатом, а не исключением, поэтому модель читала «not found», извинялась
+  прозой и шла дальше.
+
+### Added
+
+- **`SkillSetAsset` принимает несколько файлов инструкций.** В инспекторе появился список
+  дополнительных `TextAsset`: они идут за основным в порядке списка, каждый под заголовком
+  `## имя-файла`. Скилл из одного файла сохраняет текст без изменений и заголовка не получает.
+- Тесты `SkillSetAssetInstructionsEditModeTests` и `SkillToolAvailabilityEditModeTests`: тул скилла
+  вызывается без предварительного `read_skill`, а каталог в системном промпте не несёт тела
+  инструкций.
+- **Агентский текст `Resources/AgentSkills/RbxApi` дополнен `MaterialVariant`** и приведён к правде
+  по числу упакованных текстурных наборов — тридцать шесть, а не шесть.
+
+## [7.10.0] - 2026-09-04
+
+### Added
+
+- **`MaterialVariant`: игра заводит свои материалы и меняет их на лету.** Экземпляр в
+  `MaterialService` с `BaseMaterial`, четырьмя картами и `StudsPerTile`; деталь выбирает его строкой
+  `BasePart.MaterialVariant`. Пути карт — обычные `Resources`-пути проекта. Варианты и ссылки на них
+  переживают сохранение мира.
+- **Живой рендер-пруф в Play Mode.** `RbxMaterialVariantRenderPlayModeTests` фотографирует три слэба
+  и требует, чтобы деталь с вариантом ушла от кирпича и встала рядом с травой.
+
 ## [7.9.0] - 2026-09-04
 
 ### Added

Assets/CoreAiUnity/Docs/BACKLOG.md

@@ -46,15 +46,16 @@ Items here are intentionally not active TODO checkboxes.
 
 ## Skill System (before MVP2)
 
-- **Multi-file skills the model can browse structurally.** Today one `SkillSet` = one `Instructions`
-  string, and `read_skill(name)` returns the whole blob. Add a third disclosure level like Claude Code
-  (a main doc + `references/*` read lazily): a skill assembled from several files/sections, the model
-  SEES the whole structure (index/table of contents) up front, and READS only the file/section it needs
-  on demand (e.g. `read_skill_section(name, section)` or a sub-doc index). Lets big references (the Rbx
-  API skill is already large) load in pieces instead of one dump.
+- **Structural browsing of a multi-file skill.** The assembly half shipped in 7.11.0: a `SkillSet` can
+  take its `Instructions` from several sources via `FromFiles`/`FromTextParts`, joined under
+  `## name` headings. What is still missing is the third disclosure level, as in Claude Code (a main
+  doc plus `references/*` read lazily): the model SEES the structure — an index or table of contents —
+  up front, and READS only the section it needs, e.g. `read_skill_section(name, section)`. Today
+  `read_skill(name)` still returns the whole assembled document, so a large reference (the Rbx API
+  skill is already large) arrives as one dump.
 - **Skill self-improvement.** A mechanism for a skill to update/augment its own instructions from
   experience (learned corrections, new patterns the agent discovered at runtime). Design after the
-  multi-file work; both land before MVP2.
+  structural-browsing work; both land before MVP2.
 
 ## UX / Mobile
 

Assets/CoreAiUnity/Docs/DOCS_INDEX.md

@@ -79,7 +79,7 @@ Package manifests:
 | [FIRST_MOD](../../CoreAI/Docs/FIRST_MOD.md) | Your first Lua mod in 5 minutes: load via agent/C#/TextAsset, persistence, sharing. |
 | [RBX_API](../../CoreAI/Docs/RBX_API.md) | The Roblox-style API a mod builds with: `Instance.new`, datatypes, services, `BasePart.Material` / `Part.Color`, saving and loading a world, bundled samples. |
 | [WORLD_PACKAGE](../../../Docs/CoreAIMods/WORLD_PACKAGE.md) | The `.world` package format, validation limits, manual slots vs. the autosave ring, the confirm/reject load flow, and runtime session replacement. |
-| [PROCEDURAL_MATERIALS](../../CoreAIMods/Runtime/RbxApi/Unity/PROCEDURAL_MATERIALS.md) · [TEXTURE_MATERIALS](../../CoreAIMods/Runtime/RbxApi/Unity/TEXTURE_MATERIALS.md) | The `Enum.Material` render catalogs: all 45 items render; a catalog-driven texture provider (six packaged CC0 sets, any item overridable from a project-local 2K–4K catalog via the Editor menus) plus procedural surfaces and the magenta diagnostic fallback. |
+| [PROCEDURAL_MATERIALS](../../CoreAIMods/Runtime/RbxApi/Unity/PROCEDURAL_MATERIALS.md) · [TEXTURE_MATERIALS](../../CoreAIMods/Runtime/RbxApi/Unity/TEXTURE_MATERIALS.md) | The `Enum.Material` render catalogs: all 45 items render; a catalog-driven texture provider (thirty-six packaged CC0 sets, any item overridable from a project-local 2K–4K catalog via the Editor menus) plus procedural surfaces and the magenta diagnostic fallback. |
 | [LUA_GAME_API](../../CoreAI/Docs/LUA_GAME_API.md) | Capabilities, mods, world API, Full tier, `execute_lua` / `manage_mods`, persistence & sharing. |
 | [LUA_BEST_PRACTICES](../../CoreAI/Docs/LUA_BEST_PRACTICES.md) | Do's and don'ts: slots, extensions, Lua-CSharp, LLM context. |
 | [LUA_NATIVE_APIS](../../CoreAI/Docs/LUA_NATIVE_APIS.md) | Native Lua-CSharp vs custom CoreAI code. |

Assets/CoreAiUnity/Docs/SCRIPTABLE_OBJECTS.md

@@ -22,7 +22,7 @@ CoreAI uses **Options + ScriptableObject wrapper** for Unity-authored settings.
 | `AiPermissionsAsset` | CoreAiUnity | `IAiPermissions`, `AiPermissionsOptions`, `ToOptions()`, `ApplyOptions(...)` | Dashboard/runtime code can use the interface/options. |
 | `LlmRoutingManifest` | CoreAiUnity | `LlmRouteTable`, `ToRouteTable()`, `ToOptions()` | Manifest stays Unity authoring storage. Runtime routing uses the portable route table. Backend construction may still use Unity profile entries in composition. |
 | `AgentPromptsManifest` | CoreAiUnity | `AgentPromptsDefinition`, `ToDefinition()` | Reads `TextAsset.text` into plain strings. Prompt providers consume the snapshot. |
-| `SkillSetAsset` | CoreAiUnity | `SkillSetDefinition`, `ToSkillDefinition()`, `ApplyDefinition(...)` | `TextAsset`/inline instructions become a portable skill definition; tools are supplied by code. `ApplyDefinition(...)` lets editor/bootstrap code create or update skill assets without private-field reflection. |
+| `SkillSetAsset` | CoreAiUnity | `SkillSetDefinition`, `ToSkillDefinition()`, `ApplyDefinition(...)` | `TextAsset`/inline instructions become a portable skill definition; tools are supplied by code. Extra instruction files in `additionalInstructionAssets` are joined in order under `## filename` headings. `ApplyDefinition(...)` lets editor/bootstrap code create or update skill assets without private-field reflection. |
 | `CoreAiPrefabRegistryAsset` | CoreAiUnity | `ICoreAiPrefabRegistry` | Not portable because it stores `GameObject` prefab references. Consumers depend on the Unity-side interface. |
 
 ## How to use from runtime code

Assets/CoreAiUnity/Resources/AgentSkills/RbxApi.txt

@@ -70,7 +70,8 @@ buttons live at 1000+).
 ## 4. Instances
 
 - `Instance.new("Class"[, parent])` — creatable classes are "Part", "Folder", "Model",
-  "ClickDetector", "RemoteEvent", "UnreliableRemoteEvent", "RemoteFunction". Any other name
+  "ClickDetector", "RemoteEvent", "UnreliableRemoteEvent", "RemoteFunction",
+  "MaterialVariant". Any other name
   errors (a Camera is not creatable — reach the world camera through `workspace.CurrentCamera`).
   The parent argument is deprecated (logs once); set `.Parent` after configuring instead.
 - `RemoteEvent`/`UnreliableRemoteEvent` fire one-way. `RemoteFunction:InvokeServer/InvokeClient`
@@ -83,7 +84,7 @@ buttons live at 1000+).
   `cd.MaxActivationDistance` studs (default 32). Only the part under the cursor fires.
 - `game:GetService("Name")` — the standard runtime has live tree-backed `Workspace`, `Lighting`,
   `ReplicatedStorage`, `ServerStorage`, `ServerScriptService`, `StarterPlayer`, `Players`,
-  `HttpService`, `UserInputService`, and `RunService` services.
+  `HttpService`, `UserInputService`, `RunService`, and `MaterialService` services.
 - The catalog's 13 registrations are: `HttpService` and `Players` (tree-backed), `RunService`
   (MVP2; fallback), `UserInputService` (MVP10; fallback), `TweenService` (MVP8),
   `CollectionService` (MVP8), `Debris` (MVP8), `DataStoreService` (MVP9),
@@ -121,14 +122,26 @@ Pivot/property writes need WorldEdit. BaseParts also support `GetPivot()` and `P
 
 Read+write (writes need WorldEdit): `Position`, `Size`, `CFrame` (Vector3/Vector3/CFrame),
 `Color` (Color3), `Transparency` (0..1), `Anchored` (bool), `CanCollide` (bool),
-`Shape` (Enum.PartType), `Material` (Enum.Material), `Orientation` and `Rotation` (Vector3 of
+`Shape` (Enum.PartType), `Material` (Enum.Material), `MaterialVariant` (string, "" for none),
+`Orientation` and `Rotation` (Vector3 of
 degrees; Orientation is YXZ, Rotation is XYZ).
 Setting `Position` keeps the part's rotation; setting `CFrame` sets position AND rotation;
 setting `Orientation` or `Rotation` sets the rotation and keeps the position.
 `Shape` accepts `Enum.PartType.Ball`, `.Block`, `.Cylinder`, `.Wedge`, `.CornerWedge` — every
 one of them materializes its real mesh.
-`Material` accepts any of the 45 `Enum.Material` items and all 45 render. Brick, Wood,
-WoodPlanks, Grass, Cobblestone and Metal use textured PBR surfaces; the rest are procedural.
+`Material` accepts any of the 45 `Enum.Material` items and all 45 render. Thirty-six of them
+use textured PBR surfaces shipped inside the package; the rest are procedural.
+`MaterialVariant` is how you use YOUR OWN textures instead of the built-in ones: create a
+`MaterialVariant` under `MaterialService`, point it at your texture paths, then name it on a part.
+  local mv = Instance.new("MaterialVariant")
+  mv.Name = "MossyBrick"; mv.BaseMaterial = Enum.Material.Brick
+  mv.ColorMap = "MyGame/Textures/mossy_color"   -- a Resources path in your project
+  mv.NormalMap = "MyGame/Textures/mossy_normal"; mv.StudsPerTile = 8
+  mv.Parent = game:GetService("MaterialService")
+  wall.MaterialVariant = "MossyBrick"    -- swap on; wall.MaterialVariant = "" swaps back
+A map you leave empty is inherited from `BaseMaterial`, so recolouring a surface is three lines.
+Editing a live variant repaints every part already wearing it. Naming a variant that does not
+exist renders the plain `Material` — that is not an error.
 A material id outside the enum resolves to a magenta diagnostic material instead of failing
 quietly, so a wrong value is visible at once.
 `Color` is an independent Roblox-style tint. A part whose `Color` was never assigned shows the