compass_teams_nhs/AGENTS.md

# Compass / NHS (school)

> Build spec for Paperclip. Follow the phases in section 11 in order. Do not skip a
> phase's Definition of Done. When something is unclear, ask Sam — do not guess.

---

## 1. Purpose and outcome

Two school systems, for Harry and Finn:

- **Compass** — the daily schedule and planner: what is on, what is overdue, notices.
- **Teams** — homework and assignments.

Store both, surface overdue and pending work, write important events to Sam's Home
Assistant calendar, and send the morning briefs.

**Outcome (the single success statement):**
> Sam sees, in one page, what each child has due and what is overdue — without
> logging into Compass — and the family is told before work is late.

## 2. Scope

**In scope**
- Scan **Compass** per child: the daily schedule, notices, and due dates.
- Scan **Teams** per child: homework and assignments. **Scope may be limited** — pick
  the smallest section that still answers "what is overdue". Decide in Phase 2.
- Store and display per child.
- Detect overdue and pending work.
- Write important events to Sam's Home Assistant calendar.
- Send the morning briefs via Apprise.
- Answer the Hub.

**Out of scope**
- The **React calendar** — that is a separate project. Do not build a calendar UI here.
- The school's own systems. Read-only.

## 2a. Prerequisites (verify before Phase 1)

Check these first. The values come from the prerequisite check on `.13` (AUD-102).
Items marked **not verified** need a decision or a test.

| Need | Status / note |
|---|---|
| **Go toolchain** | **MISSING on `.13`** — `go` is not in the PATH, not in `nix-env`, and not in `/etc/nixos/configuration.nix`. Sam must add `go` to `environment.systemPackages` and run `nixos-rebuild switch`. Phase 1 can build in the `golang` Docker image instead. |
| **Docker + compose** | Present on `.13`. Docker client and server 29.6.2, Compose 5.3.1. Run as user `sam` (in the `docker` group, no sudo). |
| **Port 8792** | Free on `.13`. No listener and no container maps this port. Ports 8790 and 8791 are in use by other services. |
| **Caddy route on `.35`** | Caddy runs as the Docker container `caddy` (v2.8.4) on `sam-Ubuntu1` (`.35`). Routes are site blocks in `/Docker/Containers/caddy/Caddyfile`, bind-mounted to `/etc/caddy/Caddyfile`. Use `school.lab.audasmedia.com.au { import basic-auth; reverse_proxy 192.168.20.13:8792 }`. **No `school.*` block exists yet** — Phase 1 must add one. Reload with `docker exec caddy caddy reload --config /etc/caddy/Caddyfile`. DNS for the name resolves (wildcard) to `144.6.86.11`. |
| **pi-browser-harness** | Present on `.13` at `/home/sam/.agents/extensions/pi-browser-harness`, version 0.11.0. It is a **pi extension**, not a CLI. Load it as a package extension, then use the commands `/browser-setup` and `/browser-profile`. It exposes `browser_*` tools and drives a long-lived headless Chrome over CDP (`--user-data-dir=/home/sam/.chrome-pi`, debug port 9222). Session reuse works. **The extension is not enabled in this repo's `.pi/settings.json`** — Phase 2 must enable it before the login proof. |
| **Compass URL + reachability** | **`https://nhs-vic.compass.education/login.aspx`** (Northcote High School). DNS goes to Cloudflare. TCP and TLS reach the edge, but the page returns `HTTP/2 403` with `cf-mitigated: challenge` (Cloudflare bot challenge). A real browser session is necessary. This is the Phase 2 risk. |
| **Compass credentials + 2FA** | **NOT AVAILABLE** — no Compass, school, or child key exists in `~/.config/environment.d/10-secrets.conf` or its backups, and no school-named secret is in the instance config. Sam must supply the account name, the username, and the password as a **Paperclip secret** (or in `10-secrets.conf`). Never write them in this file. **2FA is not verified** — no login was attempted. Confirm whether Compass enforces 2FA or new-device email verification, and define the manual step. |
| **Apprise** | Running on `.35:8210` (container `apprise`, host 8210 to container 8000). `GET /` and `GET /status` return 200. The Caddy route `apprise.lab.audasmedia.com.au` has basic auth. |

**Gating read-out**

