REST／JSON 是真相來源
/agent/v1 提供 capabilities、project、graph、context、proposal、batch、event 與 readback；CLI 與 MCP stdio 只是薄轉接器，不直接讀 SQLite。
開發者文件
用同一份受治理契約，把相容工具接到本機 GrowthMap。
這是進階整合參考。介面在 127.0.0.1 本機提供，不是公開雲端 API，也不代表任何具名 Agent 已有一鍵整合。
01 / 介面與共同語意
Context Packet
包含 target、ancestors、children／current work、decisions、constraints、risks、relations、revisions 與 snapshot digest，讓 Agent 知道正在處理哪一段。
02 / 授權與一致性
Grant scope
read／propose／write 可限制到 project、exact node 或 branch descendants，並可到期或撤銷；撤銷會讓待審提案失效。
Revision 與 409
寫入帶 expected project／entity revision；版本不同回 409。請重新取得 Context Packet，比較並協調後再送。
Atomic batch
同一批變更全成或全不成，避免只寫入一半。
Idempotency 與 receipt
相同 idempotency key 與相同請求可安全重試並取得同一 receipt；更換 payload 卻重用 key 會被拒絕。
03 / 經 repo contract 驗證的唯讀最小例子
CLI / HTTP
CLI 取得預設 context：python3 scripts/growthmap_agent.py context --token-file <OWNER_ONLY_TOKEN_FILE> --base-url http://127.0.0.1:8100/agent/v1 --target <PROJECT_NODE_UUID>。在 POSIX，token file 必須只有擁有者可讀寫。HTTP 可另帶 objective：GET /agent/v1/context/<PROJECT_NODE_UUID>?objective=read-only-context，並以 Authorization: Bearer <GRANT_TOKEN> header 傳送；token 不得放進 URL。
04 / 整合狀態與限制
目前可用
本機 REST／JSON v1、通用 CLI、MCP stdio、grant scope、人工審核、revision 409、atomic batch、idempotent receipt 與 readback。
仍是原型或規劃
Context Packet 已由執行中 API 回傳，但獨立 JSON Schema、完整範例、各工具指南與 conformance tests 尚未發布。
不包含的能力
沒有公開雲端 Agent API、雲端同步、多人即時工作區、Git 自動掃描、自動執行 Agent、filesystem／shell／部署／付款／憑證授權，也沒有具名工具的一鍵官方整合。