opencode-rag-plugin 1.17.0 → 1.17.2

package/ReadMe.md

@@ -41,10 +41,14 @@ opencode-rag query "authentication middleware"
 | **OpenCode plugin** | Auto-inject context, read-tool override, TUI settings, Ctrl+Enter to add RAG context, MCP registration on `init` |
 | **Incremental indexing** | File-hash manifest, background watcher, auto-rebuild on corruption |
 | **Privacy-first** | All processing stays local (when using Ollama) |
-| **CLI Tools** | `index`, `query`, `status`, `list`, `show`, `dump`, `clear`, `init`, `ui`, `mcp` |
+| **CLI Tools** | `init`, `index`, `query`, `status`, `list`, `show`, `dump`, `clear`, `describe-image`, `ui`, `mcp`, `setup`, `eval:sessions`, `eval:analyze`, `eval:compare` |
 | **Proxy-aware** | Corporate proxy support with raw-socket localhost bypass |
 | **OpenAI / Anthropic / Cohere** | Use alternate embedding providers with API key auto-resolution |
 | **Evaluation** | Session-level token tracking, RAG-on vs RAG-off comparison, tiktoken BPE counting |
+| **Documentation mode** | `/doc` slash command: agent adds JSDoc/TSDoc to undocumented files, progress tracked per subdirectory |
+| **Wiki mode** | `/wiki` slash command: agent maintains a persistent knowledge wiki at `.opencode/wiki/` (ingest, query, lint, seed) |
+| **Context optimization** | Post-retrieval dedup, per-file chunk limits, adjacent-merge to fit the context window |
+| **AGENTS.md directive** | `opencode-rag init` merges a tool-usage directive into `AGENTS.md` via sentinel markers |
 
 ## Web UI
 
@@ -80,6 +84,47 @@ OpenCodeRAG can index image files (PNG, JPEG, WebP, etc.) by sending them to a v
 
 **Disabled by default** — enable in `opencode-rag.json` to opt in (recommended for dedicated GPUs).
 
