docs: portable runbook and Diataxis index

Public face is a product, not a laptop tool. Run steps live in
docs/runbook.md; decisions D3/D6/D14/D15/D17/D18 stay in the docs index.

AGENTS.md

@@ -42,7 +42,7 @@ bin/          self-describing tools bin/{subject}/{method}.go (shebang)
 bin/brain/    search.go serve.go index.go get.go stats.go eval.go watch.go
 bin/chats/    sync.go import.go facts.go apply.go; libs in internal/chats
 bin/mail/     sync.go import.go (index_mail → brain/index.go)
-bin/markdown/ import.go (mistune leafs)
+bin/markdown/ import.go (H2 leaf split; Python bin/md/import fallback)
 bin/postgres/ query.go (read-only YAML)
 bin/git/      import.go (go-git history; Python shim execs it)
 bin/web/      search.go (SearXNG; Python shim execs it)
@@ -92,7 +92,7 @@ bin/brain/get.go <id> [--body] [--json]          # Go read; Python bin/kb/get CI
 bin/brain/stats.go [--json]
 bin/brain/eval.go [--json]                       # recall@5; questions in internal/brain/rank
 bin/brain/serve.go                               # HTTP :8630; GET /openapi.json POST /mcp
-bin/markdown/import.go [dir]                      # mistune leaves → YAML
+bin/markdown/import.go [dir]                      # H2 leafs → YAML; Python bin/md/import fallback
 bin/git/import.go [REPO] [--json] [--limit N]     # go-git history → commit leafs
 bin/web/search.go "query" [--json]                # SearXNG; throttled ≠ absence
 bin/reasoner/bakeoff.go [--model ID] [--json]     # D18 CPU tool-call bake-off

PLAN.md

@@ -63,7 +63,7 @@ detective method: **a fact needs ≥2 independent sources or it is
     brain/serve.go          HTTP API in-process + OpenAPI/MCP (D20); Zig CGO (D21)
     cgo/zig zcc zc++        CGO toolchain (zig cc, not gcc)
     mail/import.go          JSON → markdown (no brain write)
-    markdown/import.go      mistune leaves
+    markdown/import.go      H2 leaf split (Go); Python bin/md/import fallback
     postgres/query.go       read-only YAML (wraps bin/db/psql-yq)
     git/import.go           go-git history (no git binary; conversion only)
     web/search.go           SearXNG client (throttled ≠ absence)

README.md

