figdown 0.1.0-rc.1

package/README.md

@@ -0,0 +1,201 @@
+# FigDown
+
+> **Figures as text — one source, two readers.**
+
+繁體中文版：[README.zh-tw.md](README.zh-tw.md)
+
+FigDown is an (early, in-design) open standard for describing figures as
+plain text inside Markdown — so that the *same* source is:
+
+- **read as text by AI agents** — the knowledge in your diagrams stops
+  being locked inside bitmaps, and
+- **rendered as figures for humans** — deterministically converted to SVG
+  that travels with the document, viewable in any Markdown viewer.
+
+Think "the figure layer of Markdown": what Mermaid did for flowcharts,
+extended to the diagram types Mermaid can't express (network topologies,
+annotated block diagrams, lookup chains, packet walks…), with layout
+treated as part of the knowledge.
+
+**[Try it live — the editor runs in your browser, no install](https://figdown.github.io/figdown/)**
+(edit text on the left, deterministic SVG on the right; open/save real
+`.fd` files; every GUI action is a text edit).
+
+## See it
+
+This figure *is* FigDown — the text below is its complete source:
+
+```figdown
+figdown 0.1 topology
+title "VXLAN/EVPN Leaf-Spine Fabric — topology with plane notes"
+
+# ── Semantic classes ─────────────────────────────────────────────────
+class underlay "Physical underlay link — eBGP/L3 transport between leaf and spine"
+class overlay  "Logical VXLAN overlay tunnel — rides on the physical underlay" style=dashed color=#dc2626
+
+# ── Topology ────────────────────────────────────────────────────────
+node sp1 "Spine-1" shape=rounded color=#e0e7ff
+node sp2 "Spine-2" shape=rounded color=#e0e7ff
+node lf1 "Leaf-1 (VTEP)" shape=rounded
+node lf2 "Leaf-2 (VTEP)" shape=rounded
+node lf3 "Leaf-3 (VTEP)" shape=rounded
+node h1 "VM-A (VLAN 10)"
+node h2 "VM-B (VLAN 10)"
+node h3 "VM-C (VLAN 20)"
+flow down
+rank sp1 sp2
+rank lf1 lf2 lf3
+
+# underlay: every leaf peers with every spine
+edge sp1 -[eBGP]- lf1 class=underlay
+edge sp1 -- lf2 class=underlay
+edge sp1 -- lf3 class=underlay
+edge sp2 -- lf1 class=underlay
+edge sp2 -- lf2 class=underlay
+edge sp2 -- lf3 class=underlay
+edge lf1 -- h1 class=underlay
+edge lf2 -- h2 class=underlay
+edge lf3 -- h3 class=underlay
+
+# overlay: VXLAN tunnel between the two VTEPs sharing VNI 10010
+layer overlay "VXLAN tunnels" z=2
+edge lf1 <-[VXLAN VNI 10010]-> lf2 class=overlay layer=overlay
+
+# ── Supplementary knowledge ─────────────────────────────────────────
+table vni "VNI mapping"
+| Leaf   | VLAN | VNI   | Type |
+|--------|:----:|-------|------|
+| Leaf-1 | 10   | 10010 | L2   |
+| Leaf-2 | 10   | 10010 | L2   |
+| Leaf-3 | 20   | 10020 | L2   |
+cell 1,3 color=#fee2e2
+cell 2,3 color=#fee2e2
+
+table planes "Fabric planes"
+| Plane           | Protocol          | Role                      |
+|-----------------|-------------------|---------------------------|
+| Underlay        | eBGP              | loopback reachability     |
+| Overlay control | MP-BGP EVPN       | MAC/IP route distribution |
+| Overlay data    | VXLAN (UDP 4789)  | L2-in-L3 encapsulation    |
+```
+
+This single source does three things mainstream diagram tools cannot combine:
+the red dashed VXLAN edge belongs to a declared `layer` (named overlay, z=2),
+so it can be toggled or styled independently of the underlay topology;
+the two GFM tables are pasted verbatim — they render as formatted tables in the
+SVG and are read as structured data by AI agents without any conversion step;
+and the rank declarations give the layout explicit semantic structure
+(spines above leaves above hosts) that survives edits without a full re-layout.
+The fenced block above is exactly what an AI agent reads as the figure's meaning.
+
+![VXLAN/EVPN Leaf-Spine Fabric](examples/evpn-fabric.svg)
+
+<sub>source: [examples/evpn-fabric.fd](examples/evpn-fabric.fd)</sub>
+
+## Why
+
+Technical documents are full of figures whose *layout carries meaning* —
+rank, zones, direction, adjacency. Today that knowledge is trapped in
+images: AI agents can't reliably read it, and hand-maintained diagrams
+drift from the text around them. Existing text-to-diagram tools cover only
+part of the problem and none of them promise the property we consider
+essential: **a small edit to the source must produce a small change in the
+figure** — never a full re-layout that destroys the reader's mental map.
+
+## Design axioms (settled so far)
+
+1. **Text is the single source of truth.** Figures are build artifacts,
+   100% generated from text. No dual maintenance, ever.
+2. **Deterministic, program-only rendering.** Same source → same SVG,
+   bit-level; no LLM in the rendering path.
+3. **Layout stability.** Local edit → local change. Explicitly declared
+   attributes (position, size, color…) are rigid; everything undeclared
+   adapts automatically with minimal spillover.
+4. **Two audiences, one artifact.** AI reads the fenced source block;
+   humans see the embedded SVG. The standard defines how the two stay
+   paired and in sync.
+5. **Defaults = the common case.** Most figures should need no
+   supplementary declarations at all (convention over configuration).
+6. **Small, closed, token-lean core.** Every line starts with a known
+   keyword; unknown lines are errors with line numbers (this powers the
+   AI write→validate→fix loop). Teaching the language to an AI agent must
+   fit in a lean prompt. Generic rules over special cases; survey existing
+   standards before inventing anything.
+7. **An editor is mandatory, but every GUI action is a text edit** —
+   dragging a node writes a position declaration. The GUI never owns state
+   that the text can't express.
+8. **Static first; dynamic later.** Dynamic = static + a discrete
+   page/step sequence (for algorithm/protocol walkthroughs), not a
+   timeline animation language.
+
+## Recommended usage in Markdown documents (current stage)
+
+Until `.fd` is natively rendered by Markdown viewers (as mermaid is),
+embed figures like this:
+
+```markdown
+![Ingress datapath](figures/ingress.svg)
+
+<sub>source: [figures/ingress.fd](figures/ingress.fd)</sub>
+```
+
+The SVG is what humans see; the `source:` footer points at the `.fd`,
+which is the figure's single source of truth — **AI agents read the
+`.fd` for the meaning** and never paste its content into the `.md`.
+Each generated SVG also embeds its own source + SHA-256, so the figure
+file alone can always be reopened and edited. See
+[AGENT-GUIDE.md](AGENT-GUIDE.md) for the full agent-facing workflow.
+
+## Status
+
+**Requirements & design phase.** Nothing to install yet. Current documents:
+
+- [requirements-notes.md](design/requirements-notes.md) — the requirements log
+  (R0–R15) and decisions (D1–D3), also in
+  [繁體中文](design/requirements-notes.zh-tw.md)
+- [syntax-draft.md](spec/syntax-draft.md) — syntax draft v0.0 (discussion
+  stage), also in [繁體中文](spec/syntax-draft.zh-tw.md)
+- [AUTHORING.md](AUTHORING.md) — the authoring SOP: how to pick a
+  template, express meaning with existing constructs, and escalate a
+  gap into a syntax proposal, also in [繁體中文](AUTHORING.zh-tw.md)
+- [AGENT-GUIDE.md](AGENT-GUIDE.md) — the self-contained guide for AI
+  agents maintaining figures with FigDown, also in
+  [繁體中文](AGENT-GUIDE.zh-tw.md)
+- [MIGRATIONS.md](spec/MIGRATIONS.md) — schema-migration-style version log:
+  every syntax change ships a mechanical rewrite rule, also in
+  [繁體中文](spec/MIGRATIONS.zh-tw.md)
+- [census.md](design/census.md) — figure-type census over a real 774-document
+  corpus; the empirical basis for v0.1 scope and priorities, also in
+  [繁體中文](design/census.zh-tw.md)
+- [spec/genres/](spec/genres/bitfield.md) — per-genre normative documents
+  (R51): one self-contained file per genre (bitfield, table, wave) covering
+  defaults, closed keyword vocabulary, semantic model, errors, and an example
+- [conformance/](conformance/README.md) — golden parser-conformance
+  fixtures (100 cases) a second implementation can be tested against;
+  engine-vs-spec deviations recorded in its DISCREPANCIES file
+- [prior-art.md](design/prior-art.md) — informative survey of mainstream
+  diagram-language conventions (edge labels, ERD, D2 relationship),
+  weighted by adoption, also in [繁體中文](design/prior-art.zh-tw.md)
+- [examples/index.md](examples/index.md) — the example gallery: real
+  figures as committed `.fd`+`.svg` pairs (protocol headers first)
+- [editor/figdown.html](editor/figdown.html) — the editor
+  ([live](https://figdown.github.io/figdown/)): open in any
+  browser, edit text on the left, get a deterministic SVG on the right
+  (core scene + bitfield + table + wave). Opens/saves `.fd` files
+  (Ctrl+S writes back to the same file), undo/redo, autosave,
+  draw.io-style direct manipulation where every GUI action is a text
+  edit. The exported SVG embeds its own source and SHA-256.
+- [skill/README.md](skill/README.md) — installable agent skill: teach
+  a coding agent (e.g. Claude Code) to maintain figures with FigDown —
+  `cp -r skill/figdown ~/.claude/skills/` and ask for a figure.
+
+## Contributing
+
+Ideas, counter-examples, and prior-art pointers are very welcome — please
+open an issue (the syntax-proposal template shows what evidence a
+ruling needs; the change process itself is documented in
+[spec/PROCESS.md](spec/PROCESS.md)). The most valuable contributions right now:
+
+- diagram types we must cover (with real samples),
+- existing standards/conventions we should borrow instead of invent,
+- attacks on the axioms above (tell us where they break).

package/README.zh-tw.md

@@ -0,0 +1,185 @@
+# FigDown
+
+> **Figures as text — one source, two readers.**（圖即文字——一份來源，兩種讀者。）
+
+English version: [README.md](README.md)
+
+FigDown 是一個（早期、設計中的）開放標準：把圖形以純文字描述、放在
+Markdown 裡——讓**同一份來源**同時被：
+
+- **AI agent 當作文字閱讀**——圖裡的知識不再被鎖在點陣圖中；
+- **人類當作圖形閱讀**——確定性地轉換成 SVG、隨文件攜帶，任何
+  Markdown viewer 都能顯示。
+
+可以理解為「Markdown 的圖形層」：Mermaid 為流程圖做到的事，延伸到
+Mermaid 表達不了的圖型（網路拓撲、帶註記的方塊圖、查表鏈、封包走訪
+……），並把 layout 視為知識的一部分。
+
+**[線上試用——編輯器直接在瀏覽器跑，零安裝](https://figdown.github.io/figdown/)**
+（左邊改文字、右邊即時確定性 SVG；可開啟/儲存真實 `.fd` 檔；
+每個 GUI 動作都是文字編輯）。
+
+## 眼見為憑
+
+這張圖*就是* FigDown——下面的文字是它的完整來源：
+
+```figdown
+figdown 0.1 topology
+title "VXLAN/EVPN Leaf-Spine Fabric — topology with plane notes"
+
+# ── Semantic classes ─────────────────────────────────────────────────
+class underlay "Physical underlay link — eBGP/L3 transport between leaf and spine"
+class overlay  "Logical VXLAN overlay tunnel — rides on the physical underlay" style=dashed color=#dc2626
+
+# ── Topology ────────────────────────────────────────────────────────
+node sp1 "Spine-1" shape=rounded color=#e0e7ff
+node sp2 "Spine-2" shape=rounded color=#e0e7ff
+node lf1 "Leaf-1 (VTEP)" shape=rounded
+node lf2 "Leaf-2 (VTEP)" shape=rounded
+node lf3 "Leaf-3 (VTEP)" shape=rounded
+node h1 "VM-A (VLAN 10)"
+node h2 "VM-B (VLAN 10)"
+node h3 "VM-C (VLAN 20)"
+flow down
+rank sp1 sp2
+rank lf1 lf2 lf3
+
+# underlay: every leaf peers with every spine
+edge sp1 -[eBGP]- lf1 class=underlay
+edge sp1 -- lf2 class=underlay
+edge sp1 -- lf3 class=underlay
+edge sp2 -- lf1 class=underlay
+edge sp2 -- lf2 class=underlay
+edge sp2 -- lf3 class=underlay
+edge lf1 -- h1 class=underlay
+edge lf2 -- h2 class=underlay
+edge lf3 -- h3 class=underlay
+
+# overlay: VXLAN tunnel between the two VTEPs sharing VNI 10010
+layer overlay "VXLAN tunnels" z=2
+edge lf1 <-[VXLAN VNI 10010]-> lf2 class=overlay layer=overlay
+
+# ── Supplementary knowledge ─────────────────────────────────────────
+table vni "VNI mapping"
+| Leaf   | VLAN | VNI   | Type |
+|--------|:----:|-------|------|
+| Leaf-1 | 10   | 10010 | L2   |
+| Leaf-2 | 10   | 10010 | L2   |
+| Leaf-3 | 20   | 10020 | L2   |
+cell 1,3 color=#fee2e2
+cell 2,3 color=#fee2e2
+
+table planes "Fabric planes"
+| Plane           | Protocol          | Role                      |
+|-----------------|-------------------|---------------------------|
+| Underlay        | eBGP              | loopback reachability     |
+| Overlay control | MP-BGP EVPN       | MAC/IP route distribution |
+| Overlay data    | VXLAN (UDP 4789)  | L2-in-L3 encapsulation    |
+```
+
+這份來源做了三件主流圖形工具無法合而為一的事：
+那條紅色虛線 VXLAN edge 屬於一個宣告的 `layer`（named overlay, z=2），
+可以獨立切換或套用樣式、不干擾 underlay 拓撲；
+兩張 GFM 表格原文貼入——在 SVG 中以格式化表格呈現，
+AI agent 也能直接讀取結構化資料，不需要任何轉換；
+而 rank 宣告賦予 layout 明確的語意結構（spine 在 leaf 上，leaf 在 host 上），
+修改後局部重排而非全圖洗牌。
+上方圍欄裡的文字，正是 AI agent 讀取這張圖「意義」的原文。
+
+![VXLAN/EVPN Leaf-Spine Fabric](examples/evpn-fabric.svg)
+
+<sub>來源：[examples/evpn-fabric.fd](examples/evpn-fabric.fd)</sub>
+
+## 為什麼
+
+技術文件裡充滿「**排版本身承載語意**」的圖——位階、分區、方向、相鄰
+關係。今天這些知識被困在圖片裡：AI 讀不可靠，手工維護的圖又跟周圍的
+文字漸行漸遠。既有的 text-to-diagram 工具只覆蓋一部分問題，而且沒有
+任何一個承諾我們視為關鍵的性質：**來源的小修改必須只造成圖的小變化**
+——絕不能全圖重排、摧毀讀者已建立的心智地圖。
+
+## 設計公理（目前已定）
+
+1. **文字是唯一真相。** 圖是建置產物，100% 由文字生成。永不雙源維護。
+2. **確定性、純程式渲染。** 同來源 → 同 SVG（位元級）；渲染路徑上
+   沒有 LLM。
+3. **排版穩定性。** 局部修改 → 局部變化。明確宣告的屬性（位置、尺寸、
+   顏色……）是剛性約束；未宣告的一切自動適應、外溢最小化。
+4. **兩種受眾，一份產物。** AI 讀圍欄裡的來源文字；人類看嵌入的
+   SVG。標準定義兩者如何配對、如何保持同步。
+5. **預設值 = 最大宗情況。** 多數圖應該完全不需要補充宣告
+   （慣例優於設定）。
+6. **小而封閉、token 精簡的核心。** 每行以已知關鍵字開頭；未知行即
+   錯誤、附行號（這支撐 AI 寫→驗→修迴圈）。教會 AI 這個語言必須只
+   需要一段精簡的 prompt。通用規則優於特例；發明任何東西之前先盤點
+   既有標準。
+7. **編輯器是必要條件，但每個 GUI 動作都是文字編輯**——拖動節點
+   = 寫入一行位置宣告。GUI 永不持有文字表達不了的狀態。
+8. **靜態優先；動態後行。** 動態 = 靜態 + 離散的頁/步驟序列（用於
+   演算法/協議講解），不是時間軸動畫語言。
+
+## Markdown 文件中的建議用法（現階段）
+
+在 `.fd` 尚未被 MD viewer 原生渲染（如 mermaid）之前，圖片這樣嵌入：
+
+```markdown
+![Ingress datapath](figures/ingress.svg)
+
+<sub>source: [figures/ingress.fd](figures/ingress.fd)</sub>
+```
+
+SVG 給人看；`source:` 註腳指向 `.fd`——它是圖的唯一真相來源，
+**AI agent 讀 `.fd` 取得意義**，且絕不把其內容貼進 `.md`。每個生成
+的 SVG 也內嵌自身來源 + SHA-256，因此單憑圖檔永遠能重新開啟編輯。
+完整的 agent 工作流見 [AGENT-GUIDE.zh-tw.md](AGENT-GUIDE.zh-tw.md)。
+
+## 現狀
+
+**需求與設計階段。** 目前還沒有可安裝的東西。現有文件：
+
+- [requirements-notes.zh-tw.md](design/requirements-notes.zh-tw.md) —
+  需求記錄（R0–R15）與決議（D1–D3），英文版
+  [requirements-notes.md](design/requirements-notes.md)
+- [syntax-draft.zh-tw.md](spec/syntax-draft.zh-tw.md) — 語法草案 v0.0
+  （討論階段），英文版 [syntax-draft.md](spec/syntax-draft.md)
+- [AUTHORING.zh-tw.md](AUTHORING.zh-tw.md) — 撰寫 SOP：如何選
+  template、以既有構件表達語意、缺口如何升級為語法提案，英文版
+  [AUTHORING.md](AUTHORING.md)
+- [AGENT-GUIDE.zh-tw.md](AGENT-GUIDE.zh-tw.md) — 給 AI agent 的
+  自足指南（以 FigDown 維護圖片），英文版 [AGENT-GUIDE.md](AGENT-GUIDE.md)
+- [MIGRATIONS.zh-tw.md](spec/MIGRATIONS.zh-tw.md) — schema-migration 式
+  版本紀錄：每次語法變更附機械式改寫規則，英文版
+  [MIGRATIONS.md](spec/MIGRATIONS.md)
+- [census.zh-tw.md](design/census.zh-tw.md) — 對 774 份真實文件語料的圖型
+  普查；v0.1 範圍與優先順序的數據依據，英文版 [census.md](design/census.md)
+- [spec/genres/](spec/genres/bitfield.zh-tw.md) — 逐圖型規範文件
+  （R51）：每個圖型一份自足的文件（bitfield、table、wave），涵蓋
+  預設值、封閉關鍵字詞彙、語意模型、錯誤情況與範例
+- [conformance/](conformance/README.md) — parser 一致性 golden
+  fixtures（100 案例），供第二實作驗證；引擎-規格偏差記錄於其
+  DISCREPANCIES 檔
+- [prior-art.zh-tw.md](design/prior-art.zh-tw.md) — 主流圖語言慣例的
+  資訊性調查（edge 標籤、ERD、與 D2 的關係），以採用度加權，
+  英文版 [prior-art.md](design/prior-art.md)
+- [examples/index.zh-tw.md](examples/index.zh-tw.md) — 範例藝廊：
+  真實圖形以 `.fd`+`.svg` 成對入庫（協議標頭先行）
+- [editor/figdown.html](editor/figdown.html) — 編輯器
+  （[線上版](https://figdown.github.io/figdown/)）：用任何瀏覽器開啟，
+  左邊改文字、右邊即時得到確定性的 SVG（核心場景 + bitfield +
+  table + wave）。可開啟/儲存 `.fd` 檔（Ctrl+S 存回同一檔案）、
+  undo/redo、自動儲存、draw.io 式直接操作——每個 GUI 動作都是
+  文字編輯。匯出的 SVG 內嵌自身來源與 SHA-256。
+- [skill/README.md](skill/README.md) — 可安裝的 agent skill：讓
+  coding agent（如 Claude Code）用 FigDown 維護圖片——
+  `cp -r skill/figdown ~/.claude/skills/` 之後直接要求畫圖即可。
+
+## 參與
+
+非常歡迎想法、反例、以及既有標準的線索——請開 issue
+（syntax-proposal 模板列出裁決所需的證據；變更流程本身見
+[spec/PROCESS.zh-tw.md](spec/PROCESS.zh-tw.md)）。現階段最有
+價值的貢獻：
+
+- 我們必須覆蓋的圖型（附真實樣本）、
+- 應該借用而非自創的既有標準/慣例、
+- 對上述公理的攻擊（告訴我們它們在哪裡會破）。