@ninjaxtools/slopdex 0.8.0 → 0.10.0

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

@@ -1,340 +1,220 @@
 ---
 name: slopdex
-description: Use when indexing Python, JavaScript, JSX, TypeScript, TSX, Rust, Go, Java, or C code, running semantic function search, finding duplicate function candidates, or analyzing physical code cohesion with the slopdex command-line tool.
+description: Semantic code search, find duplicate-function candidates, analyze physical code cohesion
 ---
 
-# Slopdex CLI
+# Slopdex operator guide for agents
 
-Use `slopdex` to index named Python, JavaScript, JSX, TypeScript, TSX, Rust, Go, Java, and C callables with Tree-sitter, search them by meaning, identify similar or duplicated functions, and find related functions scattered across a repository. Languages are detected by extension and can coexist in one index.
+Slopdex does semantic code search, finds similar-code candidates, and identifies related functions stored far apart.
 
-## Default Workflow
-
-Run the command that satisfies the user's request immediately. Do not begin with `slopdex status`, `slopdex --help`, executable lookup, API-key probes, or version probes. Slopdex performs its own validation and reports missing credentials or incompatible state.
-
-- For semantic search, run `slopdex search "<query>" --format summary --limit 10`.
-- For duplicate-code clusters, run `slopdex cross-search --cross-file-only --min-lines 4 --threshold 0.9 --limit 5`.
-- For related functions that are physically separated, run `slopdex cohesion --format summary --threshold 0.8 --neighbors 20 --limit 50`.
-- For an explicit request to refresh the current index, run `slopdex update-git`.
-- Use `slopdex status` only when the user asks for index metadata or checkpoint information.
-
-Every command refreshes its index from committed `HEAD`, then overlays working-tree changes. A missing index is created automatically; let the requested command perform the refresh rather than initializing separately. Without Git or a Git repository, every command warns on stderr and fully re-indexes the working tree. Use `--no-reindex` only when explicitly asked to skip Git working-tree overlays or reuse an existing non-empty index without Git.
-
-## Prerequisites
-
-- Run commands from the repository root or pass `--root <path>`.
-- Set `OPENAI_API_KEY` or `JINA_API_KEY` for the configured embedding provider.
-- Use Node.js 24 or newer.
-- Store optional configuration in `.slopdex/config.json`:
-
-```json
-{
-  "provider": "jina",
-  "model": "jina-embeddings-v4",
-  "dimensions": 1024,
-  "exclude": ["**/fixtures/**"]
-}
-```
-
-Do not expose API keys in commands, output, configuration files, or commits.
-
-## Indexing
-
-Root and nested `.gitignore` files restrict indexing, including tracked files. Working-tree updates use current ignore files; historical or committed-only Git updates use ignore files from the selected commit. A normal refresh removes newly ignored files from the index. Explicit updates reject ignored paths.
-
-Indexing records parse, callable-extraction, file-read, and file-size failures in SQLite while retaining healthy callables. Commands warn on stderr when unresolved diagnostics remain. Inspect them with `slopdex index-errors --format summary` (or JSON by default); this reads saved errors without refreshing the index or calling providers. Records include paths, source locations, recoverable function names, messages, and available source text. `status` reports `indexingErrorCount` and `failedFileCount`. Failed files are retried during updates; fixes, deletions, and exclusions clear their diagnostics. `--ignore-errors` silences diagnostic warnings without discarding the records.
-
-If a CLI command cannot find its source index, Slopdex prints a notice to stderr and automatically creates and populates it from committed `HEAD`, then overlays working-tree changes. Missing cross-search target indexes are initialized from the target repository's `HEAD` and working tree as well.
-
-Index the current committed snapshot and working-tree overlay:
+### Find code by meaning
 
 ```bash
-slopdex update-git
+slopdex search "validate an authenticated session" --format summary --limit 10
+slopdex search "persist user data" -e 'save|persist' --format summary --limit 5
 ```
 
-`update-git` reconciles the committed snapshot and, when the target is the checked-out `HEAD`, indexes staged, unstaged, and untracked changes. Historical or other-branch targets remain exact committed snapshots. The Git checkpoint remains the committed base hash. After the mandatory automatic refresh, explicitly re-index selected working-tree files with:
+Describe behavior rather than guessing a symbol name. `-e` is a regex that restricts which symbols (functions) are searched.
 
-```bash
-slopdex update-files src/service.ts src/model.ts
-```
+### Search function purpose
 
-Remove deleted files from the index when using explicit updates:
+Code purpose-summary generation needs to be enabled once:
 
 ```bash
-slopdex delete-files src/removed.ts
-```
-
-Index another commit or recover after changing to a divergent branch:
-
-```bash
-slopdex update-git --target HEAD
-slopdex update-git --target HEAD --rebuild-on-divergence
-```
-
-Rebuild automatically when an existing index is incompatible with the current provider, model, dimensions, strategy, schema, or repository:
-
-```bash
-slopdex update-git --force-rebuild
-```
-
-This removes the incompatible index and prints a warning before rebuilding it.
-
-Skip the otherwise mandatory full working-tree refresh when Git is unavailable and a non-empty index already exists:
-
-```bash
-slopdex search "query" --no-reindex
+slopdex summaries enable # only needed once
 ```
 
-Check index metadata and its Git checkpoint:
+Then purpose-summaries can be searched:
 
 ```bash
-slopdex status
+slopdex search-summary "keep the repository index synchronized" --format summary --limit 10
 ```
 
-Git updates reconcile committed blobs first, then overlay working-tree contents. Explicit file updates do not advance the Git checkpoint.
-
-## Failure Handling
+Enabling needs `OPENAI_API_KEY` in the environment.
 
-- Preserve and report the exact failure from the requested command. Do not retry equivalent initialization commands.
-- Provider authentication and configuration failures are actionable as printed. Never display key values, and do not probe whether keys are set unless the error specifically indicates missing credentials and the user asks for diagnosis.
-- A bare system error such as `Invalid argument` is a Slopdex/runtime failure, not evidence that a different indexing command is needed. Stop retrying, report the command and error, and recommend diagnosing or updating Slopdex.
-- `slopdex --help` is the supported capability reference. There is no `slopdex --version` option; never invoke it.
-
-## Analysis Examples
-
-### Duplicate Analysis
+To select another model:
 
 ```bash
-slopdex cross-search \
-  --cross-file-only \
-  --min-lines 4 \
-  --threshold 0.9 \
-  --limit 5
+slopdex summaries enable --summary-model <model-id>
 ```
 
