/doc reports documentationMode as disabled although the project config enables it (OpenCode 2.0.32 / plugin 2.9.0)

Summary

The /doc command reports that documentation mode is disabled, even though documentationMode.enabled is explicitly set to true in the project-root opencode-rag.json.

Loading that configuration directly through the locally installed plugin's config loader returns documentationMode.enabled === true. However, the /doc handler inside OpenCode still reports the mode as disabled.

A full restart of OpenCode does not resolve the issue. Wiki functionality works in the same project.

Environment

OS: Windows
Shell: PowerShell / Git Bash
OpenCode: 2.0.32
opencode-rag CLI: 2.9.0
Project-local opencode-rag-plugin: 2.9.0
Initial setup performed using opencode-rag setup and opencode-rag index

Relevant configuration

The project-root opencode-rag.json contains:

{
  "wikiMode": {
    "enabled": true
  },
  "documentationMode": {
    "enabled": true,
    "batchSize": 5
  }
}

This is an excerpt, not the complete configuration.

There are no additional configuration files at:

.opencode/opencode-rag.json
.opencode/rag.json

Steps to reproduce

Set up and index the project with OpenCodeRAG.
Enable documentationMode in the project-root opencode-rag.json.
Fully restart OpenCode.
Submit /doc as a chat message, ignoring the UI indication that it is not a recognized slash command.

Actual behavior

The following message appears:

Documentation mode is not enabled. Set documentationMode.enabled to true in opencode-rag.json.

The agent subsequently reads the configuration file, confirms that the setting is already true, and suggests that the notification may be stale. However, that explanation does not resolve the issue: /doc still reports documentation mode as disabled after restarting OpenCode.

Expected behavior

The /doc handler should recognize that documentation mode is enabled in the project configuration and proceed with the corresponding functionality instead of displaying the disabled-mode message.

Diagnostic checks already performed

1. Verified the project-local plugin version

node -p "require('./.opencode/node_modules/opencode-rag-plugin/package.json').version"

Output:

2.9.0

The CLI command opencode-rag --version also returns 2.9.0.

2. Tested configuration loading using the installed package

Executed from the project root:

node --input-type=module -e "import {findConfigFile,loadConfig} from './.opencode/node_modules/opencode-rag-plugin/dist/core/config.js'; const p=findConfigFile(process.cwd()); console.log('Config:',p); if(p) console.log('Documentation enabled:',loadConfig(p).documentationMode?.enabled);"

The command finds the correct project-root opencode-rag.json and prints:

Documentation enabled: true

It also emits this warning:

[opencode-rag] Config warning: decision.provider "openai" is not supported yet — only "ollama" (tev1 via /v1/systemone)

The loader still completes and returns true for documentation mode. Including the warning here for completeness; I have not established whether it is related.

3. Verified the plugin entry point

The file .opencode/plugins/opencode-rag/index.js contains:

import plugin from "../../node_modules/opencode-rag-plugin/dist/plugin-entry.js";
export default plugin;

4. Restarted and checked the log

Fully restarting OpenCode does not resolve the issue.
I did not notice an obvious related error in .opencode/opencode-rag.log.
No modifications have been made to the installed plugin code.

Additional context

The OpenCodeRAG sidebar is visible, the skill can be loaded, and wiki functionality works.

The unresolved discrepancy is between the successful standalone configuration-loading test and the disabled-mode message produced by /doc inside OpenCode.

Could you help determine why the /doc handler does not recognize the enabled setting? Please let me know if there is a supported diagnostic command or logging option that would help investigate this without modifying the installed plugin code.

fix(plugin): honour a documentationMode enabled after plugin boot (is…

Thanks for the extremely thorough report — the standalone loadConfig() check you ran was the detail that made this diagnosable, because it proved the config file was fine and the discrepancy had to live inside the running plugin.

Root cause

ragPlugin dropped its own config-cache entry after loading the config:

configCache.delete(input.directory);              // before loading — intentional
const cfg = await getConfig(input.directory);     // stores the cache entry
...
configCache.delete(input.directory);              // <- after loading: removed the entry it just stored

refreshConfig() (the live re-read behind getEffectiveCfg()) starts with if (!cached) return fallback — so with the entry gone it returned the startup snapshot for the lifetime of the process. The config file was correct; the plugin simply never looked at it again.

That also explains the two things that made this look impossible:

Why a restart didn't help. OpenCode 2 keeps plugins in a shared background service that survives TUI restarts, so closing and reopening the TUI does not necessarily re-run plugin setup(). The service still held the old snapshot. opencode service restart is what actually reloads it.
Why wiki mode worked. wikiMode.enabled defaults to true, documentationMode.enabled defaults to false. A stale snapshot therefore still looks "enabled" for wiki and "disabled" for /doc — the same bug, but only one of them is visible.

The warning you saw (decision.provider "openai" is not supported yet) is unrelated and expected — decision models currently only support ollama/tev1. Thanks for including it anyway; that's exactly the right instinct.

Fixed in 2.11.2

The stray configCache.delete is gone, so mtime-based live reload works again: editing opencode-rag.json no longer needs a restart at all.
/doc, /wiki and /quirk are cold paths and now read the workspace config straight from disk instead of trusting any snapshot, so they always agree with the file you just saved.

The "not enabled" reply now names the exact file and directories it resolved, and each plugin instance logs one line, so a different cause (a shadowing .opencode/opencode-rag.json, or a session directory that isn't the directory you edited) is immediately visible instead of looking like a stale notification:

Documentation mode is not enabled.

Set `documentationMode.enabled` to `true` in `C:\proj\opencode-rag.json`.

Config resolution — directory: C:\proj; workspace: C:\proj\opencode-rag.json; global: C:\Users\you\.config\opencode\opencode-rag.json.

[config] Config: directory: C:\proj; workspace: C:\proj\opencode-rag.json; global: ...; documentationMode.enabled=true; wikiMode.enabled=true

Regression test: boots the plugin, rewrites the config, and asserts both the /doc reply and the injected documentation system prompt flip without a restart. It fails if the cache delete is restored.

Upgrading

npm install -g opencode-rag-plugin@latest    # or your project-local install
opencode service restart                     # required once, to unload the stale snapshot

Then /doc should pick up documentationMode.enabled: true immediately — including edits made while OpenCode is running.

One small note while you're in there: the root-level opencode-rag.json is still read for compatibility, but .opencode/opencode-rag.json is the canonical location now. Running opencode-rag init migrates the old file for you.

Closing this since 2.11.2 carries the fix — but if you still see the message after upgrading and restarting the service, please paste the new Config resolution — … line and I'll take another look.

Navigation Menu

Repository navigation

/doc reports documentationMode as disabled although the project config enables it (OpenCode 2.0.32 / plugin 2.9.0) #36

Summary

Environment

Relevant configuration

Steps to reproduce

Actual behavior

Expected behavior

Diagnostic checks already performed

1. Verified the project-local plugin version

2. Tested configuration loading using the installed package

3. Verified the plugin entry point

4. Restarted and checked the log

Additional context

Root cause

Fixed in 2.11.2

Upgrading

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

/doc reports documentationMode as disabled although the project config enables it (OpenCode 2.0.32 / plugin 2.9.0) #36

Description

Summary

Environment

Relevant configuration

Steps to reproduce

Actual behavior

Expected behavior

Diagnostic checks already performed

1. Verified the project-local plugin version

2. Tested configuration loading using the installed package

3. Verified the plugin entry point

4. Restarted and checked the log

Additional context

Activity

MrDoe commented on Oct 28, 2026

Root cause

Fixed in 2.11.2

Upgrading

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions