updated docs

docs/data/en/concepts.md

@@ -0,0 +1,75 @@
+# Concepts
+
+The mental model behind soleprint.
+
+---
+
+## Rooms
+
+A room is an isolated configuration. Each room lives in `cfg/<room>/` and contains everything soleprint needs to build and run a specific instance.
+
+```
+cfg/
+  standalone/    # Soleprint only, no managed app
+  amar/          # Soleprint wrapping the Amar application
+  myroom/        # Your room
+```
+
+Rooms are independent. They don't share state. You can run multiple rooms simultaneously on different ports.
+
+## Systems
+
+Three systems plug into the soleprint core:
+
+- **Artery** — data flow. Connectors to external services. Veins talk to real APIs. Shunts fake them for testing. Pulses compose a vein with a room and depot. Plexus is a full app stack.
+- **Atlas** — documentation. Books, templates, depots. Documentation that lives next to what it describes and stays actionable.
+- **Station** — execution. Tools like tester, datagen, modelgen, graphgen. Monitors like databrowse. Desks for task orchestration.
+
+## The cfg to gen Flow
+
+`cfg/` is hand-authored. `gen/` is machine-built. Never edit `gen/` directly.
+
+```
+cfg/myroom/  ──┐
+               ├──  build.py  ──►  gen/myroom/
+soleprint/   ──┘
+```
+
+`build.py` merges the core framework (`soleprint/`) with your room config (`cfg/myroom/`). Room-specific files override or extend core defaults. The output in `gen/myroom/` is what actually runs.
+
+![Build Flow](../graphs/cfg_gen_flow.svg)
+
+## Layers
+
+Room initialization uses layers 0 through 6. Each layer adds a capability:
+
+| Layer | What |
+|-------|------|
+| 0 | Config — `config.json`, branding, terminology |
+| 1 | Docker — container setup, compose files |
+| 2 | Managed app — the application soleprint wraps |
+| 3 | Link — bridge adapters to the managed app's database |
+| 4 | Scripts — build and run scripts in `ctrl/` |
+| 5 | Systems — artery, atlas, station configs |
+| 6 | Nginx — reverse proxy, sidebar injection |
+
+![Room Layers](../graphs/room_layers.svg)
+
+## Standalone vs Managed
+
+**Standalone** — soleprint runs by itself. No managed app. Useful for tooling, documentation, or connector development.
+
+**Managed** — soleprint wraps an existing application. Nginx sits in front of the app, injecting the sidebar into every HTML response. Link adapters bridge soleprint into the app's database.
+
+## The Wrapping Concept
+
+Soleprint never touches your app's source code. The injection works like this:
+
+1. Nginx receives the app's HTML response
+2. `sub_filter` injects soleprint's CSS and JS before `</head>`
+3. The sidebar renders on top of the app's UI
+4. Link adapters connect to the app's database for data browsing and test data generation
+
+The app doesn't know soleprint exists. No SDK. No middleware. No build step changes.
+
+> Your app runs exactly as it would without soleprint. The sidebar is a layer on top.