ayhammouda · ayhammouda · May 14, 2026 · May 14, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to `python-docs-mcp-server` are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.5] — 2026-05-14
+
+### Added
+
+- **PyPI debut.** Install via `uvx python-docs-mcp-server` (no `--from` flag needed). The previous `uvx --from git+https://github.com/ayhammouda/python-docs-mcp-server.git` path keeps working via the existing GitHub source, but the published wheel is now the canonical install route.
+- `CHANGELOG.md` (this file).
+- Locked positioning anchor: *"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."* See `.planning/POSITIONING.md` for the verbatim copy and per-surface adaptation rules.
+- Forward-facing `.planning/phases/` directory. Three post-v0.1.5 backlog items have on-disk specs:
+  - `09-compare-versions` — new MCP tool: `compare_versions(symbol, v1, v2)` structured diff.
+  - `10-whatsnew` — new MCP tool: `whatsnew_for_version(version)` section-sliced "What's New" page.
+  - `11-detect-venv` — venv-aware `detect_python_version` v2 (reads `VIRTUAL_ENV`, `.venv/`, `pyvenv.cfg`).
+
+### Changed
+
+- README hero rewritten around the canonical-source positioning. The positioning sentence now sits between the package title and the badge row, with a wedge-forward "Built for the moment your agent needs…" descriptive paragraph below the badges.
+- `glama.json` `description`, `server.json` `description`, and `pyproject.toml` `description` aligned with the locked positioning. Each surface keeps the three required anchor phrases (canonical Python stdlib oracle / always free, always MIT / token-frugal) while adapting the wording for its display length.
+- `AGENTS.md` "Context Hygiene" section now distinguishes `.planning/ROADMAP.md` and `.planning/phases/0X-…/0X-CONTEXT.md` (live, forward-looking specs) from older `.planning/` content (archival history).
+- README install instructions, MCP-client config snippets, and validation commands now lead with the PyPI install (`uvx python-docs-mcp-server`). The pre-PyPI `--from git+…` blocks have been removed.
+
+### Removed
+
+- All `<!-- PRE-PYPI -->` fenced regions from `README.md` (11 blocks, 18 GitHub-source install URLs). They were scaffolding for the pre-v0.1.5 window where the only install path was a GitHub source URL.
+
+### Notes
+
+- The PyPI package name and the GitHub repository name both remain `python-docs-mcp-server`. A rename to `python-stdlib-mcp` was planned in the v0.1.5 scope (CR §9.2) but was dropped on 2026-05-14; the historical note is preserved in `.planning/ROADMAP.md`.
+- Trusted Publishing on PyPI is wired with Sigstore attestations on every release artifact. The release workflow lives at `.github/workflows/release.yml` and runs on annotated tags matching `v*`.
+
+## [0.1.4] — 2026-05-13
+
+Pre-PyPI release. Installable only via `uvx --from git+https://github.com/ayhammouda/python-docs-mcp-server.git`. Last release before the PyPI publish.
diff --git a/README.md b/README.md
@@ -72,30 +72,8 @@ then `get_docs` for the matching section. Instead of generic web results or an
 entire docs page, it gets official stdlib text for the requested Python version,
 trimmed to the section that matters.
 
-<!-- PRE-PYPI: replace this temporary GitHub-source smoke test after the first PyPI publish -->
-Local source smoke test until the PyPI package is published:
-
-```bash
-uvx --from git+https://github.com/ayhammouda/python-docs-mcp-server.git python-docs-mcp-server --version
-```
-<!-- /PRE-PYPI -->
-
 ## Install
 
-<!-- PRE-PYPI: remove this entire "Before PyPI publishing" block (heading + prose + code) after the first PyPI publish -->
-### Before PyPI publishing (install from GitHub source)
-
-Until the first PyPI release is published, run from GitHub:
-
-```bash
-uvx --from git+https://github.com/ayhammouda/python-docs-mcp-server.git python-docs-mcp-server --version
-```
-<!-- /PRE-PYPI -->
-
-<!-- PRE-PYPI: after the first PyPI publish, drop this "After PyPI publishing" heading so the section reads simply as "## Install" -->
-### After PyPI publishing
-<!-- /PRE-PYPI -->
-
 Run directly with `uvx`:
 
 ```bash
@@ -117,18 +95,6 @@ shell or use `python -m uv ...` as a fallback for local contributor commands.
 
 Build the local documentation index:
 
-<!-- PRE-PYPI: remove the GitHub-source build-index command and the "After PyPI publishing" lead-in after the first PyPI publish; the post-PyPI code fence below survives -->
-```bash
-uvx --from git+https://github.com/ayhammouda/python-docs-mcp-server.git python-docs-mcp-server build-index --versions 3.10,3.11,3.12,3.13,3.14
-```
-
-After PyPI publishing, `uvx python-docs-mcp-server build-index ...` is enough.
-<!-- /PRE-PYPI -->
-
-<!-- PRE-PYPI: after the first PyPI publish, drop this "After PyPI publishing" heading so the section reads simply as "## First run" -->
-### After PyPI publishing
-<!-- /PRE-PYPI -->
-
 ```bash
 uvx python-docs-mcp-server build-index --versions 3.10,3.11,3.12,3.13,3.14
 ```
@@ -155,25 +121,6 @@ Add this to your Claude Desktop configuration file:
 
 **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`
 
