diff --git a/.planning/phases/03-operator-experience/03-CONTEXT.md b/.planning/phases/03-operator-experience/03-CONTEXT.md new file mode 100644 index 0000000..ec8a3bd --- /dev/null +++ b/.planning/phases/03-operator-experience/03-CONTEXT.md @@ -0,0 +1,105 @@ +# Phase 3: Operator Experience - Context + +**Gathered:** 2026-03-24 +**Status:** Ready for planning + + +## Phase Boundary + +Operators can connect messaging channels (Slack via OAuth, WhatsApp via guided setup), onboard through a guided wizard, manage subscriptions via Stripe (per-agent monthly pricing with 14-day trial), provide their own LLM API keys, and view agent cost/usage metrics — all through the existing portal UI. Phase 3 builds on the portal foundation from Phase 1 (tenant CRUD, Agent Designer, Auth.js v5). + + + + +## Implementation Decisions + +### Channel Connection Wizard +- Slack connection via standard OAuth2 "Add to Slack" flow — operator clicks button, authorizes, tokens stored automatically +- WhatsApp connection: Claude's discretion (guided manual setup or embedded signup — whichever is practical for v1) +- After connecting a channel, the wizard MUST include a "send test message" step — required, not optional +- Test message verifies end-to-end connectivity before the agent goes live + +### Onboarding Flow +- Onboarding sequence: Connect Channel → Configure Agent → Send Test Message +- Agent goes live automatically after the test message succeeds — no separate "Go Live" button +- Stepper UI / progress indicator: Claude's discretion +- Onboarding target: complete in under 15 minutes (from roadmap success criteria) + +### Billing & Pricing +- Pricing model: per-agent monthly (e.g., $49/agent/month) — matches the "hire an employee" metaphor +- 14-day free trial with full access, credit card required upfront +- Subscription management via Stripe: subscribe, upgrade (add agents), downgrade (remove agents), cancel +- Enforcement on non-payment: Claude's discretion (agent deactivation recommended — clean, not punitive) +- LLM-03 resolved: BYO API keys IS in v1 scope (Phase 3) +- BYO key management: Claude's discretion (settings page vs per-agent — settings page simpler for v1) + +### Cost Dashboard +- Metrics displayed: token usage per agent, cost breakdown by LLM provider, message volume per agent/channel, budget alerts +- Budget alerts: visual indicator when approaching or exceeding per-agent budget limits (from AGNT-07) +- Time range selector: Claude's discretion +- Dashboard lives in the portal as a dedicated section + +### Claude's Discretion +- WhatsApp connection method (guided manual vs embedded signup) +- Stepper UI for onboarding (yes/no, visual style) +- Non-payment enforcement behavior +- BYO key scope (tenant-level settings page vs per-agent) +- Cost dashboard time range options +- Dashboard chart library (recharts, nivo, etc.) +- Stripe webhook event handling strategy (idempotency, retry) + + + + +## Specific Ideas + +- The "per-agent monthly" pricing reinforces the "hire an employee" brand — operators think in terms of headcount, not API calls +- The 14-day trial should feel generous — full access to everything, no artificial limits +- Channel connection should feel like the easiest part — one click for Slack, guided steps for WhatsApp +- Cost dashboard should answer "how much is this employee costing me?" at a glance — like a payroll view + + + + +## Existing Code Insights + +### Reusable Assets +- `packages/portal/` — Full Next.js 16 portal with Auth.js v5, tenant CRUD, Agent Designer +- `packages/portal/lib/auth.ts` — Auth.js v5 Credentials provider with JWT strategy +- `packages/portal/lib/api.ts` — API client for FastAPI backend +- `packages/portal/lib/queries.ts` — TanStack Query hooks for tenant/agent CRUD +- `packages/portal/components/agent-designer.tsx` — Agent Designer form with all fields +- `packages/shared/shared/api/portal.py` — FastAPI portal router (11 endpoints) +- `packages/shared/shared/models/tenant.py` — Tenant and Agent SQLAlchemy models +- `packages/shared/shared/models/audit.py` — AuditEvent model (source for cost/usage data) +- `packages/orchestrator/orchestrator/audit/logger.py` — Audit logger (logs LLM calls, tool invocations) +- `packages/shared/shared/config.py` — Centralized settings + +### Established Patterns +- Portal pages: App Router with `(dashboard)` route group, TanStack Query for data fetching +- API endpoints: FastAPI router in `shared/api/portal.py` +- Auth: Auth.js v5 JWT with Credentials provider +- Forms: react-hook-form + zod + standardSchemaResolver +- Components: shadcn/ui +- Proxy: `proxy.ts` (Next.js 16 pattern, not middleware.ts) + +### Integration Points +- Portal needs new pages: channel wizard, onboarding flow, billing management, cost dashboard +- FastAPI needs new endpoints: channel connection (OAuth callback), Stripe webhooks, usage aggregation +- Agent model needs: `is_active` field for subscription enforcement +- Tenant model needs: `stripe_customer_id`, `subscription_status`, `trial_ends_at` fields +- New DB table or extension for BYO encrypted API keys + + + + +## Deferred Ideas + +None — discussion stayed within phase scope + + + +--- + +*Phase: 03-operator-experience* +*Context gathered: 2026-03-24*