indexkit 0.6.1__tar.gz

indexkit-0.6.1/.claude-plugin/plugin.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "indexkit",
+  "displayName": "Local RAG",
+  "version": "0.6.1",
+  "description": "Local-first semantic and opt-in hybrid search: a bin/indexkit CLI that embeds through a configurable Ollama endpoint (default localhost), indexes with turbovec, and can fuse FTS5/BM25 candidates. Notes-first, corpus-agnostic via pluggable loaders.",
+  "author": {
+    "name": "Mark Beacom"
+  },
+  "homepage": "https://github.com/mbeacom/context-kit",
+  "repository": "https://github.com/mbeacom/context-kit",
+  "license": "MIT",
+  "keywords": [
+    "rag",
+    "vector-search",
+    "turbovec",
+    "ollama",
+    "embeddings",
+    "semantic",
+    "bm25",
+    "hybrid"
+  ],
+  "userConfig": {
+    "embed_model": {
+      "type": "string",
+      "title": "Embedding model",
+      "description": "ollama model used to embed chunks and queries",
+      "default": "nomic-embed-text"
+    },
+    "ollama_host": {
+      "type": "string",
+      "title": "Ollama host",
+      "description": "Base URL of the ollama server",
+      "default": "http://localhost:11434"
+    }
+  }
+}

indexkit-0.6.1/.gitignore

@@ -0,0 +1,233 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer,
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Claude Code plugin cache / local validation
+.claude/
+*.tq
+*.tvim
+
+# rtk (Rust Token Killer) local config — machine-specific, not published
+.rtk/
+
+# Internal dev process artifacts (brainstorm specs / implementation plans) — kept local, not published
+docs/superpowers/
+
+# MemPalace per-project files (issue #185)
+mempalace.yaml
+entities.json

indexkit-0.6.1/CHANGELOG.md

