opencode-rag-plugin 1.17.0 → 1.17.3

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,14 +84,57 @@ 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).
 
-## MCP Server
+## Documentation Mode
 
-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.).
+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 (Optional)
+
+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, Cursor, etc.).
 
 ```bash
 opencode-rag mcp
 ```
 
+> **Note:** The MCP server is **optional**. When running as an OpenCode plugin, the four tools are registered **in-process** and work without the MCP server. The `chat.message` hook for hotkey injection also runs in-process. The MCP server is only needed when an **external** MCP client connects to OpenCodeRAG. The plugin auto-starts the server only if `mcp.enabled` is `true` in your config (default: `false`).
+
 ### MCP Tools
 
 | Tool | Description |
@@ -124,10 +171,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/auto-update-state.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Persisted state for the background auto-update mechanism.
+ * Tracks when an install was last attempted, for which version,
+ * and consecutive failure counts to implement cooldown and backoff.
+ */
+/** Persisted state of a background auto-update attempt. */
+export interface AutoUpdateState {
+    /** Epoch ms of the most recent attempt. */
+    lastAttemptAt: number;
+    /** The latestVersion we tried to install (or checked). */
+    lastAttemptedVersion: string;
+    /** Outcome of the last attempt. */
+    lastResult: "success" | "failure";
+    /** Consecutive failures so far (reset on success). */
+    consecutiveFailures: number;
+}
+/** Full path to the state file for a given store path. */
+export declare function statePath(storePath: string): string;
+/** Load persisted auto-update state, or return null if missing / corrupt. */
+export declare function loadAutoUpdateState(storePath: string): AutoUpdateState | null;
+/** Persist auto-update state to disk (best-effort, never throws). */
+export declare function saveAutoUpdateState(storePath: string, state: AutoUpdateState): void;
+/**
+ * Determine whether an auto-install attempt should proceed, based on
+ * the persisted state, the version we just discovered, and configured
+ * limits.
+ *
+ * @returns An object with `attempt: boolean` and `reason: string`.
+ */
+export declare function shouldAttemptInstall(state: AutoUpdateState | null, latestVersion: string, cooldownMs: number, maxConsecutiveFailures: number): {
+    attempt: boolean;
+    reason: string;
+};

package/dist/core/auto-update-state.js

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview Persisted state for the background auto-update mechanism.
+ * Tracks when an install was last attempted, for which version,
+ * and consecutive failure counts to implement cooldown and backoff.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+/** Name of the state file written to the store path. */
+const STATE_FILE_NAME = ".auto-update-state.json";
+/** Full path to the state file for a given store path. */
+export function statePath(storePath) {
+    return path.join(storePath, STATE_FILE_NAME);
+}
+/** Load persisted auto-update state, or return null if missing / corrupt. */
+export function loadAutoUpdateState(storePath) {
+    try {
+        const p = statePath(storePath);
+        if (!existsSync(p))
+            return null;
+        const raw = readFileSync(p, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.lastAttemptAt !== "number" ||
+            typeof parsed.lastAttemptedVersion !== "string" ||
+            (parsed.lastResult !== "success" && parsed.lastResult !== "failure") ||
+            typeof parsed.consecutiveFailures !== "number") {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist auto-update state to disk (best-effort, never throws). */
+export function saveAutoUpdateState(storePath, state) {
+    try {
+        writeFileSync(statePath(storePath), JSON.stringify(state, null, 2), "utf-8");
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/**
+ * Determine whether an auto-install attempt should proceed, based on
+ * the persisted state, the version we just discovered, and configured
+ * limits.
+ *
+ * @returns An object with `attempt: boolean` and `reason: string`.
+ */
+export function shouldAttemptInstall(state, latestVersion, cooldownMs, maxConsecutiveFailures) {
+    if (!state) {
+        return { attempt: true, reason: "first run" };
+    }
+    const elapsed = Date.now() - state.lastAttemptAt;
+    if (state.lastAttemptedVersion === latestVersion && elapsed < cooldownMs) {
+        return {
+            attempt: false,
+            reason: `version ${latestVersion} already attempted ${Math.round(elapsed / 1000)}s ago (cooldown ${Math.round(cooldownMs / 1000)}s)`,
+        };
+    }
+    if (state.lastResult === "failure" && state.consecutiveFailures >= maxConsecutiveFailures && elapsed < cooldownMs) {
+        return {
+            attempt: false,
+            reason: `${state.consecutiveFailures} consecutive failures within cooldown window`,
+        };
+    }
+    return { attempt: true, reason: "proceeding" };
+}
+//# sourceMappingURL=auto-update-state.js.map

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. */
@@ -121,15 +128,21 @@ export interface TuiConfig {
     /** Keybinding to toggle the chunk viewer panel. */
     chunksKeybinding: string;
 }
-/** Configuration for MCP (Model Context Protocol) server integration. */
+/** Configuration for the standalone MCP (Model Context Protocol) server. */
 export interface McpConfig {
-    /** Whether the MCP server is enabled. */
+    /** Whether to auto-start the MCP server on plugin load. Default false — agent tools run in-process regardless. Set true only when an external MCP client needs to connect via `opencode-rag mcp`. */
     enabled: boolean;
 }
 /** Configuration for automatic self-updates. */
 export interface AutoUpdateConfig {
-    /** Whether auto-update checking is enabled. */
+    /** Whether update checking is enabled (defaults to true). */
     enabled: boolean;
+    /** When true, automatically install a newer release on startup (default false). */
+    autoInstall?: boolean;
+    /** Cooldown window (ms) before re-attempting the same version (default 3 600 000 = 1h). */
+    cooldownMs?: number;
+    /** Back off after this many consecutive failures (default 3). */
+    maxConsecutiveFailures?: number;
 }
 /** Configuration for post-retrieval context window optimization (adjacent merge, similarity dedup, file diversity cap). */
 export interface ContextOptimizationConfig {
@@ -251,6 +264,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,75 @@ 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,
+        enabled: false,
     },
     autoUpdate: {
-        enabled: false,
+        enabled: true,
+        autoInstall: false,
+        cooldownMs: 3_600_000,
+        maxConsecutiveFailures: 3,
     },
     ui: {
         port: 3210,
@@ -215,7 +279,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 +397,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 +465,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);