+## Documentation Mode
+
+When `documentationMode.enabled` is `true`, the OpenCode plugin exposes a `/doc` slash command that drives the agent to add JSDoc/TSDoc comments to undocumented source files. No agent tools are registered — documentation is driven entirely through the slash command and the documentation system prompt.
+
+```json
+{
+  "documentationMode": {
+    "enabled": true,
+    "batchSize": 5
+  }
+}
+```
+
+**Workflow:** Type `/doc` to list all undocumented files grouped by subdirectory. The agent picks a subdirectory, documents every public symbol (preserving existing comments and implementation code), then types `/doc src/auth/` to mark that subdirectory complete. Progress is persisted in `.opencode/rag_db/doc-mode-progress.json` so subsequent sessions resume where you left off.
+
+See [Plugin documentation](doc/plugin.md#5-documentation-mode--slash-command-doc) for details.
+
+## Wiki Mode
+
+When `wikiMode.enabled` is `true`, the OpenCode plugin injects a wiki-maintainer system prompt that instructs the agent to build and maintain a persistent knowledge wiki at `.opencode/wiki/` — a structured, interlinked collection of markdown pages synthesizing knowledge from the codebase, docs, and conversations.
+
+```json
+{
+  "wikiMode": {
+    "enabled": true
+  }
+}
+```
+
+**Slash commands:**
+
+| Command | Action |
+|---|---|
+| `/wiki` | Show wiki status (page count, subdirectories, index/log presence, latest log entry) |
+| `/wiki seed` | Generate the initial wiki from README, file structure, and code patterns |
+| `/wiki lint` | Health-check for orphan pages, stale source refs, contradictions, missing cross-links |
+
+The agent maintains all wiki pages during normal coding sessions (ingest on learning). The user never writes wiki pages directly. The wiki is git-trackable in `.opencode/` so every edit is a diff.
+
+See [Plugin documentation](doc/plugin.md#6-wiki-mode--slash-command-wiki) for the full protocol.
+
 ## MCP Server
 
 OpenCodeRAG ships a CLI-based [MCP (Model Context Protocol)](https://spec.modelcontextprotocol.io/) server that exposes semantic code tools to any MCP-compatible client (Claude Desktop, OpenCode, Cursor, etc.).
@@ -124,10 +169,10 @@ OpenCodeRAG registers tools that agents can invoke directly. Agents discover the
 
 When using OpenCode, the plugin enhances your agent with three discovery mechanisms:
 
-### 1. Skill-Based Discovery (Recommended)
+### 1. Skill-Based Discovery
 `opencode-rag init` creates `.opencode/skills/opencode-rag/SKILL.md` - an OpenCode skill that teaches agents the tool workflow. Agents load it on demand via the `skill` tool, keeping token overhead minimal.
 
-### 2. System Prompt Guidance (Conditional)
+### 2. System Prompt Guidance
 When chunks are indexed, a brief tool list is prepended to the system prompt so agents know the tools exist. This is skipped when no chunks are indexed to save tokens.
 
 ### 3. On-Demand RAG Context (Ctrl+Enter / Ctrl+Alt+Enter)

package/dist/cli/commands/index.d.ts

@@ -12,5 +12,6 @@ export { registerInitCommand } from "./init.js";
 export { registerUiCommand } from "./ui.js";
 export { registerMcpCommand } from "./mcp.js";
 export { registerSetupCommand } from "./setup.js";
+export { registerUpdateCommand } from "./update.js";
 export { registerEvalSessionsCommand, registerEvalAnalyzeCommand, registerEvalCompareCommand } from "./eval.js";
 export { registerDescribeImageCommand } from "./describe-image.js";

package/dist/cli/commands/index.js

@@ -12,6 +12,7 @@ export { registerInitCommand } from "./init.js";
 export { registerUiCommand } from "./ui.js";
 export { registerMcpCommand } from "./mcp.js";
 export { registerSetupCommand } from "./setup.js";
+export { registerUpdateCommand } from "./update.js";
 export { registerEvalSessionsCommand, registerEvalAnalyzeCommand, registerEvalCompareCommand } from "./eval.js";
 export { registerDescribeImageCommand } from "./describe-image.js";
 //# sourceMappingURL=index.js.map

package/dist/cli/commands/init-helpers.js

@@ -460,6 +460,9 @@ export function generateDefaultConfigJson() {
             timeoutMs: DEFAULT_CONFIG.description.timeoutMs,
             maxContentChars: DEFAULT_CONFIG.description.maxContentChars,
         },
+        wikiMode: {
+            enabled: DEFAULT_CONFIG.wikiMode.enabled,
+        },
         mcp: {
             enabled: DEFAULT_CONFIG.mcp.enabled,
         },

package/dist/cli/commands/status.js

@@ -147,12 +147,12 @@ export function registerStatusCommand(program) {
                     logCliInfo(logFilePath, "status", `${c.label("Runtime:")}           ${c.warn("version unknown — run `opencode-rag setup`")}`);
                 }
             }
-            // Async GitHub update check (fire-and-forget, 5s timeout)
-            // Only phone home if autoUpdate is explicitly enabled (opt-in).
+            // Async GitHub update check (fire-and-forget, 5s timeout).
+            // Runs unless autoUpdate is explicitly disabled.
             if (config.autoUpdate?.enabled) {
                 checkForUpdate(pkg.version).then((info) => {
                     if (info.updateAvailable) {
-                        process.stdout.write(`  ${c.label("Update:")}            ${c.warn(`v${info.latestVersion} available — npm update -g opencode-rag-plugin`)}\n`);
+                        process.stdout.write(`  ${c.label("Update:")}            ${c.warn(`v${info.latestVersion} available — run \`opencode-rag update\` to install`)}\n`);
                     }
                 }).catch(() => { });
             }

package/dist/cli/commands/update.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview `update` command — checks GitHub for a newer OpenCodeRAG release and installs it.
+ */
+/**
+ * `update` command — checks for a newer published version of OpenCodeRAG and,
+ * by default, installs it (via `npm install -g ...@latest`) then re-syncs the
+ * OpenCode runtime junctions so the new build is picked up on next restart.
+ */
+import type { Command } from "commander";
+/**
+ * Register the `update` command on the given Commander program.
+ *
+ * @param program - The Commander `Command` instance to register on.
+ */
+export declare function registerUpdateCommand(program: Command): void;

package/dist/cli/commands/update.js

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview `update` command — checks GitHub for a newer OpenCodeRAG release and installs it.
+ */
+/**
+ * `update` command — checks for a newer published version of OpenCodeRAG and,
+ * by default, installs it (via `npm install -g ...@latest`) then re-syncs the
+ * OpenCode runtime junctions so the new build is picked up on next restart.
+ */
+import { c } from "../format.js";
+import { checkForUpdate, getCurrentVersion, installLatestUpdate } from "../../core/version-check.js";
+/**
+ * Register the `update` command on the given Commander program.
+ *
+ * @param program - The Commander `Command` instance to register on.
+ */
+export function registerUpdateCommand(program) {
+    program
+        .command("update")
+        .description("Check for and install the newest published version of OpenCodeRAG")
+        .option("--check", "only check whether an update is available; do not install")
+        .option("-v, --verbose", "stream npm/setup output to the console")
+        .action(async (options) => {
+        const currentVersion = getCurrentVersion();
+        console.log(`\n${c.heading("OpenCodeRAG Update")}\n`);
+        console.log(`  ${c.label("Current version:")} ${c.value(currentVersion)}`);
+        console.log(`  ${c.label("Checking...")}     `);
+        let info;
+        try {
+            info = await checkForUpdate(currentVersion);
+        }
+        catch {
+            console.log(`\n  ${c.warn("Could not reach the update server. Check your network and try again.")}\n`);
+            process.exit(1);
+            return;
+        }
+        if (!info.updateAvailable) {
+            console.log(`\n  ${c.success("Already up-to-date.")} (${c.value(info.latestVersion || currentVersion)})\n`);
+            return;
+        }
+        console.log(`  ${c.label("Latest version:")}  ${c.value(info.latestVersion)}`);
+        if (info.publishedAt) {
+            console.log(`  ${c.label("Published:")}      ${c.dim(info.publishedAt)}`);
+        }
+        if (info.releaseUrl) {
+            console.log(`  ${c.label("Release notes:")}  ${c.file(info.releaseUrl)}`);
+        }
+        if (options.check) {
+            console.log(`\n  ${c.warn("Update available.")} Run ${c.file("opencode-rag update")} to install.\n`);
+            return;
+        }
+        console.log(`\n  ${c.dim("Installing newest version...")}\n`);
+        const result = await installLatestUpdate({ verbose: options.verbose });
+        if (result.success) {
+            console.log(`  ${c.success("✓")} ${result.message}`);
+            console.log(`\n  ${c.dim("Restart OpenCode if it is running to load the new version.")}\n`);
+        }
+        else {
+            console.error(`  ${c.error("✗")} ${result.message}`);
+            console.error(`\n  ${c.error("Update failed. You can retry with `opencode-rag update` or install manually:")}\n`);
+            console.error(`  ${c.dim("  npm install -g opencode-rag-plugin@latest && opencode-rag setup")}\n`);
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=update.js.map

package/dist/cli/index.js

@@ -14,7 +14,7 @@ import { realpathSync } from "node:fs";
 import { basename, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getPackageMetadata } from "./helpers.js";
-import { registerIndexCommand, registerQueryCommand, registerClearCommand, registerStatusCommand, registerListCommand, registerShowCommand, registerDumpCommand, registerInitCommand, registerUiCommand, registerMcpCommand, registerSetupCommand, registerEvalSessionsCommand, registerEvalAnalyzeCommand, registerEvalCompareCommand, registerDescribeImageCommand, } from "./commands/index.js";
+import { registerIndexCommand, registerQueryCommand, registerClearCommand, registerStatusCommand, registerListCommand, registerShowCommand, registerDumpCommand, registerInitCommand, registerUiCommand, registerMcpCommand, registerSetupCommand, registerUpdateCommand, registerEvalSessionsCommand, registerEvalAnalyzeCommand, registerEvalCompareCommand, registerDescribeImageCommand, } from "./commands/index.js";
 /**
  * The top-level Commander program instance that defines the `opencode-rag` CLI.
  *
@@ -39,6 +39,7 @@ registerDescribeImageCommand(program);
 registerUiCommand(program);
 registerMcpCommand(program);
 registerSetupCommand(program);
+registerUpdateCommand(program);
 registerEvalSessionsCommand(program);
 registerEvalAnalyzeCommand(program);
 registerEvalCompareCommand(program);

package/dist/core/config.d.ts

@@ -114,6 +114,13 @@ export interface DocumentationModeConfig {
     /** System prompt for the documentation agent. */
     systemPrompt: string;
 }
+/** Configuration for the wiki mode that instructs the AI agent to maintain a persistent knowledge wiki. */
+export interface WikiModeConfig {
+    /** Whether wiki mode is enabled. */
+    enabled: boolean;
+    /** System prompt for the wiki maintainer agent. */
+    systemPrompt: string;
+}
 /** Configuration for the terminal UI (TUI) keybindings. */
 export interface TuiConfig {
     /** Keybinding to toggle the file list panel. */
@@ -128,7 +135,7 @@ export interface McpConfig {
 }
 /** Configuration for automatic self-updates. */
 export interface AutoUpdateConfig {
-    /** Whether auto-update checking is enabled. */
+    /** Whether update checking is enabled (defaults to true). */
     enabled: boolean;
 }
 /** Configuration for post-retrieval context window optimization (adjacent merge, similarity dedup, file diversity cap). */
@@ -251,6 +258,8 @@ export interface RagConfig {
     imageDescription?: ImageDescriptionConfig;
     /** Automated documentation mode config. */
     documentationMode?: DocumentationModeConfig;
+    /** Wiki mode config that instructs the AI agent to maintain a persistent knowledge wiki. */
+    wikiMode?: WikiModeConfig;
     /** MCP server integration config. */
     mcp?: McpConfig;
     /** Auto-update checking config. */

package/dist/core/config.js

@@ -10,7 +10,7 @@ export const DEFAULT_CONFIG = {
         provider: "ollama",
         baseUrl: "http://127.0.0.1:11434/api",
         model: "qwen3-embedding:0.6b",
-        timeoutMs: 30000,
+        timeoutMs: 120000,
     },
     indexing: {
         includeExtensions: [
@@ -104,7 +104,7 @@ export const DEFAULT_CONFIG = {
         concurrency: 8,
         embedBatchSize: 100,
         embedConcurrency: 6,
-        ollamaMaxBatchSize: 4000,
+        ollamaMaxBatchSize: 500,
         descriptionConcurrency: 4,
         maxSvgSizeBytes: 1_048_576,
     },
@@ -183,11 +183,72 @@ export const DEFAULT_CONFIG = {
             "## Output format\n\n" +
             "Return your changes as a list of file paths with the full new content of the comment block for each modified symbol. Do NOT output the entire file unless asked.",
     },
+    wikiMode: {
+        enabled: false,
+        systemPrompt: "You are a wiki maintainer for this codebase. You incrementally build and maintain " +
+            "a persistent knowledge wiki at `.opencode/wiki/` — a structured, interlinked collection " +
+            "of markdown files that synthesizes knowledge from the codebase, documentation, and your conversations.\n\n" +
+            "## Three layers\n\n" +
+            "- **Raw sources**: code, docs, READMEs (immutable — read with `search_semantic`, `get_file_skeleton`, `find_usages`, `read`)\n" +
+            "- **Wiki**: `.opencode/wiki/*.md` (you own this layer — create, update, and maintain ALL pages)\n" +
+            "- **Schema**: this prompt (the protocol you follow)\n\n" +
+            "## Wiki layout\n\n" +
+            "`.opencode/wiki/`\n" +
+            "- `index.md` — content catalog: every page listed with a link and one-line summary\n" +
+            "- `log.md` — append-only timeline: `## [date] op | title`\n" +
+            "- `entities/` — pages for modules, services, key classes, components\n" +
+            "- `concepts/` — pages for patterns, conventions, architectural decisions, gotchas\n" +
+            "- `sources/` — summaries of external sources (articles, specs, discussions)\n\n" +
+            "## Page frontmatter\n\n" +
+            "Every page should start with:\n" +
+            "```\n" +
+            "---\n" +
+            "title: <page title>\n" +
+            "tags: [relevant tags]\n" +
+            "sourceRefs: [file paths or URLs this page synthesizes]\n" +
+            "lastReviewed: <date>\n" +
+            "---\n" +
+            "```\n\n" +
+            "## Operations\n\n" +
+            "### Ingest (when you learn something new)\n" +
+            "1. Read the source (code, doc, external article)\n" +
+            "2. Extract key information — what it does, why it exists, how it connects to existing knowledge\n" +
+            "3. Create or update relevant entity/concept pages\n" +
+            "4. Add cross-references with `[[wiki/page-name]]` links between related pages\n" +
+            "5. Update `index.md` with any new pages\n" +
+            "6. Append to `log.md`: `## [date] ingest | page title`\n\n" +
+            "### Query (when the user asks a question)\n" +
+            "1. Read `index.md` first to find relevant wiki pages\n" +
+            "2. Read those pages with the `read` tool\n" +
+            "3. If the wiki is insufficient, use `search_semantic` for code-level retrieval\n" +
+            "4. Synthesize an answer citing wiki pages where possible\n" +
+            "5. If the answer produced valuable analysis, file it back as a new wiki page\n\n" +
+            "### Lint (periodically, or when `/wiki lint` is invoked)\n" +
+            "Check for:\n" +
+            "- Orphan pages with no inbound `[[links]]`\n" +
+            "- Stale pages whose `sourceRefs` files changed since `lastReviewed`\n" +
+            "- Contradictions between pages\n" +
+            "- Important concepts mentioned but lacking their own page\n" +
+            "Append findings to `log.md`.\n\n" +
+            "### Seed (when `/wiki seed` is invoked)\n" +
+            "Generate initial wiki from existing sources:\n" +
+            "1. Read README and top-level docs for project overview → create overview page\n" +
+            "2. Scan file structure with `get_file_skeleton` for major modules → create entity pages\n" +
+            "3. Identify common conventions from code patterns → create concept pages\n" +
+            "4. Create `index.md` listing all pages\n" +
+            "5. Create `log.md` with initial entry\n" +
+            "6. Keep pages focused — one concept per page, short prose\n\n" +
+            "## Principles\n\n" +
+            "- You write and maintain ALL wiki pages — never ask the user to do it\n" +
+            "- Good answers and analyses get filed back as new pages — explorations compound\n" +
+            "- One concept per page — short, focused, cross-referenced\n" +
+            "- The wiki is git-trackable in `.opencode/` — every edit is a diff",
+    },
     mcp: {
         enabled: true,
     },
     autoUpdate: {
-        enabled: false,
+        enabled: true,
     },
     ui: {
         port: 3210,
@@ -215,7 +276,7 @@ export function validateConfig(config) {
     const KNOWN_TOP_KEYS = new Set([
         "embedding", "indexing", "vectorStore", "retrieval",
         "openCode", "chunkers", "chunking", "description",
-        "imageDescription", "documentationMode", "mcp", "autoUpdate", "ui", "tui", "logging",
+        "imageDescription", "documentationMode", "wikiMode", "mcp", "autoUpdate", "ui", "tui", "logging",
     ]);
     const topKeys = new Set(Object.keys(config));
     for (const key of topKeys) {
@@ -333,6 +394,8 @@ export function loadConfig(filePath, validate = true) {
     let parsed;
     try {
         raw = readFileSync(filePath, "utf-8");
+        if (raw.charCodeAt(0) === 0xfeff)
+            raw = raw.slice(1);
         parsed = JSON.parse(raw);
     }
     catch (err) {
@@ -399,6 +462,10 @@ export function loadConfig(filePath, validate = true) {
             ...DEFAULT_CONFIG.documentationMode,
             ...(safeObj(parsed.documentationMode) ?? {}),
         },
+        wikiMode: {
+            ...DEFAULT_CONFIG.wikiMode,
+            ...(safeObj(parsed.wikiMode) ?? {}),
+        },
         mcp: {
             ...DEFAULT_CONFIG.mcp,
             ...(safeObj(parsed.mcp) ?? {}),

package/dist/core/runtime-overrides.js

@@ -11,7 +11,9 @@ export function loadRuntimeOverrides(storePath) {
     if (!existsSync(overridePath))
         return {};
     try {
-        return JSON.parse(readFileSync(overridePath, "utf-8"));
+        const raw = readFileSync(overridePath, "utf-8");
+        const stripped = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+        return JSON.parse(stripped);
     }
     catch {
         return {};

package/dist/core/setup-runtime.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import os from "node:os";
-import { existsSync, mkdirSync, rmSync, writeFileSync, readFileSync, symlinkSync, } from "node:fs";
+import { existsSync, mkdirSync, rmSync, writeFileSync, readFileSync, symlinkSync, lstatSync, } from "node:fs";
 import { execSync } from "node:child_process";
 const PLUGIN_NAME = "opencode-rag-plugin";
 export function getRuntimeDir() {
@@ -131,38 +131,86 @@ export async function setupRuntime(options) {
         writeFileSync(runtimePkg, JSON.stringify({ private: true, type: "module" }, null, 2) + "\n", "utf-8");
     }
     removeIfExists(runtimePluginDir);
+    // Ensure stale directory is fully gone before creating junction
+    let retries = 3;
+    while (retries > 0 && existsSync(runtimePluginDir)) {
+        try {
+            rmSync(runtimePluginDir, { recursive: true, force: true });
+        }
+        catch { /* retry */ }
+        retries--;
+    }
     mkdirSync(path.dirname(runtimePluginDir), { recursive: true });
+    let junctionOk = false;
     try {
         createJunction(globalPluginDir, runtimePluginDir);
+        junctionOk = process.platform !== "win32";
+        if (process.platform === "win32") {
+            const stat = lstatSync(runtimePluginDir);
+            junctionOk = stat.isSymbolicLink();
+        }
     }
     catch {
+        // fall through to cpSync
+    }
+    if (!junctionOk) {
+        if (!options?.silent) {
+            console.error("  [warn] Junction not supported, falling back to copy...");
+        }
         const { cpSync } = await import("node:fs");
         cpSync(globalPluginDir, runtimePluginDir, { recursive: true });
     }
+    // Ensure the @opencode-ai/plugin SDK is available globally.
+    // We must NOT run `npm install` inside the runtime dir because npm
+    // re-resolves all of node_modules/ and replaces the plugin junction
+    // with the published npm version (corrupting the local link).
+    if (!existsSync(globalSdkPluginDir)) {
+        try {
+            execSync(`npm install -g @opencode-ai/plugin`, {
+                stdio: "pipe",
+                timeout: 60_000,
+            });
+        }
+        catch (cause) {
+            errors.push(`Failed to install @opencode-ai/plugin SDK globally: ${cause.message}`);
+            return { success: false, errors };
+        }
+    }
+    // Create junction from global SDK to runtime (same pattern as plugin above)
     if (existsSync(globalSdkPluginDir)) {
         removeIfExists(runtimeSdkPluginDir);
+        retries = 3;
+        while (retries > 0 && existsSync(runtimeSdkPluginDir)) {
+            try {
+                rmSync(runtimeSdkPluginDir, { recursive: true, force: true });
+            }
+            catch { /* retry */ }
+            retries--;
+        }
         mkdirSync(runtimeSdkDir, { recursive: true });
+        let sdkJunctionOk = false;
         try {
             createJunction(globalSdkPluginDir, runtimeSdkPluginDir);
+            sdkJunctionOk = process.platform !== "win32";
+            if (process.platform === "win32") {
+                const stat = lstatSync(runtimeSdkPluginDir);
+                sdkJunctionOk = stat.isSymbolicLink();
+            }
         }
         catch {
+            // fall through to cpSync
+        }
+        if (!sdkJunctionOk) {
+            if (!options?.silent) {
+                console.error("  [warn] SDK junction not supported, falling back to copy...");
+            }
             const { cpSync } = await import("node:fs");
             cpSync(globalSdkPluginDir, runtimeSdkPluginDir, { recursive: true });
         }
     }
     else {
-        mkdirSync(runtimeSdkDir, { recursive: true });
-        try {
-            execSync(`npm install @opencode-ai/plugin --no-save`, {
-                cwd: runtimeDir,
-                stdio: "pipe",
-                timeout: 60_000,
-            });
-        }
-        catch (cause) {
-            errors.push(`Failed to install @opencode-ai/plugin SDK: ${cause.message}`);
-            return { success: false, errors };
-        }
+        errors.push(`@opencode-ai/plugin SDK not available after global install`);
+        return { success: false, errors };
     }
     writeFileSync(versionFile, pluginVersion, "utf-8");
     patchWindowsWrappers(npmGlobalRoot);

package/dist/core/version-check.d.ts

@@ -1,9 +1,85 @@
+/**
+ * @fileoverview Version check and self-update functionality. Checks GitHub
+ * releases for new versions and installs the newest version via npm, then
+ * re-syncs the OpenCode runtime junctions.
+ */
+import { setupRuntime } from "./setup-runtime.js";
+/** Information about an available update. */
 export interface UpdateInfo {
+    /** The currently installed version string. */
     currentVersion: string;
+    /** The latest available version on GitHub. */
     latestVersion: string;
+    /** Whether a newer version than the current one exists. */
     updateAvailable: boolean;
+    /** URL to the GitHub release page. */
     releaseUrl: string;
+    /** ISO date string of when the release was published. */
     publishedAt: string;
 }
+/** Result of an install-update attempt. */
+export interface InstallUpdateResult {
+    /** Whether the install completed successfully. */
+    success: boolean;
+    /** Human-readable status message. */
+    message: string;
+    /** Version before the update. */
+    fromVersion: string;
+    /** Version after the update (undefined if the install failed). */
+    toVersion?: string;
+}
+/** Callable shape for the npm runner (a subset of execSync's signature). */
+type NpmRunner = (command: string, options: {
+    stdio: "inherit" | "pipe";
+    timeout: number;
+}) => unknown;
+/**
+ * Read the current version from the package.json sitting next to this module.
+ *
+ * Resolves the package root via `import.meta.url` so it works both from the
+ * source tree and from the compiled `dist/` output. Returns `"0.0.0"` if the
+ * file cannot be read or parsed (best-effort — never throws).
+ *
+ * @returns The current package version string.
+ */
+export declare function getCurrentVersion(): string;
+/**
+ * Compare two semver-ish strings.
+ * @returns 1 if a > b, -1 if a < b, 0 if equal.
+ */
 export declare function compareVersions(a: string, b: string): number;
+/**
+ * Check the GitHub releases API for a newer version of OpenCodeRAG.
+ *
+ * Uses a 5-second timeout; failures (network errors, non-OK responses, missing
+ * `tag_name`) are silently caught and reported as "no update available" so the
+ * caller never has to handle a rejection.
+ *
+ * @param currentVersion - The version string to compare against.
+ * @returns UpdateInfo indicating whether an update is available.
+ */
 export declare function checkForUpdate(currentVersion: string): Promise<UpdateInfo>;
+/**
+ * Install the newest published version of OpenCodeRAG.
+ *
+ * Runs `npm install -g <package>@latest` to refresh the global install, then
+ * calls {@link setupRuntime} with `force: true` to re-create the
+ * `~/.opencode/node_modules/` junctions so OpenCode picks up the new build on
+ * the next restart.
+ *
+ * @param options - Optional verbosity flag. When `verbose` is true, npm output
+ *   is streamed to the console; otherwise it is captured silently. The
+ *   `_execSync` and `_setupRuntime` seams are for testing only.
+ * @returns An {@link InstallUpdateResult} with success status, message, and the
+ *   from/to versions.
+ */
+export declare function installLatestUpdate(options?: {
+    verbose?: boolean;
+    /** Test seam: override the npm runner. */
+    _execSync?: NpmRunner;
+    /** Test seam: override the runtime sync. */
+    _setupRuntime?: typeof setupRuntime;
+    /** Test seam: override the version reader for the "to" version. */
+    _getCurrentVersion?: typeof getCurrentVersion;
+}): Promise<InstallUpdateResult>;
+export {};

package/dist/core/version-check.js

@@ -1,3 +1,45 @@
+/**
+ * @fileoverview Version check and self-update functionality. Checks GitHub
+ * releases for new versions and installs the newest version via npm, then
+ * re-syncs the OpenCode runtime junctions.
+ */
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { execSync } from "node:child_process";
+import { setupRuntime } from "./setup-runtime.js";
+/** npm package name (must match the `name` field in package.json). */
+const PACKAGE_NAME = "opencode-rag-plugin";
+/** GitHub repo used for release checks (owner/repo). */
+const GITHUB_REPO = "MrDoe/OpenCodeRAG";
+const GITHUB_API_URL = `https://api.github.com/repos/${GITHUB_REPO}/releases/latest`;
+/**
+ * Read the current version from the package.json sitting next to this module.
+ *
+ * Resolves the package root via `import.meta.url` so it works both from the
+ * source tree and from the compiled `dist/` output. Returns `"0.0.0"` if the
+ * file cannot be read or parsed (best-effort — never throws).
+ *
+ * @returns The current package version string.
+ */
+export function getCurrentVersion() {
+    try {
+        const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+/** Strip a leading 'v' or 'V' prefix from a version tag. */
+function normalizeVersion(tag) {
+    return tag.replace(/^v/i, "");
+}
+/**
+ * Compare two semver-ish strings.
+ * @returns 1 if a > b, -1 if a < b, 0 if equal.
+ */
 export function compareVersions(a, b) {
     const pa = a.split(".").map((s) => parseInt(s, 10));
     const pb = b.split(".").map((s) => parseInt(s, 10));
@@ -11,11 +53,21 @@ export function compareVersions(a, b) {
     }
     return 0;
 }
+/**
+ * Check the GitHub releases API for a newer version of OpenCodeRAG.
+ *
+ * Uses a 5-second timeout; failures (network errors, non-OK responses, missing
+ * `tag_name`) are silently caught and reported as "no update available" so the
+ * caller never has to handle a rejection.
+ *
+ * @param currentVersion - The version string to compare against.
+ * @returns UpdateInfo indicating whether an update is available.
+ */
 export async function checkForUpdate(currentVersion) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), 5_000);
     try {
-        const response = await fetch("https://api.github.com/repos/MrDoe/OpenCodeRAG/releases/latest", {
+        const response = await fetch(GITHUB_API_URL, {
             headers: {
                 Accept: "application/vnd.github+json",
                 "User-Agent": "opencode-rag-updater",
@@ -30,7 +82,7 @@ export async function checkForUpdate(currentVersion) {
         if (!tagName) {
             return { currentVersion, latestVersion: currentVersion, updateAvailable: false, releaseUrl: "", publishedAt: "" };
         }
-        const latestVersion = tagName.replace(/^v/i, "");
+        const latestVersion = normalizeVersion(tagName);
         return {
             currentVersion,
             latestVersion,
@@ -46,4 +98,63 @@ export async function checkForUpdate(currentVersion) {
         clearTimeout(timeout);
     }
 }
+/**
+ * Install the newest published version of OpenCodeRAG.
+ *
+ * Runs `npm install -g <package>@latest` to refresh the global install, then
+ * calls {@link setupRuntime} with `force: true` to re-create the
+ * `~/.opencode/node_modules/` junctions so OpenCode picks up the new build on
+ * the next restart.
+ *
+ * @param options - Optional verbosity flag. When `verbose` is true, npm output
+ *   is streamed to the console; otherwise it is captured silently. The
+ *   `_execSync` and `_setupRuntime` seams are for testing only.
+ * @returns An {@link InstallUpdateResult} with success status, message, and the
+ *   from/to versions.
+ */
+export async function installLatestUpdate(options) {
+    const verbose = options?.verbose ?? false;
+    const stdio = verbose ? "inherit" : "pipe";
+    const run = options?._execSync ?? execSync;
+    const syncRuntime = options?._setupRuntime ?? setupRuntime;
+    const readVersion = options?._getCurrentVersion ?? getCurrentVersion;
+    const fromVersion = readVersion();
+    try {
+        run(`npm install -g ${PACKAGE_NAME}@latest --no-fund --no-audit`, {
+            stdio,
+            timeout: 120_000,
+        });
+    }
+    catch (err) {
+        return {
+            success: false,
+            message: `npm install failed: ${err.message}`,
+            fromVersion,
+        };
+    }
+    const toVersion = readVersion();
+    const result = await syncRuntime({ force: true, silent: !verbose, version: toVersion });
+    if (!result.success) {
+        return {
+            success: false,
+            message: `installed v${toVersion} but runtime sync failed: ${result.errors.join("; ")}. Run \`opencode-rag setup\` to retry.`,
+            fromVersion,
+            toVersion,
+        };
+    }
+    if (compareVersions(toVersion, fromVersion) <= 0) {
+        return {
+            success: true,
+            message: `Already up-to-date (v${toVersion}). Runtime re-synced.`,
+            fromVersion,
+            toVersion,
+        };
+    }
+    return {
+        success: true,
+        message: `Updated v${fromVersion} → v${toVersion}. Restart OpenCode to load the new version.`,
+        fromVersion,
+        toVersion,
+    };
+}
 //# sourceMappingURL=version-check.js.map

package/dist/embedder/cohere.d.ts

@@ -9,7 +9,7 @@ import type { ProxyConfig } from "../core/config.js";
  * @param baseUrl - Cohere API base URL
  * @param model - Model name to use for embedding
  * @param apiKey - API key for authentication
- * @param timeoutMs - Request timeout in milliseconds (default 30000)
+ * @param timeoutMs - Request timeout in milliseconds (default 120000)
  * @param proxy - Optional proxy configuration
  */
 export declare class CohereProvider implements EmbeddingProvider {

package/dist/embedder/cohere.js

@@ -5,7 +5,7 @@ import { postJson } from "./http.js";
  * @param baseUrl - Cohere API base URL
  * @param model - Model name to use for embedding
  * @param apiKey - API key for authentication
- * @param timeoutMs - Request timeout in milliseconds (default 30000)
+ * @param timeoutMs - Request timeout in milliseconds (default 120000)
  * @param proxy - Optional proxy configuration
  */
 export class CohereProvider {
@@ -15,7 +15,7 @@ export class CohereProvider {
     apiKey;
     timeoutMs;
     proxy;
-    constructor(baseUrl, model, apiKey, timeoutMs = 30000, proxy) {
+    constructor(baseUrl, model, apiKey, timeoutMs = 120000, proxy) {
         this.baseUrl = baseUrl.replace(/\/+$/, "");
         this.model = model;
         this.apiKey = apiKey;

package/dist/embedder/factory.js

@@ -16,7 +16,7 @@ import pLimit from "p-limit";
  */
 export function createEmbedder(config) {
     const { provider, baseUrl, model, apiKey, proxy, timeoutMs } = config.embedding;
-    const effectiveTimeoutMs = timeoutMs ?? 30000;
+    const effectiveTimeoutMs = timeoutMs ?? 120000;
     if (provider === "ollama") {
         return new OllamaProvider(baseUrl, model, apiKey, effectiveTimeoutMs, proxy, config.logging.level);
     }

package/dist/embedder/health.js

@@ -4,7 +4,7 @@ import { postJson } from "./http.js";
  * Returns one result per configured model (embedding + description + image_description if enabled).
  */
 export async function checkProviderHealth(config) {
-    const timeoutMs = config.embedding.timeoutMs ?? 30000;
+    const timeoutMs = config.embedding.timeoutMs ?? 120000;
     const checks = [
         checkEmbeddingModel(config, timeoutMs),
     ];

package/dist/embedder/ollama.d.ts

@@ -9,7 +9,7 @@ import type { ProxyConfig } from "../core/config.js";
  * @param baseUrl - Ollama server base URL (e.g. http://localhost:11434)
  * @param model - Model name to use for embedding
  * @param apiKey - Optional API key for authenticated endpoints
- * @param timeoutMs - Request timeout in milliseconds (default 30000)
+   * @param timeoutMs - Request timeout in milliseconds (default 120000)
  * @param proxy - Optional proxy configuration
  * @param logLevel - Optional logging level for debug output
  */

package/dist/embedder/ollama.js

@@ -7,7 +7,7 @@ import { appendDebugLog } from "../core/fileLogger.js";
  * @param baseUrl - Ollama server base URL (e.g. http://localhost:11434)
  * @param model - Model name to use for embedding
  * @param apiKey - Optional API key for authenticated endpoints
- * @param timeoutMs - Request timeout in milliseconds (default 30000)
+   * @param timeoutMs - Request timeout in milliseconds (default 120000)
  * @param proxy - Optional proxy configuration
  * @param logLevel - Optional logging level for debug output
  */
@@ -19,7 +19,7 @@ export class OllamaProvider {
     timeoutMs;
     proxy;
     logLevel;
-    constructor(baseUrl, model, apiKey, timeoutMs = 30000, proxy, logLevel) {
+    constructor(baseUrl, model, apiKey, timeoutMs = 120000, proxy, logLevel) {
         this.baseUrl = baseUrl.replace(/\/+$/, "");
         this.model = model;
         this.apiKey = apiKey;

package/dist/embedder/openai.d.ts

@@ -9,7 +9,7 @@ import type { ProxyConfig } from "../core/config.js";
  * @param baseUrl - API base URL (e.g. https://api.openai.com/v1)
  * @param model - Model name to use for embedding
  * @param apiKey - API key for authentication
- * @param timeoutMs - Request timeout in milliseconds (default 30000)
+ * @param timeoutMs - Request timeout in milliseconds (default 120000)
  * @param proxy - Optional proxy configuration
  */
 export declare class OpenAIProvider implements EmbeddingProvider {

package/dist/embedder/openai.js

@@ -16,7 +16,7 @@ function inferProviderName(baseUrl) {
  * @param baseUrl - API base URL (e.g. https://api.openai.com/v1)
  * @param model - Model name to use for embedding
  * @param apiKey - API key for authentication
- * @param timeoutMs - Request timeout in milliseconds (default 30000)
+ * @param timeoutMs - Request timeout in milliseconds (default 120000)
  * @param proxy - Optional proxy configuration
  */
 export class OpenAIProvider {
@@ -27,7 +27,7 @@ export class OpenAIProvider {
     timeoutMs;
     proxy;
     provider;
-    constructor(baseUrl, model, apiKey, timeoutMs = 30000, proxy) {
+    constructor(baseUrl, model, apiKey, timeoutMs = 120000, proxy) {
         this.baseUrl = baseUrl.replace(/\/+$/, "");
         this.model = model;
         this.apiKey = apiKey;

package/dist/index.d.ts

@@ -25,6 +25,9 @@ export type { ContextOptimizationConfig, ContextOptimizationOptions } from "./re
  */
 export { search, indexWorkspace, getContext, validateConfig, scanWorkspace, getIndexStatusSummary } from "./api.js";
 export type { SearchOptions, IndexOptions, ContextResult, ConfigValidationResult, WorkspaceFile, IndexRunStats } from "./api.js";
+/** Version check and self-update API. */
+export { checkForUpdate, getCurrentVersion, installLatestUpdate, compareVersions } from "./core/version-check.js";
+export type { UpdateInfo, InstallUpdateResult } from "./core/version-check.js";
 /** The plugin server configuration object, used to register OpenCodeRAG as an OpenCode plugin. */
 export declare const server: import("@opencode-ai/plugin").Plugin;
 /** Unique identifier for the OpenCodeRAG plugin. */

package/dist/index.js

@@ -21,6 +21,8 @@ export { DescriptionCache } from "./core/desc-cache.js";
  * @module
  */
 export { search, indexWorkspace, getContext, validateConfig, scanWorkspace, getIndexStatusSummary } from "./api.js";
+/** Version check and self-update API. */
+export { checkForUpdate, getCurrentVersion, installLatestUpdate, compareVersions } from "./core/version-check.js";
 /** Plugin entry — only importable inside OpenCode's runtime. */
 import { ragPlugin } from "./plugin.js";
 /** The plugin server configuration object, used to register OpenCodeRAG as an OpenCode plugin. */

package/dist/indexer/pipeline.js

@@ -210,10 +210,17 @@ async function runIndexPassInner(options, logger) {
             effectiveStore = createVectorStore(options.config, tempStorePath, options.dimension);
             logger.debug(`Rebuilding index in temporary store at ${tempStorePath}`);
         }
+        else if (existingCount > 0) {
+            // NEVER destroy existing data when we can't do an atomic rebuild.
+            // Abort and ask the user to run 'opencode-rag index --force' manually.
+            logger.warn("Cannot rebuild safely without embedding dimension — aborting to protect existing data. " +
+                "Run 'opencode-rag index --force' manually to rebuild.");
+            // Restore manifest entries we just deleted so the next pass can retry incrementally
+            return createIndexStats(workspaceFiles.length, manifestStatus);
+        }
         else {
-            // Fallback — in-memory store or no dimension: clear in place.
-            logger.warn("No embedding dimension available; falling back to in-place clear.");
-            await options.store.clear();
+            // No existing data — safe to proceed with in-place indexing (no clear needed)
+            logger.debug("No existing data; indexing from scratch.");
         }
     }
     const stats = createIndexStats(workspaceFiles.length, manifestStatus);
@@ -518,7 +525,7 @@ async function runIndexPassInner(options, logger) {
     }
     // ── Phase 2: Embed all texts in a single batched call ──────────────────
     const batchSize = isOllama
-        ? Math.min(options.config.indexing.ollamaMaxBatchSize ?? 4000, defaultBatchSize)
+        ? Math.min(options.config.indexing.ollamaMaxBatchSize ?? 500, defaultBatchSize)
         : defaultBatchSize;
     let embeddedDone = 0;
     const allTexts = embedQueue.map(item => item.text);
@@ -556,6 +563,8 @@ async function runIndexPassInner(options, logger) {
         }
     }
     // ── Phase 3: Store + manifest update per file (parallel) ──────────────
+    const filesToStore = prepared.filter((p) => !earlyWorkerResults.has(prepared.indexOf(p)) && p.chunks && (p.textToEmbed?.length ?? 0) > 0).length;
+    let storedFiles = 0;
     const storeLimit = pLimit(options.config.indexing.concurrency);
     const storeResults = await Promise.all(prepared.map((prep, fi) => storeLimit(async () => {
         if (aborted()) {
@@ -618,6 +627,8 @@ async function runIndexPassInner(options, logger) {
             enqueueManifestSave();
         }
         options.progress?.finishFile(prep.fileLabel);
+        storedFiles++;
+        logChunkProgress("Storing", prep.fileLabel, storedFiles, filesToStore, storedFiles, filesToStore);
         return result;
     })));
     const workerResults = storeResults;

package/dist/plugin.js

@@ -22,9 +22,9 @@ import { loadDocProgress, markSubdirectoryDocumented } from "./core/doc-progress
 import { loadManifest } from "./core/manifest.js";
 import { createSessionLogger } from "./eval/session-logger.js";
 import { countTokens } from "./eval/token-counter.js";
-import { checkForUpdate } from "./core/version-check.js";
+import { checkForUpdate, getCurrentVersion } from "./core/version-check.js";
 import { destroyAllPooledConnections } from "./embedder/http.js";
-import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn, execSync } from "node:child_process";
@@ -39,6 +39,8 @@ const backgroundIndexers = new Map();
 const mcpServers = new Map();
 /** Pending update notifications keyed by workspace directory. */
 const pendingUpdateInfo = new Map();
+/** Workspace directories that have already been prompted about an update this session. */
+const notifiedUpdateDirs = new Set();
 /** Guard flag to prevent re-entrant shutdown. */
 let shutdownRegistered = false;
 /** Close all active background indexers and MCP servers, then destroy idle sockets. */
@@ -59,6 +61,7 @@ async function shutdownPluginResources() {
     }
     configCache.clear();
     pendingUpdateInfo.clear();
+    notifiedUpdateDirs.clear();
     destroyAllPooledConnections();
 }
 /** Register a process.beforeExit handler so that resources are cleaned up
@@ -685,17 +688,27 @@ export function createRagHooks(options) {
                 ];
                 output.system.unshift(guidance.join("\n"));
             }
-            // Inject update notification if available
+            // Inject a one-time update prompt so the agent asks the user to install.
+            // Fires only once per workspace per session to avoid nagging on every turn.
             const updateInfo = pendingUpdateInfo.get(options.worktree);
-            if (updateInfo) {
-                output.system.unshift(`OpenCodeRAG update available: ${updateInfo.currentVersion} → ${updateInfo.latestVersion}. ` +
-                    `Run \`npm update -g opencode-rag-plugin && opencode-rag setup\` to install.`);
+            if (updateInfo && !notifiedUpdateDirs.has(options.worktree)) {
+                notifiedUpdateDirs.add(options.worktree);
+                pendingUpdateInfo.delete(options.worktree);
+                output.system.unshift(`A newer OpenCodeRAG version is available: ${updateInfo.currentVersion} → ${updateInfo.latestVersion}. ` +
+                    `At the very start of your next response, briefly tell the user a new version is available and ask whether ` +
+                    `they would like you to install it. If they agree, run \`opencode-rag update\` via the bash tool, then tell ` +
+                    `them to restart OpenCode to load the new version. Do not mention this notice again.`);
             }
             // Inject documentation mode system prompt if enabled
             const docMode = getEffectiveCfg().documentationMode;
             if (docMode?.enabled && docMode.systemPrompt) {
                 output.system.unshift(docMode.systemPrompt);
             }
+            // Inject wiki mode system prompt if enabled
+            const wikiMode = getEffectiveCfg().wikiMode;
+            if (wikiMode?.enabled && wikiMode.systemPrompt) {
+                output.system.unshift(wikiMode.systemPrompt);
+            }
         },
         async "chat.message"(input, output) {
             try {
@@ -797,6 +810,64 @@ export function createRagHooks(options) {
                     }
                     return;
                 }
+                // Handle /wiki slash command
+                if (text.startsWith("/wiki")) {
+                    const wikiMode = getEffectiveCfg().wikiMode;
+                    if (!wikiMode?.enabled) {
+                        const parts = output?.parts ?? output?.message?.parts;
+                        if (Array.isArray(parts) && parts.length > 0) {
+                            const first = parts[0];
+                            if (typeof first.text === "string") {
+                                parts[0] = { ...first, text: "Wiki mode is not enabled. Set `wikiMode.enabled` to `true` in opencode-rag.json." };
+                            }
+                        }
+                        return;
+                    }
+                    const arg = text.slice(5).trim().toLowerCase();
+                    const wikiDir = path.join(options.worktree, ".opencode", "wiki");
+                    const lines = [];
+                    if (arg === "lint") {
+                        lines.push("## Wiki Lint", "", "Run a health check on the wiki. Check for:", "- Orphan pages with no inbound [[links]]", "- Stale pages whose sourceRefs files changed since lastReviewed", "- Contradictions between pages", "- Important concepts mentioned but lacking their own page", "", "Append findings to .opencode/wiki/log.md and fix any issues found.");
+                    }
+                    else if (arg === "seed") {
+                        lines.push("## Wiki Seed", "", "Generate the initial wiki from existing sources:", "1. Read README and top-level docs for project overview → create overview page", "2. Scan file structure with get_file_skeleton for major modules → create entity pages", "3. Identify common conventions from code patterns → create concept pages", "4. Create .opencode/wiki/index.md listing all pages", "5. Create .opencode/wiki/log.md with initial entry", "6. Keep pages focused — one concept per page, short prose, cross-referenced with [[links]]");
+                    }
+                    else {
+                        if (existsSync(wikiDir)) {
+                            const entries = readdirSync(wikiDir);
+                            const pages = entries.filter((e) => e.endsWith(".md") && e !== "log.md").length;
+                            const hasIndex = entries.includes("index.md");
+                            const hasLog = entries.includes("log.md");
+                            const dirs = entries.filter((e) => !e.includes(".")).length;
+                            let lastLogEntry = "";
+                            const logPath = path.join(wikiDir, "log.md");
+                            if (hasLog && existsSync(logPath)) {
+                                const logContent = readFileSync(logPath, "utf-8");
+                                const logLines = logContent.trim().split("\n").filter((l) => l.startsWith("## ["));
+                                if (logLines.length > 0) {
+                                    lastLogEntry = logLines[logLines.length - 1] ?? "";
+                                }
+                            }
+                            lines.push("## Wiki Status", "", `Wiki: \`.opencode/wiki/\``, `Pages: ~${pages} (.md files)`, `Subdirectories: \`${dirs}\``, `Index: ${hasIndex ? "yes" : "no"} | Log: ${hasLog ? "yes" : "no"}`);
+                            if (lastLogEntry) {
+                                lines.push(`Latest log: \`${lastLogEntry}\``);
+                            }
+                            lines.push("", "Commands:", "- `/wiki` — show this status", "- `/wiki lint` — health-check the wiki", "- `/wiki seed` — generate initial wiki pages from the codebase");
+                        }
+                        else {
+                            lines.push("## Wiki Status", "", "No wiki yet at `.opencode/wiki/`.", "Use `/wiki seed` to generate the initial wiki from existing sources.");
+                        }
+                    }
+                    const wikiMsg = lines.join("\n");
+                    const parts = output?.parts ?? output?.message?.parts;
+                    if (Array.isArray(parts) && parts.length > 0) {
+                        const first = parts[0];
+                        if (typeof first.text === "string") {
+                            parts[0] = { ...first, text: wikiMsg };
+                        }
+                    }
+                    return;
+                }
                 // Handle hotkey-triggered RAG injection (Ctrl+Enter / Ctrl+Alt+Enter)
                 const pendingInjection = consumePendingRagInjection(options.storePath);
                 if (pendingInjection) {
@@ -1090,6 +1161,7 @@ export const ragPlugin = async (input, _options) => {
     // Clean up stale config cache and pending update info for this directory
     configCache.delete(input.directory);
     pendingUpdateInfo.delete(input.directory);
+    notifiedUpdateDirs.delete(input.directory);
     // Clean up idle HTTP sockets from previous provider connections
     destroyAllPooledConnections();
     appendDebugLog(logFilePath, {
@@ -1165,6 +1237,7 @@ export const ragPlugin = async (input, _options) => {
             logLevel,
             keywordIndex,
             descriptionProvider,
+            dimension: vectorDimension,
         });
         backgroundIndexers.set(input.directory, indexer);
     }
@@ -1187,18 +1260,13 @@ export const ragPlugin = async (input, _options) => {
         const mcpInstance = startMcpServerProcess(input.directory, logFilePath, logLevel);
         mcpServers.set(input.directory, mcpInstance);
     }
-    // Auto-update check (non-blocking, best-effort)
+    // Auto-update check (non-blocking, best-effort). On by default; can be
+    // disabled via `autoUpdate.enabled: false` in opencode-rag.json. When a newer
+    // release is found it is stored and surfaced as a one-time install prompt via
+    // the system transform hook (see createRagHooks).
     const autoUpdateCfg = effectiveCfg.autoUpdate;
     if (autoUpdateCfg?.enabled) {
-        const currentVersion = (() => {
-            try {
-                const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json");
-                return JSON.parse(readFileSync(pkgPath, "utf-8")).version;
-            }
-            catch {
-                return "0.0.0";
-            }
-        })();
+        const currentVersion = getCurrentVersion();
         checkForUpdate(currentVersion)
             .then((info) => {
             if (info.updateAvailable) {

package/dist/tui.js

@@ -212,7 +212,9 @@ function getConfigPath(worktree) {
 /** Read and parse a JSON file, returning undefined on failure. */
 function readJsonFile(filePath) {
     try {
-        return JSON.parse(readFileSync(filePath, "utf-8"));
+        const raw = readFileSync(filePath, "utf-8");
+        const stripped = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+        return JSON.parse(stripped);
     }
     catch {
         return undefined;
@@ -341,6 +343,8 @@ function buildSettingCategories(cfg, ro, providers) {
     const descRo = (ro.description ?? {});
     const docModeCfg = (cfg.documentationMode ?? {});
     const docModeRo = (ro.documentationMode ?? {});
+    const wikiModeCfg = (cfg.wikiMode ?? {});
+    const wikiModeRo = (ro.wikiMode ?? {});
     const embeddingCfg = (cfg.embedding ?? {});
     const embeddingRo = (ro.embedding ?? {});
     const tuiCfg = (cfg.tui ?? {});
@@ -471,6 +475,19 @@ function buildSettingCategories(cfg, ro, providers) {
                 },
             ],
         },
+        {
+            id: "wiki",
+            label: "Wiki Mode",
+            description: "Configure the AI-maintained knowledge wiki that synthesizes codebase knowledge over time",
+            entries: [
+                {
+                    path: ["wikiMode", "enabled"],
+                    label: "Wiki mode",
+                    type: "boolean",
+                    currentValue: wikiModeRo.enabled ?? wikiModeCfg.enabled ?? false,
+                },
+            ],
+        },
         {
             id: "keybindings",
             label: "Keybindings",

package/dist/watcher.d.ts

@@ -30,6 +30,8 @@ export interface CreateBackgroundIndexerOptions {
     keywordIndex?: KeywordIndex;
     /** Optional provider for generating LLM-based chunk descriptions. */
     descriptionProvider?: DescriptionProvider;
+    /** Embedding vector dimension — enables atomic rebuilds instead of destructive clear. */
+    dimension?: number;
 }
 /** The current operational status of the background indexer watcher. */
 export type WatcherStatus = {

package/dist/watcher.js

@@ -28,7 +28,7 @@ function writeWatcherStatus(storePath, status) {
  * @returns A BackgroundIndexer handle with a close() method for shutdown.
  */
 export function createBackgroundIndexer(options) {
-    const { cwd, storePath, config, store, embedder, logFilePath, logLevel, keywordIndex, descriptionProvider } = options;
+    const { cwd, storePath, config, store, embedder, logFilePath, logLevel, keywordIndex, descriptionProvider, dimension } = options;
     writeWatcherStatus(storePath, { running: false, lastRunAt: undefined });
     const ac = new AbortController();
     const updateStatus = (partial) => {
@@ -45,6 +45,7 @@ export function createBackgroundIndexer(options) {
                 embedder,
                 keywordIndex,
                 descriptionProvider,
+                dimension,
                 filterPaths,
                 abortSignal: ac.signal,
                 logger: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-rag-plugin",
-  "version": "1.17.0",
+  "version": "1.17.2",
   "description": "OpenCode plugin for local-first RAG-based semantic code search",
   "type": "module",
   "main": "./dist/plugin-entry.js",