xists 0.7.0__py3-none-any.whl

.env.example

@@ -0,0 +1,54 @@
+# GitHub ingestion
+# Single token:
+GITHUB_TOKEN=your_github_token_here
+# Multiple tokens (comma-separated, for higher rate limits):
+# GITHUB_TOKENS=tok1,tok2,tok3
+
+# LLM profile generation (OpenAI-compatible chat completions endpoint)
+# Used only during ingest to turn collected repo evidence into a structured profile.
+# Works with OpenAI, vLLM, Ollama, Together, DeepSeek, Moonshot, etc.
+LLM_API_KEY=your_llm_api_key_here
+LLM_BASE_URL=https://api.deepseek.com
+LLM_MODEL=deepseek-v4-pro
+
+# Optional query canonicalization (OpenAI-compatible chat completions endpoint)
+# Used only with `xists search` or `xists eval run` plus --query-transform-mode.
+# It can convert queries into an English retrieval expression for an
+# English-dominant corpus while xists keeps the local index and ranking.
+QUERY_TRANSFORM_API_KEY=your_query_transform_api_key_here
+QUERY_TRANSFORM_BASE_URL=https://api.example.com/v1
+QUERY_TRANSFORM_MODEL=your_chat_model
+
+# Embedding vector calculation (OpenAI-compatible embeddings endpoint)
+# Used to compute vectors for:
+#   1. records during `xists index build`
+#   2. the query text during `xists search` / `xists eval run`
+# The endpoint does NOT store your index and does NOT perform vector search.
+# xists keeps vectors in local index.json and does ranking/query locally.
+#
+# IMPORTANT:
+# This single embedding config is shared by:
+#   - `xists index build` to embed repository records
+#   - `xists search` / `xists eval run` to embed query text
+# The query embedding model must match the model used to build index.json.
+# Do not change EMBEDDING_MODEL after building an index unless you rebuild it:
+#   xists index build --force
+#
+# Recommended local CUDA example: BAAI/bge-m3 via TEI on localhost:6597
+#   docker-served endpoint: http://localhost:6597/v1 or http://localhost:6597
+#   EMBEDDING_API_KEY can be any non-empty placeholder if the local server has no auth.
+EMBEDDING_API_KEY=local
+EMBEDDING_BASE_URL=http://localhost:6597/v1
+EMBEDDING_MODEL=BAAI/bge-m3
+
+# Remote embedding APIs can also be used as calculate-only endpoints.
+# They compute vectors, while xists still searches the local index.
+# Example:
+# EMBEDDING_API_KEY=your_remote_embedding_api_key_here
+# EMBEDDING_BASE_URL=https://api.openai.com/v1
+# EMBEDDING_MODEL=text-embedding-3-small
+#
+# For a dual-encoder retrieval service that requires a request role field,
+# enable it explicitly. xists then sends `passage` for index builds and
+# `query` for search/evaluation. Leave unset for ordinary embedding APIs.
+# EMBEDDING_INPUT_TYPE_FIELD=input_type

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UsonTong
+
+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.

README.md

@@ -0,0 +1,238 @@
+<div align="center"><a name="readme-top"></a>
+
+# xists
+
+Find first. Build later.
+
+`xists` is a local semantic search engine for selected lists of GitHub repositories. Check if a similar project already exists before you build it.
+
+**English** · [简体中文](./README.zh-CN.md)
+
+</div>
+
+---
+
+## Why xists?
+
+Global GitHub search is often noisy, and traditional keyword matching lacks semantic understanding. `xists` solves this by narrowing the search space: you provide a curated repository list, and `xists` builds a local index for semantic search.
+
+- **Before you build**: check if a similar project or existing solution already exists.
+- **Tech decisions**: compare candidates from a curated set using semantic search.
+- **Fast lookups**: quickly find what you need without manually opening dozens of READMEs.
+
+## How it works
+
+```mermaid
+flowchart LR
+    A[Repo List] --> B[Ingest Metadata]
+    B --> C[Generate LLM Summaries]
+    C --> D[Build Local Index]
+    D --> E[Search]
+    D -. optional .-> F[Evaluate Ranking]
+    F -.-> G[Inspect Misses]
+```
+
+1. **Ingest**: Provide a list of GitHub repos. `xists` fetches their metadata and READMEs.
+2. **Profile**: It uses an LLM to generate compact, search-optimized summaries for better matching.
+3. **Index**: It builds a local JSON embedding index.
+4. **Search**: You query the index using semantic search.
+
+## Local-first index, explicit model endpoints
+
+`xists` keeps everything transparent and local:
+- `records.json`: Raw metadata, structure signals, and LLM-generated profiles.
+- `index.json`: The embedding index.
+- `eval-report.json`: Search quality test results.
+
+You need a GitHub token for the initial data fetch, plus model endpoints for summaries and embeddings. The records, index, ranking, and evaluation report stay on your machine. An embedding endpoint calculates vectors; xists stores them in local JSON and compares them locally.
+
+## Install and first search
+
+Requires Python 3.11+. PyPI publication is prepared for v0.7.0 but has not
+yet been authorized; until then, install directly from a checked-out source
+tree:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+After v0.7.0 is published, the equivalent package installation will be:
+
+```bash
+python -m pip install xists
+```
+
+Then create a local configuration file and build an index from repositories
+you control:
+
+```bash
+cp .env.example .env
+# Set the required GitHub, LLM, and embedding variables in .env.
+
+xists ingest github --repos repos.txt --output records.json --report report.json
+xists index build --records records.json --output index.json
+xists search "open source firebase alternative" --index index.json
+```
+
+See [the demo walkthrough](docs/demo.md) for endpoint checks, concurrency,
+evaluation, and troubleshooting. No current-schema demo records/index download
+is published yet; the first Release asset will be created only after it passes
+`records validate` and `index verify`.
+
+---
+
+## Quickstart
+
+Requires Python 3.11+.
+
+```bash
+# Install
+python -m pip install -e ".[dev]"
+
+# Set up config
+cp .env.example .env
+# Edit .env with your GitHub token, LLM model, and embedding model
+```
+
+**Run the pipeline:**
+
+```bash
+# 1. Fetch data & generate summaries
+xists ingest github \
+  --repos repos.txt \
+  --output demo-records.json \
+  --report demo-report.json \
+  --github-api graphql
+
+# 2. Build the local index
+xists index build \
+  --records demo-records.json \
+  --output demo-index.json
+
+# 3. Search!
+xists search "open source firebase alternative" --index demo-index.json
+xists search "open source firebase alternative" --index demo-index.json --format json
+```
+
+The commands above generate local files and may call the endpoints configured
+in `.env`; use `records.json` / `index.json` instead if you do not want files
+named as demo artifacts.
+
+---
+
+## Python API
+
+Use the stable API when another Python program needs the same search behavior
+as the CLI. Configuration is always explicit; importing `xists.api` does not
+read `.env` or send network requests.
+
+```python
+from xists.api import load_index, search
+from xists.search.embed import EmbeddingConfig
+
+index = load_index("index.json")
+config = EmbeddingConfig(
+    api_key="your-key",
+    base_url="https://your-embedding-endpoint/v1",
+    model="your-embedding-model",
+)
+result = search("open source firebase alternative", index, embedding_config=config, top_k=5)
+```
+
+`search()` may call the endpoint in `config` to embed the query. It raises
+actionable Python exceptions for invalid indexes, incompatible embedding models,
+and endpoint failures instead of printing or terminating the process.
+
+---
+
+## Data, security, and privacy
+
+- `.env` and token files are read only from your local machine; xists does not
+  commit, print, telemetry-report, or upload their secret values.
+- `ingest github` sends your GitHub token only to GitHub. `profile refresh` and
+  ingest-time profile generation send repository text to the configured LLM
+  endpoint. `index build` sends embeddable repository text to the configured
+  embedding endpoint; `search` and `eval run` send query text to that endpoint.
+- A local endpoint keeps those requests on your machine or network. A remote
+  endpoint receives the corresponding text under that provider's terms; choose
+  it only when you are permitted to send the material. xists does not host the
+  endpoint, upload your index, or perform vector search remotely.
+- If you share records or indexes, you are responsible for checking repository
+  licenses, source content, generated profiles, and any personal or sensitive
+  information before distribution.
+
+---
+
+## Search Result Example
+
+When you run a search, `xists` returns a compact text view by default for terminal review. Add `--format json` for scripts and agent integrations. v0.2.0 keeps ranking simple: exact repo/name/alias matches are pinned first, then semantic similarity is adjusted by a few explainable metadata signals.
+
+Default text output looks like this:
+
+```text
+query: hermes ai agent
+intent: functional
+abstained: False
+results: 1
+1. repo: NousResearch/hermes-agent
+   url: https://github.com/NousResearch/hermes-agent
+   confidence: high_confidence
+   score: 0.680000
+   summary: An agent-oriented project for Hermes models.
+   why: matched metadata terms: agent
+```
+
+The JSON output keeps the same ranking evidence in a machine-readable shape:
+
+```json
+{
+  "query": "hermes ai agent",
+  "results": [
+    {
+      "repo_id": "NousResearch/hermes-agent",
+      "url": "https://github.com/NousResearch/hermes-agent",
+      "score": 0.68,
+      "semantic_score": 0.63,
+      "metadata_score": 0.05,
+      "confidence": "high_confidence",
+      "why": ["matched metadata terms: agent"]
+    }
+  ]
+}
+```
+
+`score` is the final ranking score; higher means a stronger match. Use `--format json` when another program or agent needs the structured payload.
+
+---
+
+## Optional Evaluation
+
+If you update the repository list, regenerate summaries, or change the search setup, `xists` lets you run fixed test cases to sanity-check whether results changed in a meaningful way.
+
+```bash
+pytest
+xists eval run \
+  --cases examples/eval-cases.json \
+  --index demo-index.json \
+  --output demo-eval-report.json
+
+xists eval inspect --report demo-eval-report.json --status serious_mismatch
+```
+
+The report groups results into pragmatic categories:
+- **Exact match**: The specific target repo was #1.
+- **Acceptable alternative**: Not the exact target, but a valid substitute (e.g., returning Vue when you asked for a React-like framework).
+- **Serious mismatch**: The top result missed the core intent.
+- **Insufficient evidence**: The indexed data was too thin to judge.
+
+---
+
+## Commands
+
+- `xists doctor`: Check config and file status; add `--check-endpoints` or `--strict` to probe the embedding service.
+- `xists ingest github`: Fetch repo metadata and generate summaries.
+- `xists index build`: Build or incrementally update the local index.
+- `xists search "query"`: Query the local index with readable terminal output by default; add `--format json` for scripts and agents.
+- `xists eval cases` / `xists eval run` / `xists eval inspect`: Validate the dataset and run/review ranking tests.
+- `xists records validate` / `xists records stats` / `xists records inspect`: Check record quality without printing huge payloads to your terminal.
+- `xists index stats` / `xists index verify`: Summarize an index and confirm it is in sync with records.

