infoscreen/AI-INSTRUCTIONS-MAINTENANCE.md

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.