Release 0.3.36

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01L4jrCgLiKKHAEFuZUJjckH

.gitea/workflows/publish.yml

@@ -88,9 +88,9 @@ jobs:
           tag="${{ github.ref_name }}"
           api="${{ github.server_url }}/api/v1/repos/${{ github.repository }}"
           auth="Authorization: token ${{ secrets.GITHUB_TOKEN }}"
-          subject=$(git log -1 --format=%s)
+          # The release notes are this version's section of CHANGELOG.md.
-          body=$(printf '{"tag_name":"%s","name":"%s"}' \
+          notes=$(awk -v v="${tag#v}" '/^## /{p = ($2 == v)} p' CHANGELOG.md | tail -n +2)
-            "$tag" "$tag: $(echo "$subject" | sed 's/"/\\"/g')")
+          body=$(jq -n --arg tag "$tag" --arg notes "$notes" '{tag_name: $tag, name: $tag, body: $notes}')
           id=$(curl -sf -X POST -H "$auth" -H 'Content-Type: application/json' \
             -d "$body" "$api/releases" | jq .id) \
             || id=$(curl -sf -H "$auth" "$api/releases/tags/$tag" | jq .id)

.gitea/workflows/test.yml

@@ -22,5 +22,22 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      # A throwaway JetStream for tests/jetstream.rs. Best effort: if the
+      # runner cannot use docker the variable stays unset and that one
+      # test reports itself skipped rather than failing the build.
+      - name: Start a throwaway JetStream
+        run: |
+          docker rm -f portal-test-nats >/dev/null 2>&1 || true
+          if docker run -d --rm --name portal-test-nats -p 127.0.0.1:14223:4222 nats:2.14.6-alpine -js >/dev/null 2>&1; then
+            sleep 2
+            echo "PORTAL_TEST_NATS_URL=nats://127.0.0.1:14223" >> "$GITHUB_ENV"
+          else
+            echo "::warning::no docker on this runner - the JetStream integration test will be skipped"
+          fi
+
       - name: Test
         run: cargo test --features ssr
+
+      - name: Stop the throwaway JetStream
+        if: always()
+        run: docker rm -f portal-test-nats >/dev/null 2>&1 || true

CHANGELOG.md

@@ -0,0 +1,283 @@
+# Changelog
+
+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.3.36 (2026-09-22)
+
+- Question nav: a followup is offered only once earned - the verified chain answered the alternative leading there, or a link that records nothing leads on from an earned page. Standing on a page no longer unlocks the pages behind its forms; the chain index now records which alternative was answered
+- One bounded HTTP client for every server-side fetch: 20 s budget, size caps per kind of fetch (`src/http.rs`)
+- Uploads are refused past 20 MB while streaming, and the route body limit that had capped them at axum's 2 MB default is raised to match
+- `tests/jetstream.rs`: the store, the event log and the projection tested against a real JetStream (CI starts a throwaway one)
+- `content` split into `gitea`, `validate`, `markdown`, `handlers`; every path still `content::x`
+- This changelog, and the table of what each site runs
+- Business needs as a checkable spec: needs.yaml + question_lint pass
+- needs: `success` states and a resolved simulation model
+- needs: `stages` - every stage the business named must be a state
+- needs_replay: make simulated cases real aggregates, report buckets by state
+- needs: also_moved_by - a need carried by more than one group's desk
+
+## 0.3.35 (2026-09-12)
+
+- Item cards: no paragraph margin under the description
+
+## 0.3.34 (2026-09-11)
+
+- Question nav: offer followups by reach, not by carrying any chain
+
+## 0.3.33 (2026-09-02)
+
+- Head preloads: latin font, wordmark, content-host preconnect
+
+## 0.3.32 (2026-09-01)
+
+- Per-site favicon via site.yaml
+
+## 0.3.31 (2026-09-01)
+
+- Markdown links allow tel:
+
+## 0.3.30 (2026-09-01)
+
+- Single alt-image shows natural height
+
+## 0.3.29 (2026-09-01)
+
+- Markdown image layout hints + AVIF assets
+
+## 0.3.28 (2026-09-01)
+
+- Hero description renders inline markdown
+
+## 0.3.27 (2026-09-01)
+
+- wordmark_invert: explicit, not inferred from .svg
+
+## 0.3.26 (2026-09-01)
+
+- Select fields: inline static options
+
+## 0.3.25 (2026-09-01)
+
+- Content-shipped stylesheet override (site.yaml stylesheet)
+
+## 0.3.24 (2026-09-01)
+
+- Gateway submit-as-link loses the underline
+
+## 0.3.23 (2026-09-01)
+
+- Chrome speaks the site's language: site.yaml lang + i18n table
+
+## 0.3.22 (2026-09-01)
+
+- site.yaml wordmark_height; raster logos keep their colors
+
+## 0.3.21 (2026-09-01)
+
+- Hero paragraph centers its measure box
+
+## 0.3.20 (2026-09-01)
+
+- Sign-in becomes optional: KANIDM_URL unset disables auth cleanly
+
+## 0.3.19 (2026-09-01)
+
+- Markdown images in descriptions, gated and framed
+
+## 0.3.18 (2026-09-01)
+
+- Item cards render inline markdown descriptions
+- Convergence: ink converges onto the decoded key (WebGL glow)
+- Gesture results overlay the canvas - the page never jumps
+
+## 0.3.16 (2026-08-30)
+
+- Announce sweeper: refresh open records from content
+
+## 0.3.15 (2026-08-30)
+
+- Hidden fields: carrier value without a label row
+
+## 0.3.14 (2026-08-30)
+
+- Feature cards: icon column, one text edge
+
+## 0.3.13 (2026-08-30)
+
+- Voice field: nothing leaves the browser until Keep it here
+
+## 0.3.12 (2026-08-30)
+
+- Voice preview stays hidden until there is something to play
+
+## 0.3.11 (2026-08-30)
+
+- README: gesture and voice fields
+- Validate templated actions against the page pattern
+
+## 0.3.10 (2026-08-30)
+
+- type: voice, Requirement.value, playable resource cards
+
+## 0.3.9 (2026-08-30)
+
+- Templated actions; places are pickable in the gesture input
+
+## 0.3.8 (2026-08-30)
+
+- Descriptions are inline markdown; Feature.link withdrawn
+
+## 0.3.7 (2026-08-30)
+
+- Feature.link: a card's name may point elsewhere
+
+## 0.3.6 (2026-08-30)
+
+- Announced pages: event windows, header announcements, summary tasks
+
+## 0.3.5 (2026-08-30)
+
+- Gesture widget: stop drawing the decoded ghost path
+- Gesture widget: ghost path back, for v2 keys only
+
+## 0.3.4 (2026-08-25)
+
+- Alternative.disabled: announced but not yet takeable
+
+## 0.3.3 (2026-08-25)
+
+- Empty list says so before it can parse as zero answers
+
+## 0.3.2 (2026-08-25)
+
+- README: hashed pkg assets in the release flow
+- Resource empty text: content-declared, and null counts as empty
+
+## 0.3.1 (2026-08-25)
+
+- Content-hashed pkg assets (hash-files) so stale bundles can't pair with new wasm
+
+## 0.3.0 (2026-08-25)
+
+- Hero becomes a content-owned module; site asset proxy; gesture growth fix
+
+## 0.2.4 (2026-08-25)
+
+- Gates keep the question nav
+
+## 0.2.3 (2026-08-25)
+
+- Attended-bucket lint rule; app-lifetime resources fix first-nav corruption
+
+## 0.2.2 (2026-08-24)
+
+- One app-level Title fed by a shared site resource
+
+## 0.2.1 (2026-08-24)
+
+- Docs: routing bullet + design doc marked implemented
+- Revalidating cache on app assets; site title survives SPA navigation
+
+## 0.2.0 (2026-08-24)
+
+- Initial commit: content-driven onboarding portal
+- Load content from Gitea directly, drop the local clone; add deploy workflow
+- Share sccache between manual dev builds and CI
+- Give CI its own SCCACHE_SERVER_PORT
+- Erase view types at every list/component boundary, not just leaves
+- Redirect cargo-leptos's tool cache out of act-runner-bare's StateDirectory
+- Fix Ship release: site-root is project-relative, not CARGO_TARGET_DIR
+- Drop sudo from the deploy workflow - NoNewPrivileges blocks it outright
+- Caddy snippet: use multi-line log block
+- Fix static asset 404s and build-time SITE_NAME
+- Hot-reload content on a NATS trigger instead of requiring a restart
+- Add prosekit rich-text field, Gitea repo embeds, automation KV read endpoint; fix apex/www session-cookie mismatch on /auth/callback
+- Fix prosekit-editor.js: remove bare CSS imports that aborted the whole module
+- Redirect back to the originating page after sign-in, not always /
+- Fix hero-canvas navigation race; style the prosekit editor and add a toolbar
+- yes.js: guard against the canvas not being in the DOM yet
+- Fix get_resource/transition_answer: scope feature lookup to its own alternative
+- Add self-service transitions, authorized by item possession not group membership
+- Event-sourced applicant/subscriber/project aggregates, generalized resources
+- deploy.yml: write GITEA_API_TOKEN for the new GiteaStarred/OrgRepos resource sources
+- Cargo.toml: disambiguate bin-target for cargo-leptos
+- Add manually-triggered backfill workflow, no terminal/sudo needed
+- Trigger redeploy to pick up PORTAL_GITEA_API_TOKEN secret
+- Render generic resource lists as cards, not raw JSON dump
+- Fix recursion-limit build failure in the new item-card renderer
+- Resource-backed multi/single-select requirement
+- Add Organization aggregate (client-as-status), wired but inert
+- Fix favicon (real icon, not an unrelated orange circle) + stack encouragements with the submit button
+- Fix bucket-404 on empty resources, redesign review actions as select-then-confirm, CSS polish
+- Inline encouragements with the submit button, vertically centered
+- Use the real institutional logo for the header wordmark, not plain text
+- Use the actual UHHM-letters wordmark, not the institutional mark
+- Responsive base font size via svmin, not fixed 17px
+- Add plain-unit fallbacks for svmin/svh in case of unsupported engines
+- Size the YES canvas from its container, not window.innerHeight
+- Debounce the YES canvas resize handler and skip no-op resizes
+- Revert canvas sizing to window.innerWidth/innerHeight, gate resize on width change
+- Stop blocking native scroll on the YES canvas's touch handlers
+- Quicksand: font-display optional, not swap, to stop the text-jump on scroll
+- Use lvh/lvmin, not svh/svmin - svh was the wrong end of the viewport
+- Update style/main.css
+- Update style/main.css
+- YES canvas: size off its own container rect, not window.innerHeight
+- yes.js: freeze .hero-yes's height via inline style, don't trust svh alone
+- add responsive container width
+- deploy.yml: build and publish question_lint alongside the app binary
+- Make aggregate state graphs content-driven, not compiled Rust
+- One shared, content-labeled Confirm button per alternative instead of one per row
+- get_resource/get_requirement_options: #[server(default)] on params
+- Add optional Alternative.image and Feature.color/icon for richer layouts
+- Drop the feature list's left-padding
+- Drop question-report entirely, obfuscate the mailto link instead
+- Transition.from: state graphs deeper than one decision
+- Alternative.images: array of urls, rendered as a Swiper card deck
+- Reseed lost event history from the KV projection on transition
+- Lighten the comment load
+- Validate action targets; format timestamps client-side; clippy cleanup
+- Question nav + gateway alternatives
+- Responsible note under the title; followup pages out of the nav until a chain exists
+- README: what the engine provides
+- Feature icons: masked span painted by currentColor, not <img>
+- Responsible note: one line, same hue and size as the hero description
+- Responsible note as <small>: meta information, dimmer than the description
+- Responsible note back to the footer, above the question nav
+- Bound inputs: a field that loads its value from a sibling-parameterized resource
+- add some more width to our alternatives
+- Accent to a dusty press-cyan, a muted echo of the canvas's cyan ink
+- Editor type in rem: prosekit's px typography ignored the responsive root
+- Ban px from stylesheets: every length rem/em off the responsive root
+- No translucent input chrome: solid ink-dim placeholders and embed meta
+- Editor type scales for real: drop prosekit typography.css, fix selectors
+- Stable server fn endpoints: open tabs survive deploys
+- Drop stray local tool temp file, ignore .claude/
+- Noise-driven YES, sticky hero with frosted cards, full light theme
+- increase translucency of laternative cards
+- Showcase jq test tracks Gitea repo shape and website-first links
+- Gesture input type, redoal-relay client, gitea_releases, content-driven branding
+- Echo thumbnails fade in via timeout, not rAF
+- Trigger deploy: redoal OAuth2 credentials now configured
+- Deploy becomes publish: portal ships as a versioned release artifact
+- Semver releases cut with cargo-release; publish on v* tags only
+- Docs: release/rollout flow after the instance-ownership refactor
+- README: frame portal as a generic multi-site question engine
+- Design doc: filesystem routes, sections, dynamic segments
+- Filesystem routes, sections, dynamic segments; instant YES hero
+
+
+## What each site runs
+
+Read from the hosts on 2026-09-22; a rollout is a pin bump in the
+site's content repo (`PORTAL_RELEASE` in its `deploy.yml`), or a manual
+tarball deploy on kasse.
+
+| Site | Host | Instance | Version |
+|---|---|---|---|
+| uhhm.no | ergo | `app@uhhm-portal` | v0.3.35 |
+| redoal.com | ergo | `app@redoal-portal` | v0.3.35 |
+| westra.klingenbergbygg.no | kasse | `app@westra-portal` | v0.3.35 |
+| portal.klingenbergbygg.no | kasse | `app@klingenberg-portal` | v0.3.35 |

Cargo.lock

