# 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)
- Modify scheduler polling, power-intent semantics, or retention strategy

## 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`

## Documentation sync log
- 2026-03-24: Synced docs for completed monitoring rollout and presentation flag persistence fix (`page_progress` / `auto_progress`). Updated `.github/copilot-instructions.md`, `README.md`, `TECH-CHANGELOG.md`, `DEV-CHANGELOG.md`, and `CLIENT_MONITORING_IMPLEMENTATION_GUIDE.md` without a user-version bump.