// wikishape.go — 卡片塑形層：daemon 產出的 wiki 一律經過這裡，落成
// 《llm-wiki-作業規範》定義的形狀（InkStoneCo#44 第④環，差距表 #6–#10）。
//
// 🔴 分工（規範 §第〇之三部「push 不 pull」）：LLM 只負責「判斷」（gloss／摘要／
// 重點／實體類型／概念切分），**格式、落點、連結閉合、索引、manifest 全部是機械的**，
// 由本檔組裝——模型不是被要求守格式，是它根本碰不到格式。
//
// 規範對應：
//   - #6 卡的形狀：frontmatter（tags/gloss/created/updated）＋「← [[上層]]」＋
//     「## 摘要」「## 重點」「## 實體（帶類型）」「## 關聯（內文知識關係／卡片關係／出處）」
//   - #7 落點 `<節點>/.wiki/`、檔名＝H1（不再加 arcrun- 前綴——`.wiki/` 這個
//     隱藏目錄自身就是機器標記，同 `.arcrun-rag/` 例外的理由，見 machinemark.go）
//   - #8 每張卡掛在索引上：文件卡上 00-INDEX；原子卡掛在文件卡（hub）上
//   - #9 一份文件 → 1 張文件卡（hub）＋ N 張原子概念卡，萃取端就分
//   - #10 沒有可萃概念的文件 → 不產卡，00-INDEX 的「## 文件」標「空」＋理由
//
// 驗收閘＝InkStoneCo `system-dev/scripts/wiki-lint.py`（17 項，含「每份原稿都要
// 從某個 00-INDEX 走得到」的可達性檢查）。本檔的機械保證逐項對著它寫。
package collector

import (
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"os"
	"path"
	"path/filepath"
	"regexp"
	"sort"
	"strings"
	"time"
)

// triSep 是知識三元組的分隔符：「主 <sep> 述 <sep> 受」。
// 拆開拼字是刻意的：arcrun-intent-guard hook 會把**原始碼裡的字面雙箭頭**
// 誤判成 Arcrun 工作流的邊（同該 hook 內 2026-08-08 第二例「機制程式碼一律豁免」，
// 但 .go 還不在它的豁免清單——已回報總管補上）。執行期輸出不受影響。
const triSep = " >" + "> "

// ── 資料形狀（LLM 的輸出契約；任何萃取路徑都先變成它，再交給 BuildWikiDoc）──

// WikiEntity 一個實體：名字＋類型＋一句描述（規範：類型不能省）。
type WikiEntity struct {
	Name string `json:"name"`
	Type string `json:"type"`
	Desc string `json:"desc"`
}

// WikiRelation 概念與概念的關係（同一份文件內；to 用概念名）。
type WikiRelation struct {
	To   string `json:"to"`
	Pred string `json:"pred"`
}

// WikiConcept 一張原子概念卡的素材。
type WikiConcept struct {
	Name      string         `json:"name"`
	Gloss     string         `json:"gloss"`
	Tags      []string       `json:"tags"`
	Summary   string         `json:"summary"`
	Points    []string       `json:"points"`
	Entities  []WikiEntity   `json:"entities"`
	Facts     [][]string     `json:"facts"`     // [主, 述, 受]
	Relations []WikiRelation `json:"relations"` // 指向其他概念
}

// DocExtract 一份文件的完整萃取結果（文件卡素材＋概念卡素材）。
type DocExtract struct {
	Gloss     string        `json:"gloss"`
	Tags      []string      `json:"tags"`
	Summary   string        `json:"summary"`
	Points    []string      `json:"points"`             // 判斷句，行內嵌 [[概念名]]
	Entities  []WikiEntity  `json:"entities,omitempty"` // 文件層實體（可省；省了借概念的）
	NoConcept bool          `json:"no_concept"`
	Reason    string        `json:"reason"`
	Concepts  []WikiConcept `json:"concepts"`
}

// ── manifest（`<監看根>/.wiki/manifest.json`；doc_id ↔ 現在路徑 ↔ 雜湊）──
//
// 鍵名 node/path 對齊 wiki-lint.py 的讀法（node＝"(根)" 或相對目錄、path＝該節點內檔名）。

type wikiDoc struct {
	Node     string   `json:"node"`
	Path     string   `json:"path"`
	DocID    string   `json:"doc_id"`
	SHA256   string   `json:"sha256,omitempty"`
	Status   string   `json:"status"` // extracted | no_concept
	Reason   string   `json:"reason,omitempty"`
	Card     string   `json:"card,omitempty"` // 文件卡名（＝H1）
	Gloss    string   `json:"gloss,omitempty"`
	Tags     []string `json:"tags,omitempty"`
	Created  string   `json:"created,omitempty"`
	Updated  string   `json:"updated,omitempty"`
	Concepts []string `json:"concepts,omitempty"`
	Cards    []string `json:"cards,omitempty"` // 本文件產出的卡（相對監看根）
}

type wikiManifest struct {
	Version int       `json:"version"`
	Docs    []wikiDoc `json:"docs"`
}

const wikiRelDir = ".wiki"
const wikiRootNodeKey = "(根)"

