Improve first-run onboarding and docs

Author: YSCJRH

README.md

@@ -11,6 +11,22 @@ Build a Chinese-first digital double that stays local to this skill folder. Keep
 
 ## Quick Start
 
+### Fast path for a human first run
+
+If the user only wants the first visible artifact, prefer:
+
+```powershell
+python scripts/double_builder.py start --slug my-double --display-name "我的分身"
+```
+
+Use `correct` right after generation when the user says “我不会这么说” or “我更在意 X”:
+
+```powershell
+python scripts/double_builder.py correct --slug my-double
+```
+
+### Low-level path for Codex and custom workflows
+
 1. Initialize a new double:
 
    ```powershell

SKILL.md

@@ -6,7 +6,7 @@
 ## About
 
 ```text
-Build a private digital double and an editable model of how you think, choose, and present yourself.
+Build a private digital double that captures how you judge, set boundaries, and give advice.
 ```
 
 ## Topics
@@ -29,11 +29,11 @@ v0.1.0 - A local-first starting point for building a private digital double
 ## Release Body
 
 ```md
-Not a life-log. Not a memory simulator. A local-first way to build and revise different versions of yourself.
+Not a life-log. Not a memory simulator. A local-first way to build and correct a self-model.
 
-`create-double-skill` 的第一版聚焦一件事：
+`create-double-skill` 现在最想解决的一件事是：
 
-不用自动抓取大量隐私素材，也能通过引导式提问、自由自述和显式修正，构建一个更像“你会怎么判断”的数字分身。
+不用自动抓取大量隐私素材，也能在几分钟内生成一个更像“你会怎么判断”的数字分身。
 
 这不是人生资料库，不是记忆模拟器，也不承诺“人格复制”。
 它更像一个 `local-first` 的 starter repo：用结构化档案、可回写修正和可读产物，把“自我蒸馏”变成一个可迭代的工作流。
@@ -45,6 +45,9 @@ Not a life-log. Not a memory simulator. A local-first way to build and revise di
 
 ## This release includes
 
+- 3-minute first run：`start` 命令直接提问、写入、渲染和预览
+- 自然语言 correction：`correct` 命令支持“我不会这么说”“我更在意 X”
+- `doctor` 健康检查：依赖、仓库完整性、写权限、终端编码提示
 - 混合采集：访谈提问和自由描述可随时切换
 - 固定 schema：以 `profile.yaml` 作为唯一结构化真源
 - 产物生成：自动渲染 `profile.md` 和运行时 `SKILL.md`
@@ -71,9 +74,7 @@ Not a life-log. Not a memory simulator. A local-first way to build and revise di
 
 ```powershell
 python -m pip install -r requirements.txt
-python scripts/double_builder.py init --slug my-double --display-name "我的分身"
-python scripts/double_builder.py apply-turn --slug my-double --payload-file examples/initial-freeform-payload.json
-python scripts/double_builder.py render --slug my-double
+python scripts/double_builder.py start --slug my-double --display-name "我的分身"
 ```
 
 Built with Codex, but not limited to Codex.

docs/github-publication-kit.md

@@ -29,6 +29,9 @@
 
 ## 本版包含
 
+- 3-minute first run：`start` 命令直接提问、写入、渲染和预览
+- 自然语言 correction：`correct` 命令支持“我不会这么说”“我更在意 X”
+- `doctor` 健康检查：依赖、仓库完整性、写权限、终端编码提示
 - 混合采集：访谈提问和自由描述可随时切换
 - 固定 schema：以 `profile.yaml` 作为唯一结构化真源
 - 产物生成：自动渲染 `profile.md` 和运行时 `SKILL.md`
@@ -53,9 +56,7 @@
 
 ```powershell
 python -m pip install -r requirements.txt
-python scripts/double_builder.py init --slug my-double --display-name "我的分身"
-python scripts/double_builder.py apply-turn --slug my-double --payload-file examples/initial-freeform-payload.json
-python scripts/double_builder.py render --slug my-double
+python scripts/double_builder.py start --slug my-double --display-name "我的分身"
 ```
 
 ## 公开发布前建议

docs/release-v0.1.0.md

@@ -1,15 +1,30 @@
 # create-double-skill examples
 
-这个目录放的是“可直接拿来参考”的结构化 payload。
+如果你是第一次来到这个仓库，先不要从 payload 开始。
 
-推荐顺序：
+优先顺序建议：
 
-1. 先看 `initial-freeform-payload.json`
-2. 再看 `correction-payload.json`
-3. 用你自己的原始回答替换其中的文本
-4. 通过 `apply-turn` 合并，再运行 `render`
+1. 先用 `python scripts/double_builder.py start --slug my-double --display-name "我的分身"` 跑通第一次成功
+2. 再看 [start-transcript.md](start-transcript.md)，确认交互大概长什么样
+3. 再看 [generated-artifacts.md](generated-artifacts.md)，确认产物长什么样
+4. 最后才看低层 payload 示例
 
