docs: distribute from GitHub only (drop PyPI) + SEO + unify roadmap m…

.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

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

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

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
 ```
 

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.

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` |

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?
 

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