diff --git a/README.md b/README.md
index 9e153d3..bf03232 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,24 @@
 <!-- mcp-name: io.github.knowledgestack/ks-mcp -->
 
-# `Knowledge Stack MCP`
-
-> **Focus on agents. We handle document intelligence.**
->
-> A batteries-included [Model Context Protocol](https://modelcontextprotocol.io) server that exposes Knowledge Stack's read-side tools — semantic search, keyword search, document reading, image retrieval, path browsing — to any MCP-compatible client.
->
-> Works with **Claude Desktop**, **Claude Code**, **Cursor**, **Windsurf**, **Zed**, **VS Code (Continue)**, **pydantic-ai**, **LangChain / LangGraph**, **CrewAI**, **Temporal**, the **OpenAI Agents SDK**, and anything else that speaks MCP stdio or Streamable HTTP.
-
-[![PyPI](https://img.shields.io/pypi/v/knowledgestack-mcp)](https://pypi.org/project/knowledgestack-mcp/)
-[![Python](https://img.shields.io/pypi/pyversions/knowledgestack-mcp)](https://pypi.org/project/knowledgestack-mcp/)
-[![CI](https://github.com/knowledgestack/ks-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/knowledgestack/ks-mcp/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![MCP](https://img.shields.io/badge/MCP-1.2+-8A2BE2)](https://modelcontextprotocol.io)
-[![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/McHmxUeS)
+<h1 align="center">Knowledge Stack MCP</h1>
+<p align="center"><strong>One MCP server. Every agent framework. Grounded answers in seconds.</strong></p>
+<p align="center">
+  Production-ready <a href="https://modelcontextprotocol.io">Model Context Protocol</a> server for tenant-scoped semantic search, keyword search, document reading, citations, image retrieval, and one-shot grounded Q&A.
+</p>
+<p align="center">
+  <em>Works out of the box with</em>
+  <strong>Claude Desktop</strong> · <strong>Claude Code</strong> · <strong>Cursor</strong> · <strong>Windsurf</strong> · <strong>Zed</strong> · <strong>VS Code (Continue)</strong> · <strong>pydantic-ai</strong> · <strong>LangChain / LangGraph</strong> · <strong>CrewAI</strong> · <strong>Temporal</strong> · <strong>OpenAI Agents SDK</strong>
+  — anything that speaks MCP stdio or Streamable HTTP.
+</p>
+
+<p align="center">
+  <a href="https://github.com/knowledgestack/ks-mcp/actions/workflows/ci.yml"><img src="https://github.com/knowledgestack/ks-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
+  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-1.2+-8A2BE2" alt="MCP 1.2+"></a>
+  <a href="https://discord.gg/McHmxUeS"><img src="https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
+  <a href="#install"><img src="https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white" alt="Python 3.11+"></a>
+  <a href="#install"><img src="https://img.shields.io/badge/PyPI-coming%20soon-lightgrey" alt="PyPI: coming soon"></a>
+</p>
 
 > ⭐ **If `ks-mcp` saves you a day of wiring up retrieval, please [star the repo](https://github.com/knowledgestack/ks-mcp/stargazers) — it's the single best signal we use to prioritize the [roadmap](#roadmap).**
 > Got a tool you wish existed? [Open a feature request](https://github.com/knowledgestack/ks-mcp/issues/new?template=feature_request.yml). Want a working example? See the [`ks-cookbook`](https://github.com/knowledgestack/ks-cookbook).