From 1b3319e63a6f219874188c23122acdf86ee97c4c Mon Sep 17 00:00:00 2001
From: Ziyang Guo <121015044+RerankerGuo@users.noreply.github.com>
Date: Thu, 1 Oct 2026 01:12:10 +0800
Subject: [PATCH] docs(operations): explain that reindex cannot refresh stale
 chunks

#524 reports that persisted chunks survive a chunker change and are never
re-chunked. Maintainers closed #528 with the position that automatic
invalidation stays out of scope and the recovery path is to clear derived
state and let the watchers rescan, but that path was only described in the
issue thread. The operations guide already warned that reindex does not
rechunk; add the missing half: reindex reuses stored chunks as-is, so a
chunker change requires the re-chunk recovery instead.
---
 docs/en/operations.md | 2 ++
 docs/zh/operations.md | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/docs/en/operations.md b/docs/en/operations.md
index 50160661..a2dd51c0 100644
--- a/docs/en/operations.md
+++ b/docs/en/operations.md
@@ -48,6 +48,8 @@ reme reindex scope=embedding
 
 `reindex` rebuilds BM25 and/or embedding indexes from the current `file_chunks`. It does not scan the workspace, rechunk files, or rebuild the wikilink graph. Diagnose the watcher first when ingestion is the problem.
 
+`reindex` also keeps whatever chunks are already stored. When the chunking behavior itself changes — an upgraded ReMe or edited chunker settings — the stored chunks are reused as they are, so a plain `reindex` cannot refresh them. Re-chunk from the source files instead by clearing the derived chunk state and letting the watchers rescan; see [Recover derived state](#recover-derived-state). Source files are never modified by this recovery.
+
 Rebuild a daily index page separately:
 
 ```bash
diff --git a/docs/zh/operations.md b/docs/zh/operations.md
index 43e4bcbd..46921c83 100644
--- a/docs/zh/operations.md
+++ b/docs/zh/operations.md
@@ -52,6 +52,8 @@ reme reindex scope=embedding
 
 如果问题发生在文件摄取阶段，应先确认后台 watcher 正常运行；不能把 `reindex` 当成通用“重新扫描”命令。
 
+`reindex` 同样只会复用已存储的分块。当分块行为本身发生变化时——例如升级 ReMe 或修改了 chunker 配置——旧分块会被原样沿用，此时仅执行 `reindex` 无法刷新它们。正确做法是从源文件重新分块：按下文[从派生状态故障恢复](#从派生状态故障恢复)清理派生状态后让 watcher 重新扫描。该恢复过程不会改动源文件。
+
 Daily 索引页可单独重建：
 
 ```bash