From 2543ddd5281be92a5a26be43b2ff214db28f28ed Mon Sep 17 00:00:00 2001
From: "Protocol Zero (v1.1 agent)" <agent@protocol-zero-0.dev>
Date: Sun, 17 May 2026 06:33:06 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20README=20hero=20=E2=80=94=20=E2=96=B6?=
 =?UTF-8?q?=20Try=20in=2010=20minutes=20+=20ASCII=20workflow=20(closes=20#?=
 =?UTF-8?q?33)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The first thing a stranger sees on the repo should be something they can
*run*. Insert a small hero block above "Motivation" / "动机":

1. ▶ Try in 10 minutes — 4-line shell snippet that drives
   `examples/quickstart/` to a real `evolution/accepted` commit in ~1
   second, $0, no API key. Links to the quickstart README and to
   examples/oss_fix_demo/ for the LLM-driven version.
2. How the loop works — a compact ASCII diagram showing
   Observe → Plan → Execute → Evaluate → accept/reject → ledger.
   Sits where a reader naturally lands after the call-to-action.

Both README.md and README.zh.md updated in parity. No prose rewritten;
the existing investor-narrative Motivation / SWE-bench worked-example
sections are intact below.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 README.md    | 35 +++++++++++++++++++++++++++++++++++
 README.zh.md | 35 +++++++++++++++++++++++++++++++++++
 2 files changed, 70 insertions(+)

diff --git a/README.md b/README.md
index d065d1e..2c2177d 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,41 @@
 
 ---
 
+> ### ▶ Try in 10 minutes
+>
+> ```bash
+> pip install -e . && pip install ruff
+> bash examples/quickstart/setup.sh
+> evolution-kernel \
+>   --config examples/quickstart/evolution.yml \
+>   --repo /tmp/ek-quickstart-target \
+>   --ledger /tmp/ek-quickstart-ledger \
+>   --loop
+> ```
+>
+> Closes the full loop in **~1 second**, **\$0**, **no API key**. See [examples/quickstart/](examples/quickstart/) for what just happened. For the LLM-driven version on a real OSS target, see [examples/oss_fix_demo/](examples/oss_fix_demo/).
+
+### How the loop works
+
+```
+   ┌─ Observe ─┐    ┌─ Plan ─┐    ┌─ Execute ─┐    ┌─ Evaluate ─┐
+   │  metrics  │ →  │  LLM   │ →  │ worktree  │ →  │   re-run   │
+   │ ruff/test │    │ + hist │    │  + agent  │    │   metric   │
+   └─────┬─────┘    └────────┘    └─────┬─────┘    └──────┬─────┘
+         │                              │                  │
+         │            ┌─────────────────┴──────────────────┘
+         │            ▼
+         │     ✅ accept → real git commit on evolution/accepted
+         │     ❌ reject → worktree discarded, experiment branch kept for audit
+         │            │
+         └────────────┴────► ledger: goal · obs · plan · diff · eval · decision · reflection
+                                       (every step replayable, every change rollback-able)
+```
+
+Each pass writes a complete forensic record to `runs/<id>/`. Nothing the kernel decides is held in memory; everything is reconstructable from the ledger alone.
+
+---
+
 ## Motivation
 
 Frontier-class agent behavior is the joint product of *the model* and *the harness that runs it* — prompt structure, tool loop, sampling and best-of-N, verifier, retry policy. Today that harness is hand-tuned by senior engineers at every serious AI lab, and the resulting code is usually the actual ceiling against which the base model is judged.
diff --git a/README.zh.md b/README.zh.md
index 00ed511..2355177 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -31,6 +31,41 @@
 
 ---
 
+> ### ▶ 10 分钟跑通
+>
+> ```bash
+> pip install -e . && pip install ruff
+> bash examples/quickstart/setup.sh
+> evolution-kernel \
+>   --config examples/quickstart/evolution.yml \
+>   --repo /tmp/ek-quickstart-target \
+>   --ledger /tmp/ek-quickstart-ledger \
+>   --loop
+> ```
+>
+> 整个闭环 **~1 秒** 跑完，**\$0**，**无需 API key**。详见 [examples/quickstart/](examples/quickstart/)。需要 LLM 驱动的真实 OSS 修复案例，见 [examples/oss_fix_demo/](examples/oss_fix_demo/)。
+
+### 闭环工作流
+
+```
+   ┌─ Observe ─┐    ┌─ Plan ─┐    ┌─ Execute ─┐    ┌─ Evaluate ─┐
+   │   指标     │ →  │ LLM +  │ →  │ worktree  │ →  │ 重跑指标   │
+   │ ruff/test │    │ 历史   │    │ + agent   │    │            │
+   └─────┬─────┘    └────────┘    └─────┬─────┘    └──────┬─────┘
+         │                              │                  │
+         │            ┌─────────────────┴──────────────────┘
+         │            ▼
+         │     ✅ accept → evolution/accepted 上的真实 git commit
+         │     ❌ reject → worktree 销毁，实验分支保留供审计
+         │            │
+         └────────────┴────► ledger: goal · obs · plan · diff · eval · decision · reflection
+                                      （每一步可重放，每个变更可回滚）
+```
+
+每一轮都把完整的取证记录写进 `runs/<id>/`。内核不在内存里保留任何决策状态，所有信息都能从 ledger 重建。
+
+---
+
 ## 动机
 
 旗舰级 agent 能力是 *模型* 和 *运行它的 harness* 的联合产出——prompt 结构、工具循环、采样和 best-of-N、验证器、重试策略。今天这套 harness 在每家严肃的 AI 实验室都靠资深工程师手调，最终结果通常就是评判基座模型时实际的能力上限。