diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 2fcf5b7..e6ee2f2 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -5,8 +5,7 @@ on:
     tags: ["v*"]
 
 permissions:
-  contents: write   # create the GitHub release
-  id-token: write   # PyPI trusted publishing (OIDC) — no API token stored
+  contents: write   # create the GitHub release (the sole distribution channel)
 
 jobs:
   build:
@@ -44,15 +43,3 @@ jobs:
         with:
           files: dist/*
           generate_release_notes: true
-
-  pypi:
-    needs: build
-    runs-on: ubuntu-latest
-    environment: pypi
-    steps:
-      - uses: actions/download-artifact@v4
-        with:
-          name: dist
-          path: dist
-      - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 496a6e7..5f4500a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,15 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+### Changed
+- Distribution is now **GitHub-only**: the package is no longer published to PyPI.
+  `requirements.lock` and all install docs install `codebase-index` from the GitHub
+  release tarball pinned to a tag (`@v1.0.2`); `pipx install "git+https://..."` is the
+  recommended one-command path. The bootstrap still honors `CBX_INSTALL_SPEC` to
+  override the install source for local/dev installs.
+- Removed the PyPI trusted-publishing job from the release workflow; tagged GitHub
+  releases (with attached build artifacts) are the sole distribution channel.
+
 ## [1.0.2] - 2026-05-29
 
 ### Added
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 26df174..b8df3dd 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -13,8 +13,8 @@ Thank you for your interest in contributing to `codebase-index`. This project is
 ### Clone and Install
 
 ```bash
-git clone https://github.com/<OWNER>/claude-code-codebase-index-skill.git
-cd claude-code-codebase-index-skill
+git clone https://github.com/denfry/codebase-index.git
+cd codebase-index
 
 # Using uv (recommended)
 uv sync --all-extras
diff --git a/README.md b/README.md
index 06e37f4..47ca602 100644
--- a/README.md
+++ b/README.md
@@ -38,7 +38,7 @@ If you are opening this repository for the first time, follow this order:
 If you only need the shortest path, run:
 
 ```bash
-pip install codebase-index
+pipx install "git+https://github.com/denfry/codebase-index.git@v1.0.2"
 cd your-project
 codebase-index init            # prompts for Claude Code / Codex CLI / OpenCode
 codebase-index index
@@ -50,7 +50,7 @@ codebase-index search "where is authentication implemented?"
 **`1.0.2` is released.** The current release includes repository discovery,
 SQLite FTS5 storage, Tree-sitter symbols and references, hybrid ranking, graph
 impact analysis, token-budgeted retrieval packets, optional local embeddings,
-hooks/watch support, multi-CLI installation, and a tested `pipx` install path.
+hooks/watch support, multi-CLI installation, and a tested GitHub-only `pipx` install path.
 
 The `1.0.2` patch adds multi-CLI `init` targeting and refreshes the README for
 AI coding agent search intent. See [CHANGELOG.md](CHANGELOG.md) and
@@ -71,7 +71,7 @@ For most users, install the Python package and run `init` inside the repository
 you want to index:
 
 ```bash
-pip install codebase-index
+pipx install "git+https://github.com/denfry/codebase-index.git@v1.0.2"
 cd your-project
 codebase-index init            # choose Claude Code, Codex CLI, OpenCode, or all
 codebase-index index
@@ -100,8 +100,9 @@ Or just ask: "install the codebase-index plugin".
 **What happens on first run:** when a session starts, a `SessionStart` hook
 (`scripts/bootstrap.sh` / `.ps1`) creates a private Python virtual environment under
 `~/.claude/plugins/data/codebase-index-*/venv` and installs the pinned
-`codebase-index` package (from `requirements.lock`) into it — using `uv` if present,
-otherwise `python -m venv` + `pip`. It reinstalls only when the lock file changes.
+`codebase-index` package (from `requirements.lock`, fetched directly from the GitHub
+release tarball — not PyPI) into it — using `uv` if present, otherwise
+`python -m venv` + `pip`. It reinstalls only when the lock file changes.
 Nothing is installed globally; uninstalling the plugin removes the data directory.
 
 **Prerequisite:** Python 3.10+ on your PATH. The first install needs network access to
@@ -182,21 +183,24 @@ curl -fsSL https://raw.githubusercontent.com/denfry/codebase-index/main/install.
 irm https://raw.githubusercontent.com/denfry/codebase-index/main/install.ps1 | iex
 ```
 
