@ninjaxtools/slopdex 0.10.0 → 0.13.0

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

@@ -18,26 +18,38 @@ Describe behavior rather than guessing a symbol name. `-e` is a regex that restr
 
 ### Search function purpose
 
-Code purpose-summary generation needs to be enabled once:
+Code purpose-description generation needs to be enabled once:
 
 ```bash
-slopdex summaries enable # only needed once
+slopdex descriptions enable # only needed once
 ```
 
-Then purpose-summaries can be searched:
+Then purpose descriptions can be searched:
 
 ```bash
-slopdex search-summary "keep the repository index synchronized" --format summary --limit 10
+slopdex search-description "keep the repository index synchronized" --format summary --limit 10
 ```
 
-Enabling needs `OPENAI_API_KEY` in the environment.
+Enabling needs `OPENAI_API_KEY` by default. Select OpenCode Zen or Go with
+`--description-provider opencode` or `--description-provider opencode-go` and set `OPENCODE_API_KEY`.
 
 To select another model:
 
 ```bash
-slopdex summaries enable --summary-model <model-id>
+slopdex descriptions enable --description-model <model-id>
 ```
 
+List and persist a published OpenCode model without creating an index:
+
+```bash
+slopdex models opencode-go
+slopdex config model opencode-go/gpt-5.6-luna
+slopdex config descriptions enable
+```
+
+The next index-using command applies the configured description state. A bare model ID passed to
+`config model` resolves automatically only when it belongs to one of Zen or Go; qualify shared IDs.
+
 ### Find duplicate candidates
 
 ```bash
@@ -91,7 +103,7 @@ slopdex cross-search \
   --threshold 0.9 --format summary
 ```
 
-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.
+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/description configuration. Use `--target-config <path>` for a custom target config.
 
 ### Inspect or maintain the index
 
@@ -100,6 +112,8 @@ slopdex status
 slopdex index-errors --format summary
 slopdex update-git
 slopdex update-files src/service.ts src/model.ts
+slopdex reindex-files
+slopdex reindex-files --callables
 slopdex delete-files src/removed.ts
 slopdex --version
 ```
@@ -108,6 +122,7 @@ slopdex --version
 - `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.
+- `reindex-files` regenerates stale file descriptions and embeddings. Add `--callables` to also replace callable descriptions in those files.
 - `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.
 
@@ -125,7 +140,8 @@ Usage: `slopdex <command> [arguments] [options]`. Quote queries and regexes. Boo
 | `--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. |
+| `--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. |
 | `--ignore-errors` | Silence saved-diagnostic warnings without deleting records. |
 | `-h`, `--help` | Usage; no refresh. |
 | `--version` | Package version; exits without refresh or saved-diagnostic warnings. |
@@ -136,7 +152,7 @@ Explicit relative config/index paths resolve from the current directory. Source
 
 | 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`. |
+| `--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. |
@@ -160,6 +176,7 @@ Explicit relative config/index paths resolve from the current directory. Source
 | `--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. |
+| `--callables` | With `reindex-files`, continue after the file description and regenerate every callable description in each stale file. |
 
 Use `--no-reindex` when the task calls for committed-only results or reuse of an existing non-Git index, rather than silently weakening freshness.
 
@@ -169,11 +186,11 @@ Use `--no-reindex` when the task calls for committed-only results or reuse of an
 
 | Command | Default | Alternatives |
 | --- | --- | --- |
-| `search`, `search-summary` | `summary` | JSON array; purpose search includes generated summary text |
+| `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, `summaries` | JSON object | — |
+| `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.
 
@@ -195,9 +212,9 @@ When reporting candidates, identify paths/symbols, summarize the shared behavior
 
 ### Purpose-aware scoring
 
-`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.
+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.
 
-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.
+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.
 
 ### Cohesion
 
@@ -217,4 +234,4 @@ Cohesion: 184 functions analyzed, 37 semantic edges
 - **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.
+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.

package/README.md

@@ -27,13 +27,24 @@ slopdex search "keep the repository index synchronized" --format summary --limit
 To search generated descriptions of each function's role instead:
 
 ```bash
