Release 0.6.1

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GT37Z1Xtfd9pUuQtMTg6Yt

.gitea/workflows/publish.yml

@@ -71,7 +71,9 @@ jobs:
           cp -r target/site "$stage/site"
           tar -C "$stage" -czf "portal-$tag.tar.gz" portal hash.txt site
           # The bare binary as well: a content repo's CI runs `portal lint`
-          # and needs nothing else from the release.
+          # and needs nothing else from the release. Named to sort after
+          # the tarball: Gitea lists assets by name, and deploy scripts
+          # written before 0.6 take the first one.
           cp "$stage/portal" portal-bin
           rm -rf "$stage"
 
@@ -101,5 +103,5 @@ jobs:
             "$api/releases/$id/assets?name=portal-$tag.tar.gz" > /dev/null
           curl -sf -X POST -H "$auth" \
             -F "attachment=@portal-bin" \
-            "$api/releases/$id/assets?name=portal" > /dev/null
+            "$api/releases/$id/assets?name=portal-x86_64-linux" > /dev/null
           echo "published $tag"

CHANGELOG.md

@@ -4,11 +4,21 @@ One line per change, grouped by the release that shipped it. Newest
 first. A release is a Cargo.toml bump plus a `v<version>` tag; the
 content repos pin the tag they run (see the end of this file).
 
+## 0.6.1 (2026-09-30)
+
+- Trainer: `documents` in a plan. A text the site carries word for word (bylaws, terms) becomes a page of its own where every section is one alternative: its heading the card's, its paragraphs the card's words, from a markdown file beside the plan. No model touches it.
+
+- `slideshow` on a page: a strip of pictures the full width of the screen under the question, `max_height` in svh, each picture with its caption laid over it. Swiper when the bundle has loaded, a sideways-scrolling row before. `/site/` serves `jpeg`, and lets a browser keep photographs for an hour.
+
+- The release's bare binary is named `portal-x86_64-linux` (it was `portal` in 0.6.0 only). Gitea lists assets by name, and deploy scripts that take the first asset got the binary instead of the tarball.
+
 ## 0.6.0 (2026-09-30)
 
 - One binary. The lint (uhhm/iris) and the trainer (uhhm/portal-trainer) are commands of `portal`: `portal serve` (the default), `portal lint`, and `portal plan`, `build`, `answer`, `rate`, `prefer`, `score`, `simulate`, `compare`, `report`, `generate`. Same source, same version, so the site, the lint and the trainer never disagree about what content means; both histories are merged in. The release attaches the bare `portal` binary beside the tarball, so a content repo's CI downloads it and runs `portal lint`. No more iris releases; the pins that exist keep working. The trainer's `plans/`, `intakes/`, `engines/`, `sectors/` and its reference prompt live here now; its `runs/` stay in uhhm/portal-trainer. Docs gained "Training a site" and "The lint".
 
-## 0.5.11 (2026-09-30)
+## 0.5.11 (2026-09-30, tagged, never published)
+
+The publish job failed at its lint step: iris, built against this tag, did not compile against the storylines change (the same two fixes that went into `src/lint/` when the lint moved in). Nothing was attached to the tag; 0.6.0 is the first release that ships storylines.
 
 - Storylines (`src/content/variants.rs`, `docs/storylines.md`): any text a person reads may be a list, one entry per storyline, every list the same length; a visitor is given one storyline for the whole site (the `portal_storyline` cookie, a year) and reads it on every page and in every mail about their case. What the machine reads - a field's `name`, `options`, states, groups, paths - never varies. The lint refuses a list of another length. Records and answer events carry `storyline`, and `GET /report` gives counts per bucket, per storyline, per state, and nothing else.
 
@@ -408,4 +418,4 @@ hosts now, since kasse's runner deploys its own instances.
 | redoal.com | ergo | `app@redoal-portal` | v0.5.2 |
 | westra.klingenbergbygg.no | kasse | `app@westra-portal` | v0.5.2 |
 | portal.klingenbergbygg.no | kasse | `app@klingenberg-portal` | v0.5.2 |
