AGENTS, docs, README, tools: mount grants read-only and explain new-app builds

AGENTS.md

@@ -14,7 +14,7 @@ make build APP=<app>          # one module into build/<app>.wasm
 make run APP=<app>            # build, then both passes against fixtures/
 make run APP=<app> FIXTURES=fixtures/no-call
 make run APP=<app> FIXTURES=fixtures/unanswered
-tools/check.sh                # what CI runs: links, builds, runs, ports
+sh tools/check.sh             # what CI runs: links, builds, runs, ports
 ```
 
 `make run` mounts only the paths an app's manifest declares, read-only, and
@@ -35,8 +35,9 @@ stops before its run pass there, which is expected.
   genotype can take are in `docs/04-reading-data.md`.
 - Nothing in the sandbox is random or timed. Sort anything you list.
 - Keep the module small. Rust apps carry the release profile from any sibling's
-  `Cargo.toml`.
-- Run `tools/check.sh` before proposing a change. New fixtures follow
+  `Cargo.toml`, and commit their own `Cargo.lock`, since the build runs with
+  `--locked`. One plain `cargo build` in the app's folder writes it.
+- Run `sh tools/check.sh` before proposing a change. New fixtures follow
   `fixtures/README.md`, with no trailing newline in any value file.
 
 ## The report

README.md

@@ -58,14 +58,16 @@ ark data paths                                 # what apps can read on this Ark
 ark app run build/01-hello-rust.wasm > report.md
 ```
 
-Scripts and AI agents driving an Ark read `ark help agents` first.
+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
 
 Most data comes in two versions. A *mini* shows the bare read in a few lines,
-and a full app turns the same read into a report.
+and a full app turns the same read into a report. Each row is a folder under
+`apps/`, with the language appended for the minis, such as
+`03-cilantro-mini-rust`, and that folder name is what `APP=` takes.
 
 | App | What it shows | Languages |
 | :-- | :-- | :-- |

docs/05-running.md

@@ -63,6 +63,11 @@ from the fixture root, read-only, and runs the module again with `/` as its
 first argument. An undeclared path is never mounted, which is how
 [02-permissions](../apps/02-permissions) can show a blocked read on a laptop.
 
+An app kept outside this repository runs against these fixtures the same way,
+since `tools/run.sh` takes any module, as in
+`sh tools/run.sh path/to/app.wasm fixtures`. Build it with the `wasm-opt`
+feature flags in `tools/build.sh`, because an Ark's runtime accepts only those.
+
 ### Small modules
 
 An Ark uploads and starts a smaller module faster, so every build here is tuned
@@ -132,5 +137,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. Scripts and AI agents read
-`ark help agents` first, and `ark-emulator help agents` for the emulator.
+`ark help datasets` covers the data commands. AI agents read `ark help agents`
+first, and `ark-emulator help agents` for the emulator.

tools/run.sh

@@ -17,14 +17,21 @@ printf '%s\n' "$manifest"
 
 # Mount only the datasets the manifest declares, each at its own path, so the app
 # sees exactly what it asked for and nothing else, like the device does.
+# wasmtime lets a guest write to every directory it mounts, so the datasets are
+# copied into a scratch tree without write permission and mounted from there.
+stage="$(mktemp -d)"
+trap 'chmod -R u+w "$stage"; rm -rf "$stage"' EXIT
 set --
 for dataset in $(printf '%s\n' "$manifest" | grep -oE '"v1/[^"]*"' | tr -d '"'); do
   if [ ! -d "$fixtures/$dataset" ]; then
     printf 'fixture root has no declared dataset: %s\n' "$dataset" >&2
     exit 1
   fi
-  set -- "$@" --dir "$fixtures/$dataset::/$dataset"
+  mkdir -p "$stage/$(dirname "$dataset")"
+  cp -R "$fixtures/$dataset" "$stage/$dataset"
+  set -- "$@" --dir "$stage/$dataset::/$dataset"
 done
+chmod -R a-w "$stage"
 
 echo
 echo "== run pass =="