opencode-rag-plugin 2.13.1 → 2.13.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -59,9 +59,16 @@ function proxyFields(section) {
59
59
  string([section, "proxy", "url"], "Proxy URL", {
60
60
  advanced: true,
61
61
  placeholder: "http://proxy:8080",
62
+ description: "HTTP(S) proxy for outbound provider requests.",
63
+ }),
64
+ string([section, "proxy", "username"], "Proxy username", {
65
+ advanced: true,
66
+ description: "Username for proxy authentication.",
67
+ }),
68
+ string([section, "proxy", "password"], "Proxy password", {
69
+ advanced: true,
70
+ description: "Password for proxy authentication; stored machine-globally.",
62
71
  }),
63
- string([section, "proxy", "username"], "Proxy username", { advanced: true }),
64
- string([section, "proxy", "password"], "Proxy password", { advanced: true }),
65
72
  string([section, "proxy", "noProxy"], "Proxy bypass list", {
66
73
  advanced: true,
67
74
  description: "Comma-separated hosts that skip the proxy.",
@@ -84,25 +91,45 @@ export const SETTINGS_SECTIONS = [
84
91
  "mistral",
85
92
  "together",
86
93
  "fireworks",
87
- ], { impact: "reindex" }),
88
- string(["embedding", "model"], "Model", { impact: "reindex" }),
89
- string(["embedding", "baseUrl"], "Base URL", { impact: "reindex" }),
90
- string(["embedding", "apiKey"], "API key", { impact: "reindex" }),
94
+ ], {
95
+ impact: "reindex",
96
+ description: "Service that turns text into vectors. Ollama runs locally; the others are hosted APIs. Changing it requires a full re-index.",
97
+ }),
98
+ string(["embedding", "model"], "Model", {
99
+ impact: "reindex",
100
+ description: "Embedding model at the provider (e.g. nomic-embed-text for Ollama). It defines the vector dimension, so changing it requires a re-index.",
101
+ }),
102
+ string(["embedding", "baseUrl"], "Base URL", {
103
+ impact: "reindex",
104
+ description: "Endpoint of the embedding server, e.g. http://127.0.0.1:11434 for a local Ollama. Empty uses the provider default.",
105
+ }),
106
+ string(["embedding", "apiKey"], "API key", {
107
+ impact: "reindex",
108
+ description: "Credential for hosted providers. Stored in the machine-global config only, never in a repository file.",
109
+ }),
91
110
  number(["embedding", "vectorDimension"], "Vector dimension", {
92
111
  advanced: true,
93
112
  minimum: 1,
94
113
  impact: "reindex",
95
- description: "Probed automatically; set only when the probe cannot reach the provider.",
114
+ description: "Probed automatically; set only when the probe cannot reach the provider. Must match the model, otherwise the index cannot be used.",
115
+ }),
116
+ number(["embedding", "timeoutMs"], "Request timeout (ms)", {
117
+ minimum: 1,
118
+ description: "Maximum wait for one embedding request. Raise it for slow local models or large batches.",
96
119
  }),
97
- number(["embedding", "timeoutMs"], "Request timeout (ms)", { minimum: 1 }),
98
120
  string(["embedding", "documentPrefix"], "Document prefix", {
99
121
  advanced: true,
100
122
  impact: "reindex",
123
+ description: "Text prepended to every chunk before embedding (some models need e.g. a passage prefix). Requires a re-index.",
124
+ }),
125
+ string(["embedding", "queryPrefix"], "Query prefix", {
126
+ advanced: true,
127
+ description: "Text prepended to search queries before embedding (e.g. a query prefix). Must match the model convention.",
101
128
  }),
102
- string(["embedding", "queryPrefix"], "Query prefix", { advanced: true }),
103
129
  string(["embedding", "keepAlive"], "Ollama keep-alive", {
104
130
  advanced: true,
105
131
  placeholder: "30m",
132
+ description: "How long Ollama keeps the model in memory between requests (e.g. 30m, -1 = forever).",
106
133
  }),
107
134
  ...proxyFields("embedding"),
108
135
  ],
