[ovehbe]

Summary

• Replaces the custom /docs stack (hand-rolled Markdown pipeline, marked, DOMPurify, regex HTML post-processing, and generated docs-auto-generated.ts) with Fumadocs (fumadocs-core, fumadocs-ui, fumadocs-mdx).
• Docs are loaded from docs/{architecture,guides,reference,frameworks,routing,security,compression,ops}/ via source.config.ts and src/lib/source.ts, with section ordering from per-folder meta.json files.
• Routes move from flat /docs/[slug] to nested /docs/[section]/[slug] (e.g. /docs/guides/setup-guide), with permanent redirects in next.config.mjs for legacy flat URLs and bookmarks.
• Adds Fumadocs layout (DocsLayout, dark default theme), GitHub nav link, and search at /docs/api/search (kept under /docs/ so management auth on /api/* does not block search).
• Removes obsolete docs UI modules (DocCodeBlocks, DocsSearchClient, DocsSidebarClient, Mermaid client, content.ts, generate-docs-index.mjs) and wires Fumadocs CSS in globals.css.
• Fixes the prior prose-class regex bug indirectly by dropping the custom HTML injector; MDX is rendered by Fumadocs instead.

Validation

• npm run lint
• npm run test:unit
• npm run test:coverage
• Coverage is still >= 60% for statements, lines, functions, and branches
• SonarQube PR analysis is green or any remaining issues are explicitly documented below

Tests Added Or Updated

• Removed: tests/unit/docs-site-overhaul.test.ts (covered the old generated index, sidebar grouping, and custom search pipeline — no longer applicable).
• No new automated tests in this PR; docs routing/search should be validated manually (see Reviewer Notes).

Coverage Notes

• Production code under src/app/docs/ and src/lib/source.ts changed, but behavior is largely delegated to Fumadocs. Coverage may shift because the large removed test file no longer exercises those paths.
• Repo gate for merged work remains 75/75/75/70 per CONTRIBUTING.md; confirm npm run test:coverage on CI before merge.
• If coverage drops only because obsolete docs tests were deleted, follow-up can add focused tests for redirects and /docs/api/search if we want regression guards.

Reviewer Notes

• Manual smoke test (recommended):
  • npm run dev → open /docs, browse each sidebar section, open a few deep pages (tables, code blocks, internal links).
  • Confirm search returns results (queries hit /docs/api/search, not /api/search).
  • Hit a few legacy URLs (e.g. /docs/setup-guide, /docs/mcp-server) and confirm 308/301 to nested paths.
  • npm run build — Fumadocs MDX generation must succeed.
• URL change: External links to flat /docs/<slug> should still work via redirects; update bookmarks to nested URLs when convenient.
• Out of scope for this PR: full doc content polish, i18n doc trees under docs/i18n/, and restoring removed custom widgets (Mermaid client, “What’s New” block) — can be follow-ups on Fumadocs if needed.
• Dependencies: adds fumadocs-core, fumadocs-ui, fumadocs-mdx; next.config.mjs chains createMDX() with existing withNextIntl().

[kilo-code-bot]

Kilo Code Review could not run — your account is out of credits.

Add credits or switch to a free model to enable reviews on this change.

[gemini-code-assist]

Code Review

This pull request migrates the documentation infrastructure to Fumadocs, removing legacy components and updating the Next.js configuration. It also introduces updates to the DeepSeek Web executor, specifically regarding SSE transformation and prompt construction. Feedback highlights a critical regression in conversation history handling that breaks multi-turn chat, as well as cache key inconsistencies and hardcoded environment-specific IPs. Furthermore, the reviewer noted a violation of repository rules due to the absence of new unit tests for the production logic changes in the streaming engine.

[gemini-code-assist]

The new messagesToPrompt implementation introduces a regression in conversation history handling. It currently only includes system messages and the last user message, discarding all intermediate user and assistant turns. This will break multi-turn chat context for the DeepSeek Web executor. Additionally, the broad regex for stripping images might remove useful context if the model is expected to handle markdown image markers.

function messagesToPrompt(messages: Array<{ role: string; content: string }>): string {
  const extractText = (content: unknown): string => {
    if (Array.isArray(content)) {
      return (content as any[])
        .filter((item: any) => item.type === "text")
        .map((item: any) => item.text)
        .join("\n");
    }
    return String(content || "");
  };

  if (messages.length === 0) return "";

  const parts: string[] = [];
  for (const m of messages) {
    const text = extractText(m.content).trim();
    if (!text) continue;

    if (m.role === "system") {
      parts.push(`[System]: ${text}`);
    } else if (m.role === "assistant") {
      parts.push(`[Assistant]: ${text}`);
    } else {
      parts.push(text);
    }
  }

  return parts.join("\n\n").replace(/!\[.+\]\(.+\)/g, "");
}

[gemini-code-assist]

There is a cache key mismatch when clearing the session cache. In createSession (line 435), the key is constructed as connectionId || accessToken. However, here it defaults to an empty string if connectionId is missing, which will fail to clear the cache entry associated with the accessToken fallback.

Suggested change

	sessionCache.delete((rawCreds.connectionId as string) || "");
	sessionCache.delete((rawCreds.connectionId as string) || accessToken);

[gemini-code-assist]

Similar to the issue at line 605, the session cache deletion key should match the logic used in createSession to ensure the correct entry is cleared when connectionId is absent.

Suggested change

	sessionCache.delete((rawCreds.connectionId as string) || "");
	sessionCache.delete((rawCreds.connectionId as string) || accessToken);

[gemini-code-assist]

Hardcoding specific local network IPs like 192.168.0.111 in allowedDevOrigins is environment-specific and should generally be avoided in shared configuration files. Consider using environment variables if this is required for specific development setups.

Suggested change

	allowedDevOrigins: ["localhost", "127.0.0.1", "192.168.0.250", "192.168.0.111"],
	allowedDevOrigins: ["localhost", "127.0.0.1", "192.168.0.250"],

[gemini-code-assist]

Significant logic changes have been made to open-sse/executors/deepseek-web.ts (handling APPEND operations, bare tokens, and a new prompt builder), but no new automated tests were added to cover these paths. Per Repository Rule 9, changes to production code in open-sse/ must include tests. Please add unit tests to verify the new SSE transformation logic and the prompt builder.

References

1. Always include tests when changing production code (src/, open-sse/, electron/, bin/). ^(link)

[diegosouzapw]

✅ Merged manually into release/v3.8.3 via local fast-forward merge (commit cbec5e0).

All changes from this PR are now integrated:

• Fumadocs MDX migration with nested routes
• 50+ URL redirects for backward compatibility
• Search API at /docs/api/search
• DeepSeek Web executor improvements (APPEND fragments, bare tokens, prompt builder)

GitHub's squash algorithm couldn't compute a clean squash due to the deep commit history, so the merge was done locally and pushed to the release branch.

[diegosouzapw]

Closing — content already integrated into release/v3.8.3 via local merge.

[diegosouzapw]

🎉 Thank you @ovehbe!

Your Fumadocs MDX migration has been squash-merged into release/v3.8.3 and will ship in the upcoming v3.8.3 release.

What was included:

• Full migration from custom docs engine to Fumadocs with nested routes ([...slug])
• Server-side search API at /docs/api/search
• source.config.ts with 8 doc section patterns
• meta.json navigation files for structured sidebar
• 50+ permanent redirects for backward URL compatibility
• Removal of 7 legacy custom components (~1,500 lines)

Minor adjustments applied during merge:

• Conflict resolution with release/v3.8.3 (DeepSeek executor, next.config.mjs redirects)
• Kept accessToken fallback for session cache eviction (aligned with fix(deepseek-web): re-apply SSE parser, prompt format, and error handling fixes #2616)
• Used non-greedy regex for markdown image stripping

Great work on this infrastructure modernization — it significantly simplifies the docs codebase! 🚀

[herjarsa]

I resolved the merge conflicts between this PR and origin/main. The resolution is pushed to herjarsa/fix/pr-2614-conflicts for easy cherry-picking.

Conflicts resolved:

File	Resolution
next.config.mjs	Combined both sides — kept mains context + added fumadocs-uiandfumadocs-coretotranspilePackages`
docs/compression/COMPRESSION_GUIDE.md	Took main (emoji + v3.8.2 metadata)
docs/guides/DOCKER_GUIDE.md	Took main (emoji + v3.8.2 metadata)
docs/guides/SETUP_GUIDE.md	Took main (emoji + v3.8.2 metadata)
docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md	Took main (emoji + v3.8.2 metadata)
docs/ops/PROXY_GUIDE.md	Took main (emoji + v3.8.2 metadata)
src/app/docs/lib/docs-auto-generated.ts	Accepted deletion (PR replaces old docs)
tests/unit/docs-site-overhaul.test.ts	Accepted deletion (replaced by Fumadocs)

To update your PR:

git fetch origin
git cherry-pick <hash-from-herjarsa/fix/pr-2614-conflicts>
git push origin feat/docs-fumadocs-migration --force-with-lease

Or rebase directly:

git fetch origin
git rebase origin/main
# next.config.mjs and 5 docs with metadata conflicts need resolution

The commit hash is available from herjarsa/fix/pr-2614-conflicts if you want to cherry-pick the resolution commit.

[redge76]

The file generate-docs-index.mjs was deleted without updating scripts/build/build-next-isolated.mjs.
Now the docker build faild with

 > omniroute@3.8.3 build
0.347 > node scripts/build/build-next-isolated.mjs --webpack
0.347
0.389 [build-next-isolated] Generating docs index...
0.423 node:internal/modules/cjs/loader:1522
0.423   throw err;
0.423   ^
0.423
0.423 Error: Cannot find module '/app/scripts/docs/generate-docs-index.mjs'
0.423     at Module._resolveFilename (node:internal/modules/cjs/loader:1519:15)
0.423     at wrapResolveFilename (node:internal/modules/cjs/loader:1073:27)
0.423     at defaultResolveImplForCJSLoading (node:internal/modules/cjs/loader:1097:10)
0.423     at resolveForCJSWithHooks (node:internal/modules/cjs/loader:1124:12)
0.423     at Module._load (node:internal/modules/cjs/loader:1296:5)
0.423     at wrapModuleLoad (node:internal/modules/cjs/loader:255:19)
0.423     at Module.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:154:5)
0.423     at node:internal/main/run_main_module:33:47 {
0.423   code: 'MODULE_NOT_FOUND',
0.423   requireStack: []
0.423 }
0.423
0.423 Node.js v26.2.0
0.426 [build-next-isolated] Docs index generation failed (non-fatal): Command failed: node scripts/docs/generate-docs-index.mjs
0.849 Attention: Next.js now collects completely anonymous telemetry regarding usage.
0.849 This information is used to shape Next.js' roadmap and prioritize features.
0.849 You can learn more, including how to opt-out if you'd not like to participate in this anonymous program, by visiting the following URL:
0.849 https://nextjs.org/telemetry
0.849