@@ -2948,7 +2948,7 @@ dependencies = [
 
 [[package]]
 name = "portal"
-version = "0.3.34"
+version = "0.3.36"
 dependencies = [
  "anyhow",
  "arc-swap",

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "portal"
-version = "0.3.34"
+version = "0.3.36"
 edition = "2021"
 
 [lib]
@@ -106,11 +106,20 @@ ssr = [
 [dev-dependencies]
 proptest = "1"
 
+[[test]]
+name = "jetstream"
+required-features = ["ssr"]
+
 [[bin]]
 name = "question_lint"
 path = "src/bin/question_lint.rs"
 required-features = ["ssr"]
 
+[[bin]]
+name = "needs_replay"
+path = "src/bin/needs_replay.rs"
+required-features = ["ssr"]
+
 [profile.wasm-release]
 inherits = "release"
 opt-level = 'z'

README.md

@@ -71,9 +71,21 @@ stream.
   parent(s), so a visitor's path through the questions is a verifiable
   lineage; `?chain=` links carry it, and self-service transitions
   (unsubscribe) authorize by holding one. The question nav reads it
-  too: a `followup` page is offered only when it is on that path (the
+  too: a `followup` page is offered only once the visitor has earned
-  page the chain verifiably answered) or further down from the current
+  it - the chain verifiably answered the alternative that leads there,
-  page over `action` edges - one followup path never unlocks another.
+  or it hangs off an earned page by a link that records nothing. A
+  page behind an answer they have not given is never offered.
+- **Business needs as a checkable spec** (`src/needs.rs`,
+  `question_lint`): a content repo may ship a `needs.yaml` saying who
+  wants what, which bucket the answer must land in, and which group
+  has to carry it to a finished state. The lint proves the structure
+  (a path of submissions within an effort budget, a desk held by that
+  group, every finished state reachable, no record stranding; a
+  `planned` need warns instead of failing). Its personas - visitors in
+  their own words - become typed `choice` tasks for any external
+  answering engine (`--needs-tasks`, `--skim` for headings only) whose
+  picks are graded with `--needs-score`: a misroute is a wording
+  defect. The runtime never reads the file.
 - **Live resources** (`src/resource.rs`): content can pull a KV
   bucket, Gitea starred/org repos/releases, or any public JSON URL
   (SSRF fail-closed), reshaped by a content-declared `jq` filter.
@@ -131,6 +143,11 @@ content-hashed (`hash-files = true`; instances run with
 stale cached bundle with new wasm. Plain pushes to `main` only run the
 tests (`test.yml`) — nothing reaches production from this repo.
 
+Before cutting, move the `Unreleased` lines in `CHANGELOG.md` under a
+heading for the new version. That section becomes the Gitea release
+notes, and the table at the end of the file records which version each
+site runs; update it when a pin moves.
+
 **Roll it out** (in a content repo): edit one line in that repo's
 `.gitea/workflows/deploy.yml` —
 

src/app.rs

@@ -2033,18 +2033,19 @@ pub async fn get_site() -> Result<SiteConfig, ServerFnError> {
 /// Every question the visitor may be offered from `current`, as (id,
 /// name) - the question nav's data. Front-door pages the visitor
 /// qualifies for are always in (an owner session sees the gated desks
-/// too); `followup` pages and ended events only when they are on the
+/// too). A `followup` page or an ended event is in only when the
-/// visitor's path - the page their verified `?chain=` answered - or
+/// visitor has earned it: their verified `?chain=` answered the
-/// further down from `current` (see `content::outcomes_reachable_from`).
+/// alternative that leads there, or it is reachable from an earned
-/// A chain unlocks the followup it came from, never every followup on
+/// page over links that record nothing (see `content::earned_followups`).
-/// the site; an unverifiable hash unlocks nothing.
+/// Nothing is offered that sits behind an answer they have not given;
+/// an unverifiable hash unlocks nothing.
 #[server(endpoint = "list_qualifying_questions")]
 pub async fn list_qualifying_questions(
     current: String,
     chain: Option<String>,
 ) -> Result<Vec<(String, String)>, ServerFnError> {
     use crate::auth::{User, SESSION_USER_KEY};
-    use crate::content::{is_qualified, outcomes_reachable_from, Question};
+    use crate::content::{earned_followups, is_qualified, unlocked_by, Question};
     use crate::server::AppState;
 
     let state = expect_context::<AppState>();
@@ -2056,26 +2057,23 @@ pub async fn list_qualifying_questions(
 
     let now_ms = chrono::Utc::now().timestamp_millis();
     let questions = state.questions.load();
-    // The one page the chain verifiably answered - the same lookup a
+    // What the chain verifiably answered - the same lookup a
     // `requires_chain` gate does, so a forged or foreign hash resolves
-    // to nothing relevant.
+    // to nothing - and therefore where it sent the visitor.
-    let answered: Option<String> = match &chain {
+    let seeds: Vec<String> = match &chain {
-        Some(hash) => crate::chain::lookup_node(&state.jetstream, hash)
+        Some(hash) => match crate::chain::lookup_node(&state.jetstream, hash).await {
-            .await
+            Some(node) => unlocked_by(&questions, &node.question_id, node.alternative.as_deref()),
-            .map(|node| node.question_id),
+            None => Vec::new(),
-        None => None,
+        },
+        None => Vec::new(),
     };
     // An ended event page is a followup from then on.
     let is_outcome = |q: &Question| q.is_followup() || q.event_ended_at(now_ms);
-    let reach = outcomes_reachable_from(&questions, &current, &is_outcome);
+    let earned = earned_followups(&questions, &current, &seeds, &is_outcome);
     let mut out: Vec<(String, String)> = questions
         .values()
         .filter(|q| is_qualified(user.as_ref(), q))
-        .filter(|q| {
+        .filter(|q| !is_outcome(q) || earned.contains(&q.id))
-            !is_outcome(q)
-                || answered.as_deref() == Some(q.id.as_str())
-                || reach.contains(&q.id)
-        })
         // A live event is announced in the header instead.
         .filter(|q| !q.event_live_at(now_ms))
         // A dynamic page has no URL of its own to link to.
@@ -2225,7 +2223,7 @@ pub async fn submit_answer(
     // Index the node so requires_chain pages can verify lineage.
     // Best-effort: the NATS event above is the durable record.
     if let Err(e) =
-        crate::chain::record_node(&state.jetstream, &chain_hash, &question_id, timestamp_ms).await
+        crate::chain::record_node(&state.jetstream, &chain_hash, &question_id, &alternative, timestamp_ms).await
     {
         tracing::error!("failed to index chain node: {e}");
     }

src/bin/needs_replay.rs

@@ -0,0 +1,107 @@
+//! Makes a simulation's cases real: every case becomes an aggregate in
+//! its bucket, created and moved by the same code the running site
+//! uses - `answers::store_answer` for the submission,
+//! `aggregates::transition` for each desk move, against a real
+//! JetStream with its event log and its refusal of undeclared moves.
+//! Then the buckets are read back by replaying each record's events,
+//! and reported per need against `done_when` and `success`.
+//!
+//! The report half runs on its own (`--report-only`) against any
+//! JetStream, which is how the same scorecard is taken from a live
+//! site's buckets.
+//!
+//! Point it at a throwaway NATS, never a site's own: it writes.
+#![cfg(feature = "ssr")]
+
+use std::collections::{BTreeMap, HashMap};
+
+use futures::StreamExt;
+use portal::events::store::{ensure_stream, load_events};
+use portal::local::{load_aggregates_from_dir, load_from_dir, load_needs_from_dir};
+use portal::{aggregates, answers, content, needs};
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let argv: Vec<String> = std::env::args().skip(1).collect();
+    let value = |flag: &str| argv.iter().position(|a| a == flag).and_then(|i| argv.get(i + 1)).cloned();
+    let usage = "usage: needs_replay --path <questions dir> --nats <url> (--cases <cases.jsonl> | --report-only)";
+    let dir = value("--path").ok_or_else(|| anyhow::anyhow!(usage))?;
+    let nats_url = value("--nats").ok_or_else(|| anyhow::anyhow!(usage))?;
+    let cases_path = value("--cases");
+    if cases_path.is_none() && !argv.iter().any(|a| a == "--report-only") {
+        anyhow::bail!(usage);
+    }
+
+    let questions = load_from_dir(&dir)?;
+    let schemas = content::with_builtin_aggregates(load_aggregates_from_dir(&dir)?);
+    let file = needs::parse(&load_needs_from_dir(&dir)?.ok_or_else(|| anyhow::anyhow!("the repo has no needs.yaml"))?)?;
+    let js = async_nats::jetstream::new(async_nats::connect(&nats_url).await?);
+    // The same call the site makes at boot.
+    ensure_stream(&js).await?;
+
+    if let Some(path) = cases_path {
+        let raw = std::fs::read_to_string(&path).map_err(|e| anyhow::anyhow!("reading {path}: {e}"))?;
+        let (mut created, mut moved, mut refused) = (0, 0, 0);
+        for (n, line) in raw.lines().filter(|l| !l.trim().is_empty()).enumerate() {
+            let case: serde_json::Value = serde_json::from_str(line)?;
+            let Some(need) = file.needs.iter().find(|need| case["need"] == need.id.as_str()) else { continue };
+            let Some(schema) = schemas.get(&need.lands_in) else { continue };
+            // Only a case that got as far as submitting leaves a record.
+            let states: Vec<&str> = case["states"].as_array().into_iter().flatten().filter_map(|s| s.as_str()).collect();
+            if states.is_empty() {
+                continue;
+            }
+            let step = needs::path_for(&questions, need).and_then(|p| p.last().cloned());
+            let (page, alternative) = step.map(|s| (s.page, s.alternative)).unwrap_or_default();
+            let id = format!("sim-{}-{}-{n}", case["persona"].as_str().unwrap_or("x"), case["run"]);
+            let now = chrono::Utc::now().timestamp_millis();
+            answers::store_answer(&js, &schemas, &need.lands_in, id.clone(), &page, &alternative, &case["record"], now).await?;
+            created += 1;
+            for target in &states[1..] {
+                match aggregates::transition(&js, schema, &id, target, serde_json::json!({"by": "simulation"}), now).await {
+                    Ok(_) => moved += 1,
+                    Err(e) => {
+                        refused += 1;
+                        eprintln!("REFUSED by the engine: {id} -> {target}: {e:?}");
+                        break;
+                    }
+                }
+            }
+        }
+        println!("{created} aggregate(s) created, {moved} transition(s) accepted, {refused} refused by the engine\n");
+    }
+
+    // Read every bucket back the way the engine knows it: by replaying
+    // each record's own event log.
+    let mut by_bucket: HashMap<String, BTreeMap<String, usize>> = HashMap::new();
+    for bucket in file.needs.iter().map(|n| n.lands_in.clone()).collect::<std::collections::BTreeSet<_>>() {
+        let (Some(schema), Ok(store)) = (schemas.get(&bucket), js.get_key_value(&bucket).await) else { continue };
+        let mut keys = store.keys().await?;
+        while let Some(Ok(id)) = keys.next().await {
+            let events = load_events(&js, &bucket, &id).await?;
+            if let Some(record) = aggregates::replay(schema, &id, &events) {
+                *by_bucket.entry(bucket.clone()).or_default().entry(record.state).or_default() += 1;
+            }
+        }
+    }
+    println!("{:<18} {:>8} {:>9} {:>9}   {}", "bucket", "records", "finished", "success", "by state");
+    let mut buckets: Vec<_> = by_bucket.iter().collect();
+    buckets.sort();
+    for (bucket, states) in buckets {
+        let needs_here: Vec<&needs::Need> = file.needs.iter().filter(|n| &n.lands_in == bucket).collect();
+        let is = |pick: fn(&needs::Need) -> &Vec<String>, state: &String| needs_here.iter().any(|n| pick(n).contains(state));
+        let total: usize = states.values().sum();
+        let finished: usize = states.iter().filter(|(s, _)| is(|n| &n.done_when, s)).map(|(_, c)| c).sum();
+        let success: usize = states.iter().filter(|(s, _)| is(|n| &n.success, s)).map(|(_, c)| c).sum();
+        let pct = |n: usize| if total == 0 { "-".to_string() } else { format!("{:.0}%", n as f64 * 100.0 / total as f64) };
+        println!(
+            "{:<18} {:>8} {:>9} {:>9}   {}",
+            bucket,
+            total,
+            pct(finished),
+            pct(success),
+            states.iter().map(|(s, c)| format!("{s} {c}")).collect::<Vec<_>>().join(", ")
+        );
+    }
+    Ok(())
+}

src/bin/question_lint.rs

@@ -9,7 +9,8 @@
 //! static binary," not "build a Rust workspace."
 #![cfg(feature = "ssr")]
 
-use portal::{aggregates, content};
+use portal::local::{load_aggregates_from_dir, load_from_dir, load_needs_from_dir, load_site_from_dir};
+use portal::{aggregates, content, needs};
 
 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
@@ -18,6 +19,11 @@ async fn main() -> anyhow::Result<()> {
     let mut branch = "main".to_string();
     let mut subdir = "questions".to_string();
     let mut path: Option<String> = None;
+    let mut tasks_out: Option<String> = None;
+    let mut answers_in: Option<String> = None;
+    let mut min_accuracy: f64 = 0.0;
+    let mut skim = false;
+    let mut sim_out: Option<String> = None;
 
     while let Some(arg) = args.next() {
         match arg.as_str() {
@@ -25,6 +31,13 @@ async fn main() -> anyhow::Result<()> {
             "--branch" => branch = args.next().unwrap_or(branch),
             "--subdir" => subdir = args.next().unwrap_or(subdir),
             "--path" => path = args.next(),
+            "--needs-tasks" => tasks_out = args.next(),
+            "--skim" => skim = true,
+            "--needs-sim" => sim_out = args.next(),
+            "--needs-score" => answers_in = args.next(),
+            "--min-accuracy" => {
+                min_accuracy = args.next().and_then(|v| v.parse().ok()).unwrap_or(min_accuracy)
+            }
             other => {
                 eprintln!("unknown argument: {other}");
                 std::process::exit(2);
@@ -32,18 +45,24 @@ async fn main() -> anyhow::Result<()> {
         }
     }
 
-    let (questions, aggregates_map, site) = if let Some(dir) = path {
+    let (questions, aggregates_map, site, needs_raw) = if let Some(dir) = path {
-        (load_from_dir(&dir)?, load_aggregates_from_dir(&dir)?, load_site_from_dir(&dir)?)
+        (
+            load_from_dir(&dir)?,
+            load_aggregates_from_dir(&dir)?,
+            load_site_from_dir(&dir)?,
+            load_needs_from_dir(&dir)?,
+        )
     } else if let Some(repo_url) = repo {
         let questions = content::load_questions_from_gitea(&repo_url, &branch, &subdir).await?;
         let aggregates_map = content::load_aggregates_from_gitea(&repo_url, &branch).await?;
         // load_site_from_gitea already validates; a missing file is
         // the default config, same as at portal boot.
         let site = content::load_site_from_gitea(&repo_url, &branch).await?;
-        (questions, aggregates_map, site)
+        let needs_raw = content::load_needs_from_gitea(&repo_url, &branch).await?;
+        (questions, aggregates_map, site, needs_raw)
     } else {
         eprintln!(
-            "usage: question-lint --repo <gitea-url> [--branch main] [--subdir questions] | --path <local-dir>"
+            "usage: question-lint (--repo <gitea-url> [--branch main] [--subdir questions] | --path <local-dir>) [--needs-tasks <out.jsonl> [--skim]] [--needs-sim <model.json>] [--needs-score <answers.jsonl> [--min-accuracy 0.8]]"
         );
         std::process::exit(2);
     };
@@ -72,7 +91,16 @@ async fn main() -> anyhow::Result<()> {
                 questions.len(),
                 aggregates_map.len()
             );
-            Ok(())
+            check_needs(
+                needs_raw.as_deref(),
+                &questions,
+                &aggregates_map,
+                tasks_out.as_deref(),
+                skim,
+                sim_out.as_deref(),
+                answers_in.as_deref(),
+                min_accuracy,
+            )
         }
         Err(e) => {
             eprintln!("FAIL: {e}");
@@ -81,78 +109,118 @@ async fn main() -> anyhow::Result<()> {
     }
 }
 
-/// The offline counterpart to `content::load_site_from_gitea` -
+/// The business-needs pass (see `portal::needs`): structure always,
-/// `site.yaml` lives at the repo root like `aggregates.yaml`, and is
+/// then the wording tasks written out and/or an engine's answers
-/// just as optional locally: missing means default branding.
+/// scored, when asked. A repo without `needs.yaml` skips all of it.
-fn load_site_from_dir(dir: &str) -> anyhow::Result<content::SiteConfig> {
+fn check_needs(
-    let site_path = std::path::Path::new(dir)
+    raw: Option<&str>,
-        .parent()
+    questions: &std::collections::HashMap<String, content::Question>,
-        .unwrap_or_else(|| std::path::Path::new("."))
+    aggregates_map: &std::collections::HashMap<String, aggregates::AggregateSchema>,
-        .join("site.yaml");
+    tasks_out: Option<&str>,
-    if !site_path.exists() {
+    skim: bool,
-        return Ok(content::SiteConfig::default());
+    sim_out: Option<&str>,
-    }
+    answers_in: Option<&str>,
-    let raw = std::fs::read_to_string(&site_path)
+    min_accuracy: f64,
-        .map_err(|e| anyhow::anyhow!("reading {}: {e}", site_path.display()))?;
-    serde_yaml::from_str(&raw).map_err(|e| anyhow::anyhow!("parsing {}: {e}", site_path.display()))
-}
-
-/// The offline counterpart to `content::load_aggregates_from_gitea` -
-/// `aggregates.yaml` lives at the repo root, one level up from the
-/// pages directory `--path` names, so `dir`'s parent is where it's
-/// looked for. Missing entirely is not an error here (unlike
-/// `--repo` mode, where `aggregates.yaml` is required) - a local
-/// checkout being linted may not have one, and every declared
-/// transition still gets checked against whatever *is* found; an
-/// empty map just means nothing is checked.
-fn load_aggregates_from_dir(
-    dir: &str,
-) -> anyhow::Result<std::collections::HashMap<String, aggregates::AggregateSchema>> {
-    let aggregates_path = std::path::Path::new(dir)
-        .parent()
-        .unwrap_or_else(|| std::path::Path::new("."))
-        .join("aggregates.yaml");
-    if !aggregates_path.exists() {
-        return Ok(std::collections::HashMap::new());
-    }
-    let raw = std::fs::read_to_string(&aggregates_path)
-        .map_err(|e| anyhow::anyhow!("reading {}: {e}", aggregates_path.display()))?;
-    aggregates::parse_aggregates_yaml(&raw)
-}
-
-/// The offline counterpart to `content::load_questions_from_gitea` -
-/// the same recursive tree walk and `content::build_questions`
-/// pipeline (derived ids, relative refs, sections, followup
-/// inference), just reading a local checkout instead of Gitea's API,
-/// for linting a branch that hasn't been pushed yet.
-fn load_from_dir(
-    dir: &str,
-) -> anyhow::Result<std::collections::HashMap<String, content::Question>> {
-    let base = std::path::Path::new(dir);
-    let mut files = Vec::new();
-    collect_yaml(base, base, &mut files)?;
-    content::build_questions(&files)
-}
-
-fn collect_yaml(
-    base: &std::path::Path,
-    dir: &std::path::Path,
-    out: &mut Vec<(String, String)>,
 ) -> anyhow::Result<()> {
-    for entry in std::fs::read_dir(dir)? {
+    let Some(raw) = raw else {
-        let path = entry?.path();
+        if tasks_out.is_some() || answers_in.is_some() {
-        if path.is_dir() {
+            eprintln!("FAIL: --needs-tasks/--needs-score given, but the repo has no needs.yaml");
-            collect_yaml(base, &path, out)?;
+            std::process::exit(1);
-        } else if path.extension().and_then(|e| e.to_str()) == Some("yaml") {
-            let rel = path
-                .strip_prefix(base)
-                .expect("walked paths sit under their base")
-                .to_string_lossy()
-                .replace('\\', "/");
-            let raw = std::fs::read_to_string(&path)
-                .map_err(|e| anyhow::anyhow!("reading {}: {e}", path.display()))?;
-            out.push((rel, raw));
         }
+        return Ok(());
+    };
+    let file = match needs::parse(raw) {
+        Ok(file) => file,
+        Err(e) => {
+            eprintln!("FAIL: {e}");
+            std::process::exit(1);
+        }
+    };
+    let findings = needs::check(&file, questions, aggregates_map);
+    let mut failed = 0;
+    for finding in &findings {
+        let level = match finding.level {
+            needs::Level::Fail => {
+                failed += 1;
+                "FAIL"
+            }
+            needs::Level::Warn => "WARN",
+        };
+        eprintln!("{level}: need {:?}: {}", finding.need, finding.message);
+    }
+    for need in &file.needs {
+        if let Some(path) = needs::path_for(questions, need) {
+            let steps: Vec<String> = path
+                .iter()
+                .map(|s| format!("{} [{}]", s.page, s.alternative))
+                .collect();
+            println!("need {:?}: {} -> {:?}", need.id, steps.join(" -> "), need.lands_in);
+        }
+    }
+    if failed == 0 {
+        let planned = file.needs.iter().filter(|n| n.planned).count();
+        println!(
+            "OK: {} need(s) structurally met, {} planned, {} persona(s)",
+            file.needs.len() - planned,
+            planned,
+            file.personas.len()
+        );
+    }
+    // The wording pass still runs for the needs that do have a path -
+    // a closed flow elsewhere is no reason to stop grading the rest.
+
+    if let Some(out) = sim_out {
+        let model = needs::sim_model(&file, questions, aggregates_map);
+        std::fs::write(out, serde_json::to_string_pretty(&model)?)
+            .map_err(|e| anyhow::anyhow!("writing {out}: {e}"))?;
+        println!("wrote the simulation model to {out}");
+    }
+    let tasks = needs::tasks(&file, questions, skim);
+    if let Some(out) = tasks_out {
+        let mut lines = String::new();
+        for task in &tasks {
+            lines.push_str(&serde_json::to_string(task)?);
+            lines.push('\n');
+        }
+        std::fs::write(out, lines).map_err(|e| anyhow::anyhow!("writing {out}: {e}"))?;
+        println!("wrote {} wording task(s) to {out}", tasks.len());
+    }
+    if let Some(path) = answers_in {
+        let raw = std::fs::read_to_string(path).map_err(|e| anyhow::anyhow!("reading {path}: {e}"))?;
+        let mut answers = Vec::new();
+        for (n, line) in raw.lines().enumerate().filter(|(_, l)| !l.trim().is_empty()) {
+            answers.push(
+                serde_json::from_str::<needs::Answer>(line)
+                    .map_err(|e| anyhow::anyhow!("{path}:{}: {e}", n + 1))?,
+            );
+        }
+        let score = needs::score(&tasks, &answers, 0.6);
+        for (id, picked, expected, confidence) in &score.misroutes {
+            eprintln!(
+                "MISROUTE: {id}: picked {picked:?}{}, the need is met by {expected:?}",
+                confidence.map(|c| format!(" ({c:.2})")).unwrap_or_default()
+            );
+        }
+        for (id, confidence) in &score.hesitant {
+            eprintln!("HESITANT: {id}: right, at {confidence:.2}");
+        }
+        for id in &score.unanswered {
+            eprintln!("UNANSWERED: {id}");
+        }
+        println!(
+            "wording: {}/{} routed right ({:.0}%)",
+            score.correct,
+            score.total,
+            score.accuracy() * 100.0
+        );
+        if score.accuracy() < min_accuracy {
+            eprintln!("FAIL: below --min-accuracy {min_accuracy}");
+            std::process::exit(1);
+        }
+    }
+    if failed > 0 {
+        eprintln!("FAIL: {failed} unmet business need finding(s)");
+        std::process::exit(1);
     }
     Ok(())
 }

src/chain.rs

@@ -20,6 +20,11 @@ pub const CHAIN_BUCKET: &str = "portal_chains";
 #[derive(serde::Serialize, serde::Deserialize)]
 pub struct ChainNode {
     pub question_id: String,
+    /// Which alternative was answered - what decides where the visitor
+    /// was sent next, and so which followup the chain has earned. Nodes
+    /// indexed before this field existed carry `None`.
+    #[serde(default)]
+    pub alternative: Option<String>,
     pub timestamp_ms: i64,
 }
 
@@ -30,6 +35,7 @@ pub async fn record_node(
     js: &async_nats::jetstream::Context,
     chain_hash: &str,
     question_id: &str,
+    alternative: &str,
     timestamp_ms: i64,
 ) -> anyhow::Result<()> {
     let store = match js.get_key_value(CHAIN_BUCKET).await {
@@ -44,6 +50,7 @@ pub async fn record_node(
     };
     let node = ChainNode {
         question_id: question_id.to_string(),
+        alternative: Some(alternative.to_string()),
         timestamp_ms,
     };
     store.put(chain_hash, serde_json::to_vec(&node)?.into()).await?;

src/content/gitea.rs

@@ -0,0 +1,252 @@
+//! Loading a content repo from Gitea, and the NATS-signalled reload
+//! that hot-swaps it (last-good content is kept on any failure). Every
+//! fetch goes through `crate::http`: bounded in time and size.
+
+use super::*;
+
+/// Fetches `needs.yaml` from the content repo root - the business's
+/// needs spec `question_lint` checks the pages against (see
+/// `crate::needs`). Optional: a fetch failure means the repo declares
+/// none. The runtime never reads it.
+#[cfg(feature = "ssr")]
+pub async fn load_needs_from_gitea(repo_url: &str, branch: &str) -> anyhow::Result<Option<String>> {
+    let (owner, repo) = parse_owner_repo(repo_url)?;
+    let api_base = gitea_api_base(repo_url)?;
+    Ok(fetch_gitea_file(&api_base, &owner, &repo, branch, "needs.yaml")
+        .await
+        .ok())
+}
+
+/// Fetches and parses `site.yaml` from the content repo root. A fetch
+/// failure (typically 404 - the file is optional) yields the default
+/// config; a file that exists but doesn't parse or validate is a real
+/// error, surfaced at boot rather than papered over.
+#[cfg(feature = "ssr")]
+pub async fn load_site_from_gitea(repo_url: &str, branch: &str) -> anyhow::Result<SiteConfig> {
+    let (owner, repo) = parse_owner_repo(repo_url)?;
+    let api_base = gitea_api_base(repo_url)?;
+    let raw = match fetch_gitea_file(&api_base, &owner, &repo, branch, "site.yaml").await {
+        Ok(raw) => raw,
+        Err(e) => {
+            tracing::info!("no site.yaml in content repo ({e}), using default branding");
+            return Ok(SiteConfig::default());
+        }
+    };
+    let site: SiteConfig =
+        serde_yaml::from_str(&raw).map_err(|e| anyhow::anyhow!("parsing site.yaml: {e}"))?;
+    site.validate()?;
+    Ok(site)
+}
+
+/// Extracts `scheme://host` from a repo's normal browser URL - the
+/// Gitea API base every helper in this module builds requests against.
+#[cfg(feature = "ssr")]
+/// `{gitea}/api/v1/repos/{owner}/{repo}/raw` - the base
+/// `site_asset_handler` proxies content-shipped files from.
+#[cfg(feature = "ssr")]
+pub fn gitea_raw_base(repo_url: &str) -> anyhow::Result<String> {
+    let (owner, repo) = parse_owner_repo(repo_url)?;
+    Ok(format!("{}/api/v1/repos/{owner}/{repo}/raw", gitea_api_base(repo_url)?))
+}
+
+#[cfg(feature = "ssr")]
+pub fn gitea_api_base(repo_url: &str) -> anyhow::Result<String> {
+    let parsed = url::Url::parse(repo_url)
+        .map_err(|e| anyhow::anyhow!("parsing repo url {repo_url}: {e}"))?;
+    Ok(format!(
+        "{}://{}",
+        parsed.scheme(),
+        parsed
+            .host_str()
+            .ok_or_else(|| anyhow::anyhow!("no host in repo url {repo_url}"))?
+    ))
+}
+
+/// Splits a repo's normal browser URL into `(owner, repo)` - shared by
+/// every loader in this module that needs to build a Gitea contents API
+/// URL (`load_questions_from_gitea`, `load_aggregates_from_gitea`).
+#[cfg(feature = "ssr")]
+pub(crate) fn parse_owner_repo(repo_url: &str) -> anyhow::Result<(String, String)> {
+    let parsed = url::Url::parse(repo_url)
+        .map_err(|e| anyhow::anyhow!("parsing content repo url {repo_url}: {e}"))?;
+    let mut segments = parsed
+        .path_segments()
+        .ok_or_else(|| anyhow::anyhow!("no path in content repo url {repo_url}"))?;
+    let owner = segments
+        .next()
+        .filter(|s| !s.is_empty())
+        .ok_or_else(|| anyhow::anyhow!("missing owner in content repo url {repo_url}"))?
+        .to_string();
+    let repo = segments
+        .next()
+        .filter(|s| !s.is_empty())
+        .ok_or_else(|| anyhow::anyhow!("missing repo name in content repo url {repo_url}"))?
+        .to_string();
+    Ok((owner, repo))
+}
+
+/// Fetches one file from a Gitea repo's contents API and returns its raw
+/// text - the single-file counterpart to `load_questions_from_gitea`'s
+/// directory-listing loop, used by `load_aggregates_from_gitea` for the
+/// one `aggregates.yaml` file at the repo root.
+#[cfg(feature = "ssr")]
+pub(crate) async fn fetch_gitea_file(
+    api_base: &str,
+    owner: &str,
+    repo: &str,
+    branch: &str,
+    path: &str,
+) -> anyhow::Result<String> {
+    let meta_url = format!("{api_base}/api/v1/repos/{owner}/{repo}/contents/{path}?ref={branch}");
+    let meta_text = crate::http::get_text(&meta_url, crate::http::GITEA_CAP)
+        .await
+        .map_err(|e| anyhow::anyhow!("fetching {meta_url}: {e}"))?;
+    let meta: serde_json::Value = serde_json::from_str(&meta_text)
+        .map_err(|e| anyhow::anyhow!("parsing contents response from {meta_url}: {e}"))?;
+    let download_url = meta
+        .get("download_url")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| anyhow::anyhow!("no download_url for {path}"))?;
+    crate::http::get_text(download_url, crate::http::GITEA_CAP)
+        .await
+        .map_err(|e| anyhow::anyhow!("fetching {path}: {e}"))
+}
+
+/// Fetches and parses `aggregates.yaml` from the repo root (sibling to
+/// the pages `subdir`, so the "every yaml under subdir is a page"
+/// convention needs no exclusion). A malformed file fails here, before
+/// ever reaching `AppState`.
+#[cfg(feature = "ssr")]
+pub async fn load_aggregates_from_gitea(
+    repo_url: &str,
+    branch: &str,
+) -> anyhow::Result<std::collections::HashMap<String, crate::aggregates::AggregateSchema>> {
+    let (owner, repo) = parse_owner_repo(repo_url)?;
+    let api_base = gitea_api_base(repo_url)?;
+    let raw = fetch_gitea_file(&api_base, &owner, &repo, branch, "aggregates.yaml").await?;
+    crate::aggregates::parse_aggregates_yaml(&raw)
+}
+
+#[cfg(feature = "ssr")]
+pub async fn load_questions_from_gitea(
+    repo_url: &str,
+    branch: &str,
+    subdir: &str,
+) -> anyhow::Result<std::collections::HashMap<String, Question>> {
+    let (owner, repo) = parse_owner_repo(repo_url)?;
+    let api_base = gitea_api_base(repo_url)?;
+
+    // One recursive git-trees call for the whole repo instead of a
+    // contents listing per directory - the tree IS the router now, so
+    // nested files matter.
+    let tree_url =
+        format!("{api_base}/api/v1/repos/{owner}/{repo}/git/trees/{branch}?recursive=true");
+    let listing = crate::http::get_text(&tree_url, crate::http::GITEA_CAP)
+        .await
+        .map_err(|e| anyhow::anyhow!("listing {tree_url}: {e}"))?;
+    let tree: serde_json::Value = serde_json::from_str(&listing)
+        .map_err(|e| anyhow::anyhow!("parsing tree from {tree_url}: {e}"))?;
+    if tree.get("truncated").and_then(|v| v.as_bool()) == Some(true) {
+        anyhow::bail!("git tree listing for {owner}/{repo} was truncated - repo too large");
+    }
+    let prefix = format!("{subdir}/");
+
+    let mut files = Vec::new();
+    for entry in tree
+        .get("tree")
+        .and_then(|v| v.as_array())
+        .map(|v| v.as_slice())
+        .unwrap_or_default()
+    {
+        let path = entry.get("path").and_then(|v| v.as_str()).unwrap_or("");
+        if entry.get("type").and_then(|v| v.as_str()) != Some("blob")
+            || !path.starts_with(&prefix)
+            || !path.ends_with(".yaml")
+        {
+            continue;
+        }
+        // Brackets (dynamic pages like `[record].yaml`) must be
+        // percent-encoded in the raw URL's path.
+        let encoded = path.replace('[', "%5B").replace(']', "%5D");
+        let raw_url = format!("{api_base}/api/v1/repos/{owner}/{repo}/raw/{encoded}?ref={branch}");
+        let raw = crate::http::get_text(&raw_url, crate::http::GITEA_CAP)
+            .await
+            .map_err(|e| anyhow::anyhow!("fetching {path}: {e}"))?;
+        files.push((path[prefix.len()..].to_string(), raw));
+    }
+    build_questions(&files)
+}
+
+/// Published by the content repo's own CI (after it lints a push) to
+/// tell every running instance to pick up the change - a plain fire
+/// and forget NATS publish, no payload, matching `events.rs`'s
+/// `ANSWERS_SUBJECT` pattern.
+#[cfg(feature = "ssr")]
+pub const CONTENT_RELOAD_SUBJECT: &str = "portal.content.reload";
+
+/// Runs for the life of the process: re-fetches `repo_url`/`branch` and
+/// atomically swaps both `questions` and `aggregates` on every
+/// `CONTENT_RELOAD_SUBJECT` message - the two only ever swap together,
+/// after both have loaded and validated successfully, so a reader never
+/// sees pages that reference a half-updated state graph. A fetch/parse
+/// failure logs and keeps serving the last-good content rather than
+/// clearing it - a bad push to the content repo (which should already
+/// have been caught by its own lint step) doesn't take the site down.
+#[cfg(feature = "ssr")]
+pub async fn watch_for_reload(
+    nats: async_nats::Client,
+    repo_url: String,
+    branch: String,
+    subdir: String,
+    questions: std::sync::Arc<arc_swap::ArcSwap<std::collections::HashMap<String, Question>>>,
+    aggregates: std::sync::Arc<
+        arc_swap::ArcSwap<std::collections::HashMap<String, crate::aggregates::AggregateSchema>>,
+    >,
+    site: std::sync::Arc<arc_swap::ArcSwap<SiteConfig>>,
+) {
+    let mut sub = match nats.subscribe(CONTENT_RELOAD_SUBJECT).await {
+        Ok(sub) => sub,
+        Err(e) => {
+            tracing::error!(error = %e, "failed to subscribe to content reload subject");
+            return;
+        }
+    };
+    use futures::StreamExt;
+    while sub.next().await.is_some() {
+        let loaded_aggregates = match load_aggregates_from_gitea(&repo_url, &branch).await {
+            Ok(loaded) => with_builtin_aggregates(loaded),
+            Err(e) => {
+                tracing::error!(error = %e, "aggregates.yaml reload failed, keeping last-good content");
+                continue;
+            }
+        };
+        // Branding swaps with the same all-or-nothing rule: a
+        // present-but-broken site.yaml keeps last-good everything
+        // (load_site distinguishes "absent" - a normal default - from
+        // "present but invalid").
+        let loaded_site = match load_site_from_gitea(&repo_url, &branch).await {
+            Ok(loaded) => loaded,
+            Err(e) => {
+                tracing::error!(error = %e, "site.yaml reload failed, keeping last-good content");
+                continue;
+            }
+        };
+        match load_questions_from_gitea(&repo_url, &branch, &subdir).await {
+            Ok(loaded) => {
+                if let Err(e) = validate_questions(&loaded, &loaded_aggregates) {
+                    tracing::error!(error = %e, "content reload failed validation, keeping last-good content");
+                    continue;
+                }
+                let count = loaded.len();
+                questions.store(std::sync::Arc::new(loaded));
+                aggregates.store(std::sync::Arc::new(loaded_aggregates));
+                site.store(std::sync::Arc::new(loaded_site));
+                tracing::info!(count, "reloaded content");
+            }
+            Err(e) => {
+                tracing::error!(error = %e, "content reload failed, keeping last-good content");
+            }
+        }
+    }
+}
+

src/content/handlers.rs

@@ -0,0 +1,193 @@
+//! The Axum routes that expose content and buckets outside the Leptos
+//! app: content-shipped assets proxied same-origin, repo info for the
+//! showcase, and the automation read API over KV buckets.
+
+use super::*;
+
+/// A repo-relative asset path portal is willing to proxy from the
+/// content repo: plain segments only - no traversal, no leading slash,
+/// no scheme - so `/site/<path>` can only ever reach the content repo.
+pub fn is_safe_site_path(path: &str) -> bool {
+    !path.is_empty()
+        && !path.starts_with('/')
+        && path.split('/').all(|seg| {
+            !seg.is_empty()
+                && seg != ".."
+                && seg
+                    .chars()
+                    .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_' || c == '.')
+        })
+}
+
+/// A public Gitea repo's basic info - what `resolve_gitea_repo` returns
+/// for the prosekit editor's repo-embed node to render as a static
+/// card, baked in once at embed time rather than re-fetched by every
+/// reader (an emailed newsletter can't run JS to do that anyway).
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct GiteaRepoInfo {
+    pub owner: String,
+    pub repo: String,
+    pub description: String,
+    pub url: String,
+}
+
+#[derive(Deserialize)]
+#[cfg(feature = "ssr")]
+pub struct GiteaRepoQuery {
+    pub owner: String,
+    pub repo: String,
+}
+
+/// `GET /site/{*path}` - serves a file from the content repo's default
+/// branch same-origin, so content-shipped assets (the hero module,
+/// its stylesheet) are importable by the page: Gitea's raw endpoint
+/// sends no CORS headers, and an ES module import across origins is
+/// refused without them. Path is validated to plain segments
+/// (`is_safe_site_path`), the response revalidates like /pkg
+/// (Cache-Control: no-cache) so a content push shows up on reload.
+#[cfg(feature = "ssr")]
+pub async fn site_asset_handler(
+    axum::extract::State(state): axum::extract::State<crate::server::AppState>,
+    axum::extract::Path(path): axum::extract::Path<String>,
+) -> axum::response::Response {
+    use axum::http::{header, StatusCode};
+    use axum::response::IntoResponse;
+
+    if !is_safe_site_path(&path) {
+        return (StatusCode::BAD_REQUEST, "invalid asset path").into_response();
+    }
+    let url = format!("{}/{path}?ref={}", state.content_raw_base, state.content_branch);
+    let resp = match crate::http::client().get(&url).send().await.and_then(|r| r.error_for_status()) {
+        Ok(r) => r,
+        Err(e) => {
+            tracing::warn!("site asset {path}: {e}");
+            return (StatusCode::NOT_FOUND, "no such site asset").into_response();
+        }
+    };
+    let bytes = match crate::http::bytes(resp, crate::http::ASSET_CAP).await {
+        Ok(b) => axum::body::Bytes::from(b),
+        Err(e) => return (StatusCode::BAD_GATEWAY, e.to_string()).into_response(),
+    };
+    let mime = match path.rsplit('.').next() {
+        Some("js") | Some("mjs") => "text/javascript; charset=utf-8",
+        Some("css") => "text/css; charset=utf-8",
+        Some("svg") => "image/svg+xml",
+        Some("json") => "application/json",
+        Some("png") => "image/png",
+        Some("webp") => "image/webp",
+        Some("avif") => "image/avif",
+        Some("ico") => "image/x-icon",
+        Some("woff2") => "font/woff2",
+        _ => "application/octet-stream",
+    };
+    (
+        [(header::CONTENT_TYPE, mime), (header::CACHE_CONTROL, "no-cache")],
+        bytes,
+    )
+        .into_response()
+}
+
+/// Looks up `owner/repo` on the same Gitea instance content is loaded
+/// from (`AppState.gitea_base`) - a raw Axum handler (mounted at
+/// `/gitea-repo` in `main.rs`), not a Leptos server fn, since the
+/// caller here is the prosekit editor's own paste-to-embed rule (see
+/// `prosekit-editor.js`) doing a plain `fetch`, the same reason
+/// `/upload` (`src/upload.rs`) is a raw handler rather than a `#[server]`
+/// fn. Keeping this server-resolved (rather than having the browser
+/// call Gitea's API directly) is consistent with every other backing
+/// store in this app, and sidesteps needing a CORS allowance on Gitea's
+/// side just for this. No auth, same as content loading - resolves
+/// only what's already public.
+#[cfg(feature = "ssr")]
+pub async fn gitea_repo_handler(
+    axum::extract::State(state): axum::extract::State<crate::server::AppState>,
+    axum::extract::Query(query): axum::extract::Query<GiteaRepoQuery>,
+) -> Result<axum::Json<GiteaRepoInfo>, (axum::http::StatusCode, String)> {
+    let is_safe_segment = |s: &str| {
+        !s.is_empty()
+            && s.chars()
+                .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_' || c == '.')
+    };
+    if !is_safe_segment(&query.owner) || !is_safe_segment(&query.repo) {
+        return Err((axum::http::StatusCode::BAD_REQUEST, "invalid owner/repo".to_string()));
+    }
+    let GiteaRepoQuery { owner, repo } = query;
+
+    let api_url = format!("{}/api/v1/repos/{owner}/{repo}", state.gitea_base);
+    let body = crate::http::get_text(&api_url, crate::http::GITEA_CAP)
+        .await
+        .map_err(|e| (axum::http::StatusCode::BAD_GATEWAY, format!("fetching {api_url}: {e}")))?;
+    let json: serde_json::Value = serde_json::from_str(&body).map_err(|e| {
+        (
+            axum::http::StatusCode::BAD_GATEWAY,
+            format!("parsing repo info from {api_url}: {e}"),
+        )
+    })?;
+
+    Ok(axum::Json(GiteaRepoInfo {
+        owner: owner.clone(),
+        repo: repo.clone(),
+        description: json
+            .get("description")
+            .and_then(|v| v.as_str())
+            .unwrap_or("")
+            .to_string(),
+        url: json
+            .get("html_url")
+            .and_then(|v| v.as_str())
+            .map(|s| s.to_string())
+            .unwrap_or_else(|| format!("{}/{owner}/{repo}", state.gitea_base)),
+    }))
+}
+
+/// Lists every entry in a NATS KV bucket as JSON - a raw Axum handler
+/// (mounted at `/automation/kv/{bucket}` in `main.rs`), for backing
+/// automations (e.g. an n8n workflow reading `portal_subscribers` to
+/// send a newsletter) that aren't a signed-in browser session and so
+/// can't go through `resource::get_resource`'s Kanidm-group check.
+/// Gated by a single shared bearer token (`AUTOMATION_READ_TOKEN`) -
+/// deliberately not per-caller/per-bucket scoped, since every current
+/// caller is a trusted internal automation, not a third party. Read
+/// only, matching `get_resource`'s own "reads can be public/shared,
+/// mutations always need real identity" split - nothing here writes.
+#[cfg(feature = "ssr")]
+pub async fn automation_kv_handler(
+    axum::extract::State(state): axum::extract::State<crate::server::AppState>,
+    axum::extract::Path(bucket): axum::extract::Path<String>,
+    headers: axum::http::HeaderMap,
+) -> Result<axum::Json<serde_json::Value>, (axum::http::StatusCode, String)> {
+    let expected = std::env::var("AUTOMATION_READ_TOKEN").unwrap_or_default();
+    let presented = headers
+        .get(axum::http::header::AUTHORIZATION)
+        .and_then(|v| v.to_str().ok())
+        .and_then(|v| v.strip_prefix("Bearer "))
+        .unwrap_or("");
+    if expected.is_empty() || presented != expected {
+        return Err((axum::http::StatusCode::UNAUTHORIZED, "unauthorized".to_string()));
+    }
+
+    let store = state
+        .jetstream
+        .get_key_value(&bucket)
+        .await
+        .map_err(|e| (axum::http::StatusCode::BAD_GATEWAY, format!("bucket unavailable: {e}")))?;
+
+    use futures::TryStreamExt;
+    let keys: Vec<String> = store
+        .keys()
+        .await
+        .map_err(|e| (axum::http::StatusCode::BAD_GATEWAY, e.to_string()))?
+        .try_collect()
+        .await
+        .map_err(|e| (axum::http::StatusCode::BAD_GATEWAY, e.to_string()))?;
+    let mut items = Vec::new();
+    for key in keys {
+        if let Ok(Some(bytes)) = store.get(&key).await {
+            if let Ok(value) = serde_json::from_slice::<serde_json::Value>(&bytes) {
+                items.push(value);
+            }
+        }
+    }
+    Ok(axum::Json(serde_json::Value::Array(items)))
+}
+

src/content/markdown.rs

@@ -0,0 +1,120 @@
+//! Inline markdown for descriptions: links on a short allow-list of
+//! schemes, images gated and framed, with layout hints read from the
+//! image title. Never raw HTML.
+
+/// Descriptions are inline markdown: `[text](https://…)` links,
+/// `*emphasis*`, `**strong**`, `` `code` ``. Block structure is
+/// flattened (a description is one paragraph) and raw HTML in the
+/// source is dropped, so content can link out without being able to
+/// inject markup. Link targets are limited to https, mailto and
+/// site-relative paths; anything else renders as plain text.
+pub fn render_inline_markdown(text: &str) -> String {
+    use pulldown_cmark::{html, Event, Options, Parser, Tag, TagEnd};
+    let parser = Parser::new_ext(text, Options::empty());
+    let mut in_link = 0usize;
+    let mut in_dropped_image = 0usize;
+    let filtered = parser.filter_map(|event| match event {
+        Event::Html(_) | Event::InlineHtml(_) => None,
+        Event::Start(Tag::Paragraph) | Event::End(TagEnd::Paragraph) => None,
+        Event::SoftBreak => Some(Event::Text(" ".into())),
+        Event::Start(Tag::Link { dest_url, .. })
+            if !(dest_url.starts_with("https://")
+                || dest_url.starts_with("mailto:")
+                || dest_url.starts_with("tel:")
+                || dest_url.starts_with('/')) =>
+        {
+            in_link += 1;
+            None
+        }
+        Event::End(TagEnd::Link) if in_link > 0 => {
+            in_link -= 1;
+            None
+        }
+        // Images take the same gate as links: https or same-origin
+        // only - no data:, no plain http. Unlike a dropped link (whose
+        // label is real text worth keeping), a dropped image's alt
+        // text is a caption for something that isn't there - swallow it.
+        Event::Start(Tag::Image { dest_url, .. })
+            if !(dest_url.starts_with("https://") || dest_url.starts_with('/')) =>
+        {
+            in_dropped_image += 1;
+            None
+        }
+        Event::End(TagEnd::Image) if in_dropped_image > 0 => {
+            in_dropped_image -= 1;
+            None
+        }
+        Event::Text(_) if in_dropped_image > 0 => None,
+        other => Some(other),
+    });
+    let mut out = String::new();
+    html::push_html(&mut out, filtered);
+    apply_image_hints(out.trim())
+}
+
+/// Translate a markdown image's title (`![alt](url "right 9rem")`)
+/// into layout: `left`/`right` float via a class, a bare number
+/// (optionally with `rem`) into a validated `max-width`. Unknown
+/// tokens are ignored; the title attribute is dropped either way.
+/// Only touches `<img>` tags in our own render output, and only ever
+/// emits a numeric max-width - no arbitrary CSS reaches the page.
+pub(crate) fn apply_image_hints(html: &str) -> String {
+    let mut out = String::new();
+    let mut rest = html;
+    while let Some(pos) = rest.find("<img ") {
+        out.push_str(&rest[..pos]);
+        let after = &rest[pos..];
+        let end = after.find('>').map(|e| e + 1).unwrap_or(after.len());
+        out.push_str(&rewrite_img_tag(&after[..end]));
+        rest = &after[end..];
+    }
+    out.push_str(rest);
+    out
+}
+
+pub(crate) fn rewrite_img_tag(tag: &str) -> String {
+    // Pull the title value, if any.
+    let title = tag
+        .find("title=\"")
+        .map(|i| &tag[i + 7..])
+        .and_then(|r| r.find('"').map(|e| &r[..e]))
+        .unwrap_or("");
+
+    let mut class = String::new();
+    let mut max_rem: Option<f32> = None;
+    for tok in title.split_whitespace() {
+        match tok {
+            "left" => class = "md-float-left".into(),
+            "right" => class = "md-float-right".into(),
+            other => {
+                if let Ok(n) = other.trim_end_matches("rem").parse::<f32>() {
+                    if n > 0.0 && n <= 60.0 {
+                        max_rem = Some(n);
+                    }
+                }
+            }
+        }
+    }
+
+    // Strip the title attribute from the tag.
+    let mut cleaned = tag.to_string();
+    if let Some(i) = cleaned.find(" title=\"") {
+        if let Some(e) = cleaned[i + 8..].find('"') {
+            cleaned.replace_range(i..i + 8 + e + 1, "");
+        }
+    }
+
+    // Inject class/style right after `<img`.
+    let mut attrs = String::new();
+    if !class.is_empty() {
+        attrs.push_str(&format!(" class=\"{class}\""));
+    }
+    if let Some(n) = max_rem {
+        attrs.push_str(&format!(" style=\"max-width:{n}rem\""));
+    }
+    if attrs.is_empty() {
+        return cleaned;
+    }
+    cleaned.replacen("<img", &format!("<img{attrs}"), 1)
+}
+

src/content/validate.rs

@@ -0,0 +1,290 @@
+//! What a content repo must satisfy before it serves: every action
+//! lands on a page, every transition is one the state machine allows,
+//! every recorded bucket is read back somewhere, and the built-in
+//! aggregates the runtime owns are always present.
+
+#[allow(unused_imports)] // the browser build sees fewer items
+use super::*;
+
+/// A relay must be a ws:// or wss:// URL - shared between site.yaml's
+/// hero and `Requirement.relay` validation.
+#[cfg(feature = "ssr")]
+pub fn validate_relay_url(relay: &str) -> anyhow::Result<()> {
+    let parsed = url::Url::parse(relay)
+        .map_err(|e| anyhow::anyhow!("relay {relay:?} is not a valid URL: {e}"))?;
+    if !matches!(parsed.scheme(), "ws" | "wss") {
+        anyhow::bail!("relay {relay:?} must use the ws:// or wss:// scheme");
+    }
+    Ok(())
+}
+
+/// Validates every declared transition target (`SelfTransition.to`,
+/// `ResourceSpec.transitions[].to`) against `aggregates` - the real
+/// state graph loaded from `aggregates.yaml` - for every bucket that
+/// has one declared. A bucket with no entry in `aggregates` is left
+/// alone entirely (no validation applied): not every bucket needs to
+/// be event-sourced to keep working. Called on every content
+/// load/reload (`watch_for_reload`, `main.rs`'s boot path) and by the
+/// standalone `question-lint` binary, so a YAML typo becomes a caught,
+/// logged rejection instead of a silently-accepted, later-broken
+/// string.
+/// Bucket the runtime keeps for announced pages (`Question.event`):
+/// one record per event question, `announced` while the window is
+/// open, `awaiting_summary` once it closes - the "post what happened"
+/// task a desk reading this bucket picks up - and `summarized` when an
+/// owner marks it done. Declared here, not in content, because the
+/// runtime's sweeper (`announce.rs`) is what moves the records.
+pub const EVENTS_BUCKET: &str = "portal_events";
+
+#[cfg(feature = "ssr")]
+const BUILTIN_AGGREGATES_YAML: &str = "\
+aggregates:
+  - bucket: portal_events
+    initial: announced
+    states:
+      announced: { event: announced }
+      awaiting_summary: { event: ended }
+      summarized: { event: summarized }
+    transitions:
+      announced: [awaiting_summary, summarized]
+      awaiting_summary: [summarized]
+";
+
+/// Adds the runtime's own state graphs to a content repo's. Content
+/// wins if it declares the same bucket (say, to add states).
+#[cfg(feature = "ssr")]
+pub fn with_builtin_aggregates(
+    mut aggregates: std::collections::HashMap<String, crate::aggregates::AggregateSchema>,
+) -> std::collections::HashMap<String, crate::aggregates::AggregateSchema> {
+    let builtin = crate::aggregates::parse_aggregates_yaml(BUILTIN_AGGREGATES_YAML)
+        .expect("builtin aggregates yaml is valid");
+    for (bucket, schema) in builtin {
+        aggregates.entry(bucket).or_insert(schema);
+    }
+    aggregates
+}
+
+/// True when some kv resource in the content reads `bucket` - the
+/// attended-bucket check, exposed so the lint can warn about the
+/// runtime's own `portal_events` (a warning, not a failure: a repo
+/// with no event pages has nothing to attend).
+#[cfg(feature = "ssr")]
+pub fn bucket_is_read(questions: &std::collections::HashMap<String, Question>, bucket: &str) -> bool {
+    questions.values().any(|q| {
+        q.alternatives.iter().any(|a| {
+            a.features
+                .iter()
+                .any(|f| f.resource.as_ref().and_then(|r| r.bucket()).is_some_and(|b| b == bucket))
+        })
+    })
+}
+
+#[cfg(feature = "ssr")]
+pub fn validate_questions(
+    questions: &std::collections::HashMap<String, Question>,
+    aggregates: &std::collections::HashMap<String, crate::aggregates::AggregateSchema>,
+) -> anyhow::Result<()> {
+    for question in questions.values() {
+        if let Some(event) = &question.event {
+            if question.is_dynamic() {
+                anyhow::bail!("question {:?}: a dynamic page can't carry an event", question.id);
+            }
+            if let Err(e) = event.window_ms() {
+                anyhow::bail!("question {:?}: event: {e}", question.id);
+            }
+        }
+        if let Some(target) = &question.requires_chain {
+            if !questions.contains_key(target) {
+                anyhow::bail!(
+                    "question {:?}: requires_chain {:?} does not match any declared question id",
+                    question.id,
+                    target
+                );
+            }
+        }
+        for alternative in &question.alternatives {
+            // A dangling action is a literal dead end: the submit
+            // button navigates to "Nothing here".
+            if let Some(action) = &alternative.action {
+                if action.contains('{') {
+                    // Placeholders are filled at submit time; the
+                    // shape must land on a dynamic page once filled.
+                    let probe = template_action(action, &serde_json::json!({}));
+                    let filled = {
+                        let mut a = action.clone();
+                        while let (Some(i), Some(j)) = (a.find('{'), a.find('}')) {
+                            a.replace_range(i..=j, "x");
+                        }
+                        a
+                    };
+                    let _ = probe;
+                    // Match the pattern itself: resolve_question would
+                    // hand back a clone whose id is already concrete.
+                    let lands = questions
+                        .values()
+                        .any(|q| q.is_dynamic() && path_matches(&q.id, &filled).is_some());
+                    if lands {
+                        continue;
+                    }
+                    anyhow::bail!(
+                        "question {:?} alternative {:?}: templated action {:?} must land on a dynamic page ([name].yaml)",
+                        question.id, alternative.name, action
+                    );
+                }
+                match questions.get(action) {
+                    None => anyhow::bail!(
+                        "question {:?} alternative {:?}: action {:?} does not match any declared question id",
+                        question.id, alternative.name, action
+                    ),
+                    // A dynamic page needs a concrete segment value to
+                    // be a URL - a submit button can't supply one.
+                    Some(target) if target.is_dynamic() => anyhow::bail!(
+                        "question {:?} alternative {:?}: action {:?} targets a dynamic page - actions must name a concrete question",
+                        question.id, alternative.name, action
+                    ),
+                    Some(_) => {}
+                }
+            }
+            if let Some(st) = &alternative.self_transition {
+                if let Some(schema) = aggregates.get(&st.bucket) {
+                    if !schema.has_state(&st.to) {
+                        anyhow::bail!(
+                            "question {:?} alternative {:?}: self_transition.to {:?} is not a declared state for bucket {:?}",
+                            question.id, alternative.name, st.to, st.bucket
+                        );
+                    }
+                }
+            }
+            // Bind targets resolve across the whole alternative, same
+            // scope as the signal maps the renderer builds.
+            let sibling_names: std::collections::HashSet<&str> = alternative
+                .features
+                .iter()
+                .flat_map(|f| f.requirements.iter())
+                .map(|r| r.name.as_str())
+                .collect();
+            for feature in &alternative.features {
+                for requirement in &feature.requirements {
+                    if requirement.kind == "select"
+                        && requirement.resource.is_none()
+                        && requirement.options.is_empty()
+                    {
+                        anyhow::bail!(
+                            "question {:?} alternative {:?} feature {:?}: requirement {:?} is type: select but declares neither a resource nor inline options",
+                            question.id, alternative.name, feature.name, requirement.name
+                        );
+                    }
+                    if let Some(relay) = &requirement.relay {
+                        if requirement.kind != "gesture" && requirement.kind != "voice" {
+                            anyhow::bail!(
+                                "question {:?} alternative {:?} feature {:?}: requirement {:?} declares relay but is type {:?} - relay only makes sense on type: gesture or voice",
+                                question.id, alternative.name, feature.name, requirement.name, requirement.kind
+                            );
+                        }
+                        validate_relay_url(relay).map_err(|e| anyhow::anyhow!(
+                            "question {:?} alternative {:?} feature {:?}: requirement {:?}: {e}",
+                            question.id, alternative.name, feature.name, requirement.name
+                        ))?;
+                    }
+                    if requirement.kind == "gesture"
+                        && (requirement.resource.is_some() || requirement.bind.is_some())
+                    {
+                        anyhow::bail!(
+                            "question {:?} alternative {:?} feature {:?}: requirement {:?} is type: gesture - it draws its value, it can't also load one from a resource or bind",
+                            question.id, alternative.name, feature.name, requirement.name
+                        );
+                    }
+                    if let Some(bind) = &requirement.bind {
+                        if bind.field == requirement.name
+                            || !sibling_names.contains(bind.field.as_str())
+                        {
+                            anyhow::bail!(
+                                "question {:?} alternative {:?} feature {:?}: requirement {:?} binds to {:?}, which is not another requirement on this alternative",
+                                question.id, alternative.name, feature.name, requirement.name, bind.field
+                            );
+                        }
+                    }
+                }
+                let Some(resource) = &feature.resource else {
+                    continue;
+                };
+                let Some(bucket) = resource.bucket() else {
+                    continue;
+                };
+                let Some(schema) = aggregates.get(bucket) else {
+                    continue;
+                };
+                for transition in &resource.transitions {
+                    if !schema.has_state(&transition.from) {
+                        anyhow::bail!(
+                            "question {:?} alternative {:?} feature {:?}: transition.from {:?} is not a declared state for bucket {:?}",
+                            question.id, alternative.name, feature.name, transition.from, bucket
+                        );
+                    }
+                    if !schema.has_state(&transition.to) {
+                        anyhow::bail!(
+                            "question {:?} alternative {:?} feature {:?}: transition.to {:?} is not a declared state for bucket {:?}",
+                            question.id, alternative.name, feature.name, transition.to, bucket
+                        );
+                    }
+                    if !schema.allowed(&transition.from).iter().any(|s| s == &transition.to) {
+                        anyhow::bail!(
+                            "question {:?} alternative {:?} feature {:?}: transition {:?} -> {:?} is not a declared edge for bucket {:?}",
+                            question.id, alternative.name, feature.name, transition.from, transition.to, bucket
+                        );
+                    }
+                }
+            }
+        }
+    }
+
+    // Attended buckets: no publicly collected answer may land somewhere
+    // nothing reads. Every `record_as` bucket must either be read back
+    // by some Kv resource in this same content repo (a desk or listing)
+    // or carry an explicit `attended_by:` annotation in aggregates.yaml
+    // naming the automation that consumes it. This is a contract, not a
+    // convention, because convention already failed once: a question
+    // was dropped and its bucket - answers included - silently fell out
+    // of every reader's view.
+    let mut read_buckets = std::collections::HashSet::new();
+    let note_resource = |spec: &ResourceSpec, set: &mut std::collections::HashSet<String>| {
+        if let ResourceSource::Kv { bucket } = &spec.source {
+            set.insert(bucket.clone());
+        }
+    };
+    for question in questions.values() {
+        for alternative in &question.alternatives {
+            for feature in &alternative.features {
+                if let Some(spec) = &feature.resource {
+                    note_resource(spec, &mut read_buckets);
+                }
+                for requirement in &feature.requirements {
+                    if let Some(spec) = &requirement.resource {
+                        note_resource(spec, &mut read_buckets);
+                    }
+                    if let Some(bind) = &requirement.bind {
+                        note_resource(&bind.resource, &mut read_buckets);
+                    }
+                }
+            }
+        }
+    }
+    for question in questions.values() {
+        for alternative in &question.alternatives {
+            if let Some(bucket) = &alternative.record_as {
+                let attended = read_buckets.contains(bucket)
+                    || aggregates
+                        .get(bucket)
+                        .is_some_and(|schema| schema.attended_by.is_some());
+                if !attended {
+                    anyhow::bail!(
+                        "question {:?} alternative {:?}: record_as {bucket:?} is unattended - no page reads that bucket back, and aggregates.yaml declares no attended_by for it. Add a desk/listing resource over it, or annotate the automation that consumes it.",
+                        question.id, alternative.name
+                    );
+                }
+            }
+        }
+    }
+    Ok(())
+}
+

src/http.rs

@@ -0,0 +1,64 @@
+//! The one outbound HTTP client, bounded. Every server-side fetch -
+//! Gitea content at boot and on reload, the raw-asset proxy, the
+//! repo-info endpoint, and the content-declared `url` resource - goes
+//! through here, so a slow or oversized upstream can cost a request at
+//! most `TIMEOUT` and `cap` bytes, never a thread or the heap. Before
+//! this module each call site built its own client with no timeout and
+//! read whole bodies with `.text()`.
+#![cfg(feature = "ssr")]
+
+use std::sync::OnceLock;
+use std::time::Duration;
+
+use openidconnect::reqwest;
+
+/// Whole-request budget: connect, headers, and body.
+pub const TIMEOUT: Duration = Duration::from_secs(20);
+const CONNECT_TIMEOUT: Duration = Duration::from_secs(5);
+
+/// A content-declared URL resource: JSON for one card.
+pub const URL_RESOURCE_CAP: usize = 2 * 1024 * 1024;
+/// A Gitea API reply or one content file (a tree listing, a YAML page).
+pub const GITEA_CAP: usize = 8 * 1024 * 1024;
+/// A content-shipped asset proxied to the browser (an image, a font).
+pub const ASSET_CAP: usize = 32 * 1024 * 1024;
+
+pub fn client() -> &'static reqwest::Client {
+    static CLIENT: OnceLock<reqwest::Client> = OnceLock::new();
+    CLIENT.get_or_init(|| {
+        reqwest::Client::builder()
+            .connect_timeout(CONNECT_TIMEOUT)
+            .timeout(TIMEOUT)
+            .redirect(reqwest::redirect::Policy::limited(5))
+            .user_agent(concat!("portal/", env!("CARGO_PKG_VERSION")))
+            .build()
+            .expect("a client with static options always builds")
+    })
+}
+
+/// Reads a body up to `cap` bytes; one byte more is an error, not a
+/// truncation, so a caller never parses half a document.
+pub async fn bytes(mut response: reqwest::Response, cap: usize) -> anyhow::Result<Vec<u8>> {
+    let hint = response.content_length().unwrap_or(0) as usize;
+    if hint > cap {
+        anyhow::bail!("response of {hint} bytes exceeds the cap of {cap}");
+    }
+    let mut out = Vec::with_capacity(hint.min(cap));
+    while let Some(chunk) = response.chunk().await? {
+        if out.len() + chunk.len() > cap {
+            anyhow::bail!("response exceeds the cap of {cap} bytes");
+        }
+        out.extend_from_slice(&chunk);
+    }
+    Ok(out)
+}
+
+pub async fn text(response: reqwest::Response, cap: usize) -> anyhow::Result<String> {
+    Ok(String::from_utf8(bytes(response, cap).await?)?)
+}
+
+/// `GET url`, status checked, body read under `cap`.
+pub async fn get_text(url: &str, cap: usize) -> anyhow::Result<String> {
+    let response = client().get(url).send().await?.error_for_status()?;
+    text(response, cap).await
+}

src/lib.rs

@@ -13,6 +13,15 @@ pub mod aggregates;
 #[cfg(feature = "ssr")]
 pub mod announce;
 
+#[cfg(feature = "ssr")]
+pub mod needs;
+
+#[cfg(feature = "ssr")]
+pub mod local;
+
+#[cfg(feature = "ssr")]
+pub mod http;
+
 #[cfg(feature = "ssr")]
 pub mod server;
 

src/local.rs

@@ -0,0 +1,100 @@
+//! Loading a content repo from a local checkout - the offline
+//! counterparts to the Gitea loaders in `content`, for tools that lint
+//! or replay a branch that has not been pushed (question_lint,
+//! needs_replay). `dir` is always the pages directory (`questions/`);
+//! `site.yaml`, `aggregates.yaml` and `needs.yaml` sit one level up.
+#![cfg(feature = "ssr")]
+
+use crate::{aggregates, content};
+
+/// The offline counterpart to `content::load_site_from_gitea` -
+/// `site.yaml` lives at the repo root like `aggregates.yaml`, and is
+/// just as optional locally: missing means default branding.
+pub fn load_site_from_dir(dir: &str) -> anyhow::Result<content::SiteConfig> {
+    let site_path = std::path::Path::new(dir)
+        .parent()
+        .unwrap_or_else(|| std::path::Path::new("."))
+        .join("site.yaml");
+    if !site_path.exists() {
+        return Ok(content::SiteConfig::default());
+    }
+    let raw = std::fs::read_to_string(&site_path)
+        .map_err(|e| anyhow::anyhow!("reading {}: {e}", site_path.display()))?;
+    serde_yaml::from_str(&raw).map_err(|e| anyhow::anyhow!("parsing {}: {e}", site_path.display()))
+}
+
+/// The offline counterpart to `content::load_aggregates_from_gitea` -
+/// `aggregates.yaml` lives at the repo root, one level up from the
+/// pages directory `--path` names, so `dir`'s parent is where it's
+/// looked for. Missing entirely is not an error here (unlike
+/// `--repo` mode, where `aggregates.yaml` is required) - a local
+/// checkout being linted may not have one, and every declared
+/// transition still gets checked against whatever *is* found; an
+/// empty map just means nothing is checked.
+pub fn load_aggregates_from_dir(
+    dir: &str,
+) -> anyhow::Result<std::collections::HashMap<String, aggregates::AggregateSchema>> {
+    let aggregates_path = std::path::Path::new(dir)
+        .parent()
+        .unwrap_or_else(|| std::path::Path::new("."))
+        .join("aggregates.yaml");
+    if !aggregates_path.exists() {
+        return Ok(std::collections::HashMap::new());
+    }
+    let raw = std::fs::read_to_string(&aggregates_path)
+        .map_err(|e| anyhow::anyhow!("reading {}: {e}", aggregates_path.display()))?;
+    aggregates::parse_aggregates_yaml(&raw)
+}
+
+/// The offline counterpart to `content::load_questions_from_gitea` -
+/// the same recursive tree walk and `content::build_questions`
+/// pipeline (derived ids, relative refs, sections, followup
+/// inference), just reading a local checkout instead of Gitea's API,
+/// for linting a branch that hasn't been pushed yet.
+pub fn load_from_dir(
+    dir: &str,
+) -> anyhow::Result<std::collections::HashMap<String, content::Question>> {
+    let base = std::path::Path::new(dir);
+    let mut files = Vec::new();
+    collect_yaml(base, base, &mut files)?;
+    content::build_questions(&files)
+}
+
+fn collect_yaml(
+    base: &std::path::Path,
+    dir: &std::path::Path,
+    out: &mut Vec<(String, String)>,
+) -> anyhow::Result<()> {
+    for entry in std::fs::read_dir(dir)? {
+        let path = entry?.path();
+        if path.is_dir() {
+            collect_yaml(base, &path, out)?;
+        } else if path.extension().and_then(|e| e.to_str()) == Some("yaml") {
+            let rel = path
+                .strip_prefix(base)
+                .expect("walked paths sit under their base")
+                .to_string_lossy()
+                .replace('\\', "/");
+            let raw = std::fs::read_to_string(&path)
+                .map_err(|e| anyhow::anyhow!("reading {}: {e}", path.display()))?;
+            out.push((rel, raw));
+        }
+    }
+    Ok(())
+}
+
+/// The offline counterpart to `content::load_needs_from_gitea` -
+/// `needs.yaml` sits at the repo root beside `aggregates.yaml`.
+pub fn load_needs_from_dir(dir: &str) -> anyhow::Result<Option<String>> {
+    let needs_path = std::path::Path::new(dir)
+        .parent()
+        .unwrap_or_else(|| std::path::Path::new("."))
+        .join("needs.yaml");
+    if !needs_path.exists() {
+        return Ok(None);
+    }
+    std::fs::read_to_string(&needs_path)
+        .map(Some)
+        .map_err(|e| anyhow::anyhow!("reading {}: {e}", needs_path.display()))
+}
+

src/main.rs

@@ -145,7 +145,13 @@ async fn main() -> anyhow::Result<()> {
         .route("/auth/callback", get(oidc::callback))
         .route("/auth/logout", get(oidc::logout))
         .route("/api/{*fn_name}", any(server_fn_handler))
-        .route("/upload", post(upload::upload))
+        // axum caps request bodies at 2 MB by default, which had made the
+        // 20 MB upload limit unreachable; raise the fence on this route only,
+        // with room for the multipart framing.
+        .route(
+            "/upload",
+            post(upload::upload).layer(axum::extract::DefaultBodyLimit::max(upload::MAX_UPLOAD_BYTES + 64 * 1024)),
+        )
         .route("/gitea-repo", get(content::gitea_repo_handler))
         // Content-shipped assets (hero module etc.), same-origin.
         .route("/site/{*path}", get(content::site_asset_handler))

src/needs.rs

@@ -0,0 +1,969 @@
+//! A business's needs, stated apart from how its pages word them.
+//!
+//! A content repo may ship a `needs.yaml` at its root: each *need* says
+//! who wants what, where they enter, which bucket the answer must land
+//! in, and which group has to be able to carry it to a finished state.
+//! Two things are checked against it:
+//!
+//! - **Structure** (`check`): deterministic. A path of submissions
+//!   leads from the entry page to the bucket, within an effort budget;
+//!   the handling group has a desk over that bucket; every finished
+//!   state is reachable through the moves that desk offers, and no
+//!   record strands on the way.
+//! - **Wording** (`tasks` / `score`): each *persona* is a visitor in
+//!   their own words. Every page on their path becomes one typed
+//!   `choice` question for an external answering engine - the page's
+//!   question, its alternatives as the options - and the engine's picks
+//!   are scored against the alternatives that actually meet the need.
+//!   A misroute is a wording defect: the page said one thing and the
+//!   visitor heard another.
+//!
+//! The engine is deliberately outside this crate: tasks go out as
+//! JSONL, answers come back as JSONL, so any classifier or LLM can sit
+//! in between and be compared on the same tasks.
+#![cfg(feature = "ssr")]
+
+use std::collections::{BTreeMap, HashMap, HashSet, VecDeque};
+
+use serde::{Deserialize, Serialize};
+
+use crate::aggregates::AggregateSchema;
+use crate::content::{action_target_id, Alternative, Question};
+
+#[derive(Debug, Default, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct NeedsFile {
+    #[serde(default)]
+    pub needs: Vec<Need>,
+    #[serde(default)]
+    pub personas: Vec<Persona>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Need {
+    pub id: String,
+    /// The kind of visitor - prose, for the reader of the report.
+    pub who: String,
+    pub wants: String,
+    /// The page they arrive on.
+    #[serde(default = "root")]
+    pub enters: String,
+    /// The group they hold when they arrive; unset means anonymous.
+    #[serde(default)]
+    pub enters_as: Option<String>,
+    /// The alternative on the entry page that serves this need, when
+    /// several record into the same bucket.
+    #[serde(default)]
+    pub via: Option<String>,
+    /// The bucket their answer must be recorded into.
+    pub lands_in: String,
+    /// The group that must be able to see the record and move it.
+    pub handled_by: String,
+    /// The states that count as handled.
+    pub done_when: Vec<String>,
+    /// Submissions the visitor may be asked for before the record
+    /// exists.
+    #[serde(default = "default_max_steps")]
+    pub max_steps: usize,
+    /// Required fields across the whole path - the onboarding effort
+    /// budget.
+    #[serde(default)]
+    pub max_fields: Option<usize>,
+    /// Declared, and knowingly not open yet: what is missing reports
+    /// as a warning, so the gap stays visible without failing CI.
+    #[serde(default)]
+    pub planned: bool,
+    /// The finished states that are a good outcome for the business -
+    /// a subset of `done_when`. "lost" is finished; "won" is success.
+    /// What a simulation or a live bucket report counts toward.
+    #[serde(default)]
+    pub success: Vec<String>,
+    /// Every stage the business said a case goes through, in its own
+    /// order, first to last. Written from how the business describes
+    /// its work, before any state machine exists, so that a machine
+    /// which quietly skips a stage ("we go and look, then we quote"
+    /// becoming open -> quoted) fails instead of passing.
+    #[serde(default)]
+    pub stages: Vec<String>,
+    /// Other groups whose desks carry some of this need's moves: a
+    /// site manager closing what a project manager opened. Their
+    /// buttons count toward reaching `done_when` exactly as
+    /// `handled_by`'s do. `handled_by` must still hold a desk of its
+    /// own - someone has to be answerable for the record.
+    #[serde(default)]
+    pub also_moved_by: Vec<String>,
+}
+
+fn root() -> String {
+    "/".to_string()
+}
+
+fn default_max_steps() -> usize {
+    2
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Persona {
+    pub id: String,
+    pub need: String,
+    /// The visitor's situation in their own words - never the page's.
+    pub text: String,
+}
+
+pub fn parse(raw: &str) -> anyhow::Result<NeedsFile> {
+    serde_yaml::from_str(raw).map_err(|e| anyhow::anyhow!("parsing needs.yaml: {e}"))
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Level {
+    Fail,
+    Warn,
+}
+
+#[derive(Debug)]
+pub struct Finding {
+    pub need: String,
+    pub level: Level,
+    pub message: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct Step {
+    pub page: String,
+    pub alternative: String,
+}
+
+/// One alternative on a page that still meets the need, with the
+/// cheapest way on from it.
+struct Viable {
+    alternative: String,
+    path: Vec<Step>,
+    fields: usize,
+    records_with_action: Option<bool>,
+}
+
+type Questions = HashMap<String, Question>;
+
+fn visible(q: &Question, as_group: Option<&str>) -> bool {
+    match &q.qualifies {
+        None => true,
+        Some(group) => as_group == Some(group.as_str()),
+    }
+}
+
+fn required_fields(alt: &Alternative) -> usize {
+    alt.features
+        .iter()
+        .flat_map(|f| &f.requirements)
+        .filter(|r| !r.optional)
+        .count()
+}
+
+/// The alternatives on `page` from which the need is still met within
+/// `remaining` submissions.
+fn viable(
+    questions: &Questions,
+    need: &Need,
+    page: &Question,
+    remaining: usize,
+    entry: bool,
+    include_disabled: bool,
+    trail: &mut Vec<String>,
+) -> Vec<Viable> {
+    let mut out = Vec::new();
+    if remaining == 0 {
+        return out;
+    }
+    for alt in page.alternatives.iter().filter(|a| include_disabled || !a.disabled) {
+        if entry && need.via.as_deref().is_some_and(|via| via != alt.name) {
+            continue;
+        }
+        let step = Step {
+            page: page.id.clone(),
+            alternative: alt.name.clone(),
+        };
+        let fields = required_fields(alt);
+        if alt.record_as.as_deref() == Some(need.lands_in.as_str()) {
+            out.push(Viable {
+                alternative: alt.name.clone(),
+                path: vec![step],
+                fields,
+                records_with_action: Some(alt.action.is_some()),
+            });
+            continue;
+        }
+        let Some(target) = alt
+            .action
+            .as_deref()
+            .and_then(|a| action_target_id(questions, a))
+            .and_then(|id| questions.get(&id))
+        else {
+            continue;
+        };
+        if trail.contains(&target.id) || !visible(target, need.enters_as.as_deref()) {
+            continue;
+        }
+        trail.push(target.id.clone());
+        let onward = viable(questions, need, target, remaining - 1, false, include_disabled, trail);
+        trail.pop();
+        if let Some(best) = onward.into_iter().min_by_key(|v| (v.path.len(), v.fields)) {
+            let mut path = vec![step];
+            path.extend(best.path);
+            out.push(Viable {
+                alternative: alt.name.clone(),
+                path,
+                fields: fields + best.fields,
+                records_with_action: best.records_with_action,
+            });
+        }
+    }
+    out
+}
+
+fn entry_viable(questions: &Questions, need: &Need, include_disabled: bool) -> Option<Vec<Viable>> {
+    let page = questions.get(&need.enters)?;
+    let mut trail = vec![page.id.clone()];
+    Some(viable(questions, need, page, need.max_steps, true, include_disabled, &mut trail))
+}
+
+/// The cheapest path that meets the need, if any.
+pub fn path_for(questions: &Questions, need: &Need) -> Option<Vec<Step>> {
+    entry_viable(questions, need, false)?
+        .into_iter()
+        .min_by_key(|v| (v.path.len(), v.fields))
+        .map(|v| v.path)
+}
+
+struct Desk {
+    page: String,
+    group: Option<String>,
+    /// (from, to, button label)
+    moves: Vec<(String, String, String)>,
+}
+
+fn desks_over(questions: &Questions, bucket: &str) -> Vec<Desk> {
+    let mut desks = Vec::new();
+    for q in questions.values() {
+        for resource in q
+            .alternatives
+            .iter()
+            .flat_map(|a| &a.features)
+            .filter_map(|f| f.resource.as_ref())
+            .filter(|r| r.bucket() == Some(bucket))
+        {
+            desks.push(Desk {
+                page: q.id.clone(),
+                group: resource.requires_group.clone().or_else(|| q.qualifies.clone()),
+                moves: resource
+                    .transitions
+                    .iter()
+                    .map(|t| (t.from.clone(), t.to.clone(), t.label.clone()))
+                    .collect(),
+            });
+        }
+    }
+    desks.sort_by(|a, b| a.page.cmp(&b.page));
+    desks
+}
+
+/// Self-service moves into `bucket` - a visitor holding their own
+/// record's link, no group involved (unsubscribe).
+fn self_moves(questions: &Questions, bucket: &str) -> Vec<String> {
+    questions
+        .values()
+        .flat_map(|q| &q.alternatives)
+        .filter_map(|a| a.self_transition.as_ref())
+        .filter(|s| s.bucket == bucket)
+        .map(|s| s.to.clone())
+        .collect()
+}
+
+/// Structural check of every need. `Fail` findings mean the business
+/// need is not met by the content as written.
+pub fn check(
+    file: &NeedsFile,
+    questions: &Questions,
+    aggregates: &HashMap<String, AggregateSchema>,
+) -> Vec<Finding> {
+    let mut findings = Vec::new();
+    let mut seen = HashSet::new();
+    for need in &file.needs {
+        let mut report = |level: Level, message: String| {
+            findings.push(Finding {
+                need: need.id.clone(),
+                level: if need.planned { Level::Warn } else { level },
+                message: if need.planned && level == Level::Fail {
+                    format!("planned, not met yet: {message}")
+                } else {
+                    message
+                },
+            })
+        };
+        if !seen.insert(need.id.as_str()) {
+            report(Level::Fail, "declared more than once".to_string());
+            continue;
+        }
+
+        // The visitor's side: can they get their answer recorded?
+        match questions.get(&need.enters) {
+            None => report(Level::Fail, format!("entry page {:?} does not exist", need.enters)),
+            Some(page) if !visible(page, need.enters_as.as_deref()) => report(
+                Level::Fail,
+                format!(
+                    "entry page {:?} is gated on {:?}, which this visitor does not hold",
+                    need.enters, page.qualifies
+                ),
+            ),
+            Some(page) => {
+                if page.responsible.is_none() {
+                    report(
+                        Level::Warn,
+                        format!("entry page {:?} names no one responsible to turn to", need.enters),
+                    );
+                }
+                let best = entry_viable(questions, need, false)
+                    .unwrap_or_default()
+                    .into_iter()
+                    .min_by_key(|v| (v.path.len(), v.fields));
+                match best {
+                    None if entry_viable(questions, need, true).is_some_and(|v| !v.is_empty()) => {
+                        let blocked = entry_viable(questions, need, true)
+                            .unwrap_or_default()
+                            .into_iter()
+                            .min_by_key(|v| (v.path.len(), v.fields))
+                            .map(|v| v.path)
+                            .unwrap_or_default();
+                        let at = blocked
+                            .iter()
+                            .find(|s| {
+                                questions[&s.page]
+                                    .alternatives
+                                    .iter()
+                                    .any(|a| a.name == s.alternative && a.disabled)
+                            })
+                            .map(|s| format!("{:?} on {}", s.alternative, s.page))
+                            .unwrap_or_default();
+                        report(
+                            Level::Fail,
+                            format!(
+                                "the path exists but is closed: {at} is `disabled`, so the answer is advertised and refused"
+                            ),
+                        )
+                    }
+                    None => report(
+                        Level::Fail,
+                        format!(
+                            "no path from {:?}{} records into {:?} within {} submission(s)",
+                            need.enters,
+                            need.via
+                                .as_ref()
+                                .map(|v| format!(" via {v:?}"))
+                                .unwrap_or_default(),
+                            need.lands_in,
+                            need.max_steps
+                        ),
+                    ),
+                    Some(best) => {
+                        if let Some(budget) = need.max_fields {
+                            if best.fields > budget {
+                                report(
+                                    Level::Fail,
+                                    format!(
+                                        "the path asks for {} required field(s), over the budget of {budget}",
+                                        best.fields
+                                    ),
+                                );
+                            }
+                        }
+                        if best.records_with_action == Some(false) {
+                            report(
+                                Level::Warn,
+                                "the recording alternative has no `action` - the visitor is never told what happens next".to_string(),
+                            );
+                        }
+                    }
+                }
+            }
+        }
+
+        // The business's side: can the handling group finish it?
+        let Some(schema) = aggregates.get(&need.lands_in) else {
+            report(
+                Level::Fail,
+                format!("aggregates.yaml declares no state machine for {:?}", need.lands_in),
+            );
+            continue;
+        };
+        let desks = desks_over(questions, &need.lands_in);
+        let own: Vec<&Desk> = desks
+            .iter()
+            .filter(|d| {
+                d.group.as_deref().is_some_and(|g| g == need.handled_by || need.also_moved_by.iter().any(|m| m == g))
+            })
+            .collect();
+        if !desks.iter().any(|d| d.group.as_deref() == Some(need.handled_by.as_str())) {
+            let others: Vec<String> = desks
+                .iter()
+                .map(|d| format!("{} ({})", d.page, d.group.as_deref().unwrap_or("ungated")))
+                .collect();
+            report(
+                Level::Fail,
+                format!(
+                    "no desk gated on {:?} reads {:?}{}",
+                    need.handled_by,
+                    need.lands_in,
+                    if others.is_empty() {
+                        String::new()
+                    } else {
+                        format!(" - it is read by {}", others.join(", "))
+                    }
+                ),
+            );
+            continue;
+        }
+        let selfs = self_moves(questions, &need.lands_in);
+        let exits = |state: &str| -> Vec<String> {
+            let allowed = schema.allowed(state);
+            let mut to: Vec<String> = own
+                .iter()
+                .flat_map(|d| &d.moves)
+                .filter(|(from, to, _)| from == state && allowed.contains(to))
+                .map(|(_, to, _)| to.clone())
+                .collect();
+            to.extend(selfs.iter().filter(|to| allowed.contains(to)).cloned());
+            to
+        };
+        let done: HashSet<&str> = need.done_when.iter().map(String::as_str).collect();
+        // Reachability walks the whole machine (a finished state may
+        // lead on to another: subscribed, then unsubscribed). Stranding
+        // only counts on the way to the first finished state - what
+        // happens to a handled record afterwards is not this need.
+        let mut reached: HashSet<String> = HashSet::from([schema.initial.clone()]);
+        let mut queue = VecDeque::from([(schema.initial.clone(), false)]);
+        let mut stranded = Vec::new();
+        while let Some((state, past_done)) = queue.pop_front() {
+            let past_done = past_done || done.contains(state.as_str());
+            let next = exits(&state);
+            if next.is_empty() && !past_done {
+                stranded.push(state.clone());
+            }
+            for to in next {
+                if reached.insert(to.clone()) {
+                    queue.push_back((to, past_done));
+                }
+            }
+        }
+        for state in &need.done_when {
+            if !schema.has_state(state) {
+                report(
+                    Level::Fail,
+                    format!("done_when names {state:?}, which {:?} has no such state", need.lands_in),
+                );
+            } else if !reached.contains(state) {
+                report(
+                    Level::Fail,
+                    format!(
+                        "{:?} cannot move a record to {state:?} - no desk of theirs offers the moves",
+                        need.handled_by
+                    ),
+                );
+            }
+        }
+        for stage in &need.stages {
+            if !schema.has_state(stage) {
+                report(
+                    Level::Fail,
+                    format!(
+                        "the business describes a stage {stage:?} that {:?} has no state for",
+                        need.lands_in
+                    ),
+                );
+            } else if !reached.contains(stage) {
+                report(
+                    Level::Fail,
+                    format!(
+                        "stage {stage:?} exists but {:?} is offered no moves that reach it",
+                        need.handled_by
+                    ),
+                );
+            }
+        }
+        for state in &need.success {
+            if !need.done_when.contains(state) {
+                report(
+                    Level::Fail,
+                    format!("success names {state:?}, which is not one of done_when"),
+                );
+            }
+        }
+        stranded.sort();
+        for state in stranded {
+            report(
+                Level::Fail,
+                format!(
+                    "records strand in {state:?}: {:?} is offered no move out of it",
+                    need.handled_by
+                ),
+            );
+        }
+    }
+
+    let need_ids: HashSet<&str> = file.needs.iter().map(|n| n.id.as_str()).collect();
+    for persona in &file.personas {
+        if !need_ids.contains(persona.need.as_str()) {
+            findings.push(Finding {
+                need: persona.need.clone(),
+                level: Level::Fail,
+                message: format!("persona {:?} points at a need that is not declared", persona.id),
+            });
+        }
+    }
+    findings
+}
+
+/// Everything a simulation of the business needs, resolved: each
+/// need's path with the choice on every page and the form that gets
+/// filled, each bucket's state machine with the buttons every desk
+/// offers, and the personas. Portal resolves it because only portal
+/// loads content the way the runtime does (derived ids, relative
+/// refs, sections); whoever simulates reads plain JSON.
+pub fn sim_model(
+    file: &NeedsFile,
+    questions: &Questions,
+    aggregates: &HashMap<String, AggregateSchema>,
+) -> serde_json::Value {
+    use serde_json::json;
+    let mut needs = Vec::new();
+    let mut buckets = serde_json::Map::new();
+    for need in &file.needs {
+        let Some(path) = path_for(questions, need) else {
+            continue;
+        };
+        let steps: Vec<serde_json::Value> = path
+            .iter()
+            .enumerate()
+            .map(|(i, step)| {
+                let page = &questions[&step.page];
+                let mut trail: Vec<String> = path[..=i].iter().map(|s| s.page.clone()).collect();
+                let expect: Vec<String> =
+                    viable(questions, need, page, need.max_steps - i, i == 0, false, &mut trail)
+                        .into_iter()
+                        .map(|v| v.alternative)
+                        .collect();
+                let fields: Vec<serde_json::Value> = page
+                    .alternatives
+                    .iter()
+                    .find(|a| a.name == step.alternative)
+                    .into_iter()
+                    .flat_map(|a| &a.features)
+                    .flat_map(|f| &f.requirements)
+                    .map(|r| {
+                        json!({
+                            "name": r.name,
+                            "label": r.label.clone().unwrap_or_else(|| r.name.clone()),
+                            "type": r.kind,
+                            "optional": r.optional,
+                            "options": r.options,
+                        })
+                    })
+                    .collect();
+                json!({
+                    "page": step.page,
+                    "question": page.name,
+                    "options": page.alternatives.iter().filter(|a| !a.disabled).map(|a| json!({
+                        "name": a.name,
+                        "description": plain(&a.description),
+                    })).collect::<Vec<_>>(),
+                    "expect": expect,
+                    "alternative": step.alternative,
+                    "fields": fields,
+                })
+            })
+            .collect();
+        needs.push(json!({
+            "id": need.id,
+            "who": need.who,
+            "wants": need.wants,
+            "enters_as": need.enters_as,
+            "lands_in": need.lands_in,
+            "handled_by": need.handled_by,
+            "done_when": need.done_when,
+            "success": need.success,
+            "steps": steps,
+        }));
+        if let Some(schema) = aggregates.get(&need.lands_in) {
+            buckets.entry(need.lands_in.clone()).or_insert_with(|| {
+                json!({
+                    "initial": schema.initial,
+                    "transitions": schema.transitions,
+                    "desks": desks_over(questions, &need.lands_in).iter().map(|d| json!({
+                        "page": d.page,
+                        "group": d.group,
+                        "moves": d.moves.iter().map(|(from, to, label)| json!({
+                            "from": from, "to": to, "label": label,
+                        })).collect::<Vec<_>>(),
+                    })).collect::<Vec<_>>(),
+                    "self_moves": self_moves(questions, &need.lands_in),
+                })
+            });
+        }
+    }
+    json!({
+        "needs": needs,
+        "buckets": buckets,
+        "personas": file.personas.iter().map(|p| json!({
+            "id": p.id, "need": p.need, "text": plain(&p.text),
+        })).collect::<Vec<_>>(),
+    })
+}
+
+/// One decision for the answering engine - the shape is laya's
+/// `predict(state, questions)` input, so an adapter is a loop and
+/// nothing more; any other engine reads the same fields.
+#[derive(Debug, Serialize)]
+pub struct Task {
+    pub id: String,
+    pub persona: String,
+    pub need: String,
+    pub page: String,
+    pub state: BTreeMap<&'static str, String>,
+    pub questions: BTreeMap<&'static str, ChoiceQuestion>,
+    /// Every alternative that still meets the need from here. The
+    /// engine never sees this.
+    pub expect: Vec<String>,
+}
+
+#[derive(Debug, Serialize)]
+pub struct ChoiceQuestion {
+    #[serde(rename = "type")]
+    pub kind: &'static str,
+    pub instructions: String,
+    pub criteria: BTreeMap<String, String>,
+}
+
+fn plain(text: &str) -> String {
+    text.split_whitespace().collect::<Vec<_>>().join(" ")
+}
+
+/// Every (persona, page-on-their-path) pair with a real choice on it.
+/// `skim` shows the engine only each alternative's heading - what a
+/// visitor who never reads the description has to go on.
+pub fn tasks(file: &NeedsFile, questions: &Questions, skim: bool) -> Vec<Task> {
+    let mut out = Vec::new();
+    for persona in &file.personas {
+        let Some(need) = file.needs.iter().find(|n| n.id == persona.need) else {
+            continue;
+        };
+        let Some(path) = path_for(questions, need) else {
+            continue;
+        };
+        for (i, step) in path.iter().enumerate() {
+            let page = &questions[&step.page];
+            let open: Vec<&Alternative> = page.alternatives.iter().filter(|a| !a.disabled).collect();
+            if open.len() < 2 {
+                continue;
+            }
+            let mut trail: Vec<String> = path[..=i].iter().map(|s| s.page.clone()).collect();
+            let expect: Vec<String> = viable(questions, need, page, need.max_steps - i, i == 0, false, &mut trail)
+                .into_iter()
+                .map(|v| v.alternative)
+                .collect();
+            let criteria = open
+                .iter()
+                .map(|a| {
+                    let description = plain(&a.description);
+                    (
+                        a.name.clone(),
+                        if skim || description.is_empty() { a.name.clone() } else { description },
+                    )
+                })
+                .collect();
+            out.push(Task {
+                id: format!("{}@{}", persona.id, step.page),
+                persona: persona.id.clone(),
+                need: need.id.clone(),
+                page: step.page.clone(),
+                state: BTreeMap::from([("body", plain(&persona.text))]),
+                questions: BTreeMap::from([(
+                    "pick",
+                    ChoiceQuestion {
+                        kind: "choice",
+                        instructions: format!(
+                            "A visitor reads the page question {:?}. Which alternative do they choose?",
+                            page.name
+                        ),
+                        criteria,
+                    },
+                )]),
+                expect,
+            });
+        }
+    }
+    out
+}
+
+#[derive(Debug, Deserialize)]
+pub struct Answer {
+    pub id: String,
+    pub choice: String,
+    #[serde(default)]
+    pub confidence: Option<f64>,
+}
+
+#[derive(Debug, Default)]
+pub struct Score {
+    pub total: usize,
+    pub correct: usize,
+    /// (task id, picked, expected, confidence)
+    pub misroutes: Vec<(String, String, Vec<String>, Option<f64>)>,
+    /// Right, but the engine was under `hesitant_below` - wording that
+    /// works and is still close to a coin flip.
+    pub hesitant: Vec<(String, f64)>,
+    pub unanswered: Vec<String>,
+}
+
+impl Score {
+    pub fn accuracy(&self) -> f64 {
+        if self.total == 0 {
+            1.0
+        } else {
+            self.correct as f64 / self.total as f64
+        }
+    }
+}
+
+pub fn score(tasks: &[Task], answers: &[Answer], hesitant_below: f64) -> Score {
+    let by_id: HashMap<&str, &Answer> = answers.iter().map(|a| (a.id.as_str(), a)).collect();
+    let mut score = Score {
+        total: tasks.len(),
+        ..Score::default()
+    };
+    for task in tasks {
+        match by_id.get(task.id.as_str()) {
+            None => score.unanswered.push(task.id.clone()),
+            Some(answer) if task.expect.contains(&answer.choice) => {
+                score.correct += 1;
+                if let Some(c) = answer.confidence.filter(|c| *c < hesitant_below) {
+                    score.hesitant.push((task.id.clone(), c));
+                }
+            }
+            Some(answer) => score.misroutes.push((
+                task.id.clone(),
+                answer.choice.clone(),
+                task.expect.clone(),
+                answer.confidence,
+            )),
+        }
+    }
+    score
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::aggregates::parse_aggregates_yaml;
+    use crate::content::build_questions;
+
+    fn site(desk_moves: &str) -> (Questions, HashMap<String, AggregateSchema>) {
+        let files = vec![
+            (
+                "index.yaml".to_string(),
+                "name: What are you here for?\nresponsible: { name: A, contact: a@b.c }\nalternatives:\n  - name: Hire us\n    description: Bring a problem.\n    action: /thanks\n    record_as: projects\n    features:\n      - name: Brief\n        requirements:\n          - name: email\n            type: email\n          - name: brief\n            type: textarea\n          - name: budget\n            optional: true\n  - name: Follow along\n    description: Notes by mail.\n    action: /thanks\n    record_as: subscribers\n".to_string(),
+            ),
+            ("thanks.yaml".to_string(), "name: Thanks\nfollowup: true\n".to_string()),
+            (
+                "desk/index.yaml".to_string(),
+                format!("name: Desk\nqualifies: owners\nalternatives:\n  - name: Projects\n    features:\n      - name: \"\"\n        resource:\n          source: {{ kind: kv, bucket: projects }}\n          requires_group: owners\n          transitions:\n{desk_moves}"),
+            ),
+        ];
+        let aggregates = parse_aggregates_yaml(
+            "aggregates:\n  - bucket: projects\n    initial: open\n    states:\n      open: { event: submitted }\n      quoted: { event: quoted }\n      won: { event: won }\n      lost: { event: lost }\n    transitions:\n      open: [quoted, lost]\n      quoted: [won, lost]\n  - bucket: subscribers\n    attended_by: a mailer\n    initial: open\n    states:\n      open: { event: subscribed }\n    transitions: {}\n",
+        )
+        .unwrap();
+        (build_questions(&files).unwrap(), aggregates)
+    }
+
+    const FULL_DESK: &str = "            - { to: quoted, label: Quote }\n            - { to: lost, label: Lose }\n            - { from: quoted, to: won, label: Win }\n            - { from: quoted, to: lost, label: Lose }\n";
+
+    fn needs(extra: &str) -> NeedsFile {
+        parse(&format!(
+            "needs:\n  - id: hire\n    who: a client\n    wants: work done\n    lands_in: projects\n    handled_by: owners\n    done_when: [won, lost]\n{extra}personas:\n  - id: founder\n    need: hire\n    text: I need someone to build our booking tool.\n"
+        ))
+        .unwrap()
+    }
+
+    fn fails(findings: &[Finding]) -> Vec<&str> {
+        findings
+            .iter()
+            .filter(|f| f.level == Level::Fail)
+            .map(|f| f.message.as_str())
+            .collect()
+    }
+
+    #[test]
+    fn a_met_need_is_silent() {
+        let (questions, aggregates) = site(FULL_DESK);
+        let findings = check(&needs("    max_fields: 2\n"), &questions, &aggregates);
+        assert!(findings.is_empty(), "{findings:?}");
+    }
+
+    #[test]
+    fn effort_budget_counts_required_fields_only() {
+        let (questions, aggregates) = site(FULL_DESK);
+        let findings = check(&needs("    max_fields: 1\n"), &questions, &aggregates);
+        assert_eq!(fails(&findings), vec!["the path asks for 2 required field(s), over the budget of 1"]);
+    }
+
+    #[test]
+    fn a_desk_missing_a_move_strands_records_and_cannot_finish() {
+        // The desk can quote, but never close a quoted job.
+        let (questions, aggregates) = site("            - { to: quoted, label: Quote }\n            - { to: lost, label: Lose }\n");
+        let findings = check(&needs(""), &questions, &aggregates);
+        assert_eq!(
+            fails(&findings),
+            vec![
+                "\"owners\" cannot move a record to \"won\" - no desk of theirs offers the moves",
+                "records strand in \"quoted\": \"owners\" is offered no move out of it",
+            ]
+        );
+    }
+
+    #[test]
+    fn a_finished_state_may_lead_on_to_another() {
+        // quoted counts as handled here, yet won must still be
+        // reachable past it; lost-after-quoted is not this need's
+        // business, so nothing strands.
+        let (questions, aggregates) = site(FULL_DESK);
+        let mut file = needs("");
+        file.needs[0].done_when = vec!["quoted".to_string(), "won".to_string(), "lost".to_string()];
+        let findings = check(&file, &questions, &aggregates);
+        assert!(findings.is_empty(), "{findings:?}");
+    }
+
+    #[test]
+    fn a_disabled_alternative_is_named_as_the_reason() {
+        let (mut questions, aggregates) = site(FULL_DESK);
+        questions.get_mut("/").unwrap().alternatives[0].disabled = true;
+        let findings = check(&needs(""), &questions, &aggregates);
+        assert_eq!(
+            fails(&findings),
+            vec!["the path exists but is closed: \"Hire us\" on / is `disabled`, so the answer is advertised and refused"]
+        );
+    }
+
+    #[test]
+    fn success_must_be_a_finished_state_and_the_sim_model_carries_the_whole_flow() {
+        let (questions, aggregates) = site(FULL_DESK);
+        let mut file = needs("    success: [won]\n");
+        assert!(check(&file, &questions, &aggregates).is_empty());
+
+        let model = sim_model(&file, &questions, &aggregates);
+        let need = &model["needs"][0];
+        assert_eq!(need["success"][0], "won");
+        let step = &need["steps"][0];
+        assert_eq!(step["question"], "What are you here for?");
+        assert_eq!(step["expect"][0], "Hire us");
+        assert_eq!(step["options"].as_array().unwrap().len(), 2);
+        // The form the visitor fills, required and optional alike.
+        let fields = step["fields"].as_array().unwrap();
+        assert_eq!(fields.len(), 3);
+        assert_eq!(fields[2]["optional"], true);
+        // The desk's buttons, labelled, per state.
+        let moves = model["buckets"]["projects"]["desks"][0]["moves"].as_array().unwrap();
+        assert!(moves.iter().any(|m| m["from"] == "quoted" && m["to"] == "won" && m["label"] == "Win"));
+        assert_eq!(model["buckets"]["projects"]["initial"], "open");
+        assert_eq!(model["personas"][0]["id"], "founder");
+
+        // A stage the business named must exist as a state.
+        file.needs[0].stages = vec!["open".into(), "surveyed".into(), "quoted".into()];
+        assert_eq!(
+            fails(&check(&file, &questions, &aggregates)),
+            vec!["the business describes a stage \"surveyed\" that \"projects\" has no state for"]
+        );
+        file.needs[0].stages = vec!["open".into(), "quoted".into(), "won".into()];
+        assert!(check(&file, &questions, &aggregates).is_empty());
+
+        file.needs[0].success = vec!["quoted".to_string()];
+        assert_eq!(
+            fails(&check(&file, &questions, &aggregates)),
+            vec!["success names \"quoted\", which is not one of done_when"]
+        );
+    }
+
+    #[test]
+    fn a_need_can_be_carried_by_more_than_one_groups_desk() {
+        // owners may only quote or lose; closing a quoted job is the
+        // site managers' button, on a desk of their own.
+        let (mut questions, aggregates) = site("            - { to: quoted, label: Quote }\n            - { to: lost, label: Lose }\n");
+        let more = build_questions(&[(
+            "site/index.yaml".to_string(),
+            "name: Site desk\nqualifies: site_managers\nalternatives:\n  - name: Projects\n    features:\n      - name: \"\"\n        resource:\n          source: { kind: kv, bucket: projects }\n          requires_group: site_managers\n          transitions:\n            - { from: quoted, to: won, label: Win }\n            - { from: quoted, to: lost, label: Lose }\n".to_string(),
+        )])
+        .unwrap();
+        questions.extend(more);
+
+        let mut file = needs("");
+        // Alone, owners cannot finish it...
+        assert_eq!(fails(&check(&file, &questions, &aggregates)).len(), 2);
+        // ...with the site managers' buttons counted, they can.
+        file.needs[0].also_moved_by = vec!["site_managers".to_string()];
+        assert!(check(&file, &questions, &aggregates).is_empty());
+        // But someone has to be answerable: handled_by needs its own desk.
+        file.needs[0].handled_by = "nobody".to_string();
+        assert!(fails(&check(&file, &questions, &aggregates))[0].starts_with("no desk gated on \"nobody\""));
+    }
+
+    #[test]
+    fn the_wrong_group_holding_the_desk_is_a_failure() {
+        let (questions, aggregates) = site(FULL_DESK);
+        let mut file = needs("");
+        file.needs[0].handled_by = "sales".to_string();
+        let findings = check(&file, &questions, &aggregates);
+        assert_eq!(
+            fails(&findings),
+            vec!["no desk gated on \"sales\" reads \"projects\" - it is read by /desk (owners)"]
+        );
+    }
+
+    #[test]
+    fn via_pins_the_entry_alternative() {
+        let (questions, aggregates) = site(FULL_DESK);
+        let mut file = needs("");
+        file.needs[0].via = Some("Follow along".to_string());
+        let findings = check(&file, &questions, &aggregates);
+        assert_eq!(
+            fails(&findings),
+            vec!["no path from \"/\" via \"Follow along\" records into \"projects\" within 2 submission(s)"]
+        );
+    }
+
+    #[test]
+    fn tasks_carry_the_page_as_a_choice_and_score_separates_misroutes() {
+        let (questions, _) = site(FULL_DESK);
+        let file = needs("");
+        let tasks = tasks(&file, &questions, false);
+        let skimmed = super::tasks(&file, &questions, true);
+        assert_eq!(skimmed[0].questions["pick"].criteria["Follow along"], "Follow along");
+        assert_eq!(tasks.len(), 1);
+        let task = &tasks[0];
+        assert_eq!(task.id, "founder@/");
+        assert_eq!(task.expect, vec!["Hire us"]);
+        let q = &task.questions["pick"];
+        assert_eq!(q.kind, "choice");
+        assert_eq!(q.criteria["Follow along"], "Notes by mail.");
+        assert!(q.instructions.contains("What are you here for?"));
+
+        let right = vec![Answer { id: "founder@/".into(), choice: "Hire us".into(), confidence: Some(0.55) }];
+        let s = score(&tasks, &right, 0.6);
+        assert_eq!((s.correct, s.misroutes.len(), s.hesitant.len()), (1, 0, 1));
+
+        let wrong = vec![Answer { id: "founder@/".into(), choice: "Follow along".into(), confidence: Some(0.9) }];
+        let s = score(&tasks, &wrong, 0.6);
+        assert_eq!((s.correct, s.misroutes.len()), (0, 1));
+        assert_eq!(s.accuracy(), 0.0);
+
+        assert_eq!(score(&tasks, &[], 0.6).unanswered, vec!["founder@/"]);
+    }
+}

src/resource.rs

@@ -260,21 +260,20 @@ async fn fetch_gitea_json(
     for (k, v) in params {
         url.query_pairs_mut().append_pair(k, v);
     }
-    let client = openidconnect::reqwest::Client::new();
+    let mut req = crate::http::client().get(url.clone());
-    let mut req = client.get(url.clone());
     if let Ok(token) = std::env::var("GITEA_API_TOKEN") {
         if !token.is_empty() {
             req = req.header("Authorization", format!("token {token}"));
         }
     }
-    let text = req
+    let response = req
         .send()
         .await
         .and_then(|r| r.error_for_status())
-        .map_err(|e| ServerFnError::new(format!("fetching {url}: {e}")))?
+        .map_err(|e| ServerFnError::new(format!("fetching {url}: {e}")))?;
-        .text()
+    let text = crate::http::text(response, crate::http::GITEA_CAP)
         .await
-        .map_err(|e| ServerFnError::new(e.to_string()))?;
+        .map_err(|e| ServerFnError::new(format!("reading {url}: {e}")))?;
     serde_json::from_str(&text).map_err(|e| ServerFnError::new(e.to_string()))
 }
 
@@ -341,16 +340,17 @@ async fn fetch_url_json(
     for (k, v) in &leftover {
         parsed.query_pairs_mut().append_pair(k, v);
     }
-    let client = openidconnect::reqwest::Client::new();
+    let response = crate::http::client()
-    let text = client
         .get(parsed.clone())
         .send()
         .await
         .and_then(|r| r.error_for_status())
-        .map_err(|e| ServerFnError::new(format!("fetching {parsed}: {e}")))?
+        .map_err(|e| ServerFnError::new(format!("fetching {parsed}: {e}")))?;
-        .text()
+    // Content picks the URL; the cap is what keeps a runaway endpoint
+    // from becoming a runaway allocation here.
+    let text = crate::http::text(response, crate::http::URL_RESOURCE_CAP)
         .await
-        .map_err(|e| ServerFnError::new(e.to_string()))?;
+        .map_err(|e| ServerFnError::new(format!("reading {parsed}: {e}")))?;
     serde_json::from_str(&text).map_err(|e| ServerFnError::new(e.to_string()))
 }
 

src/upload.rs

@@ -15,7 +15,7 @@ use serde::Serialize;
 
 use crate::server::AppState;
 
-const MAX_UPLOAD_BYTES: usize = 20 * 1024 * 1024;
+pub const MAX_UPLOAD_BYTES: usize = 20 * 1024 * 1024;
 
 #[derive(Clone)]
 pub struct Garage {
@@ -84,12 +84,20 @@ pub async fn upload(
             .unwrap_or("application/octet-stream")
             .to_string();
         let filename = field.file_name().unwrap_or("upload").to_string();
-        let bytes = field
+        // Chunk by chunk, refused the moment the cap is crossed: an
-            .bytes()
+        // oversized body is never buffered whole before being turned
+        // away. The route's body limit (main.rs) is the outer fence.
+        let mut bytes: Vec<u8> = Vec::new();
+        let mut field = field;
+        while let Some(chunk) = field
+            .chunk()
             .await
-            .map_err(|e| (StatusCode::BAD_REQUEST, e.to_string()))?;
+            .map_err(|e| (StatusCode::BAD_REQUEST, e.to_string()))?
-        if bytes.len() > MAX_UPLOAD_BYTES {
+        {
-            return Err((StatusCode::PAYLOAD_TOO_LARGE, "file too large".to_string()));
+            if bytes.len() + chunk.len() > MAX_UPLOAD_BYTES {
+                return Err((StatusCode::PAYLOAD_TOO_LARGE, "file too large".to_string()));
+            }
+            bytes.extend_from_slice(&chunk);
         }
 
         let key = format!("{}-{filename}", uuid::Uuid::new_v4());

style/main.css

@@ -1045,6 +1045,9 @@ textarea:focus {
 .item-card-description {
   font-size: 0.9rem;
   color: var(--ink-dim);
+  /* The card is a grid with its own gap; the global p bottom margin
+     would stack on top of it. */
+  margin: 0;
 }
 
 .item-card-fields {

tests/jetstream.rs

@@ -0,0 +1,66 @@
+//! The one test that meets a real JetStream: a submission becomes an
+//! aggregate, a desk move is accepted, an undeclared move is refused,
+//! and the record reads back from its own event log. Everything else
+//! in the suite replays in memory; this is what proves the store, the
+//! event log and the projection agree with each other.
+//!
+//! Runs only when `PORTAL_TEST_NATS_URL` points at a JetStream (CI
+//! starts a throwaway one, see `.gitea/workflows/test.yml`); without
+//! it the test passes as skipped, so `cargo test` stays green offline.
+#![cfg(feature = "ssr")]
+
+use portal::aggregates::{self, parse_aggregates_yaml, TransitionError};
+use portal::answers::{store_answer, Answer};
+use portal::events::store::{ensure_stream, load_events};
+use serde_json::json;
+
+#[tokio::test]
+async fn a_submission_is_created_moved_refused_and_read_back_through_the_real_engine() {
+    let Ok(url) = std::env::var("PORTAL_TEST_NATS_URL") else {
+        eprintln!("skipped: PORTAL_TEST_NATS_URL is not set");
+        return;
+    };
+    let js = async_nats::jetstream::new(async_nats::connect(&url).await.expect("connect"));
+    ensure_stream(&js).await.expect("event stream");
+
+    // A bucket of its own per run, so reruns and parallel runs never
+    // read each other's records.
+    let bucket = format!("it_{}", chrono::Utc::now().timestamp_millis());
+    let schemas = parse_aggregates_yaml(&format!(
+        "aggregates:\n  - bucket: {bucket}\n    initial: open\n    states:\n      open: {{ event: received }}\n      quoted: {{ event: quoted }}\n      won: {{ event: won }}\n      lost: {{ event: lost }}\n    transitions:\n      open: [quoted, lost]\n      quoted: [won, lost]\n"
+    ))
+    .expect("schema");
+    let schema = &schemas[&bucket];
+    let now = chrono::Utc::now().timestamp_millis();
+
+    // The submission: a KV record in the initial state, plus the first event.
+    store_answer(&js, &schemas, &bucket, "rec-1".into(), "/", "Hire us", &json!({"email": "a@b.example"}), now)
+        .await
+        .expect("store");
+    let store = js.get_key_value(&bucket).await.expect("bucket exists");
+    let stored: Answer = serde_json::from_slice(&store.get("rec-1").await.unwrap().expect("record")).unwrap();
+    assert_eq!(stored.state, "open");
+    assert_eq!(stored.responses["email"], "a@b.example");
+
+    // A desk move the machine allows.
+    let moved = aggregates::transition(&js, schema, "rec-1", "quoted", json!({"by": "test"}), now + 1)
+        .await
+        .expect("open -> quoted is declared");
+    assert_eq!(moved.state, "quoted");
+
+    // Moves the machine does not allow are refused, whoever asks.
+    let back = aggregates::transition(&js, schema, "rec-1", "open", json!({}), now + 2).await;
+    assert!(matches!(back, Err(TransitionError::DisallowedTransition { .. })), "{back:?}");
+    let skip = aggregates::transition(&js, schema, "rec-1", "won", json!({}), now + 2).await;
+    assert!(skip.is_ok(), "quoted -> won is declared: {skip:?}");
+    let nobody = aggregates::transition(&js, schema, "rec-9", "quoted", json!({}), now + 3).await;
+    assert!(matches!(nobody, Err(TransitionError::UnknownAggregate)), "{nobody:?}");
+
+    // The record reads back from its own event log, in the state the
+    // accepted moves left it, with a sequence that moved forward.
+    let events = load_events(&js, &bucket, "rec-1").await.expect("events");
+    assert_eq!(events.len(), 3, "received, quoted, won");
+    let replayed = aggregates::replay(schema, "rec-1", &events).expect("replays");
+    assert_eq!(replayed.state, "won");
+    assert!(replayed.sequence > moved.sequence);
+}