-```text
-Cluster 1 (3 functions, similarity 0.9124-0.9568)
-  src/auth/session.ts:18:1 :: validateSession
-  src/http/middleware.ts:42:1 :: authenticate
-  src/users/user-service.ts:27:3 :: UserService.authenticate
-```
-
-This result found three substantial authentication functions in three files with very high similarity. Review them for repeated validation or session-handling logic that could move into one shared implementation. The middleware and service locations may represent intentional architectural layers, so treat the result as evidence to inspect rather than proof that the functions should be merged. The range describes observed links in a connected component; transitive clustering means every function is not necessarily directly similar to every other function.
-
-### Cohesion Analysis
+### Find duplicate candidates
 
 ```bash
-slopdex cohesion --format summary --threshold 0.8 --neighbors 20 --limit 50
-```
-
-```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
-```
-
-There is no universal pass/fail cutoff for cohesion, but this example has several warning signs. More than a third of weighted semantic affinity crosses folder boundaries, and the mean distance of 1.84 is above the same-folder distance of one. The top pair is strongly related at 0.94 similarity yet four distance units apart, producing a relatively high gap of 0.6053; the reciprocal match strengthens that signal. A more cohesive result under the same settings would concentrate affinity in the same-file and same-folder percentages, have a lower mean distance, and contain few high-gap remote pairs. Inspect whether shared authentication behavior belongs in one module, while accounting for the possibility that session and middleware responsibilities are intentionally separated. Compare modules or repository history rather than treating one percentage as a fixed quality threshold.
-
-## Reading Analysis Output
-
-Interpret values only within the same embedding profile and similar command settings. Changing the model, threshold, neighbor count, source scope, or minimum line count changes the candidate graph and makes direct comparisons unreliable.
-
-### Duplicate Clusters
-
-For `Cluster 1 (3 functions, similarity 0.9124-0.9568)`:
-
-- `Cluster 1` is the display identifier. Clusters are ordered by function count and then name, not severity, so a lower number is not inherently worse.
-- `3 functions` counts unique callables connected by observed edges. Higher can indicate a larger duplicate family, but may also result from generic helpers or transitive links.
-- `similarity 0.9124-0.9568` is the weakest-to-strongest raw cosine similarity among observed edges. Higher means greater semantic resemblance according to the configured model. A high minimum means every observed link is strong; a wide range can identify a weaker bridge.
-- Callable lines use `path:line:column :: qualifiedFunctionName`. Location is contextual rather than scored; inspect architectural roles before consolidating code.
-
-### Cohesion Summary
-
-For `Cohesion: 184 functions analyzed, 37 semantic edges`:
-
-- `functions analyzed` is coverage after filters, not a quality value.
-- `semantic edges` counts unique top-neighbor pairs meeting the threshold before output limiting. Higher can reflect more overlapping responsibilities, but also increases with more neighbors or a lower threshold.
-
-For `same file 35.1%  same folder 29.7%  remote 35.2%  mean distance 1.84`:
-
-- Higher `same file` generally means stronger co-location, though very high values can indicate oversized files.
-- Higher `same folder` means related code is split into nearby modules but remains locally grouped.
-- Higher `remote` means more semantic affinity crosses folder boundaries and indicates weaker physical cohesion.
-- Lower `mean distance` generally means stronger physical cohesion. Zero is entirely within files, one reaches only other files in the same folder, and larger values indicate greater dispersion.
-
-### Cohesion Findings
-
-For `1. gap 0.6053  similarity 0.9400  distance 4  reciprocal`:
-
-- A lower rank number is a higher review priority.
-- Higher `gap` means stronger semantic affinity combined with greater physical separation; same-file pairs have zero gap.
-- Higher `similarity` means stronger model-assessed resemblance, but does not prove duplication and is not comparable across embedding profiles.
-- Higher `distance` means more file and directory-tree separation: zero is the same file and one is different files in the same folder.
-- `reciprocal` strengthens confidence because both functions rank each other as neighbors. Its absence means one-directional or unevaluated under a source filter.
-
-In JSON, higher `semanticWeight` means similarity lies farther above the threshold, and higher `separationWeight` means greater path distance. `sourceTestPair: true` flags an often-intentional source/test relationship. Higher file `externalAffinityRatio` means more observed related-function affinity lies outside that file's folder; lower means relationships are primarily internal or local.
-
-## Semantic Search
-
-Search indexed functions by intent:
-
-```bash
-slopdex search "validate an authenticated session" --limit 10
-```
-
-Use compact human-readable output and filter weak results:
-
-```bash
-slopdex search "validate an authenticated session" \
-  --format summary \
-  --threshold 0.8 \
-  --limit 10
-```
-
-`--threshold` is the minimum raw cosine similarity. Use a half-open range such as `--threshold 0.85-0.95` to include the left bound and exclude the right bound.
-
-## Duplicate Discovery
-
-Cross-search defaults to connected clusters. Treat each cluster as a source-review candidate rather than proof of duplication. Lower `--threshold` to broaden discovery, or lower `--min-lines` when short wrappers are relevant.
-
-Summary output can instead group matches beneath each source:
-
-```text
-src/users.ts :: Users.authenticate
-  0.9321  src/session.ts :: validateSession
-  0.8475  src/auth.ts :: authenticate
-```
-
-Interpret high similarity as a candidate requiring source review, not proof of duplication. Public facade methods, API wrappers, interface implementations, and test doubles often score highly while serving distinct roles.
-
-Cross-search excludes one-line callables by default. Raise `--min-lines` for more substantial duplicate candidates, or use `--min-lines 1` when short wrappers are relevant:
-
-```bash
-slopdex cross-search --min-lines 4 --threshold 0.9
-```
-
-Filter source symbols by qualified callable name while searching the whole eligible index:
-
-```bash
-slopdex cross-search -e '^(User|Session)\.' --source-path src --threshold 0.9
-```
-
-`-e` / `--regexp` uses a case-sensitive JavaScript regex. In cross-search and cohesion, it restricts sources only. Combine it with `--source-path`, `--changed-since`, `--uncommitted`, and other analysis options. When both Git filters are present, sources must have changed since the commit and belong to an uncommitted file. In `search` and `search-summary`, `-e` filters result names before applying `--limit`.
-
-To filter both source and matching candidates, use `--regex`:
-
-```bash
-slopdex cross-search --regex '^(User|Session)\.' --threshold 0.9
+slopdex cross-search --cross-file-only --min-lines 4 --threshold 0.9 --limit 5
 ```
 
