Skip to content

Commit 84833e8

Browse files
supachai-jclaude
supachai-j
and
claude
committed
Enterprise diagrams, TOC icons, and authorship credit
- Mermaid diagrams in the enterprise chapters: architecture (git + MCP internal-network flowchart, replacing ASCII) and write-models (PR-gated flow + lease/lock flow). Both languages; in-diagram Thai labels localized for the EN book. - Nice SVG line-icons on the landing-page TOC cards (7 per language) + icon CSS. - Authorship on both covers + book.toml: compiled by Supachai Jaturaprom [TumEz], written by Claude Code — Opus 4.8 (AI). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent 7152bb4 commit 84833e8

10 files changed

Lines changed: 90 additions & 50 deletions

File tree

‎book-en/book.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[book]
22
title = "The Open Knowledge Format (OKF) Handbook"
3-
authors = ["Supachai-ja"]
3+
authors = ["Supachai Jaturaprom [TumEz] (compiler)", "Claude Code — Opus 4.8 (AI, author)"]
44
description = "An English user handbook for building and operating an AI-maintained knowledge base with the Open Knowledge Format — from beginner to enterprise."
55
language = "en"
66
src = "src"

‎book-en/css/custom.css‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,8 @@
7979
}
8080
.okf-toc-card .ttl { display: block; font-weight: 700; color: var(--fg); margin-bottom: 0.2rem; }
8181
.okf-toc-card .dsc { display: block; font-size: 0.85rem; color: var(--sidebar-fg, #6b7280); line-height: 1.5; }
82+
.okf-toc-card svg.ico { width: 26px; height: 26px; color: #8b5cf6; display: block; margin-bottom: 0.45rem; }
83+
.okf-cover-meta br { line-height: 2; }
8284

8385
/* language switch button injected into the top menu bar */
8486
#okf-lang { font-weight: 700; }

‎book-en/src/README.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
<a class="okf-btn" href="./okf-manual-en.pdf">📄 Download PDF</a>
1010
<a class="okf-btn" href="./viz-example.html">🕸 See an example graph</a>
1111
</div>
12-
<div class="okf-cover-meta">by <strong>Supachai-ja</strong> · Updated <span id="okf-date">2026-06-15</span> · OKF v0.1</div>
12+
<div class="okf-cover-meta">Compiled by <strong>Supachai Jaturaprom [TumEz]</strong><br/>Written by Claude Code — Opus 4.8 (AI) · Updated <span id="okf-date">2026-06-15</span> · OKF v0.1</div>
1313
</div>
1414

1515
# Preface
@@ -23,13 +23,13 @@ with YAML frontmatter that both humans and AI agents can use, without any SDK or
2323
## Table of Contents
2424

2525
<div class="okf-toc-grid">
26-
<a class="okf-toc-card" href="./part1/what-is-okf.md"><span class="num">PART 1</span><span class="ttl">Meet OKF</span><span class="dsc">What OKF is, and why it beats classic RAG</span></a>
27-
<a class="okf-toc-card" href="./part2/install.md"><span class="num">PART 2</span><span class="ttl">Getting Started</span><span class="dsc">Install · first KB · project layout</span></a>
28-
<a class="okf-toc-card" href="./part3/concepts.md"><span class="num">PART 3</span><span class="ttl">Core Concepts</span><span class="dsc">concept · frontmatter · linking · reserved files</span></a>
29-
<a class="okf-toc-card" href="./part4/ingest.md"><span class="num">PART 4</span><span class="ttl">Everyday Operations</span><span class="dsc">ingest · query/search · authoring · validate/viz</span></a>
30-
<a class="okf-toc-card" href="./part5/best-practices.md"><span class="num">PART 5</span><span class="ttl">Authoring Well</span><span class="dsc">best practices and anti-patterns</span></a>
31-
<a class="okf-toc-card" href="./part6/architecture.md"><span class="num">PART 6</span><span class="ttl">Enterprise</span><span class="dsc">self-host · MCP · write models · security</span></a>
32-
<a class="okf-toc-card" href="./appendix/tools.md"><span class="num">APPENDIX</span><span class="ttl">Reference</span><span class="dsc">CLI reference · FAQ · glossary</span></a>
26+
<a class="okf-toc-card" href="./part1/what-is-okf.md"><svg class="ico" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="9"/><line x1="12" y1="11" x2="12" y2="16"/><line x1="12" y1="8" x2="12" y2="8"/></svg><span class="num">PART 1</span><span class="ttl">Meet OKF</span><span class="dsc">What OKF is · history · why it beats classic RAG</span></a>
27+
<a class="okf-toc-card" href="./part2/install.md"><svg class="ico" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polygon points="8 5 19 12 8 19 8 5"/></svg><span class="num">PART 2</span><span class="ttl">Getting Started</span><span class="dsc">Install · first KB · project layout</span></a>
28+
<a class="okf-toc-card" href="./part3/concepts.md"><svg class="ico" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 3l8 4.5v9L12 21l-8-4.5v-9z"/><path d="M12 12l8-4.5"/><path d="M12 12v9"/><path d="M12 12L4 7.5"/></svg><span class="num">PART 3</span><span class="ttl">Core Concepts</span><span class="dsc">concept · frontmatter · linking · reserved files</span></a>
29+
<a class="okf-toc-card" href="./part4/ingest.md"><svg class="ico" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="4" width="18" height="16" rx="2"/><path d="M7 9l3 3-3 3"/><line x1="13" y1="15" x2="17" y2="15"/></svg><span class="num">PART 4</span><span class="ttl">Everyday Operations</span><span class="dsc">ingest · query/search · authoring · validate/viz</span></a>
30+
<a class="okf-toc-card" href="./part5/best-practices.md"><svg class="ico" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M4 20l1-4L16 5l3 3L8 19z"/><line x1="14" y1="7" x2="17" y2="10"/></svg><span class="num">PART 5</span><span class="ttl">Authoring Well</span><span class="dsc">best practices and anti-patterns</span></a>
31+
<a class="okf-toc-card" href="./part6/architecture.md"><svg class="ico" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="4" width="18" height="7" rx="1.5"/><rect x="3" y="13" width="18" height="7" rx="1.5"/><line x1="7" y1="7.5" x2="7" y2="7.5"/><line x1="7" y1="16.5" x2="7" y2="16.5"/></svg><span class="num">PART 6</span><span class="ttl">Enterprise</span><span class="dsc">self-host · MCP · write models · security</span></a>
32+
<a class="okf-toc-card" href="./appendix/tools.md"><svg class="ico" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M6 4h12v16l-6-4-6 4z"/></svg><span class="num">APPENDIX</span><span class="ttl">Reference</span><span class="dsc">CLI reference · FAQ · glossary · bibliography</span></a>
3333
</div>
3434

3535
## Who this book is for

‎book-en/src/part6/architecture.md‎

Lines changed: 15 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -10,22 +10,21 @@ When a knowledge base must be shared **across sessions and teams at the enterpri
1010
1111
## Diagram
1212

13-
```
14-
┌─────────────── Internal Network ───────────────┐
15-
Team A ─┐ │ ┌──────────┐ pull / webhook │
16-
(agent) │ MCP │ │ Git server│◄──────────────┐ │
17-
Team B ─┼─────►│ │ (Gitea/ │ ┌────────────┴──────────┐ │
18-
(agent) │(HTTP/│ │ GitLab) │ │ OKF MCP server │ │
19-
CI/cron─┘ SSE +│ │ = OKF repo│ │ search · get · │ │
20-
token│ └─────┬─────┘ │ propose / commit │ │
21-
/mTLS)│ │ PR/MR │ (FastMCP) │ │
22-
│ ▼ └──────────┬────────────┘ │
23-
│ ┌──────────┐ builds │ search index │
24-
│ │ CI runner │ ▼ (BM25 +/- embed) │
25-
│ │ validate │ │
26-
│ └──────────┘ │
27-
└────────────────────────────────────────────────┘
28-
```
13+
<pre class="mermaid">
14+
flowchart TB
15+
subgraph net["Internal network (on-prem / air-gap)"]
16+
MCP["OKF MCP server<br/>search · get · propose / commit"]
17+
GIT["Git server (Gitea/GitLab)<br/>= OKF repo · source of truth"]
18+
IDX["Search index<br/>BM25 (+ semantic)"]
19+
CI["CI runner<br/>okf-validate + viz"]
20+
MCP -->|"pull / webhook"| GIT
21+
MCP --> IDX
22+
GIT -->|"PR/MR triggers"| CI
23+
end
24+
A1["Agent team A"] -->|"MCP: HTTP/SSE + token/mTLS"| MCP
25+
A2["Agent team B"] --> MCP
26+
CR["CI / cron"] --> MCP
27+
</pre>
2928

3029
## Components
3130

‎book-en/src/part6/write-models.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,16 @@ When multiple agents write knowledge concurrently, you must choose how to manage
1212
3. Opens a PR/MR via the git server API and returns the URL
1313
4. CI runs `okf-validate.py` (+ regenerates viz) → a human/curator reviews and merges
1414

15+
<pre class="mermaid">
16+
flowchart LR
17+
AG["Agent"] -->|propose_change| BR["branch + commit"]
18+
BR --> PR["Pull Request"]
19+
PR --> CIv["CI: okf-validate"]
20+
CIv --> RV["review (human/curator)"]
21+
RV -->|merge| MAIN["main"]
22+
MAIN -->|webhook| RE["MCP pull + reindex"]
23+
</pre>
24+
1525
Full enterprise properties: **audit trail** (git log), **review/diff**, **rollback** (git revert),
1626
**no write conflicts** (merges applied one at a time in order), **quality gate** (CI + review)
1727

@@ -32,6 +42,15 @@ okf_commit_concept("tables/orders", frontmatter, body, token=...) # server che
3242
okf_release_lease("tables/orders", token=...) # release when done
3343
```
3444

45+
<pre class="mermaid">
46+
flowchart LR
47+
ACQ["acquire_lease<br/>(TTL)"] --> ED["edit concept"]
48+
ED --> CM["commit_concept<br/>(verify token)"]
49+
CM --> PUSH["pull --rebase + push"]
50+
PUSH --> REL["release_lease"]
51+
OT["another agent requests the same concept"] -.->|locked| ACQ
52+
</pre>
53+
3554
Another agent requesting the same concept receives `{error:"locked", held_by}` → it works on something else instead.
3655
Concurrency safety: the lease prevents duplicate concepts + `git pull --rebase` before push handles
3756
commits to different files (auto-merge).

‎book/book.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[book]
22
title = "คู่มือ Open Knowledge Format (OKF)"
3-
authors = ["Supachai-ja"]
3+
authors = ["Supachai Jaturaprom [TumEz] (compiler)", "Claude Code — Opus 4.8 (AI, author)"]
44
description = "คู่มือผู้ใช้งานภาษาไทยสำหรับสร้างและดูแล knowledge base ด้วย Open Knowledge Format — ตั้งแต่เริ่มต้นจนถึงระดับองค์กร"
55
language = "th"
66
src = "src"

‎book/css/custom.css‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,8 @@
7979
}
8080
.okf-toc-card .ttl { display: block; font-weight: 700; color: var(--fg); margin-bottom: 0.2rem; }
8181
.okf-toc-card .dsc { display: block; font-size: 0.85rem; color: var(--sidebar-fg, #6b7280); line-height: 1.5; }
82+
.okf-toc-card svg.ico { width: 26px; height: 26px; color: #8b5cf6; display: block; margin-bottom: 0.45rem; }
83+
.okf-cover-meta br { line-height: 2; }
8284

8385
/* language switch button injected into the top menu bar */
8486
#okf-lang { font-weight: 700; }

‎book/src/README.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
<a class="okf-btn" href="./okf-manual-th.pdf">📄 ดาวน์โหลด PDF</a>
1010
<a class="okf-btn" href="./viz-example.html">🕸 ดู graph ตัวอย่าง</a>
1111
</div>
12-
<div class="okf-cover-meta">โดย <strong>Supachai-ja</strong> · ปรับปรุงล่าสุด <span id="okf-date">2026-06-15</span> · OKF v0.1</div>
12+
<div class="okf-cover-meta">เรียบเรียงโดย <strong>Supachai Jaturaprom [TumEz]</strong><br/>เขียนโดย Claude Code — Opus 4.8 (AI) · ปรับปรุง <span id="okf-date">2026-06-15</span> · OKF v0.1</div>
1313
</div>
1414

1515
# คำนำ
@@ -23,13 +23,13 @@
2323
## สารบัญ
2424

2525
<div class="okf-toc-grid">
26-
<a class="okf-toc-card" href="./part1/what-is-okf.md"><span class="num">ภาคที่ 1</span><span class="ttl">รู้จัก OKF</span><span class="dsc">OKF คืออะไร และทำไมถึงดีกว่า RAG แบบเดิม</span></a>
27-
<a class="okf-toc-card" href="./part2/install.md"><span class="num">ภาคที่ 2</span><span class="ttl">เริ่มต้นใช้งาน</span><span class="dsc">ติดตั้ง · สร้าง KB แรก · โครงสร้างโปรเจกต์</span></a>
28-
<a class="okf-toc-card" href="./part3/concepts.md"><span class="num">ภาคที่ 3</span><span class="ttl">แนวคิดหลัก</span><span class="dsc">concept · frontmatter · การลิงก์ · ไฟล์สงวน</span></a>
29-
<a class="okf-toc-card" href="./part4/ingest.md"><span class="num">ภาคที่ 4</span><span class="ttl">การใช้งานประจำวัน</span><span class="dsc">ingest · query/search · เขียน concept · validate/viz</span></a>
30-
<a class="okf-toc-card" href="./part5/best-practices.md"><span class="num">ภาคที่ 5</span><span class="ttl">เขียนให้ดี</span><span class="dsc">แนวทางการเขียนและ anti-patterns</span></a>
31-
<a class="okf-toc-card" href="./part6/architecture.md"><span class="num">ภาคที่ 6</span><span class="ttl">ระดับองค์กร</span><span class="dsc">self-host · MCP · write models · security</span></a>
32-
<a class="okf-toc-card" href="./appendix/tools.md"><span class="num">ภาคผนวก</span><span class="ttl">อ้างอิง</span><span class="dsc">CLI reference · FAQ · อภิธานศัพท์</span></a>
26+
<a class="okf-toc-card" href="./part1/what-is-okf.md"><svg class="ico" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="9"/><line x1="12" y1="11" x2="12" y2="16"/><line x1="12" y1="8" x2="12" y2="8"/></svg><span class="num">ภาคที่ 1</span><span class="ttl">รู้จัก OKF</span><span class="dsc">OKF คืออะไร · ประวัติศาสตร์ · ทำไมดีกว่า RAG</span></a>
27+
<a class="okf-toc-card" href="./part2/install.md"><svg class="ico" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polygon points="8 5 19 12 8 19 8 5"/></svg><span class="num">ภาคที่ 2</span><span class="ttl">เริ่มต้นใช้งาน</span><span class="dsc">ติดตั้ง · สร้าง KB แรก · โครงสร้างโปรเจกต์</span></a>
28+
<a class="okf-toc-card" href="./part3/concepts.md"><svg class="ico" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 3l8 4.5v9L12 21l-8-4.5v-9z"/><path d="M12 12l8-4.5"/><path d="M12 12v9"/><path d="M12 12L4 7.5"/></svg><span class="num">ภาคที่ 3</span><span class="ttl">แนวคิดหลัก</span><span class="dsc">concept · frontmatter · การลิงก์ · ไฟล์สงวน</span></a>
29+
<a class="okf-toc-card" href="./part4/ingest.md"><svg class="ico" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="4" width="18" height="16" rx="2"/><path d="M7 9l3 3-3 3"/><line x1="13" y1="15" x2="17" y2="15"/></svg><span class="num">ภาคที่ 4</span><span class="ttl">การใช้งานประจำวัน</span><span class="dsc">ingest · query/search · เขียน concept · validate/viz</span></a>
30+
<a class="okf-toc-card" href="./part5/best-practices.md"><svg class="ico" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M4 20l1-4L16 5l3 3L8 19z"/><line x1="14" y1="7" x2="17" y2="10"/></svg><span class="num">ภาคที่ 5</span><span class="ttl">เขียนให้ดี</span><span class="dsc">แนวทางการเขียนและ anti-patterns</span></a>
31+
<a class="okf-toc-card" href="./part6/architecture.md"><svg class="ico" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="4" width="18" height="7" rx="1.5"/><rect x="3" y="13" width="18" height="7" rx="1.5"/><line x1="7" y1="7.5" x2="7" y2="7.5"/><line x1="7" y1="16.5" x2="7" y2="16.5"/></svg><span class="num">ภาคที่ 6</span><span class="ttl">ระดับองค์กร</span><span class="dsc">self-host · MCP · write models · security</span></a>
32+
<a class="okf-toc-card" href="./appendix/tools.md"><svg class="ico" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M6 4h12v16l-6-4-6 4z"/></svg><span class="num">ภาคผนวก</span><span class="ttl">อ้างอิง</span><span class="dsc">CLI reference · FAQ · อภิธานศัพท์ · บรรณานุกรม</span></a>
3333
</div>
3434

3535
## หนังสือเล่มนี้เหมาะกับใคร

‎book/src/part6/architecture.md‎

Lines changed: 15 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -10,22 +10,21 @@
1010
1111
## แผนภาพ
1212

13-
```
14-
┌─────────────── เครือข่ายภายใน ────────────────┐
15-
ทีม A ─┐ │ ┌──────────┐ pull / webhook │
16-
(agent) │ MCP │ │ Git server│◄──────────────┐ │
17-
ทีม B ─┼─────►│ │ (Gitea/ │ ┌────────────┴──────────┐ │
18-
(agent) │(HTTP/│ │ GitLab) │ │ OKF MCP server │ │
19-
CI/cron─┘ SSE +│ │ = OKF repo│ │ search · get · │ │
20-
token│ └─────┬─────┘ │ propose / commit │ │
21-
/mTLS)│ │ PR/MR │ (FastMCP) │ │
22-
│ ▼ └──────────┬────────────┘ │
23-
│ ┌──────────┐ builds │ search index │
24-
│ │ CI runner │ ▼ (BM25 +/- embed) │
25-
│ │ validate │ │
26-
│ └──────────┘ │
27-
└────────────────────────────────────────────────┘
28-
```
13+
<pre class="mermaid">
14+
flowchart TB
15+
subgraph net["เครือข่ายภายใน (on-prem / air-gap)"]
16+
MCP["OKF MCP server<br/>search · get · propose / commit"]
17+
GIT["Git server (Gitea/GitLab)<br/>= OKF repo · ต้นทางความจริง"]
18+
IDX["Search index<br/>BM25 (+ semantic)"]
19+
CI["CI runner<br/>okf-validate + viz"]
20+
MCP -->|"pull / webhook"| GIT
21+
MCP --> IDX
22+
GIT -->|"PR/MR triggers"| CI
23+
end
24+
A1["Agent team A"] -->|"MCP: HTTP/SSE + token/mTLS"| MCP
25+
A2["Agent team B"] --> MCP
26+
CR["CI / cron"] --> MCP
27+
</pre>
2928

3029
## องค์ประกอบ
3130

0 commit comments

Comments
 (0)