[loopx-agent]

Goal And Delivered Outcome

Readers need a complete first-use path after following the README links. The bug-fixing tutorial previously introduced recurring work before the exercise's verification step; the coding guide led with a different installer from the current installation guide; and the Workspace manual opened with a feature list and video rather than a first task.

This change improves the linked content as well as its discovery:

• Bug-fixing tutorial (English and Chinese): verify and commit the exercise before the optional recurring workflow; show concrete wrong/right outputs, distinguish terminal commands from agent messages, and add symptom-based recovery. Preserve the old section anchors.
• Long-running coding agents: align normal installation with PyPI, distinguish read-only status from connecting project state, and explain the task boundary, actual host activation, interruption recovery and ongoing costs.
• Continuous repository refactoring: add copyable English/Chinese task examples, an illustrative shared-validation refactoring, and instructions to retain behavior, permission/privacy boundaries, review feedback, budget and stopping rules. Judge the maintenance problem resolved instead of code churn.
• Workspace manual: start with plain Goal/Todo definitions and a concrete read-only project task; explain what to inspect before confirmation and how to judge the returned result. Move the optional launch video after the reference material and distinguish receipts from verified outcomes.
• README discovery: keep the three purpose-specific guide links in both quick starts, with explicit cross-language labels.

Outcome basis: maintainer request to surface useful onboarding guides and improve their content. Intended base: main; no issue closure claimed.

Author Declaration

• Written by: model_agent — OpenAI GPT-6 / Codex.

Implemented against

• No written specification; the request in this PR is the basis. Documentation placement and visual evidence follow docs/development/documentation-layout.md and docs/development/design.md at 10c84d1c0c97820499db595be55023283a28fa08.

Criterion	Disposition	Path	Check
Link existing practical guides directly from quick start	implemented	README.md, README.zh-CN.md	Six Markdown targets resolve to tracked files; rendered GitHub hrefs checked
Explain each guide's purpose without duplicating its content	implemented	Both quick-start paragraphs	Reviewed the first exercise, setup/recovery guide, and relevant App/dashboard instructions
Support both README languages and identify cross-language destinations	implemented	English exercise / Chinese exercise; language-qualified guide labels	English and Chinese rendered views at desktop and narrow widths
Provide an actionable continuous-refactoring example	implemented	docs/guides/long-running-coding-agents.md, docs/guides/first-bugfix-loop{,.zh-CN}.md	English/Chinese content review, strict site build, stable cross-language anchors and desktop/narrow readback; no sustained refactoring run claimed
Complete the local exercise before introducing recurrence	implemented	docs/guides/first-bugfix-loop{,.zh-CN}.md	Existing six-check fixture: two initial failures, zero after an isolated temporary repair; moved recurring prompts unchanged; old/new anchors checked
Make setup, execution, recovery and costs actionable	implemented	docs/guides/long-running-coding-agents.md	Installation guide and CLI connect registration checked; strict docs build and rendered-page inspection
Provide a concrete first App task with accurate confirmation and result boundaries	implemented	docs/guides/personal-workspace-user-guide.md	Checked against existing Goal form, preview request builder and localized confirmation labels; rendered documentation inspected

• Self-check: read the selected guide content and applicable documentation instructions; inspected the six-file diff and published GitHub rendering. Read the complete linked guides and relevant owning CLI/UI sections. The task-creation example was checked against source; no live/private Goal was created for validation. No runtime behavior changes.

Scope And Continuation

• Complete within this scope: two README entry paths and all three linked guide families (four guide files, including both exercise languages). No successor needed.
• Scope fit: existing Markdown links are sufficient; no new abstraction, duplicated guide, or layout component is introduced.

Validation

• Tested revision: 5e09a3394d110c5a4cd3179b050124219974e9db.
• Run state: finished.
• Input classes: public_fixture (published repository README and guides).