@@ -112,34 +139,83 @@ export const SETTINGS_SECTIONS = [
112
139
  label: "Descriptions",
113
140
  description: "LLM-generated summaries embedded alongside code chunks.",
114
141
  fields: [
115
- boolean(["description", "enabled"], "Generate descriptions", { impact: "reindex" }),
142
+ boolean(["description", "enabled"], "Generate descriptions", {
143
+ impact: "reindex",
144
+ description: "Write a one-sentence summary for every chunk and embed it alongside the code. Improves semantic search quality and requires a re-index.",
145
+ }),
116
146
  enumField(["description", "provider"], "Provider", ["ollama", "openai", "anthropic", "google"], {
117
147
  impact: "reindex",
148
+ description: "Model service that writes the summaries: a local Ollama instance or a hosted API.",
149
+ }),
150
+ string(["description", "model"], "Model", {
151
+ impact: "reindex",
152
+ description: "Model used for the summaries. Smaller models are cheaper and usually sufficient for one-sentence descriptions.",
153
+ }),
154
+ string(["description", "baseUrl"], "Base URL", {
155
+ impact: "reindex",
156
+ description: "Endpoint of the description model, e.g. a local Ollama or an OpenAI-compatible server. Empty uses the provider default.",
157
+ }),
158
+ string(["description", "apiKey"], "API key", {
159
+ impact: "reindex",
160
+ description: "Credential for hosted providers. Stored in the machine-global config only.",
161
+ }),
162
+ number(["description", "timeoutMs"], "Request timeout (ms)", {
163
+ minimum: 1,
164
+ description: "Maximum wait for one description request. Raise it for slow or remote models.",
165
+ }),
166
+ string(["description", "keepAlive"], "Ollama keep-alive", {
167
+ advanced: true,
168
+ description: "How long Ollama keeps the description model loaded between requests (e.g. 30m).",
118
169
  }),
119
- string(["description", "model"], "Model", { impact: "reindex" }),
120
- string(["description", "baseUrl"], "Base URL", { impact: "reindex" }),
121
- string(["description", "apiKey"], "API key", { impact: "reindex" }),
122
- number(["description", "timeoutMs"], "Request timeout (ms)", { minimum: 1 }),
123
- string(["description", "keepAlive"], "Ollama keep-alive", { advanced: true }),
124
170
  string(["description", "systemPrompt"], "System prompt", {
125
171
  advanced: true,
126
172
  multiline: true,
127
173
  impact: "reindex",
174
+ description: "Instruction sent to the model for every chunk. Edit it to change summary style, language, or length.",
175
+ }),
176
+ boolean(["description", "think"], "Allow reasoning tokens", {
177
+ advanced: true,
178
+ description: "Let reasoning models think before answering. Slower and usually unnecessary for short summaries.",
179
+ }),
180
+ number(["description", "numCtx"], "Context window", {
181
+ advanced: true,
182
+ minimum: 1,
183
+ description: "Context window of the description model in tokens. Larger values allow bigger chunks per request.",
128
184
  }),
129
- boolean(["description", "think"], "Allow reasoning tokens", { advanced: true }),
130
- number(["description", "numCtx"], "Context window", { advanced: true, minimum: 1 }),
131
185
  number(["description", "maxContentChars"], "Max content chars", {
132
186
  advanced: true,
133
187
  minimum: 1,
188
+ description: "Truncate chunk content to this many characters before sending it to the model; keeps requests small.",
189
+ }),
190
+ boolean(["description", "batchEnabled"], "Batch requests", {
191
+ advanced: true,
192
+ impact: "reindex",
193
+ description: "Bundle several chunks into one request (OpenAI-style batch endpoints). Fewer calls, but one failure affects the whole batch.",
194
+ }),
195
+ number(["description", "batchMaxChunks"], "Batch size", {
196
+ advanced: true,
197
+ minimum: 1,
198
+ description: "Maximum number of chunks per batch request.",
199
+ }),
200
+ number(["description", "batchTimeoutMs"], "Batch timeout (ms)", {
201
+ advanced: true,
202
+ minimum: 1,
203
+ description: "Maximum wait for one batch request before it counts as failed.",
204
+ }),
205
+ number(["description", "batchConcurrency"], "Batch concurrency", {
206
+ advanced: true,
207
+ minimum: 1,
208
+ description: "Number of batch requests sent in parallel.",
209
+ }),
210
+ number(["description", "retryMax"], "Max retries", {
211
+ advanced: true,
212
+ minimum: 0,
213
+ description: "How often a failed description request is retried before the chunk is left without a summary.",
134
214
  }),
135
- boolean(["description", "batchEnabled"], "Batch requests", { advanced: true, impact: "reindex" }),
136
- number(["description", "batchMaxChunks"], "Batch size", { advanced: true, minimum: 1 }),
137
- number(["description", "batchTimeoutMs"], "Batch timeout (ms)", { advanced: true, minimum: 1 }),
138
- number(["description", "batchConcurrency"], "Batch concurrency", { advanced: true, minimum: 1 }),
139
- number(["description", "retryMax"], "Max retries", { advanced: true, minimum: 0 }),
140
215
  number(["description", "retryBaseDelayMs"], "Retry base delay (ms)", {
141
216
  advanced: true,
142
217
  minimum: 0,
218
+ description: "Initial delay between retries; doubles after each attempt.",
143
219
  }),
144
220
  ...proxyFields("description"),
145
221
  ],
@@ -149,7 +225,10 @@ export const SETTINGS_SECTIONS = [
149
225
  label: "Image Descriptions",
150
226
  description: "Vision model used to describe images during indexing.",
151
227
  fields: [
152
- boolean(["imageDescription", "enabled"], "Describe images", { impact: "reindex" }),
228
+ boolean(["imageDescription", "enabled"], "Describe images", {
229
+ impact: "reindex",
230
+ description: "Describe images during indexing so screenshots, diagrams, and photos become searchable text. Requires a vision model and a re-index.",
231
+ }),
153
232
  enumField(["imageDescription", "provider"], "Provider", [
154
233
  "ollama",
155
234
  "openai",
@@ -157,18 +236,48 @@ export const SETTINGS_SECTIONS = [
157
236
  "google",
158
237
  "opencode",
159
238
  "opencode-go",
160
- ], { impact: "reindex" }),
161
- string(["imageDescription", "model"], "Model", { impact: "reindex" }),
162
- string(["imageDescription", "baseUrl"], "Base URL", { impact: "reindex" }),
163
- string(["imageDescription", "apiKey"], "API key", { impact: "reindex" }),
164
- number(["imageDescription", "timeoutMs"], "Request timeout (ms)", { minimum: 1 }),
165
- string(["imageDescription", "prompt"], "Prompt", { multiline: true, impact: "reindex" }),
166
- boolean(["imageDescription", "think"], "Allow reasoning tokens", { advanced: true }),
167
- number(["imageDescription", "numCtx"], "Context window", { advanced: true, minimum: 1 }),
168
- string(["imageDescription", "keepAlive"], "Ollama keep-alive", { advanced: true }),
239
+ ], {
240
+ impact: "reindex",
241
+ description: "Vision model service: a local Ollama instance or a hosted API, including OpenCode Zen.",
242
+ }),
243
+ string(["imageDescription", "model"], "Model", {
244
+ impact: "reindex",
245
+ description: "Vision model used to describe images, e.g. a Qwen-VL or MiniCPM-V variant.",
246
+ }),
247
+ string(["imageDescription", "baseUrl"], "Base URL", {
248
+ impact: "reindex",
249
+ description: "Endpoint of the vision model. Empty uses the provider default.",
250
+ }),
251
+ string(["imageDescription", "apiKey"], "API key", {
252
+ impact: "reindex",
253
+ description: "Credential for hosted vision providers. Stored in the machine-global config only.",
254
+ }),
255
+ number(["imageDescription", "timeoutMs"], "Request timeout (ms)", {
256
+ minimum: 1,
257
+ description: "Maximum wait for one image description. Raise it for large images or slow models.",
258
+ }),
259
+ string(["imageDescription", "prompt"], "Prompt", {
260
+ multiline: true,
261
+ impact: "reindex",
262
+ description: "Instruction used for every image. Shape it to capture what matters, e.g. UI elements, diagram labels, or visible text.",
263
+ }),
264
+ boolean(["imageDescription", "think"], "Allow reasoning tokens", {
265
+ advanced: true,
266
+ description: "Let reasoning models think before answering. Slower and rarely needed for short captions.",
267
+ }),
268
+ number(["imageDescription", "numCtx"], "Context window", {
269
+ advanced: true,
270
+ minimum: 1,
271
+ description: "Context window of the vision model in tokens.",
272
+ }),
273
+ string(["imageDescription", "keepAlive"], "Ollama keep-alive", {
274
+ advanced: true,
275
+ description: "How long Ollama keeps the vision model in memory between requests.",
276
+ }),
169
277
  number(["imageDescription", "resizeMaxDimension"], "Max image dimension", {
170
278
  advanced: true,
171
279
  minimum: 1,
280
+ description: "Downscale images so the longest side fits this pixel size before sending. Reduces cost and latency.",
172
281
  }),
173
282
  ...proxyFields("imageDescription"),
174
283
  enumField(["imageDescription", "onDemand", "provider"], "On-demand provider", [
@@ -178,48 +287,96 @@ export const SETTINGS_SECTIONS = [
178
287
  "google",
179
288
  "opencode",
180
289
  "opencode-go",
181
- ], { advanced: true }),
182
- string(["imageDescription", "onDemand", "model"], "On-demand model", { advanced: true }),
183
- string(["imageDescription", "onDemand", "baseUrl"], "On-demand base URL", { advanced: true }),
184
- string(["imageDescription", "onDemand", "apiKey"], "On-demand API key", { advanced: true }),
290
+ ], {
291
+ advanced: true,
292
+ description: "Separate provider for query-time image questions. Falls back to the indexing vision model when unset.",
293
+ }),
294
+ string(["imageDescription", "onDemand", "model"], "On-demand model", {
295
+ advanced: true,
296
+ description: "Vision model for on-demand descriptions; may differ from the indexing model.",
297
+ }),
298
+ string(["imageDescription", "onDemand", "baseUrl"], "On-demand base URL", {
299
+ advanced: true,
300
+ description: "Endpoint for the on-demand vision model. Empty uses the provider default.",
301
+ }),
302
+ string(["imageDescription", "onDemand", "apiKey"], "On-demand API key", {
303
+ advanced: true,
304
+ description: "Credential for the on-demand vision provider; stored machine-globally.",
305
+ }),
185
306
  number(["imageDescription", "onDemand", "timeoutMs"], "On-demand timeout (ms)", {
186
307
  advanced: true,
187
308
  minimum: 1,
309
+ description: "Maximum wait for one on-demand image description.",
310
+ }),
311
+ string(["imageDescription", "onDemand", "prompt"], "On-demand prompt", {
312
+ advanced: true,
313
+ description: "Prompt used for on-demand descriptions. It may ask a different question than the indexing prompt.",
188
314
  }),
189
- string(["imageDescription", "onDemand", "prompt"], "On-demand prompt", { advanced: true }),
190
315
  boolean(["imageDescription", "onDemand", "think"], "On-demand reasoning tokens", {
191
316
  advanced: true,
317
+ description: "Allow reasoning tokens for on-demand descriptions.",
192
318
  }),
193
319
  number(["imageDescription", "onDemand", "numCtx"], "On-demand context window", {
194
320
  advanced: true,
195
321
  minimum: 1,
322
+ description: "Context window in tokens for on-demand descriptions.",
196
323
  }),
197
324
  string(["imageDescription", "onDemand", "keepAlive"], "On-demand keep-alive", {
198
325
  advanced: true,
326
+ description: "How long Ollama keeps the on-demand model loaded.",
199
327
  }),
200
328
  number(["imageDescription", "onDemand", "resizeMaxDimension"], "On-demand max dimension", {
201
329
  advanced: true,
202
330
  minimum: 1,
331
+ description: "Downscale images for on-demand descriptions so the longest side fits this pixel size.",
203
332
  }),
204
333
  ],