@@ -0,0 +1,157 @@
+# Changelog
+
+## 0.6.1 — 2026-08-08
+
+- Correct host guidance and stale command names in the skill and README.
+  GitHub Copilot CLI loads `hooks/hooks.json`, so it auto-bootstraps like
+  Claude Code; only APM needs a manual step. The CLI is `indexkit`, not `rag`.
+- Mark the PyPI install as forthcoming and document the working source install,
+  since the package name is not claimed yet.
+- Restore pre-rename CHANGELOG entries to their original wording. Rewriting
+  them made an old release's notes describe variables that release never had.
+
+## 0.6.0 — 2026-08-08
+
+- **Installable and usable without a plugin host** (ADR-0006). `pip install
+  indexkit` now works standalone: the default index location is
+  `${XDG_DATA_HOME:-~/.local/share}/indexkit` instead of
+  `~/.claude/plugins/data/indexkit`, so a user with no Claude install no longer
+  gets a `.claude` directory created for an unrelated tool.
+- An existing `~/.claude/plugins/data/indexkit` still wins while the new default
+  has not been created, so upgrading a plugin install does not orphan indexes.
+- `bin/indexkit` degrades instead of refusing: bootstrapped venv, then an
+  `indexkit` on `PATH`, then any importable `indexkit` module. A guard prevents
+  the launcher re-executing itself when the plugin `bin/` is on `PATH`.
+- Add publish metadata (readme, license, authors, classifiers, project URLs);
+  `twine check` passes on both sdist and wheel.
+- Rewrite the README to lead with standalone install, since it is now the
+  package's PyPI landing page.
+
+## 0.5.0 — 2026-08-08
+
+- **Renamed from `local-rag` to `indexkit`** (ADR-0007). The name encoded a
+  deployment property that a supported setting falsifies: pointing
+  `CONTEXT_KIT_OLLAMA_HOST` at a remote ollama made "local" untrue. "RAG" also
+  understated an engine that does lexical BM25 alongside semantic search.
+- Unify all four naming surfaces on `indexkit`: the package, the console script,
+  the CLI `prog`, and the launcher (`bin/rag` is now `bin/indexkit`).
+- Honor `CONTEXT_KIT_LOCAL_RAG_HOME` as a fallback for
+  `CONTEXT_KIT_INDEXKIT_HOME`, so existing environments keep resolving.
+- Add package keywords (`rag`, `local-rag`, `offline`, `hybrid-retrieval`) so the
+  pre-rename search terms still find the project.
+
+## 0.4.1 — 2026-08-05
+
+- Correct the host guidance in the skill and README. GitHub Copilot CLI loads a
+  plugin's `hooks/hooks.json` (verified on 1.0.79), so it auto-bootstraps the
+  `rag` venv exactly as Claude Code does; only APM needs a manual bootstrap.
+  The docs previously grouped Copilot with APM and sent Copilot users through
+  an unnecessary manual step.
+
+## 0.4.0 — 2026-08-04
+
+- Separate venv resolution from index-data location. `CONTEXT_KIT_LOCAL_RAG_HOME`
+  now locates the bootstrapped venv (and its `pyproject.sha` stamp), while
+  `CONTEXT_KIT_DATA` continues to locate index data. Previously both were derived
+  from `CONTEXT_KIT_DATA`, so a caller redirecting index data to an isolated
+  store also relocated the venv and `bin/rag` failed with "venv missing". The new
+  variable is optional and falls back to the existing `CONTEXT_KIT_DATA` chain,
+  so default single-user behavior is unchanged.
+- Add `rag --version`, so an integrating adapter can report and pin a provider
+  version the same way it does for other retrieval backends.
+- Add `scripts/bootstrap.sh --check`, a side-effect-free readiness probe that
+  prints `KEY=VALUE` status lines and exits 0 when ready or 3 when a bootstrap
+  is required. This gives hosts that do not run the Claude `SessionStart` hook
+  — GitHub Copilot and APM — a deterministic way to detect an unusable runtime.
+- `--check` reports a **stale** venv (one built from different `pyproject.toml`
+  metadata) as loudly as a missing one. Previously a stale venv ran outdated
+  code silently, because the launcher never consulted the stamp.
+- `--check` decides venv state before considering `uv`, and reports
+  `venv_status` and `uv` as separate fields. `uv` is only needed to *build* the
+  venv, so an already-usable runtime now reports `ready` on a machine without
+  `uv` instead of sending the user after an irrelevant install; `uv-missing` is
+  returned only when the venv genuinely needs rebuilding.
+
+## 0.3.3 — 2026-08-03
+
+- Shorten the discovery description(s) to free aggregate budget for the new
+  `deep-review` components. Triggers and scope are unchanged; the catalog
+  budget stays at 4096 characters rather than being raised.
+
+## 0.3.2 — 2026-07-27
+
+- Shorten the discovery description(s) to free aggregate budget for the new
+  `corpus-review` components. Triggers and scope are unchanged; the catalog
+  budget is fixed, so every addition competes for the same remainder.
+
+## 0.3.1 — 2026-07-19
+
+- Clarify the configurable Ollama trust boundary: storage and embedding are
+  local by default, while a remote `CONTEXT_KIT_OLLAMA_HOST` receives submitted
+  corpus chunks and queries.
+
+## 0.3.0 — 2026-07-19
+
+- Add automation-safe `rag remove --name NAME --yes` for permanent deletion of
+  obsolete or corrupt named indexes. Removal atomically leaves the active
+  namespace, unlinks only flat per-index artifacts without recursive deletion,
+  preserves sibling indexes, and reports partial cleanup locations.
+- Apply one containment-safe, backward-compatible index-name contract across
+  `index`, `query`, `status`, and `remove`; reject traversal while preserving
+  legacy names with spaces or more than 80 characters.
+- Serialize operations with a per-index process lock, reject owned-artifact
+  symlinks before opening or writing, close partially initialized resources,
+  and keep removal quarantine entries out of `rag list`.
+
+## 0.2.0 — 2026-07-19
+
+- Add opt-in `rag query --hybrid`, which fuses turbovec semantic and SQLite
+  FTS5/BM25 lexical candidates with deterministic, equal-weight reciprocal-rank
+  fusion (RRF constant 60 and `3 × k` candidate depth).
+- Keep FTS5 synchronized for incremental indexing, changed files, and deletions;
+  automatically migrate/backfill existing indexes. Status now reports FTS5
+  capability, and hybrid requests clearly fail when it is unavailable.
+- Add source offsets and semantic, lexical, and fused retrieval metadata to JSON
+  results while preserving semantic-only as the default.
+
+## 0.1.6 — 2026-07-18
+
+- Lead host guidance with GitHub Copilot, APM, then Claude Code in the plugin
+  README (the manual `rag` bootstrap now comes first; the Claude auto-bootstrap
+  note follows).
+
+## 0.1.5 — 2026-07-18
+
+- Rebrand: the marketplace was renamed `productivity-skills` → `context-kit`.
+  Environment variables are now `CONTEXT_KIT_*` (`CONTEXT_KIT_DATA`,
+  `CONTEXT_KIT_EMBED_MODEL`, `CONTEXT_KIT_OLLAMA_HOST`); the former
+  `PRODUCTIVITY_SKILLS_*` names still resolve as a deprecated alias, so resolution
+  order is `CONTEXT_KIT_*` → `PRODUCTIVITY_SKILLS_*` → Claude fallback. Updated URLs
+  and install commands (`… install local-rag@context-kit`).
+
+## 0.1.4 — 2026-07-13
+
+- Add an `apm.yml` manifest so Agent Package Manager (`microsoft/apm`) users can
+  install this plugin (`apm install local-rag@context-kit`) alongside the
+  Claude Code and GitHub Copilot flows. As with Copilot, APM does not run the
+  Claude `SessionStart` bootstrap hook — bootstrap `bin/rag` manually and use the
+  `PRODUCTIVITY_SKILLS_*` env vars (see docs/APM.md).
+
+## 0.1.3 — 2026-05-29
+
+- Add GitHub Copilot/manual setup docs and portable `PRODUCTIVITY_SKILLS_*`
+  environment variables while preserving `CLAUDE_PLUGIN_*` fallbacks.
+
+## 0.1.2 — 2026-05-28
+
+- Docs: clarify that `rag` is not rtk-wrapped (prefixing is a no-op); prefer
+  `rtk` on the surrounding `rg` step, where `rtk rg -l` keeps paths raw. Permit
+  `Bash(rg:*)`/`Bash(rtk rg:*)` so the hybrid `rg -l | rag query` example runs.
+
+## 0.1.1 — 2026-05-24
+
+Docs: correct the `rag status` skill example (reports counts/model/dim, not staleness).
+
+## 0.1.0 — 2026-05-24
+
+Initial engine: bin/rag CLI, uv venv bootstrap, plugin manifest (loader/store/embed/index/engine/cli land in subsequent commits).

