@ninjaxtools/slopdex 0.13.0 → 0.14.0

package/.agents/skills/slopdex/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: slopdex
-description: Semantic code search, find duplicate-function candidates, analyze physical code cohesion
+description: Semantic code search, duplicate-function candidates, and physical-distance re-ranking
 ---
 
 # Slopdex operator guide for agents
@@ -16,6 +16,16 @@ slopdex search "persist user data" -e 'save|persist' --format summary --limit 5
 
 Describe behavior rather than guessing a symbol name. `-e` is a regex that restricts which symbols (functions) are searched.
 
+Hosted reranking is optional and persists in repository config:
+
+```bash
+slopdex config reranker cohere
+# Or: slopdex config reranker jina
+# Or use an LLM: slopdex config reranker openai
+```
+
+Set `COHERE_API_KEY`, `JINA_API_KEY`, or `OPENAI_API_KEY` respectively. The OpenAI LLM reranker defaults to `gpt-5.6-luna`, high reasoning, and the top 10 embedding candidates; configure the pool with `slopdex config reranker openai --reranker-candidates 20`. Disable reranking with `slopdex config reranker disable`. Reranking applies to `search` and `search-description`, not cross-search. It preserves embedding `similarity`, adds `rerankScore`, and orders a wider candidate set by that score.
+
 ### Search function purpose
 
 Code purpose-description generation needs to be enabled once:
@@ -75,7 +85,7 @@ slopdex cross-search --changed-since origin/main --format summary --threshold 0.
 slopdex cross-search --source-path src/services -e '^UserService\.' --format summary --threshold 0.9
 ```
 
-These restrict sources while searching the full eligible index. The same filters work with `cohesion`. All supplied restrictions intersect:
+These restrict sources while searching the full eligible index. All supplied restrictions intersect:
 
 ```bash
 slopdex cross-search --source-path src -e 'validate' \
@@ -88,11 +98,11 @@ Here a source must have changed since the commit and belong to an uncommitted fi
 ### Review physical cohesion
 
 ```bash
-slopdex cohesion --threshold 0.8 --neighbors 20 --limit 50 --format summary
-slopdex cohesion --source-path src/services --threshold 0.8 --format summary
+slopdex cross-search --cohesion --threshold 0.8 --limit 20 --format summary
+slopdex cross-search --cohesion --source-path src/services --threshold 0.8 --format summary
 ```
 
-Ranks related functions by semantic affinity and file/folder separation. add `--include-source` only when full callable bodies are needed.
+`--cohesion` keeps cross-search's semantic matches and orders each source's matches from greatest to least physical path distance. Similarity breaks distance ties. Summary output includes the distance; JSONL matches include `physicalDistance`.
 
 ### Compare repositories
 
@@ -142,6 +152,7 @@ Usage: `slopdex <command> [arguments] [options]`. Quote queries and regexes. Boo
 | `--dimensions <number>` | Positive dimensions supported by the model; OpenAI `3072`, Jina `1024`. |
 | `--description-provider <openai\|opencode\|opencode-go>` | Description provider; OpenAI by default. OpenCode values require `OPENCODE_API_KEY`. |
 | `--description-model <name>` | Description model; `gpt-5.6-sol` for OpenAI/Zen and `gpt-5.6-luna` for Go. |
+| `--reranker-candidates <number>` | With `config reranker openai`, embedding-ranked functions sent to the LLM; range `1`-`100`, default `10`. |
 | `--ignore-errors` | Silence saved-diagnostic warnings without deleting records. |
 | `-h`, `--help` | Usage; no refresh. |
 | `--version` | Package version; exits without refresh or saved-diagnostic warnings. |
@@ -152,18 +163,17 @@ Explicit relative config/index paths resolve from the current directory. Source
 
 | Argument | Applies to / behavior |
 | --- | --- |
