docs: polish onboarding guides and surface them in README

README.md

@@ -37,6 +37,14 @@ $loopx speed up this project's slowest workflow; compare approaches and verify t
 
 Claude Code uses `/loopx <complex task>`. [Other hosts, install options and upgrades ↓](#try-loopx)
 
+**New to LoopX?** Start with the [first bug-fixing loop](docs/guides/first-bugfix-loop.md):
+reproduce a bug in a small Python project, let the Agent fix it, then check the patch.
+
+- **Use your own project:** follow the [coding agent guide](docs/guides/long-running-coding-agents.md)
+  to set up your host and resume work across sessions.
+- **Use the App:** follow the [illustrated Workspace guide (中文)](docs/guides/personal-workspace-user-guide.md)
+  to manage projects, conversations and results.
+
 ## 📰 News
 
 <!-- Curate major product/architecture releases, research findings, consequential

README.zh-CN.md

@@ -37,6 +37,14 @@ $loopx 优化这个项目最慢的流程，对比方案并验证性能提升
 
 Claude Code 使用 `/loopx <复杂任务>`。[其他宿主、安装方式与升级说明 ↓](#试用-loopx)
 
+**第一次用 LoopX？** 先跟着[查 bug 入门教程](docs/guides/first-bugfix-loop.zh-CN.md)，
+用一个小型 Python 项目走完「复现 bug → Agent 修复 → 检查补丁」的流程。
+
+- **接入自己的项目：** 阅读[长程编程任务指南（English）](docs/guides/long-running-coding-agents.md)，
+  了解宿主接入与跨会话恢复。
+- **使用 App：** 跟着[图文工作区手册](docs/guides/personal-workspace-user-guide.md)，
+  管理项目、对话与交付结果。
+
 ## 📰 最新动态
 
 <!-- Curate major product/architecture releases, research findings, consequential

docs/guides/first-bugfix-loop.md

@@ -2,9 +2,12 @@
 
 [中文](first-bugfix-loop.zh-CN.md)
 
-Start with a tiny checkout-pricing bug. See a test fail, let an agent repair
-it through LoopX, rerun the tests, and inspect a local commit. Then reuse the
-same workflow for a recurring bug hunt in your own repository.
+Fix a tiny checkout-pricing project with an agent you already use. You will
+reproduce two failing checks, ask the agent to repair the code through LoopX,
+inspect the patch, and make a local commit. No remote repository is required.
+
+**Finish steps 1–4 first.** Steps 5–6 are optional extensions for recurring
+bug fixes or refactoring in your own repository.
 
 You need Python 3.11+ for the exercise. To use LoopX, also install Node.js
 22.22.3+ (24 LTS recommended), LoopX, and an agent host you already use. The
@@ -33,6 +36,10 @@ Prices are integer cents. An empty cart costs zero. Orders totaling at least
 are rejected and inputs must not be modified. The two initial bugs violate
 the empty-cart and exact-threshold rules.
 
+For example, `[]` should return `0`, but initially returns `500`.
+`[6_000, 4_000]` should return `10_000`, but initially returns `10_500`.
+These are logic failures to repair, not signs that LoopX is installed incorrectly.
+
 Initialize the copied project and record the intentionally broken baseline:
 
 ```bash
@@ -94,7 +101,7 @@ guided setup for this actual host, with its registered Agent and useful Todos.
 Confirm the host's continuation mechanism is active; initialization alone
 is not completion. Follow LoopX's current quota and stop conditions.
 Run all six checks after the change and show the actual diff and results.
-Leave the patch uncommitted so I can inspect and commit it in step 5.
+Leave the patch uncommitted so I can inspect and commit it in step 4.
 Do not push, create a remote repository, merge, or call additional external services.
 Stop when these requirements are verified, or explain a concrete blocker.
 ```
@@ -103,6 +110,10 @@ You should see a failure reproduction, a small patch, and a final test result.
 The exercise ends when the six checks pass and the diff preserves the
 requirements. It does not need to run forever.
 
+Keep the two input surfaces separate: run `python3 checks.py` and Git commands
+in the **project terminal**; send `$loopx …` in the **agent conversation**.
+An Agent's explanation is useful context, but the next step checks its actual patch.
+
 ### Confirm that it actually started
 
 Ask the agent to report the current LoopX goal, its Agent, the next Todo, and
@@ -122,38 +133,18 @@ activation gap rather than say that autonomous execution is ready.
 Both paths require their host to remain available. Installing LoopX does not
 keep a closed terminal or unavailable App running.
 
-## 4. Turn the workflow into a recurring bug hunt
-
-Use this on a real project after completing the small exercise. Replace the
-scope and test command with your project's actual ones:
-
-```text
-$loopx Keep checking <owned module or directory> for reproducible bugs.
-Start by reading repository instructions and identifying the relevant test
-command, scope, and existing budget. Work in the repository's isolated branch
-or worktree. For each real bug: reproduce it, add a failing regression, make
-the smallest coherent repair, rerun that regression and the affected suite,
-then prepare a signed-off commit and reviewable PR under repository rules.
-Record the result and next action in the existing LoopX work.
-If no new evidence justifies work, wait according to LoopX's scheduler and
-record the next meaningful trigger instead of repeating the same empty scan.
-Honor the current quota and spending boundary. Report environmental failures
-and unresolved tests honestly. Keep merge and release for my explicit decision.
-```
+If you get stuck:
 
-Here, “infinite loop” means authorized work can continue or resume. Each repair
-still has a finish line. Quiet monitoring should wait for a meaningful event
-or its scheduled check; a higher wake frequency does not prove useful progress.
-Start with one module, a known test command, and a spending boundary you accept.
+| What you see | What to check next |
+| --- | --- |
+| `$loopx` is unavailable | Refresh the skill with `loopx workflow-skills --install` in the installation used by this host; then reopen the host if needed |
+| A setup packet, but no repair | Complete activation in the same host as above; then ask it to resume this task, without creating another Goal |
+| Python/import errors | Repair the local Python environment before diagnosing the cart logic |
+| The agent says “done” | Run the checks and inspect the diff in step 4 before accepting the repair |
 
-To pause, ask the agent to pause this LoopX goal and its corresponding driver,
-then read back both states. In CLI you can first use `/goal pause`; in App pause
-the matching automation. Pausing the host driver and pausing the LoopX goal are
-separate state changes. Do not delete project state to stop a loop. To resume,
-open the same project, explicitly resume the same Agent lane, read its existing
-state and last evidence, and reactivate the appropriate host driver.
+<a id="5-test-inspect-commit-then-request-review"></a>
 
-## 5. Test, inspect, commit, then request review
+## 4. Test, inspect, commit, then request review
 
 For the local exercise, run these yourself after the agent finishes:
 
@@ -188,6 +179,51 @@ results. Read back its head and checks. A local commit, a pushed branch, an open
 PR and a merged PR are different outcomes; CI or review feedback may require
 another repair. Creation of a PR does not authorize merging it.
 
+<a id="4-turn-the-workflow-into-a-recurring-bug-hunt"></a>
+
+## 5. Turn the workflow into a recurring bug hunt
+
+Use this on a real project after completing the small exercise. Replace the
+scope and test command with your project's actual ones:
+
+```text
+$loopx Keep checking <owned module or directory> for reproducible bugs.
+Start by reading repository instructions and identifying the relevant test
+command, scope, and existing budget. Work in the repository's isolated branch
+or worktree. For each real bug: reproduce it, add a failing regression, make
+the smallest coherent repair, rerun that regression and the affected suite,
+then prepare a signed-off commit and reviewable PR under repository rules.
+Record the result and next action in the existing LoopX work.
+If no new evidence justifies work, wait according to LoopX's scheduler and
+record the next meaningful trigger instead of repeating the same empty scan.
+Honor the current quota and spending boundary. Report environmental failures
+and unresolved tests honestly. Keep merge and release for my explicit decision.
+```
+
+Here, “infinite loop” means authorized work can continue or resume. Each repair
+still has a finish line. Quiet monitoring should wait for a meaningful event
+or its scheduled check; a higher wake frequency does not prove useful progress.
+Start with one module, a known test command, and a spending boundary you accept.
+
+To pause, ask the agent to pause this LoopX goal and its corresponding driver,
+then read back both states. In CLI you can first use `/goal pause`; in App pause
+the matching automation. Pausing the host driver and pausing the LoopX goal are
+separate state changes. Do not delete project state to stop a loop. To resume,
+open the same project, explicitly resume the same Agent lane, read its existing
+state and last evidence, and reactivate the appropriate host driver.
+
+## 6. Keep improving repository quality
+
+The same loop can address maintenance work before it causes a bug: duplicated
+rules that drift, tangled module dependencies, or a routine change that requires
+editing several unrelated places. Start with evidence from a module you own,
+keep existing behavior and permission boundaries, and verify each useful change.
+
+The [continuous-refactoring example](long-running-coding-agents.md#example-keep-improving-repository-quality)
+provides a complete task prompt and an example of what to compare before and
+after. Continue from the same Goal and its recorded evidence; each refactoring
+still needs a reviewable result and a stopping rule.
+
 ## Setup effort, ongoing cost, and limits
 
 The copied exercise needs two files and the Python standard library. LoopX

docs/guides/first-bugfix-loop.zh-CN.md

@@ -2,8 +2,10 @@
 
 [English](first-bugfix-loop.md)
 
-先用一个小型购物车项目走完流程：看到测试失败，让 Agent 通过 LoopX 修复，
-重新测试，再检查并提交补丁。跑通之后，把同一套流程用于自己仓库的持续查错。
+用你已经在用的 Agent 修好一个小型购物车项目：先复现两个失败检查，通过 LoopX
+修复代码，再检查补丁、完成本地提交。练习不需要远端仓库。
+
+**先完成第 1–4 步。** 第 5–6 步是用于真实仓库的持续查错与重构扩展，跑通练习后再读。
 
 练习需要 Python 3.11+。使用 LoopX 还需要 Node.js 22.22.3+（推荐 24 LTS）、
 LoopX，以及你已经在用的 Agent 宿主。练习测试只用 Python 标准库，不需要模型。
@@ -27,6 +29,9 @@ python3 checks.py
 其他非空购物车加 500 分运费；负价格必须拒绝，输入列表不能被修改。
 初始代码在空购物车和刚好达到免运费门槛时有 bug。
 
+例如，`[]` 应返回 `0`，初始代码却返回 `500`；`[6_000, 4_000]` 应返回
+`10_000`，却返回 `10_500`。这两项失败是要修复的业务逻辑，不是 LoopX 安装失败。
+
 初始化这个复制出来的项目，保存故意带错的起点：
 
 ```bash
@@ -77,13 +82,16 @@ $loopx 修复当前购物车练习。先运行 python3 checks.py，按 cart.py 
 项目已经连接 LoopX 就复用；否则按当前实际宿主完成引导式初始化，注册自己的
 Agent，写入有实际工作的 Todo。确认宿主的自动续跑已激活，不能只报告初始化完成。
 遵守 LoopX 当前的额度和停止条件。修改后运行全部 6 项检查，展示实际 diff 和结果。
-先保留未提交补丁，让我在第 5 步检查后提交。不要 push、新建远端仓库、合并或调用
+先保留未提交补丁，让我在第 4 步检查后提交。不要 push、新建远端仓库、合并或调用
 额外的外部服务。全部需求验证后停止；若有阻塞，说明具体原因。
 ```
 
 你应该看到一次失败复现、一份小补丁，以及最后的测试结果。6 项检查通过，且 diff
 保留全部需求，练习就完成了。这一轮无需一直运行。
 
+分清两个输入位置：`python3 checks.py` 和 Git 命令在**项目终端**运行，
+`$loopx …` 请求发到 **Agent 对话**。Agent 的解释帮助理解原因，下一步仍要检查实际补丁。
+
 ### 确认它真的开始执行
 
 让 Agent 说明当前 LoopX 目标、自己的 Agent、下一个 Todo，以及已经激活的宿主驱动。
@@ -100,30 +108,18 @@ Codex App 中确认对应的 heartbeat automation 已实际保存。若当前宿
 
 两条路径都依赖宿主可用。安装 LoopX 不会让已经关闭的终端或不可用的 App 自动运行。
 
-## 4. 改成持续查 bug 的工作方式
-
-完成小练习后，可以在真实项目使用下面的请求。把范围和测试命令替换成项目实际值：
-
-```text
-$loopx 持续检查 <我负责的模块或目录> 中可复现的 bug。先读仓库说明，确定相关
-测试命令、工作范围和已有预算，在仓库要求的独立分支或 worktree 中工作。
-每个真实问题依次完成：复现、失败回归测试、最小且完整的修复、相关测试与回归、
-按仓库规则准备带 sign-off 的提交和可评审 PR。把结果与下一步写回既有 LoopX 工作。
-没有新证据支持行动时，按 LoopX 调度等待，记录下一次有意义的触发条件，不重复
-执行同样的空扫描。遵守当前额度和费用边界；如实报告环境失败和未解决的测试。
-合并与发布留给我明确决定。
-```
+遇到问题时，按现象处理：
 
-这里的“无限循环”，是允许有用且已授权的工作持续推进或恢复。每次修复仍有验收终点。
-没有新问题时，监控按事件或计划等待；唤醒频率更高，不代表取得了更多进展。
-初次只选一个模块、一个明确的测试命令，以及自己接受的费用边界。
+| 看到什么 | 下一步检查什么 |
+| --- | --- |
+| 找不到 `$loopx` | 在当前宿主使用的安装环境运行 `loopx workflow-skills --install`，必要时重启宿主 |
+| 只有初始化命令包，没有修复 | 在同一宿主完成上述激活，再接着做原任务，不另建 Goal |
+| Python 或导入错误 | 先修本机 Python 环境，再判断购物车逻辑 |
+| Agent 说“完成了” | 按第 4 步自己运行检查、查看 diff，再接受修复 |
 
-暂停时，让 Agent 暂停这个 LoopX 目标及其对应驱动，并读回两者的实际状态。
-CLI 可以先用 `/goal pause`，App 暂停对应 automation。暂停宿主驱动和暂停 LoopX
-目标是两次不同的状态变化，不要靠删除项目状态停止循环。恢复时打开同一项目，明确
-恢复同一个 Agent 的工作，读已有状态和上次证据，再激活当前宿主的驱动。
+<a id="5-测试检查提交再进入评审"></a>
 
-## 5. 测试、检查、提交，再进入评审
+## 4. 测试、检查、提交，再进入评审
 
 Agent 完成本地练习后，自己再运行：
 
@@ -154,6 +150,59 @@ git show --stat --oneline HEAD
 状态。本地 commit、推送分支、打开 PR、合并 PR 是不同结果。CI 或评审反馈可能带来
 下一轮修复，创建 PR 本身不授予合并权限。
 
+<a id="4-改成持续查-bug-的工作方式"></a>
+
+## 5. 改成持续查 bug 的工作方式
+
+完成小练习后，可以在真实项目使用下面的请求。把范围和测试命令替换成项目实际值：
+
+```text
+$loopx 持续检查 <我负责的模块或目录> 中可复现的 bug。先读仓库说明，确定相关
+测试命令、工作范围和已有预算，在仓库要求的独立分支或 worktree 中工作。
+每个真实问题依次完成：复现、失败回归测试、最小且完整的修复、相关测试与回归、
+按仓库规则准备带 sign-off 的提交和可评审 PR。把结果与下一步写回既有 LoopX 工作。
+没有新证据支持行动时，按 LoopX 调度等待，记录下一次有意义的触发条件，不重复
+执行同样的空扫描。遵守当前额度和费用边界；如实报告环境失败和未解决的测试。
+合并与发布留给我明确决定。
+```
+
+这里的“无限循环”，是允许有用且已授权的工作持续推进或恢复。每次修复仍有验收终点。
+没有新问题时，监控按事件或计划等待；唤醒频率更高，不代表取得了更多进展。
+初次只选一个模块、一个明确的测试命令，以及自己接受的费用边界。
+
+暂停时，让 Agent 暂停这个 LoopX 目标及其对应驱动，并读回两者的实际状态。
+CLI 可以先用 `/goal pause`，App 暂停对应 automation。暂停宿主驱动和暂停 LoopX
+目标是两次不同的状态变化，不要靠删除项目状态停止循环。恢复时打开同一项目，明确
+恢复同一个 Agent 的工作，读已有状态和上次证据，再激活当前宿主的驱动。
+
+<a id="continuous-refactoring"></a>
+
+## 6. 持续重构仓库，提升代码质量
+
+同一套流程也能用于维护：例如重复规则已经出现分歧，模块依赖让局部修改牵动多个
+位置，或关键逻辑难以独立验证。先从你负责的一个模块开始，说明当前维护困难，再
+用前后对照和测试验证改进。可以给 Agent 这样的任务：
+
+```text
+$loopx 持续重构 <我负责的仓库或模块>，提升可维护性。先读仓库说明，复用已有
+Goal、任务归属和待评审 PR，确认写入范围、测试命令、当前额度与停止条件。
+根据真实代码和维护问题选择下一项重构，说明当前问题、预期收益和取舍；优先处理
+重复规则、职责混杂或难以测试的边界。每次交付一个完整、可独立评审的改进，在仓库
+要求的分支或 worktree 中实现。保留外部行为、公共 API、错误语义、配置兼容与权限/
+隐私边界；需要改变这些契约时先说明，按既有流程处理，不混进普通重构。
+运行相关测试与边界回归，展示前后结构、实际 diff 和验证结果，按仓库规则准备提交
+与 PR。已有评审反馈回到原 PR 修正；将采用的反馈、结果和下一步写回原 Goal。
+以维护问题是否得到解决判断质量，不以改名、格式调整、文件数或代码行数充当成果。
+在当前授权和额度内，根据新证据继续下一项；依赖未满足时按既有调度等待。没有值得
+继续的改进、额度用尽或达到停止条件时，说明结果并停止，不重复空扫描。不要合并或发布。
+```
+
+例如，两个导入入口复制了同一套字段校验，可以评估提取共享校验函数，同时保留
+各入口原有的默认值、合法输入和错误行为。前后对照要说明规则如何从两处维护变成
+一处，测试仍覆盖两条真实入口及错误输入；若新抽象反而让调用更绕，就不值得采用。
+这是选题示例，不代表你的仓库已经存在该问题。英文完整示例见
+[长程编程任务指南](long-running-coding-agents.md#example-keep-improving-repository-quality)。
+
 ## 准备成本、持续费用与适用范围
 
 复制练习只需两个文件和 Python 标准库。LoopX 另外需要一次 CLI/技能安装和宿主激活。