-| vel.klingenbergbygg.no | kasse | `tomtervel-portal-1` (podman, tomtervel/infrastructure) | v0.5.10, memberships |
+| vel.klingenbergbygg.no | kasse | `tomtervel-portal-1` (podman, tomtervel/infrastructure) | v0.6.0, memberships |

Cargo.lock

@@ -3357,7 +3357,7 @@ dependencies = [
 
 [[package]]
 name = "portal"
-version = "0.6.0"
+version = "0.6.1"
 dependencies = [
  "anyhow",
  "arc-swap",

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "portal"
-version = "0.6.0"
+version = "0.6.1"
 edition = "2021"
 
 [lib]

docs/content-reference.md

@@ -76,6 +76,26 @@ nearest `_section.yaml`. `event` makes a page an occasion with a time;
 opening any `type: location` field on the page there rather than on
 the whole world.
 
+### Pictures across the page
+
+`slideshow` lays a strip of pictures under the question, the full
+width of the screen: every picture as tall as the strip and as wide as
+its own shape, swiped or arrowed through, its caption over its foot.
+
+```yaml
+slideshow:
+  max_height: 60               # svh; 60 unless set, between 20 and 100
+  slides:
+    - image: images/built/01.webp     # a path in the content repo, or https://
+      caption: The canteen at the theatre, renewed
+      width: 3207                     # the picture's own size, optional:
+      height: 1400                    # holds its place before it has loaded
+```
+
+Pictures in the content repo are served from this origin under
+`/site/`; `webp`, `avif` and `jpeg` may be kept by the browser for an
+hour. Keep them web-sized: around 1400 pixels tall is plenty.
+
 ## An alternative
 
 One choice. Never two actions behind one heading: if two things can be

docs/lint.md

@@ -15,7 +15,7 @@ content repo's CI downloads the release and runs it:
 
 ```yaml
       - run: |
-          curl -sfL "https://project.uhhm.no/uhhm/portal/releases/download/$PORTAL_RELEASE/portal" -o portal
+          curl -sfL "https://project.uhhm.no/uhhm/portal/releases/download/$PORTAL_RELEASE/portal-x86_64-linux" -o portal
           chmod +x portal && ./portal lint --path questions
 ```
 

plans/documents/tomtervel-vedtekter.md

@@ -0,0 +1,88 @@
+# Vedtekter
+
+### av 23.04.2018
+
+##### § 1
+
+Tomter vel er upolitisk. Foreningen har som formål å virke for stedets velferd, forskjønnelse og utvikling og ellers ivareta Tomters interesser.
+
+##### § 2
+
+Alle som er bosatt i Tomter kan bli medlem av foreningen. Midlertidig utflyttede medlemmer kan beholde sitt medlemskap.
+
+##### § 3
+
+Årsmøte, som er vellets øverste myndighet, holdes innen utgangen av mars hvert år. Møtet kunngjøres med minst tre ukers varsel. Forslag skal også gjøres kjent minst to uker før møtet. Årsmøte godkjenner beretning, regnskap og budsjett. Den velger styre, komitéledere, og valgkomite.
+
+##### § 4.
+
+Ekstraordinært årsmøte holdes når styret, eller minst 15 medlemmer krever det i skriftlig form. Gjennomføringen følger samme prosedyre som ordinært årsmøte
+
+##### § 5
+
+Tomter Vel ledes av et styre på seks medlemmer. Leder, nestleder, sekretær, kasserer og to styremedlemmer, som alle velges på årsmøtet. Funksjonstiden er to år. Leder, sekretær og ett styremedlem velges det ene året, nestleder, kasserer og det andre styremedlemmet det andre året. Det skal dessuten på årsmøte velges ett varamedlem til styret med funksjonstid to år. Styret engasjerer revisor eller ekstern regnskapsfører. Oppnevning av andre komitémedlemmer og representanter foretas av styret etter behov. Komitéledere har møterett på styremøter.
+
+##### § 6
+
+Medlemsmøte avholdes når styret finner det nødvendig og skal bekjentgjøres minst en uke i forveien. Det bør avholdes minst ett medlemmsmøte mellom hvert årsmøte.
+
+##### § 7.1
+
+Styret skal:
+
+iverksette årsmøtets vedtak og bestemmelser.
+
+Stå for velforeningens daglige ledelse og ivareta medlemmenes interesser overfor andre instanser.
+
+Stå for den alminnelige forvaltningen av foreningen, herunder forvalte velforeningens eiendeler og føre kontroll med foreningens økonomi.
+
+etter behov opprette komitéer eller bemyndige personer for å løse spesielle oppgaver.
+
+etter beste evne søke å oppfylle foreningens formål eller gjeldende regler.
+
+sørge for at foreningen er forsvarlig forsikret.
+
+##### § 7.2
+
+Styret har disposisjonsrett over velforeningens midler til alminnelige administrative formål og rett til å bevilge beløp til gjennomføring av vedtak på årsmøtet. Alle utbetalinger skal attesteres av leder og kasserer før utbetaling. Styret har imidlertid ikke adgang til uten samtykke fra årsmøtet å treffe beslutninger av større betydning for foreningen.
+
+##### § 7.3
+
+Styret holder møte når leder bestemmer eller et flertall av styremedlemmene forlanger det. Varamedlemmet kan møte på samtlige styremøter, men har kun stemmerett når styret ikke er fulltallig.
+
+Alle saker og all korrespondanse skal legges fram på styremøtet. Styrets vedtak skal protokolleres. Det skal fremgå av protokollen om vedtaket er enstemmig, og eventuelle dissenser protokolleres. Alle medlemmene har rett til innsyn i protokollene fra styremøtene. Innsyn kan nektes av styret i enkeltsaker, dersom hensynet til tredjemann tilsier det eller dersom andre saklige grunner for nektelse foreligger.
+
+##### § 7.4
+
+Styret er beslutningsdyktig når et flertall av styremedlemmene, deriblant leder eller nestleder, er tilstede. Leder eller i hans/hennes fravær nestleder, leder styrets møter. Styrebeslutninger krever alminnelig flertall. Ved stemmelikhet har fungerende leder dobbeltstemme.
+
+Et styremedlem kan ikke være med å stemme i saker hvor dette har særinteresser.
+
+##### § 8
+
+Regnskapsåret går fra 01.01–31.12. Styret skal påse at regnskapet blir ført.
+
+##### § 9
+
+Medlemskontingenten er den som til enhver tid er/blir fastsatt av Årsmøte. Kontingenten innkreves av styret. Den betales forskuddsvis.
+
+##### § 10
+
+Tomter Vel kan bare oppløses ved vedtak på Årsmøte etter forslag fra styret. Til slikt vedtak kreves to tredjedels stemmeflertall blant de frammøtte medlemmer. Forslag om oppløsning skal gjøres kjent 3 uker før årsmøtet holdes. Eventuelle midler som Tomter Vel sitter inne med, anvendes da straks til formål som kommer Tomter til gode.
+
+##### § 11
+
+Styret eller årsmøtet oppretter komiteer for definerte formål. Komitéer skal bestå av komiteleder som rapporterer til styret. Komiteleder tilknytter et egnet antall personer til formålet og organiserer arbeidet.
+
+##### § 12
+
+Valgkomiteen består av to medlemmer med funksjonstid ett år. Valgkomiteen foreslår overfor Årsmøte medlemmer og varamedlemmer til styre, komitéer og valgkomite, samt revisor.
+
+##### § 13
+
+Tomter Vel skal ha en revisorer med funksjonstid to år. Revisoren skal revidere regnskapet og legge fram revisjonsberetning for Årsmøtet.
+
+##### § 14
+
+Forandringer i disse lover kan bare skje ved vedtak på Årsmøte. Slikt vedtak krever to tredjedels stemmeflertall blant de frammøtte medlemmene.
+

plans/tomtervel.yaml

@@ -62,6 +62,14 @@ does:
       nabohjelpsgruppa deg med en nabo som kan. Du sier selv fra når
       det er ordnet.
 
+# Vedtektene, ord for ord slik årsmøtet vedtok dem: en side der hver
+# paragraf er sitt eget kort. Ingen modell rører teksten.
+documents:
+  - id: vedtekter
+    question: Hva sier vedtektene?
+    description: Vedtektene for Tomter Vel, av 23.04.2018.
+    file: documents/tomtervel-vedtekter.md
+
 doors:
   - id: medlem
     who: en husstand i Tomter som vil bli medlem, betale kontingent, eller melde flytting, ny e-post eller utmelding

src/app.rs

@@ -369,7 +369,7 @@ fn QuestionView(
     // Swiper Element only registers its custom elements when its
     // (vendored, ~180KB) script runs - loaded once per page, and only
     // on pages where some alternative actually declares a deck.
-    let needs_swiper = question.alternatives.iter().any(|a| a.images.len() > 1);
+    let needs_swiper = question.slideshow.is_some() || question.alternatives.iter().any(|a| a.images.len() > 1);
     // MapLibre is vendored and large, so it loads only where a field
     // actually asks for a place, and only where this instance can
     // serve tiles at all.
@@ -397,6 +397,60 @@ fn QuestionView(
             site=site.clone()
             current_id=question_id.clone()
         />
+        // Pictures across the page: the full width of the screen, each
+        // as wide as its own shape at the strip's height, the caption
+        // laid over its foot. Inert until the Swiper bundle upgrades
+        // the elements; without it, a row that scrolls sideways.
+        {question
+            .slideshow
+            .clone()
+            .map(|show| {
+                let height = format!("--slideshow-height: {}svh", show.max_height);
+                view! {
+                    // In the page itself, so the strip works from the
+                    // server's HTML alone; the head's copy above covers
+                    // arriving here by a link within the site.
+                    <script src="/swiper-element-bundle.min.js" defer=true></script>
+                    <swiper-container
+                        class="slideshow"
+                        style=height
+                        slides-per-view="auto"
+                        space-between="6"
+                        grab-cursor="true"
+                        free-mode="true"
+                        mousewheel-force-to-axis="true"
+                        keyboard="true"
+                        navigation="true"
+                    >
+                        <For
+                            each={move || show.slides.clone().into_iter().enumerate().collect::<Vec<_>>()}
+                            key=|(_, slide)| slide.image.clone()
+                            children=|(n, slide): (usize, crate::content::Slide)| {
+                                let caption = slide.caption.clone();
+                                // The first screenful loads with the
+                                // page; the rest when swiped to.
+                                let loading = if n < 4 { "eager" } else { "lazy" };
+                                view! {
+                                    <swiper-slide>
+                                        <figure class="slide">
+                                            <img
+                                                src=slide.src()
+                                                alt=slide.caption.clone()
+                                                width=slide.width.map(|w| w.to_string())
+                                                height=slide.height.map(|h| h.to_string())
+                                                loading=loading
+                                                decoding="async"
+                                            />
+                                            {(!caption.trim().is_empty()).then(|| view! { <figcaption>{caption}</figcaption> })}
+                                        </figure>
+                                    </swiper-slide>
+                                }
+                                .into_any()
+                            }
+                        />
+                    </swiper-container>
+                }
+            })}
         // A page that is about somewhere says where, under the
         // question: a still from this origin, and the place in words
         // for anyone who cannot see it.

src/content/handlers.rs

@@ -74,14 +74,19 @@ pub async fn site_asset_handler(
         Some("svg") => "image/svg+xml",
         Some("json") => "application/json",
         Some("png") => "image/png",
+        Some("jpg") | Some("jpeg") => "image/jpeg",
         Some("webp") => "image/webp",
         Some("avif") => "image/avif",
         Some("ico") => "image/x-icon",
         Some("woff2") => "font/woff2",
         _ => "application/octet-stream",
     };
+    // Photographs are large and do not change under a name, so a
+    // browser may keep them for an hour; everything else revalidates,
+    // so a content push shows on reload.
+    let cache = if matches!(mime, "image/webp" | "image/avif" | "image/jpeg") { "public, max-age=3600" } else { "no-cache" };
     (
-        [(header::CONTENT_TYPE, mime), (header::CACHE_CONTROL, "no-cache")],
+        [(header::CONTENT_TYPE, mime), (header::CACHE_CONTROL, cache)],
         bytes,
     )
         .into_response()

src/content/mod.rs

@@ -95,6 +95,12 @@ pub struct Question {
     /// rather than on the whole world.
     #[serde(default)]
     pub place: Option<Place>,
+    /// Pictures across the page, under the question: a strip the full
+    /// width of the screen that a visitor swipes through, each picture
+    /// with its caption laid over it. What the business has built,
+    /// shown rather than described.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub slideshow: Option<Slideshow>,
 }
 
 /// A point a page is about. `zoom` is a map zoom level, 0 (the globe)
@@ -625,6 +631,50 @@ pub struct Requirement {
 /// listing may ask about a record's own contents: one field, one
 /// value, compared as strings. Anything more is a query language, and
 /// a jq filter is already there for shaping what comes back.
+/// A strip of pictures across a page (`Question.slideshow`).
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct Slideshow {
+    /// How tall the strip may be, in hundredths of the small viewport
+    /// height (`svh`): 60 is six tenths of the screen. Every picture is
+    /// that tall and as wide as its own shape makes it.
+    #[serde(default = "default_slideshow_height")]
+    pub max_height: u8,
+    pub slides: Vec<Slide>,
+}
+
+fn default_slideshow_height() -> u8 {
+    60
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct Slide {
+    /// A path in the content repo (`images/built/01.webp`, served from
+    /// this origin under `/site/`) or an `https://` address.
+    pub image: String,
+    /// Laid over the foot of the picture, and its alternative text.
+    #[serde(default)]
+    pub caption: String,
+    /// The picture's own size in pixels, when known: the browser then
+    /// holds its place in the strip before it has loaded, so pictures
+    /// further along can wait until they are swiped to.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub width: Option<u32>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub height: Option<u32>,
+}
+
+impl Slide {
+    /// Where the browser fetches the picture: https as given, anything
+    /// else as a content-repo path under `/site/`.
+    pub fn src(&self) -> String {
+        if self.image.starts_with("https://") || self.image.starts_with("/site/") {
+            self.image.clone()
+        } else {
+            format!("/site/{}", self.image.trim_start_matches('/'))
+        }
+    }
+}
+
 /// A link from every listed record to a page about it (`ResourceSpec.link`).
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
 pub struct RowLink {
@@ -1904,6 +1954,17 @@ alternatives:
         assert_eq!((reqs[1].kind.as_str(), reqs[1].value.as_deref()), ("text", None));
     }
 
+    #[test]
+    fn a_slide_is_fetched_from_this_origin_unless_it_is_https() {
+        let q: Question = serde_yaml::from_str("name: Q?\nslideshow:\n  slides:\n    - { image: images/built/01.webp, caption: The canteen, width: 3207, height: 1400 }\n    - { image: \"https://cdn.example/a.jpg\" }\n").unwrap();
+        let show = q.slideshow.unwrap();
+        assert_eq!(show.max_height, 60);
+        assert_eq!(show.slides[0].src(), "/site/images/built/01.webp");
+        assert_eq!(show.slides[0].width, Some(3207));
+        assert_eq!(show.slides[1].src(), "https://cdn.example/a.jpg");
+        assert_eq!(show.slides[1].caption, "");
+    }
+
     #[test]
     fn markdown_drops_html_and_unsafe_links() {
         assert_eq!(render_inline_markdown("x <script>y</script> z"), "x y z");

src/content/validate.rs

@@ -146,6 +146,25 @@ pub fn validate_questions(
         }
     }
 
+    // A slideshow shows something, at a height that leaves the page
+    // its question: between a fifth and the whole of the screen.
+    for question in questions.values() {
+        if let Some(show) = &question.slideshow {
+            if show.slides.is_empty() {
+                anyhow::bail!("question {:?}: slideshow has no slides", question.id);
+            }
+            if !(20..=100).contains(&show.max_height) {
+                anyhow::bail!("question {:?}: slideshow max_height is {} svh; between 20 and 100", question.id, show.max_height);
+            }
+            for slide in &show.slides {
+                let ok = slide.image.starts_with("https://") || crate::content::is_safe_site_path(slide.image.trim_start_matches("/site/").trim_start_matches('/'));
+                if !ok {
+                    anyhow::bail!("question {:?}: slideshow image {:?} is neither an https address nor a path in the content repo", question.id, slide.image);
+                }
+            }
+        }
+    }
+
     // A mail to the record this one belongs to goes through a field of
     // the form: `{notice.email}` needs a `type: record` field called
     // `notice` on every form that records into the bucket, or the mail

src/trainer/build.rs

@@ -62,6 +62,12 @@ pub struct Plan {
     /// is what the page-load limit asks for.
     #[serde(default)]
     pub doors: Vec<Door>,
+    /// Texts the site carries word for word - bylaws, terms - each as
+    /// a page of its own where every section of the text is one
+    /// alternative: its heading the card's, its paragraphs the card's
+    /// words. No model touches them and no form hangs off them.
+    #[serde(default)]
+    pub documents: Vec<Document>,
     /// Groups with a label the public may see: the committees a
     /// person can ask to join. A select field with `options_from:
     /// groups` offers exactly these, so the form and the desks can
@@ -158,6 +164,85 @@ pub struct GroupDef {
     pub invited_by: Vec<String>,
 }
 
+/// A text carried word for word (`Plan.documents`).
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Document {
+    /// The page's path: `vedtekter` is served at `/vedtekter`.
+    pub id: String,
+    /// The question the page asks, which the text answers.
+    pub question: String,
+    #[serde(default)]
+    pub description: String,
+    /// A markdown file beside the plan: every heading with text under
+    /// it is a section. Read into `sections` when the plan is loaded.
+    #[serde(default)]
+    pub file: Option<String>,
+    #[serde(default)]
+    pub sections: Vec<Section>,
+}
+
+#[derive(Debug, Deserialize, Clone, PartialEq)]
+#[serde(deny_unknown_fields)]
+pub struct Section {
+    pub heading: String,
+    /// The section's paragraphs, exactly as written.
+    pub text: Vec<String>,
+}
+
+/// A markdown text as sections: each heading with text under it, and
+/// that text as paragraphs. A heading with nothing under it is a title
+/// and no section; text before the first heading belongs to nobody and
+/// is left out. Nothing is reworded: a paragraph's lines are joined
+/// with one space, and that is all.
+pub fn sections_of(markdown: &str) -> Vec<Section> {
+    let mut out: Vec<Section> = Vec::new();
+    let mut heading: Option<String> = None;
+    let mut paragraphs: Vec<String> = Vec::new();
+    let mut current: Vec<&str> = Vec::new();
+    let mut close = |heading: &mut Option<String>, paragraphs: &mut Vec<String>, out: &mut Vec<Section>| {
+        if let Some(h) = heading.take() {
+            if !paragraphs.is_empty() {
+                out.push(Section { heading: h, text: std::mem::take(paragraphs) });
+            }
+        }
+        paragraphs.clear();
+    };
+    for line in markdown.lines().chain(std::iter::once("")) {
+        let trimmed = line.trim();
+        let is_heading = trimmed.starts_with('#') && trimmed.trim_start_matches('#').starts_with(' ');
+        if trimmed.is_empty() || is_heading {
+            if !current.is_empty() {
+                paragraphs.push(current.join(" "));
+                current.clear();
+            }
+        }
+        if is_heading {
+            close(&mut heading, &mut paragraphs, &mut out);
+            heading = Some(trimmed.trim_start_matches('#').trim().trim_end_matches('.').to_string());
+        } else if !trimmed.is_empty() {
+            current.push(trimmed);
+        }
+    }
+    close(&mut heading, &mut paragraphs, &mut out);
+    out
+}
+
+impl Plan {
+    /// Reads every document's `file`, relative to `dir`, into its
+    /// sections. Done once, when a plan is loaded from disk.
+    pub fn load_documents(&mut self, dir: &Path) -> anyhow::Result<()> {
+        for doc in &mut self.documents {
+            if let Some(file) = &doc.file {
+                let path = dir.join(file);
+                let raw = std::fs::read_to_string(&path).with_context(|| format!("document {:?}: reading {}", doc.id, path.display()))?;
+                doc.sections = sections_of(&raw);
+            }
+        }
+        Ok(())
+    }
+}
+
 #[derive(Debug, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct Door {
@@ -410,6 +495,17 @@ impl Plan {
                 bail!("contact: group {group:?} has no desk: it must handle, watch or move something");
             }
         }
+        for doc in &self.documents {
+            if !is_id(&doc.id) || ["status", "received", "decide"].contains(&doc.id.as_str()) || groups(self).contains(&doc.id) || self.doors.iter().any(|d| d.id == doc.id) {
+                bail!("document {:?}: id must be ASCII lowercase with - or _, and a path no door, group or builder page has", doc.id);
+            }
+            if doc.question.trim().is_empty() {
+                bail!("document {:?}: the page needs the question its text answers", doc.id);
+            }
+            if doc.sections.is_empty() {
+                bail!("document {:?} has no sections: give it a `file` with headings, or `sections`", doc.id);
+            }
+        }
         let mut doors = BTreeSet::new();
         for door in &self.doors {
             if !is_id(&door.id) || !doors.insert(&door.id) {
@@ -2160,6 +2256,27 @@ pub fn render(plan: &Plan, words: &BTreeMap<String, Value>) -> anyhow::Result<BT
         );
     }
 
+    // Documents: a public page per text, one alternative per section,
+    // every word the plan's own. The first paragraph is the card's
+    // description; any further ones follow as unnamed features.
+    for doc in &plan.documents {
+        files.insert(
+            format!("questions/{}.yaml", doc.id),
+            json!({
+                "name": doc.question.trim(),
+                "description": doc.description.trim(),
+                "responsible": responsible,
+                "alternatives": doc.sections.iter().map(|section| {
+                    let mut alt = json!({ "name": section.heading, "description": section.text.first().cloned().unwrap_or_default() });
+                    if section.text.len() > 1 {
+                        alt["features"] = json!(section.text[1..].iter().map(|p| json!({ "name": "", "description": p })).collect::<Vec<_>>());
+                    }
+                    alt
+                }).collect::<Vec<_>>(),
+            }),
+        );
+    }
+
     // Public views: an ungated nav page per opened bucket, listing it
     // read-only, with contact details and private fields projected
     // away. Anyone can see what was sent in and where it stands.
@@ -2317,8 +2434,9 @@ pub fn run(argv: &[String]) -> anyhow::Result<()> {
     let usage = "usage: portal-trainer build --plan <plan.yaml> --out <dir> [--words-from <existing repo>] [--words <words.json>]... [--llm 'cmd'] [--lint question_lint]";
     let plan_path = value("--plan").ok_or_else(|| anyhow!(usage))?;
     let out = std::path::PathBuf::from(value("--out").ok_or_else(|| anyhow!(usage))?);
-    let plan: Plan = serde_yaml::from_str(&std::fs::read_to_string(&plan_path).with_context(|| format!("reading {plan_path}"))?)
+    let mut plan: Plan = serde_yaml::from_str(&std::fs::read_to_string(&plan_path).with_context(|| format!("reading {plan_path}"))?)
         .with_context(|| format!("parsing {plan_path}"))?;
+    plan.load_documents(Path::new(&plan_path).parent().unwrap_or_else(|| Path::new(".")))?;
     plan.validate()?;
     for warning in plan.spectators() {
         eprintln!("build: {warning}");
@@ -3267,6 +3385,34 @@ mod invite_tests {
         assert!(blank.validate().unwrap_err().to_string().contains("tones"));
     }
 
+    #[test]
+    fn a_document_is_a_page_with_one_card_per_section_word_for_word() {
+        let text = "# Vedtekter\n\n### av 23.04.2018\n\n##### § 1\n\nTomter vel er upolitisk. Foreningen har som\nformål å virke for stedets velferd.\n\n##### § 4.\n\nEkstraordinært årsmøte holdes når styret krever det.\n\nGjennomføringen følger samme prosedyre.\n";
+        let sections = sections_of(text);
+        // Titles with nothing under them are not sections; a wrapped
+        // paragraph is one paragraph; the words are untouched.
+        assert_eq!(sections.len(), 2);
+        assert_eq!(sections[0], Section { heading: "§ 1".into(), text: vec!["Tomter vel er upolitisk. Foreningen har som formål å virke for stedets velferd.".into()] });
+        assert_eq!(sections[1].heading, "§ 4");
+        assert_eq!(sections[1].text.len(), 2);
+        let mut plan: Plan = serde_yaml::from_str(&format!("{PLAN}documents:\n  - id: vedtekter\n    question: Hva sier vedtektene?\n    description: Vedtatt 23.04.2018.\n")).unwrap();
+        assert!(plan.validate().unwrap_err().to_string().contains("no sections"));
+        plan.documents[0].sections = sections;
+        plan.validate().unwrap();
+        let files = render(&plan, &fallback_words(&plan)).unwrap();
+        let page: Value = serde_yaml::from_str(&files["questions/vedtekter.yaml"]).unwrap();
+        assert_eq!(page["name"], "Hva sier vedtektene?");
+        let alts = page["alternatives"].as_array().unwrap();
+        assert_eq!(alts.len(), 2);
+        assert_eq!(alts[0]["name"], "§ 1");
+        assert_eq!(alts[0]["description"], "Tomter vel er upolitisk. Foreningen har som formål å virke for stedets velferd.");
+        assert!(alts[0].get("action").is_none() && alts[0].get("features").is_none());
+        assert_eq!(alts[1]["features"][0]["description"], "Gjennomføringen følger samme prosedyre.");
+        // A path something else has is refused.
+        plan.documents[0].id = "status".into();
+        assert!(plan.validate().unwrap_err().to_string().contains("document"));
+    }
+
     #[test]
     fn with_memberships_a_desk_invites_by_phone_and_lists_who_is_in() {
         let plan: Plan = serde_yaml::from_str(&PLAN.replace("invites_by: [board]\n", "invites_by: [board]\npeople: memberships\n")).unwrap();

src/trainer/plan.rs

@@ -175,6 +175,9 @@ rest. Each is one line in the plan, and the builder does the wiring:
   each brought in. Two is plenty; name them as a person would ("plain,
   like a good notice on the door"; "warm, as a neighbour would put
   it"). Leave it out to tell one story.
+- **Carry a text word for word.** `documents` puts bylaws or terms on
+  a page of their own, one card per section, from a markdown file
+  beside the plan. Nothing rewords them.
 - **Keep the people in portal.** `people: memberships` keeps every
   group in portal itself: a desk invite is a place held until the
   person signs in, a person is their phone number first, and any

style/main.css

@@ -269,6 +269,69 @@ main.not-found {
 /* position + z-index on these three: everything that scrolls over the
    sticky canvas must be a positioned box above the hero's z-index 0,
    or the (positioned) hero would paint over it. */
+/* Pictures across the page (`slideshow`): the full width of the
+   screen, every picture the strip's height and as wide as its own
+   shape, never wider than the screen. The caption floats over the
+   foot of its picture. */
+.slideshow {
+  --swiper-navigation-color: #fff;
+  --swiper-navigation-size: 1.8rem;
+  position: relative;
+  z-index: 1;
+  display: block;
+  width: 100%;
+  height: var(--slideshow-height, 60svh);
+  max-height: var(--slideshow-height, 60svh);
+  margin: 0 0 3rem;
+}
+
+/* Before the Swiper bundle has upgraded the element, or without it:
+   a row that scrolls sideways. */
+.slideshow:not(:defined) {
+  display: flex;
+  gap: 6px;
+  overflow-x: auto;
+  overflow-y: hidden;
+}
+
+.slideshow swiper-slide {
+  flex: none;
+  width: auto;
+  height: 100%;
+}
+
+.slide {
+  position: relative;
+  height: 100%;
+  margin: 0;
+}
+
+.slide img {
+  display: block;
+  height: 100%;
+  width: auto;
+  /* A picture that has not loaded and says nothing of its size still
+     takes a place, or the whole strip would sit in view at once. */
+  min-width: 12rem;
+  max-width: 100vw;
+  object-fit: cover;
+  background: var(--line);
+}
+
+.slide figcaption {
+  position: absolute;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  padding: 2.4rem 1rem 0.9rem;
+  color: #fff;
+  font-size: 0.95rem;
+  line-height: 1.35;
+  text-shadow: 0 0.06rem 0.2rem rgba(0, 0, 0, 0.6);
+  background: linear-gradient(to top, rgba(0, 0, 0, 0.72), rgba(0, 0, 0, 0));
+  pointer-events: none;
+}
+
 .alternatives {
   position: relative;
   z-index: 1;