[DISCUSS] Make Maka easier to understand: benchmark-first homepage and a clearer README

[Astro-Han]

Follow-up to #4307, with a concrete homepage prototype for feedback.

The problem: a newcomer should understand Maka before understanding our architecture

A useful point raised in our community discussion was: when evaluating an unfamiliar agent or ADE, he visits its website to quickly understand what it is, what it can do, and whether it fits his work. The current homepage does not make that clear enough. We also discussed how the README's abstract language makes the same first encounter harder.

A product screenshot or a short demonstration can explain more than another paragraph about the harness. At the same time, “it can fix a failing test” is now a common capability. We need both a recognizable product and evidence that helps someone choose it.

Proposal: lead with evidence, then show the product

The attached English-language prototype explores four sections:

1. Product identity + benchmark evidence. Say that Maka is an open-source agent workspace, provide a download entry, and show the nine-harness comparison immediately. Five report tabs let readers inspect other experiments, with the model, result, caveat and report link changing together.
2. A tangible workspace. Show a polished Astryx conversation and result-inspection demo. This is explicitly example data, not a live agent or a promise that every illustrated detail is already shipped.
3. How the product improves. Connect evaluation findings to engineering choices and technical reading, including the event log as the source of execution history.
4. A clear next step. Download and try Maka on your own work.

Evaluation-driven evolution, beyond one ranking

The nine-harness report is the default because it is our broadest published comparison in this set. But the story should be sustained evaluation, not one selected high score. The existing evaluation reports also include a four-harness comparison, Maka vs OpenCode, an Ollama Cloud 0731 comparison, and Maka vs Kimi Code on K3.

These are different experiments on Terminal-Bench 2.1, not five independent benchmarks or a directly comparable improvement curve. Model/provider conditions, repetitions, infrastructure gaps and recovery accounting matter. Reports and per-task results should remain close to the headline numbers. Benchmarks are necessary evidence, not a guarantee for every user's work; showing limitations and regressions is part of earning trust.

What changes in the README?

Use the same concrete product identity as the homepage. Lead with one sentence explaining Maka, a product image, a practical getting-started entry and a link to the evaluation evidence. Put architecture and terminology after that opening. The homepage can carry the visual narrative; the README should help a repository visitor understand and start using the project quickly.

Design and implementation direction

The prototype uses real Astryx templates and components: Side Gallery's composition, the AI Chat Conversation primitives, and native Table/ProgressBar/TabList elements. The website has its own responsive typography scale derived from Maka's theme; the embedded workspace retains the client's density. We keep Astro for the website. No Next.js migration is proposed.

This is a direction sketch, not a finished visual design or a replacement for the live site. Production work still needs bilingual copy, faithful product examples and the existing Apache/Incubator navigation and notices. References from the community, including Today.ai and agent/ADE websites, inform clarity and visual presentation rather than a request to copy their branding.

Feedback requested

• If you did not know Maka, would this first screen tell you what it is and give you a reason to continue?
• Is benchmark evidence the right first-screen emphasis? What product information is still missing?
• Which real workflow should replace the example demo to best represent Maka?
• What should the first few paragraphs of the README say, and which terms should move deeper?
• Where does the visual design still feel too empty, too dense, or unlike Maka?

AI assistance: Codex helped inspect the templates and reports, implement the prototype, capture the screenshot, and draft this discussion.

简体中文（含中文界面长图）

这是 #4307 的一个具体方案补充，想结合长图请大家一起讨论。

社区讨论中提到一个很重要的用户视角：面对一个不熟悉的 Agent / ADE，通常先看官网，希望快速知道“这是什么、有哪些核心能力、是不是自己需要的”。目前官网还不能很好地回答这些问题；我们也认为 README 的表达偏抽象，要求读者先理解理念，才看得到产品。

这版尝试把顺序改为：首屏看到产品定位和评测证据 → 看到实际工作台 → 理解评测怎样推动技术演进 → 下载试用。九臂比较默认展示，其余四份报告可以切换。它们是同一 Terminal-Bench 2.1 上的不同实验，不能当成五套 Benchmark，也不能连成能力增长曲线。比较条件、局限与逐题结果都应随成绩一起公开。

