opencode-rag-plugin 2.13.2 → 2.13.4

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,28 +287,48 @@ 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
  },
@@ -208,19 +337,46 @@ export const SETTINGS_SECTIONS = [
208
337
  label: "Decision Model",
209
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
- string(["decision", "apiKey"], "API key"),
216
- number(["decision", "timeoutMs"], "Request timeout (ms)", { minimum: 1 }),
217
- string(["decision", "keepAlive"], "Ollama keep-alive", { advanced: true }),
218
- boolean(["decision", "routeBeforeAsking"], "Route choices before asking"),
219
- number(["decision", "maxStateChars"], "Max state chars", { advanced: true, minimum: 1 }),
220
- 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
+ }),
221
376
  number(["decision", "retryBaseDelayMs"], "Retry base delay (ms)", {
222
377
  advanced: true,
223
378
  minimum: 0,
379
+ description: "Initial delay between retries; doubles after each attempt.",
224
380
  }),
225
381
  ...proxyFields("decision"),
226
382
  ],
@@ -230,23 +386,48 @@ export const SETTINGS_SECTIONS = [
230
386
  label: "Reranking",
231
387
  description: "Optional cross-encoder rerank stage after hybrid fusion.",
232
388
  fields: [
233
- boolean(["reranking", "enabled"], "Enable reranking"),
234
- enumField(["reranking", "provider"], "Provider", ["llama-server"]),
235
- string(["reranking", "model"], "Model"),
236
- string(["reranking", "baseUrl"], "Base URL"),
237
- string(["reranking", "apiKey"], "API key"),
238
- number(["reranking", "candidates"], "Candidates", { minimum: 1 }),
239
- 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
+ }),
240
413
  number(["reranking", "minScore"], "Rerank min score", {
241
414
  advanced: true,
242
415
  minimum: 0,
243
416
  maximum: 1,
244
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.",
245
427
  }),
246
- number(["reranking", "timeoutMs"], "Timeout (ms)", { minimum: 1 }),
247
- string(["reranking", "queryTemplate"], "Query template", { advanced: true }),
248
428
  enumField(["reranking", "docField"], "Document field", ["content", "content+description"], {
249
429
  advanced: true,
430
+ description: "Which text is scored as the document: the code content alone or content plus its generated description.",
250
431
  }),
251
432
  ...proxyFields("reranking"),
252
433
  ],
@@ -256,25 +437,48 @@ export const SETTINGS_SECTIONS = [
256
437
  label: "Shell Guard",
257
438
  description: "Decision-model vetting of shell commands before they run.",
258
439
  fields: [
259
- 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
+ }),
260
443
  number(["shellGuard", "threshold"], "Flag threshold", {
261
444
  minimum: 0,
262
445
  maximum: 1,
263
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.",
264
472
  }),
265
- enumField(["shellGuard", "onError"], "On classifier error", ["allow", "ask"]),
266
- number(["shellGuard", "timeoutMs"], "Classification timeout (ms)", { minimum: 1 }),
267
- string(["shellGuard", "provider"], "Provider override", { advanced: true }),
268
- string(["shellGuard", "baseUrl"], "Base URL override", { advanced: true }),
269
- string(["shellGuard", "model"], "Model override", { advanced: true }),
270
- string(["shellGuard", "apiKey"], "API key override", { advanced: true, scope: "global" }),
271
473
  number(["shellGuard", "cacheTtlMs"], "Verdict cache TTL (ms)", {
272
474
  advanced: true,
273
475
  minimum: 0,
476
+ description: "Reuse identical verdicts for this long. 0 disables the cache.",
274
477
  }),
275
478
  number(["shellGuard", "maxCacheEntries"], "Max cached verdicts", {
276
479
  advanced: true,
277
480
  minimum: 1,
481
+ description: "Upper bound of cached verdicts before the oldest are dropped.",
278
482
  }),
279
483
  ],
280
484
  },
@@ -283,46 +487,73 @@ export const SETTINGS_SECTIONS = [
283
487
  label: "Indexing",
284
488
  description: "What gets scanned and how indexing is tuned.",
285
489
  fields: [
286
- 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
+ }),
287
494
  strings(["indexing", "includeDirs"], "Included folders", {
288
495
  impact: "reindex",
289
- 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.",
290
505
  }),
291
- strings(["indexing", "excludeDirs"], "Excluded folders", { impact: "reindex" }),
292
- strings(["indexing", "excludeFiles"], "Excluded files", { impact: "reindex" }),
293
506
  number(["indexing", "chunkOverlap"], "Chunk overlap (lines)", {
294
507
  minimum: 0,
295
508
  impact: "reindex",
509
+ description: "Lines of overlap between adjacent chunks; helps when a definition spans a chunk boundary.",
296
510
  }),