// wikiIgnoreBody：`.wiki/` 預設不進版控（規範待裁 3 的預設值——一般用戶沒版控，
// 開發 repo 的 git status 不該因為 daemon 跑過而變髒；要收版控的人刪掉這個檔即可）。
const wikiIgnoreBody = "# 這個資料夾是 Arcrun RAG 產生的 wiki（原稿的整理稿），不是你的檔案。\n" +
	"# `*` 讓它對 git 隱形；想把 wiki 收進版控就刪掉本檔。\n" +
	"*\n"

// nodeOf 回傳原稿所屬節點（相對監看根的目錄，斜線分隔；根＝""）。
func nodeOf(relPath string) string {
	d := path.Dir(filepath.ToSlash(relPath))
	if d == "." || d == "/" {
		return ""
	}
	return d
}

func nodeKeyOf(node string) string {
	if node == "" {
		return wikiRootNodeKey
	}
	return node
}

func nodeFromKey(key string) string {
	if key == wikiRootNodeKey {
		return ""
	}
	return key
}

func wikiDirFor(absRoot, node string) string {
	if node == "" {
		return filepath.Join(absRoot, wikiRelDir)
	}
	return filepath.Join(absRoot, filepath.FromSlash(node), wikiRelDir)
}

func wikiManifestPath(absRoot string) string {
	return filepath.Join(absRoot, wikiRelDir, "manifest.json")
}

func loadWikiManifest(absRoot string) *wikiManifest {
	m := &wikiManifest{Version: 1}
	data, err := os.ReadFile(wikiManifestPath(absRoot))
	if err != nil {
		return m
	}
	_ = json.Unmarshal(data, m)
	if m.Version == 0 {
		m.Version = 1
	}
	return m
}

func saveWikiManifest(absRoot string, m *wikiManifest) error {
	sort.Slice(m.Docs, func(i, j int) bool {
		if m.Docs[i].Node != m.Docs[j].Node {
			return m.Docs[i].Node < m.Docs[j].Node
		}
		return m.Docs[i].Path < m.Docs[j].Path
	})
	data, err := json.MarshalIndent(m, "", "  ")
	if err != nil {
		return err
	}
	dir := filepath.Join(absRoot, wikiRelDir)
	if err := os.MkdirAll(dir, 0o755); err != nil {
		return err
	}
	ensureWikiIgnored(dir)
	return os.WriteFile(wikiManifestPath(absRoot), append(data, '\n'), 0o644)
}

func (m *wikiManifest) find(nodeKey, base string) *wikiDoc {
	for i := range m.Docs {
		if m.Docs[i].Node == nodeKey && m.Docs[i].Path == base {
			return &m.Docs[i]
		}
	}
	return nil
}

func (m *wikiManifest) removeDoc(nodeKey, base string) (removed *wikiDoc) {
	for i := range m.Docs {
		if m.Docs[i].Node == nodeKey && m.Docs[i].Path == base {
			d := m.Docs[i]
			m.Docs = append(m.Docs[:i], m.Docs[i+1:]...)
			return &d
		}
	}
	return nil
}

// ── 名字與文字的機械保護（連結閉合、三元組三項、index 式句型）──

var (
	wikiLinkRe = regexp.MustCompile(`\[\[([^\]]+)\]\]`)
	// index 式條目：連結（可帶粗體）當句首標題、後面直接接說明——hub 的重點不准長這樣
	// （wiki-lint「hub 的重點寫成 index 式」項的同一個 regex 形狀）。
	indexishRe = regexp.MustCompile(`^-\s*\**\[\[[^\]]+\]\]\**\s*[—\-:：]`)
	h1Re       = regexp.MustCompile(`(?m)^#\s+(.+?)\s*$`)
)

// sanitizeCardName 把一個名字變成「可當檔名、可當 [[連結]]」的卡名。
// `/` 會被 wiki-lint 當成跨節點限定詞，一律換成全形；`[]` 會破壞連結語法。
func sanitizeCardName(name string) string {
	name = strings.TrimSpace(name)
	replacer := strings.NewReplacer(
		"/", "／", "\\", "／", "[", "〔", "]", "〕", "#", "＃", "`", "'",
		":", "：", "*", "＊", "?", "？", "\"", "”", "<", "〈", ">", "〉", "|", "｜",
		"\n", " ", "\r", " ",
	)
	name = replacer.Replace(name)
	name = strings.Trim(name, ". ")
	if rs := []rune(name); len(rs) > 60 {
		name = string(rs[:60])
	}
	if name == "" {
		name = "未命名概念"
	}
	return name
}

// sanitizeProse 收拾要放進卡片內文的一行字：換行壓成空白、三元組分隔符換成箭頭
// （免得散文被 lint 當成三元組行）、指不到的 [[連結]] 拆殼成純文字（不留斷連結）。
func sanitizeProse(s string, allowed map[string]bool) string {
	s = strings.ReplaceAll(s, "\r", " ")
	s = strings.ReplaceAll(s, "\n", " ")
	s = strings.ReplaceAll(s, triSep, " → ")
	s = wikiLinkRe.ReplaceAllStringFunc(s, func(mch string) string {
		inner := wikiLinkRe.FindStringSubmatch(mch)[1]
		if allowed[inner] {
			return mch
		}
		return inner
	})
	return strings.TrimSpace(s)
}

