Initial commit - copied workspace after database cleanup

AI-INSTRUCTIONS-MAINTENANCE.md

@@ -0,0 +1,100 @@
+# Maintaining AI Assistant Instructions (copilot-instructions.md)
+
+This repo uses `.github/copilot-instructions.md` to brief AI coding agents about your architecture, workflows, and conventions. Keep it concise, repo-specific, and always in sync with your code.
+
+This guide explains when and how to update it, plus small guardrails to help—even for a solo developer.
+
+## When to update
+Update the instructions in the same commit as your change whenever you:
+- Add/rename services, ports, or container wiring (docker-compose*.yml, Nginx, Mosquitto)
+- Introduce/rename MQTT topics or change retained-message behavior
+- Add/rename environment variables or change defaults (`.env.example`, `deployment.md`)
+- Change DB models or time/UTC handling (e.g., `models/models.py`, UTC normalization in routes/scheduler)
+- Add/modify API route patterns or session lifecycle (files in `server/routes/*`, `server/wsgi.py`)
+- Adjust frontend dev proxy or build settings (`dashboard/vite.config.ts`, Dockerfiles)
+
+## What to update (and where)
+- `.github/copilot-instructions.md`
+  - Big picture: services and ports
+  - Service boundaries & data flow: DB connection rules, MQTT topics, retained messages, screenshots
+  - API patterns: Blueprints, Session per request, enum/datetime serialization
+  - Frontend patterns: Vite dev proxy and pre-bundled dependencies
+  - Environment variables (reference): names, purposes, example patterns
+  - Conventions & gotchas: UTC comparisons, retained MQTT, container hostnames
+- `.env.example`
+  - Add new variable names with placeholders and comments (never secrets)
+  - Keep in-container defaults (e.g., `DB_HOST=db`, `MQTT_BROKER_HOST=mqtt`)
+- `deployment.md`
+  - Update Quickstart URLs/ports/commands
+  - Document prod-specific env usage (e.g., `VITE_API_URL`, `DB_CONN`)
+
+## How to write good updates
+- Keep it short (approx. 20–50 lines total). Link to code by path or route rather than long prose.
+- Document real, present patterns—not plans.
+- Use UTC consistently and call out any special handling.
+- Include concrete examples from this repo when describing patterns (e.g., which route shows enum serialization).
+- Never include secrets or real tokens; show only variable names and example formats.
+
+## Solo-friendly workflow
+- Update docs in the same commit as your change:
+  - Code changed → docs changed (copilot-instructions, `.env.example`, `deployment.md` as needed)
+- Use a quick self-checklist before pushing:
+  - Services/ports changed? Update “Big picture”.
+  - MQTT topics/retained behavior changed? Update “Service boundaries & data flow”.
+  - API/Session/UTC rules changed? Update “API patterns” and “Conventions & gotchas”.
+  - Frontend proxy/build changed? Update “Frontend patterns”.
+  - Env vars changed? Update “Environment variables (reference)” + `.env.example`.
+  - Dev/prod run steps changed? Update `deployment.md` Quickstart.
+- Keep commits readable by pairing code and doc changes:
+  - `feat(api): add events endpoint; docs: update routes and UTC note`
+  - `chore(compose): rename service; docs: update ports + nginx`
+  - `docs(env): add MQTT_USER to .env.example + instructions`
+
+## Optional guardrails (even for solo)
+- PR (or MR) template (useful even if you self-merge)
+  - Add `.github/pull_request_template.md` with:
+```
+Checklist
+- [ ] Updated .github/copilot-instructions.md (services/MQTT/API/UTC/env)
+- [ ] Synced .env.example (new/renamed vars)
+- [ ] Adjusted deployment.md (dev/prod steps, URLs/ports)
+- [ ] Verified referenced files/paths in the instructions exist
+```
+- Lightweight docs check (optional pre-commit hook)
+  - Non-blocking script that warns if referenced files/paths don’t exist. Example sketch:
+```
+#!/usr/bin/env bash
+set -e
+FILE=.github/copilot-instructions.md
+missing=0
+for path in \
+  server/wsgi.py \
+  server/routes/clients.py \
+  server/routes/events.py \
+  server/routes/groups.py \
+  dashboard/vite.config.ts \
+  docker-compose.yml \
+  docker-compose.override.yml; do
+  if ! test -e "$path"; then
+    echo "[warn] referenced path not found: $path"; missing=1
+  fi
+done
+exit 0  # warn only; do not block commit
+```
+- Weekly 2-minute sweep
+  - Read `.github/copilot-instructions.md` top-to-bottom and remove anything stale.
+
+## FAQ
+- Where do the AI assistants look?
+  - `.github/copilot-instructions.md` + the code you have open. Keep this file synced with the codebase.
+- Is it safe to commit this file?
+  - Yes—no secrets. It should contain only structure, patterns, and example formats.
+- How detailed should it be?
+  - Concise and actionable; point to exact files for details. Avoid generic advice.
+
+## Pointers to key files
+- Compose & infra: `docker-compose*.yml`, `nginx.conf`, `mosquitto/config/mosquitto.conf`
+- Backend: `server/database.py`, `server/wsgi.py`, `server/routes/*`, `models/models.py`
+- MQTT workers: `listener/listener.py`, `scheduler/scheduler.py`, `server/mqtt_helper.py`
+- Frontend: `dashboard/vite.config.ts`, `dashboard/package.json`, `dashboard/src/*`
+- Dev/Prod docs: `deployment.md`, `.env.example`