docs: rewrite audit, design adrs and m1 plan

.trellis/spec/data/index.md

@@ -6,7 +6,7 @@ and the shared foundation in `lib/core/` (errors, logger, constants, utils).
 
 Neither directory imports `lib/services/` or `lib/providers/` (one recorded
 exception, `lib/core/extensions/track_extensions.dart`, in
-`test/support/layer_boundary_static_rule_test.dart`) — see AGENTS.md § Boundaries. Vocabulary for auth and media handoff is in `CONTEXT.md`.
+`test/support/layer_boundary_static_rule_test.dart`) — see AGENTS.md § Boundaries. Vocabulary for auth and media handoff is in `services/download-and-auth.md` § Auth vocabulary.
 
 ## Guidelines
 

.trellis/spec/data/sources.md

@@ -78,7 +78,7 @@ Adapters never read accounts. Credentials arrive per request as
 `getVideoDetail(…, {authHeaders})`, `parsePlaylist(…, {authHeaders})`), and the
 adapter keeps only what it needs (`NeteaseSource._withAuth` keeps `Cookie`). The
 caller side is `SourceAuthContext` in `lib/services/account/`; the terms are
-defined in `CONTEXT.md`.
+defined in `services/download-and-auth.md` § Auth vocabulary.
 
 ## Errors: one `SourceApiException` subtype per source
 

.trellis/spec/guides/cross-layer-thinking-guide.md

@@ -48,6 +48,6 @@ relinked in the same transaction.
 
 ### Anything about credentials
 
-Name which of the `CONTEXT.md` terms applies: Stream Resolution Auth
+Name which of the auth vocabulary terms (`services/download-and-auth.md`) applies: Stream Resolution Auth
 (adapter request) and Media Request Credentials (byte request, empty by
 construction) are different arrows. Changing either needs the user's approval.

.trellis/spec/services/download-and-auth.md

@@ -1,6 +1,32 @@
 # Download pipeline, media handoff, accounts
 
-Vocabulary: `CONTEXT.md`. Storage paths and Android permissions: ADR 0004.
+Vocabulary: § Auth vocabulary below (the principle is recorded in ADR 0012).
+Storage paths and Android permissions: ADR 0004.
+
+## Auth vocabulary
+
+Use these terms as defined; avoid the synonyms in brackets.
+
+- **Source Auth Context** — the policy that decides which source credentials a
+  given source operation may use; distinct from account login and credential
+  storage. (Not: auth helper, header utility, account service.)
+- **Media Handoff** — the move from a resolved stream URL to the audio or
+  download backend: redirect checks, per-hop media headers, resumed-download
+  range headers, and Source Auth Context credentials narrowed into Media Request
+  Credentials. (Not: playback URL helper, download header helper.)
+- **Stream Resolution Auth** — credentials used while asking a source adapter to
+  resolve or refresh a stream URL; broader than Media Request Credentials and may
+  include Bilibili or YouTube auth that must never reach a media/CDN request.
+  (Not: media auth, playback headers.)
+- **Auth For Play** — the user setting that gates credentials for stream
+  resolution, playback handoff, download, track detail and auth-aware
+  metadata/detail paths; it does not control playlist import, playlist refresh
+  or search. (Not: import auth, search auth.)
+- **Media Request Credentials** — credentials allowed on the actual audio byte
+  request. There are none: `SourceHttpPolicy.mediaHeaders(String sourceType)`
+  (`lib/data/sources/source_http_policy.dart`) takes only the source id, so no
+  cookie or token can reach the media host through it; the former Netease media
+  allowlist was removed in `c09aec10`. (Not: stream auth, source auth.)
 
 ## Download (`lib/services/download/`)
 
@@ -35,8 +61,8 @@ Media byte requests — playback and download — carry only
 `SourceHttpPolicy.mediaHeaders(sourceType)` plus `Range`.
 `streamResolutionAuth` is carried through but deliberately unused. Stream
 Resolution Auth is for asking the adapter for a URL, never for fetching the
-bytes. Do not add credentials here without changing `CONTEXT.md` and getting the
-user's approval.
+bytes. Do not add credentials here without changing § Auth vocabulary and getting
+the user's approval.
 
 ## Accounts and credentials (`lib/services/account/`)
 

.trellis/spec/services/index.md

@@ -5,7 +5,7 @@ radio, search, cache, network, platform, update, backup, and the shared
 `ToastService` / image-loading services in `lib/core/services/`.
 
 Terms used here — Source Auth Context, Media Handoff, Auth For Play, Media Request
-Credentials — are defined in `CONTEXT.md`; use them as defined.
+Credentials — are defined in `download-and-auth.md` § Auth vocabulary; use them as defined.
 
 ## Guidelines
 
