docs(plans): Agent UI v2 thin-host implementation breakdown

[kovtcharov]

Why this matters

The v2 sidecar-first architecture (#1913) is signed-in design, but nothing yet tells an implementer where to start, what's reusable vs. net-new, or which unsigned decisions block which work — so the build can't be parallelized or even safely begun. This adds the implementation decomposition: a code-verified delta table for every v2 building block, 19 sequenced issue proposals (with acceptance criteria, dependencies, S/M/L sizes — proposals only, none filed), a specced first vertical slice (headless daemon + supervised email sidecar + /query streamed to the CLI), and the three sign-off decisions (§0.4 confirmation model, §0.9 custody home, §0.24 containment 🔒) as explicit questions.

It also pins verified design-vs-merged deviations so implementers don't trip on them: gaia api still mounts email in-process (the pattern #1910 removed from the UI only), the only scheduler on main is UI-internal (PR #1566 — gaia schedule/PR #1371 is unmerged), and contract 2.1 has no /query, no auth (#1706), and no /shutdown.

Test plan

• Docs-only — no code paths touched
• Spot-check the delta table's file/LoC claims against main @ 080e7259 (all were verified while writing)
• Confirm the issue proposals don't duplicate existing open issues (checked: Harden the email sidecar's local REST API with caller authentication #1706, [packaging] Agent UI consumes @amd-gaia/agent-email sidecar (dogfood validation) #1653, [Epic] Email in Agent UI via the frozen sidecar (user/dev modes) — supersedes #1767 #1896, Hub: catalog schema v2 — type field + Apps/Components/Agents lanes #1717 are linked, not duplicated)

[github-actions]

Verdict: Approve

This is a docs-only PR adding one planning document — the implementation decomposition for the v2 thin-host/sidecar architecture (delta table, 19 sequenced issue proposals, a first vertical slice, and three sign-off decisions). No code paths are touched, so there's nothing to break at runtime.

The standout here is that the claims are actually verified against main, not asserted: I spot-checked the LoC figures, file paths, and line references and they hold up. The "corrections to the design doc" section is genuinely valuable — it pins the design-vs-merged deviations (email still mounted in-process on gaia api, no gaia schedule on main, contract 2.1 has no /query/auth//shutdown) so an implementer doesn't build against stale design text.

Only nit: one small factual imprecision about the email OpenAPI contract (it describes it as declaring an empty security array when the field is simply absent). Substantively identical — no auth either way — so it doesn't block. Nothing else worth holding the merge for.

🔍 Technical details

Verification performed (all pass):

• Referenced files all exist: proxy_agent.py, manager.py, fetch.py, platform.py, scheduler.py, routers/schedules.py, openapi.email.json, openai_server.py, and the four sibling plan docs.
• LoC claims are exact: proxy_agent.py 330, manager.py 498, scheduler.py 1231, server.py 909, sse_handler.py 1307 — all match.
• openai_server.py in-process email mount claim (correction 1) is accurate: the find_spec("gaia_agent_email") gate + app.include_router(email_router) sits at ~135–143.
• cli.py:4786 delegates to gaia_agent_email.cli:main in-process, exactly as the doc's V2-8 self-correction of §0.23 states.
• openapi.email.json has 16 paths — matches "16 deterministic /v1/email/* routes."
• docs.json registration: not required. The design-doc sibling agent-ui-agent-capabilities-plan.md is itself unregistered in nav, so this breakdown following the same pattern is consistent, not an omission.

🟢 Minor — OpenAPI security claim slightly imprecise (agent-ui-v2-implementation-breakdown.md, correction 3 and delta row 10)
The doc says schema-2.1 "declares 16 deterministic /v1/email/* routes with securitySchemes: []". The contract has 16 paths, but components.securitySchemes is absent, not an empty array. The conclusion (no auth on the sidecar today) is correct — this is wording only. Suggest "with no securitySchemes declared" to avoid an implementer grepping for a [] that isn't there.

Strengths

• Code-grounded rather than aspirational — the delta table's exists/partial/net-new split and the "corrections" section reflect the actual repo state at 080e7259, which is exactly what makes a decomposition safe to parallelize against.
• Correctly labels the issues as proposals-not-filed and confirms non-duplication of Harden the email sidecar's local REST API with caller authentication #1706/[packaging] Agent UI consumes @amd-gaia/agent-email sidecar (dogfood validation) #1653/[Epic] Email in Agent UI via the frozen sidecar (user/dev modes) — supersedes #1767 #1896/Hub: catalog schema v2 — type field + Apps/Components/Agents lanes #1717, avoiding issue-tracker noise.
• Handles the security-sensitive containment/trust-root decisions (D3) at the right altitude — flags 🔒 and recommends a private advisory rather than spelling out threat specifics in a public doc.
• Bakes GAIA's own conventions into the proposed acceptance criteria (the feat(agent-email): auto-reap sidecar on parent exit/crash (no manual wiring) #1841 "update all doc surfaces together" rule for V2-2, cold-state testing for V2-13/V2-16, serial-eval + baseline compare for V2-10) — the plan enforces the repo's rules on itself.