297
511
  number(["indexing", "maxChunkSize"], "Max chunk size (lines)", {
298
512
  minimum: 0,
299
513
  impact: "reindex",
300
- description: "0 = no limit (whole AST node).",
514
+ description: "0 = no limit (whole AST node). Smaller values produce more, smaller chunks.",
301
515
  }),
302
516
  number(["indexing", "minFileSizeBytes"], "Minimum file size (bytes)", {
303
517
  minimum: 0,
304
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.",
305
532
  }),
306
- number(["indexing", "concurrency"], "File concurrency", { minimum: 1 }),
307
- number(["indexing", "embedBatchSize"], "Embedding batch size", { minimum: 1 }),
308
- number(["indexing", "embedConcurrency"], "Embedding concurrency", { minimum: 1 }),
309
533
  number(["indexing", "ollamaMaxBatchSize"], "Ollama max batch size", {
310
534
  advanced: true,
311
535
  minimum: 1,
536
+ description: "Upper bound for one Ollama embedding request. Ollama handles smaller batches more reliably.",
312
537
  }),
313
538
  number(["indexing", "descriptionConcurrency"], "Description concurrency", {
314
539
  advanced: true,
315
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.",
316
546
  }),
317
- boolean(["indexing", "embedDescriptions"], "Embed descriptions", { impact: "reindex" }),
318
547
  number(["indexing", "maxSvgSizeBytes"], "Max SVG size (bytes)", {
319
548
  advanced: true,
320
549
  minimum: 0,
321
550
  impact: "reindex",
551
+ description: "SVGs above this size are skipped to avoid huge diagram payloads; 0 = no limit.",
322
552
  }),
323
553
  number(["indexing", "optimizeIntervalWindows"], "Optimize every N windows", {
324
554
  advanced: true,
325
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.",
326
557
  }),
327
558
  ],
328
559
  },
@@ -334,12 +565,18 @@ export const SETTINGS_SECTIONS = [
334
565
  stringMap(["chunking", "parsers"], "Extension → parser", {
335
566
  advanced: true,
336
567
  impact: "reindex",
568
+ description: "Override the parser per file extension, e.g. {.ssl: ssl}. Useful when a language needs a different splitter.",
337
569
  }),
338
570
  stringArrayMap(["chunking", "nodeTypes"], "Language → node types", {
339
571
  advanced: true,
340
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.",
341
579
  }),
342
- json(["chunkers"], "Custom chunker modules", { advanced: true, impact: "restart" }),
343
580
  ],
344
581
  },
345
582
  {
@@ -347,53 +584,72 @@ export const SETTINGS_SECTIONS = [
347
584
  label: "Retrieval",
348
585
  description: "Query-time ranking and context shaping.",
349
586
  fields: [
350
- 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
+ }),
351
592
  number(["retrieval", "minScore"], "Minimum score", {
352
593
  minimum: 0,
353
594
  maximum: 1,
354
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.",
355
603
  }),
356
- enumField(["retrieval", "minScoreMode"], "Min-score mode", ["fused", "normalized"]),
357
- boolean(["retrieval", "hybridSearch", "enabled"], "Hybrid search"),
358
604
  number(["retrieval", "hybridSearch", "keywordWeight"], "Keyword weight", {
359
605
  minimum: 0,
360
606
  maximum: 1,
361
607
  step: 0.01,
608
+ description: "Weight of keyword matches in the fused score (0-1). 0 disables the keyword contribution.",
362
609
  }),
363
610
  number(["retrieval", "hybridSearch", "symbolKeywordWeight"], "Symbol keyword weight", {
364
611
  minimum: 0,
365
612
  maximum: 1,
366
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.",
367
615
  }),
368
616
  number(["retrieval", "hybridSearch", "docKeywordDemotion"], "Document demotion", {
369
617
  advanced: true,
370
618
  minimum: 0,
371
619
  maximum: 1,
372
620
  step: 0.01,
621
+ description: "Multiplier (0-1) on keyword scores of documentation chunks so prose does not outrank code.",
373
622
  }),
374
623
  number(["retrieval", "hybridSearch", "testKeywordDemotion"], "Test demotion", {
375
624
  advanced: true,
376
625
  minimum: 0,
377
626
  maximum: 1,
378
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.",
379
632
  }),
380
- boolean(["retrieval", "contextOptimization", "enabled"], "Context optimization"),
381
633
  number(["retrieval", "contextOptimization", "maxPerFile"], "Max chunks per file", {
382
634
  advanced: true,
383
635
  minimum: 0,
636
+ description: "Maximum chunks taken from a single file. 0 = unlimited.",
384
637
  }),
385
638
  boolean(["retrieval", "contextOptimization", "mergeAdjacent"], "Merge adjacent chunks", {
386
639
  advanced: true,
640
+ description: "Merge chunks that touch or nearly touch into one continuous block.",
387
641
  }),
388
642
  number(["retrieval", "contextOptimization", "adjacentGapThreshold"], "Adjacent gap", {
389
643
  advanced: true,
390
644
  minimum: 0,
645
+ description: "Maximum line gap at which two chunks are still merged.",
391
646
  }),
392
647
  number(["retrieval", "contextOptimization", "similarityThreshold"], "Similarity threshold", {
393
648
  advanced: true,
394
649
  minimum: 0,
395
650
  maximum: 1,
396
651
  step: 0.01,
652
+ description: "Drop a chunk when it is at least this similar (0-1) to a higher-ranked chunk.",
397
653
  }),
398
654
  ],
399
655
  },
@@ -402,79 +658,98 @@ export const SETTINGS_SECTIONS = [
402
658
  label: "Vector Store",
403
659
  description: "Where the index lives. Most changes need a restart.",
404
660
  fields: [
405
- 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
+ }),
406
665
  enumField(["vectorStore", "provider"], "Backend", ["lancedb", "memory", "clickhouse"], {
407
666
  impact: "restart",
667
+ description: "Storage backend: lancedb (local default), memory (tests only, not persistent), clickhouse (shared server).",
408
668
  }),
409
669
  string(["vectorStore", "clickhouse", "url"], "ClickHouse URL", {
410
670
  advanced: true,
411
671
  impact: "restart",
672
+ description: "ClickHouse HTTP endpoint, e.g. http://pat06:8123.",
412
673
  }),
413
674
  string(["vectorStore", "clickhouse", "database"], "ClickHouse database", {
414
675
  advanced: true,
415
676
  impact: "restart",
677
+ description: "Database that holds the index tables.",
416
678
  }),
417
679
  string(["vectorStore", "clickhouse", "username"], "ClickHouse user", {
418
680
  advanced: true,
419
681
  impact: "restart",
682
+ description: "Login user for ClickHouse.",
420
683
  }),
421
684
  string(["vectorStore", "clickhouse", "password"], "ClickHouse password", {
422
685
  advanced: true,
423
686
  impact: "restart",
687
+ description: "Login password. Prefer the env var option so no secret lands in a committed file.",
424
688
  }),
425
689
  string(["vectorStore", "clickhouse", "passwordEnv"], "Password env var", {
426
690
  advanced: true,
427
691
  impact: "restart",
428
- 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.",
429
693
  }),
430
694
  string(["vectorStore", "clickhouse", "namespace"], "Namespace", {
431
695
  advanced: true,
432
696
  impact: "restart",
697
+ description: "Logical index name inside the database; isolates workspaces that share one server.",
433
698
  }),
434
699
  number(["vectorStore", "clickhouse", "requestTimeoutMs"], "Request timeout (ms)", {
435
700
  advanced: true,
436
701
  minimum: 1,
437
702
  impact: "restart",
703
+ description: "Maximum wait for one ClickHouse request.",
438
704
  }),
439
705
  number(["vectorStore", "clickhouse", "maxOpenConnections"], "Max connections", {
440
706
  advanced: true,
441
707
  minimum: 1,
442
708
  impact: "restart",
709
+ description: "Connection pool size for ClickHouse.",
443
710
  }),
444
711
  boolean(["vectorStore", "clickhouse", "compression"], "Compression", {
445
712
  advanced: true,
446
713
  impact: "restart",
714
+ description: "Compress HTTP traffic to ClickHouse. Lower bandwidth, slightly more CPU.",
447
715
  }),
448
716
  boolean(["vectorStore", "clickhouse", "state", "syncDescCache"], "Sync description cache", {
449
717
  advanced: true,
450
718
  impact: "restart",
719
+ description: "Mirror the description cache to ClickHouse so other machines reuse generated summaries.",
451
720
  }),
452
721
  boolean(["vectorStore", "clickhouse", "lease", "enabled"], "Single-writer lease", {
453
722
  advanced: true,
454
723
  impact: "restart",
724
+ description: "Allow only one process to write the shared index at a time, preventing concurrent-write corruption.",
455
725
  }),
