Model card: how to draw with a sample page (a run-file line, the caption form, the draw settings, one command)

README.md

@@ -52,10 +52,32 @@ uv run diffu-run --jobs run.jsonl --draw-settings draw.json --model ../moss-diff
 ```
 
 `diffu-moss-init` reads `export.json` and writes the sample's size into the model directory, so the sample page is
-sized as in training (`legible`: a whole page's sample at the drawn page's pixel count). `run.jsonl` holds one page job
-per line, as JSON: the layout (`template`, a PAGE/ALTO file, or `layout`, the lines' boxes in pixels), the text (left
-out, the layout's own), the style, the sample page and an id. diffu's `README.md` shows two lines; `docs/INFERENCE.md`
-section 5 describes every field.
+sized as in training (`legible`: a whole page's sample at the drawn page's pixel count).
+
+### With a sample page
+
+The sample page is an ordinary scan (JPEG or PNG) of a page whose **paper, ink and look** the drawn page should have:
+best a page of the same volume as the layout, or any page whose look you want. It does not set the handwriting (see
+Limitations). Each page job in `run.jsonl` is one line of JSON: the layout (`template`, a PAGE/ALTO file, or `layout`,
+the lines' boxes in pixels), the text (left out: the layout's own), the style, the sample page under `reference`, and
+an id:
+
+```json
+{"id": "court-0001", "template": "templates/0105.xml", "text": "Anno 1649 den 6 Aprilis Tå laga tingh höltz medh Allmogen ...", "style": {"provenance": {"title": "the court records of Jämtlands domsaga", "years": "1649"}, "look": {"greyscale": false, "paper": "cream", "ink": "black"}}, "reference": {"image": "samples/court-sample.jpg", "caption": "sample"}}
+```
+
+`"caption": "sample"` is the prompt form this model was trained on most (the sample page alone, nothing named; the
+style's title and look are then left out of the prompt). `"sample_look"` adds the look in words beside the sample.
+`draw.json` holds the draw settings, for example `{"steps": 50, "device": "cuda", "reference_guidance_scale": 2}`.
+Each page comes out as `<id>.jpg` with its `<id>.alto.xml` and `<id>.page.xml`. `docs/INFERENCE.md` section 5
+describes every field, with a worked example of each combination.
+
+One page from the command line, without a run file:
+
+```bash
+uv run diffu-generate --model ../moss-diffu --templates templates/0105.xml --text-from text.txt \
+    --reference samples/court-sample.jpg --reference-caption sample --reference-guidance 2 --whole-page --out pages
+```
 
 Recommended drawing: about 1 MP, 50 steps, guidance 3, shift 5, block 22 skipped in the unconditional pass (MOSS-Image's
 own recipe), and **reference guidance 2** (a third pass toward the sample: `--reference-guidance 2` in