feat: lock positioning + rewrite hero around canonical-source framing (#25)

PR #1 of 6 in v0.1.5 launch wave. Locks positioning sentence + README hero rewrite + glama/server/pyproject description alignment + token-frugal addition to PyPI summary.

Author: ayhammouda

.planning/POSITIONING.md

@@ -0,0 +1,20 @@
+# Locked positioning (decision 9.1, locked 2026-05-14)
+
+**Sentence (verbatim):**
+
+> For AI coding agents writing Python, python-docs-mcp-server is the canonical Python stdlib oracle: exact symbols, exact sections, exact versions — offline, **always free, always MIT**, token-frugal.
+
+**Use verbatim (no rewording) in:**
+
+- `README.md` hero
+- GitHub repo `About` text
+- `LAUNCH-POST.md` lede
+- Talk bio
+
+**Adapt for length and grammar in (preserve key phrases: `canonical Python stdlib oracle`, `always free, always MIT`, `token-frugal`):**
+
+- `glama.json` `description` — long marketing form (Glama directory display)
+- `server.json` `description` — medium form (MCP Registry display)
+- `pyproject.toml` `description` — short form (PyPI summary, ≤512 chars)
+
+The locked sentence is the anchor; adapted forms must keep the three key phrases and the wedge claim (canonical / version-aware / offline). They may drop "exact symbols, exact sections, exact versions" for brevity if needed, but never the three anchors above.

README.md

@@ -2,6 +2,8 @@
 
 <!-- mcp-name: io.github.ayhammouda/python-docs-mcp-server -->
 
+**For AI coding agents writing Python, `python-docs-mcp-server` is the canonical Python stdlib oracle: exact symbols, exact sections, exact versions — offline, *always free, always MIT*, token-frugal.**
+
 [![CI](https://github.com/ayhammouda/python-docs-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/ayhammouda/python-docs-mcp-server/actions/workflows/ci.yml)
 [![Security Audit](https://github.com/ayhammouda/python-docs-mcp-server/actions/workflows/security.yml/badge.svg)](https://github.com/ayhammouda/python-docs-mcp-server/actions/workflows/security.yml)
 [![CodeQL](https://github.com/ayhammouda/python-docs-mcp-server/actions/workflows/codeql.yml/badge.svg)](https://github.com/ayhammouda/python-docs-mcp-server/actions/workflows/codeql.yml)
@@ -13,12 +15,7 @@
 [![No API Keys](https://img.shields.io/badge/API%20keys-none-success)](#why-use-it)
 [![Official Python Docs](https://img.shields.io/badge/source-official%20python%20docs-informational)](https://docs.python.org/3/)
 
-`python-docs-mcp-server` is a read-only MCP server for the Python standard
-library docs. It builds a local, version-aware index and gives MCP clients the
-relevant section instead of a whole docs page.
-
-Use it with Claude, Cursor, Codex, or any MCP client when you want answers from
-docs.python.org without API keys or a hosted docs API at query time.
+Built for the moment your agent needs `asyncio.TaskGroup` signatures, `pathlib.Path` semantics, or what changed in 3.12 — *not* a web fetch, *not* a hosted API, *not* a vector store hallucinating section anchors. Just an indexed slice of `docs.python.org`, returned by symbol or by query, scoped to the version you actually ship on.
 
 ## Why this exists
 

glama.json

@@ -1,5 +1,6 @@
 {
   "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "description": "For AI coding agents writing Python: the canonical Python stdlib oracle. Exact symbols, exact sections, exact versions — offline, always free, always MIT, token-frugal.",
   "maintainers": [
     "ayhammouda"
   ]

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 [project]
 name = "python-docs-mcp-server"
 version = "0.1.4"
-description = "A read-only, version-aware MCP retrieval server over Python standard library documentation"
+description = "The canonical Python stdlib oracle for AI coding agents — exact symbols, exact sections, exact versions, offline, always free, always MIT, token-frugal."
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.12"

server.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.ayhammouda/python-docs-mcp-server",
-  "description": "Local, read-only MCP retrieval over official Python standard library docs.",
+  "description": "The canonical Python stdlib oracle for AI coding agents. Exact symbols, exact sections, exact versions — offline, always free, always MIT, token-frugal.",
   "title": "Python Docs MCP Server",
   "websiteUrl": "https://github.com/ayhammouda/python-docs-mcp-server",
   "repository": {