Add audience fit and use cases

Author: wimi321

README.md

@@ -11,8 +11,10 @@
 <p align="center">
   <a href="#quickstart"><strong>Quick Start</strong></a> ·
   <a href="#example-output"><strong>Example Output</strong></a> ·
+  <a href="#who-its-for"><strong>Who It's For</strong></a> ·
   <a href="#where-it-fits"><strong>Where It Fits</strong></a> ·
   <a href="./docs/bundle-format.md"><strong>Bundle Format</strong></a> ·
+  <a href="./docs/use-cases.md"><strong>Use Cases</strong></a> ·
   <a href="./docs/sample-benchmark-report.md"><strong>Sample Report</strong></a> ·
   <a href="./ROADMAP.md"><strong>Roadmap</strong></a>
 </p>
@@ -36,6 +38,19 @@ Reach for it when you want to:
 - compare outputs across tools and models
 - grow toward replay and benchmark workflows
 
+<a id="who-its-for"></a>
+
+## Who It's For
+
+![Task Bundle audience fit](./assets/audience-fit.svg)
+
+This tends to resonate most with:
+- agent builders who want durable task artifacts instead of loose transcripts
+- evaluation teams that want to grow into benchmark workflows gradually
+- teams comparing multiple coding tools on the same starting point
+
+For more concrete scenarios, see [docs/use-cases.md](./docs/use-cases.md).
+
 It is not:
 - an agent framework
 - a chat UI
@@ -160,6 +175,7 @@ See:
 - [docs/bundle-format.zh-CN.md](./docs/bundle-format.zh-CN.md)
 - [docs/design-decisions.md](./docs/design-decisions.md)
 - [docs/replay-contract.md](./docs/replay-contract.md)
+- [docs/use-cases.md](./docs/use-cases.md)
 
 ## Five-Minute Demo
 

README.zh-CN.md

@@ -11,8 +11,10 @@
 <p align="center">
   <a href="#quickstart"><strong>快速开始</strong></a> ·
   <a href="#example-output"><strong>示例输出</strong></a> ·
+  <a href="#who-its-for"><strong>适合谁用</strong></a> ·
   <a href="#where-it-fits"><strong>方案对比</strong></a> ·
   <a href="./docs/bundle-format.zh-CN.md"><strong>格式说明</strong></a> ·
+  <a href="./docs/use-cases.zh-CN.md"><strong>使用场景</strong></a> ·
   <a href="./docs/sample-benchmark-report.zh-CN.md"><strong>示例报告</strong></a> ·
   <a href="./ROADMAP.zh-CN.md"><strong>路线图</strong></a>
 </p>
@@ -36,6 +38,19 @@ Task Bundle 是一个 TypeScript + Node.js CLI，用来把一次编码任务打
 - 比较不同模型或工具在同一起点上的表现
 - 作为未来 replay / benchmark 工作流的基础层
 
+<a id="who-its-for"></a>
+
+## 适合谁用
+
+![Task Bundle audience fit](./assets/audience-fit.svg)
+
+它通常最能打动这几类人：
+- 想把任务结果保存成稳定制品的 agent 作者
+- 想一步步积累 benchmark 工作流的评测团队
+- 想在同一起点上比较多个 coding 工具的团队
+
+如果你想看更具体的落地方式，可以继续看 [docs/use-cases.zh-CN.md](./docs/use-cases.zh-CN.md)。
+
 它不打算解决这些问题：
 - agent 框架
 - 聊天 UI
@@ -160,6 +175,7 @@ task-bundle/
 - [docs/bundle-format.md](./docs/bundle-format.md)
 - [docs/design-decisions.md](./docs/design-decisions.md)
 - [docs/replay-contract.md](./docs/replay-contract.md)
+- [docs/use-cases.zh-CN.md](./docs/use-cases.zh-CN.md)
 
 ## 五分钟演示
 

assets/audience-fit.svg

@@ -8,6 +8,8 @@ This repository includes the visual assets used in the README and GitHub social
   Hero image used at the top of the README.
 - `assets/workflow-overview.svg`
   Workflow diagram used in the README.
+- `assets/audience-fit.svg`
+  Audience card graphic used to show which teams Task Bundle is for.
 - `assets/quick-demo.gif`
   Animated terminal walkthrough for the README quick start section.
 - `assets/terminal-showcase.svg`

docs/branding.md

@@ -8,6 +8,8 @@
   README 顶部使用的主视觉横幅。
 - `assets/workflow-overview.svg`
   README 中使用的工作流示意图。