456
726
  number(["vectorStore", "clickhouse", "lease", "ttlSeconds"], "Lease TTL (s)", {
457
727
  advanced: true,
458
728
  minimum: 10,
459
729
  impact: "restart",
730
+ description: "How long a writer lease stays valid without renewal.",
460
731
  }),
461
732
  number(["vectorStore", "clickhouse", "diskFreeFloorBytes"], "Disk free floor (bytes)", {
462
733
  advanced: true,
463
734
  minimum: 0,
464
735
  impact: "restart",
736
+ description: "Refuse a full rebuild when the server has less free disk than this. Default is 5 GiB.",
465
737
  }),
466
738
  enumField(["vectorStore", "clickhouse", "ann"], "ANN index", ["off", "hnsw"], {
467
739
  advanced: true,
468
740
  impact: "restart",
741
+ description: "Approximate nearest-neighbour index: off uses exact search, hnsw is faster on large indexes.",
469
742
  }),
470
743
  number(["vectorStore", "clickhouse", "annFetchMultiplier"], "ANN fetch multiplier", {
471
744
  advanced: true,
472
745
  minimum: 1,
473
746
  impact: "restart",
747
+ description: "How many extra candidates the ANN search fetches before rescoring. Higher = better recall, slower.",
474
748
  }),
475
749
  boolean(["vectorStore", "clickhouse", "annWithRescoring"], "ANN rescoring", {
476
750
  advanced: true,
477
751
  impact: "restart",
752
+ description: "Rescore ANN candidates with exact vector distance for better accuracy.",
478
753
  }),
479
754
  ],
480
755
  },
@@ -483,48 +758,83 @@ export const SETTINGS_SECTIONS = [
483
758
  label: "OpenCode Integration",
484
759
  description: "Tools, prompt injection, and background indexing.",
485
760
  fields: [
486
- boolean(["openCode", "enabled"], "Plugin enabled"),
487
- number(["openCode", "maxContextChunks"], "Max context chunks", { minimum: 1 }),
488
- 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
+ }),
489
771
  number(["openCode", "maxReadOutputChars"], "Max read output chars", {
490
772
  advanced: true,
491
773
  minimum: 1,
774
+ description: "Character budget for the overridden read tool output.",
492
775
  }),
493
776
  enumField(["openCode", "readNoResultsBehavior"], "Read with no results", [
494
777
  "hint",
495
778
  "empty",
496
779
  "error",
497
- ], { 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
+ }),
498
784
  number(["openCode", "readRelatedFilesMax"], "Related files shown", {
499
785
  advanced: true,
500
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
+ enumField(["openCode", "agentsMdDetail"], "AGENTS.md guidance size", ["auto", "full", "compact"], {
793
+ impact: "restart",
794
+ description: "How much of the tool protocol `AGENTS.md` carries. \"auto\" writes the short form when the system prompt already delivers the full protocol, so the same rules do not arrive twice per turn.",
795
+ }),
796
+ number(["openCode", "weakHitThreshold"], "Weak-hit label floor", {
797
+ minimum: 0,
798
+ maximum: 1,
799
+ step: 0.05,
800
+ description: "Average relevance below which a search result is labelled weak, telling the agent the hits are leads to verify. 0 disables the label.",
801
+ }),
802
+ boolean(["openCode", "exploreAgentTools"], "Give explore agent RAG tools", {
803
+ description: "Grant the built-in explore agent access to the RAG tools so it can search semantically.",
804
+ }),
805
+ boolean(["openCode", "autoIndex", "enabled"], "Auto-index file changes", {
806
+ description: "Re-index changed files automatically in the background while you work.",
501
807
  }),
502
- boolean(["openCode", "injectSystemPrompt"], "Inject RAG guidance"),
503
- boolean(["openCode", "exploreAgentTools"], "Give explore agent RAG tools"),
504
- boolean(["openCode", "autoIndex", "enabled"], "Auto-index file changes"),
505
808
  number(["openCode", "autoIndex", "debounceMs"], "Auto-index debounce (ms)", {
506
809
  minimum: 0,
810
+ description: "Wait this long after the last change before re-indexing, to batch rapid edits.",
507
811
  }),
508
812
  number(["openCode", "autoIndex", "intervalMs"], "Git poll interval (ms)", {
509
813
  advanced: true,
510
814
  minimum: 0,
815
+ description: "How often the git watcher checks for changes.",
511
816
  }),
512
817
  enumField(["openCode", "autoIndex", "watcher"], "Watcher backend", ["chokidar", "git"], {
513
818
  advanced: true,
819
+ description: "Change detector: chokidar watches the filesystem, git polls git status (more robust on network drives).",
514
820
  }),
515
821
  boolean(["openCode", "shell", "backgroundGuidance"], "Background guidance", {
516
822
  advanced: true,
823
+ description: "Tell the agent to run long commands in the background instead of blocking.",
517
824
  }),
518
825
  number(["openCode", "shell", "longRunningThresholdMs"], "Long command threshold (ms)", {
519
826
  advanced: true,
520
827
  minimum: 0,
828
+ description: "Commands expected to run longer than this count as long-running.",
521
829
  }),
522
830
  number(["openCode", "shell", "foregroundTimeoutMs"], "Foreground timeout (ms)", {
523
831
  advanced: true,
524
832
  minimum: 1,
833
+ description: "Default timeout for shell commands running in the foreground.",
525
834
  }),
526
835
  boolean(["openCode", "shell", "captureLongRunningQuirk"], "Capture long-command quirks", {
527
836
  advanced: true,
837
+ description: "Record a quirk when a foreground command exceeds the long-running threshold, so sessions learn from it.",
528
838
  }),
529
839
  ],
530
840
  },
