From 4bb50454928f8779f7fdacaa20f1b1b02dbe12a0 Mon Sep 17 00:00:00 2001 From: ymote <151983+ymote@users.noreply.github.com> Date: Fri, 2 Oct 2026 00:09:34 -0700 Subject: [PATCH 1/5] docs: explain app development flow and runtime integration --- AGENTS.md | 31 +++- README.md | 19 ++- README.zh-CN.md | 16 +- docs/CODE-WALKTHROUGH.md | 312 +++++++++++++++++++++++++++++++++++++++ 4 files changed, 367 insertions(+), 11 deletions(-) create mode 100644 docs/CODE-WALKTHROUGH.md diff --git a/AGENTS.md b/AGENTS.md index e915c6b4..f8d70be5 100644 --- a/AGENTS.md +++ b/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/commands without pretending to complete an app-authoring flow. +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:/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,24 @@ 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. +- 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()`; diff --git a/README.md b/README.md index be210cdc..f13b52ad 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,8 @@ 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` forwards `hub check` output and exit +status, and adds wrapper progress and listing-placeholder notes. Who it is for: hackathon contestants and other developers building an OctoSense app, and the coding agents they work with. @@ -23,6 +24,15 @@ 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 for Rust beginners + +[docs/CODE-WALKTHROUGH.md](docs/CODE-WALKTHROUGH.md) traces the Python CLI, +script template, image/card pipeline and runtime pins into App Hub and the +OctoSense shell. It explains native Rust versus Splash/L0 apps, how to run +a bundle, app-agent data access and conversations, cross-app tool limits, +and where Tokio belongs. `tools/octo` is the development CLI; octos is the +separate agent kernel. + ## Contents - [Hackathon: start here](#hackathon-start-here) @@ -263,8 +273,9 @@ 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 @@ -517,7 +528,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 diff --git a/README.zh-CN.md b/README.zh-CN.md index 031907ff..f1c54df9 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -12,7 +12,7 @@ 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。 @@ -20,6 +20,15 @@ Agent）从一个想法（一段文字需求、一张生成的 UX 图）走到 自 2026-09-27 起位于 [OctoSense `apps/`](https://github.com/OctoSense-org/OctoSense/tree/main/apps) （OctoSense-System-Apps 已归档，不再公开）。 +## 面向 Rust 初学者的代码导读 + +[代码导读（英文）](docs/CODE-WALKTHROUGH.md) 从 Python CLI、脚本模板、图像/卡片 +流水线和运行时版本追踪到 App Hub 与 OctoSense Shell，解释原生 Rust、Splash 与 L0 +应用的差别、实际运行方式、应用 Agent 的数据访问和对话、跨应用工具限制，以及 Tokio +所在的层级。`tools/octo` 是开发命令；octos 是独立的 Agent 内核。 +`main.splash` 由 Makepad Script 在 Splash 隔离环境中求值，与 Octoscript L0 +（`page.card`）的解析路径不同。 + ## 目录 - [黑客松：从这里开始](#黑客松从这里开始) @@ -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")`）。应用可以调用的全部内容， @@ -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) | 应用运行所依赖的框架与语言 | ## 许可证 diff --git a/docs/CODE-WALKTHROUGH.md b/docs/CODE-WALKTHROUGH.md new file mode 100644 index 00000000..5434c476 --- /dev/null +++ b/docs/CODE-WALKTHROUGH.md @@ -0,0 +1,312 @@ +# Walk an app from this repository into OctoSense + +For a junior Rust developer, begin with the executable path: this repository +is primarily a Python development harness, not the app's Rust runtime or +the octos agent kernel. This review follows Design Flow `caa5d364` and App +Hub `41bc959` on 2026-10-01. GUI, build, model-provider and device commands +below are **unverified in this review** unless specifically recorded as run. + +## 1. Three kinds of source, two kinds of agent + +| Name | Meaning and code owner | +| --- | --- | +| Native Rust app | A compiled `AppModule` hosted standalone or inside the OctoSense shell | +| `main.splash` | A script program evaluated by Makepad Script in a Splash isolate; the template here uses it | +| `page.card` / L0 | Declarative card source parsed/realized by Octoscript and lowered by Octoscript-Makepad into Makepad UI | +| `tools/octo` | This repository's Python command wrapping App Hub's `hub` and `card-host` | +| octos | Rust agent kernel managed by OctoSense; unrelated to the spelling of this CLI | +| Coding agent | An optional development assistant following this repository's `AGENTS.md` | +| App agent | A runtime peer that the device's shell prepares for an allowed app | + +Splash script and Octoscript L0 reach the same UI host by different parsing +paths. A native Rust app may embed script UI while keeping its operations +in compiled Rust. Neither an app bundle nor this CLI automatically starts +an AI agent. The shell supplies the model provider, permissions, peer and +conversation routes. + +Repository `AGENTS.md` is for development. A bundle's singular `AGENT.md` +is declared runtime agent material. App Hub validates the latter, but the +current shell does not install its instructions or skills into the peer. + +## 2. Read these files in order + +1. [`tools/octo`](../tools/octo): CLI dispatch, binary discovery, app + creation, process launch, screenshots and admission checks. +2. [`templates/script-app/bundle/main.splash`](../templates/script-app/bundle/main.splash) + and [`manifest.json`](../templates/script-app/bundle/manifest.json): + the actual small notes app and its requested permissions. +3. [`SCRIPT-API.md`](SCRIPT-API.md): the callable script API and lifetime + rules, including `ui` availability and callbacks. +4. [`flows/script-app/FLOW.md`](../flows/script-app/FLOW.md): how to turn + a brief into a tested app without making up host APIs. +5. [`flows/image-to-card/flow.py`](../flows/image-to-card/flow.py): the + separate orchestration path for visual/card projects. +6. [`flows/core/native_runtime.py`](../flows/core/native_runtime.py): + how runtime source versions are prepared and checked. + +Then follow the runtime in +[App Hub's code walkthrough](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/main/docs/CODE-WALKTHROUGH.md) +and the complete shell/peer path in +[OctoSense](https://github.com/OctoSense-org/OctoSense/blob/main/docs/architecture-walkthrough.md). + +## 3. Trace `tools/octo new`, `run`, `shot`, `check` + +`hub_repo` selects `OCTOSENSE_APP_HUB`, or the sibling App Hub checkout. +`find_binary` checks explicit `OCTO_HUB`/`OCTO_CARD_HOST`, candidate release +directories and `PATH`. It checks the `hub help` banner when searching so +GitHub's unrelated `hub` executable is not mistaken for App Hub. Explicit +binary overrides are the caller's responsibility. + +`cmd_new` validates the app id, rejects `os.*` without `--system`, copies +the template and contributor instructions, and edits name/version/id in +the new manifest. It stamps when `hub` is available. A directory containing +the template is not yet a publishable app: listing placeholders and artwork +still need the author's work. + +`cmd_run` requires a manifest and a free remote port. It constructs: + +```text +card-host --bundle --app-data + --allow-unsigned --stamp +``` + +`--no-stamp` omits the write; `--system` requests system-app admission. +The default state directory is `/.local-state`. +`MAKEPAD_REMOTE` selects the bridge port; `--hidden` sets +`MAKEPAD_HIDE_WINDOWS=1` and removes a focus override. + +There are two process modes, which matter in scripts: + +- Without `--detach`, Python waits for `card-host` to exit. A visible or + hidden app keeps this terminal occupied. +- With `--detach`, it writes `card-host.log`, waits for admission and the + expected process's bridge, verifies `/s` returns the new process id, + waits for app widgets in `/snap` and a rendered frame, then returns. + Startup failure terminates only the process it started. + +`cmd_shot` uses the bridge's `/g?raw=1`, verifies PNG bytes, waits for app +widgets and attempts to capture two identical frames. An animation can +exhaust the settling interval; the tool reports that and keeps the last +frame. A file existing is not a visual review: open the capture. + +`cmd_check` calls the real `hub stamp` for unsigned bundles and then +`hub check`, forwarding extra gate flags and returning its exit status. +For a signed manifest it skips restamping. It also prints wrapper status +and listing-placeholder notes, so the **gate output is forwarded**, not +necessarily the CLI's only output. The gate itself lives in App Hub, never +in this Python command. + +## 4. Run a contained script app + +Follow [QUICKSTART](QUICKSTART.md) for cloning/prerequisites. Use a prepared +workspace with this repository, App Hub, `makepad`, `octoscript-makepad` +and `octoscript` as siblings. From Design Flow: + +```sh +python3 tools/setup-native.py +python3 tools/setup-native.py --check +``` + +From the App Hub sibling: + +```sh +cargo build --release -p octosense-card-host -p octosense-app-hub +``` + +Back in Design Flow: + +```sh +tools/octo doctor +tools/octo new /tmp/octosense-walkthrough-notes --id walkthrough.notes --name "Walkthrough Notes" +tools/octo run /tmp/octosense-walkthrough-notes/bundle --hidden --detach --port 8141 +curl -s http://127.0.0.1:8141/snap +tools/octo shot 8141 /tmp/octosense-walkthrough-notes/first-frame.png +curl -s http://127.0.0.1:8141/quit +``` + +Use a new destination if that directory already exists, and a different +port if occupied. This captures evidence outside the submission bundle. +For publication, first complete the listing and capture its named +screenshots, then run: + +```sh +tools/octo check /tmp/octosense-walkthrough-notes/bundle +``` + +The untouched template may fail the complete submission gate; the +walkthrough does not claim it is publication-ready. `run` modifies the +manifest by default and `card-host` cannot verify signed manifests. Use a +development copy, and use the store path for signing/install tests. + +The same host accepts an L0 `page.card` bundle with its data and kit. The +runtime first looks for the script entry; otherwise it prepares/lowers the +card. This is not `cargo run` on a native app crate. To run a native Rust +app, desktop shell, Android Home app or ROM, use the commands in +[OctoSense's README](https://github.com/OctoSense-org/OctoSense/blob/main/README.md). +The ROM packages the shell with the operating system; creating a bundle +here does not build or flash it. + +## 5. Understand what the standalone run proves + +`card-host` applies the manifest policy before evaluating the UI. That +checks the contained app path: script/card parsing, rendering, jail storage, +network allowlist and declared capabilities. It has the host-request +transport but **registers no services**. `mail.*`, `model.complete`, +`octos.*` and `glance.*` therefore cannot be tested end to end there. + +The shell uses App Hub's `CardModule`, plus its own registered Rust services. +A script call follows this route: + +```mermaid +sequenceDiagram + participant UI as Splash app + participant Host as Card runner / host services + participant Agent as Shell app peer + participant Kernel as octos / model + UI->>Host: host.request("octos.turn.start", args, callback) + Host->>Host: Check grant and app-agent consent + Host->>Agent: Route request on this app's context + Agent->>Kernel: Start model turn with allowed tools + Kernel-->>Agent: Events and completion + Agent-->>Host: Reply/event data + Host-->>UI: Deliver to original isolate callback +``` + +The exact request/event schemas and graceful unavailable example are in +[AI-SERVICES](AI-SERVICES.md). A one-shot `model.complete` uses a separate +service and does not imply a peer conversation. `llm` manages provider +configuration for system apps; it is not a general prompt API. + +To test your app in the desktop shell before public submission, follow +[the local signed-catalog rehearsal](PUBLISHING.md#4-rehearse-the-store-path-locally). +The standalone store installs but does not launch a shell app. A phone's +stock Home build does not gain a development catalog just because you set +environment variables in your Mac terminal; see +[the phone limitations](QUICKSTART.md#9-run-it-on-an-octosense-phone). + +## 6. How an app agent reaches data, people and other agents + +A runtime app agent is a model conversation restricted to one app/account. +The shell asks the person to allow it, prepares its peer, installs available +tool declarations and opens conversation contexts. On desktop, **Ask +<app>** is a host-owned human chat surface. App-owned `octos.*` screens +and supported L0 `sys.chat` cards are other entry points. The general phone +per-app panel entry is not present at the reviewed shell snapshot. + +The system assistant can discover allowed, prepared peers and send work +using their **peer slug**, then gather their replies. Human and system +requests use distinct contexts on the app's peer. A reply goes to the +requesting context; being on the same peer does not merge both transcripts. + +The shell normally gives an app agent bounded read tools over +`accounts/device/` for a single-account app, or the active account folder. +`storage.agent_workspace` controls whether such a workspace is exposed. +This does not mean the agent understands every file format or can read +arbitrary paths. If the UI saves a record at the jail root, it is not +automatically inside the agent's account workspace. Store data there +deliberately or expose a supported tool. Host-service credentials and +`.host` state remain outside the app's jail. + +An app's `tools.json` describes APIs for model callers. It is not executable +script registration. At this snapshot, first-party host-service handlers +can execute tools; a store app's `implemented_by: "app"` tool has no shell +dispatcher. `AGENT.md`, skills, background triggers and model `needs` +likewise have more contract support than runtime wiring. Do not build an +app whose essential behavior depends on these missing paths. + +Cross-app tool use needs an owner's shareable declaration, the caller's +grant, host admission and an executable route. Destructive/outward calls +also have supervision policy. A field requesting `mail.send` is not enough: +App Hub's default `HostLimits::offered_tools` does not contain arbitrary +other-app names. The only plain kernel tool allowed in a contained agent's +`agent.tools` is `ask_user_question`; peer and unrestricted file/shell tools +are not inherited from the system assistant. System-to-app delegation is +implemented; arbitrary app-to-system delegation is not an implied grant. + +## 7. Where Tokio fits + +This repository's CLI starts operating-system child processes and polls an +HTTP bridge. It does not schedule Tokio tasks. App Hub runs UI events, +request/reply queues and worker threads. The shell-managed octos runtime has asynchronous sessions/turns and peer +routing. Desktop normally launches a separate kernel process; the broker +and kernel-service runtimes live in the shell. A peer identity, +conversation context, running future and worker thread are different +objects: one app peer can serve separate contexts over time; it is not one +permanent thread or one task per widget. + +For the exact `tokio::spawn`, channels, cancellation and UI handoff, continue +in OctoSense's `crates/ai-host`, `crates/app-peers` and the octos dependency +at the shell's pin. The end-to-end +[shell walkthrough](https://github.com/OctoSense-org/OctoSense/blob/main/docs/architecture-walkthrough.md) +connects those objects to Rust code. + +## 8. The image/card design path is a separate pipeline + +[`tools/image-to-appcard-flow.sh`](../tools/image-to-appcard-flow.sh) invokes +[`flows/image-to-card/flow.py`](../flows/image-to-card/flow.py). +`read_manifest` validates the project schema, scene ids, relative paths, +406×776 artboard, 8–12 scenes, and `en`/`cn` locales. `local` prevents paths +escaping the project. `fingerprint` hashes the manifest and input artifacts +so evidence can be tied to source bytes. + +`STAGES` names intake, prepare, observe, measure, map, semantic, compile, +capture, gate, extract, bundle, service-test, wasm, integrate, web-test and +hosted-test. `commands_for` builds stage commands; configured checks use +argument arrays, not shell command strings. `run` records execution +evidence. The default stage subset is not proof that all visual, service, +browser and hosted checks ran. `plan` describes work; it does not perform +the checks it prints. + +Shared policy/review/repair logic is in +[`flows/core`](../flows/core/README.md). The script-app flow does not require +an image pipeline. A browser preview validates its own route, not native +rendering or shell services. Follow the chosen flow's evidence and human +checkpoints when actually authoring or publishing; a repository code review +does not need to invent app screenshots or submit a bundle. + +## 9. Pins, checks and useful failure boundaries + +[`native-runtime.lock.json`](../native-runtime.lock.json) selects +Octoscript-Makepad `cb66de073469063abeb2a5ab2a2bbf3cdb365745`. +Its `runtime.json` then owns the underlying Makepad and Octoscript revisions. +`setup-native.py` delegates to the runtime preparation/verification code; +`--check` inspects rather than updates the prepared set. It is possible for +OctoSense main to support `sys.chat` while this older authoring pin cannot. +Do not erase that difference by casually changing a shared sibling checkout. + +Lightweight checks for a documentation/CLI review: + +```sh +python3 tools/check-links.py +python3 tools/octo --help +python3 tools/octo run --help +python3 -m unittest discover -s flows/tests -p 'test_octo_run.py' +``` + +The link checker checks tracked Markdown and skips historical evidence; +it does not fetch external URLs or verify anchors. Check newly added files +as well. `doctor` proves executable discovery, not a GPU launch or a model +conversation. Runtime setup checks prove source pins, not a device build. + +| Failure | Investigate | +| --- | --- | +| `hub` not found | Explicit binary paths, release build and sibling layout | +| Busy port | Existing process identity; choose another port, do not kill unrelated apps | +| Admitted but no app widgets | `card-host.log`, `/snap`, script/lowering diagnostics | +| `no service answers` | Wrong host for the test or absent shell registration | +| Gate accepts agent metadata, runtime feature absent | AI status table and actual shell executor/setup code | +| Agent misses a saved note | Account workspace versus UI storage location | +| New shell card syntax fails in authoring | Consumer runtime pins before changing app source | + +Preserve dated historical verification in existing docs. For new claims, +report the exact command and result, and distinguish source inspection, +mocked/unit checks, real native execution, provider-backed AI and device +testing. + +Review verification (2026-10-01): `tools/check-links.py` reported 0 broken / +0 pending; the changed-file link check also passed; both CLI help commands +passed; `test_octo_run.py` passed all 6 tests using fake processes/HTTP +bridges. `tools/octo doctor` reported missing `hub` and `card-host` binaries +in this isolated review workspace. `tools/setup-native.py --check` refused +the unprepared locked runtime. No shared runtime checkout was changed to +make those checks pass; native builds and launches remain unverified. From 71163c03d55edd3e6371947e1d6eab8f982bf088 Mon Sep 17 00:00:00 2001 From: ymote <151983+ymote@users.noreply.github.com> Date: Fri, 2 Oct 2026 00:55:31 -0700 Subject: [PATCH 2/5] docs: address architecture review and clarify runtime boundaries --- AGENTS.md | 4 +- README.md | 12 +- README.zh-CN.md | 13 +-- docs/CODE-WALKTHROUGH.md | 242 ++++++++++++++++++++++----------------- 4 files changed, 155 insertions(+), 116 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f8d70be5..9e291375 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,7 +6,7 @@ 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. For repository architecture/documentation work, read [docs/CODE-WALKTHROUGH.md](docs/CODE-WALKTHROUGH.md): trace code and -check links/commands without pretending to complete an app-authoring flow. +check links and commands. The screenshot, gate and publishing checklist below applies when delivering an app bundle, not when reviewing this repository's documentation. @@ -14,7 +14,7 @@ an app bundle, not when reviewing this repository's documentation. | 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: [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) | +| 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) | diff --git a/README.md b/README.md index f13b52ad..ab917522 100644 --- a/README.md +++ b/README.md @@ -13,8 +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` forwards `hub check` output and exit -status, and adds wrapper progress and listing-placeholder notes. +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. @@ -24,7 +25,7 @@ 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 for Rust beginners +## Code walkthrough [docs/CODE-WALKTHROUGH.md](docs/CODE-WALKTHROUGH.md) traces the Python CLI, script template, image/card pipeline and runtime pins into App Hub and the @@ -275,7 +276,8 @@ screenshots, the platforms you actually tested, age rating and the publisher **`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 +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 @@ -330,7 +332,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 " 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 diff --git a/README.zh-CN.md b/README.zh-CN.md index f1c54df9..1bc2c77d 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -12,7 +12,8 @@ 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` 的输出与退出码，并额外输出封装层进度和 listing 占位符提示。 +先为未签名的包写入摘要，再转发 `hub check` 的输出与退出码，并显示进度和清单（listing） +占位提示。摘要写入失败时，命令立即返回其错误码，不运行准入检查。 面向：参加黑客松的选手、其他开发 OctoSense 应用的开发者，以及与他们协作的编码 Agent。 @@ -20,14 +21,12 @@ Agent）从一个想法（一段文字需求、一张生成的 UX 图）走到 自 2026-09-27 起位于 [OctoSense `apps/`](https://github.com/OctoSense-org/OctoSense/tree/main/apps) （OctoSense-System-Apps 已归档，不再公开）。 -## 面向 Rust 初学者的代码导读 +## 代码导读 -[代码导读（英文）](docs/CODE-WALKTHROUGH.md) 从 Python CLI、脚本模板、图像/卡片 -流水线和运行时版本追踪到 App Hub 与 OctoSense Shell，解释原生 Rust、Splash 与 L0 +[代码导读（英文）](docs/CODE-WALKTHROUGH.md) 沿着 Python CLI、脚本模板、图像/卡片 +流水线和运行时版本，一路讲到 App Hub 与 OctoSense Shell，解释原生 Rust、Splash 与 L0 应用的差别、实际运行方式、应用 Agent 的数据访问和对话、跨应用工具限制，以及 Tokio 所在的层级。`tools/octo` 是开发命令；octos 是独立的 Agent 内核。 -`main.splash` 由 Makepad Script 在 Splash 隔离环境中求值，与 Octoscript L0 -（`page.card`）的解析路径不同。 ## 目录 @@ -291,7 +290,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 ”面板、卡片内对话、应用自己的界面），系统 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` 和 diff --git a/docs/CODE-WALKTHROUGH.md b/docs/CODE-WALKTHROUGH.md index 5434c476..5f4b2677 100644 --- a/docs/CODE-WALKTHROUGH.md +++ b/docs/CODE-WALKTHROUGH.md @@ -1,12 +1,12 @@ # Walk an app from this repository into OctoSense -For a junior Rust developer, begin with the executable path: this repository -is primarily a Python development harness, not the app's Rust runtime or -the octos agent kernel. This review follows Design Flow `caa5d364` and App -Hub `41bc959` on 2026-10-01. GUI, build, model-provider and device commands -below are **unverified in this review** unless specifically recorded as run. +This repository is a Python development harness. The Rust hosts live in +App Hub; OctoSense supplies the shell and manages the octos agent kernel. +Start with the CLI, then follow the bundle into its runtime. Runtime versions +come from [`native-runtime.lock.json`](../native-runtime.lock.json) and the +selected framework's `runtime.json`. -## 1. Three kinds of source, two kinds of agent +## 1. Names and responsibilities | Name | Meaning and code owner | | --- | --- | @@ -20,9 +20,8 @@ below are **unverified in this review** unless specifically recorded as run. Splash script and Octoscript L0 reach the same UI host by different parsing paths. A native Rust app may embed script UI while keeping its operations -in compiled Rust. Neither an app bundle nor this CLI automatically starts -an AI agent. The shell supplies the model provider, permissions, peer and -conversation routes. +in compiled Rust. The shell supplies the model provider, permissions, peer +and conversation routes for an app agent. Repository `AGENTS.md` is for development. A bundle's singular `AGENT.md` is declared runtime agent material. App Hub validates the latter, but the @@ -45,9 +44,9 @@ current shell does not install its instructions or skills into the peer. how runtime source versions are prepared and checked. Then follow the runtime in -[App Hub's code walkthrough](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/main/docs/CODE-WALKTHROUGH.md) +[App Hub's code walkthrough](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/docs/junior-architecture-walkthrough/docs/CODE-WALKTHROUGH.md) and the complete shell/peer path in -[OctoSense](https://github.com/OctoSense-org/OctoSense/blob/main/docs/architecture-walkthrough.md). +[OctoSense](https://github.com/OctoSense-org/OctoSense/blob/docs/junior-architecture-walkthrough/docs/architecture-walkthrough.md). ## 3. Trace `tools/octo new`, `run`, `shot`, `check` @@ -59,9 +58,8 @@ binary overrides are the caller's responsibility. `cmd_new` validates the app id, rejects `os.*` without `--system`, copies the template and contributor instructions, and edits name/version/id in -the new manifest. It stamps when `hub` is available. A directory containing -the template is not yet a publishable app: listing placeholders and artwork -still need the author's work. +the new manifest. It stamps when `hub` is available. Complete the listing, +artwork and screenshots before submitting the generated app. `cmd_run` requires a manifest and a free remote port. It constructs: @@ -87,20 +85,21 @@ There are two process modes, which matter in scripts: `cmd_shot` uses the bridge's `/g?raw=1`, verifies PNG bytes, waits for app widgets and attempts to capture two identical frames. An animation can exhaust the settling interval; the tool reports that and keeps the last -frame. A file existing is not a visual review: open the capture. +frame. Open the PNG and look at it. -`cmd_check` calls the real `hub stamp` for unsigned bundles and then -`hub check`, forwarding extra gate flags and returning its exit status. -For a signed manifest it skips restamping. It also prints wrapper status -and listing-placeholder notes, so the **gate output is forwarded**, not -necessarily the CLI's only output. The gate itself lives in App Hub, never -in this Python command. +`cmd_check` calls `hub stamp` for unsigned bundles. If stamping fails, it +prints that command's output, returns its failure status and skips the gate. +Otherwise it runs `hub check`, forwards extra gate flags and returns the +gate's exit status. A signed manifest skips stamping. The command also +prints progress lines and listing-placeholder notes. App Hub owns admission +policy; this Python command handles the development sequence. ## 4. Run a contained script app Follow [QUICKSTART](QUICKSTART.md) for cloning/prerequisites. Use a prepared workspace with this repository, App Hub, `makepad`, `octoscript-makepad` -and `octoscript` as siblings. From Design Flow: +and `octoscript` as siblings. **Validation status: build, GUI and device +execution unverified.** From Design Flow: ```sh python3 tools/setup-native.py @@ -133,18 +132,18 @@ screenshots, then run: tools/octo check /tmp/octosense-walkthrough-notes/bundle ``` -The untouched template may fail the complete submission gate; the -walkthrough does not claim it is publication-ready. `run` modifies the -manifest by default and `card-host` cannot verify signed manifests. Use a -development copy, and use the store path for signing/install tests. +The untouched template names a screenshot that you still need to capture; +finish its listing and screenshot files before the full gate can pass. +`run` stamps the manifest by default. Use an unsigned development copy for +`card-host` and the store path for signing/install tests. The same host accepts an L0 `page.card` bundle with its data and kit. The runtime first looks for the script entry; otherwise it prepares/lowers the -card. This is not `cargo run` on a native app crate. To run a native Rust -app, desktop shell, Android Home app or ROM, use the commands in +card. Native Rust apps use their own Cargo targets. For a native app, +desktop shell, Android Home app or ROM, use the commands in [OctoSense's README](https://github.com/OctoSense-org/OctoSense/blob/main/README.md). -The ROM packages the shell with the operating system; creating a bundle -here does not build or flash it. +The ROM packages the shell with the operating system and has a separate +build and flash workflow. ## 5. Understand what the standalone run proves @@ -174,51 +173,65 @@ sequenceDiagram The exact request/event schemas and graceful unavailable example are in [AI-SERVICES](AI-SERVICES.md). A one-shot `model.complete` uses a separate -service and does not imply a peer conversation. `llm` manages provider -configuration for system apps; it is not a general prompt API. +service for a single model request. `llm` manages provider configuration +for system apps. To test your app in the desktop shell before public submission, follow [the local signed-catalog rehearsal](PUBLISHING.md#4-rehearse-the-store-path-locally). -The standalone store installs but does not launch a shell app. A phone's -stock Home build does not gain a development catalog just because you set -environment variables in your Mac terminal; see +The standalone store installs bundles; the full shell launches their app +clients. Phone catalog configuration belongs to the Home build; see [the phone limitations](QUICKSTART.md#9-run-it-on-an-octosense-phone). ## 6. How an app agent reaches data, people and other agents A runtime app agent is a model conversation restricted to one app/account. The shell asks the person to allow it, prepares its peer, installs available -tool declarations and opens conversation contexts. On desktop, **Ask -<app>** is a host-owned human chat surface. App-owned `octos.*` screens -and supported L0 `sys.chat` cards are other entry points. The general phone -per-app panel entry is not present at the reviewed shell snapshot. - -The system assistant can discover allowed, prepared peers and send work -using their **peer slug**, then gather their replies. Human and system -requests use distinct contexts on the app's peer. A reply goes to the -requesting context; being on the same peer does not merge both transcripts. - -The shell normally gives an app agent bounded read tools over -`accounts/device/` for a single-account app, or the active account folder. -`storage.agent_workspace` controls whether such a workspace is exposed. -This does not mean the agent understands every file format or can read -arbitrary paths. If the UI saves a record at the jail root, it is not -automatically inside the agent's account workspace. Store data there -deliberately or expose a supported tool. Host-service credentials and +tool declarations and opens conversation contexts. On desktop, `Ask ` +is a host-owned human chat surface. App-owned `octos.*` screens and +supported L0 `sys.chat` cards are other entry points; the +[shell walkthrough](https://github.com/OctoSense-org/OctoSense/blob/docs/junior-architecture-walkthrough/docs/architecture-walkthrough.md#6-where-a-person-talks-and-where-the-answer-goes) +explains their routing. + +The system assistant discovers allowed, prepared peers and sends work using +their **peer slug**. The system lane runs on the app peer's own session; +its result reaches the peer blackboard for the system assistant to gather. +The human lane runs on a separate sharing-context session of that peer; +its events and completion return to the human conversation's event sink. +Each lane owns its transcript. Sharing provides bounded recent history from +the other lane, and the shell panel can display both. + +On Unix, the shell gives an app agent bounded `files.list/read/search` +tools when the person has consented and an account workspace is available. +They read `accounts/device/` for a single-account app, or the active account +folder. `storage.agent_workspace` controls whether that workspace is exposed. +Put records the agent should read in that account folder, or expose a +supported tool that interprets them. A record saved at the jail root stays +outside the account workspace. Host-service credentials and `.host` state remain outside the app's jail. -An app's `tools.json` describes APIs for model callers. It is not executable -script registration. At this snapshot, first-party host-service handlers -can execute tools; a store app's `implemented_by: "app"` tool has no shell -dispatcher. `AGENT.md`, skills, background triggers and model `needs` -likewise have more contract support than runtime wiring. Do not build an -app whose essential behavior depends on these missing paths. +An app's `tools.json` describes APIs for model callers. First-party +host-service handlers execute their declared tools; a store app's +`implemented_by: "app"` tool still needs a script dispatcher in the shell. +`AGENT.md`, skills, background triggers and model `needs` are validated +metadata awaiting runtime wiring. Use implemented services for essential +app behavior. + +The system bundles demonstrate this split: News has read and notification +tools; Mail has `mail.notify`; Calendar has event and card tools. Photos, +Maps, Camera and YouTube declare their own `.notify`, executed +by the shell's shared +[`glance_notice` service](https://github.com/OctoSense-org/OctoSense/blob/main/crates/shell/src/glance_notice.rs). +These declarations add an agent and a notice route, not general access to +camera controls or photo records. AI providers remains excluded from that +set: its `ai-providers` namespace fails the tool-name rule. The shell's +[`script_apps` tests](https://github.com/OctoSense-org/OctoSense/blob/main/crates/shell/src/host_tools/script_apps.rs) +record these exact tool rosters. Cross-app tool use needs an owner's shareable declaration, the caller's grant, host admission and an executable route. Destructive/outward calls -also have supervision policy. A field requesting `mail.send` is not enough: -App Hub's default `HostLimits::offered_tools` does not contain arbitrary -other-app names. The only plain kernel tool allowed in a contained agent's +also have supervision policy. App Hub admission checks the request against +`HostLimits::offered_tools`; its default list excludes arbitrary other-app +names such as `mail.send`. The only plain kernel tool allowed in a contained agent's `agent.tools` is `ask_user_question`; peer and unrestricted file/shell tools are not inherited from the system assistant. System-to-app delegation is implemented; arbitrary app-to-system delegation is not an implied grant. @@ -226,55 +239,93 @@ implemented; arbitrary app-to-system delegation is not an implied grant. ## 7. Where Tokio fits This repository's CLI starts operating-system child processes and polls an -HTTP bridge. It does not schedule Tokio tasks. App Hub runs UI events, -request/reply queues and worker threads. The shell-managed octos runtime has asynchronous sessions/turns and peer +HTTP bridge. App Hub runs UI events, request/reply queues and worker threads. +The shell-managed octos runtime has asynchronous sessions/turns and peer routing. Desktop normally launches a separate kernel process; the broker -and kernel-service runtimes live in the shell. A peer identity, -conversation context, running future and worker thread are different -objects: one app peer can serve separate contexts over time; it is not one -permanent thread or one task per widget. +and kernel-service runtimes live in the shell. One peer can hold several +conversation contexts over its lifetime. Tokio tasks execute the work for +those contexts; the peer identity persists between turns. For the exact `tokio::spawn`, channels, cancellation and UI handoff, continue in OctoSense's `crates/ai-host`, `crates/app-peers` and the octos dependency at the shell's pin. The end-to-end -[shell walkthrough](https://github.com/OctoSense-org/OctoSense/blob/main/docs/architecture-walkthrough.md) +[shell walkthrough](https://github.com/OctoSense-org/OctoSense/blob/docs/junior-architecture-walkthrough/docs/architecture-walkthrough.md) connects those objects to Rust code. ## 8. The image/card design path is a separate pipeline -[`tools/image-to-appcard-flow.sh`](../tools/image-to-appcard-flow.sh) invokes +[`tools/image-to-appcard-flow.sh`](../tools/image-to-appcard-flow.sh) forwards +to [`tools/beauty-pipeline.sh`](../tools/beauty-pipeline.sh) with +`--image-to-appcard-flow`; that dispatcher selects Python and invokes [`flows/image-to-card/flow.py`](../flows/image-to-card/flow.py). `read_manifest` validates the project schema, scene ids, relative paths, 406×776 artboard, 8–12 scenes, and `en`/`cn` locales. `local` prevents paths escaping the project. `fingerprint` hashes the manifest and input artifacts so evidence can be tied to source bytes. -`STAGES` names intake, prepare, observe, measure, map, semantic, compile, +The supporting paths have distinct inputs and outputs: + +| Path | Responsibility | +| --- | --- | +| [`flows/script-app`](../flows/script-app/FLOW.md) | Text brief to a contained `main.splash` app | +| [`flows/image-to-card`](../flows/image-to-card/FLOW.md) | One atlas of 8–12 screens to native cards, service bindings and an optional WASM bundle | +| [`flows/image-lib`](../flows/image-lib/README.md) | Per-design observe/measure/map/compile/capture/gate loop and its recorded evidence | +| [`flows/kits/sketch`](../flows/kits/sketch/FLOW.md) | Licensed Sketch design assets to a reusable theme kit, consumed by app/card flows | +| [`flows/core`](../flows/core/README.md) | Shared policy, review packets, repair, composition and gates | +| [`tools/beauty-pipeline.sh`](../tools/beauty-pipeline.sh) | Dispatches the image-card flow, `--ux-image`, `--repair`, or the default Sketch `run_kit.py` path | + +`STAGES` lists intake, prepare, observe, measure, map, semantic, compile, capture, gate, extract, bundle, service-test, wasm, integrate, web-test and -hosted-test. `commands_for` builds stage commands; configured checks use -argument arrays, not shell command strings. `run` records execution -evidence. The default stage subset is not proof that all visual, service, -browser and hosted checks ran. `plan` describes work; it does not perform -the checks it prints. - -Shared policy/review/repair logic is in -[`flows/core`](../flows/core/README.md). The script-app flow does not require -an image pipeline. A browser preview validates its own route, not native -rendering or shell services. Follow the chosen flow's evidence and human -checkpoints when actually authoring or publishing; a repository code review -does not need to invent app screenshots or submit a bundle. +hosted-test. The default `--stages` is +`intake,semantic,compile,bundle,service-test`. Choose further stages for the +surfaces and checks your project delivers. A browser capture covers the +browser route; native and hosted stages cover their respective runtimes. + +`commands_for` builds stage commands; configured checks use argument arrays. +`run` resolves the entire selected plan before mutation, then creates a run +receipt with input fingerprints and the stages left unrun. Each command +gets a log, exit status and log hash. The first nonzero command marks its +stage failed and stops subsequent execution. The `finally` block records +failure or interruption and the remaining stages in `run.json`. `plan` +prints commands; `run` executes them; `status` reads the recorded result. +Follow [the flow contract](../flows/README.md#every-flow-follows-the-same-contract) +when a step fails: report the command, exit code and log, then fix the cause. + +### Finish the app hand-off + +All app flows converge on the same delivery sequence in +[flows/README.md](../flows/README.md#every-flow-follows-the-same-contract): + +1. Package the app, stamp it and run the initial unsigned gate. Before + capture, the expected missing-screenshot refusal may remain. +2. Run the bundle in `card-host`, drive the real interactions and capture + the screenshots named in the listing. **HUMAN:** review the screenshots. +3. Restamp and check the completed bundle; only the unsigned warning may + remain. Complete the `hub scan` review packet in + [PUBLISHING](PUBLISHING.md). +4. **HUMAN:** the key holder signs using a private key stored outside the + repository, then checks the signature with the publisher's public key. +5. **HUMAN:** approve submission of the exact version and open the App Hub + issue. A maintainer repeats the gate and review before publishing. + +The image and kit flows also have human checkpoints for paid generation or +licensed assets and semantic/visual approval. Preserve the source inputs +and resulting evidence through these decisions. ## 9. Pins, checks and useful failure boundaries -[`native-runtime.lock.json`](../native-runtime.lock.json) selects -Octoscript-Makepad `cb66de073469063abeb2a5ab2a2bbf3cdb365745`. -Its `runtime.json` then owns the underlying Makepad and Octoscript revisions. +[`native-runtime.lock.json`](../native-runtime.lock.json) selects an +Octoscript-Makepad release. That release's `runtime.json` owns the underlying +Makepad and Octoscript revisions. `setup-native.py` delegates to the runtime preparation/verification code; -`--check` inspects rather than updates the prepared set. It is possible for -OctoSense main to support `sys.chat` while this older authoring pin cannot. -Do not erase that difference by casually changing a shared sibling checkout. +`--check` inspects rather than updates the prepared set. The current +authoring pin lacks L0 `sys.chat` and `ChatEntry` support, while the +OctoSense shell's runtime supports that in-card chat path. Such cards require +a newer authoring runtime; see +[AI-written text and in-card chat](AI-SERVICES.md#ai-written-text-and-in-card-chat-model-copy-syschat). +Compare both consumers' pins before updating their shared sibling checkouts. -Lightweight checks for a documentation/CLI review: +Check the documentation links and CLI behavior with: ```sh python3 tools/check-links.py @@ -297,16 +348,3 @@ conversation. Runtime setup checks prove source pins, not a device build. | Gate accepts agent metadata, runtime feature absent | AI status table and actual shell executor/setup code | | Agent misses a saved note | Account workspace versus UI storage location | | New shell card syntax fails in authoring | Consumer runtime pins before changing app source | - -Preserve dated historical verification in existing docs. For new claims, -report the exact command and result, and distinguish source inspection, -mocked/unit checks, real native execution, provider-backed AI and device -testing. - -Review verification (2026-10-01): `tools/check-links.py` reported 0 broken / -0 pending; the changed-file link check also passed; both CLI help commands -passed; `test_octo_run.py` passed all 6 tests using fake processes/HTTP -bridges. `tools/octo doctor` reported missing `hub` and `card-host` binaries -in this isolated review workspace. `tools/setup-native.py --check` refused -the unprepared locked runtime. No shared runtime checkout was changed to -make those checks pass; native builds and launches remain unverified. From 0ae5aafedd01640c3994baf424bebd0165e5babf Mon Sep 17 00:00:00 2001 From: ymote <151983+ymote@users.noreply.github.com> Date: Fri, 2 Oct 2026 00:59:45 -0700 Subject: [PATCH 3/5] docs: keep companion walkthrough links stable after merge --- docs/CODE-WALKTHROUGH.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/CODE-WALKTHROUGH.md b/docs/CODE-WALKTHROUGH.md index 5f4b2677..e928c4ca 100644 --- a/docs/CODE-WALKTHROUGH.md +++ b/docs/CODE-WALKTHROUGH.md @@ -44,9 +44,9 @@ current shell does not install its instructions or skills into the peer. how runtime source versions are prepared and checked. Then follow the runtime in -[App Hub's code walkthrough](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/docs/junior-architecture-walkthrough/docs/CODE-WALKTHROUGH.md) +[App Hub's code walkthrough](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/f560e9b1e751d9ab7d4ba7f74204ee37056d27dd/docs/CODE-WALKTHROUGH.md) and the complete shell/peer path in -[OctoSense](https://github.com/OctoSense-org/OctoSense/blob/docs/junior-architecture-walkthrough/docs/architecture-walkthrough.md). +[OctoSense](https://github.com/OctoSense-org/OctoSense/blob/c3011a2057ec59738b79466f48ff2ad8d0e60130/docs/architecture-walkthrough.md). ## 3. Trace `tools/octo new`, `run`, `shot`, `check` @@ -189,7 +189,7 @@ The shell asks the person to allow it, prepares its peer, installs available tool declarations and opens conversation contexts. On desktop, `Ask ` is a host-owned human chat surface. App-owned `octos.*` screens and supported L0 `sys.chat` cards are other entry points; the -[shell walkthrough](https://github.com/OctoSense-org/OctoSense/blob/docs/junior-architecture-walkthrough/docs/architecture-walkthrough.md#6-where-a-person-talks-and-where-the-answer-goes) +[shell walkthrough](https://github.com/OctoSense-org/OctoSense/blob/c3011a2057ec59738b79466f48ff2ad8d0e60130/docs/architecture-walkthrough.md#6-where-a-person-talks-and-where-the-answer-goes) explains their routing. The system assistant discovers allowed, prepared peers and sends work using @@ -249,7 +249,7 @@ those contexts; the peer identity persists between turns. For the exact `tokio::spawn`, channels, cancellation and UI handoff, continue in OctoSense's `crates/ai-host`, `crates/app-peers` and the octos dependency at the shell's pin. The end-to-end -[shell walkthrough](https://github.com/OctoSense-org/OctoSense/blob/docs/junior-architecture-walkthrough/docs/architecture-walkthrough.md) +[shell walkthrough](https://github.com/OctoSense-org/OctoSense/blob/c3011a2057ec59738b79466f48ff2ad8d0e60130/docs/architecture-walkthrough.md) connects those objects to Rust code. ## 8. The image/card design path is a separate pipeline From 218b25d2460d64f843932f67d419467618464fb9 Mon Sep 17 00:00:00 2001 From: ymote <151983+ymote@users.noreply.github.com> Date: Fri, 2 Oct 2026 09:36:37 -0700 Subject: [PATCH 4/5] docs: clarify walkthroughs for junior Rust readers --- AGENTS.md | 3 ++ README.md | 13 +++--- README.zh-CN.md | 9 ++-- docs/CODE-WALKTHROUGH.md | 99 +++++++++++++++++++++++++++++++++------- 4 files changed, 97 insertions(+), 27 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9e291375..ea313974 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -134,6 +134,9 @@ End with a report a person can check without rerunning anything: - 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. diff --git a/README.md b/README.md index ab917522..ab19d90f 100644 --- a/README.md +++ b/README.md @@ -27,12 +27,13 @@ live in [OctoSense `apps/`](https://github.com/OctoSense-org/OctoSense/tree/main ## Code walkthrough -[docs/CODE-WALKTHROUGH.md](docs/CODE-WALKTHROUGH.md) traces the Python CLI, -script template, image/card pipeline and runtime pins into App Hub and the -OctoSense shell. It explains native Rust versus Splash/L0 apps, how to run -a bundle, app-agent data access and conversations, cross-app tool limits, -and where Tokio belongs. `tools/octo` is the development CLI; octos is the -separate agent kernel. +[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 diff --git a/README.zh-CN.md b/README.zh-CN.md index 1bc2c77d..637a74f0 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -23,10 +23,11 @@ Agent）从一个想法（一段文字需求、一张生成的 UX 图）走到 ## 代码导读 -[代码导读（英文）](docs/CODE-WALKTHROUGH.md) 沿着 Python CLI、脚本模板、图像/卡片 -流水线和运行时版本，一路讲到 App Hub 与 OctoSense Shell，解释原生 Rust、Splash 与 L0 -应用的差别、实际运行方式、应用 Agent 的数据访问和对话、跨应用工具限制，以及 Tokio -所在的层级。`tools/octo` 是开发命令；octos 是独立的 Agent 内核。 +[代码导读（英文）](docs/CODE-WALKTHROUGH.md) 沿着 Python CLI，从脚本模板走到运行中的 +应用，再进入 App Hub 与 OctoSense Shell。“总结已保存的笔记”这一请求解释 Peer、对话、 +数据访问和应答路由；从画面图集到卡片的示例解释图像流水线的默认阶段。导读还介绍原生 +Rust、Splash 与 L0 应用的差别、跨应用工具限制、运行时版本和 Tokio 所在的层级。 +`tools/octo` 是开发命令；octos 是独立的 Agent 内核。 ## 目录 diff --git a/docs/CODE-WALKTHROUGH.md b/docs/CODE-WALKTHROUGH.md index e928c4ca..1c4bc283 100644 --- a/docs/CODE-WALKTHROUGH.md +++ b/docs/CODE-WALKTHROUGH.md @@ -14,9 +14,9 @@ selected framework's `runtime.json`. | `main.splash` | A script program evaluated by Makepad Script in a Splash isolate; the template here uses it | | `page.card` / L0 | Declarative card source parsed/realized by Octoscript and lowered by Octoscript-Makepad into Makepad UI | | `tools/octo` | This repository's Python command wrapping App Hub's `hub` and `card-host` | -| octos | Rust agent kernel managed by OctoSense; unrelated to the spelling of this CLI | +| octos | Rust agent kernel managed by OctoSense; separate from `tools/octo` | | Coding agent | An optional development assistant following this repository's `AGENTS.md` | -| App agent | A runtime peer that the device's shell prepares for an allowed app | +| App agent | A model conversation with app-scoped tools; the shell gives it a peer identity for routing | Splash script and Octoscript L0 reach the same UI host by different parsing paths. A native Rust app may embed script UI while keeping its operations @@ -187,18 +187,46 @@ clients. Phone catalog configuration belongs to the Home build; see A runtime app agent is a model conversation restricted to one app/account. The shell asks the person to allow it, prepares its peer, installs available tool declarations and opens conversation contexts. On desktop, `Ask ` -is a host-owned human chat surface. App-owned `octos.*` screens and -supported L0 `sys.chat` cards are other entry points; the +is a host-owned human chat surface. App-owned `octos.*` screens are another +entry point. L0 `sys.chat` cards also provide chat when the runtime supports +them; see [§9](#9-pins-checks-and-useful-failure-boundaries) for the current +authoring-pin limitation. The [shell walkthrough](https://github.com/OctoSense-org/OctoSense/blob/c3011a2057ec59738b79466f48ff2ad8d0e60130/docs/architecture-walkthrough.md#6-where-a-person-talks-and-where-the-answer-goes) explains their routing. -The system assistant discovers allowed, prepared peers and sends work using -their **peer slug**. The system lane runs on the app peer's own session; -its result reaches the peer blackboard for the system assistant to gather. -The human lane runs on a separate sharing-context session of that peer; -its events and completion return to the human conversation's event sink. -Each lane owns its transcript. Sharing provides bounded recent history from -the other lane, and the shell panel can display both. +### Follow “Summarize my saved notes” + +Assume the app has saved notes in its account folder and the person has +allowed its agent. This example illustrates the shell route; the standalone +run in §4 cannot exercise it. + +1. **Choose the recipient.** A **peer** is an agent identity used for routing. + Its **peer slug** is the name the kernel assigns that identity. The shell + routes a person's `Ask ` request to that app's prepared peer. The + system assistant discovers allowed peers and uses the actual slug when + delegating the same request; an app id is not a substitute for that slug. +2. **Choose the conversation.** A **session** owns a conversation transcript + and its model turns. Human requests use a separate **sharing-context + session**: a conversation attached to the peer that can receive bounded + recent history from its other conversation. The system request uses the + app peer's own session. The two keep their own transcripts, while the + shell panel can display both. +3. **Read the notes.** The model requests an available file-read tool; the + shell limits it to the exposed account workspace described below. The + tool's result becomes input for the model's summary. Notes elsewhere + require a supported tool that can read them. +4. **Return the answer.** The human session sends events and completion to + its **event sink**, the receiver that forwards updates to that human + conversation. A system-delegated answer reaches the **peer blackboard**, + the kernel's record of peer results that the system assistant gathers. + Sharing a peer identity does not send both answers to the same receiver. + +An app-owned chat uses the `octos.*` route in §5 to start work and retrieve +its reply/event data. See [AI-SERVICES](AI-SERVICES.md) for that API; the +host callback and the model's completed answer are separate parts of the +exchange. + +### Data and executable tools On Unix, the shell gives an app agent bounded `files.list/read/search` tools when the person has consented and an account workspace is available. @@ -254,6 +282,35 @@ connects those objects to Rust code. ## 8. The image/card design path is a separate pipeline +The script path starts with a text brief and produces `main.splash`. +The image/card path starts with an existing atlas of 8–12 screens and +produces native L0 card assets and service bindings. Choose this path when +the project starts from those visual designs. + +### Trace the default stages through one project + +Consider an eight-screen project with a supplied atlas, its exact prompt, +a valid flow manifest and reviewed mappings for each scene. The default +stages consume those inputs and produce these artifacts: + +| Stage | Input → result | Code to follow | +| --- | --- | --- | +| `intake` | Atlas + prompt + scene crop rectangles → preserved inputs and normalized reference images in `pipeline-output/intake` | [`atlas.py`](../flows/image-to-card/atlas.py) | +| `semantic` | Each scene's reference, contract, mapping and service-action files → semantic preflight result | [`native.py`](../flows/image-to-card/native.py), `preflight` | +| `compile` | Reviewed scene mapping → `page.card`, `page.data.json` and native kit assets | [`native.py`](../flows/image-to-card/native.py), `compile_page` | +| `bundle` | Compiled scenes + declared artwork → exported card bundle in `wizard/card-bundle` | [`bundle.py`](../flows/image-to-card/bundle.py) | +| `service-test` | The manifest's explicit `checks.service-test` command arrays → logs and exit results | [`flow.py`](../flows/image-to-card/flow.py), `configured_commands` | + +Those are default output paths; the manifest can override them. Before +`semantic`, scene directories must already contain `reference.png`, +`contract.json`, `mapped.json`, `semantic-map.json` and `service-actions.json`. +The default selection does not prepare or author those files, render a +capture, or grant visual approval. Use the preparation and review steps in +[the image/card flow](../flows/image-to-card/FLOW.md) first. The exported +card assets also still need the app hand-off below. + +### Follow the dispatcher and extend the plan + [`tools/image-to-appcard-flow.sh`](../tools/image-to-appcard-flow.sh) forwards to [`tools/beauty-pipeline.sh`](../tools/beauty-pipeline.sh) with `--image-to-appcard-flow`; that dispatcher selects Python and invokes @@ -274,12 +331,20 @@ The supporting paths have distinct inputs and outputs: | [`flows/core`](../flows/core/README.md) | Shared policy, review packets, repair, composition and gates | | [`tools/beauty-pipeline.sh`](../tools/beauty-pipeline.sh) | Dispatches the image-card flow, `--ux-image`, `--repair`, or the default Sketch `run_kit.py` path | -`STAGES` lists intake, prepare, observe, measure, map, semantic, compile, -capture, gate, extract, bundle, service-test, wasm, integrate, web-test and -hosted-test. The default `--stages` is -`intake,semantic,compile,bundle,service-test`. Choose further stages for the -surfaces and checks your project delivers. A browser capture covers the -browser route; native and hosted stages cover their respective runtimes. +The default `--stages` is `intake,semantic,compile,bundle,service-test`, +traced above. `STAGES` also offers these steps for other inputs or delivery +surfaces: + +| Additional stages | Purpose | +| --- | --- | +| `prepare`, `observe`, `measure`, `map` | Prepare scene directories and develop their measured mappings | +| `capture`, `gate` | Capture the native UI and evaluate its recorded evidence | +| `extract` | Export declared service surfaces as independently mountable native trees | +| `wasm`, `integrate` | Build the browser runtime bundle and sync it into the website | +| `web-test`, `hosted-test` | Run the manifest's explicit checks for those delivery routes | + +Select the stages your project needs. A browser capture covers the browser +route; native and hosted stages cover their respective runtimes. `commands_for` builds stage commands; configured checks use argument arrays. `run` resolves the entire selected plan before mutation, then creates a run From e4e65d575d73a31253c65fdc7b8e3305870645c8 Mon Sep 17 00:00:00 2001 From: ymote <151983+ymote@users.noreply.github.com> Date: Fri, 2 Oct 2026 09:40:35 -0700 Subject: [PATCH 5/5] docs: align final review corrections and companion links --- docs/CODE-WALKTHROUGH.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/CODE-WALKTHROUGH.md b/docs/CODE-WALKTHROUGH.md index 1c4bc283..f1689c84 100644 --- a/docs/CODE-WALKTHROUGH.md +++ b/docs/CODE-WALKTHROUGH.md @@ -44,9 +44,9 @@ current shell does not install its instructions or skills into the peer. how runtime source versions are prepared and checked. Then follow the runtime in -[App Hub's code walkthrough](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/f560e9b1e751d9ab7d4ba7f74204ee37056d27dd/docs/CODE-WALKTHROUGH.md) +[App Hub's code walkthrough](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/19bb52d402e80e89e085dea989615e3ec612d359/docs/CODE-WALKTHROUGH.md) and the complete shell/peer path in -[OctoSense](https://github.com/OctoSense-org/OctoSense/blob/c3011a2057ec59738b79466f48ff2ad8d0e60130/docs/architecture-walkthrough.md). +[OctoSense](https://github.com/OctoSense-org/OctoSense/blob/61c668279a7c38a0f8056134d8d29e42ed715806/docs/architecture-walkthrough.md). ## 3. Trace `tools/octo new`, `run`, `shot`, `check` @@ -191,7 +191,7 @@ is a host-owned human chat surface. App-owned `octos.*` screens are another entry point. L0 `sys.chat` cards also provide chat when the runtime supports them; see [§9](#9-pins-checks-and-useful-failure-boundaries) for the current authoring-pin limitation. The -[shell walkthrough](https://github.com/OctoSense-org/OctoSense/blob/c3011a2057ec59738b79466f48ff2ad8d0e60130/docs/architecture-walkthrough.md#6-where-a-person-talks-and-where-the-answer-goes) +[shell walkthrough](https://github.com/OctoSense-org/OctoSense/blob/61c668279a7c38a0f8056134d8d29e42ed715806/docs/architecture-walkthrough.md#6-where-a-person-talks-and-where-the-answer-goes) explains their routing. ### Follow “Summarize my saved notes” @@ -277,7 +277,7 @@ those contexts; the peer identity persists between turns. For the exact `tokio::spawn`, channels, cancellation and UI handoff, continue in OctoSense's `crates/ai-host`, `crates/app-peers` and the octos dependency at the shell's pin. The end-to-end -[shell walkthrough](https://github.com/OctoSense-org/OctoSense/blob/c3011a2057ec59738b79466f48ff2ad8d0e60130/docs/architecture-walkthrough.md) +[shell walkthrough](https://github.com/OctoSense-org/OctoSense/blob/61c668279a7c38a0f8056134d8d29e42ed715806/docs/architecture-walkthrough.md) connects those objects to Rust code. ## 8. The image/card design path is a separate pipeline