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

<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 Ideas

None — discussion stayed within phase scope

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

4.9 KiB Raw Blame History