-Use `--threshold <minimum>-<maximum>` for a half-open similarity range, such as `--threshold 0.85-0.95`. It includes the minimum, excludes the maximum, and is applied before `--limit`.
+The default output is connected clusters. This excludes same-file matches and short functions. For source-by-source matches, add `--format summary`.
 
-Review duplicate candidates iteratively from high confidence to lower-confidence bands instead of requesting one broad result set:
+Broaden discovery through adjacent score bands when needed:
 
 ```bash
-slopdex cross-search --cross-file-only --min-lines 4 --threshold 0.9 --limit 5
 slopdex cross-search --cross-file-only --min-lines 4 --threshold 0.85-0.9 --limit 5
 slopdex cross-search --cross-file-only --min-lines 4 --threshold 0.8-0.85 --limit 5
 ```
 
-Because range upper bounds are exclusive, adjacent passes do not repeat boundary candidates.
-
-Same-index search reports each unordered pair once by default. Include both `A -> B` and `B -> A` only when explicitly needed:
-
-```bash
-slopdex cross-search --include-symmetric-duplicates
-```
-
-Exclude candidates from the source function's file when looking for duplication across files:
-
-```bash
-slopdex cross-search --cross-file-only --format summary --threshold 0.9
-```
+Ranges include the lower bound and exclude the upper bound. Use `--min-lines 1` when one-line wrappers are relevant.
 
-Group overlapping pairs into connected components and list each function once:
+### Review changes or a module
 
 ```bash
-slopdex cross-search --format clusters --threshold 0.9
+slopdex cross-search --uncommitted --cross-file-only --min-lines 4 --threshold 0.9
+slopdex cross-search --changed-since origin/main --format summary --threshold 0.9
+slopdex cross-search --source-path src/services -e '^UserService\.' --format summary --threshold 0.9
 ```
 
-Restrict source functions to a file or recursive directory while still matching them against the whole codebase:
+These restrict sources while searching the full eligible index. The same filters work with `cohesion`. All supplied restrictions intersect:
 
 ```bash
-slopdex cross-search --source-path src/services --format summary --threshold 0.9
+slopdex cross-search --source-path src -e 'validate' \
+  --changed-since origin/main --uncommitted \
+  --cross-file-only --min-lines 4 --threshold 0.9
 ```
 
-`--source-path` restricts only source functions. It can be combined with `-e`, `--changed-since`, and `--uncommitted`; all supplied restrictions must match.
+Here a source must have changed since the commit and belong to an uncommitted file, within the selected path/name scope. `--regex` is an alias for `-e/--regexp`.
 
-Restrict source functions to additions, modifications, and moves relative to a commit, including current working-tree changes:
+### Review physical cohesion
 
 ```bash
-slopdex cross-search --changed-since origin/main --format summary --threshold 0.9
+slopdex cohesion --threshold 0.8 --neighbors 20 --limit 50 --format summary
+slopdex cohesion --source-path src/services --threshold 0.8 --format summary
 ```
 
