docs: Phase 7 complete - summary email delivered and Hub registered (AUD-73)

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-10-13 10:37:23 +11:00
parent 9f5e60039d
commit 55a08524b5
1 changed files with 86 additions and 27 deletions
--- a/docs/phase7-summary-hub.md
+++ b/docs/phase7-summary-hub.md
@@ -1,15 +1,14 @@
 # Phase 7 — Summary and Hub

-Status: **built, tested, deployed on `.13`, and the project side of the DoD is
-demonstrated against real mail.** Two items wait on Sam's explicit approval: the
-real summary email (Apprise key) and registering this project with the running
-Hub. Parent [AUD-68](/AUD/issues/AUD-68). Phase 7 of AGENTS.md §11. Code commit
-`a349b42`.
+Status: **complete.** Built, tested, deployed on `.13`. Both approval-gated
+steps are done: the daily summary was delivered by email through the house
+Apprise API, and `email_agent` is registered with the running Hub. Parent
+[AUD-68](/AUD/issues/AUD-68). Phase 7 of AGENTS.md §11. Code commit `a349b42`,
+docs commit `9f5e600` plus this completion update on top.

 **DoD:** the Hub asks "anything important in my inbox?" and gets a correct short
-answer. — the Hub contract round-trip works (§2.1). Wiring the live Hub requires
-a shared token and a Hub restart, which is outside the "do not touch other
-projects" rule for this pass (see §7).
+answer. — **met end to end.** The live Hub routed the question to `email_agent`
+and returned the correct short answer (§2.6).

 ## 1. What was built

@@ -148,7 +147,7 @@ for the message, classification, action-log, and summary counts.
 ### 2.4 Daily-summary-by-email path

 `docker exec email-agent email-agent -summary` produced and stored the summary
-(row `id=1`, date `2026-10-11`, 1110 bytes, `delivered_to` empty):
+(row `id=1`, date `2026-10-11`, 1110 bytes, `delivered_to` empty at build time):

 ```
 Email Agent — daily summary for 2026-10-11
@@ -171,8 +170,28 @@ Spam (recommend, never auto-delete): 1

 `-summary-send` with no Apprise key stops before sending:
 `summary failed: apprise is not configured: set APPRISE_URL and APPRISE_KEY (or
-APPRISE_URLS)`. **No summary email has been sent.** A real send waits on Sam's
-approval and an Apprise key (§7).
+APPRISE_URLS)`.
+
+**Real send (approved).** Sam approved one real summary email and the house
+Apprise destination. `APPRISE_URLS` on the container was set to the shared
+mailto destination, then `-summary-send` ran once:
+
+```
+summary delivered id=1 to=samuelrolfe@gmail.com
+```
+
+Evidence: the stored row reports `delivered_to=samuelrolfe@gmail.com`, and the
+Apprise container on `.35` logged the delivery and answered `200`:
+
+```
+2026-10-11 07:16:20,853 [INFO] apprise: Applying Google Mail Defaults
+2026-10-11 07:16:25,505 [INFO] apprise: Sent Email to samuelrolfe@gmail.com
+2026-10-11 07:16:25,806 [INFO] django: NOTIFY -  - Delivered Stateless Notification(s)
+192.168.20.13 - - [11/Oct/2026:12:16:25 +0000] "POST /notify HTTP/1.1" 200 104 "-" "Go-http-client/1.1"
+```
+
+The recipient was `EMAIL_AGENT_SUMMARY_TO` (`samuelrolfe@gmail.com`). No other
+summary has been sent.

 ### 2.5 Automated tests

@@ -188,6 +207,41 @@ approval and an Apprise key (§7).
 | `internal/config` | Hub/Apprise defaults, `HubConfigured`, `AppriseConfigured`, URL-list parsing |
 | `internal/server` | capabilities auth + shape, ask auth, ask answer, **ask writes nothing**, reports page auth, generate stores without sending, send delivers through Apprise, CSRF |

