Knowledge Publisher — Runbook (v1)

Cách chạy Knowledge Publisher — công cụ biến tài liệu Markdown canonical thành trang Academy có thể xuất bản.
Thực thi KNOWLEDGE-PUBLISHING-SPEC.md v1.0. Chỉ là công cụ xuất bản — không phải Academy, không backend, không UI, không CMS.
Phiên bản: 1.0.0 · Ngày: 2026-07-06.

1. Là gì

scripts/publish-knowledge.mjs đọc một tài liệu Markdown canonical và sinh ra:

• Structured HTML — trang đã render (heading, bảng, blockquote, danh sách, code).
• Knowledge Card(s) — mỗi section ## → một card (một tài liệu ⇒ nhiều lesson).
• Navigation metadata — danh sách section + liên kết *Related Documents*.
• Breadcrumb — suy từ đường dẫn tài liệu.
• Lesson metadata — tiêu đề, nguồn, phiên bản, thời điểm sinh, owner, audience, status.

2. Yêu cầu

• Node.js (đã có sẵn trong dự án). Không cài thêm dependency — bộ chuyển Markdown→HTML tự chứa trong script.
• Chạy từ thư mục gốc repo (~/bng-booking-demo).

3. Chạy

# Mặc định (không cần chỉnh sửa gì) — xuất ra examples/published/<slug>/
node scripts/publish-knowledge.mjs docs/commercial/WHITE-LABEL-COMMERCIAL-PACKAGE.md

# Tuỳ chọn ghi đè metadata + thư mục ra:
node scripts/publish-knowledge.mjs docs/commercial/PILOT-PACKAGE.md \
  --audience Customer --status Approved --out examples/published

Xuất bản cả bộ Commercial Release v1.0:

for f in docs/commercial/WHITE-LABEL-COMMERCIAL-PACKAGE.md \
         docs/commercial/PRICING-STRATEGY.md \
         docs/commercial/DISCOVERY-PLAYBOOK.md \
         docs/commercial/PILOT-PACKAGE.md \
         docs/commercial/COMMERCIAL-PROPOSAL.md; do
  node scripts/publish-knowledge.mjs "$f"
done

4. Kết quả

Mỗi lần chạy tạo examples/published/<slug>/:

5. Mỗi trang luôn chứa (bắt buộc)

Panel metadata + thẻ <meta name="knowledge:*"> trên mỗi trang gồm 6 trường:

• Source document · Source version · Generated time · Owner · Audience · Status

6. Giá trị mặc định (không cần chỉnh source)

7. Bảo đảm chỉ-đọc

• Công cụ chỉ đọc tài liệu nguồn; chỉ ghi dưới thư mục --out (mặc định examples/published/).
• Không bao giờ sửa Markdown nguồn. (Kiểm chứng: mtime nguồn không đổi sau khi chạy.)

8. Đồng bộ phiên bản (spec §7)

• Mỗi card lưu source_version + source_hash lúc sinh. Khi tài liệu nguồn đổi (băm khác), chạy lại publisher → source_hash mới; so sánh với bản đã xuất bản cho biết trang nào cần tái sinh (stale).
• v1 sinh trạng thái current lúc tạo; việc so khớp tự động (đánh dấu stale/orphaned) là bước kế tiếp của cơ chế sync, không thuộc phạm vi công cụ v1.

9. Giới hạn v1 (ghi rõ, không giấu)

• Bộ chuyển Markdown bao đúng cú pháp bộ tài liệu canonical hiện dùng (heading, bảng GFM, blockquote, danh sách/checkbox, code, đậm, liên kết, ---). Cú pháp ngoài phạm vi này chưa xử lý.
• Slug tiếng Việt lược bỏ dấu (anchor xác định, không hoàn hảo tiếng Việt).
• learning_objectives là scaffolding suy từ tiêu đề section — không thêm tri thức nghiệp vụ mới.
• Công cụ không dựng site/điều hướng liên trang; đó là việc của Academy (ngoài phạm vi v1).

10. Change Log