205
334
  },
206
335
  {
207
336
  id: "decision",
208
337
  label: "Decision Model",
209
- description: "Local tev1 model behind the make_decision tool.",
338
+ description: "Local decision model behind the make_decision tool (Ollama /v1/systemone or a compatible server such as llama-swap).",
210
339
  fields: [
211
- boolean(["decision", "enabled"], "Enable make_decision"),
212
- enumField(["decision", "provider"], "Provider", ["ollama"]),
213
- string(["decision", "model"], "Model"),
214
- string(["decision", "baseUrl"], "Base URL"),
215
- number(["decision", "timeoutMs"], "Request timeout (ms)", { minimum: 1 }),
216
- string(["decision", "keepAlive"], "Ollama keep-alive", { advanced: true }),
217
- boolean(["decision", "routeBeforeAsking"], "Route choices before asking"),
218
- number(["decision", "maxStateChars"], "Max state chars", { advanced: true, minimum: 1 }),
219
- number(["decision", "retryMax"], "Max retries", { advanced: true, minimum: 0 }),
340
+ boolean(["decision", "enabled"], "Enable make_decision", {
341
+ description: "Expose the make_decision tool that answers classification, routing, and scoring questions with a small local model.",
342
+ }),
343
+ enumField(["decision", "provider"], "Provider", ["ollama"], {
344
+ description: "Decision backend. Only ollama is implemented; it also works with any server exposing POST /v1/systemone, e.g. a llama-swap router.",
345
+ }),
346
+ string(["decision", "model"], "Model", {
347
+ description: "Model name passed to the endpoint (tev1 for Ollama, or e.g. Clef-Flash on llama-swap).",
348
+ }),
349
+ string(["decision", "baseUrl"], "Base URL", {
350
+ description: "Decision server URL. Root, /api, or /v1 suffixes are accepted; the request is sent to <root>/v1/systemone.",
351
+ }),
352
+ string(["decision", "apiKey"], "API key", {
353
+ description: "Bearer key sent as the Authorization header. Required by key-protected servers such as llama-swap.",
354
+ }),
355
+ number(["decision", "timeoutMs"], "Request timeout (ms)", {
356
+ minimum: 1,
357
+ description: "Maximum wait for one decision call. The first call can be slow because the server may load the model.",
358
+ }),
359
+ string(["decision", "keepAlive"], "Ollama keep-alive", {
360
+ advanced: true,
361
+ description: "How long the server keeps the decision model in memory between calls (e.g. 30m).",
362
+ }),
363
+ boolean(["decision", "routeBeforeAsking"], "Route choices before asking", {
364
+ description: "Instruct the agent to resolve option choices through make_decision before asking you; you are asked only when the answer is uncertain or preference-based.",
365
+ }),
366
+ number(["decision", "maxStateChars"], "Max state chars", {
367
+ advanced: true,
368
+ minimum: 1,
369
+ description: "Reject longer state texts instead of truncating them. The model context is small (~2k tokens).",
370
+ }),
371
+ number(["decision", "retryMax"], "Max retries", {
372
+ advanced: true,
373
+ minimum: 0,
374
+ description: "How often retryable failures (rate limit, server error, network) are retried.",
375
+ }),
220
376
  number(["decision", "retryBaseDelayMs"], "Retry base delay (ms)", {
221
377
  advanced: true,
222
378
  minimum: 0,
379
+ description: "Initial delay between retries; doubles after each attempt.",
223
380
  }),
224
381
  ...proxyFields("decision"),
225
382
  ],
@@ -229,23 +386,48 @@ export const SETTINGS_SECTIONS = [
229
386
  label: "Reranking",
230
387
  description: "Optional cross-encoder rerank stage after hybrid fusion.",
231
388
  fields: [
232
- boolean(["reranking", "enabled"], "Enable reranking"),
233
- enumField(["reranking", "provider"], "Provider", ["llama-server"]),
234
- string(["reranking", "model"], "Model"),
235
- string(["reranking", "baseUrl"], "Base URL"),
236
- string(["reranking", "apiKey"], "API key"),
237
- number(["reranking", "candidates"], "Candidates", { minimum: 1 }),
238
- number(["reranking", "maxDocChars"], "Max document chars", { advanced: true, minimum: 1 }),
389
+ boolean(["reranking", "enabled"], "Enable reranking", {
390
+ description: "Rescore the fused candidate list with a cross-encoder before returning results. Better ordering, slightly slower queries.",
391
+ }),
392
+ enumField(["reranking", "provider"], "Provider", ["llama-server"], {
393
+ description: "Rerank backend. llama-server works with llama.cpp and llama-swap.",
394
+ }),
395
+ string(["reranking", "model"], "Model", {
396
+ description: "Cross-encoder model name, e.g. a Qwen3-Reranker variant.",
397
+ }),
398
+ string(["reranking", "baseUrl"], "Base URL", {
399
+ description: "Rerank server endpoint (OpenAI-compatible /v1 API).",
400
+ }),
401
+ string(["reranking", "apiKey"], "API key", {
402
+ description: "Bearer key for key-protected rerank servers such as llama-swap.",
403
+ }),
404
+ number(["reranking", "candidates"], "Candidates", {
405
+ minimum: 1,
406
+ description: "How many fused candidates are scored. More candidates improve recall but add latency.",
407
+ }),
408
+ number(["reranking", "maxDocChars"], "Max document chars", {
409
+ advanced: true,
410
+ minimum: 1,
411
+ description: "Truncate each candidate document before scoring; keeps requests small.",
412
+ }),
239
413
  number(["reranking", "minScore"], "Rerank min score", {
240
414
  advanced: true,
241
415
  minimum: 0,
242
416
  maximum: 1,
243
417
  step: 0.01,
418
+ description: "Drop reranked results below this score. 0 keeps everything.",
419
+ }),
420
+ number(["reranking", "timeoutMs"], "Timeout (ms)", {
421
+ minimum: 1,
422
+ description: "Maximum wait for one rerank request.",
423
+ }),
424
+ string(["reranking", "queryTemplate"], "Query template", {
425
+ advanced: true,
426
+ description: "Optional template applied to the query; use {query} as the placeholder.",
244
427
  }),
245
- number(["reranking", "timeoutMs"], "Timeout (ms)", { minimum: 1 }),
246
- string(["reranking", "queryTemplate"], "Query template", { advanced: true }),
247
428
  enumField(["reranking", "docField"], "Document field", ["content", "content+description"], {
248
429
  advanced: true,
430
+ description: "Which text is scored as the document: the code content alone or content plus its generated description.",
249
431
  }),
250
432
  ...proxyFields("reranking"),
251
433
  ],
@@ -255,24 +437,48 @@ export const SETTINGS_SECTIONS = [
255
437
  label: "Shell Guard",
256
438
  description: "Decision-model vetting of shell commands before they run.",
257
439
  fields: [
258
- boolean(["shellGuard", "enabled"], "Enable Shell Guard"),
440
+ boolean(["shellGuard", "enabled"], "Enable Shell Guard", {
441
+ description: "Classify every shell command for destructive or malicious intent before it runs and escalate suspicious ones to a confirmation prompt.",
442
+ }),
259
443
  number(["shellGuard", "threshold"], "Flag threshold", {
260
444
  minimum: 0,
261
445
  maximum: 1,
262
446
  step: 0.01,
447
+ description: "Probability (0-1) at which a command is flagged. Lower values mean more prompts.",
448
+ }),
449
+ enumField(["shellGuard", "onError"], "On classifier error", ["allow", "ask"], {
450
+ description: "What happens when the classifier fails or times out: allow runs the command (fail-open), ask requires confirmation.",
451
+ }),
452
+ number(["shellGuard", "timeoutMs"], "Classification timeout (ms)", {
453
+ minimum: 1,
454
+ description: "Maximum wait for the classification. Keep it short because every command waits for the verdict.",
455
+ }),
456
+ string(["shellGuard", "provider"], "Provider override", {
457
+ advanced: true,
458
+ description: "Override the decision backend for shell vetting (default: the decision section).",
459
+ }),
460
+ string(["shellGuard", "baseUrl"], "Base URL override", {
461
+ advanced: true,
462
+ description: "Override the decision endpoint for shell vetting.",
463
+ }),
464
+ string(["shellGuard", "model"], "Model override", {
465
+ advanced: true,
466
+ description: "Override the decision model for shell vetting, e.g. Clef-Flash.",
467
+ }),
468
+ string(["shellGuard", "apiKey"], "API key override", {
469
+ advanced: true,
470
+ scope: "global",
471
+ description: "Bearer key for a key-protected decision endpoint such as llama-swap. Stored machine-globally.",
263
472
  }),
264
- enumField(["shellGuard", "onError"], "On classifier error", ["allow", "ask"]),
265
- number(["shellGuard", "timeoutMs"], "Classification timeout (ms)", { minimum: 1 }),
266
- string(["shellGuard", "provider"], "Provider override", { advanced: true }),
267
- string(["shellGuard", "baseUrl"], "Base URL override", { advanced: true }),
268
- string(["shellGuard", "model"], "Model override", { advanced: true }),
269
473
  number(["shellGuard", "cacheTtlMs"], "Verdict cache TTL (ms)", {
270
474
  advanced: true,
271
475
  minimum: 0,
476
+ description: "Reuse identical verdicts for this long. 0 disables the cache.",
272
477
  }),
273
478
  number(["shellGuard", "maxCacheEntries"], "Max cached verdicts", {
274
479
  advanced: true,
275
480
  minimum: 1,
481
+ description: "Upper bound of cached verdicts before the oldest are dropped.",
276
482
  }),
277
483
  ],
278
484
  },
@@ -281,46 +487,73 @@ export const SETTINGS_SECTIONS = [
281
487
  label: "Indexing",
282
488
  description: "What gets scanned and how indexing is tuned.",
283
489
  fields: [
284
- strings(["indexing", "includeExtensions"], "Included extensions", { impact: "reindex" }),
490
+ strings(["indexing", "includeExtensions"], "Included extensions", {
491
+ impact: "reindex",
492
+ description: "File extensions that are indexed. Empty uses the built-in default list.",
493
+ }),
285
494
  strings(["indexing", "includeDirs"], "Included folders", {
286
495
  impact: "reindex",
287
- description: "Empty = whole workspace. Paths are anchored to the workspace root.",
496
+ description: "Only index these folders. Empty = whole workspace. Paths are anchored to the workspace root.",
497
+ }),
498
+ strings(["indexing", "excludeDirs"], "Excluded folders", {
499
+ impact: "reindex",
500
+ description: "Folders that are never scanned, e.g. node_modules or .git.",
501
+ }),
502
+ strings(["indexing", "excludeFiles"], "Excluded files", {
503
+ impact: "reindex",
504
+ description: "Individual files or glob patterns to skip.",
288
505
  }),
289
- strings(["indexing", "excludeDirs"], "Excluded folders", { impact: "reindex" }),
290
- strings(["indexing", "excludeFiles"], "Excluded files", { impact: "reindex" }),
291
506
  number(["indexing", "chunkOverlap"], "Chunk overlap (lines)", {
292
507
  minimum: 0,
293
508
  impact: "reindex",
509
+ description: "Lines of overlap between adjacent chunks; helps when a definition spans a chunk boundary.",
294
510
  }),
295
511
  number(["indexing", "maxChunkSize"], "Max chunk size (lines)", {
296
512
  minimum: 0,
297
513
  impact: "reindex",
298
- description: "0 = no limit (whole AST node).",
514
+ description: "0 = no limit (whole AST node). Smaller values produce more, smaller chunks.",
299
515
  }),
300
516
  number(["indexing", "minFileSizeBytes"], "Minimum file size (bytes)", {
301
517
  minimum: 0,
302
518
  impact: "reindex",
519
+ description: "Skip files smaller than this. Filters empty or trivial files; 0 = no minimum.",
520
+ }),
521
+ number(["indexing", "concurrency"], "File concurrency", {
522
+ minimum: 1,
523
+ description: "Files parsed in parallel. Higher values speed up indexing at the cost of CPU and memory.",
524
+ }),
525
+ number(["indexing", "embedBatchSize"], "Embedding batch size", {
526
+ minimum: 1,
527
+ description: "Chunks per embedding request sent to the provider.",
528
+ }),
529
+ number(["indexing", "embedConcurrency"], "Embedding concurrency", {
530
+ minimum: 1,
531
+ description: "Embedding requests in flight at the same time.",
303
532
  }),
304
- number(["indexing", "concurrency"], "File concurrency", { minimum: 1 }),
305
- number(["indexing", "embedBatchSize"], "Embedding batch size", { minimum: 1 }),
306
- number(["indexing", "embedConcurrency"], "Embedding concurrency", { minimum: 1 }),
307
533
  number(["indexing", "ollamaMaxBatchSize"], "Ollama max batch size", {
308
534
  advanced: true,
309
535
  minimum: 1,
536
+ description: "Upper bound for one Ollama embedding request. Ollama handles smaller batches more reliably.",
310
537
  }),
311
538
  number(["indexing", "descriptionConcurrency"], "Description concurrency", {
312
539
  advanced: true,
313
540
  minimum: 1,
541
+ description: "Description requests in flight at the same time.",
542
+ }),
543
+ boolean(["indexing", "embedDescriptions"], "Embed descriptions", {
544
+ impact: "reindex",
545
+ description: "Embed generated summaries as vectors instead of only storing them as text. Requires a re-index.",
314
546
  }),
315
- boolean(["indexing", "embedDescriptions"], "Embed descriptions", { impact: "reindex" }),
316
547
  number(["indexing", "maxSvgSizeBytes"], "Max SVG size (bytes)", {
317
548
  advanced: true,
318
549
  minimum: 0,
319
550
  impact: "reindex",
551
+ description: "SVGs above this size are skipped to avoid huge diagram payloads; 0 = no limit.",
320
552
  }),
321
553
  number(["indexing", "optimizeIntervalWindows"], "Optimize every N windows", {
322
554
  advanced: true,
323
555
  minimum: 0,
556
+ description: "Run a store optimization after every N indexing windows during a pass. 8 is the default; the store is optimized once more at the end.",
324
557
  }),
325
558
  ],
326
559
  },
@@ -332,12 +565,18 @@ export const SETTINGS_SECTIONS = [
332
565
  stringMap(["chunking", "parsers"], "Extension → parser", {
333
566
  advanced: true,
334
567
  impact: "reindex",
568
+ description: "Override the parser per file extension, e.g. {.ssl: ssl}. Useful when a language needs a different splitter.",
335
569
  }),
336
570
  stringArrayMap(["chunking", "nodeTypes"], "Language → node types", {
337
571
  advanced: true,
338
572
  impact: "reindex",
573
+ description: "Restrict which syntax-tree node types become chunks per language, e.g. only function declarations.",
574
+ }),
575
+ json(["chunkers"], "Custom chunker modules", {
576
+ advanced: true,
577
+ impact: "restart",
578
+ description: "Pluggable custom chunker modules (JSON). They are loaded at startup, so a change requires a restart.",
339
579
  }),
340
- json(["chunkers"], "Custom chunker modules", { advanced: true, impact: "restart" }),
341
580
  ],
342
581
  },
343
582
  {
@@ -345,53 +584,72 @@ export const SETTINGS_SECTIONS = [
345
584
  label: "Retrieval",
346
585
  description: "Query-time ranking and context shaping.",
347
586
  fields: [
348
- number(["retrieval", "topK"], "Top K", { minimum: 1, maximum: 1000 }),
587
+ number(["retrieval", "topK"], "Top K", {
588
+ minimum: 1,
589
+ maximum: 1000,
590
+ description: "Chunks returned per search. Higher values give more context but consume more tokens.",
591
+ }),
349
592
  number(["retrieval", "minScore"], "Minimum score", {
350
593
  minimum: 0,
351
594
  maximum: 1,
352
595
  step: 0.01,
596
+ description: "Drop results scoring below this threshold. How the value is applied depends on the min-score mode.",
597
+ }),
598
+ enumField(["retrieval", "minScoreMode"], "Min-score mode", ["fused", "normalized"], {
599
+ description: "How the threshold is interpreted: fused compares the combined score as-is; normalized rescales it so the same value behaves the same across keyword weights.",
600
+ }),
601
+ boolean(["retrieval", "hybridSearch", "enabled"], "Hybrid search", {
602
+ description: "Combine vector similarity with keyword matching so exact identifiers and rare terms are found reliably.",
353
603
  }),
354
- enumField(["retrieval", "minScoreMode"], "Min-score mode", ["fused", "normalized"]),
355
- boolean(["retrieval", "hybridSearch", "enabled"], "Hybrid search"),
356
604
  number(["retrieval", "hybridSearch", "keywordWeight"], "Keyword weight", {
357
605
  minimum: 0,
358
606
  maximum: 1,
359
607
  step: 0.01,
608
+ description: "Weight of keyword matches in the fused score (0-1). 0 disables the keyword contribution.",
360
609
  }),
361
610
  number(["retrieval", "hybridSearch", "symbolKeywordWeight"], "Symbol keyword weight", {
362
611
  minimum: 0,
363
612
  maximum: 1,
364
613
  step: 0.01,
614
+ description: "Keyword weight for symbol-style queries (a bare identifier). Defaults to the general keyword weight; raise it to favor exact symbol hits.",
365
615
  }),
366
616
  number(["retrieval", "hybridSearch", "docKeywordDemotion"], "Document demotion", {
367
617
  advanced: true,
368
618
  minimum: 0,
369
619
  maximum: 1,
370
620
  step: 0.01,
621
+ description: "Multiplier (0-1) on keyword scores of documentation chunks so prose does not outrank code.",
371
622
  }),
372
623
  number(["retrieval", "hybridSearch", "testKeywordDemotion"], "Test demotion", {
373
624
  advanced: true,
374
625
  minimum: 0,
375
626
  maximum: 1,
376
627
  step: 0.01,
628
+ description: "Multiplier (0-1) on keyword scores of test chunks so tests do not outrank the implementation.",
629
+ }),
630
+ boolean(["retrieval", "contextOptimization", "enabled"], "Context optimization", {
631
+ description: "Post-process retrieved chunks: merge adjacent pieces and drop near-duplicates before returning them.",
377
632
  }),
378
- boolean(["retrieval", "contextOptimization", "enabled"], "Context optimization"),
379
633
  number(["retrieval", "contextOptimization", "maxPerFile"], "Max chunks per file", {
380
634
  advanced: true,
381
635
  minimum: 0,
636
+ description: "Maximum chunks taken from a single file. 0 = unlimited.",
382
637
  }),
383
638
  boolean(["retrieval", "contextOptimization", "mergeAdjacent"], "Merge adjacent chunks", {
384
639
  advanced: true,
640
+ description: "Merge chunks that touch or nearly touch into one continuous block.",
385
641
  }),
386
642
  number(["retrieval", "contextOptimization", "adjacentGapThreshold"], "Adjacent gap", {
387
643
  advanced: true,
388
644
  minimum: 0,
645
+ description: "Maximum line gap at which two chunks are still merged.",
389
646
  }),
390
647
  number(["retrieval", "contextOptimization", "similarityThreshold"], "Similarity threshold", {
391
648
  advanced: true,
392
649
  minimum: 0,
393
650
  maximum: 1,
394
651
  step: 0.01,
652
+ description: "Drop a chunk when it is at least this similar (0-1) to a higher-ranked chunk.",
395
653
  }),
396
654
  ],
397
655
  },
@@ -400,79 +658,98 @@ export const SETTINGS_SECTIONS = [
400
658
  label: "Vector Store",
401
659
  description: "Where the index lives. Most changes need a restart.",
402
660
  fields: [
403
- string(["vectorStore", "path"], "Store path", { impact: "restart" }),
661
+ string(["vectorStore", "path"], "Store path", {
662
+ impact: "restart",
663
+ description: "Directory for the local index (LanceDB) or the disposable local cache. Relative paths resolve against the workspace.",
664
+ }),
404
665
  enumField(["vectorStore", "provider"], "Backend", ["lancedb", "memory", "clickhouse"], {
405
666
  impact: "restart",
667
+ description: "Storage backend: lancedb (local default), memory (tests only, not persistent), clickhouse (shared server).",
406
668
  }),
407
669
  string(["vectorStore", "clickhouse", "url"], "ClickHouse URL", {
408
670
  advanced: true,
409
671
  impact: "restart",
672
+ description: "ClickHouse HTTP endpoint, e.g. http://pat06:8123.",
410
673
  }),
411
674
  string(["vectorStore", "clickhouse", "database"], "ClickHouse database", {
412
675
  advanced: true,
413
676
  impact: "restart",
677
+ description: "Database that holds the index tables.",
414
678
  }),
415
679
  string(["vectorStore", "clickhouse", "username"], "ClickHouse user", {
416
680
  advanced: true,
417
681
  impact: "restart",
682
+ description: "Login user for ClickHouse.",
418
683
  }),
419
684
  string(["vectorStore", "clickhouse", "password"], "ClickHouse password", {
420
685
  advanced: true,
421
686
  impact: "restart",
687
+ description: "Login password. Prefer the env var option so no secret lands in a committed file.",
422
688
  }),
423
689
  string(["vectorStore", "clickhouse", "passwordEnv"], "Password env var", {
424
690
  advanced: true,
425
691
  impact: "restart",
426
- description: "Preferred over a password in a committed file.",
692
+ description: "Name of the environment variable that holds the password; preferred over a password in a committed file.",
427
693
  }),
428
694
  string(["vectorStore", "clickhouse", "namespace"], "Namespace", {
429
695
  advanced: true,
430
696
  impact: "restart",
697
+ description: "Logical index name inside the database; isolates workspaces that share one server.",
431
698
  }),
432
699
  number(["vectorStore", "clickhouse", "requestTimeoutMs"], "Request timeout (ms)", {
433
700
  advanced: true,
434
701
  minimum: 1,
435
702
  impact: "restart",
703
+ description: "Maximum wait for one ClickHouse request.",
436
704
  }),
437
705
  number(["vectorStore", "clickhouse", "maxOpenConnections"], "Max connections", {
438
706
  advanced: true,
439
707
  minimum: 1,
440
708
  impact: "restart",
709
+ description: "Connection pool size for ClickHouse.",
441
710
  }),
442
711
  boolean(["vectorStore", "clickhouse", "compression"], "Compression", {
443
712
  advanced: true,
444
713
  impact: "restart",
714
+ description: "Compress HTTP traffic to ClickHouse. Lower bandwidth, slightly more CPU.",
445
715
  }),
446
716
  boolean(["vectorStore", "clickhouse", "state", "syncDescCache"], "Sync description cache", {
447
717
  advanced: true,
448
718
  impact: "restart",
719
+ description: "Mirror the description cache to ClickHouse so other machines reuse generated summaries.",
449
720
  }),
450
721
  boolean(["vectorStore", "clickhouse", "lease", "enabled"], "Single-writer lease", {
451
722
  advanced: true,
452
723
  impact: "restart",
724
+ description: "Allow only one process to write the shared index at a time, preventing concurrent-write corruption.",
453
725
  }),
454
726
  number(["vectorStore", "clickhouse", "lease", "ttlSeconds"], "Lease TTL (s)", {
455
727
  advanced: true,
456
728
  minimum: 10,
457
729
  impact: "restart",
730
+ description: "How long a writer lease stays valid without renewal.",
458
731
  }),
459
732
  number(["vectorStore", "clickhouse", "diskFreeFloorBytes"], "Disk free floor (bytes)", {
460
733
  advanced: true,
461
734
  minimum: 0,
462
735
  impact: "restart",
736
+ description: "Refuse a full rebuild when the server has less free disk than this. Default is 5 GiB.",
463
737
  }),
464
738
  enumField(["vectorStore", "clickhouse", "ann"], "ANN index", ["off", "hnsw"], {
465
739
  advanced: true,
466
740
  impact: "restart",
741
+ description: "Approximate nearest-neighbour index: off uses exact search, hnsw is faster on large indexes.",
467
742
  }),
468
743
  number(["vectorStore", "clickhouse", "annFetchMultiplier"], "ANN fetch multiplier", {
469
744
  advanced: true,
470
745
  minimum: 1,
471
746
  impact: "restart",
747
+ description: "How many extra candidates the ANN search fetches before rescoring. Higher = better recall, slower.",
472
748
  }),
473
749
  boolean(["vectorStore", "clickhouse", "annWithRescoring"], "ANN rescoring", {
474
750
  advanced: true,
475
751
  impact: "restart",
752
+ description: "Rescore ANN candidates with exact vector distance for better accuracy.",
476
753
  }),
477
754
  ],
478
755
  },
@@ -481,48 +758,73 @@ export const SETTINGS_SECTIONS = [
481
758
  label: "OpenCode Integration",
482
759
  description: "Tools, prompt injection, and background indexing.",
483
760
  fields: [
484
- boolean(["openCode", "enabled"], "Plugin enabled"),
485
- number(["openCode", "maxContextChunks"], "Max context chunks", { minimum: 1 }),
486
- boolean(["openCode", "readOverride"], "Override read tool"),
761
+ boolean(["openCode", "enabled"], "Plugin enabled", {
762
+ description: "Activate the plugin in OpenCode sessions: RAG tools, quirk memory, and prompt injection.",
763
+ }),
764
+ number(["openCode", "maxContextChunks"], "Max context chunks", {
765
+ minimum: 1,
766
+ description: "Maximum number of chunks included in one tool response.",
767
+ }),
768
+ boolean(["openCode", "readOverride"], "Override read tool", {
769
+ description: "Replace the built-in read tool with a RAG-aware version that appends related snippets.",
770
+ }),
487
771
  number(["openCode", "maxReadOutputChars"], "Max read output chars", {
488
772
  advanced: true,
489
773
  minimum: 1,
774
+ description: "Character budget for the overridden read tool output.",
490
775
  }),
491
776
  enumField(["openCode", "readNoResultsBehavior"], "Read with no results", [
492
777
  "hint",
493
778
  "empty",
494
779
  "error",
495
- ], { advanced: true }),
780
+ ], {
781
+ advanced: true,
782
+ description: "What the read tool reports when nothing matches: a hint with suggestions, an empty result, or an error.",
783
+ }),
496
784
  number(["openCode", "readRelatedFilesMax"], "Related files shown", {
497
785
  advanced: true,
498
786
  minimum: 0,
787
+ description: "How many related files the read tool may list alongside a result.",
788
+ }),
789
+ boolean(["openCode", "injectSystemPrompt"], "Inject RAG guidance", {
790
+ description: "Add a short block describing the RAG tools and their intended workflow to the system prompt.",
791
+ }),
792
+ boolean(["openCode", "exploreAgentTools"], "Give explore agent RAG tools", {
793
+ description: "Grant the built-in explore agent access to the RAG tools so it can search semantically.",
794
+ }),
795
+ boolean(["openCode", "autoIndex", "enabled"], "Auto-index file changes", {
796
+ description: "Re-index changed files automatically in the background while you work.",
499
797
  }),
500
- boolean(["openCode", "injectSystemPrompt"], "Inject RAG guidance"),
501
- boolean(["openCode", "exploreAgentTools"], "Give explore agent RAG tools"),
502
- boolean(["openCode", "autoIndex", "enabled"], "Auto-index file changes"),
503
798
  number(["openCode", "autoIndex", "debounceMs"], "Auto-index debounce (ms)", {
504
799
  minimum: 0,
800
+ description: "Wait this long after the last change before re-indexing, to batch rapid edits.",
505
801
  }),
506
802
  number(["openCode", "autoIndex", "intervalMs"], "Git poll interval (ms)", {
507
803
  advanced: true,
508
804
  minimum: 0,
805
+ description: "How often the git watcher checks for changes.",
509
806
  }),
510
807
  enumField(["openCode", "autoIndex", "watcher"], "Watcher backend", ["chokidar", "git"], {
511
808
  advanced: true,
809
+ description: "Change detector: chokidar watches the filesystem, git polls git status (more robust on network drives).",
512
810
  }),
513
811
  boolean(["openCode", "shell", "backgroundGuidance"], "Background guidance", {
514
812
  advanced: true,
813
+ description: "Tell the agent to run long commands in the background instead of blocking.",
515
814
  }),
516
815
  number(["openCode", "shell", "longRunningThresholdMs"], "Long command threshold (ms)", {
517
816
  advanced: true,
518
817
  minimum: 0,
818
+ description: "Commands expected to run longer than this count as long-running.",
519
819
  }),
520
820
  number(["openCode", "shell", "foregroundTimeoutMs"], "Foreground timeout (ms)", {
521
821
  advanced: true,
522
822
  minimum: 1,
823
+ description: "Default timeout for shell commands running in the foreground.",
523
824
  }),
524
825
  boolean(["openCode", "shell", "captureLongRunningQuirk"], "Capture long-command quirks", {
525
826
  advanced: true,
827
+ description: "Record a quirk when a foreground command exceeds the long-running threshold, so sessions learn from it.",
526
828
  }),
527
829
  ],
528
830
  },
@@ -531,104 +833,159 @@ export const SETTINGS_SECTIONS = [
531
833
  label: "Quirk Memory",
532
834
  description: "Experiential memory captured across sessions.",
533
835
  fields: [
534
- boolean(["memory", "enabled"], "Memory enabled"),
535
- boolean(["memory", "autoInject"], "Auto-inject quirks"),
836
+ boolean(["memory", "enabled"], "Memory enabled", {
837
+ description: "Persist quirks (gotchas, preferences, decisions, environment facts) across sessions.",
838
+ }),
839
+ boolean(["memory", "autoInject"], "Auto-inject quirks", {
840
+ description: "Automatically inject matching quirks into prompts when the request touches known knowledge.",
841
+ }),
536
842
  number(["memory", "minConfidence"], "Min confidence", {
537
843
  minimum: 0,
538
844
  maximum: 1,
539
845
  step: 0.01,
846
+ description: "Minimum confidence a quirk needs to be recalled at all. Lower-confidence memories fade out.",
540
847
  }),
541
848
  number(["memory", "recallMinScore"], "Manual recall min score", {
542
849
  minimum: 0,
543
850
  maximum: 1,
544
851
  step: 0.01,
852
+ description: "Minimum similarity for explicit recall_quirks calls.",
545
853
  }),
546
854
  number(["memory", "autoInjectMinScore"], "Auto-inject min score", {
547
855
  minimum: 0,
548
856
  maximum: 1,
549
857
  step: 0.01,
858
+ description: "Minimum similarity for automatic injection into a turn.",
859
+ }),
860
+ number(["memory", "autoInjectTopK"], "Auto-inject top K", {
861
+ minimum: 0,
862
+ description: "Maximum number of quirks injected automatically per turn.",
550
863
  }),
551
- number(["memory", "autoInjectTopK"], "Auto-inject top K", { minimum: 0 }),
552
864
  number(["memory", "autoInjectMinTokenOverlap"], "Auto-inject token overlap", {
553
865
  advanced: true,
554
866
  minimum: 0,
867
+ description: "Minimum shared meaningful words between request and quirk. Blocks vector-only false positives.",
555
868
  }),
556
869
  number(["memory", "autoInjectLatencyBudgetMs"], "Auto-inject latency budget (ms)", {
557
870
  advanced: true,
558
871
  minimum: 0,
872
+ description: "Skip auto-injection when recall takes longer than this. 0 = no budget.",
873
+ }),
874
+ boolean(["memory", "passiveCapture"], "Passive capture", {
875
+ advanced: true,
876
+ description: "Extract quirks from each completed agent turn automatically.",
877
+ }),
878
+ boolean(["memory", "promptEnforcement"], "Mandatory capture prompt", {
879
+ advanced: true,
880
+ description: "Upgrade the system-prompt nudge into a mandatory capture instruction.",
881
+ }),
882
+ boolean(["memory", "sessionEndExtraction"], "Session-end extraction", {
883
+ advanced: true,
884
+ description: "Summarize the full session transcript into quirks when the session ends.",
559
885
  }),
560
- boolean(["memory", "passiveCapture"], "Passive capture", { advanced: true }),
561
- boolean(["memory", "promptEnforcement"], "Mandatory capture prompt", { advanced: true }),
562
- boolean(["memory", "sessionEndExtraction"], "Session-end extraction", { advanced: true }),
563
886
  number(["memory", "autoCaptureMaxPerTurn"], "Max captures per turn", {
564
887
  advanced: true,
565
888
  minimum: 0,
889
+ description: "Cap on quirks captured from a single turn.",
566
890
  }),
567
891
  number(["memory", "autoCaptureDedupThreshold"], "Capture dedup threshold", {
568
892
  advanced: true,
569
893
  minimum: 0,
570
894
  maximum: 1,
571
895
  step: 0.01,
896
+ description: "Similarity above which a new capture counts as a duplicate and is skipped.",
897
+ }),
898
+ boolean(["memory", "injectOnToolError"], "Inject after tool errors", {
899
+ advanced: true,
900
+ description: "After a failed tool call, recall matching quirks and inject them into the next request.",
572
901
  }),
573
- boolean(["memory", "injectOnToolError"], "Inject after tool errors", { advanced: true }),
574
902
  number(["memory", "toolErrorMinScore"], "Tool-error min score", {
575
903
  advanced: true,
576
904
  minimum: 0,
577
905
  maximum: 1,
578
906
  step: 0.01,
907
+ description: "Minimum similarity for tool-error quirk injection.",
908
+ }),
909
+ number(["memory", "toolErrorTopK"], "Tool-error top K", {
910
+ advanced: true,
911
+ minimum: 0,
912
+ description: "Maximum number of tool-error quirks injected at once.",
579
913
  }),
580
- number(["memory", "toolErrorTopK"], "Tool-error top K", { advanced: true, minimum: 0 }),
581
914
  number(["memory", "toolErrorMinTokenOverlap"], "Tool-error token overlap", {
582
915
  advanced: true,
583
916
  minimum: 0,
917
+ description: "Minimum shared words for a tool-error quirk to qualify for injection.",
584
918
  }),
585
919
  number(["memory", "toolErrorCooldownMs"], "Tool-error cooldown (ms)", {
586
920
  advanced: true,
587
921
  minimum: 0,
922
+ description: "Do not re-attempt the same error signature within this window.",
588
923
  }),
589
924
  number(["memory", "toolErrorMaxPerSession"], "Tool-error injections / session", {
590
925
  advanced: true,
591
926
  minimum: 0,
927
+ description: "Cap on tool-error quirk injections per session.",
592
928
  }),
593
929
  number(["memory", "toolErrorLatencyBudgetMs"], "Tool-error latency budget (ms)", {
594
930
  advanced: true,
595
931
  minimum: 0,
932
+ description: "Skip tool-error recall when it takes longer than this.",
596
933
  }),
597
934
  boolean(["memory", "autoCreateOnToolError"], "Create quirks from tool errors", {
598
935
  advanced: true,
936
+ description: "Create a new quirk when a tool error has no matching memory.",
599
937
  }),
600
938
  number(["memory", "toolErrorCreateMaxPerSession"], "Creations / session", {
601
939
  advanced: true,
602
940
  minimum: 0,
941
+ description: "Cap on quirks created from tool errors per session.",
603
942
  }),
604
943
  number(["memory", "toolErrorCreateCooldownMs"], "Creation cooldown (ms)", {
605
944
  advanced: true,
606
945
  minimum: 0,
946
+ description: "Minimum time between creations of the same error signature.",
607
947
  }),
608
948
  number(["memory", "toolErrorCreateMinScore"], "Creation min score", {
609
949
  advanced: true,
610
950
  minimum: 0,
611
951
  maximum: 1,
612
952
  step: 0.01,
953
+ description: "Highest similarity at which an error still counts as having no matching quirk.",
613
954
  }),
614
955
  number(["memory", "toolErrorCreateLatencyBudgetMs"], "Creation latency budget (ms)", {
615
956
  advanced: true,
616
957
  minimum: 0,
958
+ description: "Skip creation when the lookup takes longer than this.",
959
+ }),
960
+ boolean(["memory", "toolErrorInjectCreated"], "Inject created quirk", {
961
+ advanced: true,
962
+ description: "Inject a freshly created quirk into the next request so the lesson is visible immediately.",
963
+ }),
964
+ boolean(["memory", "toolErrorProactiveInject"], "Proactive tool gotchas", {
965
+ advanced: true,
966
+ description: "Warn about known tool gotchas before the tool is called.",
617
967
  }),
618
- boolean(["memory", "toolErrorInjectCreated"], "Inject created quirk", { advanced: true }),
619
- boolean(["memory", "toolErrorProactiveInject"], "Proactive tool gotchas", { advanced: true }),
620
968
  number(["memory", "toolErrorProactiveMaxItems"], "Max proactive gotchas", {
621
969
  advanced: true,
622
970
  minimum: 0,
971
+ description: "Maximum proactive gotchas injected per prompt.",
972
+ }),
973
+ boolean(["memory", "interceptAllErrors"], "Intercept all failures", {
974
+ advanced: true,
975
+ description: "Also treat failures reported inside successful tool output (non-zero exit code, stack traces) as errors.",
623
976
  }),
624
- boolean(["memory", "interceptAllErrors"], "Intercept all failures", { advanced: true }),
625
977
  boolean(["memory", "autoCreateOnInterceptedError"], "Create from intercepted failures", {
626
978
  advanced: true,
979
+ description: "Create quirks from those intercepted failures too, not just from remembered ones.",
980
+ }),
981
+ boolean(["memory", "decay", "enabled"], "Confidence decay", {
982
+ advanced: true,
983
+ description: "Slowly reduce quirk confidence over time so stale knowledge fades away.",
627
984
  }),
628
- boolean(["memory", "decay", "enabled"], "Confidence decay", { advanced: true }),
629
985
  number(["memory", "decay", "halfLifeDays"], "Decay half-life (days)", {
630
986
  advanced: true,
631
987
  minimum: 1,
988
+ description: "Days after which a quirk's confidence halves.",
632
989
  }),
633
990
  ],
634
991
  },
