docs: run/edit mode, profiles behavior, send presets

Made-with: Cursor

README.md

@@ -1,6 +1,36 @@
 # led-controller
 
-## Run on port 80 without root
+LED controller web app for managing profiles, tabs, presets, and color palettes, and sending commands to LED devices over the serial -> ESP-NOW bridge.
 
-Run once: `sudo scripts/setup-port80.sh`. Then start the app with: `pipenv run run`.
+## Run
+
+- One-time setup for port 80 without root: `sudo scripts/setup-port80.sh`
+- Start app: `pipenv run run`
+- Dev watcher (auto-restart on `src/` changes): `pipenv run dev`
+
+## UI modes
+
+- **Run mode**: focused control view. Select tabs/presets and apply profiles. Editing actions are hidden.
+- **Edit mode**: management view. Shows Tabs, Presets, Patterns, Color Palette, and Send Presets controls, plus per-tile preset edit/remove and drag-reorder.
+
+## Profiles
+
+- Applying a profile updates session scope and refreshes the active tab content.
+- In **Run mode**, Profiles supports apply-only behavior (no create/clone/delete).
+- In **Edit mode**, Profiles supports create/clone/delete.
+- Creating a profile always creates a populated `default` tab (starter presets).
+- Optional **DJ tab** seeding creates:
+  - `dj` tab bound to device name `dj`
+  - starter DJ presets (rainbow, single color, transition)
+
+## Preset colors and palette linking
+
+- In preset editor, selecting a color picker value auto-adds it when the picker closes.
+- Use **From Palette** to add a palette-linked preset color.
+- Linked colors are stored as palette references and shown with a `P` badge.
+- When profile palette colors change, linked preset colors update across that profile.
+
+## API docs
+
+- Main API reference: `docs/API.md`
 

docs/API.md

@@ -11,6 +11,22 @@ All JSON APIs use `Content-Type: application/json` for bodies and responses unle
 
 ---
 
+## UI behavior notes
+
+The main UI has two modes controlled by the mode toggle:
+
+- **Run mode**: optimized for operation (tab/preset selection and profile apply).
+- **Edit mode**: shows editing/management controls (tabs, presets, patterns, color palette, send presets, and profile management actions).
+
+Profiles are available in both modes, but behavior differs:
+
+- **Run mode**: profile **apply** only.
+- **Edit mode**: profile **create/clone/delete/apply**.
+
+`POST /presets/send` is wired to the **Send Presets** UI action, which is exposed in Edit mode.
+
+---
+
 ## Session and scoping
 
 Several routes use **`@with_session`**: the server stores a **current profile** in the session (cookie). Endpoints that scope data to “the current profile” (notably **`/presets`**) only return or mutate presets whose `profile_id` matches that session value.
@@ -61,7 +77,7 @@ Below, `<id>` values are string identifiers used by the JSON stores (numeric str
 | GET | `/profiles` | `{"profiles": {...}, "current_profile_id": "<id>"}`. Ensures a default current profile when possible. |
 | GET | `/profiles/current` | `{"id": "...", "profile": {...}}` |
 | GET | `/profiles/<id>` | Single profile. If `<id>` is `current`, same as `/profiles/current`. |
-| POST | `/profiles` | Create profile. Body may include `name` and other fields. Returns `{ "<id>": { ... } }` with status 201. |
+| POST | `/profiles` | Create profile. Body may include `name` and other fields. Optional `seed_dj_tab` (request-only) seeds a DJ tab + presets. New profiles always get a populated `default` tab. Returns `{ "<id>": { ... } }` with status 201. |
 | POST | `/profiles/<id>/apply` | Sets session current profile to `<id>`. |
 | POST | `/profiles/<id>/clone` | Clone profile (tabs, palettes, presets). Body may include `name`. |
 | PUT | `/profiles/current` | Update the current profile (from session). |
@@ -99,6 +115,11 @@ Scoped to **current profile** in session (see above).
 
 Response on success includes `presets_sent`, `messages_sent` (chunking splits payloads so each JSON string stays ≤ 240 bytes).
 
+Stored preset records can include:
+
+- `colors`: resolved hex colors for editor/display.
+- `palette_refs`: optional array of palette indexes parallel to `colors`. If a slot contains an integer index, the color is linked to the current profile palette at that index.
+
 ### Tabs — `/tabs`
 
 | Method | Path | Description |