Manual: add worked-example chapter + document okf-selftest (bilingual)

supachai-j · claude · supachai-j · commit a84d4e7edc1f · 2026-06-16T01:12:46.000+07:00
Audit found the manual covered every tool except the newly-added okf-selftest.sh, and
lacked a hands-on walkthrough. Added (TH + EN):
- part4/worked-example.md — full bookstore-KB walkthrough (init → ingest → validate →
  search → viz → MCP share) with a Mermaid graph; registered in SUMMARY + the TOC page.
- appendix/tools.md — okf-selftest.sh entry.
- appendix/faq.md — "how do I verify the toolchain works?" → okf-selftest.

Verified: 26 chapters ↔ 26 TOC placeholders; links + fences balanced both languages.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/book-en/src/SUMMARY.md b/book-en/src/SUMMARY.md
@@ -29,6 +29,7 @@
 - [Query and Search](./part4/query-search.md)
 - [Adding and editing concepts](./part4/authoring.md)
 - [Validate and Visualize](./part4/validate-viz.md)
+- [Worked example: a bookstore KB](./part4/worked-example.md)
 
 # Part 5 — Authoring Well
 
diff --git a/book-en/src/appendix/faq.md b/book-en/src/appendix/faq.md
@@ -38,3 +38,6 @@ Every concept must have a non-empty `type` in its frontmatter. Add `type: ...` (
 
 ### How do I migrate an existing wiki (Obsidian, etc.) into OKF?
 In most cases: add a `type` field to each frontmatter, add `index.md`/`log.md`, convert links to relative paths, then run validate.
+
+### How do I verify the whole toolchain works?
+Run `bash tools/okf-selftest.sh` — 10 end-to-end checks (init/validate/index/search/viz/lease + embed/hybrid if Ollama is up); exits non-zero on any failure. See the [Worked Example](../part4/worked-example.md) for a hands-on full-loop walkthrough.
diff --git a/book-en/src/appendix/tools.md b/book-en/src/appendix/tools.md
@@ -49,6 +49,14 @@ python3 tools/okf-lease.py break   <concept>      # admin force-release
 ```
 env: `OKF_LEASE_DIR` (lease storage location), `OKF_LEASE_TTL` (default 300)
 
+## okf-selftest.sh — exercise the whole toolchain
+```bash
+bash tools/okf-selftest.sh
+```
+Runs 10 end-to-end checks (init → validate both a clean bundle and a deliberately-broken one →
+index → search → air-gap viz → lease → embed/hybrid if Ollama is up) · exits non-zero on any
+failure · suitable for CI.
+
 ## install.sh — Install Skill
 ```bash
 ./install.sh                 # global  → ~/.claude/skills/okf
diff --git a/book-en/src/part4/worked-example.md b/book-en/src/part4/worked-example.md
@@ -0,0 +1,103 @@
+# Worked Example: a Bookstore KB
+
+This chapter walks the whole path from zero to searchable — a small knowledge base for an
+online bookstore, with real commands. Use it as a template for your own domain.
+
+## 1. Scaffold (init)
+
+```bash
+python3 tools/okf-init.py ./bookstore-kb
+cd bookstore-kb
+```
+You get `AGENTS.md` + `wiki/{index.md, log.md, getting-started.md}` + `raw/`.
+
+## 2. Add knowledge (simulated ingest)
+
+Create concepts in the canonical layout — two tables, a metric, a join, a playbook. Example
+`wiki/tables/books.md`:
+
+```markdown
+---
+type: BigQuery Table
+title: Books
+description: One row per book in the catalog.
+tags: [catalog, books]
+timestamp: 2026-06-16T00:00:00Z
+---
+
+# Schema
+| Column | Type | Description |
+| :--- | :--- | :--- |
+| book_id | STRING | Book id (PK) |
+| author_id | STRING | FK to [authors](authors.md) |
+| price | NUMERIC | Price (USD) |
+| stock | INT64 | Units in stock |
+
+# Joins
+Join [authors](authors.md) on `author_id` — see [Books → Authors](../references/joins/books__authors.md).
+Low stock → [restock runbook](../playbooks/low-stock-runbook.md)
+```
+
+Do the same for `authors`, `references/metrics/monthly-revenue`, `references/joins/books__authors`,
+and `playbooks/low-stock-runbook`, then update `wiki/index.md` + `wiki/log.md`.
+
+> In real use: drop a source into `raw/` and have the agent run the supervised INGEST flow
+> ([Ingest chapter](./ingest.md)) — it extracts claims, shows them for approval, then writes the
+> concepts and updates index/log for you.
+
+The resulting KB is this graph:
+
+<pre class="mermaid">
+flowchart LR
+  D["datasets/bookstore"] --> B["tables/books"]
+  D --> A["tables/authors"]
+  B -->|author_id| A
+  J["references/joins/books__authors"] --> B
+  J --> A
+  M["references/metrics/monthly-revenue"] --> D
+  P["playbooks/low-stock-runbook"] --> B
+</pre>
+
+## 3. Validate conformance
+
+```bash
+python3 tools/okf-validate.py ./wiki
+# → ✓ CONFORMANT with OKF v0.1  (0 warning(s), 0 info)
+```
+
+## 4. Search
+
+```bash
+python3 tools/okf-index.py build ./wiki                       # build the BM25 index
+python3 tools/okf-search.py "how to join books to authors" --bundle ./wiki
+# → references/joins/books__authors  [Reference]   ranked #1
+```
+
+Add semantic (optional, on-prem):
+```bash
+ollama pull nomic-embed-text
+python3 tools/okf-embed.py build ./wiki
+python3 tools/okf-search.py "who wrote the novels" --bundle ./wiki
+# → mode: hybrid (bm25+semantic, RRF) — finds authors even with no keyword overlap
+```
+
+## 5. Visualize
+
+```bash
+python3 tools/okf-viz.py ./wiki --name "Bookstore KB"
+open wiki/viz.html        # one file, opens offline
+```
+
+## 6. (Team) Share via MCP
+
+To let the whole team/agents use it: commit `wiki/` to an internal git server and bring up the
+[MCP server](../part6/self-host.md) pointed at this bundle — agents can then `okf_search` (hybrid)
+and propose changes via PR/lease.
+
+## Summary
+
+```text
+okf-init → (ingest concepts) → okf-validate → okf-index/okf-search → okf-viz → [MCP share]
+```
+
+That's the full loop! Next, see [Authoring Well](../part5/best-practices.md) to grow the KB with quality.
diff --git a/book-en/src/toc.md b/book-en/src/toc.md
@@ -28,6 +28,7 @@
 - [Query and Search](./part4/query-search.md)<span class="okf-leader"></span><span class="okf-pg"></span>
 - [Adding and editing concepts](./part4/authoring.md)<span class="okf-leader"></span><span class="okf-pg"></span>
 - [Validate and Visualize](./part4/validate-viz.md)<span class="okf-leader"></span><span class="okf-pg"></span>
+- [Worked example: a bookstore KB](./part4/worked-example.md)<span class="okf-leader"></span><span class="okf-pg"></span>
 
 **Part 5 — Authoring Well**
 
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
@@ -29,6 +29,7 @@
 - [Query และ Search](./part4/query-search.md)
 - [เพิ่มและแก้ไข concept](./part4/authoring.md)
 - [Validate และ Visualize](./part4/validate-viz.md)
+- [ตัวอย่างใช้งานจริง: KB ร้านหนังสือ](./part4/worked-example.md)
 
 # ภาคที่ 5 — เขียนให้ดี
 
diff --git a/book/src/appendix/faq.md b/book/src/appendix/faq.md
@@ -44,3 +44,6 @@ filing, bookkeeping
 
 ### จะ migrate wiki เดิม (Obsidian ฯลฯ) เข้า OKF ยังไง?
 ส่วนใหญ่แค่เพิ่มฟิลด์ `type` ใน frontmatter + เพิ่ม `index.md`/`log.md` + ปรับลิงก์ให้ relative แล้วรัน validate
+
+### จะตรวจว่า toolchain ใช้ได้จริงทั้งชุดยังไง?
+รัน `bash tools/okf-selftest.sh` — เทสต์ end-to-end 10 ข้อ (init/validate/index/search/viz/lease + embed/hybrid ถ้ามี Ollama) exit ≠ 0 ถ้ามีข้อพลาด · ดู[ตัวอย่างใช้งานจริง](../part4/worked-example.md) สำหรับการเดินครบลูปด้วยมือ
diff --git a/book/src/appendix/tools.md b/book/src/appendix/tools.md
@@ -49,6 +49,12 @@ python3 tools/okf-lease.py break   <concept>      # admin บังคับป
 ```
 env: `OKF_LEASE_DIR` (ที่เก็บ lease), `OKF_LEASE_TTL` (default 300)
 
+## okf-selftest.sh — ทดสอบ toolchain ทั้งชุด
+```bash
+bash tools/okf-selftest.sh
+```
+รัน 10 ข้อ end-to-end (init → validate ทั้ง clean และจับ bundle เสีย → index → search → viz air-gap → lease → embed/hybrid ถ้ามี Ollama) · exit ≠ 0 ถ้ามีข้อพลาด · เหมาะใช้ใน CI
+
 ## install.sh — ติดตั้ง skill
 ```bash
 ./install.sh                 # global  → ~/.claude/skills/okf
diff --git a/book/src/part4/worked-example.md b/book/src/part4/worked-example.md
@@ -0,0 +1,99 @@
+# ตัวอย่างใช้งานจริง: KB ร้านหนังสือ
+
+บทนี้เดินครบทุกขั้นตั้งแต่ศูนย์จนค้นได้ — สร้าง knowledge base เล็ก ๆ ของร้านหนังสือออนไลน์
+ด้วยคำสั่งจริง ใช้เป็นแม่แบบกับโดเมนของคุณได้เลย
+
+## 1. สร้างโครง (init)
+
+```bash
+python3 tools/okf-init.py ./bookstore-kb
+cd bookstore-kb
+```
+ได้ `AGENTS.md` + `wiki/{index.md, log.md, getting-started.md}` + `raw/`
+
+## 2. ใส่ความรู้ (จำลอง ingest)
+
+สร้าง concept ตามโครงสร้าง canonical — ตาราง 2 ตัว, metric, join, playbook ตัวอย่าง `wiki/tables/books.md`:
+
+```markdown
+---
+type: BigQuery Table
+title: Books
+description: หนึ่งแถวต่อหนังสือหนึ่งเล่มในแคตตาล็อก
+tags: [catalog, books]
+timestamp: 2026-06-16T00:00:00Z
+---
+
+# Schema
+| Column | Type | Description |
+| :--- | :--- | :--- |
+| book_id | STRING | รหัสหนังสือ (PK) |
+| author_id | STRING | FK ไปยัง [authors](authors.md) |
+| price | NUMERIC | ราคา (USD) |
+| stock | INT64 | จำนวนคงคลัง |
+
+# Joins
+เชื่อม [authors](authors.md) ผ่าน `author_id` — ดู [Books → Authors](../references/joins/books__authors.md)
+stock ต่ำ → [restock runbook](../playbooks/low-stock-runbook.md)
+```
+
+ทำแบบเดียวกันกับ `authors`, `references/metrics/monthly-revenue`, `references/joins/books__authors`,
+`playbooks/low-stock-runbook` แล้วอัปเดต `wiki/index.md` + `wiki/log.md`
+
+> ในงานจริง: วาง source ลง `raw/` แล้วให้ agent ทำ INGEST แบบมีคนกำกับ ([บท Ingest](./ingest.md)) — agent จะดึงประเด็น แสดงให้อนุมัติ แล้วเขียน concept + อัปเดต index/log ให้
+
+KB ที่ได้เป็นกราฟแบบนี้:
+
+<pre class="mermaid">
+flowchart LR
+  D["datasets/bookstore"] --> B["tables/books"]
+  D --> A["tables/authors"]
+  B -->|author_id| A
+  J["references/joins/books__authors"] --> B
+  J --> A
+  M["references/metrics/monthly-revenue"] --> D
+  P["playbooks/low-stock-runbook"] --> B
+</pre>
+
+## 3. ตรวจ conformance
+
+```bash
+python3 tools/okf-validate.py ./wiki
+# → ✓ CONFORMANT with OKF v0.1  (0 warning(s), 0 info)
+```
+
+## 4. ค้นหา
+
+```bash
+python3 tools/okf-index.py build ./wiki                       # สร้าง BM25 index
+python3 tools/okf-search.py "how to join books to authors" --bundle ./wiki
+# → references/joins/books__authors  [Reference]   อันดับ 1
+```
+
+เพิ่ม semantic (ไม่บังคับ, on-prem):
+```bash
+ollama pull nomic-embed-text
+python3 tools/okf-embed.py build ./wiki
+python3 tools/okf-search.py "who wrote the novels" --bundle ./wiki
+# → mode: hybrid (bm25+semantic, RRF) — จับ authors ได้แม้ไม่มีคำตรงกัน
+```
+
+## 5. ดูกราฟ
+
+```bash
+python3 tools/okf-viz.py ./wiki --name "Bookstore KB"
+open wiki/viz.html        # ไฟล์เดียว เปิด offline ได้
+```
+
+## 6. (ทีม) แชร์ผ่าน MCP
+
+ทำให้ทั้งทีม/agent ใช้ร่วมกัน: commit `wiki/` ขึ้น git ภายใน แล้วยก [MCP server](../part6/self-host.md)
+ชี้มาที่ bundle นี้ — agent จะ `okf_search` แบบ hybrid และเสนอแก้ผ่าน PR/lease ได้
+
+## สรุปลำดับ
+
+```text
+okf-init → (ingest concepts) → okf-validate → okf-index/okf-search → okf-viz → [MCP share]
+```
+
+ครบลูปแล้ว! ต่อไปดู[แนวทางการเขียนที่ดี](../part5/best-practices.md) เพื่อให้ KB โตอย่างมีคุณภาพ
diff --git a/book/src/toc.md b/book/src/toc.md
@@ -28,6 +28,7 @@
 - [Query และ Search](./part4/query-search.md)<span class="okf-leader"></span><span class="okf-pg"></span>
 - [เพิ่มและแก้ไข concept](./part4/authoring.md)<span class="okf-leader"></span><span class="okf-pg"></span>
 - [Validate และ Visualize](./part4/validate-viz.md)<span class="okf-leader"></span><span class="okf-pg"></span>
+- [ตัวอย่างใช้งานจริง: KB ร้านหนังสือ](./part4/worked-example.md)<span class="okf-leader"></span><span class="okf-pg"></span>
 
 **ภาคที่ 5 — เขียนให้ดี**
 
