[ymote]

Add a source-linked walkthrough from manifest admission through signed catalog installation, contained UI, service pumping and the shell's app-agent bridge. Update English/Chinese README entry points and contributor guidance.

The guide now includes all crates and supporting paths, explains the top-level Cargo patch versus crates.io app contract, separates accepted metadata from implemented agent operations, and traces consent, Unix workspace read tools and cross-app admission limits. Review prose and fixed source snapshots were removed; companion links resolve on published documentation revisions.

Writing revision for junior Rust readers: Move first-run instructions before the crate inventory. Follow a saved-notes request through conversation routing, workspace reads, grants and reply delivery; keep reference details after the teaching path.

Validation: Relative file links across Hub/Design Flow, Design Flow's link checker and whitespace checks pass; companion URLs resolve. Source review checked policy limits, service queues/timeouts, store verification and shell executors. No native/provider/device run is claimed.

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

[ymote]

Review: needs changes before merge

Accuracy: A−. Writing: B−.

Checked against main 41bc959 (unchanged since the PR base) and OctoSense main 3006b534. The App Hub claims all hold: store and system limits, host-service timeouts and queue caps, RefuseAllSignatures in card-host, catalog sequence and freshness rules, may_run, and the agent-declaration table. That table is the best part of the doc. The OctoSense-side references (script_apps.rs, cardapp.rs:195, app-peers/storage.rs) check out too.

Accuracy

1. How OctoSense consumes App Hub. OctoSense pins App Hub at 58c3c8a, and OctoSense, App Hub and Rinx all take octosense-app-contract from crates.io (1.0.0), not from crates/app-contract. One sentence in §2 or §7 would save readers a search.
2. Missing crates. card-studio isn't mentioned. appstore-app is mentioned only indirectly in §4, and skills/ and templates/ not at all. A one-line crate map would cover them.
3. Broken link. CODE-WALKTHROUGH.md:177 points to OctoSense docs/architecture-walkthrough.md, which only exists in OctoSense #275. Merge after #275.
4. Pinned hash. "App Hub 41bc959 … on 2026-10-01" (:3) will go stale.
5. Related, against OctoSense, not this PR. script_apps.rs:201 tells users to "open the app to use it" for script tools, which doesn't help. §6 describes this correctly; the OctoSense message should change.

Writing

• Remove the review artefacts at :3-7, :244, :301-305 ("unverified in this documentation review", "Verification in this review: …").
• About 25 "does not / is not" sentences; most can be stated positively or cut.
• Drop "for Rust beginners" from the title, and the Rust primer at :71.

Suggested rewrites:

Where	Current	Suggested
:1	App Hub code walkthrough for Rust beginners	App Hub code walkthrough
:3-4	It explains the code, not a claim that every command below has been run on every platform.	Delete.
:15	None of these words means an operating-system process, Rust thread, or Tokio task.	These are logical roles; §5 covers threads.
:104	…is a serializable helper, not the shell's complete peer/storage setup.	…serializes the policy; the shell builds the actual peer and storage.
:119-120	…a separate central always-running octos service is not required by this code.	The catalog is a set of static files; no server process is needed.
:191-192	Host-level relay support is not evidence that a default store manifest can pass admission with those names.	Delete; the previous sentence covers it.
:232	do not assume they can invoke peer_send_input…	They cannot call peer_send_input or act through the system agent.

zh-CN

• The last sentence of the new README section ("发布者应用源码位于各自仓库；本仓库也包含…") repeats the intro word for word, and the English doesn't have it.
• 回包 → 应答, to match the next paragraph.
• "Agent 声明与 Shell 中真实可运行的 Peer/工具" → "应用 Agent 的声明与 Shell 中实际可执行的 Peer 和工具".

Minor: README.md:7 is one long unwrapped line, and the new README section repeats the card-host caveats; a link would do.