diff --git a/README.en.md b/README.en.md
index f5d4e74..17ed0de 100644
--- a/README.en.md
+++ b/README.en.md
@@ -125,6 +125,9 @@ adaptive choice, remove the last three entries of `cordis.patch.yml` (the
 node scripts/build-client.mjs   # generates client.js from src/panel.js + src/qrcode.js
 node scripts/smoke.mjs          # host forwarding contract (HTTP/WS/Host/Origin/cookie/bind failure)
 node scripts/test-qr.mjs        # module-by-module comparison against the npm qrcode reference
+# test-qr.mjs compares against a reference implementation (test-only, never a runtime dep):
+#   mkdir -p /tmp/qr-oracle && cd /tmp/qr-oracle && npm init -y && npm i qrcode@1.5.4
+# elsewhere: QR_ORACLE_DIR=<dir> node scripts/test-qr.mjs
 node scripts/test-client.mjs    # browser contract (slot registration, render, route agreement)
 ```
 
diff --git a/README.md b/README.md
index ee5686b..d621be2 100644
--- a/README.md
+++ b/README.md
@@ -126,6 +126,9 @@ DSH 官方把「持久化设置」限制在回环页面：客户端由 `location
 node scripts/build-client.mjs   # 由 src/panel.js + src/qrcode.js 生成 client.js
 node scripts/smoke.mjs          # 宿主端转发契约（HTTP/WS/Host/Origin/cookie/绑定失败）
 node scripts/test-qr.mjs        # 与 npm qrcode 参考实现逐模块比对
+# test-qr.mjs 需要一个“参考实现”作为对照（仅测试用，不是运行时依赖）：
+#   mkdir -p /tmp/qr-oracle && cd /tmp/qr-oracle && npm init -y && npm i qrcode@1.5.4
+# 放在别处就用 QR_ORACLE_DIR=<dir> node scripts/test-qr.mjs
 node scripts/test-client.mjs    # 浏览器端契约（槽位注册、渲染、路由一致）
 ```
 
diff --git a/scripts/test-qr.mjs b/scripts/test-qr.mjs
index d8bede5..7f04d30 100644
--- a/scripts/test-qr.mjs
+++ b/scripts/test-qr.mjs
@@ -16,6 +16,9 @@ try {
   oracle = requireFromOracle('qrcode')
 } catch (error) {
   console.error(`cannot load the qrcode oracle from ${oracleDir}: ${error.message}`)
+  console.error('prepare it once with:')
+  console.error(`  mkdir -p ${oracleDir} && cd ${oracleDir} && npm init -y && npm i qrcode@1.5.4`)
+  console.error(`or point QR_ORACLE_DIR at a directory that already has it.`)
   process.exit(2)
 }