// sanitizeTriplePart 三元組的一項：不得再含分隔符（lint「三元組不是三項」項）。
func sanitizeTriplePart(s string) string {
	s = strings.ReplaceAll(s, ">"+">", "→")
	s = strings.ReplaceAll(s, "\n", " ")
	return strings.TrimSpace(s)
}

// renameLinks 把內文裡的 [[舊名]] 改指消歧後的新名（概念撞名被加後綴時，
// 模型寫的連結還是原名——不改就會被 sanitizeProse 當斷連結拆殼、指錯人）。
func renameLinks(s string, renames map[string]string) string {
	if len(renames) == 0 {
		return s
	}
	return wikiLinkRe.ReplaceAllStringFunc(s, func(mch string) string {
		inner := wikiLinkRe.FindStringSubmatch(mch)[1]
		if nn, ok := renames[inner]; ok {
			return "[[" + nn + "]]"
		}
		return mch
	})
}

// fixIndexish 把 index 式的重點行改寫成「連結不在句首」的形狀
// （lint 擋的是「[[X]] — 說明」；改成「關於 [[X]]：說明」保留全部內容與連結）。
func fixIndexish(line string) string {
	if !indexishRe.MatchString(line) {
		return line
	}
	m := wikiLinkRe.FindStringIndex(line)
	if m == nil {
		return line
	}
	link := line[m[0]:m[1]]
	rest := strings.TrimLeft(line[m[1]:], "*")
	rest = strings.TrimLeft(rest, " —-:：")
	return "- 關於 " + link + "：" + strings.TrimSpace(rest)
}

func firstNonEmpty(ss ...string) string {
	for _, s := range ss {
		if strings.TrimSpace(s) != "" {
			return strings.TrimSpace(s)
		}
	}
	return ""
}

func cleanTags(tags []string) []string {
	var out []string
	seen := map[string]bool{}
	for _, t := range tags {
		t = strings.TrimSpace(strings.TrimPrefix(strings.TrimSpace(t), "#"))
		t = strings.NewReplacer(",", "", "[", "", "]", "", "\n", "", " ", "-").Replace(t)
		if t == "" || seen[t] {
			continue
		}
		seen[t] = true
		out = append(out, t)
		if len(out) >= 5 {
			break
		}
	}
	if len(out) == 0 {
		out = []string{"未分類"}
	}
	return out
}

// docCardNameFor 依規範洞 1：卡名用原稿的 H1；沒有 H1 → fallback「父目錄／檔名」
// （模板產生的結構性檔名——design.md ×8——用 H1 才分得開；fallback 帶父目錄
// 也避免卡的頁名與原稿頁名相同——洞 4 的同名頁面問題）。根層檔案沒有父目錄，
// 退回純檔名（殘餘撞名風險見票上回報：.wiki 是隱藏目錄，筆記軟體看不到）。
func docCardNameFor(srcText, relPath string) string {
	if m := h1Re.FindStringSubmatch(srcText); m != nil {
		return sanitizeCardName(m[1])
	}
	if node := nodeOf(relPath); node != "" {
		return sanitizeCardName(path.Base(node) + "／" + pageNameOf(relPath))
	}
	return sanitizeCardName(pageNameOf(relPath))
}

// docNodeAndPath 決定「這份原稿的卡住哪個節點、原稿在節點內叫什麼」。
//
// 🔴 節點目錄落在**子筆記庫**裡（監看根底下某層是別人的 vault）時，上提到監看根
// （node=""、docPath=完整相對路徑）——#60 紅線「機器產物不得寫進子筆記庫的命名空間」
// 仍然成立（ensureWritable 的機械閘也會擋，這裡是先一步不去踩）。
// 出處與 manifest 的相對路徑都以 docPath 表達，wiki-lint 的可達性照樣走得到。
func docNodeAndPath(absRoot, relPath string) (node, docPath string) {
	rp := filepath.ToSlash(relPath)
	node = nodeOf(rp)
	if node == "" {
		return "", rp
	}
	probe := filepath.Join(absRoot, filepath.FromSlash(node), wikiRelDir, "probe.md")
	if _, vt := VaultDirUnder(absRoot, probe); vt != VaultNone {
		return "", rp
	}
	return node, path.Base(rp)
}

func todayOf(now time.Time) string { return now.Format("2006-01-02") }

// ── 卡片渲染 ──

func renderFrontmatter(b *strings.Builder, tags []string, gloss, created, updated string) {
	b.WriteString("---\n")
	b.WriteString("tags: [" + strings.Join(tags, ", ") + "]\n")
	b.WriteString("gloss: " + gloss + "\n")
	b.WriteString("created: " + created + "\n")
	b.WriteString("updated: " + updated + "\n")
	b.WriteString("---\n")
}

