From 91a25ae01aa37bba3eae97214f7c19f874eb21e8 Mon Sep 17 00:00:00 2001
From: Pokey Rule <755842+pokey@users.noreply.github.com>
Date: Tue, 18 Jul 2023 14:08:42 +0100
Subject: [PATCH] Add docs

---
 docs/user/README.md           | 2 +-
 docs/user/scope-visualizer.md | 9 +++++++++
 2 files changed, 10 insertions(+), 1 deletion(-)
 create mode 100644 docs/user/scope-visualizer.md

diff --git a/docs/user/README.md b/docs/user/README.md
index 9f1042ea4b..91d69cd73a 100644
--- a/docs/user/README.md
+++ b/docs/user/README.md
@@ -143,7 +143,7 @@ Note that if the mark is `"this"`, and you have multiple cursors, the modifiers
 
 ##### Syntactic scopes
 
-For programming languages where Cursorless has rich parse tree support, we support modifiers that expand to the nearest containing function, class, etc. See [the source code](../../queries) for a list of supported languages. Some languages are still supported using our legacy implementation; those will be listed in [here](../../packages/cursorless-engine/src/languages/LegacyLanguageId.ts). Below is a list of supported scope types, keeping in mind that this table can sometimes lag behind the actual list. Your cheatsheet (say `"cursorless cheatsheet"` with VSCode focused) will have the most up-to-date list.
+For programming languages where Cursorless has rich parse tree support, we support modifiers that expand to the nearest containing function, class, etc. See [the source code](../../queries) for a list of supported languages. Some languages are still supported using our legacy implementation; those will be listed in [here](../../packages/cursorless-engine/src/languages/LegacyLanguageId.ts). Below is a list of supported scope types, keeping in mind that this table can sometimes lag behind the actual list. Your cheatsheet (say `"cursorless cheatsheet"` with VSCode focused) will have the most up-to-date list.  It can also be helpful to use the [scope visualizer](./scope-visualizer.md) to visualize the scope types on your own code.
 
 | Term           | Syntactic element                                   |
 | -------------- | --------------------------------------------------- |
diff --git a/docs/user/scope-visualizer.md b/docs/user/scope-visualizer.md
new file mode 100644
index 0000000000..ff9fefab99
--- /dev/null
+++ b/docs/user/scope-visualizer.md
@@ -0,0 +1,9 @@
+# Scope visualizer
+
+The scope visualizer allows you to visualize Cursorless scopes on your code in real time. It is useful to understand how Cursorless scopes work, and is also useful for Cursorless contributors as they develop new scopes.
+
+## Usage
+
+To start the scope visualizer, say `"visualize <scope>"`, where `<scope>` is the name of the scope you want to visualize. For example, `"visualize funk"`. To stop the scope visualizer, say `"visualize nothing"`.
+
+You can also visualize removal and iteration ranges for scopes by saying `"visualize <scope> removal"` and `"visualize <scope> iteration"`, respectively.