+- `assets/audience-fit.svg`
+  README 中使用的受众卡片图，用来说明 Task Bundle 更适合哪些团队。
 - `assets/quick-demo.gif`
   README 快速开始部分使用的动图演示。
 - `assets/terminal-showcase.svg`

docs/branding.zh-CN.md

@@ -0,0 +1,59 @@
+# Use Cases
+
+Task Bundle is most useful when you already have real coding runs and want a lightweight way to keep them inspectable, comparable, and reusable.
+
+## 1. Save a run for later review
+
+If an AI coding session ends as a patch, transcript, and a half-remembered prompt, it is hard to revisit later.
+
+Task Bundle gives you a stable directory with:
+- the original task
+- a short summary
+- event history
+- the resulting diff
+- workspace files
+
+That makes it easier to review what happened a day or a month later.
+
+## 2. Compare tools on the same task
+
+If you want to compare Codex, Claude Code, Cursor, or an internal tool, you usually need more than screenshots.
+
+Task Bundle lets you keep:
+- tool and model metadata
+- artifact hashes
+- outcome fields such as status and score
+- a comparable workspace snapshot
+
+That gives `compare` and `report` something real to work with.
+
+## 3. Build a benchmark collection gradually
+
+Not every team wants to start by building a full benchmark platform.
+
+Task Bundle works well as an intermediate step:
+- package runs as they happen
+- keep them in one directory
+- scan and report over the collection later
+
+This is often enough to validate whether deeper benchmark tooling is even worth building.
+
+## 4. Hand tasks to another teammate or tool
+
+Sometimes the next step is not analysis. It is handoff.
+
+Because the task, artifacts, and workspace snapshot live together, another person or tool can pick up the same bundle and continue from a clearer starting point.
+
+## A Good Fit
+
+Task Bundle is a good fit if:
+- chat logs feel too loose
+- zip files feel too unstructured
+- a full eval platform feels too heavy
+
+## Not The Best Fit
+
+Task Bundle is probably not the right tool if:
+- you need a hosted benchmark product
+- you need a chat interface
+- you need token-perfect capture of every prompt and response

docs/use-cases.md

@@ -0,0 +1,61 @@
+# 使用场景
+
+Task Bundle 最适合这样的情况：你已经有真实的 AI coding 运行结果，但还不想一上来就搭完整平台，只想先把这些任务保存好、看得清、比得动、之后还能继续复用。
+
+## 1. 把一次运行保存下来，之后还能看懂
+
+很多 AI coding 任务最后只留下 patch、聊天记录和一点模糊印象，过几天再回头看就很难还原。
+
+Task Bundle 会把这些内容整理成一个稳定目录，里面通常包括：
+- 原始任务
+- 结果摘要
+- 关键事件
+- 最终 diff
+- 工作区文件
+
+这样后面再回看时，不用重新翻整段聊天记录。
+
+## 2. 比较不同工具在同一个任务上的表现
+
+如果你想比较 Codex、Claude Code、Cursor 或内部工具，光看截图通常不够。
+
+Task Bundle 会把这些比较真正需要的东西留住：
+- 工具和模型元数据
+- artifact 哈希
+- `status`、`score` 这类 outcome 字段
+- 可以一起对照的工作区快照
+
+这样 `compare` 和 `report` 才有真实内容可用。
+
+## 3. 先慢慢积累 benchmark 数据，再决定要不要上平台
+
+不是每个团队都适合一开始就做完整 benchmark 平台。
+
+Task Bundle 更像一个中间层：
+- 先把真实运行结果打包下来
+- 放进同一个目录里管理
+- 之后再做扫描、汇总和排行
+
+很多时候，这一步就足够帮助团队判断有没有必要继续往更重的评测系统走。
+
+## 4. 把任务交给下一个人或下一个工具
+
+有时候下一步不是分析，而是交接。
+
+任务描述、结果文件和工作区快照都在同一个 bundle 里，另一个人或另一个工具接手时，会比只给一段聊天记录清楚得多。
+
+## 适合什么情况
+
+如果你觉得：
+- 聊天记录太散
+- zip 文件太糙
+- 完整 eval 平台太重
+
+那 Task Bundle 通常会是一个合适的选择。
+
+## 不太适合什么情况
+
+如果你需要的是这些东西，Task Bundle 可能就不是最佳答案：
+- 托管式 benchmark 产品
+- 聊天界面
+- 对每一轮 prompt 和 response 做逐 token 级别的精确录制

docs/use-cases.zh-CN.md

@@ -31,6 +31,7 @@
     "dist",
     "examples",
     "docs",
+    "assets/audience-fit.svg",
     "assets/hero-banner.svg",
     "assets/quick-demo.gif",
     "assets/social-preview.svg",