From 26feac2fb1cf6d04576d9215e7a6bafb8c86496c Mon Sep 17 00:00:00 2001
From: space <space@reversed.dev>
Date: Sat, 23 May 2026 14:45:20 +0200
Subject: [PATCH] Add Agents.md contributor and agent guide

---
 Agents.md | 137 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 137 insertions(+)
 create mode 100644 Agents.md

diff --git a/Agents.md b/Agents.md
new file mode 100644
index 0000000..9ed7a5e
--- /dev/null
+++ b/Agents.md
@@ -0,0 +1,137 @@
+# Agents Guide: Custom Streamdeck
+
+This file is a practical onboarding guide for coding agents and contributors working in this repository.
+
+## Mission
+
+Build and maintain a local-first Streamdeck platform:
+
+- Raspberry Pi Pico emits button events over USB serial.
+- FastAPI backend owns state, persistence, action execution, and plugin runtime.
+- React frontend is the configuration UI.
+- Optional Electron overlay displays active profile/folder context.
+
+## Tech Stack
+
+- Backend: Python, FastAPI, SQLite, pyserial, pynput
+- Frontend: React 19 + TypeScript + Vite
+- Overlay: Electron + TypeScript + Tailwind CLI
+- Device firmware: MicroPython (`pico/main.py`)
+
+## Repository Map
+
+- `backend/`: API, runtime lifecycle, DB, action engine, serial + plugin services
+- `frontend/`: Vite React app for deck configuration
+- `overlay/`: transparent desktop overlay app
+- `plugins/`: backend plugin modules (`PLUGIN` entrypoint contract)
+- `pico/`: Pico firmware
+- `tests/`: backend and plugin behavior tests
+- `data/`: runtime SQLite data (gitignored)
+
+## Fast Start Commands
+
+From repo root:
+
+```powershell
+python -m pip install -r requirements.txt
+cd frontend; npm install; cd ..
+cd overlay; npm install; cd ..
+```
+
+Run backend:
+
+```powershell
+python -m uvicorn backend.main:app --host 127.0.0.1 --port 8000
+```
+
+Frontend dev mode (separate shell):
+
+```powershell
+cd frontend
+npm run dev
+```
+
+Frontend production-style build:
+
+```powershell
+cd frontend
+npm run build
+```
+
+Run tests:
+
+```powershell
+pytest
+```
+
+Overlay local run:
+
+```powershell
+cd overlay
+npm run dev
+```
+
+## Runtime Contracts To Respect
+
+### Backend Runtime
+
+- App entrypoint and route wiring live in `backend/main.py`.
+- `Runtime` owns `db`, websocket manager, plugin manager, action engine, serial service, and app discovery.
+- WebSocket event flow (`/ws`) is part of the product behavior; avoid breaking event names casually.
+
+### Database and Layout Rules
+
+- SQLite file defaults to `data/streamdeck.sqlite`.
+- First profile/root folder define canonical physical button layout.
+- Physical mapping updates are intentionally restricted to the first profile's root folder.
+- Schema + defaults are managed in `backend/database.py`; preserve migration safety and default seeding.
+
+### Action Engine
+
+- Action dispatch is centralized in `backend/services/actions.py`.
+- Built-ins include: `noop`, `key_combo`, `chain`, `app_launch`, `folder`, `folder_rotation`, `plugin`.
+- `click_check` mode blocks action execution and is relied on by UI/testing flows.
+
+### Plugin System
+
+- Plugins load from `plugins/` through `backend/services/plugins.py`.
+- Each plugin exports top-level `PLUGIN`.
+- Expected plugin attributes: `name`, `desc`, `version`, `actions`.
+- Optional hooks: `on_load(ctx)`, `on_event(ctx, event)`, `execute_action(ctx, action_id, config, event)`.
+- Plugin failures should be isolated (disabled plugin, backend stays alive).
+
+## Firmware Assumptions
+
+- Pico reports JSON lines with fields: `button`, `pin`, `event`, `pressed`.
+- Button indices are 1..10.
+- Wiring order in firmware is authoritative: `28,27,26,22,21,20,18,19,17,16`.
+
+## Change Workflow (Recommended)
+
+1. Read impacted module(s) and existing tests.
+2. Implement minimal, targeted change.
+3. Add/update tests in `tests/` for behavior changes.
+4. Run `pytest`.
+5. If frontend/overlay touched, run corresponding build command(s).
+6. Summarize user-visible impact and any migration or operational notes.
+
+## Guardrails
+
+- Keep backend behavior deterministic and explicit; avoid silent fallbacks unless already established.
+- Do not commit runtime/generated directories:
+  - `data/`
+  - `frontend/dist/`, `frontend/node_modules/`
+  - `overlay/dist/`, `overlay/release/`, `overlay/node_modules/`
+- Prefer extending existing action/plugin patterns over introducing parallel frameworks.
+- Preserve local-first behavior: no cloud dependency required for baseline functionality.
+
+## High-Value Test Targets
+
+When changing core behavior, prioritize tests around:
+
+- Pico event parsing (`parse_pico_line`)
+- Profile/folder/button invariants in `Database`
+- Physical layout synchronization and restrictions
+- Action execution paths (`folder`, `folder_rotation`, `plugin`, `chain`)
+- Plugin isolation and HTTP/device integration plugins
+