peaks-loop 4.0.0-beta.7 → 4.0.0-beta.8

package/README.md

@@ -1,106 +1,227 @@
-# Peaks Loop
+<div align="center">
 
-[English](./README-en.md) | **简体中文**
+# peaks-loop
 
-[![npm](https://img.shields.io/npm/v/peaks-loop?style=flat-square&logo=npm)](https://www.npmjs.com/package/peaks-loop)
-[![license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](./LICENSE)
-[![stars](https://img.shields.io/github/stars/SquabbyZ/peaks-loop?style=flat-square&logo=github)](https://github.com/SquabbyZ/peaks-loop/stargazers)
+### 你说话,它替你跑完一整条工程流水线 —— 不止写代码,跑两次就沉淀成本地战术。
+
+[![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop)
+[![license](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](./LICENSE)
+[![node](https://img.shields.io/badge/node-%E2%89%A520-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://www.npmjs.com/package/peaks-loop)
+[![tests](https://img.shields.io/badge/tests-5%2C439%20passed-22c55e?style=for-the-badge&logo=vitest&logoColor=white)](#status)
+[![stars](https://img.shields.io/github/stars/SquabbyZ/peaks-loop?style=for-the-badge&logo=github&logoColor=white)](https://github.com/SquabbyZ/peaks-loop/stargazers)
+
+[English](./README-en.md) · **简体中文**
+
+</div>
 
 <p align="center">
-  <a href="https://raw.githubusercontent.com/SquabbyZ/peaks-loop/main/examples/video-demo/preview/peaks-loop-demo.mp4">
-    <img src="https://raw.githubusercontent.com/SquabbyZ/peaks-loop/main/examples/video-demo/out/zh-closing-960.png" alt="peaks-loop demo (点击播放)" width="100%" style="border-radius: 12px; box-shadow: 0 12px 40px rgba(0,0,0,0.55);">
-  </a>
+  <img
+    src="https://raw.githubusercontent.com/SquabbyZ/peaks-loop/main/examples/video-demo/preview/peaks-loop-demo.gif"
+    alt="peaks-loop 30 秒演示(前 18 秒 · install + 斜杠命令 + 5 域 + 沉淀成 bee)"
+    width="92%"
+    style="border-radius: 14px; box-shadow: 0 12px 40px rgba(0,0,0,0.55); display: block;"
+  />
   <br>
-  <sub>👆 点击图片播放 60s 演示</sub>
+  <sub>👆 18s 循环 GIF(<a href="https://raw.githubusercontent.com/SquabbyZ/peaks-loop/main/examples/video-demo/preview/peaks-loop-demo.mp4">完整 30s mp4 下载</a> · 13MB · 480p)</sub>
 </p>
 
+---
+
 ## 它是什么
 
-### loop engineering 的工程实现
+peaks-loop 是一个 **Loop Engineering 结晶系统**,不是工作流工具 —— 你跑过的工作里,沉淀下来的不是「流程」,是一套**可被 karpathy 风格工程化、又被 darwin 风格独立验证**的 Loop Engineering 方法资产。**Loop engineering 结晶系统** 的工程实现见 [`docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md`](./docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md)。
 
-**peaks-loop 是你的 Loop Engineering 结晶系统 —— 不是工作流工具。** 它从真实完成的工作里把 loop engineering 资产结晶出来,只通过被验证的改进让它们进化。你只用自然语言和选择操作系统,所有结构化操作由 LLM 代办。
+| 资产层 | 角色 | 一句话 |
+| --- | --- | --- |
+| **Loop Engineering 资产** | 方法系统,一等公民 | 回答「为什么有这条 loop、何时触发、怎样算成功、如何改进」 |
+| **Bee 资产** | 可执行体,一等公民 | Loop Engineering 资产的可执行体,蜂群里的每只 bee |
+| **Workflow Trace (执行轨迹)** | 证据,**不是**主资产 | 不可变的单次执行记录,供结晶与评估反查,不是用户对外的产品 |
+| **Evolution Evaluation (反漂移)** | 反漂移闸门,强制项 | 每次改进都要有独立上下文的评估者 + 反方怀疑者,过了才留,不过就回滚 |
 
-产品遵循四层资产模型与 karpathy × darwin 双层纪律,两者缺一不可:
+- **工程化每条规则 = karpathy 风格 · 验证每次改进 = darwin 风格** —— 两条缺一不可。砍掉 karpathy,原则没人写清;砍掉 darwin,改得对不对没人验。这一对是 co-equal 的双层结构,不是先后两步。
+- `/peaks-code` 是 **code-domain** 长任务 Loop Engineering 编排器,不是通用编排器;非代码域(`peaks-content` / `peaks-doctor` / `peaks-issue-fix-orchestrator` / `peaks-sop`)都是独立的 `peaks-*` 蜂,不是 `peaks-code` 的子类。
+- 跑两次稳定就沉淀成本地战术(bee);跑翻车的会让你重定义。bee 跟着你的口味长。
 
-- **四层资产模型**:Loop Engineering 资产(方法体系,一等公民)+ Bee 资产(可执行体,一等公民)+ Workflow Trace(执行轨迹,只作证据,不作资产)+ Evolution Evaluation(反漂移闸门,变更必经)。
-- **karpathy × darwin 双层纪律**:karpathy 工程化每一条规则(failure modes + imperative→declarative rewrite + self-check + out-of-scope);darwin 校验每一次改进(单对象 + 单维度 + 独立上下文评估 + ratchet 防回退)。两层是平行的伙伴,谁都不是谁的子集 —— 详见 `.peaks/standards/loop-engineering-guidelines.md` 与上游参考 `multica-ai/andrej-karpathy-skills`、`alchaincyf/darwin-skill`。
-- **post-run crystallization**:`loop_release` 与 `bee_release` 只在一次真实任务跑完后才写入;pre-run 永远是 scratch。沉淀触发支持四种,user explicit 优先级最高。
-- **Human-NL-Choice-Only**:你只说话或选择,LLM 替你跑 CLI;禁止手写 JSON / manifest / form field。
+---
 
-### peaks-code 是 code-domain 唯一的入口
+## 30 秒上手
 
-`peaks-code` 是 loop engineering 在 **代码域** 的长任务编排器,管 PRD、RD、QA、UI、SC、TXT 这一长串工序的主调度,也是你日常跟 peaks-loop 说话时最常打交道的那个角色。它**不是通用编排器** —— 研究 / 内容 / 产品等其他域各自是独立的 `peaks-*` 技能,复用同一份 Loop Engineering 准则。详见 Loop Engineering 设计 `docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md` §0.4 + RL-8,以及 sediment 设计 `docs/superpowers/specs/2026-07-04-peaks-maker-dynamic-skill-sediment-design.md`。
+```bash
+npm i -g peaks-loop
+```
 
-召之即来,事完收队,**不跳步,不半截扔给你**。它不是新发明一个 AI CLI,而是架在你已有的 Claude Code / Codex / Copilot 之上,把它们都调成同一支团队,只对你这一个开发者的口味。
+装好之后,在你已经用的 **Claude Code** 或 **Z Code** 对话框里发一条**显式命令**(必须以斜杠开头,才会触发 peaks-loop):
 
-### peaks-solo 是分诊员(新增,4.0.0-beta.5)
+```
+/peaks-code 帮我熟悉下当前的项目
+```
 
-如果**你不知道该用哪个 peaks-* 技能**,直接用 `/peaks-solo` 描述你的诉求就行。它会替你分诊:有合适的 leaf 就透明转交,没合适的就自己规划 + 跑(deep-search / WebSearch / Bash / Edit markdown),跑完回头问你要不要沉淀。`/peaks-code` / `/peaks-content` / `/peaks-doctor` 等老入口照常可用,**0 breaking**。
+剩下的就交给 peaks-loop —— 它会按这条命令的语义判断该走哪一域,用对应的编排器拆工序,一道门一道门跑,**坏在哪道停在哪道**,中间不会扔半截给你。
 
-**每一步都有强退出条件**:审计不通过就停,QA 没过就停,任何一道门失败 = 全流程停。你不必追着它催、也不必替它补,它跑完一道再交你拍板,拍完再走下一道。
+其他常用的显式命令:
 
-#### 门禁不是装饰 —— 5439 tests passed · 19 skipped · 0 failed
+```
+/peaks-content                 帮我把今天这篇推文写完发出
+/peaks-doctor                  帮我体检一下这个仓库
+/peaks-issue-fix-orchestrator  帮我把 upstream 的 30 个 open issue 修一批
+/peaks-sop                     帮我把团队的发布流程沉淀成 SOP
+/peaks-solo                    这套打法以后还会用,沉淀成本地战术
+/peaks-solo                    按上次那样再跑一次
+```
 
-每一行代码都过自己的门:测试套件 5,420 个用例真挡得住事,不是装饰。门禁不是写给用户看的,是写给自己看的。
+<sub>📦 其他 AI 编程工具适配中,欢迎共建 → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues) 提适配请求 / PR。</sub>
 
-#### 做这个项目的只有一个人,工程师口味:
+不需要记 CLI、不需要写 manifest、不需要切到第二个终端。**斜杠命令一发,后面的活它替你跑完。**
 
-- **极客精神。**
-- **你跟 AI 之间只该用自然语言讲话,没有 CLI 表面给你。**
-- **单测覆盖率和门禁审计真挡得住事,不是装饰。**
-- **严于律己,宽以待人 —— 自己写的代码过自己的门,使用者随便怎么说都能跑通。**
-- **AI 使用水平的下限平权:你不需要懂 prompt engineering,就跟说话一样用。**
+---
 
-这套项目级硬规则也写进了 `~/.peaks/memory/`,不是口号,是被工具链守住的红线。
+## 它能为你做什么
 
-## 装了你有什么战术角色
+代码、内容、项目健康、issue 修复、自定义工作流 —— **4.x 已经覆盖五条域**,每条域都有专门编排器,按"门禁不通过就停"的纪律一条一条跑。
 
-先给你上的是 `peaks-code`,主官。它是 peaks-loop 默认入口,管 PRD、RD、QA、UI、SC、TXT 这一长串工序的主调度,也是你日常跟 peaks-loop 说话时最常打交道的那个角色。
+| 域 | 你发这条命令 | 它会做什么 |
+| --- | --- | --- |
+| 💻 **代码域 (code-domain) only** | `/peaks-code 帮我实现这个功能` | PRD → RD → 实现 → QA → UI → 切片,跑完交你拍板 |
+| 💻 **代码域 (code-domain) only** | `/peaks-code 这个 bug 帮我修一下` | 复现 → 改 → review → 测试,同日 ship |
+| 📝 **内容** | `/peaks-content 帮我把这篇推文写出来再发` | 草稿 → 编辑 → 调性检查 → 发布 → 归档,中间不跳步 |
+| 🩺 **项目健康** | `/peaks-doctor 帮我体检一下这个仓库` | 红线审计 + L3 doctor 检查 + 转 OpenSpec,坏在哪道停在哪道 |
+| 🐛 **批量修 issue** | `/peaks-issue-fix-orchestrator 帮我把 upstream 的 30 个 open issue 修一批` | 调研 → 分类 → 参考 PR → 逐个修复 + commit + PR 草稿 |
+| 📋 **自定义工作流** | `/peaks-sop 帮我把团队的发布流程沉淀成 SOP` | 自然语言描述 → 自动生成 + 校验 + 注册成可执行的 SOP |
+| 🔁 **跑过一次再来** | `/peaks-solo 按上次那样再跑一次` | 调出你已经沉淀好的战术,自动复跑 |
+| 🆕 **接手陌生仓库** | `/peaks-code 这是新仓库,先带我过一遍` | 摸清结构、识别风险点、给一个上手顺序 |
+| 🧠 **沉淀自己的打法** | `/peaks-solo 这套打法以后还会用,沉淀一下` | 变成你本地常驻的战术,下次说"跑那只"就行 |
 
-它能做的:
-- 写长任务代码(端到端需求 → PRD → 实现 → QA),一道门一道门跑,坏在哪道停在哪道
-- 修 bug 当天发,改完顺手过审 + 测试,不是改完就完
-- 帮你做 / 接 / 拆长跑的需求,把一个模糊需求一路剥到能落地的实现
+每一条路,**一条斜杠命令**就能开跑。
 
-它一句话能扛完的活,你都不必开第二个终端。它对测试覆盖率、审计门、卡点阻断一视同仁:跑不到位的活不交付,跑歪的活直接退回重跑。
+---
 
-它既是装好就立刻能用的那个入口,也是后面要长出来的内建角色的调度口;它内部有一套连续审计、QA 闸口、review 验收,默认打开,你想关哪一道才需要单独说。
+## 为什么大家会选它
 
-其他内置 loop engineering,敬请期待。
+- **自然语言即界面** —— 你不学 CLI、不背命令。**用一条斜杠命令(比如 `/peaks-code xxx`)** 显式触发到对应编排器,后面说什么都行。LLM 替你跟 peaks-loop 跑命令。
+- **门禁真挡事,不是装饰** —— 5,439 个测试用例、QA 闸口、review 验收默认全开。**审计不通过就停,QA 没过就停**。
+- **跑过的事会变成本地战术(bee)** —— 沉淀下来的 loop engineering 落到你本地的 `~/.peaks/` 池子里,跑两次稳定就自动晋升;跑翻车的会让你重新定义。**下次说"跑那只"整套流程自动就位**,你那几只战术会跟着你的口味长。
+- **搭在你已经用的工具上** —— 不是新发明一个 AI CLI,而是架在 **Claude Code** 和 **Z Code** 之上。不抢你的 shell、不抢你的 prompt、不抢你的 IDE。其他工具适配中,欢迎共建。
+- **你拍板,它执行** —— 影响资产的决策都给你选;其余的它自己跑。**0 学习成本,1 分钟上手。**
 
-## 你也能沉淀自己的 loop engineering
+---
 
-跑过一次还想跑,说一句话让它永久驻场。
+## 装上以后的几道闸门
 
-你沉淀的是 loop engineering(战术套路),不是简单的 skill(动作招式)。下次说"跑那只",整套流程自动就位。
+| 闸门 | 默认状态 | 用来挡什么 |
+| --- | --- | --- |
+| 单元测试 / 集成测试 | ✅ 开 | 代码层面的回归 |
+| 代码审计 (lint / prose / type) | ✅ 开 | 写法与意图漂移 |
+| 安全扫描 | ✅ 开 | 凭据、SSRF、注入、危险 IO |
+| QA 复核 | ✅ 开 | 任务级闸门,坏在哪道停在哪道 |
+| review 验收 | ✅ 开 | 改完不立刻出门,review 通过才出门 |
 
-它落到你本地的一个池子里,只对你生效。命名、复用、迭代都是你说了算:跑过两遍稳定的会被抬高,跑翻车的会让你重新定。决策影响资产的,你拍板。
+**所有闸门默认开,你想关哪一道才需要单独说。**
 
-这套机制关键不是"工具给你造了多少只 bee",而是你那几只 bee 一直在跟着你的口味长 —— 你提一句,它长一点。
+---
 
-## 上号
+## 当前状态 · 4.x 正式版
 
-```bash
-npm i -g peaks-loop
-```
+| | |
+| --- | --- |
+| **最新版本** | [`4.0.0-beta.7`](https://github.com/SquabbyZ/peaks-loop/releases) — 4.x 正式版筹备中 |
+| **覆盖域** | 代码(`peaks-code`) · 内容(`peaks-content`) · 项目健康(`peaks-doctor`) · 批量修 issue(`peaks-issue-fix-orchestrator`) · 自定义 SOP(`peaks-sop`) · 通用原语(`peaks-solo` 分诊 / `peaks-resume` 续 / `peaks-status` 看 / `peaks-test` 测) |
+| **沉淀池** | `~/.peaks/` 本地池 · 跑两次自动晋升成 bee · 跑翻车让你重定义 · bee 跟着你的口味长 |
+| **测试套件** | 5,439 passed · 19 skipped · 0 failed |
+| **适配 IDE** | ✅ Claude Code · ✅ Z Code · 🚧 Codex / Cursor / Trae / Tongyi Lingma / Hermes / OpenClaw / Qoder(适配中,欢迎共建) |
+| **依赖运行时** | Node ≥ 20 |
+| **License** | MIT |
 
-装完一句话接活。
+---
 
-## 顺便说一句
+## 强烈推荐 · 四个项目组合起来用
 
-这个仓库以前叫 [`peaks-cli`](https://github.com/SquabbyZ/peaks-cli),现在叫 `peaks-loop`。
+> **0 学习成本。** 这是组合起来用最大的好处 —— 不只是效果俱佳,更是因为这四个项目的**接口对齐到了"自然语言"**,你只需要说一句话,谁替你跑命令、按什么闸门、按什么战术手册,完全不用你记。
 
-里面的技能从 `peaks-code`(单角色)演化到 `peaks-code`(带门禁的代码域).两边都还在,只是分工不同:`peaks-code` 如今是给单任务跑流程用的那个老入口,`peaks-code` 接管了端到端的主路径。
+<p align="center">
+  <a href="https://github.com/affaan-m/ECC">
+    <img src="https://img.shields.io/badge/ECC-affaan--m-6366f1?style=for-the-badge&logo=github&logoColor=white" alt="affaan-m/ECC" />
+  </a>
+  &nbsp;
+  <a href="https://github.com/Egonex-AI/Understand-Anything">
+    <img src="https://img.shields.io/badge/Understand--Anything-Egonex--AI-22c55e?style=for-the-badge&logo=github&logoColor=white" alt="Egonex-AI/Understand-Anything" />
+  </a>
+  &nbsp;
+  <a href="https://github.com/obra/superpowers">
+    <img src="https://img.shields.io/badge/superpowers-obra-f59e0b?style=for-the-badge&logo=github&logoColor=white" alt="obra/superpowers" />
+  </a>
+</p>
 
-事情一直没换过:你说话,它替你排工程门禁,坏哪道停哪道,你来拍板。
+| 角色 | 项目 | 一句话 |
+| --- | --- | --- |
+| **结晶与门禁** | [**peaks-loop**](https://github.com/SquabbyZ/peaks-loop) ← 你在这里 | loop engineering 结晶系统,装上就有 PRD/RD/QA/UI/SC/TXT 一整条工程链 + 沉淀 |
+| **战术手册** | [affaan-m/ECC](https://github.com/affaan-m/ECC) | everything-claude-code:Claude Code 上能拿到的最好用的战术、技能、SOP 集合 |
+| **代码理解** | [Egonex-AI/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything) | 任意仓库,一句话读懂 —— 让 LLM 真正"理解"项目,而不是猜 |
+| **流程与纪律** | [obra/superpowers](https://github.com/obra/superpowers) | brainstorming / TDD / debugging / code-review 等流程纪律,每条都自带硬退出条件 |
 
-你只需要把这一个仓库装好,后面每次跑新需求,都有现成的战术角色等你点。
+**用起来就一句话**:把上面三个仓库都 clone 到本地,peaks-loop 装上,剩下的交给 LLM —— 它会按需取用、按纪律守门、按战术落地、按需求沉淀。
+
+### 致敬
+
+peaks-loop 的两条工程脊柱直接来自这两个项目:
+
+- [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) — 把"工程化每一条规则"刻进我们的方法层。
+- [alchaincyf/darwin-skill](https://github.com/alchaincyf/darwin-skill) — 把"演化校验每一次改进"刻进我们的反漂移闸门。
+
+---
+
+## FAQ
+
+<details>
+<summary><b>它跟 Claude Code / Z Code 是什么关系?</b></summary>
+
+它是**搭在上面**,不是替换。peaks-loop 不抢你的 shell、不抢你的 prompt、不抢你的 IDE。它在 Claude Code / Z Code 这两个一等公民适配里跑,你照常用。**其他 AI 编程工具适配中,欢迎共建** → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues)。
+
+</details>
+
+<details>
+<summary><b>我需要记 CLI 命令吗?</b></summary>
+
+不需要。你只用自然语言或选选项,LLM 替你跑命令。**所有 CLI 命令对外隐藏,对 LLM 开放**。
+
+</details>
+
+<details>
+<summary><b>沉淀下来的战术会一直留在本地吗?</b></summary>
+
+会。沉淀落在你本地的池子里,只对你生效。命名、复用、迭代都是你说了算;跑翻车的会让你重新定义。
+
+</details>
+
+<details>
+<summary><b>它会自己改我的代码吗?</b></summary>
+
+改,但过门禁。**审计不通过 = 不出门**,**QA 没过 = 不出门**,**review 不通过 = 不出门**。它替你跑,但每道门都给你审。
+
+</details>
+
+<details>
+<summary><b>跟 3.x 比,4.x 有什么不同?</b></summary>
+
+**最大的不同:从"代码专用"扩成"多域编排系统"。** 4.x 不再只是写代码 —— 新增了 `peaks-content`(内容生产)、`peaks-doctor`(项目健康)、`peaks-issue-fix-orchestrator`(批量修 issue)、`peaks-sop`(自定义 SOP)四条域编排链,加上 `peaks-solo` 分诊员按你说话自动判断该走哪一域。再加 9 个 IDE 适配、结晶系统重命名、post-run crystallization 机制、5,439 tests 通过。完整变更 → [`CHANGELOG.md`](./CHANGELOG.md)。
+
+</details>
 
 ---
 
-MIT License · Made by [SquabbyZ](https://github.com/SquabbyZ)
+## 链接
 
 - 全部技能清单 → [`skills/`](./skills/)
-- 设计文档 → [`docs/`](./docs/)
 - 更新日志 → [`CHANGELOG.md`](./CHANGELOG.md)
 - 提问 → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues)
+- 致敬: [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) · [alchaincyf/darwin-skill](https://github.com/alchaincyf/darwin-skill)
+- 组合推荐: [affaan-m/ECC](https://github.com/affaan-m/ECC) · [Egonex-AI/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything) · [obra/superpowers](https://github.com/obra/superpowers)
+- 沉淀设计 → [`docs/superpowers/specs/2026-07-04-peaks-maker-dynamic-skill-sediment-design.md`](./docs/superpowers/specs/2026-07-04-peaks-maker-dynamic-skill-sediment-design.md)
+- Loop Engineering 结晶设计 → [`docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md`](./docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md)
+
+---
+
+<div align="center">
+
+MIT License · Made by [SquabbyZ](https://github.com/SquabbyZ) · 中文版 · [English version](./README-en.md)
+
+</div>

package/examples/video-demo/README.md

@@ -1,40 +1,101 @@
-# peaks-loop video demo
+# peaks-loop video demo (v5)
 
-Remotion-based 30-second brand walk-through for peaks-loop 4.0. Mirrors `README.md`.
+Remotion-based ~27-second brand walk-through for peaks-loop 4.x. Mirrors the multi-domain + slash-command narrative of the top-level README.
 
 ## Composition
 
 - Two compositions, one per locale:
-  - `peaks-loop-demo`     — 30 seconds @ 30fps (900 frames), 1920×1080 — Chinese primary.
-  - `peaks-loop-demo-en`  — same frame budget, English primary.
-- Scene timeline (frozen in `src/Root.tsx`):
-  - 0–90    — **TitleScene** (`peaks-loop`, no ·, no emoji)
-  - 90–240  — **PhilosophyScene** — 5 hero philosophy items, bilingual
-  - 240–540 — **DemoScene × 3** — `写长任务代码` / `修 bug 当天发` / `接一个长跑的需求`
-  - 540–780 — **SedimentScene** — 3-beat `NL → MANIFEST → BEE`
-  - 780–900 — **ClosingScene** — `npm i -g peaks-loop` + repo-name vs skill-name arc + 5,439 tests stats
+  - `peaks-loop-demo`     — Chinese primary
+  - `peaks-loop-demo-en`  — English primary
+- Same frame budget for both; dimensions 1920×1080 @ 30fps.
+- Scene timeline (frozen in `src/Root.tsx`, v5 narrative):
+
+  | # | Scene | Slug | Frames |
+  | --- | --- | --- | --- |
+  | 1 | `IntroScene` | intro | 80 |
+  | 2 | `RecordingScene` | install | 100 |
+  | 3 | `RecordingScene` | first-slash | 100 |
+  | 4 | `RecordingScene` | domains | 100 |
+  | 5 | `RecordingScene` | sediment | 100 |
+  | 6 | `CreditScene` | credit | 130 |
+  | 7 | `ClosingScene` | closing | 110 |
+
+  Plus 12-frame overlap transitions between every scene.
 
 ## Visual style
 
-- Background: `#0f172a` (slate-900) via `bg-brand-bg`
-- Primary text: `#f8fafc` (slate-50) via `text-brand-fg`
-- Accent: `#6366f1` (indigo-500) via `text-brand-accent`
-- Stable badge: `#22c55e` (green-500)
-- Mono font for kickers / install chip / chat bubbles; sans font for headlines
+- Background: `#0f172a` (slate-900) via `bg-brand-bg` + `BrandBackground` (drifting indigo halo + diagonal sweep line + bottom green glow).
+- Accent: `#6366f1` (indigo-500) · Stable: `#22c55e` (green-500) · Warn: `#f59e0b` (amber-500).
+- Typography: `font-mono` for kickers, captions, IDE/terminal HUD; `font-sans` for headlines.
+- Three caption styles (`CaptionOverlay`):
+  - **subtitle** — black semi-transparent bar at the bottom.
+  - **callout** — indigo gradient emphasis box, slides in from the left.
+  - **annotation** — amber speech-bubble, drops in from the top-right.
 
-## Public preview files (tracked)
+## Scene components
 
-The READMEs embed `<video>` tags that point at:
+```
+src/scenes/
+├── IntroScene.tsx       — hero title + tagline (kicker / brand / tagline)
+├── RecordingScene.tsx   — the workhorse: 4 instances, each plays an HUD + captions + cursor
+├── HudWindow.tsx        — stylised terminal/IDE panel that types out lines one at a time
+├── CaptionOverlay.tsx   — 3-style caption layer (subtitle / callout / annotation)
+├── CursorHighlight.tsx  — macOS-style cursor with smooth waypoint interpolation + click ripple
+├── BrandBackground.tsx  — shared brand background (halo + sweep + bottom glow)
+├── CreditScene.tsx      — tribute + recommended stack
+└── ClosingScene.tsx     — install chip + 5,439 tests stats
+```
+
+## Copy registry
 
-- `preview/peaks-loop-demo.mp4`    (zh, 4.9 MB)
-- `preview/peaks-loop-demo-en.mp4` (en, 5.0 MB)
+All on-screen text lives in `src/copy.ts`. Both locales are strict: no hardcoded
+CN/EN inline in scene components. The `recordings[]` array holds 4 scene slugs
+(install / first-slash / domains / sediment), each with its own captions,
+cursor choreography, and HUD payload.
 
-These are produced by the render command below and committed to git so a clone (and the GitHub rendering) sees the same path. The shell snippet under **Render** keeps `preview/` in sync after a fresh build.
+## v5 recording pipeline (Playwright + Remotion)
 
-## Render
+The `RecordingScene` slots are designed to host **real recorded footage**
+when you have a Chromium-equipped machine. The HUD window is the stand-in
+for that footage until the recording pass runs.
+
+### 1. Install the recording side
 
 ```bash
 cd examples/video-demo
+pnpm add -D playwright
+pnpm exec playwright install chromium
+```
+
+### 2. Author a scenario JSON
+
+Write `recordings/<slug>.json` per scene using the
+`web-demo-video_skills` schema (`goto` / `click` / `fill` / `wait` / `screenshot`).
+For our 4 slugs, the natural targets are:
+
+| slug | URL / action |
+| --- | --- |
+| `install` | terminal typing `npm i -g peaks-loop` |
+| `first-slash` | Claude Code chat with `/peaks-code ...` |
+| `domains` | same chat, scrolling through the 5 `/peaks-*` slash commands |
+| `sediment` | same chat, completing a run + asking to sediment |
+
+### 3. Record per scene
+
+```bash
+pnpm exec tsx scripts/record-scenes.ts
+# outputs recordings/<slug>.webm  +  recordings/<slug>.cursor.json
+```
+
+### 4. Swap the HUD for the recorded clip
+
+In `src/scenes/RecordingScene.tsx`, replace the `<HudWindow>` block with a
+`<Video src={...}>` from the matching `recordings/<slug>.webm`. Drop the
+`HudWindow` import when no scene needs it any more.
+
+### 5. Render
+
+```bash
 pnpm install
 npx remotion render peaks-loop-demo out/peaks-loop-demo.mp4
 npx remotion render peaks-loop-demo-en out/peaks-loop-demo-en.mp4
@@ -44,10 +105,10 @@ cp out/peaks-loop-demo.mp4    preview/peaks-loop-demo.mp4
 cp out/peaks-loop-demo-en.mp4 preview/peaks-loop-demo-en.mp4
 ```
 
-Fallback (no Chromium available):
+Fallback (no Chromium available — renders the HUD stand-in only):
 
 ```bash
-npx remotion still peaks-loop-demo out/still.png --frame=120
+npx remotion still peaks-loop-demo out/still.png --frame=400
 ```
 
 ## Preview during dev
@@ -55,3 +116,27 @@ npx remotion still peaks-loop-demo out/still.png --frame=120
 ```bash
 npx remotion studio   # http://localhost:3000
 ```
+
+## Why this layout
+
+The 4 recording slugs follow the **black-box mental model** the README now
+uses: install → first slash command → tour the 5 domains → sediment. Each
+scene is **self-contained** (own HUD payload, captions, cursor ticks),
+so you can rearrange them, drop one, or A/B test a new one without
+touching the others. The 12-frame overlap transitions cross-fade between
+scenes so the result feels like one continuous take rather than a slide
+deck.
+
+## Adding a new scene
+
+1. Add a new entry to `recordings` in `src/copy.ts` (both `zh` and `en`):
+   - `slug` (kebab-case, used for the corner chip + recording filename)
+   - `captions` (array of `{ text, style }` triples)
+   - `cursor` (array of waypoints; empty = no cursor overlay)
+   - `hud` (terminal / ide, with the lines you want typed out)
+2. Add an extra frame budget to `src/Root.tsx` if you want a longer hold.
+3. Typecheck: `pnpm exec tsc --noEmit`.
+4. Re-render.
+
+If you have a recording, drop a `<Video>` into `RecordingScene.tsx` and
+point it at the new `recordings/<slug>.webm`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.0-beta.7",
+  "version": "4.0.0-beta.8",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "license": "MIT",
@@ -26,6 +26,7 @@
     "dist/src/**/*.js",
     "dist/src/**/*.d.ts",
     "scripts/clean-dist.mjs",
+    "scripts/copy-templates.mjs",
     "scripts/sync-version.mjs",
     "scripts/install-skills.mjs",
     "scripts/watch.mjs",
@@ -46,7 +47,7 @@
     "examples/video-demo/out/en-closing-960.png"
   ],
   "scripts": {
-    "build": "node ./scripts/sync-version.mjs && node ./scripts/clean-dist.mjs && tsc -p tsconfig.json",
+    "build": "node ./scripts/sync-version.mjs && node ./scripts/clean-dist.mjs && tsc -p tsconfig.build.json && node ./scripts/copy-templates.mjs",
     "prepack": "npm run build",
     "prepublishOnly": "node scripts/prepublish-build.mjs",
     "prepublish": "node ./scripts/sync-version.mjs",
@@ -55,7 +56,18 @@
     "dev": "tsx src/cli/index.ts",
     "dev:watch": "node ./scripts/watch.mjs",
     "pretest": "node ./scripts/sync-version.mjs",
-    "test": "node ./scripts/lint/silent-warning-detector.mjs && vitest run",
+    "test": "vitest run tests/unit/cli-program.core.test.ts tests/unit/cli-program.stateful.test.ts tests/unit/cli-program.workflow.test.ts tests/unit/cli-program.workflow-cli.test.ts tests/unit/cli-program.workspace.test.ts tests/unit/cli",
+    "test:full": "vitest run",
+    "test:fast": "vitest run --maxWorkers=8 -t \"^((?!@slow|@integration|@replay).)*$\" tests/unit",
+    "test:dev": "vitest run tests/unit",
+    "test:dev:cli": "vitest run tests/unit/cli-program.core.test.ts tests/unit/cli-program.stateful.test.ts tests/unit/cli-program.workflow.test.ts tests/unit/cli-program.workflow-cli.test.ts tests/unit/cli-program.workspace.test.ts tests/unit/cli",
+    "test:unit": "vitest run tests/unit",
+    "test:integration": "vitest run tests/integration",
+    "test:cli": "vitest run tests/unit/cli-program.core.test.ts tests/unit/cli-program.stateful.test.ts tests/unit/cli-program.workflow.test.ts tests/unit/cli-program.workflow-cli.test.ts tests/unit/cli-program.workspace.test.ts tests/unit/cli",
+    "test:workflow": "vitest run tests/unit/cli-program.workflow.test.ts tests/unit/cli-program.workflow-cli.test.ts tests/unit/workflow-autonomous-resume-validation.test.ts tests/unit/workflow-autonomous-service.test.ts tests/unit/workflow-router-service.test.ts tests/unit/skill-browser-workflow.test.ts tests/unit/services/workflow",
+    "test:audit:silent-warning": "node ./scripts/lint/silent-warning-detector.mjs",
+    "test:ci": "node ./scripts/sync-version.mjs && node ./scripts/lint/silent-warning-detector.mjs && vitest run --coverage",
+    "test:changed": "node scripts/test-changed.mjs",
     "lint:silent-warning": "node ./scripts/lint/silent-warning-detector.mjs",
     "test:race": "vitest run --no-file-parallelism tests/unit/g8-shared-channel.test.ts tests/unit/dispatch-record-writer.test.ts tests/unit/services/retrospective/heartbeat.test.ts tests/unit/cli/commands/share-commands.test.ts",
     "test:replay": "node scripts/fixture-capture-setup.mjs && vitest run tests/unit/replay tests/unit/fixture",
@@ -99,13 +111,14 @@
     "@jridgewell/trace-mapping": "^0.3.31",
     "@stryker-mutator/core": "^8.7.1",
     "@stryker-mutator/typescript-checker": "^8.7.1",
-    "@stryker-mutator/vitest-runner": "^8.7.1",
+    "@stryker-mutator/vitest-runner": "^9.6.1",
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.10.2",
-    "@vitest/coverage-v8": "^2.1.8",
+    "@vitest/coverage-v8": "^4.1.10",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
-    "vitest": "^2.1.8",
+    "vite": "^6.0.0",
+    "vitest": "^4.1.0",
     "zod-to-json-schema": "^3.25.2"
   }
 }

package/scripts/copy-templates.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * copy-templates.mjs — copy bundled non-JS template assets into dist/
+ * after `tsc` runs. Required by slice 2026-07-15-project-scan-bootstrap
+ * (PRD G4b / R1 / QA BLOCKER): `tsc` only emits .js / .d.ts, so the
+ * audit/business markdown templates at
+ * `src/services/workspace/templates/project-scan/*.md` are absent
+ * from `dist/`. Downstream `npm install peaks-loop` consumers would
+ * therefore only get the dynamically-generated `project-scan.md` and
+ * the 4 audit/business templates would silently be missing.
+ *
+ * Idempotent: safe to run multiple times. Run after `tsc` in `build`.
+ */
+import { copyFileSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+/**
+ * @param {string} srcDir absolute source directory
+ * @param {string} destDir absolute destination directory (created if absent)
+ * @param {readonly string[]} extensions file extensions to copy (lowercase, with leading dot)
+ */
+function copyTree(srcDir, destDir, extensions) {
+  if (!statSync(srcDir, { throwIfNoEntry: false })) return;
+  mkdirSync(destDir, { recursive: true });
+  for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+    const srcPath = join(srcDir, entry.name);
+    const destPath = join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      copyTree(srcPath, destPath, extensions);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    const ext = entry.name.toLowerCase().slice(entry.name.lastIndexOf('.'));
+    if (!extensions.includes(ext)) continue;
+    copyFileSync(srcPath, destPath);
+  }
+}
+
+const targets = [
+  {
+    src: join(packageRoot, 'src/services/workspace/templates/project-scan'),
+    dest: join(packageRoot, 'dist/src/services/workspace/templates/project-scan'),
+    extensions: ['.md']
+  }
+];
+
+let totalCopied = 0;
+for (const { src, dest, extensions } of targets) {
+  const before = statSync(dest, { throwIfNoEntry: false })
+    ? readdirSync(dest).length
+    : 0;
+  copyTree(src, dest, extensions);
+  const after = readdirSync(dest).length;
+  const added = after - before;
+  totalCopied += added;
+  process.stdout.write(
+    `copy-templates: ${src.replace(packageRoot + '/', '')} -> ${dest.replace(packageRoot + '/', '')} (+${added} files)\n`
+  );
+}
+
+process.stdout.write(`copy-templates: done (${totalCopied} files copied)\n`);

package/skills/bee/peaks-rd/SKILL.md

@@ -185,7 +185,7 @@ Peaks-Loop PRD/RD/QA gates remain authoritative: OpenSpec structures the durable
 
 ## Mock data placement rules (BLOCKING — framework-aware)
 
-When the project-scan in `.peaks/_runtime/<sessionId>/rd/project-scan.md` identifies a frontend framework, mock data MUST follow the framework's built-in mock mechanism. **Never write mock data inline in component files.**
+When the project-scan in `.peaks/project-scan/project-scan.md` (project-level, git-tracked; slice 2026-07-15-project-scan-bootstrap) identifies a frontend framework, mock data MUST follow the framework's built-in mock mechanism. **Never write mock data inline in component files.**
 
 → see `references/mock-data-placement.md` for the framework-to-mock-directory mapping + hard rules + verification gate.
 

package/skills/bee/peaks-rd/references/library-version-awareness.md

@@ -2,12 +2,12 @@
 
 > Body of `## Library version awareness (3rd-party breaking-change gate)`. After `peaks scan libraries` lands the dependency list under `## Library versions` in `rd/project-scan.md`, RD MUST cross-check the slice's diff against `schemas/library-breaking-changes.data.json` before writing any 3rd-party API call. Concretely:
 
-1. **Read the project's `## Library versions` section** in `.peaks/_runtime/<sessionId>/rd/project-scan.md`. Identify the `name` + `major` of every dependency the slice imports from.
+1. **Read the project's `## Library versions` section** in `.peaks/project-scan/project-scan.md`. Identify the `name` + `major` of every dependency the slice imports from.
 2. **Open `schemas/library-breaking-changes.data.json`** (LLM reads via the `Read` tool). For each library where the installed `major` matches a `toMajor` in the table, load the corresponding `breakingChanges[]` list.
 3. **For each `import` statement in the slice's diff** (e.g. `import { Drawer } from 'antd'`), check whether the imported symbol or its prop signature matches any `breakingChanges[].api` entry for the library's installed major.
 4. **On a hit**:
    - **Warn the LLM in the slice's handoff**: in `.peaks/_runtime/<sessionId>/rd/requests/<rid>.md` under `## Implementation evidence`, append a one-line note per hit: `- [lib-version] <library> <installed version> imports <api>; breaking-change rule says use <replacement> instead.`
-   - **Persist a `lesson` memory** at the END of `.peaks/_runtime/<sessionId>/rd/project-scan.md` (or the tech-doc, or the handoff — any of these is read by future RD runs):
+   - **Persist a `lesson` memory** at the END of `.peaks/project-scan/project-scan.md` (or the tech-doc, or the handoff — any of these is read by future RD runs):
      ```
      <!-- peaks-memory:start -->
      title: <library> <installed major> requires <api> → <replacement>

package/skills/bee/peaks-rd/references/mock-data-placement.md

@@ -2,7 +2,7 @@
 
 > Body of `## Mock data placement rules` + `### Framework-to-mock-directory mapping` + `### Hard rules` + `### Verification gate`. **BLOCKING — framework-aware.**
 
-When the project-scan in `.peaks/_runtime/<sessionId>/rd/project-scan.md` identifies a frontend framework, mock data MUST follow the framework's built-in mock mechanism. **Never write mock data inline in component files.**
+When the project-scan in `.peaks/project-scan/project-scan.md` identifies a frontend framework, mock data MUST follow the framework's built-in mock mechanism. **Never write mock data inline in component files.**
 
 ## Framework-to-mock-directory mapping