[oyi77]

Replaces #3784 as a clean, non-contaminated PR branched from release/v3.8.27.

Updates the Plugin SDK reference documentation with:

• Typed API docs for IPC, DB, and UI extension interfaces
• Corrected code examples (searchMarketplace takes string, testPlugin needs validateManifest)
• Resolved merge conflict markers in PLUGIN_SDK.md

Only docs/plugins/ changes, no unrelated churn.

Supersedes: #3784

[gemini-code-assist]

Code Review

This pull request adds comprehensive documentation for OmniRoute's plugin system, including new guides for plugin development and the marketplace, alongside updates to the Plugin SDK reference. The feedback highlights critical issues in the marketplace documentation examples where asynchronous functions (listMarketplacePlugins, searchMarketplace, and getMarketplaceEntry) are not awaited, which would cause runtime errors or logical failures in user implementations.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The listMarketplacePlugins function is asynchronous and returns a Promise. It must be awaited to retrieve the actual array of plugins, otherwise iterating over it with for...of will throw a TypeError at runtime.

Suggested change

	const plugins = listMarketplacePlugins();
	const plugins = await listMarketplacePlugins();

[gemini-code-assist]

The searchMarketplace function is asynchronous and returns a Promise. Both calls should be awaited to obtain the filtered plugin lists.

Suggested change

	const loggingPlugins = searchMarketplace("logging");
	const securityPlugins = searchMarketplace("security");
	const loggingPlugins = await searchMarketplace("logging");
	const securityPlugins = await searchMarketplace("security");

[gemini-code-assist]

The getMarketplaceEntry function is asynchronous and returns a Promise. It must be awaited, otherwise the subsequent if (entry) check will always evaluate to true because a Promise object is truthy.

Suggested change

	const entry = getMarketplaceEntry("request-logger");
	const entry = await getMarketplaceEntry("request-logger");

[diegosouzapw]

Thanks @oyi77 — the cleanup (branched fresh from release, corrected examples) is appreciated, and the marketplace/manifest parts map to real code (src/lib/plugins/marketplace.ts, manifest.ts). Two blockers before this can land:

1. Documents hooks that don't exist yet. check:fabricated-docs flags PLUGIN_SDK.md onPluginMessage (line ~45) and onRender (line ~52) — neither is in BUILTIN_EVENTS (hooks.ts) because the plugin IPC (feat(plugins): plugin IPC/runtime core with permission model (split from #3668) #3783) and UI-extensibility (feat(plugins): plugin UI-extensibility — admin pages, render routes, sidebar (split from #3668) #3785) PRs that define them are not merged. Documenting non-existent hooks in the SDK reference will mislead users. Please either (a) trim the SDK reference to only the hooks/APIs that exist on release/v3.8.27 today, or (b) land feat(plugins): plugin IPC/runtime core with permission model (split from #3668) #3783/feat(plugins): plugin UI-extensibility — admin pages, render routes, sidebar (split from #3668) #3785 first, then document them.
2. Stray artifact: the PR includes .omo/run-continuation/ses_13df7fbe7ffeFEg7W8RPT6aaOD.json (an agent-session file) — please drop it from the branch.

Also FYI: #4006 and #4007 have identical diffs (both contain all three docs) — one of them is redundant; keep a single PR. Rebase onto current release/v3.8.27 when you re-cut. Happy to merge once it documents only merged APIs + the artifact is gone. 🙏

[oyi77]

Closing in favor of #4007 — both PRs had identical diffs. Consolidated into docs/plugin-dev-guide (#4007) with fixes:

• Stray artifact .omo/run-continuation/ removed
• onPluginMessage/ onRender trimmed from PLUGIN_SDK.md (not in BUILTIN_EVENTS — feat(plugins): plugin IPC/runtime core with permission model (split from #3668) #3783/feat(plugins): plugin UI-extensibility — admin pages, render routes, sidebar (split from #3668) #3785 not merged)
• Rebased onto release/v3.8.28

All changes are now in #4007.

[oyi77]

Closing — consolidated into #4007. See comment above for details.