@@ -21,7 +21,7 @@ Error and logging rules shared with other layers: [../shared/errors-and-logging.
 
 - [ ] Audio change → read `audio.md` and ADR 0003 (two backends). UI calls `AudioController`, never `FmpAudioService`; radio is the one exception (AGENTS.md § Boundaries).
 - [ ] Download / storage path change → read `download-and-auth.md` and ADR 0004.
-- [ ] Anything that decides which credentials go where → read `CONTEXT.md` first. Changing the auth boundary needs the user's approval (AGENTS.md § Conventions).
+- [ ] Anything that decides which credentials go where → read `download-and-auth.md` § Auth vocabulary first. Changing the auth boundary needs the user's approval (AGENTS.md § Conventions).
 - [ ] A new repeating timer, outbound host or cross-feature import → plan the static-rule entry with its reason.
 
 ## Quality Check

.trellis/tasks/09-26-fmp-rewrite/milestones.md

@@ -0,0 +1,145 @@
+# 里程碑清單（ADR 0026）
+
+> 每完成一個里程碑或平台任務，就更新它的「狀態」與驗收勾選。
+> 範圍若在開工時要大改，先改這份清單並寫明原因。
+> 「§7」「§8」指 `phase2-plan.md` 的第 7 節（第一個里程碑的必要驗證）與第 8 節（延後的實測）。
+
+| # | 里程碑 | 依賴 | 狀態 |
+|---|---|---|---|
+| M1 | 骨架＋曳光彈 | — | 進行中（`09-28-m1-skeleton-tracer`） |
+| M2 | 完整播放 | M1 | 未開始 |
+| M3 | 三音源、帳號與開發工具 | M2 | 未開始 |
+| M4 | 音樂庫與同步 | M3 | 未開始 |
+| M5 | 舊資料匯入 | M4 | 未開始 |
+| M6 | 下載 | M5 | 未開始 |
+| M7 | 歌詞 | M5 | 未開始 |
+| M8 | 桌面整合 | M2 | 未開始 |
+| M9 | 發版、更新與切換 | M1–M8 | 未開始 |
+| L | Linux 平台 | M1 | 未開始 |
+| Mac | macOS 平台 | Mac 到貨 | 未開始 |
+| iOS | iOS 平台 | Mac 到貨 | 未開始 |
+
+- M6、M7 互不依賴，可以對調。
+- M8 放在 M7 之後，是因為它不擋試用。
+
+## M1 骨架＋曳光彈
+
+- **做完**：Android、Windows 上能搜尋 B 站並連續播放兩首。
+- **範圍**：
+  - `app/` 新專案，Flutter 用當時的 stable；`app/AGENTS.md`；flavor dev／prod 與 App 身分；單一實例鎖（ADR 0008、0015）。
+  - `fmp_lints` 與接線哨兵；CI 以 `dorny/paths-filter` 切分、五平台編譯、`always()` 彙總（ADR 0015 §9）。
+  - 平台層骨架與能力宣告（ADR 0009）。
+  - drift 最小 schema 與快照（ADR 0010）。
+  - log 門面、遮蔽函式、log 檔（ADR 0011）。
+  - 網路層（不含登入，ADR 0012）、錯誤模型（ADR 0013）。
+  - JS 執行環境、宿主 API 最小集、以「從檔案安裝」載入 B 站插件（ADR 0014）。
+  - 播放核心最小集：兩個後端、兩首的佇列、前瞻交接（ADR 0018）。
+  - `ToastHost` 與 `Toaster`（ADR 0023）。
+  - token、斷點、字型、slang 三語言骨架、播放快捷鍵（ADR 0024）。
+  - `app/` 發版 workflow 以 release-please dry-run 驗證（ADR 0022）。
+- **限時探針**：YouTube.js 可行性。失敗就在 M3 以 Dart 實作 YouTube（ADR 0014）。
+- **驗收**：
+  - [ ] 兩平台端到端操作
+  - [ ] §7 全部項目
+- **之後**：開 Linux 平台任務。
+
+## M2 完整播放
+
+- **做完**：以單一音源像舊版一樣日常聽歌。
+- **範圍**：
+  - 完整 `QueueModel` 與 `RecoveryPolicy`（ADR 0018）；
+  - 播放頁方案 B、播放列三段、App 內快捷鍵全表、焦點三區（ADR 0024）；
+  - 系統媒體控制；速度、音量、輸出裝置（E19）；播放歷史（E15）；
+  - 統一快取庫與離線狀態（ADR 0016）；
+  - 背景排程器與啟動維護清單（ADR 0017），含 log 保留 7 天（ADR 0025）。
+- **驗收**：
+  - [ ] 兩平台端到端操作
+  - [ ] ADR 0016、0017、0018 的測試
+
+## M3 三音源、帳號與開發工具
+
+- **做完**：三個音源都能搜尋、播放、登入。
+- **範圍**：
+  - YouTube、網易雲插件；B 站分 P（E2）、Mix（E13）、電台直播（E12）；
+  - 帳號與 `CredentialStore`、`AuthRequirement`（ADR 0012，E6）；
+  - `1morr/fmp-plugins` repo、CI、`index.json`；插件頁；首次啟動引導（ADR 0014）；
+  - Debug 頁與插件開發工具（ADR 0025、0015 §7）；錯誤詳細頁、GitHub 回報、`.github/ISSUE_TEMPLATE/bug_report.yml`（ADR 0023）。
+- **驗收**：
+  - [ ] 兩平台端到端操作
+  - [ ] §8：YouTube App 內網頁登入（ADR 0012）
+  - [ ] §8：加入 Debug 頁的里程碑實測（ADR 0025）
+
+## M4 音樂庫與同步
+
+- **做完**：建歌單、匯入並刷新平台歌單、匯入 Spotify／QQ 歌單。
+- **範圍**：
+  - 關聯表與孤兒清理（ADR 0019）；本機歌單（E3）；
+  - 匯入與刷新（E4）；僅元資料來源的匹配（E5）；遠端歌單編輯（E7）；
+  - 首頁排行（E14）；新格式的備份與還原（E16）。
+- **驗收**：
+  - [ ] 兩平台端到端操作
+  - [ ] `opencc` native assets 在各平台建置（ADR 0019）
+
+## M5 舊資料匯入
+
+- **做完**：首次啟動自動匯入舊版的歌單、曲目、歷史、設定、帳號；也能匯入舊備份檔。
+- **範圍**：`legacy_import`（ADR 0010）：先寫暫存庫、驗證後才換上；錯誤頁；「刪除舊版資料」。
+- **驗收**：
+  - [ ] 以擁有者的真實資料副本完整匯入，比對筆數
+  - [ ] 擁有者開始以 dev flavor＋真實資料副本日常試用
+
+## M6 下載
+
+- **範圍**：ADR 0020 全部（E8）；匯入舊下載紀錄。
+- **驗收**：
+  - [ ] 兩平台端到端操作
+  - [ ] §8：加入下載的里程碑實測（ADR 0020）
+
+## M7 歌詞
+
+- **範圍**：
+  - ADR 0021 全部（E9–E11）；
+  - 官方 AI 插件 `openai-compatible`、`system-one`；
+  - 舊歌詞配對以 `manual` 匯入。
+- **驗收**：
+  - [ ] 兩平台端到端操作
+  - [ ] §8：桌面歌詞、Android 懸浮歌詞、逐字的里程碑實測（ADR 0021）
+
+## M8 桌面整合
+
+- **範圍**：托盤、全域快捷鍵、開機自啟、關閉縮到托盤（E18）；設定頁「鍵盤快捷鍵」列出兩組（ADR 0024）。
+- **驗收**：
+  - [ ] Windows 端到端操作
+  - [ ] 錄製全域快捷鍵時，與 App 內快捷鍵衝突會提示
+
+## M9 發版、更新與切換
+
+- **範圍**：
+  - 應用內更新（ADR 0022，E17）；
+  - `docs/user-guide.md` 與關於頁（ADR 0024）；
+  - 切換 PR（ADR 0008 §決定 5）：刪除根目錄舊專案、`docs/audit/`、ADR 0001–0007；`release.yml`、`ci.yml`、`orca.yaml`、`tool/release/` 改指向 `app/`。
+- **驗收**（ADR 0026 §決定 5）：
+  - [ ] 功能清單 E1–E17 與各 ADR 行為逐項通過
+  - [ ] 舊版與新版同機各量 5 次，新版每項不差超過 5%
+  - [ ] 真實資料副本完整匯入，並比對筆數
+  - [ ] 從 v1.11.0 實際升級：Android、Windows 安裝版、Windows 免安裝版（§8，ADR 0022）
+  - [ ] Windows 自行下載的安裝檔不帶 Mark of the Web
+  - [ ] App 身分比對（ADR 0008）
+  - [ ] 試用 2 週，沒有未解決的阻擋性 bug
+
+## 平台任務
+
+- **Linux**（M1 之後）：
+  - 驗收在 VMware Workstation Pro 的 Ubuntu LTS 桌面虛擬機，X11 與 Wayland 各一次；日常開發用 WSL2。
+  - 之後每個里程碑在虛擬機跑一次冒煙測試。
+  - [ ] §8：沒有 keyring 時的 secure storage（ADR 0012）
+  - [ ] §8：X11／Wayland 桌面歌詞（ADR 0021）
+  - [ ] §8：AppImage 改名替換（ADR 0022）
+- **macOS**（Mac 到貨後）：
+  - [ ] §8：AVPlayer 對 B 站 DASH 與直播 HLS（ADR 0018）
+  - [ ] §8：桌面歌詞（ADR 0021）
+  - [ ] §8：更新不帶 quarantine（ADR 0022）
+- **iOS**（Mac 到貨後，實機與付費帳號在該任務決定）：
+  - [ ] §8：AVPlayer 對 B 站 DASH 與直播 HLS（ADR 0018）
+  - [ ] §8：Live Activity 本機逐行更新（ADR 0021）
+- 各平台實機驗證完才發佈（ADR 0009）。