AV-Watch/CLAUDE.md

CLAUDE.md

Every session: stay in sync with Gitea

This repo is backed up to http://10.3.8.90:3000/chris/AV-Watch (private, branch main). The Git login is in Windows Credential Manager, not in this repo.

1. Pull at the start. Before starting on the first request of every session, pull in the repo root (C:\Users\Live Stream\Desktop\Claude\avwatch):

   # 'never' makes a bad token fail fast instead of opening a login window
   $env:GCM_INTERACTIVE = 'never'; git pull --ff-only
   

   Report the result in one line, then carry on with the request. If the pull fails (server unreachable, local changes in the way, history diverged), say why in that line and carry on. Don't stash, reset, rebase or merge to get past it unless asked. If git isn't found, use C:\Program Files\Git\cmd\git.exe.

2. Remind before finishing. When you finish a piece of work and git status shows uncommitted changes or unpushed commits, end your reply with a one-line reminder of what isn't on Gitea yet and offer to commit and push. Do the same when the user says they're wrapping up. Only commit or push when asked, and don't repeat the reminder if nothing has changed since the last one.

What this is

AVWatch is a Python CLI that monitors firmware/software updates across the Waters Church live-production AV fleet. For each item it answers "a new version exists, is it safe to install or should we wait?" and makes a Go / Wait / Avoid call. It does this by finding the current release, searching Reddit, GitHub and the web for people reporting breakage, and applying a conservative soak policy.

The design principle: a dead device on Sunday morning costs far more than running one release behind. The update has to prove it is safe, and waiting is the default. It also never guesses a version it can't verify. Anything it can't verify goes to a "check by hand" list rather than getting an invented answer.

README.md is the full user guide. This file is orientation for working on the code.

Layout

Path	Purpose
avwatch/cli.py	Entry point. Commands: doctor, list, scan, digest, report, set-installed, mark, history, test-email, worksheet
avwatch/config.py	Loads config.toml. All secrets are read from env vars here, never from the file
avwatch/inventory.py, models.py	Loads/merges inventory*.yaml; item model
avwatch/coupling.py	Version-coupling graph (must_match, must_be_at_least, host_of, …); mirrors edges, detects live mismatches
avwatch/scanner.py, versions.py	Orchestrates lookups; version comparison
avwatch/sources/	Version sources: blackmagic (support JSON), github_releases, generic (HTML regex), websearch (Claude + web search, must cite a source)
avwatch/risk/	collectors (Reddit/GitHub/DDG evidence), heuristics (rule-based score), llm (Claude verdict), classify
avwatch/report/	HTML dashboard + email digest (templates/*.jinja)
avwatch/store.py	SQLite state in data/avwatch.sqlite3 (versions seen, verdicts, mark decision history)
avwatch/http.py	Cached HTTP client (data/cache/)
scripts/	install_tasks.ps1 (Task Scheduler: scans Tue/Thu/Sat 06:00, digest Mon 07:00), run_avwatch.ps1, set_api_key.ps1
tests/	test_core.py, test_coupling.py (unittest)

Commands

python -m pip install -r requirements.txt
python -m unittest discover -s tests      # 65 tests, all passing as of 2026-09-24
python -m avwatch doctor --network
python -m avwatch scan --no-llm           # no API spend

Secrets and config

• Credentials come only from env vars: ANTHROPIC_API_KEY, AVWATCH_SMTP_PASSWORD, AVWATCH_GITHUB_TOKEN, AVWATCH_REDDIT_CLIENT_ID, AVWATCH_REDDIT_CLIENT_SECRET. Keep it that way. Don't add a secret field that gets read from config.toml.
• config.toml is gitignored because it can hold recipient addresses and usernames. config.example.toml is the committed template.
• data/, reports/ and logs/ are runtime output and gitignored. This means the SQLite decision history is not in git. Back it up separately if it matters.
• Community post text is untrusted input to the LLM. Keep the prompt-injection guarding in risk/llm.py intact.

Where it stands (2026-09-24)

• v1.0.0. Core pipeline, coupling checks, dashboard, email digest and scheduled tasks are built. Reports from 2026-09-08 and 2026-09-09 show real runs.
• inventory.yaml has 88 items, but only 3 have installed: filled in. Until more do, AVWatch can report "a newer version exists" but not "you are behind", and coupling mismatches can't be checked.
• The README describes inventory-expansion.yaml (116 items) and inventory-optional.yaml (57 items), but neither file exists in this folder. Either they were deleted (the README says that's supported) or they were never saved. The README counts (259 total, 130 unconfirmed, cost estimates) are out of date until this is sorted out.
• The five VERIFY entries the README lists (DQ Rack, Quantum 225, DBOX+, AJA, Netgear Dante switch) no longer carry a VERIFY marker in inventory.yaml. Check whether they were resolved or just lost the marker.

Next steps

1. Record installed versions with python -m avwatch worksheet and set-installed, starting with the coupled clusters (ATEM trio, Shure RF, DiGiCo pair, Netgear Dante switch).
2. Resolve the missing expansion/optional inventory files, then update the README counts.
3. Set AVWATCH_REDDIT_CLIENT_ID/SECRET (the best evidence source) and AVWATCH_GITHUB_TOKEN.
4. Confirm the scheduled tasks are registered and the Monday digest mails correctly (python -m avwatch digest --dry-run).
5. Decide whether data/avwatch.sqlite3 needs a backup.