[ymote]

The architecture references mixed historical behavior with current implementation. Add source-linked walkthroughs that follow desktop/Home/ROM startup, native and script hosting, system and app agents, human conversations, app data, tool routing, and concrete thread/task ownership. English and Chinese cover the same flows and diagrams; README and contributor instructions point to the relevant source paths.

Review corrections include the complete approval order, native process peer links, all seven system-app tool rosters, Glance source/script cards and notifications, working companion links, and the implemented Calendar versus planned Mail-send example. Integrate current main, including the related consent and Glance documentation from #268 and #271. Correct the unsupported script-tool error: opening the app cannot enable the missing dispatcher. Dependency pins and tool behavior are otherwise unchanged.

The Glance correction distinguishes shipped notice/Calendar cards (no chat) from the Mail demonstration (canned replies), and reuses #271’s corrected card-flow image. Resolve the overlapping README and AI-services changes after merging #268 and #271, preserving the reviewed bilingual explanations and newer runtime changes from main.

Writing revision for junior Rust readers: Use a desktop Calendar question to connect the two conversation lanes, host-service data access and Tokio scheduling. Define terms at first use, split dense explanations, repair the app table, and align the overlapping Glance/consent sections in English and Chinese.

Validation:

• Setup with --check --cargo, native manifest generation, root/phone offline Cargo metadata and the ROM local-path test pass.
• Kernel/app-peer tests pass: 132 unit/scripted-connector tests exercised. The 22 optional real-kernel functions return early without a binary; they are not integration evidence.
• From phone/, cargo test --locked --features mobile-apps -p octosense-shell host_tools passes all 62 tests.
• Relative file links across the changed Markdown files resolve; local heading links, published companion guide URLs, bilingual section/command/diagram parity and whitespace checked.
• Final integration head b1462bc passes setup with Cargo validation, 232 local links/anchors, 32 Markdown tables, and whitespace/conflict checks; main’s runtime changes are preserved.
• GUI, real-provider, mobile/ROM build and device execution remain unverified; recipes say so.

Source review was split across three parallel reviewers, followed by cross-review of the revised guides. Two factual review suggestions were corrected against code: host-managed WebSocket is conditional on Talk to Octos, and the runtime starts a barrier-waiting task before turn admission.

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-App-Hub
• OctoSense-org/OctoScript-App-Design-Flow
• OctoSense-org/Octoscript-Makepad
• octos-org/octos

[ymote]

Review: needs changes before merge

Accuracy: B. Writing: C+.

Checked against main at 3006b53 (after #272 and #273) and the current pins (octos ae230ce0, makepad e29a0eaa, App Hub 58c3c8ae). Individual facts hold up: kernel runtime threads and stack size, the broker runtime, Mail's tools.json, app_tool_unavailable, the 10-minute deny-on-expiry. The gaps are in the overall picture.

Accuracy

1. Approvals are underdescribed. architecture-walkthrough.md:142 says required approvals are "resolved through the shell". crates/shell/src/approvals/mod.rs has a router, standing rules the person sets in advance, confirm: app sheets drawn by the owning app, an owner-only audit log, and developer mode, which overrides every approval. Line 175 ("silence never becomes consent") is true but misleading without rules and developer mode.
2. Tool routing covers one path. §7 follows host-service executors only. host_tools/mod.rs:5-34 also routes to process apps over peer_link, to in-process modules via set_tool_executor, to the Terminal for terminal.run (the way the system agent runs commands, approved per command), and to files.*, dev.run and the toolbox. A routing table would help.
3. Process apps and peer_link. :33 and desktop/docs/code-walkthrough.md:86 say a process app is independent of any octos peer. peer_link/mod.rs gives native apps a link to their own agent over the same hub socket. No current process app is granted octos, so the statement holds today, but it hides the mechanism.
4. Glance predates #273. :35 describes Glance as L0 cards only. It now accepts script cards, has notify toasts, and supports glance::dismiss.
5. Missed stale claims. README.md:280 (and zh-CN) still says only the person answers a peer's tool approvals. apps/README.md:36 (and zh-CN) still calls AppCard "the one native app". The PR fixes both claims elsewhere.
6. Pinned snapshots. c19da8d, ae230ce0 and "inspected on 2026-10-01" (:5, zh :5, architecture.md intro) will be wrong after the next repin. Point at the Cargo.toml pins instead.
7. Companion links (:22) 404 until App Hub #55, Design Flow #143, Octoscript-Makepad #69 and octos #2669 merge.

Writing

The content is solid, but it reads like an audit report rather than documentation.

• Remove the review artefacts: :37, all of §11 (:212-223), code-walkthrough.md:10-14,53,101,267, zh :163-169, and "本次文档审查未验证". Who checked what belongs in the PR description.
• About 27 "X is not Y" sentences, mostly answering questions nobody asked. State what the code does.
• Drop the "junior Rust" labels and the Rust primers (:179, code-walkthrough.md:29-36).
• The new AGENTS.md sections read like a reviewer's checklist. Contributor guidance should say what to do.

Suggested rewrites:

Where	Current	Suggested
:5	An ADR describes a decision, not proof that all its steps execute today.	ADRs record decisions; some steps are not implemented yet (see §11).
:63	Dropping a Rust Connection is not deleting the peer's saved memory.	A peer's memory outlives any Connection.
:71	The UI is not awaiting the model on its drawing thread.	Delete; the previous sentence says it.
:173	Five negations in a row	Questions reach the person only. Scripts get no system-agent API, and toolbox calls are ordinary tool calls.
:210	…an identity and isolation rule, not one Tokio task or thread per agent.	One peer per app and account is an identity rule. It says nothing about threads or tasks.
code-walkthrough.md:228	Observe that ordering when debugging a missing Settings update.	If a Settings update goes missing, check this ordering first.
README	For junior Rust developers, [From an app window…]	New to the codebase? Start with [From an app window to an agent turn].

zh-CN

It reads naturally, but has drifted from the English:

• :14 uses 降级 ("downgrade") for "lowering". Use 下降为 or "lower 到".
• :128 uses 输入面板 for "sheets". Use 确认面板.
• Both Mermaid diagrams are missing (the §5 sequence diagram and the §10 flowchart).
• The desktop walkthrough is about half the English length.

Merge order

Merge this first; the other four link to docs/architecture-walkthrough.md.