[ymote]

Add a source-linked walkthrough of UI nodes, checked evaluation, L0 realization/lowering, AI text marks, widget translation and the native hosts. Correct README/contributor guidance about main-VM mounting and align English/Chinese run guidance.

The guide names the external L0 and chart crates and distinguishes renderer budgets, beauty-host's final checked evaluation and kit-host's final unbudgeted evaluation. Both kit-host and Flutter have current_source functions; their distinct lookup paths are described. Also correct kit-host's obsolete source comment about an upstream prerequisite and isolate mounting. No executable behavior changes.

Writing revision for junior Rust readers: Follow a small text label from source through UiNode and generated Label to native mounting. Define realization, lowering and kit bindings; move limits and preview replacement details after the normal path.

Validation: runtime manifest pins, binary declarations, relative file links across framework/octos, the published companion guide and whitespace checked. Confirmed the Rust diff is comment-only. Independent source review verified call order, budgets and VM ownership. No native GPU/device/build result is claimed.

Writing assessment after parallel revision and a separate review: 4.6/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-App-Design-Flow
• octos-org/octos

[ymote]

Review: needs changes before merge

Accuracy: B+. Writing: C+.

Checked against main 8f103d0 (the PR base). The pins match the org: makepad e29a0eaa and Octoscript 5991dfae, the same as OctoSense main. Removing the old "one upstream PR / isolate: false" story is the right call. The main-VM mount (main.rs:616-623, beauty.rs:140-166), crate dependencies, binaries, BEAUTY_REQUEST fields and the L0 path all check out.

Accuracy

1. ai::expand_ai_marks is missing. Since #68, to_makepad_ui and to_makepad_l0_ui run ai::expand_ai_marks (lib.rs:62, lib.rs:86) before emitting widgets. The walkthrough says translation only emits widget source. Step 2 should also name ai.rs, state.rs and units.rs, not just node.rs.
2. current_source is in the wrong place (walkthrough:97-99). It's in a kit-host paragraph, but current_source exists only in apps/flutter-samples/src/lib.rs:214. kit-host has current_route (file, then SPLASH_ROUTE, then "button").
3. Stale comment. apps/kit-host/src/main.rs:76-81 still says the kit needs the upstream PR and mounts on an isolate. The new docs tell readers not to repeat that; update the comment in this PR.
4. Budgets. Only beauty-host uses eval_checked; kit-host uses eval_with_append_source with no budget (main.rs:617). The AGENTS.md line that budget-exhausted input "must fail as a whole" reads as if both hosts enforce it.
5. Missing crates. makepad-d3, makepad-plot and the external octoscript-ui-l0 crate aren't mentioned. realize_with_state, InstanceStore and kit_pack come from octoscript-ui-l0, and readers will look for them here.
6. Smaller issues:
   • walkthrough:130: octoscript-node::state → octoscript_node::state.
   • walkthrough:3-6 hard-codes 8f103d0c…; point at runtime.json instead.
   • walkthrough:135 links to OctoSense docs/architecture-walkthrough.md, which only exists in OctoSense #275.

Writing

There are no buzzwords. About a third of the text is disclaimers and review leftovers, though, and cutting them would shorten the doc by roughly 30%.

Where	Current	Suggested
README.md:12	junior Rust code walkthrough	code walkthrough (zh: 面向初级 Rust 开发者的源码导读 → 源码导读)
walkthrough:3	This guide is for a Rust developer new to OctoSense.	Delete.
walkthrough:84, :120	Commands below are source-derived recipes, not a record of a GUI/device run. / This documentation pass did not run a GPU preview.	Delete both.
walkthrough:11-13	A rendered card does not acquire an AI agent, network access, or an app database just because it renders here.	Agents, network and storage come from the host; the renderer only draws.
walkthrough:41	It is the portable data boundary; it is not a window or a running agent.	It is the portable data boundary between backends.
README Status	not a new device verification of this checkout	Device results above predate the current pins; re-run native acceptance before shipping.
AGENTS.md:17-18	Do not repeat historical claims that they must wait for an isolate: false field…	Delete; line 16 already describes the mount correctly.
AGENTS.md:25-26	Record unavailable GPU/device checks honestly. Do not label structural tests as visual acceptance.	If you could not run the native check, say so in the PR.

Also:

• Pick one spelling, Octoscript or OctoScript (README :7 vs :9).
• In zh-CN the run recipe sits under 状态与验证范围, while the English has it under native validation. AGENTS.md asks for the two to stay aligned.