Add comprehensive guides for Sendama editor usage

README.md

@@ -15,6 +15,8 @@ Sendama CLI is a console application that provides a command line interface for
 
 For the current editor manual, see [Editor.md](docs/Editor.md).
 
+For the modular guide set, see [docs/guides/README.md](docs/guides/README.md).
+
 ## Requirements
 
 - PHP 8.3 or newer

docs/Editor.md

@@ -4,6 +4,8 @@ This document is a living guide to the Sendama editor.
 
 It is meant to track the editor as it exists today, including current hotkeys, panel workflows, and known behavior. Update this file whenever the editor gains new tools, panels, controls, or shortcuts.
 
+For the task-oriented guide set, start with [docs/guides/README.md](guides/README.md).
+
 ## Starting the Editor
 
 Open the editor from inside a Sendama project:
@@ -21,15 +23,21 @@ sendama edit --directory /path/to/project
 The editor expects a valid Sendama project workspace. In particular:
 
 - editor settings and project settings must be present
-- the project should contain an `Assets` folder
+- the project should contain an `Assets` folder, or a legacy lowercase `assets` folder
 - the active scene is loaded from the configured scene metadata
 
+When the editor opens a project, it also runs a startup sanity check.
+If it finds missing structure such as `config/input.php`, `configuration.json`, log files, or required asset directories, it opens a normalize prompt:
+
+- `Normalize`: create the missing directories and bootstrap files
+- `Cancel` or `Escape`: continue without changing the project
+
 ## Layout Overview
 
 The editor currently uses five main panels:
 
 - `Hierarchy`: scene tree and scene object management
-- `Assets`: project browser rooted at the project's `Assets` folder
+- `Assets`: project browser rooted at the active asset root, preferring `Assets` but compatible with legacy `assets`
 - `Main`: workspace area with `Scene`, `Game`, and `Sprite` tabs
 - `Console`: project log view
 - `Inspector`: object and asset details, plus property editing
@@ -48,7 +56,12 @@ These shortcuts work regardless of the currently focused panel unless a modal is
 | `Shift+5` | Toggle play mode globally |
 | `Ctrl+C` | Close the editor gracefully |
 | `Ctrl+S` | Save the loaded scene |
-| `Shift+A` | Open the Hierarchy add workflow, or create a Sprite asset when the Sprite tab is focused |
+
+`Shift+A` is panel-local:
+
+- in `Hierarchy`, it opens the add-object workflow
+- in `Assets`, it opens the create-asset workflow
+- in `Inspector`, it opens the add-component menu when a hierarchy object is loaded
 
 ## Panel List Modal
 
@@ -89,7 +102,7 @@ Current scene rendering behavior:
 - texture paths are resolved relative to the editor's configured project directory
 - scene coordinates are rendered into a scrollable viewport
 - UI text objects render their `text`
-- objects without a visible representation are not currently drawn in the scene tab
+- selected objects without a visible representation render as a muted `x`
 - the main panel help line shows the current scene controls on the left and the active mode on the right
 
 When the main panel has focus and the `Scene` tab is active, it uses scene-view modes.
@@ -173,19 +186,11 @@ Controls:
 - `Shift+2`: open the character selector modal for special characters
 - `Space`: place a blank character
 - `Backspace`: erase the current cell
-- `Shift+A`: open the create-asset modal
 - `Ctrl+Z`: undo the last grid change
 - `Ctrl+Y`: redo the last undone grid change
 - `Shift+R`: reset the loaded asset back to the state it had when it was opened
 - `Delete`: open the delete-asset confirmation modal
 
-Create workflow:
-
-- `Shift+A` opens a modal with `Texture`, `Tile Map`, and `Cancel`
-- choosing `Texture` creates a new `.texture` file in `Assets/Textures`
-- choosing `Tile Map` creates a new `.tmap` file in `Assets/Maps`
-- the new asset is loaded into the sprite editor immediately
-
 Delete workflow:
 
 - `Delete` opens a confirmation modal for the currently loaded asset
@@ -267,6 +272,7 @@ Controls:
 - `Right`: expand a folder, or move into it
 - `Left`: collapse a folder, or move to its parent
 - `Enter`: load the selected asset into the Inspector
+- `Shift+A`: open the asset create workflow
 - `Delete`: open the delete confirmation dialog
 
 Inspector type mapping:
@@ -288,6 +294,25 @@ Controls:
 - `Enter`: confirm the selection
 - `Escape`: cancel
 
+### Asset Create Workflow
+
+Press `Shift+A` while the Assets panel has focus to open the create modal.
+
+Current create targets:
+
+- `Script`
+- `Scene`
+- `Texture`
+- `Tile Map`
+- `Event`
+
+Behavior:
+
+- selecting an asset type runs the corresponding Sendama generator command in the opened project directory
+- the editor creates the asset with the next available default name for that asset family
+- after creation, the Assets tree refreshes, the new asset is selected, and the Inspector loads it
+- if the created asset is a texture or tile map, the Sprite tab loads it too
+
 ## Inspector Panel
 
 The Inspector shows details for the currently inspected target.
@@ -304,14 +329,20 @@ For file assets, the Inspector currently shows:
 - editable `Name`
 - read-only `Path`
 