-## 最短演示流程
+## First-Run Assets
+
+- [start-transcript.md](start-transcript.md)
+- [generated-artifacts.md](generated-artifacts.md)
+- [correction-before-after.md](correction-before-after.md)
+
+这些示例对应的是“陌生用户第一次来到仓库，如何在 3 分钟内完成第一次成功”。
+
+## Advanced Payload Examples
+
+如果你在做高级用法、Codex 工作流、或自定义 patch，再看这些：
+
+- [initial-freeform-payload.json](initial-freeform-payload.json)
+- [correction-payload.json](correction-payload.json)
+
+最短低层流程：
 
 ```powershell
 python scripts/double_builder.py init --slug demo --display-name "演示分身"
@@ -19,8 +34,9 @@ python scripts/double_builder.py apply-turn --slug demo --payload-file examples/
 python scripts/double_builder.py render --slug demo
 ```
 
-## 说明
+## Notes
 
-- 这些 payload 是演示格式，不是“唯一正确答案”
+- 这些 payload 是低层接口示例，不是第一次使用者的主入口
 - 最好的 payload 应该尽量小、尽量准
 - 如果一句话还不能确定，就先放进 `unknowns`
+- canonical truth 仍然是 `profile.yaml`，不是这些 JSON 示例本身

examples/README.md

@@ -0,0 +1,37 @@
+# correction before / after
+
+`create-double-skill` 的灵魂不是“一次生成”，而是“生成后能改”。
+
+下面是一个极简例子。
+
+## before
+
+```md
+## Signature Phrases
+Tentative:
+- 你应该先冷静一下
+```
+
+## user correction
+
+```text
+我不会直接说“你应该”，我更常说“如果是我，我会先把边界讲清楚”。
+```
+
+## after
+
+```md
+## Taboo Phrases
+Confirmed:
+- 你应该
+
+## Signature Phrases
+Confirmed:
+- 如果是我，我会先把边界讲清楚
+```
+
+这种 correction 会同时做三件事：
+
+- 把原句记进 `corrections`
+- 把更像你的表达回写到结构化字段
+- 重新渲染 `profile.md` 和 `SKILL.md`

examples/correction-before-after.md

@@ -0,0 +1,51 @@
+# generated artifacts
+
+`start` 跑完之后，你至少会看到这三类产物：
+
+## 1. Canonical truth: `profile.yaml`
+
+```yaml
+values:
+  priorities:
+    - text: 长期可持续
+      source: direct
+    - text: 关系里的稳定感
+      source: direct
+decision_model:
+  default_questions:
+    - text: 我会先问这件事三个月后还重要吗
+      source: direct
+interaction_style:
+  boundary_style:
+    - text: 我会把底线讲清楚，但尽量不把气氛推到最糟
+      source: direct
+```
+
+## 2. Human-readable snapshot: `profile.md`
+
+```md
+## Priorities
+Confirmed:
+- 长期可持续
+- 关系里的稳定感
+
+## Default Questions
+Confirmed:
+- 我会先问这件事三个月后还重要吗
+
+## Boundary Style
+Confirmed:
+- 我会把底线讲清楚，但尽量不把气氛推到最糟
+```
+
+## 3. Runtime double: `SKILL.md`
+
+```md
+## Confirmed Material
+
+- 优先级: 长期可持续；关系里的稳定感
+- 先问的问题: 我会先问这件事三个月后还重要吗
+- 设边界的方式: 我会把底线讲清楚，但尽量不把气氛推到最糟
+```
+
+first success 的目标不是“字段填满”，而是先得到一个足够真实、可继续修正的第一版。

examples/generated-artifacts.md

@@ -0,0 +1,38 @@
+# start transcript
+
+下面是一段更接近真实 first run 的交互示例。
+
+```text
+$ python scripts/double_builder.py start --slug my-double --display-name "我的分身"
+3 分钟内生成你的第一个 double，不需要写 JSON。
+
+1/3 你做重要决定时，通常先保护什么？
+> 长期可持续、关系里的稳定感
+
+2/3 别人来找你要建议时，你通常会先问什么，或先看什么？
+> 我会先问这件事三个月后还重要吗
+
+3/3 你不舒服时会怎么设边界？
+> 我会把底线讲清楚，但尽量不把气氛推到最糟
+
+已生成：
+- doubles/my-double/profile.md
+- doubles/my-double/SKILL.md
+
+当前 preview：
+- 优先保护：长期可持续；关系里的稳定感
+- 给建议前先问：我会先问这件事三个月后还重要吗
+- 设边界方式：我会把底线讲清楚，但尽量不把气氛推到最糟
+- 下一步：别人低落或混乱时，你更像是安抚、追问，还是帮对方看清取舍？
+
+如果有一句不对，直接输入“我不会这么说...”或“我更在意...”，回车跳过：
+> 我更在意边界清晰
+```
+
+这个 first run 刻意把重点放在：
+
+- 取舍顺序
+- 默认提问方式
+- 边界风格
+
+而不是先让你写一堆 biography。