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

# Configuration

> Create a health score config with the three-step wizard — choose who to score, set buckets and category weights, add AI scoring intelligence — then tune metric thresholds.

## Overview

Health score configuration is managed from **Settings > Health Scores**. The configuration page has three tabs: Configuration, Test, and History.

## Creating a config

New configs start with a three-step wizard:

<Steps>
  <Step title="Choose customers">
    Score **all customers** or a specific **segment**. You can have one all-customers config plus one per segment (a segment can only be bound to one config). Picking a segment shows a live count of matching customers.
  </Step>

  <Step title="Scores & categories">
    Set the score-range buckets and category weights (details below).
  </Step>

  <Step title="Scoring intelligence">
    Click **Auto-configure** and AI generates **risk signals** and **growth signals** tailored to your organization and connected tools. They're editable as plain text — refine or regenerate as needed.
  </Step>
</Steps>

***

## Score Buckets

The score bucket bar at the top defines four risk levels that map score ranges to labels and colors.

* **Drag the dividers** between buckets to adjust score ranges
* **Click a label** to rename it
* Buckets must cover the full 0-100 range without gaps

Default buckets: Critical (0-24), At Risk (25-49), Medium (50-74), Healthy (75-100).

***

## Category Weights

Sliders control how much each category contributes to the overall score. Five categories are available:

* **Revenue**
* **Product Usage**
* **Engagement**
* **Support**
* **Market Signals**

Each category has an enable/disable toggle. Disabled categories are excluded from the calculation. Weights for enabled categories must total exactly 100%.

***

## Metric Configuration

Each enabled category contains individual metrics that can be toggled on or off. Expand a category section to see its available metrics.

### Threshold Editor

Each metric (except Market Signals) uses three threshold values that create four scoring buckets. Click the edit button on a metric to configure:

* **Three threshold values** - Define the boundaries between Critical, At Risk, Medium, and Healthy
* **Direction** - Whether higher values are better (e.g., MRR) or lower values are better (e.g., open tickets)

### Time Periods

Metrics that measure activity over time support configurable lookback periods:

* **Product Usage** - 30d, 60d, 90d, 180d, 1y
* **Engagement / Support** - 30d, 90d

### Product Usage Scoring Methods

Product usage metrics support four scoring methods:

| Method                  | Description                                              |
| ----------------------- | -------------------------------------------------------- |
| **Trend + Volume**      | Combines usage volume with trend direction (recommended) |
| **Absolute Value**      | Score based on raw usage numbers                         |
| **Growth Percentage**   | Score based on percentage change vs previous period      |
| **Absolute Difference** | Score based on change in units vs previous period        |

### Market Signals

Market Signals scoring is automatic based on detected signals. Positive signals (funding, growth) improve the score, while negative signals (layoffs, financial trouble) reduce it. No threshold configuration is needed.

### Orphaned Metrics

If a usage metric was configured but its data source is removed, it is flagged with a warning badge so you can update the configuration.

***

## Saving and Publishing

The configuration supports a draft/publish workflow:

* **Save Draft** - Saves your changes without affecting live scores
* **Publish** - Activates the configuration for the customers it scopes (all customers, or its segment). Scores calculate on the next daily run.
* **Reset** - Reverts unsaved changes to the last saved state

An "Unsaved" indicator appears when you have pending changes.

### Publishing

When you publish:

1. A dialog prompts for a **version name** (required) and **change description** (required for subsequent versions)
2. The previous published version is archived
3. A new version number is assigned
4. All future health score calculations use the new configuration

<Warning>
  Publishing affects every customer the config scopes. Use the Test tab to validate your configuration before publishing.
</Warning>