@@ -533,104 +843,159 @@ export const SETTINGS_SECTIONS = [
533
843
  label: "Quirk Memory",
534
844
  description: "Experiential memory captured across sessions.",
535
845
  fields: [
536
- boolean(["memory", "enabled"], "Memory enabled"),
537
- boolean(["memory", "autoInject"], "Auto-inject quirks"),
846
+ boolean(["memory", "enabled"], "Memory enabled", {
847
+ description: "Persist quirks (gotchas, preferences, decisions, environment facts) across sessions.",
848
+ }),
849
+ boolean(["memory", "autoInject"], "Auto-inject quirks", {
850
+ description: "Automatically inject matching quirks into prompts when the request touches known knowledge.",
851
+ }),
538
852
  number(["memory", "minConfidence"], "Min confidence", {
539
853
  minimum: 0,
540
854
  maximum: 1,
541
855
  step: 0.01,
856
+ description: "Minimum confidence a quirk needs to be recalled at all. Lower-confidence memories fade out.",
542
857
  }),
543
858
  number(["memory", "recallMinScore"], "Manual recall min score", {
544
859
  minimum: 0,
545
860
  maximum: 1,
546
861
  step: 0.01,
862
+ description: "Minimum similarity for explicit recall_quirks calls.",
547
863
  }),
548
864
  number(["memory", "autoInjectMinScore"], "Auto-inject min score", {
549
865
  minimum: 0,
550
866
  maximum: 1,
551
867
  step: 0.01,
868
+ description: "Minimum similarity for automatic injection into a turn.",
869
+ }),
870
+ number(["memory", "autoInjectTopK"], "Auto-inject top K", {
871
+ minimum: 0,
872
+ description: "Maximum number of quirks injected automatically per turn.",
552
873
  }),
553
- number(["memory", "autoInjectTopK"], "Auto-inject top K", { minimum: 0 }),
554
874
  number(["memory", "autoInjectMinTokenOverlap"], "Auto-inject token overlap", {
555
875
  advanced: true,
556
876
  minimum: 0,
877
+ description: "Minimum shared meaningful words between request and quirk. Blocks vector-only false positives.",
557
878
  }),
558
879
  number(["memory", "autoInjectLatencyBudgetMs"], "Auto-inject latency budget (ms)", {
559
880
  advanced: true,
560
881
  minimum: 0,
882
+ description: "Skip auto-injection when recall takes longer than this. 0 = no budget.",
883
+ }),
884
+ boolean(["memory", "passiveCapture"], "Passive capture", {
885
+ advanced: true,
886
+ description: "Extract quirks from each completed agent turn automatically.",
887
+ }),
888
+ boolean(["memory", "promptEnforcement"], "Mandatory capture prompt", {
889
+ advanced: true,
890
+ description: "Upgrade the system-prompt nudge into a mandatory capture instruction.",
891
+ }),
892
+ boolean(["memory", "sessionEndExtraction"], "Session-end extraction", {
893
+ advanced: true,
894
+ description: "Summarize the full session transcript into quirks when the session ends.",
561
895
  }),
562
- boolean(["memory", "passiveCapture"], "Passive capture", { advanced: true }),
563
- boolean(["memory", "promptEnforcement"], "Mandatory capture prompt", { advanced: true }),
564
- boolean(["memory", "sessionEndExtraction"], "Session-end extraction", { advanced: true }),
565
896
  number(["memory", "autoCaptureMaxPerTurn"], "Max captures per turn", {
566
897
  advanced: true,
567
898
  minimum: 0,
899
+ description: "Cap on quirks captured from a single turn.",
568
900
  }),
569
901
  number(["memory", "autoCaptureDedupThreshold"], "Capture dedup threshold", {
570
902
  advanced: true,
571
903
  minimum: 0,
572
904
  maximum: 1,
573
905
  step: 0.01,
906
+ description: "Similarity above which a new capture counts as a duplicate and is skipped.",
907
+ }),
908
+ boolean(["memory", "injectOnToolError"], "Inject after tool errors", {
909
+ advanced: true,
910
+ description: "After a failed tool call, recall matching quirks and inject them into the next request.",
574
911
  }),
575
- boolean(["memory", "injectOnToolError"], "Inject after tool errors", { advanced: true }),
576
912
  number(["memory", "toolErrorMinScore"], "Tool-error min score", {
577
913
  advanced: true,
578
914
  minimum: 0,
579
915
  maximum: 1,
580
916
  step: 0.01,
917
+ description: "Minimum similarity for tool-error quirk injection.",
918
+ }),
919
+ number(["memory", "toolErrorTopK"], "Tool-error top K", {
920
+ advanced: true,
921
+ minimum: 0,
922
+ description: "Maximum number of tool-error quirks injected at once.",
581
923
  }),
582
- number(["memory", "toolErrorTopK"], "Tool-error top K", { advanced: true, minimum: 0 }),
583
924
  number(["memory", "toolErrorMinTokenOverlap"], "Tool-error token overlap", {
584
925
  advanced: true,
585
926
  minimum: 0,
927
+ description: "Minimum shared words for a tool-error quirk to qualify for injection.",
586
928
  }),
587
929
  number(["memory", "toolErrorCooldownMs"], "Tool-error cooldown (ms)", {
588
930
  advanced: true,
589
931
  minimum: 0,
932
+ description: "Do not re-attempt the same error signature within this window.",
590
933
  }),
591
934
  number(["memory", "toolErrorMaxPerSession"], "Tool-error injections / session", {
592
935
  advanced: true,
593
936
  minimum: 0,
937
+ description: "Cap on tool-error quirk injections per session.",
594
938
  }),
595
939
  number(["memory", "toolErrorLatencyBudgetMs"], "Tool-error latency budget (ms)", {
596
940
  advanced: true,
597
941
  minimum: 0,
942
+ description: "Skip tool-error recall when it takes longer than this.",
598
943
  }),
599
944
  boolean(["memory", "autoCreateOnToolError"], "Create quirks from tool errors", {
600
945
  advanced: true,
946
+ description: "Create a new quirk when a tool error has no matching memory.",
601
947
  }),
602
948
  number(["memory", "toolErrorCreateMaxPerSession"], "Creations / session", {
603
949
  advanced: true,
604
950
  minimum: 0,
951
+ description: "Cap on quirks created from tool errors per session.",
605
952
  }),
606
953
  number(["memory", "toolErrorCreateCooldownMs"], "Creation cooldown (ms)", {
607
954
  advanced: true,
608
955
  minimum: 0,
956
+ description: "Minimum time between creations of the same error signature.",
609
957
  }),
610
958
  number(["memory", "toolErrorCreateMinScore"], "Creation min score", {
611
959
  advanced: true,
612
960
  minimum: 0,
613
961
  maximum: 1,
614
962
  step: 0.01,
963
+ description: "Highest similarity at which an error still counts as having no matching quirk.",
615
964
  }),
616
965
  number(["memory", "toolErrorCreateLatencyBudgetMs"], "Creation latency budget (ms)", {
617
966
  advanced: true,
618
967
  minimum: 0,
968
+ description: "Skip creation when the lookup takes longer than this.",
969
+ }),
970
+ boolean(["memory", "toolErrorInjectCreated"], "Inject created quirk", {
971
+ advanced: true,
972
+ description: "Inject a freshly created quirk into the next request so the lesson is visible immediately.",
973
+ }),
974
+ boolean(["memory", "toolErrorProactiveInject"], "Proactive tool gotchas", {
975
+ advanced: true,
976
+ description: "Warn about known tool gotchas before the tool is called.",
619
977
  }),
620
- boolean(["memory", "toolErrorInjectCreated"], "Inject created quirk", { advanced: true }),
621
- boolean(["memory", "toolErrorProactiveInject"], "Proactive tool gotchas", { advanced: true }),
622
978
  number(["memory", "toolErrorProactiveMaxItems"], "Max proactive gotchas", {
623
979
  advanced: true,
624
980
  minimum: 0,
981
+ description: "Maximum proactive gotchas injected per prompt.",
982
+ }),
983
+ boolean(["memory", "interceptAllErrors"], "Intercept all failures", {
984
+ advanced: true,
985
+ description: "Also treat failures reported inside successful tool output (non-zero exit code, stack traces) as errors.",
625
986
  }),
626
- boolean(["memory", "interceptAllErrors"], "Intercept all failures", { advanced: true }),
627
987
  boolean(["memory", "autoCreateOnInterceptedError"], "Create from intercepted failures", {
628
988
  advanced: true,
989
+ description: "Create quirks from those intercepted failures too, not just from remembered ones.",
990
+ }),
991
+ boolean(["memory", "decay", "enabled"], "Confidence decay", {
992
+ advanced: true,
993
+ description: "Slowly reduce quirk confidence over time so stale knowledge fades away.",
629
994
  }),
630
- boolean(["memory", "decay", "enabled"], "Confidence decay", { advanced: true }),
631
995
  number(["memory", "decay", "halfLifeDays"], "Decay half-life (days)", {
632
996
  advanced: true,
633
997
  minimum: 1,
998
+ description: "Days after which a quirk's confidence halves.",
634
999
  }),
635
1000
  ],
636
1001
  },