-### Option 1: Install from PyPI
+> **Note:** `codebase-index` is **not published to PyPI**. It is distributed only
+> from GitHub. All commands below install straight from the repository.
+
+### Option 1: Install with pipx (recommended)
 
 ```bash
+pipx install "git+https://github.com/denfry/codebase-index.git@v1.0.2"
 cd your-project
-pip install codebase-index
-codebase-index init
+codebase-index init --target auto
 codebase-index index
 ```
 
-### Option 2: Install with pipx
+### Option 2: Install with pip
 
 ```bash
-pipx install codebase-index
+pip install "git+https://github.com/denfry/codebase-index.git@v1.0.2"
 cd your-project
-codebase-index init --target auto
+codebase-index init
 codebase-index index
 ```
 
diff --git a/ROADMAP.md b/ROADMAP.md
index e1680bb..f7a3169 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -4,68 +4,69 @@
 
 ## Milestones
 
-### M0 — Repository Packaging ✅
-- Polished README, documentation, badges, issue templates, CI workflows.
-- MIT license, changelog, code of conduct, contributing guide.
-- Claude Code Skill directory structure.
-- **Exit:** Repository is ready for public listing and awesome-list submissions.
-
-### M1 — SQLite + FTS5 Index ✅
-- SQLite database with FTS5 virtual table for full-text search.
-- File discovery with layered ignore rules (`.gitignore`, `.codeindexignore`, built-in denylist).
-- Incremental indexing with file hash tracking.
+Milestone numbering matches [docs/ROADMAP.md](docs/ROADMAP.md) (the detailed
+implementation roadmap) and the `(Mx)` tags in [CHANGELOG.md](CHANGELOG.md).
+
+### M0 — Architecture & scaffold ✅
+- Repo tree, core docs (ARCHITECTURE, RETRIEVAL, SCHEMA, SECURITY, INSTALLATION), SKILL.md draft.
+- `pyproject.toml`, module skeletons, CLI command stubs, MIT license, changelog, contributing guide.
+- **Exit:** `codebase-index --help` lists all commands; repository is ready for public listing.
+
+### M1 — Storage + discovery + ignore rules ✅
+- SQLite storage with `meta.schema_version`; file discovery with layered ignore rules
+  (`.gitignore`, `.codeindexignore`, built-in denylist) and secret/binary/size gates.
+- Incremental indexing with file-hash tracking.
 - **Exit:** `codebase-index index` populates the database; secrets and binaries are excluded.
 
-### M2 — Tree-sitter Symbol Extraction
-- AST-based symbol extraction for Python, JavaScript, TypeScript.
-- Symbol-aligned chunking with gap windows.
-- `symbol` and `refs` commands for intra-file symbol lookup.
-- **Exit:** `codebase-index symbol "AuthService"` returns symbol definitions and references.
-
-### M3 — Hybrid Retrieval
-- Combined search: path match + symbol match + FTS5 + optional vector search.
-- Reciprocal Rank Fusion (RRF) for result merging.
-- Confidence scoring and fallback suggestions.
-- **Exit:** `codebase-index search "query"` returns ranked results from multiple retrievers.
-
-### M4 — Graph Expansion
-- Dependency, import, call, and inheritance edge extraction.
-- Graph-based result expansion (related files, callers, callees).
-- `impact` command for blast radius analysis.
+### M2 — FTS5 lexical indexing ✅
+- Line-window chunks + FTS5 virtual table with sync triggers and a code-aware tokenizer.
+- **Exit:** `codebase-index search "<query>"` returns ranked lexical results with line ranges.
+
+### M3 — Tree-sitter symbol extraction ✅
+- AST symbol extraction for Python, JavaScript, TypeScript; symbol-aligned chunking.
+- `symbol` and `refs` commands for symbol lookup, with a line-based fallback for other languages.
+- **Exit:** `codebase-index symbol "AuthService"` returns definitions and references.
+
+### M4 — Hybrid search + ranking ✅
+- Path + symbol + FTS5 (+ optional vector) retrieval with Reciprocal Rank Fusion (RRF),
+  confidence scoring, fallback suggestions, and token-budgeted retrieval packets.
+- **Exit:** hybrid results outrank single-retriever search; output stays within the token budget.
+
+### M5 — Graph edges + impact ✅
+- Import, call, and inheritance edge extraction; bounded BFS impact walk (up/down/both, depth).
 - **Exit:** `codebase-index impact "src/auth/AuthService.ts"` shows affected files and symbols.
 
