Release 0.3.37

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

.gitea/workflows/publish.yml

@@ -37,6 +37,8 @@ jobs:
       SCCACHE_DIR: /var/local/sccache
       SCCACHE_SERVER_PORT: "4228"
       CARGO_TARGET_DIR: /var/local/cargo-target
+      # The iris release shipped in this portal release's tarball.
+      IRIS_RELEASE: v0.1.1
       # cargo-leptos's own downloaded tools (wasm-bindgen, wasm-opt) cache
       # under $XDG_CACHE_HOME - left at its default that resolves inside
       # this unit's systemd StateDirectory, files it creates there end up
@@ -58,8 +60,11 @@ jobs:
 
       # cargo-leptos only builds the leptos bin-target ("portal") - the
       # question-lint utility binary needs its own plain cargo build.
-      - name: Build question-lint
+      # The lint lives in uhhm/iris and is pinned to the portal release it
-        run: cargo build --release --bin question_lint --features ssr
+      # matches; shipping it in the tarball keeps a site that pins nothing
+      # extra lint-capable at /srv/app/<instance>/current/iris.
+      - name: Build iris
+        run: cargo install --git "${{ github.server_url }}/uhhm/iris.git" --tag "$IRIS_RELEASE" --root "$CARGO_TARGET_DIR/iris-install" --force iris
 
       - name: Package
         run: |
@@ -67,7 +72,7 @@ jobs:
           tag="${{ github.ref_name }}"
           stage=$(mktemp -d)
           cp "$CARGO_TARGET_DIR/release/portal" "$stage/portal"
-          cp "$CARGO_TARGET_DIR/release/question_lint" "$stage/question_lint"
+          cp "$CARGO_TARGET_DIR/iris-install/bin/iris" "$stage/iris"
           # hash-files = true: leptos resolves hash.txt next to the running
           # binary, so it ships beside portal in the release dir.
           cp "$CARGO_TARGET_DIR/release/hash.txt" "$stage/hash.txt"
@@ -75,7 +80,7 @@ jobs:
           # not affected by CARGO_TARGET_DIR - only the plain `cargo build`
           # outputs (release/, front/) move with that override.
           cp -r target/site "$stage/site"
-          tar -C "$stage" -czf "portal-$tag.tar.gz" portal question_lint hash.txt site
+          tar -C "$stage" -czf "portal-$tag.tar.gz" portal iris hash.txt site
           rm -rf "$stage"
 
       # The run's own ephemeral token has write access to this repo -