Check kind	Result	Public-safe evidence / limitation
static	passed	git diff --check; scoped check resolves all six guide links and confirms the rest of both READMEs is unchanged; all 44 relative links/images in the four guide files resolve, fences are balanced, and legacy/new exercise anchors and the new cross-language refactoring targets exist
static	passed	Source-checkout loopx check with the six explicit changed-file scan paths: public-boundary scan completed with no findings; subsequently changed guide files were scanned again
static	blocked	The combined loopx check health result is not green: the isolated check environment has no registry. This is distinct from the completed public-boundary scan
static	passed	PYTHONPATH=. uv run --no-project --python 3.12 --with-requirements docs/requirements-docs.txt mkdocs build --strict with output outside the checkout; complete documentation site built successfully. Existing INFO-level link notices elsewhere are not claimed resolved
unit	passed	Existing public exercise copied to a temporary directory: 6 checks / 2 failures before, 6 checks / 0 failures after a minimal temporary repair; original checks, negative-price rejection and input preservation retained. Repository fixture remains intentionally broken
manual	passed	All four guide files inspected at 1440×1000 and 390×844 during the guide polish; the current refactoring sections and updated Chinese opening were checked again at both widths. Ordered headings, code/table wrapping and the Workspace first-task section checked. Earlier captures are identified below
real_entrypoint	failed	Earlier head 9f32985599910e520b76da1c21df0c453db4ae63: Release Artifacts browser smoke timed out waiting for the Goal overview refresh button in goal-work-map.mjs. Base attribution has not been established; this documentation-only PR does not repair that path
integration	not_applicable	Documentation text and links only; no runtime, authority, scheduling, or CLI behavior changed

• Coverage and gaps: checks cover the README entry paths, the full four-guide content, links, exercise behavior and rendered presentation. No live host-activation, new Goal-creation, or benchmark-effectiveness claim; source checks for existing UI instructions are separate from a live end-to-end run. The isolated registry is absent, and the earlier-head packaged browser-smoke failure above remains recorded. New-head CI is separate from the completed static/manual checks.

Frontend / Visual Evidence

• UI impact: changed (rendered README and guide content).
• README before: 10c84d1c0c97820499db595be55023283a28fa08; guides before: e662272326bc20a4f7f72d6239a1f10a9d622d1d.
• Current guides and refactoring captures: 5e09a3394d110c5a4cd3179b050124219974e9db. The coding/Workspace opening and Workspace-task captures retain 67a2df9e6e7fd0af8e383c4f9108bca9dddcc9f7; their displayed content is unchanged. The Chinese exercise opening is refreshed at the current head. README captures below are from e662272326bc20a4f7f72d6239a1f10a9d622d1d; both README blobs remain unchanged at the current head.
• Boundary / source data: GitHub's actual Markdown renderer with public repository content; no local preview or private data.
• Preview: English README, Chinese README.

Guide previews: bug-fixing exercise (EN), 查 bug 练习, coding agents, Workspace.

Continuous-refactoring examples

New content; before: N/A for these sections. This is a documented task example, not evidence of a completed repository refactor or measured maintainability gains.

Preview: English example, 中文示例. The explicit Chinese anchor works in GitHub and MkDocs.

Narrow views (390×844):

Guide opening viewports in GitHub (1440×1000):

Guide	Before	After
Bug-fixing exercise (Chinese; English inspected separately)
Long-running coding agents
Workspace manual

Narrow guide views (390×844):

Workspace first-task instructions (public documentation, not a live execution screenshot):

English onboarding viewport, before and after (1440×1000):

Chinese onboarding viewport, before and after (1440×1000):

Narrow onboarding views (390×844):

• Attention review: one recommended exercise gives newcomers a clear starting point; two compact, purpose-labeled items distinguish using an existing project from using the App. The install command and first task stay first, with no additional card or competing heading.
• Craft review: reuse existing Markdown styling, bring the first task before optional reference material, and shorten the Workspace title for narrow screens. Existing failure, permission, privacy and recovery instructions remain. No runtime UI, colors, motion or controls changed.

Type of Change

• Documentation update

LoopX Area

• Public docs or presentation surface (README and guides)

Technical Direction

• N/A — bounded onboarding-content and discovery improvement.

Shared-authority RFC fixture impact

N/A — no shared-authority, runtime-routing, or protocol change.

Boundary Checklist

• Diff, description, and attachments contain public repository content only; no private state, credentials, raw traces, internal links, or machine paths.
• No maintainer-owned benchmark work duplicated.
• Change remains scoped to the onboarding-guide request.
• No paired RFC changed.
• Visual evidence included above.
• Every commit includes a DCO Signed-off-by trailer.