-### M5 — Token-Budgeted Retrieval Packets
-- Ranked retrieval packets with file paths, line ranges, snippets, and "next files to read".
-- Token budget enforcement (configurable max output size).
-- Compact Markdown and JSON output formats.
-- **Exit:** Claude reads only the recommended line ranges, not entire files.
-
-### M6 — Optional Local Embeddings
-- `sqlite-vec` integration for vector similarity search.
-- Local embedding models (sentence-transformers) as default.
-- External embedding APIs behind explicit opt-in with warnings.
-- **Exit:** Semantic queries improve recall when embeddings are enabled.
-
-### M7 — Optional Hooks
-- Post-tool-use hook for automatic index updates.
-- `--with-hooks` flag and hook configuration.
-- `doctor` reports enabled hooks and their status.
-- **Exit:** Index stays fresh automatically after file edits.
-
-### M8 — Optional MCP Bridge
-- Model Context Protocol wrapper for external tool integration.
-- MCP server exposing `search`, `symbol`, `refs`, `impact` as tools.
+### M6 — Optional local embeddings ✅
+- `sqlite-vec` vector backend (opt-in), local sentence-transformers as default, external
+  embedding APIs gated behind explicit opt-in with warnings.
+- **Exit:** semantic queries improve recall when enabled; the disabled path imports no optional dep.
+
+### M7 — Claude Code Skill packaging ✅
+- `init` materializes the bundled skill template, resolved `config.json`, and `.gitignore` rules;
+  end-to-end freshness contract so the skill triggers `update`/`index`.
+- **Exit:** the skill returns real `stale`/`files_changed_since_build` signals for codebase questions.
+
+### M7.5 — One-command plugin install ✅
+- Repo doubles as a Claude Code plugin; a `SessionStart` bootstrap provisions an isolated venv
+  from the GitHub-pinned `requirements.lock` (uv-preferred, pip fallback).
+- **Exit:** `/plugin install codebase-index@codebase-index` → ask a question → compact reads,
+  no manual `pip`/`init`/`index`.
+
+### M8 — Hooks + watch mode ✅
+- Incremental `update`; `init --with-hooks` auto-merges the PostToolUse hook idempotently;
+  `watch` mode coalesces edit bursts into one debounced `update`; `doctor` reports freshness.
+- **Exit:** the index stays fresh automatically after file edits.
+
+### M9 — Tests, docs, examples, release ✅
+- Coverage gates, CLI golden-output tests, perf smoke on a medium repo.
+- Finalized docs, CHANGELOG, tagged GitHub release (distribution is GitHub-only — not on PyPI).
+- **Exit:** `pipx install "git+https://github.com/denfry/codebase-index.git@v1.0.2"` works on a clean machine.
+
+### M10 — Optional MCP bridge (planned)
+- Model Context Protocol server exposing `search`, `symbol`, `refs`, `impact` as tools.
 - Compatible with Claude Desktop, Cursor, and other MCP clients.
 - **Exit:** `codebase-index` can be used as an MCP tool by any MCP-compatible client.
 
-### M9 — Public Release
-- Comprehensive test suite with coverage targets.
-- Performance benchmarks on medium-sized repositories.
-- PyPI package publication.
-- GitHub release with tagged version.
-- Awesome-list submissions (Claude Code skills, AI coding tools).
-- **Exit:** `pipx install codebase-index` works on a clean machine.
-
 ---
 
 See [CHANGELOG.md](CHANGELOG.md) for released versions and their changes.
