diff --git a/CHANGELOG.md b/CHANGELOG.md
index 304a0d3b..1c45b996 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,7 +3,7 @@
 
 ### Changed
 
-- Documentation generator swapped from `mkdocs-material` to `zensical`. Drops `mkdocs` / `mkdocs-material` dev deps. `build-docs` workflow now runs `uv run zensical build` and publishes via the GitHub Pages artifact actions instead of `mkdocs gh-deploy`.
+- Documentation generator swapped from `mkdocs-material` to `zensical`. Drops `mkdocs` / `mkdocs-material` dev deps, replaces `mkdocs.yml` with `zensical.toml`, adds `overrides/main.html` (OG/Twitter share meta) and `docs/stylesheets/extra.css`. `build-docs` workflow now runs `uv run zensical build` and publishes via the GitHub Pages artifact actions instead of `mkdocs gh-deploy`.
 
 ## [0.48.0] - 2026-05-20
 
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
new file mode 100644
index 00000000..0a2a3674
--- /dev/null
+++ b/docs/stylesheets/extra.css
@@ -0,0 +1 @@
+/* haiku.rag site overrides */
diff --git a/mkdocs.yml b/mkdocs.yml
deleted file mode 100644
index 6e458c42..00000000
--- a/mkdocs.yml
+++ /dev/null
@@ -1,106 +0,0 @@
-site_name: haiku.rag
-site_description: Opinionated agentic RAG powered by LanceDB, Pydantic AI, and Docling.
-site_url: https://ggozad.github.io/haiku.rag/
-theme:
-  palette:
-    - media: "(prefers-color-scheme)"
-      toggle:
-        icon: material/lightbulb-auto
-        name: Switch to light mode
-    - media: "(prefers-color-scheme: light)"
-      scheme: default
-      primary: deep purple
-      accent: amber
-      toggle:
-        icon: material/lightbulb
-        name: Switch to dark mode
-    - media: "(prefers-color-scheme: dark)"
-      scheme: slate
-      primary: deep purple
-      accent: amber
-      toggle:
-        icon: material/lightbulb-outline
-        name: Switch to system preference
-  features:
-    - content.code.annotate
-    - content.code.copy
-    - content.code.select
-    - content.footnote.tooltips
-    - content.tabs.link
-    - content.tooltips
-    - navigation.footer
-    - navigation.indexes
-    - navigation.instant
-    - navigation.instant.prefetch
-    - navigation.instant.progress
-    - navigation.path
-    - navigation.tabs
-    - navigation.tabs.sticky
-    - navigation.top
-    - navigation.tracking
-    - search.highlight
-    - search.share
-    - search.suggest
-    - toc.follow
-
-  icon:
-    repo: fontawesome/brands/github-alt
-  # logo: img/icon-white.svg
-  # favicon: img/favicon.png
-  language: en
-repo_name: ggozad/haiku.rag
-repo_url: https://github.com/ggozad/haiku.rag
-plugins:
-  # Material for MkDocs
-  search:
-nav:
-  - Get started:
-      - index.md
-      - Quickstart: tutorial.md
-      - Installation: installation.md
-  - Use it:
-      - CLI: cli.md
-      - Chat: chat.md
-  - Skills:
-      - skills/index.md
-      - RAG skill: skills/rag.md
-      - Analysis skill: skills/analysis.md
-      - Custom skills: skills/custom.md
-  - Configure:
-      - configuration/index.md
-      - Providers: configuration/providers.md
-      - Search and question answering: configuration/qa.md
-      - Document processing: configuration/processing.md
-      - Storage: configuration/storage.md
-      - Prompts: configuration/prompts.md
-      - Tuning: tuning.md
-  - Production:
-      - Server: server.md
-      - MCP: mcp.md
-      - Remote processing: remote-processing.md
-  - Develop:
-      - Python: python.md
-      - Custom pipelines: custom-pipelines.md
-      - Toolsets: tools.md
-      - Web app: apps.md
-  - Reference:
-      - Benchmarks: benchmarks.md
-      - Development: development.md
-      - Changelog: changelog.md
-markdown_extensions:
-  - admonition
-  - attr_list
-  - pymdownx.details
-  - pymdownx.highlight:
-      anchor_linenums: true
-      line_spans: __span
-      pygments_lang_class: true
-      use_pygments: true
-  - pymdownx.inlinehilite
-  - pymdownx.snippets:
-      base_path: ["."]
-  - pymdownx.superfences:
-      custom_fences:
-        - name: mermaid
-          class: mermaid
-          format: !!python/name:pymdownx.superfences.fence_code_format
diff --git a/overrides/main.html b/overrides/main.html
new file mode 100644
index 00000000..0249f0fb
--- /dev/null
+++ b/overrides/main.html
@@ -0,0 +1,11 @@
+{% extends "base.html" %}
+
+{% block extrahead %}
+<meta property="og:type" content="website">
+<meta property="og:title" content="{% if page.title and page.title != config.site_name %}{{ page.title }} – {{ config.site_name }}{% else %}{{ config.site_name }}{% endif %}">
+<meta property="og:description" content="{{ config.site_description }}">
+<meta property="og:url" content="{{ page.canonical_url }}">
+<meta property="og:image" content="{{ config.site_url }}img/chat-qa.png">
+<meta name="twitter:card" content="summary_large_image">
+<meta name="twitter:image" content="{{ config.site_url }}img/chat-qa.png">
+{% endblock %}
diff --git a/zensical.toml b/zensical.toml
new file mode 100644
index 00000000..1c651fc0
--- /dev/null
+++ b/zensical.toml
@@ -0,0 +1,132 @@
+[project]
+site_name = "haiku.rag"
+site_description = "Opinionated agentic RAG powered by LanceDB, Pydantic AI, and Docling."
+site_url = "https://ggozad.github.io/haiku.rag/"
+repo_url = "https://github.com/ggozad/haiku.rag"
+repo_name = "ggozad/haiku.rag"
+site_author = "Yiorgis Gozadinos"
+copyright = "Copyright &copy; 2025&ndash;2026 Yiorgis Gozadinos"
+extra_css = ["stylesheets/extra.css"]
+
+nav = [
+    { "Get started" = [
+        "index.md",
+        { Quickstart = "tutorial.md" },
+        { Installation = "installation.md" },
+    ] },
+    { "Use it" = [
+        { CLI = "cli.md" },
+        { Chat = "chat.md" },
+    ] },
+    { Skills = [
+        "skills/index.md",
+        { "RAG skill" = "skills/rag.md" },
+        { "Analysis skill" = "skills/analysis.md" },
+        { "Custom skills" = "skills/custom.md" },
+    ] },
+    { Configure = [
+        "configuration/index.md",
+        { Providers = "configuration/providers.md" },
+        { "Search and question answering" = "configuration/qa.md" },
+        { "Document processing" = "configuration/processing.md" },
+        { Storage = "configuration/storage.md" },
+        { Prompts = "configuration/prompts.md" },
+        { Tuning = "tuning.md" },
+    ] },
+    { Production = [
+        { Server = "server.md" },
+        { MCP = "mcp.md" },
+        { "Remote processing" = "remote-processing.md" },
+    ] },
+    { Develop = [
+        { Python = "python.md" },
+        { "Custom pipelines" = "custom-pipelines.md" },
+        { Toolsets = "tools.md" },
+        { "Web app" = "apps.md" },
+    ] },
+    { Reference = [
+        { Benchmarks = "benchmarks.md" },
+        { Development = "development.md" },
+        { Changelog = "changelog.md" },
+    ] },
+]
+
+[project.theme]
+custom_dir = "overrides"
+font.code = "JetBrains Mono"
+features = [
+    "content.action.view",
+    "content.code.annotate",
+    "content.code.copy",
+    "content.code.select",
+    "content.footnote.tooltips",
+    "content.tabs.link",
+    "content.tooltips",
+    "navigation.footer",
+    "navigation.indexes",
+    "navigation.instant",
+    "navigation.instant.prefetch",
+    "navigation.instant.progress",
+    "navigation.path",
+    "navigation.tabs",
+    "navigation.tabs.sticky",
+    "navigation.top",
+    "navigation.tracking",
+    "search.highlight",
+    "search.share",
+    "search.suggest",
+    "toc.follow",
+]
+
+[project.theme.icon]
+repo = "fontawesome/brands/github-alt"
+
+[[project.theme.palette]]
+media = "(prefers-color-scheme)"
+toggle.icon = "material/lightbulb-auto"
+toggle.name = "Switch to light mode"
+
+[[project.theme.palette]]
+media = "(prefers-color-scheme: light)"
+scheme = "default"
+primary = "deep purple"
+accent = "amber"
+toggle.icon = "material/lightbulb"
+toggle.name = "Switch to dark mode"
+
+[[project.theme.palette]]
+media = "(prefers-color-scheme: dark)"
+scheme = "slate"
+primary = "deep purple"
+accent = "amber"
+toggle.icon = "material/lightbulb-outline"
+toggle.name = "Switch to system preference"
+
+[project.markdown_extensions.admonition]
+[project.markdown_extensions.attr_list]
+[project.markdown_extensions."pymdownx.details"]
+[project.markdown_extensions."pymdownx.inlinehilite"]
+
+[project.markdown_extensions."pymdownx.highlight"]
+anchor_linenums = true
+line_spans = "__span"
+pygments_lang_class = true
+use_pygments = true
+
+[project.markdown_extensions."pymdownx.snippets"]
+base_path = ["."]
+
+[project.markdown_extensions."pymdownx.superfences"]
+custom_fences = [
+    { name = "mermaid", class = "mermaid", format = "pymdownx.superfences.fence_code_format" },
+]
+
+[[project.extra.social]]
+icon = "fontawesome/brands/github"
+link = "https://github.com/ggozad/haiku.rag"
+name = "haiku.rag on GitHub"
+
+[[project.extra.social]]
+icon = "simple/pypi"
+link = "https://pypi.org/project/haiku.rag/"
+name = "haiku.rag on PyPI"