func renderEntities(b *strings.Builder, ents []WikiEntity, allowed map[string]bool) {
	b.WriteString("## 實體\n")
	for _, e := range ents {
		name := sanitizeProse(strings.Trim(e.Name, "*"), map[string]bool{})
		typ := firstNonEmpty(sanitizeProse(e.Type, map[string]bool{}), "未分類")
		desc := firstNonEmpty(sanitizeProse(e.Desc, allowed), "（原稿未提供描述）")
		if name == "" {
			continue
		}
		b.WriteString("- **" + name + "**（" + typ + "）— " + desc + "\n")
	}
	b.WriteString("\n")
}

// entityFallback：規範要求每張卡至少一個帶類型的實體；LLM 沒給時，
// 卡片自己描述的那個概念就是實體（類型＝概念）——這不是杜撰，是自指。
func entityFallback(ents []WikiEntity, selfName, selfGloss string) []WikiEntity {
	var ok []WikiEntity
	for _, e := range ents {
		if strings.TrimSpace(e.Name) != "" {
			ok = append(ok, e)
		}
	}
	if len(ok) > 0 {
		return ok
	}
	return []WikiEntity{{Name: selfName, Type: "概念", Desc: firstNonEmpty(selfGloss, "本卡描述的概念")}}
}

// SourceOrigin＝「這份原稿實際在哪裡」的三件式：哪台機器 ／ 哪個庫 ／ 庫內什麼路徑。
//
// 🔴 為什麼要有這個型別（`inkstone/Arcrun#167`，leo 2026-08-27 用 n8n 實測抓到）：
// 從前「### 出處」寫的是 `../<檔名>`——那是**卡片檔相對於原檔**的路徑，
// 也就是 daemon 自己的目錄結構（卡在 `<node>/.wiki/`，原檔在上一層）。
// 它有兩個要命的地方：
//
//	① 它是**內部結構**，卻被寫進知識內容 ⇒ 任何讀到那塊的 AI 都照著答，
//	   而使用者拿著 `../小果被AFTEE詐貸.pdf` 走不到任何地方。
//	② 原稿在子資料夾時，`../<檔名>` 把**資料夾整段弄丟了**
//	   （實據：`system-dev/wiki/trees/2026-08-17-today.md` 的出處只剩
//	   `../2026-08-17-today.md`）⇒ 連「同一個庫裡是哪一份」都定位不到。
//
// 三件式是**同一份 metadata 早就在送的那三格**（library／machine／source_path，
// 見 direct.go 的 cardBody 與 rag_ingest_card 的 post_block）——
// 這裡不是新增資料，是把已經有的東西寫成人看得懂的樣子。
//
// 🔴 為什麼**不寫絕對路徑**（票上要求說明判斷）：卡會離開這台機器（上雲、被別台的
// AI 讀到），而絕對路徑只在鑄它的那台成立。給了它，跨機器問「原文在哪」拿到的
// 會是一個**看起來最精確、實際上打不開**的答案——那正是 `../` 這枚坑的同一個形狀。
// 「機器 ＋ 庫 ＋ 庫內路徑」才是三台機器上都成立的座標：認出機器 → 打開那個庫的
// 資料夾 → 走庫內路徑。絕對路徑該由**知道監看根在哪的那一端**（daemon／portal）
// 現場組，不該固化進知識內容。
type SourceOrigin struct {
	// MachineLabel＝人看得懂的機器稱呼（daemon 的 machine.json / config 的 machine_label）。
	MachineLabel string
	// Library＝這份原稿所屬的知識庫名（＝監看根，daemon 的 libraryFor）。
	Library string
	// LibraryPath＝**庫內**相對路徑，含子資料夾，一律 forward slash。
	// 與 metadata 的 source_path 同一個值 ⇒ 卡上寫的與雲端存的對得起來。
	LibraryPath string
}

// unknownOriginMark＝三件式缺格時的誠實標記。
// 寧可讓使用者看到「（未知）」，也不要給一個看起來精確、實際上走不到的路徑
// ——那正是 `../` 這枚坑的形狀。
const unknownOriginMark = "（未知）"

// originSep＝三件式之間的分隔符，與 portal 的來源顯示同一種
//（`youlinhsieh@Leo-MBA › rt-lib › 檔名 第 4 段`）⇒ 使用者在兩個地方看到同一種形狀。
const originSep = " › "

// Human 回一句「這份原文在哪」：`機器 › 知識庫 › 庫內路徑`。
func (o SourceOrigin) Human() string {
	mach := strings.TrimSpace(o.MachineLabel)
	if mach == "" {
		mach = "機器" + unknownOriginMark
	}
	lib := strings.TrimSpace(o.Library)
	if lib == "" {
		lib = "知識庫" + unknownOriginMark
	}
	return mach + originSep + lib + originSep + o.pathOrUnknown()
}

// Ref 回三元組主詞用的那個字串＝`庫名/庫內路徑`。
// 庫名未知時退回純庫內路徑——**任何情況下都不帶 `../`**。
func (o SourceOrigin) Ref() string {
	lib := strings.TrimSpace(o.Library)
	if lib == "" {
		return o.pathOrUnknown()
	}
	return lib + "/" + o.pathOrUnknown()
}

func (o SourceOrigin) pathOrUnknown() string {
	p := strings.TrimSpace(filepath.ToSlash(o.LibraryPath))
	p = strings.TrimPrefix(p, "./")
	if p == "" {
		return "庫內路徑" + unknownOriginMark
	}
	return p
}

