docs: walk through app design flow and clarify runtime boundaries

AGENTS.md

@@ -4,13 +4,17 @@
 
 You are in **OctoScript App Design Flow**: the harness for building an
 OctoSense app and taking it to the OctoSense App Hub. Read this file first,
-then the one flow you are following.
+then the one flow you are following. For repository architecture/documentation
+work, read [docs/CODE-WALKTHROUGH.md](docs/CODE-WALKTHROUGH.md): trace code and
+check links and commands.
+The screenshot, gate and publishing checklist below applies when delivering
+an app bundle, not when reviewing this repository's documentation.
 
 ## What this repository is, and is not
 
 | It is | It is not (go there instead) |
 | --- | --- |
-| Flows (`flows/*/FLOW.md`): step-by-step procedures from an input to a checked bundle | The runtime: [OctoSense-org/makepad](https://github.com/OctoSense-org/makepad) (Splash isolate, widgets) and [OctoSense-App-Hub](https://github.com/OctoSense-org/OctoSense-App-Hub) (the Card runner); the AppCard assistant and the L0 card language: [OctoSense `apps/appcard`](https://github.com/OctoSense-org/OctoSense/tree/main/apps/appcard) |
+| Flows (`flows/*/FLOW.md`): step-by-step procedures from an input to a checked bundle | The runtime: [OctoSense-org/makepad](https://github.com/OctoSense-org/makepad) (Splash isolate, widgets) and [OctoSense-App-Hub](https://github.com/OctoSense-org/OctoSense-App-Hub) (the Card runner); the AppCard assistant: [OctoSense `apps/appcard`](https://github.com/OctoSense-org/OctoSense/tree/main/apps/appcard); the L0 parser/checker: [Octoscript](https://github.com/OctoSense-org/Octoscript), and its Makepad lowering/renderer: [Octoscript-Makepad](https://github.com/OctoSense-org/OctoScript-Makepad) |
 | Developer docs (`docs/`): quickstart, script API, capabilities, host services, AI services, publishing, glossary | System apps (News, Photos, Maps, Camera, Mail, AI providers): [OctoSense `apps/`](https://github.com/OctoSense-org/OctoSense/tree/main/apps) |
 | `tools/octo`: doctor, new, run, shot, check around the real `card-host` and `hub` | The store, gate, catalog, `hub` and `card-host` source: [OctoSense-App-Hub](https://github.com/OctoSense-org/OctoSense-App-Hub) |
 | Templates (`templates/script-app/`) and worked examples (`examples/`) | The shells that run apps: [OctoSense](https://github.com/OctoSense-org/OctoSense) `phone/` (Home, the phone launcher) and `desktop/` (the desktop shell) |
@@ -87,8 +91,9 @@ patch around it here.
 - **Clean up what you launch.** End every `card-host` you start with
   `curl -s 127.0.0.1:<port>/quit` (or `/gq`); do not `pkill` other windows.
   `tools/octo run` refuses a port that is still taken and prints the `/quit`
-  command for whatever holds it; it returns once the app is drawn, so you can
-  click, type or `shot` immediately.
+  command for whatever holds it. With `--detach` it returns once the app is
+  drawn, so you can click, type or `shot` immediately; without `--detach`
+  it waits for the child process to exit.
 
 ## Definition of done (before hand-off to a human)
 
@@ -117,6 +122,27 @@ End with a report a person can check without rerunning anything:
 - **Gaps found**: runtime or tool behavior that contradicted the docs, with the
   smallest reproduction you have.
 
+## Architecture claims and documentation changes
+
+- Keep Splash/Makepad Script and Octoscript L0 distinct; the project name
+  does not make `.splash` and `.card` interchangeable languages.
+- Separate validation, grants, registration and executable handlers. A
+  `tools.json` entry or `AGENT.md` accepted by the gate is not proof the
+  runtime executes or installs it. Default App Hub admission also checks
+  `agent.tools` against `HostLimits::offered_tools`; shell relay support
+  alone does not make an arbitrary cross-app tool request admissible.
+- Distinguish an account workspace from the entire app jail and host
+  service storage. Agent access is bounded; do not promise automatic access
+  to data written elsewhere by the UI.
+- Explain routing terms through one request and show pipeline inputs and
+  outputs before enumerating stages. Keep worked examples explicit about
+  required files, consent and runtime support.
+- Keep English/Chinese README summaries aligned, preserve dated evidence,
+  run `python3 tools/check-links.py`, and also check links in new untracked
+  Markdown files. Report unrun native, provider and device paths explicitly.
+- Runtime locks belong to each consumer. Do not update shared sibling
+  checkouts or pins merely to make a documentation command pass.
+
 ## Syntax reminders for `main.splash`
 
 `#x` for hex colors containing `e` (`#x1e1e2e`); `for i in n`, no `range()`;

README.md

@@ -13,7 +13,9 @@ flows ([flows/](flows/README.md)), the developer docs ([docs/](docs/)), a
 runnable app template ([templates/script-app](templates/script-app/README.md)),
 worked examples ([examples/](examples/README.md)) and `tools/octo`, a small CLI
 over the App Hub's real `card-host` and `hub` binaries. It never decides
-admission itself: `tools/octo check` prints exactly what `hub check` prints.
+admission itself: `tools/octo check` stamps unsigned bundles, then forwards
+`hub check` output and exit status, with progress and listing-placeholder
+notes. A failed stamp returns its status immediately and skips the gate.
 
 Who it is for: hackathon contestants and other developers building an
 OctoSense app, and the coding agents they work with.
@@ -23,6 +25,16 @@ the first-party apps moved to OctoSense-System-Apps and, since 2026-09-27,
 live in [OctoSense `apps/`](https://github.com/OctoSense-org/OctoSense/tree/main/apps)
 (OctoSense-System-Apps is archived and no longer public).
 
+## Code walkthrough
+
+[docs/CODE-WALKTHROUGH.md](docs/CODE-WALKTHROUGH.md) follows the Python CLI
+from a script template to a running app, then into App Hub and the OctoSense
+shell. A saved-notes request explains peers, conversations, data access and
+reply routing; an atlas-to-card example explains the image pipeline's default
+stages. It also covers native Rust versus Splash/L0 apps, cross-app tool
+limits, runtime pins and Tokio. `tools/octo` is the development CLI; octos
+is the separate agent kernel.
+
 ## Contents
 
 - [Hackathon: start here](#hackathon-start-here)
@@ -263,8 +275,10 @@ screenshots, the platforms you actually tested, age rating and the publisher
 (name, support, https privacy-policy URL). Valid values:
 [docs/PUBLISHING.md §3.2](docs/PUBLISHING.md#32-finalize-the-listing).
 
-**`main.splash`**: the program, in Splash (OctoScript), interpreted with no
-compile step. Top-level `let` state and `fn`s, then one root widget; start
+**`main.splash`**: the program, evaluated by Makepad Script in a Splash
+isolate with no Rust compile step. This is a different parsing path from
+Octoscript L0 (`page.card`). Top-level `let` state and `fn`s, then one root
+widget; start
 work with `start_timeout(0.05, || boot())`, since `ui` is injected after the
 body runs. `{{assets}}` in the source is replaced by the loopback origin that
 serves the bundle (`http_resource("{{assets}}/thumbs/a.jpg")`). Everything an
@@ -319,7 +333,7 @@ its own host-owned peer. As of 2026-10-01, on OctoSense `main`
 | Make a one-shot, schema-checked model call | `model` capability, `host.request("model.complete", …)`, within a daily budget | `no service answers "model"` |
 | Talk to the assistant from its own screens | the four `octos.*` capabilities, once the person allows the app's agent on a first-use sheet | `no service answers "octos"` |
 | Have its own agent, which the person talks to directly (the shell's "Ask <app>" panel, drawn for every app with an agent; an in-card chat; the app's own screens) and the system agent can hand work to | an `agent` block (`"tools": ["ask_user_question"]`), optional `tools.json`; the agent reads the app's account folder (`accounts/device/`) | checked by `hub check` only |
-| Publish cards to the glance screen, with an in-card chat its agent answers and model-written text marked AI-written | `glance` capability, `glance.publish` (L0 `sys.chat`, `model-copy`) | `no service answers "glance"`; this repository's runtime predates `sys.chat` |
+| Publish cards to the glance screen, with an in-card chat its agent answers and model-written text marked AI-written | `glance` capability, `glance.publish` (L0 `sys.chat`, `model-copy`) | `no service answers "glance"`; this repository's authoring pin lacks `sys.chat` and `ChatEntry` |
 
 Still **coming**: a store app's own `tools.json` tools running (today only
 system apps' host-service tools run), the host choosing the agent's model
@@ -517,7 +531,7 @@ For a script app, the complete examples are the first-party bundles in
 | [OctoSense-App-Hub](https://github.com/OctoSense-org/OctoSense-App-Hub) | The signed catalog, the gate, `hub`, `card-host`, the store and the Card runner |
 | [OctoSense](https://github.com/OctoSense-org/OctoSense) | The shell and what ships in it: the desktop shell (`desktop/`), the phone shell Home (`phone/`, as a Home app or in the ROM image built by `rom/`), and the first-party apps with their host services (`apps/`). Formerly OctoSense-Desktop, OctoSense-ROM and OctoSense-System-Apps. |
 | [OctoSense `apps/`](https://github.com/OctoSense-org/OctoSense/tree/main/apps) | First-party apps (News, Photos, Maps, Camera, Mail, AI providers) and their host services (`mail`, `llm`) |
-| [OctoSense `apps/appcard`](https://github.com/OctoSense-org/OctoSense/tree/main/apps/appcard) | The AppCard assistant (`octos-app`, opt-in in the shells with `--features app-appcard`) and the L0 card language; the Splash isolate and widgets themselves are in makepad |
+| [OctoSense `apps/appcard`](https://github.com/OctoSense-org/OctoSense/tree/main/apps/appcard) | The AppCard assistant (`octos-app`, opt-in in the shells with `--features app-appcard`); the L0 parser/checker is in Octoscript and its Makepad lowering/renderer in Octoscript-Makepad; Splash isolates and widgets are in makepad |
 | [OctoSense-org/makepad](https://github.com/OctoSense-org/makepad), [Octoscript](https://github.com/OctoSense-org/OctoScript), [Octoscript-Makepad](https://github.com/OctoSense-org/OctoScript-Makepad) | The framework and language the apps run on |
 
 ## License

README.zh-CN.md

@@ -12,14 +12,23 @@ Agent）从一个想法（一段文字需求、一张生成的 UX 图）走到
 （[templates/script-app](templates/script-app/README.zh-CN.md)）、完整示例
 （[examples/](examples/README.zh-CN.md)），以及 `tools/octo`：一个包装 App Hub 真实
 `card-host` 与 `hub` 二进制的小型命令行工具。它自己从不决定准入：`tools/octo check`
-输出的就是 `hub check` 的原样输出。
+先为未签名的包写入摘要，再转发 `hub check` 的输出与退出码，并显示进度和清单（listing）
+占位提示。摘要写入失败时，命令立即返回其错误码，不运行准入检查。
 
 面向：参加黑客松的选手、其他开发 OctoSense 应用的开发者，以及与他们协作的编码 Agent。
 
 原名 *Octoscript-AppCard*。AppCard 助手运行时和第一方应用先迁至 OctoSense-System-Apps，
 自 2026-09-27 起位于 [OctoSense `apps/`](https://github.com/OctoSense-org/OctoSense/tree/main/apps)
 （OctoSense-System-Apps 已归档，不再公开）。
 
+## 代码导读
+
+[代码导读（英文）](docs/CODE-WALKTHROUGH.md) 沿着 Python CLI，从脚本模板走到运行中的
+应用，再进入 App Hub 与 OctoSense Shell。“总结已保存的笔记”这一请求解释 Peer、对话、
+数据访问和应答路由；从画面图集到卡片的示例解释图像流水线的默认阶段。导读还介绍原生
+Rust、Splash 与 L0 应用的差别、跨应用工具限制、运行时版本和 Tokio 所在的层级。
+`tools/octo` 是开发命令；octos 是独立的 Agent 内核。
+
 ## 目录
 
 - [黑客松：从这里开始](#黑客松从这里开始)
@@ -237,7 +246,8 @@ my-app/                     the app's own git repository
 以及发布者信息（名称、支持方式、https 隐私政策 URL）。合法取值见
 [docs/PUBLISHING.md §3.2](docs/PUBLISHING.md#32-finalize-the-listing)。
 
-**`main.splash`**：程序本身，用 Splash（OctoScript）编写，无需编译即可解释执行。顶层是
+**`main.splash`**：程序本身，由 Makepad Script 在 Splash 隔离环境中求值，
+无需 Rust 编译；它与 Octoscript L0（`page.card`）的解析路径不同。顶层是
 `let` 状态和 `fn`，然后是一个根组件；由于 `ui` 在主体执行后才注入，请用
 `start_timeout(0.05, || boot())` 启动逻辑。源码中的 `{{assets}}` 会被替换为提供应用包内容
 的本地回环地址（`http_resource("{{assets}}/thumbs/a.jpg")`）。应用可以调用的全部内容，
@@ -281,7 +291,7 @@ OctoSense 每个 Shell 运行一个 octos Agent 内核，由用户在系统应
 | 进行一次性、按 schema 校验的模型调用 | `model` 权限，`host.request("model.complete", …)`，受每日预算限制 | `no service answers "model"` |
 | 在自己的界面上与助手对话 | 4 个 `octos.*` 权限，用户在首次使用的确认页上允许该应用的 Agent 之后 | `no service answers "octos"` |
 | 拥有自己的 Agent：用户可以直接与它对话（Shell 为每个有 Agent 的应用绘制的“Ask <app>”面板、卡片内对话、应用自己的界面），系统 Agent 也可以把任务交给它 | `agent` 块（`"tools": ["ask_user_question"]`），可选 `tools.json`；该 Agent 可以读取应用的账户文件夹（`accounts/device/`） | 只能用 `hub check` 检查 |
-| 向 glance 屏幕发布卡片，卡片内可与应用 Agent 对话，模型写的文字标为 AI 撰写 | `glance` 权限，`glance.publish`（L0 `sys.chat`、`model-copy`） | `no service answers "glance"`；本仓库锁定的运行时早于 `sys.chat` |
+| 向 glance 屏幕发布卡片，卡片内可与应用 Agent 对话，模型写的文字标为 AI 撰写 | `glance` 权限，`glance.publish`（L0 `sys.chat`、`model-copy`） | `no service answers "glance"`；本仓库锁定的开发运行时尚不支持 `sys.chat` 与 `ChatEntry` |
 
 仍在**规划中**：商店应用自己的 `tools.json` 工具真正运行（目前只有系统应用的 host-service
 工具能运行）、宿主根据 `needs` 为 Agent 选择模型、触发器与后台运行、安装 `AGENT.md` 和
@@ -445,7 +455,7 @@ curl -s 127.0.0.1:8161/quit; curl -s 127.0.0.1:8162/quit
 | [OctoSense-App-Hub](https://github.com/OctoSense-org/OctoSense-App-Hub) | 签名目录、准入检查、`hub`、`card-host`、商店与 Card runner |
 | [OctoSense](https://github.com/OctoSense-org/OctoSense) | Shell 及其内置的一切：桌面端 Shell（`desktop/`）、手机 Shell Home（`phone/`，可作为 Home 应用安装，也可放进由 `rom/` 构建的 ROM 镜像），以及第一方应用和它们的宿主服务（`apps/`）。原为 OctoSense-Desktop、OctoSense-ROM 和 OctoSense-System-Apps 三个仓库。 |
 | [OctoSense `apps/`](https://github.com/OctoSense-org/OctoSense/tree/main/apps) | 第一方应用（News、Photos、Maps、Camera、Mail、AI providers）及其宿主服务（`mail`、`llm`） |
-| [OctoSense `apps/appcard`](https://github.com/OctoSense-org/OctoSense/tree/main/apps/appcard) | AppCard 助手（`octos-app`，在 Shell 中需 `--features app-appcard` 才启用）与 L0 卡片语言；Splash 隔离环境和组件本身在 makepad 中 |
+| [OctoSense `apps/appcard`](https://github.com/OctoSense-org/OctoSense/tree/main/apps/appcard) | AppCard 助手（`octos-app`，在 Shell 中需 `--features app-appcard` 才启用）；L0 解析器/检查器位于 Octoscript，Makepad 转换/渲染层位于 Octoscript-Makepad；Splash 隔离环境和组件位于 makepad |
 | [OctoSense-org/makepad](https://github.com/OctoSense-org/makepad)、[Octoscript](https://github.com/OctoSense-org/OctoScript)、[Octoscript-Makepad](https://github.com/OctoSense-org/OctoScript-Makepad) | 应用运行所依赖的框架与语言 |
 
 ## 许可证