README.zh-CN.md

@@ -0,0 +1,218 @@
+<div align="center"><a name="readme-top"></a>
+
+# xists
+
+先找，再做。
+
+`xists` 是一个面向 GitHub 仓库清单的本地语义搜索工具。造轮子前，先用它查查是否有类似项目或现成方案。
+
+[English](./README.md) · **简体中文**
+
+</div>
+
+---
+
+## 为什么写 xists？
+
+GitHub 的全局搜索常常伴随较高的信息噪音，而传统的关键词匹配又受限于字面约束。`xists` 的核心思路是通过缩小搜索域来提升精度：基于用户提供的特定仓库清单构建本地索引，从而实现更高效的语义检索。
+
+- **动手之前**：通过语义检索查一下有没有类似项目或现成方案。
+- **技术选型**：在候选项目池里快速比对，不用挨个翻 README。
+- **快速定位**：告别精确关键词，用你脑海里的描述直接搜。
+
+## 工作流
+
+```mermaid
+flowchart LR
+    A[仓库清单] --> B[抓取元数据]
+    B --> C[LLM 生成结构化摘要]
+    C --> D[构建本地索引]
+    D --> E[搜索]
+    D -. 可选 .-> F[评测排序质量]
+    F -.-> G[检查未命中案例]
+```
+
+1. **拉取**：提供仓库列表，`xists` 通过 GitHub API 抓取它们的元数据和 README。
+2. **总结**：调用 LLM 为每个仓库生成适合被检索的结构化短语和简介。
+3. **索引**：在本地构建基于 Embedding 的 JSON 向量索引。
+4. **搜索**：直接在本地进行语义检索。
+
+## 本地索引，模型接口显式配置
+
+`xists` 所有的中间产物和结果都透明且受你掌控：
+- `records.json`：存放仓库的基础信息和 LLM 生成的特征画像。
+- `index.json`：本地的 Embedding 索引。
+- `eval-report.json`：检索质量评测报告。
+
+首次采集需要 GitHub token；生成摘要与 embedding 还需要模型接口。records、index、排序和评测报告都保留在本机。embedding 接口只负责计算向量；xists 把向量保存为本地 JSON，并在本地完成相似度计算与排序。
+
+## 安装与第一次搜索
+
+环境要求：Python 3.11+。v0.7.0 正在准备 PyPI 首发，但尚未获授权发布；在此之前，请从检出的源码目录安装：
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+v0.7.0 发布后，对应的安装方式会是：
+
+```bash
+python -m pip install xists
+```
+
+然后创建本地配置，并从你有权处理的仓库清单构建索引：
+
+```bash
+cp .env.example .env
+# 在 .env 中填写 GitHub、LLM 和 embedding 配置。
+
+xists ingest github --repos repos.txt --output records.json --report report.json
+xists index build --records records.json --output index.json
+xists search "open source firebase alternative" --index index.json
+```
+
+完整的接口预检、并发、评测和排错说明请看[演示流程](docs/demo.md)。目前尚未发布符合当前 schema 的 demo records/index 下载包；首个 Release asset 必须先通过 `records validate` 与 `index verify` 才会提供。
+
+---
+
+## 快速开始
+
+环境要求：Python 3.11+。
+
+```bash
+# 安装
+python -m pip install -e ".[dev]"
+
+# 配置
+cp .env.example .env
+# 在 .env 中填入你的 GitHub token、LLM 模型和 embedding 模型配置
+```
+
+**跑通全流程：**
+
+```bash
+# 1. 抓取数据并生成总结
+xists ingest github \
+  --repos repos.txt \
+  --output demo-records.json \
+  --report demo-report.json \
+  --github-api graphql
+
+# 2. 构建本地向量索引
+xists index build \
+  --records demo-records.json \
+  --output demo-index.json
+
+# 3. 开始搜索！
+xists search "open source firebase alternative" --index demo-index.json
+xists search "open source firebase alternative" --index demo-index.json --format json
+```
+
+上面的命令会生成本地文件，并可能调用 `.env` 里配置的接口；若不希望使用 demo 命名，请改用 `records.json` 和 `index.json`。
+
+---
+
+## Python API
+
+其他 Python 程序需要使用和 CLI 相同的搜索逻辑时，可以使用稳定 API。配置必须显式传入；导入 `xists.api` 不会读取 `.env`，也不会发起网络请求。
+
+```python
+from xists.api import load_index, search
+from xists.search.embed import EmbeddingConfig
+
+index = load_index("index.json")
+config = EmbeddingConfig(
+    api_key="your-key",
+    base_url="https://your-embedding-endpoint/v1",
+    model="your-embedding-model",
+)
+result = search("open source firebase alternative", index, embedding_config=config, top_k=5)
+```
+
+`search()` 会按需调用 `config` 指定的接口来计算查询向量。无效 index、embedding 模型不兼容或接口失败会以可捕获的 Python 异常返回，不会打印信息或结束进程。
+
+---
+
+## 数据、安全与隐私
+
+- `.env` 和 token 文件只在本地读取；xists 不会提交、打印、遥测上报或上传其中的密钥。
+- `ingest github` 只会把 GitHub token 发给 GitHub。`profile refresh` 与 ingest 中生成 profile 的步骤会把仓库文本发送给你配置的 LLM 接口。`index build` 会把可 embedding 的仓库文本发送给 embedding 接口；`search` 和 `eval run` 会把查询文本发送给该接口。
+- 选择本地接口时，请求会留在你的机器或网络中；选择远端接口时，对应文本会发送给该提供商，并受其条款约束。xists 不托管接口、不上传你的 index，也不在远端执行向量搜索。
+- 若你分享 records 或 index，需要自行检查仓库许可证、源内容、生成的 profile，以及其中是否包含个人或敏感信息。
+
+---
+
+## 检索结果示例
+
+每次搜索，`xists` 默认都会输出适合终端阅读的紧凑文本。脚本和 agent 集成可以加 `--format json` 获取结构化结果。v0.2.0 的排序刻意保持简单：先固定精确 repo/name/alias 命中，再用少量可解释 metadata 信号调整语义相似度。
+
+默认文本输出类似这样：
+
+```text
+query: hermes ai agent
+intent: functional
+abstained: False
+results: 1
+1. repo: NousResearch/hermes-agent
+   url: https://github.com/NousResearch/hermes-agent
+   confidence: high_confidence
+   score: 0.680000
+   summary: An agent-oriented project for Hermes models.
+   why: matched metadata terms: agent
+```
+
+JSON 输出保留相同的排序证据，适合机器读取：
+
+```json
+{
+  "query": "hermes ai agent",
+  "results": [
+    {
+      "repo_id": "NousResearch/hermes-agent",
+      "url": "https://github.com/NousResearch/hermes-agent",
+      "score": 0.68,
+      "semantic_score": 0.63,
+      "metadata_score": 0.05,
+      "confidence": "high_confidence",
+      "why": ["matched metadata terms: agent"]
+    }
+  ]
+}
+```
+
+`score` 是最终排序分数，越高代表匹配越强。其他程序或 agent 需要结构化 payload 时使用 `--format json`。
+
+---
+
+## 可选评测
+
+如果你更换了仓库清单、重新生成了摘要，或调整了搜索配置，`xists` 内置的评测工具可以用固定测试用例帮你检查结果是否有明显变化：
+
+```bash
+pytest
+xists eval run \
+  --cases examples/eval-cases.json \
+  --index demo-index.json \
+  --output demo-eval-report.json
+
+# 直接查看错误的 Case
+xists eval inspect --report demo-eval-report.json --status serious_mismatch
+```
+
+评测报告会将结果分为以下几种务实的类型：
+- **精确命中**：第一名就是预期中的目标仓库。
+- **可接受替代**：第一名不是指定仓库，但也是个合理的同类竞品（比如你搜 React 相关的，它推了 Vue）。
+- **明显不匹配**：第一名完全不符合搜索意图。
+- **证据不足**：索引的数据太少，没法客观判断。
+
+---
+
+## 常用命令一览
+
+- `xists doctor`：检查本地配置和文件状态；加 `--check-endpoints` 或 `--strict` 可探测 embedding 服务。
+- `xists ingest github`：拉取仓库信息并生成短语摘要。
+- `xists index build`：构建或增量更新本地向量索引。
+- `xists search "query"`：执行搜索，默认输出适合终端阅读；加 `--format json` 可输出给脚本和 agent 使用的结构化结果。
+- `xists eval cases` / `xists eval run` / `xists eval inspect`：校验评测集并运行、检查检索评测。
+- `xists records validate` / `xists records stats` / `xists records inspect`：检查 records 质量，避免终端被长 JSON 刷屏。
+- `xists index stats` / `xists index verify`：概览 index，并确认它和 records 仍然同步。