@@ -88,9 +93,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,287 @@
+# 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.37 (2026-09-22)
+
+- The lint moves to its own repo, uhhm/iris: `question_lint` becomes `iris check`, `needs_replay` becomes `iris replay`; the tarball ships `iris` (pinned in publish.yml) instead of `question_lint`; the needs module and local loaders leave portal
+
+## 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.36 |
+| redoal.com | ergo | `app@redoal-portal` | v0.3.36 |
+| 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.25"
+version = "0.3.37"
 dependencies = [
  "anyhow",
  "arc-swap",

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "portal"
-version = "0.3.26"
+version = "0.3.37"
 edition = "2021"
 
 [lib]
@@ -106,9 +106,8 @@ ssr = [
 [dev-dependencies]
 proptest = "1"
 
-[[bin]]
+[[test]]
-name = "question_lint"
+name = "jetstream"
-path = "src/bin/question_lint.rs"
 required-features = ["ssr"]
 
 [profile.wasm-release]

README.md

@@ -30,7 +30,7 @@ stream.
 
 ## What the engine provides
 
-- **Content-driven pages** (`src/content.rs`, `src/app.rs`): YAML
+- **Content-driven pages** (`src/content/`, `src/app.rs`): YAML
   loaded from Gitea at boot and hot-swapped on a NATS reload signal;
   a bad push keeps the last-good content serving. The `questions/`
   tree IS the router — file paths become URLs, `_section.yaml`
@@ -70,7 +70,17 @@ stream.
 - **Answer chains** (`src/chain.rs`): each submission hashes its
   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.
+  (unsubscribe) authorize by holding one. The question nav reads it
+  too: a `followup` page is offered only once the visitor has earned
+  it - the chain verifiably answered the alternative that leads there,
+  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** (in
+  [uhhm/iris](https://project.uhhm.no/uhhm/iris)): 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.
+  `iris check` proves the site meets it. The runtime never reads the
+  file; portal only provides the content types iris reads.
 - **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.
@@ -87,17 +97,18 @@ stream.
 ## Binaries
 
 - `portal` — the server (Leptos SSR + hydrate, Axum underneath).
-- `question_lint` — headless content validation, shipped inside every
+- `iris` — the lint, from [uhhm/iris](https://project.uhhm.no/uhhm/iris),
-  release artifact so each content repo's CI lints with the exact
+  which depends on this crate as a library pinned to a release tag.
-  portal version its instance runs; also works offline:
+  Every release tarball ships the matching `iris` binary
-  `question_lint --path <dir>`.
+  (`IRIS_RELEASE` in `publish.yml`), so each content repo's CI can
+  lint with the exact portal version its instance runs:
+  `iris check --path <dir>`.
 
 ## Development
 
 ```sh
 cargo leptos build            # full app (server + wasm)
-cargo test --features ssr     # engine tests
+cargo test --features ssr     # engine tests; tests/jetstream.rs needs PORTAL_TEST_NATS_URL
-cargo build --features ssr --bin question_lint
 ```
 
 Runtime configuration is env vars (see `src/main.rs`, and each
@@ -121,13 +132,18 @@ cargo release patch        # or minor / major
 
 That bumps `Cargo.toml`, tags `v<version>`, and pushes; CI
 (`.gitea/workflows/publish.yml`) reacts to the tag, builds once, and
-attaches `portal-v<version>.tar.gz` (`portal` + `question_lint` +
+attaches `portal-v<version>.tar.gz` (`portal` + `iris` +
 `hash.txt` + `site/`) to the Gitea release. Pkg files are
 content-hashed (`hash-files = true`; instances run with
 `LEPTOS_HASH_FILES=true`), so a freshly served page can never pair a
 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

@@ -1,5 +1,5 @@
 use leptos::prelude::*;
-use leptos_meta::{provide_meta_context, HashedStylesheet, Html, MetaTags, Stylesheet, Title};
+use leptos_meta::{provide_meta_context, HashedStylesheet, Html, Link, MetaTags, Stylesheet, Title};
 use leptos_router::{
     components::{Route, Router, Routes},
     hooks::{use_location, use_navigate, use_query_map},
@@ -40,6 +40,20 @@ pub fn shell(options: LeptosOptions) -> impl IntoView {
                 // once loaded via <link>/<img> on Safari/iOS.
                 <link rel="icon" media="(prefers-color-scheme: light)" href="/favicon-light.svg" type="image/svg+xml"/>
                 <link rel="icon" media="(prefers-color-scheme: dark)" href="/favicon-dark.svg" type="image/svg+xml"/>
+                // Fonts hide behind the stylesheet: the browser must
+                // fetch and parse CSS before it discovers them. The
+                // latin subset is on every page's critical path, so
+                // announce it up front; latin-ext and vietnamese stay
+                // unicode-range-gated and load only when script needs
+                // them - preloading those would tax everyone for a few.
+                // (Font preloads require crossorigin even same-origin.)
+                <link
+                    rel="preload"
+                    href="/fonts/quicksand-semibold-latin.woff2"
+                    r#as="font"
+                    type="font/woff2"
+                    crossorigin="anonymous"
+                />
                 // Server-side, so it can read hash.txt and link the
                 // content-hashed stylesheet (hash-files = true).
                 <HashedStylesheet id="leptos" options=options.clone()/>
@@ -89,10 +103,34 @@ pub fn App() -> impl IntoView {
             .and_then(|s| s.stylesheet)
             .map(|p| format!("/site/{p}"))
     });
+    // The wordmark paints in the hero on first view; announcing it in
+    // the head starts the fetch during hydration instead of after. On
+    // redoal.com it lives on the content host, so a preconnect opens
+    // that TLS session while the preload is still queued.
+    let wordmark_href = Memo::new(move |_| {
+        site.get().and_then(|r| r.ok()).and_then(|s| s.wordmark)
+    });
+    let wordmark_origin = Memo::new(move |_| {
+        wordmark_href.get().and_then(|w| {
+            let rest = w.strip_prefix("https://")?;
+            Some(format!("https://{}", rest.split('/').next()?))
+        })
+    });
+    // A content-shipped favicon overrides the built-in one; injected
+    // into the head after the static defaults, so it wins.
+    let favicon = Memo::new(move |_| {
+        site.get()
+            .and_then(|r| r.ok())
+            .and_then(|s| s.favicon)
+            .map(|p| format!("/site/{p}"))
+    });
 
     view! {
         <Html attr:lang=move || lang.get()/>
+        {move || wordmark_origin.get().map(|href| view! { <Link rel="preconnect" href=href crossorigin="anonymous"/> })}
+        {move || wordmark_href.get().map(|href| view! { <Link rel="preload" as_="image" href=href/> })}
         {move || custom_css.get().map(|href| view! { <Stylesheet id="site-custom" href=href/> })}
+        {move || favicon.get().map(|href| view! { <Link rel="icon" href=href/> })}
         <Suspense fallback=|| ()>
             {move || {
                 site.get()
@@ -175,7 +213,10 @@ fn PortalShell() -> impl IntoView {
         |(path, chain)| get_question(path, chain),
     );
     let user = Resource::new(|| (), |_| current_user());
-    let nav = Resource::new(move || chain.get().is_some(), list_qualifying_questions);
+    let nav = Resource::new(
+        move || (path.get(), chain.get()),
+        |(path, chain)| list_qualifying_questions(path, chain),
+    );
     let announcements = Resource::new(|| (), |_| list_announcements());
     provide_context(QuestionRes(question));
     provide_context(UserRes(user));
@@ -251,7 +292,6 @@ fn QuestionView(
     site: SiteConfig,
 ) -> impl IntoView {
     let question_id = question.id.clone();
-    let has_chain = parent_hash.is_some();
 
     // The provenance counterpart to the qualifies gate below: a
     // requires_chain page whose visitor holds no verifiable lineage to
@@ -280,7 +320,7 @@ fn QuestionView(
                 </section>
             </div>
             // A gate is never a dead end: the same nav as every page.
-            <QuestionNav current_id=question_id has_chain=has_chain/>
+            <QuestionNav current_id=question_id/>
         }
         .into_any();
     }
@@ -317,7 +357,7 @@ fn QuestionView(
                     }}
                 </section>
             </div>
-            <QuestionNav current_id=question_id has_chain=has_chain/>
+            <QuestionNav current_id=question_id/>
         }
         .into_any();
     }
@@ -380,7 +420,7 @@ fn QuestionView(
             .map(|r| {
                 view! { <ResponsibleNote responsible=r/> }
             })}
-        <QuestionNav current_id=question_id has_chain=has_chain/>
+        <QuestionNav current_id=question_id/>
     }
     .into_any()
 }
@@ -389,8 +429,7 @@ fn QuestionView(
 /// small nav - how a concern reaches the people it speaks to without
 /// claiming front-page space (an owner also sees the gated desks here).
 #[component]
-fn QuestionNav(current_id: String, has_chain: bool) -> impl IntoView {
+fn QuestionNav(current_id: String) -> impl IntoView {
-    let _ = has_chain; // keyed into the shared resource by PortalShell
     let NavRes(nav) = expect_context();
     view! {
         <Suspense fallback=|| ()>
@@ -587,14 +626,10 @@ fn Hero(title: String, description: String, landing: bool, site: SiteConfig, cur
         None
     };
     let has_module = module.is_some();
-    // Light theme inverts white-stroke wordmarks to ink. The house
+    // Light theme can invert a white-stroke wordmark to ink. Default:
-    // mark and the sibling-site marks are all white-stroke SVGs; a
+    // only the built-in house mark inverts; a content-shipped logo
-    // raster logo is a client brand and keeps its colors.
+    // keeps its colours unless site.yaml opts in with wordmark_invert.
-    let house_wordmark = site
+    let house_wordmark = site.wordmark_invert.unwrap_or(site.wordmark.is_none());
-        .wordmark
-        .as_deref()
-        .map(|w| w.ends_with(".svg"))
-        .unwrap_or(true);
     let wordmark = site.wordmark.clone().unwrap_or_else(|| "/wordmark.svg".to_string());
     // Clamped server-side too, but belt and braces for the inline style.
     let wordmark_style = site
@@ -691,7 +726,7 @@ fn Hero(title: String, description: String, landing: bool, site: SiteConfig, cur
                     <img src=wordmark alt=site_title style=wordmark_style/>
                 </a>
                 <h1>{title}</h1>
-                <p>{description}</p>
+                <p inner_html=render_inline_markdown(&description)></p>
             </div>
         </header>
     }
@@ -1995,16 +2030,22 @@ pub async fn get_site() -> Result<SiteConfig, ServerFnError> {
     Ok(state.site.load().as_ref().clone())
 }
 
-/// Every question the current visitor qualifies for, as (id, name) -
+/// Every question the visitor may be offered from `current`, as (id,
-/// the site nav's data. Context-dependent: an owner session sees the
+/// name) - the question nav's data. Front-door pages the visitor
-/// gated pages too, and `followup` pages only appear once the visitor
+/// qualifies for are always in (an owner session sees the gated desks
-/// carries an answer chain.
+/// too). A `followup` page or an ended event is in only when the
+/// visitor has earned it: their verified `?chain=` answered the
+/// alternative that leads there, or it is reachable from an earned
+/// page over links that record nothing (see `content::earned_followups`).
+/// 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(
-    has_chain: bool,
+    current: String,
+    chain: Option<String>,
 ) -> Result<Vec<(String, String)>, ServerFnError> {
     use crate::auth::{User, SESSION_USER_KEY};
-    use crate::content::is_qualified;
+    use crate::content::{earned_followups, is_qualified, unlocked_by, Question};
     use crate::server::AppState;
 
     let state = expect_context::<AppState>();
@@ -2015,14 +2056,24 @@ pub async fn list_qualifying_questions(
         .map_err(|e| ServerFnError::new(e.to_string()))?;
 
     let now_ms = chrono::Utc::now().timestamp_millis();
-    let mut out: Vec<(String, String)> = state
+    let questions = state.questions.load();
-        .questions
+    // What the chain verifiably answered - the same lookup a
-        .load()
+    // `requires_chain` gate does, so a forged or foreign hash resolves
+    // to nothing - and therefore where it sent the visitor.
+    let seeds: Vec<String> = match &chain {
+        Some(hash) => match crate::chain::lookup_node(&state.jetstream, hash).await {
+            Some(node) => unlocked_by(&questions, &node.question_id, node.alternative.as_deref()),
+            None => Vec::new(),
+        },
+        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 earned = earned_followups(&questions, &current, &seeds, &is_outcome);
+    let mut out: Vec<(String, String)> = questions
         .values()
         .filter(|q| is_qualified(user.as_ref(), q))
-        // An ended event page is a followup from then on - only a
+        .filter(|q| !is_outcome(q) || earned.contains(&q.id))
-        // visitor carrying a chain (they answered it) still sees it.
-        .filter(|q| !(q.is_followup() || q.event_ended_at(now_ms)) || has_chain)
         // 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.
@@ -2172,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/question_lint.rs

@@ -1,158 +0,0 @@
-//! Headless schema-check binary - loads content and `aggregates.yaml`
-//! (from a Gitea repo URL or a local directory) and validates them
-//! exactly the way `content::watch_for_reload`/`main.rs`'s boot path
-//! do, with no NATS, OIDC, web server, or JetStream connection
-//! involved. Built once by portal's own deploy workflow and run
-//! directly by `questions`' own CI (same bare-metal runner/host,
-//! published to a stable path - no artifact download needed), rather
-//! than compiled there - keeps that repo's CI coupling to "run a
-//! static binary," not "build a Rust workspace."
-#![cfg(feature = "ssr")]
-
-use portal::{aggregates, content};
-
-#[tokio::main]
-async fn main() -> anyhow::Result<()> {
-    let mut args = std::env::args().skip(1);
-    let mut repo: Option<String> = None;
-    let mut branch = "main".to_string();
-    let mut subdir = "questions".to_string();
-    let mut path: Option<String> = None;
-
-    while let Some(arg) = args.next() {
-        match arg.as_str() {
-            "--repo" => repo = args.next(),
-            "--branch" => branch = args.next().unwrap_or(branch),
-            "--subdir" => subdir = args.next().unwrap_or(subdir),
-            "--path" => path = args.next(),
-            other => {
-                eprintln!("unknown argument: {other}");
-                std::process::exit(2);
-            }
-        }
-    }
-
-    let (questions, aggregates_map, site) = if let Some(dir) = path {
-        (load_from_dir(&dir)?, load_aggregates_from_dir(&dir)?, load_site_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)
-    } else {
-        eprintln!(
-            "usage: question-lint --repo <gitea-url> [--branch main] [--subdir questions] | --path <local-dir>"
-        );
-        std::process::exit(2);
-    };
-
-    if let Err(e) = site.validate() {
-        eprintln!("FAIL: {e}");
-        std::process::exit(1);
-    }
-    let aggregates_map = content::with_builtin_aggregates(aggregates_map);
-    match content::validate_questions(&questions, &aggregates_map) {
-        Ok(()) => {
-            // The runtime's own event desk: a repo announcing pages
-            // (Question.event) should read portal_events somewhere, or
-            // "post what happened" tasks pile up unseen. Warn, don't
-            // fail - the runtime creates the records either way.
-            if questions.values().any(|q| q.event.is_some())
-                && !content::bucket_is_read(&questions, content::EVENTS_BUCKET)
-            {
-                eprintln!(
-                    "WARN: pages carry `event:` but no kv resource reads bucket {:?} - add a desk so summaries get posted",
-                    content::EVENTS_BUCKET
-                );
-            }
-            println!(
-                "OK: {} question(s), {} aggregate(s) valid",
-                questions.len(),
-                aggregates_map.len()
-            );
-            Ok(())
-        }
-        Err(e) => {
-            eprintln!("FAIL: {e}");
-            std::process::exit(1);
-        }
-    }
-}
-
-/// 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.
-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.
-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 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(())
-}

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,239 @@
+//! 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 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,9 @@ pub mod aggregates;
 #[cfg(feature = "ssr")]
 pub mod announce;
 
+#[cfg(feature = "ssr")]
+pub mod http;
+
 #[cfg(feature = "ssr")]
 pub mod server;
 

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/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

@@ -147,6 +147,10 @@ a {
 main.loading,
 main.not-found {
   min-height: 60vh;
+  /* svh so wrapper browsers that resize the webview as their toolbar
+     animates (Firefox/Chrome iOS) don't reflow this placeholder - the
+     small viewport is a fixed value. Same ladder as .hero-piece. */
+  min-height: 60svh;
   display: flex;
   flex-direction: column;
   align-items: center;
@@ -368,8 +372,12 @@ main.not-found {
 .alt-image {
   display: block;
   width: 100%;
-  max-height: 14rem;
+  height: auto;
-  object-fit: cover;
+  /* Natural aspect, not a cropped band; a very tall image is still
+     bounded so it can't tower. The deck below overrides for its
+     fixed-height cards. */
+  max-height: 32rem;
+  object-fit: contain;
   border-radius: calc(var(--radius) - 0.3rem);
   margin-bottom: 1.1rem;
 }
@@ -552,6 +560,30 @@ main.not-found {
   border: 0.06rem solid var(--line);
 }
 
+/* Content hint via a markdown image title (`![alt](url "right 9rem")`):
+   float and shrink so text wraps around a portrait. */
+.alt-description img.md-float-left,
+.item-card-description img.md-float-left,
+.feature p img.md-float-left,
+.alt-description img.md-float-right,
+.item-card-description img.md-float-right,
+.feature p img.md-float-right {
+  width: auto;
+  max-width: 45%;
+}
+.alt-description img.md-float-left,
+.item-card-description img.md-float-left,
+.feature p img.md-float-left {
+  float: left;
+  margin: 0.2rem 1.1rem 0.5rem 0;
+}
+.alt-description img.md-float-right,
+.item-card-description img.md-float-right,
+.feature p img.md-float-right {
+  float: right;
+  margin: 0.2rem 0 0.5rem 1.1rem;
+}
+
 .alt-description code,
 .feature p code {
   font-size: 0.9em;
@@ -1013,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);
+}