@@ -637,12 +994,20 @@ export const SETTINGS_SECTIONS = [
637
994
  label: "Documentation Mode",
638
995
  description: "Agent mode that adds doc comments to undocumented code.",
639
996
  fields: [
640
- boolean(["documentationMode", "enabled"], "Documentation mode enabled"),
641
- boolean(["documentationMode", "autoStart"], "Start automatically"),
642
- number(["documentationMode", "batchSize"], "Files per batch", { minimum: 1 }),
997
+ boolean(["documentationMode", "enabled"], "Documentation mode enabled", {
998
+ description: "Turn the agent into a documentation maintainer that adds doc comments to undocumented code.",
999
+ }),
1000
+ boolean(["documentationMode", "autoStart"], "Start automatically", {
1001
+ description: "Start documentation mode automatically in new sessions.",
1002
+ }),
1003
+ number(["documentationMode", "batchSize"], "Files per batch", {
1004
+ minimum: 1,
1005
+ description: "Files processed per documentation pass.",
1006
+ }),
643
1007
  string(["documentationMode", "systemPrompt"], "System prompt", {
644
1008
  advanced: true,
645
1009
  multiline: true,
1010
+ description: "Instruction that defines the documentation behaviour. Edit it to change style and scope.",
646
1011
  }),
647
1012
  ],
648
1013
  },
