Document AI scene explorer folders and object subtree tools

docs/AGENT_INTEGRATION.md

@@ -7,6 +7,8 @@ generated programming workspace still belong to the game project.
 
 ## Topics
 
+- [Organize the scene explorer](/docs/guides/ai-agents/organize-scene-explorer)
+
 - [Author scenes, models and playtests](/docs/guides/ai-agents/author-scenes-models-and-playtest)
 
 - [Connect an agent](/docs/guides/ai-agents/connect-an-agent)

docs/AGENT_INTEGRATION/author-scenes-models-and-playtest.md

@@ -51,7 +51,7 @@ Stop play and resolve any runtime-change review before editing or switching.
 Call `editor_status` again after switching to get that scene's object IDs.
 `scene_summary` reads the saved file; `editor_status` reads the live document.
 
-`object_create` accepts `name` and `kind`: `empty`, `camera`, `light`, or `blockout`.
+`object_create` accepts `name` and `kind`: `folder`, `empty`, `camera`, `light`, or `blockout`, with optional `parent`.
 Use its returned `entity_id` with `object_update`, for example:
 
 ```json
@@ -75,6 +75,15 @@ whole component value. Read their exact JSON structure from `editor_status`.
 A null camera/light removes it. Invalid batches fail without partial object edits.
 `editor_undo` and `editor_redo` handle object edits. Save with `scene_save`.
 
+## Organize folders and object subtrees
+
+Read `scene_explorer_guide` for the bundled hierarchy organization skill.
+`object_create` with `kind:"folder"` creates actual scene explorer folders;
+`object_duplicate` copies an object/folder and all descendants with fresh IDs;
+`object_delete` removes the selected subtree with undo. Use `object_update` to
+rename or reparent. See [Organize the scene explorer](/docs/guides/ai-agents/organize-scene-explorer)
+for copyable examples, parent/transform behavior, recursive deletion and saving.
+
 ## Model, preview, then place
 
 Agents should prefer Blender when installed, exporting a supported model such as

docs/AGENT_INTEGRATION/organize-scene-explorer.md

@@ -0,0 +1,128 @@
+# Organize the scene explorer with AI
+
+[Back to AI agents & app data](/docs/guides/ai-agents).
+
+The bundled `rustic-scene-explorer` skill teaches agents how to organize the
+scene explorer (Hierarchy panel), create folders and add, duplicate or delete
+objects. These operations work directly through the plugin and the editor's undo
+system. They do not require clicking the explorer through computer use.
+
+## Setup and inspect
+
+Open the game in the writable Rustic editor, reload the updated `rustic-workspace`
+MCP connection and select the game with `workspace_info`. Call
+`scene_explorer_guide` with `{}` to read the current skill, including on upgrades
+that preserve customized agent instructions. The skill is also installed in
+Rustic app data for Codex, Claude and the Codex plugin. Existing customized skill
+files are preserved.
+
+Call `editor_status` with `{}` before changing the hierarchy. Each object has an
+`entity_id`, `name`, `parent` (an object UUID or null) and `folder` flag. Use these
+UUIDs to distinguish similarly named objects. `scene_summary` also reports folder
+flags for saved files; use live status for unsaved edits.
+
+A scene folder is an organizational entity in the active scene, not a directory
+on disk. File tools cannot create explorer folders by making asset directories.
+This guide concerns scene hierarchy layout; editor dock/tab placement is a
+separate preference.
+
+## Lay out useful groups
+
+Use a small, shallow structure that matches the game. For example, World might
+contain Buildings and Vegetation, while Gameplay holds actors, triggers and spawn
+points, with Lighting and UI as other top-level groups. Reuse existing naming
+conventions and avoid creating empty groups without a purpose.
+
+Folders do not contribute translation, rotation or scale to their descendants.
+Changing a folder's transform does not move its contents. Use an ordinary empty
+root object for an assembly that should move as a group.
+
+Reparenting retains the child's **local** transform. Changing its non-folder
+ancestors can change world placement: a folder adds no transform of its own, but
+still inherits from any ordinary object above it. Inspect the ancestor chain and
+calculate the intended local transform when needed. Folder membership does not
+change script lifetime or make its children global.
+
+## Create folders and objects
+
+Pass the following to `object_create`:
+
+```json
+{"name":"World","kind":"folder"}
+```
+
+The returned `entity_id` is the new folder UUID. Create a nested folder with that
+UUID as `parent`:
+
+```json
+{"name":"Buildings","kind":"folder","parent":"<World UUID>"}
+```
+
+The supported kinds are `folder`, `empty`, `camera`, `light` and `blockout`.
+Omit `parent` or pass null to create at scene root. Use `model_create` for finished
+visible mesh assets, then parent the returned model object with `object_update`:
+
+```json
+{"entity_id":"<model UUID>","properties":{"parent":"<Buildings UUID>"}}
+```
+
+Rename a folder or object through `object_update` with `properties.name`.
+Use `properties.parent:null` to move it back to scene root. Missing parents,
+invalid IDs and cycles are rejected without partially changing the hierarchy.
+
+## Duplicate an object or a folder subtree
+
+Call `object_duplicate`, for example:
+
+```json
+{"entity_id":"<Buildings UUID>","name":"Buildings copy"}
+```
+
+The entire subtree is copied with fresh object UUIDs and preserved internal
+parent links, folder flags, local transforms and components. The source is
+unchanged. By default the new root is a sibling under the original parent.
+Supply `parent` to choose another destination, or `parent:null` for scene root.
+`name` optionally renames only the copied root.
+
+The response contains the copied root `entity_id`, all new `entity_ids`, the
+`source_entity_id` and `saved:false`. Use the **new** IDs to edit the copy. The copy
+initially overlaps the original when using the same parent and transforms; move
+it through `object_update` if that is not intended. A different parent can change
+world placement because local transforms are retained.
+
+Mesh/material asset IDs and script source IDs stay shared. Script attachments
+and their properties are copied, but arbitrary entity references inside script
+properties are not automatically rewritten to the new objects. Inspect those
+references when making the copy independent.
+
+## Delete and recover
+
+Inspect the target's descendants using `editor_status`, then call
+`object_delete`:
+
+```json
+{"entity_id":"<obsolete object or folder UUID>"}
+```
+
+Deleting a folder or object removes **every descendant**, as one undoable edit.
+To keep children, move them to a surviving parent first. The response lists
+`deleted_entity_ids` and `saved:false`. Asset files, script source files, global
+scripts and scene startup lists are not deleted.
+
+`editor_undo` restores the deleted subtree with its IDs and parent links;
+`editor_redo` deletes it again. Creation, duplication and reparenting also support
+scene undo/redo. A duplicate operation is one undo step, including its optional
+root name and parent.
+
+## Verify and save
+
+Re-read `editor_status` after changes to verify folder flags, parents and copied
+IDs. Inspect the scene with `viewport_capture` to catch unintended placement
+changes. Call `scene_save` to persist the hierarchy; these tools initially edit
+the unsaved active scene. Refresh IDs after switching scenes.
+
+Stop play and resolve pending runtime-change review before editing. Read-only
+editors cannot mutate the scene. If a tool is missing, update/reopen Rustic and
+reload its MCP connection. If an operation fails, inspect status and correct the
+ID or parent; do not modify a stale saved scene behind unsaved editor work or
+claim a hierarchy change succeeded.

lib/docs-catalog.ts

@@ -107,6 +107,7 @@ const categoryGroups: DocGroup[] = [
     { slug: "guides/ai-agents/connect-an-agent", title: "Connect an agent", description: "Connect an agent for AI agents & app data.", source: "docs/AGENT_INTEGRATION/connect-an-agent.md", parent: "guides/ai-agents" },
     { slug: "guides/ai-agents/read-and-edit-agent-information", title: "Read and edit agent information", description: "Read and edit agent information for AI agents & app data.", source: "docs/AGENT_INTEGRATION/read-and-edit-agent-information.md", parent: "guides/ai-agents" },
     { slug: "guides/ai-agents/storage-and-migration", title: "Storage and migration", description: "Storage and migration for AI agents & app data.", source: "docs/AGENT_INTEGRATION/storage-and-migration.md", parent: "guides/ai-agents" },
+    { slug: "guides/ai-agents/organize-scene-explorer", title: "Organize the scene explorer", description: "Use AI tools to create folders, organize hierarchy parents and duplicate or delete object subtrees with undo.", source: "docs/AGENT_INTEGRATION/organize-scene-explorer.md", parent: "guides/ai-agents" },
     { slug: "guides/ai-agents/author-scenes-models-and-playtest", title: "Author scenes, models and playtests", description: "Use direct editor tools for modeling, scene authoring, script scopes and keyboard playtesting.", source: "docs/AGENT_INTEGRATION/author-scenes-models-and-playtest.md", parent: "guides/ai-agents" },
     { slug: "guides/ai-agents/limits-and-troubleshooting", title: "Limits and troubleshooting", description: "Limits and troubleshooting for AI agents & app data.", source: "docs/AGENT_INTEGRATION/limits-and-troubleshooting.md", parent: "guides/ai-agents" },
     { slug: "guides/gameplay-programming", title: "Gameplay programming", description: "Choose a focused guide to gameplay programming.", source: "docs/GAMEPLAY_PROGRAMMING.md" },