Expand request review tooling and KB

docs/kb/systems/layers-tile-editing.md

@@ -1,47 +1,55 @@
 # Layers And Tile Editing
 
-## What It Does
+## What It Owns
 
-This subsystem handles normal tile painting, erasing, selection, visible layer management, sparse height layers, and the mapping between visible document edits and stored chunk data.
+This system owns the main world-canvas tile workflow: selecting a room layer, choosing a tile brush, painting, erasing, and editing sparse height layers in world mode.
 
-## Key Files
+## Core Behaviors
+
+- Freehand tile painting on the active layer.
+- Shape strokes for the world canvas:
+  - freehand
+  - rectangle outline
+  - circle outline
+  - line with axis lock behavior
+- Height-layer painting modes:
+  - single or freehand paint
+  - rectangle fill
+  - circle fill
+  - erase variants for the same shapes
+- Background-cell editing modes:
+  - explicit tile stamp
+  - transparent hole
+  - inherit world background
+
+## Important UI Surfaces
+
+- Layers sidebar
+- Height layer list
+- Canvas brush interactions
+- Background mode button and preview
+
+## Important Files
 
 - `src/worldshaperStudio/interactionController.ts`
-- `src/worldshaperStudio/runtime.ts`
 - `src/worldshaperStudio/sidebarController.ts`
+- `src/worldshaperStudio/runtime.ts`
 - `src/worldshaperStudio/mapDocumentController.ts`
-- `src/worldshaperStudio/popupSessionStore.ts`
-- `src/worldshaperStudio/dom.ts`
 
-## Endpoints It Uses
+## Known Tool Details
 
-- primarily saved through `POST /api/world/:worldId/chunks/batch-save`
+- Tile strokes register history entries with shape-specific labels such as rectangle stroke, circle stroke, brush stroke, and erase stroke.
+- Height strokes register their own history labels and track the target Z layer.
+- Layer editing is tightly coupled to the currently loaded chunk neighborhood in world mode.
+- Brush behavior depends on catalog tile metadata resolved through runtime helpers.
 
-## Important Data And Rules
+## Relationships
 
-- room layer `0` is the base layer
-- non-base layers use sparse or transparent-style fill semantics
-- height layers are separate structures from room layers
-- visibility is tracked in popup session state
-- painting in world mode must mark affected chunks dirty
+- Depends on `Content Catalog And Records` for tile definitions and brush metadata.
+- Depends on `Chunk Storage And Streaming` for the currently editable chunk neighborhood.
+- Depends on `Persistence And Save Pipeline` for actually writing edits back to storage.
+- Feeds `Rendering And Viewport`, which visualizes the edited layers and sparse height patches.
 
-## Invariants And Constraints
+## Triage Hints
 
-- layer ordering matters to rendering and selection behavior
-- layer visibility must not destroy layer data
-- tile edits in world mode must map local viewport coordinates back to world chunk coordinates
-- height layers are not the same thing as standard room layers
-
-## Common Request Themes
-
-- better layer reordering
-- more precise tiling tools
-- height/elevation features
-- snapping or unsnapped placement
-- erase or selection behavior
-
-## Triage Questions
-
-- Is this about normal room layers or height layers?
-- Does the request affect paint semantics, visibility, ordering, or storage?
-- Does it apply to map mode, world mode, or both?
+Requests about rectangle tools, brush behavior, height painting, active layer confusion, background stamping, and tile-placement modes should usually start here, even when they also touch rendering or chunk persistence.