How-to guides with pictures; legend and title fixes

.gitattributes

@@ -50,3 +50,4 @@ assets/PHerc0841-xz.webp filter=lfs diff=lfs merge=lfs -text
 assets/PHerc0846A-xz.webp filter=lfs diff=lfs merge=lfs -text
 assets/PHerc0846B-xz.webp filter=lfs diff=lfs merge=lfs -text
 media/example-result.png filter=lfs diff=lfs merge=lfs -text
+media/howto-slices.gif filter=lfs diff=lfs merge=lfs -text

app.py

@@ -324,7 +324,7 @@ def make_field(volume: str, z: float, y: float, x: float, size: float = 256, mod
     with one_run(request):
         r = run_field(p, progress)
     c = p["centre_level0_zyx"]
-    pic = L.compose(r["pictures"], f"{p['sample']} · {p['size_zyx'][0]}³ box at z {c[0]}, y {c[1]}, x {c[2]}")
+    pic = L.compose(r["pictures"], f"{p['sample']} · {p['size_zyx'][0]}-voxel box at z {c[0]}, y {c[1]}, x {c[2]}")
     return pic, r["receipt"], r["zip"]
 
 
@@ -346,29 +346,74 @@ field. Each will be marked here with what it was tested on.
 """
 
 HOW_TO = """\
-### 1. Make your first field (one minute)
+<p class="lf-toc">Guides: <a href="#what">What a lasagna field is</a> · <a href="#first">Make your first field</a> ·
+<a href="#read">Read the result</a> · <a href="#point">Pick your own point</a> · <a href="#download">Use the
+download</a> · <a href="#agents">Call it from code or an agent</a> · <a href="#yourself">Run it yourself</a> ·
+<a href="#wrong">When something goes wrong</a></p>
 
-1. Open **Make a field**. It starts on an example point in PHerc0139; other examples are in the list under the point.
-2. Press **Make the field**. The Space reads about 450 MB of CT from the open data, then runs villa's model
-   on the GPU for about half a minute.
-3. Look at the three rows: the middle slice of your box along z, y and x. Each row shows the CT, then **cos**
-   (bright and dark bands, one pair per papyrus layer), **grad_mag** (how sharply cos changes) and the
-   **normal** as colour (red for x, green for y, blue for z: which way the sheet faces).
-4. Read the check under the picture. The same box should agree with the open data's own field far better than
-   the control, which is the published field read a few layers away.
+<h3 id="what">What a lasagna field is</h3>
 
-### 2. Pick your own point
+A scroll's CT shows papyrus layers rolled and squashed together. villa's lasagna model turns the CT into a smooth
+field that surface tools can follow: **cos** goes once from bright to dark and back per papyrus layer, so counting
+bands counts layers; **grad_mag** says how sharply cos changes (how tightly the layers are packed); the **normal**
+says which way the sheet faces at each point. villa's lasagna surface fit and the spiral fit read these channels.
 
-1. Open the scan in the [Vesuvius Challenge data browser](https://scrollprize.org/data_browser/) or in VC3D and note
-   a point inside the papyrus, in full-resolution (level 0) voxels: z, then y, then x.
-2. Choose the same scan here (the 14-digit volume id is in the scan's folder name) and type the point.
-3. Choose 256 (about 2.4 mm a side at 9.4 um voxels) or 512 (four times the time, eight times the volume).
-4. The line under the size says how much CT it reads, how many model tiles it runs and how much GPU time it asks.
+![The CT of one box of PHerc0139 next to villa's lasagna field, stepping through the box](/gradio_api/file=media/howto-slices.gif)
+
+*PHerc0139 (not on any prize list), one box about 2.5 mm a side: the CT, cos and the normal as colour, stepping
+through z. Model output: geometry, not a reading of any text.*
+
+<h3 id="first">1. Make your first field (one minute)</h3>
+
+1. Open **Make a field**. It starts on an example point in PHerc0139; more examples are in the first list.
+2. Press **Make the field**. The Space reads about 450 MB of CT from the open data, then runs villa's model on the
+   GPU for about 20 seconds. The first run after the Space wakes up also loads the model (about a minute).
+3. The picture, the check and the download appear on the right.
+
+![Making a field on this page: press the button, wait about half a minute, read the check](/gradio_api/file=media/howto-make.gif)
+
+<h3 id="read">2. Read the result</h3>
+
+![A result: three rows of slices, each row CT, cos, grad_mag and normal](/gradio_api/file=media/example-result.png)
+
+- **Rows** are the middle slice of your box along z, y and x. **Columns** are the CT, cos, grad_mag and the
+  normal as colour (red for x, green for y, blue for z).
+- **cos** should run along the papyrus in the CT, one bright and one dark band per layer. Where layers touch or
+  the CT is unclear, the bands bend or merge: that is where surface tracing is hard too.
+- **The check** compares your field with the published one for the same box, and with a **control**: the same
+  published field read 48 voxels away. A correct run gives cos r = 1.0 and grad_mag r = 1.0 for the same box and
+  near 0 for the control.
+- **Normals** are compared where the layer signal is strong; where it is weak the normal is barely defined. On the
+  open data's fields they can differ in parts of a box, because villa changed how lasagna estimates normals after
+  those fields were made (April 2026, by their run names). This Space runs the later code, the same as its ten
+  whole-scan fields; on PHerc0175A it matched that field on 99.9% of voxels, with a median normal angle of 0°.
+
+![The check under a result](/gradio_api/file=media/howto-check.png)
+
+<h3 id="point">3. Pick your own point</h3>
+
+1. Find a point inside the papyrus in the [Vesuvius Challenge data browser](https://scrollprize.org/data_browser/),
+   VC3D or neuroglancer, in full-resolution (level 0) voxels: z, then y, then x.
+2. Choose the same scan in **Scan**: type part of the scroll name or the 14-digit volume id to filter the list.
+3. Type the point. The line under the button says the box it will make, how much CT it reads, how many model
+   tiles it runs and how much GPU time it asks.
+4. Choose **256** (about 2.5 mm a side at 9.4 um) or **512** (eight times the volume, about a minute of GPU).
+
+![Choosing a scan, a point and a box size](/gradio_api/file=media/howto-point.png)
 
 Boxes are whole 256-voxel blocks of the scan, because villa writes the field in 64-voxel chunks of its quarter
-grid; that is also why a box's field matches the one villa makes for the whole scan.
+grid and puts its tiles on one lattice over the whole scan: that is why a box's field is the whole-scan field
+there. The box is the block nearest your point, so your point is inside it but not always at its centre.
 
-### 3. Use the download
+<h3 id="download">4. Use the download</h3>
+
+The zip holds three things:
+
+| Item | What it is | Open it with |
+| --- | --- | --- |
+| `villa/` | villa's own output folder: `*.lasagna.json` and four OME-Zarr channels, in the scan's coordinates with only your box written | lasagna's fit, as you would a published run |
+| `field.npz` | the box's four arrays (cos at half, the others at a quarter of the input level's grid) | numpy |
+| `receipt.json` | the plan, villa commit, checkpoint hash, timings and the check | any JSON reader |
 
 ```bash
 unzip PHerc0139-*.zip -d box && cd box
@@ -376,17 +421,17 @@ python - <<'EOF'
 import numpy as np, json
 f = np.load("field.npz"); r = json.load(open("receipt.json"))
 print({k: f[k].shape for k in f}, r["boxes"])
+nx, ny = (f["nx"] - 128) / 127, (f["ny"] - 128) / 127        # normals are stored as v x 127 + 128
 EOF
 ```
 
-`villa/` is villa's own output folder: point lasagna's fit at `villa/*.lasagna.json` as you would a published run.
-Its arrays have the whole scan's shape in level-0 coordinates, with only your box written.
-
-### 4. Call it from Python or an agent
+<h3 id="agents">5. Call it from code or an agent</h3>
 
-See **Agents and API**: the same four calls as the page, from `gradio_client`, plain HTTP, or any MCP client.
+The page is also an API and an MCP server. See **Agents and API** for the calls, a Python example and the MCP
+address. An agent can list the scans, plan a box without running it, then make it, and read the check from the
+receipt. Each field uses the caller's own ZeroGPU time.
 
-### 5. Run it yourself, for big regions or whole scans
+<h3 id="yourself">6. Run it yourself, for big regions or whole scans</h3>
 
 The Space is for boxes. For a whole scan, run villa's lasagna on a GPU of your own or a cloud job:
 
@@ -400,11 +445,11 @@ python scripts/bootstrap_venv.py --venv .venv
 Measured on an NVIDIA L4 (25 Oct 2026): about 2 million voxels a second end to end, so about ten minutes per
 cubic centimetre at 9.4 um. It fits in 5.6 GB of GPU memory at its default tile, 2.3 GB at `--tile-size 128`.
 
-### When something goes wrong
+<h3 id="wrong">When something goes wrong</h3>
 
 | What you see | What to do |
 | --- | --- |
-| "ZeroGPU refused this run" | Your daily ZeroGPU time is used up. Sign in to Hugging Face for more, or come back tomorrow. |
+| "ZeroGPU refused this run" | Your ZeroGPU time or runs are used up; visitors who are not signed in get very little. Sign in to Hugging Face for more, or come back tomorrow. |
 | "the field is empty" | The box is outside the scroll, where the masked CT is all zero. Move the point toward the papyrus. |
 | "the point is outside the scan" | The point is past the scan's level-0 shape; check you used level-0 voxels, not a coarser level. |
 | "not a volume in the open data" | Use the 14-digit volume id (list it with `list_scans`). |
@@ -454,6 +499,11 @@ CSS = """
 .lf-credit { text-align:center; font-size:13px; color: var(--body-text-color-subdued); padding:18px 0 6px; }
 .lf-credit a { color: var(--lf-accent) !important; padding:0 !important; margin:0 !important; }
 .lf-howto img { border-radius:10px; border:1px solid var(--border-color-primary); max-width:100%; }
+.lf-howto { max-width: 920px; }
+.lf-howto h3 { scroll-margin-top: 16px; margin-top: 1.6em !important; }
+.lf-howto em { color: var(--body-text-color-subdued); font-size: 13.5px; }
+.lf-toc { font-size: 14px; line-height: 1.9; padding: 10px 14px; border-radius: 10px;
+  background: var(--block-background-fill); border: 1px solid var(--border-color-primary); }
 @media (max-width: 640px) {
   .lf-head h1 { font-size:24px; }
   .lf-head span { display:none; }