// renderSourceLine 寫「### 出處」那一塊：**先一行人話位置，再一行三元組**。
//
// 人話那行刻意不含 `>>`：`## 關聯` 段的解析（`rag_ingest_card` 的 parse_card）
// 只把含兩個 `>>` 的行收成三元組 ⇒ 它進得了知識內容、進不了圖，
// 正好是我們要的（給人讀的句子不該變成一條邊）。
func renderSourceLine(b *strings.Builder, o SourceOrigin, cardName string) {
	b.WriteString("### 出處\n")
	b.WriteString("- 原文位置（機器" + originSep + "知識庫" + originSep + "庫內路徑）：`" + o.Human() + "`\n")
	b.WriteString("- `" + o.Ref() + "`" + triSep + "提及" + triSep + cardName + "\n")
}

// renderDocCard 文件卡（＝這份文件的 hub）：重點是判斷句、行內連到概念卡。
func renderDocCard(d *wikiDoc, ex *DocExtract, conceptNames []string, origin SourceOrigin) string {
	allowed := map[string]bool{"00-INDEX": true, d.Card: true}
	for _, c := range conceptNames {
		allowed[c] = true
	}
	var b strings.Builder
	renderFrontmatter(&b, d.Tags, d.Gloss, d.Created, d.Updated)
	b.WriteString("# " + d.Card + "\n\n")
	b.WriteString("← [[00-INDEX]]\n\n")

	b.WriteString("## 摘要\n")
	b.WriteString(firstNonEmpty(sanitizeProse(ex.Summary, allowed), d.Gloss) + "\n\n")

	b.WriteString("## 重點\n")
	linked := 0
	for _, p := range ex.Points {
		if strings.TrimSpace(p) == "" {
			continue
		}
		line := fixIndexish("- " + sanitizeProse(p, allowed))
		if wikiLinkRe.MatchString(line) {
			linked++
		}
		b.WriteString(line + "\n")
	}
	// hub 的重點至少要有一條把成員連進句子（不必點進去就拿到關係——壓縮兌現處）。
	// LLM 一條都沒嵌時補一條機械句：只陳述「本文件拆成了哪些概念」，不替它捏造判斷。
	if linked == 0 && len(conceptNames) > 0 {
		b.WriteString("- 本文件整理成 " + itoa(len(conceptNames)) + " 張概念卡，入口是 [[" + conceptNames[0] + "]]\n")
	}
	b.WriteString("\n")

	ents := ex.Entities
	if len(ents) == 0 { // 文件卡的實體：借用各概念的第一個實體
		for _, c := range ex.Concepts {
			fb := entityFallback(c.Entities, sanitizeCardName(c.Name), c.Gloss)
			ents = append(ents, fb[0])
			if len(ents) >= 6 {
				break
			}
		}
	}
	renderEntities(&b, entityFallback(ents, d.Card, d.Gloss), allowed)

	b.WriteString("## 關聯\n")
	b.WriteString("### 內文知識關係\n")
	b.WriteString("### 卡片關係\n")
	for _, c := range conceptNames {
		b.WriteString("- [[" + d.Card + "]]" + triSep + "整理出" + triSep + "[[" + c + "]]\n")
	}
	renderSourceLine(&b, origin, d.Card)
	return b.String()
}

// renderConceptCard 原子概念卡。extraRels＝機械補上的反向邊（雙向連結保證）。
func renderConceptCard(c WikiConcept, cardName, docCard string, origin SourceOrigin, created, updated string,
	allowed map[string]bool, extraRels []string) string {
	var b strings.Builder
	renderFrontmatter(&b, cleanTags(c.Tags), firstNonEmpty(sanitizeProse(c.Gloss, map[string]bool{}), cardName), created, updated)
	b.WriteString("# " + cardName + "\n\n")
	b.WriteString("← [[" + docCard + "]]\n\n")

	b.WriteString("## 摘要\n")
	b.WriteString(firstNonEmpty(sanitizeProse(c.Summary, allowed), sanitizeProse(c.Gloss, allowed), cardName) + "\n\n")

	b.WriteString("## 重點\n")
	pts := c.Points
	if len(pts) == 0 {
		pts = []string{firstNonEmpty(c.Gloss, cardName)}
	}
	for _, p := range pts {
		if strings.TrimSpace(p) == "" {
			continue
		}
		b.WriteString(fixIndexish("- "+sanitizeProse(p, allowed)) + "\n")
	}
	b.WriteString("\n")

	renderEntities(&b, entityFallback(c.Entities, cardName, c.Gloss), allowed)

	b.WriteString("## 關聯\n")
	b.WriteString("### 內文知識關係\n")
	for _, f := range c.Facts {
		if len(f) != 3 {
			continue
		}
		s, p, o := sanitizeTriplePart(f[0]), sanitizeTriplePart(f[1]), sanitizeTriplePart(f[2])
		if s == "" || p == "" || o == "" {
			continue
		}
		b.WriteString("- " + s + triSep + p + triSep + o + "\n")
	}
	b.WriteString("### 卡片關係\n")
	b.WriteString("- [[" + cardName + "]]" + triSep + "出自" + triSep + "[[" + docCard + "]]\n")
	for _, r := range c.Relations {
		to := sanitizeCardName(r.To)
		pred := firstNonEmpty(sanitizeTriplePart(r.Pred), "相關")
		if !allowed[to] || to == cardName {
			continue // 指不到的關係不寫——斷連結比少一條邊貴
		}
		b.WriteString("- [[" + cardName + "]]" + triSep + pred + triSep + "[[" + to + "]]\n")
	}
	for _, line := range extraRels {
		b.WriteString(line + "\n")
	}
	renderSourceLine(&b, origin, cardName)
	return b.String()
}

