docs(wiki): 同步目錄頁條列格式的敘述與工具用法

README 的工具用法、技能行為清單、連結規則與 wiki 技能本文，全部改寫成
目錄頁的區塊格式：參數名從整列改成整個區塊、key-col 的用途縮回只給轉檔
用、補上取標題與換引言的判準，並登錄新增的驗證腳本。

文件與工具講的不是同一件事，呼叫端就會照舊敘述傳整列的表格文字進去，寫出
半表格半條列的頁面。key-col 的語意變動最容易誤解——它從「要換掉哪一欄」
變成「轉檔時哪一欄持有身分」，敘述不改就會被填成別的欄位。

目錄頁條列、內容頁維持圖表優先，這個區分在每一份文件裡都寫明，避免把改版
範圍誤讀成整個 wiki。結束碼說明一併對回工具現況。

功能範圍：目錄頁版面改版的文件同步。

references/behaviors.md

@@ -36,11 +36,11 @@
 
 | 項目 | 內容 |
 | --- | --- |
-| 觸發時機 | 技能組裡任何一次 wiki 頁的讀、寫、刪或搬移，都經過這一支。呼叫端有 jsc-ask、jsc-sdlc、jsc-log、jsc-hooks 的 ERROR 頁、jsc-cli 的 CHECK 頁、jsc-meta 的 SKILLSET 與 TOOLING 頁、jsc-assist 的 MONITOR 頁。存放庫裡的程式碼檔案不歸這一支管。 |
-| 關鍵步驟 | 確認 GITEA_HOST 有值、用 tools/gitea.sh wiki-repo {TYPE} 解出 {owner}/{repo}、用 tools/hash-id 算頁名要用的 HASH、用 tools/page-name.sh check 驗過頁名、再依動作跑 wiki-list、wiki-get、wiki-put、wiki-delete 或 wiki-url，每一次呼叫都照結束碼表分流。所有 *_CONTENTS 頁一律走型別 CONTENTS，內容頁走自己的型別；存放庫的解法是先讀 JSC_WIKI_REPO_{TYPE}、再讀 JSC_WIKI_REPO、兩個都沒有才問使用者，而且不借用別的頁型的存放庫。頁面裡的連結一律寫成 [文字](絕對網址)，網址取自 wiki-url，不自行組路徑；wiki-put 之前先把這一頁要放的每一條連結交給 tools/link-check.sh，結束碼 0 才寫，1 就不寫並回報 DEAD 那幾筆，7 停下來回報金鑰問題。目錄頁的整列 upsert 交給 tools/wiki-contents.sh，寫入前一定先 wiki-get 讀回舊內容，只有結束碼 4 才准用範本建新頁；舊頁搬到新規則走 tools/migrate-wiki.sh，不帶 --apply 只印對照表，寫每一個目的地之前也一樣先 wiki-get 讀一次。收尾一律呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-gitea:wiki 寫下這一輪的結果，走每一條出口，連停在主機閘門那一條也要寫；這支被幾乎每支技能呼叫，只回報這一次 wiki 動作的成敗，不回報呼叫端自己的結果。status 五選一，讀到頁面或寫入落地是 ok，主機沒值、或 wiki-repo 回 3 而使用者沒給 {owner}/{repo}、整輪沒讀也沒寫是 blocked，金鑰失效那個結束碼 7 算 failed 不算頁面不存在、結束碼 8 與 link-check 回 1 擋下寫入也是 failed，內容頁寫成功但目錄頁沒更新（wiki-contents.sh 回 3 或 1）是 degraded、搬移只搬掉一部分也是 degraded，人工確認被否決或頁型不在允許清單而停在 wiki-repo 回 2 是 aborted。detail 只放頁名，不放頁面內容。腳本不在這台機器就安靜跳過，回報失敗不得改變回給呼叫端的結果。 |
-| 外部呼叫 | tools/gitea.sh 的 wiki-repo、wiki-list、wiki-get、wiki-put、wiki-delete、wiki-url、tools/hash-id、tools/page-name.sh、tools/link-check.sh、tools/wiki-contents.sh、tools/migrate-wiki.sh、tools/write-confirm.sh、jsc-ask:ask、jsc-hooks/tools/report-status.sh skill-end、Gitea 的 wiki API 與議題 API。 |
-| 完成條件 | 讀取動作拿到頁面內容，或拿到一個講得清楚的結束碼。這一輪還要留下一筆 skill-end 事件，或是腳本不在而略過，兩者都算收好；略過不影響回給呼叫端的結束碼。寫入動作先讓 tools/link-check.sh 回結束碼 0，再通過人工確認、wiki-put 回結束碼 0，而且送出去的是舊內容加上這次的異動，不是整頁覆蓋。連結檢查回 1 就不寫入，回 7 連同整個動作一起中止。wiki-put 的結束碼 7 與 8 一律中止整個動作，不建頁、不寫入、不用原參數重試。搬移動作要嘛全部搬完回 0，要嘛把失敗頁、孤兒頁、目的地已有內容的頁、指向被搬頁卻沒被搬的引用方逐條列出來，這四種一律交給人判斷。 |
-| 可驗證跡象 | 目標 wiki 存放庫多一頁或改一頁。內容頁的頁名是 {型別}_{40 碼大寫十六進位}，目錄頁是 {型別}_CONTENTS 且落在 JSC_WIKI_REPO_CONTENTS 指的那個存放庫。頁面內容是 UTF-8 繁體中文，以 mermaid 圖與 markdown 表格為主，散文每節最多三句；頁面裡每一條連結都是 [文字](絕對網址)，沒有 wiki 內部連結語法，而且每一條在寫入前都被 tools/link-check.sh 判成 OK。寫入與刪除前 tools/write-confirm.sh 會各留下一次人工確認。$JSC_HOME/usage/events.jsonl 會多一筆 {kind:skill,phase:end} 事件，name 是 jsc-gitea:wiki，status 與 exit 就是這一次 wiki 動作的結果。只做讀取的呼叫沒有 wiki 寫入跡象，只有回報內容與那一筆事件。 |
+| 觸發時機 | 技能組裡任何一次 wiki 頁的讀、寫、刪或搬移，都經過這一支。呼叫端有 jsc-ask、jsc-sdlc、jsc-log、jsc-hooks 的 ERROR 頁、jsc-cli 的 CHECK 頁、jsc-meta 的 SKILLSET 與 TOOLING 頁、jsc-assist 的 MONITOR 頁。要在目錄頁登記一筆紀錄，也走這一支。存放庫裡的程式碼檔案不歸這一支管。 |
+| 關鍵步驟 | 確認 GITEA_HOST 有值、用 tools/gitea.sh wiki-repo {TYPE} 解出 {owner}/{repo}、用 tools/hash-id 算頁名要用的 HASH、用 tools/page-name.sh check 驗過頁名、再依動作跑 wiki-list、wiki-get、wiki-put、wiki-delete 或 wiki-url，每一次呼叫都照結束碼表分流。所有 *_CONTENTS 頁一律走型別 CONTENTS，內容頁走自己的型別；存放庫的解法是先讀 JSC_WIKI_REPO_{TYPE}、再讀 JSC_WIKI_REPO、兩個都沒有才問使用者，而且不借用別的頁型的存放庫。頁面裡的連結一律寫成 [文字](絕對網址)，網址取自 wiki-url，不自行組路徑；wiki-put 之前先把這一頁要放的每一條連結交給 tools/link-check.sh，結束碼 0 才寫，1 就不寫並回報 DEAD 那幾筆，7 停下來回報金鑰問題。內容頁的內容以圖表優先，目錄頁不放表格：一筆紀錄一個 H2 區塊，標題就是那一筆對應的內容頁頁名，欄位是標題底下一層條列「- {欄位名}：{值}」。目錄頁的區塊 upsert 交給 tools/wiki-contents.sh，參數是 upsert {TYPE} {key-col} {key} {區塊檔} [範本檔]：它先 wiki-get 讀回舊內容，舊頁還是 markdown 表格就整頁轉成區塊，再找「## {key}」，命中換掉整塊、沒命中附加到頁尾，最後整頁寫回；key-col 只給轉檔認舊表格的身分欄用，頁面已是條列就忽略；轉檔的 H2 標題只看身分欄那一格，有連結就取網址最後一段路徑、百分號編碼先解碼，沒連結才取格子純文字，取到什麼就用什麼，不拿頁名樣式去驗；轉檔那一次呼叫端有給範本，就把第一個「## 」之前的 H1 與「>」引言換成範本那一段，範本的示範區塊不得混進來，因為轉檔只搬表格不動散文，舊引言會一直講「每個存取庫一列」這種只對表格成立的話，頁面已是條列或沒給範本則引言原樣不動。只有結束碼 4 才准用範本建新頁，7 與 8 一律中止；建新頁時範本的示範區塊要剝掉。舊頁搬到新規則走 tools/migrate-wiki.sh，不帶 --apply 只印對照表，寫每一個目的地之前也一樣先 wiki-get 讀一次。收尾一律呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-gitea:wiki 寫下這一輪的結果，走每一條出口，連停在主機閘門那一條也要寫；這支被幾乎每支技能呼叫，只回報這一次 wiki 動作的成敗，不回報呼叫端自己的結果。status 五選一，讀到頁面或寫入落地是 ok，主機沒值、或 wiki-repo 回 3 而使用者沒給 {owner}/{repo}、整輪沒讀也沒寫是 blocked，金鑰失效那個結束碼 7 算 failed 不算頁面不存在、結束碼 8 與 link-check 回 1 擋下寫入也是 failed，內容頁寫成功但目錄頁沒更新（wiki-contents.sh 回 3，或回 1 組不出頁面內容、寫入沒落地）是 degraded、搬移只搬掉一部分也是 degraded，人工確認被否決或頁型不在允許清單而停在 wiki-repo 回 2 是 aborted。detail 只放頁名，不放頁面內容。腳本不在這台機器就安靜跳過，回報失敗不得改變回給呼叫端的結果。 |
+| 外部呼叫 | tools/gitea.sh 的 wiki-repo、wiki-list、wiki-get、wiki-put、wiki-delete、wiki-url、tools/hash-id、tools/page-name.sh、tools/link-check.sh、tools/wiki-contents.sh 的 upsert 與 format、tools/migrate-wiki.sh、tools/write-confirm.sh、jsc-ask:ask、jsc-hooks/tools/report-status.sh skill-end、Gitea 的 wiki API 與議題 API。 |
+| 完成條件 | 讀取動作拿到頁面內容，或拿到一個講得清楚的結束碼。這一輪還要留下一筆 skill-end 事件，或是腳本不在而略過，兩者都算收好；略過不影響回給呼叫端的結束碼。寫入動作先讓 tools/link-check.sh 回結束碼 0，再通過人工確認、wiki-put 回結束碼 0，而且送出去的是舊內容加上這次的異動，不是整頁覆蓋。目錄頁的異動只動自己那一個 H2 區塊：別人那幾筆一字不變，頁面上不留 markdown 表格，也不出現兩個同名的 H2 標題；只有從表格轉成區塊那一次，且呼叫端有給範本，引言才會換成範本那一份，其餘情況引言與別人那幾筆一起一字不動。連結檢查回 1 就不寫入，回 7 連同整個動作一起中止。wiki-put 的結束碼 7 與 8 一律中止整個動作，不建頁、不寫入、不用原參數重試。搬移動作要嘛全部搬完回 0，要嘛把失敗頁、孤兒頁、目的地已有內容的頁、指向被搬頁卻沒被搬的引用方逐條列出來，這四種一律交給人判斷。 |
+| 可驗證跡象 | 目標 wiki 存放庫多一頁或改一頁。內容頁的頁名是 {型別}_{40 碼大寫十六進位}，目錄頁是 {型別}_CONTENTS 且落在 JSC_WIKI_REPO_CONTENTS 指的那個存放庫。頁面內容是 UTF-8 繁體中文；內容頁以 mermaid 圖與 markdown 表格為主，散文每節最多三句。目錄頁只有三段：H1 頁名、「>」引言、一筆一個 H2 區塊，區塊之間空一行，H2 與第一條條列之間也空一行，H2 標題就是內容頁頁名而且不帶連結。頁面裡每一條連結都是 [文字](絕對網址)，沒有 wiki 內部連結語法，而且每一條在寫入前都被 tools/link-check.sh 判成 OK。wiki-contents.sh 印出一行 updated 或 added 加上 {owner}/{repo}/{頁名}。寫入與刪除前 tools/write-confirm.sh 會各留下一次人工確認。$JSC_HOME/usage/events.jsonl 會多一筆 {kind:skill,phase:end} 事件，name 是 jsc-gitea:wiki，status 與 exit 就是這一次 wiki 動作的結果。只做讀取的呼叫沒有 wiki 寫入跡象，只有回報內容與那一筆事件。 |
 
 ## wiki-to-issue
 

references/wiki-links.md

@@ -8,7 +8,7 @@
 
 | 情境 | 寫法 |
 | --- | --- |
-| 目錄頁指向內容頁（例：`PLAN_CONTENTS` → `PLAN_{HASH}`） | `[PLAN_{HASH}](https://…/wiki/PLAN_…)` |
+| 目錄頁指向內容頁（例：`PLAN_CONTENTS` → `PLAN_{HASH}`）：連結寫在該筆 H2 區塊的條列裡，H2 標題本身只放頁名，不放連結 | `- 計畫頁：[PLAN_{HASH}](https://…/wiki/PLAN_…)` |
 | 內容頁指向目錄頁，或指向別的型別 | `[顯示文字](絕對網址)` |
 | 目錄頁之間、同型別的內容頁之間 | `[顯示文字](絕對網址)` |
 | 議題、PR、存放庫檔案 | `[顯示文字](絕對網址)` |