# Email Agent — Agent Runbook

## Before you start

1. Read `00-index.md`. Inject only the documents you need.
2. Read `AGENTS.md` section 11 (build order) and section 10 (rules).
3. Check git status and the last commits.

```sh
cd /home/sam/paseo/projects/email_agent
git status
git log -n 5 --oneline
```

## Run the tests

Run the Go tests in a container. The image has the toolchain.

```sh
timeout 600 docker run --rm -v "$PWD":/src -w /src golang:1.25-alpine go test ./...
timeout 600 docker run --rm -v "$PWD":/src -w /src golang:1.25-alpine go vet ./...
```

Expected: `go test ./...` is green and `go vet ./...` is silent.

## Run locally

```sh
go run ./cmd/email-agent
curl -s localhost:8790/health
```

The health reply is JSON: `{"status":"ok","database":"ok", ...}`.

## Build and deploy on .13

Load the host secrets, then build and start the container.

```sh
set -a; . ~/.config/environment.d/10-secrets.conf; set +a
cd /home/sam/paseo/projects/email_agent
EMAIL_AGENT_VERSION=phase8 EMAIL_AGENT_COMMIT=$(git rev-parse --short HEAD) docker compose build
docker compose up -d
```

Check the result:

```sh
docker ps --filter name=email-agent
curl -s https://mail.lab.audasmedia.com.au/health
```

## Check the live service

```sh
curl -s http://127.0.0.1:8790/health
curl -s http://127.0.0.1:8790/readyz
timeout 10 docker exec email-agent email-agent -version
timeout 10 docker exec email-agent email-agent -check-smtp
```

`-check-smtp` verifies IPv4, STARTTLS, and login. It sends no mail.

## Trigger the jobs

The jobs also run from the dashboard buttons. The CLI runs them without the UI.

```sh
timeout 60 docker exec email-agent email-agent -fetch
timeout 120 docker exec email-agent email-agent -classify
timeout 60 docker exec email-agent email-agent -summary
```

`-summary-send` sends a real email. Get Sam's approval first. `-retain` clears
old bodies and caps the log.

## The Hub API

`HUB_TOKEN` protects `/capabilities` and `/ask`. `email_agent` is registered
with the running Hub.

```sh
set -a; . ~/.config/environment.d/10-secrets.conf; set +a
curl -s -H "Authorization: Bearer $HUB_TOKEN" http://127.0.0.1:8790/capabilities
curl -s -H "Authorization: Bearer $HUB_TOKEN" -H 'Content-Type: application/json' \
  -d '{"question":"anything important in my inbox?","asker":"sam"}' \
  http://127.0.0.1:8790/ask
```

`/ask` is read-only. It never writes to the database.

## Restart

```sh
docker compose restart email-agent
docker logs --tail 50 email-agent
```

## Roll back

1. `git revert <commit> && docker compose up -d --build`.
2. The database is on the `email_agent_data` volume. It is not changed by a code
   revert. A schema migration is forward-only; restore a database copy to go
   back a schema version.
3. To disable the Hub API, remove `HUB_TOKEN` from the host secrets and restart.

## Rebuild the documentation

```sh
cd /home/sam/paseo/projects/email_agent
mmdc -i docs/email-agent-architecture.mmd -o docs/diagrams/email-agent-architecture.png --scale 2 -b white
cd /home/sam/.agents/skills/archify
node bin/archify.mjs validate architecture /home/sam/paseo/projects/email_agent/docs/archify/email-agent.architecture.json --quality showcase --json
node bin/archify.mjs deliver  architecture /home/sam/paseo/projects/email_agent/docs/archify/email-agent.architecture.json /home/sam/paseo/projects/email_agent/docs/email-agent-map.html --quality showcase --json
```

## Publish the map

```sh
~/.agents/skills/project-docs/scripts/publish-maps.sh /home/sam/paseo/projects/email_agent
```

Result: `https://maps.lab.audasmedia.com.au/email_agent/docs/`.

## Documentation surfaces

| Surface | Location |
| :--- | :--- |
| Gitea | `ssh://git@gitea.lab.audasmedia.com.au:2222/sam/email_agent.git` |
| Obsidian | Vault `010 inbox` on `.27` (the sorter files it later). |
| Outline | Collection `Email Agent` on `outline.lab.audasmedia.com.au`. |
| Vikunja | Project `Email Agent` on `vikunja.lab.audasmedia.com.au`. |
| Map | `central_ai_llm_master/docs/hub-architecture-map.html` and this repo's map. |

## Safety rules

- Force IPv4 for every Gmail connection. IPv6 fails from `.13`.
- Never commit a secret.
- Never send a real email as a test. Ask Sam first.
- Never follow a real unsubscribe link. Only mark and record.
- Spam is recommended, never auto-deleted.
- Bound every `docker run` with `timeout` and `--entrypoint sh`. A bare
  `docker run` starts the server and hangs.