Add a first-run checklist for future sessions

Constraint: New sessions need a minimal startup checklist so they can verify repo health and resume development quickly
Rejected: Keep startup knowledge implicit in long docs only | Increases ramp-up time and the chance of missing key checks
Confidence: high
Scope-risk: narrow
Directive: Update this checklist whenever the default startup workflow or open-dataset commands materially change
Tested: existence checks for acr-engine/FIRST_RUN_CHECKLIST.md, docs/README.md, docs/session-handoff.md, plus docs link-presence checks
Not-tested: Human walkthrough of the full checklist from a fresh shell

+# First Run Checklist
+
+Use this checklist when a new session starts working on the repo.
+
+## 1. Read docs
+- `docs/README.md`
+- `docs/open-dataset-workflow.md`
+- `docs/session-handoff.md`
+
+## 2. Verify repo health
+```bash
+git status --short
+```
+
+## 3. Verify open-dataset tooling
+```bash
+/usr/local/miniconda3/bin/python -m py_compile src/data/external_adapters.py src/data/manifest_tools.py train.py run_demo.py evaluate.py
+```
+
+## 4. Verify drop zones
+- `data/raw/fma_small_audio/`
+- `data/raw/mtg_jamendo_audio/`
+
+## 5. If real local audio exists, run smoke
+```bash
+/usr/local/miniconda3/bin/python src/data/external_adapters.py smoke-local fma data/raw/fma_small_audio --output-root data/external_smoke --eval-ratio 0.2 --query-duration 8.0 --train-epochs 1 --batch-size 2
+```
+
+## 6. If real local audio does not exist
+- continue using synthetic stand-ins
+- or continue improving ingestion/benchmark/documentation paths

@@ -164,6 +164,21 @@
 - 现在真实开放数据只需要放进明确目录即可
 - 现在真实开放数据只需要放进明确目录即可
 - 后续替换真实 FMA / MTG-Jamendo 本地音频时无需再猜目录结构
 - 后续替换真实 FMA / MTG-Jamendo 本地音频时无需再猜目录结构
 
 
+### Stage: 新 session 首次启动清单
+
+完成项：
+- 新增 [acr-engine/FIRST_RUN_CHECKLIST.md](../acr-engine/FIRST_RUN_CHECKLIST.md)
+- 把最常用启动检查命令与读文档顺序固化到 repo
+- 将 checklist 接入 [docs/README.md](./README.md) 与 [docs/session-handoff.md](./session-handoff.md)
+
+验证结果：
+- `FIRST_RUN_CHECKLIST.md` 已创建
+- docs 入口已挂接 checklist
+
+结论：
+- 新 session 现在可以更快进入有效开发状态
+- 启动成本和漏看关键文档/命令的风险进一步下降
+
 ### Stage: confused 定向优化 v6（sample-level weighting）
 ### Stage: confused 定向优化 v6（sample-level weighting）
 
 
 完成项：
 完成项：

@@ -70,6 +70,7 @@ flowchart TD
 ### C. 服务与工程
 ### C. 服务与工程
 - [服务接口](./service-api.md)
 - [服务接口](./service-api.md)
 - [持续开发交接文档](./session-handoff.md)
 - [持续开发交接文档](./session-handoff.md)
+- [首次启动检查清单](../acr-engine/FIRST_RUN_CHECKLIST.md)
 - [更新记录](./CHANGELOG.md)
 - [更新记录](./CHANGELOG.md)
 
 
 ### D. 研究与路线
 ### D. 研究与路线

@@ -274,6 +274,7 @@
    - [docs/README.md](./README.md)
    - [docs/README.md](./README.md)
    - [docs/open-dataset-workflow.md](./open-dataset-workflow.md)
    - [docs/open-dataset-workflow.md](./open-dataset-workflow.md)
    - [docs/session-handoff.md](./session-handoff.md)
    - [docs/session-handoff.md](./session-handoff.md)
+   - [acr-engine/FIRST_RUN_CHECKLIST.md](../acr-engine/FIRST_RUN_CHECKLIST.md)
 
 
 2. 检查真实数据是否已落位：
 2. 检查真实数据是否已落位：
    - `acr-engine/data/raw/fma_small_audio/`
    - `acr-engine/data/raw/fma_small_audio/`