@@ -7,14 +7,16 @@
 [![Latest Release](https://img.shields.io/github/v/tag/eSlider/2dph?sort=semver&label=release)](https://github.com/eSlider/2dph/releases)
 [![GitHub Stars](https://img.shields.io/github/stars/eSlider/2dph?style=social)](https://github.com/eSlider/2dph/stargazers)
 
-An evidence-first brain over the operational eSlider stack. **Facts need two
+An evidence-first brain. **Facts need two independent sources, or they are
-independent sources, or they are `(not confirmed)`.**
+`(not confirmed)`.** Cursor is not the runtime.
 
-`2dph` is a single embedded knowledge graph (LadybugDB = Kuzu successor) with
+`2dph` is a single embedded knowledge graph (LadybugDB) with native **HNSW
-native **HNSW vector** + **BM25 full-text** indexes, built from markdown,
+vector** + **BM25 full-text** indexes. Search is *deduction*: confirmed facts
-compose files, ssh config, docker state, and git history. Search is
+first, supporting info second, `web-search` as the independent second source
-*deduction*: confirmed facts first, supporting info second, `web-search` as
+when the local graph cannot confirm.
-the independent second source when the local graph cannot confirm.
+
+Run it: [docs/runbook.md](docs/runbook.md). Design: [docs/design.md](docs/design.md).
+Docs index: [docs/README.md](docs/README.md).
 
 ## Architecture
 
@@ -31,7 +33,7 @@ graph TB
         EX["bin/facts/extract.go<br/>2-source pairing"]
         AU["bin/facts/audit.go<br/>confidence + staleness"]
         IDX["bin/brain/index.go<br/>chunk + embed"]
-        MD["bin/markdown/import.go<br/>mistune leaves"]
+        MD["bin/markdown/import.go<br/>H2 leaf split"]
         SR["bin/brain/search.go<br/>deduction"]
     end
 
@@ -74,7 +76,7 @@ graph TB
 ## The method
 
 Every assertion is `Who / What / How / Where / When + evidence + confidence`,
-mirroring the detective detective skill: **≥2 independent sources confirm a
+mirroring the detective method: **≥2 independent sources confirm a
 fact; conflicting sources or a single source → `hypothesis` → `(not confirmed)`.**
 
 | root | meaning | used for answers |
@@ -124,17 +126,15 @@ bin/brain/search.go "invoice from last week"                            # same s
 
 ## Storage
 
-- **LadybugDB** — single `var/kb.lbug`, Cypher property graph, HNSW + BM25
+- **LadybugDB** — single `var/kb.lbug`, Cypher + HNSW + BM25, embedded.
-  in one engine, embedded (no server), ACID, read-only-safe for concurrent
+  Read tools (`get` / `stats` / `eval`) are Go + Zig CGO (`bin/cgo/zcc`).
-  readers. Read tools (`get` / `stats` / `eval`) are Go + Zig CGO (`bin/cgo/zcc`); Python
+  Python fallbacks stay for CI until the runner fetches Zig. Write is
-  `bin/kb/{get,stats,eval}` is the CI fallback. **Never `DROP INDEX` FTS/VECTOR** on Ladybug 0.19: DROP leaves
+  Compose profile `index` (`bin/brain/index.go`).
-  ghost catalog tables (`_0_Leaf_vec_UPPER`) so recreate fails while
+- **model2vec** — `potion-multilingual-128M` (256-dim), CPU, no Ollama
-  `SHOW_INDEXES` omits HNSW. Fresh indexes = delete `var/kb.lbug` +
+  runtime dependency.
-  `bin/brain/index.go --rebuild`. Use `ensure_indexes()` after upserts.
+- facts and info split by `root` but written in the same transaction.
-- **model2vec** — `potion-multilingual-128M` static embeddings (256-dim),
+
-  CPU-fast, deterministic, no Ollama runtime dependency.
+Ladybug 0.19 DROP INDEX warning: [docs/runbook.md](docs/runbook.md).
-- facts and info split semantically by `root` column but written inside the
-  same transaction.
 
 ## Tooling conventions
 
@@ -145,11 +145,13 @@ machines. Tests gate every commit. HTTP: `bin/brain/serve.go` calls
 
 ## Development
 
+See the portable runbook: [docs/runbook.md](docs/runbook.md).
+
 ```bash
-uv venv .venv                                  # Python 3.12, uv-managed
+uv venv .venv
-uv pip install -r requirements.lock.txt        # pinned toolchain
+uv pip install -r requirements.lock.txt
-bin/facts/audit.go self                        # lexicon consistency gate
+bin/facts/audit.go self
-go test ./... && python -m unittest discover -s bin/tools -t .
+go test ./... && uv run python -m unittest discover -s bin/tools -t .
 ```
 
 Docker (optional, cached model + var volumes):

bin/markdown/import.go

@@ -1,20 +1,100 @@
-//usr/bin/env go run -tags=markdown_import "$0" "$@"; exit
+//usr/bin/env go run "$0" "$@"; exit
-//go:build markdown_import
 //
-// bin/markdown/import.go - split markdown into leafs (mistune).
+// bin/markdown/import.go - split markdown into leafs (H2 boundaries).
 //
 //	./bin/markdown/import.go [dir]
 //	./bin/markdown/import.go --files a.md,b.md --json
 //
+// Conversion only. Brain write is bin/brain/index.go.
+// Python bin/md/import remains as a fallback.
 // NOTE: never run `gofmt -w` on this file — it breaks the shebang.
 package main
 
 import (
+	"fmt"
 	"os"
+	"strings"
 
-	"github.com/eSlider/2dph/internal/cmdbin"
+	"github.com/eSlider/2dph/internal/mdleaves"
 )
 
 func main() {
-	os.Exit(cmdbin.ExecFile("bin/md/import", os.Args[1:]))
+	os.Exit(run(os.Args[1:]))
+}
+
+func run(args []string) int {
+	jsonOut := false
+	files := ""
+	root := "."
+	for i := 0; i < len(args); i++ {
+		a := args[i]
+		switch {
+		case a == "--json":
+			jsonOut = true
+		case a == "--files" && i+1 < len(args):
+			i++
+			files = args[i]
+		case strings.HasPrefix(a, "--files="):
+			files = strings.TrimPrefix(a, "--files=")
+		case a == "-h" || a == "--help":
+			fmt.Fprintln(os.Stderr, "bin/markdown/import.go [dir] [--files a.md,b.md] [--json]")
+			return 0
+		case strings.HasPrefix(a, "-"):
+			fmt.Fprintln(os.Stderr, "unknown arg:", a)
+			return 2
+		default:
+			root = a
+		}
+	}
+
+	var paths []string
+	if files != "" {
+		for _, f := range strings.Split(files, ",") {
+			f = strings.TrimSpace(f)
+			if f != "" {
+				paths = append(paths, f)
+			}
+		}
+	} else {
+		st, err := os.Stat(root)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "md/import: no such path %s\n", root)
+			return 2
+		}
+		if !st.IsDir() {
+			paths = []string{root}
+		} else {
+			var err error
+			paths, err = mdleaves.WalkMarkdown(root)
+			if err != nil {
+				fmt.Fprintf(os.Stderr, "md/import: %v\n", err)
+				return 1
+			}
+		}
+	}
+	if len(paths) == 0 {
+		fmt.Fprintln(os.Stderr, "md/import: no markdown files")
+		return 1
+	}
+
+	var all []mdleaves.Leaf
+	for _, p := range paths {
+		raw, err := os.ReadFile(p)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "md/import: %s: %v\n", p, err)
+			continue
+		}
+		all = append(all, mdleaves.ToAll(string(raw), p, "")...)
+	}
+	if jsonOut {
+		s, err := mdleaves.EncodeJSON(all)
+		if err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			return 1
+		}
+		fmt.Print(s)
+		return 0
+	}
+	fmt.Print(mdleaves.EncodeYAML(all))
+	return 0
 }

