[ymote]

What

This corrects four statements in the docs, in English and Chinese. I found them while re-checking the code issues listed in #333.

Where	It said	It now says
docs/architecture.md, "Where the code and the ADRs disagree", item 11 (from #333)	The in-process Terminal still offers run, so the AI pane can type into it.	Only the system agent's terminal.run checks the sandbox. The AI pane can use a process Terminal's own run whether or not the Terminal's sandbox applied. In developer mode, the host-tool relay grants terminal.run to every covered app agent without that check. On Windows there is no sandbox, so both paths reach an unsandboxed Terminal. The in-process Terminal is read-only on the bus, as the ADR says.
The same list, item 8 (from #333)	terminal.run is never offered on Windows.	That holds for the system agent only. Other callers are covered in item 11.
README.md, "Zero-copy frames for process apps" (from #331)	Linux with OpenGL can only copy frames, so every app runs inside the shell there.	On Linux the shell starts the Terminal as a process only in a Vulkan build in a Wayland session. Task has no module, so it is a process either way. Its frames are copied only where the GL driver cannot export a DMA_BUF.
desktop/README.md, the app-terminal row	The row had six errors: - in either hosting the assistant may type a command; - the command is confirmed on the assistant's card; - a command too long for the card is refused; - the app is built with cargo run; - it runs in-process "as on phones"; - release packages are waiting on #94.	The AI pane reads the Terminal in either hosting, but types only into a process Terminal. Outside developer mode, each command waits for a host sheet. The limit is 4 KiB. The shell builds the Terminal with cargo build and starts it itself. Phone builds don't link it. Release packages ship only octosense and the kernel (#94 closed unmerged).

Evidence

At a287d530 and the Makepad pin c155f61d.

• The in-process Terminal is read-only on the bus.
  • At creation, the shell reads the manifest of the module's own executor (crates/shell/src/module_host.rs:573). That is Makepad's read_only_manifest (apps/terminal/src/module.rs:80).
  • The read happens before host_executor swaps the executor (:608). The instance keeps this manifest (:616).
  • crates/shell/src/lib.rs:2590 and :2611 register it. Replays and re-announcements reuse it.
  • The pane's engine refuses any tool the manifest doesn't declare (Makepad libs/ai/services/src/engine/core.rs:551-553). AiBus::shell_call filters by the same manifest.
• The sandbox check.
  • Windows process apps run unsandboxed (crates/shell/src/sandbox/mod.rs:493).
  • The Terminal process registers its full manifest, run included (Makepad apps/terminal/src/main.rs:379).
  • Only system_chat/grants.rs:205 and shell/menu.rs:879 read the sandbox state. ai_bus.rs and host_tools/relay.rs don't.
  • In developer mode, Catalog::may_call (host_tools/relay.rs:354-360) grants every shareable tool except the toolbox's.
• Release packages have no AI pane.
  • They ship no aichat binary (desktop/packaging/release.json).
  • They don't build the app-aichat feature.
  • So opening the pane says "Assistant unavailable" (crates/shell/src/lib.rs:2343-2344).
• Frames on Linux.
  • With OpenGL, Makepad exports each frame as a DMA_BUF through eglExportDMABUFImageMESA (platform/src/os/linux/x11/opengl_x11.rs:30-115). It falls back to a software readback only when that fails (platform/src/os/shared_framebuf.rs:437-466).
  • The shell starts the Terminal as a process only when vulkan_wayland() holds (crates/shell/src/apps.rs).
  • AppRegistry::hosting applies process-if-vulkan only to linked modules, and Task's entry has "module": null.
• The app-terminal row.
  • crates/shell/src/clients.rs:22 and :1030 say cargo build, never cargo run.
  • The Terminal's shells.phone is off.
  • ai_bus.rs:437: the host sheet shows the arguments in full.
  • Makepad apps/terminal/src/ai.rs sets MAX_COMMAND_BYTES to 4 KiB.
  • The PTY helper is octosense (crates/shell/src/apps.rs:57).
  • Desktop release packages (macOS .app/.dmg, Windows NSIS, Linux .deb/.AppImage) and release-desktop workflow #94 was closed unmerged on 2026-10-01.

Not in this PR

• App Hub: its own agent, with read tools only #339 gave App Hub an agent, but docs/architecture.md still shows App Hub without one:

  • the native-apps table lists no agent for App Hub;
  • item 1 of the list doesn't name App Hub among the agents that get a folder.

  That's a separate change.

• ADR 0004's tables still say OpenGL means "CPU readback of every frame" and "in-process for every app", and so does the tools/native_apps.py docstring. The ADR is a dated record, and this PR changes no code.

• The code gaps themselves are listed in docs: bring docs/ up to date with the code and rewrite the guides to the README's standard #333's description.

Verification

• A link check of the six files, using GitHub's slug rules, finds no broken link or anchor.
• Table rows keep their pipe counts. No raw tags remain outside code, and backticks are balanced.
• git diff --check is clean.
• python3 -m unittest discover -s rom/tests -p test_no_local_paths.py passes.
• Before commit, an independent reviewer checked each changed sentence against the code and the Makepad pin. I verified each of its corrections and applied them:
  • the OpenGL export path;
  • the developer-mode relay path;
  • the closed Desktop release packages (macOS .app/.dmg, Windows NSIS, Linux .deb/.AppImage) and release-desktop workflow #94;
  • "AI pane" in place of "assistant", since the system agent has no Terminal read tools.
• No command was added or changed.

🤖 Generated with Claude Code