-| `--limit <number>` | Positive integer. `search`/`search-description`: matches, default `10`. Cross-search: neighbors per source, default `5`. Cohesion: reported pairs and file rows, default `50`. |
-| `--threshold <number\|min-max>` | Both query searches and analyses. Inclusive minimum or half-open range. Default `-1` for query/cross-search; `0.8` for cohesion. Cohesion minimum must be in `[-1, 1)`. |
-| `--format <json\|summary\|clusters>` | Both query searches, cross-search, cohesion, index-errors. `clusters` only supports cross-search; output defaults below. |
-| `-e <regex>`, `--regexp <regex>`, `--regex <regex>` | Equivalent case-sensitive JavaScript regex options on qualified names. Query searches filter results before limiting; cross-search/cohesion filter sources only. |
-| `--min-lines <number>` | Cross-search/cohesion: positive source/candidate length minimum, default `2`. |
-| `--source-path <path>` | Cross-search/cohesion: source file or recursive directory within the root. |
-| `--changed-since <commit>` | Cross-search/cohesion: added, modified, or moved functions since an ancestor of the indexed Git checkpoint, including working-tree changes. Requires Git. |
-| `--uncommitted` | Cross-search/cohesion: functions indexed from working-tree files; in Git these are staged, unstaged, or untracked changes. Without Git this selects all working-tree functions. |
+| `--limit <number>` | Positive integer. `search`/`search-description`: matches, default `10`. Cross-search: neighbors per source, default `5`. |
+| `--threshold <number\|min-max>` | Both query searches and cross-search. Inclusive minimum or half-open range; default `-1`. |
+| `--format <json\|summary\|clusters>` | Both query searches, cross-search, and index-errors. Cohesion-ranked cross-search supports summary or JSONL, not clusters. |
+| `-e <regex>`, `--regexp <regex>`, `--regex <regex>` | Equivalent case-sensitive JavaScript regex options on qualified names. Query searches filter results before limiting; cross-search filters sources only. |
+| `--min-lines <number>` | Cross-search: positive source/candidate length minimum, default `2`. |
+| `--source-path <path>` | Cross-search: source file or recursive directory within the root. |
+| `--changed-since <commit>` | Cross-search: added, modified, or moved functions since an ancestor of the indexed Git checkpoint, including working-tree changes. Requires Git. |
+| `--uncommitted` | Cross-search: functions indexed from working-tree files; in Git these are staged, unstaged, or untracked changes. Without Git this selects all working-tree functions. |
 | `--cross-file-only` | Cross-search: exclude same-physical-file matches. |
 | `--include-symmetric-duplicates` | Cross-search: allow both directions of same-index matches; otherwise each unordered pair appears once. |
-| `--neighbors <number>` | Cohesion: positive neighbor count per source, default `20`; changes analysis scope. |
-| `--include-source` | Cohesion JSON: include callable bodies; omitted by default. |
+| `--cohesion` | Cross-search: add physical distance and order each source's matches from farthest to nearest. Defaults to summary output. |
 | `--target-root <path>` | Cross-search: second repository; requires `--target-index`. |
 | `--target-index <path>` | Cross-search: second index file; requires `--target-root`. |
 | `--target-config <path>` | Cross-search: target config, default `<target-root>/.slopdex/config.json`; requires both target options. |
@@ -188,12 +198,13 @@ Use `--no-reindex` when the task calls for committed-only results or reuse of an
 | --- | --- | --- |
 | `search`, `search-description` | `summary` | JSON array; purpose search includes generated description text |
 | `cross-search` | `clusters` | `summary`, or `json` for JSONL with one row per matched source |
-| `cohesion` | `summary` | One JSON report |
 | `index-errors` | `summary` | JSON array |
 | `status`, update commands, `descriptions` | JSON object | — |
 
 Prefer summary output for compact source review, clusters for duplicate families, and JSON/JSONL for structured processing. Stdout carries results; stderr carries notices and warnings. Cross-search omits sources without emitted matches. Empty output means no findings under the chosen coverage/filters, not proof that no similar code exists.
 
