From 9ca89f3e400d2ce7acd5619c7123c327308060ac Mon Sep 17 00:00:00 2001
From: Mieszko Makuch <m.makuch@cyfronet.pl>
Date: Fri, 11 Sep 2026 13:58:49 +0200
Subject: [PATCH] demo article in English: stack overview and redesigned
 architecture diagrams

---
 README.md                                     |   6 +-
 news/architektura-demo-git-cms.md             | 175 ----------------
 news/how-this-portal-works.md                 | 191 ++++++++++++++++++
 .../diagrams/architecture-cms-database.svg    | 101 +++++++++
 uploads/diagrams/architecture-machine.svg     | 105 ++++++++++
 uploads/diagrams/architektura-cms-z-baza.svg  | 110 ----------
 uploads/diagrams/architektura-maszyna.svg     | 111 ----------
 uploads/diagrams/attack-surface.svg           |  48 +++++
 uploads/diagrams/cover-git-cms.svg            |   2 +-
 uploads/diagrams/od-zapisu-do-publikacji.svg  |  76 -------
 uploads/diagrams/powierzchnia-ataku.svg       |  48 -----
 uploads/diagrams/publish-flow.svg             |  54 +++++
 uploads/diagrams/stack-overview.svg           |  70 +++++++
 13 files changed, 573 insertions(+), 524 deletions(-)
 delete mode 100644 news/architektura-demo-git-cms.md
 create mode 100644 news/how-this-portal-works.md
 create mode 100644 uploads/diagrams/architecture-cms-database.svg
 create mode 100644 uploads/diagrams/architecture-machine.svg
 delete mode 100644 uploads/diagrams/architektura-cms-z-baza.svg
 delete mode 100644 uploads/diagrams/architektura-maszyna.svg
 create mode 100644 uploads/diagrams/attack-surface.svg
 delete mode 100644 uploads/diagrams/od-zapisu-do-publikacji.svg
 delete mode 100644 uploads/diagrams/powierzchnia-ataku.svg
 create mode 100644 uploads/diagrams/publish-flow.svg
 create mode 100644 uploads/diagrams/stack-overview.svg

diff --git a/README.md b/README.md
index 05dadf5..042fb2a 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,18 @@
-# CTAO Science Portal — content
+# CTAO Science Portal: content
 
 Editorial content of the CTAO Science Portal, separated from the portal code
 so editorial history stays clean and publishing never mixes with development.
 
 | Path | What |
 |---|---|
-| `news/*.md` | Articles — Markdown + frontmatter |
+| `news/*.md` | Articles: Markdown with frontmatter |
 | `pages/*.md` | Static pages (contact, privacy, disclaimer) |
 | `uploads/` | Editor-uploaded media (the CMS converts images to WebP) |
 
 ## How to edit
 
 Editors use the visual editor at the portal's `/admin/` page (sign in with a
-Gitea account) — every save is a commit here, and the site republishes
+Gitea account). Every save is a commit here, and the site republishes
 automatically within seconds. Direct git commits work exactly the same way.
 
 The portal code lives in the `ctao-portal` repository; its build overlays
