[DISCUSS] Rebuild the Maka website and project narrative

[Astro-Han]

English

Supports #3404 (podling website publication) and #3272 (Incubator branding).

#3404 covers publication: where the source lives, how it builds, which branch .asf.yaml serves, and the minimum ASF-required pages. Its exit criteria are all checkable.

What the site should say is not. The last attempt shows the cost: maka-agent.github.io#1 has held the download, documentation, architecture, security, and releases pages since 12 August, waiting on design decisions that a PR is a poor place to make. Better to settle direction here, then write the work item.

Where we are

Three surfaces, three opening claims:

Surface	Opens with
README.md	"A local-first Agent workspace built for real work."
.asf.yaml description	"a local-first AI agent workspace" whose events "are recorded as an append-only log"
maka-agent.com	"An open source agent that turns intent into inspectable work."

Also:

• The homepage never says Apache Maka (Incubating) and carries no Incubator disclaimer. infra: publish the podling website at maka.apache.org #3404 requires both. The README has them.
• On main the site is one page: hero, a scripted tool-call demo, a first-run sequence. No downloads, documentation, community, or security. Those pages live only in the stalled draft.
• The README tells readers to build from source and recommends no prebuilt download, but npm nightly snapshots (PR feat(release): publish npm nightly snapshots #4131) and Desktop Nightly (PR ci: declare the Desktop Nightly environment #4260, PR test: make Desktop Nightly validation deterministic #4282) have since landed, and the badge row above that text advertises GitHub downloads and a Windows preview.
• Both READMEs run the same 18 sections in the same order, so any change has to hold in two languages.

Questions

1. What is Maka, in one sentence that the README, the homepage, and the repository description can all use? Today each writes its own.
2. What pages does the site need beyond the ASF minimum, and how do documentation, downloads, community, and security fit together? Should the Maka website provide a faster download path for Desktop Nightlies? #4301 asks whether the site becomes the main entry to Desktop Nightlies; leave room for that answer.
3. Full English and Chinese like the README, or translate a subset? Where is the boundary?
4. Which parts of the READMEs are stale rather than just long, and what should the README hand off once the site exists? It runs 290 lines and currently serves as landing page, install guide, and architecture summary.
5. Which existing assets, copy, fonts, and images do we keep? Anything reused has to clear legal: close incoming IP provenance for the first Apache release #3268 before entering an ASF repository. Anything rewritten does not.
6. What to do with the open design and content checklist in maka-agent.github.io#1.

Not here

• Publication mechanics: website/ layout, build workflow, publish branch, .asf.yaml. Those are infra: publish the podling website at maka.apache.org #3404 and are not waiting on this.
• README branding, which PR docs: identify the project as Apache Maka (Incubating) in both READMEs #3391 landed and docs: apply Apache Incubator branding to release surfaces #3272 tracks. This is about stale content.
• First-release artifact scope: [TRACKING] Apache Maka 0.2.0-incubating source release #2974.
• The future of maka-agent.com: infra: publish the podling website at maka.apache.org #3404.
• Nightly delivery: whether a website cache speeds up 150 MB installers, and what to do about installer size if it does not. Should the Maka website provide a faster download path for Desktop Nightlies? #4301 has that. The structure of the download page is a question here; how the bytes arrive is not.

AI use: I used Claude to review the three surfaces and draft this post. I checked the quoted lines and the cited policies, and I own it.

简体中文

支撑 #3404（podling 官网发布）与 #3272（孵化器品牌）。

#3404 覆盖发布链路：源码放哪、如何构建、.asf.yaml 发布哪个分支、以及 ASF 要求的最小页面集合。它的完成条件都可以核对。

官网该讲什么则不可核对。上一次尝试的代价已经看到了：maka-agent.github.io#1 自 8 月 12 日起装着下载、文档、架构、安全和 releases 页面，等的是一些不适合放在 PR 里做的设计决定。先在这里把方向定下来，再写工作项。

现状

三个界面，三种开场主张：

界面	开场表述
README.md	"A local-first Agent workspace built for real work."
.asf.yaml 仓库描述	"a local-first AI agent workspace"，其事件 "are recorded as an append-only log"
maka-agent.com	"An open source agent that turns intent into inspectable work."

另外：

• 首页从未出现 Apache Maka (Incubating)，也没有 Incubator disclaimer。infra: publish the podling website at maka.apache.org #3404 两者都要求。README 已经具备。
• main 上官网只有一页：hero、一段脚本化的 Tool Call 演示、首次运行流程。没有下载、文档、社区、安全。那些页面只存在于停滞的 draft 里。
• README 让读者从源码构建、不推荐任何预构建下载，但 npm nightly snapshots（PR feat(release): publish npm nightly snapshots #4131）和 Desktop Nightly（PR ci: declare the Desktop Nightly environment #4260、PR test: make Desktop Nightly validation deterministic #4282）此后已经合入，而这段文字上方的徽章行还在展示 GitHub downloads 和 Windows preview。
• 两份 README 是相同顺序的相同 18 个章节，任何改动都要在双语下同时成立。

问题

1. 用一句话说，Maka 是什么？这句话要让 README、首页和仓库描述都能用。今天三处各写各的。
2. 除 ASF 最小集合外官网还需要哪些页面，文档、下载、社区、安全之间怎么组织？Should the Maka website provide a faster download path for Desktop Nightlies? #4301 在问官网是否成为 Desktop Nightly 的主入口，给那个答案留出位置。
3. 像 README 那样中英完全并行，还是只翻译一个子集？边界划在哪？
4. 两份 README 里哪些是真过时，而不只是长？官网有了之后 README 该交出哪些职责？它现在 290 行，同时充当 landing page、安装指南和架构摘要。
5. 现有的设计资产、文案、字体和图片保留哪些？复用的部分进 ASF 仓库前要先过 legal: close incoming IP provenance for the first Apache release #3268，重写的不用。
6. maka-agent.github.io#1 里那份未了结的设计与内容清单怎么办。

不在这里

• 发布机制：website/ 布局、构建 workflow、发布分支、.asf.yaml。那些属于 infra: publish the podling website at maka.apache.org #3404，且不在等本讨论。
• README 的品牌标识，由 PR docs: identify the project as Apache Maka (Incubating) in both READMEs #3391 完成、docs: apply Apache Incubator branding to release surfaces #3272 跟踪。这里说的是过时的内容。
• 首次发版的 artifact 范围：[TRACKING] Apache Maka 0.2.0-incubating source release #2974。
• maka-agent.com 的去留：infra: publish the podling website at maka.apache.org #3404。
• Nightly 投递：官网缓存能否让 150 MB 安装包更快，以及如果不能，安装包体积该怎么办。那些在 Should the Maka website provide a faster download path for Desktop Nightlies? #4301。下载页的结构是这里的问题；字节如何送达不是。

AI 使用：我用 Claude 审阅了上述三个界面并起草本帖。引用的原文和政策我已核对，文责在我。

[yihanzhu]

English

Thanks for moving these decisions out of the implementation PR. I reviewed the current READMEs, the old website draft, the Nightly changes, the asset provenance notes, and several comparable agent harnesses. Here is one proposal covering all six questions.

1. One sentence for Maka

I suggest using this sentence unchanged in the README, homepage, and repository description:

Apache Maka (Incubating) is an agent workspace that helps you understand what the agent actually did, what remains uncertain, and what is safe to do next.

A supporting sentence can explain the mechanism:

Maka keeps tool calls, permission decisions, results, and interruptions in one shared execution history across Desktop and terminal, so the model's final answer is not the only thing you have to trust.

I would not lead with “real work,” “local-first,” or “inspectable history.” “Real work” is vague, while local execution, persistent sessions, compaction, branching, tool logs, and multiple interfaces are increasingly common. Codex has resume and handoff, Claude Code has persistent sessions and checkpoint/rewind, OpenCode V2 has a shared service and durable sessions, and Pi has persistent session trees and history-preserving compaction.

The more useful direction for Maka is to connect those execution facts to a user-visible outcome: what is confirmed, what failed or remains unfinished, what may have had an uncertain side effect, and what is safe to do next. Maka already has much of the recording foundation, but this outcome and recovery experience is not complete. Recovery should not imply universal rollback or verified completion.

In local dogfooding on 2026-08-29 against main@5d2df91, one task changed exactly one production file and an unchanged verifier separately reported verification passed; in an interrupted task, Bash failed, the expected file was absent, and Read confirmed the absence, yet the model said DONE and the Run was stored as completed. The website should describe the recorded facts, not turn “the model stopped” into “the work was verified.”

2. Site structure and downloads

Beyond the pages required by ASF policy, I would initially maintain one product homepage rather than a second documentation tree. It should contain:

• the positioning above;
• one reproducible journey available today: choose a project/model/permission boundary → request a concrete change → inspect tool results → inspect the diff and validation output → review the result with its evidence;
• a short, honest explanation of permission, cancellation, and recovery limits;
• a compact Get Maka block;
• links to the authoritative Docs, Security, Community, Releases, Roadmap, and Architecture locations.

The homepage provides orientation. Docs explains how Maka works, Security owns policy and reporting, Community owns participation and project decisions, and Releases owns downloadable artifacts and release history. The site should link to those sources rather than copy their contents.

So initially I would add no standalone product-owned pages beyond the homepage; Docs, Security, Community, Releases, Roadmap, and Architecture remain authoritative destinations linked from it.

The homepage should say “Review the result and its recorded evidence,” not “Verified complete.” An interruption/recovery principle can be explained in text, but it should not be shown as a product screenshot until the product can actually provide that experience.

The Get Maka block should keep three paths separate:

1. Try Desktop Nightly — the primary path for developers and testers for now. Link to GitHub Releases, and place “not an ASF release; may be unstable; not for production use” beside the action.
2. Build from source — link to the repository quick start.
3. Apache Releases — state clearly that Maka has not made one yet. Once an approved source release exists, it becomes the official release entry; installers and registry packages built from that approved source release are convenience artifacts.

The premise of #4301 changed after #4307 was opened: #4317 moved Desktop Nightlies from nightlies.apache.org to GitHub prereleases and the GitHub dev update channel. My answer to #4301's discovery question is still yes: the homepage should be the easiest place to find the Nightly, but it should remain an entry point, not a new artifact host. CTA order, names, warnings, and the distinction between Nightly, source builds, and Apache Releases belong here. Hosting, caching, updater feeds, installer size, and differential delivery remain #4301 delivery mechanics.

Versions, platforms, and support status should come from shared release/support data or linked documentation, not copied prose. The homepage should change for a release or a meaningful change in positioning, the primary journey, platform support, or the trust boundary—not for ordinary feature PRs.

3. English and Chinese

The product homepage should have complete /en/ and /zh-CN/ versions with the same sections, claims, warnings, and links. Dynamic version, download, platform, and support data should be shared rather than translated twice. This does not require every linked document to be translated: Docs can keep their own translation boundary, and English remains the authoritative language for Apache decisions and policies where required. The Chinese homepage should still be a complete product page, not a summary.

4. What the READMEs keep and hand off

I audited both root READMEs at main@064c3b2 (reviewed 2026-08-31): English and Chinese. They remain close bilingual peers. Most of their roughly 290 lines are not factually stale; they are too detailed, duplicated, and likely to change.

• Keep in README: ASF identity and disclaimer, the same one-line positioning, the shortest source-build path, a brief first-run note, CLI-package and authoritative-doc links, repository layout, essential contributor commands, Security/Contributing, and License. Keep a stable Nightly link and the statement that it is not an Apache release.
• Hand to the homepage: the hero, “Why Maka,” the real product journey, and the main download choices.
• Hand to versioned or package Docs: capability inventories; Peer/Electron workarounds; Graph, profile, and Eval details; the full architecture diagram; storage, migration, and resume internals; model-metadata instructions; and detailed test commands.
• Generate or link: current versions, downloads, platform badges, and the support matrix.

There are also concrete corrections to make. The current hero positioning should be replaced by the shared sentence above. “Runs can be aborted” is broader than the current cancellation guarantee; an abort request does not prove that an active tool stopped or that no side effect occurred. “Recovery” must be qualified as state convergence and optional resume, not universal rollback or verified completion. The project-level “Linux soon” badge is also misleading because it does not say Desktop while the Linux CLI path is already listed as validated; platform labels should be Desktop-specific or generated from the support matrix. The “source-build only” observation in #4307 is no longer current: the READMEs now include Desktop Nightly, and #4317 moved that Nightly to GitHub Releases.

5. Assets, copy, fonts, and images

#3268 is still open. It is an IP-evidence gate, not a blanket approval for website assets. The current code-origin audit provides useful provenance evidence, but evidence and final clearance are not the same thing.

Action	Concrete proposal
Carry forward for review	Subject to #3268/legal confirmation, use apps/desktop/assets/icon.png as the sole candidate source for the app mark rather than copying old-site icons. Geist and Geist Mono 5.3.0 can remain candidates if their OFL-1.1 licenses and notices travel with the site.
Regenerate	Generate favicon, manifest icons, and the OG card from that source. Capture all product screenshots again from the current dev build with a disposable project, and record commit, platform, and date.
Rewrite or drop	Rewrite homepage copy from current product, architecture, security, and release facts. Do not carry over the README hero images and “Your work. Your agent.” slogan, the July UI screenshots, the old OG image, or the scripted recovery demo.
Defer unless separately cleared	Pacifico, the generated letter paths, the 3D/WebGL wordmark, reference-derived layout/motion/shader work, old-site binaries, and GitHub attachment screenshots. At the reviewed revision, the old repository has no root LICENSE or NOTICE, and its reference study needs an independent provenance/legal review before any implementation is copied into an ASF repository.

This keeps the first site visually modest and reproducible. A real screenshot proves one observed build and journey; it does not prove that every task succeeds.

6. The stalled website draft and checklist

Treat maka-agent.github.io#1 as research and decision history, not as the implementation base.

Preserve and re-check its useful ideas: the unresolved checklist, ASF/compliance questions, verified factual links, machine-readable endpoints such as sitemap.xml, security.txt, JSON-LD and llms.txt, shared release-data generation, and automated link/metadata tests. Do not automatically inherit its page hierarchy, product positioning, public copy, scripted demo, or visual implementation.

After this discussion reaches consensus, copy the remaining actionable items into the new website work item, link that item and this decision from PR #1, and close the draft as superseded rather than deleting its history. Any old-site code or asset still proposed for reuse must first resolve its license, transfer, and provenance status.

Scope

This proposal deliberately does not decide publication mechanics (#3404), README branding (#3272), first-release artifact scope (#2974), the future of maka-agent.com (#3404), or Nightly delivery mechanics (#4301). It only decides the project narrative, information structure, language boundary, content ownership, and reuse policy needed before implementation.

In short:

Maintain one complete bilingual homepage, show a real user journey, make only claims supported by recorded results, and keep changing details in the sources that already own them.

AI use: I used OpenAI Codex to review current project files and official competitor documentation, run local dogfood checks, organize the question-by-question discussion, and consolidate this draft. I reviewed the conclusions and take responsibility for the submitted text.

简体中文

感谢把这些方向性问题从实现 PR 中单独拿出来讨论。我检查了当前 README、旧官网 Draft、Nightly 的最新变化、素材来源记录，也对比了几个相近的 Agent harness。下面的提案对应原帖的全部六个问题。

1. 用一句话介绍 Maka

我建议 README、官网首页和仓库描述统一使用这句话：

Apache Maka（孵化中）是一个 Agent 工作台，让你清楚知道 Agent 实际做了什么、还有哪些不确定，以及接下来怎样做更安全。

可以再用一句话解释它是怎样做到的：

Maka 会在桌面端和终端之间保留同一份执行记录，包括工具调用、权限决定、执行结果和中断信息，因此你不必只相信模型的最后一句话。

我不建议再用 “real work”“local-first” 或 “inspectable history” 作为主要定位。“Real work” 太模糊；本地运行、持久 Session、上下文压缩、分支、工具日志和多种交互入口，也越来越像 Agent harness 的常见能力。Codex 有 Session 恢复和 handoff，Claude Code 有持久 Session 和 checkpoint/rewind，OpenCode V2 有共享服务和持久 Session，Pi 有持久的 Session tree 和保留原始历史的上下文压缩。

对 Maka 更有价值的方向，是把这些执行事实连到用户真正关心的结果上：哪些已经确认，哪些失败或没有完成，哪些操作可能留下无法确认的副作用，以及接下来怎样做更安全。Maka 已经具备不少记录层基础，但这套结果与恢复体验还没有完成。“恢复”不能让人误以为 Maka 已经提供通用回滚，或者能自动证明任务已经完成。

我在 2026-08-29 对 main@5d2df91 做的本地 dogfood 测试正好暴露了这个缺口：一个任务只修改了一个生产文件，未改动的验证脚本另行输出 verification passed；另一个任务被中断后，Bash 失败、预期文件不存在，Read 也确认了文件缺失，但模型仍回答 DONE，Run 也被保存成 completed。官网应该说明系统记录下来的事实，而不能把“模型停了”写成“工作已经验证完成”。

2. 官网结构和下载入口

除了 ASF 政策要求的页面，我建议先只维护一个产品首页，不再复制出第二套文档结构。首页包含：

• 上面的核心定位；
• 一条今天就能复现的真实用户旅程：选择项目、模型和权限边界 → 提出一个具体修改 → 查看工具结果 → 检查 diff 和验证输出 → 把结果与证据放在一起审阅；
• 对权限、取消和恢复边界的简短、诚实说明；
• 一个紧凑的 开始使用 Maka 区块；
• 指向权威 Docs、Security、Community、Releases、Roadmap 和 Architecture 的链接。

首页负责说明方向和提供入口；Docs 解释 Maka 怎样工作，Security 负责安全政策和问题报告，Community 负责参与方式与项目决策，Releases 负责下载产物和发布历史。官网应该链接到这些权威来源，而不是复制它们的内容。

因此，第一阶段除了首页，不再增加由产品团队单独维护的页面；Docs、Security、Community、Releases、Roadmap 和 Architecture 继续作为权威入口，由首页链接过去。

首页应该写“审阅结果和记录下来的执行证据”，而不是“Verified complete”。中断和恢复的原则可以先用文字说明；在产品还不能真正提供这套体验之前，不应该把它画成产品截图。

开始使用 Maka 区块明确分开三条路径：

1. 试用 Desktop Nightly——目前的主要入口，面向开发者和测试者。链接到 GitHub Releases，并在入口旁直接写明“不是 ASF release，可能不稳定，不适合生产使用”。
2. 从源码构建——链接到仓库的快速开始说明。
3. Apache Releases——目前明确写 Maka 还没有 Apache release。将来获批的源码 release 出现后，它才成为正式 release 入口；由这份获批源码 release 构建的安装包和包管理器中的包属于 convenience artifacts。

#4307 发出后，#4301 的前提已经发生变化：#4317 把 Desktop Nightly 从 nightlies.apache.org 迁到了 GitHub prerelease 和 GitHub dev 更新渠道。对于 #4301 里“官网是否应该成为 Nightly 主要发现入口”的问题，我的答案仍然是肯定的，但官网只做入口，不做新的 artifact host。CTA 的顺序、名称、警示语，以及 Nightly、源码构建和 Apache Release 之间的区分属于本讨论；托管、缓存、更新 feed、安装包体积和差分投递仍属于 #4301 的交付机制。

版本、平台和支持状态应共用同一份发布与平台支持数据，或者链接到现有文档，不要复制进首页文案。官网只在 Release，或者核心定位、主要用户旅程、平台支持、信任边界发生重要变化时更新，不需要跟随普通功能 PR 更新。

3. 中英文边界

产品首页提供完整的 /en/ 和 /zh-CN/ 版本，两种语言拥有相同的章节、主张、警示语和链接。版本、下载、平台和支持状态等动态信息由两种语言共享，不分别维护。这不代表每一篇外链文档都必须翻译；Docs 可以继续使用自己的翻译边界，而 Apache 决策和政策在需要时仍以英文为权威来源。中文首页本身应该是一份完整产品页面，而不是英文版摘要。

4. README 保留什么、交出什么

我检查了 main@064c3b2（检查日期：2026-08-31）的两份根 README：英文版和中文版。两份 README 基本对等。约 290 行内容中，大多数并不是事实已经失效，而是太细、重复，而且很容易变化。

• README 保留： ASF 项目标识和 disclaimer、与官网完全相同的一句话定位、最短源码启动路径、简短的首次运行说明、CLI package 与权威文档链接、仓库结构、必要的贡献者命令、Security/Contributing 入口和 License。可以保留一个稳定的 Nightly 链接，以及“它不是 Apache release”的说明。
• 交给官网： Hero、“为什么选择 Maka”、真实产品旅程和主要下载选择。
• 交给版本化 Docs 或 package Docs： 能力清单；Peer/Electron workaround；Graph、profile 和 Eval 细节；完整架构图；存储、迁移和续跑内部机制；模型元数据说明；详细测试命令。
• 生成或链接： 当前版本、下载、平台徽章和支持矩阵。

还有几处需要直接修正。当前 Hero 定位应换成上面统一的一句话。“运行可以中止”比当前取消机制真正能保证的范围更宽；发出中止请求，并不能证明活跃工具已经停止，也不能证明没有产生副作用。“恢复”需要明确限定为状态收敛和可选续跑，不能暗示通用回滚或已经验证完成。项目级的 “Linux soon” badge 也容易误导：它没有说明这里指 Desktop，而 Linux CLI 路径已经被列为通过验证；平台标签应该明确写 Desktop，或者从 support matrix 生成。#4307 原帖中“README 只让用户从源码构建”的观察已经不再符合现状：当前 README 已加入 Desktop Nightly，#4317 又把这个 Nightly 迁到了 GitHub Releases。

5. 设计素材、文案、字体和图片

#3268 仍然是 Open 状态。它是 IP 证据的检查门槛，不等于已经一揽子批准官网素材。当前的代码来源审计提供了有用的来源证据，但“有证据”和“最终通过审查”不是一回事。

处理方式	具体建议
保留为待审候选	在通过 #3268/法律确认的前提下，把 apps/desktop/assets/icon.png 作为应用图标的唯一候选源文件，不复制旧站图标。Geist 和 Geist Mono 5.3.0 也可以保留为候选，但网站必须同时保留相应的 OFL-1.1 license 和 notices。
重新生成	从上述源文件重新生成 favicon、manifest icons 和 Open Graph 分享图。所有产品截图都用最新 dev build 和临时测试项目重拍，并记录 commit、平台和日期。
重写或放弃	首页文案根据当前产品、架构、安全和发布事实重写。不沿用 README Hero 图片与 “Your work. Your agent.” slogan、7 月旧 UI 截图、旧 OG 图和脚本化恢复 Demo。
单独审查前暂缓	Pacifico、生成的字形路径、3D/WebGL 字标、基于参考站点整理的布局、动效和 shader 实现、旧站的 PNG 等二进制素材，以及 GitHub attachment 截图。在本次检查的 revision中，旧仓库根目录没有 LICENSE 或 NOTICE；其中的视觉参考研究在任何实现进入 ASF 仓库前，都需要独立的来源和法律审查。

这样可以让第一版官网保持克制，也能重新生成。真实截图只能证明某个版本下的一次真实旅程，不能证明所有任务都会成功。

6. 停滞的旧官网 Draft 和清单

把 maka-agent.github.io#1 当作研究与决策历史，而不是新官网的实现基础。

保留并重新核对其中有价值的想法：未解决清单、ASF/合规问题、已经核实的事实链接、sitemap.xml、security.txt、JSON-LD、llms.txt 等机器可读入口、共享 release 数据生成，以及自动链接/metadata 测试。不要自动继承旧页面层级、产品定位、公开文案、脚本 Demo 或视觉实现。

本讨论形成共识后，把剩余可执行事项转到新的官网工作项，在 PR #1 中链接这个决定和新工作项，然后把旧 Draft 标记为已被取代并关闭，而不是删除历史。任何仍想复用的旧站代码或素材，都要先解决许可证、转移范围和来源审查问题。

讨论边界

这份提案不决定发布机制（#3404）、README 品牌标识（#3272）、首次 release 的 artifact 范围（#2974）、maka-agent.com 的去留（#3404），也不决定 Nightly 的交付机制（#4301）。它只回答实现前必须确定的项目叙事、信息结构、中英文边界、内容归属和复用规则。

总结成一句话：

维护一个完整的双语首页，用真实用户旅程说明 Maka，只做执行记录能够支持的公开承诺；经常变化的信息继续由原本负责维护它们的地方管理。

AI 使用说明：我使用 OpenAI Codex 检查当前项目文件和竞争产品的官方文档、进行本地 dogfood 测试、整理逐题讨论过程，并整合这份草稿。我已经审阅所有结论，并对最终提交内容负责。

[liuxiaocs7]

Thanks for the thorough proposal. I agree with the overall direction:

• maintain one complete bilingual product homepage;
• keep Docs, Security, Community, Releases, Roadmap, and Architecture as authoritative sources rather than duplicating them;
• clearly separate Desktop Nightly, source builds, and future Apache Releases;
• treat the old website PR as research history instead of the implementation base;
• reuse assets only after provenance and licensing are confirmed.

My main concern is the proposed one-sentence positioning. “What is safe to do next” may sound like a capability Maka can already determine, while the proposal also notes that this experience is not complete yet. I suggest using a more directly verifiable statement:

Apache Maka (Incubating) is an agent workspace that records tool calls, decisions, and results, helping you inspect what happened and decide what to do next.

This keeps the intended direction without implying verified completion, universal rollback, or a safety guarantee.

I also think we can add focused documentation to help users better understand Maka. The homepage can provide the high-level narrative and a concrete user journey, while the documentation explains concepts such as execution history, permission boundaries, interruption and recovery behavior, and how to interpret recorded results. This content should complement the homepage rather than duplicate it, with each topic maintained in its authoritative location.

[Astro-Han]

English

Thanks to both of you. @liuxiaocs7 — your objection to "what is safe to do next" is right, and I want to go further than adjusting the wording.

1. Positioning

Apache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.

And the sentence under it:

An agent harness exists to finish tasks. We hold it to one measure — how many it completes and what that costs — and we publish the results: a nine-harness leaderboard and head-to-head runs, each on the same model and the same official verifier, with the full per-task record in docs/eval/.

Two changes from the proposal, both from material that landed after you wrote it.

Performance belongs in the sentence. #3004 merged today: nine harnesses, DeepSeek V4 Flash, Terminal-Bench 2.1, the official verifier, 89 tasks. This is the one thing on the site no competitor can produce, and it is the thing a user actually chooses on. high-performance also has precedent across the foundation — SeaTunnel, Fury, and Gravitino all carry it in their one-liner.

But no numbers in the README. Scores move, everyone optimizes, and a number in prose goes stale silently. The README commits to the measure and to publishing; the numbers live in the reports and change there.

"What is safe to do next" stays out, because it is a goal we have not met. I checked the recovery path today. The classification is genuinely good — it separates definitely_not_dispatched from indeterminate from corruption, and an unproven tool boundary is refused replay in code rather than left to the model. Then all of it collapses into one error toast with no action, and one layer above that, ten distinct diagnostic codes are already flattened into a single rejection reason, so a tool that provably never ran is reported the same as one that may have had side effects.

That is #4423 and #4424. Your dogfood finding is the user-visible half of the same gap, and I would rather fix it than describe it. Once the product can actually tell you what is safe to do next, the sentence can say so.

2–6

Agreed as proposed. Three additions.

README (Q4). Beyond the handoff list, the README should gain a short architecture section, because it is the part a reader cannot get anywhere else: one Runtime Host owns execution and every client — Desktop, TUI, CLI, bots, eval — is thin; RuntimeEvent is the single canonical fact source and every surface is a projection of it. We took this direction from Google ADK and have built on it since the first commit; it is not a claim of novelty. One note on the OpenCode comparison: their shared service is on the v2 line and has not reached their main line. Maka has had a single owning Runtime Host since #1154, merged 17 July.

A correction to my own post. "The README tells readers to build from source and recommends no prebuilt download" is wrong — the README has carried a full Desktop Nightly section since #4260. @yihanzhu already caught this. The README needs updating for the other items in your Q4 audit regardless.

Benchmarks on the homepage (Q2). The leaderboard deserves a block of its own, linking to the reports rather than restating them. It fits your rule that the homepage changes for positioning, not for feature PRs — a new report is exactly that kind of change.

AI use: I used Claude to read the recovery code paths, verify the architecture claims against five other agent harnesses in source, and draft this reply. I checked the code citations and own the positions.

简体中文

谢谢两位。@liuxiaocs7 —— 你对 "what is safe to do next" 的质疑是对的，而且我想比改措辞走得更远一点。

1. 定位

Apache Maka（孵化中）是一个高性能的 Agent 工作台，并完整记录它做过的每一件事。

紧跟的一句：

Agent harness 存在的意义就是把任务做完。我们只用一个标准衡量它 —— 完成了多少，花了多少成本 —— 并且公开结果：一份九 harness 榜单和多次头对头实验，每一次都是同一个模型、同一套官方 verifier，逐任务记录都在 docs/eval/。

和提案相比有两处改动，都来自你们写完之后才落地的材料。

性能应该进这句话。 #3004 今天合并了：九个 harness、DeepSeek V4 Flash、Terminal-Bench 2.1、官方 verifier、89 个任务。这是官网上唯一一件竞品拿不出来的东西，也是用户真正据以选择的东西。high-performance 在基金会内也有先例 —— SeaTunnel、Fury、Gravitino 的一句话里都有。

但 README 里不写数字。分数会变，大家都在优化，写进散文里的数字会悄无声息地过时。README 承诺的是这个衡量标准和公开跑分本身，数字留在报告里，也在报告里更新。

"接下来怎样做更安全" 不进这句话，因为这是我们还没做到的目标。 我今天查了恢复路径。判定部分确实很好 —— 它把 definitely_not_dispatched、indeterminate、corruption 分得很清楚，无法证明终态的工具边界是由代码拒绝重放的，而不是交给模型自己判断。但这些判定最后全部收敛成一个没有任何操作的错误 toast；再上一层，十个不同的 diagnostic code 早就被压成了同一个拒绝原因，所以一个可证明从未执行的工具，和一个可能已经产生副作用的工具，对用户显示的是同一句话。

这就是 #4423 和 #4424。你的 dogfood 发现正是同一个缺口的用户侧那一半，我更想把它修掉而不是描述它。等产品真的能告诉你接下来怎样做更安全，这句话再这么写。

2–6

同意提案。三点补充。

README（第 4 问）。 除了交接清单之外，README 应该新增一节架构说明，因为这是读者在别处拿不到的部分：一个 Runtime Host 拥有执行权威，所有客户端 —— Desktop、TUI、CLI、bot、eval —— 都是薄客户端；RuntimeEvent 是唯一 canonical 事实源，每个界面都是它的投影。这个方向我们借鉴自 Google ADK，并从第一个提交起就这么建，不主张原创。关于 OpenCode 的对比补一句：他们的共享服务在 v2 线上，尚未进入主线；Maka 自 #1154（7 月 17 日合并）起就是单一 Runtime Host 拥有执行权威。

更正我自己原帖里的一处。 「README 让读者从源码构建、不推荐任何预构建下载」是错的 —— 自 #4260 起 README 就有完整的 Desktop Nightly 段落。@yihanzhu 已经指出来了。不管怎样，README 都需要按你第 4 问的审计结果更新。

跑分进首页（第 2 问）。 榜单值得单独一个板块，链接到报告而不是复述它们。这也符合你定的规则：首页为定位变化而更新，不为普通功能 PR 更新 —— 一份新报告正是这种变化。

AI 使用：我用 Claude 读了恢复相关代码路径、对照五个其他 agent harness 的源码核实了架构主张，并起草了本条回复。代码引用我已核对，观点文责在我。

[M4n5ter]

+1. I support the overall direction reached in this discussion and have no objection to proceeding with implementation under #3404. The separate IP-clearance and domain decisions can remain tracked in their existing scope.