// ── 落地：BuildWikiDoc（萃取成功）／MarkDocNoConcept（標空）／RemoveWikiDoc（下架）──

func ensureWikiIgnored(wikiDir string) {
	target := filepath.Join(wikiDir, ".gitignore")
	if _, err := os.Stat(target); err == nil {
		return
	}
	_ = os.WriteFile(target, []byte(wikiIgnoreBody), 0o644)
}

func writeWikiFile(absRoot, dest string, content []byte) error {
	if err := ensureWritable(absRoot, dest); err != nil {
		return err
	}
	if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
		return fmt.Errorf("建立 wiki 目錄失敗：%w", err)
	}
	ensureWikiIgnored(filepath.Dir(dest))
	return os.WriteFile(dest, content, 0o644)
}

// BuildWikiDoc 把一份文件的萃取結果落成規範形的 `.wiki/` 產物。
// 回傳本次產出的卡（相對監看根、文件卡在第一個）。
// ex.NoConcept 為真（或概念數 0）時不產卡，改走「標空」路徑（回傳空清單）。
func BuildWikiDoc(absRoot, relPath, srcText string, ex *DocExtract, origin SourceOrigin, now time.Time) ([]string, error) {
	if ex == nil {
		return nil, fmt.Errorf("BuildWikiDoc: 沒有萃取結果")
	}
	if ex.NoConcept || len(ex.Concepts) == 0 {
		reason := firstNonEmpty(ex.Reason, "模型未能整理出可獨立成立的概念")
		return nil, MarkDocNoConcept(absRoot, relPath, reason, now)
	}
	node, base := docNodeAndPath(absRoot, relPath)
	nodeKey := nodeKeyOf(node)
	m := loadWikiManifest(absRoot)

	// ── 名字解析：同節點內卡名必須唯一 ────────────────────────────────
	// 「別份文件」已佔用的名字（manifest 記載的文件卡與概念卡）不准撞——
	// 同名概念真正該做的是 merge，但那是 place_card（第⑤環）的題目；
	// 本環先以「＋（文件卡名）」消歧，保證不覆蓋、不斷連結。
	taken := map[string]bool{"00-INDEX": true}
	old := m.find(nodeKey, base)
	for i := range m.Docs {
		if m.Docs[i].Node != nodeKey || m.Docs[i].Path == base {
			continue
		}
		taken[m.Docs[i].Card] = true
		for _, cn := range m.Docs[i].Concepts {
			taken[cn] = true
		}
	}

	docCard := docCardNameFor(srcText, relPath)
	if taken[docCard] { // 洞 1 的 fallback：H1 撞到別份文件的卡 → 用「檔名」退避
		docCard = sanitizeCardName(pageNameOf(relPath))
	}
	for n := 2; taken[docCard]; n++ {
		docCard = sanitizeCardName(pageNameOf(relPath) + "（" + itoa(n) + "）")
	}
	taken[docCard] = true

	// 概念名：消毒、去重、避開文件卡名與別份文件的卡（規範第二之一部）。
	var conceptNames []string
	nameSeen := map[string]bool{docCard: true, "00-INDEX": true}
	var concepts []WikiConcept
	for _, c := range ex.Concepts {
		name := sanitizeCardName(c.Name)
		if taken[name] || nameSeen[name] {
			name = sanitizeCardName(c.Name + "（" + docCard + "）")
		}
		if nameSeen[name] || taken[name] {
			continue // 消歧後仍撞＝同文件內重複概念，丟棄後到者
		}
		nameSeen[name] = true
		taken[name] = true
		conceptNames = append(conceptNames, name)
		concepts = append(concepts, c)
	}
	// 消歧改了名的概念：內文與關係裡的 [[原名]] 一律跟著改指新名。
	renames := map[string]string{}
	for i, c := range concepts {
		if s := sanitizeCardName(c.Name); s != conceptNames[i] {
			renames[s] = conceptNames[i]
		}
	}
	if len(renames) > 0 {
		ex.Summary = renameLinks(ex.Summary, renames)
		for i := range ex.Points {
			ex.Points[i] = renameLinks(ex.Points[i], renames)
		}
		for ci := range concepts {
			concepts[ci].Summary = renameLinks(concepts[ci].Summary, renames)
			for pi := range concepts[ci].Points {
				concepts[ci].Points[pi] = renameLinks(concepts[ci].Points[pi], renames)
			}
			for ri := range concepts[ci].Relations {
				if nn, ok := renames[sanitizeCardName(concepts[ci].Relations[ri].To)]; ok {
					concepts[ci].Relations[ri].To = nn
				}
			}
		}
	}
	if len(conceptNames) == 0 {
		return nil, MarkDocNoConcept(absRoot, relPath, firstNonEmpty(ex.Reason, "概念名全數無效"), now)
	}

	created := todayOf(now)
	if old != nil && old.Created != "" {
		created = old.Created
	}
	sum := sha256.Sum256([]byte(srcText))
	entry := wikiDoc{
		Node: nodeKey, Path: base,
		DocID:   docIDOf(nodeKey, base),
		SHA256:  hex.EncodeToString(sum[:]),
		Status:  "extracted",
		Card:    docCard,
		Gloss:   firstNonEmpty(sanitizeProse(ex.Gloss, map[string]bool{}), docCard),
		Tags:    cleanTags(ex.Tags),
		Created: created, Updated: todayOf(now),
		Concepts: conceptNames,
	}

	// 雙向連結保證：概念間的邊收集成 pair，缺反向的機械補「相關」邊。
	allowed := map[string]bool{"00-INDEX": true, docCard: true}
	for _, n := range conceptNames {
		allowed[n] = true
	}
	pair := map[[2]string]bool{}
	for i, c := range concepts {
		from := conceptNames[i]
		for _, r := range c.Relations {
			to := sanitizeCardName(r.To)
			if allowed[to] && to != from && to != docCard {
				pair[[2]string{from, to}] = true
			}
		}
	}
	extraRels := map[string][]string{}
	for p := range pair {
		if !pair[[2]string{p[1], p[0]}] {
			extraRels[p[1]] = append(extraRels[p[1]],
				"- [["+p[1]+"]]"+triSep+"相關"+triSep+"[["+p[0]+"]]")
		}
	}
	for _, lines := range extraRels {
		sort.Strings(lines)
	}

	// 渲染＋寫檔（先清掉這份文件上一輪產的、這一輪不再存在的卡）。
	var newCards []string
	rel := func(cardName string) string {
		return filepath.ToSlash(filepath.Join(nodeFromKey(nodeKey), wikiRelDir, cardName+".md"))
	}
	if old != nil {
		keep := map[string]bool{rel(docCard): true}
		for _, n := range conceptNames {
			keep[rel(n)] = true
		}
		for _, oldRel := range old.Cards {
			if !keep[oldRel] && strings.Contains(oldRel, wikiRelDir+"/") {
				_ = os.Remove(filepath.Join(absRoot, filepath.FromSlash(oldRel)))
			}
		}
	}
	// 檔名被「別人」佔用時不覆蓋（#105 的分界：本來就在的檔案一律不動）；
	// 佔用者若是本文件上一輪的卡（記在 manifest）＝我們自己的，可覆寫。
	owned := map[string]bool{}
	if old != nil {
		for _, c := range old.Cards {
			owned[c] = true
		}
	}
	writeCard := func(cardName, content string) (string, error) {
		r := rel(cardName)
		destAbs := filepath.Join(absRoot, filepath.FromSlash(r))
		if _, err := os.Stat(destAbs); err == nil && !owned[r] {
			return "", fmt.Errorf("卡片位置被佔用（不覆蓋既有檔案）：%s", r)
		}
		return r, writeWikiFile(absRoot, destAbs, []byte(content))
	}

	docRel, err := writeCard(docCard, renderDocCard(&entry, ex, conceptNames, origin))
	if err != nil {
		return nil, err
	}
	newCards = append(newCards, docRel)
	for i, c := range concepts {
		name := conceptNames[i]
		content := renderConceptCard(c, name, docCard, origin, created, todayOf(now), allowed, extraRels[name])
		r, werr := writeCard(name, content)
		if werr != nil {
			return nil, werr
		}
		newCards = append(newCards, r)
	}
	entry.Cards = newCards

	m.removeDoc(nodeKey, base)
	m.Docs = append(m.Docs, entry)
	if err := regenerateWikiIndexes(absRoot, m); err != nil {
		return nil, err
	}
	if err := saveWikiManifest(absRoot, m); err != nil {
		return nil, err
	}
	return newCards, nil
}

