diff --git a/README.md b/README.md
index 7a1e62d775..161bf9e6dc 100644
--- a/README.md
+++ b/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
diff --git a/README.zh-CN.md b/README.zh-CN.md
index f3b33c9e43..7ee5af9412 100644
--- a/README.zh-CN.md
+++ b/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
diff --git a/docs/guides/first-bugfix-loop.md b/docs/guides/first-bugfix-loop.md
index 552568c95a..82028406c3 100644
--- a/docs/guides/first-bugfix-loop.md
+++ b/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
diff --git a/docs/guides/first-bugfix-loop.zh-CN.md b/docs/guides/first-bugfix-loop.zh-CN.md
index e82e1c592f..5047379a4e 100644
--- a/docs/guides/first-bugfix-loop.zh-CN.md
+++ b/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/技能安装和宿主激活。
diff --git a/docs/guides/long-running-coding-agents.md b/docs/guides/long-running-coding-agents.md
index 6ea37c61a4..bf92332d6d 100644
--- a/docs/guides/long-running-coding-agents.md
+++ b/docs/guides/long-running-coding-agents.md
@@ -15,36 +15,66 @@ use. A host's native Goal can also be sufficient when continuation stays in
 one host. The [session, Codex Goal and LoopX comparison](../book/en/chapters/02-session-goal-loopx.md)
 explains when project-level state earns its additional setup.
 
+If this is your first LoopX task, run the [small bug-fixing exercise](first-bugfix-loop.md)
+before leaving a real project running. This guide takes the next step: define
+a bounded result, activate the host you use, then recover the same work after an interruption.
+
 ## Install and check the current project
 
-Run the [no-clone installer](installing-loopx.md), then open the project you
-want your agent to work on:
+If LoopX is already installed, keep that installation and start with
+`loopx doctor`. For a new installation, the normal release channel is PyPI.
+Use a Python environment whose console scripts are on `PATH`:
 
 ```bash
-curl -fsSL https://loopx-project.github.io/loopx/install.sh | bash
-export PATH="$HOME/.local/bin:$PATH"
-cd /path/to/your-project
+python3 -m pip install --upgrade loopx
+loopx workflow-skills --install
 loopx doctor
-loopx connect
+```
+
+You need Python 3.11+ and Node.js 22.22.3+ (24 LTS recommended). See
+[Installing LoopX](installing-loopx.md) for pipx, uv, the no-clone installer,
+and upgrades. Choose one installation owner rather than layering another copy
+over a working installation. Open or restart the agent host after registering
+its skills if it cannot see them yet.
+
+Then open the project the agent will work on:
+
+```bash
+cd /path/to/your-project
 loopx status
 ```
 