@@ -651,10 +1016,13 @@ export const SETTINGS_SECTIONS = [
651
1016
  label: "Wiki Mode",
652
1017
  description: "Agent instruction that maintains a knowledge wiki.",
653
1018
  fields: [
654
- boolean(["wikiMode", "enabled"], "Wiki mode enabled"),
1019
+ boolean(["wikiMode", "enabled"], "Wiki mode enabled", {
1020
+ description: "Turn the agent into a wiki maintainer that keeps a structured knowledge wiki under .opencode/wiki.",
1021
+ }),
655
1022
  string(["wikiMode", "systemPrompt"], "System prompt", {
656
1023
  advanced: true,
657
1024
  multiline: true,
1025
+ description: "Instruction that defines the wiki layout and operations. Edit it to change the workflow.",
658
1026
  }),
659
1027
  ],
660
1028
  },
@@ -662,28 +1030,45 @@ export const SETTINGS_SECTIONS = [
662
1030
  id: "mcp",
663
1031
  label: "MCP Server",
664
1032
  description: "Standalone Model Context Protocol server.",
665
- fields: [boolean(["mcp", "enabled"], "Auto-start MCP server", { impact: "restart" })],
1033
+ fields: [
1034
+ boolean(["mcp", "enabled"], "Auto-start MCP server", {
1035
+ impact: "restart",
1036
+ description: "Run the standalone MCP server at startup so other MCP clients can use the RAG tools.",
1037
+ }),
1038
+ ],
666
1039
  },
