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.

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