From e83cc688c3ddd27de297a4897b10233ad8d64502 Mon Sep 17 00:00:00 2001
From: Hashim1999164 <64767361+Hashim1999164@users.noreply.github.com>
Date: Thu, 13 Aug 2026 02:57:30 +0500
Subject: [PATCH] docs: explain when to use $inspect vs {@debug}

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 documentation/docs/02-runes/07-$inspect.md         | 6 +++++-
 documentation/docs/03-template-syntax/11-@debug.md | 6 +++++-
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/documentation/docs/02-runes/07-$inspect.md b/documentation/docs/02-runes/07-$inspect.md
index 7792e2cde7..8564325067 100644
--- a/documentation/docs/02-runes/07-$inspect.md
+++ b/documentation/docs/02-runes/07-$inspect.md
@@ -65,4 +65,8 @@ This rune, added in 5.14, causes the surrounding function to be _traced_ in deve
 
 ## $inspect vs {@debug ...}
 
-`$inspect` is used inside a `<script>` block. To debug values from the template markup itself, use the [`{@debug ...}`](@debug) tag.
+Svelte has both `$inspect` and [`{@debug ...}`](@debug) because they debug from different places and do different jobs. `{@debug}` is not deprecated.
+
+Use `$inspect` from `<script>` when you want a development-only log that re-runs as reactive state changes, including nested updates inside objects and arrays. It can take expressions, and `.with()` / `$inspect.trace()` cover custom callbacks and effect tracing. In production it becomes a noop.
+
+Use `{@debug}` when you need to debug from the template itself, or when you want the browser debugger to pause. It only accepts variable names (not expressions like `user.firstname`), and it compiles to `console.log` plus a `debugger` statement.
diff --git a/documentation/docs/03-template-syntax/11-@debug.md b/documentation/docs/03-template-syntax/11-@debug.md
index b610bd0cfc..3d4ae68067 100644
--- a/documentation/docs/03-template-syntax/11-@debug.md
+++ b/documentation/docs/03-template-syntax/11-@debug.md
@@ -36,4 +36,8 @@ The `{@debug}` tag without any arguments will insert a `debugger` statement that
 
 ## {@debug ...} vs $inspect
 
-`{@debug ...}` is used in the template. To log reactive values from inside a `<script>` block instead, use [`$inspect`]($inspect).
+`{@debug}` and [`$inspect`]($inspect) both exist because one is a template debugger and the other is a `<script>` rune. `{@debug}` is not deprecated.
+
+Reach for `{@debug}` when the value you care about is used in markup and you want DevTools to pause (`debugger`) when it changes. It only accepts identifiers, not expressions.
+
+Reach for `$inspect` when you are already in `<script>`, need to log an expression, or want deep reactive tracking that is stripped from production builds. If you only need a breakpoint from script, `$inspect(value).with(() => { debugger; })` is the rune equivalent of `{@debug}`.