@ninjaxtools/slopdex 0.11.0 → 0.13.0

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

@@ -30,7 +30,8 @@ Then purpose descriptions can be searched:
 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:
 
@@ -38,6 +39,17 @@ To select another model:
 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
@@ -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`. |
-| `--description-model <name>` | OpenAI description 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. |
@@ -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.
 
@@ -195,7 +212,7 @@ When reporting candidates, identify paths/symbols, summarize the shared behavior
 
 ### Purpose-aware scoring
 
-`search` uses code only; `search-description` uses purpose descriptions only. Cross-search and cohesion automatically use **50% code + 50% description similarity** when descriptions are enabled and complete. Cross-repository analysis needs completeness on both sides; otherwise all scores are code-only. Description-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 description-generator profiles, threshold, neighbor count, and source/candidate filters.
 

package/README.md

@@ -31,10 +31,21 @@ 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 [descriptions and scoring](#descriptions-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).
 
 `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
 
 ```bash
@@ -88,6 +99,9 @@ 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 |
 | `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 |
@@ -97,6 +111,7 @@ Usage: `slopdex <command> [arguments] [options]`.
 | `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. |
-| `--description-model <name>` | OpenAI description 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. |
@@ -208,13 +226,17 @@ For automation, pass `--format json`: query searches and diagnostics return JSON
 
 ### Descriptions and scoring
 
-Descriptions are optional and disabled initially. `descriptions enable` persists the selected description model and keeps descriptions current on later updates, including file-context and path changes. Use `slopdex descriptions enable --description-model <model-id>` to change it, or `slopdex descriptions disable` to stop automatic updates and description-based searching/scoring while retaining cached descriptions. `status` exposes `descriptionsEnabled`, `descriptionCount`, and `descriptionProfile`.
+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.
 
 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-description` always searches purpose descriptions. When all callables have enabled descriptions, cross-search and cohesion automatically use **50% code similarity + 50% description similarity**. Cross-repository analysis needs complete descriptions 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`, `descriptionSimilarity`, 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 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
 
@@ -232,13 +254,14 @@ Use the recovery flag named in the error: `--rebuild-on-divergence` for Git hist
 
 ## 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/**"]
 }
 ```
@@ -246,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. |
-| `descriptionModel` | Description 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