docs: walk through admission, app hosting and agent service boundaries

AGENTS.md

@@ -0,0 +1,42 @@
+# Working on App Hub
+
+Read [README.md](README.md), the
+[code walkthrough](docs/CODE-WALKTHROUGH.md), and the relevant crate before
+editing. This repository owns the app contract, admission, catalog/signing,
+store, contained runner and shared host-service transport. OctoSense owns
+the shells, first-party services and live agent integration; Design Flow
+owns authoring workflows.
+
+- Trace behavior to executable code. Distinguish manifest validation,
+  resolved grants, shell registration and an actual executor. `AgentBundle`
+  loading alone does not start a peer or install instructions/skills.
+- Keep native `AppModule`, Splash script bundles and Octoscript L0 cards
+  distinct. `tools/octo` is Design Flow's Python CLI; octos is the agent
+  kernel. `card-host` supplies no registered host services or agent runtime.
+- For agent/storage changes, also inspect OctoSense `crates/shell/src/host_tools`,
+  `crates/shell/src/app_storage`, `crates/ai-host` and `crates/app-peers` at
+  the consumer's actual pin. Do not claim store script tools run merely
+  because `tools.json` passes the gate.
+- Preserve contract compatibility and refusal behavior. Consult
+  [app-contract's compatibility rules](crates/app-contract/README.md).
+  Do not widen an app's resolved grants in a mounting path.
+- Use the prepared sibling source layout from `Cargo.toml`; do not replace
+  pins or regenerate locks as a side effect of a documentation edit.
+- Match validation to the change: contract/policy/hub tests for admission,
+  `card-host` CLI tests for arguments, relevant service tests for lifecycle
+  changes. Documentation-only changes need source/link/command checks;
+  report unavailable builds or devices explicitly.
+- In walkthroughs, lead with a launch path, then trace one request to its
+  reply. Define routing terms at first use and keep source inventories after
+  the main path. Preserve prerequisites and capability limits in examples.
+- Keep English and Chinese README summaries aligned. Preserve historical
+  evidence and label source-reviewed commands separately from commands run.
+- Use hidden windows for automated GUI checks, a distinct bridge port and
+  app-data directory per instance, and quit only instances you started.
+- Do not change real `catalog.json`, `index/`, `artifacts/`, publisher keys
+  or publication status as part of ordinary documentation/development work.
+  Use a temporary local fixture for install tests; publishing follows
+  [PUBLISHING.md](docs/PUBLISHING.md) and the user's authorized scope.
+
+`AGENTS.md` instructs repository contributors. A bundle's singular
+`AGENT.md` is runtime app-agent material with separate contract rules.

README.md

@@ -4,14 +4,16 @@ English | [简体中文](README.zh-CN.md)
 
 The index of apps published for OctoSense, the signed catalog every OctoSense
 store reads, the hub's own copy of each admitted bundle, and the code that
-runs the hub and the store. No app code lives here; each app stays in its
-publisher's repository.
+runs the hub and the store. Publisher app source stays in each publisher's
+repository; this repository also contains the store UI, runtime hosts,
+templates and test fixtures.
 
 | Looking for | Repository |
 | --- | --- |
 | How to build an app: quickstart, script API, script-app template, design flows, examples | [OctoScript-App-Design-Flow](https://github.com/OctoSense-org/OctoScript-App-Design-Flow) |
-| The AppCard assistant runtime (opt-in in the shells, `--features app-appcard`) and the L0 card language | [OctoSense `apps/appcard`](https://github.com/OctoSense-org/OctoSense/tree/main/apps/appcard) |
+| The AppCard assistant runtime (opt-in in the shells, `--features app-appcard`) | [OctoSense `apps/appcard`](https://github.com/OctoSense-org/OctoSense/tree/main/apps/appcard) |
 | The first-party system apps (News, Photos, Maps, Camera, Mail, AI providers) and their host services (`mail`, `llm`) | [OctoSense `apps/`](https://github.com/OctoSense-org/OctoSense/tree/main/apps) |
+| The L0 parser/checker and its Makepad lowering/renderer | [Octoscript](https://github.com/OctoSense-org/Octoscript) and [Octoscript-Makepad](https://github.com/OctoSense-org/OctoScript-Makepad) |
 | The bundle format, the gate, signing, submission and the store | this repository |
 
 **Building an app?** Start at the [OctoSense-org profile](https://github.com/OctoSense-org)'s "read these first" list (OctoScript-App-Design-Flow's `AGENTS.md`, then its `docs/QUICKSTART.md`). You need this repository only as a sibling checkout to build `hub` and `card-host`, and to submit (an issue here, see [Submitting](docs/PUBLISHING.md#submitting)). Clone it; do not edit `catalog.json`, `index/` or `artifacts/`.
@@ -44,6 +46,15 @@ resolved from sibling checkouts (`../makepad`, `../octoscript-makepad`,
 runs the policy, gate, signing and store tests headless; `cargo run -p
 octosense-app-hub --bin hub` is the publishing tool.
 
+## Code walkthrough
+
+Start with [the walkthrough's host and launch choices](docs/CODE-WALKTHROUGH.md#2-run-the-right-host),
+then trace a bundle into its UI and a host-service reply back to its callback.
+A saved-notes request connects app-agent conversations, account storage and
+tool grants. The walkthrough distinguishes native `AppModule`, Splash and
+L0 apps, with the crate inventory at the end. Contributor instructions are
+in [AGENTS.md](AGENTS.md).
+
 ## Trust anchor
 
 Stores trust this anchor and follow its certificate to the working key that

README.zh-CN.md

@@ -2,13 +2,14 @@
 
 [English](README.md) | 简体中文
 
-这里是为 OctoSense 发布的应用索引、每个 OctoSense 商店都会读取的签名目录、App Hub 为每个已准入应用包保存的副本，以及运行 hub 和商店的代码。这里不存放任何应用代码，每个应用都留在其发布者自己的仓库中。
+这里是为 OctoSense 发布的应用索引、每个 OctoSense 商店都会读取的签名目录、App Hub 为每个已准入应用包保存的副本，以及运行 hub 和商店的代码。发布者的应用源码留在各自仓库中；本仓库也包含商店 UI、运行宿主、模板和测试夹具。
 
 | 想找 | 仓库 |
 | --- | --- |
 | 如何开发应用：快速上手、脚本 API、脚本应用模板、设计流程、示例 | [OctoScript-App-Design-Flow](https://github.com/OctoSense-org/OctoScript-App-Design-Flow) |
-| AppCard 助手运行时（在 Shell 中需 `--features app-appcard` 才启用）与 L0 卡片语言 | [OctoSense `apps/appcard`](https://github.com/OctoSense-org/OctoSense/tree/main/apps/appcard) |
+| AppCard 助手运行时（在 Shell 中需 `--features app-appcard` 才启用） | [OctoSense `apps/appcard`](https://github.com/OctoSense-org/OctoSense/tree/main/apps/appcard) |
 | 第一方系统应用（新闻、相册、地图、相机、邮件、AI providers）及其宿主服务（`mail`、`llm`） | [OctoSense `apps/`](https://github.com/OctoSense-org/OctoSense/tree/main/apps) |
+| L0 解析器/检查器及其 Makepad 转换/渲染层 | [Octoscript](https://github.com/OctoSense-org/Octoscript) 与 [Octoscript-Makepad](https://github.com/OctoSense-org/OctoScript-Makepad) |
 | 应用包格式、准入检查、签名、提交与商店 | 本仓库 |
 
 **要开发应用？** 请从 [OctoSense-org 主页](https://github.com/OctoSense-org)的“请按顺序先阅读”列表开始（先读 OctoScript-App-Design-Flow 的 `AGENTS.md`，再读其 `docs/QUICKSTART.md`）。你只需要把本仓库作为兄弟目录克隆下来，用于构建 `hub` 和 `card-host`，以及提交应用（在这里开 issue，见[提交](docs/PUBLISHING.md#submitting)）。不要修改 `catalog.json`、`index/` 或 `artifacts/`。
@@ -37,6 +38,13 @@
 
 这些 crate 基于固定版本的 OctoSense Makepad 与 Octoscript 分支构建，和启动器工作区一样，从同级检出目录（`../makepad`、`../octoscript-makepad`、`../octoscript`）解析依赖。`cargo test --workspace` 以无界面方式运行策略、准入检查、签名和商店测试；`cargo run -p octosense-app-hub --bin hub` 是发布工具。
 
+## 代码导读
+
+先看[代码导读中的宿主选择与启动命令（英文）](docs/CODE-WALKTHROUGH.md#2-run-the-right-host)，
+再追踪应用包如何进入 UI，以及宿主服务的应答如何回到回调函数。“总结已保存的笔记”
+这一请求串起应用 Agent 的对话、账户存储与工具授权。导读区分原生 `AppModule`、
+Splash 脚本和 L0 卡片，并把 crate 索引放在最后。仓库协作规则见 [AGENTS.md](AGENTS.md)。
+
 ## 信任锚
 
 商店信任这个锚，并沿着它的证书找到为目录签名的工作密钥。轮换工作密钥不需要发布新版商店。