667
1040
  {
668
1041
  id: "setup",
669
1042
  label: "Workspace Setup",
670
1043
  description: "Scaffolding behaviour for repositories without a config.",
671
- fields: [boolean(["setup", "autoScaffold"], "Auto-scaffold new workspaces", { advanced: true })],
1044
+ fields: [
1045
+ boolean(["setup", "autoScaffold"], "Auto-scaffold new workspaces", {
1046
+ advanced: true,
1047
+ description: "Create config, skills, and AGENTS.md snippets automatically in workspaces that have none.",
1048
+ }),
1049
+ ],
672
1050
  },
673
1051
  {
674
1052
  id: "autoUpdate",
675
1053
  label: "Auto Update",
676
1054
  description: "Update checks and optional automatic installs.",
677
1055
  fields: [
678
- boolean(["autoUpdate", "enabled"], "Check for updates"),
679
- boolean(["autoUpdate", "autoInstall"], "Install updates automatically", { advanced: true }),
1056
+ boolean(["autoUpdate", "enabled"], "Check for updates", {
1057
+ description: "Check npm for newer plugin versions.",
1058
+ }),
1059
+ boolean(["autoUpdate", "autoInstall"], "Install updates automatically", {
1060
+ advanced: true,
1061
+ description: "Install newer versions automatically when one is found.",
1062
+ }),
680
1063
  number(["autoUpdate", "cooldownMs"], "Retry cooldown (ms)", {
681
1064
  advanced: true,
682
1065
  minimum: 0,
1066
+ description: "Minimum time between update checks.",
683
1067
  }),
684
1068
  number(["autoUpdate", "maxConsecutiveFailures"], "Max consecutive failures", {
685
1069
  advanced: true,
686
1070
  minimum: 1,
1071
+ description: "Disable automatic installs after this many failed attempts in a row.",
687
1072
  }),
688
1073
  ],
689
1074
  },
