diff --git a/docs/alerts/creating-an-alert.md b/docs/alerts/creating-an-alert.md
new file mode 100644
index 0000000..8f8b760
--- /dev/null
+++ b/docs/alerts/creating-an-alert.md
@@ -0,0 +1,136 @@
+---
+sidebar_position: 2
+---
+
+# Creating an alert
+
+**Every alert is created through the same three-step wizard — Define, Notify, Test — opened from one of three places depending on the alert type.**
+
+## Where alerts are created
+
+You can start a new alert from three surfaces:
+
+| From | What it creates | How to open |
+|---|---|---|
+| **KPIs page** | A KPI alert pre-scoped to that KPI | On a KPI card, select the **⋯ menu** → **Create alert**. From the detail drawer, select the **bell icon** in the top-right. |
+| **Metrics library** | A Metric alert pre-scoped to that Metric | On a metric row, select the **⋯ menu** → **Create alert**. |
+| **Alerts page** | Any of the three alert types — picked in a dialog | Select **CREATE ALERT** in the top-right. |
+
+When you open the wizard from a KPI or Metric, the source is locked — the wizard skips the picker and the alert is scoped to that object.
+
+When you open it from the Alerts page, the **CREATE ALERT** button opens a **Select alert type** dialog. Pick one of three options and select **NEXT** to open the wizard:
+
+- **Use a KPI** — Notify stakeholders on key state changes.
+- **Use a metric** — Trigger alerts against your computed metrics.
+- **Build custom alerts** — Write a custom query.
+
+![Select alert type](/img/alerts/alerts_create_type_modal.png)
+
+:::note
+If your organisation has no KPIs yet, the **Use a KPI** option is disabled and a **+ Create KPI** button appears next to it that takes you to the KPI library. The same applies to **Use a metric** when the Metrics library is empty. **Build custom alerts** is always available.
+:::
+
+## Step 1 — Define
+
+This step covers what the alert measures, what condition fires it, and how often it runs.
+
+![Create KPI alert — Define step](/img/alerts/alerts_create_kpi_define.png)
+
+1. Enter a **Name** for the alert. The name must be unique within your organisation.
+2. Set the **Source**. The fields here depend on the alert type:
+   - **KPI alert** — pick a KPI from the **KPI** dropdown. The card below shows the KPI's target, RAG band percentages, and direction.
+   - **Metric alert** — pick a Metric from the **Metric** dropdown. The line below shows the metric's source table and expression.
+   - **Custom alert** — pick a **Datasource** (schema + table), then a **Function** (`sum`, `avg`, `count`, `min`, `max`, `count_distinct`), then a **Column**. For `count`, the column auto-fills to `*` (count all rows).
+3. Set the **Condition**:
+   - **KPI alert** — tick one or two **RAG states** that should fire the alert (Red, Amber, or Green).
+   - **Metric and Custom alerts** — pick an **Operator** (`is less than`, `is greater than`, `is equal to`) and a **Value**.
+
+![Create Metric alert — Define step](/img/alerts/alerts_create_metric_define.png)
+
+4. Set the **Schedule** — when the alert runs:
+   - **Frequency** — Hourly, Daily, Weekly, or Monthly.
+   - **Time of day** — the hour and minute the evaluation runs, in your browser's local timezone. Dalgo converts this to UTC when saving.
+   - **Day of week** — only for Weekly schedules.
+   - **Day of month** (1–28) — only for Monthly schedules.
+
+![Create Custom alert — Define step](/img/alerts/alerts_create_custom_define.png)
+
+5. Select **Next** to continue.
+
+:::note
+For KPI alerts, you may pick at most two RAG states. To fire on any one of the three states, create three separate alerts or pick the two most important.
+:::
+
+## Step 2 — Notify
+
+This step covers how the alert reaches your team — by email, by Slack, or both — and what message they receive.
+
+### Delivery channels
+
+Tick **Email**, **Slack**, or both.
+
+**Email**
+
+Add one or more recipient email addresses. Type the address and press Enter (or comma) to add it as a chip. To remove a recipient, select the **×** on its chip.
+
+**Slack**
+
+Paste an **Incoming Webhook URL** from your Slack workspace. The URL starts with `https://hooks.slack.com/services/`. Select **Send test message** to verify Dalgo can post to the channel — you'll see a green confirmation if Slack accepts the request, or the HTTP status and Slack's response if it doesn't.
+
+:::note
+Slack delivery is per-webhook, not per-recipient. Everyone watching the channel the webhook points to will see the message. To deliver an alert to multiple Slack channels, create a separate alert for each channel.
+:::
+
+:::note
+When you edit an alert, the saved webhook URL is masked for security. Leave the field as-is to keep using the existing URL, or paste a new one to replace it.
+:::
+
+### Message template
+
+The **Message Template** is the body that Dalgo sends on every fire. Write it in plain text and insert tokens that Dalgo substitutes with live values at evaluation time.
+
+Available tokens appear as chips above the editor — select a chip to insert it. The token set depends on the alert type:
+
+- **All types** — `{{alert_name}}`, `{{current_value}}`, `{{evaluated_at}}`, `{{condition}}`
+- **Metric and KPI alerts** — `{{metric_name}}`, `{{table}}`
+- **KPI alerts** — `{{kpi_name}}`, `{{target_value}}`, `{{rag_state}}`
+- **Custom alerts** — `{{aggregation}}`, `{{column}}`
+
+For example:
+
+```
+Alert {{alert_name}} fired. Current value is {{current_value}} vs target {{target_value}}.
+KPI is in {{rag_state}} state.
+```
+
+Select **Next** to continue.
+
+## Step 3 — Test
+
+The Test step runs the alert once against your live warehouse, without sending a notification, so you can confirm the alert behaves the way you expect.
+
+A status pill at the top shows one of three outcomes:
+
+- **Alert will fire for current data** — the condition is met right now. The alert will notify recipients on its next scheduled run.
+- **Alert will not fire for current data** — the condition is not met. Dalgo still evaluates on schedule; the alert just stays silent until the data crosses the threshold.
+- **No data available — current value is empty** — the query returned no rows. Re-check your data source or the time window you care about.
+
+Below the pill, three panels show the dry-run details:
+
+- **Result** — the current value the query returned and the threshold condition for comparison.
+- **Message Preview** — the rendered message, with tokens substituted from the dry-run values. This is exactly what your recipients will see when the alert fires.
+- **View generated Sql** — expandable accordion showing the SQL that ran. Useful for debugging unexpected values or sharing with your data team.
+
+If you change a setting in steps 1 or 2 and return to step 3, the dry-run re-runs automatically.
+
+When you're satisfied, select **Create alert** at the bottom right. The alert is saved and will run on its next scheduled tick.
+
+## Editing an alert
+
+From the alert row's **⋯ menu**, select **Edit**. The wizard reopens with all three steps prefilled. The alert type and its source (KPI, Metric, or dataset) are locked; the name, condition, schedule, delivery channels, recipients, and message template can all be changed.
+
+Select **Save changes** in step 3 to save.
+
+---
+
+**Next:** [Alerts overview](./index.md) · [KPIs](../kpis/index.md) · [Metrics](../data/metrics.md)
diff --git a/docs/alerts/index.md b/docs/alerts/index.md
new file mode 100644
index 0000000..8a267d5
--- /dev/null
+++ b/docs/alerts/index.md
@@ -0,0 +1,82 @@
+---
+sidebar_position: 1
+---
+
+# Alerts
+
+**Alerts notify you by email or Slack when your data crosses a threshold you care about — a KPI going red, a Metric dropping below a number, or a custom check on any table in your warehouse.**
+
+An alert is a saved rule. Dalgo evaluates it on a schedule you set, and notifies your chosen recipients whenever the rule fires. Every evaluation is logged so you can see what ran, what value came back, and who received the message.
+
+## The Alerts page
+
+Select **Alerts** in the left menu to open the alert list.
+
+![Alerts list](/img/alerts/alerts_list.png)
+
+Each row shows:
+
+- **Name** — the alert name. The line below shows the linked KPI, Metric, or dataset; selecting it opens the source.
+- **Alert condition** — for Metric and Custom alerts, the operator and threshold (e.g. `< 500`). For KPI alerts, one or more RAG state chips (Red / Amber / Green).
+- **Enabled** — toggle the alert on or off. A disabled alert is not evaluated and does not notify.
+- **Frequency** — when the alert runs (Hourly, Daily, Weekly, Monthly) in your local timezone.
+- **Fire streak** — how many consecutive evaluations have fired. Resets to 0 when the alert next evaluates without firing.
+- **Last fire** — relative time since the alert most recently fired.
+
+Sort by any of the column headers. The list is paginated — change the page size with the dropdown at the bottom right.
+
+## Alert types
+
+Dalgo supports three alert types. The type is picked when you create the alert and cannot be changed afterwards.
+
+| Type | What it checks | Best for |
+|---|---|---|
+| **KPI alert** | A linked KPI is in one or two RAG states you select (e.g. fire when red or amber) | Leadership-facing indicators with targets and RAG bands |
+| **Metric alert** | A linked Metric crosses a numeric threshold (less than / greater than / equal to) | Operational thresholds on saved measurements |
+| **Custom alert** | An ad-hoc aggregation on any warehouse table, with optional filters, against a numeric threshold | Data-quality checks, row counts, or measurements that are not in your Metrics library |
+
+See [Creating an alert](./creating-an-alert.md) for the three entry points and the wizard.
+
+## Row actions
+
+Select the **⋯ menu** at the end of any row to:
+
+- **Edit** — reopens the wizard with all three steps prefilled. The alert type and its source (KPI / Metric / dataset) are locked; everything else can be changed.
+- **Alert log** — opens the evaluation history for this alert (see below).
+- **Delete** — removes the alert.
+
+:::warning
+Deleting an alert is permanent. The alert's evaluation history is removed with it.
+:::
+
+## Viewing the alert log
+
+The alert log shows every time the alert ran, whether it fired, what value the query returned, and the SQL that was executed. Open it from the row's **⋯ menu** → **Alert log**.
+
+Each row in the log shows:
+
+- **Time** — when the evaluation ran, with a relative timestamp underneath.
+- **Current value** — the number returned by the query (or `—` if the query returned no rows).
+- **Channel · Recipients** — `Email`, `Slack`, or `Email · Slack`, plus the first two recipient addresses with an overflow count.
+- **Status** — whether each delivery was sent or failed (with the HTTP status code if Slack rejected it).
+
+Expand any row to see the rendered message that was sent, the per-recipient delivery status, and the SQL that ran.
+
+:::note
+The log records every evaluation, including non-fires. The rendered message field is always populated so you can see what *would* have been sent if the alert had fired.
+:::
+
+## Permissions
+
+Three permissions control who can do what with alerts:
+
+- **View Alerts** — read the list and open the alert log.
+- **Create Alerts** — opens the **CREATE ALERT** button and the **Create alert** menu items on KPI cards and Metric rows.
+- **Edit Alerts** — needed to toggle the **Enabled** switch and to use the **Edit** action.
+- **Delete Alerts** — needed to use the **Delete** action.
+
+Permissions are assigned per-role in [User Management](../settings/user-management.md).
+
+---
+
+**Next:** [Creating an alert](./creating-an-alert.md) · [KPIs](../kpis/index.md) · [Metrics](../data/metrics.md)
diff --git a/sidebars.js b/sidebars.js
index 786ea14..a9a844b 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -126,7 +126,17 @@ const sidebars = {
       ],
     },
 
