docs, apps: add a reports guideline and shape the full apps to it

AGENTS.md

@@ -0,0 +1,71 @@
+# Writing Ark apps in this repository
+
+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.
+
+## Commands
+
+```sh
+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
+```
+
+`make run` mounts only the paths an app's manifest declares, read-only, and
+runs it with `/` as the data directory, the way an Ark does. The three fixture
+roots are described in `fixtures/README.md`. An app whose grants a root lacks
+stops before its run pass there, which is expected.
+
+## Adding an app
+
+- Copy the nearest example. One source file, in `apps/<nn>-<name>-<lang>/` for
+  a mini and `apps/<nn>-<name>/` for a full app, with a short `README.md` that
+  says what it shows and how to run it.
+- The manifest names the app, its version and the narrowest grants that answer
+  the question. Spell every path exactly as `ark data paths` shows it, with
+  `v1/` kept and no trailing `/`. `docs/02-manifest.md` has the rules.
+- Read grants as plain files. Absent means "not found" and is a result. Any
+  other error goes to standard error with a non-zero exit. The shapes a
+  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
+  `fixtures/README.md`, with no trailing newline in any value file.
+
+## The report
+
+Follow `docs/06-reports.md`. In short:
+
+- One `#` title in Title Case naming the subject, then the finding straight
+  under it with no heading, within the first ten lines. No app name, version
+  or grant list; the Ark reports those beside the report.
+- Then sections in this order, `Evidence`, `Method`, `Limitations`,
+  `Sources`, each when it has content, headings in sentence case.
+- The finding is a sentence and a value. A verdict label may lead it when
+  the value follows at once. Say "carries" and "is associated with", never
+  "you have" or "you will". An absent answer is stated as a finding, never
+  read as reference.
+- Every value beside its coordinate. Genotypes exactly as the file holds
+  them, in prose or code when they contain a pipe. Coordinates labelled with
+  the assembly only when the app granted `v1/genome/reference` and read
+  `build`.
+- Studies named inline as author and year, listed in Sources with a stable
+  URL. Links nowhere else.
+- Pick one voice and keep it. Light or serious, never both in one report.
+  Genomics words, never clinic words.
+- Plain Markdown only. No images, HTML, footnotes, encoded content, dates or
+  run ids. Tables with as few columns as carry the evidence, rows about 80
+  characters.
+
+## Never
+
+- Never read absence as homozygous reference.
+- Never assume the ALT allele is the risk allele. Derive it from the study.
+- Never grant more than the question needs.
+- Never depend on randomness, time, the network or writable storage.
+- Never put anything in a report the owner can't read.

README.md

@@ -23,7 +23,7 @@ An app is a [WebAssembly](https://webassembly.org/) module built for
 - **With no arguments**, the app prints a short TOML manifest naming itself and
   the data it wants. The Ark checks it and shows it to the owner for approval.
 - **With a data directory as its first argument**, the app reads its granted
-  files and prints its report.
+  files and prints its report, a Markdown page the owner reads first.
 
 ```rust
 fn main() {
@@ -88,6 +88,8 @@ and a full app turns the same read into a report.
 - [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.
+- [06-reports.md](docs/06-reports.md) covers the report, its shape and its
+  voice.
 
 ## A note on scope
 

apps/03-cilantro-soapiness/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "cilantro-soapiness"
-version = "0.3.0"
+version = "0.4.0"
 edition = "2024"
 
 # A smaller module uploads and starts faster on an Ark.

apps/03-cilantro-soapiness/README.md

@@ -1,10 +1,12 @@
 # 03 - cilantro-soapiness
 
 The single variant from [03-cilantro-mini-rust](../03-cilantro-mini-rust),
-turned into a full report with a verdict, the copies behind it, caveats and
-further reading. A no-call and an absent genotype each get their own
-explanation instead of a verdict, and a call without exactly two copies shows
-its copies without a homozygous or heterozygous label.
+turned into a full report in the shape [06-reports.md](../../docs/06-reports.md)
+describes, with a finding, the evidence behind it, the method, its limitations
+and sources. A no-call and an absent genotype each get their
+own finding instead of a verdict, and a call without exactly two copies shows
+its copies without a homozygous or heterozygous label. The `reference` grant is
+read for one file, the assembly build the coordinate is reported on.
 
 ## Build and run