> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thread.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Key Concepts

> Understand the fundamental building blocks of Thread: Templates, Milestones, Actions, and Automation

## Core Concepts

Thread is built around four fundamental concepts that work together to automate customer onboarding:

<CardGroup cols={2}>
  <Card title="Templates" icon="file-lines">
    Reusable onboarding blueprints that define the customer journey
  </Card>

  <Card title="Milestones" icon="flag">
    Sequential phases within templates (Kickoff, Implementation, Go-Live)
  </Card>

  <Card title="Actions" icon="bolt">
    Specific tasks within milestones (emails, forms, docs, meetings)
  </Card>

  <Card title="Automation" icon="robot">
    Triggers, AI generation, and execution rules that power workflows
  </Card>
</CardGroup>

Let's explore each concept in depth.

***

## Templates

Templates are the foundation of Thread. They capture your proven onboarding process as a reusable workflow.

### What's in a Template?

A template contains:

* **Metadata** - Name, description, estimated total duration
* **Milestones** - Sequential phases of the onboarding journey
* **Actions within milestones** - Specific tasks that execute during each phase
* **Automation rules** - When and how actions trigger
* **Portal configuration** - What customers see at each stage

```typescript theme={null}
// Template structure (simplified)
{
  name: "Standard SaaS Onboarding",
  duration_weeks: 8,
  milestones: [
    {
      name: "Kickoff",
      sequence: 1,
      duration_days: 7,
      actions: [/* ... */]
    },
    {
      name: "Implementation",
      sequence: 2,
      duration_days: 30,
      actions: [/* ... */]
    },
    // More milestones...
  ]
}
```

### Template Immutability

<Warning>
  **Critical concept:** When you apply a template to an account, Thread creates an **immutable snapshot** of that template's configuration.
</Warning>

This means:

* ✅ You can edit templates anytime without affecting existing accounts
* ✅ Each account keeps the template version it started with
* ✅ Consistency is guaranteed for in-flight customers
* ❌ Changes to templates don't retroactively affect existing accounts

**Why this matters:**
If you improve your template based on learnings, new customers get the updated version while existing customers complete their original journey without disruption.

### Creating Effective Templates

<Tip>
  Start with 3-5 milestones and 2-3 actions per milestone. You can always add complexity later.
</Tip>

**Good milestone examples:**

* Kickoff (Week 1)
* Technical Setup (Weeks 2-3)
* Training & Enablement (Weeks 4-5)
* Pilot Program (Week 6)
* Go-Live (Week 7)
* Post-Launch Support (Week 8)

**Bad milestone examples:**

* "Everything" (too broad)
* "Phase 1" (not descriptive)
* "Setup Part A" and "Setup Part B" (over-segmented)

***

## Milestones

Milestones represent phases of the customer journey. They provide structure and progress tracking.

### Milestone Attributes

Each milestone has:

| Attribute                | Purpose                 | Example                              |
| ------------------------ | ----------------------- | ------------------------------------ |
| **Name**                 | What phase is this?     | "Implementation"                     |
| **Sequence**             | Order in the journey    | 2 (second milestone)                 |
| **Duration (days)**      | Estimated time          | 30 days                              |
| **CSM Description**      | What team is doing      | "Configure platform, integrate APIs" |
| **Customer Description** | What customer is doing  | "Provide credentials, review setup"  |
| **Actions**              | Tasks within this phase | Emails, forms, meetings              |

### Milestone Status

Milestones progress through these statuses:

```
pending → in_progress → completed → blocked
```

* **Pending**: Not started yet (future milestone)
* **In Progress**: Currently active phase
* **Completed**: All actions done, customer moves to next milestone
* **Blocked**: Stuck due to customer delays or issues

<Info>
  CSMs can manually update milestone status or let it progress automatically based on action completion.
</Info>

### Dual Perspective Display

Every milestone shows two perspectives:

**CSM View ("What we're doing"):**

* Internal team tasks
* Technical setup steps
* Behind-the-scenes work

**Customer View ("What you're doing"):**

* Customer responsibilities
* Information they need to provide
* Decisions they need to make

This dual perspective ensures alignment and clear expectations on both sides.

***

## Actions

Actions are the specific tasks that happen within milestones. Thread supports five action types:

### Action Types

<Tabs>
  <Tab title="Send Email">
    **Purpose:** Send templated emails to customers with AI-powered personalization

    **Use cases:**

    * Welcome emails
    * Status updates
    * Reminders and follow-ups
    * Milestone completion notifications

    **Features:**

    * Variable interpolation (`{{company_name}}`, `{{csm_name}}`)
    * AI-generated draft content
    * To/CC/BCC recipient management
    * CSM review before sending
  </Tab>

  <Tab title="Request Docs">
    **Purpose:** Collect documents from customers via portal upload

    **Use cases:**

    * Contracts and agreements
    * Technical specifications
    * Logo and brand assets
    * Security questionnaires

    **Features:**

    * Configurable document types
    * Optional/required flags
    * Automatic upload tracking
    * Reminder system
  </Tab>

  <Tab title="Collect Info">
    **Purpose:** Gather structured information through portal forms

    **Use cases:**

    * Technical requirements
    * User provisioning details
    * Feature preferences
    * Integration credentials

    **Features:**

    * Multiple field types (text, textarea, select, checkbox, date)
    * Validation rules
    * Intro text and instructions
    * Completion confirmation messages
  </Tab>

  <Tab title="Schedule Meeting">
    **Purpose:** Coordinate calls and meetings with customers

    **Use cases:**

    * Kickoff calls
    * Training sessions
    * Check-in meetings
    * Go-live reviews

    **Features:**

    * Calendar integration (Google Calendar)
    * Meeting type configuration
    * Attendee management
    * Automatic reminders

    <Info>
      Currently manual scheduling. Automatic calendar integration coming soon!
    </Info>
  </Tab>

  <Tab title="Slack Message">
    **Purpose:** Send notifications to customer Slack channels

    **Use cases:**

    * Milestone completions
    * Urgent updates
    * Status notifications
    * Team celebrations

    **Features:**

    * Channel selection
    * Rich message formatting
    * Threaded replies
    * Reaction tracking

    <Info>
      Requires Slack integration to be connected for your organization.
    </Info>
  </Tab>
</Tabs>

### Action Lifecycle

Every action follows this workflow:

```
Triggered → Draft Generated → CSM Reviews → CSM Edits → CSM Executes → Customer Receives → Customer Responds → Marked Complete
```

**Key points:**

* ✅ Actions are **never** sent automatically without CSM approval
* ✅ AI generates drafts but humans have final say
* ✅ CSMs can edit AI-generated content before execution
* ✅ Actions track completion and customer responses

### Action Triggers

Actions trigger based on rules you configure:

<CodeGroup>
  ```typescript Milestone Start (Immediate) theme={null}
  {
    trigger: {
      type: "milestone_start",
      delay_hours: 0
    }
  }
  // Triggers as soon as milestone begins
  ```

  ```typescript Milestone Start (Delayed) theme={null}
  {
    trigger: {
      type: "milestone_start",
      delay_hours: 48
    }
  }
  // Triggers 48 hours after milestone starts
  ```

  ```typescript Manual Trigger theme={null}
  {
    trigger: {
      type: "manual"
    }
  }
  // CSM must manually execute (no automation)
  ```
</CodeGroup>

<Tip>
  Use delays strategically! For example, send a follow-up email 48-72 hours after kickoff to give customers time to complete initial setup tasks.
</Tip>

***

## Automation

Thread's automation engine handles the heavy lifting so CSMs can focus on high-value work.

### How Automation Works

1. **Trigger Processing**
   * When a milestone starts, Thread scans for actions with `milestone_start` triggers
   * Actions with `delay_hours: 0` trigger immediately
   * Actions with delays are scheduled for future execution

2. **AI Draft Generation**
   * Thread uses OpenAI GPT models to generate action content
   * Context includes: customer data, template config, milestone info, previous communications
   * Drafts are stored in the database for CSM review

3. **CSM Review & Execution**
   * CSMs see drafts in the Implementation Tab
   * They can edit, regenerate, or approve as-is
   * Execution sends emails, creates portal forms, etc.

4. **Customer Interaction**
   * Customers receive emails or see actions in their portal
   * They complete actions at their own pace
   * Thread tracks completion automatically

