Add Troubleshooting section for UserPromptSubmit hook timeout error

Document the known hook timeout issue when NER engine takes >30s on
first run. Recommend increasing timeout to 60000ms or switching to
regex engine for faster processing. Added to both EN and ZH READMEs.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: haowu77

README.md

@@ -99,6 +99,53 @@ privacy-mask follows the [agentskills.io](https://agentskills.io) SKILL.md stand
 
 ---
 
+## Troubleshooting
+
+### `UserPromptSubmit hook error`
+
+If you see this error when sending images in Claude Code, it means the privacy-mask hook **timed out** before finishing. This is a known issue — the NER engine needs time to load the GLiNER model (~170MB) on first run. The image is usually still masked successfully despite the error message.
+
+**Fix: increase the hook timeout** in `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ~/.claude/hooks/privacy-mask.sh",
+            "timeout": 60000
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+The default timeout is 30000ms (30s). We recommend **60000ms (60s)** for NER engine, or 30000ms if you only use the regex engine.
+
+**Alternative: switch to regex engine** for faster processing (~2-5s vs ~20-30s):
+
+```bash
+# Edit ~/.claude/hooks/privacy-mask.sh or config.json
+# Set detection engine to regex
+privacy-mask mask screenshot.png --detection-engine regex
+```
+
+To change the default engine, edit `mask_engine/data/config.json`:
+
+```json
+{
+  "detection": { "engine": "regex" }
+}
+```
+
+---
+
 ## Detection Engines
 
 privacy-mask supports two detection engines, switchable via config or CLI:

README.zh.md

@@ -96,6 +96,45 @@ privacy-mask 遵循 [agentskills.io](https://agentskills.io) SKILL.md 标准，
 
 ---
 
+## 常见问题
+
+### `UserPromptSubmit hook error`
+
+在 Claude Code 中发送图片时看到此错误，表示 privacy-mask hook **处理超时**。这是已知问题——NER 引擎首次运行需要加载 GLiNER 模型（约 170MB）。尽管显示错误，图片通常仍然成功遮蔽。
+
+**解决方法：增加 hook 超时时间**，编辑 `~/.claude/settings.json`：
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ~/.claude/hooks/privacy-mask.sh",
+            "timeout": 60000
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+默认超时 30000ms（30 秒），NER 引擎建议设为 **60000ms（60 秒）**。如果只用 regex 引擎，30000ms 即可。
+
+**替代方案：切换到 regex 引擎**（处理速度 2-5 秒 vs NER 的 20-30 秒）：
+
+```json
+{
+  "detection": { "engine": "regex" }
+}
+```
+
+---
+
 ## 检测能力
 
 **47 条正则规则**，覆盖 **15+ 国家**：