From aa36b2905a39171e492109784c15acf8fd9923e5 Mon Sep 17 00:00:00 2001
From: claude-timemachine <llm@timemachine.center>
Date: Wed, 13 May 2026 00:52:53 +0200
Subject: [PATCH] initial: zero-trust markdown tutorials site
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Single-binary Go service that renders markdown pages from a runtime
volume mount. Targeted at public, no-auth, no-WAF deployment behind a
TLS ingress; security posture is defense-in-depth at every layer:

- goldmark with no WithUnsafe — raw HTML in author markdown is stripped
- CSP without 'unsafe-inline', plus HSTS, COOP, CORP, Permissions-Policy
- static handler rejects non-GET/HEAD, directory listings, dotfiles, traversal
- content loader rejects symlinks that escape the content root, dotfiles,
  and .md files larger than 1 MiB
- per-page template trees (cloned from layout) so define-blocks don't
  collide between home/category/page
- SIGHUP triggers atomic library swap — live edits on volume, no rebuild

Locale layout content/<locale>/<category>/<slug>.md. Categories without
_index.md still appear on the home page with a humanized name. Search is
a ~70-line vanilla JS scan over /search.json?lang=<locale>; swap for a
real indexer if the corpus ever balloons.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .gitignore                                  |  12 +
 Dockerfile                                  |  21 ++
 Makefile                                    |  19 ++
 README.md                                   |  92 ++++++
 cmd/automc-tutorials/main.go                |  63 ++++
 content/cs/install-client/_index.md         |  14 +
 content/cs/install-client/java-edition.md   |  50 +++
 content/cs/install-client/offline-client.md |  52 +++
 content/en/install-client/_index.md         |  14 +
 content/en/install-client/java-edition.md   |  50 +++
 content/en/install-client/offline-client.md |  52 +++
 go.mod                                      |   8 +
 go.sum                                      |   6 +
 internal/content/library.go                 | 322 ++++++++++++++++++
 internal/render/markdown.go                 |  35 ++
 internal/server/server.go                   | 344 ++++++++++++++++++++
 internal/server/static/search.js            |  71 ++++
 internal/server/static/style.css            | 152 +++++++++
 internal/server/templates/category.html     |  18 +
 internal/server/templates/home.html         |  17 +
 internal/server/templates/layout.html       |  43 +++
 internal/server/templates/page.html         |  10 +
 22 files changed, 1465 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 Dockerfile
 create mode 100644 Makefile
 create mode 100644 README.md
 create mode 100644 cmd/automc-tutorials/main.go
 create mode 100644 content/cs/install-client/_index.md
 create mode 100644 content/cs/install-client/java-edition.md
 create mode 100644 content/cs/install-client/offline-client.md
 create mode 100644 content/en/install-client/_index.md
 create mode 100644 content/en/install-client/java-edition.md
 create mode 100644 content/en/install-client/offline-client.md
 create mode 100644 go.mod
 create mode 100644 go.sum
 create mode 100644 internal/content/library.go
 create mode 100644 internal/render/markdown.go
 create mode 100644 internal/server/server.go
 create mode 100644 internal/server/static/search.js
 create mode 100644 internal/server/static/style.css
 create mode 100644 internal/server/templates/category.html
 create mode 100644 internal/server/templates/home.html
 create mode 100644 internal/server/templates/layout.html
 create mode 100644 internal/server/templates/page.html

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..d6871c1
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,12 @@
+# compiled binary (root only — don't shadow cmd/automc-tutorials/)
+/automc-tutorials
+
+# test artifacts
+*.test
+*.out
+coverage.txt
+
+# editor + os
+.vscode/
+.idea/
+.DS_Store
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..4192e9c
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,21 @@
+# --- build stage ---
+FROM golang:1.25-alpine AS build
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags='-s -w' \
+    -o /out/automc-tutorials ./cmd/automc-tutorials
+
+# --- runtime stage ---
+# Image carries only the binary. Content is provided at runtime via a volume
+# mount at /content (typically a Longhorn RWX PVC populated by `git pull` or
+# rsync from an admin shell). Live edits + SIGHUP reload = no rebuild needed.
+FROM gcr.io/distroless/static-debian12:nonroot
+WORKDIR /app
+COPY --from=build /out/automc-tutorials /app/automc-tutorials
+EXPOSE 8080
+ENV ADDR=:8080 CONTENT_DIR=/content DEFAULT_LOCALE=en
+VOLUME ["/content"]
+USER 65532:65532
+ENTRYPOINT ["/app/automc-tutorials"]
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..2ea111d
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,19 @@
+.PHONY: build run dev test vet docker
+
+build:
+	go build -o automc-tutorials ./cmd/automc-tutorials
+
+run: build
+	./automc-tutorials
+
+dev:
+	go run ./cmd/automc-tutorials
+
+test:
+	go test ./...
+
+vet:
+	go vet ./...
+
+docker:
+	docker build -t git.timemachine.center/timemachine/automc-tutorials:latest .
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..beb114c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,92 @@
+# automc-tutorials
+
+Public-facing tutorials site for the automc Minecraft platform. Renders markdown from a mounted volume as a localized static-ish web app. No auth, no database, no state — exposed to the open internet behind TLS, hardened for zero-trust.
+
+## Stack
+
+- **Go** + `net/http` + `html/template` — single binary
+- **goldmark** — markdown → HTML (GFM + footnotes + auto heading IDs)
+- **Plain CSS** — no framework, dark mode via `prefers-color-scheme`
+- **Vanilla JS** — ~70-line client-side substring search, no dependency
+- Content lives on a mounted volume; reload via SIGHUP
+
+## Layout
+
+```
+cmd/automc-tutorials/main.go    — entry: flags, signals, SIGHUP reload
+internal/content/               — loader + path-traversal guard for content/<locale>/<category>/<slug>.md
+internal/render/                — goldmark wrapper (HTML escaping on)
+internal/server/                — mux, handlers, embedded templates + /static/ bundle
+content/<locale>/<category>/    — markdown source. _index.md is the category landing page (optional).
+```
+
+## Adding or editing a tutorial
+
+The image carries only the binary. Markdown sits on a volume mounted at `/content` (default in the image; override with `CONTENT_DIR`). Workflow:
+
+1. Open an admin shell on the host that owns the PVC (or shell into a pod that mounts the same RWX volume).
+2. Drop / edit `.md` files under `<volume>/<locale>/<category>/`.
+3. Add YAML frontmatter:
+
+   ```yaml
+   ---
+   title: Page title
+   summary: One-sentence preview shown on category list.
+   order: 1
+   ---
+   ```
+
+4. Write markdown. GFM tables, fenced code, footnotes, autolinks, task lists all work. Raw HTML in markdown is **escaped** — don't try to embed `<script>` or `<iframe>`, they'll render as text.
+5. Reload without restart: `kill -HUP $(pidof automc-tutorials)` inside the container, or `kubectl exec deploy/automc-tutorials -- kill -HUP 1`.
+
+No rebuild, no rollout. The atomic library swap means in-flight requests keep serving the old library; new requests see the new one.
+
+## Localization
+
+Each top-level directory under the content root is a locale. Pages are independent per locale — translations are not auto-mapped. The header has a locale switcher that just changes `/<locale>/` in the URL.
+
+If a page exists in `en` but not `cs`, switching to `cs` lands on the `cs` home (no automatic redirect, no fallback render).
+
+## Search
+
+Client-side substring search over `title`, `summary`, and `body`. Index served at `GET /search.json?lang=<locale>` — flat array of `{path, title, summary, body}`. `static/search.js` does a case-insensitive linear scan with crude scoring (title hit = 100, summary = 10, body = 1) and shows the top 8.
+
+This is fine for a few hundred pages. If the corpus ever balloons, swap the in-browser scan for a real indexer — the endpoint contract is stable.
+
+## Configuration
+
+| Var | Default | Purpose |
+|---|---|---|
+| `ADDR` | `:8080` | HTTP listen address |
+| `CONTENT_DIR` | `/content` | Path to content root (volume mount in production, `./content` in dev) |
+| `DEFAULT_LOCALE` | `en` | Locale used when none in URL (`/` → `/<locale>/`) |
+
+## Zero-trust posture
+
+The service is intended to sit behind TLS (k8s ingress) on the open internet, with no auth and no WAF. Hardening:
+
+- **No HTML in markdown.** `goldmark.WithUnsafe()` is not enabled, so raw HTML in `.md` is escaped.
+- **CSP** restricts everything to `'self'`; `'unsafe-inline'` is absent (templates carry no inline styles or scripts). Frame ancestors blocked, base/form-action pinned to self.
+- **HSTS, COOP, CORP, Permissions-Policy** all set conservatively.
+- **No directory listing** on `/static/`; only GET/HEAD; hidden files (`/.foo`) blocked.
+- **Content loader** rejects symlinks that escape the content root, hidden files, and `.md` files larger than 1 MiB.
+- **HTTP timeouts** are set on read header, read body, write, and idle.
+- **Distroless static, runs as 65532:65532**, no shell, no package manager.
+- **No outbound calls** — the service never reaches out to anything.
+
+## Build
+
+```fish
+make build      # binary
+make dev        # go run, no build artifact
+make test       # go test ./...
+make docker     # Docker image
+```
+
+## Deployment
+
+Single binary, distroless image, port 8080, no persistent state. Deploy as a normal k8s `Deployment` + `Service` + `Ingress` for `tutorials.timemachine.center`. Mount the content PVC read-only at `/content`. No DB, no auth, no secrets.
+
+## Repo
+
+Standalone Gitea repo at `git.timemachine.center/Timemachine/automc-tutorials`. Sibling of the automc orchestration repo.
diff --git a/cmd/automc-tutorials/main.go b/cmd/automc-tutorials/main.go
new file mode 100644
index 0000000..011aa98
--- /dev/null
+++ b/cmd/automc-tutorials/main.go
@@ -0,0 +1,63 @@
+// Command automc-tutorials serves a public, localized markdown-driven tutorials site.
+// Content lives in content/<locale>/<slug>/<page>.md and is loaded into memory at startup;
+// SIGHUP triggers a reload without restarting the server.
+package main
+
+import (
+	"context"
+	"flag"
+	"log/slog"
+	"os"
+	"os/signal"
+	"syscall"
+
+	"git.timemachine.center/Timemachine/automc-tutorials/internal/content"
+	"git.timemachine.center/Timemachine/automc-tutorials/internal/server"
+)
+
+func main() {
+	addr := flag.String("addr", envOr("ADDR", ":8080"), "HTTP listen address")
+	contentDir := flag.String("content", envOr("CONTENT_DIR", "content"), "Path to content/ directory")
+	defaultLocale := flag.String("default-locale", envOr("DEFAULT_LOCALE", "en"), "Locale used when none requested")
+	flag.Parse()
+
+	library, err := content.Load(*contentDir)
+	if err != nil {
+		slog.Error("loading content", "err", err)
+		os.Exit(1)
+	}
+	slog.Info("content loaded", "locales", library.Locales(), "pages", library.PageCount())
+
+	srv := server.New(library, *defaultLocale)
+
+	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer cancel()
+
+	// SIGHUP → reload content without restart. Useful in dev and for live edits in
+	// container environments where rebuilding the binary is overkill.
+	hup := make(chan os.Signal, 1)
+	signal.Notify(hup, syscall.SIGHUP)
+	go func() {
+		for range hup {
+			fresh, err := content.Load(*contentDir)
+			if err != nil {
+				slog.Error("reloading content", "err", err)
+				continue
+			}
+			srv.SwapLibrary(fresh)
+			slog.Info("content reloaded", "pages", fresh.PageCount())
+		}
+	}()
+
+	if err := srv.Run(ctx, *addr); err != nil {
+		slog.Error("server error", "err", err)
+		os.Exit(1)
+	}
+}
+
+func envOr(key, fallback string) string {
+	if v := os.Getenv(key); v != "" {
+		return v
+	}
+	return fallback
+}
diff --git a/content/cs/install-client/_index.md b/content/cs/install-client/_index.md
new file mode 100644
index 0000000..6e1d729
--- /dev/null
+++ b/content/cs/install-client/_index.md
@@ -0,0 +1,14 @@
+---
+title: Instalace Minecraft klienta
+summary: Nainstaluj si Minecraft a připoj se na naše servery.
+order: 1
+---
+
+# Instalace Minecraft klienta
+
+Vyber edici podle toho, co máš (nebo co chceš hrát offline):
+
+- **Java Edition** — oficiální launcher od Mojangu. Nutný pro naše Fabric/Paper servery.
+- **Bedrock Edition** — Windows/konzole/mobil. **Nepodporováno** na našich serverech.
+
+Pokud Minecraft nevlastníš, podívej se na **offline (cracked) klient** — pořád si můžeš zahrát na serverech, které offline režim povolí (po registraci přes Discord).
diff --git a/content/cs/install-client/java-edition.md b/content/cs/install-client/java-edition.md
new file mode 100644
index 0000000..c1fd533
--- /dev/null
+++ b/content/cs/install-client/java-edition.md
@@ -0,0 +1,50 @@
+---
+title: Java Edition (oficiální launcher)
+summary: Nainstaluj Mojang launcher a ověř, že tvůj účet funguje.
+order: 1
+---
+
+# Java Edition (oficiální launcher)
+
+Mojang/Microsoft launcher je jediná oficiálně podporovaná cesta jak hrát Java Edition.
+
+## Stažení
+
+1. Jdi na [minecraft.net/download](https://www.minecraft.net/cs-cz/download).
+2. Stáhni launcher pro tvůj OS:
+   - **Windows:** `.msi` instalátor.
+   - **macOS:** `.dmg` obraz disku.
+   - **Linux:** `.deb`, `.tar.gz`, nebo přes balíčkovací systém distra (např. `sudo pacman -S minecraft-launcher` na Archu).
+3. Spusť instalátor a launcher.
+
+## Přihlášení
+
+Potřebuješ **Microsoft účet** s licencí Minecraftu. Pokud jsi koupil Minecraft před rokem 2020 a stále používáš Mojang účet, launcher tě vyzve k migraci — postupuj podle pokynů. Migrace je zdarma.
+
+Pokud vidíš "Failed to authenticate":
+
+- Zkontroluj, že tvůj Microsoft účet nebyl přepnut na dětský účet nebo přesunut do rodinné skupiny bez přístupu k Minecraftu.
+- Zkus [account.live.com/Authorize](https://account.live.com/Authorize) pro vyčištění tokenů.
+
+## Vyber verzi
+
+Naše servery běží na **Minecraft 1.21.4**. V launcheru:
+
+1. Klikni **Installations** (nahoře).
+2. **New installation**.
+3. **Version** nastav na `release 1.21.4`.
+4. Ulož — launcher si verzi stáhne při prvním spuštění.
+
+## Připojení na server
+
+1. V launcheru klikni **Play** na tvé `1.21.4` instalaci.
+2. V Minecraftu: **Multiplayer** → **Add Server**.
+3. Server name: cokoliv (např. "Survival").
+4. Server address: adresa od admina (např. `survival.g.timemachine.center`).
+5. **Done** → vyber server → **Join Server**.
+
+## Co dál
+
+- Pokud máš placený (Java) účet: nic — server tě rozezná automaticky a spawneš se do světa.
+- Pokud placený účet nemáš: viz [offline klient](./offline-client).
+- Tak jako tak — nejprve si zaregistruj jméno na Discordu — server tě o to požádá ještě než tě pustí dovnitř.
diff --git a/content/cs/install-client/offline-client.md b/content/cs/install-client/offline-client.md
new file mode 100644
index 0000000..9607ccf
--- /dev/null
+++ b/content/cs/install-client/offline-client.md
@@ -0,0 +1,52 @@
+---
+title: Offline (cracked) klient
+summary: Zahraj si bez nákupu Minecraftu — open-source launcher.
+order: 2
+---
+
+# Offline (cracked) klient
+
+Pokud Minecraft nemáš, můžeš hrát na serverech, které offline režim povolí. Doporučujeme **Prism Launcher** — open-source, zdarma, dobře udržovaný.
+
+> **Pozn.:** offline účty se nepřipojí na oficiální servery (Hypixel atd.). Fungují jen na serverech, které je explicitně povolí. Naše platforma podporuje obojí — při registraci na Discordu si vybereš typ účtu.
+
+## Stažení Prism Launcher
+
+1. Jdi na [prismlauncher.org](https://prismlauncher.org/).
+2. Stáhni pro tvůj OS — Windows, macOS, Linux.
+3. Nainstaluj a otevři.
+
+## První spuštění
+
+Při prvním spuštění Prism požaduje účet. Klikni **Skip** — offline profil přidáme za chvíli.
+
+1. Vpravo nahoře: **Accounts** → **Add Offline**.
+2. Username: musí odpovídat tomu, co si zaregistruješ na našem Discordu (3–16 znaků, písmena/čísla/podtržítka).
+3. Ulož.
+
+## Přidej Minecraft instalaci
+
+1. Hlavní pohled: **Add Instance**.
+2. Vyber **Vanilla** (nebo **Fabric**, pokud admin řekne).
+3. Verze: **1.21.4**.
+4. Pojmenuj (např. "automc Survival").
+5. **OK**.
+
+## Spuštění + připojení
+
+1. Dvojklik na instanci.
+2. Prism stáhne potřebné soubory (~100 MB).
+3. V Minecraftu: **Multiplayer** → **Add Server** → adresa od admina.
+4. Připoj se.
+
+## Nejdřív registrace na Discordu
+
+Než se připojíš, musíš si zaregistrovat jméno na našem Discordu:
+
+1. Připoj se na Discord server (odkaz od admina).
+2. Spusť `/register`.
+3. Bot ti pošle DM — vyber **Offline** typ účtu.
+4. Napiš stejné jméno, jaké máš v Prism.
+5. Bot vygeneruje heslo — také ho pošle DM. Ulož si ho.
+
+Po připojení na MC server se ozve LibreLogin — napíšeš `/login <heslo>` v chatu.
diff --git a/content/en/install-client/_index.md b/content/en/install-client/_index.md
new file mode 100644
index 0000000..0edab5d
--- /dev/null
+++ b/content/en/install-client/_index.md
@@ -0,0 +1,14 @@
+---
+title: Install Minecraft client
+summary: Get a working Minecraft client to connect to our servers.
+order: 1
+---
+
+# Install Minecraft client
+
+Pick the edition that matches what you bought (or want to play offline):
+
+- **Java Edition** — official launcher from Mojang. Required for our Fabric/Paper servers.
+- **Bedrock Edition** — Windows/console/mobile. Currently **not supported** by our servers.
+
+If you don't own Minecraft, see the **offline (cracked) client** guide — you can still play on servers that allow offline mode after registering through Discord.
diff --git a/content/en/install-client/java-edition.md b/content/en/install-client/java-edition.md
new file mode 100644
index 0000000..a376f14
--- /dev/null
+++ b/content/en/install-client/java-edition.md
@@ -0,0 +1,50 @@
+---
+title: Java Edition (official launcher)
+summary: Install the Mojang launcher and verify your account works.
+order: 1
+---
+
+# Java Edition (official launcher)
+
+The Mojang/Microsoft launcher is the only officially supported way to play Java Edition.
+
+## Download
+
+1. Go to [minecraft.net/download](https://www.minecraft.net/en-us/download).
+2. Download the launcher for your OS:
+   - **Windows:** `.msi` installer.
+   - **macOS:** `.dmg` disk image.
+   - **Linux:** `.deb`, `.tar.gz`, or via your distro's package manager (e.g. `sudo pacman -S minecraft-launcher` on Arch).
+3. Run the installer and launch it.
+
+## Sign in
+
+You need a **Microsoft account** with a Minecraft license attached. If you bought Minecraft before 2020 and still use a Mojang account, the launcher will prompt you to migrate — follow the steps. Migration is free.
+
+If you see "Failed to authenticate":
+
+- Check that your Microsoft account hasn't been switched to a child account or moved to a family group without Minecraft access.
+- Try [account.live.com/Authorize](https://account.live.com/Authorize) to clear stale tokens.
+
+## Pick a version
+
+Our servers run **Minecraft 1.21.4**. In the launcher:
+
+1. Click **Installations** (top of the launcher).
+2. Click **New installation**.
+3. Set **Version** to `release 1.21.4`.
+4. Save — the launcher downloads it on first play.
+
+## Connect to a server
+
+1. From the launcher, click **Play** on your `1.21.4` installation.
+2. In Minecraft: **Multiplayer** → **Add Server**.
+3. Server name: anything (e.g. "Survival").
+4. Server address: the address you got from the admin (e.g. `survival.g.timemachine.center`).
+5. **Done** → select the server → **Join Server**.
+
+## What's next
+
+- If you have a paid (Java) account: nothing — the server recognizes you automatically and you'll spawn into the world.
+- If you don't have a paid account: see the [offline client](./offline-client) guide.
+- Either way, register your username on Discord first — the server will ask you to before it lets you in.
diff --git a/content/en/install-client/offline-client.md b/content/en/install-client/offline-client.md
new file mode 100644
index 0000000..5d8db13
--- /dev/null
+++ b/content/en/install-client/offline-client.md
@@ -0,0 +1,52 @@
+---
+title: Offline (cracked) client
+summary: Play without buying Minecraft, using a free open-source launcher.
+order: 2
+---
+
+# Offline (cracked) client
+
+If you don't own Minecraft, you can still play on our servers that allow offline mode. We recommend **Prism Launcher** — it's open-source, free, and well-maintained.
+
+> **Note:** offline accounts can't connect to Mojang's official servers (Hypixel, etc.). They work only on servers that explicitly allow them. Our platform supports both — when you register on Discord, you choose "Offline" account type.
+
+## Download Prism Launcher
+
+1. Go to [prismlauncher.org](https://prismlauncher.org/).
+2. Download for your OS — Windows, macOS, Linux.
+3. Install + open.
+
+## First-time setup
+
+On first launch, Prism asks for an account. Click **Skip** for now — we'll add an offline profile after.
+
+1. Top right: **Accounts** → **Add Offline**.
+2. Username: must match what you'll register on our Discord (3–16 characters, letters/numbers/underscore).
+3. Save.
+
+## Add a Minecraft installation
+
+1. Main view: click **Add Instance**.
+2. Pick **Vanilla** (or **Fabric** if the admin tells you to).
+3. Version: **1.21.4**.
+4. Name it something memorable (e.g. "automc Survival").
+5. Click **OK**.
+
+## Launch + connect
+
+1. Double-click your instance.
+2. Prism downloads the assets first time (~100 MB).
+3. In Minecraft: **Multiplayer** → **Add Server** → enter the address the admin gave you.
+4. Connect.
+
+## Register on Discord first
+
+Before connecting, you must register your username on our Discord:
+
+1. Join the Discord server (link from the admin).
+2. Run `/register`.
+3. The bot DMs you — pick **Offline** account type.
+4. Type the same username you set in Prism.
+5. The bot saves a password — also DMs it. Keep it.
+
+When you join the MC server, it'll ask for the password in chat: type `/login <password>`.
diff --git a/go.mod b/go.mod
new file mode 100644
index 0000000..53d1932
--- /dev/null
+++ b/go.mod
@@ -0,0 +1,8 @@
+module git.timemachine.center/Timemachine/automc-tutorials
+
+go 1.25
+
+require (
+	github.com/yuin/goldmark v1.7.8
+	gopkg.in/yaml.v3 v3.0.1
+)
diff --git a/go.sum b/go.sum
new file mode 100644
index 0000000..3ca28b4
--- /dev/null
+++ b/go.sum
@@ -0,0 +1,6 @@
+github.com/yuin/goldmark v1.7.8 h1:iERMLn0/QJeHFhxSt3p6PeN9mGnvIKSpG9YYorDMnic=
+github.com/yuin/goldmark v1.7.8/go.mod h1:uzxRWxtg69N339t3louHJ7+O03ezfj6PlliRlaOzY1E=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/internal/content/library.go b/internal/content/library.go
new file mode 100644
index 0000000..045f45c
--- /dev/null
+++ b/internal/content/library.go
@@ -0,0 +1,322 @@
+// Package content loads and indexes markdown tutorial pages from disk.
+//
+// Layout on disk:
+//
+//	content/
+//	  <locale>/             — e.g. en, cs
+//	    <category>/         — e.g. install-client, registration, troubleshooting
+//	      _index.md         — category landing page (optional)
+//	      <slug>.md         — individual tutorial page
+//
+// Each markdown file may have YAML frontmatter delimited by `---`:
+//
+//	---
+//	title: Install Minecraft Java Edition
+//	order: 1
+//	summary: Step-by-step for installing the official launcher.
+//	---
+//	# heading...
+//
+// Pages without frontmatter use the filename as title and order=999.
+package content
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"gopkg.in/yaml.v3"
+)
+
+// Library is an in-memory index of all loaded pages. Construct via Load.
+// Read-only after construction; the server swaps whole Library values on reload.
+type Library struct {
+	pages   map[string]*Page            // key: <locale>/<category>/<slug>
+	byPath  map[string][]*Page          // key: <locale>/<category>, value: pages sorted by Order then Title
+	locales []string                    // sorted, unique
+	categs  map[string]map[string]*Page // <locale> → <category> → category-index page (or nil if no _index.md)
+}
+
+// maxPageBytes caps the size of a single markdown file. Loader skips bigger files with a stderr warning.
+// Content is operator-controlled (volume mount), but this prevents a stray dump from ballooning memory.
+const maxPageBytes = 1 << 20 // 1 MiB
+
+// Page is one markdown document.
+type Page struct {
+	Locale   string // "en", "cs"
+	Category string // "install-client"
+	Slug     string // "java-edition", "_index"
+	Title    string
+	Summary  string
+	Order    int
+	Source   []byte // raw markdown body (no frontmatter)
+	Path     string // <locale>/<category>/<slug>
+}
+
+type frontmatter struct {
+	Title   string `yaml:"title"`
+	Summary string `yaml:"summary"`
+	Order   int    `yaml:"order"`
+}
+
+// Load walks contentDir and returns a populated Library.
+// Returns an error only on filesystem-level failures; individual malformed pages are skipped with a warning written to stderr.
+//
+// Zero-trust posture: the content dir is volume-mounted in production. The loader
+// resolves the absolute path of contentDir once and rejects any entry (dir or file)
+// whose evaluated symlink target falls outside it. This prevents a misconfigured
+// volume (or an operator slipping in a symlink) from reading host files.
+func Load(contentDir string) (*Library, error) {
+	info, err := os.Stat(contentDir)
+	if err != nil {
+		return nil, fmt.Errorf("stat content dir %q: %w", contentDir, err)
+	}
+	if !info.IsDir() {
+		return nil, fmt.Errorf("content path %q is not a directory", contentDir)
+	}
+	rootAbs, err := filepath.Abs(contentDir)
+	if err != nil {
+		return nil, fmt.Errorf("abs content dir: %w", err)
+	}
+	rootAbs, err = filepath.EvalSymlinks(rootAbs)
+	if err != nil {
+		return nil, fmt.Errorf("eval root symlinks: %w", err)
+	}
+
+	lib := &Library{
+		pages:  make(map[string]*Page),
+		byPath: make(map[string][]*Page),
+		categs: make(map[string]map[string]*Page),
+	}
+
+	localeEntries, err := os.ReadDir(contentDir)
+	if err != nil {
+		return nil, fmt.Errorf("read content dir: %w", err)
+	}
+	for _, lEntry := range localeEntries {
+		name := lEntry.Name()
+		if strings.HasPrefix(name, ".") || !lEntry.IsDir() {
+			continue
+		}
+		localeDir := filepath.Join(contentDir, name)
+		if !withinRoot(rootAbs, localeDir) {
+			fmt.Fprintf(os.Stderr, "[content] skipping locale %q: escapes content root\n", name)
+			continue
+		}
+		lib.locales = append(lib.locales, name)
+		lib.categs[name] = make(map[string]*Page)
+
+		categEntries, err := os.ReadDir(localeDir)
+		if err != nil {
+			return nil, fmt.Errorf("read locale %q: %w", name, err)
+		}
+		for _, cEntry := range categEntries {
+			cName := cEntry.Name()
+			if strings.HasPrefix(cName, ".") || !cEntry.IsDir() {
+				continue
+			}
+			categDir := filepath.Join(localeDir, cName)
+			if !withinRoot(rootAbs, categDir) {
+				fmt.Fprintf(os.Stderr, "[content] skipping %s/%s: escapes content root\n", name, cName)
+				continue
+			}
+			// Register the category even if _index.md is missing; it'll show up
+			// on the home page with a humanized name.
+			if _, ok := lib.categs[name][cName]; !ok {
+				lib.categs[name][cName] = nil
+			}
+			if err := lib.loadCategory(rootAbs, name, cName, categDir); err != nil {
+				return nil, err
+			}
+		}
+	}
+
+	sort.Strings(lib.locales)
+	for k := range lib.byPath {
+		pages := lib.byPath[k]
+		sort.SliceStable(pages, func(i, j int) bool {
+			if pages[i].Order != pages[j].Order {
+				return pages[i].Order < pages[j].Order
+			}
+			return pages[i].Title < pages[j].Title
+		})
+		lib.byPath[k] = pages
+	}
+	return lib, nil
+}
+
+// withinRoot returns true if p, after resolving symlinks, is rootAbs or a descendant.
+// Used to reject volume entries that point outside the content directory.
+func withinRoot(rootAbs, p string) bool {
+	abs, err := filepath.Abs(p)
+	if err != nil {
+		return false
+	}
+	resolved, err := filepath.EvalSymlinks(abs)
+	if err != nil {
+		return false
+	}
+	rel, err := filepath.Rel(rootAbs, resolved)
+	if err != nil {
+		return false
+	}
+	return rel == "." || (!strings.HasPrefix(rel, "..") && !filepath.IsAbs(rel))
+}
+
+func (l *Library) loadCategory(rootAbs, locale, category, dir string) error {
+	files, err := os.ReadDir(dir)
+	if err != nil {
+		return err
+	}
+	pathKey := locale + "/" + category
+	for _, f := range files {
+		name := f.Name()
+		if strings.HasPrefix(name, ".") || f.IsDir() || !strings.HasSuffix(name, ".md") {
+			continue
+		}
+		fp := filepath.Join(dir, name)
+		if !withinRoot(rootAbs, fp) {
+			fmt.Fprintf(os.Stderr, "[content] skipping %s: escapes content root\n", fp)
+			continue
+		}
+		// Use Stat on the resolved path to enforce size cap before reading.
+		info, err := os.Stat(fp)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "[content] stat %s: %v\n", fp, err)
+			continue
+		}
+		if info.Size() > maxPageBytes {
+			fmt.Fprintf(os.Stderr, "[content] skipping %s: %d bytes exceeds %d cap\n", fp, info.Size(), maxPageBytes)
+			continue
+		}
+		slug := strings.TrimSuffix(name, ".md")
+		raw, err := os.ReadFile(fp)
+		if err != nil {
+			return err
+		}
+		page, err := parsePage(raw, locale, category, slug)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "[content] skipping %s: %v\n", fp, err)
+			continue
+		}
+		key := page.Path
+		l.pages[key] = page
+		if slug == "_index" {
+			l.categs[locale][category] = page
+		} else {
+			l.byPath[pathKey] = append(l.byPath[pathKey], page)
+		}
+	}
+	return nil
+}
+
+func parsePage(raw []byte, locale, category, slug string) (*Page, error) {
+	body := raw
+	fm := frontmatter{Order: 999}
+	if bytes := raw; len(bytes) >= 4 && string(bytes[:3]) == "---" {
+		// Find closing fence on its own line.
+		rest := bytes[3:]
+		idx := strings.Index(string(rest), "\n---")
+		if idx >= 0 {
+			head := rest[:idx]
+			if err := yaml.Unmarshal(head, &fm); err != nil {
+				return nil, fmt.Errorf("frontmatter: %w", err)
+			}
+			body = rest[idx+4:]
+			body = trimLeadingNewline(body)
+		}
+	}
+	if fm.Title == "" {
+		fm.Title = slugToTitle(slug)
+	}
+	return &Page{
+		Locale:   locale,
+		Category: category,
+		Slug:     slug,
+		Title:    fm.Title,
+		Summary:  fm.Summary,
+		Order:    fm.Order,
+		Source:   body,
+		Path:     locale + "/" + category + "/" + slug,
+	}, nil
+}
+
+func trimLeadingNewline(b []byte) []byte {
+	if len(b) > 0 && b[0] == '\n' {
+		return b[1:]
+	}
+	return b
+}
+
+func slugToTitle(slug string) string {
+	s := strings.ReplaceAll(slug, "-", " ")
+	s = strings.ReplaceAll(s, "_", " ")
+	if s == "" {
+		return ""
+	}
+	return strings.ToUpper(s[:1]) + s[1:]
+}
+
+// --- Accessors ---
+
+func (l *Library) Locales() []string  { return append([]string(nil), l.locales...) }
+func (l *Library) PageCount() int     { return len(l.pages) }
+func (l *Library) HasLocale(loc string) bool {
+	_, ok := l.categs[loc]
+	return ok
+}
+
+// Categories returns the categories in a locale, sorted by their _index.Order then name.
+type Category struct {
+	Name    string
+	Index   *Page // may be nil if no _index.md
+	Pages   []*Page
+}
+
+func (l *Library) Categories(locale string) []Category {
+	cats, ok := l.categs[locale]
+	if !ok {
+		return nil
+	}
+	var out []Category
+	for name := range cats {
+		idx := cats[name]
+		out = append(out, Category{
+			Name:  name,
+			Index: idx,
+			Pages: l.byPath[locale+"/"+name],
+		})
+	}
+	// Stable order: by index Order, then name.
+	sort.SliceStable(out, func(i, j int) bool {
+		oi, oj := 999, 999
+		if out[i].Index != nil {
+			oi = out[i].Index.Order
+		}
+		if out[j].Index != nil {
+			oj = out[j].Index.Order
+		}
+		if oi != oj {
+			return oi < oj
+		}
+		return out[i].Name < out[j].Name
+	})
+	return out
+}
+
+// Page returns the page for a path or nil.
+func (l *Library) Page(locale, category, slug string) *Page {
+	return l.pages[locale+"/"+category+"/"+slug]
+}
+
+// AllPages returns every page; used by the search index endpoint.
+func (l *Library) AllPages() []*Page {
+	out := make([]*Page, 0, len(l.pages))
+	for _, p := range l.pages {
+		out = append(out, p)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Path < out[j].Path })
+	return out
+}
diff --git a/internal/render/markdown.go b/internal/render/markdown.go
new file mode 100644
index 0000000..60dab1f
--- /dev/null
+++ b/internal/render/markdown.go
@@ -0,0 +1,35 @@
+// Package render converts markdown to HTML using goldmark.
+//
+// Zero-trust posture: raw HTML in markdown is escaped. Even though content comes from
+// an operator-mounted volume (not a request), defense-in-depth keeps a stray <script>
+// or <iframe> in a tutorial from running in a visitor's browser. Authors get goldmark
+// + GFM + footnotes; raw HTML in .md is rendered as text.
+package render
+
+import (
+	"bytes"
+
+	"github.com/yuin/goldmark"
+	"github.com/yuin/goldmark/extension"
+	"github.com/yuin/goldmark/parser"
+)
+
+var md = goldmark.New(
+	goldmark.WithExtensions(
+		extension.GFM, // tables, strikethrough, autolink, tasklist
+		extension.Footnote,
+	),
+	goldmark.WithParserOptions(
+		parser.WithAutoHeadingID(),
+	),
+	// No WithUnsafe() — raw HTML stays escaped.
+)
+
+// Markdown renders a markdown body to HTML.
+func Markdown(source []byte) (string, error) {
+	var buf bytes.Buffer
+	if err := md.Convert(source, &buf); err != nil {
+		return "", err
+	}
+	return buf.String(), nil
+}
diff --git a/internal/server/server.go b/internal/server/server.go
new file mode 100644
index 0000000..b35be11
--- /dev/null
+++ b/internal/server/server.go
@@ -0,0 +1,344 @@
+// Package server is the HTTP layer: route mux, page handlers, search index endpoint.
+//
+// Routing:
+//
+//	GET /                           → redirect to /<defaultLocale>/
+//	GET /<locale>/                  → home (lists categories)
+//	GET /<locale>/<category>/       → category landing (lists pages)
+//	GET /<locale>/<category>/<slug> → render single page
+//	GET /search.json                → ?lang=<locale> returns search index for client-side FlexSearch
+//	GET /static/...                 → bundled CSS / htmx.min.js
+//	GET /healthz                    → liveness
+package server
+
+import (
+	"context"
+	"embed"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"html/template"
+	"io/fs"
+	"log/slog"
+	"net/http"
+	"strings"
+	"sync/atomic"
+	"time"
+
+	"git.timemachine.center/Timemachine/automc-tutorials/internal/content"
+	"git.timemachine.center/Timemachine/automc-tutorials/internal/render"
+)
+
+//go:embed all:templates
+var templatesFS embed.FS
+
+//go:embed all:static
+var staticFS embed.FS
+
+// Server holds the swappable library + per-page template trees + default locale.
+// SwapLibrary is used by SIGHUP-driven reload in main.go.
+//
+// Templates are parsed as one base tree (layout.html) plus a clone per page
+// template so that `{{define "title"}}` / `{{define "content"}}` blocks from
+// home/category/page don't overwrite each other. Rendering invokes the
+// "layout" template name from the page-specific tree.
+type Server struct {
+	lib       atomic.Pointer[content.Library]
+	tmpls     map[string]*template.Template
+	defLocale string
+}
+
+// New constructs a Server with the given library + default locale.
+func New(lib *content.Library, defaultLocale string) *Server {
+	s := &Server{defLocale: defaultLocale, tmpls: make(map[string]*template.Template)}
+	s.lib.Store(lib)
+
+	sub, err := fs.Sub(templatesFS, "templates")
+	if err != nil {
+		panic(fmt.Errorf("subFS templates: %w", err))
+	}
+	base := template.Must(template.New("base").Funcs(funcMap()).ParseFS(sub, "layout.html"))
+	for _, name := range []string{"home.html", "category.html", "page.html"} {
+		t := template.Must(base.Clone())
+		template.Must(t.ParseFS(sub, name))
+		s.tmpls[name] = t
+	}
+	return s
+}
+
+// SwapLibrary replaces the active library atomically (used by SIGHUP reload).
+func (s *Server) SwapLibrary(lib *content.Library) { s.lib.Store(lib) }
+
+func (s *Server) currentLib() *content.Library { return s.lib.Load() }
+
+// Run starts the HTTP server and blocks until ctx is cancelled.
+func (s *Server) Run(ctx context.Context, addr string) error {
+	mux := http.NewServeMux()
+	mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusNoContent)
+	})
+	mux.HandleFunc("GET /search.json", s.handleSearch)
+	mux.HandleFunc("GET /{$}", s.handleRoot)
+	mux.HandleFunc("GET /{locale}/{$}", s.handleHome)
+	mux.HandleFunc("GET /{locale}/{category}/{$}", s.handleCategory)
+	mux.HandleFunc("GET /{locale}/{category}/{slug}", s.handlePage)
+
+	// /static/* is served BEFORE the mux to avoid pattern conflicts between
+	// `/static/` and `/{locale}/{$}` (Go 1.22's mux can't pick a winner —
+	// they overlap at exactly "/static/"). Wrapping order: securityHeaders
+	// → staticFirst → mux.
+	staticSub, err := fs.Sub(staticFS, "static")
+	if err != nil {
+		return err
+	}
+	staticFileHandler := http.StripPrefix("/static/", http.FileServerFS(staticSub))
+	staticHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Zero-trust posture: only GET/HEAD, no directory listings, no dotfiles.
+		if r.Method != http.MethodGet && r.Method != http.MethodHead {
+			w.Header().Set("Allow", "GET, HEAD")
+			http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+			return
+		}
+		path := r.URL.Path
+		if strings.HasSuffix(path, "/") || strings.Contains(path, "/.") {
+			http.NotFound(w, r)
+			return
+		}
+		w.Header().Set("Cache-Control", "public, max-age=3600")
+		staticFileHandler.ServeHTTP(w, r)
+	})
+
+	root := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if strings.HasPrefix(r.URL.Path, "/static/") {
+			staticHandler.ServeHTTP(w, r)
+			return
+		}
+		mux.ServeHTTP(w, r)
+	})
+
+	srv := &http.Server{
+		Addr:              addr,
+		Handler:           securityHeaders(root),
+		ReadHeaderTimeout: 10 * time.Second,
+		ReadTimeout:       30 * time.Second,
+		WriteTimeout:      60 * time.Second,
+		IdleTimeout:       120 * time.Second,
+	}
+
+	errCh := make(chan error, 1)
+	go func() {
+		slog.Info("listening", "addr", addr, "default_locale", s.defLocale)
+		err := srv.ListenAndServe()
+		if !errors.Is(err, http.ErrServerClosed) {
+			errCh <- err
+			return
+		}
+		errCh <- nil
+	}()
+
+	select {
+	case <-ctx.Done():
+		shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+		defer cancel()
+		_ = srv.Shutdown(shutdownCtx)
+		return <-errCh
+	case err := <-errCh:
+		return err
+	}
+}
+
+// --- Handlers ---
+
+func (s *Server) handleRoot(w http.ResponseWriter, r *http.Request) {
+	http.Redirect(w, r, "/"+s.defLocale+"/", http.StatusFound)
+}
+
+func (s *Server) handleHome(w http.ResponseWriter, r *http.Request) {
+	locale := r.PathValue("locale")
+	lib := s.currentLib()
+	if !lib.HasLocale(locale) {
+		http.NotFound(w, r)
+		return
+	}
+	s.render(w, "home.html", map[string]any{
+		"Locale":     locale,
+		"Locales":    lib.Locales(),
+		"Categories": lib.Categories(locale),
+		"Path":       []crumb{},
+	})
+}
+
+func (s *Server) handleCategory(w http.ResponseWriter, r *http.Request) {
+	locale := r.PathValue("locale")
+	categoryName := r.PathValue("category")
+	lib := s.currentLib()
+	if !lib.HasLocale(locale) {
+		http.NotFound(w, r)
+		return
+	}
+	var cat *content.Category
+	for _, c := range lib.Categories(locale) {
+		c := c
+		if c.Name == categoryName {
+			cat = &c
+			break
+		}
+	}
+	if cat == nil {
+		http.NotFound(w, r)
+		return
+	}
+
+	var indexHTML template.HTML
+	if cat.Index != nil {
+		out, err := render.Markdown(cat.Index.Source)
+		if err == nil {
+			indexHTML = template.HTML(out)
+		}
+	}
+	s.render(w, "category.html", map[string]any{
+		"Locale":    locale,
+		"Locales":   lib.Locales(),
+		"Category":  cat,
+		"IndexHTML": indexHTML,
+		"Path": []crumb{
+			{Label: titleFor(cat), URL: "/" + locale + "/" + cat.Name + "/"},
+		},
+	})
+}
+
+func (s *Server) handlePage(w http.ResponseWriter, r *http.Request) {
+	locale := r.PathValue("locale")
+	category := r.PathValue("category")
+	slug := r.PathValue("slug")
+	lib := s.currentLib()
+	page := lib.Page(locale, category, slug)
+	if page == nil {
+		http.NotFound(w, r)
+		return
+	}
+	html, err := render.Markdown(page.Source)
+	if err != nil {
+		http.Error(w, "render error", http.StatusInternalServerError)
+		return
+	}
+	s.render(w, "page.html", map[string]any{
+		"Locale":      locale,
+		"Locales":     lib.Locales(),
+		"Page":        page,
+		"BodyHTML":    template.HTML(html),
+		"Path": []crumb{
+			{Label: humanize(category), URL: "/" + locale + "/" + category + "/"},
+			{Label: page.Title, URL: ""},
+		},
+	})
+}
+
+// handleSearch returns a flat JSON array of {path, title, summary, body} for FlexSearch
+// to index in the browser. Body is plain markdown source — small enough for the page set.
+func (s *Server) handleSearch(w http.ResponseWriter, r *http.Request) {
+	lang := r.URL.Query().Get("lang")
+	if lang == "" {
+		lang = s.defLocale
+	}
+	lib := s.currentLib()
+	type entry struct {
+		Path    string `json:"path"`
+		Title   string `json:"title"`
+		Summary string `json:"summary,omitempty"`
+		Body    string `json:"body"`
+	}
+	var out []entry
+	for _, p := range lib.AllPages() {
+		if p.Locale != lang || p.Slug == "_index" {
+			continue
+		}
+		out = append(out, entry{
+			Path:    "/" + p.Path,
+			Title:   p.Title,
+			Summary: p.Summary,
+			Body:    string(p.Source),
+		})
+	}
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	w.Header().Set("Cache-Control", "public, max-age=300")
+	_ = json.NewEncoder(w).Encode(out)
+}
+
+// --- Helpers ---
+
+type crumb struct {
+	Label string
+	URL   string // empty for the active leaf
+}
+
+func (s *Server) render(w http.ResponseWriter, name string, data map[string]any) {
+	t, ok := s.tmpls[name]
+	if !ok {
+		slog.Error("template not found", "name", name)
+		http.Error(w, "template error", http.StatusInternalServerError)
+		return
+	}
+	w.Header().Set("Content-Type", "text/html; charset=utf-8")
+	if err := t.ExecuteTemplate(w, "layout", data); err != nil {
+		slog.Error("template render", "name", name, "err", err)
+	}
+}
+
+func titleFor(c *content.Category) string {
+	if c.Index != nil {
+		return c.Index.Title
+	}
+	return humanize(c.Name)
+}
+
+func humanize(s string) string {
+	s = strings.ReplaceAll(s, "-", " ")
+	s = strings.ReplaceAll(s, "_", " ")
+	if s == "" {
+		return ""
+	}
+	return strings.ToUpper(s[:1]) + s[1:]
+}
+
+func funcMap() template.FuncMap {
+	return template.FuncMap{
+		"humanize": humanize,
+	}
+}
+
+// securityHeaders adds the hardening headers expected for a public, no-auth,
+// internet-facing service. The intent is zero-trust: every visitor is anonymous
+// and untrusted, and the only data we serve is rendered markdown plus the static
+// CSS/JS bundle in /static/. Headers are tuned for that surface specifically.
+//
+//   - CSP is tight: 'self' for default/script/style/connect; images from data: + https:.
+//     'unsafe-inline' is deliberately absent — templates have no inline styles or
+//     scripts, and goldmark output (with WithUnsafe disabled) contains neither.
+//   - HSTS is set assuming TLS termination upstream (k8s ingress).
+//   - COOP/CORP isolate the document from cross-origin actors.
+//   - Permissions-Policy disables every browser capability we don't use.
+func securityHeaders(next http.Handler) http.Handler {
+	const csp = "default-src 'self'; " +
+		"img-src 'self' data: https:; " +
+		"style-src 'self'; " +
+		"script-src 'self'; " +
+		"connect-src 'self'; " +
+		"object-src 'none'; " +
+		"base-uri 'self'; " +
+		"form-action 'self'; " +
+		"frame-ancestors 'none'"
+	const permissionsPolicy = "accelerometer=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()"
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		h := w.Header()
+		h.Set("X-Content-Type-Options", "nosniff")
+		h.Set("X-Frame-Options", "DENY")
+		h.Set("Referrer-Policy", "no-referrer")
+		h.Set("Strict-Transport-Security", "max-age=31536000; includeSubDomains")
+		h.Set("Cross-Origin-Opener-Policy", "same-origin")
+		h.Set("Cross-Origin-Resource-Policy", "same-origin")
+		h.Set("Content-Security-Policy", csp)
+		h.Set("Permissions-Policy", permissionsPolicy)
+		next.ServeHTTP(w, r)
+	})
+}
diff --git a/internal/server/static/search.js b/internal/server/static/search.js
new file mode 100644
index 0000000..eaf26b5
--- /dev/null
+++ b/internal/server/static/search.js
@@ -0,0 +1,71 @@
+// search.js — minimal client-side search.
+// Loads /search.json?lang=<locale>, builds an in-memory index, renders results
+// as the user types in the header search box.
+//
+// Deliberately tiny — no FlexSearch dependency yet (the page set is small,
+// linear scan with case-insensitive substring is plenty). Swap in FlexSearch
+// or Lunr if the corpus grows past a few hundred pages.
+(function () {
+  const input = document.getElementById('search-input');
+  const results = document.getElementById('search-results');
+  if (!input || !results) return;
+
+  const lang = document.documentElement.lang || 'en';
+  let pages = [];
+  let loaded = false;
+
+  function loadIndex() {
+    if (loaded) return Promise.resolve();
+    return fetch('/search.json?lang=' + encodeURIComponent(lang))
+      .then(r => r.json())
+      .then(data => { pages = data || []; loaded = true; })
+      .catch(() => { /* silent — search just stays empty */ });
+  }
+
+  function escapeHtml(s) {
+    return String(s).replace(/[&<>"']/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
+  }
+
+  function search(q) {
+    if (!q || q.length < 2) return [];
+    const needle = q.toLowerCase();
+    const out = [];
+    for (const p of pages) {
+      const titleHit = p.title && p.title.toLowerCase().includes(needle);
+      const summaryHit = p.summary && p.summary.toLowerCase().includes(needle);
+      const bodyHit = p.body && p.body.toLowerCase().includes(needle);
+      if (titleHit || summaryHit || bodyHit) {
+        // crude scoring: title > summary > body
+        const score = (titleHit ? 100 : 0) + (summaryHit ? 10 : 0) + (bodyHit ? 1 : 0);
+        out.push({ ...p, score });
+      }
+      if (out.length >= 50) break;
+    }
+    out.sort((a, b) => b.score - a.score);
+    return out.slice(0, 8);
+  }
+
+  function render(matches) {
+    if (!matches.length) { results.hidden = true; results.innerHTML = ''; return; }
+    results.innerHTML = matches.map(m =>
+      `<li><a href="${escapeHtml(m.path)}">
+        <span class="title">${escapeHtml(m.title)}</span>
+        ${m.summary ? `<span class="summary">${escapeHtml(m.summary)}</span>` : ''}
+      </a></li>`
+    ).join('');
+    results.hidden = false;
+  }
+
+  let timer = null;
+  input.addEventListener('focus', loadIndex);
+  input.addEventListener('input', () => {
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      loadIndex().then(() => render(search(input.value.trim())));
+    }, 80);
+  });
+  input.addEventListener('blur', () => {
+    // Delay so click on a result registers before hiding.
+    setTimeout(() => { results.hidden = true; }, 150);
+  });
+})();
diff --git a/internal/server/static/style.css b/internal/server/static/style.css
new file mode 100644
index 0000000..7706bf6
--- /dev/null
+++ b/internal/server/static/style.css
@@ -0,0 +1,152 @@
+/* automc-tutorials — minimal opinionated CSS, no framework. */
+* { box-sizing: border-box; }
+html { font: 16px/1.55 system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; color: #222; background: #fff; }
+body { margin: 0; }
+a { color: #2c5fa3; text-decoration: none; }
+a:hover { text-decoration: underline; }
+
+.site-header {
+  display: flex; align-items: center; gap: 1rem;
+  padding: 0.75rem 1.25rem;
+  border-bottom: 1px solid #e5e5e5;
+  background: #fafafa;
+  position: sticky; top: 0; z-index: 10;
+}
+.brand { font-weight: 700; font-size: 1.05rem; color: #222; }
+.brand:hover { text-decoration: none; }
+
+.search { position: relative; flex: 1; max-width: 28rem; }
+.search input {
+  width: 100%; padding: 0.4rem 0.6rem;
+  border: 1px solid #ccc; border-radius: 6px;
+  font: inherit;
+}
+#search-results {
+  position: absolute; top: 100%; left: 0; right: 0;
+  margin: 0.25rem 0 0; padding: 0; list-style: none;
+  background: #fff; border: 1px solid #ddd; border-radius: 6px;
+  max-height: 18rem; overflow-y: auto;
+  box-shadow: 0 4px 12px rgba(0,0,0,0.08);
+}
+#search-results li { padding: 0; }
+#search-results a {
+  display: block; padding: 0.5rem 0.75rem;
+  border-bottom: 1px solid #f0f0f0;
+  color: #222;
+}
+#search-results a:hover { background: #f4f7fb; text-decoration: none; }
+#search-results .title { font-weight: 600; }
+#search-results .summary { display: block; font-size: 0.85rem; color: #666; }
+
+.locale-switch a.lang {
+  display: inline-block;
+  padding: 0.25rem 0.5rem;
+  margin-left: 0.25rem;
+  border-radius: 4px;
+  text-transform: uppercase;
+  font-size: 0.8rem;
+  color: #555;
+}
+.locale-switch a.lang.active { background: #2c5fa3; color: #fff; }
+
+.breadcrumbs {
+  padding: 0.5rem 1.25rem;
+  font-size: 0.9rem; color: #666;
+  border-bottom: 1px solid #f0f0f0;
+}
+.breadcrumbs .sep { margin: 0 0.4rem; color: #aaa; }
+.breadcrumbs .active { color: #222; }
+
+main {
+  max-width: 50rem;
+  margin: 0 auto;
+  padding: 2rem 1.25rem;
+}
+
+h1 { font-size: 1.75rem; margin: 0 0 0.5rem; }
+h2 { font-size: 1.35rem; margin: 1.5rem 0 0.5rem; }
+.lead { font-size: 1.1rem; color: #555; margin: 0.5rem 0 1.5rem; }
+
+.category-list { list-style: none; padding: 0; display: grid; gap: 1rem; }
+.category-item a {
+  display: block;
+  padding: 1rem 1.25rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 8px;
+  color: #222;
+  transition: border-color 0.15s, box-shadow 0.15s;
+}
+.category-item a:hover {
+  border-color: #2c5fa3;
+  box-shadow: 0 2px 8px rgba(44,95,163,0.1);
+  text-decoration: none;
+}
+.category-item h2 { margin: 0 0 0.25rem; font-size: 1.15rem; }
+.category-item p { margin: 0.25rem 0; color: #555; }
+.category-item .page-count { font-size: 0.85rem; color: #888; }
+
+.page-list { list-style: none; padding: 0; }
+.page-list li { margin-bottom: 0.5rem; }
+.page-list a {
+  display: block;
+  padding: 0.6rem 0.8rem;
+  border-left: 3px solid transparent;
+  border-radius: 4px;
+}
+.page-list a:hover { border-left-color: #2c5fa3; background: #f7f9fc; text-decoration: none; }
+.page-list strong { color: #222; }
+.page-list .summary { display: block; font-size: 0.9rem; color: #666; margin-top: 0.15rem; }
+
+.page-header { margin-bottom: 1.5rem; }
+.page-header .summary { color: #555; font-size: 1.05rem; }
+
+.prose { line-height: 1.7; }
+.prose code {
+  background: #f4f4f5; padding: 0.1rem 0.35rem; border-radius: 3px;
+  font-size: 0.9em; font-family: ui-monospace, "SF Mono", Menlo, monospace;
+}
+.prose pre {
+  background: #1e1e2e; color: #cdd6f4;
+  padding: 1rem; border-radius: 8px; overflow-x: auto;
+  font-size: 0.9rem; line-height: 1.5;
+}
+.prose pre code { background: transparent; padding: 0; color: inherit; }
+.prose img { max-width: 100%; border-radius: 8px; }
+.prose blockquote {
+  border-left: 4px solid #2c5fa3;
+  margin: 1rem 0; padding: 0.5rem 1rem;
+  background: #f7f9fc;
+}
+.prose table { border-collapse: collapse; width: 100%; margin: 1rem 0; }
+.prose th, .prose td { border: 1px solid #e0e0e0; padding: 0.5rem 0.75rem; text-align: left; }
+.prose th { background: #fafafa; }
+
+.site-footer {
+  margin-top: 4rem;
+  padding: 1.5rem 1.25rem;
+  border-top: 1px solid #e5e5e5;
+  text-align: center;
+  font-size: 0.85rem;
+  color: #888;
+}
+
+@media (prefers-color-scheme: dark) {
+  html { color: #ddd; background: #1a1a1a; }
+  .site-header { background: #222; border-color: #333; }
+  .brand { color: #ddd; }
+  a { color: #6aa2dc; }
+  .search input { background: #2a2a2a; border-color: #444; color: #ddd; }
+  #search-results { background: #222; border-color: #444; }
+  #search-results a { color: #ddd; border-color: #2f2f2f; }
+  #search-results a:hover { background: #2a2f3a; }
+  .breadcrumbs { color: #999; border-color: #333; }
+  .breadcrumbs .active { color: #eee; }
+  .category-item a { background: #222; border-color: #333; color: #ddd; }
+  .category-item a:hover { border-color: #6aa2dc; }
+  .page-list a:hover { background: #2a2a2a; }
+  .prose code { background: #2a2a2a; color: #f4f4f5; }
+  .prose blockquote { background: #222; }
+  .prose th { background: #222; }
+  .prose th, .prose td { border-color: #333; }
+  .site-footer { border-color: #333; color: #777; }
+}
diff --git a/internal/server/templates/category.html b/internal/server/templates/category.html
new file mode 100644
index 0000000..f87ada2
--- /dev/null
+++ b/internal/server/templates/category.html
@@ -0,0 +1,18 @@
+{{define "title"}}{{if .Category.Index}}{{.Category.Index.Title}}{{else}}{{humanize .Category.Name}}{{end}} · automc tutorials{{end}}
+{{define "content"}}
+<article class="category">
+  <h1>{{if .Category.Index}}{{.Category.Index.Title}}{{else}}{{humanize .Category.Name}}{{end}}</h1>
+  {{with .IndexHTML}}<div class="prose">{{.}}</div>{{end}}
+
+  <ul class="page-list">
+    {{range .Category.Pages}}
+      <li>
+        <a href="/{{$.Locale}}/{{.Category}}/{{.Slug}}">
+          <strong>{{.Title}}</strong>
+          {{with .Summary}}<span class="summary">{{.}}</span>{{end}}
+        </a>
+      </li>
+    {{end}}
+  </ul>
+</article>
+{{end}}
diff --git a/internal/server/templates/home.html b/internal/server/templates/home.html
new file mode 100644
index 0000000..616db7c
--- /dev/null
+++ b/internal/server/templates/home.html
@@ -0,0 +1,17 @@
+{{define "title"}}automc tutorials{{end}}
+{{define "content"}}
+<h1>Tutorials</h1>
+<p class="lead">Pick a topic. New here? Start with <strong>install client</strong>, then <strong>register</strong>.</p>
+
+<ul class="category-list">
+  {{range .Categories}}
+    <li class="category-item">
+      <a href="/{{$.Locale}}/{{.Name}}/">
+        <h2>{{if .Index}}{{.Index.Title}}{{else}}{{humanize .Name}}{{end}}</h2>
+        {{with .Index}}{{with .Summary}}<p>{{.}}</p>{{end}}{{end}}
+        <span class="page-count">{{len .Pages}} page{{if ne (len .Pages) 1}}s{{end}}</span>
+      </a>
+    </li>
+  {{end}}
+</ul>
+{{end}}
diff --git a/internal/server/templates/layout.html b/internal/server/templates/layout.html
new file mode 100644
index 0000000..0f16bde
--- /dev/null
+++ b/internal/server/templates/layout.html
@@ -0,0 +1,43 @@
+{{define "layout"}}<!doctype html>
+<html lang="{{.Locale}}">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{{block "title" .}}automc tutorials{{end}}</title>
+  <link rel="stylesheet" href="/static/style.css">
+</head>
+<body>
+  <header class="site-header">
+    <a class="brand" href="/{{.Locale}}/">automc tutorials</a>
+    <div class="search">
+      <input type="search" id="search-input" placeholder="Search..." autocomplete="off">
+      <ul id="search-results" hidden></ul>
+    </div>
+    <nav class="locale-switch">
+      {{range .Locales}}
+        <a href="/{{.}}/" class="lang {{if eq . $.Locale}}active{{end}}">{{.}}</a>
+      {{end}}
+    </nav>
+  </header>
+
+  {{with .Path}}
+    <nav class="breadcrumbs">
+      <a href="/{{$.Locale}}/">home</a>
+      {{range .}}
+        <span class="sep">›</span>
+        {{if .URL}}<a href="{{.URL}}">{{.Label}}</a>{{else}}<span class="active">{{.Label}}</span>{{end}}
+      {{end}}
+    </nav>
+  {{end}}
+
+  <main>
+    {{block "content" .}}{{end}}
+  </main>
+
+  <footer class="site-footer">
+    <span>automc-tutorials · <a href="https://git.timemachine.center/Timemachine/automc-tutorials">source</a></span>
+  </footer>
+
+  <script src="/static/search.js" defer></script>
+</body>
+</html>{{end}}
diff --git a/internal/server/templates/page.html b/internal/server/templates/page.html
new file mode 100644
index 0000000..e7c97d1
--- /dev/null
+++ b/internal/server/templates/page.html
@@ -0,0 +1,10 @@
+{{define "title"}}{{.Page.Title}} · automc tutorials{{end}}
+{{define "content"}}
+<article class="page">
+  <header class="page-header">
+    <h1>{{.Page.Title}}</h1>
+    {{with .Page.Summary}}<p class="summary">{{.}}</p>{{end}}
+  </header>
+  <div class="prose">{{.BodyHTML}}</div>
+</article>
+{{end}}