+With reranking enabled, query summaries display both reranker relevance and embedding similarity. Similarity thresholds filter candidates before reranking; limits apply to the reranked output. LLM candidate documents include descriptions when available and function metadata/source code.
+
 ### Similarity and clusters
 
 ```text
@@ -212,26 +223,16 @@ When reporting candidates, identify paths/symbols, summarize the shared behavior
 
 ### Purpose-aware scoring
 
-When descriptions are complete, `search`, cross-search, and cohesion average code, callable-description, and file-description similarity with equal one-third weights. `search-description` averages callable and file descriptions. Cross-repository analysis needs completeness on both sides; otherwise all scores are code-only. Stale file descriptions remain in scoring until `reindex-files` refreshes them. Description-generator models may differ even though embedding profiles must match.
+When descriptions are complete, `search` and cross-search average code, callable-description, and file-description similarity with equal one-third weights. `search-description` averages callable and file descriptions. Cross-repository analysis needs completeness on both sides; otherwise all scores are code-only. Stale file descriptions remain in scoring until `reindex-files` refreshes them. Description-generator models may differ even though embedding profiles must match.
 
-Thresholds and limits apply to the selected score. Text labels combined scoring; JSON includes component scores and mode/weights (`scoring` in cross-search, `parameters` in cohesion). Compare runs only with matching scoring mode, weights, embedding and description-generator profiles, threshold, neighbor count, and source/candidate filters.
+Thresholds and limits apply to the selected score. Text labels combined scoring; JSON includes component scores and mode/weights in `scoring`. Compare runs only with matching scoring mode, weights, embedding and description-generator profiles, threshold, and source/candidate filters.
 
 ### Cohesion
 
 ```text
-Cohesion: 184 functions analyzed, 37 semantic edges
-  same file 35.1%  same folder 29.7%  remote 35.2%  mean distance 1.84
-
-1. gap 0.6053  similarity 0.9400  distance 4  reciprocal
-   src/auth/session.ts:18:1 :: validateSession
-   packages/http/middleware.ts:42:1 :: authenticate
+src/auth/session.ts :: validateSession
+  0.9400  packages/http/middleware.ts :: authenticate  [distance 4]
+  0.9300  src/auth/token.ts :: validateToken  [distance 1]
 ```
 
-- **Functions analyzed / edges:** selected-source coverage and unique qualifying neighbor pairs before report limiting, not quality grades.
-- **Same file / same folder / remote:** shares of weighted semantic affinity. More remote affinity means more related code crosses folder boundaries.
-- **Mean distance:** weighted physical separation; `0` is same file, `1` is different files in one folder, larger means farther apart.
-- **Gap / rank:** a `0–1` review score combining similarity above the threshold with separation. Higher gap ranks earlier; same-file pairs have zero gap.
-- **Reciprocal:** both functions selected each other as neighbors. JSON `null` means an endpoint was not evaluated because of source filtering.
-- **JSON details:** `semanticWeight` reflects similarity above threshold; `separationWeight` reflects distance; `sourceTestPair` flags a path-inferred source/test relationship; file `externalAffinityRatio` measures affinity outside that file's folder.
-
-The example merits reviewing separated authentication responsibilities, while accounting for intentional layering. There is no universal pass/fail threshold. Use comparable runs to evaluate changes. Filtered reports describe selected sources, not the full repository. Cohesion metrics use all qualifying edges; pairs/files are limited, and groups use reported pairs.
+Physical distance is `0` within one file, `1` between files in one folder, and `1` plus directory-tree hops across folders. The option only reorders the selected semantic matches; it does not change similarity or prove that distant code should be moved. Review architectural layers, tests, adapters, and other intentional separation before recommending consolidation.

package/README.md

@@ -24,6 +24,17 @@ Add `.slopdex/` to your repository's `.gitignore`.
 slopdex search "keep the repository index synchronized" --format summary --limit 10
 ```
 
+Optionally enable a hosted second-stage reranker for `search` and `search-description`:
+
+```bash
+export COHERE_API_KEY="your-api-key"
+slopdex config reranker cohere
+# Or: export JINA_API_KEY="your-api-key" && slopdex config reranker jina
+# Or use an LLM: export OPENAI_API_KEY="your-api-key" && slopdex config reranker openai
+```
+
+The config command is the only CLI switch for reranking. Use `slopdex config reranker disable` to return to embedding-only ordering. An optional final argument selects a model, for example `slopdex config reranker cohere rerank-v4.0-fast`. OpenAI LLM reranking defaults to `gpt-5.6-luna` with high reasoning and receives the top 10 embedding results; change the pool with `--reranker-candidates`, for example `slopdex config reranker openai gpt-5.6-luna --reranker-candidates 20`.
+
 To search generated descriptions of each function's role instead:
 
 ```bash
@@ -62,15 +73,15 @@ slopdex cross-search --changed-since origin/main --format summary --threshold 0.
 slopdex cross-search --source-path src/services -e '^UserService\.' --format summary --threshold 0.9
 ```
 