5. **Progress Tracking**
   * Action status updates (pending → ready → review\_pending → executed → completed)
   * Milestone progress calculated based on action completion
   * Overall account health monitored

### AI-Powered Content Generation

Thread uses AI to create drafts for:

<AccordionGroup>
  <Accordion title="Email Content">
    **Input context:**

    * Customer name, company, industry
    * Template action configuration
    * Milestone information
    * Previous email history

    **Output:**

    * Subject line with personalization
    * Email body with proper tone
    * Variable interpolation applied
    * Call-to-action included

    CSMs can regenerate with additional instructions like "Make it more casual" or "Add urgency".
  </Accordion>

  <Accordion title="Handoff Q&A">
    **Input context:**

    * CRM data (deal info, notes, contacts)
    * Company research
    * Handoff question prompts

    **Output:**

    * Draft answers for each question
    * Sourced from available data
    * Ready for AE review and editing

    AEs can regenerate with extra context before submitting to CSM.
  </Accordion>

  <Accordion title="Form Introductions">
    **Input context:**

    * Form purpose
    * Required fields
    * Milestone context

    **Output:**

    * Friendly intro text
    * Instructions for completion
    * Motivation for why this info is needed
  </Accordion>
</AccordionGroup>

### Scheduled Action Execution

Actions with delays are handled by Thread's cron system:

1. When an action has `delay_hours > 0`, it's stored in `scheduled_action_executions`
2. Every hour, a cron job checks for actions ready to execute
3. Ready actions are moved to CSM review queue
4. CSMs see them in the Implementation Tab as new drafts

<Warning>
  Scheduled actions appear in CSM review queue but still require manual execution. Thread never sends customer communications without human approval.
</Warning>

***

## Variable Interpolation

Thread supports dynamic variables in email content and other text fields:

| Variable           | Output                   | Example                                                 |
| ------------------ | ------------------------ | ------------------------------------------------------- |
| `{{company_name}}` | Customer's company name  | "Acme Corp"                                             |
| `{{csm_name}}`     | Assigned CSM full name   | "Sarah Johnson"                                         |
| `{{csm_email}}`    | CSM email address        | "[sarah@yourcompany.com](mailto:sarah@yourcompany.com)" |
| `{{arr}}`          | Annual recurring revenue | "\$50,000"                                              |
| `{{close_date}}`   | Deal close date          | "2024-03-15"                                            |
| `{{account_name}}` | Account display name     | "Acme Corp (Enterprise)"                                |

**Example usage:**

```
Subject: Welcome to {{company_name}}!

Hi {{primary_contact_name}},

I'm {{csm_name}}, your dedicated Customer Success Manager at Thread.
I'm excited to help {{company_name}} get up and running!

Let's schedule our kickoff call to discuss your goals and timeline.

Best,
{{csm_name}}
```

<Info>
  Variables are replaced at execution time, so the latest account data is always used.
</Info>

***

## Portal Visibility

Actions can be configured for visibility in the customer portal:

* **CSM Dashboard Only**: Internal actions customers never see
* **Customer Portal**: Actions visible to customers with status tracking
* **Both**: Visible to everyone (most common)

**Portal visibility affects:**

* Whether customers see the action in their timeline
* Whether they can complete it in the portal
* Whether completion is tracked in portal analytics

***

## Summary

Thread's core concepts work together to create scalable, automated onboarding:

1. **Templates** capture your onboarding process as reusable workflows
2. **Milestones** structure the journey into sequential phases
3. **Actions** define specific tasks within each milestone
4. **Automation** triggers actions, generates AI drafts, and tracks completion

<CardGroup cols={2}>
  <Card title="Create Templates" icon="hammer" href="/csm-guide/templates/creating-templates">
    Learn how to build effective onboarding templates
  </Card>

  <Card title="Manage Accounts" icon="users" href="/csm-guide/accounts/creating-accounts">
    Apply templates and manage customer implementations
  </Card>

  <Card title="Action Types" icon="list-check" href="/reference/action-types">
    Complete reference for all action types
  </Card>

  <Card title="Best Practices" icon="star" href="/csm-guide/templates/best-practices">
    Tips for designing high-performing templates
  </Card>
</CardGroup>