# Phase 3: Operator Experience - Context

**Gathered:** 2026-03-24
**Status:** Ready for planning

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

</domain>

<decisions>
## 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)

</decisions>

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

</specifics>

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

</code_context>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope

</deferred>

---

*Phase: 03-operator-experience*
*Context gathered: 2026-03-24*