Update from code changes: custom metrics cloned from existing metrics

guides/custom-fields.mdx

@@ -34,6 +34,44 @@ If you want to delete the custom metric, you can just click on the three-dot `op
 
 To learn more about the custom metric types, read the [metrics reference documentation here](/references/metrics). Only aggregate metric types are available as custom metrics.
 
+### Creating a custom metric from an existing metric
+
+You can also start a custom metric from an existing YAML metric in the Explorer. This is useful when you want to reuse the base metric's SQL and settings but tweak one thing — most commonly, adding a filter to narrow the aggregation (for example, cloning `orders.total_revenue` and filtering it to a single product category).
+
+To create a custom metric from an existing metric:
+
+1. In the field tree sidebar or in the results table's column header menu, open the metric's three-dot `options` menu.
+2. Click `Create custom metric`.
+3. In the modal, edit the label, filters, and formatting, then click `Create`.
+
+The clone starts with the same values as the base metric, so it returns the same numbers until you change something. Specifically, the following are copied from the base metric and are editable in the modal:
+
+- The metric's `sql`, type (and `percentile`, where applicable).
+- The base metric's YAML `filters`, as editable filter rules.
+- The base metric's formatting (`formatOptions`, or legacy `format` / `round` / `compact` / `separator`, normalized to structured format options).
+
+Clones of `min` / `max` metrics over `date` or `timestamp` columns inherit the base column's date or timestamp format automatically, and the numeric Format section is hidden for them.
+
+The custom metric modal also displays the source metric (read-only) at the top so you can see where the clone came from when you edit it later.
+
+<Info>
+  **Which metrics can be cloned?**
+
+  Only aggregate metric types (`sum`, `count`, `count_distinct`, `min`, `max`, `average`, `median`, `percentile`) can be cloned into a custom metric. Non-aggregate and derived metric types — including `sum_distinct` and `average_distinct` — do not show the `Create custom metric` action.
+</Info>
+
+<Info>
+  **Defaults for filters you add**
+
+  When you add a new filter rule inside the modal, it defaults to the base metric's underlying column (its `dimensionReference`). This matters in explores that join tables with same-named columns (for example, an `amount` column on both `orders` and `payments`) — the filter targets the same table the base metric aggregates, rather than whichever `amount` column happens to appear first in the explore.
+</Info>
+
+<Info>
+  **Re-syncing clones with the base metric**
+
+  Custom metrics record their source metric internally, but they are not automatically re-synced when the base YAML metric changes. If the base metric is updated in dbt, edit the custom metric (or recreate it) to pick up the new definition.
+</Info>
+
 ### Adding filters to your custom metric
 
 You can add filters to limit the rows included in your metric aggregation. You can add filters when:

guides/developer/dbt-write-back.mdx

@@ -24,6 +24,12 @@ To get started, create a [Custom Metric](/guides/custom-fields#custom-metrics) i
 
 ![](/images/guides/developer/write-back-metrics.jpg)
 
+<Info>
+  **Write-back requires a base dimension column.**
+
+  `Write back to dbt` is only available for custom metrics that were built from a dimension (the YAML write-back attaches the metric to that dimension in the dbt model). Custom metrics that were [cloned from an existing metric](/guides/custom-fields#creating-a-custom-metric-from-an-existing-metric) do not have a base dimension, so the option is hidden from both the individual metric menu and the bulk `Write back to dbt` action in the sidebar's Custom metrics section.
+</Info>
+
 Once the pull request with your new Metric is merged, you can click `Refresh dbt` in Lightdash (or, if you're [using GitHub actions](/guides/cli/how-to-use-lightdash-deploy#automatically-deploy-your-changes-to-lightdash-using-a-github-action), your project will automatically refresh once your changes are merged) and your Custom Metric will be replaced by your new YAML Metric automatically.
 
 ![](/images/guides/developer/refresh-after-write-back.jpg)