Run request analysis on demand on the VPS

docs/kb/systems/persistence-save-pipeline.md

@@ -0,0 +1,49 @@
+# Persistence And Save Pipeline
+
+## What It Does
+
+This subsystem turns editor state into saved content and world data. It persists content records, world metadata, bookmarks, and dirty chunks, while keeping save state and toolbar status in sync.
+
+## Key Files
+
+- `src/worldshaperStudio/persistenceController.ts`
+- `src/worldshaperStudio/historyController.ts`
+- `src/worldshaperStudio/historyStateStore.ts`
+- `server.js`
+
+## Endpoints It Uses
+
+- `POST /api/world/:worldId/chunks/batch-save`
+- `POST /api/content/:type`
+- `GET /api/editor-settings`
+- `POST /api/editor-settings`
+- `GET /api/catalog-meta`
+- `POST /api/catalog-meta`
+
+## Important Data And Rules
+
+- world save batches metadata, bookmarks, and dirty chunks together
+- content saves are per content type
+- successful world saves clear dirty chunk keys
+- save failures surface through status messages and toolbar state
+
+## Invariants And Constraints
+
+- save must not lose dirty chunk edits
+- content records and world chunks have different persistence paths
+- history state should know when a save succeeds
+- partial failures need clear error reporting
+
+## Common Request Themes
+
+- save reliability
+- auto-save ideas
+- validation before save
+- batch save size or performance
+- stale content vs world metadata mismatches
+
+## Triage Questions
+
+- Is the failure on world save, content save, or both?
+- Are we persisting the right data, but at the wrong time?
+- Does the request need new API support or just better client save orchestration?