Make every subcommand input an explicit CLI argument or option

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/decision_log.md

@@ -96,3 +96,26 @@
   逐連線設定）。裁定其歸屬為連線組態，實作於 `database.py`
   的 `__create_engine`——建 engine 時對 SQLite 註冊 connect
   listener，所有消費者全程生效，不再由 build-db 各自註冊。
+
+## 2026-08-02
+
+- **`import-lyrics` 不設為子命令，pilot 歌詞改以私人腳本
+  匯入**。理由：pilot 捕捉檔不隨論文發布，子命令
+  形式會在發布的 CLI 裡留下讀者無法執行的死命令——要交待的
+  是「沿用 pilot 捕捉」的事實（記於 lyrics_provenance.csv 與
+  論文方法節），不是工具本身；工具移出專案，發布管線即
+  「讀者可完整執行的程序」。讀者重現歌詞的路徑為
+  `fetch-lyrics`，API 漂移造成的差異屬捕捉層的已承認限制。
+  provenance 的 method 值域定為
+  pilot-import / api-fetch / manual。
+- **資料路徑全面改為顯式 CLI 引數**——必要運算元為位置
+  引數、選擇性輸入為選項（build-db 吃榜單 CSV 一個位置引數，
+  歌詞目錄、Wikidata 快照、overrides 為 `--lyrics-dir`／
+  `--wikidata-csv`／`--overrides-csv` 三個選項；fetch-lyrics
+  吃歌詞目錄、provenance、缺漏報表三個位置引數；fetch-artists
+  吃快照檔；run-llm 吃 runs 目錄），命令與 CWD 無關，且每次
+  執行觸碰的檔案完整見於指令本身。省略選項即不載入該捕捉層；
+  給了選項而路徑不存在即建置失敗，取代原本的默默跳過。理由：
+  settings 的 `.env` 依 pydantic 慣例讀自 CWD（約定
+  `tools/`），資料路徑原以 repo 根為 CWD，兩者衝突；顯式引數
+  消滅隱性 CWD 契約，亦拒絕以父目錄推導兄弟檔案的隱性慣例。

docs/project_structure.md

@@ -39,8 +39,8 @@ pop-fem-audit/
 │   │   │                      #   public APIs into data/lyrics/
 │   │   ├── models.py          # SQLAlchemy ORM 資料模型
 │   │   └── run_llm.py         # API runner：2+1 協定、Batch API、
-│   │                          #   自動寫入 runs/；執行方式
-│   │                          #   pop-fem-audit-tools run-llm
+│   │                          #   寫入引數指定的 runs 目錄；執行
+│   │                          #   方式 pop-fem-audit-tools run-llm
 │   └── tests/                 # 單元測試（unittest）
 ├── runs/                      # 每次執行的完整稽核紀錄（進 git）
 │   └── <階段>/<日期>-<定義檔版本>/

docs/research_plan.md

@@ -56,16 +56,20 @@
   維持歌詞-only，避免光環偏誤污染條件 A/B 實驗。women-power
   候選歌曲的歌手另做深度背景（族裔以公開自我認同為準、音樂
   場景），script 輔助、人工核定。
-- **Pilot 歌詞沿用**：先導研究捕捉檔（lyrics.json，684 首，
-  2018–2025）匯入歌詞快取——只取識別欄位與歌詞本文，pilot
-  的分析欄位一律不匯入；以 (year, rank) 精確匹配 song_id。
-  出處記於 `data/lyrics_provenance.csv`（進 git）：`source`
-  （原始 API）與 `method`（pilot-import / api-fetch）兩層，
-  取得日期不可考者不假造，僅記可證上界。
+- **Pilot 歌詞沿用（私人匯入，不進發布管線）**：先導研究
+  捕捉檔（lyrics.json，684 首，2018–2025）以私人腳本
+  匯入歌詞快取——只取識別欄位與歌詞本文，以
+  (year, rank) 精確匹配 song_id。匯入工具不屬於專案交付物
+  （讀者拿不到其輸入），讀者的重現路徑純粹是 `fetch-lyrics`；
+  沿用之**事實**記於 `data/lyrics_provenance.csv`（進 git）：
+  `source`（原始 API）與 `method`
+  （pilot-import / api-fetch / manual）兩層，取得日期不可考者
+  不假造，僅記可證上界。
 - **子命令**（`pop-fem-audit-tools <cmd>` 或
-  `python -m pop_fem_audit_tools <cmd>`）：`run-llm`（已完成）、
-  `build-db`、`import-lyrics`、`fetch-lyrics`、`fetch-artists`、
-  `export-llm-input`；之後再加報表 export 與統計。
+  `python -m pop_fem_audit_tools <cmd>`）：`run-llm`、
+  `build-db`、`fetch-lyrics`、`fetch-artists`（皆已完成）、
+  `export-llm-input`（階段 2 前補上）；之後再加報表 export
+  與統計。
 
 ## 階段與時程（全文截稿 2026-08-15）