[ymote]

This PR is rebased onto main at 91063e3, after #275 (the architecture walkthrough), #256, #268, #278, #279 and #290. #275's rewrites stay as they are: the intro, the kernel and session text, the script-app account wording, the tools-table examples, the worked example's intro and rows 1, 3 and 5, and follow-up 13. So do #256's desktop kernel row and the follow-up 5 that reflects #268.

On top of them, this PR fixes what still disagrees with main's code, in docs/architecture.md and docs/architecture.zh-CN.md. Before this PR the Chinese page had fallen behind the English one; both now say the same thing.

Corrections still added on top of #275 (old claim → what the code says)

Agents and tools

• §2 named News as the example (and docs: add app and agent architecture walkthroughs for Rust developers #275 left its list at News); §4 listed only News's and the Terminal's tools → every system app except AI providers has an agent (apps.rs agent_apps, apps/*/bundle/tools.json).
  • Mail has mail.notify.
  • Calendar (desktop only) has events, add_event, remove_event (destructive, confirm: host), notify and agenda.
  • Photos, Maps, YouTube and Camera have <app>.notify, which the shell's NoticeService answers.
  • The relay row notes that a system app's own namespace needs no capability grant (script_apps.rs). None of the system apps calls octos.* or draws a chat.
• "agents.ask shows the first-use sheet" → it is also act, outward and confirm: "app". The kernel holds it until the person has answered and the peer is ready (agents.rs, system_chat settle_asks). Also added to worked-example row 2.
• Toolbox row: "In progress (toolbox-peers: offer the system toolbox to app agents (ADR 0002 §6, behind a feature) #108); model not registered" → on main behind toolbox-peers (toolbox-peers: offer the system toolbox to app agents (ADR 0002 §6, ADR 0004 §12, behind a feature) #151), on by default only in the phone build.
• Command execution row: "a process app on macOS, Windows, and Linux" → only where the Terminal's newest launch ran in its OS sandbox. Windows is excluded (grants.rs terminal_target).
• The cross-app row now says mail.send is not declared yet.
• docs: add app and agent architecture walkthroughs for Rust developers #275 left a broken sentence in §2 ("octos's command turns and tool dispatch in the session's workspace"); it now says octos's command tools are offered to no agent.

Glance

• New paragraph in §4:
  • Every <app>.notify fills the shell's notice card (glance_notice.rs).
  • A new card opens the panel unless a card window is open. The toast always shows and stacks left of the open panel (lib.rs glance_notify, keep_clear_of).
  • A dismissal can be undone (Glance and notifications UX: undo, keyboard, motion, cards that follow the mode #290).
  • Only the OCTOSENSE_GLANCE_DEMO=mail card has sys.chat.
• §5: "a glance tile is still contained…; interactive cards are a PR branch" → tiles run under the app's policy (Interactive glance cards under the publishing app's policy [skip ci] #153). L0 taps run in the card window and, since Glance: the panel's cards run their taps and in-card chat; chat threads keep Mail's account #278, in the glance panel (LiveCards). The phone's glance page does not run them yet.

Communication and approvals

• Questions: "the shell's overlay" → the open "Ask " panel, otherwise the overlay's card, never both at once (Ask <app>: a question has one surface, the open panel, not a modal card over it #279).
• Router: added step 0 (an external client's turn is left to it, Route::LeftToClient). Step 3 now covers calls not on the host's connection.
• "octos approvals in an app's context still go to that app" → all of them go to the shell's router (shell, app-peers: every approval on an app's peer or context goes to the shell's sheets (G4) [skip ci] #155).
• "Stop 's agent on the app-conversation sheet" → on the approval sheet and question card. The "Ask " panel stops one lane at a time.
• Added: a failed peer/input start is refused with its reason, and the oldest instance drives an app's peer (app-peers: one instance drives an app's peer; the next takes over when it closes #201).

Processes, storage, sandboxes

• "cargo run … --stdin-loop" → the shell builds the app locked, outside any sandbox, then starts the binary sandboxed (launch_plan, Process apps: build from the workspace (locked), start the binary sandboxed; force-close; terminal.run needs a sandboxed launch (ADR 0004 review) #225).
• Hub ports 8765–8784, not 8765–8785.
• "Release packages… (Desktop release packages (macOS .app/.dmg, Windows NSIS, Linux .deb/.AppImage) and release-desktop workflow #94)" → Desktop release packages; a release workflow that keeps signing out of the build #257, in progress.
• "Rinx stays in process until the peer link and the sandboxes exist" → both now exist. Rinx still uses the injected service, and its hosting is still module.
• §6: "App Hub accepts only storage.max_bytes, so script apps act for the device" → App Hub also accepts accounts, agent_workspace and cache_max_bytes, and Mail acts for its active account.
• §7 and follow-up 12: the Linux sandbox was validated on 2026-09-30 (ADR 0004: validate the Linux sandbox on a real kernel #138, Linux sandbox: run it on a real kernel; a cargo launch sandboxes only the app (#138) #199, Linux sandbox: seccomp refuses the kernel's other ABIs #200, Linux sandbox: network none means no IP but the hub; scope signals #202), not "unvalidated".
• Script apps list: Calendar is added (desktop only).
• Rinx#37 is cited as the release-tag rule it is.

Worked example and disagreements

• The intro now says Calendar is desktop only.
• Row 4: add_event is act and its events are kept in events.json.
• Row 6: calendar.remove_event takes the router's path today.
• Row 7: mail.send exists only as a method for Mail's own UI.
• Row 9: Calendar's own window cannot list events yet.
• Follow-up 7 is fixed. Follow-up 8 says that agents.ask is the only confirm: app tool on main.
• Also: ADR 0004 is marked Implemented, the overview diagrams gain the host-tool relay and host services, and the source map adds the agents, chats, host tools, questions, glance, host services and sandbox files.

Checks

On the rebased head:

• python3 -m unittest discover -s tools -p 'test_*.py': 95 tests, OK.
• From rom/: python3 -m unittest tests.test_no_local_paths: OK.
• Every relative link and anchor in both files resolves (160 links, 0 broken), including docs: add app and agent architecture walkthroughs for Rust developers #275's walkthrough anchors.
• A per-section comparison of the English and Chinese pages finds matching code spans, links, tables, bullets and code blocks.

Docs only. No device run.

🤖 Generated with Claude Code