-slopdex summaries enable
-slopdex search-summary "keep the repository index synchronized" --format summary --limit 10
+slopdex descriptions enable
+slopdex search-description "keep the repository index synchronized" --format summary --limit 10
 ```
 
-This requires `OPENAI_API_KEY` even when Jina supplies embeddings, and adds generation costs. See [summaries and scoring](#summaries-and-scoring).
+The default description provider requires `OPENAI_API_KEY` even when Jina supplies embeddings. OpenCode Zen and Go use `OPENCODE_API_KEY`. Description generation can add provider costs; see [descriptions and scoring](#descriptions-and-scoring).
 
-`summaries disable` turns off summary generation while retaining cached data.
+`descriptions disable` turns off description generation while retaining cached data.
+
+To choose from OpenCode's current published models and persist description settings without creating an index:
+
+```bash
+slopdex models opencode-go
+slopdex config model opencode-go/gpt-5.6-luna
+slopdex config descriptions enable
+```
+
+The next index-using command creates or refreshes the index and applies the configured description state.
+You can also pass the selection separately as `slopdex config model --description-provider opencode-go --description-model gpt-5.6-luna`.
 
 ### Find duplicate-code candidates
 
@@ -70,7 +81,7 @@ slopdex cross-search \
   --threshold 0.9 --format summary
 ```
 
-Both indexes refresh automatically and must use identical embedding profiles. The target is refreshed with the source command's embedding provider; target configuration supplies file-selection and summary settings. Use `--target-config` for a non-default target config.
+Both indexes refresh automatically and must use identical embedding profiles. The target is refreshed with the source command's embedding provider; target configuration supplies file-selection and description settings. Use `--target-config` for a non-default target config.
 
 ### Inspect index health
 
@@ -88,15 +99,19 @@ Usage: `slopdex <command> [arguments] [options]`.
 
 | Command | Purpose | Output |
 | --- | --- | --- |
+| `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 |
 | `search <query>` | Search function code by meaning. Quote multiword queries. | Summary; optional JSON array |
-| `summaries <enable\|disable>` | Enable or disable automatic purpose summaries. Re-enabling with unchanged inputs reuses cached summaries. | JSON statistics |
-| `search-summary <query>` | Search purpose summaries after enabling them. | Summary including summary text; 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 |
 | `update-files <path...>` | After automatic refresh, explicitly reparse selected working-tree files. Paths are repository-relative or absolute within the root. | JSON update statistics |
+| `reindex-files [--callables]` | Regenerate descriptions for files changed since their stored file description. By default stops after each file description; `--callables` also regenerates its callable descriptions. | JSON description statistics |
 | `delete-files <path...>` | After automatic refresh, remove paths from the index; source files are not deleted. A later refresh can restore eligible files. | JSON update statistics |
 
 Manual maintenance examples:
@@ -104,6 +119,8 @@ Manual maintenance examples:
 ```bash
 slopdex update-git
 slopdex update-files src/service.ts src/model.ts
+slopdex reindex-files
+slopdex reindex-files --callables
 slopdex delete-files src/removed.ts
 slopdex update-git --target HEAD --rebuild-on-divergence
 slopdex update-git --force-reindex
@@ -119,7 +136,8 @@ slopdex update-git --force-reindex
 | `--provider <openai\|jina>` | Embedding provider; `openai` by default. |
 | `--model <name>` | Embedding model; `text-embedding-3-large` for OpenAI, `jina-embeddings-v4` for Jina. |
 | `--dimensions <number>` | Positive embedding dimension count; OpenAI `3072`, Jina `1024`. Must be supported by the model. |
-| `--summary-model <name>` | OpenAI summary model; `gpt-5.6-sol` initially, then the persisted model unless overridden. |
+| `--description-provider <openai\|opencode\|opencode-go>` | Description provider; OpenAI by default. OpenCode values use Zen or Go with `OPENCODE_API_KEY`. |
+| `--description-model <name>` | Description model; `gpt-5.6-sol` for OpenAI/Zen and `gpt-5.6-luna` for Go, then the persisted model unless overridden. Published OpenCode models use their documented protocol. |
 | `--ignore-errors` | Silence warnings about saved indexing errors; records remain available. |
 | `-h`, `--help` | Show CLI usage without refreshing. |
 | `--version` | Print the package version and exit. |