diff --git a/docs/COMPARISON.md b/docs/COMPARISON.md
index 5479920..2e810b0 100644
--- a/docs/COMPARISON.md
+++ b/docs/COMPARISON.md
@@ -6,7 +6,7 @@ How `codebase-index` compares to other code search and context tools.
 
 | Tool | Type | Scope | Search Method | Setup |
 |---|---|---|---|---|
-| codebase-index | Claude Code Skill | Local project | Hybrid (FTS5 + symbols + graph) | `pip install` |
+| codebase-index | Claude Code Skill | Local project | Hybrid (FTS5 + symbols + graph) | `pipx` (GitHub) |
 | Cursor indexing | IDE feature | Local project | Proprietary index | Built into IDE |
 | Continue | IDE extension | Local project | LLM-based + RAG | Extension install |
 | Aider repo-map | CLI tool | Local project | File map + grep | `pip install` |
diff --git a/docs/FAQ.md b/docs/FAQ.md
index 859ddd8..a898726 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -1,6 +1,23 @@
-# FAQ
+# FAQ: codebase-index for AI Coding Agents
 
-Frequently asked questions about `codebase-index`.
+`codebase-index` is a local-first codebase indexing tool that gives Claude Code,
+Codex CLI, and OpenCode Cursor-like code search without sending source to the cloud.
+This page answers the most common questions about installing, running, and trusting it.
+
+## How do I install codebase-index?
+
+`codebase-index` is distributed from **GitHub, not PyPI**. Install it in one command
+with `pipx` (isolated) or `pip`, pinned to a release tag for reproducibility:
+
+```bash
+pipx install "git+https://github.com/denfry/codebase-index.git@v1.0.2"
+```
+
+Then run `codebase-index init` inside your project and `codebase-index index` to build
+the first index. In Claude Code you can instead install the plugin
+(`/plugin install codebase-index@codebase-index`), which provisions an isolated venv on
+first run. See [QUICKSTART.md](QUICKSTART.md) and [INSTALLATION.md](INSTALLATION.md) for
+every install path.
 
 ## Is this a Cursor replacement?
 
@@ -48,7 +65,7 @@ Grep is great for exact string matching but has limitations:
 
 ## Why not MCP?
 
-MCP (Model Context Protocol) is a great standard for tool integration, and an MCP bridge is planned (M8 on the roadmap). However:
+MCP (Model Context Protocol) is a great standard for tool integration, and an MCP bridge is planned (M10 on the roadmap). However:
 
 - MCP adds complexity for a tool that works well as a local CLI
 - Not all AI agents support MCP yet
@@ -63,7 +80,7 @@ Yes. While optimized for Claude Code, the CLI is agent-agnostic:
 - JSON output (`--json`) is parseable by any tool
 - The skill is specific to Claude Code, but the underlying CLI is not
 
-Future plans include an MCP server (M8) for broader agent compatibility.
+Future plans include an MCP server (M10) for broader agent compatibility.
 
 ## How do I reset the index?
 
@@ -111,14 +128,17 @@ Yes. Use any of these methods:
 
 ## Is it production-ready?
 
-The core indexing and search functionality is implemented and tested. However:
+Yes — `codebase-index` is released as **v1.0.2**. Indexing, hybrid search, Tree-sitter
+symbols and references, graph impact analysis, optional local embeddings, post-tool-use
+hooks, and watch mode are all implemented, tested, and shipped:
 
-- Graph expansion (M5) is in progress
-- Optional embeddings (M6) are in progress
-- Hooks (M7) are in progress
-- MCP bridge (M8) is planned
+- Graph expansion / impact analysis — shipped
+- Optional local embeddings (`sqlite-vec`) — shipped (opt-in)
+- Post-tool-use hooks + watch mode — shipped
+- MCP bridge — planned, not yet released
 
-See [ROADMAP.md](../ROADMAP.md) for the full milestone plan.
+See [CHANGELOG.md](../CHANGELOG.md) for released versions and [ROADMAP.md](../ROADMAP.md)
+for the full milestone plan.
 
 ## How do I contribute?
 
diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md
index 66c8905..5bac1d4 100644
--- a/docs/INSTALLATION.md
+++ b/docs/INSTALLATION.md
@@ -2,6 +2,10 @@
 
 This page explains how to install `codebase-index` and make it available in Claude Code, Codex CLI, or OpenCode.
 