@@ -639,12 +1004,20 @@ export const SETTINGS_SECTIONS = [
639
1004
  label: "Documentation Mode",
640
1005
  description: "Agent mode that adds doc comments to undocumented code.",
641
1006
  fields: [
642
- boolean(["documentationMode", "enabled"], "Documentation mode enabled"),
643
- boolean(["documentationMode", "autoStart"], "Start automatically"),
644
- number(["documentationMode", "batchSize"], "Files per batch", { minimum: 1 }),
1007
+ boolean(["documentationMode", "enabled"], "Documentation mode enabled", {
1008
+ description: "Turn the agent into a documentation maintainer that adds doc comments to undocumented code.",
1009
+ }),
1010
+ boolean(["documentationMode", "autoStart"], "Start automatically", {
1011
+ description: "Start documentation mode automatically in new sessions.",
1012
+ }),
1013
+ number(["documentationMode", "batchSize"], "Files per batch", {
1014
+ minimum: 1,
1015
+ description: "Files processed per documentation pass.",
1016
+ }),
645
1017
  string(["documentationMode", "systemPrompt"], "System prompt", {
646
1018
  advanced: true,
647
1019
  multiline: true,
1020
+ description: "Instruction that defines the documentation behaviour. Edit it to change style and scope.",
648
1021
  }),
649
1022
  ],
650
1023
  },
