docs(watcher): state what changedSince can and cannot detect

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

ingestion/internal/watcher/watcher.go

@@ -217,8 +217,10 @@ func processFile(ctx context.Context, cfg Config, root *os.Root, rawDir, path, d
 }
 
 // changedSince reports whether the note at rel differs (size or mtime) from
-// before. A note replaced mid-ingest (Syncthing) has newer content than the
-// archive copy, so it must not be removed.
+// before. A note replaced mid-ingest (Syncthing) was extracted from older
+// content than it now holds, so it must not be removed. Limits: a same-size
+// rewrite with a restored mtime is not detected (the new bytes then survive
+// only in the archive copy), nor a change between this check and Remove.
 func changedSince(root *os.Root, rel string, before os.FileInfo) bool {
 	now, err := root.Lstat(rel)
 	if err != nil {

ingestion/internal/watcher/watcher_test.go

@@ -446,7 +446,9 @@ func TestProcessDir_KeepsTheOriginalWhenTheArchiveCopyFails(t *testing.T) {
 }
 
 // If the note is replaced (e.g. by Syncthing) while it is being ingested, the
-// archive holds the OLD content; removing the original would lose the new one.
+// wiki page was extracted from the old content; removing the original would
+// leave the new content only in the archive and never re-ingest it. Observes
+// size/mtime change only: a same-size rewrite with a restored mtime is not caught.
 func TestProcessDir_KeepsANoteThatChangedWhileItWasBeingIngested(t *testing.T) {
 	brainDir := setupBrainDir(t)
 	note := filepath.Join(brainDir, "raw", "edited.md")