refactor: split CLI design rules into cli-design/ directory

Replace monolithic cli-textutil-compat.md with structured directory:
- unix-conventions.md — Unix CLI general conventions
- textutil-compat.md — macOS textutil syntax mapping
- convert-entry-point.md — convert unified entry point rules
- error-and-output.md — error messages and output conventions

Author: kiki830621

.claude/rules/cli-design/convert-entry-point.md

@@ -0,0 +1,33 @@
+# convert 統一入口規範
+
+## 原則
+
+所有格式轉換必須走 `macdoc convert --to <format> <file>` 統一入口。
+舊的 per-format 子命令（`word`, `html`, `srt`）保留為 alias，但 help text 提示改用 `convert`。
+
+## 新增轉換路由的步驟
+
+1. 在 `MacDoc+Convert.swift` 的 `switch (ext, target)` 加 case
+2. 寫對應的 `private func convert<Source>To<Target>(inputURL:)` 方法
+3. 用 `validatedInputURL()` 驗證輸入（不要自己寫 guard）
+4. 用 `writeStringOutput()` 或 `convertToFile/convertToStdout` 輸出
+5. 支援 `--full` 和 `--css`（如果輸出 HTML）
+6. Error messages 用中文（`找不到輸入檔案:`）
+
+## 已接線的路由
+
+```
+(docx, md)  → WordConverter
+(html, md)  → HTMLConverter
+(md, html)  → MarkdownConverter
+(srt, html) → SRTConverter（支援 --full + --css dark|light）
+(bib, html) → BibToAPAHTMLFormatter（支援 --full + --css minimal|web）
+(bib, md)   → BibToAPAFormatter
+(bib, json) → BibToAPAJSONFormatter
+```
+
+## 不該做的事
+
+- 不要建新的 top-level subcommand 來做轉換（用 `convert`）
+- 不要在 `convert` 裡重複實作 CLIHelpers 已有的功能
+- 不要用英文 error messages

.claude/rules/cli-design/error-and-output.md

@@ -0,0 +1,31 @@
+# Error Messages 與輸出規範
+
+## Error Messages
+
+- 語言：**繁體中文**
+- 用 `validatedInputURL()` 統一處理（輸出 `找不到輸入檔案: <path>`）
+- 不要自己寫 `guard FileManager.default.fileExists`
+
+```swift
+// 正確
+let inputURL = try validatedInputURL(input)
+
+// 錯誤 — 不要這樣寫
+guard FileManager.default.fileExists(atPath: inputURL.path) else {
+    throw ValidationError("File not found: \(input)")  // ← 英文，不一致
+}
+```
+
+## 輸出
+
+- 用 `writeStringOutput(_:to:)` 統一處理 file/stdout 分流
+- 寫入檔案後的狀態訊息寫到 stderr：`已寫入: <path>`
+- 不要重複實作 output 邏輯
+
+## CSS / Full Document
+
+- `--full` 輸出完整 HTML 文件（DOCTYPE + head + CSS + body）
+- `--css` 選擇 CSS 風格（值因格式而異）
+- bib: `minimal`（學術 Times New Roman）, `web`（現代系統字體）
+- srt: `dark`（深色主題）, `light`（淺色/列印）
+- 不指定 `--full` 時只輸出 HTML fragment

.claude/rules/cli-design/textutil-compat.md

@@ -0,0 +1,33 @@
+# textutil 語法對映
+
+macdoc 的 `convert` 子命令語法與 macOS 內建 `textutil` 對齊。
+使用者如果會用 `textutil`，應該能直覺地使用 `macdoc`。
+
+## textutil → macdoc 對照
+
+```bash
+# textutil                          # macdoc
+textutil -convert html file.docx    macdoc convert --to html file.docx
+textutil -info file.docx            macdoc info file.docx    (planned)
+textutil -convert txt -output o.txt macdoc convert --to md --output o.md file.docx
+textutil -convert html -stdout      macdoc convert --to html --stdout file.md
+```
+
+## 語法差異
+
+| textutil | macdoc | 理由 |
+|----------|--------|------|
+| `-convert html` | `--to html` | swift-argument-parser 慣例用 `--` long flags |
+| `-output file` | `--output file` | 同上 |
+| `-format txt` | (自動偵測) | 從副檔名推斷，更簡潔 |
+| `-cat` | (不支援) | 合併多檔不在 scope 內 |
+
+## Format 短名
+
+| --to 值 | 全名 | 對應 package |
+|---------|------|-------------|
+| `md` | Markdown | `word-to-md`, `html-to-md`, `pdf-to-md` |
+| `html` | HTML | `md-to-html`, `srt-to-html`, `bib-apa-to-html` |
+| `docx` | Word | `md-to-word`, `html-to-word`, `pdf-to-docx` |
+| `json` | JSON | `bib-apa-to-json` |
+| `latex` | LaTeX | `pdf-to-latex` |

.claude/rules/cli-design/unix-conventions.md

@@ -0,0 +1,14 @@
+# Unix CLI 通用慣例
+
+macdoc CLI 遵循標準 Unix 命令列工具的設計慣例。
+
+## 規則
+
+1. **檔案放最後** — `macdoc convert --to md file.docx`，不是 `macdoc convert file.docx --to md`
+2. **stdout 是預設輸出** — 不指定 `--output` 時寫到 stdout，可 pipe 給其他工具
+3. **stderr 寫狀態訊息** — 進度、警告、「已寫入: path」等用 `FileHandle.standardError`
+4. **exit code** — 0 = 成功，非零 = 失敗（swift-argument-parser 自動處理）
+5. **input format 從副檔名自動偵測** — 不需要使用者指定 `--from`
+6. **`--stdout` 強制輸出到 stdout** — 覆蓋 `--output`（stdout 優先）
+7. **`--` long flags** — 遵循 GNU 慣例（`--to`, `--output`, `--full`），不用單 dash
+8. **靜默原則** — 成功時不輸出多餘訊息到 stderr，除非寫檔時報告路徑

.claude/rules/cli-textutil-compat.md

@@ -29,7 +29,7 @@ macdoc 必須優先使用 macOS 原生 framework 處理文件，不引入外部
 
 ## textutil 能力對照
 
-`textutil` 是 macOS 內建的文件轉換 CLI，macdoc 的轉換指令語法與其相容（見 `cli-textutil-compat.md`）。
+`textutil` 是 macOS 內建的文件轉換 CLI，macdoc 的轉換指令語法與其相容（見 `cli-design/textutil-compat.md`）。
 
 | textutil 支援 | macdoc 對應 | 差異 |
 |--------------|------------|------|
@@ -45,5 +45,5 @@ macdoc 必須優先使用 macOS 原生 framework 處理文件，不引入外部
 - [ ] 基礎提取用原生 framework（PDFKit / Vision / CoreGraphics）
 - [ ] 不引入可用原生替代的外部依賴
 - [ ] 如果需要外部依賴，記錄在上方「允許的例外」
-- [ ] CLI 語法遵循 `cli-textutil-compat.md`
+- [ ] CLI 語法遵循 `cli-design/` 規範（unix-conventions + textutil-compat + convert-entry-point）
 - [ ] 在 `CONVERSIONS.md` 更新轉換矩陣