README, docs: link the emulator, the phone app and the agents help

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
 

README.md

@@ -2,15 +2,16 @@
 
 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
 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.
 

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.