-    // 9. Settings
+    // 9. Alerts — top-level product surface
+    {
+      type: 'category',
+      label: 'Alerts',
+      link: { type: 'doc', id: 'alerts/index' },
+      items: [
+        'alerts/creating-an-alert',
+      ],
+    },
+
+    // 11. Settings
     {
       type: 'category',
       label: 'Settings',
@@ -138,7 +148,7 @@ const sidebars = {
       ],
     },
 
-    // 10. Support
+    // 12. Support
     {
       type: 'category',
       label: 'Support',
diff --git a/static/img/alerts/alerts_create_custom_define.png b/static/img/alerts/alerts_create_custom_define.png
new file mode 100644
index 0000000..787c393
Binary files /dev/null and b/static/img/alerts/alerts_create_custom_define.png differ
diff --git a/static/img/alerts/alerts_create_kpi_define.png b/static/img/alerts/alerts_create_kpi_define.png
new file mode 100644
index 0000000..84cf461
Binary files /dev/null and b/static/img/alerts/alerts_create_kpi_define.png differ
diff --git a/static/img/alerts/alerts_create_metric_define.png b/static/img/alerts/alerts_create_metric_define.png
new file mode 100644
index 0000000..64bfd7d
Binary files /dev/null and b/static/img/alerts/alerts_create_metric_define.png differ
diff --git a/static/img/alerts/alerts_create_type_modal.png b/static/img/alerts/alerts_create_type_modal.png
new file mode 100644
index 0000000..b375d3a
Binary files /dev/null and b/static/img/alerts/alerts_create_type_modal.png differ
diff --git a/static/img/alerts/alerts_kpi_entry_point.png b/static/img/alerts/alerts_kpi_entry_point.png
new file mode 100644
index 0000000..27f3e5e
Binary files /dev/null and b/static/img/alerts/alerts_kpi_entry_point.png differ
diff --git a/static/img/alerts/alerts_list.png b/static/img/alerts/alerts_list.png
new file mode 100644
index 0000000..d4f57a3
Binary files /dev/null and b/static/img/alerts/alerts_list.png differ
diff --git a/static/img/alerts/alerts_metric_entry_point.png b/static/img/alerts/alerts_metric_entry_point.png
new file mode 100644
index 0000000..3fd3bb9
Binary files /dev/null and b/static/img/alerts/alerts_metric_entry_point.png differ