FrontDeskOS — Platform Documentation

FrontDeskOS is an AI-powered "virtual team" platform for solo SaaS founders. It deploys 5 specialized AI agents — Sales, Customer Success, Marketing, Product Manager, and Developer — orchestrated by a Founder's Meta Agent that acts as a virtual Chief of Staff.

1. Getting Started

Registration & Login

Register at /register with:

• Name (min 2 characters)
• Email (valid format, unique)
• Password (min 8 characters, must include uppercase, lowercase, and a number)

After registration, you are automatically logged in and redirected to the dashboard.

Login at /login with email and password. The system includes brute-force protection:

• 5 failed attempts triggers a 15-minute lockout
• Failed attempts are tracked in Redis and cleared on successful login

Token system:

• Access token: 15-minute expiry (used for all API requests)
• Refresh token: 7-day expiry (used to get new access tokens)
• Tokens are automatically refreshed by the frontend

Two-Factor Authentication (TOTP)

Enable 2FA from Settings > Security:

1. Setup: Generate a TOTP secret and QR code
2. Verify: Scan QR code with an authenticator app (Google Authenticator, Authy, etc.) and enter the 6-digit code
3. Recovery codes: 8 one-time recovery codes are generated — store these safely
4. Login with TOTP: After entering email/password, you'll be prompted for a TOTP code or recovery code

You can disable TOTP at any time by verifying your current code.

Onboarding & Business Profile

After first login, complete your business profile in Settings > Business Profile:

This context is used by all AI agents to personalize their output — emails, briefings, recommendations, and more.

2. Dashboard

The main dashboard (/dashboard) provides an at-a-glance overview of your virtual team:

• Agent cards for each of the 6 agents with key metrics
• Quick navigation to each agent's dedicated page
• Notification bell with unread count in the header
• User menu for profile, settings, and logout

Navigation sidebar (desktop) or bottom bar (mobile):

• Dashboard, Briefing, each Agent page, Chat, Notifications, Settings

3. Atlas Reed — Meta Agent (Chief of Staff)

AI Model: Claude Opus 4.6 (most capable model) Token Budget: 100,000 tokens/period (highest allocation)

Atlas Reed is your virtual Chief of Staff. He synthesizes data from all agents, generates strategic briefings, and helps you prioritize what matters most.

Weekly Briefings

Navigate to /briefing or generate from the Meta Agent page.

What a briefing contains:

How to generate:

1. Click "Generate Briefing" on the Briefing page
2. Optionally provide a founder directive (e.g., "Focus on enterprise pipeline this week")
3. The briefing is generated asynchronously — progress shown via WebSocket
4. Review, edit, and approve the briefing

Briefing types:

• Weekly — Full strategic overview
• Daily Nudge — Quick daily priorities
• Friday Retro — End-of-week retrospective

Priorities

Each briefing generates 3 ranked priorities. You can:

• Mark as completed — Logs completion timestamp
• Defer — Push to next cycle
• Edit — Update title or description
• Delete — Remove entirely

Priority statuses: ACTIVE, COMPLETED, DEFERRED

Assumption Tracking

Track and validate your business hypotheses:

1. Create an assumption — e.g., "Solo founders will pay $49/mo for AI sales automation"
2. Track status: UNTESTED → TESTING → VALID / AT_RISK / KILLED
3. Add evidence — JSON notes about what you've learned
4. Atlas references assumptions in briefings and strategic advice

Ask Meta

Chat directly with Atlas for strategic advice:

1. Ask a question: "Should I focus on outbound or inbound sales this quarter?"
2. Atlas builds context from: current briefing, priorities, assumptions, agent statuses, your goals
3. Returns a structured response:
   • Recommendation: YES / NO / MAYBE
   • Reasoning: 2-4 sentence explanation
   • Considerations: Key factors
   • Suggested Next Step: One actionable item

Agent Health Monitoring

The Meta dashboard shows health status for all agents:

• Healthy: Active within the last hour
• Degraded: Active within the last 24 hours
• Offline: Inactive for 24+ hours or disabled

Scheduled Jobs

Configure automated briefing schedules:

• Weekly briefing — Cron-based (e.g., every Monday at 9 AM)
• Daily nudge — Quick morning priorities
• Friday retro — End-of-week review
• All schedules are timezone-aware and can be enabled/disabled

4. Sterling Chase — Sales Agent (CSO)

AI Model: Claude Sonnet 4.5 (standard), Claude Haiku 4.5 (lead qualification)

Sterling Chase is your Chief Sales Officer. He manages your sales pipeline, automates email outreach, qualifies leads, and provides data-driven strategy.

Lead Management

Navigate to Sales > Leads tab.

Creating a lead:

• Manually add: name, email, company, source, phone, website, notes, estimated value
• System auto-calculates an initial completeness score (0-100) based on data filled:
  • Company: +10, Source/Email/Phone/Website/Notes: +5 each (max 35, normalized to 100)
• Lead starts at NEW stage, ACTIVE status

Lead stages (pipeline progression):

NEW → CONTACTED → QUALIFIED → PROPOSAL → NEGOTIATION → CLOSED_WON / CLOSED_LOST

Lead detail page (/agents/sales/leads/:id) shows:

• Profile card with score, stage, and company info
• Engagement metrics: days in stage, touch count, engagement score, response time
• Email stats: sent, delivered, opened, clicked, replied, bounced (with rates)
• Active sequences: progress through enrolled email sequences
• Conversation thread: inbound/outbound email history
• Activity timeline: chronological event feed
• Notes: custom notes field

Lead Qualification (AI)

Qualify leads to score and categorize them:

1. Click "Qualify" on a lead (or use auto-qualify on import)
2. AI evaluates: company size match, role relevance, engagement signals, data completeness
3. Weighted score: Completeness (20%) + AI Score (80%) = Final Score (0-100)
4. AI suggests a pipeline stage based on the score
5. Lead updated with new score and stage

Models used:

• Haiku (fast, cost-effective) for qualify-lead-lite
• Sonnet (more capable) for full qualify-lead with admin context

Pipeline View

Navigate to Sales > Pipeline tab.

Visual pipeline board grouped by stage:

• Each column shows leads in that stage
• Displays lead count and total estimated value per stage
• Ordered by creation date (newest first)

Email Sequences

Navigate to Sales > Sequences tab.

Email sequences are multi-step automated drip campaigns with configurable delays between steps.

Creating a sequence:

1. Click "Create Sequence"
2. Enter name and description
3. Add steps manually or use "AI Generate Steps":
   • Provide a goal (e.g., "Nurture cold leads to book a demo")
   • Select number of steps and tone
   • AI generates subject lines, email bodies, and delay hours
4. Edit delay hours per step — this is the time to wait after the previous step
5. Save the sequence

Enrolling leads:

• Single: Click "Enroll Leads" on the sequence dashboard, select leads
• Bulk: Select multiple leads and enroll at once
• Each lead gets an independent execution tracking progress

How the sequence executes:

1. Step 0 sends immediately (delay 0)
2. After each step sends successfully, the next step is scheduled via BullMQ with the configured delay
3. Emails are personalized with placeholders: {{name}}, {{first_name}}, {{company}}, {{email}}, {{source}}
4. AI personalization enhances each email with lead-specific context (falls back to basic placeholder replacement if AI fails)

Sequence dashboard shows:

• Stats: Total Enrolled, Active, Completed, Failed, Paused
• Step Performance: per-step metrics (sent, opened, clicked, replied, bounced) with open/click rates and delay hours displayed
• Enrolled Leads: list with current step progress and status
• Actions: Pause, Resume, Unenroll, Edit, Delete

Editing delay hours (live rescheduling): When you edit a sequence's steps, the system automatically:

1. Finds all active executions waiting on delayed jobs
2. Removes the old BullMQ delayed jobs
3. Re-queues with the new delay hours

This means you can reduce delays for testing without re-enrolling leads.

Cold Email Generation (AI)

Generate personalized cold emails using AI:

1. Select a lead and click "Generate Cold Email"
2. Choose a tone: Professional, Casual, Direct, or Consultative
3. AI generates:
   • Subject line (under 60 characters)
   • Email body (under 150 words, HTML formatted with signature)
   • Reasoning (AI's approach explanation)
4. Preview, edit if needed, then send

Batch generation: Select multiple leads to queue batch cold email generation as a background job.

The AI uses your business profile, ICP, goals, and lead context to write relevant, personalized emails. Emails never mention "FrontDeskOS" — they represent your company.

Bulk Lead Import

Navigate to Sales > Import tab.

Supported formats: CSV, Excel (.xlsx, .xls) Max file size: 2MB Max rows: 100 per import

Column auto-detection (flexible naming):

• name / full_name / contact_name
• email / email_address
• company / company_name / organization
• source / lead_source
• phone / phone_number
• website / url
• notes / comments
• estimatedValue / deal_value / value

Import process:

1. Upload file → system parses and validates rows
2. Duplicate detection: Skips rows where email already exists
3. Creates leads with completeness scores
4. Reports: success count, failed count, duplicate count, error details

Options:

• autoQualify=true: Automatically queue AI qualification for each imported lead (staggered 2s apart)
• sequenceId: Auto-enroll all new leads in a specified email sequence

Campaign Tracking & Analytics

All email activity is tracked via Resend webhooks:

Metrics available:

• Overall campaign metrics: total sent, open rate, click rate, reply rate, bounce rate
• Per-sequence metrics: same breakdown per sequence
• Per-step metrics: performance of each individual step in a sequence
• Lead engagement timeline: chronological activity feed per lead
• Engagement score: opened(x1) + clicked(x3) + replied(x5)

Pipeline Analytics & Forecasting

Navigate to Sales > Intelligence tab.

Pipeline metrics:

• Total Pipeline Value (sum of open deal estimated values)
• Weighted Pipeline Value (adjusted by stage probability)
• Total Open Deals, Average Deal Size
• Win Rate, Loss Rate

Stage probability weights:

Revenue forecasting: 30-day, 60-day, and 90-day projections based on weighted pipeline value.

Conversion rates: Stage-to-stage conversion percentages to identify bottlenecks.

CSO Strategy Briefings (AI)

Generate AI-powered strategic sales briefings:

1. Click "Generate Briefing" on the Intelligence tab
2. Optionally specify a focus area (e.g., "pipeline", "email_performance")
3. AI analyzes pipeline analytics + campaign metrics + your ICP/goals
4. Returns:
   • Executive Summary: 2-3 sentence sales health overview
   • Key Insights: 3-5 data-driven observations
   • Recommendations: 3-5 actionable next steps
   • Risks: 2-3 concerns to watch

Briefing history is saved for reference.

Ask the CSO

Interactive Q&A with your Chief Sales Officer:

1. Ask a question: "Why is my reply rate declining?" or "Should I raise my prices?"
2. Sterling analyzes real pipeline data and campaign metrics
3. Returns:
   • Recommendation with reasoning
   • Data points referenced
   • Suggested actions to take

5. Grace Harper — Customer Success Agent (CCO)

AI Model: Claude Sonnet 4.5

Grace Harper is your Chief Customer Officer. She manages support tickets, detects churn risk, maintains a knowledge base, and provides customer health insights.

Support Tickets

Navigate to CS > Tickets tab.

Create, update, and manage customer support tickets:

• Fields: subject, description, priority (LOW/MEDIUM/HIGH/CRITICAL), status
• Status flow: OPEN → IN_PROGRESS → RESOLVED / CLOSED
• Filter by status and priority
• Each ticket gets automatic sentiment analysis

AI Ticket Responses

For any open ticket, click "AI Response":

1. System fetches ticket context + knowledge base articles
2. Claude generates a context-aware response
3. Review and send or edit before sending

Churn Detection & Risk Assessment

Automated daily churn scan (cron job):

1. Analyzes customer support patterns: ticket frequency, sentiment, escalations, inactivity
2. Calculates a risk score (0-100)
3. Categorizes: LOW, MEDIUM, HIGH, CRITICAL
4. Optional AI enrichment with organization context for prioritized actions

Navigate to CS > Churn Risk to view at-risk customers ranked by risk score.

Per-customer analysis available: detailed breakdown of risk factors and recommended actions.

Customer Health Scoring

Navigate to CS > Customer Health tab.

Tracks customer health across tiers:

Scoring based on: ticket resolution rates, sentiment analysis, response times, engagement patterns.

Knowledge Base

Navigate to CS > Knowledge Base tab.

Build an internal knowledge base for AI-powered ticket responses:

• Add documents: Title, content, category
• Full-text search with vector embeddings for semantic matching
• AI uses KB articles to generate more accurate ticket responses
• Documents can be reindexed for updated embeddings

Follow-Up Campaigns

Navigate to CS > Follow-Ups tab.

Automatic satisfaction surveys after ticket resolution:

• Customizable email templates
• Triggered when tickets are marked RESOLVED
• Track satisfaction responses

CCO Intelligence

Strategic customer success advice:

• Generate CCO Briefing: AI analysis of support metrics, churn risks, and escalated tickets
• Ask the CCO: Direct Q&A based on real-time customer health data
• Briefing History: Review past strategic recommendations

6. Maven Cross — Marketing Agent (CMO)

AI Model: Claude Sonnet 4.5

Maven Cross is your Chief Marketing Officer. She generates content, manages campaigns, handles scheduling, and provides marketing intelligence.

Content Generation (AI)

Navigate to Marketing > Content tab.

Generate content with AI:

1. Select content type: Blog Post, Social Media, Newsletter, Landing Page
2. Provide topic, keywords, and tone
3. AI generates optimized content:
   • Blog posts with SEO scoring
   • Social posts (280-character limit)
   • Newsletters with sections
   • Landing pages with CTAs

Repurpose content: Transform a blog post into social snippets, newsletter sections, or other formats.

Campaign Management

Navigate to Marketing > Campaigns tab.

Plan and execute marketing campaigns:

1. Create campaign: Name, description, goals
2. AI campaign plan: Generates strategy, recommended channels, timeline, estimated reach
3. Execute: Schedule content across channels
4. Track: Monitor campaign performance metrics

Content Scheduling

Navigate to Marketing > Calendar tab.

Calendar view of scheduled posts:

• Schedule content across channels: Twitter, Blog, LinkedIn, etc.
• Select content, date/time, and channel
• View upcoming and past scheduled posts

Email Marketing & Subscribers

Navigate to Marketing > Subscribers tab.

Manage subscriber lists and send newsletters:

• Create and manage subscriber lists
• Segment subscribers
• Send newsletters with tracking

SEO Analysis

Navigate to Marketing > SEO tab.

Per-content SEO scoring:

• Content score with improvement suggestions
• Keyword extraction and analysis
• Issue detection (missing meta descriptions, poor readability, etc.)
• Optimization recommendations

Content Analytics

Navigate to Marketing > Analytics tab.

Track performance across all content:

• Views, clicks, shares, engagement rates
• Breakdown by content type and channel
• Trend analysis over time

A/B Testing

Navigate to Marketing > A/B Tests tab.

Create and track experiments:

1. Create test with variants (A vs B)
2. Define metrics: click rate, conversion, open rate, engagement
3. Run test and monitor results
4. Determine winner with statistical confidence

Brand Management

Navigate to Marketing > Brand (via CMO section).

Define and maintain brand guidelines:

• Voice and tone rules
• Color palette
• Messaging pillars
• Target personas

Competitive Analysis

Request competitive intelligence:

1. Submit competitor names
2. AI generates SWOT analysis:
   • Strengths, Weaknesses, Opportunities, Threats
3. Actionable insights and positioning recommendations

CMO Intelligence

• Generate CMO Briefing: Strategic marketing recommendations from content performance, campaign results, and market position
• Ask the CMO: Direct Q&A on marketing strategy
• Briefing History: Past recommendations

7. Sage Patel — Product Manager Agent (CPO)

AI Model: Claude Sonnet 4.5

Sage Patel is your Chief Product Officer. She manages feature requests, plans roadmaps, organizes sprints, and tracks OKRs.

Feedback Management

Navigate to PM > Feedback tab.

Collect and manage feature requests:

• Create requests with title, description, priority, category
• Track status: NEW → UNDER_REVIEW → PLANNED → IN_PROGRESS → SHIPPED → REJECTED
• Voting and impact scoring
• Filter by status, priority, category

Feedback Clustering (AI)

Group feedback into semantic themes:

1. Click "Cluster Feedback"
2. AI analyzes all feature requests
3. Groups into themes/clusters (e.g., "Reporting & Analytics", "Integration Requests")
4. Helps identify patterns and high-demand areas

Roadmap Prioritization

Navigate to PM > Roadmap tab.

Two scoring frameworks available (toggle between them):

RICE Score:

• Reach: How many users are affected
• Impact: How much it moves the needle (1-3)
• Confidence: How confident are you (0-100%)
• Effort: Person-weeks to build

ICE Score:

• Impact: Business impact (1-10)
• Confidence: Confidence level (1-10)
• Ease: Ease of implementation (1-10)

Custom formula: Priority = (frequency x 0.4) + (revenue_impact x 0.35) + (1/effort x 0.25)

Leaderboard view shows features ranked by score.

Spec Generation (AI)

Generate detailed specifications from a feature request:

1. Select a feature request
2. Click "Generate Spec"
3. AI produces:
   • User stories with acceptance criteria
   • Technical notes and considerations
   • Effort estimates
   • Dependencies

Sprint Planning

Navigate to PM > Sprints tab.

Organize work into sprints:

1. AI Sprint Plan: Select a feature request, AI generates tasks with story points and timeline
2. Kanban board: TODO → IN_PROGRESS → IN_REVIEW → DONE
3. Sprint velocity: Track completion rate, story points delivered
4. Sprint summary: Progress metrics and burndown

User Research

Navigate to PM > Research tab.

Manage research sessions:

• Types: Interviews, Surveys, Usability Tests, Focus Groups
• Upload transcripts for AI analysis
• AI extracts: themes, pain points, key quotes, insights
• Findings feed into feedback and roadmap decisions

Release Notes

Navigate to PM > Releases tab.

Generate release notes from a date range:

1. Select date range and version number
2. AI generates notes in 3 formats:
   • Customer-facing: Friendly, benefit-focused
   • Internal: Technical details, impact notes
   • Changelog: Structured version history

OKRs (Objectives & Key Results)

Navigate to PM > OKRs tab.

Track quarterly goals:

1. Create Objective: Title, description, time period
2. Add Key Results: Measurable outcomes with target values
3. Track Progress: Update current values, view progress bars
4. Dashboard view: All OKRs with completion percentages

Competitor Monitoring

Navigate to PM > Competitors tab.

Track competitor activity:

• Add competitor updates (pricing changes, feature launches, partnerships)
• Categorize by type
• Feed into product strategy decisions

CPO Intelligence

• Generate CPO Briefing: Analysis of feedback trends, roadmap velocity, competition, and OKR progress
• Ask the CPO: Q&A on product strategy
• Stakeholder Updates: Generate executive summaries for stakeholders
• Briefing History: Past recommendations

8. Luca Hendrix — Developer Agent (CTO)

AI Model: Claude Sonnet 4.5

Luca Hendrix is your CTO. He manages development tasks, tracks PRs, monitors errors, and integrates with GitHub.

Task Management

Navigate to Dev > Tasks tab.

Create and manage development tasks:

• Fields: title, description, priority (LOW/MEDIUM/HIGH/CRITICAL), status, estimate, assignee
• Status flow: OPEN → IN_PROGRESS → IN_REVIEW → DONE
• Filter by status, priority

Task Execution (AI)

AI-powered execution planning:

1. Select a task and click "Execute"
2. AI considers:
   • Task description and requirements
   • System health status (active alerts, error trends, uptime)
   • Risk factors and dependencies
3. Generates:
   • System health assessment
   • Risk factors identified
   • Step-by-step execution plan
   • Estimated impact on the system

Pull Request Tracking

Navigate to Dev > PRs tab.

Monitor GitHub pull requests:

• Track status: OPEN → MERGED / CLOSED
• View additions/deletions per PR
• Auto-sync via GitHub webhooks
• Link PRs to dev tasks

Error Logging

Navigate to Dev > Errors tab.

Centralized error tracking:

• Log errors with severity (LOW/MEDIUM/HIGH/CRITICAL)
• Automatic deduplication: Groups identical errors by (error_type + message), increments count
• Track occurrence frequency
• Mark errors as resolved with timestamp
• Filter by severity and resolution status

GitHub Integration

Navigate to Dev > GitHub tab (requires setup in Settings).

Setup:

1. Go to Settings > GitHub Integration
2. Enter your GitHub Personal Access Token (PAT)
3. Add default repositories (comma-separated)

Features:

• Browse repositories and their contents
• View issues and PRs
• Webhook receiver (POST /dev/webhooks/github): Automatically syncs PR events (open/close/merge)
• Auto-links GitHub issues to dev tasks

CTO Intelligence

• Ask the CTO: Engineering advice based on velocity metrics, error patterns, and deployment risks
• Dev Metrics: Task completion rate, cycle time, PR velocity, error severity breakdown

9. Chat Assistant

Navigate to /chat.

The chat assistant lets you communicate with any agent directly.

How Chat Works

1. Select an agent from the dropdown: Meta (Atlas), Sales (Sterling), CS (Grace), Marketing (Maven), PM (Sage), Dev (Luca)
2. Type your message and send
3. The selected agent responds with context-aware advice:
   • Meta Agent uses Claude Opus 4.6 and can trigger briefing generation
   • All other agents use Claude Sonnet 4.5 with their domain-specific context
4. Responses include structured data: recommendations, reasoning, data points, and suggested actions

Agent Mentions & Follow-Ups

Agents can @-mention other agents in their responses. When this happens:

1. A follow-up job is queued for the mentioned agent
2. A typing indicator shows which agents are responding
3. The follow-up response appears in the same conversation
4. Max chain depth: 2 levels (prevents infinite loops)

Example: You ask Sterling (Sales) about pipeline. He might @-mention Grace (CS) about a customer churn risk, and Grace will automatically provide her perspective.

Conversation Management

• Conversation list in the sidebar shows all past conversations
• Start new conversation to begin a fresh thread
• Delete conversations you no longer need
• Last 20 messages are used as context for each response
• Conversations can be linked to briefings for additional context

10. Inbox

Each agent has an Inbox tab showing inbound email activity:

• Sales Inbox: Replies from leads to your outreach emails
• CS Inbox: Customer support email threads
• Marketing Inbox: Subscriber responses

Inbound emails are:

• Received via webhooks from the email service (Resend)
• Stored with direction (INBOUND), read status, and conversation context
• Visible on the lead/customer detail page in the conversation thread
• Marked as read when viewed

11. Notifications

Navigate to /notifications or click the bell icon in the header.

Notification types:

Actions:

• View all notifications (paginated)
• See unread count on the bell icon
• Mark individual or all as read
• Delete notifications

Notifications are delivered in real-time via WebSocket — no need to refresh the page.

12. Settings

Navigate to /settings.

Business Profile

Your company context that powers all AI agents:

Security Settings

• Change password: Requires current password verification
• TOTP 2FA: Setup, verify, and manage two-factor authentication
• Recovery codes: View and regenerate backup codes

GitHub Integration Settings

• Personal Access Token: Encrypted storage for GitHub API access
• Default Repositories: Comma-separated list of repos for the Dev agent

Notification Preferences

Agent Configuration

Enable or disable individual agents and configure their model tier:

• Enabled/Disabled: Toggle agents on or off
• Model tier: Standard (Sonnet) or Premium (Opus) — only Meta uses Opus by default
• Custom config: Agent-specific JSON configuration

13. Real-Time Features (WebSocket)

FrontDeskOS uses WebSocket (Socket.io) for real-time updates:

Connection is authenticated via JWT token. The frontend automatically reconnects on network disruption and reloads any missed messages.

14. Cross-Agent Communication

Agents communicate via an event bus (Redis Pub/Sub):

The Meta Agent monitors all agent activity to synthesize briefings and health status.

Reprioritization: The Meta Agent (or founder via Ask Meta) can publish reprioritization signals to any agent, directing them to shift focus.

15. API Reference Summary

All endpoints require JWT authentication unless noted. Rate limits: 100 req/min general, 10 req/min for auth.

Authentication

Meta Agent

Sales Agent

CS Agent

Marketing Agent

PM Agent

Dev Agent

Chat

Settings

Notifications

Users

Last updated: February 14, 2026