diff --git a/news/architektura-demo-git-cms.md b/news/architektura-demo-git-cms.md
deleted file mode 100644
index ef04678..0000000
--- a/news/architektura-demo-git-cms.md
+++ /dev/null
@@ -1,175 +0,0 @@
----
-title: "Jak działa to demo: portal statyczny + CMS oparty o git"
-description: "Architektura rozwiązania, przydatne linki i porównanie klas rozwiązań: strona w 100% statyczna z graficznym edytorem treści vs CMS z własną bazą danych."
-date: 2026-07-23
-category: demo
-author: Cyfronet
-cover: /uploads/diagrams/cover-git-cms.svg
-lang: pl
-draft: false
----
-
-Ten portal to **statyczne pliki HTML** generowane z plików Markdown trzymanych
-w repozytorium git. Redaktor dostaje **graficzny edytor w przeglądarce** —
-a mimo to **po stronie publicznej** nie działa żadna aplikacja ani baza:
-między czytelnikiem a treścią jest wyłącznie serwer plików. Jedyny działający
-serwis (Gitea) obsługuje edycję i stoi poza ścieżką czytelnika — wracamy do
-tego uczciwie niżej. Ten artykuł został napisany i opublikowany dokładnie tą
-ścieżką.
-
-## Od zapisu do publikacji
-
-![Pięć kroków publikacji: zapis w edytorze → commit w repo → detekcja zmiany → build strony → publikacja](/uploads/diagrams/od-zapisu-do-publikacji.svg)
-
-Publikacja jest automatyczna — zapis w edytorze po chwili sam pojawia się
-na stronie, bez żadnego ręcznego deployu. Każda zmiana to commit, więc
-**pełna historia treści i możliwość cofnięcia są w gicie za darmo**.
-
-## Jak to wygląda na maszynie
-
-![Architektura na maszynie demo: redaktor zapisuje przez Sveltię do Gitei, timer systemd uruchamia jednorazowy kontener builda Astro, wynik trafia do wolumenu releases, a nginx serwuje czytelnikom wyłącznie statyczne pliki](/uploads/diagrams/architektura-maszyna.svg)
-
-Dla porównania — ta sama maszyna z klasycznym CMS-em. Układ diagramu jest
-celowo identyczny, żeby różnice było widać na pierwszy rzut oka: tu każdy
-element działa bez przerwy, a panel logowania i aplikacja są wystawione
-do internetu.
-
-![Architektura klasycznego CMS z bazą danych: aplikacja z publicznym panelem admina i renderowaniem na żądanie działa non stop, obok baza danych wymagająca backupów i wolumen mediów](/uploads/diagrams/architektura-cms-z-baza.svg)
-
-## Gdzie co jest
-
-| Co | Gdzie |
-|---|---|
-| Portal | strona główna tego serwisu |
-| Edytor treści | `/admin/` (link „Content editor" w stopce) |
-| Gitea (repo `ctao/portal`) | port 3000 na maszynie demo |
-| Konto demo | użytkownik `ctao` (hasło u prowadzącego demo) |
-| Dokumentacja wdrożenia | katalog `deploy/` w repo kodu: `README.md` (runbook) |
-
-Całość działa w podmanie na jednej maszynie: kontener Gitei, kontener nginx
-i jednorazowy kontener builda odpalany przez systemd timer.
-
-## Dlaczego strona statyczna
-
-![Porównanie powierzchni ataku: CMS z bazą wystawia publicznie aplikację, panel logowania, bazę i pluginy — tu publiczne są tylko pliki HTML, a edycja idzie przez git dla zalogowanych](/uploads/diagrams/powierzchnia-ataku.svg)
-
-- **Bezpieczeństwo**: publicznie wystawione są tylko pliki. Nie istnieje
-  panel admina dostępny z internetu, baza do wykradzenia ani runtime z CVE.
-- **Utrzymanie**: nie ma aplikacji, która musi być monitorowana i
-  aktualizowana pod presją łatek bezpieczeństwa. Do utrzymania zostaje git
-  (który i tak utrzymujemy) i krótki skrypt builda.
-- **Szybkość**: statyczny HTML to najszybsza możliwa strona — istotne też
-  dla SEO.
-- **Historia**: wersjonowanie treści to naturalna cecha gita, nie płatna
-  funkcja produktu.
-
-## Dwie klasy rozwiązań
-
-Linia podziału jest często mylona: nie chodzi o to, czy treść leży w bazie
-czy w plikach, tylko o to, **czy między czytelnikiem a treścią stoi
-działająca aplikacja**.
-
-| | Statyczne + git-CMS *(to demo)* | CMS serwujący stronę aplikacją |
-|---|---|---|
-| Przykłady | Sveltia, Decap (+ Astro / Hugo / Eleventy) | Strapi, WordPress, Drupal, Grav, TinaCMS |
-| Treść żyje w | plikach Markdown w gicie | zwykle w bazie; Grav — w plikach, Tina — w gicie |
-| W produkcji działa | serwer plików | aplikacja (zwykle + baza), non stop |
-| Utrzymanie | skrypt builda + serwis gitowy | patche, aktualizacje, backupy bazy |
-| Historia zmian | git, wbudowana | zależnie od produktu (bywa płatna) |
-
-Dwa doprecyzowania, żeby tabela nie upraszczała: **Grav** trzyma treść
-w plikach bez żadnej bazy — ale stronę i tak serwuje aplikacja PHP, więc pod
-względem powierzchni ataku i utrzymania należy do prawej kolumny. **TinaCMS**
-trzyma treść wręcz w Markdownie w gicie, ale do działania edytora wymaga
-stale działającego backendu z bazą — jest hybrydą, która dziedziczy koszty
-obu światów.
-
-Ograniczenia poszczególnych rozwiązań, które zweryfikowaliśmy podczas
-researchu:
-
-- **Strapi** — historia wersji treści nie istnieje w darmowym self-hosted
-  (tylko płatne plany Growth/Enterprise). Wymaga stale działającego Node +
-  Postgresa i regularnych aktualizacji.
-- **WordPress** — największy ekosystem, ale i największa historia podatności
-  (głównie pluginy); publiczny panel logowania i PHP do ciągłego patchowania.
-- **Grav** (PHP, flat-file — „lekka" alternatywa) — poważne podatności RCE
-  w ostatnich latach; nadal wymaga serwera PHP wystawionego do internetu.
-- **TinaCMS** — edytuje Markdown, ale wymaga backendu: chmura Tina jest
-  darmowa tylko do 2 użytkowników, a self-hosting to własny serwer Node +
-  baza (Mongo/Postgres) + auth — wracamy do utrzymywania aplikacji.
-- **Ryzyko open-core**: funkcje potrafią z czasem przechodzić do płatnych
-  planów (przykład wyżej). Gdy treść i jej historia leżą w gicie, nie ma
-  funkcji, którą dostawca mógłby przenieść do płatnego planu.
-
-## Plusy i minusy obu podejść
-
-Portal ma być utrzymywany przez co najmniej 6 lat, więc bilans trzeba robić
-w dwóch horyzontach. Poniżej ocena podejść jako klas rozwiązań, nie
-konkretnych produktów.
-
-**Krótkoterminowo (uruchomienie i pierwsze miesiące)**
-
-| | Statyczne + git | CMS z bazą |
-|---|---|---|
-| Plusy | mało ruchomych części od pierwszego dnia; edytor graficzny gotowy; historia i rollback od razu, w gicie | bogatszy panel od ręki: role i uprawnienia, workflow redakcyjny, relacje między treściami, więcej gotowych integracji |
-| Minusy | uprawnienia proste (dziedziczone z gita — bez ról redakcyjnych); przeglądanie historii na razie w interfejsie gita, nie w edytorze | więcej komponentów do postawienia, spięcia i zabezpieczenia od pierwszego dnia (aplikacja, baza, backupy) |
-
-**W horyzoncie 6 lat**
-
-| | Statyczne + git | CMS z bazą |
-|---|---|---|
-| Plusy | strona publiczna bez aplikacji = brak presji łatek na ścieżce czytelnika; do utrzymania zostaje serwis gitowy (najlepiej ten, który zespół i tak ma); treść w otwartym formacie przetrwa każdą wymianę narzędzi | jeśli z czasem będą potrzebne funkcje aplikacyjne (konta, personalizacja, treści silnie strukturalne), platforma już je ma |
-| Minusy | przy bardzo dużej skali (tysiące stron) buildy rosną i wymagają optymalizacji; zaawansowane funkcje redakcyjne zależą od tempa rozwoju narzędzi open-source | kilka dużych migracji wersji w 6 lat (zmiany łamiące); baza wymaga backupów i testów odtwarzania; stała powierzchnia ataku; ryzyko przenoszenia funkcji do płatnych planów |
-
-## „Czy Gitea to nie jest po prostu drugi CMS?"
-
-Uczciwe pytanie: Gitea też ma logowanie, bazę i wymaga aktualizacji
-bezpieczeństwa, a dla edytorów musi być dostępna spoza VPN. Czy różnica nie
-sprowadza się więc do tego, że zamiast CMS-a utrzymujemy Giteę?
-
-Częściowo tak — i dlatego nie twierdzimy, że utrzymanie jest zerowe. Różnica
-polega na trzech rzeczach:
-
-- **Gitea stoi poza ścieżką czytelnika.** Może mieć przerwę, aktualizację,
-  a nawet zostać przejęta — portal dalej stoi i serwuje bezpieczne pliki.
-  Najgorszy scenariusz włamania to wandalizm treści: widoczny, z pełną
-  historią, odwracalny jednym revertem. W CMS-ie serwującym stronę ten sam
-  incydent oznacza przejętą stronę publiczną.
-- **Zespół już utrzymuje Giteę.** Docelowo repozytorium treści może żyć na
-  istniejącej instancji zespołu — wtedy krańcowy koszt utrzymania jest
-  bliski zera, a logowanie załatwia jedna integracja z AAI.
-- **Klasa oprogramowania.** Gitea to pojedynczy program w Go z SQLite:
-  aktualizacja to podmiana obrazu i restart, bez ekosystemu pluginów i bez
-  drzewa zależności npm po stronie serwera. Platformy CMS to frameworki
-  aplikacyjne z regularnymi migracjami głównych wersji.
-
-## Gdzie jeszcze może się przydać
-
-Ten sam wzorzec — edytor graficzny nad repozytorium Markdown — nie jest
-ograniczony do portalu. Naturalni kandydaci u nas:
-
-- **Projekt Mickiewicza** — treści redagowane przez osoby nietechniczne,
-  a publikowane jako strona statyczna.
-- **Dokumentacja Episodes Platform** — już dziś jest w Markdownie; podpięcie
-  edytora dałoby wygodną edycję w przeglądarce zamiast edytora plików
-  w Gitei, bez żadnych zmian w istniejącym repozytorium.
-
-Koszt wdrożenia w takich miejscach jest niewielki: edytor to jeden statyczny
-plik HTML plus konfiguracja wskazująca repozytorium i strukturę treści.
-
-## Brak lock-inu
-
-Każdy element jest wymienialny osobno, bo treść to czysty Markdown:
-
-- **Sveltia ↔ Decap** — ten sam format konfiguracji; podmiana = jedna linijka
-  `<script>`.
-- **Astro ↔ Hugo / Eleventy** — Markdown zostaje bez zmian, wymieniamy tylko
-  szablony.
-- **Gitea ↔ dowolny hosting gitowy** — GitHub, GitLab i inne.
-- Nawet rezygnacja z całego podejścia = eksport trywialny, bo treść od
-  początku leży w otwartym formacie w naszym repozytorium.
-
-Wniosek z tego demo: zaczynamy od najprostszego rozwiązania, które spełnia
-wymagania — graficzny edytor dla redaktorów i bezpieczna, bezobsługowa strona
-publiczna. Złożoność dodajemy dopiero wtedy, gdy pojawi się potrzeba, której
-to podejście nie obsłuży.
diff --git a/news/how-this-portal-works.md b/news/how-this-portal-works.md
new file mode 100644
index 0000000..40c5960
--- /dev/null
+++ b/news/how-this-portal-works.md
@@ -0,0 +1,191 @@
+---
+title: "How this portal works: static pages, a visual editor, git as the database"
+description: "The architecture behind this demo: a visual editor in the browser, content as Markdown in git, and a public site that is nothing but static files. With an honest comparison against database-backed CMS platforms."
+date: 2026-09-11
+category: demo
+author: Cyfronet
+cover: /uploads/diagrams/cover-git-cms.svg
+draft: false
+---
+
+This portal is a set of **static HTML files** generated from Markdown kept in a
+git repository. Editors get a **visual editor in the browser**, and still
+**nothing on the public side runs an application or a database**: between the
+reader and the content there is only a file server. The one service that does
+run, the git server, stands behind the editor and off the reader's path, and we
+come back to that honestly below. This article was written and published
+through exactly the path it describes.
+
+## The stack in three parts
+
+![The three parts of the stack: Sveltia CMS as the editor, git and Gitea as the database, Astro as the build-time generator, with only nginx and static files involved when a reader opens a page](/uploads/diagrams/stack-overview.svg)
+
+**Sveltia CMS is the editor.** It is one JavaScript file served as a static page
+under `/admin/`. It signs the editor in to Gitea and writes Markdown files and
+images straight into the repository through the git API. There is no CMS server
+and no database behind it, and every save is a commit.
+
+**Git, served by Gitea, is the database.** An article is a Markdown file with a
+defined set of fields, and uploaded images sit next to it. History, diffs and a
+one-command rollback come from git itself rather than from a paid tier of a
+product.
+
+**Astro is a generator, not a server.** Its build turns those Markdown files
+into a directory of plain HTML, CSS and images, so deployment is copying that
+directory onto a file server. Nothing from Astro runs in production. Pages ship
+without JavaScript by default, while components, React among them, are rendered
+to HTML during the build, so an interactive dashboard can later be added as an
+island on the same site without changing the stack. The build also checks every
+article against the defined fields, which means a malformed article stops the
+build instead of reaching the public site.
+
+On the reader's side that leaves one moving part: nginx handing over files.
+
+## From a save to a published page
+
+![Five steps of publishing: save in the editor, commit in the repository, change detected, site build, published](/uploads/diagrams/publish-flow.svg)
+
+Publishing is automatic. A save in the editor shows up on the site moments
+later, with no manual deployment step in between. Every change is a commit, so
+**a full content history and a one-command rollback come for free**.
+
+## How it runs on the machine
+
+![Architecture on the demo machine: the editor writes through Sveltia into the Gitea content repository, a systemd timer runs a one-shot Astro build container, the result lands in the releases volume and nginx serves readers static files only](/uploads/diagrams/architecture-machine.svg)
+
+Two repositories, by design. The portal **code** is developed by the team, the
+editorial **content** is written by the CMS. Every build takes the newest commit
+from both, overlays content onto code and renders the site, so a push to either
+repository republishes. Editors never touch the code repository, and
+development never mixes with the editorial history.
+
+Everything runs rootless in podman on a single machine: a Gitea container, an
+nginx container, and a one-shot build container started by a systemd timer. A
+build that fails changes nothing, because the previous release keeps serving.
+
+For comparison, the same machine running a classic CMS. The diagram keeps the
+same skeleton on purpose, so the difference is visible at a glance: every
+element is up around the clock, the editor and the reader talk to the very same
+application, and its login panel faces the internet.
+
+![Architecture of a database-backed CMS: an application with a public admin panel and on-demand rendering runs non stop, next to a database that needs backups and a separate media volume](/uploads/diagrams/architecture-cms-database.svg)
+
+## Where things are
+
+| What | Where |
+|---|---|
+| Portal | this site |
+| Content editor | `/admin/`, the "Content editor" link in the footer |
+| Content repository | `ctao/content` on the demo machine's Gitea, written by the CMS |
+| Code repository | `ctao/portal`, maintained by the team |
+| Deployment documentation | `deploy/README.md` in the code repository |
+
+## Why a static site
+
+![Attack surface compared: a database-backed CMS exposes an application, a login panel, a database and plugins, while this solution exposes static HTML files only and keeps editing behind a git sign-in](/uploads/diagrams/attack-surface.svg)
+
+- **Security.** What faces the internet is a file server and a directory of
+  files. There is no admin panel to attack, no database to exfiltrate and no
+  application runtime carrying its own vulnerabilities.
+- **Maintenance.** There is no application that has to be monitored and upgraded
+  under patch pressure. What remains is a git service, which the team runs
+  anyway, and a short build script.
+- **Speed.** Static HTML is as fast as a page gets, which search engines reward
+  as well.
+- **History.** Versioning is a property of git, not a feature tier of a product.
+
+## Two classes of solution
+
+The dividing line is often misread. The question is not whether content sits in
+a database or in files. It is **whether a running application stands between the
+reader and the content**.
+
+| | Static + git CMS *(this demo)* | CMS that serves the site itself |
+|---|---|---|
+| Examples | Sveltia, Decap (+ Astro / Hugo / Eleventy) | Strapi, WordPress, Drupal, Grav, TinaCMS |
+| Content lives in | Markdown files in git | usually a database; Grav in files, Tina in git |
+| In production you run | a file server | an application, usually with a database, non stop |
+| Maintenance | a build script plus a git service | patches, upgrades, database backups |
+| Change history | git, built in | product-dependent, sometimes paid |
+
+Two clarifications, so the table is not read too simply. **Grav** keeps content
+in files with no database at all, yet a PHP application still serves every page,
+which puts it in the right-hand column for attack surface and maintenance.
+**TinaCMS** keeps content as Markdown in git, but its editor needs a backend
+with a database in order to work, so it inherits the costs of both worlds.
+
+Limits of the individual products, verified during our research:
+
+- **Strapi**: content version history does not exist in the free self-hosted
+  edition (Growth and Enterprise plans only). It needs Node and PostgreSQL
+  running at all times, plus regular upgrades.
+- **WordPress**: the largest ecosystem, and also the longest vulnerability
+  history, mostly through plugins; a public login panel and PHP to patch
+  continuously.
+- **Grav** (PHP, flat file, the "light" alternative): serious remote code
+  execution issues in recent years, and still a PHP server facing the internet.
+- **TinaCMS**: it edits Markdown, but it requires a backend. The Tina cloud is
+  free for up to two users, and self-hosting means your own Node server, a
+  database and authentication, which is an application to maintain again.
+- **Open-core risk**: features can move into paid plans over time, as above.
+  When the content and its history live in git, there is no feature a vendor
+  can move behind a paywall.
+
+## Trade-offs over six years
+
+The portal is meant to be maintained for at least six years, so the balance has
+to be drawn over two horizons. What follows judges the two approaches as classes
+of solution, not individual products.
+
+**Short term: launch and the first months**
+
+| | Static + git | CMS with a database |
+|---|---|---|
+| Strengths | few moving parts from day one; a visual editor ready to use; history and rollback immediately, in git | a richer panel out of the box: roles and permissions, editorial workflow, relations between content types, more ready-made integrations |
+| Weaknesses | simple permissions, inherited from git, without editorial roles; browsing history happens in the git interface rather than in the editor | more components to stand up, connect and secure from day one: application, database, backups |
+
+**Over six years**
+
+| | Static + git | CMS with a database |
+|---|---|---|
+| Strengths | no application on the reader's path, so no patch pressure there; what stays is a git service, ideally the one the team already runs; content in an open format survives any change of tooling | if application features are eventually needed (accounts, personalisation, strongly structured content), the platform already has them |
+| Weaknesses | at very large scale (thousands of pages) build times grow and need attention; advanced editorial features depend on the pace of open-source tools | several major version migrations in six years, with breaking changes; the database needs backups and restore drills; a permanent attack surface; features can move into paid tiers |
+
+## "Isn't Gitea just another CMS?"
+
+A fair question. Gitea also has a login, a database and security updates, and it
+has to be reachable by editors. Does the difference come down to maintaining
+Gitea instead of a CMS?
+
+Partly yes, and we do not claim that maintenance is zero. The difference rests
+on three things:
+
+- **Gitea is off the reader's path.** It can be down, mid-upgrade, or even
+  compromised while the portal keeps serving safe files. The worst case of a
+  break-in is content vandalism: visible, fully recorded, and undone with a
+  single revert. In a CMS that serves the site, the same incident means a
+  compromised public site.
+- **The team already runs Gitea.** The content repository can live on the
+  instance the team maintains anyway, which brings the marginal cost close to
+  zero and lets one AAI integration handle sign-in.
+- **Class of software.** Gitea is a single Go program with SQLite: an upgrade is
+  swapping an image and restarting, with no plugin ecosystem and no server-side
+  npm dependency tree. CMS platforms are application frameworks with regular
+  major-version migrations.
+
+## No lock-in
+
+Every element can be replaced on its own, because the content is plain Markdown:
+
+- **Sveltia to Decap**: the same configuration format, so switching is one
+  script tag.
+- **Astro to Hugo or Eleventy**: the Markdown stays untouched, only templates
+  change.
+- **Gitea to any git hosting**: GitHub, GitLab, or an internal service.
+- Even dropping the whole approach is a trivial export, because the content has
+  been sitting in an open format in our own repository from the start.
+
+The conclusion we draw from this demo: start with the simplest solution that
+meets the requirements, which means a visual editor for the editors and a public
+site that needs no care. Add complexity only when a need appears that this
+approach cannot serve.
diff --git a/uploads/diagrams/architecture-cms-database.svg b/uploads/diagrams/architecture-cms-database.svg
new file mode 100644
index 0000000..19a164d
--- /dev/null
+++ b/uploads/diagrams/architecture-cms-database.svg
@@ -0,0 +1,101 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 800" role="img" aria-label="Architecture of a database-backed CMS: one always-on application serves both the editor's admin panel and the reader's pages, backed by a database that needs backups and a separate media volume">
+  <defs>
+    <marker id="arrB" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10 z" fill="#00004a"/>
+    </marker>
+    <filter id="softB" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="2" stdDeviation="5" flood-color="#00004a" flood-opacity="0.10"/>
+    </filter>
+    <style>
+      .t   { font-family: Inter, "Segoe UI", Arial, sans-serif; }
+      .box { fill: #ffffff; stroke: #00004a; stroke-width: 1.5; }
+      .sub { fill: #f5f5f5; stroke: #e2e5ee; stroke-width: 1; }
+      .ttl { font-weight: 700; font-size: 19px; fill: #00004a; letter-spacing: .04em; }
+      .act { font-weight: 700; font-size: 18px; fill: #00004a; }
+      .cap { font-size: 15px; fill: #46536a; }
+      .sml { font-size: 14px; fill: #46536a; }
+      .lbl { font-size: 14px; fill: #46536a; paint-order: stroke; stroke: #f8f9fc; stroke-width: 5; }
+      .chipbg { fill: #e9ebf3; }
+      .chip { font-size: 12.5px; font-weight: 700; fill: #00004a; letter-spacing: .06em; }
+      .flow { stroke: #00004a; stroke-width: 1.8; fill: none; marker-end: url(#arrB); }
+      .name { font-size: 16px; font-weight: 700; fill: #101228; }
+      .pill { fill: #f5f5f5; stroke: #e2e5ee; }
+      .pilltxt { font-size: 14px; fill: #101228; }
+    </style>
+  </defs>
+
+  <!-- actor: editor -->
+  <g filter="url(#softB)"><rect class="box" x="49" y="20" width="380" height="86" rx="16"/></g>
+  <circle cx="80" cy="48" r="11" fill="none" stroke="#00004a" stroke-width="1.8"/>
+  <path d="M64 78 q16 -18 32 0" fill="none" stroke="#00004a" stroke-width="1.8"/>
+  <text class="t act" x="108" y="54">Editor</text>
+  <text class="t sml" x="108" y="80">admin panel in the browser, signs in</text>
+
+  <!-- actor: reader -->
+  <g filter="url(#softB)"><rect class="box" x="395" y="20" width="380" height="86" rx="16"/></g>
+  <circle cx="426" cy="48" r="11" fill="none" stroke="#00004a" stroke-width="1.8"/>
+  <path d="M410 78 q16 -18 32 0" fill="none" stroke="#00004a" stroke-width="1.8"/>
+  <text class="t act" x="454" y="54">Reader</text>
+  <text class="t sml" x="454" y="80">the public portal, assembled live</text>
+
+  <!-- machine boundary (same vertical skeleton as the static diagram) -->
+  <rect x="30" y="158" width="740" height="560" rx="18" fill="#f8f9fc" stroke="#e2e5ee" stroke-width="1.5"/>
+  <text class="t" x="400" y="194" text-anchor="middle" font-size="14" font-weight="700" fill="#00004a" letter-spacing=".18em">MACHINE · DATABASE-BACKED CMS</text>
+  <text class="t sml" x="400" y="216" text-anchor="middle">WordPress, Strapi, Drupal and the like</text>
+
+  <path class="flow" d="M239 106 V232"/>
+  <text class="t lbl" x="253" y="150">sign in to the panel</text>
+  <path class="flow" d="M585 232 V110"/>
+  <text class="t lbl" x="599" y="150">HTML built per request</text>
+
+  <!-- the application: always on, serves everybody -->
+  <g filter="url(#softB)"><rect class="box" x="60" y="238" width="680" height="210" rx="16"/></g>
+  <text class="t ttl" x="88" y="278">CMS APPLICATION</text>
+  <rect class="chipbg" x="290" y="258" width="110" height="24" rx="12"/>
+  <text class="t chip" x="345" y="275" text-anchor="middle">ALWAYS ON</text>
+  <rect class="sub" x="84" y="298" width="204" height="130" rx="12"/>
+  <text class="t name" x="104" y="330">admin panel</text>
+  <text class="t cap" x="104" y="356">public address</text>
+  <text class="t cap" x="104" y="378">and login, open</text>
+  <text class="t cap" x="104" y="400">to the internet</text>
+  <rect class="sub" x="298" y="298" width="204" height="130" rx="12"/>
+  <text class="t name" x="318" y="330">page rendering</text>
+  <text class="t cap" x="318" y="356">every visit is</text>
+  <text class="t cap" x="318" y="378">work for the app</text>
+  <text class="t cap" x="318" y="400">and the database</text>
+  <rect class="sub" x="512" y="298" width="204" height="130" rx="12"/>
+  <text class="t name" x="532" y="330">plugins</text>
+  <text class="t cap" x="532" y="356">each with its own</text>
+  <text class="t cap" x="532" y="378">update cycle and</text>
+  <text class="t cap" x="532" y="400">its own bugs</text>
+
+  <path class="flow" d="M239 448 V504"/>
+  <text class="t lbl" x="253" y="484">upload</text>
+  <path class="flow" d="M585 448 V504"/>
+  <text class="t lbl" x="599" y="484">SQL</text>
+
+  <!-- media volume -->
+  <g filter="url(#softB)"><rect class="sub" x="60" y="508" width="310" height="170" rx="16"/></g>
+  <text class="t ttl" x="88" y="546">media/</text>
+  <rect class="chipbg" x="180" y="526" width="86" height="24" rx="12"/>
+  <text class="t chip" x="223" y="543" text-anchor="middle">VOLUME</text>
+  <text class="t cap" x="88" y="582">images and files</text>
+  <text class="t cap" x="88" y="606">outside the database</text>
+  <text class="t cap" x="88" y="630">backed up separately</text>
+
+  <!-- database -->
+  <g filter="url(#softB)"><rect class="box" x="430" y="508" width="310" height="170" rx="16"/></g>
+  <text class="t ttl" x="458" y="546">DATABASE</text>
+  <rect class="chipbg" x="590" y="526" width="110" height="24" rx="12"/>
+  <text class="t chip" x="645" y="543" text-anchor="middle">ALWAYS ON</text>
+  <text class="t cap" x="458" y="582">content and accounts</text>
+  <text class="t cap" x="458" y="606">backups and restore drills</text>
+  <text class="t cap" x="458" y="630">schema migrations</text>
+  <text class="t cap" x="458" y="654">on every upgrade</text>
+
+  <!-- summary pills -->
+  <rect class="pill" x="60" y="740" width="330" height="46" rx="23"/>
+  <text class="t pilltxt" x="225" y="768" text-anchor="middle">two processes run non stop, day and night</text>
+  <rect class="pill" x="410" y="740" width="330" height="46" rx="23"/>
+  <text class="t pilltxt" x="575" y="768" text-anchor="middle">security updates are a standing duty</text>
+</svg>
diff --git a/uploads/diagrams/architecture-machine.svg b/uploads/diagrams/architecture-machine.svg
new file mode 100644
index 0000000..1e4133f
--- /dev/null
+++ b/uploads/diagrams/architecture-machine.svg
@@ -0,0 +1,105 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 1040" role="img" aria-label="Architecture on the demo machine: the editor writes through Sveltia into the Gitea content repository, a systemd timer runs a one-shot Astro build container that overlays content onto the code repository, the result lands in the releases volume and nginx serves readers static files only">
+  <defs>
+    <marker id="arr" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10 z" fill="#00004a"/>
+    </marker>
+    <filter id="soft" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="2" stdDeviation="5" flood-color="#00004a" flood-opacity="0.10"/>
+    </filter>
+    <style>
+      .t   { font-family: Inter, "Segoe UI", Arial, sans-serif; }
+      .box { fill: #ffffff; stroke: #00004a; stroke-width: 1.5; }
+      .sub { fill: #f5f5f5; stroke: #e2e5ee; stroke-width: 1; }
+      .ttl { font-weight: 700; font-size: 19px; fill: #00004a; letter-spacing: .04em; }
+      .act { font-weight: 700; font-size: 18px; fill: #00004a; }
+      .cap { font-size: 15px; fill: #46536a; }
+      .sml { font-size: 14px; fill: #46536a; }
+      .lbl { font-size: 14px; fill: #46536a; paint-order: stroke; stroke: #f8f9fc; stroke-width: 5; }
+      .chipbg { fill: #d2faf7; }
+      .chip { font-size: 12.5px; font-weight: 700; fill: #00004a; letter-spacing: .06em; }
+      .flow { stroke: #00004a; stroke-width: 1.8; fill: none; marker-end: url(#arr); }
+      .mono { font-family: "SF Mono", Consolas, Menlo, monospace; font-size: 14px; fill: #101228; }
+      .name { font-size: 16px; font-weight: 700; fill: #101228; }
+    </style>
+  </defs>
+
+  <!-- actor: editor -->
+  <g filter="url(#soft)"><rect class="box" x="49" y="20" width="380" height="86" rx="16"/></g>
+  <circle cx="80" cy="48" r="11" fill="none" stroke="#00004a" stroke-width="1.8"/>
+  <path d="M64 78 q16 -18 32 0" fill="none" stroke="#00004a" stroke-width="1.8"/>
+  <text class="t act" x="108" y="54">Editor</text>
+  <text class="t sml" x="108" y="80">browser · <tspan font-weight="600">/admin/</tspan> (Sveltia), visual editing</text>
+
+  <!-- machine boundary -->
+  <rect x="30" y="158" width="740" height="730" rx="18" fill="#f8f9fc" stroke="#e2e5ee" stroke-width="1.5"/>
+  <text class="t" x="400" y="194" text-anchor="middle" font-size="14" font-weight="700" fill="#00004a" letter-spacing=".18em">DEMO MACHINE · PODMAN</text>
+  <text class="t sml" x="400" y="216" text-anchor="middle">separate containers under systemd</text>
+
+  <path class="flow" d="M239 106 V232"/>
+  <text class="t lbl" x="253" y="150">save through the API (OAuth)</text>
+
+  <!-- gitea: two repositories -->
+  <g filter="url(#soft)"><rect class="box" x="60" y="238" width="680" height="190" rx="16"/></g>
+  <text class="t ttl" x="88" y="278">GITEA</text>
+  <rect class="chipbg" x="170" y="258" width="62" height="24" rx="12"/>
+  <text class="t chip" x="201" y="275" text-anchor="middle">:3000</text>
+  <rect class="sub" x="84" y="298" width="310" height="108" rx="12"/>
+  <text class="t name" x="106" y="330">ctao/content</text>
+  <text class="t cap" x="106" y="356">Markdown and images,</text>
+  <text class="t cap" x="106" y="380">written by the CMS</text>
+  <rect class="sub" x="414" y="298" width="302" height="108" rx="12"/>
+  <text class="t name" x="436" y="330">ctao/portal</text>
+  <text class="t cap" x="436" y="356">portal code,</text>
+  <text class="t cap" x="436" y="380">maintained by the team</text>
+
+  <path class="flow" d="M400 428 V454"/>
+  <text class="t lbl" x="414" y="447">git fetch, both repos</text>
+
+  <!-- build (ephemeral) -->
+  <g filter="url(#soft)">
+    <rect x="60" y="460" width="680" height="190" rx="16" fill="#ffffff" stroke="#00004a" stroke-width="1.5" stroke-dasharray="7 5"/>
+  </g>
+  <text class="t ttl" x="88" y="500">BUILD · ASTRO</text>
+  <rect class="chipbg" x="250" y="480" width="190" height="24" rx="12"/>
+  <text class="t chip" x="345" y="497" text-anchor="middle">ONE-SHOT CONTAINER</text>
+  <text class="t cap" x="88" y="536">a systemd timer checks both repositories every 10 seconds</text>
+  <text class="t cap" x="88" y="564">on a change: fetch both, overlay content onto code</text>
+  <text class="t cap" x="88" y="592" font-weight="700" fill="#101228">Markdown becomes static HTML</text>
+  <text class="t cap" x="88" y="620">the container exits when the build is done</text>
+
+  <path class="flow" d="M400 650 V676"/>
+  <text class="t lbl" x="414" y="669">new version of the site</text>
+
+  <!-- releases volume -->
+  <g filter="url(#soft)"><rect class="sub" x="60" y="682" width="310" height="176" rx="16"/></g>
+  <text class="t ttl" x="88" y="720">releases/</text>
+  <rect class="chipbg" x="196" y="700" width="86" height="24" rx="12"/>
+  <text class="t chip" x="239" y="717" text-anchor="middle">VOLUME</text>
+  <text class="t mono" x="88" y="754">9f2c1d-43e2bb/  previous</text>
+  <text class="t mono" x="88" y="778">71b980-8c1a2f/ <tspan font-weight="700" fill="#00004a">← current</tspan></text>
+  <text class="t cap" x="88" y="812">atomic swap,</text>
+  <text class="t cap" x="88" y="836">zero downtime</text>
+
+  <!-- nginx -->
+  <g filter="url(#soft)"><rect class="box" x="430" y="682" width="310" height="176" rx="16"/></g>
+  <text class="t ttl" x="458" y="720">NGINX</text>
+  <rect class="chipbg" x="540" y="700" width="62" height="24" rx="12"/>
+  <text class="t chip" x="571" y="717" text-anchor="middle">:8080</text>
+  <text class="t cap" x="458" y="754">serves <tspan font-weight="600">releases/current</tspan></text>
+  <text class="t cap" x="458" y="782">static files only</text>
+  <text class="t cap" x="458" y="810">no application, no database,</text>
+  <text class="t cap" x="458" y="836">no PHP, no plugins</text>
+
+  <path class="flow" d="M372 770 H424"/>
+  <text class="t lbl" x="398" y="756" text-anchor="middle">current/</text>
+
+  <path class="flow" d="M585 860 V930"/>
+  <text class="t lbl" x="599" y="900">static HTML</text>
+
+  <!-- actor: reader -->
+  <g filter="url(#soft)"><rect class="box" x="395" y="940" width="380" height="86" rx="16"/></g>
+  <circle cx="426" cy="968" r="11" fill="none" stroke="#00004a" stroke-width="1.8"/>
+  <path d="M410 998 q16 -18 32 0" fill="none" stroke="#00004a" stroke-width="1.8"/>
+  <text class="t act" x="454" y="974">Reader</text>
+  <text class="t sml" x="454" y="1000">the public portal, plain and fast HTML</text>
+</svg>
diff --git a/uploads/diagrams/architektura-cms-z-baza.svg b/uploads/diagrams/architektura-cms-z-baza.svg
deleted file mode 100644
index 8b4db31..0000000
--- a/uploads/diagrams/architektura-cms-z-baza.svg
+++ /dev/null
@@ -1,110 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 640" role="img" aria-label="Architektura klasycznego CMS z bazą danych: aplikacja CMS z publicznym panelem admina działa non stop, obok baza danych i wolumen mediów; czytelnik dostaje strony renderowane na żądanie">
-  <defs>
-    <marker id="arrB" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
-      <path d="M0 0 L10 5 L0 10 z" fill="#00004a"/>
-    </marker>
-    <filter id="softB" x="-20%" y="-20%" width="140%" height="140%">
-      <feDropShadow dx="0" dy="2" stdDeviation="5" flood-color="#00004a" flood-opacity="0.10"/>
-    </filter>
-    <style>
-      .t   { font-family: Inter, "Segoe UI", Arial, sans-serif; }
-      .box { fill: #ffffff; stroke: #00004a; stroke-width: 1.5; }
-      .sub { fill: #f5f5f5; stroke: #e2e5ee; stroke-width: 1; }
-      .ttl { font-weight: 700; font-size: 15.5px; fill: #00004a; letter-spacing: .04em; }
-      .cap { font-size: 12.5px; fill: #46536a; }
-      .lbl { font-size: 12px; fill: #46536a; paint-order: stroke; stroke: #ffffff; stroke-width: 4; }
-      .chipbg { fill: #e9ebf3; }
-      .chip { font-size: 11.5px; font-weight: 700; fill: #00004a; letter-spacing: .06em; }
-      .flow { stroke: #00004a; stroke-width: 1.8; fill: none; marker-end: url(#arrB); }
-      .pill { fill: #f5f5f5; stroke: #e2e5ee; }
-      .pilltxt { font-size: 12.5px; fill: #101228; }
-    </style>
-  </defs>
-
-  <!-- machine boundary (mirrors the static-demo diagram 1:1) -->
-  <rect x="340" y="40" width="830" height="570" rx="18" fill="#f8f9fc" stroke="#e2e5ee" stroke-width="1.5"/>
-  <text class="t" x="366" y="76" font-size="13" font-weight="700" fill="#00004a" letter-spacing=".18em">MASZYNA · CMS Z BAZĄ DANYCH</text>
-  <text class="t cap" x="366" y="96">np. WordPress, Strapi, Drupal — wspólny schemat tej klasy rozwiązań</text>
-
-  <!-- actor: redaktor -->
-  <g filter="url(#softB)">
-    <rect class="box" x="52" y="120" width="220" height="120" rx="16"/>
-  </g>
-  <circle cx="88" cy="156" r="11" fill="none" stroke="#00004a" stroke-width="1.8"/>
-  <path d="M72 186 q16 -18 32 0" fill="none" stroke="#00004a" stroke-width="1.8"/>
-  <text class="t ttl" x="116" y="162">Redaktor</text>
-  <text class="t cap" x="70" y="212">panel admina w przeglądarce</text>
-  <text class="t cap" x="70" y="228">logowanie do aplikacji</text>
-
-  <!-- actor: czytelnik -->
-  <g filter="url(#softB)">
-    <rect class="box" x="52" y="400" width="220" height="120" rx="16"/>
-  </g>
-  <circle cx="88" cy="436" r="11" fill="none" stroke="#00004a" stroke-width="1.8"/>
-  <path d="M72 466 q16 -18 32 0" fill="none" stroke="#00004a" stroke-width="1.8"/>
-  <text class="t ttl" x="116" y="442">Czytelnik</text>
-  <text class="t cap" x="70" y="492">publiczna strona portalu</text>
-  <text class="t cap" x="70" y="508">HTML składany na żądanie</text>
-
-  <!-- CMS application (tall box, always running) -->
-  <g filter="url(#softB)">
-    <rect class="box" x="400" y="120" width="320" height="400" rx="16"/>
-  </g>
-  <text class="t ttl" x="424" y="152">APLIKACJA CMS</text>
-  <rect class="chipbg" x="590" y="136" width="106" height="22" rx="11"/>
-  <text class="t chip" x="643" y="151" text-anchor="middle">NON STOP</text>
-  <rect class="sub" x="420" y="176" width="280" height="88" rx="12"/>
-  <text class="t" x="436" y="202" font-size="13.5" font-weight="700" fill="#101228">panel admina</text>
-  <text class="t cap" x="436" y="224">publiczny adres + logowanie</text>
-  <text class="t cap" x="436" y="242">z internetu</text>
-  <rect class="sub" x="420" y="278" width="280" height="88" rx="12"/>
-  <text class="t" x="436" y="304" font-size="13.5" font-weight="700" fill="#101228">renderowanie stron</text>
-  <text class="t cap" x="436" y="326">każde wejście czytelnika =</text>
-  <text class="t cap" x="436" y="344">praca aplikacji i bazy</text>
-  <rect class="sub" x="420" y="380" width="280" height="88" rx="12"/>
-  <text class="t" x="436" y="406" font-size="13.5" font-weight="700" fill="#101228">pluginy / rozszerzenia</text>
-  <text class="t cap" x="436" y="428">własny cykl aktualizacji</text>
-  <text class="t cap" x="436" y="446">i podatności</text>
-
-  <!-- database -->
-  <g filter="url(#softB)">
-    <rect class="box" x="790" y="120" width="340" height="185" rx="16"/>
-  </g>
-  <text class="t ttl" x="814" y="152">BAZA DANYCH</text>
-  <rect class="chipbg" x="972" y="136" width="106" height="22" rx="11"/>
-  <text class="t chip" x="1025" y="151" text-anchor="middle">NON STOP</text>
-  <text class="t cap" x="814" y="188">treść + konta użytkowników</text>
-  <text class="t cap" x="814" y="212">wymaga backupów i testów odtwarzania</text>
-  <text class="t cap" x="814" y="236">migracje schematu przy aktualizacjach</text>
-  <text class="t cap" x="814" y="266">historia zmian: zależnie od produktu,</text>
-  <text class="t cap" x="814" y="284">bywa funkcją płatną</text>
-
-  <!-- media volume -->
-  <g filter="url(#softB)">
-    <rect class="sub" x="790" y="400" width="340" height="120" rx="16"/>
-  </g>
-  <text class="t ttl" x="814" y="432">media/</text>
-  <rect class="chipbg" x="896" y="416" width="82" height="22" rx="11"/>
-  <text class="t chip" x="937" y="431" text-anchor="middle">WOLUMEN</text>
-  <text class="t cap" x="814" y="462">obrazy i pliki poza bazą</text>
-  <text class="t cap" x="814" y="480">osobny backup</text>
-
-  <!-- flows -->
-  <path class="flow" d="M272 180 H396"/>
-  <text class="t lbl" x="334" y="170" text-anchor="middle">logowanie do panelu</text>
-
-  <path class="flow" d="M400 460 H276"/>
-  <text class="t lbl" x="338" y="450" text-anchor="middle">HTML na żądanie</text>
-
-  <path class="flow" d="M720 212 H786"/>
-  <text class="t lbl" x="753" y="202" text-anchor="middle">SQL</text>
-
-  <path class="flow" d="M720 440 H786"/>
-  <text class="t lbl" x="753" y="430" text-anchor="middle">upload</text>
-
-  <!-- summary pills -->
-  <rect class="pill" x="380" y="552" width="360" height="36" rx="18"/>
-  <text class="t pilltxt" x="560" y="575" text-anchor="middle">2 procesy działają bez przerwy, także nocą</text>
-  <rect class="pill" x="770" y="552" width="360" height="36" rx="18"/>
-  <text class="t pilltxt" x="950" y="575" text-anchor="middle">aktualizacje bezpieczeństwa = stały obowiązek</text>
-</svg>
diff --git a/uploads/diagrams/architektura-maszyna.svg b/uploads/diagrams/architektura-maszyna.svg
deleted file mode 100644
index bda902b..0000000
--- a/uploads/diagrams/architektura-maszyna.svg
+++ /dev/null
@@ -1,111 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 640" role="img" aria-label="Architektura demo na maszynie: redaktor i czytelnik łączą się z kontenerami podmana — Gitea, build Astro, wolumen releases i nginx">
-  <defs>
-    <marker id="arr" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
-      <path d="M0 0 L10 5 L0 10 z" fill="#00004a"/>
-    </marker>
-    <filter id="soft" x="-20%" y="-20%" width="140%" height="140%">
-      <feDropShadow dx="0" dy="2" stdDeviation="5" flood-color="#00004a" flood-opacity="0.10"/>
-    </filter>
-    <style>
-      .t   { font-family: Inter, "Segoe UI", Arial, sans-serif; }
-      .box { fill: #ffffff; stroke: #00004a; stroke-width: 1.5; }
-      .sub { fill: #f5f5f5; stroke: #e2e5ee; stroke-width: 1; }
-      .ttl { font-weight: 700; font-size: 15.5px; fill: #00004a; letter-spacing: .04em; }
-      .cap { font-size: 12.5px; fill: #46536a; }
-      .lbl { font-size: 12px; fill: #46536a; paint-order: stroke; stroke: #ffffff; stroke-width: 4; }
-      .chipbg { fill: #d2faf7; }
-      .chip { font-size: 11.5px; font-weight: 700; fill: #00004a; letter-spacing: .06em; }
-      .flow { stroke: #00004a; stroke-width: 1.8; fill: none; marker-end: url(#arr); }
-      .mono { font-family: "SF Mono", Consolas, Menlo, monospace; font-size: 12.5px; fill: #101228; }
-    </style>
-  </defs>
-
-  <!-- machine boundary -->
-  <rect x="340" y="40" width="830" height="570" rx="18" fill="#f8f9fc" stroke="#e2e5ee" stroke-width="1.5"/>
-  <text class="t" x="366" y="76" font-size="13" font-weight="700" fill="#00004a" letter-spacing=".18em">MASZYNA DEMO · PODMAN</text>
-  <text class="t cap" x="366" y="96">osobne kontenery pod systemd · wszystko w jednym katalogu użytkownika</text>
-
-  <!-- actor: redaktor -->
-  <g filter="url(#soft)">
-    <rect class="box" x="52" y="120" width="220" height="120" rx="16"/>
-  </g>
-  <circle cx="88" cy="156" r="11" fill="none" stroke="#00004a" stroke-width="1.8"/>
-  <path d="M72 186 q16 -18 32 0" fill="none" stroke="#00004a" stroke-width="1.8"/>
-  <text class="t ttl" x="116" y="162">Redaktor</text>
-  <text class="t cap" x="70" y="212">przeglądarka · <tspan font-weight="600">/admin/</tspan> (Sveltia)</text>
-  <text class="t cap" x="70" y="228">edycja WYSIWYG, podgląd 1:1</text>
-
-  <!-- actor: czytelnik -->
-  <g filter="url(#soft)">
-    <rect class="box" x="52" y="400" width="220" height="120" rx="16"/>
-  </g>
-  <circle cx="88" cy="436" r="11" fill="none" stroke="#00004a" stroke-width="1.8"/>
-  <path d="M72 466 q16 -18 32 0" fill="none" stroke="#00004a" stroke-width="1.8"/>
-  <text class="t ttl" x="116" y="442">Czytelnik</text>
-  <text class="t cap" x="70" y="492">publiczna strona portalu</text>
-  <text class="t cap" x="70" y="508">czysty, szybki HTML</text>
-
-  <!-- gitea -->
-  <g filter="url(#soft)">
-    <rect class="box" x="400" y="120" width="320" height="185" rx="16"/>
-  </g>
-  <text class="t ttl" x="424" y="152">GITEA</text>
-  <rect class="chipbg" x="490" y="136" width="52" height="22" rx="11"/>
-  <text class="t chip" x="516" y="151" text-anchor="middle">:3000</text>
-  <rect class="sub" x="420" y="172" width="280" height="112" rx="12"/>
-  <text class="t" x="436" y="198" font-size="13.5" font-weight="700" fill="#101228">repo ctao/portal</text>
-  <text class="t cap" x="436" y="220">treść: Markdown + obrazy (WebP)</text>
-  <text class="t cap" x="436" y="238">każda zmiana = commit</text>
-  <text class="t cap" x="436" y="256">pełna historia + rollback za darmo</text>
-
-  <!-- build (ephemeral) -->
-  <g filter="url(#soft)">
-    <rect x="790" y="120" width="340" height="185" rx="16" fill="#ffffff" stroke="#00004a" stroke-width="1.5" stroke-dasharray="7 5"/>
-  </g>
-  <text class="t ttl" x="814" y="152">BUILD · ASTRO</text>
-  <rect class="chipbg" x="948" y="136" width="164" height="22" rx="11"/>
-  <text class="t chip" x="1030" y="151" text-anchor="middle">KONTENER JEDNORAZOWY</text>
-  <text class="t cap" x="814" y="188">timer systemd (co ~10 s) sprawdza,</text>
-  <text class="t cap" x="814" y="206">czy w repo jest nowy commit</text>
-  <text class="t cap" x="814" y="234">jeśli tak: git fetch → checkout →</text>
-  <text class="t cap" x="814" y="252"><tspan font-weight="700" fill="#101228">Markdown → statyczny HTML</tspan></text>
-  <text class="t cap" x="814" y="280">po buildzie kontener znika</text>
-
-  <!-- releases volume -->
-  <g filter="url(#soft)">
-    <rect class="sub" x="790" y="400" width="340" height="150" rx="16"/>
-  </g>
-  <text class="t ttl" x="814" y="432">releases/</text>
-  <rect class="chipbg" x="908" y="416" width="82" height="22" rx="11"/>
-  <text class="t chip" x="949" y="431" text-anchor="middle">WOLUMEN</text>
-  <text class="t mono" x="814" y="466">9f2c1d/   poprzednia wersja</text>
-  <text class="t mono" x="814" y="488">71b980/ <tspan font-weight="700" fill="#00004a">← current (symlink)</tspan></text>
-  <text class="t cap" x="814" y="518">podmiana atomowa — zero przestoju</text>
-
-  <!-- nginx -->
-  <g filter="url(#soft)">
-    <rect class="box" x="400" y="400" width="320" height="150" rx="16"/>
-  </g>
-  <text class="t ttl" x="424" y="432">NGINX</text>
-  <rect class="chipbg" x="500" y="416" width="52" height="22" rx="11"/>
-  <text class="t chip" x="526" y="431" text-anchor="middle">:8080</text>
-  <text class="t cap" x="424" y="466">serwuje <tspan font-weight="600">releases/current</tspan></text>
-  <text class="t cap" x="424" y="484">wyłącznie statyczne pliki</text>
-  <text class="t cap" x="424" y="502">brak aplikacji · brak bazy · brak PHP</text>
-
-  <!-- flows -->
-  <path class="flow" d="M272 180 H396"/>
-  <text class="t lbl" x="334" y="170" text-anchor="middle">zapis przez API (OAuth)</text>
-
-  <path class="flow" d="M790 212 H724"/>
-  <text class="t lbl" x="757" y="202" text-anchor="middle">git fetch</text>
-
-  <path class="flow" d="M960 305 V396"/>
-  <text class="t lbl" x="968" y="354" text-anchor="start">nowa wersja strony</text>
-
-  <path class="flow" d="M790 475 H724"/>
-  <text class="t lbl" x="757" y="465" text-anchor="middle">current/</text>
-
-  <path class="flow" d="M400 475 H276"/>
-  <text class="t lbl" x="338" y="465" text-anchor="middle">statyczny HTML</text>
-</svg>
diff --git a/uploads/diagrams/attack-surface.svg b/uploads/diagrams/attack-surface.svg
new file mode 100644
index 0000000..21eb87b
--- /dev/null
+++ b/uploads/diagrams/attack-surface.svg
@@ -0,0 +1,48 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 540" role="img" aria-label="Attack surface compared: a database-backed CMS exposes an application, a login panel, a database and plugins, while this solution exposes static HTML files only and keeps editing behind a git sign-in">
+  <defs>
+    <filter id="soft3" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="2" stdDeviation="5" flood-color="#00004a" flood-opacity="0.10"/>
+    </filter>
+    <marker id="arr3" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10 z" fill="#00004a"/>
+    </marker>
+    <style>
+      .t    { font-family: Inter, "Segoe UI", Arial, sans-serif; }
+      .hd   { font-weight: 800; font-size: 16px; fill: #00004a; letter-spacing: .14em; }
+      .cap  { font-size: 14.5px; fill: #46536a; }
+      .item { font-size: 15.5px; fill: #101228; }
+      .side { font-size: 15px; fill: #101228; }
+      .bad  { fill: #fdf0f0; stroke: #e8c5c5; stroke-width: 1.5; }
+      .good { fill: #ffffff; stroke: #00004a; stroke-width: 1.5; }
+      .flow { stroke: #00004a; stroke-width: 1.8; fill: none; marker-end: url(#arr3); }
+    </style>
+  </defs>
+
+  <!-- top: classic CMS -->
+  <text class="t hd" x="40" y="48">DATABASE-BACKED CMS</text>
+  <text class="t side" x="40" y="173">internet</text>
+  <path class="flow" d="M120 168 H176"/>
+  <g filter="url(#soft3)"><rect class="bad" x="180" y="68" width="580" height="200" rx="16"/></g>
+  <text class="t item" x="208" y="106">▪ CMS application (PHP / Node), public</text>
+  <text class="t item" x="208" y="140">▪ login panel, public</text>
+  <text class="t item" x="208" y="174">▪ database holding the content</text>
+  <text class="t item" x="208" y="208">▪ plugins and dependencies</text>
+  <text class="t" x="208" y="242" font-size="14.5" font-weight="700" fill="#8f3b3b">all of it runs non stop and needs patching</text>
+
+  <!-- divider -->
+  <line x1="40" y1="300" x2="760" y2="300" stroke="#e2e5ee" stroke-width="1.5"/>
+
+  <!-- bottom: this solution -->
+  <text class="t hd" x="40" y="334">THIS SOLUTION</text>
+  <text class="t side" x="40" y="389">internet</text>
+  <path class="flow" d="M120 384 H176"/>
+  <g filter="url(#soft3)"><rect class="good" x="180" y="346" width="580" height="76" rx="16"/></g>
+  <text class="t item" x="208" y="378">▪ HTML files served by nginx</text>
+  <text class="t cap" x="208" y="404">no application, no database, no login panel</text>
+
+  <text class="t side" x="40" y="483">editing</text>
+  <path class="flow" d="M120 478 H176"/>
+  <g filter="url(#soft3)"><rect class="good" x="180" y="440" width="580" height="76" rx="16"/></g>
+  <text class="t item" x="208" y="472">▪ git (Gitea), signed-in users only</text>
+  <text class="t cap" x="208" y="498">off the reader's path, so an outage is invisible</text>
+</svg>
diff --git a/uploads/diagrams/cover-git-cms.svg b/uploads/diagrams/cover-git-cms.svg
index 565f5fe..f5b6570 100644
--- a/uploads/diagrams/cover-git-cms.svg
+++ b/uploads/diagrams/cover-git-cms.svg
@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 900" role="img" aria-label="Grafika: graf commitów w gicie przechodzący w statyczną stronę WWW">
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 900" role="img" aria-label="Illustration: a graph of git commits flowing into a static web page">
   <defs>
     <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
       <stop offset="0" stop-color="#00004a"/>
diff --git a/uploads/diagrams/od-zapisu-do-publikacji.svg b/uploads/diagrams/od-zapisu-do-publikacji.svg
deleted file mode 100644
index 471b2ad..0000000
--- a/uploads/diagrams/od-zapisu-do-publikacji.svg
+++ /dev/null
@@ -1,76 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 430" role="img" aria-label="Pięć kroków od zapisu w edytorze do publikacji: zapis, commit, detekcja, build, publikacja">
-  <defs>
-    <marker id="arr2" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
-      <path d="M0 0 L10 5 L0 10 z" fill="#00004a"/>
-    </marker>
-    <filter id="soft2" x="-20%" y="-20%" width="140%" height="140%">
-      <feDropShadow dx="0" dy="2" stdDeviation="5" flood-color="#00004a" flood-opacity="0.10"/>
-    </filter>
-    <style>
-      .t   { font-family: Inter, "Segoe UI", Arial, sans-serif; }
-      .card { fill: #ffffff; stroke: #00004a; stroke-width: 1.5; }
-      .ttl { font-weight: 700; font-size: 15px; fill: #00004a; }
-      .cap { font-size: 12.3px; fill: #46536a; }
-      .num { font-weight: 800; font-size: 15px; fill: #00004a; }
-      .pill { fill: #f5f5f5; stroke: #e2e5ee; }
-      .pilltxt { font-size: 12.5px; fill: #101228; }
-      .flow { stroke: #00004a; stroke-width: 1.8; fill: none; marker-end: url(#arr2); }
-    </style>
-  </defs>
-
-  <!-- cards -->
-  <g filter="url(#soft2)"><rect class="card" x="55"  y="100" width="200" height="175" rx="16"/></g>
-  <g filter="url(#soft2)"><rect class="card" x="285" y="100" width="200" height="175" rx="16"/></g>
-  <g filter="url(#soft2)"><rect class="card" x="515" y="100" width="200" height="175" rx="16"/></g>
-  <g filter="url(#soft2)"><rect class="card" x="745" y="100" width="200" height="175" rx="16"/></g>
-  <g filter="url(#soft2)"><rect class="card" x="975" y="100" width="200" height="175" rx="16"/></g>
-
-  <!-- connectors -->
-  <path class="flow" d="M255 187 H281"/>
-  <path class="flow" d="M485 187 H511"/>
-  <path class="flow" d="M715 187 H741"/>
-  <path class="flow" d="M945 187 H971"/>
-
-  <!-- step numbers -->
-  <circle cx="155"  cy="100" r="17" fill="#00e4d8"/><text class="t num" x="155"  y="106" text-anchor="middle">1</text>
-  <circle cx="385"  cy="100" r="17" fill="#00e4d8"/><text class="t num" x="385"  y="106" text-anchor="middle">2</text>
-  <circle cx="615"  cy="100" r="17" fill="#00e4d8"/><text class="t num" x="615"  y="106" text-anchor="middle">3</text>
-  <circle cx="845"  cy="100" r="17" fill="#00e4d8"/><text class="t num" x="845"  y="106" text-anchor="middle">4</text>
-  <circle cx="1075" cy="100" r="17" fill="#00e4d8"/><text class="t num" x="1075" y="106" text-anchor="middle">5</text>
-
-  <!-- card 1 -->
-  <text class="t ttl" x="155" y="152" text-anchor="middle">Zapis w edytorze</text>
-  <text class="t cap" x="155" y="182" text-anchor="middle">Sveltia · WYSIWYG</text>
-  <text class="t cap" x="155" y="200" text-anchor="middle">podgląd artykułu 1:1</text>
-  <text class="t cap" x="155" y="218" text-anchor="middle">obrazy → WebP przy uploadzie</text>
-
-  <!-- card 2 -->
-  <text class="t ttl" x="385" y="152" text-anchor="middle">Commit w repo</text>
-  <text class="t cap" x="385" y="182" text-anchor="middle">Gitea · logowanie OAuth</text>
-  <text class="t cap" x="385" y="200" text-anchor="middle">zapis przez API = commit</text>
-  <text class="t cap" x="385" y="218" text-anchor="middle">historia każdej zmiany</text>
-
-  <!-- card 3 -->
-  <text class="t ttl" x="615" y="152" text-anchor="middle">Detekcja zmiany</text>
-  <text class="t cap" x="615" y="182" text-anchor="middle">timer systemd</text>
-  <text class="t cap" x="615" y="200" text-anchor="middle">sprawdza repo co ~10 s</text>
-  <text class="t cap" x="615" y="218" text-anchor="middle">brak zmian = brak pracy</text>
-
-  <!-- card 4 -->
-  <text class="t ttl" x="845" y="152" text-anchor="middle">Build strony</text>
-  <text class="t cap" x="845" y="182" text-anchor="middle">jednorazowy kontener</text>
-  <text class="t cap" x="845" y="200" text-anchor="middle">Astro: Markdown →</text>
-  <text class="t cap" x="845" y="218" text-anchor="middle">statyczny HTML</text>
-
-  <!-- card 5 -->
-  <text class="t ttl" x="1075" y="152" text-anchor="middle">Publikacja</text>
-  <text class="t cap" x="1075" y="182" text-anchor="middle">atomowa podmiana symlinka</text>
-  <text class="t cap" x="1075" y="200" text-anchor="middle">nginx od razu serwuje</text>
-  <text class="t cap" x="1075" y="218" text-anchor="middle">nową wersję</text>
-
-  <!-- reassurance pills -->
-  <rect class="pill" x="240" y="330" width="330" height="40" rx="20"/>
-  <text class="t pilltxt" x="405" y="355" text-anchor="middle">awaria builda? strona działa dalej na starej wersji</text>
-  <rect class="pill" x="630" y="330" width="330" height="40" rx="20"/>
-  <text class="t pilltxt" x="795" y="355" text-anchor="middle">rollback = git revert — jedna komenda</text>
-</svg>
diff --git a/uploads/diagrams/powierzchnia-ataku.svg b/uploads/diagrams/powierzchnia-ataku.svg
deleted file mode 100644
index b887430..0000000
--- a/uploads/diagrams/powierzchnia-ataku.svg
+++ /dev/null
@@ -1,48 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 360" role="img" aria-label="Porównanie powierzchni ataku: CMS z bazą wystawia publicznie aplikację, bazę i pluginy; rozwiązanie statyczne wystawia tylko pliki HTML, a edycja idzie przez git">
-  <defs>
-    <filter id="soft3" x="-20%" y="-20%" width="140%" height="140%">
-      <feDropShadow dx="0" dy="2" stdDeviation="5" flood-color="#00004a" flood-opacity="0.10"/>
-    </filter>
-    <marker id="arr3" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
-      <path d="M0 0 L10 5 L0 10 z" fill="#00004a"/>
-    </marker>
-    <style>
-      .t   { font-family: Inter, "Segoe UI", Arial, sans-serif; }
-      .hd  { font-weight: 800; font-size: 14px; fill: #00004a; letter-spacing: .14em; }
-      .cap { font-size: 12.5px; fill: #46536a; }
-      .item{ font-size: 13px; fill: #101228; }
-      .bad { fill: #fdf0f0; stroke: #e8c5c5; stroke-width: 1.5; }
-      .good{ fill: #ffffff; stroke: #00004a; stroke-width: 1.5; }
-      .flow{ stroke: #00004a; stroke-width: 1.8; fill: none; marker-end: url(#arr3); }
-      .lbl { font-size: 12px; fill: #46536a; paint-order: stroke; stroke: #ffffff; stroke-width: 4; }
-    </style>
-  </defs>
-
-  <!-- left: classic CMS -->
-  <text class="t hd" x="300" y="52" text-anchor="middle">CMS Z BAZĄ DANYCH</text>
-  <text class="t item" x="60" y="150">internet</text>
-  <path class="flow" d="M130 145 H186"/>
-  <g filter="url(#soft3)"><rect class="bad" x="190" y="80" width="360" height="200" rx="16"/></g>
-  <text class="t item" x="218" y="126">▪ aplikacja CMS (PHP / Node) — publiczna</text>
-  <text class="t item" x="218" y="158">▪ panel logowania — publiczny</text>
-  <text class="t item" x="218" y="190">▪ baza danych z treścią</text>
-  <text class="t item" x="218" y="222">▪ pluginy i zależności</text>
-  <text class="t cap" x="218" y="256" font-weight="700" fill="#8f3b3b">wszystko działa non stop i wymaga patchowania</text>
-
-  <!-- divider -->
-  <line x1="600" y1="60" x2="600" y2="320" stroke="#e2e5ee" stroke-width="1.5"/>
-
-  <!-- right: static -->
-  <text class="t hd" x="900" y="52" text-anchor="middle">TO ROZWIĄZANIE</text>
-  <text class="t item" x="646" y="130">internet</text>
-  <path class="flow" d="M716 125 H772"/>
-  <g filter="url(#soft3)"><rect class="good" x="776" y="88" width="360" height="76" rx="16"/></g>
-  <text class="t item" x="804" y="120">▪ pliki HTML — i nic więcej</text>
-  <text class="t cap" x="804" y="146">nie ma czego zhakować ani patchować</text>
-
-  <text class="t item" x="646" y="252">edycja</text>
-  <path class="flow" d="M716 247 H772"/>
-  <g filter="url(#soft3)"><rect class="good" x="776" y="210" width="360" height="76" rx="16"/></g>
-  <text class="t item" x="804" y="242">▪ git (Gitea) — tylko zalogowani</text>
-  <text class="t cap" x="804" y="268">poza ścieżką czytelnika — awaria nie kładzie strony</text>
-</svg>
diff --git a/uploads/diagrams/publish-flow.svg b/uploads/diagrams/publish-flow.svg
new file mode 100644
index 0000000..0cbdb6c
--- /dev/null
+++ b/uploads/diagrams/publish-flow.svg
@@ -0,0 +1,54 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 620 600" role="img" aria-label="Five steps from a save in the editor to a published page: save, commit, change detected, site build, published">
+  <defs>
+    <filter id="soft2" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="2" stdDeviation="5" flood-color="#00004a" flood-opacity="0.10"/>
+    </filter>
+    <style>
+      .t    { font-family: Inter, "Segoe UI", Arial, sans-serif; }
+      .ttl  { font-weight: 700; font-size: 18px; fill: #00004a; }
+      .cap  { font-size: 15px; fill: #46536a; }
+      .num  { font-weight: 800; font-size: 16px; fill: #00004a; }
+      .pill { fill: #f5f5f5; stroke: #e2e5ee; }
+      .pilltxt { font-size: 14px; fill: #101228; }
+    </style>
+  </defs>
+
+  <!-- rail -->
+  <line x1="60" y1="70" x2="60" y2="470" stroke="#c7cde9" stroke-width="2"/>
+
+  <!-- step 1 -->
+  <circle cx="60" cy="70" r="20" fill="#00e4d8"/>
+  <text class="t num" x="60" y="76" text-anchor="middle">1</text>
+  <text class="t ttl" x="100" y="66">Save in the editor</text>
+  <text class="t cap" x="100" y="92">Sveltia, visual editing with a preview that matches the page</text>
+
+  <!-- step 2 -->
+  <circle cx="60" cy="170" r="20" fill="#00e4d8"/>
+  <text class="t num" x="60" y="176" text-anchor="middle">2</text>
+  <text class="t ttl" x="100" y="166">Commit in the repository</text>
+  <text class="t cap" x="100" y="192">Gitea signs the editor in; each save becomes one commit</text>
+
+  <!-- step 3 -->
+  <circle cx="60" cy="270" r="20" fill="#00e4d8"/>
+  <text class="t num" x="60" y="276" text-anchor="middle">3</text>
+  <text class="t ttl" x="100" y="266">Change detected</text>
+  <text class="t cap" x="100" y="292">a systemd timer checks both repositories every 10 seconds</text>
+
+  <!-- step 4 -->
+  <circle cx="60" cy="370" r="20" fill="#00e4d8"/>
+  <text class="t num" x="60" y="376" text-anchor="middle">4</text>
+  <text class="t ttl" x="100" y="366">Site build</text>
+  <text class="t cap" x="100" y="392">a one-shot container runs Astro: Markdown becomes static HTML</text>
+
+  <!-- step 5 -->
+  <circle cx="60" cy="470" r="20" fill="#00e4d8"/>
+  <text class="t num" x="60" y="476" text-anchor="middle">5</text>
+  <text class="t ttl" x="100" y="466">Published</text>
+  <text class="t cap" x="100" y="492">an atomic symlink swap; nginx serves the new version at once</text>
+
+  <!-- reassurance -->
+  <rect class="pill" x="40" y="524" width="310" height="46" rx="23"/>
+  <text class="t pilltxt" x="195" y="552" text-anchor="middle">a failed build leaves the old version up</text>
+  <rect class="pill" x="370" y="524" width="220" height="46" rx="23"/>
+  <text class="t pilltxt" x="480" y="552" text-anchor="middle">rollback is one git revert</text>
+</svg>
diff --git a/uploads/diagrams/stack-overview.svg b/uploads/diagrams/stack-overview.svg
new file mode 100644
index 0000000..c0a953b
--- /dev/null
+++ b/uploads/diagrams/stack-overview.svg
@@ -0,0 +1,70 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 700" role="img" aria-label="The three parts of the stack: Sveltia CMS as the editor, git and Gitea as the database, Astro as the build-time generator; when a reader opens a page only nginx and the generated files are involved">
+  <defs>
+    <marker id="arr0" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10 z" fill="#00004a"/>
+    </marker>
+    <filter id="soft0" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="2" stdDeviation="5" flood-color="#00004a" flood-opacity="0.10"/>
+    </filter>
+    <style>
+      .t    { font-family: Inter, "Segoe UI", Arial, sans-serif; }
+      .card { fill: #ffffff; stroke: #00004a; stroke-width: 1.5; }
+      .ttl  { font-weight: 700; font-size: 19px; fill: #00004a; letter-spacing: .04em; }
+      .cap  { font-size: 15.5px; fill: #46536a; }
+      .chipbg { fill: #d2faf7; }
+      .chip { font-size: 12.5px; font-weight: 700; fill: #00004a; letter-spacing: .06em; }
+      .gain { font-size: 15.5px; font-weight: 700; fill: #101228; }
+      .flow { stroke: #00004a; stroke-width: 1.8; fill: none; marker-end: url(#arr0); }
+      .lbl  { font-size: 14px; fill: #46536a; }
+      .band { fill: #f5f5f5; stroke: #e2e5ee; }
+      .bandtxt { font-size: 14px; fill: #101228; }
+    </style>
+  </defs>
+
+  <!-- row 1: the editor -->
+  <g filter="url(#soft0)"><rect class="card" x="20" y="20" width="760" height="160" rx="16"/></g>
+  <text class="t ttl" x="48" y="68">SVELTIA CMS</text>
+  <rect class="chipbg" x="48" y="84" width="78" height="26" rx="13"/>
+  <text class="t chip" x="87" y="102" text-anchor="middle">EDITOR</text>
+  <text class="t gain" x="48" y="142">every save is</text>
+  <text class="t gain" x="48" y="164">a commit</text>
+  <line x1="284" y1="46" x2="284" y2="154" stroke="#e2e5ee" stroke-width="1"/>
+  <circle cx="312" cy="64" r="3" fill="#00e4d8"/><text class="t cap" x="330" y="69">visual editing in the browser at /admin/</text>
+  <circle cx="312" cy="98" r="3" fill="#00e4d8"/><text class="t cap" x="330" y="103">one JavaScript file, no server to run</text>
+  <circle cx="312" cy="132" r="3" fill="#00e4d8"/><text class="t cap" x="330" y="137">signs in to Gitea over OAuth</text>
+
+  <path class="flow" d="M400 180 V220"/>
+  <text class="t lbl" x="414" y="205">commit</text>
+
+  <!-- row 2: the storage -->
+  <g filter="url(#soft0)"><rect class="card" x="20" y="224" width="760" height="160" rx="16"/></g>
+  <text class="t ttl" x="48" y="272">GIT · GITEA</text>
+  <rect class="chipbg" x="48" y="288" width="86" height="26" rx="13"/>
+  <text class="t chip" x="91" y="306" text-anchor="middle">STORAGE</text>
+  <text class="t gain" x="48" y="346">the repository</text>
+  <text class="t gain" x="48" y="368">is the database</text>
+  <line x1="284" y1="250" x2="284" y2="358" stroke="#e2e5ee" stroke-width="1"/>
+  <circle cx="312" cy="268" r="3" fill="#00e4d8"/><text class="t cap" x="330" y="273">articles as Markdown files</text>
+  <circle cx="312" cy="302" r="3" fill="#00e4d8"/><text class="t cap" x="330" y="307">images stored next to them</text>
+  <circle cx="312" cy="336" r="3" fill="#00e4d8"/><text class="t cap" x="330" y="341">history, diff and revert built in</text>
+
+  <path class="flow" d="M400 384 V424"/>
+  <text class="t lbl" x="414" y="409">build</text>
+
+  <!-- row 3: the generator -->
+  <g filter="url(#soft0)"><rect class="card" x="20" y="428" width="760" height="160" rx="16"/></g>
+  <text class="t ttl" x="48" y="476">ASTRO</text>
+  <rect class="chipbg" x="48" y="492" width="110" height="26" rx="13"/>
+  <text class="t chip" x="103" y="510" text-anchor="middle">BUILD ONLY</text>
+  <text class="t gain" x="48" y="550">nothing of it runs</text>
+  <text class="t gain" x="48" y="572">in production</text>
+  <line x1="284" y1="454" x2="284" y2="562" stroke="#e2e5ee" stroke-width="1"/>
+  <circle cx="312" cy="472" r="3" fill="#00e4d8"/><text class="t cap" x="330" y="477">Markdown becomes static HTML</text>
+  <circle cx="312" cy="506" r="3" fill="#00e4d8"/><text class="t cap" x="330" y="511">article fields checked at build time</text>
+  <circle cx="312" cy="540" r="3" fill="#00e4d8"/><text class="t cap" x="330" y="545">React islands where they are needed</text>
+
+  <!-- what the reader actually touches -->
+  <rect class="band" x="20" y="616" width="760" height="64" rx="32"/>
+  <text class="t bandtxt" x="400" y="645" text-anchor="middle">When a reader opens a page, only nginx and the generated files are involved.</text>
+  <text class="t bandtxt" x="400" y="667" text-anchor="middle">No application, no database, no admin login.</text>
+</svg>