docs/demo.md

@@ -0,0 +1,160 @@
+# Demo Workflow
+
+This guide walks through the smallest end-to-end xists workflow using the committed demo inputs.
+
+## Files
+
+- `repos.txt`: the current demo repository list in the project root
+- `examples/eval-cases.json`: committed 100-case evaluation baseline
+- `examples/eval-cases-extended.json`: optional 112-case evaluation dataset for broader checking
+
+## 1. Install
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## 2. Configure credentials
+
+Create a local `.env` file:
+
+```bash
+cp .env.example .env
+```
+
+Set the required GitHub, LLM, and embedding credentials in `.env`.
+
+## 3. Preflight and endpoint checks
+
+Before spending GitHub or LLM quota, verify the local files and configuration:
+
+```bash
+xists doctor \
+  --records demo-records.json \
+  --index demo-index.json \
+  --cases examples/eval-cases.json
+```
+
+`doctor` returns JSON. Missing generated files are warnings because the demo may
+not have been generated yet. Missing embedding or LLM variables are errors with
+`next_steps` entries showing what to set in `.env`.
+
+When your embedding service is supposed to be running, probe it with a real
+request before building an index, searching, or running eval:
+
+```bash
+xists doctor \
+  --records demo-records.json \
+  --index demo-index.json \
+  --cases examples/eval-cases.json \
+  --check-endpoints
+```
+
+Use `--strict` in scripts or CI-style smoke checks when endpoint failures should
+make the command exit non-zero:
+
+```bash
+xists doctor \
+  --records demo-records.json \
+  --index demo-index.json \
+  --cases examples/eval-cases.json \
+  --check-endpoints \
+  --strict
+```
+
+If the probe cannot connect, start the embedding server referenced by
+`EMBEDDING_BASE_URL`, confirm the URL is the API root such as
+`http://localhost:6597/v1`, and rerun the strict doctor command before retrying
+`index build`, `search`, or `eval run`.
+
+## 4. Ingest example repositories
+
+```bash
+xists ingest github \
+  --repos repos.txt \
+  --output demo-records.json \
+  --report demo-report.json \
+  --github-api graphql \
+  --github-batch-size 10 \
+  --workers 4
+```
+
+This fetches GitHub data, generates LLM profiles, and writes checkpoints as records finish:
+
+- `demo-records.json`
+- `demo-report.json`
+
+The ingest command prints progress to stderr while it runs. If your LLM endpoint is rate-limited, reduce `--workers` to `1` or `2`.
+
+## 5. Build the example index
+
+```bash
+xists index build \
+  --records demo-records.json \
+  --output demo-index.json
+```
+
+## 6. Run a few searches
+
+```bash
+xists search "frontend ui library" --index demo-index.json
+xists search "python web framework for building apis" --index demo-index.json
+xists search "open source workflow automation platform" --index demo-index.json
+```
+
+Expected results vary by model and repository data, but the top results should usually come from the same neighborhood as the query.
+
+## 7. Optionally evaluate the demo index
+
+```bash
+xists eval cases --cases examples/eval-cases.json
+xists eval run \
+  --cases examples/eval-cases.json \
+  --index demo-index.json \
+  --output demo-eval-report.json
+```
+
+The report includes:
+
+- hard retrieval metrics such as `exact_hit_at_1`, `acceptable_hit_at_k`, and `mrr_exact`
+- a readable `summary_text` block for exact top-1, acceptable top-1, serious mismatches, abstains, and wrong high-confidence cases
+- `top_misses`, a sorted list of the most actionable failures
+- confidence counts for top-1 predictions
+- per-case top-1 outcomes in `results`
+
+Inspect the failures that matter most:
+
+```bash
+xists eval inspect --report demo-eval-report.json
+xists eval inspect --report demo-eval-report.json --status serious_mismatch
+xists eval inspect --report demo-eval-report.json --tag ai
+```
+
+## 8. Inspect misses and iterate
+
+After changing the repository list, regenerating summaries, or adjusting search behavior, rerun:
+
+```bash
+xists index build --records demo-records.json --output demo-index.json --force
+xists eval cases --cases examples/eval-cases.json
+xists eval run --cases examples/eval-cases.json --index demo-index.json --output demo-eval-report.json
+xists eval inspect --report demo-eval-report.json --status serious_mismatch
+```
+
+That gives you a stable way to sanity-check search behavior before moving on to larger repository lists or evaluation datasets.
+
+## Common run failures
+
+- `Embedding is required ... Missing environment variables`: copy `.env.example`
+  to `.env` and set `EMBEDDING_API_KEY`, `EMBEDDING_BASE_URL`, and
+  `EMBEDDING_MODEL`.
+- `Embedding request failed for all configured endpoints`: the embedding server
+  is not reachable at `EMBEDDING_BASE_URL`, the URL points at the wrong API root,
+  or the server exposes only one of the supported OpenAI-compatible `/embeddings`
+  or TEI `/embed` shapes. Run `xists doctor --check-endpoints --strict` after
+  fixing it.
+- `LLM endpoint is not configured`: set `LLM_API_KEY`, `LLM_BASE_URL`, and
+  `LLM_MODEL`; this is required for ingest because profiles are LLM-generated.
+- `GitHub token is not configured`: set `GITHUB_TOKEN`/`GITHUB_TOKENS` or pass
+  `--token-file` before ingesting. Existing records, indexes, search, and eval do
+  not need a GitHub token.