bin/tools/test_bin_layout.py

@@ -125,8 +125,28 @@ class BinLayoutTest(unittest.TestCase):
             "index_mail must point at bin/brain/index.go",
         )
 
-    def test_markdown_import_is_shebang(self) -> None:
+    def test_markdown_import_is_go_not_python_exec(self) -> None:
         self._assert_shebang("bin/markdown/import.go")
+        text = (ROOT / "bin" / "markdown" / "import.go").read_text()
+        self.assertNotIn("ExecFile", text)
+        self.assertNotIn("cmdbin", text)
+        self.assertIn("internal/mdleaves", text)
+        self.assertNotIn("kb.lbug", text)
+
+    def test_import_adapters_do_not_write_ladybug(self) -> None:
+        for rel in (
+            "bin/mail/import.go",
+            "bin/mail/import",
+            "bin/markdown/import.go",
+            "bin/chats/import.go",
+            "bin/git/import.go",
+        ):
+            text = (ROOT / rel).read_text()
+            self.assertNotIn("upsert_leaf", text, rel)
+            self.assertNotIn("kb.lbug", text, rel)
+            self.assertNotIn("var/brain.lbug", text, rel)
+        index = (ROOT / "bin" / "brain" / "index.go").read_text()
+        self.assertIn("bin/kb/index", index)
 
     def test_postgres_query_is_shebang(self) -> None:
         self._assert_shebang("bin/postgres/query.go")

bin/tools/test_index_adapters.py

