diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml
index a146c0a..63952cd 100644
--- a/.gitea/workflows/ci.yml
+++ b/.gitea/workflows/ci.yml
@@ -31,6 +31,9 @@ jobs:
       - name: Format check
         run: pnpm format:check
 
+      - name: Markdown lint
+        run: pnpm md:lint
+
       - name: Typecheck
         run: pnpm typecheck
 
diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc
index 3ec0ab4..877f908 100644
--- a/.markdownlint-cli2.jsonc
+++ b/.markdownlint-cli2.jsonc
@@ -16,8 +16,8 @@
     // Rules DISABLED (Prettier owns these OR they fire on non-author-controlled files):
     "MD041": false, // first-line-h1: CLAUDE.md legitimately starts with ## Project
     "MD034": false, // no-bare-urls: CLAUDE.md version table uses pkg@version syntax
-    "MD036": false // no-emphasis-as-heading: docs/API.md uses **Response 200** as label
+    "MD036": false, // no-emphasis-as-heading: docs/API.md uses **Response 200** as label
   },
   "globs": ["docs/**/*.md", "*.md", "apps/**/*.md"],
-  "ignores": [".planning/**", "node_modules/**", "**/node_modules/**", ".pnpm-store/**"]
+  "ignores": [".planning/**", "node_modules/**", "**/node_modules/**", ".pnpm-store/**"],
 }
diff --git a/README.md b/README.md
index f96ba68..8d4efe6 100644
--- a/README.md
+++ b/README.md
@@ -75,7 +75,7 @@ The API listens on port 3000. The PWA build is served separately (Vite `preview`
 
 ## Monorepo Structure
 
-```
+```text
 apps/
   api/        Hono backend — CalDAV sync, OIDC auth, lists API, push notifications
   pwa/        React 19 PWA — calendar view, lists UI, service worker
@@ -116,7 +116,7 @@ docker-compose.dev.yml   Dev overrides (bind-mount src/, expose DB/Redis ports)
 
 FamilySync reads and writes calendars via CalDAV against Fastmail — not JMAP (not available for Fastmail calendars). Configure your Fastmail app password under the "Mail, Contacts & Calendars" scope. The principal URL follows the pattern:
 
-```
+```text
 https://caldav.fastmail.com/dav/principals/user/<your-fastmail-address>/
 ```
 
diff --git a/apps/api/README.md b/apps/api/README.md
index dec2081..6ac07dd 100644
--- a/apps/api/README.md
+++ b/apps/api/README.md
@@ -16,7 +16,7 @@ Part of the [FamilySync monorepo](../../README.md).
 
 ## Source layout
 
-```
+```text
 src/
   index.ts              Hono app entrypoint; server startup; background worker initialization
   routes/
diff --git a/apps/pwa/README.md b/apps/pwa/README.md
index 1b05479..55e4d19 100644
--- a/apps/pwa/README.md
+++ b/apps/pwa/README.md
@@ -42,7 +42,7 @@ The API backend must also be running for most features. See [GETTING-STARTED.md]
 
 ## Source layout
 
-```
+```text
 src/
   api/          # Typed fetch wrappers for @familysync/api (client.ts, listsClient.ts)
   components/   # Shared UI components co-located with their *.test.tsx files
diff --git a/apps/pwa/e2e/README.md b/apps/pwa/e2e/README.md
index 54d2509..18ec683 100644
--- a/apps/pwa/e2e/README.md
+++ b/apps/pwa/e2e/README.md
@@ -73,7 +73,7 @@ Set `DB_PASSWORD` (and other non-default values) via the shell or the repo root
 
 The API enforces this via `apps/api/src/auth/devBypass.ts`:
 
-```
+```text
 if (process.env.NODE_ENV === 'production') → bypass is a no-op (always)
 if (process.env.DEV_AUTH_BYPASS !== 'true') → bypass is a no-op
 ```
diff --git a/docs/API.md b/docs/API.md
index cc7ed11..199ef2d 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -514,7 +514,7 @@ Streams `heartbeat` events every 10 seconds indefinitely. Used as a Pangolin tun
 
 **Event format**
 
-```
+```text
 event: heartbeat
 id: 0
 data: {"ts":"2025-06-10T14:00:00.000Z","id":0}
@@ -541,7 +541,7 @@ A `heartbeat` event is sent every 30 seconds to keep the Pangolin connection ali
 
 **Event format example**
 
-```
+```text
 event: item:added
 id: 1-1718020800000
 data: {"type":"item:added","listId":1,"payload":{"id":11,"listId":1,"text":"Eggs"}}
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 3efd060..53f8505 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -61,7 +61,7 @@ graph TD
 
 ## Directory Structure
 
-```
+```text
 familysync/
 ├── apps/
 │   ├── api/                  # Hono backend (Node 22 + TypeScript)
@@ -168,7 +168,7 @@ familysync/
 
 ### Backend modules
 
-```
+```text
 routes/events.ts  ──→  broker/expand.ts     (read: RRULE expansion)
                   ──→  calendarOutbox (DB)   (write: enqueue)
                   ──→  broker/sync.ts        (write-sync after outbox drain)
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
index 9c4d5f4..4b3bf8d 100644
--- a/docs/DEVELOPMENT.md
+++ b/docs/DEVELOPMENT.md
@@ -6,7 +6,7 @@ Local development setup and workflows for FamilySync — a pnpm monorepo with tw
 
 ## Repo Layout
 
-```
+```text
 familysync/
 ├── apps/
 │   ├── api/          # Hono API server — Node.js 22, TypeScript, Drizzle/MariaDB
@@ -19,7 +19,7 @@ familysync/
 
 Key paths inside `apps/api/src/`:
 
-```
+```text
 src/
 ├── db/
 │   ├── schema.ts       # Drizzle table definitions (source of truth for migrations)
diff --git a/docs/GETTING-STARTED.md b/docs/GETTING-STARTED.md
index af5bd7d..755f327 100644
--- a/docs/GETTING-STARTED.md
+++ b/docs/GETTING-STARTED.md
@@ -49,9 +49,11 @@ Open `.env` and fill in the required values. See [docs/CONFIGURATION.md](CONFIGU
 
 - `DB_PASSWORD` and `DB_ROOT_PASSWORD` — pick any local passwords
 - `APP_PASSWORD_ENCRYPTION_KEY` — 64 hex characters; generate with:
+
   ```bash
   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
   ```
+
 - `DEV_AUTH_BYPASS=true` — bypasses the live Authelia OIDC flow for local dev
 - `DB_HOST=localhost` — the dev Docker Compose exposes MariaDB on the host at `localhost:3306`