-Restrict source functions to uncommitted files:
-
-```bash
-slopdex cross-search --uncommitted --format summary --threshold 0.9
-```
+Ranks related functions by semantic affinity and file/folder separation. add `--include-source` only when full callable bodies are needed.
 
-Search against another compatible index:
+### Compare repositories
 
 ```bash
 slopdex cross-search \
-  --target-root /path/to/other/repository \
-  --target-index /path/to/other/repository/.slopdex/index.sqlite \
-  --format summary \
-  --threshold 0.8
+  --target-root /path/to/other/repo \
+  --target-index /path/to/other/repo/.slopdex/index.sqlite \
+  --threshold 0.9 --format summary
 ```
 
-Cross-index searches require identical provider, model, dimensions, and embedding strategy profiles.
-Use `--target-config <path>` when the target repository does not use `.slopdex/config.json`.
+Both target options are required. Both indexes refresh and must have identical embedding profiles. The target refresh uses the source command's embedding provider and the target's file-selection/summary configuration. Use `--target-config <path>` for a custom target config.
 
-## Cohesion Analysis
-
-Use JSON when passing the report to another tool or an LLM:
+### Inspect or maintain the index
 
 ```bash
-slopdex cohesion --format json --threshold 0.8 --neighbors 20 --limit 50
+slopdex status
+slopdex index-errors --format summary
+slopdex update-git
+slopdex update-files src/service.ts src/model.ts
+slopdex delete-files src/removed.ts
+slopdex --version
+```
+
+- `status` refreshes, then reports coverage, checkpoint, profiles, and error counts; use when metadata is requested.
+- `index-errors` reads saved failures without refreshing or needing API credentials.
+- `update-git` explicitly refreshes HEAD and working-tree changes.
+- `update-files` reparses specified working-tree files after automatic refresh, even when their contents are unchanged.
+- `delete-files` removes index entries after automatic refresh, not source files. Eligible files can return on later refresh.
+- `--version` prints the built package version. `--help` describes available commands/options.
+
+## Command-line reference
+
+Usage: `slopdex <command> [arguments] [options]`. Quote queries and regexes. Boolean flags default to off. Use options only with their applicable commands.
+
+### General settings
+
+| Argument | Meaning / default |
+| --- | --- |
+| `--root <path>` | Repository root; current directory by default. |
+| `--config <path>` | Config; `<root>/.slopdex/config.json`. |
+| `--index <path>` | Index; `<root>/.slopdex/index.sqlite`. Overrides config `indexPath`. |
+| `--provider <openai\|jina>` | Embedding provider; `openai`. |
+| `--model <name>` | Embedding model; OpenAI `text-embedding-3-large`, Jina `jina-embeddings-v4`. |
+| `--dimensions <number>` | Positive dimensions supported by the model; OpenAI `3072`, Jina `1024`. |
+| `--summary-model <name>` | OpenAI summary model; initially `gpt-5.6-sol`, then the persisted selection. |
+| `--ignore-errors` | Silence saved-diagnostic warnings without deleting records. |
+| `-h`, `--help` | Usage; no refresh. |
+| `--version` | Package version; exits without refresh or saved-diagnostic warnings. |
+
+Explicit relative config/index paths resolve from the current directory. Source paths and explicit file arguments resolve within `--root`. Prefer absolute paths when operating across repositories. CLI settings override config.
+
+### Query and analysis options
+
+| Argument | Applies to / behavior |
+| --- | --- |
+| `--limit <number>` | Positive integer. `search`/`search-summary`: 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. |
+| `--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. |
+| `--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. |
+
+### Refresh and recovery options
+
+| Argument | Behavior |
+| --- | --- |
+| `--target <ref>` | `update-git` snapshot, default `HEAD`. Non-HEAD targets are committed-only; later commands normally return to HEAD. |
+| `--rebuild-on-divergence` | Permit reconciliation after non-descendant history changes, such as a rebase/branch switch. |
+| `--force-reindex` | Recreate an incompatible index. Compatible indexes still use normal refresh; this is not an unconditional reparse flag. |
+| `--no-reindex` | With Git, reconcile the committed snapshot but omit working-tree overlays. Without Git, reuse a non-empty index; missing/empty indexes still populate. Not an offline mode. |
+
+Use `--no-reindex` when the task calls for committed-only results or reuse of an existing non-Git index, rather than silently weakening freshness.
+
+## Interpret and report results
+
+### Output formats
+
+| Command | Default | Alternatives |
+| --- | --- | --- |
+| `search`, `search-summary` | `summary` | JSON array; purpose search includes generated summary 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, `summaries` | 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.
+
+### Similarity and clusters
+
+```text
+Cluster 1 (3 functions, similarity 0.9124-0.9568)
+  src/auth/session.ts:18:1 :: validateSession
+  src/http/middleware.ts:42:1 :: authenticate
+  src/users/user-service.ts:27:3 :: UserService.authenticate
 ```
 