@@ -0,0 +1,41 @@
+"""Import adapters write files only. Index rebuild is brain/index (D14 / Gitea #7)."""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+class IndexAdapterTest(unittest.TestCase):
+    def test_dry_run_fixture_corpus_does_not_write_lbug(self) -> None:
+        tmp = Path(tempfile.mkdtemp())
+        (tmp / "note.md").write_text("# Fixture\n\n## Leaf\n\nhello corpus\n", encoding="utf-8")
+        lbug = tmp / "kb.lbug"
+        try:
+            import ladybug  # noqa: F401
+        except ImportError:
+            venv_py = ROOT / ".venv" / "bin" / "python"
+            if not venv_py.is_file():
+                self.skipTest("ladybug missing")
+            py = str(venv_py)
+        else:
+            py = sys.executable
+        proc = subprocess.run(
+            [py, str(ROOT / "bin" / "kb" / "index"), "--dry-run", "--json", "--corpus", str(tmp)],
+            cwd=ROOT,
+            capture_output=True,
+            text=True,
+            env=os.environ.copy(),
+            check=False,
+        )
+        self.assertEqual(proc.returncode, 0, proc.stderr)
+        msg = json.loads(proc.stdout)
+        self.assertTrue(msg.get("dry_run"))
+        self.assertGreaterEqual(msg.get("corpus_total", 0), 1)
+        self.assertFalse(lbug.exists(), "dry-run must not create a Ladybug file")

bin/tools/test_published_docs.py

@@ -145,6 +145,8 @@ class PublishedDocsTest(unittest.TestCase):
             ROOT / "docs" / "design.md",
             ROOT / "skills" / "brain" / "SKILL.md",
             ROOT / "skills" / "diataxis-docs" / "SKILL.md",
+            ROOT / "docs" / "runbook.md",
+            ROOT / "docs" / "README.md",
         ]
         # Command-style `--hop 1` / `--hop N` plus follow/walk = the old lie.
         # Honest "not implemented" notes must not match.
@@ -155,3 +157,19 @@ class PublishedDocsTest(unittest.TestCase):
                 lie.search(text),
                 f"{path.relative_to(ROOT)} still claims --hop walks the graph",
             )
+
+    def test_docs_are_portable_diataxis(self) -> None:
+        index = (ROOT / "docs" / "README.md").read_text()
+        self.assertIn("type: reference", index)
+        for d in ("D3", "D6", "D14", "D15", "D17", "D18"):
+            self.assertIn(d, index)
+        runbook = (ROOT / "docs" / "runbook.md").read_text()
+        self.assertIn("type: howto", runbook)
+        self.assertIn("bin/brain/search.go", runbook)
+        self.assertIn("bin/brain/index.go", runbook)
+        self.assertNotIn("search.ops.io", runbook)
+        self.assertNotIn("/mnt/", runbook)
+        self.assertNotIn("/home/", runbook)
+        readme = (ROOT / "README.md").read_text()
+        self.assertIn("docs/runbook.md", readme)
+        self.assertNotIn("search.ops.io", readme)

docs/README.md

@@ -1,16 +1,34 @@
-# 2dph (deductionphile)
+---
+type: reference
+status: current
+related:
+  - docs/runbook.md
+  - docs/design.md
+  - PLAN.md
+---
 
-Evidence-first knowledge graph + hybrid RAG over the operational
+# 2dph docs (Diataxis)
-Brain/ops/eSlider stack. Facts need proof or they are
+
+Evidence-first knowledge graph. Facts need proof or they are
 `(not confirmed)`.
 
