Phase 1: Parent-control web UI (mobile-responsive) for v0 demo

[hanwencheng]

Context

Without the parent-control UI, Act 3 of the M1 three-act demo (revocation) is invisible — the parent has no surface to revoke from, and the audience watching the demo can't see the authority action happen. The demo reads as "smart chatbot," not as "Agent IAM."

This UI is the consumer face of AgentKeys for M1. It's mobile-responsive web (not native — native is M5, after a paying vendor pilot signs). The bet is: a web UI that's good enough to demo on a phone proves the UX premise; once vendor pilot confirms demand, M5 ships native.

Per agent-iam-strategy.md §6 Risk 3: a weak consumer face kills the Pro-tier upgrade economics. Even at M1, the parent has to see something tangible.

Scope (M1)

Pages

Page	Purpose
Actor list	Devices bound to this user's actor tree (per arch.md §6.2 HDKD tree). One row per device: name, vendor, last-active, status indicator.
Actor detail	Per-actor scope toggles: read/write per namespace (personal/family/work/travel), payment cap config, time-window limits.
Revoke	Per-cap-token, per-actor, per-scope revoke buttons. One-tap revocation that propagates via #109's Tier 1 feed.
Audit feed	Real-time (Tier 1) event stream from #109. Latest 50 events with timestamp + actor + event-type chips. Click any row for detail.
Anchor status	Link to chain explorer showing Tier 2's latest 2-min batch root. No embed — just a "Anchored ✓ HH:MM" badge with explorer link.

Stack

• Framework: Next.js (recommended) or SvelteKit. Pick what the engineer is fastest in. Prefer Next.js for community-size + Vercel deploy ease.
• Deploy: Vercel for v0 — easier for early UI iteration. Move to demo-host bundle in M2 if vendor latency/region demands it.
• Auth: session JWT from broker (K6 per arch.md §4 K-key inventory). Standard cookie-based auth; refresh via K11 WebAuthn for sensitive actions (revocation, payment).
• Real-time: SSE consumer of audit-service Tier 1 feed (Phase 1: Two-tier audit wiring (real-time off-chain feed + 2-min on-chain anchor) #109). One persistent connection per session.
• Mobile-first: must work in iPhone Safari + Chrome Android + desktop. Tailwind responsive grid + touch-friendly tap targets.

Out of scope (defer)

• Native iOS / Android — M5 only after vendor pilot
• Family / work / kids namespace separation UX — M4 with the delegation depth work
• Audit replay (timeline scrubbing, historical reconstruction) — M4
• Vendor branding / white-label — M2 (vendor onboarding portal handles per-vendor branding hooks)
• Approval workflow UI (one-tap-approve for high-risk actions) — M4

Acceptance criteria

• Demo Act 3 succeeds: parent taps "Revoke FoloToy payment access" → next device attempt fails immediately on online cap-token check (per Phase 1: Parent-control web UI (mobile-responsive) for v0 demo #110 / revocation work)
• Real-time audit feed updates within 200ms of an authority event (verified against Phase 1: Two-tier audit wiring (real-time off-chain feed + 2-min on-chain anchor) #109 Tier 1 SSE)
• Works in iPhone Safari (latest 2 versions), Chrome Android (latest 2), desktop Chrome / Safari / Firefox
• Lighthouse mobile score ≥ 90 for Performance + Accessibility
• Session JWT auth tested: expired → redirect to login; revoked-by-parent-side → audit row + force logout
• One-tap revocation requires WebAuthn re-auth (K11) — proves the parent (not a session hijacker) authorized the action
• Three-act demo runbook (Phase 1: Three-act demo runbook + 15-min vendor pitch script #111) confirms the UI cooperates with the demo flow end-to-end

Risks

Risk	Mitigation
Web UI feels less "real" than native — vendors discount the demo	Lead with the live SSE feed (the "wow"); the UI moves immediately, beats most native apps' polling
SSE drops on iOS mobile when browser backgrounds	Auto-reconnect + back-fill from #109 ring buffer on resume
Tailwind + Next.js boilerplate eats day 1-2	Use a clean starter (e.g. Vercel Next.js template + shadcn/ui); don't roll bespoke UI primitives

References

• docs/spec/plans/milestones-roadmap.md §2 (M1 scope)
• docs/research/agent-iam-strategy.md §4.4 (Phase 1 deliverables), §6 Risk 3 (weak consumer face)
• docs/arch.md §4 (K-keys — K6 session JWT, K11 WebAuthn), §6.2 (HDKD actor tree the UI renders)
• Phase 1: AgentKeys MCP server — 7 active tools + 3 schema-only #107 (MCP server — UI may also call its permission.check for the toggle preview)
• Phase 1: Two-tier audit wiring (real-time off-chain feed + 2-min on-chain anchor) #109 (Tier 1 audit feed — primary data source for the UI)

Effort

~3-4 days for a v0 demo-quality UI. Sequencing:

1. (Day 1) Next.js skeleton + Tailwind + shadcn/ui + auth via session JWT
2. (Day 2) Actor list + actor detail with scope toggles (read-only first)
3. (Day 3) Revocation flow (with K11 WebAuthn re-auth) + SSE audit feed
4. (Day 4) Mobile polish + Lighthouse pass + cross-browser test

Pickup notes for the next agent / developer

• Read agent-iam-strategy.md §4.3 (storyboard) so you know what Act 3 has to feel like
• Then agent-iam-strategy.md §4.4 (deliverables) for the full Phase 1 deliverable list
• Existing session JWT issuance lives in crates/agentkeys-broker-server/src/handlers/ — auth shape is documented in arch.md §4 (K6 row)
• WebAuthn re-auth for revocation: see arch.md §10 ceremonies for K11 binding shape
• Watch for: don't gold-plate the UI. M1 is a demo; M2 vendor pilot ships the polished version. Aim for "5-minute pitch reads as Agent IAM, not chatbot" — that's the bar.
• Don't: write a backend in the Next.js project. All data comes from the existing broker + audit-service via SSE; the UI is a thin client.
• The 4 default namespaces (personal/family/work/travel from Phase 1: Memory namespace model — wire to cap-token + worker filter #108) are an enum — render as checkbox grid, not free-text input