[ymote]

Add a walkthrough from the Python CLI and script template through runtime preparation, bundle admission and publication. Correct run --detach guidance and check behavior in the English/Chinese README and contributor instructions.

The guide maps the sketch kit, image library, pipeline scripts, default stages, fail-fast receipts and human screenshot/restamp/sign/submit steps. It distinguishes the system peer session from human conversation contexts, qualifies Unix workspace tools, and states that the current authoring pin lacks sys.chat/ChatEntry. Runtime versions are read from lock files; companion guide links resolve before merge.

Writing revision for junior Rust readers: Define peer, slug, session, shared context, event sink and blackboard within one request. Trace the five default image stages through concrete inputs and outputs before optional stages.

Validation: six CLI tests and all five example plans pass; the repository link checker reports zero failures; relative file links, remote companion links and whitespace pass. Native UI, provider conversations and publishing credentials were not exercised.

Writing assessment after parallel revision and a separate review: 4.5/5 (A−), considering beginner orientation, terminology, worked examples, organization and consistency. This supersedes the earlier combined technical/writing score where present; it is our assessment, not an external approval.

Companion PRs:

• OctoSense-org/OctoSense
• OctoSense-org/OctoSense-App-Hub
• OctoSense-org/Octoscript-Makepad
• octos-org/octos

[ymote]

Review: needs changes before merge

Accuracy: B. Writing: C.

Checked against main caa5d36 (the PR base) and the current lock pin cb66de07 (makepad 1f3b1ded, Octoscript dbd48cfb). Correct: tools/octo binary lookup, run/--detach, shot waiting for two identical frames, check and stamp handling, the flow.py artboard, scene count, locales and stages, card-host registering no services, offered_tools defaults, and the sys.chat caveat (Octoscript #53 is after dbd48cfb). check-links.py and test_octo_run.py pass.

The README and AGENTS.md corrections (--detach, check forwarding, where L0 lives) are good as they are.

Accuracy

1. Cross-repo links. §2 (:47-50) and §7 link to App Hub docs/CODE-WALKTHROUGH.md and OctoSense docs/architecture-walkthrough.md, which only exist in App Hub #55 and OctoSense #275. check-links.py skips external URLs, so CI won't catch this. Merge after those.
2. Parts of the flow are missing.
   • kits/sketch isn't mentioned.
   • Neither is flows/image-lib.
   • Neither is beauty-pipeline.sh, which image-to-appcard-flow.sh actually calls.
   • The hand-off stops at check. flows/README.md defines stamp → check → card-host → screenshot (human) → restamp → sign (human) → submit (human). Name the human steps.
   • §8 should give the default --stages (intake,semantic,compile,bundle,service-test).
3. Snapshots. :5 ("Design Flow caa5d364 and App Hub 41bc959") and the full lock hash at :270 will go stale; Octoscript-Makepad main is already 10 commits past cb66de07. "At the reviewed shell snapshot" (:194) and "At this snapshot" (:211) don't say which one. Link the pin files.
4. §1 heading. "Three kinds of source, two kinds of agent" doesn't match its table, which has seven mixed rows including the CLI and octos.
5. Exit status. In the README, "forwards exit status" has one exception: if hub stamp fails, cmd_check returns that status and never runs hub check.

Writing

The facts are dense and correct, but the voice is a reviewer's, not a manual's.

Where	Current	Suggested
:3	For a junior Rust developer, begin with the executable path…	This repository is a Python harness. The Rust runtime lives in App Hub and the agent kernel in octos.
:5-7	This review follows… unverified in this review…	Delete.
:306-312	Review verification (2026-10-01)…	Delete; put it in the PR description.
:90	A file existing is not a visual review: open the capture.	Open the PNG and look at it.
:95-96	…so the gate output is forwarded, not necessarily the CLI's only output	check prints the hub check output and exit status, plus its own progress lines.
:136-137	…the walkthrough does not claim it is publication-ready	The untouched template fails the full gate until the listing and screenshots are done.
:264-265	…a repository code review does not need to invent app screenshots	Delete.
:230	…a peer identity, conversation context, running future and worker thread are different objects	One peer can hold several conversation contexts over its lifetime; it is not a thread or a task.

Also:

• :192 shows <app> as raw HTML entities. Use `Ask <app>`.
• The AGENTS.md phrase "without pretending to complete an app-authoring flow" has the same reviewer voice.
• README "Code walkthrough for Rust beginners" → "Code walkthrough".
• Two over-long lines: README.md ("…Octoscript L0 (page.card). Top-level…") and §7.

zh-CN

• README.zh-CN.md adds the "main.splash vs L0 parsing path" sentence in two places; the English has it once.
• "从 Python CLI…追踪到 App Hub 与 OctoSense Shell" reads like a translation. Try "沿着 Python CLI、脚本模板…一路讲到 App Hub 与 OctoSense Shell".
• 封装层进度和 listing 占位符提示 → 清单（listing）占位提示.