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,