diff --git a/README.md b/README.md
index 3c5b2db..c38528d 100644
--- a/README.md
+++ b/README.md
@@ -37,6 +37,13 @@ luarocks install diffs.nvim
 
 ## Known Limitations
 
+- **Incomplete syntax context**: Treesitter parses each diff hunk in isolation
+  without surrounding code context. When a hunk shows lines added to an existing
+  block (e.g., adding a plugin inside `return { ... }`), the parser doesn't see
+  the `return` statement and may produce incorrect highlighting. This is
+  inherent to parsing code fragments—no diff tooling solves this without
+  significant complexity.
+
 - **Syntax flashing**: `diffs.nvim` hooks into the `FileType fugitive` event
   triggered by `vim-fugitive`, at which point the buffer is preliminarily
   painted. The buffer is then re-painted after `debounce_ms` milliseconds,
diff --git a/doc/diffs.nvim.txt b/doc/diffs.nvim.txt
index d75a552..6b66ee1 100644
--- a/doc/diffs.nvim.txt
+++ b/doc/diffs.nvim.txt
@@ -185,6 +185,17 @@ Diff mode views: ~
 ==============================================================================
 KNOWN LIMITATIONS                                       *diffs-limitations*
 
+Incomplete Syntax Context ~
+                                                      *diffs-syntax-context*
+Treesitter parses each diff hunk in isolation without surrounding code
+context. When a hunk shows lines added to an existing block (e.g., adding a
+plugin inside `return { ... }`), the parser doesn't see the `return`
+statement and may produce incorrect or unusual highlighting.
+
+This is inherent to parsing code fragments. No diff tooling solves this
+problem without significant complexity—the parser simply doesn't have enough
+information to understand the full syntactic structure.
+
 Syntax Highlighting Flash ~
                                                              *diffs-flash*
 When opening a fugitive buffer, there is an unavoidable visual "flash" where