indexion-readme

indexion readme — README 建構

從模板、文件註解、手寫文章及各套件 README 建構專案 README。此技能涵蓋建構面：建立骨架、產生、規劃、組合及驗證。如需評估既有文件，請參閱 indexion-documentation。

檔案位置

各專案慣例不同；編輯前請先確認實際存在的檔案：

資產	常見位置模式
設定檔	doc.json（專案根目錄）或 .indexion/readme/doc.json
各套件模板	docs/templates/readme.md（無固定來源；透過 --template 宣告）
靜態文章	docs/intro.md、docs/installation.md、docs/license.md、…
各套件 README	cmd/<name>/README.md、src/<name>/README.md
組合後的根 README	通常是 README.md。部分專案使用 .mbt.md 後綴，使檔案同時為 MoonBit doctest 模組 — 此時 README.md 是 README.mbt.md 的符號連結。
.indexion.toml	[doc] config_path / per_package 自動載入 doc.json

首先要檢查的是 git diff / ls -la：README.md 是否為符號連結、是否有 doc.json（在根目錄或 .indexion/readme/ 下）、以及 .indexion.toml。這些檔案的存在告訴你 README 是手動維護、建構組合、還是混合模式。

工作流程概覽

doc init                      → .indexion/readme/template.md + doc.json（全新專案）
編輯 doc.json + docs/*.md     → 宣告事實來源
doc readme --per-package      → cmd/<pkg>/README.md（API 骨架；不覆寫）
手寫各套件 README 的 Overview / Usage / Options / Examples
doc readme --config           → 組合後的根 README
plan drift <舊版> <新版>       → 驗證組合輸出（或手動編輯）僅為新增內容

步驟 1：初始化（僅限全新專案）

indexion doc init <專案目錄>

建立 .indexion/readme/template.md + .indexion/readme/doc.json。若專案已有 doc.json 或 .indexion.toml 指向設定檔，則跳過此步驟。

步驟 2：設定 doc.json

{
  "$schema": "./schemas/doc-config.schema.json",
  "version": "1.0",
  "spec": "moonbit",
  "output": { "format": "markdown", "filename": "README.md" },
  "packages": [
    {
      "path": "cmd/<name>",
      "title": "<命令名稱>",
      "include_in_root": true,
      "sections": ["overview", "usage"]
    }
    // …每個應出現在組合後根 README 的套件一個條目
  ],
  "root": {
    "output": "README.md",
    "sections": [
      { "type": "static",   "file": "docs/intro.md" },
      { "type": "toc",      "title": "命令" },
      { "type": "packages", "filter": "cmd/**" },
      { "type": "static",   "file": "docs/installation.md" },
      { "type": "static",   "file": "docs/license.md" }
    ]
  }
}

根區段類型：

• static — 直接包含 markdown 檔案內容
• toc — 插入目錄標題
• packages — 從 packages 陣列中拉入符合 glob 篩選的條目

套件欄位：

• include_in_root — 是否包含在組合後的根 README 中
• sections — 要擷取的 README 標題；由各套件擷取流程使用。請注意，根區段中的 { "type": "packages" } 目前輸出的是套件連結的表格，而非各套件 sections 所暗示的豐富 Overview/Usage 展開。請參閱下方「已知限制」。

步驟 3：產生各套件 README

indexion doc readme --per-package src/ cmd/

在尚未有 README 的套件目錄中產生 README.md。不覆寫 — 既有的各套件 README 保持不變。

骨架僅包含 API（透過 KGF 從 /// 文件註解擷取）。將其視為起點，之後再手寫文章區段（Overview、Usage、Options、Examples）。

# 單一套件輸出至 stdout
indexion doc readme src/kgf/lexer/

# 單一套件輸出至檔案
indexion doc readme -o=README.md src/kgf/lexer/

關於副作用：doc readme --template=<t> <paths...>（以下基於模板的模式）會遍歷給定路徑，並自動建立缺少 README 的套件 — 即使沒有 --per-package。若在寬泛路徑（cmd/、src/）上執行，可能會在不相關的套件中產生新檔案。請使用狹窄路徑執行，或事後透過 git status 清理非預期的建立。

步驟 4：撰寫靜態內容

建立 docs/intro.md、docs/installation.md 等 — 即 root.sections 所引用的檔案。這些是手寫文章；組合器會直接引入。

步驟 5：產生寫作計劃（可選）

indexion plan readme --template=docs/templates/readme.md --plans-dir=.indexion/plans src/

為每個區段輸出寫作任務，供手動或 LLM 輔助撰寫。

步驟 6：組合 README

# 設定驅動（建議；doc.json 控制版面與套件列表）
indexion doc readme --config=doc.json

# 模板驅動（替代方案；使用 {{include:…}} 與 {{packages}} 佔位符）
indexion doc readme --template=docs/templates/readme.md -o=README.md cmd/

設定檔路徑可位於專案根目錄或 .indexion/readme/ 下。若 .indexion.toml 設有 [doc] config_path = "…"，則 --config= 旗標可省略。

步驟 7：使用 plan drift 驗證

在重新產生或任何對根 README 的手動編輯後，驗證變更僅為新增（無靜默刪除、無無關區段重排）：

# 快照前一版本
git show HEAD:README.md > /tmp/README.before.md

# 與新版本比較
indexion plan drift --top=20 /tmp/README.before.md README.md

輸出中應注意：

• Drift terms in /tmp/README.before.md (missing on the other side): (none) — 無內容被移除
• Drift terms in README.md (missing on the other side): … — 正是你打算新增的詞彙（命令名稱、新旗標、新概念）
• Cosine similarity 接近 1.0 表示小幅新增變更；若大幅低於 1.0 則表示你重組了某個區段

用於 CI 整合：

indexion plan drift --vocab-threshold=0.05 /tmp/README.before.md README.md
# 若 cosine_distance > 0.05 則退出碼為 1 — 可作為防止意外大幅改寫的防護

相同工作流程也適用於翻譯後的 README 配對（README.md ↔ README-ja.md）：跨語言漂移檢測原生支援，因為詞彙子標記化委派給 kgfs/natural/ 中的自然語言 KGF。

模板語法

模板檔案支援 {{placeholder}} 替換：

佔位符	展開內容
{{include:path}}	檔案內容（相對於專案根目錄）
{{packages}}	所有發現的套件（由 CLI --include / --exclude 篩選）
{{module_doc}}	僅模組層級的文件

.indexion.toml 整合

[doc]
config_path = "doc.json"   # 自動載入 doc.json，無需 --config
per_package = true         # 使 `doc readme <path>` 預設為 --per-package

明確的 --config=… 始終優先。

已知限制：packages 根區段產生表格，而非豐富展開

doc-config.schema.json 允許每個 packageEntry 設定 sections: ["overview", "usage", …]，但目前的 doc readme --config 實作在根區段輸出 { "type": "packages" } 時，並未內聯展開這些區段。輸出僅為套件連結的 markdown 表格，且描述為空。

兩個實際後果：

1. 若專案已簽入的根 README 包含豐富的每個命令 Overview / Usage 段落，則這些段落並非由目前的 doc readme --config 產生。它們是手動維護的。將 doc readme --config -o=/tmp/regen.md 與已簽入的 README 進行 diff，可了解其中有多少是手動維護的；差異極大表示 README 主要是手動維護。
2. 對於新命令，你目前需要同時手動將豐富區段編輯到組合後的 README 中，此外還需將套件條目加入 doc.json 並撰寫各套件 README。使用上述 plan drift 驗證來確認手動編輯僅新增、不刪除。

若你修正此限制（使 { "type": "packages" } 遵循每個條目的 sections），請更新此技能以移除本節。

常見陷阱

「doc readme --per-package 未產生任何內容」

• 所有套件已有 README。該命令僅建立新檔案，從不覆寫。請先刪除既有 README 以重新產生。

「對 cmd/ 執行 doc readme --template … 在我未觸及的套件中建立了 README」

• 模板模式會自動產生缺少的各套件 README 作為副作用。請傳入狹窄路徑，或從 git status 還原非預期的建立。

「自動產生的各套件 README 僅為 API 列表」

• 這是設計使然。請手寫 Overview、Usage、Options、Examples。對於 CLI 命令，權威行為來自 indexion <command> --help。

「我對 README.md 的手動編輯將被 doc readme --config 清除」

• 若組合器未來產生豐富形狀（參閱「已知限制」），則會清除。在此之前，組合器產生嚴格子集（表格），你對豐富區段的手動編輯得以保留。請務必執行 plan drift 交叉檢查以確保安全。

「README.md 編輯破壞了無關區段」

• 執行 plan drift HEAD:README.md README.md，查看前一版本的「missing on the other side」輸出。若列出任何非 (none) 的內容，則表示你移除了內容。