From 5d5587b22f4f0d8b4848a73b61dfabbd1857d450 Mon Sep 17 00:00:00 2001
From: Barrett Ruth <br.barrettruth@gmail.com>
Date: Sun, 1 Feb 2026 20:20:55 -0500
Subject: [PATCH] feat(doc): add known limitations

---
 README.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/README.md b/README.md
index c2fdd61..fd9d96c 100644
--- a/README.md
+++ b/README.md
@@ -41,6 +41,14 @@ Using [lazy.nvim](https://github.com/folke/lazy.nvim):
 :help fugitive-ts.nvim
 ```
 
+## Known Limitations
+
+- Syntax "flashing": `fugitive-ts.nvim` hooks into the `FileType fugitive` event
+  triggered by `vim-fugitive`, at which point the `fugitive` buffer is
+  preliminarily painted. The buffer is then re-painted after `debounce_ms`
+  milliseconds, causing an unavoidable visual "flash" even when
+  `debounce_ms = 0`. Feel free to reach out if you know how to fix this!
+
 ## Acknowledgements
 
 - [vim-fugitive](https://github.com/tpope/vim-fugitive)