- **Phase 1** is unblocked except for Go. Build in the `golang` Docker image, or ask Sam to install Go on the host.
- **Phase 2** is blocked until Sam supplies a Compass credential and confirms the 2FA step. Phase 2 must also enable the `pi-browser-harness` extension in this repo.
- The Cloudflare challenge is the main technical risk. Prove it first.

**Not verified**

- Whether Compass enforces 2FA.
- The exact per-child account model.
- Whether the headless Chrome profile clears the Cloudflare challenge (no login was attempted).

## 3. Users and roles

| User | Can do |
|---|---|
| **Sam** | Everything. Session login. |
| **Jo / Harry / Finn** | Receive notifications. Read-only. |

## 4. Functional requirements

| ID | Requirement |
|---|---|
| FR-1 | Scan Compass with the **pi-browser-harness** on an n8n schedule, once per child. |
| FR-2 | Log in and reuse a stored session. A manual step is allowed when the school demands it. |
| FR-3 | Parse messages, homework, due dates, and calendar events into structured items. |
| FR-4 | Use JEV or the LLM to structure the page content and classify importance. |
| FR-5 | Store every item with its child, source page, type, subject, due date, and link. |
| FR-6 | Detect overdue work and work due today and this week. |
| FR-7 | Show a per-child view: overdue, due today, due this week, and messages. |
| FR-8 | Write **important school events** to **Sam's Home Assistant calendar**. The Hub or Jervis may also push into it. |
| FR-9 | Send a **morning brief to each boy** (Harry, Finn): what is on today, overdue work, pending work, and school notices. |
| FR-10 | Provide a **Delete** action and a **Send** action on items and summaries. |
| FR-11 | Hub API: `GET /capabilities`, `POST /ask` (read-only), `POST /notify`. |
| FR-12 | Fail **loudly** on a scrape failure. Never report "nothing due" when the scan failed. |
| FR-13 | Log every scan: time, child, pages, items, errors. |
| FR-14 | Send a **combined brief** for both boys to **Jo and Sam** via Apprise. |
| FR-15 | Scan **Teams** for homework and assignments, with the smallest useful scope. |

## 5. Screens and UX flow

**Screens**
1. **Login** — session form.
2. **Child dashboard** — a tab per child: overdue, due today, due this week, messages.
3. **Item detail** — subject, teacher, due date, link, and full text.
4. **Send panel** — choose recipients, preview the brief, send.
5. **Scan history** — last scans, items found, errors.

**Main flow**
```
n8n triggers the morning scan → items stored
   → each boy gets his own morning brief (today, overdue, pending, notices)
   → Jo and Sam get one combined brief
   → important events are written to Sam's Home Assistant calendar
```

**Output style:** brief, concise, lists only. No fluff. Overdue first.

## 6. Look and feel

Reuse the Family Home Lab design system.

- Source: `/home/sam/Docker/Containers/family-home-lab/DESIGN.md`
- Tokens: `/home/sam/Docker/Containers/family-home-lab/portal/static/tokens.css`
- Copy `tokens.css` into this project.

Canvas `#f6f5f4`, one action blue `#0075de`, Inter, 8px grid, pill CTAs, hairline
borders. Dark mode. Works on a phone browser.

## 7. Data model

SQLite inside the service. Suggested tables:

| Table | Holds |
|---|---|
| `children` | id, name, year, compass id |
| `items` | child, type (`message`, `task`, `event`), subject, teacher, title, body, due-at, url |
| `scans` | started-at, child, pages fetched, items found, error |
| `notifications` | recipient, summary text, sent-at |
| `session` | harness session state per child |

Retention: keep items while the term is current. Scans are append-only and size-capped.

## 8. Integrations

| System | Use |
|---|---|
| **pi-browser-harness** | Log in and fetch Compass pages. Already built and working. |
| **JEV** | Structure page content; classify importance. HTTP API. |
| **OmniRoute** | All other models. |
| **n8n** | Triggers the daily scan. |
| **Apprise** | Per-boy morning briefs, and one combined brief to Jo and Sam. Running on `.35:8210`. |
| **Calendar** | **Sam's Home Assistant calendar.** The Hub or Jervis pushes into HA. |
| **Hub** | `POST /ask`, `POST /notify`, `GET /capabilities`. |

