Maka documentation

This page is the authority map for Maka documentation. Code and contract tests remain the final authority when documentation disagrees with the implementation.

Where information belongs

• Root and package READMEs describe stable product entry points, public seams, and local ownership.
• docs/ contains current cross-cutting architecture, security, product, and validation contracts.
• docs/blogs/ contains long-form explanations of Maka's design ideas; code and current contracts remain authoritative.
• GitHub issues and pull requests contain implementation plans, migration progress, and time-sensitive TODOs.
• docs/archive/ preserves completed plans and superseded material for historical context. Archived documents are not current implementation guidance.

Start here

• Backend architecture (中文)
• Desktop architecture
• Renderer architecture
• Evaluation kernel
• Runtime package
• Computer Use package
• UI package architecture
• Security policy

Blogs

• Log Is the Runtime: How Maka Uses an Append-Only Log to Manage Agent State and Context (中文)
• From Copy-on-Write to Mailboxes: Two Paths for Multi-Agent Scheduling (中文)
• From Stateless Functions to Agent Runtimes: The Serverless Scheduling Unit Is Growing (中文)

Current contracts

Runtime and Eval

• Deep Research durable workspace
• SessionTodo lifecycle
• Desktop message queue
• Work Board contract
• Work Board Phase 1 surface
• WorkHub domain language
• WorkHub Coordination Session ADR
• Runtime resume architecture (中文)
• Runtime Host architecture (中文)
• Peer Mesh architecture (中文)
• Remote Runtime Host setup (中文)
• Runtime resume extraction ledger
• Runtime resume Phase 3–4 implementation route
• Skill catalog policy
• Provider-hosted web search capability
• Agent Swarm
• Side Conversation
• Agent Graph stream scheduling (中文)
• IM 扫码接入 runtime architecture
• Backend architecture chapters

Computer use

• Foundation contract
• Model-loop foundation
• Evidence classes
• Provider evidence contract
• Host events contract

Frontend and validation

• Product design
• Frontend CSS governance (中文)
• Windows support baseline

Release operations

• CLI/TUI distribution contract
• CLI npm release (中文)

Security and privacy

• Workspace privacy context
• Runtime sandbox boundary

Historical material

• Runtime kernel extraction
• Runtime v2 architecture evolution
• Runtime v2 implementation notes
• DeepSeek Reasonix cost runtime design
• Documentation archive

Maintenance

• Add stable cross-cutting documentation to the closest section above.
• Put local architecture beside the code and link it from Start here.
• Keep progress and TODOs in issues or pull requests instead of copying them into stable documents.
• Move completed plans to docs/archive/; remove a document only after its unique references are updated or no longer needed.
• Prefer updating an existing authority over adding a parallel document.
• Keep PR follow-up records, incident investigations, and run logs in the pull request or docs/archive/, not as new current contracts. notes/ and docs/local/ are workspace-local scratch and stay untracked.
• Do not commit PR or issue screenshots under docs/. Attach temporary visual evidence on the GitHub thread; product hero/marketing images live under .github/assets/.