+> **Distribution:** `codebase-index` is **not on PyPI**. It is installed directly
+> from GitHub via `git+https://...@<tag>`. Pin to a release tag (e.g. `@v1.0.2`)
+> for reproducible installs; use `@main` to track the latest.
+
 ## Choose Your Path
 
 - New user: use **Option 1**.
@@ -24,7 +28,7 @@ Install the package and scaffold the skill into your project:
 
 ```bash
 cd your-project
-pip install codebase-index
+pip install "git+https://github.com/denfry/codebase-index.git@v1.0.2"
 codebase-index init
 codebase-index index
 ```
@@ -58,13 +62,13 @@ ln -s ~/codebase-index/skill ~/.claude/skills/codebase-index
 
 ```bash
 # Using pip
-pip install codebase-index
+pip install "git+https://github.com/denfry/codebase-index.git@v1.0.2"
 
 # Using pipx (isolated environment)
-pipx install codebase-index
+pipx install "git+https://github.com/denfry/codebase-index.git@v1.0.2"
 
 # Using uv
-uv tool install codebase-index
+uv tool install "git+https://github.com/denfry/codebase-index.git@v1.0.2"
 
 # From source (editable mode)
 git clone https://github.com/denfry/codebase-index.git
@@ -90,7 +94,7 @@ pip install -e ".[embeddings-local,watch,dev]"
 On a machine with only Python + pipx:
 
 ```bash
-pipx install codebase-index
+pipx install "git+https://github.com/denfry/codebase-index.git@v1.0.2"
 cd /path/to/your/repo
 codebase-index init           # writes .claude/skills/codebase-index/ + .gitignore rules
 codebase-index index          # builds .claude/cache/codebase-index/index.sqlite
@@ -170,7 +174,7 @@ Use `codebase-index doctor` to verify which hooks are enabled. For heavy editing
 For heavy editing sessions, `watch` mode keeps the index fresh via a debounced filesystem observer. Requires the `[watch]` extra:
 
 ```bash
-pip install "codebase-index[watch]"
+pip install "codebase-index[watch] @ git+https://github.com/denfry/codebase-index.git@v1.0.2"
 codebase-index watch --debounce 500
 ```
 
@@ -260,7 +264,7 @@ Set `allow_external` to `false` to disable external API calls.
 ## Recommended Flow for First-Time Users
 
 ```bash
-pip install codebase-index
+pipx install "git+https://github.com/denfry/codebase-index.git@v1.0.2"
 cd your-project
 codebase-index init
 codebase-index index
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
index 6a0894c..158fdd3 100644
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@@ -1,6 +1,8 @@
 # Quick Start: Install and Run codebase-index in 5 Minutes
 
-Use this guide if you are new to `codebase-index` and want the fastest path to your first useful search result.
+`codebase-index` is a local-first code search tool you install from GitHub in one
+command, then query from Claude Code, Codex CLI, or OpenCode. This guide takes you
+from install to your first ranked search result in about five minutes.
 
 ## Before You Start
 
@@ -10,8 +12,16 @@ Use this guide if you are new to `codebase-index` and want the fastest path to y
 
 ## Step 1: Install
 
+`codebase-index` is distributed from GitHub (not PyPI). Install it with `pipx`:
+
+```bash
+pipx install "git+https://github.com/denfry/codebase-index.git@v1.0.2"
+```
+
+Or with plain `pip`:
+
 ```bash
