8 files changed, 98 insertions, 13 deletions
diff --git a/docs/site/casts/casts.toml b/docs/site/casts/casts.toml
index 5771e6be..9f0dd1a5 100644
--- a/docs/site/casts/casts.toml
+++ b/docs/site/casts/casts.toml
@@ -7,7 +7,7 @@
 [[cast]]
 name = "live-text"
 title = "Live text"
-caption = "Helix keys edit; middle-click runs make; right-click the error opens its line."
+caption = "Rename a variable with helix keys, middle-click make, right-click the error."
 cols = 100
 rows = 30
 ready = true
diff --git a/docs/site/media/clips.toml b/docs/site/media/clips.toml
index adb97762..ca3002d0 100644
--- a/docs/site/media/clips.toml
+++ b/docs/site/media/clips.toml
@@ -1,7 +1,7 @@
 # The landing page's recordings, in the order shown. For each clip the
 # site ships media/<name>.webm and media/<name>.mp4, with media/<name>.png
-# as the poster; the first ready clip's poster is also the landing's
-# hero image. While `ready` is false the clip shows placeholder.svg and
+# as the poster. `landing = false` keeps a clip off the landing (the
+# terminal casts show the same) while its files stay for the chapters. While `ready` is false the clip shows placeholder.svg and
 # no video, so the site builds before a recording exists.
 
 [[clip]]
@@ -28,10 +28,11 @@ ready = true
 name = "terminals-are-panes"
 caption = "A terminal is a pane: Ctrl-b, then move over its output."
 ready = true
+landing = false
 
 [[clip]]
 name = "scripting-over-9p"
-caption = "A script drives the session through its virtual filesystem (9P)."
+caption = "A shell under 9ns, where the session is a directory: ls, cat, echo."
 ready = true
 
 [[clip]]