The Hub interface is frozen in `central_ai_llm_master/docs/ask-contract.md`.
`/ask` is read-only.

## 9. Technology (locked)

| Item | Value |
|---|---|
| Backend | **Go** |
| UI | **HTMX** + server-rendered HTML |
| Database | **SQLite** |
| Scraper | **patchright** (headless Playwright). The **pi-browser-harness** cannot do the daily scan: it gets a Cloudflare **403 managed challenge** on the login POST. |
| Design | Family Home Lab `tokens.css` |
| Host | `.13`, Docker |
| Container | **This project's own** image and compose file. |
| Port | Allocate one (suggest **8792**). Record it once chosen. |
| URL | `school.lab.audasmedia.com.au` via Caddy on `.35` |
| Auth | **Separate session login.** |

## 10. Rules and constraints

1. **Read-only against the school.** Never post, message, or submit anything.
2. **A failed scan must be loud.** Never show an empty day as "nothing due".
3. School credentials and session state are secrets. Never commit them.
4. Models go through **OmniRoute**, except JEV.
5. `/ask` is read-only.
6. Output is brief: lists, no fluff, overdue first.
7. Writing a calendar event needs **no** approval.
8. Own folder, own container, own port.

## 11. Build order

**Phase 1 — Skeleton**
Go service, SQLite, config, session login, Dockerfile, compose, Caddy route.
*DoD:* the app runs on `.13`, login works, `/health` returns ok.

**Phase 2 — Prove the login and the fetch**
Point the pi-browser-harness at Compass. Log in once. Fetch the pages needed for one
child. Store the raw pages.
*DoD:* a real Compass page for one child is fetched and stored. **This is the risk
phase — a failed login stops the project, so prove it early.**

**Phase 3 — Parse into items**
Turn pages into structured items: messages, tasks, events, due dates, links.
*DoD:* real homework and messages for one child appear as structured rows.

**Phase 4 — Both children**
Repeat for Harry and Finn, with per-child sessions.
*DoD:* both children's items are stored and separated.

**Phase 5 — Dashboard**
Per-child view with overdue, due today, due this week, and messages.
*DoD:* Sam can see, per child, what is overdue and due, on a phone.

**Phase 6 — Calendar write**
Write school events to the calendar.
*DoD:* a real school event appears in the calendar.

**Phase 7 — Notify and send**
Apprise notifications, recipient selection, and the Send panel.
*DoD:* a brief is sent to a real recipient.

**Phase 8 — Hub**
`/capabilities`, `/ask`, `/notify`.
*DoD:* the Hub asks "what does Harry have on today at school?" and gets a correct answer.

**Phase 9 — Documentation**
*DoD:* project-docs run; Gitea, Obsidian, Outline, Vikunja, and the map are updated.

## 12. Acceptance criteria

- The scan runs daily and stores real items for both children.
- Overdue work is detected and shown first.
- A failed login shows an error, not an empty day.
- A school event can be written to the calendar.
- A brief can be sent to a real recipient from the app.
- The Hub answers a school question correctly.
- Runs in its own container on its own port, behind Caddy.

## 13. Decisions and remaining questions

Resolved:
1. **React calendar dropped.** Separate project.
2. **Login** is on-screen, via the **pi-browser-harness** or JEV.
3. **Go + HTMX + SQLite**, own container, `school.lab.audasmedia.com.au`, session login.
4. **Calendar = Home Assistant (Sam's).** Important events are written there.
5. **Recipients:** each boy gets his own morning brief; Jo and Sam get one combined brief.
6. **Focus:** Compass gives the daily schedule; Teams gives homework and assignments.
7. **Trigger time: 6:00 am.**
8. **Apprise channels: Email and WhatsApp.**
9. **Scraper = patchright.** The daily scan uses patchright (headless Playwright).
   The pi-browser-harness cannot pass the Cloudflare managed challenge on the login POST.
10. **2FA:** the Compass parent login required no two-factor or one-time code during
    the Phase 2 proof.

Remaining:
1. **Teams scope:** find the smallest section that answers "what is overdue". Teams
   may be hard to reach. This is a decision for the brief and for Phase 2.
2. **Teams two-factor auth:** not verified. Confirm whether Teams needs 2FA, then
   define the manual step.