-These select source functions while keeping the full eligible index available for matches. The same source filters work with `cohesion`.
+These select source functions while keeping the full eligible index available for matches.
 
 ### Find related code stored far apart
 
 ```bash
-slopdex cohesion --threshold 0.8 --neighbors 20 --limit 50 --format summary
+slopdex cross-search --cohesion --threshold 0.8 --limit 20 --format summary
 ```
 
-Ranks semantically related pairs by their physical separation.
+`--cohesion` keeps the semantic matches selected by cross-search, annotates them with physical distance, and orders each source's matches from farthest to nearest. Similarity breaks distance ties.
 
 ### Compare repositories
 
@@ -102,11 +113,11 @@ Usage: `slopdex <command> [arguments] [options]`.
 | `models [opencode\|opencode-go]` | Fetch valid models from the current published Zen and/or Go catalogs. | Qualified `provider/model` lines; optional JSON array |
 | `config model <model\|provider/model>` | Validate a published OpenCode model and persist its provider/model selection without opening an index. Bare IDs auto-resolve only when unambiguous. | Updated setting summary; optional JSON |
 | `config descriptions <enable\|disable>` | Persist whether the next index-using command should enable or disable descriptions. Does not open an index. | Updated setting summary; optional JSON |
+| `config reranker <cohere\|jina\|openai\|disable> [model]` | Enable a hosted or OpenAI LLM query reranker, optionally selecting a model, or disable it. OpenAI accepts `--reranker-candidates <number>` from 1 to 100 and defaults to 10. Does not open an index. | Updated setting summary; optional JSON |
 | `search <query>` | Search function code by meaning. Quote multiword queries. | Summary; optional JSON array |
 | `descriptions <enable\|disable>` | Enable or disable automatic purpose descriptions. Re-enabling with unchanged inputs reuses cached descriptions. | JSON statistics |
 | `search-description <query>` | Search purpose descriptions after enabling them. | Summary including description text; optional JSON array |
 | `cross-search` | Find neighbors for each selected function in this or another index. | `clusters` by default; optional `summary` or JSONL |
-| `cohesion` | Analyze semantic relationships versus file/folder separation. | Summary; optional JSON report |
 | `status` | Refresh and show index metadata, counts, and profiles. | JSON object |
 | `index-errors` | Read saved file/function indexing failures. | Summary; optional JSON array |
 | `update-git` | Explicitly refresh a Git snapshot, with current working-tree changes when targeting HEAD. | JSON update statistics |
@@ -148,18 +159,17 @@ Explicit relative config and index paths resolve from the current directory, not
 
 | Argument | Applies to | Meaning / default |
 | --- | --- | --- |
