From bf5f9e2d0900c3eccb3e05cc9912e6cd05034908 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A9ter=20Szil=C3=A1gyi?= Date: Mon, 21 Sep 2026 20:57:34 +0200 Subject: [PATCH] README, docs: link the emulator, the phone app and the agents help Co-authored-by: Claude Opus 5 (1M context) --- AGENTS.md | 6 ++++-- README.md | 21 ++++++++++++++------- docs/05-running.md | 25 ++++++++++++++----------- 3 files changed, 32 insertions(+), 20 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b5544a0..3bea3e6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,8 +2,10 @@ This repository teaches how to write apps for the Ark. Read `README.md` first, then `docs/01-app-model.md` through `docs/06-reports.md` in order. They are -short and they are the rules. When a real Ark is involved, `ark help agents` -comes before anything else. +short and they are the rules. When an Ark is involved, `ark help agents` comes +before anything else. Without hardware, Ark Emulator from +https://github.com/dark-bio/emulator boots one on this computer, and +`ark-emulator help agents` covers running it. ## Commands diff --git a/README.md b/README.md index 5190c07..f3f4be2 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Worked examples for writing apps that run on an Ark. -[dark.bio](https://dark.bio) · [Whitepaper](https://dark.bio/whitepaper) · [GitHub](https://github.com/dark-bio) · [Bluesky](https://bsky.app/profile/dark.bio) · [X](https://x.com/dark_dot_bio) +[dark.bio](https://dark.bio) · [Whitepaper](https://dark.bio/whitepaper.pdf) · [GitHub](https://github.com/dark-bio) · [Bluesky](https://bsky.app/profile/dark.bio) · [X](https://x.com/dark_dot_bio) An Ark holds a person's genome on a device only they control. Apps never receive a copy of that data. They are sent to it instead, and run in a deterministic @@ -10,7 +10,8 @@ sandbox on the Ark with no network and no writable storage. An app reads the data it was granted as plain files and prints a report. The owner approves every run on their phone and decides whether to release the result. Because the sandbox contains the code, anyone can write an app and anyone can run anyone -else's. The [whitepaper](https://dark.bio/whitepaper) lays out the trust model. +else's. The [whitepaper](https://dark.bio/whitepaper.pdf) lays out the trust +model. These examples teach that model one idea at a time, from printing a line to scanning a whole call file. Every app is a single source file. @@ -45,16 +46,21 @@ make run APP=01-hello-rust # one app make run # every app ``` -Run it on a real Ark with the [`ark`](https://github.com/dark-bio/cli) tool, -approving it on your phone: +Run it on an Ark with the [`ark`](https://github.com/dark-bio/cli) tool. The +owner approves the run on their phone, in Ark Companion for +[iOS](https://apps.apple.com/app/id6751324700) or +[Android](https://play.google.com/store/apps/details?id=bio.dark.companion). +Without hardware, [Ark Emulator](https://github.com/dark-bio/emulator) boots +the real Ark firmware on your computer, and `ark` runs apps on it the same way. ```sh ark data paths # what apps can read on this Ark ark app run build/01-hello-rust.wasm > report.md ``` -[docs/05-running.md](docs/05-running.md) covers the toolchains, the fixtures, and -what a laptop can't reproduce. +Scripts and AI agents driving an Ark read `ark help agents` first. +[docs/05-running.md](docs/05-running.md) covers the toolchains, the fixtures, +what a laptop can't reproduce, and running on an Ark or an emulator. ## The examples @@ -87,7 +93,8 @@ and a full app turns the same read into a report. every path follows. - [04-reading-data.md](docs/04-reading-data.md) covers absence, errors, sequences and genotypes, with a grant for every need. -- [05-running.md](docs/05-running.md) covers running apps locally and on an Ark. +- [05-running.md](docs/05-running.md) covers running apps locally, on an + emulator and on an Ark. - [06-reports.md](docs/06-reports.md) covers the report, its shape and its voice. diff --git a/docs/05-running.md b/docs/05-running.md index 6b5c314..611c10e 100644 --- a/docs/05-running.md +++ b/docs/05-running.md @@ -2,7 +2,7 @@ You don't need an Ark to write an app. A WebAssembly runtime and the fixture data in this repository run both passes on a laptop. When the app works, the -`ark` command line tool runs it on a real Ark. +`ark` command line tool runs it on an Ark, whether hardware or emulated. ## Locally @@ -107,19 +107,21 @@ missing grants there. - **Startup cost.** A laptop starts a module far faster than an Ark does, so a heavy module feels cheaper here than it is there. -## On an Ark +An emulated Ark has all of these except the startup cost, since it runs the real +firmware at your computer's speed. -Install the `ark` tool: +## On an Ark -```sh -brew install dark-bio/tap/ark-cli # macOS -curl -fsSL https://github.com/dark-bio/cli/releases/latest/download/ark-installer.sh | sh # Linux -cargo install darkbio-ark --locked # anywhere with Rust -``` +Install the [`ark`](https://github.com/dark-bio/cli) command line tool as its +README describes. It talks to an Ark plugged in over USB, or to one that +[Ark Emulator](https://github.com/dark-bio/emulator) boots on your computer from +the real firmware. The emulator keeps its data in a plain file, and +`ark-emulator start` boots one. An Ark is paired with `ark pair` once, and unlocked with `ark unlock` after each -power loss, both approved on the owner's phone. Then check what the Ark holds and -run the app: +power loss, both approved on the owner's phone in Ark Companion. A fresh +emulator is first enrolled at Ark Hub, in a browser, at the address `ark enroll` +prints. Then check what the Ark holds and run the app: ```sh ark status # trust, firmware, pairing and lock state @@ -130,4 +132,5 @@ ark app run build/03-cilantro-mini-rust.wasm > report.md `ark app run` uploads the module and waits while the owner approves it on their phone. It then writes the report to standard output. A refused app comes back with the reason. `ark help apps` covers manifests and grants, and -`ark help datasets` covers the data commands. +`ark help datasets` covers the data commands. Scripts and AI agents read +`ark help agents` first, and `ark-emulator help agents` for the emulator.