+### 2.6 Live Hub registration and end-to-end round-trip
+
+Sam approved registering this project with the running Hub. The changes are host
+configuration only (no image change):
+
+- `HUB_PROJECT_EMAIL_AGENT_TOKEN=<HUB_TOKEN>` and
+  `HUB_PROJECTS=email_agent=http://192.168.20.13:8790` were added to
+  `~/.config/environment.d/10-secrets.conf` (mode 600, backup
+  `10-secrets.conf.bak.aud73-*`). The Hub mounts this file read-only and reads
+  `HUB_PROJECTS` from it.
+- The `hub` container was restarted to pick up the registration. It came back
+  `healthy`; `GET /health` → `200`.
+
+End-to-end proof, against the live Hub on `.13` (`POST /ask` with the console
+door token and `source: "console"`):
+
+```
+POST http://192.168.20.13:8788/ask
+{"text":"anything important in my inbox?","asker":"sam","source":"console"}
+
+200 {"status":"ok",
+     "answer":"20 emails need your attention, including \"Security alert\" from Google.",
+     "shape":"text",
+     "route":{"kind":"project","project":"email_agent"}}
+```
+
+The Hub chose `email_agent`, and the answer matches the project's own `/ask`.
+The project endpoint is still token-protected: no token or a wrong token returns
+`401` (§2.1).
+
+Note: `central_ai_llm_master/routing.md` still lists `email_agent` with the
+"placeholder — not built" status. Routing works regardless, because the Hub
+reads live `/capabilities` first. Updating that human-owned row to `active` is a
+cosmetic follow-up in the Hub repo, outside this phase's change set.
+
 ## 3. Configuration

 New environment variables (names only; values live in
@@ -227,25 +281,30 @@ The migration-free change started in place on the Phase 1–6 volume
 2. No schema change to undo. The `summaries` table rows and the `HUB_TOKEN`
   secret are left in place; remove the token from the secrets file if the Hub
   API must be disabled.
-3. The Reports screen, `/capabilities`, and `/ask` disappear with the revert;
-   the running Hub is unaffected because it is not yet registered.
+3. The Reports screen, `/capabilities`, and `/ask` disappear with the revert.
+   The Hub registration now exists; remove `HUB_PROJECTS` and
+   `HUB_PROJECT_EMAIL_AGENT_TOKEN` from the secrets file and restart `hub` to
+   undo it.

 ## 6. Not done / deferred

- **1-month body retention** (§7) is still not implemented.
- The Hub's `/notify` receiver does not exist yet in the Hub v1, so the outbound
+- **1-month body retention** (AGENTS.md §7) is still not implemented. It is a
+  data-model rule, not part of the Phase 7 DoD; it remains project backlog.
+- The Hub's `/notify` receiver does not exist yet in Hub v1, so the outbound
  path is verified against a stub, not the live Hub.
- The Hub routing decision is LLM-based (`understand.OmniRouter`). This pass did
-  not run the Hub pipeline, to respect "the Hub endpoints are the only external
-  calls" — no OmniRoute routing call was made.
+- `routing.md` still labels `email_agent` a placeholder (see §2.6). The live Hub
+  routes correctly from `/capabilities` regardless.

-## 7. Waiting on Sam (two approvals)
+## 7. Approvals and execution

-1. **Real summary email.** Provide the Apprise key (or URLs) and approve one
-   real send for evidence. Until then no summary email is sent.
-2. **Register this project with the Hub.** Add
-   `HUB_PROJECT_EMAIL_AGENT_TOKEN=<HUB_TOKEN>` and
-   `HUB_PROJECTS=email_agent=http://192.168.20.13:8790` to the Hub's environment
-   and restart the `hub` container. This touches a running family service, so it
-   needs Sam's yes. After that the Hub can route "anything important in my
-   inbox?" through `routing.md` to this project.
+Both approval-gated steps were approved by Sam (interaction
+`73a5494e-e054-4cf9-aa9e-7b8a17295002`): `approve-house` for one real summary
+email and `wire-now` for the Hub registration. Both are now executed:
+
+1. **Real summary email** — sent through the house Apprise API on `.35`; the
+   delivery is recorded in §2.4.
+2. **Hub registration** — the shared token and `HUB_PROJECTS` are in the host
+   secrets file and the Hub was restarted; the end-to-end round-trip is recorded
+   in §2.6.
+
+The `routing.md` status row is the only cosmetic leftover; see §2.6 and §6.