# Compass NHS — Agent Runbook

## First Checks

Run these commands before any change.

```bash
git -C /home/sam/paseo/projects/compass_teams_nhs status
git -C /home/sam/paseo/projects/compass_teams_nhs log -n 5 --oneline
curl -s http://127.0.0.1:8792/health
```

`/health` must return `"ok": true`. It also shows the scan state and
`hub_api`. A red scan state is real data, not a test failure.

## Build and Test

The host `.13` has no Go toolchain. Build and test inside `golang:1.25-alpine`
through `make`. Bound every Docker command.

```bash
make test          # go test ./... in golang:1.25-alpine
make vet           # go vet ./...
make build         # build the container image
```

## Deploy and Restart

```bash
make up            # docker compose up -d --build
make ps            # container state
make logs          # follow the service log
make restart       # restart the service only
```

The container is `compass-teams-nhs`. The image tag is
`compass-teams-nhs/school:0.6.2-phase6b7b`.

## Operate

```bash
make scan                          # fetch and parse both children
make scan SCAN_CHILD=Finn          # one child
make parse CHILD=Harry RUN=latest  # parse stored pages
make preview                       # print the briefs, send nothing
make notify                        # send the briefs from the last scan
make morning-brief                 # scan, then send (the n8n job)
make calendar CALENDAR_ARGS='push --dry-run'
make calendar CALENDAR_ARGS='status'
```

The send log:

```bash
docker exec compass-teams-nhs /app/school notify status
```

## Verify

```bash
make verify-phase1                 # /health, the login, the Caddy route
make verify-phase8                 # /capabilities, /ask, /notify auth
make verify-phase8 ARGS=--send     # also deliver one real /notify message
```

## The n8n Schedule

```bash
make n8n-key                       # dry run: print the key plan
make n8n-key APPLY=1               # create the restricted key
make n8n-import                    # dry run: print the import plan
make n8n-import APPLY=1            # import, publish and restart n8n
docker exec n8n n8n list:workflow --active=true
```

The workflow runs at 06:00 in `Australia/Melbourne`. The trigger key has a forced
command and `restrict`. It can run one command only.

## Documentation

```bash
# Publish the maps and diagrams to the LAN maps site.
~/.agents/skills/project-docs/scripts/publish-maps.sh \
  /home/sam/paseo/projects/compass_teams_nhs

# Force one Obsidian sorter pass on .27.
ssh sam@192.168.20.27 'obsidian-sort watch --once'
```

## Rules

1. **Read-only against the school.** Never post, message or submit.
2. **Fail loudly.** Never report "nothing due" when a scan failed.
3. **Never commit a secret.** Credentials, tokens and cookies stay in
   `environment.d/school-service.env` or a Paperclip secret.
4. **Never write personal page content into a document.**
5. Use one commit and one push for a change. End the message with
   `Co-Authored-By: Paperclip <noreply@paperclip.ing>`.