@@ -653,10 +1026,13 @@ export const SETTINGS_SECTIONS = [
653
1026
  label: "Wiki Mode",
654
1027
  description: "Agent instruction that maintains a knowledge wiki.",
655
1028
  fields: [
656
- boolean(["wikiMode", "enabled"], "Wiki mode enabled"),
1029
+ boolean(["wikiMode", "enabled"], "Wiki mode enabled", {
1030
+ description: "Turn the agent into a wiki maintainer that keeps a structured knowledge wiki under .opencode/wiki.",
1031
+ }),
657
1032
  string(["wikiMode", "systemPrompt"], "System prompt", {
658
1033
  advanced: true,
659
1034
  multiline: true,
1035
+ description: "Instruction that defines the wiki layout and operations. Edit it to change the workflow.",
660
1036
  }),
661
1037
  ],
662
1038
  },
@@ -664,28 +1040,45 @@ export const SETTINGS_SECTIONS = [
664
1040
  id: "mcp",
665
1041
  label: "MCP Server",
666
1042
  description: "Standalone Model Context Protocol server.",
667
- fields: [boolean(["mcp", "enabled"], "Auto-start MCP server", { impact: "restart" })],
1043
+ fields: [
1044
+ boolean(["mcp", "enabled"], "Auto-start MCP server", {
1045
+ impact: "restart",
1046
+ description: "Run the standalone MCP server at startup so other MCP clients can use the RAG tools.",
1047
+ }),
1048
+ ],
668
1049
  },
669
1050
  {
670
1051
  id: "setup",
671
1052
  label: "Workspace Setup",
672
1053
  description: "Scaffolding behaviour for repositories without a config.",
673
- fields: [boolean(["setup", "autoScaffold"], "Auto-scaffold new workspaces", { advanced: true })],
1054
+ fields: [
1055
+ boolean(["setup", "autoScaffold"], "Auto-scaffold new workspaces", {
1056
+ advanced: true,
1057
+ description: "Create config, skills, and AGENTS.md snippets automatically in workspaces that have none.",
1058
+ }),
1059
+ ],
674
1060
  },