-The report includes raw similarity, physical path distance, a combined cohesion-gap score, reciprocal-neighbor status, repository metrics, file-level external affinity, and connected groups for navigation. Reciprocity is `null` when the other endpoint was not searched because a source filter is active. Source code is omitted from JSON by default; add `--include-source` only when the consumer needs complete callable bodies.
+- Similarity is a model-dependent resemblance score, not a duplication probability.
+- The range describes observed links. Members can be connected transitively; not all pairs necessarily match.
+- Cluster numbers reflect ordering by member count and name, not severity.
+- Inspect listed locations and callers. Tests, facades, adapters, and intentional layers can resemble each other without being redundant.
 
-Treat findings as review candidates. Tests, facades, adapters, and intentionally layered implementations can be semantically related while correctly living in separate locations.
+When reporting candidates, identify paths/symbols, summarize the shared behavior you verified, and explain whether consolidation is appropriate. Do not infer equivalence from the score alone.
 
-## Output Formats
+### Purpose-aware scoring
 
-- `--format summary` is intended for human review and includes file and qualified function names.
-- `--format clusters` groups overlapping pairs and lists each function once with its source line.
-- The default `search` output is formatted JSON.
-- The default `cross-search` output is connected clusters. Use `--format json` for JSONL with one object per source function.
-- The default `cohesion` output is one compact JSON report. Use `--format summary` for ranked pairs.
-- Functions with no matches after threshold filtering are omitted from cross-search output.
+`search` uses code only; `search-summary` uses purpose summaries only. Cross-search and cohesion automatically use **50% code + 50% summary similarity** when summaries are enabled and complete. Cross-repository analysis needs completeness on both sides; otherwise all scores are code-only. Summary-generator models may differ even though embedding profiles must match.
 
-Prefer JSON or JSONL when another command will consume the results. Prefer summary output when presenting candidates to a user.
+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 summary-generator profiles, threshold, neighbor count, and source/candidate filters.
 
-## Common Options
+### Cohesion
 
 ```text
---root <path>                       Repository root
---config <path>                     Configuration file
---index <path>                      SQLite index path
---provider <openai|jina>            Embedding provider
---model <name>                      Embedding model
---dimensions <number>               Embedding dimensions
---force-rebuild                     Rebuild an incompatible existing index
---limit <number>                    Result limit
---neighbors <number>                Semantic neighbors per function for cohesion
---threshold <number|range>          Similarity threshold or half-open range
---format <json|summary|clusters>    Output format
---include-source                    Include callable source in cohesion JSON
---cross-file-only                   Exclude matches from the source file
---min-lines <number>               Minimum cross-search callable length
--e, --regexp <regex>               Match qualified symbols (analysis: sources only)
---regex <regex>                    Match both analysis source and candidate names
---target-config <path>             Target repository configuration file
+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
 ```
 
-Run `slopdex --help` for the complete current option list.
+- **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. Summary metrics use all qualifying edges; pairs/files are limited, and groups use reported pairs.