# 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: `<pending>`.