ymote · Sep 28, 2026 · Sep 28, 2026
diff --git a/README.md b/README.md
@@ -14,6 +14,24 @@ It was OctoSense-Desktop; OctoSense-ROM (retired; merged into this repository) a
 
 > **Building an OctoSense app?** You do not need this repository to build, check or publish one. Start at the [OctoSense-org profile](https://github.com/OctoSense-org)'s reading list: [OctoScript-App-Design-Flow](https://github.com/OctoSense-org/OctoScript-App-Design-Flow) (`AGENTS.md`, then `docs/QUICKSTART.md`) and [OctoSense-App-Hub](https://github.com/OctoSense-org/OctoSense-App-Hub). The system apps in [`apps/`](apps/README.md) are complete examples of the same app shape (`apps/<name>/bundle/`). Build the desktop shell from here only to see your app in a shell before it is published ([PUBLISHING §4](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/docs/PUBLISHING.md#4-rehearse-the-store-path-locally)).
 
+## How it fits together
+
+```
+ person ──> OctoSense shell (one process) ──── OUP (stdio) ────> octos kernel (one per shell)
+            ├─ native modules: App Hub, Rinx          ├─ system agent session
+            ├─ Card runner: script apps in isolates   └─ one app agent (peer) per (app, account)
+            ├─ approval router, host sheets, storage
+            └─ hub ──> process apps (desktop: Terminal)
+```
+
+- **One shell process** hosts the window manager, the native modules (App Hub, Rinx) and App Hub's Card runner, where every script app runs in its own isolate. On the desktop the Terminal runs as its own process, attached over the shell's hub.
+- **One octos kernel per shell**, started on first use: a child process on the desktop and Android, in process on OpenHarmony, none on iOS. The shell is its host connection and holds the host token; apps never talk to the kernel.
+- **Agents are sessions in that kernel**: the system agent, and one app agent (an octos peer) per app and account, each with its own workspace, memory and transcript. The system agent briefs app agents and reads their results on the peers' blackboard.
+- **Apps reach their agent through the shell**: an injected service for native modules, `host.request("octos.*")` for script apps. Talk to Octos (opt-in) lets a web or terminal client use the system conversation with a limited token, never the app agents.
+- **The person approves**: outward and destructive tool calls go through the shell's approval router, live on a sheet or by a standing rule the person set.
+
+Processes, agents, protocols, tools, approvals, storage and trust boundaries, with what is on `main` and what is planned: [docs/architecture.md](docs/architecture.md).
+
 ## Layout
 
 | Path | What it is |
@@ -53,7 +71,7 @@ Each shell runs one [octos](https://github.com/octos-org/octos) agent kernel, st
 
 What works today: native modules (Rinx) use their peer; AppCard (opt-in) uses the kernel directly. Contained script apps, system or store, reach it through the `octos` host service in a shell that hosts a kernel: each app gets its own host-owned peer (`card.<app id>`), and tool approvals are declined until the Card runner has an approval sheet. The `llm` service manages providers for `os.*` apps only. An app's own agent (`tools.json`, `AGENT.md`, skills, triggers, glance cards) is [ADR 0002](docs/adr/0002-event-driven-app-agents.md), Proposed, with its first pieces merged or in review.
 
-The architecture, the trust model, what each kind of app can use, the plan with its status, and how to run and test it locally: [docs/ai-services.md](docs/ai-services.md). For app developers: OctoScript-App-Design-Flow's [AI-SERVICES](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/docs/AI-SERVICES.md).
+The architecture, the trust model, what each kind of app can use, the plan with its status, and how to run and test it locally: [docs/ai-services.md](docs/ai-services.md). How it fits into the whole system: [docs/architecture.md](docs/architecture.md). For app developers: OctoScript-App-Design-Flow's [AI-SERVICES](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/docs/AI-SERVICES.md).
 
 ## Set up
 

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -14,6 +14,24 @@
 
 > **要开发 OctoSense 应用？** 开发、检查或发布应用都不需要本仓库。请从 [OctoSense-org 主页](https://github.com/OctoSense-org)的阅读列表开始：[OctoScript-App-Design-Flow](https://github.com/OctoSense-org/OctoScript-App-Design-Flow)（先读 `AGENTS.md`，再读 `docs/QUICKSTART.md`）和 [OctoSense-App-Hub](https://github.com/OctoSense-org/OctoSense-App-Hub)。[`apps/`](apps/README.zh-CN.md) 中的系统应用是同样应用结构的完整示例（`apps/<name>/bundle/`）。只有想在发布前先在 Shell 里看到自己的应用时，才需要从这里构建桌面端 Shell（[PUBLISHING §4](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/docs/PUBLISHING.md#4-rehearse-the-store-path-locally)）。
 
+## 整体如何运作
+
+```
+ 用户 ──> OctoSense Shell（一个进程）──── OUP（stdio）────> octos 内核（每个 Shell 一个）
+          ├─ 原生模块：App Hub、Rinx                ├─ 系统 Agent 会话
+          ├─ Card runner：脚本应用各在隔离环境中    └─ 每个（应用，账号）一个应用 Agent（peer）
+          ├─ 审批路由、宿主面板、存储
+          └─ hub ──> 进程应用（桌面端：Terminal）
+```
+
+- **一个 Shell 进程**承载窗口管理器、原生模块（App Hub、Rinx）和 App Hub 的 Card runner，每个脚本应用都在自己的隔离环境中运行。桌面端的 Terminal 作为独立进程运行，通过 Shell 的 hub 连接。
+- **每个 Shell 一个 octos 内核**，首次使用时启动：桌面端和 Android 上是子进程，OpenHarmony 上在进程内，iOS 上没有。Shell 是它的宿主连接并持有宿主 token；应用从不直接与内核通信。
+- **Agent 是这个内核中的会话**：系统 Agent，以及每个应用、每个账号一个应用 Agent（octos peer），各自有独立的工作区、记忆和对话记录。系统 Agent 向应用 Agent 下达任务，并在 peer 黑板上读取它们的结果。
+- **应用通过 Shell 使用自己的 Agent**：原生模块用注入的服务，脚本应用用 `host.request("octos.*")`。Talk to Octos（需手动开启）让网页或终端客户端以受限 token 使用系统对话，但永远接触不到应用 Agent。
+- **由用户批准**：对外和破坏性的工具调用都经过 Shell 的审批路由，在面板上实时批准，或由用户设定的常设规则批准。
+
+进程、Agent、协议、工具、审批、存储和信任边界，以及哪些已在 `main` 上、哪些还在规划中：[docs/architecture.zh-CN.md](docs/architecture.zh-CN.md)。
+
 ## 目录结构
 
 | 路径 | 内容 |
@@ -53,7 +71,7 @@ Shell 只有一份，位于 `crates/shell`（[ADR 0001（英文）](docs/adr/000
 
 目前可用的：原生模块（Rinx）使用自己的 peer；AppCard（需主动开启）直接使用内核。隔离运行的脚本应用，无论系统应用还是商店应用，在托管了内核的 Shell 中通过 `octos` 宿主服务使用助手：每个应用有自己的、由宿主拥有的 peer（`card.<应用 id>`），在 Card runner 有审批面板之前工具审批一律被拒绝。`llm` 服务只为 `os.*` 应用管理提供方。应用自己的 Agent（`tools.json`、`AGENT.md`、skills、触发器、glance 卡片）见 [ADR 0002](docs/adr/0002-event-driven-app-agents.md)（Proposed），其中最早的几部分已合入或正在评审。
 
-架构、信任模型、各类应用能用什么、规划及其状态，以及如何在本地运行和测试：[docs/ai-services.zh-CN.md](docs/ai-services.zh-CN.md)。面向应用开发者：OctoScript-App-Design-Flow 的 [AI-SERVICES](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/docs/AI-SERVICES.zh-CN.md)。
+架构、信任模型、各类应用能用什么、规划及其状态，以及如何在本地运行和测试：[docs/ai-services.zh-CN.md](docs/ai-services.zh-CN.md)。它在整个系统中的位置：[docs/architecture.zh-CN.md](docs/architecture.zh-CN.md)。面向应用开发者：OctoScript-App-Design-Flow 的 [AI-SERVICES](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/docs/AI-SERVICES.zh-CN.md)。
 
 ## 环境准备
 

diff --git a/docs/adr/README.md b/docs/adr/README.md
@@ -4,6 +4,8 @@ English | [简体中文](README.zh-CN.md)
 
 Decisions for the OctoSense repository: the shell, its services, the system apps and the desktop, phone and ROM packagings. New ADRs go here, numbered after the last one in this table.
 
+How these decisions fit together in the code on `main`, and which parts are still planned: [OctoSense architecture](../architecture.md).
+
 | ADR | Title | Status |
 | --- | --- | --- |
 | [0001](0001-one-octosense-repository.md) | One OctoSense repository for the shell, its services, the system apps and both packagings | Accepted |

diff --git a/docs/adr/README.zh-CN.md b/docs/adr/README.zh-CN.md
@@ -4,6 +4,8 @@
 
 OctoSense 仓库的决策：Shell、Shell 服务、系统应用，以及桌面、手机和 ROM 三种打包形态。新的 ADR 放在这里，编号接在下表最后一条之后。
 
+这些决策在 `main` 的代码中如何组合在一起、哪些部分仍在规划中：[OctoSense 架构](../architecture.zh-CN.md)。
+
 | ADR | 标题 | 状态 |
 | --- | --- | --- |
 | [0001](0001-one-octosense-repository.md)（英文） | 用一个 OctoSense 仓库承载 Shell、Shell 服务、系统应用和两种打包形态 | 已接受 |

diff --git a/docs/ai-services.md b/docs/ai-services.md
@@ -6,6 +6,8 @@ How the assistant is wired into OctoSense: the [octos](https://github.com/octos-
 
 This page is about the assistant *inside* OctoSense. Building an app needs no AI service and no particular coding agent: the app harness, [OctoScript-App-Design-Flow](https://github.com/OctoSense-org/OctoScript-App-Design-Flow), works with any agent or none. Its [AI-SERVICES](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/docs/AI-SERVICES.md) page is the app developer's short version of this one.
 
+For the whole system around it (processes per platform, agents, protocols, tools and grants, approvals, storage and trust boundaries), see [OctoSense architecture](architecture.md).
+
 ## Contents
 
 - [At a glance](#at-a-glance)

diff --git a/docs/ai-services.zh-CN.md b/docs/ai-services.zh-CN.md
@@ -6,6 +6,8 @@
 
 本文讨论的是 OctoSense *内部*的助手。开发应用不需要任何 AI 服务，也不需要特定的编程 Agent：应用开发工具集 [OctoScript-App-Design-Flow](https://github.com/OctoSense-org/OctoScript-App-Design-Flow) 适用于任何 Agent，也可以不用 Agent。它的 [AI-SERVICES](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/docs/AI-SERVICES.zh-CN.md) 页面是本文面向应用开发者的简短版本。
 
+它所处的整个系统（各平台的进程、Agent、协议、工具与授权、审批、存储和信任边界）见 [OctoSense 架构](architecture.zh-CN.md)。
+
 ## 目录
 
 - [概览](#概览)