diff --git a/README.md b/README.md
index 1c3867bea6..9633eb98b4 100644
--- a/README.md
+++ b/README.md
@@ -17,18 +17,34 @@
under the License.
-->
-# Apache Maka (Incubating)
-
-[](https://github.com/apache/maka/actions/workflows/ci.yml)
-[](./LICENSE)
-[](./README.zh-CN.md)
+
+ 
Apache Maka (Incubating)
+
+
+Incubating at The Apache Software Foundation
+
+
+ 
+ 
+ 
+ 
+ 
+ 
+
+
+
+ 简体中文
+
+
+
+ A local-first Agent workspace built for real work.
+ Maka inspects projects, runs tools under a sandbox boundary, and records
+ model messages and tool calls as recoverable execution facts — on your
+ machine, through one Runtime Host.
+
-**A local-first Agent workspace built for real work.**
-
-Maka does more than answer questions. With controlled permissions, it can inspect projects, execute tools, produce artifacts, and preserve model messages and tool calls as recoverable execution facts. Desktop, the terminal TUI, the non-interactive CLI, and Maka evaluation subjects all execute through Runtime Host.
-
> [!NOTE]
> Apache Maka (Incubating) is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator PMC. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision-making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF. [DISCLAIMER-WIP](./DISCLAIMER-WIP) records the issues the project is currently aware of.
@@ -37,12 +53,12 @@ Maka does more than answer questions. With controlled permissions, it can inspec
## Why Maka
-- **Local-first instead of hosted-first**: sessions, settings, and run records stay on your machine by default. You choose the model connection: cloud API, local model, or compatible gateway.
-- **Log is the Runtime**: model messages, Tool Calls, Tool Results, and termination facts enter Runtime Event Log. Sessions, UI, model context, and recovery are projections over that log.
-- **Context is not history**: Tool Result pruning and LLM Compaction change what the next inference sees without treating recorded evidence as disposable context.
-- **One execution authority**: Runtime Host owns Session, Turn, agent lifecycle, continuation, tools, and events. Eval owns only experiment semantics and results.
+- **Your machine, your data.** Sessions, settings, and run records stay local by default. You bring the model: a cloud API, a local model, or a compatible gateway.
+- **The record is kept.** Model messages, tool calls, tool results, and how a turn ended are written down. The UI and the next model call are views of that record, not the only copy.
+- **Shorter context is not deleted history.** Maka can omit old tool output from the next prompt without throwing away the saved evidence.
+- **One place runs the agent.** Desktop, the terminal, and Maka evaluation all go through Runtime Host. Eval only owns the experiment and its scores.
-Read [Maka Backend Architecture](./ARCHITECTURE.md) for the complete design.
+Read [Maka Backend Architecture](./ARCHITECTURE.md) for the design.
## Surfaces
@@ -56,17 +72,17 @@ Read [Maka Backend Architecture](./ARCHITECTURE.md) for the complete design.
### Agent Runtime
-- Multiple model connections, streaming output, thinking, usage accounting, and provider-error normalization;
-- Local tools including `Read`, `Write`, `Edit`, `Bash`, `Glob`, and `Grep`;
-- Tool schema validation, dynamic availability, permission policy, watchdogs, abort, and error classification;
-- Runtime Event Log, AgentRun ledger, startup recovery, Turn Evidence, active Tool Result pruning, and history compaction.
+- Multiple model connections, streaming output, thinking, usage, and clearer provider errors;
+- Built-in tools: `Read`, `Write`, `Edit`, `Bash`, `Glob`, `Grep`. Computer Use and catalog skills are optional and not on by default;
+- Tools that leave the sandbox must be approved; runs can be aborted; failures are classified;
+- A durable execution record, crash recovery, and optional resume of an interrupted turn.
### Desktop workspace
- Create, archive, search, rename, retry, regenerate, and branch sessions from a Turn;
-- Artifact lists and previews, workspace instructions, model settings, and permission settings;
-- Local memory, web search, and bot entry points;
-- Integrations are configured independently, and not every experimental entry is available by default.
+- Artifact lists and previews, workspace instructions, model settings, and sandbox settings;
+- Local memory and web search when configured;
+- Chat apps (IM bots) are experimental. See [IM onboarding](./docs/architecture/bot-onboarding-runtime.zh-CN.md).
### Evaluation
@@ -83,7 +99,7 @@ Apache Maka has not made an Apache release yet. Everything currently published f
Once Apache releases exist, the official release is the source release published by the ASF and approved by the podling PPMC and the Incubator PMC. A package built from that source and distributed elsewhere, for example through a package registry or as a Desktop installer, is a convenience artifact rather than the release itself, and it is valid only when it is built from an approved source release. [`.github/ASF_SOURCE_RELEASE.md`](./.github/ASF_SOURCE_RELEASE.md) holds the candidate contract, signing path, and verification steps.
-Until an approved source release exists, this README recommends no prebuilt download. Build and run Maka from source as described below. Desktop currently targets Apple Silicon Macs (`arm64`); Intel Macs and Linux are not supported yet, and [Windows support](docs/windows-support.md) remains an unsigned preview rather than a supported release tier.
+Until an approved source release exists, this README recommends no prebuilt download. Build and run Maka from source as described below. Desktop currently targets Apple Silicon Macs (`arm64`). Intel Macs and Linux are not supported yet. [Windows](docs/windows-support.md) is an unsigned preview, not a supported release tier.
### Requirements
@@ -187,9 +203,9 @@ docs/ Architecture, product, security, privacy, and test contracts
scripts/ Build hygiene, visual checks, smoke tests, and release helpers
```
-## Local data and security boundary
+## Local data and recovery
-Maka stores workspace data under Electron `userData` by default:
+Workspace data lives under Electron `userData` by default:
```text
/workspaces/default/
@@ -200,54 +216,12 @@ Maka stores workspace data under Electron `userData` by default:
artifacts/
```
-Current boundaries that matter:
-
-- The current connection catalog is `connection-catalog.json`. Existing `llm-connections.json` files stay on disk and are not imported;
-- Sessions, messages, execution ledgers, workflows, usage, Automations, and Daily Review live in `runtime.sqlite`;
-- Runtime Policy credentials, including Connection API/OAuth material, request headers, web-search keys, and proxy passwords, live in local plaintext `credential-vault.json`, behind the OS account boundary, with POSIX directory mode `0700` and file mode `0600` enforced;
-- Runtime Host client profile access credentials are separate and live under `/runtime-host-client/credentials.json`. Pre-existing Electron `safeStorage` credential/token files are not imported; affected users must re-authenticate;
-- Renderer does not receive plaintext credentials. File writes, Shell, and dangerous tool calls pass through the permission engine;
-- Eval does not construct Runtime or read Runtime storage. Maka subjects connect to an existing Runtime Host.
-
-Read [SECURITY.md](./SECURITY.md) for security reporting and policy, and [docs/README.md](./docs/README.md) for current privacy and sandbox contracts.
-
-## Runtime storage and recovery
-
-`runtime.sqlite` is the sole operational authority. It owns RuntimeEvents,
-session metadata and message history, Agent Graph control, core execution state,
-workflow state, usage and pricing, Artifact metadata, Automations, Daily Review,
-and Runtime continuation records. Artifact payload bytes remain regular files under
-`artifacts/`; connections, credentials, settings, MCP configuration, skills,
-and device identity remain configuration files.
-
-This storage generation does not import earlier File/JSONL authorities. On
-upgrade, legacy session titles may still be discoverable through current
-metadata, but conversation history that exists only in legacy transcript files
-is not copied into `session_messages` and opens as an empty thread. Likewise,
-pre-version or `safeStorage`-encrypted credential/token files are not migrated;
-users with only those copies must re-authenticate. This data-loss boundary is
-intentional for this release and must be considered before upgrading an
-existing workspace.
-
-Full operational backup uses the database owner's online SQLite backup API and
-copies canonical Artifact payloads under the Artifact writer lock. Its manifest
-binds every file by size and SHA-256. Validation checks the standalone SQLite
-snapshot's integrity, foreign keys, schema registry and required tables,
-decodes canonical session-message and Artifact records, and verifies Artifact
-payload sizes against SQLite metadata before restore. Backup and restore use
-owner-only file modes, file and directory synchronization, staging, and atomic
-publication.
-
-Runtime continuation remains opt-in:
-
-- `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1` enables the Desktop interrupted-turn
- **Safe resume** action, CLI/TUI `/resume`, and Desktop startup auto-resume.
- These paths may call the configured model provider and consume tokens. Enable
- the flag only when that behavior is explicitly desired.
-
-Phase 2 provides the durable write-side boundary and fail-closed safe-boundary
-continuation. Phase 3 reconciliation for indeterminate tool side effects is not
-implemented yet; ambiguous tool outcomes remain parked rather than retried.
+- API keys and similar secrets are a local plaintext file (`credential-vault.json`), readable only by your OS account. The renderer never sees them.
+- Tools that write files or run a shell must pass the sandbox boundary first.
+- `runtime.sqlite` is the live record. Older JSONL transcripts and Electron `safeStorage` credential files are not imported; an upgraded workspace can show empty threads, and those credentials must be entered again.
+- Resuming an interrupted turn is off by default. Set `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1` only if you want Desktop **Safe resume**, CLI `/resume`, and startup auto-resume — those calls hit the model and use tokens.
+
+Details: [SECURITY.md](./SECURITY.md), [privacy](./docs/workspace-privacy-context.md), [resume](./docs/architecture/runtime-resume-architecture.md).
## Development and verification
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 176a55a587..f43151dd6f 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -17,18 +17,32 @@
under the License.
-->
-# Apache Maka (Incubating)
-
-[](https://github.com/apache/maka/actions/workflows/ci.yml)
-[](./LICENSE)
-[](./README.md)
+
+ Apache Maka (Incubating)
+
+
+正在 Apache 软件基金会孵化
+
+
+
+
+
+
+
+
+
+
+
+ English
+
+
+
+ 一个为真实工作而生的本地优先 Agent 工作台。
+ Maka 在沙箱边界下阅读项目、执行工具，并把模型消息和工具调用保存为可恢复的运行事实——数据在本机，执行走同一个 Runtime Host。
+
-**一个为真实工作而生的本地优先 Agent 工作台。**
-
-Maka 不只回答问题。它可以在受控权限下阅读项目、执行工具、生成产物，并把模型消息和工具调用保存为可恢复的运行事实。桌面应用、终端 TUI、非交互 CLI 和 Maka 评测 subject 都通过 Runtime Host 执行。
-
> [!NOTE]
> Apache Maka (Incubating) 是一个正在 Apache 软件基金会（ASF）孵化的项目，由 Apache Incubator PMC 提供 sponsor。所有新接受的项目都必须经过孵化，直到进一步审查表明其基础设施、沟通方式和决策流程已经稳定到与其他成功的 ASF 项目一致的程度。孵化状态并不必然反映代码的完成度或稳定性，但它确实表明该项目尚未得到 ASF 的完全认可。项目当前已知的问题记录在 [DISCLAIMER-WIP](./DISCLAIMER-WIP)（以英文原文为准）。
@@ -37,10 +51,10 @@ Maka 不只回答问题。它可以在受控权限下阅读项目、执行工具
## 为什么是 Maka
-- **本地优先，而不是云端托管优先**：会话、设置和运行记录默认保存在本机；模型连接由你配置，可以使用云 API、本地模型或兼容网关。
-- **Log is the Runtime**：模型消息、Tool Call、Tool Result 和终止事实进入 Runtime Event Log，Session、UI、模型上下文和恢复逻辑从日志生成投影。
-- **上下文不是历史本身**：Tool Result prune 和 LLM Compaction 只改变下一次推理看到什么，不把已记录的证据当作上下文垃圾删除。
-- **唯一执行 authority**：Runtime Host 拥有 Session、Turn、agent lifecycle、continuation、tools 和 events；Eval 只拥有实验语义与结果。
+- **数据在你的机器上。** 会话、设置和运行记录默认保存在本机。模型由你接：云 API、本地模型或兼容网关。
+- **做过的事会留下来。** 模型消息、工具调用、工具结果、这一轮怎么结束，都会记下来。界面和下一次模型请求只是这份记录的视图，不是唯一副本。
+- **缩短上下文不等于删掉历史。** Maka 可以不把旧的工具输出送进下一轮提示，但不会扔掉已保存的证据。
+- **Agent 只在一处跑。** 桌面、终端和 Maka 评测都走 Runtime Host。Eval 只负责实验和分数。
完整设计见 [Maka Backend Architecture](./ARCHITECTURE.zh-CN.md)。
@@ -56,24 +70,24 @@ Maka 不只回答问题。它可以在受控权限下阅读项目、执行工具
### Agent Runtime
-- 多模型连接、流式输出、thinking、usage 和 provider error normalization；
-- `Read`、`Write`、`Edit`、`Bash`、`Glob`、`Grep` 等本地工具；
-- Tool schema validation、动态 availability、permission policy、watchdog、abort 和错误分类；
-- Runtime Event Log、AgentRun ledger、启动恢复、Turn Evidence、active tool prune 与 history compaction。
+- 多模型连接、流式输出、thinking、用量统计，以及更清楚的 provider 错误；
+- 内置工具：`Read`、`Write`、`Edit`、`Bash`、`Glob`、`Grep`。Computer Use 和目录里的 skill 是可选的，默认不开；
+- 越出沙箱的工具需要批准；运行可以中止；失败会被分类；
+- 有一份可恢复的执行记录，进程崩溃后可以收敛状态，中断的回合可以按需续跑。
### Desktop Workspace
- 会话创建、归档、搜索、重命名、重试、重新生成和从 Turn 分支；
-- Artifact 列表与预览、workspace instructions、模型与权限设置；
-- 本地记忆、联网搜索和机器人入口；
-- 不同集成需要单独配置，并非所有实验入口默认可用。
+- Artifact 列表与预览、工作区说明、模型和沙箱设置；
+- 配置后可使用本地记忆和联网搜索；
+- 聊天应用（IM bot）仍是实验能力，见 [IM 接入](./docs/architecture/bot-onboarding-runtime.zh-CN.md)。
### Evaluation
- 声明式多臂 Experiment 展开为 task × repetition × subject cell；
- 每个 cell 使用 immutable attempt，基础设施失败只替换该 cell，并选择最早有效 attempt；
- 通用结果只包含 score、normalized usage、可归因 cost、duration、status/failure reason 与 artifacts；
-- Maka subject 只通过 Runtime Host 执行，外部竞品使用 generic external subject adapter。
+- Maka subject 只通过 Runtime Host 执行，外部 subject 使用 generic external subject adapter。
## 快速开始
@@ -83,7 +97,7 @@ Apache Maka 目前还没有发布过 Apache release。当前从本仓库或包
在 Apache release 出现之后，官方 release 指的是由 ASF 发布、并经 podling PPMC 和 Incubator PMC 批准的源码 release。由该源码构建并通过其他渠道分发的包，例如包管理器中的包或 Desktop 安装程序，属于 convenience artifact，本身不是 release，并且只有在由获批源码 release 构建时才有效。候选契约、签名路径和验包步骤见 [`.github/ASF_SOURCE_RELEASE.md`](./.github/ASF_SOURCE_RELEASE.md)。
-在获批源码 release 出现之前，本 README 不推荐任何预构建下载，请按下文从源码构建并运行 Maka。Desktop 目前面向 Apple Silicon Mac（`arm64`），暂不支持 Intel Mac、Windows 和 Linux，[Windows 支持](docs/windows-support.md)仍属于未签名预览，不是正式支持的平台。
+在获批源码 release 出现之前，本 README 不推荐任何预构建下载，请按下文从源码构建并运行 Maka。Desktop 目前面向 Apple Silicon Mac（`arm64`）。暂不支持 Intel Mac 和 Linux。[Windows](docs/windows-support.md) 是未签名预览，不是正式支持的发布层级。
### 环境要求
@@ -186,9 +200,9 @@ docs/ 架构、产品、安全、隐私和测试契约
scripts/ Build hygiene、视觉检查、smoke 和 release helpers
```
-## 本地数据与安全边界
+## 本地数据与恢复
-Maka 默认把 workspace 数据放在 Electron `userData` 下：
+Workspace 数据默认放在 Electron `userData` 下：
```text
/workspaces/default/
@@ -199,50 +213,12 @@ Maka 默认把 workspace 数据放在 Electron `userData` 下：
artifacts/
```
-需要明确的当前边界：
-
-- 当前连接配置文件为 `connection-catalog.json`；已有的 `llm-connections.json` 不会被导入；
-- 会话、消息、执行 ledger、workflow、usage、Automations 和 Daily Review 都保存在 `runtime.sqlite`；
-- Runtime Policy 凭据（包括 Connection API/OAuth 信息、请求头、Web Search key 和代理密码）保存在本地 plaintext `credential-vault.json`，依赖 OS 账号边界，并在 POSIX 上强制目录 `0700`、文件 `0600`；
-- Runtime Host client profile 的访问凭据单独保存在 `/runtime-host-client/credentials.json`；历史 Electron `safeStorage` 凭据/token 文件不会被导入，仅保留这些历史副本的用户需要重新登录；
-- Renderer 不接收明文凭据；文件写入、Shell 和危险工具调用需要经过 permission engine；
-- Eval 不构造 Runtime，也不读取 Runtime storage；Maka subject 连接已有 Runtime Host。
-
-安全问题请阅读 [SECURITY.md](./SECURITY.md)，当前隐私和 sandbox contract 见 [docs/README.md](./docs/README.md)。
-
-## 运行时存储与恢复
-
-`runtime.sqlite` 是唯一的运行 authority。它拥有 RuntimeEvents、
-session 元数据和消息历史、Agent Graph 控制、核心执行状态、
-workflow 状态、usage 与定价、Artifact 元数据、Automations、Daily Review
-以及 Runtime continuation 记录。Artifact 的 payload 字节仍是 `artifacts/` 下的普通文件；
-connections、credentials、settings、MCP 配置、skills
-和 device identity 仍是配置文件。
-
-本存储代次不会导入更早的 File/JSONL authority。升级时，
-legacy session 标题仍可能通过当前元数据被发现，但仅存在于 legacy transcript
-文件中的会话历史不会被复制进 `session_messages`，打开时会显示为空会话。同样，
-pre-version 或 `safeStorage` 加密的 credential/token 文件不会被迁移；
-仅保留这些副本的用户必须重新认证。这一数据丢失边界是本版本的有意设计，
-升级既有 workspace 之前必须仔细考虑。
-
-完整运维备份使用数据库 owner 的 online SQLite backup API，并在 Artifact
-writer 锁下复制 canonical Artifact payload。其 manifest 以 size 和 SHA-256
-绑定每个文件。校验会在 restore 之前检查独立 SQLite snapshot 的完整性、
-foreign keys、schema registry 与必需表，解码 canonical session-message
-和 Artifact 记录，并对照 SQLite 元数据核对 Artifact payload 大小。备份与恢复
-使用 owner-only 文件权限、文件与目录同步、staging 以及原子发布。
-
-Runtime continuation 仍为显式开启：
-
-- `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1` 会开启 Desktop 中断回合的
- **安全恢复**（Safe resume）操作、CLI/TUI 的 `/resume` 以及 Desktop 启动时自动续跑。
- 这些路径都可能调用已配置的模型 provider 并消耗 token，
- 只应在你明确需要这一行为时开启。
-
-Phase 2 交付 durable 的写侧边界和 fail-closed 的 safe-boundary continuation。
-Phase 3 针对不确定工具副作用的 reconcile 尚未实现；结果不明的工具结果仍保持 park，
-不会被盲目重试。
+- API key 一类的秘密是本地明文文件（`credential-vault.json`），只有你的系统账号能读。界面进程拿不到明文。
+- 写文件、跑 Shell 的工具必须先过沙箱边界。
+- `runtime.sqlite` 是当前活记录。更早的 JSONL transcript 和 Electron `safeStorage` 凭据不会导入；升级后会话可能是空的，那些凭据需要重新填写。
+- 中断回合的续跑默认关闭。只有设置 `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1` 才会打开 Desktop **安全恢复**、CLI `/resume` 和启动时自动续跑——这些路径会打模型、消耗 token。
+
+细节见 [SECURITY.md](./SECURITY.md)、[隐私](./docs/workspace-privacy-context.md)、[续跑](./docs/architecture/runtime-resume-architecture.zh-CN.md)。
## 开发与验证
diff --git a/docs/windows-support.md b/docs/windows-support.md
index ec76288f9f..f0d33f4c4e 100644
--- a/docs/windows-support.md
+++ b/docs/windows-support.md
@@ -19,7 +19,7 @@
# Windows support baseline
-Windows is an active enablement target, not a fully supported Maka platform yet. The CLI and Electron desktop application can run from source, and release workflows produce a verified unsigned Windows x64 preview. The x64 package includes an AppContainer sandbox for restricted managed execution, and automatic updates are verified end to end in CI on the unsigned preview channel; signing, the complete adversarial sandbox matrix, and computer-use guarantees remain incomplete. Progress is tracked in [GitHub issue #2142](https://github.com/maka-agent/maka-agent/issues/2142).
+Windows is an active enablement target, not a fully supported Maka platform yet. The CLI and Electron desktop application can run from source, and release workflows produce a verified unsigned Windows x64 preview. The x64 package includes an AppContainer sandbox for restricted managed execution, and automatic updates are verified end to end in CI on the unsigned preview channel; signing, the complete adversarial sandbox matrix, and computer-use guarantees remain incomplete. Progress is tracked in [GitHub issue #2142](https://github.com/apache/maka/issues/2142).
## Install the Windows x64 preview