email_agent/docs/outline/04-agent-runbook.md

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.

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.

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

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.

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:

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

Check the live service

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.

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.

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

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

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

~/.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.