-`connect` should reuse an existing connection. If state is missing, follow the
-[guided first-goal path](newcomer-command-path.md#one-cli-quickstart); do not
-replace an existing goal just to restart a session. Keep runtime state out of
-version control as described in the installation guide.
+If the project already has a Goal, check its objective and current owner before
+continuing. If state is missing, give the task below to your host and follow the
+[guided first-goal path](newcomer-command-path.md#one-cli-quickstart).
+`loopx connect` creates or connects project state; it is not a read-only health
+check. Do not create a replacement Goal merely to restart a session. Keep
+runtime state out of version control as described in the installation guide.
 
 ## Codex: continue a task across sessions
 
 In Codex App, use the installed `loopx` skill through `$loopx` or `/skills`.
-A useful first task has a bounded result and a clear stopping rule:
+Before starting, decide what a successful result looks like. For a failing test,
+that might be a reproduced failure, a patch, passing relevant checks, and a PR
+ready for review. Name the module or repository the agent may change, the
+existing test command, your spending boundary, and the point where it must stop:
 
 ```text
 $loopx Fix the failing integration test, explain the cause, and prepare a
-reviewable PR. Preserve the existing project goal and record test evidence.
-Wait for my approval before merging.
+reviewable PR. Read repository instructions first; identify the failing test
+and its actual test command. Reuse the existing Goal and assigned owner when
+present; otherwise complete guided setup for this project and host.
+Reproduce the failure, repair its cause without weakening assertions, and
+run the relevant checks. Record the actual diff, test results and remaining
+failures. Follow the project's existing quota and spending boundary; stop
+and report if a necessary boundary is missing. Do not merge or release.
+Stop when the patch and validation are ready for review, or report a concrete blocker.
 ```
 
+Replace “the failing integration test” with the actual test or issue and its
+scope before sending. If another Agent already owns the work, continue through
+that assignment instead of starting a second implementation.
+
 For Codex CLI, start from the project root and use the generated bootstrap
 message:
 
@@ -58,6 +88,17 @@ contracts; they are not interchangeable. The [driver selection table](newcomer-c
 and [Codex App chapter](../book/en/chapters/06-codex-app.md) explain activation.
 Installing LoopX by itself does not keep a closed or unavailable host running.
 
+Check three different outcomes before leaving:
+
+| Checkpoint | Evidence to look for |
+| --- | --- |
+| Project connected | The intended Goal and Agent are identified; existing work is reused |
+| Host activated | The native Goal or App automation is actually active, not merely described in a setup packet |
+| Useful work started | The agent has reproduced the named failure or reports the exact reason it cannot |
+
+These checks establish setup and initial execution. Accept the finished patch
+only after reading its actual test results and diff.
+
 ## Claude Code: track work without losing review state
 
 The installer registers lightweight Claude Code skills. Use `/loopx` with the
@@ -83,6 +124,49 @@ Use the [DeepSeek Harness SDK connector](../integrations/deepseek-harness-connec
 when an outer supervisor needs bounded headless turns instead. It is a
 different integration from the native Web plugin.
 
+## Example: keep improving repository quality
+
+Continuous work can improve maintainability as well as fix bugs. Choose a
+repository or module you own, with a real maintenance problem and checks that
+can detect behavior changes. Use this task in Codex; Claude Code uses `/loopx`
+instead of `$loopx`:
+
+```text
+$loopx Continuously refactor <owned repository or module> to improve
+maintainability. Read repository instructions and reuse the existing Goal,
+work ownership and pending PRs. Establish the write scope, actual test commands,
+current quota and stopping rule. Use code and maintenance evidence to choose
+the next refactoring; explain the problem, expected benefit and tradeoffs.
+Prefer duplicated rules, mixed responsibilities or hard-to-test boundaries.
+Deliver one coherent, independently reviewable improvement at a time in the
+required branch or worktree. Preserve external behavior, public APIs, error
+semantics, configuration compatibility, and permission/privacy boundaries.
+If a contract must change, explain it and follow the existing change process
+rather than hiding it in a refactoring. Run relevant tests and boundary
+regressions. Show the before/after structure, actual diff and check results;
+prepare commits and PRs under repository rules. Address review feedback in its
+existing PR and retain adopted feedback, results and the next action in this Goal.
+Judge quality by the maintenance problem resolved, not renames, formatting,
+file counts or lines of code. Continue from new evidence within current
+authority and budget; wait under the existing scheduler when dependencies
+are unmet. Stop and report when no worthwhile improvement remains, the budget
+is exhausted or the stopping condition is reached. Do not merge or release.
+```
+
+For example, two import paths may duplicate field validation. A useful
+refactoring could consolidate the shared rules while retaining each entry's
+defaults, accepted input and error behavior. Compare where a rule change must
+be made before and after, and test both real entry points, including invalid
+input. Reject the abstraction if it makes the callers harder to understand.
+This is an illustrative target, not a finding about your repository.
+
+Keep each result in its original Goal and PR so review feedback can change the
+next decision. A passing suite alone does not establish improved maintainability;
+explain the structural benefit and its costs. If later work requires a pending
+review, use the existing wait rather than starting overlapping changes.
+The [Chinese walkthrough](first-bugfix-loop.zh-CN.md#continuous-refactoring)
+contains the same task in Chinese.
+
 ## Resume after an interruption
 
 Open the same project and read `loopx status` before issuing another task.
@@ -104,6 +188,12 @@ A transcript saying “done” is not a substitute for current tests, review or
 accepted evidence. See [long-task operations](../operations/long-task-cadence-policy.md)
 for waiting, budgets and continuation.
 
+If work appears stuck, distinguish a host that is unavailable from a task that
+is correctly waiting for CI, review, quota or a recorded decision. Inspect that
+dependency before restarting anything. To pause, pause both the LoopX Goal and
+its host driver and read back their states; the [exercise's pause instructions](first-bugfix-loop.md#5-turn-the-workflow-into-a-recurring-bug-hunt)
+explain the two separate controls. Deleting state is not a pause mechanism.
+
 ## What to verify before leaving a task running
 
 - `loopx status` shows the intended goal and a useful next action.
@@ -111,6 +201,20 @@ for waiting, budgets and continuation.
 - The task has an acceptance check, spending boundary and stopping rule.
 - Merge, publication and other consequential operations retain explicit approval.
 
+## Setup effort and ongoing cost
+
+Initial setup adds CLI/skill installation, project connection and host
+activation. Keep the same installation owner for upgrades, then verify skill
+discovery and the host driver again. Reopening a project should reuse its
+existing Goal rather than repeat setup.
+
+Agent turns consume the host's model allowance and the project's test, build
+or external-service resources. Recurring checks add wakeup work even when no
+patch is produced. Cost depends on cadence, context size, retries and provider
+terms; this guide does not establish a fixed price or a saving. Use existing
+quota and scheduled/event-driven waits. A shell `while true` or a more frequent
+heartbeat does not establish better outcomes.
+
 For examples rather than setup, explore the
 [public application scenarios](https://loopx-project.github.io/loopx/blog/application-scenarios/)
 and [long-horizon terminal study](https://loopx-project.github.io/loopx/benchmarks/lhtb/).
diff --git a/docs/guides/personal-workspace-user-guide.md b/docs/guides/personal-workspace-user-guide.md
index 3f747de6fa..acdae36b6c 100644
--- a/docs/guides/personal-workspace-user-guide.md
+++ b/docs/guides/personal-workspace-user-guide.md
@@ -1,47 +1,94 @@
-# LoopX 个人工作区控制台（Personal Workspace Console）使用指南
+<a id="loopx-个人工作区控制台personal-workspace-console使用指南"></a>
 
-LoopX 控制台是为工程师与 Agent 深度协作打造的统一本地工作台。它将分散在不同会话、话题与后台运行中的 Agent 任务统一汇聚，提供**「LoopX 管家全局总览」**、**「Goal 4 列任务看板」**、**「轻量悬浮会话托盘」**、**「先预览后确认安全门禁」**与**「Lark / 飞书话题直连」**。
+# LoopX 个人工作区使用指南
 
----
-
-## 🎬 30 秒产品发布演示视频
-
-<video controls width="100%" poster="https://loopx-project.github.io/loopx/docs/assets/personal-workspace/guide_manager_overview.png" style="border-radius: 12px; box-shadow: 0 8px 30px rgba(0,0,0,0.12);">
-  <source src="https://loopx-project.github.io/loopx/docs/assets/personal-workspace/loopx-dashboard-launch.mp4" type="video/mp4">
-  您的浏览器暂不支持直接播放视频，可下载 <a href="https://loopx-project.github.io/loopx/docs/assets/personal-workspace/loopx-dashboard-launch.mp4">MP4 视频文件</a> 进行查看。
-</video>
+在 LoopX 工作区里，你可以交代任务、查看 Agent 的进展、处理需要你决定的事项，
+再检查交付结果。**Goal 是你想要的结果，Todo 是为实现它而推进的具体工作。**
+管家汇总多个 Goal；进入一个 Goal 后，再看它的任务、对话和成果。
 
-> 💡 **视频高光**：终端一键启动 ➔ 管家 4 泳道任务流 ➔ 快捷指令浮动托盘 ➔ 4 列看板与智能「转为 Task」清洗 ➔ 飞书话题直连 ➔ Brutal 野兽派主题切换。
+第一次使用，先按第 1 节完成一个小任务。第 3–4 节说明日常查看与跟进，第 6 节
+按需接入飞书，第 8 节解释操作确认与结果核对。演示视频放在文末，不必看完视频再开始。
+想从代码修复入手，也可以先做[查 bug 练习](first-bugfix-loop.zh-CN.md)。
 
 ---
 
 ## 🚀 1. 快速启动与访问
 
-在本地仓库或已安装 LoopX 的终端中执行：
+先按[安装指南](installing-loopx.md)准备 LoopX、Python 3.11+ 和 Node.js 22.22.3+
+（推荐 24 LTS）。普通使用不需要克隆源码或启动前端开发服务器。
+在你要使用的项目目录打开终端，执行：
 
 ```bash
+loopx doctor
 # 启动本地 Dashboard 控制台（默认自动打开浏览器）
 loopx dashboard
 ```
 
+若 `doctor` 报告缺少依赖，先修复它指出的问题。若缺的是 Agent 登录或运行环境，
+按下文「Agent 运行环境未就绪」处理；看到页面不等于 Agent 已可执行。
+
 安装版会在同一个进程中启动打包后的工作区、状态投影和 Agent Chat，不需要另开
 终端运行 `loopx serve-status`。命令默认自动打开浏览器；无界面启动可使用
 `loopx dashboard --no-open`，并访问命令实际打印的 URL。默认地址为
 `http://127.0.0.1:8767/chat/`。
 
-可用下面两条命令验证页面和状态投影都来自同一个进程：
+<details>
+<summary>可选：从终端检查页面和状态是否可读</summary>
+
+下面使用默认地址；若启动命令打印了其他端口，替换为实际地址。两项均读取本地服务，
+不创建 Goal，也不启动 Agent：
 
 ```bash
 curl -fsS http://127.0.0.1:8767/chat/ >/dev/null
 curl -fsS http://127.0.0.1:8767/status.json
 ```
 
+</details>
+
 > 💡 **两种入口可共存**：`loopx dashboard`（浏览器 / PWA）与 Tauri 原生桌面壳
 > 都会复用已经在运行且版本匹配的 LoopX Chat 服务。先开 dashboard 再开桌面壳，
 > 或先开桌面壳再执行 `loopx dashboard`，两种顺序都可以；当桌面壳已经启动时，
 > 也可以直接访问 `http://127.0.0.1:8767/chat/` 使用浏览器 / PWA，无需再启动一套
 > 服务。
 
+### 第一次使用：完成一个小任务
+
+先用你愿意让 Agent 读取的项目，体验一次「提出要求 → 确认 → 执行 → 核对结果」。
+已有同一目标的 Goal 时直接打开它，不重复创建。
+
+1. 点击 **创建 Goal**（或侧栏 `+`），可以用下面这组内容填写：
+
+   - **目标：** 梳理这个项目的启动与测试方式。
+   - **完成标准：** 给出启动命令、测试命令及对应文件依据；没有找到明确说明时如实说明。
+   - **执行边界：** 只读取项目文件，不启动项目、不运行测试、不修改文件、不调用外部服务；回答后停止。
+
+2. 选择正确的**工作目录**，将**执行权限**设为「只读」，点击**检查配置**。
+   预览应写明目标、完成标准、实际目录和权限；先检查这些内容。检查配置仍未创建 Goal。
+3. 确认预览后点击**创建 Goal 并开始首轮**。这一步会创建 Goal 和首个 Todo，并让
+   选定 Agent 开始首轮推进。随后进入该 Goal 的**对话**查看实际回答；排队与正在执行
+   是不同状态，失败时先看原错误，不重复创建同一个 Goal。
+4. 按回答给出的文件依据核对命令。这个任务没有运行测试，回答也就不能声称“测试通过”。
+   要让 Agent 继续验证或修改代码，再在原 Goal 中说明新增范围与权限，沿既有流程处理。
+
+跑通的标志是：找到了正确的项目、Agent 返回了有依据的说明、你能核对它的结果。
+不是只看到一张 Goal 卡片或“已完成”标签。没有可用执行器、目录不可用或来源只读时，
+先处理页面报告的具体问题，不把本机新建 Goal 当作远端工作的替代。
+
+**准备与费用：** 本地页面与 Agent 执行是两件事。创建首轮或发送执行任务会使用所选
+宿主的模型额度和工具资源；周期任务还会增加唤醒与检查开销。先用这个有终点的小任务，
+确认既有额度、运行环境和停止条件，再考虑定时任务。升级沿用原安装渠道；运行时登录、
+飞书连接等按各自设置维护，不需要为了开始而全部配置。
+
+English: Start with one bounded task in a project you choose. Create a Goal with
+an objective, completion criteria, workspace and **Read only** permission; review
+the configuration before **Create Goal and start first run**. For example, ask
+for the project's documented start/test commands and their file references,
+without running tests or changing files. Inspect the returned references rather
+than treating a created card as a completed result. Reuse an existing Goal for
+the same work. Agent execution uses the selected host's allowance; recurring
+work adds wakeup/checking costs. Neither opening the page nor creating a Goal
+proves that its host is active or that its result passes acceptance.
+
 ---
 
 ### 1.1 Agent 运行环境未就绪 / When no Agent runtime is ready
@@ -619,10 +666,16 @@ replace channel notifications such as Lark. An optional reminder (a user action
 
 ## 🛡️ 8. 安全与不可逆操作保护
 
-LoopX 控制台严格遵循 **Human-in-the-Loop（人类介入）安全模型**：
-1. **先预览，后确认**：任何会写入 Goal 状态、修改配置或执行外部变更的指令，都会先在界面弹出 **Typed Action 预览卡片**，明确展示影响范围与待填参数；
-2. **用户点击确认后才下发**：杜绝 Agent 自行执行未授权的高危操作；
-3. **操作回执（Receipt）**：每次操作执行完毕均会生成不可篡改的带时间戳回执，随时可溯源。
+需要你确认的操作使用各自的预览与确认流程。以创建 Goal 为例：
+
+1. **先检查范围：** 预览列出目标、目录、执行权限及预期影响；内容不对就返回修改。
+2. **再确认具体操作：** 创建 Goal 的确认会开始首轮推进。合并、发布、删除、支付等
+   受保护操作仍按各自授权流程处理；批准一项操作不会顺带批准另一项。
+3. **核对实际结果：** 查看操作回执和刷新后的状态。预览、请求被接收、执行完成、
+   产物通过验收是不同阶段；失败或结果未知时保留这个区别，不能只凭提示文字认定成功。
+
+Agent 在既有授权内推进普通任务，不等于每一步都要你重新点击确认。阅读页面、筛选任务、
+下载快照也不会增加执行权限。只读来源保留其限制，截图、导出和对外分享仍需检查是否含私有内容。
 
 
 ### 键盘快速导航 / Keyboard quick navigation
@@ -670,3 +723,16 @@ Saving reuses the existing readback without running an Agent, invoking validatio
 recording adoption or changing the Goal. The file is a local copy of that version,
 not a promise of continuing acceptance. If the reader becomes unavailable, use its
 existing refresh/retry before downloading again.
+
+---
+
+## 🎬 30 秒产品发布演示视频
+
+<video controls width="100%" poster="https://loopx-project.github.io/loopx/docs/assets/personal-workspace/guide_manager_overview.png" style="border-radius: 12px; box-shadow: 0 8px 30px rgba(0,0,0,0.12);">
+  <source src="https://loopx-project.github.io/loopx/docs/assets/personal-workspace/loopx-dashboard-launch.mp4" type="video/mp4">
+  您的浏览器暂不支持直接播放视频，可下载 <a href="https://loopx-project.github.io/loopx/docs/assets/personal-workspace/loopx-dashboard-launch.mp4">MP4 视频文件</a> 进行查看。
+</video>
+
+视频展示总览、任务看板、对话托盘、飞书连接和主题切换。
+也可以直接[打开演示视频](https://loopx-project.github.io/loopx/docs/assets/personal-workspace/loopx-dashboard-launch.mp4)。
+具体按钮与状态以当前安装版本和上文操作说明为准。