675
1061
  {
676
1062
  id: "autoUpdate",
677
1063
  label: "Auto Update",
678
1064
  description: "Update checks and optional automatic installs.",
679
1065
  fields: [
680
- boolean(["autoUpdate", "enabled"], "Check for updates"),
681
- boolean(["autoUpdate", "autoInstall"], "Install updates automatically", { advanced: true }),
1066
+ boolean(["autoUpdate", "enabled"], "Check for updates", {
1067
+ description: "Check npm for newer plugin versions.",
1068
+ }),
1069
+ boolean(["autoUpdate", "autoInstall"], "Install updates automatically", {
1070
+ advanced: true,
1071
+ description: "Install newer versions automatically when one is found.",
1072
+ }),
682
1073
  number(["autoUpdate", "cooldownMs"], "Retry cooldown (ms)", {
683
1074
  advanced: true,
684
1075
  minimum: 0,
1076
+ description: "Minimum time between update checks.",
685
1077
  }),
686
1078
  number(["autoUpdate", "maxConsecutiveFailures"], "Max consecutive failures", {
687
1079
  advanced: true,
688
1080
  minimum: 1,
1081
+ description: "Disable automatic installs after this many failed attempts in a row.",
689
1082
  }),
690
1083
  ],
691
1084
  },
@@ -694,8 +1087,16 @@ export const SETTINGS_SECTIONS = [
694
1087
  label: "Web UI",
695
1088
  description: "This dashboard's own server settings.",
696
1089
  fields: [
697
- number(["ui", "port"], "Port", { minimum: 1, maximum: 65535, impact: "restart" }),
698
- boolean(["ui", "openBrowser"], "Open browser on start", { impact: "restart" }),
1090
+ number(["ui", "port"], "Port", {
1091
+ minimum: 1,
1092
+ maximum: 65535,
1093
+ impact: "restart",
1094
+ description: "HTTP port of this dashboard. Changing it requires a restart.",
1095
+ }),
1096
+ boolean(["ui", "openBrowser"], "Open browser on start", {
1097
+ impact: "restart",
1098
+ description: "Open the dashboard in the default browser when the server starts.",
1099
+ }),
699
1100
  enumField(["ui", "theme"], "Theme", ["dark", "light", "plasma", "drama"], {
700
1101
  scope: "global",
701
1102
  description: "Dashboard color theme. A machine-wide preference, saved to the global config.",
@@ -707,9 +1108,18 @@ export const SETTINGS_SECTIONS = [
707
1108
  label: "Terminal UI",
708
1109
  description: "Keybindings for the OpenCode terminal plugin.",
709
1110
  fields: [
710
- string(["tui", "settingsKeybinding"], "Open settings", { impact: "restart" }),
711
- string(["tui", "fileListKeybinding"], "Add file list", { impact: "restart" }),
712
- string(["tui", "chunksKeybinding"], "Add chunks", { impact: "restart" }),
1111
+ string(["tui", "settingsKeybinding"], "Open settings", {
1112
+ impact: "restart",
1113
+ description: "Key chord that opens the RAG settings dialog in the OpenCode terminal UI.",
1114
+ }),
1115
+ string(["tui", "fileListKeybinding"], "Add file list", {
1116
+ impact: "restart",
1117
+ description: "Key chord that inserts the indexed file list into the prompt.",
1118
+ }),
1119
+ string(["tui", "chunksKeybinding"], "Add chunks", {
1120
+ impact: "restart",
1121
+ description: "Key chord that inserts the chunk overview into the prompt.",
1122
+ }),
713
1123
  ],
714
1124
  },
715
1125
  {
@@ -717,8 +1127,13 @@ export const SETTINGS_SECTIONS = [
717
1127
  label: "Logging",
718
1128
  description: "Plugin log verbosity and destination.",
719
1129
  fields: [
720
- enumField(["logging", "level"], "Level", ["debug", "info", "error", "none"]),
721
- string(["logging", "logFilePath"], "Log file path", { advanced: true }),
1130
+ enumField(["logging", "level"], "Level", ["debug", "info", "error", "none"], {
1131
+ description: "Log verbosity: debug = everything, info = normal operation, error = failures only, none = silent.",
1132
+ }),
1133
+ string(["logging", "logFilePath"], "Log file path", {
1134
+ advanced: true,
1135
+ description: "Where the plugin writes its log. Relative paths resolve against the workspace.",
1136
+ }),
722
1137
  ],
723
1138
  },
724
1139
  ];