-Renaming a texture or tile map from the Inspector renames the file on disk and updates known scene references in memory, such as `sprite.texture.path` and `environmentTileMapPath`.
+Renaming a file asset from the Inspector renames the file on disk. If the current scene references that file through `sprite.texture.path` or `environmentTileMapPath`, those scene references are updated in memory and should be saved with `Ctrl+S`.
+If the renamed asset is a PHP script under `Assets/Scripts`, the editor also rewrites the class declaration inside the source file to match the new filename.
 
 ### Inspector Hotkeys
 
 When the Inspector has focus:
 
 - `Tab`: move to the next control
 - `Shift+Tab`: move to the previous control
+- `Shift+A`: open the add-component menu for the currently inspected hierarchy object
+- `Shift+W`: enter or leave component move mode when a component header is selected
+- `Delete`: open the remove-component confirmation modal when a component header is selected
+
+The Inspector help line updates dynamically to show the active controls on the left and the current mode on the right.
 
 The Inspector uses a small state machine.
 
@@ -325,6 +356,9 @@ Controls:
 
 - `Up` / `Down`: move between controls
 - `Enter`: activate the selected control
+- `Shift+A`: open the add-component menu when a hierarchy object is being inspected
+- `Shift+W`: toggle component move mode when a component header is focused
+- `Delete`: open the remove-component confirmation modal when a component header is focused
 - `/`: toggle the focused collapsible section, such as `Transform`, `Renderer`, or a component block
 
 #### 2. Property Selection
@@ -385,6 +419,47 @@ For hierarchy objects, the Inspector currently renders:
 
 Component headers are visually marked as collapsible sections.
 
+### Add Component Workflow
+
+When the Inspector is focused on a hierarchy object other than the scene root, press `Shift+A` to open `Add Component`.
+
+Current component candidates come from:
+
+- built-in engine component defaults
+- PHP classes discovered under `Assets/Scripts`
+- component classes already present in the loaded scene
+
+Behavior:
+
+- selecting a component appends it to the object's `components` list
+- if the editor can discover serializable default data for that component, it adds that data immediately
+- the new component section appears in the Inspector right away
+
+### Component Remove Workflow
+
+When a component header is focused, press `Delete` to open the remove confirmation modal.
+
+Behavior:
+
+- the modal asks whether to remove the selected component from the current object
+- `Delete`: confirm removal
+- `Cancel` or `Escape`: abort removal
+- confirming removes that component from the object's `components` list immediately
+
+### Component Reorder Workflow
+
+When a component header is focused, press `Shift+W` to enter component move mode.
+
+Behavior:
+
+- `Up`: move the selected component one slot earlier, wrapping to the end from the first slot
+- `Down`: move the selected component one slot later, wrapping to the start from the last slot
+- `Escape`: leave move mode
+
+Current limit:
+
+- component reordering is currently driven from the component header itself, not from nested component fields
+
 ### Renderer Section
 
 The renderer reads from the object's `sprite` metadata.

docs/guides/README.md

@@ -0,0 +1,65 @@
+# Sendama Editor Guides
+
+This guide set explains how the current Sendama editor works in practice so you can use it to build scenes, draw assets, tune properties, and iterate on your game quickly.
+
+## Start Here
+
+Read these guides in order if you are learning the editor for the first time:
+
+1. [Getting Started](getting-started.md)
+2. [Layout and Navigation](layout-and-navigation.md)
+3. [Building Scenes](building-scenes.md)
+4. [Working with Assets](working-with-assets.md)
+5. [Inspector and Properties](inspector-and-properties.md)
+6. [Playtest and Debug](playtest-and-debug.md)
+7. [Reference](reference.md)
+
+## What The Editor Can Do Today
+
+- Open a Sendama project and load its active scene.
+- Browse the `Assets` tree.
+- Inspect scene roots, scene objects, and file assets.
+- Add top-level `GameObject`, `Text`, and `Label` entries to the active scene.
+- Select visible objects directly in the Scene tab and move them with the keyboard.
+- Edit scene, transform, renderer, text, and serialized component fields in the Inspector.
+- Add components to hierarchy objects from the Inspector.
+- Create scripts, scenes, textures, tile maps, and events from the Assets panel.
+- Create, edit, rename, and delete `.texture` and `.tmap` assets.
+- Save the active scene back to its `.scene.php` source file.
+- Watch project logs from inside the editor.
+
+## What Still Happens Outside The Editor
+
+The editor is best used as part of a hybrid workflow. You will still use the CLI or code for some tasks:
+
+- Writing the PHP logic inside generated scripts, events, and engine classes.
+- Removing or reordering components after they have been added.
+- Reparenting hierarchy objects or creating new child objects under an existing object.
+- Running the full game runtime in a dedicated session.
+
+For those tasks, the usual companion commands are:
+
+```bash
+sendama generate:scene level01
+sendama generate:script PlayerController
+sendama play
+```
+
+## Recommended Build Loop
+
+Use the editor in this order when building a level or game screen:
+
+1. Open the project with `sendama edit`.
+2. Set the scene size and background tile map.
+3. Add scene objects from the Hierarchy panel.
+4. Assign textures, text, and components in the Inspector.
+5. Draw or update textures and tile maps in the Sprite tab.
+6. Save the scene with `Ctrl+S`.
+7. Check logs in the Console panel and run the game with `sendama play` when you need a full playthrough.
+
+## A Few Important Rules To Remember
+
+- Scene edits are not written to disk until you press `Ctrl+S`.
+- Sprite and tile map edits are written to disk immediately.
+- File renames happen immediately, but you should save the scene afterward if that scene references the renamed asset.
+- Asset deletions happen immediately and can leave broken references behind if the deleted file was still in use.