-| `--limit <number>` | Both query searches, cross-search, cohesion | Positive integer. Query matches: `10`; cross-search neighbors per source: `5`; cohesion reported pairs and file rows: `50`. |
-| `--threshold <number\|min-max>` | Both query searches, cross-search, cohesion | Minimum similarity, or range with inclusive minimum and exclusive maximum. Default `-1` for query/cross-search, `0.8` for cohesion. Cohesion minimum must be at least `-1` and below `1`. |
-| `--format <json\|summary\|clusters>` | Both query searches, cross-search, cohesion, index-errors | Output format; see the commands table. `clusters` is only for cross-search. |
-| `-e <regex>`, `--regexp <regex>`, `--regex <regex>` | Both query searches, cross-search, cohesion | Equivalent case-sensitive JavaScript regex options over qualified names. Query searches: filter results before limiting. Analysis: filter sources only. |
-| `--min-lines <number>` | Cross-search, cohesion | Minimum source and candidate callable length; positive integer, default `2`. Use `1` to include one-line wrappers. |
-| `--source-path <path>` | Cross-search, cohesion | Select sources in a file or recursive directory, relative to the repository root (or absolute within it). |
-| `--changed-since <commit>` | Cross-search, cohesion | Select added, modified, or moved functions relative to an ancestor of the indexed Git checkpoint, including working-tree changes. Requires Git. |
-| `--uncommitted` | Cross-search, cohesion | Select functions indexed from working-tree files: staged, unstaged, or untracked changes in Git; all working-tree functions without Git. |
+| `--limit <number>` | Both query searches, cross-search | Positive integer. Query matches: `10`; cross-search neighbors per source: `5`. |
+| `--threshold <number\|min-max>` | Both query searches, cross-search | Minimum similarity, or range with inclusive minimum and exclusive maximum. Default `-1`. |
+| `--format <json\|summary\|clusters>` | Both query searches, cross-search, index-errors | Output format; see the commands table. `clusters` is only for ordinary cross-search. |
+| `-e <regex>`, `--regexp <regex>`, `--regex <regex>` | Both query searches, cross-search | Equivalent case-sensitive JavaScript regex options over qualified names. Query searches filter results before limiting; cross-search filters sources only. |
+| `--min-lines <number>` | Cross-search | Minimum source and candidate callable length; positive integer, default `2`. Use `1` to include one-line wrappers. |
+| `--source-path <path>` | Cross-search | Select sources in a file or recursive directory, relative to the repository root (or absolute within it). |
+| `--changed-since <commit>` | Cross-search | Select added, modified, or moved functions relative to an ancestor of the indexed Git checkpoint, including working-tree changes. Requires Git. |
+| `--uncommitted` | Cross-search | Select functions indexed from working-tree files: staged, unstaged, or untracked changes in Git; all working-tree functions without Git. |
 | `--cross-file-only` | Cross-search | Exclude matches from the same physical file. |
 | `--include-symmetric-duplicates` | Cross-search | Allow both directions of same-index matches; otherwise each unordered pair is emitted once. |
-| `--neighbors <number>` | Cohesion | Neighbors considered per source; positive integer, default `20`. Changes the analysis graph. |
-| `--include-source` | Cohesion JSON | Include callable bodies; omitted by default. |
+| `--cohesion` | Cross-search | Add `physicalDistance` and re-rank each source's matches by descending distance, with similarity as the tie-breaker. Defaults to summary output; incompatible with clusters. |
 | `--target-root <path>` | Cross-search | Second repository root; requires `--target-index`. |
 | `--target-index <path>` | Cross-search | Second index file; requires `--target-root`. |
 | `--target-config <path>` | Cross-search | Target config; defaults to `<target-root>/.slopdex/config.json`. Requires both target options. |
@@ -186,6 +196,8 @@ slopdex cross-search --cross-file-only --min-lines 4 --threshold 0.85-0.9 --limi
 
 Similarity is a model-dependent score, not a probability of duplication. Higher scores mean greater semantic resemblance. Query summaries show `score  path :: qualifiedName`; cross-search summaries group those lines beneath each source. Functions without matches are omitted from cross-search output.
 
+With reranking enabled, query summaries show `rerankScore rerank (similarity similarity)`. JSON retains `similarity` and adds `rerankScore`. The similarity threshold first filters embedding candidates. Cohere and Jina receive up to five times the requested limit. The OpenAI LLM receives the configured number of top embedding results, 10 by default, or the requested result limit when it is larger. Candidates include function descriptions when available and function metadata/source code. Cross-search and cohesion analysis are not sent to rerankers.
+
 ```text
 Cluster 1 (3 functions, similarity 0.9124-0.9568)
   src/auth/session.ts:18:1 :: validateSession
@@ -197,30 +209,17 @@ Cluster 1 (3 functions, similarity 0.9124-0.9568)
 - Clusters sort by member count, then name. Cluster number is not severity.
 - Locations identify where to inspect behavior, callers, and architectural roles. Wrappers, adapters, tests, and separate interface implementations can legitimately resemble one another.
 
-### Cohesion
+### Physical cohesion
 
 ```text
