[CCT-1506] Feature documentation for custom forecast

content/en/cloud_cost_management/planning/budgets.md

@@ -139,6 +139,72 @@ To view detailed forecast information in a budget, click {{< ui >}}View Performa
 
 Learn more about how [forecasting][3] works and data requirements.
 
+## Customize your budget forecast
+
+Datadog automatically generates a **Bits forecast** for each budget, projecting future costs from your historical spend. When you have knowledge that the Bits forecast cannot capture, such as a planned product launch, migration, seasonal demand, or retired workloads, you can override it with your own values. This override is called a **custom forecast**.
+
+Custom forecast values are:
+
+- Editable with the `ccm_forecast_write` permission (see [Permissions](#permissions)).
+- Editable for the current and future months.
+
+For [hierarchical budgets](#set-up-budgets), you edit custom forecast values at the child level. The parent level reflects the sum of its children.
+
+Once set, your custom values take precedence over the Bits forecast on the budget status page, in the forecast totals on the Budgets page, and in [budget monitors][2].
+
+### Add or edit custom forecast values
+
+{{< tabs >}}
+{{% tab "When creating a budget" %}}
+
+1. Follow the steps in [Set up budgets](#set-up-budgets) to start creating a budget.
+1. Toggle {{< ui >}}Customize Bits Forecast{{< /ui >}} to display forecast columns interleaved with the budget columns. Each month shows a {{< ui >}}Budget{{< /ui >}} column and a {{< ui >}}Forecast{{< /ui >}} column.
+
+  {{< img src="cloud_cost/budgets/cust-fcst-during-create.png" alt="Toggle Customize Bits Forecast to display forecast columns" style="width:100%;">}}
+
+1. Each forecast cell displays the Bits forecast as a gray placeholder. Enter a dollar amount to override it. Negative values are not allowed.
+
+   The preview chart updates as you edit, so you can review the final forecast before saving.
+
+  {{< img src="cloud_cost/budgets/cust-fcst-during-create-table.png" alt="Toggle Customize Bits Forecast to display forecast columns" style="width:100%;">}}
+
+1. Click {{< ui >}}Save{{< /ui >}}.
+
+{{% /tab %}}
+{{% tab "When editing a budget" %}}
+
+1. On the [Budgets page][1], click the edit icon for a budget.
+
+   The forecast columns appear automatically if you have the `ccm_forecast_write` permission. Each forecast cell displays your saved override, or the Bits forecast as a gray placeholder when no override exists.
+
+1. Enter or change a dollar amount in any forecast cell. Negative values are not allowed.
+1. To compare your overrides against the original automatic values, toggle {{< ui >}}Show Bits AI forecast{{< /ui >}} to display a read-only Bits AI column next to each forecast column.
+1. Click {{< ui >}}Save{{< /ui >}}.
+
+[1]: https://app.datadoghq.com/cost/plan/budgets
+
+{{% /tab %}}
+{{< /tabs >}}
+
+While editing, the appearance of each forecast cell indicates its state:
+
+| Cell appearance | Meaning |
+|---|---|
+| Gray text | Bits forecast placeholder: no override is set for this cell. |
+| Black text | A saved custom forecast override. |
+| Black text with a blue outline | An override you entered but have not saved yet. |
+
+To remove an override, clear the cell. The cell reverts to the gray Bits forecast placeholder.
+
+<div class="alert alert-info">Datadog saves the budget first, and then saves the custom forecast. If the budget saves but the custom forecast does not, a notification prompts you to retry from the edit page.</div>
+
+### How custom forecasts are used
+
+- **Budget status**: The budget status page and the forecast totals on the Budgets page include your custom forecast.
+- **Budget monitors**: When [budget monitors][2] evaluate, a custom forecast takes precedence over the Bits forecast when one is present.
+- **CSV export**: Downloading a budget as a CSV includes the custom forecast values where they are set.
+- **Deleting a budget**: Deleting a budget also deletes its associated custom forecast values.
+
 ## Permissions
 
 | Action | Required Permission |
@@ -155,4 +221,4 @@ For the full list of CCM permissions, see the [Permissions documentation][4].
 [1]: https://app.datadoghq.com/cost/plan/budgets
 [2]: /cloud_cost_management/cost_changes/monitors/
 [3]: /cloud_cost_management/planning/forecasting
-[4]: /cloud_cost_management/setup/permissions
+[4]: /cloud_cost_management/setup/permissions

content/en/cloud_cost_management/planning/forecasting.md

@@ -50,6 +50,14 @@ To generate accurate forecasts, CCM requires:
 - **At least 64 consecutive days of cost data**: This helps ensure the model has sufficient information to identify meaningful patterns. If fewer days are available, the model pads the remaining days with zeros to generate a forecast.
 - **Recent data**: The model uses up to the last 64 days of your cost history to generate predictions.
 
+## Bits and custom forecasts
+
+The forecast that Datadog generates automatically from your historical spend is called the **Bits forecast**. Because it is trend-based, it projects past patterns forward but cannot account for planned business events, such as a product launch, migration, or seasonal demand.
+
+In [budgets][3], you can override the Bits forecast with your own monthly values, called a **custom forecast**. Datadog overlays your custom forecast on the Bits forecast, so your overrides take precedence wherever you set them. Budgets and budget monitors use the forecast with your overrides by default.
+
+To set custom forecast values, see [Customize your budget forecast][4].
+
 ## View forecasts in reports
 
 Navigate to [**Cloud Cost > Analyze > Reports**][1] in Datadog to enable forecasts on Cost reports and Budget reports.
@@ -104,9 +112,13 @@ To view detailed forecast information:
 
 {{< img src="cloud_cost/forecasts/updated_budget_status_forecast-1.png" alt="Budget performance view showing the forecast toggle and forecasted costs displayed with a hatched pattern" style="width:100%;" >}}
 
+By default, Datadog combines the automatic Bits forecast with any custom forecast values you set in budgets. To override the Bits forecast with your own monthly values, see [Customize your budget forecast][4].
+
 ## Further reading
 
 {{< partial name="whats-next/whats-next.html" >}}
 
 [1]: https://app.datadoghq.com/cost/analyze/reports
 [2]: https://app.datadoghq.com/cost/plan/budgets
+[3]: /cloud_cost_management/planning/budgets
+[4]: /cloud_cost_management/planning/budgets#customize-your-budget-forecast