Board ↔ Wiki, Skills & MCP

Đối tượng: knowledge role phối hợp với team Board; nhân sự dùng Claude với tri thức công ty. Điều kiện: đã quen Nạp tài liệu & duyệt Wiki.

Vòng đời tri thức gắn với Board

• Chiều Board đọc: server semantic-search Wiki của Department gắn Space → ghi .board/wiki/INDEX.md + tối đa 5 trang vào worktree trước khi agent chạy (deadline 8s, tắt bằng AGENTBOARD_WIKI_CONTEXT=0).
• Chiều Board ghi: wikiProposals trong result.json → ingest thành draft Arkon sau task complete → bạn duyệt ở Wiki Review như draft thường.
• Nạp tài liệu kiến trúc vào Wiki trước khi team chạy Planner — Planner tìm semantic search trên đó nên chất lượng plan tăng rõ rệt. Chi tiết phía Board: Wiki hai chiều.

Kiểm chứng nhanh phía Board: task đang chạy có .board/wiki/INDEX.md không rỗng (không phải "No wiki pages available"); sau task xong có draft mới trong Review Queue.

AI Skills — gói tri thức cho agent

• Upload gói skill (.zip có SKILL.md, versioned), phân phối theo department.
• Contributor đề xuất, reviewer duyệt (Approve & Merge / Reject).
• Theo dõi ở /skills: MyContributions (của bạn) / PendingContributions (chờ duyệt).

Danh tính thật & token persona (Chặng 0B)

• User tokens (AGENTBOARD_ARKON_USER_TOKENS=1): lời gọi Arkon mang email chính user — hết thời audit log ghi admin@arkon.local cho thao tác của người. User chưa xác thực không sinh token.
• Persona tokens (AGENTBOARD_ARKON_PERSONA_TOKENS=1): đề xuất wiki của agent ký @persona theo đúng task.persona (@architect / @coder / @reviewer / @qa / @devops). Tra nguồn gốc một trang ở wiki_draft_origins (persona, actor_id, run_id). Persona không tự duyệt draft của chính nó — kể cả draft nó vừa tạo.
• MCP per-run (AGENTBOARD_ARKON_MCP=1): credential bơm vào worktree lúc run, thu hồi sau run (kể cả khi agent lỗi).

Đừng nhầm token MCP với JWT SSO

Token MCP (POST /api/employees/{id}/token) chỉ dùng được ở /mcp/; đem gọi REST Arkon → 401. Đề xuất wiki của agent đi bằng JWT qua POST /api/auth/sso. Nhầm hai loại này làm mọi đề xuất wiki thất bại khi bật cờ.

MCP cho người dùng Claude

Nhân sự kết nối Claude Desktop / Claude.ai qua connector https://<arkon-host>/mcp (OAuth 2.1 + PKCE, không copy token tay). Tool agent được dùng theo scope token:

Nhóm	Tool
Wiki	search_wiki, read_wiki_page, list_wiki_pages
Drill-down nguồn	get_source, get_source_outline, get_source_pages, list_sources
Edit workflow	propose_wiki_edit, edit_wiki_page, list_pending_drafts, review_draft, approve_draft, reject_draft
Discovery	list_knowledge_types, get_knowledge_type_docs

MCP token cá nhân: tự phục vụ ở Profile → McpTokenCard; admin cấp/thu hồi ở Employees (POST/DELETE /api/employees/{id}/token). Đổi role/dept/revoke hiệu lực ngay (verify mỗi request, không cache).

Việc bạn KHÔNG làm được (và vì sao)

Bạn thử	Kết quả	Vì sao
Contributor duyệt draft / direct edit	bị chặn	Cần wiki:write:all (manager/admin)
Persona duyệt draft do chính nó đề xuất	bị chặn	Bất biến 0B: người đề xuất không tự duyệt
Đọc Wiki department khác	không thấy nội dung	Cô lập scope; admin mới thấy all

Không đổi model embedding sau khi đã nạp tài liệu

Vector khác số chiều sẽ làm hỏng search. Muốn đổi: chạy Online Re-embed Migration (admin, atomic flip, không downtime) và verify Diagnose #6 trước khi re-embed.

Checklist tự xác minh

• Biết khi nào gọi admin: đổi embedding model, re-index, cấp token, MRP kẹt, audit.denied tăng đột biến (Dashboard).
• Kết nối thử Claude qua /mcp và search_wiki ra trang trong dept mình; trang dept khác không lộ nội dung.

Gặp lỗi? Xem Xử lý sự cố.