-Cohesion: 184 functions analyzed, 37 semantic edges
-  same file 35.1%  same folder 29.7%  remote 35.2%  mean distance 1.84
-
-1. gap 0.6053  similarity 0.9400  distance 4  reciprocal
-   src/auth/session.ts:18:1 :: validateSession
-   packages/http/middleware.ts:42:1 :: authenticate
+src/auth/session.ts :: validateSession
+  0.9400  packages/http/middleware.ts :: authenticate  [distance 4]
+  0.9300  src/auth/token.ts :: validateToken  [distance 1]
 ```
 
-| Field | Interpretation |
-| --- | --- |
-| Functions analyzed / semantic edges | Selected-source coverage / unique qualifying neighbor pairs, before report limiting. Not quality scores. |
-| Same file / same folder / remote | Shares of weighted semantic affinity. Higher remote affinity means more related code crosses folder boundaries. |
-| Mean distance | Weighted physical separation: `0` for the same file, `1` for different files in one folder, larger across folders. |
-| Gap / rank | A `0–1` review score combining similarity above the threshold and separation; higher gap ranks first. Same-file pairs have zero gap. |
-| Reciprocal | Both functions selected each other as neighbors. JSON `null` means the other endpoint was not evaluated under source filtering. |
-| `sourceTestPair` | A source/test relationship inferred from paths; separation may be intentional. |
-| `externalAffinityRatio` | In JSON file reports, the share of observed affinity outside that file's folder. |
-
-The example suggests reviewing separated authentication responsibilities. It does not establish that they belong in one module. There is no universal cohesion pass threshold. Filtered reports describe selected sources, not the entire repository. Cohesion metrics cover all qualifying edges; reported pairs/files are limited, and groups are built from reported pairs.
+Run cross-search with `--cohesion` to put physically distant matches first. Distance is `0` within one file, `1` between files in one folder, and `1` plus directory-tree hops across folders. The option only changes the order of each source's selected semantic matches; it does not change similarity scores or establish that distant code belongs together.
 
-For automation, pass `--format json`: query searches and diagnostics return JSON arrays; cross-search returns **JSONL**, one row per matched source; cohesion returns one JSON object containing `repository`, `parameters`, `metrics`, `pairs`, `files`, and `groups`. Results go to stdout; notices and warnings go to stderr.
+For automation, pass `--format json`: query searches and diagnostics return JSON arrays; cross-search returns **JSONL**, one row per matched source. With `--cohesion`, each match includes `physicalDistance`. Results go to stdout; notices and warnings go to stderr.
 
 ## System behavior
 
@@ -234,9 +233,9 @@ Ordinary updates preserve an existing file description even when its source chan
 
 Tree-sitter extraction, generated descriptions, and document/query vectors are content-addressed in the same SQLite database. Each validated result is committed immediately, independently of the final logical index update. If indexing is interrupted or a later provider call fails, rerunning reuses every completed result whose profile, operation, input, and source context hash still match.
 
-With complete descriptions, `search`, cross-search, and cohesion average **one-third code similarity + one-third callable-description similarity + one-third file-description similarity**. `search-description` averages callable and file descriptions without code. Cross-repository analysis needs complete descriptions on both sides; otherwise the entire analysis uses code-only scores. Stale file descriptions remain searchable until explicitly reindexed. Thresholds and neighbor limits apply to the selected score.
+With complete descriptions, `search` and cross-search average **one-third code similarity + one-third callable-description similarity + one-third file-description similarity**. `search-description` averages callable and file descriptions without code. Cross-repository analysis needs complete descriptions on both sides; otherwise the entire analysis uses code-only scores. Stale file descriptions remain searchable until explicitly reindexed. Thresholds and limits apply to the selected score.
 
-Text output labels combined scores. JSON exposes `codeSimilarity`, `descriptionSimilarity`, `fileDescriptionSimilarity`, and scoring mode/weights (`scoring` for cross-search, `parameters` for cohesion). Compare runs only with matching scoring mode, weights, embedding and description-generator profiles, threshold, neighbor count, and source/candidate filters.
+Text output labels combined scores. JSON exposes `codeSimilarity`, `descriptionSimilarity`, `fileDescriptionSimilarity`, and cross-search scoring mode/weights. Compare runs only with matching scoring mode, weights, embedding and description-generator profiles, threshold, and source/candidate filters.
 
 ### Exclusions
 
@@ -250,17 +249,21 @@ Parse, extraction, read, and file-size failures are saved while healthy callable
 
 Saved failures trigger stderr warnings, including on cached runs, help, and cross-search targets. `--ignore-errors` silences warnings without clearing records. Updates retry failed files; successful indexing, deletion, or exclusion clears their diagnostics. Version output bypasses diagnostics.
 
-Use the recovery flag named in the error: `--rebuild-on-divergence` for Git history changes, `--force-reindex` for incompatible indexes. Schema versions before 5 require `--force-reindex`; schema-5 rebuilds preserve reusable artifact caches. For provider/authentication failures, fix the reported configuration and rerun. For source-change-during-indexing errors, rerun after edits settle. Exit status is `0` on success, `2` for argument/domain errors, and `1` for other failures (or invocation without a command).
+Use the recovery flag named in the error: `--rebuild-on-divergence` for Git history changes, `--force-reindex` for incompatible indexes. Schema versions 6 and 7 migrate in place; earlier schemas require `--force-reindex`, with compatible rebuilds preserving reusable artifact caches. For provider/authentication failures, fix the reported configuration and rerun. For source-change-during-indexing errors, rerun after edits settle. Exit status is `0` on success, `2` for argument/domain errors, and `1` for other failures (or invocation without a command).
 
 ## Configuration
 
-Optional file: `<root>/.slopdex/config.json`. Example using Jina embeddings and OpenCode Go descriptions (requires `JINA_API_KEY`, plus `OPENCODE_API_KEY` when descriptions are enabled):
+Optional file: `<root>/.slopdex/config.json`. Example using Jina embeddings, OpenAI LLM reranking, and OpenCode Go descriptions (requires `JINA_API_KEY`, `OPENAI_API_KEY` for query searches, plus `OPENCODE_API_KEY` when descriptions are enabled):
 
 ```json
 {
   "provider": "jina",
   "model": "jina-embeddings-v4",
   "dimensions": 1024,
+  "rerankingEnabled": true,
+  "rerankerProvider": "openai",
+  "rerankerModel": "gpt-5.6-luna",
+  "rerankerCandidates": 10,
   "descriptionProvider": "opencode-go",
   "exclude": ["**/fixtures/**"]
 }