我们想表达的是“评测驱动演进”：不止公布一次好成绩，也公开发现了什么问题、做了什么改进、结果如何。Event Log 等架构创新和技术文章在这个基础上展开，让用户先理解价值，再理解实现。

README 则建议先给清楚的产品定义、产品图、上手入口和评测链接，再展开架构。官网和 README 应说同一种容易理解的语言。

长图是讨论原型，演示区已标明示例数据，视觉与文案仍待打磨。继续使用 Astro 和真正的 Astryx 组件；官网用适合阅读的字体比例，产品窗口保留客户端密度。

尤其想听大家反馈：第一眼是否看得懂？评测放首屏是否有吸引力？应该用哪个真实场景展示产品？README 哪些抽象表述最需要改？页面哪里还显得空、挤或不像 Maka？

[liuxiaocs7]

Thanks @Astro-Han — this is a valuable proposal and the diagnosis is spot on: a newcomer should understand what Maka is and whether it fits their work before our architecture. I also really appreciate the intellectual honesty (different experiments, not five benchmarks or a comparable curve; example data clearly labeled; showing limitations and regressions). That posture is itself trust-building for an incubating project.

I'm in favor of the direction. A few suggestions to de-risk and sharpen it:

1. Ship the README improvements first — they're a low-cost, high-leverage quick win. The README changes (one-sentence identity, product image, getting-started entry, link to evaluation evidence, architecture moved deeper) don't need to wait on the homepage redesign. Decoupling them lets us land value early and iterate the site separately.

2. On the first screen, lead with identity + a real product demo; keep benchmarks as strong supporting evidence just below. The stated goal is "what is it / is it for me," and a pass-rate table mostly answers "is it good." I'd open with a one-line positioning plus a tangible product view, then let the nine-harness comparison carry the evidence a scroll away. Benchmark-forward is powerful, but it may not be the thing that tells a stranger what Maka is.

3. Confirm ASF compliance for competitor comparisons before making them first-screen. Direct comparisons (Maka vs OpenCode, vs Kimi Code) on an official Apache (incubating) homepage touch trademark and "undue promotion" sensitivities. Worth aligning with the mentors on framing before this goes prominent — the eval reports themselves are fine; it's the comparison-forward presentation on the official site I'd check.

4. Assign an owner for keeping the eval tabs current. Five linked report tabs (model/result/caveat/report changing together) will rot if not updated each release, and a stale benchmark is worse than none. Naming who refreshes this per release keeps the first screen from becoming a liability.

5. Use real, reproducible captured sessions rather than an idealized example demo. This is the actual crux (your question "which real workflow should replace the example demo"). A polished mockup, even when labeled as example data, risks a first-run letdown if the real product looks different. A real, reproducible session that maps to the published eval work would double as evidence and product tour.

Happy to help on any of these — especially the README pass and sanity-checking that the eval numbers/tabs stay tied to the reports.

[2BAB]

I support making the product understandable before introducing the architecture, and the README improvements seem worth moving forward independently.

Reading the discussion, though, I still think the original question needs a clearer answer: What distinguishes Maka today, and what problems would give someone a reason to choose it? Benchmarks, product demos, and architecture articles can all help, but we first need to decide what product value they should communicate.

From the perspective of practical work, I would suggest organizing the story around three characteristics of Maka at its current stage.

1. Model neutrality: use the model that fits your work.

Maka provides the workspace and execution runtime while letting users choose models from different providers, local deployments, or compatible gateways.

This gives users a concrete choice to understand. We should explain supported integrations without implying that every model has identical capabilities or behavior.

2. Designed for long tasks: keep track of progress, decisions, and uncertainty.

The value of the event log, context management, and recovery mechanisms becomes clearer when connected to practical questions: Where did the task stop? Which results already exist? What is waiting for input? What can happen next after an interruption?

“Designed for long tasks” is a reasonable positioning, with reliability demonstrated through reproducible examples. Preserving history, restoring a pending interaction, and avoiding duplicate external effects are separate capabilities; each needs its own evidence.

3. Beyond coding: coordinate different kinds of work toward one deliverable.

