From 72ac39dc3a99d11640739d8b1ab3b1780374f22d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A9ter=20Szil=C3=A1gyi?= Date: Tue, 13 Oct 2026 16:46:17 +0300 Subject: [PATCH 1/2] docs, README: run apps with ark run, and attach duration units Co-authored-by: Claude Opus 5.5 --- README.md | 2 +- docs/01-app-model.md | 4 ++-- docs/05-running.md | 4 ++-- docs/06-reports.md | 7 ++++--- 4 files changed, 9 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index e542523..682f17c 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ 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 +ark run build/01-hello-rust.wasm > report.md ``` AI agents driving an Ark read `ark help agents` first. diff --git a/docs/01-app-model.md b/docs/01-app-model.md index ce6b753..a34beab 100644 --- a/docs/01-app-model.md +++ b/docs/01-app-model.md @@ -77,7 +77,7 @@ An app that needs a random-looking choice derives it from its input. | Table | 65,536 elements | 65,536 elements | | Standard output | 64 KiB | 1 MiB | | Standard error | 1 KiB, never returned | 1 MiB | -| Time | 250 ms | none, but cancellable | +| Time | 250ms | none, but cancellable | | Data | none | granted paths, read-only | A manifest pass that prints more than 64 KiB is refused, and a report pass that @@ -98,7 +98,7 @@ of apps you ship. ## Running on an Ark 1. A developer sends the module to the Ark, for example with - `ark app run app.wasm`. + `ark run app.wasm`. 2. The Ark checks the module, runs the manifest pass, then checks the manifest and every path it grants. 3. The owner sees the app's name, version and requested paths on their phone. diff --git a/docs/05-running.md b/docs/05-running.md index 6523e84..03e44bb 100644 --- a/docs/05-running.md +++ b/docs/05-running.md @@ -151,10 +151,10 @@ prints. Then check what the Ark holds and run the app: ```sh ark status # trust, firmware, pairing and lock state ark data paths # the paths apps can read, and what is available -ark app run build/04-cilantro-mini-rust.wasm > report.md +ark run build/04-cilantro-mini-rust.wasm > report.md ``` -`ark app run` uploads the module and waits while the owner approves it on their +`ark run` uploads the module and waits while the owner approves it on their phone, with any optional grants and answers. When the app ends, the owner reviews its report, and the command writes it to standard output once the owner releases it. A refused app comes back with the reason, and a report the owner diff --git a/docs/06-reports.md b/docs/06-reports.md index 647a5fd..356c1b3 100644 --- a/docs/06-reports.md +++ b/docs/06-reports.md @@ -3,10 +3,11 @@ A report is what an app prints in its report pass, and it is the only thing an app can send out of the sandbox. The owner reads it first, on their phone, and decides whether it goes any further. Once the owner releases it, the session -that started the task gets its exact bytes, in a terminal from `ark app run` or +that started the task gets its exact bytes, in a terminal from `ark run` or rendered as Markdown in Ark Hub. So a report is read three ways, on a phone, as -raw text and as a rendered page, and it has to work in all of them. This page is a guideline for that. The Ark itself checks -only that a report is text, as [Form](#form) says. +raw text and as a rendered page, and it has to work in all of them. This page +is a guideline for that. The Ark itself checks only that a report is text, as +[Form](#form) says. ## What a report has to do From 227be9bf28cb6c3ff7bce70a7088f17b9e091c4f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A9ter=20Szil=C3=A1gyi?= Date: Tue, 13 Oct 2026 16:56:14 +0300 Subject: [PATCH 2/2] docs: drop the claim that a public grant shows on the approval screen Co-authored-by: Claude Opus 5.5 --- docs/06-reports.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/06-reports.md b/docs/06-reports.md index 356c1b3..c980c70 100644 --- a/docs/06-reports.md +++ b/docs/06-reports.md @@ -135,10 +135,9 @@ absent. A long list is cut, with a count of what was left out. Coordinates name their assembly when the app can read it. It sits in `v1/genome/reference/build`, and reading it means granting -`v1/genome/reference`, which puts the stored reference genome on the approval -screen. The demos take that trade. An app that doesn't leaves the coordinate -unlabelled rather than labelling it wrongly, since an Ark may hold a GRCh37 -genome. +`v1/genome/reference`, as the demos do. An app without that grant leaves the +coordinate unlabeled rather than labeling it wrongly, since an Ark may hold a +GRCh37 genome. **Method** explains how the finding follows from the evidence, in plain words, and names each study inline, as author and year, with the population it was