-<!-- PRE-PYPI: remove the GitHub-source config and the "After PyPI publishing, use:" lead-in after the first PyPI publish; the post-PyPI config fence below survives -->
-```json
-{
-  "mcpServers": {
-    "python-docs": {
-      "command": "uvx",
-      "args": [
-        "--from",
-        "git+https://github.com/ayhammouda/python-docs-mcp-server.git",
-        "python-docs-mcp-server"
-      ]
-    }
-  }
-}
-```
-
-After PyPI publishing, use:
-<!-- /PRE-PYPI -->
-
 ```json
 {
   "mcpServers": {
@@ -192,25 +139,6 @@ Restart Claude Desktop after editing the config file.
 Add this to your Cursor MCP settings (`.cursor/mcp.json` in your project or
 global settings):
 
-<!-- PRE-PYPI: remove the GitHub-source config and the "After PyPI publishing, use:" lead-in after the first PyPI publish; the post-PyPI config fence below survives -->
-```json
-{
-  "mcpServers": {
-    "python-docs": {
-      "command": "uvx",
-      "args": [
-        "--from",
-        "git+https://github.com/ayhammouda/python-docs-mcp-server.git",
-        "python-docs-mcp-server"
-      ]
-    }
-  }
-}
-```
-
-After PyPI publishing, use:
-<!-- /PRE-PYPI -->
-
 ```json
 {
   "mcpServers": {
@@ -226,16 +154,6 @@ After PyPI publishing, use:
 
 Add this to `.codex/config.toml`:
 
-<!-- PRE-PYPI: remove the GitHub-source config and the "After PyPI publishing, use:" lead-in after the first PyPI publish; the post-PyPI config fence below survives -->
-```toml
-[mcp_servers.python-docs]
-command = "uvx"
-args = ["--from", "git+https://github.com/ayhammouda/python-docs-mcp-server.git", "python-docs-mcp-server"]
-```
-
-After PyPI publishing, use:
-<!-- /PRE-PYPI -->
-
 ```toml
 [mcp_servers.python-docs]
 command = "uvx"
@@ -319,16 +237,6 @@ search, or silently fall back to unofficial community mirrors.
 
 ## Diagnostics
 
-<!-- PRE-PYPI: remove the GitHub-source doctor invocation and "After PyPI publishing:" lead-in after the first PyPI publish; the post-PyPI code fence below survives -->
-Before PyPI publishing, run `doctor` from the GitHub source package:
-
-```bash
-uvx --from git+https://github.com/ayhammouda/python-docs-mcp-server.git python-docs-mcp-server doctor
-```
-
-After PyPI publishing:
-<!-- /PRE-PYPI -->
-
 Check the local environment:
 
 ```bash
@@ -338,17 +246,6 @@ uvx python-docs-mcp-server doctor
 This checks the runtime Python version, SQLite FTS5, cache/index paths, disk
 space, and the `venv`/`ensurepip` support needed by `build-index`.
 
-<!-- PRE-PYPI: remove the GitHub-source validate-corpus invocation and "After PyPI publishing:" lead-in after the first PyPI publish; the post-PyPI code fence below survives -->
-Before PyPI publishing, validate an existing index from the GitHub source
-package:
-
-```bash
-uvx --from git+https://github.com/ayhammouda/python-docs-mcp-server.git python-docs-mcp-server validate-corpus
-```
-
-After PyPI publishing:
-<!-- /PRE-PYPI -->
-
 Validate an existing index:
 
 ```bash
@@ -434,25 +331,6 @@ uv cache clean python-docs-mcp-server
 The MSIX-packaged version of Claude Desktop on Windows may have restricted PATH
 access. If `uvx` is not found, specify the full path in your config:
 
-<!-- PRE-PYPI: remove the GitHub-source config and the "After PyPI publishing, use:" lead-in after the first PyPI publish; the post-PyPI config fence below survives -->
-```json
-{
-  "mcpServers": {
-    "python-docs": {
-      "command": "C:\\Users\\YOU\\.local\\bin\\uvx.exe",
-      "args": [
-        "--from",
-        "git+https://github.com/ayhammouda/python-docs-mcp-server.git",
-        "python-docs-mcp-server"
-      ]
-    }
-  }
-}
-```
-
-After PyPI publishing, use:
-<!-- /PRE-PYPI -->
-
 ```json
 {
   "mcpServers": {

diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-docs-mcp-server"
-version = "0.1.4"
+version = "0.1.5"
 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"

diff --git a/server.json b/server.json
@@ -8,13 +8,13 @@
     "url": "https://github.com/ayhammouda/python-docs-mcp-server",
     "source": "github"
   },
-  "version": "0.1.4",
+  "version": "0.1.5",
   "packages": [
     {
       "registryType": "pypi",
       "registryBaseUrl": "https://pypi.org",
       "identifier": "python-docs-mcp-server",
-      "version": "0.1.4",
+      "version": "0.1.5",
       "runtimeHint": "uvx",
       "transport": {
         "type": "stdio"

diff --git a/uv.lock b/uv.lock