fix(#52): add post-generation validation and LLM verification

CLAUDE.md

@@ -15,7 +15,7 @@ AI-powered GitHub Action that analyzes code changes and generates documentation
 | `suggest_docs.py` | Main orchestrator — command detection, file discovery, generation, PR/comment posting |
 | `config.py` | Environment configuration, LLM client setup, style config loading |
 | `discovery.py` | File discovery — index-based optimized path and full-scan fallback |
-| `generation.py` | LLM content generation, file reading/writing, summary caching |
+| `generation.py` | LLM content generation, post-generation validation, file reading/writing, summary caching |
 | `doc_index.py` | Semantic index system — build, cache, fetch, commit indexes |
 | `comments.py` | PR comment building, parsing previous reviews, posting |
 | `github_ops.py` | Git operations, docs environment setup, pushing/creating PRs |

README.md

@@ -20,7 +20,9 @@ Comment on any Pull Request:
 2. Uncheck any files you don't want updated
 3. Comment `[update-docs]` to create a PR with only the checked files
 
-You can guide how the AI generates doc updates by adding instructions in your `[update-docs]` comment — global on the first line, per-file on subsequent lines:
+Note: `[update-docs]` runs post-generation validation (content preservation check and an independent LLM review) that `[review-docs]` skips, so the committed content may differ from the preview, and a file may be skipped entirely if validation fails.
+
+You can guide how the AI generates doc updates by adding instructions in your `[update-docs]` comment. Lines matching `filename.ext: instruction` are per-file instructions; all other lines are global instructions passed to the LLM:
 
 ```
 [update-docs] keep changes minimal