@@ -692,8 +1077,16 @@ export const SETTINGS_SECTIONS = [
692
1077
  label: "Web UI",
693
1078
  description: "This dashboard's own server settings.",
694
1079
  fields: [
695
- number(["ui", "port"], "Port", { minimum: 1, maximum: 65535, impact: "restart" }),
696
- boolean(["ui", "openBrowser"], "Open browser on start", { impact: "restart" }),
1080
+ number(["ui", "port"], "Port", {
1081
+ minimum: 1,
1082
+ maximum: 65535,
1083
+ impact: "restart",
1084
+ description: "HTTP port of this dashboard. Changing it requires a restart.",
1085
+ }),
1086
+ boolean(["ui", "openBrowser"], "Open browser on start", {
1087
+ impact: "restart",
1088
+ description: "Open the dashboard in the default browser when the server starts.",
1089
+ }),
697
1090
  enumField(["ui", "theme"], "Theme", ["dark", "light", "plasma", "drama"], {
698
1091
  scope: "global",
699
1092
  description: "Dashboard color theme. A machine-wide preference, saved to the global config.",
@@ -705,9 +1098,18 @@ export const SETTINGS_SECTIONS = [
705
1098
  label: "Terminal UI",
706
1099
  description: "Keybindings for the OpenCode terminal plugin.",
707
1100
  fields: [
708
- string(["tui", "settingsKeybinding"], "Open settings", { impact: "restart" }),
709
- string(["tui", "fileListKeybinding"], "Add file list", { impact: "restart" }),
710
- string(["tui", "chunksKeybinding"], "Add chunks", { impact: "restart" }),
1101
+ string(["tui", "settingsKeybinding"], "Open settings", {
1102
+ impact: "restart",
1103
+ description: "Key chord that opens the RAG settings dialog in the OpenCode terminal UI.",
1104
+ }),
1105
+ string(["tui", "fileListKeybinding"], "Add file list", {
1106
+ impact: "restart",
1107
+ description: "Key chord that inserts the indexed file list into the prompt.",
1108
+ }),
1109
+ string(["tui", "chunksKeybinding"], "Add chunks", {
1110
+ impact: "restart",
1111
+ description: "Key chord that inserts the chunk overview into the prompt.",
1112
+ }),
711
1113
  ],
712
1114
  },
713
1115
  {
@@ -715,8 +1117,13 @@ export const SETTINGS_SECTIONS = [
715
1117
  label: "Logging",
716
1118
  description: "Plugin log verbosity and destination.",
717
1119
  fields: [
718
- enumField(["logging", "level"], "Level", ["debug", "info", "error", "none"]),
719
- string(["logging", "logFilePath"], "Log file path", { advanced: true }),
1120
+ enumField(["logging", "level"], "Level", ["debug", "info", "error", "none"], {
1121
+ description: "Log verbosity: debug = everything, info = normal operation, error = failures only, none = silent.",
1122
+ }),
1123
+ string(["logging", "logFilePath"], "Log file path", {
1124
+ advanced: true,
1125
+ description: "Where the plugin writes its log. Relative paths resolve against the workspace.",
1126
+ }),
720
1127
  ],
721
1128
  },
722
1129
  ];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "opencode-rag-plugin",
3
- "version": "2.13.1",
3
+ "version": "2.13.3",
4
4
  "description": "OpenCode plugin for local-first RAG-based semantic code search",
5
5
  "type": "module",
6
6
  "main": "./dist/plugin-entry.js",