docs: add app and agent architecture walkthroughs for Rust developers

AGENTS.md

@@ -49,3 +49,13 @@ On a machine that already has clones of Makepad, OctoScript or Octoscript-Makepa
 8. **Commit with a public identity.** Author and committer are your GitHub noreply address (for the maintainer, `ymote <151983+ymote@users.noreply.github.com>`) or another address you mean to publish; never a work or machine-local address. Check `git config user.email` before the first commit in a clone: a repository-local identity on a shared machine leaked a work address into this project's history once, and removing it took a history rewrite.
 9. **Keep docs honest and bilingual.** Every command in a doc was run; anything not run is marked **unverified**. User-facing docs are `README.md` plus `README.zh-CN.md`, linked by the single switcher line under the title (`English | [简体中文](README.zh-CN.md)`), and change together. `AGENTS.md` files are English only.
 10. **Keep signing keys, keystores, tokens and personal paths out of the repository.** `rom/tests/test_no_local_paths.py` checks for local paths.
+
+## Architecture documentation and code walkthroughs
+
+Start with the [architecture walkthrough](docs/architecture-walkthrough.md) and [product walkthrough](desktop/docs/code-walkthrough.md), then follow the source symbols. Update English/Chinese guides and README entry points together when changing a boundary.
+
+- For hosting changes, document the module/process/Splash/card loader and its identity source in `module_host`, `peer_link`, or App Hub's runner.
+- For agent changes, trace `contract.rs` → `broker.rs` → the owning executor. Describe the peer/account identity, system session and human context separately from their runtime tasks.
+- For a new tool, update its manifest, `tools.json`, admission offer, caller grant and executable handler. Show which host service or workspace owns its data and how approval reaches the router.
+- Read external code at the Cargo/runtime pins. Use current `desktop/`, `phone/`, `rom/` and `apps/` paths when writing product instructions.
+- Record test execution in the PR: distinguish unit/scripted connectors from optional real-kernel tests that return early without a binary. Mark unrun launch/device recipes unverified.

apps/AGENTS.md

@@ -36,18 +36,20 @@ app's own agent and `tools.json`, the system toolbox, `glance.publish` and
   `cargo test --locked -p octosense-mail-service`. Calendar's and News's:
   `apps/calendar/host-service`, `apps/news/host-service`, and
   `cargo test --locked -p octosense-calendar-service -p octosense-news-service`.
-- An app's agent (News, Mail, Calendar) is declared by its manifest's
-  `agent` block and `bundle/tools.json`; each tool runs on the app's host
-  service (`implemented_by: "host-service"`), so a new tool is a new
-  host-service method plus its `tools.json` entry, with schemas that match
-  what the method answers (octos needs an object `output_schema`). Give a
-  tool the smallest `risk` that is true: `destructive` and outward tools get
-  the person's approval, `act` ones do not. A tool that shows something on
-  the glance screen fills a fixed L0 card the host service ships
-  (`resources/*.card`) and publishes it through the publisher the shell
-  installs (`on_publish_card`); never let the model write card code. The
-  app needs `glance` in its manifest. See the README's
-  [App agents](README.md#app-agents).
+- Declare an app's agent in its manifest and `bundle/tools.json`. Keep the
+  input/output schemas consistent with the executor (octos requires an object
+  output schema), and select the actual risk, sharing and confirmation policy.
+  Add the implementation before adding a tool declaration; `implemented_by:
+  "app"` still has no Card runner executor.
+- For a notification tool, follow `../crates/shell/src/glance_notice.rs`.
+  Mail/News install `on_notify` callbacks; the shell's `NoticeService` serves
+  Photos, Maps, YouTube and Camera. The fixed notice template lives in
+  `../crates/shell/resources/glance/notice.card`; Calendar keeps its own event
+  and agenda templates. Grant `glance` in the manifest and publish as the app.
+- For richer app-owned cards, use `glance.publish` with either L0 `source` and
+  optional `data`, or a Splash `script`. Preserve app attribution, policy and
+  the distinction between app UI actions and agent tool calls. See
+  [App agents](README.md#app-agents) and the shell's glance tests.
 - There are no pins to bump: both shells pack `apps/` from the same commit
   (`desktop/system-apps.json`, `phone/system-apps.json`), so one pull request
   carries a change to every shell. App Hub, octos and the runtime are pinned
@@ -80,7 +82,9 @@ app's own agent and `tools.json`, the system toolbox, `glance.publish` and
 
 ## AppCard (apps/appcard)
 
-AppCard is the one native app: Rust crates, not a bundle. Its own rules
+AppCard is an opt-in native assistant: Rust crates, not a bundle. Reference
+(`apps/reference`) is another native app; other native apps are linked from
+external crates through `native-apps.json`. Its own rules
 are in [appcard/AGENTS.md](appcard/AGENTS.md); in short:
 
 - Its crates (`apps/appcard/app/app`, `apps/appcard/app/crates/*`,
@@ -105,3 +109,21 @@ are in [appcard/AGENTS.md](appcard/AGENTS.md); in short:
   dependency.
 - CI for it is the `apps` job of `.github/workflows/apps.yml`, which runs on
   changes under `apps/`, `crates/` and the workspace files.
+
+## Changing tools and data access
+
+Trace each tool from `bundle/tools.json` through
+`../crates/shell/src/host_tools/script_apps.rs` to its executor. Test schemas,
+caller identity, approval behavior and results at that boundary. Keep UI API
+methods separate from the tools actually declared for the agent: Mail currently
+exposes only `mail.notify`; News exposes list/read/notify; Photos, Maps, YouTube
+and Camera expose notify only. AI providers declares no app agent.
+
+Use the [product walkthrough](../desktop/docs/code-walkthrough.md) for the data
+and notice paths. For a cross-app tool, update the owner's shareable declaration,
+requesting app's grant and App Hub admission offer together. Keep credentials in
+the host service; expose business data through a narrow method or tool.
+
+Update both README languages when declarations, storage or runtime support
+change. Add agent scheduling claims only when the trigger dispatcher exists;
+News's fetch timer currently collects data without starting an LLM turn.