@@ -272,13 +275,17 @@ Optional file: `<root>/.slopdex/config.json`. Example using Jina embeddings and
 | `descriptionProvider` | Description provider: `openai`, `opencode` (Zen), or `opencode-go`; defaults to `openai`. |
 | `descriptionModel` | Description model; provider default unless explicitly set. |
 | `descriptionsEnabled` | When true or false, the next index-using command applies that enabled state during its normal refresh. Unset leaves persisted index state unchanged. |
+| `rerankingEnabled` | Enables second-stage ranking for `search` and `search-description`; disabled/unset by default. Prefer changing it through `config reranker`. |
+| `rerankerProvider` | Reranker: `cohere`, `jina`, or `openai`. OpenAI uses an LLM rather than a dedicated reranking endpoint. |
+| `rerankerModel` | Provider model; defaults to Cohere `rerank-v4.0-pro`, Jina `jina-reranker-v3.5`, or OpenAI `gpt-5.6-luna`. |
+| `rerankerCandidates` | Embedding-ranked candidates sent to the OpenAI LLM; integer from `1` to `100`, default `10`. The requested result limit takes precedence when larger, up to 100. |
 | `indexPath` | Index location; `<root>/.slopdex/index.sqlite`. |
 | `include` | Repository-relative glob array; empty/unset includes all supported eligible files. |
 | `exclude` | Additional repository-relative exclusion globs. |
 | `maxFileSize` | Maximum source-file size in bytes; positive integer, default `1048576`. |
 | `embeddingBatchSize` | Embedding inputs per batch; positive integer, default `32`. |
 
-Keep keys in the environment (`OPENAI_API_KEY`, `JINA_API_KEY`, `OPENCODE_API_KEY`). Changing the embedding profile requires rebuilding with `--force-reindex`.
+Keep keys in the environment (`OPENAI_API_KEY`, `JINA_API_KEY`, `COHERE_API_KEY`, `OPENCODE_API_KEY`). Reranker settings do not change the stored index and do not require a rebuild. Changing the embedding profile requires rebuilding with `--force-reindex`.
 
 ## Development