Document how the block list is kept and how the sources are verified

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

README.en.md

@@ -27,9 +27,9 @@ Personal project, only tried on Fedora 44, KDE Plasma 6.7 on Wayland, NVIDIA
 GPU, Fcitx5 5.1.23 with the Pinyin engine. Animations, the right click menu,
 forgetting candidates and starting at login have been used on that setup.
 
-**`scripts/build.sh` has not been run from scratch in a clean environment**, and
-no other distribution or desktop has been tried. Please open an issue if
-something breaks.
+`scripts/build.sh` has been run from scratch in a clean directory once (Fedora 44),
+no other distribution or desktop has been tried. Please open an issue if something
+breaks.
 
 The addon is a fork of `classicui` and is built inside the Fcitx5 source tree,
 because Fcitx5's Wayland protocol wrappers are not installed by `fcitx5-devel`.
@@ -60,7 +60,11 @@ scripts/install.sh    # installs into ~/.local, nothing outside $HOME
 ```
 
 `build.sh` picks the Fcitx5 version from `pkg-config`, override it with
-`FCITX_VERSION`.
+`FCITX_VERSION`. The sources are fetched **by commit hash** and the hash is checked
+afterwards (a tag can be moved, a commit hash cannot be faked). A version without a
+pinned commit is refused unless you pass `FCITX_COMMIT=<sha>`. The plugin runs
+inside the input method and sees everything you type, so what it is built from
+matters.
 
 ## Use
 
@@ -114,7 +118,16 @@ When you pick *Forget candidate*, m3ui therefore also records the word in
 those words from the candidate list before every refresh.
 
 - Matching is exact on the full text of the candidate.
-- To bring a word back, delete its line and restart Fcitx5.
+- **It survives restarts**: the file is replaced atomically (temporary file,
+  `fsync`, rename, so a kill in the middle never leaves a half written list) and is
+  mode `600`. If a save fails the word stays hidden for that run and the save is
+  retried.
+- Changes made to the file by other programs or by hand are picked up without a
+  restart.
+- Only words forgotten **through the right click menu** are recorded. A word
+  forgotten with the Pinyin engine's own shortcut (`Ctrl+7`) is not, and if it comes
+  from a system dictionary it will show up again.
+- To bring a word back, delete its line.
 - This is a layer on top of the engine. With the stock classicui the words
   show up again.
 

README.md

@@ -22,7 +22,7 @@
 Fcitx5 5.1.23、拼音引擎上用过。动画、右键菜单、忘记候选词、开机自动启动
 在这套环境里都实际用过。
 
-**`scripts/build.sh` 没有在干净环境里从零完整跑过**,其他发行版和桌面也没有试过,
+`scripts/build.sh` 在干净目录里从零完整构建通过过一次(Fedora 44),其他发行版和桌面没有试过,
 遇到问题请开 issue。
 
 本插件是 `classicui` 的分支,需要在 Fcitx5 源码树内构建:Fcitx5 的 Wayland
@@ -54,6 +54,9 @@ scripts/install.sh    # 安装到 ~/.local,不改动 $HOME 以外的任何东西
 ```
 
 `build.sh` 会用 `pkg-config` 取已安装的 Fcitx5 版本,可以用 `FCITX_VERSION` 覆盖。
+源码是**按提交哈希**从 GitHub 取的并在取完后校验(标签可以被移动,提交哈希无法伪造),
+没有固定提交的版本会被拒绝,除非你自己用 `FCITX_COMMIT=<sha>` 指定。这个插件跑在输入法进程里,
+看得到你打的所有字,所以构建来源值得认真对待。
 
 ## 使用
 
@@ -107,7 +110,12 @@ systemctl --user daemon-reload && systemctl --user restart app-org.fcitx.Fcitx5@
 之前把它们从候选列表里摘掉。
 
 - 按候选词的完整文字精确匹配,只隐藏这个词本身。
-- 想恢复某个词:删掉文件里对应的一行,然后重启 Fcitx5。
+- **重启不会丢**:文件是原子写入的(先写临时文件、`fsync` 再改名,中途被杀也不会留下写坏的文件),
+  权限是 `600`;某次保存失败时这个词在本次运行里仍然隐藏,下次会重试写入。
+- 文件被别的程序或手动修改后会自动重新读取,不用重启。
+- 只有**通过右键菜单点"忘记候选词"**才会记录。用拼音自带的快捷键(`Ctrl+7`)忘记的词不会被记录,
+  这类词如果来自系统词库,下次还会出现。
+- 想恢复某个词:删掉文件里对应的一行即可。
 - 这是界面层的补充。换回原版 classicui 后,这些词会重新出现。
 
 ## KWin 淡出(可选,KDE Plasma)