email_agent/docs/phase8-documentation.md

Phase 8 — Documentation

Status: complete. Ran the project-docs skill (Simplified Technical English) and updated all five documentation surfaces. Parent AUD-68. Phase 8 of AGENTS.md §11. Task 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

# 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>.