From e70e31d8f109118e53d1aec3963d85b931afc6b0 Mon Sep 17 00:00:00 2001
From: gps23 <143864435+gps23@users.noreply.github.com>
Date: Fri, 24 Jul 2026 12:47:08 +0530
Subject: [PATCH 1/2] docs: document standalone audits

Signed-off-by: gps23 <143864435+gps23@users.noreply.github.com>
---
 docs/concepts/audits.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/docs/concepts/audits.md b/docs/concepts/audits.md
index a5a9fccc49..d97b4350e5 100644
--- a/docs/concepts/audits.md
+++ b/docs/concepts/audits.md
@@ -158,7 +158,36 @@ AUDIT (name price_is_not_null);
 SELECT * FROM @this_model
 WHERE price IS NULL;
 ```
+### Standalone audits
 
+Standalone audits are defined independently rather than being attached to a specific model. They specify the models they depend on using the `depends_on` property.
+
+Unlike model-level audits, standalone audits can be used to validate data across one or more models without being associated with a single model.
+
+```sql
+AUDIT (
+  name assert_item_price_is_not_null,
+  dialect spark,
+  standalone TRUE,
+  depends_on (
+    sushi.items
+  )
+);
+
+SELECT *
+FROM sushi.items
+WHERE
+  ds BETWEEN @start_ds AND @end_ds
+  AND price IS NULL;
+```
+
+In this example, the audit checks that the `price` column in `sushi.items` does not contain `NULL` values for the selected date range.
+
+Standalone audits must declare the models they depend on using `depends_on`, since they are not attached to a model definition.
+
+!!! note
+
+    Standalone audits are non-blocking only. Because they are not associated with a single model, SQLMesh cannot determine which model should be blocked if the audit fails.
 ## Built-in audits
 SQLMesh comes with a suite of built-in generic audits that cover a broad set of common use cases. Built-in audits are blocking by default, but they all have non-blocking counterparts which you can use by appending `_non_blocking` - see [Non-blocking audits](#non-blocking-audits).
 

From 4ad15cdf9d3f98bc402b3ba8584da7382c3d8aec Mon Sep 17 00:00:00 2001
From: gps23 <143864435+gps23@users.noreply.github.com>
Date: Sun, 26 Jul 2026 09:20:26 +0530
Subject: [PATCH 2/2] docs: address review feedback

Signed-off-by: gps23 <143864435+gps23@users.noreply.github.com>
---
 docs/concepts/audits.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/docs/concepts/audits.md b/docs/concepts/audits.md
index d97b4350e5..c7c7cbd190 100644
--- a/docs/concepts/audits.md
+++ b/docs/concepts/audits.md
@@ -164,7 +164,9 @@ Standalone audits are defined independently rather than being attached to a spec
 
 Unlike model-level audits, standalone audits can be used to validate data across one or more models without being associated with a single model.
 
-```sql
+Standalone audits run as scheduled nodes during both `sqlmesh plan` and `sqlmesh run`.
+
+```sql linenums="1"
 AUDIT (
   name assert_item_price_is_not_null,
   dialect spark,
@@ -183,7 +185,7 @@ WHERE
 
 In this example, the audit checks that the `price` column in `sushi.items` does not contain `NULL` values for the selected date range.
 
-Standalone audits must declare the models they depend on using `depends_on`, since they are not attached to a model definition.
+Standalone audits can declare dependencies using the `depends_on` property. SQLMesh can often infer dependencies directly from the audit query, but using `depends_on` is recommended when inference isn't sufficient.
 
 !!! note