母案：CM-1049（文件產出機制泛化）— 文件產出機制泛化：md + build 涵蓋討論稿/規格，並自動生成 FR 索引頁

設計與驗證結論全文：docs/analysis/2026-08-03-doc-html-pipeline.md（開工必讀，本卡只列摘要）

本案範圍

把「手刻討論稿 HTML」換成「寫 md → build → 單檔 HTML → 發 Artifact」。三部分一起做（會互相回饋，拆開要來回）：

A. 抽共用 CSS

• 新增 docs/specs/_shared/doc-base.css（排版底：token / 字級 / 表格 / code / callout）
• 新增 docs/specs/_shared/doc-artifact.css（Artifact 專屬：主題切換鈕 / statgrid / diagram 容器 / grid2）
• 內容來自 FR-060 discussion.html 那 163 行實測可用的 CSS，去掉頁面專屬部分
• 🔴 不動 site.css（SPEC 站在跑的東西，決策者明示 SPEC 站既有機制不動）

B. scripts/deliverables/render_doc.py

• 🔴 不改 render_html.py（避免動到 SPEC 站）
• pandoc -f gfm+fenced_divs+bracketed_spans → 套 template
• build 時自動做掉三件事，寫稿者完全不碰：① CSS 內嵌 ② 主題切換鈕 + script ③ §1 §2 章節編號（由 h2 順序產生）

C. 反向驗證（最硬的驗收）

• 把 FR-060 discussion.html（1,003 行）轉成 discussion.md，重新 build
• 發 Artifact 用瀏覽器實看，比對與原手刻版是否等價
• 這是證明機制真能產出同級品質的唯一方法

已驗證的事實（① 做完了，不要重做探針）

1. pandoc 輸出不需後處理。<pre class="mermaid"><code> 多一層 code、%%{init}%% 單引號被跳脫成 '——雲端 renderer 都能吃，V1 原樣就成功。build 不必加 unwrap。
2. %%{init}%% 每張圖第一行照舊要寫。陰性對照（拿掉 init）退回預設灰白，證明它確實生效。範本在 .claude/skills/big-feature-workflow/references/mermaid-init-template.md。