-pip install codebase-index
+pip install "git+https://github.com/denfry/codebase-index.git@v1.0.2"
 ```
 
 Or from source:
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index b7a42da..9d2b010 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -1,6 +1,8 @@
 # Roadmap & First Implementation Tasks
 
 Milestones are vertical-ish slices: each ends with something runnable and testable.
+This numbering is canonical — the product-level [ROADMAP.md](../ROADMAP.md) and the
+`(Mx)` tags in [CHANGELOG.md](../CHANGELOG.md) follow it.
 
 ## M0 — Architecture & scaffold ✅ (this repo)
 - Repo tree, docs (ARCHITECTURE/RETRIEVAL/SCHEMA/SECURITY/INSTALLATION), SKILL.md draft.
@@ -30,7 +32,7 @@ Milestones are vertical-ish slices: each ends with something runnable and testab
 - Shipped languages: Python, JavaScript, TypeScript. Go/Java/Rust/C/C++/Ruby/PHP follow the recipe
   in `docs/LANGUAGES.md`. `refs` is intra-file (call sites + defs); cross-file resolution is M5.
 
-## M4 — Hybrid search + ranking
+## M4 — Hybrid search + ranking ✅
 - `retrieval/intent.py`, path + symbol searchers, `fusion.py` (RRF), `rerank.py`, `budget.py`.
 - `confidence` + `fallback_suggestions`; `search --mode hybrid` (default); `explain`.
 - **Exit:** hybrid results outrank single-retriever on the fixture queries; token budget enforced.
@@ -49,29 +51,37 @@ Milestones are vertical-ish slices: each ends with something runnable and testab
 ## M7 — Claude Code Skill packaging ✅
 - Shipped: `init` materializes the wheel-bundled skill template (SKILL.md + cbx/cbx.ps1) to `.claude/skills/codebase-index/`, writes resolved `config.json`, and idempotently gitignores the cache (`--force` to overwrite). The freshness contract is honored end-to-end — `search` returns real `stale`/`files_changed_since_build` (git clean-tree fast-path + mtime diff), so the skill triggers `update`/`index` per SKILL.md. `--with-hooks` writes a reviewable hooks example; auto-merging hooks + `watch` are M8.
 
-## M7.5 — One-command plugin install
+## M7.5 — One-command plugin install ✅
 - Repo doubles as a Claude Code plugin (`.claude-plugin/plugin.json` + `marketplace.json`).
 - `SessionStart` hook (`scripts/bootstrap.sh`/`.ps1`) provisions a venv in `${CLAUDE_PLUGIN_DATA}`
   with the pinned CLI (uv-preferred, pip fallback), reinstalling only when `requirements.lock` changes.
 - `bin/cbx` + `bin/codebase-index` wrappers resolve the venv via a `.venv-path` pointer and keep the
   subcommand whitelist.
 - **Exit:** `/plugin install codebase-index@<marketplace>` → ask a codebase question → compact reads,
-  no manual `pip`/`init`/`index`. Depends on the M9 PyPI release for the non-`CBX_INSTALL_SPEC` path.
+  no manual `pip`/`init`/`index`. The bootstrap installs the package from the GitHub release tarball
+  pinned in `requirements.lock` (not PyPI); `CBX_INSTALL_SPEC` overrides the source for local/dev installs.
 
 ## M8 — Hooks + watch mode ✅
 - Shipped: incremental `update` (mtime fast-path + sha verify + prune; `--since <ref>`, `--all`) is the engine the freshness contract calls; `init --with-hooks` auto-merges the `PostToolUse` update hook into `.claude/settings.json` idempotently; `watch` mode (optional `[watch]` extra) coalesces edit bursts into one debounced `update` and degrades to a clear error when watchdog is absent; `doctor` reports enabled hooks, cache-gitignore coverage, and freshness, exiting non-zero under `--strict` on high-severity findings. The full SECURITY.md §6 doctor checklist (secret-leak scan, perms, allowed-tools diff) is M9.
 
 ## M9 — Tests, docs, examples, release ✅
 - Coverage across modules; CLI golden-output tests; perf check on a medium repo.
-- `examples/queries.md`, finalized docs, CHANGELOG, PyPI release, tagged GitHub release.
-- **Exit:** `pipx install codebase-index` + `init` + ask a question works on a clean machine.
+- `examples/queries.md`, finalized docs, CHANGELOG, tagged GitHub release (GitHub-only distribution — no PyPI).
+- **Exit:** `pipx install "git+https://github.com/denfry/codebase-index.git@v1.0.2"` + `init` + ask a question works on a clean machine.
 
 *Shipped: golden-file tests lock CLI `--json` output; a `--runslow` perf smoke test guards
 index/search latency on a synthetic medium repo; coverage is gated (`--cov-fail-under`) in a
 CI matrix (Ubuntu/macOS/Windows × py3.10–3.13). `CHANGELOG.md` tracks releases; a tag-triggered
-release pipeline builds, runs `twine check` + a clean-venv install smoke, publishes a GitHub
-release, and pushes to PyPI via trusted publishing. `pipx install codebase-index` → `init` →
-`index` → ask a question is verified end-to-end by `scripts/release_smoke.py`.*
+release pipeline builds, runs `twine check` + a clean-venv install smoke, and publishes a GitHub
+release with the built artifacts (GitHub-only distribution — no PyPI publish). `pipx install
+"git+https://github.com/denfry/codebase-index.git@v1.0.2"` → `init` → `index` → ask a question is
+verified end-to-end by `scripts/release_smoke.py`.*
+
+## M10 — Optional MCP bridge (planned)
+- Model Context Protocol server exposing `search`, `symbol`, `refs`, `impact` as tools for
+  MCP-compatible clients (Claude Desktop, Cursor, etc.). An optional addition, not a replacement
+  for the Skill/CLI interface.
+- **Exit:** `codebase-index` can be used as an MCP tool by any MCP-compatible client.
 
 ---
 
diff --git a/docs/SEO.md b/docs/SEO.md
index df65632..97364f1 100644
--- a/docs/SEO.md
+++ b/docs/SEO.md
@@ -10,7 +10,8 @@ Repository SEO strategy for `codebase-index`.
 codebase-index
 ```
 