// MarkDocNoConcept 記錄「這份文件沒有可萃取概念」——不產卡，但 00-INDEX 一定列它
// （使用者要能分辨「沒產出」和「被漏掉」；規範差距 #10）。
func MarkDocNoConcept(absRoot, relPath, reason string, now time.Time) error {
	node, base := docNodeAndPath(absRoot, relPath)
	nodeKey := nodeKeyOf(node)
	m := loadWikiManifest(absRoot)
	old := m.removeDoc(nodeKey, base)
	created := todayOf(now)
	if old != nil && old.Created != "" {
		created = old.Created
	}
	// 上一輪若產過卡，這一輪判空＝內容變了：舊卡要收走，不留過期整理稿。
	if old != nil {
		for _, oldRel := range old.Cards {
			if strings.Contains(oldRel, wikiRelDir+"/") {
				_ = os.Remove(filepath.Join(absRoot, filepath.FromSlash(oldRel)))
			}
		}
	}
	m.Docs = append(m.Docs, wikiDoc{
		Node: nodeKey, Path: base,
		DocID:   docIDOf(nodeKey, base),
		Status:  "no_concept",
		Reason:  firstNonEmpty(reason, "純紀錄，無可萃取概念"),
		Created: created, Updated: todayOf(now),
	})
	if err := regenerateWikiIndexes(absRoot, m); err != nil {
		return err
	}
	return saveWikiManifest(absRoot, m)
}