diff --git a/docs/site/site.css b/docs/site/site.css
index 7d6d0660..6e4a2e93 100644
--- a/docs/site/site.css
+++ b/docs/site/site.css
@@ -150,8 +150,8 @@ body { margin:0; min-height:100vh; background:var(--field) radial-gradient(color
 @media (max-width:600px) { .cmd pre { white-space:pre-wrap; overflow-wrap:anywhere; } }
 
 /* terminal recordings: the first across the page, the rest two by two */
-.casts { display:grid; grid-template-columns:repeat(auto-fit, minmax(min(100%, 340px), 1fr)); gap:18px; margin:1em 0 1.4em; }
-.casts .first { grid-column:1 / -1; }
+/* one per row at the page's full width: a terminal at half width is unreadable */
+.casts { display:grid; grid-template-columns:minmax(0, 1fr); gap:22px; margin:1em 0 1.4em; }
 .cast .player { background:#121314; }
 .cast figcaption strong { color:var(--leaf); }
 .content h2.shelf { font-size:26px; margin:1.2em 0 .4em; }
@@ -191,3 +191,19 @@ main[data-page="builtins"] .content h4 + p { margin-top:0; }
   /* under the name: its prefix is --cols cells of the 13px mono font */
   .fstree .desc { display:block; padding-left:calc(var(--cols) * 7.8px); font-size:15px; margin-bottom:.15em; }
 }
+
+/* what's in it: a row of linked chips under the lead */
+.inside { display:flex; flex-wrap:wrap; gap:8px 10px; margin:.2em 0 1.1em; padding:0; list-style:none; }
+.inside a { display:inline-block; padding:2px 10px; font:17px var(--pixel); color:var(--leaf); background:var(--tag); border:2px solid var(--leaf); text-decoration:none; }
+.inside a:hover { color:var(--amber); border-color:var(--amber); }
+
+/* a screenshot with numbered pins, their labels listed beside it */
+.annotated { margin:1.2em 0 1.6em; display:grid; grid-template-columns:minmax(0, 3fr) minmax(12em, 2fr); gap:14px 22px; align-items:center; }
+.annotated .frame { position:relative; border:2px solid var(--leaf); box-shadow:5px 5px 0 var(--shadow); }
+.annotated img { display:block; width:100%; height:auto; }
+.annotated .pin { position:absolute; transform:translate(-50%, -50%); width:1.5em; height:1.5em; border-radius:50%;
+  display:flex; align-items:center; justify-content:center; font:700 14px var(--mono); background:var(--amber); color:#1b120a; box-shadow:0 0 0 2px var(--panel); }
+.annotated .pins { margin:0; padding-left:1.8em; font-size:18px; }
+.annotated .pins li { margin:.25em 0; }
+.annotated .pins li::marker { font:700 15px var(--mono); color:var(--amber); }
+@media (max-width:600px) { .annotated { grid-template-columns:minmax(0, 1fr); } }
diff --git a/docs/site/site.typ b/docs/site/site.typ
index e0cd9d4d..787844f5 100644
--- a/docs/site/site.typ
+++ b/docs/site/site.typ
@@ -26,6 +26,16 @@
     Bell Labs: #link("https://9p.io/sys/doc/acme/acme.html")[acme]'s text as
     the interface, and the 9P protocol.],
   status: [Linux; macOS in progress. Version #version.],
+  // what's in it: a word each, linked to where it is told; no prose
+  inside: (
+    ("Terminals", "guide.html#terminals"),
+    ("PDFs", "builtins.html#builtin-PdfSections"),
+    ("Images", "reference.html#panes"),
+    ("Language servers", "setup.html#language-servers"),
+    ("Diff review", "guide.html#reviewing-diffs"),
+    ("Scripting", "scripting.html"),
+    ("Themes", "themes.html"),
+  ),
   terminal: [In a terminal],
   window: [In its own window],
   start: (
@@ -152,7 +162,7 @@
   // "</" may not appear inside a script element
   let data = json.encode(list, pretty: false).replace("</", "<\\/")
   el("script", (src: "player/asciinema-player.min.js"))[]
-  el("script")[#("for (const c of " + data + ") { const el = document.getElementById(c.id); el.player = AsciinemaPlayer.create({data: c.data}, el, {cols: c.cols, rows: c.rows, autoPlay: true, loop: true, fit: 'width'}); }")]
+  el("script")[#("for (const c of " + data + ") { const el = document.getElementById(c.id); el.player = AsciinemaPlayer.create({data: c.data}, el, {cols: c.cols, rows: c.rows, autoPlay: true, loop: true, fit: 'width', poster: 'npt:0:2'}); }")]
 }
 
 /// Plays a recording while it is on screen and pauses it once it leaves.
@@ -173,6 +183,9 @@
 #document(href("index"), title: "pardes", shell("index", "pardes")[
   #el("h1", (class: "masthead"))[pardes]
   #el("p", (class: "lead"))[#landing.lead]
+  #el("ul", (class: "inside", "aria-label": "What's in it"))[
+    #for (name, to) in landing.inside { el("li")[#el("a", (href: to))[#name]] }
+  ]
   #el("p", (class: "credit"))[#landing.credit]
   #el("p", (class: "runs"))[#landing.status]
   #el("div", (class: "start"))[
@@ -189,7 +202,7 @@
   #el("div", (class: "casts"))[#for (i, c) in casts.enumerate() { cast(c, i) }]
   #el("h2", (class: "shelf"))[#landing.window]
   #el("div", (class: "clips"))[
-    #for c in clips {
+    #for c in clips.filter(c => c.at("landing", default: true)) {
       el("figure", (class: "clip"))[
         #if c.ready { video(c) } else { placeholder }
         #el("figcaption")[#c.caption]
diff --git a/docs/typ/cheatsheet-a4.pdf b/docs/typ/cheatsheet-a4.pdf
index 9ef291b9..d33db316 100644
--- a/docs/typ/cheatsheet-a4.pdf
+++ b/docs/typ/cheatsheet-a4.pdf
@@ -1575,12 +1575,12 @@ x�}��Kq�?�U�X
94%MQKS��N�#Ԧ��Q�v��B�ˡ�h�Fk	������!
 endstream
 endobj
 426 0 obj
-<</Creator(Typst 0.15.1)/ModDate(D:20261001133131-03'00)/CreationDate(D:20261001133131-03'00)>>
+<</Creator(Typst 0.15.1)/ModDate(D:20261001134538-03'00)/CreationDate(D:20261001134538-03'00)>>
 endobj
 427 0 obj
 <</Length 996/Type/Metadata/Subtype/XML>>
 stream
-<?xpacket begin="" id="W5M0MpCehiHzreSzNTczkc9d"?><x:xmpmeta xmlns:x="adobe:ns:meta/" x:xmptk="xmp-writer"><rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"><rdf:Description rdf:about="" xmlns:dc="http://purl.org/dc/elements/1.1/"  xmlns:xmp="http://ns.adobe.com/xap/1.0/"  xmlns:xmpMM="http://ns.adobe.com/xap/1.0/mm/"  xmlns:xmpTPg="http://ns.adobe.com/xap/1.0/t/pg/"  xmlns:pdf="http://ns.adobe.com/pdf/1.3/" ><xmp:CreatorTool>Typst 0.15.1</xmp:CreatorTool><dc:language><rdf:Bag><rdf:li>en</rdf:li></rdf:Bag></dc:language><xmp:ModifyDate>2026-10-01T13:31:31-03:00</xmp:ModifyDate><xmp:CreateDate>2026-10-01T13:31:31-03:00</xmp:CreateDate><xmpTPg:NPages>1</xmpTPg:NPages><dc:format>application/pdf</dc:format><xmpMM:InstanceID>IcrvJ+JD6aLZ3AQsDl9daw==</xmpMM:InstanceID><xmpMM:DocumentID>IcrvJ+JD6aLZ3AQsDl9daw==</xmpMM:DocumentID><xmpMM:RenditionClass>proof</xmpMM:RenditionClass><pdf:PDFVersion>1.7</pdf:PDFVersion></rdf:Description></rdf:RDF></x:xmpmeta><?xpacket end="r"?>
+<?xpacket begin="" id="W5M0MpCehiHzreSzNTczkc9d"?><x:xmpmeta xmlns:x="adobe:ns:meta/" x:xmptk="xmp-writer"><rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"><rdf:Description rdf:about="" xmlns:dc="http://purl.org/dc/elements/1.1/"  xmlns:xmp="http://ns.adobe.com/xap/1.0/"  xmlns:xmpMM="http://ns.adobe.com/xap/1.0/mm/"  xmlns:xmpTPg="http://ns.adobe.com/xap/1.0/t/pg/"  xmlns:pdf="http://ns.adobe.com/pdf/1.3/" ><xmp:CreatorTool>Typst 0.15.1</xmp:CreatorTool><dc:language><rdf:Bag><rdf:li>en</rdf:li></rdf:Bag></dc:language><xmp:ModifyDate>2026-10-01T13:45:38-03:00</xmp:ModifyDate><xmp:CreateDate>2026-10-01T13:45:38-03:00</xmp:CreateDate><xmpTPg:NPages>1</xmpTPg:NPages><dc:format>application/pdf</dc:format><xmpMM:InstanceID>Wg9IHgE89UC5Ijb2EbcBRQ==</xmpMM:InstanceID><xmpMM:DocumentID>Wg9IHgE89UC5Ijb2EbcBRQ==</xmpMM:DocumentID><xmpMM:RenditionClass>proof</xmpMM:RenditionClass><pdf:PDFVersion>1.7</pdf:PDFVersion></rdf:Description></rdf:RDF></x:xmpmeta><?xpacket end="r"?>
 endstream
 endobj
 428 0 obj
@@ -2018,7 +2018,7 @@ xref
 0000109208 00000 n
 0000110281 00000 n
 trailer
-<</Size 429/Root 428 0 R/Info 426 0 R/ID[(IcrvJ+JD6aLZ3AQsDl9daw==)(IcrvJ+JD6aLZ3AQsDl9daw==)]>>
+<</Size 429/Root 428 0 R/Info 426 0 R/ID[(Wg9IHgE89UC5Ijb2EbcBRQ==)(Wg9IHgE89UC5Ijb2EbcBRQ==)]>>
 startxref
 110468
 %%EOF
 \ No newline at end of file
diff --git a/docs/typ/guide.typ b/docs/typ/guide.typ
index e2b9ae77..1505afbc 100644
--- a/docs/typ/guide.typ
+++ b/docs/typ/guide.typ
@@ -1,7 +1,7 @@
 // The guide: pardes day to day, the path a newcomer reads once. Edge cases
 // live in the reference, the pager and the language servers in setup, the
 // keys on the cheatsheet.
-#import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs, glossary
+#import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs, glossary, annotated
 
 pardes reads the text on its screen as things to do, with two builtins.
 #word("Look") (right-click) on `src/bar.c:12` opens that line; on a URL,
@@ -11,6 +11,15 @@ screen is columns of panes, each a tag (a line of words) over a file, a
 terminal, a PDF or an image. The keys are helix's, and every session is a
 virtual filesystem, served over 9P, for scripts.
 
+#annotated("/docs/site/media/themes/orchard.png", (640, 513),
+  ([the workspace tag: words for the whole session], 330, 11),
+  ([a column's tag], 400, 34),
+  ([a pane's tag: its path, then its words], 560, 58),
+  ([the box: the pane's mode, and the handle to drag it], 8, 58),
+  ([the body: here a file, below it a terminal], 500, 128),
+  ([the scrollbar: how much of the body is in view], 8, 160),
+)
+
 #glossary("Words you'll see", <words>,
   [tag], [the line of words over a pane, a column or the screen; every word in it can be clicked],
   [the pane with the keyboard], [where your keys go; one pane at a time],
diff --git a/docs/typ/install.typ b/docs/typ/install.typ
index f4fc7fd3..f54cda46 100644
--- a/docs/typ/install.typ
+++ b/docs/typ/install.typ
@@ -6,7 +6,13 @@
 #let first = project.mirrors.first()
 #cmd("git clone " + first.clone + " && cd pardes")
 
-With Zig 0.16 (the build fetches everything else):
+#if project.download != none [
+  A static #raw(project.download.arch) binary: #link(project.download.url)[#raw(project.download.url.split("/").last())]
+  (sha256 #raw(project.download.sha256)). Or build it:
+]
+
+With Zig 0.16 (the build fetches everything else; once that is
+downloaded, a first build from a clean cache took 62 seconds on 16 cores):
 #cmd("# pardes, in a terminal\nzig build -Dplatform=tty --prefix ~/.local")
 #cmd("# pardes-gui, its own window\nzig build -Dplatform=gui --prefix ~/.local")
 Then run `pardes` or `pardes FILE`.
diff --git a/docs/typ/style.typ b/docs/typ/style.typ
index 2f63f3b2..c96b5e39 100644
--- a/docs/typ/style.typ
+++ b/docs/typ/style.typ
@@ -308,6 +308,9 @@
     (name: "git.0x4200.cafe", web: "https://git.0x4200.cafe/pardes", clone: "https://git.0x4200.cafe/pardes.git"),
   ),
   license: "ISC",
+  // a built binary to download, when there is one:
+  // (url: "...", sha256: "...", arch: "x86_64-linux")
+  download: none,
 )
 
 /// A glossary: like #pairs, under its own heading. On paper the heading
@@ -514,3 +517,40 @@
       )).flatten()))
   }
 }
+
+/// A screenshot with numbered pins on it and their labels as text beside
+/// it, so the labels read, search and translate as text. `src` is from
+/// the repository root (the site serves it from the same path under
+/// docs/site/); `size` is its pixel (width, height); each pin is (label,
+/// x, y) in pixels of that image.
+#let annotated(src, size, ..pins) = {
+  let (w, h) = size
+  let pins = pins.pos()
+  context if html-out() {
+    let web = src.trim("/docs/site/", at: start)
+    html.elem("figure", attrs: (class: "annotated"), {
+      html.elem("div", attrs: (class: "frame"), {
+        html.elem("img", attrs: (src: web, alt: "", width: str(w), height: str(h)))
+        for (i, (label, x, y)) in pins.enumerate() {
+          html.elem("span", attrs: (class: "pin", "aria-hidden": "true",
+            style: "left:" + str(calc.round(100 * x / w, digits: 2)) + "%;top:" + str(calc.round(100 * y / h, digits: 2)) + "%"), str(i + 1))
+        }
+      })
+      html.elem("ol", attrs: (class: "pins"), for (label, x, y) in pins { html.elem("li", label) })
+    })
+  } else {
+    let width = 11cm
+    let k = width / w
+    let pin(n) = box(width: 1.25em, height: 1.25em, radius: 50%, fill: palette.mouse,
+      align(center + horizon, text(size: 0.75em, weight: "bold", fill: white, str(n))))
+    block(breakable: false, grid(columns: (width, 1fr), column-gutter: 1.2em, align: horizon,
+      box(width: width, height: h * k, {
+        place(top + left, image(src, width: width))
+        for (i, (label, x, y)) in pins.enumerate() {
+          place(top + left, dx: x * k - 0.625em, dy: y * k - 0.625em, pin(i + 1))
+        }
+      }),
+      enum(..pins.map(p => p.at(0)), spacing: 0.7em),
+    ))
+  }
+}