[ymote]

What

This rewrites the root README.md and README.zh-CN.md so a newcomer learns the architecture before the setup. The old README was accurate in places, but it read like a changelog: inline PR numbers, dated history and UI minutiae. Several of its statements went stale after #309, #329 and #330.

New sections (both languages)

• Key concepts defines thirteen terms in a sentence or two each: octos, OUP, the shell, the system agent, app agents, lanes, native and script apps (with Splash), the Card runner, host services, the peer link, glance cards (with L0) and the approval router.

• How the system agent and an app agent talk gives the peer_send_input → peer/input → shell-started turn → blackboard / peer_gather loop in four steps.

• How an app uses its agent has one table covering:

  • script apps, through host.request("octos.*");
  • native apps, through OctosPeer plus serve_tools;
  • Rinx, through OctosAppService.

  It ends with the minimal Splash example from Design Flow's AI-SERVICES guide.

• What an app gives its agent lists:

  • the declaration;
  • tools.json and what actually executes each tool;
  • data (the account folder or agent_workspace: "none", and files.*);
  • memory;
  • glance;
  • events.

  It states plainly that a store app's agent cannot act through tools of its own yet.

• Why it stays light on memory and CPU lists the Rust design choices, each checked against the code:

  • one kernel, with agents as sessions;
  • one shared connection to the kernel (crates/kernel/src/router.rs);
  • threads per service, not per turn;
  • start on demand and idle stop;
  • apps running in-process as isolates or modules;
  • zero-copy frames for process apps.

Fixed stale facts

• The app-agent table now lists the native agents (Terminal; Calculator, Clock, Notes, Reminders, Weather), not only Rinx and the script apps. It separates each agent's own tools (own_tools) from what the system agent may call (system_tools). It also says a native app's agent is live only while the app is open, while a script app's agent is prepared at startup.
• Removed two false claims: "the Terminal is not granted an agent" and "no process app / no module uses the peer link yet". The Terminal and the five Makepad apps open the link with OctosPeer. I verified this in OctoSense-org/makepad at the pinned c155f61d (apps/*/src/view.rs) and in the Terminal's stacked runtime patch.
• docs/architecture.md and docs/architecture.zh-CN.md had the same stale statements, now fixed:
  • the native-apps table;
  • who gets a peer;
  • the illustration note;
  • the Mermaid peer-link edge;
  • the module and process peer-link rows;
  • the agents table's status cell;
  • the trust-boundary row;
  • what the AI bus is still used for.
• docs/images/agents-processes.png: the native-modules box said only "App Hub, Rinx" and its arrow said only OctosAppService. I redrew those two labels in place, and the rest of the image is unchanged. They now read "App Hub, Rinx, Notes, Clock, …" and "OctosPeer, OctosAppService". The Mermaid text versions match.
• <app> written outside code was stripped by GitHub as an HTML tag, so "Ask " rendered as "Ask ". It is now escaped.

Moved or trimmed

• The desktop glance panel's UI table and OCTOSENSE_REDUCE_MOTION moved to a new The glance panel section in desktop/README.md and desktop/README.zh-CN.md. Each also gets a row in its environment table.
• Removed from the root README:
  • the "Ask " panel's button-by-button behavior;
  • card quotas;
  • the transcript path;
  • the import history;
  • the dated "until 2026-09-29" note;
  • inline PR and issue numbers.
• The hub setup instructions stay under Set up, collapsed in <details>, because desktop/README.md, phone/README.md and AGENTS.md point there.

Every heading that other docs link to is kept:

• English: how-it-fits-together, the-system-agent-and-the-app-agents, talking-to-an-apps-agent-yourself, in-card-chat, what-it-depends-on, set-up.
• Chinese: 整体如何运作, 直接与应用的-agent-对话, 卡内对话, 依赖, 环境准备.

Verification

• A link checker using GitHub's heading-slug rules found no broken relative link or anchor in the six changed Markdown files. That includes the anchors into Design Flow's AI-SERVICES.md and AI-SERVICES.zh-CN.md, and every inbound anchor from other docs in this repository.
• Both READMEs render through GitHub's Markdown API (POST /markdown, gfm) with 8 tables, 22 headings and 5 <details> blocks each, and no stray tags.
• python3 -m unittest discover -s rom/tests -p test_no_local_paths.py: OK.
• git diff --check: clean.
• An independent review agent graded the English README against the brief: knowledge transfer, human voice, no needless detail, coverage of octos, shell integration, the two kinds of agents, communication, human interaction, app integration, what an app provides, and Rust efficiency. It spot-checked about 30 claims against the code. Its scores were 8.2, then 9.3 after fixes, then 9.6 after the last round, with no remaining factual errors.
• No code changed. The README's commands are the same as before, and none was re-run for this change.

🤖 Generated with Claude Code