-- [PLAN.md](../PLAN.md) — decisions, execution order, open questions (v2)
+| Type | Doc |
-- [design](design.md) — schema, deduction model, sources
+|------|-----|
-- [reasoner](reasoner.md) — D18 CPU bake-off (Qwen3.5-9B vs Bonsai / Qwen3.6-27B)
+| tutorial / howto | [runbook](runbook.md) — run anywhere (uv, Go, Docker) |
-- [Gitea issues](https://git.produktor.io/eSlider/2dph/issues) — work board (origin)
+| explanation | [design](design.md) — two roots, deduction, D17/D20/D18 |
+| howto | [picoclaw](picoclaw.md) — MCP agent profile |
+| howto | [reasoner](reasoner.md) — CPU bake-off (D18) |
+| reference | [PLAN.md](../PLAN.md) — decisions D1–D21 |
+
+Decisions the public face must name: **D3** SearXNG compose, **D6** Go service /
+Python write sidecar, **D14** `bin/{subject}/{method}.go`, **D15** Gitea origin,
+**D17** assertion gate (facts → info → web), **D18** pluggable reasoner.
 
 Search: `bin/brain/search.go "query"` (HTTP: `bin/brain/serve.go` —
 `/health` `/search` `/get` `/stats` `/audit` `/ingest`). `--hop` is
 not a walk; the flag errors until File/FROM_FILE edges exist.
 
-Published docs live here and mirror the project state.
+Work board: [Gitea issues](https://git.produktor.io/eSlider/2dph/issues).
+PRs and CI: GitHub [`eSlider/2dph`](https://github.com/eSlider/2dph).
+
+Published docs live here and match live commands.

docs/design.md

@@ -1,3 +1,11 @@
+---
+type: explanation
+status: current
+related:
+  - docs/README.md
+  - docs/runbook.md
+---
+
 # Design — facts, info, deduction
 
 ## Two roots, one transaction

docs/runbook.md

@@ -0,0 +1,81 @@
+---
+type: howto
+status: current
+related:
+  - docs/README.md
+  - PLAN.md
+---
+
+# Run 2dph (portable)
+
+No laptop-absolute paths. Config lives in env files under `$HOME/.config/brain/`
+(mode 0600), not in git.
+
+## Toolchain
+
+- Go (see `go.mod`)
+- Python 3.12 + [uv](https://docs.astral.sh/uv)
+- Optional: Docker, Zig CGO via `bin/cgo/zig` (not gcc)
+
+```bash
+uv venv .venv
+uv pip install -r requirements.lock.txt
+eval "$(bin/cgo/zig env)"   # when compiling Ladybug read tools
+go test ./...
+uv run python -m unittest discover -s bin/tools -t .
+```
+
+## Config
+
+| File / env | Purpose |
+|------------|---------|
+| `$BRAIN_SEARCH_ENV` (default `$HOME/.config/brain/search.env`) | `BRAIN_SEARCH_URL` (SearXNG). Optional Basic Auth. |
+| `$HOME/.config/brain/db-profiles.yml` | read-only Postgres profiles (OnlyOffice via tunnel) |
+
+If the host already runs SearXNG, point `BRAIN_SEARCH_URL` at it. Do not start
+a second copy (D3). Optional Compose instance:
+
+```bash
+SEARXNG_SECRET=$(openssl rand -hex 32) docker compose --profile searxng up -d
+```
+
+That binds `127.0.0.1:8888`. JSON format must stay enabled.
+
+## Index then search
+
+Write path is Compose profile `index` (Python Ladybug rebuild) until
+`brain/add` is v2. The operator command is `bin/brain/index.go`.
+
+```bash
+bin/brain/index.go --rebuild
+bin/brain/search.go "LadybugDB vector index"     # facts → info → web (D17)
+bin/brain/search.go "upstream flag" --no-web
+bin/brain/get.go <id> --body
+bin/brain/stats.go
+```
+
+`--hop` is not implemented. Empty web results are `throttled`, not absence.
+
+Ladybug 0.19: never `DROP INDEX` FTS/VECTOR (ghost catalog). Fresh indexes =
+delete `var/kb.lbug` then `--rebuild`.
+
+## HTTP / MCP
+
+```bash
+docker compose up -d brain                       # :8630 Zig CGO serve
+docker compose --profile index run --rm index    # rebuild
+docker compose --profile picoclaw up brain-mcp   # MCP 127.0.0.1:8630
+```
+
+`GET /openapi.json`, `POST /mcp`. Agent tool order: `search` → `get` → `audit`.
+
+## Reasoner (optional, D18)
+
+CPU sidecar on `127.0.0.1:11435`. Weights are not in the 2dph image.
+
+```bash
+docker compose --profile reasoner up -d reasoner
+REASONER_BASE_URL=http://127.0.0.1:11435/v1 ./bin/reasoner/bakeoff.go --json
+```
+
+See [reasoner.md](reasoner.md).

internal/mdleaves/leaf.go

@@ -0,0 +1,146 @@
+package mdleaves
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+)
+
+type Leaf struct {
+	Source  string `json:"source"`
+	Repo    string `json:"repo"`
+	Heading string `json:"heading"`
+	Text    string `json:"text"`
+	Type    string `json:"type"`
+	Status  string `json:"status"`
+	Related string `json:"related"`
+}
+
+type chunk struct {
+	Heading string
+	Text    string
+}
+
+var (
+	h1 = regexp.MustCompile(`^# \S`)
+	h2 = regexp.MustCompile(`^## \S`)
+)
+
+func ExtractFrontmatter(text string) (map[string]string, string) {
+	if !strings.HasPrefix(text, "---") {
+		return map[string]string{}, text
+	}
+	end := strings.Index(text[3:], "\n---")
+	if end == -1 {
+		return map[string]string{}, text
+	}
+	fm := strings.TrimSpace(text[3 : 3+end])
+	body := text[3+end+4:]
+	meta := map[string]string{}
+	for _, line := range strings.Split(fm, "\n") {
+		key, value, ok := strings.Cut(line, ":")
+		if !ok {
+			continue
+		}
+		meta[strings.TrimSpace(key)] = strings.Trim(strings.TrimSpace(value), `"'`)
+	}
+	return meta, body
+}
+
+func SplitLeafs(meta map[string]string, body string) []chunk {
+	lines := strings.Split(body, "\n")
+	title := ""
+	type hdr struct {
+		heading string
+		start   int
+	}
+	var headers []hdr
+	for i, line := range lines {
+		switch {
+		case h1.MatchString(line):
+			title = strings.TrimSpace(strings.TrimLeft(line, "#"))
+		case h2.MatchString(line):
+			headers = append(headers, hdr{strings.TrimSpace(strings.TrimLeft(line, "#")), i})
+		}
+	}
+	if len(headers) == 0 {
+		var kept []string
+		for _, l := range lines {
+			if strings.TrimSpace(l) != "" {
+				kept = append(kept, l)
+			}
+		}
+		return []chunk{{Heading: title, Text: strings.TrimSpace(strings.Join(kept, "\n"))}}
+	}
+	out := make([]chunk, 0, len(headers))
+	for idx, h := range headers {
+		end := len(lines)
+		if idx+1 < len(headers) {
+			end = headers[idx+1].start
+		}
+		var kept []string
+		for _, l := range lines[h.start:end] {
+			if strings.TrimSpace(l) != "" {
+				kept = append(kept, l)
+			}
+		}
+		text := strings.Join(kept, "\n")
+		if idx == 0 && title != "" {
+			text = title + "\n\n" + text
+		}
+		out = append(out, chunk{Heading: h.heading, Text: strings.TrimSpace(text)})
+	}
+	return out
+}
+
+func ToAll(text, path, repo string) []Leaf {
+	meta, body := ExtractFrontmatter(text)
+	if meta["type"] == "" {
+		meta["type"] = "reference"
+	}
+	if meta["status"] == "" {
+		meta["status"] = "current"
+	}
+	chunks := SplitLeafs(meta, body)
+	out := make([]Leaf, 0, len(chunks))
+	for _, c := range chunks {
+		out = append(out, Leaf{
+			Source:  path,
+			Repo:    repo,
+			Heading: c.Heading,
+			Text:    c.Text,
+			Type:    meta["type"],
+			Status:  meta["status"],
+			Related: meta["related"],
+		})
+	}
+	return out
+}
+
+func WalkMarkdown(root string) ([]string, error) {
+	var out []string
+	err := filepath.Walk(root, func(p string, info os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+		if info.IsDir() {
+			return nil
+		}
+		ext := strings.ToLower(filepath.Ext(p))
+		if ext == ".md" || ext == ".markdown" {
+			out = append(out, p)
+		}
+		return nil
+	})
+	return out, err
+}
+
+func EncodeJSON(leafs []Leaf) (string, error) {
+	raw, err := json.MarshalIndent(leafs, "", "  ")
+	if err != nil {
+		return "", err
+	}
+	return string(raw) + "\n", nil
+}

internal/mdleaves/leaf_test.go

@@ -0,0 +1,73 @@
+package mdleaves
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestSplitLeafsOnH2(t *testing.T) {
+	body := "# Title\n\n## One\n\nalpha\n\n## Two\n\nbeta\n"
+	leafs := SplitLeafs(map[string]string{}, body)
+	if len(leafs) != 2 {
+		t.Fatalf("n=%d", len(leafs))
+	}
+	if leafs[0].Heading != "One" || !strings.Contains(leafs[0].Text, "Title") {
+		t.Fatalf("first=%+v", leafs[0])
+	}
+	if leafs[1].Heading != "Two" || strings.Contains(leafs[1].Text, "Title") {
+		t.Fatalf("second=%+v", leafs[1])
+	}
+}
+
+func TestSplitLeafsNoH2IsWholeDoc(t *testing.T) {
+	body := "# Title\n\njust a paragraph\n"
+	leafs := SplitLeafs(nil, body)
+	if len(leafs) != 1 {
+		t.Fatalf("n=%d", len(leafs))
+	}
+	if leafs[0].Heading != "Title" {
+		t.Fatalf("heading=%q", leafs[0].Heading)
+	}
+	if !strings.Contains(leafs[0].Text, "just a paragraph") {
+		t.Fatalf("text=%q", leafs[0].Text)
+	}
+}
+
+func TestFrontmatterAndToAll(t *testing.T) {
+	raw := "---\ntype: howto\nstatus: current\nrelated: docs/design.md\n---\n# Doc\n\n## Step\n\ndo it\n"
+	got := ToAll(raw, "docs/x.md", "eSlider/2dph")
+	if len(got) != 1 {
+		t.Fatalf("n=%d", len(got))
+	}
+	if got[0].Type != "howto" || got[0].Status != "current" {
+		t.Fatalf("%+v", got[0])
+	}
+	if got[0].Source != "docs/x.md" || got[0].Repo != "eSlider/2dph" {
+		t.Fatalf("%+v", got[0])
+	}
+	if got[0].Related != "docs/design.md" {
+		t.Fatalf("related=%q", got[0].Related)
+	}
+}
+
+func TestEncodeJSONAndYAML(t *testing.T) {
+	leafs := ToAll("# Hi\n\nbody\n", "a.md", "")
+	js, err := EncodeJSON(leafs)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(js, `"heading": "Hi"`) {
+		t.Fatalf("json=%s", js)
+	}
+	y := EncodeYAML(leafs)
+	if !strings.Contains(y, "heading: Hi") {
+		t.Fatalf("yaml=%s", y)
+	}
+}
+
+func TestDefaultsTypeAndStatus(t *testing.T) {
+	got := ToAll("# Hi\n\nbody\n", "a.md", "")
+	if got[0].Type != "reference" || got[0].Status != "current" {
+		t.Fatalf("%+v", got[0])
+	}
+}

internal/mdleaves/yaml.go

@@ -0,0 +1,36 @@
+package mdleaves
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+)
+
+func EncodeYAML(leafs []Leaf) string {
+	if len(leafs) == 0 {
+		return "[]\n"
+	}
+	var b strings.Builder
+	for _, lf := range leafs {
+		b.WriteString("-\n")
+		writeKV(&b, "source", lf.Source)
+		writeKV(&b, "repo", lf.Repo)
+		writeKV(&b, "heading", lf.Heading)
+		writeKV(&b, "text", lf.Text)
+		writeKV(&b, "type", lf.Type)
+		writeKV(&b, "status", lf.Status)
+		writeKV(&b, "related", lf.Related)
+	}
+	return b.String()
+}
+
+func writeKV(b *strings.Builder, k, v string) {
+	fmt.Fprintf(b, "  %s: %s\n", k, yamlScalar(v))
+}
+
+func yamlScalar(s string) string {
+	if strings.Contains(s, "\n") || s == "" || strings.ContainsAny(s, ":#'\"[]{}&*!|>%@`") || s != strings.TrimSpace(s) {
+		return strconv.Quote(s)
+	}
+	return s
+}