@@ -200,19 +218,25 @@ Cohesion: 184 functions analyzed, 37 semantic edges
 | `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. Summary metrics cover all qualifying edges; reported pairs/files are limited, and groups are built from reported pairs.
+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.
 
-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`, `summary`, `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; cohesion returns one JSON object containing `repository`, `parameters`, `metrics`, `pairs`, `files`, and `groups`. Results go to stdout; notices and warnings go to stderr.
 
 ## System behavior
 
-### Summaries and scoring
+### Descriptions and scoring
+
+Descriptions are optional and disabled initially. `descriptions enable` persists the selected provider and model and keeps callable descriptions current on later updates. Use `slopdex descriptions enable --description-provider opencode-go` for OpenCode Go, or combine `--description-provider` and `--description-model` to change both. `slopdex descriptions disable` stops automatic updates and description-based searching/scoring while retaining cached descriptions. `status` exposes callable/file description counts, stale file-description count, enabled state, and profile.
+
+Descriptions are generated in source order through one conversation per file. Instructions and complete file source form a stable prefix; Slopdex asks for the overall file description first, then each callable request and answer extends that conversation. This allows supported providers to reuse their prompt cache instead of receiving a separate duplicated file context for every callable.
+
+Ordinary updates preserve an existing file description even when its source changes, while still refreshing callable descriptions. `slopdex reindex-files` explicitly regenerates stale file descriptions and their embeddings; add `--callables` to continue through and replace every callable description in those files.
 
-Summaries are optional and disabled initially. `summaries enable` persists the selected summary model and keeps summaries current on later updates, including file-context and path changes. Use `slopdex summaries enable --summary-model <model-id>` to change it, or `slopdex summaries disable` to stop automatic updates and summary-based searching/scoring while retaining cached summaries. `status` exposes `summariesEnabled`, `summaryCount`, and `summaryProfile`.
+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.
 
-`search` always searches code; `search-summary` always searches purpose summaries. When all callables have enabled summaries, cross-search and cohesion automatically use **50% code similarity + 50% summary similarity**. Cross-repository analysis needs complete summaries on both sides; otherwise the entire analysis uses code-only scores. Thresholds and neighbor limits apply to the selected score.
+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.
 
-Text output labels combined scores. JSON exposes `codeSimilarity`, `summarySimilarity`, and scoring mode/weights (`scoring` for cross-search, `parameters` for cohesion). Compare runs only with matching scoring mode, weights, embedding and summary-generator profiles, threshold, neighbor count, and source/candidate filters.
+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.
 
 ### Exclusions
 
@@ -226,17 +250,18 @@ 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. For provider/authentication failures, fix the reported configuration. 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 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).
 
 ## Configuration
 
-Optional file: `<root>/.slopdex/config.json`. Example using Jina (requires `JINA_API_KEY`):
+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):
 
 ```json
 {
   "provider": "jina",
   "model": "jina-embeddings-v4",
   "dimensions": 1024,
+  "descriptionProvider": "opencode-go",
   "exclude": ["**/fixtures/**"]
 }
 ```
@@ -244,14 +269,16 @@ Optional file: `<root>/.slopdex/config.json`. Example using Jina (requires `JINA
 | Property | Purpose / default |
 | --- | --- |
 | `provider`, `model`, `dimensions` | Embedding settings; defaults are listed in the CLI table. |
-| `summaryModel` | Summary model; initially `gpt-5.6-sol`. |
+| `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. |
 | `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`). Changing the embedding profile requires rebuilding with `--force-reindex`.
+Keep keys in the environment (`OPENAI_API_KEY`, `JINA_API_KEY`, `OPENCODE_API_KEY`). Changing the embedding profile requires rebuilding with `--force-reindex`.
 
 ## Development