For example:

Combine sales data, customer feedback, and competitor research into recommendations for the next quarter, then deliver an analysis spreadsheet and a presentation.

Research and data analysis can proceed in parallel. Synthesis depends on those results. A key decision may require user input. The final artifacts need to remain consistent with that decision.

This is where Agent Graph / DAG can become meaningful to users: coordinating dependencies, parallel work, handoffs, and result aggregation. Users should be able to see how Maka organizes the work without first learning the scheduling architecture.

Under this framing, products such as ChatGPT Work and WorkBuddy are useful product references alongside harness comparisons with Pi and others.

What this could mean for the homepage

A possible opening direction is:

Your choice of model. Complex work, coordinated.
Maka is an open-source agent workspace designed to coordinate tasks across tools, manage dependencies, and preserve the execution history of longer workflows.

I would pair this with a reproducible demonstration from the current product: parallel subtasks, a human decision, and results brought together. Showing how a changed requirement propagates into the final spreadsheet and presentation would make the benefit especially tangible.

Benchmarks should remain strong supporting evidence. A compact result and report link could sit near the opening, with the full comparisons below. To support the broader positioning, we should also evaluate workflows across files and tools, including output quality, elapsed time, cost, and required human intervention.

That would give the page a clearer sequence: what work users can delegate to Maka, how it handles that work, and what evidence supports the claims.

简体中文

我赞成先让新人理解产品，再展开架构；README 的改进也可以独立推进。

不过，读完上面的讨论，我觉得最初的问题还没有得到足够明确的回答：Maka 当前的产品特色到底是什么？用户遇到什么问题时，会有理由选择它？ 评测、产品演示和架构文章都有帮助，但我们需要先明确，它们要共同说明什么产品价值。

我想从实际工作中需要解决的问题出发，试着归纳当前阶段 Maka 的三个特点。

1. 模型中立：选择适合自己工作的模型。

Maka 提供工作台和执行运行时，用户可以选择不同供应商的模型、本地部署的模型或兼容网关。

这是一个具体、容易理解的选择权。介绍时应说明支持范围，同时避免让用户误以为所有模型的能力与行为都完全一致。

2. 为长程任务设计：管理进度、决定与不确定性。

Event Log、上下文管理和恢复机制的价值，可以对应到几个实际问题：任务停在哪里？哪些结果已经产生？哪些步骤还在等待输入？中断后，接下来可以做什么？

“为长程任务设计”可以作为定位，可靠性则通过可复现的案例来证明。保留历史、恢复待答交互、避免重复的外部操作，是不同层次的能力，需要分别提供证据。

3. Beyond coding：把不同类型的工作组织成完整交付。

例如：

结合销售数据、客户反馈和竞品资料，提出下一季度的产品建议，并交付分析表与汇报材料。

资料收集和数据分析可以并行，综合判断需要等待上游结果，关键方向可能需要用户选择，最后的成果需要与这个决定保持一致。

Agent Graph / DAG 的价值，就体现在依赖管理、并行工作、任务交接和结果汇总上。用户应该能直接看到 Maka 怎样组织工作，而不必先学习调度架构。

按这个方向，除了与 Pi 等 harness 做技术比较，ChatGPT Work、WorkBuddy 这类产品也值得作为产品定位的参照。

这对首页意味着什么

首屏可以尝试这样的方向：

用你选择的模型，协调完成复杂工作。
Maka 是一个开源 Agent 工作台，面向跨工具的任务编排、步骤之间的依赖管理，以及长程工作的执行历史保留。

旁边配一段当前产品可复现的真实任务演示，展示并行分工、人工决定和成果汇合。尤其可以展示：用户调整一个要求后，最终的分析表和汇报材料怎样一起更新。这会让价值更具体。

Benchmark 仍然是重要证据。首屏可以保留紧凑的成绩与报告入口，完整比较放在后面。要支撑更广泛的产品定位，还应该评测跨文件、跨工具的工作流程，包括交付质量、耗时、成本，以及需要多少次人工介入。

这样，页面的顺序会更清楚：用户可以把什么工作交给 Maka，它怎样处理这些工作，以及有哪些证据支持这些主张。