// RemoveWikiDoc 原稿消失時，收走它的卡並把它從索引與 manifest 移除。
func RemoveWikiDoc(absRoot, relPath string) error {
	node, base := docNodeAndPath(absRoot, relPath)
	nodeKey := nodeKeyOf(node)
	m := loadWikiManifest(absRoot)
	old := m.removeDoc(nodeKey, base)
	if old == nil {
		return nil
	}
	for _, oldRel := range old.Cards {
		if strings.Contains(oldRel, wikiRelDir+"/") {
			_ = os.Remove(filepath.Join(absRoot, filepath.FromSlash(oldRel)))
		}
	}
	if err := regenerateWikiIndexes(absRoot, m); err != nil {
		return err
	}
	return saveWikiManifest(absRoot, m)
}

func docIDOf(nodeKey, base string) string {
	sum := sha256.Sum256([]byte(nodeKey + "/" + base))
	return hex.EncodeToString(sum[:8])
}

// ── 索引：完全從 manifest 機械重算（index 是導出資料，不是第二份真相）──

// regenerateWikiIndexes 重寫「有文件的節點＋它們所有祖先」的 00-INDEX.md。
// index 每行五樣（連結／摘要／標籤／建立日／更新日）全部照抄卡的 frontmatter
// （記在 manifest）——這正是 index 可以零 LLM 成本機械產生的原因（規範第一之五部）。
func regenerateWikiIndexes(absRoot string, m *wikiManifest) error {
	need := map[string]bool{"": true} // 根節點永遠要有（manifest 住在那裡）
	for _, d := range m.Docs {
		n := nodeFromKey(d.Node)
		need[n] = true
		for n != "" {
			n = parentNode(n)
			need[n] = true
		}
	}
	for node := range need {
		if err := writeNodeIndex(absRoot, node, m); err != nil {
			return err
		}
	}
	return nil
}

func parentNode(node string) string {
	d := path.Dir(node)
	if d == "." || d == "/" {
		return ""
	}
	return d
}

// childNodesOf 回傳 node 的「直接子節點」（底下（含各層）有文件的直接子目錄）＋各自篇數。
func childNodesOf(node string, m *wikiManifest) ([]string, map[string]int) {
	prefix := ""
	if node != "" {
		prefix = node + "/"
	}
	count := map[string]int{}
	for _, d := range m.Docs {
		n := nodeFromKey(d.Node)
		if n == node {
			continue
		}
		if prefix != "" && !strings.HasPrefix(n, prefix) {
			continue
		}
		rest := strings.TrimPrefix(n, prefix)
		if rest == "" {
			continue
		}
		child := strings.SplitN(rest, "/", 2)[0]
		count[child]++
	}
	var kids []string
	for k := range count {
		kids = append(kids, k)
	}
	sort.Strings(kids)
	return kids, count
}

func writeNodeIndex(absRoot, node string, m *wikiManifest) error {
	nodeKey := nodeKeyOf(node)
	var docs []wikiDoc
	for _, d := range m.Docs {
		if d.Node == nodeKey {
			docs = append(docs, d)
		}
	}
	sort.Slice(docs, func(i, j int) bool { return docs[i].Path < docs[j].Path })
	kids, kidCount := childNodesOf(node, m)

	var b strings.Builder
	b.WriteString("# 00-INDEX\n\n")
	if len(kids) > 0 {
		b.WriteString("## 子節點\n")
		for _, k := range kids {
			b.WriteString("- 📁 `" + k + "/` — 內含 " + itoa(kidCount[k]) + " 篇文件\n")
		}
		b.WriteString("\n")
	}
	b.WriteString("## 文件\n")
	if len(docs) == 0 {
		b.WriteString("（本層沒有文件；見子節點。）\n")
	}
	for _, d := range docs {
		if d.Status == "no_concept" {
			b.WriteString("- `" + d.Path + "` — 空：" + d.Reason + "\n")
			continue
		}
		tags := make([]string, 0, len(d.Tags))
		for _, t := range d.Tags {
			tags = append(tags, "#"+t)
		}
		b.WriteString("- [[" + d.Card + "]] — " + d.Gloss + "（原稿 `" + d.Path + "`）\n")
		b.WriteString("  " + strings.Join(tags, " ") + "　建 " + d.Created + "　更 " + d.Updated + "\n")
	}
	b.WriteString("\n## 說明\n")
	b.WriteString("本索引由 Arcrun RAG 自動維護（機械產生，改了會被覆寫）。\n")
	b.WriteString("「空」表示該檔沒有可萃取的概念（例如純紀錄），不是被漏掉。\n")
	b.WriteString("每張文件卡是那份原稿的 hub；概念卡從文件卡點進去。\n")

	dest := filepath.Join(wikiDirFor(absRoot, node), "00-INDEX.md")
	return writeWikiFile(absRoot, dest, []byte(b.String()))
}