c5760db43d
- README: architecture Mermaid, Phase 8 status, Phase 7 endpoints, Documentation index - docs/outline/: AI-context collection (index, system, config, code map, runbook) - docs/email-agent-architecture.mmd + rendered PNG + Archify map (showcase pass) - docs/vikunja-tasks.json (Vikunja project 17, tasks 179-185) - docs/phase8-documentation.md evidence
144 lines
4.3 KiB
Markdown
144 lines
4.3 KiB
Markdown
# 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.
|