indexkit-0.6.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Beacom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

indexkit-0.6.1/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: indexkit
+Version: 0.6.1
+Summary: Offline hybrid retrieval: build a local semantic + BM25 index over your files and query it. Local RAG with ollama, turbovec, and SQLite FTS5.
+Project-URL: Homepage, https://github.com/mbeacom/context-kit
+Project-URL: Repository, https://github.com/mbeacom/context-kit
+Project-URL: Changelog, https://github.com/mbeacom/context-kit/blob/main/plugins/indexkit/CHANGELOG.md
+Project-URL: Issues, https://github.com/mbeacom/context-kit/issues
+Author: Mark Beacom
+License: MIT License
+        
+        Copyright (c) 2026 Mark Beacom
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: bm25,embeddings,hybrid-retrieval,local-rag,offline,ollama,rag,semantic-search,vector-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Text Processing :: Indexing
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: turbovec>=0.5
+Description-Content-Type: text/markdown
+
+# indexkit
+
+Offline hybrid retrieval: build a local semantic + lexical index over your files
+and query it. Chunks and embeds a corpus through [`ollama`](https://ollama.com),
+indexes it with [`turbovec`](https://github.com/RyanCodrai/turbovec) (a quantized
+vector index), and fuses that with SQLite FTS5/BM25 for opt-in hybrid search.
+
+No API key and no network egress by default — the embedding endpoint is
+localhost. A configured remote `CONTEXT_KIT_OLLAMA_HOST` receives corpus chunks
+and queries, so that is the one setting that sends data off the machine.
+
+Notes-first but corpus-agnostic: loaders are pluggable, so the same engine can
+index Markdown notes, code, or any text corpus.
+
+> Formerly `local-rag`. The old name claimed a deployment property that a
+> supported setting falsifies, and understated an engine that also does lexical
+> retrieval. Pre-rename environment variables are still honored.
+
+## Install
+
+> **Not on PyPI yet.** The package is publish-ready but the name has not been
+> claimed. Until the release workflow runs, install from source; the `pip
+> install` line below is what will work once it ships.
+
+```bash
+# From a clone of https://github.com/mbeacom/context-kit
+pip install ./plugins/indexkit    # or: uv tool install ./plugins/indexkit
+ollama pull nomic-embed-text      # once
+```
+
+Once published:
+
+```bash
+pip install indexkit          # or: uv tool install indexkit
+```
+
+Either way that is the whole setup — no plugin host, no bootstrap step. Indexes
+default to `${XDG_DATA_HOME:-~/.local/share}/indexkit`.
+
+```bash
+indexkit index ~/notes --name notes
+indexkit query "how did we handle retry backoff" --name notes --k 8
+```
+
+### As a context-kit plugin
+
+Claude Code and GitHub Copilot CLI auto-bootstrap the bundled `bin/indexkit`
+launcher from the plugin's `SessionStart` hook, into `${CLAUDE_PLUGIN_DATA}/venv`
+— for Copilot, `~/.copilot/plugin-data/<marketplace>/indexkit/venv`. In that
+mode the host controls where indexes live.
+
+The launcher prefers that bootstrapped venv, then falls back to an `indexkit`
+already on your `PATH`, then to any importable `indexkit` module. So a
+pip-installed copy satisfies the plugin too, and a missing venv is not fatal.
+
+## Requirements
+
+- [`ollama`](https://ollama.com) running with an embedding model pulled:
+
+  ```bash
+  ollama pull nomic-embed-text
+  ```
+
+- [`uv`](https://docs.astral.sh/uv/) — **only** for the plugin bootstrap path.
+  A `pip install` needs nothing beyond Python 3.10+.
+
+For APM or manual plugin usage — or on any host where the venv is missing or
+stale — bootstrap it yourself into a neutral data location:
+
+```bash
+export CONTEXT_KIT_DATA="$HOME/.local/share/context-kit"
+bash scripts/bootstrap.sh
+export PATH="$PWD/bin:$PATH"
+```
+
+To check readiness without installing anything:
+
+```bash
+bash scripts/bootstrap.sh --check   # exit 0 ready, 3 needs bootstrap
+```
+
+It prints `KEY=VALUE` lines: `status` (`ready`, `missing`, `stale`,
+`uv-missing`), the raw `venv_status` and `uv` availability as separate fields,
+the resolved `home`/`venv` paths, and the exact `bootstrap_command`. A `stale`
+venv was built from different `pyproject.toml` metadata and would run outdated
+code, so it is reported as clearly as a missing one. Because `uv` is only
+needed to *build* the venv, an already-usable venv reports `ready` even when
+`uv` is absent. Dependent tooling uses this to detect an unusable runtime on
+hosts that do not deploy plugin hooks, such as APM. (Claude Code and GitHub
+Copilot CLI both run this plugin's `SessionStart` bootstrap.)
+
+## Usage
+
+Index a corpus, then query it:
+
+```bash
+indexkit index <path> --name X
+indexkit query "your question" --name X
+indexkit query "exact terms and intent" --name X --hybrid
+indexkit status --name X
+indexkit list
+indexkit remove --name X --yes
+```
+
+Each named index is persisted under `<data-dir>/indexes/<name>/`, so queries are
+fast and survive across sessions. The data directory resolves in this order:
+
+1. `CONTEXT_KIT_DATA` (or the `PRODUCTIVITY_SKILLS_DATA` alias)
+2. `CLAUDE_PLUGIN_DATA`, set by a plugin host
+3. `${XDG_DATA_HOME:-~/.local/share}/indexkit` — the standalone default
+
+An existing `~/.claude/plugins/data/indexkit` directory still wins over the
+standalone default while that default has not been created, so upgrading a
+plugin install does not orphan indexes you already built.
+
+### Index lifecycle
+
+Index names remain backward-compatible with earlier releases: any non-empty
+single path component except `.` or `..` is accepted, including names with
+spaces or more than 80 characters. Path separators (`/` and `\`) and NUL are
+rejected. These containment rules apply consistently to `index`, `query`,
+`status`, and `remove`.
+
+`indexkit remove --name X --yes` permanently removes one named index. The command is
+non-interactive and refuses to run without `--yes`; missing indexes fail clearly.
+Indexing, querying, status inspection, and removal share a per-index process
+lock, so removal fails clearly while that index is in use. Once locked, removal
+moves only the selected index out of the active namespace, then unlinks its flat
+artifact files without recursive directory deletion. Other indexes are
+untouched, and incomplete cleanup is reported with the quarantined artifact
+location rather than silently ignored.
+
+Portable environment variables:
+
+| Variable | Purpose | Claude fallback |
+| --- | --- | --- |
+| `CONTEXT_KIT_DATA` | venv and index storage | `CLAUDE_PLUGIN_DATA` |
+| `CONTEXT_KIT_INDEXKIT_HOME` | venv location only, when it must differ from index storage | — (defaults to `CONTEXT_KIT_DATA`) |
+| `CONTEXT_KIT_EMBED_MODEL` | ollama embedding model | `CLAUDE_PLUGIN_OPTION_EMBED_MODEL` |
+| `CONTEXT_KIT_OLLAMA_HOST` | ollama base URL | `CLAUDE_PLUGIN_OPTION_OLLAMA_HOST` |
+| `XDG_DATA_HOME` | relocates the standalone default data directory | — |
+
+None of these are required for a standalone install; all have defaults.
+The pre-rename `CONTEXT_KIT_LOCAL_RAG_HOME` is still read as a fallback for
+`CONTEXT_KIT_INDEXKIT_HOME`.
+
+`CONTEXT_KIT_DATA` normally holds both the venv and the indexes. Set
+`CONTEXT_KIT_INDEXKIT_HOME` only when a caller needs to redirect *index data*
+to an isolated store while still using one shared bootstrapped venv — the
+`memory` plugin does this to keep each project's index inside its own
+project-isolated provider directory. When it is unset, behavior is unchanged.
+
+The pre-rename `PRODUCTIVITY_SKILLS_*` names still resolve as a deprecated alias
+(`CONTEXT_KIT_*` → `PRODUCTIVITY_SKILLS_*` → Claude fallback).
+
+## Hybrid retrieval
+
+Semantic-only retrieval remains the default. `--hybrid` adds SQLite FTS5 lexical
+BM25 candidates and fuses them with turbovec semantic candidates using deterministic
+reciprocal-rank fusion: `1.0 / (60 + semantic_rank) + 1.0 / (60 + lexical_rank)`.
+Each source retrieves `3 × k` candidates before fusion, so the candidate depth is
+greater than the requested final result count. JSON results include source offsets
+and per-source rank/score metadata; text output remains compact.
+
+`indexkit query` also accepts an `--allowlist` of candidate documents (read from a file,
+or `-` for stdin), which applies to both semantic and lexical candidates. For
+example, feeding Obsidian backlinks into a hybrid query:
+
+```bash
+obsidian backlinks file="X" | indexkit query "..." --hybrid --allowlist -
+```
+
+FTS5 is detected and backfilled automatically for existing indexes. `indexkit status`
+reports its `fts5` capability. If the SQLite build lacks FTS5, semantic retrieval
+continues to work but `--hybrid` exits with a clear error.
+
+MIT © Mark Beacom.