docs: add incomplete syntax context as known limitation

Treesitter parses diff hunks in isolation without surrounding code
context, which can cause incorrect highlighting when hunks show partial
blocks (e.g., adding lines inside `return { ... }` without seeing the
`return`). Document this as a known limitation in README and vimdoc.

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,

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