docs: Phase 8 documentation - Gitea, Obsidian, Outline, Vikunja, map (AUD-74)
- 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
This commit is contained in:
Documenter
143
docs/outline/04-agent-runbook.md
Normal file
143
docs/outline/04-agent-runbook.md
Normal file
@@ -0,0 +1,143 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user