136 lines
6.5 KiB
Markdown
136 lines
6.5 KiB
Markdown
# Phase 8 — Documentation
|
||
|
||
Status: **complete.** Ran the `project-docs` skill (Simplified Technical
|
||
English) and updated all five documentation surfaces. Parent
|
||
[AUD-68](/AUD/issues/AUD-68). Phase 8 of AGENTS.md §11. Task
|
||
[AUD-74](/AUD/issues/AUD-74).
|
||
|
||
**DoD:** project-docs run; Gitea, Obsidian, Outline, Vikunja, and the map are
|
||
updated. — **met.** Evidence for each surface is below.
|
||
|
||
## 1. Surfaces updated
|
||
|
||
| Surface | Destination | What changed |
|
||
| :--- | :--- | :--- |
|
||
| Gitea | `sam/email_agent` (repo) | README refreshed (architecture diagram, Phase 8 status, Phase 7 endpoints, retention vars, documentation index). Added `docs/outline/` (5 AI-context docs), `docs/vikunja-tasks.json`, `docs/email-agent-architecture.mmd`, `docs/diagrams/email-agent-architecture.png`, `docs/archify/email-agent.architecture.json`, `docs/email-agent-map.html`. |
|
||
| Obsidian | Vault `010 inbox` on `.27` | New note `Email Agent — Family Inbox Triage.md` (human overview, portfolio highlights, Mermaid, links). The `obsidian-sorter` watcher proposes the final folder. |
|
||
| Outline | `outline.lab.audasmedia.com.au` | New collection `Email Agent` (`f096RBNsbV`) with five documents: AI index, system overview, configuration, code map, runbook. |
|
||
| Vikunja | `vikunja.lab.audasmedia.com.au` | New project `Email Agent` (id 17) with seven completed human milestones (task ids 179–185). |
|
||
| Map | `central_ai_llm_master/docs/` | `hub-architecture.mmd` and the Archify IR now show the Email Agent as a live peer. `hub-architecture-map.html` re-delivered, `diagrams/hub-architecture.png` re-rendered, and `routing.md` marks `email_agent` an active service. |
|
||
|
||
## 2. Gitea
|
||
|
||
Repo: `ssh://git@gitea.lab.audasmedia.com.au:2222/sam/email_agent.git`.
|
||
|
||
- `README.md` — status is now "complete and deployed" for all eight phases. Adds
|
||
the Mermaid architecture diagram, the Phase 7 Hub API and Reports endpoints,
|
||
the retention variables, and a Documentation section.
|
||
- `docs/outline/00-index.md` — the AI document index.
|
||
- `docs/outline/01-system-overview.md` — purpose, architecture, FR map, phase
|
||
status.
|
||
- `docs/outline/02-config-and-env.md` — environment variables, paths, ports.
|
||
- `docs/outline/03-code-map.md` — folders, flags, routes, schema, tests.
|
||
- `docs/outline/04-agent-runbook.md` — test, deploy, restart, rollback.
|
||
- `docs/vikunja-tasks.json` — the Vikunja project id and task ids.
|
||
- `docs/email-agent-architecture.mmd` and `docs/diagrams/email-agent-architecture.png`.
|
||
- `docs/archify/email-agent.architecture.json` and `docs/email-agent-map.html`.
|
||
|
||
The Archify map passed the **showcase** profile: 9 of 9 checks, 0 errors,
|
||
0 warnings. The Mermaid diagram rendered with `mmdc` (no errors).
|
||
|
||
## 3. Obsidian
|
||
|
||
Written over SSH to `.27`:
|
||
|
||
```
|
||
/home/sam/obsidian/010 inbox/Email Agent — Family Inbox Triage.md
|
||
```
|
||
|
||
The note uses the generic inbox template (`type: note`) with `project` and
|
||
topic tags. It holds a plain-language explanation, the portfolio highlights,
|
||
a Mermaid diagram, and links to Gitea, the map, Outline, and Vikunja. No folder
|
||
and no note type were chosen; the `obsidian-sorter` watcher proposes both and
|
||
Sam approves.
|
||
|
||
## 4. Outline
|
||
|
||
Collection `Email Agent`, id `ccb6b59b-2bf6-4946-8dca-5b6da95f768a`, url id
|
||
`f096RBNsbV`.
|
||
|
||
| Document | Id |
|
||
| :--- | :--- |
|
||
| Email Agent — AI Document Index | `d1025188-6640-4f3d-8e46-41439faed342` |
|
||
| Email Agent — System Overview | `cdcdf640-425b-42ad-843c-96d58ead81a2` |
|
||
| Email Agent — Configuration and Environment | `1a239b9c-63a4-4a5e-9c12-56626c4d2d07` |
|
||
| Email Agent — Code Map | `924617ea-47fd-4ab4-9eef-e2dfc7c3f854` |
|
||
| Email Agent — Agent Runbook | `e745a791-1c07-4ad4-bc30-6a4f6119dceb` |
|
||
|
||
The documents are the same files as `docs/outline/` in the repo. The index
|
||
itemizes every document so an AI agent can inject the exact file.
|
||
|
||
## 5. Vikunja
|
||
|
||
Project `Email Agent`, id 17.
|
||
|
||
| Task id | Title | Done |
|
||
| :--- | :--- | :--- |
|
||
| 179 | Build and deploy phases 1–7 | yes |
|
||
| 180 | Deploy on `.13` behind Caddy | yes |
|
||
| 181 | Gitea README, Mermaid, Archify, publish maps | yes |
|
||
| 182 | Outline collection `Email Agent` | yes |
|
||
| 183 | Obsidian note in `010 inbox` | yes |
|
||
| 184 | 1-month retention and `actions_log` cap (AUD-75) | yes |
|
||
| 185 | Confirm the Gmail send-as identity (FR-15) | yes |
|
||
|
||
The repo copy is `docs/vikunja-tasks.json`.
|
||
|
||
## 6. The map
|
||
|
||
`central_ai_llm_master/docs/` is the Hub's map. The Email Agent now appears as
|
||
a live peer:
|
||
|
||
- `docs/hub-architecture.mmd` — added `EMAIL["Email Agent<br/>inbox triage"]`
|
||
and `HUB -- "ask only (query)" --> EMAIL`.
|
||
- `docs/archify/hub.architecture.json` — added the `email` component and the
|
||
`to-email` relationship; the profile is `standard` (the existing Hub map was
|
||
already a standard-quality map — it fails the stricter showcase profile).
|
||
- `docs/hub-architecture-map.html` — re-delivered: 9 of 9 checks, 0 errors,
|
||
30 warnings.
|
||
- `docs/diagrams/hub-architecture.png` — re-rendered from the updated Mermaid.
|
||
- `routing.md` — the `email, inbox, mail, message, unread` row is now
|
||
`active service`, and `email_agent` is removed from the placeholder table.
|
||
|
||
The Email Agent's own map is published to
|
||
`https://maps.lab.audasmedia.com.au/email_agent/docs/`, and the Hub map to
|
||
`https://maps.lab.audasmedia.com.au/central_ai_llm_master/docs/`.
|
||
|
||
## 7. Commands used
|
||
|
||
```sh
|
||
# Mermaid
|
||
mmdc -i docs/email-agent-architecture.mmd -o docs/diagrams/email-agent-architecture.png --scale 2 -b white
|
||
|
||
# Archify (validate then deliver)
|
||
node ~/.agents/skills/archify/bin/archify.mjs validate architecture docs/archify/email-agent.architecture.json --quality showcase --json
|
||
node ~/.agents/skills/archify/bin/archify.mjs deliver architecture docs/archify/email-agent.architecture.json docs/email-agent-map.html --quality showcase --json
|
||
|
||
# Publish to the LAN maps site
|
||
~/.agents/skills/project-docs/scripts/publish-maps.sh /home/sam/paseo/projects/email_agent
|
||
~/.agents/skills/project-docs/scripts/publish-maps.sh /home/sam/paseo/projects/central_ai_llm_master
|
||
```
|
||
|
||
## 8. Not done / notes
|
||
|
||
- The Obsidian note is in the inbox. The sorter, not this phase, chooses the
|
||
final folder. Sam approves the proposal in Obsidian.
|
||
- Vikunja bucket (stage) placement uses the API default views. The tasks carry
|
||
their done flags; a human can drag them if a stage is wanted.
|
||
- 1-month retention is covered by AUD-75 (commit `e5cce1c`), not by this phase.
|
||
- The project-docs role says a note is finished only when its path is named in
|
||
the task. This file and the summary comment name each path.
|
||
|
||
## 9. Commit
|
||
|
||
Docs commit for this phase: `c5760db` (Phase 8 documentation). The follow-up
|
||
commit that records this hash is the one that contains this line.
|