-Rationale: Matches the PyPI package and primary product keyword.
+Rationale: Matches the GitHub repository and primary product keyword. The package
+is distributed from GitHub (not PyPI), so the repo name is the canonical identifier.
 
 ### GitHub About Description
 
@@ -133,7 +134,7 @@ Submit to these lists for backlinks and discoverability:
 ### Directories
 - Claude Skill Directory (if exists)
 - MCP Server Directory (for future MCP bridge)
-- PyPI (package listing)
+- GitHub Releases (tagged distribution — the package is GitHub-only, not on PyPI)
 
 ### Communities
 - Claude Code Discord
@@ -158,7 +159,7 @@ Features:
 - Secret redaction
 - Respects .gitignore
 
-Install: pip install codebase-index
+Install: pipx install "git+https://github.com/denfry/codebase-index.git@v1.0.2"
 GitHub: https://github.com/denfry/codebase-index
 ```
 
@@ -173,5 +174,5 @@ codebase-index builds a local hybrid index so Claude finds the right files witho
 - No network by default
 - Token-efficient output
 
-pip install codebase-index
+pipx install "git+https://github.com/denfry/codebase-index.git@v1.0.2"
 ```
diff --git a/requirements.lock b/requirements.lock
index 7295f20..7cf0dfd 100644
--- a/requirements.lock
+++ b/requirements.lock
@@ -1,3 +1,3 @@
-codebase-index==1.0.2
+codebase-index @ https://github.com/denfry/codebase-index/archive/refs/tags/v1.0.2.tar.gz
 tree-sitter==0.25.2
 tree-sitter-language-pack==1.8.1
diff --git a/tests/test_plugin_manifest.py b/tests/test_plugin_manifest.py
index b14ebd4..cd56095 100644
--- a/tests/test_plugin_manifest.py
+++ b/tests/test_plugin_manifest.py
@@ -33,10 +33,17 @@ def test_plugin_version_matches_pyproject():
     assert _load(".claude-plugin/plugin.json")["version"] == ver
 
 
-def test_requirements_lock_pins_package_version():
+def test_requirements_lock_pins_package_from_github_tag():
+    # codebase-index is distributed from GitHub (not PyPI): the lock pins the
+    # package to the matching release tag tarball, not a PyPI version specifier.
     version = _load(".claude-plugin/plugin.json")["version"]
-    lock_lines = (ROOT / "requirements.lock").read_text(encoding="utf-8").splitlines()
-    assert f"codebase-index=={version}" in lock_lines
+    lock_text = (ROOT / "requirements.lock").read_text(encoding="utf-8")
+    expected = (
+        "codebase-index @ "
+        f"https://github.com/denfry/codebase-index/archive/refs/tags/v{version}.tar.gz"
+    )
+    assert expected in lock_text.splitlines()
+    assert "codebase-index==" not in lock_text  # must not fall back to PyPI
 
 
 def test_requirements_lock_pins_tree_sitter_grammars():