diff --git a/CLAUDE.md b/CLAUDE.md
index 792e68b..8655b91 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -112,6 +112,42 @@ Nvim keymaps (via `td_mappings.lua`): `<leader>ts/tp/tr/tw`
 - `cj` — cd to journal
 - `jr` / `hc` — sync journal / hc notes
 
+## How Neovim understands code (tree-sitter vs LSP)
+
+Two parallel systems, different jobs:
+
+```
+tree-sitter:  file → parser (.so grammar) → syntax tree → highlighting / aerial outline / folding
+LSP:          file → language server process → diagnostics / completion / hover / go-to-def
+```
+
+**Tree-sitter** is a structural parser. It turns text into a tree of named syntax nodes
+(`create_table`, `create_function`, etc.) but knows nothing about semantics — it can't
+tell you a column doesn't exist. Each language has a community-maintained grammar that
+gets compiled to a `.so` file. `nvim-treesitter` manages downloading and compiling these.
+Plugins like aerial ship `.scm` query files that pattern-match against node types in that
+tree to extract symbols.
+
+**LSP** (Language Server Protocol) is a separate process (installed via Mason) that
+understands the language semantically — it can autocomplete column names, validate queries
+against a real schema, etc. It has no idea tree-sitter exists.
+
+Aerial can use either backend. If an LSP is attached to the file, aerial can ask it for
+document symbols and skip tree-sitter entirely.
+
+**Where things break:** if a `.scm` query references a node type (e.g. `create_policy`)
+that the installed grammar `.so` doesn't define, tree-sitter rejects the whole query at
+parse time — before it even looks at your file. Fix: override the query in
+`~/.config/nvim/queries/<lang>/` so your version wins over the plugin's copy.
+
+## Treesitter Query Overrides
+
+`dotfiles/nvim/queries/` contains local query overrides that shadow plugin-provided queries in `~/.config/nvim/queries/`. They are deployed as symlinks by `deploy_nvim` in `_lib.sh` (alongside `lua/` and `lua/plugins/`).
+
+Current overrides:
+
+- **`queries/sql/aerial.scm`** — aerial.nvim's upstream SQL query includes `(create_policy ...)`, which is not a valid node type in the installed tree-sitter-sql grammar and causes aerial to crash on SQL files. This file is a full replacement with `create_policy` commented out. If a future `TSUpdate sql` adds the node, remove the comment and retire the override.
+
 ## Machine-specific Configuration
 
 `.bashrc` sources two gitignored files:
diff --git a/_lib.sh b/_lib.sh
index b2bce63..d6ebb1d 100755
--- a/_lib.sh
+++ b/_lib.sh
@@ -86,4 +86,12 @@ deploy_nvim() {
       create_symlink "$mod" ~/.config/nvim/lua/plugins/"$(basename "$mod")"
     done
   fi
+  if [[ -d "$src_dir/queries" ]]; then
+    find "$src_dir/queries" -name "*.scm" | while read -r qfile; do
+      local rel="${qfile#"$src_dir/queries/"}"
+      local dest=~/.config/nvim/queries/"$rel"
+      mkdir -p "$(dirname "$dest")"
+      create_symlink "$qfile" "$dest"
+    done
+  fi
 }
diff --git a/dotfiles/nvim/queries/sql/aerial.scm b/dotfiles/nvim/queries/sql/aerial.scm
new file mode 100644
index 0000000..5ca7965
--- /dev/null
+++ b/dotfiles/nvim/queries/sql/aerial.scm
@@ -0,0 +1,49 @@
+(create_table
+  (object_reference) @name
+  (#set! "kind" "Class")) @symbol
+
+(create_view
+  (object_reference) @name
+  (#set! "kind" "Class")) @symbol
+
+(create_materialized_view
+  (object_reference) @name
+  (#set! "kind" "Class")) @symbol
+
+(create_function
+  (object_reference) @name
+  (#set! "kind" "Function")) @symbol
+
+(create_type
+  (object_reference) @name
+  (#set! "kind" "Struct")) @symbol
+
+(create_sequence
+  (object_reference) @name
+  (#set! "kind" "Class")) @symbol
+
+(create_trigger
+  (object_reference) @name
+  (#set! "kind" "Class")) @symbol
+
+(create_index
+  column: (_) @name
+  (#set! "kind" "Class")) @symbol
+
+(create_role
+  (identifier) @name
+  (#set! "kind" "Class")) @symbol
+
+; create_policy omitted — not supported by tree-sitter-sql grammar (causes aerial to crash)
+
+(create_extension
+  (identifier) @name
+  (#set! "kind" "Module")) @symbol
+
+(create_schema
+  (identifier) @name
+  (#set! "kind" "Module")) @symbol
+
+(create_database
+  (identifier) @name
+  (#set! "kind" "Module")) @symbol