diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 7a30f29..30dab78 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -1,26 +1,24 @@
-
-
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
-# Required
 version: 2
 
-# Set the OS, Python version, and other tools you might need
 build:
   os: ubuntu-24.04
   tools:
     python: "3.13"
 
-# Build documentation in the "docs/" directory with Sphinx
 sphinx:
-   configuration: docs/conf.py
+  configuration: docs/conf.py
+  # Keep builds strict-ish without failing on the odd cross-file link.
+  fail_on_warning: false
 
-# Optionally, but recommended,
-# declare the Python requirements required to build your documentation
-# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
-# python:
-#    install:
-#    - requirements: docs/requirements.txt
-        
+# HTML only: the mermaid diagrams need a headless browser to rasterize, which
+# the PDF/epub builders don't have on Read the Docs.
+formats: []
 
+# Only the doc toolchain is installed — the docs are prose, so ConfLens itself
+# (and its heavy LLM / NiceGUI deps) is never imported at build time.
+python:
+  install:
+    - requirements: docs/requirements.txt
diff --git a/README.md b/README.md
index 700b4e3..4a6fd8f 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
 [![Stars](https://img.shields.io/github/stars/picaultj/conflens?logo=github&style=flat)](https://github.com/picaultj/conflens/stargazers)
 [![Last commit](https://img.shields.io/github/last-commit/picaultj/conflens?logo=github)](https://github.com/picaultj/conflens/commits/main)
 [![Issues](https://img.shields.io/github/issues/picaultj/conflens?logo=github)](https://github.com/picaultj/conflens/issues)
-[![License: MPL 2.0](https://img.shields.io/badge/license-MPL%202.0-brightgreen.svg)](LICENSE)
+[![License: MPL 2.0](https://img.shields.io/badge/license-MPL%202.0-brightgreen.svg)](https://github.com/picaultj/conflens/blob/main/LICENSE)
 [![uv](https://img.shields.io/badge/managed%20by-uv-DE5FE9.svg?logo=uv&logoColor=white)](https://docs.astral.sh/uv/)
 [![Built with NiceGUI](https://img.shields.io/badge/UI-NiceGUI-2b6cb0.svg)](https://nicegui.io)
 
@@ -77,7 +77,7 @@ ways:
   plus `OPENAI_BASE_URL` for an OpenAI-compatible endpoint; `LITELLM_API_KEY`).
 - **A `.env` file** in the directory you launch `conflens` from — same keys, one
   `NAME=value` per line. It's loaded automatically from the current working
-  directory (from a clone, copy [`.env.example`](.env.example) as a starting
+  directory (from a clone, copy [`.env.example`](https://github.com/picaultj/conflens/blob/main/.env.example) as a starting
   point). Real environment variables take precedence over `.env`.
 - **The in-app “API key” field** at runtime.
 
diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..170b071
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,39 @@
+"""Sphinx configuration for the ConfLens documentation.
+
+The docs are plain Markdown (rendered through MyST), so this build never
+imports ConfLens itself — no LLM/NiceGUI dependencies are needed on Read the
+Docs. The version is read straight from ``pyproject.toml`` to keep it in sync
+with the release that `release.yml` bumps.
+"""
+
+import tomllib
+from pathlib import Path
+
+_pyproject = tomllib.loads(
+    (Path(__file__).parent.parent / "pyproject.toml").read_text(encoding="utf-8")
+)
+
+project = "ConfLens"
+author = _pyproject["project"]["authors"][0]["name"]
+copyright = f"2025, {author}"  # noqa: A001 - Sphinx expects this name
+release = _pyproject["project"]["version"]
+version = ".".join(release.split(".")[:2])
+
+extensions = ["myst_parser", "sphinxcontrib.mermaid"]
+
+exclude_patterns = ["_build", "requirements.txt", "Thumbs.db", ".DS_Store"]
+
+# -- MyST ---------------------------------------------------------------------
+# `colon_fence` lets directives be written as ::: blocks; heading anchors make
+# the README's in-page "Contents" links (#quick-start, ...) resolve.
+myst_enable_extensions = ["colon_fence", "deflist", "linkify", "substitution"]
+myst_heading_anchors = 3
+
+# Render GitHub-style ```mermaid fences (used throughout ARCHITECTURE.md and the
+# README) through sphinxcontrib-mermaid instead of trying to syntax-highlight them.
+myst_fence_as_directive = ["mermaid"]
+
+# -- HTML ---------------------------------------------------------------------
+html_theme = "furo"
+html_title = f"{project} {release}"
+html_static_path = ["_static"]
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..8a386ee
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,14 @@
+# ConfLens
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+
+ARCHITECTURE
+```
+
+```{include} ../README.md
+:start-line: 1
+:relative-docs: docs/
+:relative-images:
+```
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 0000000..5048cee
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,5 @@
+# Documentation toolchain for the Read the Docs build (see ../.readthedocs.yaml).
+sphinx>=8.1
+myst-parser[linkify]>=4.0
+sphinxcontrib-mermaid>=1.0
+furo>=2024.8.6