[nightshift] doc-drift: Documentation drift analysis

[nightshift-micr]

Automated analysis by Nightshift v3 (GLM 5.1)

---

Doc Drift Detector Report — Microck/opencode-studio

Repository: /home/ubuntu/nightshift-workspace/opencode-studio-clone
Analysis Date: 2026-04-12
Tool: Hermes Agent — Doc Drift Detector

---

Executive Summary

Analysis identified 20 documentation drift issues across the codebase, ranging from stale/outdated documentation to code-after-module.exports dead code. The most critical findings are: a duplicated CHANGELOG entry, a stale npm package reference in the landing page, dead code after module.exports, undocumented UI routes, and a hardcoded placeholder Dropbox client ID in production code.

---

Findings

P0 — Critical (Breaking / Misleading)

1. CHANGELOG Contains Duplicate Entries

• File: CHANGELOG.md (lines 5-11, 32-41)
• Issue: Version [1.16.0] - 2026-01-30 appears twice with identical content (lines 5-10 and lines 11-16). Version [1.14.5] - 2026-01-17 also appears three times (lines 32-36, 37-41, 58-62). These duplicates make the changelog unreliable as a historical record.
• Impact: Users and maintainers cannot trust the changelog to accurately reflect what changed in each release.
• Fix: Remove the duplicate entries. Review git history to determine which entries are canonical.

2. Dead Code After module.exports — Routes Never Executed

• File: server/index.js (lines 4637-4667)
• Issue: Two API route handlers (GET /api/prompts/global and POST /api/prompts/global) are defined after the module.exports = { ... } statement on line 4627. In CommonJS modules, code after module.exports is still reachable via app.get()/app.post() because Express routes are registered eagerly — however, these routes are only reachable if require.main === module triggers startServer(), which calls app.listen(). If the module is imported (e.g., by tests), these routes are registered but the server may not start. More importantly, this is a code organization smell — the module.exports block sits between the preset routes and the prompt routes, breaking the logical flow.
• Impact: Confusing for developers. The prompts API works today but could easily break if the module.exports block is moved or refactored.
• Fix: Move the two /api/prompts/global route definitions above the module.exports block (e.g., after line 4603).

---

P1 — High (Functional Discrepancy)

3. Stale npm Package Name in Landing Page

• File: client-next/src/components/app-shell.tsx (lines 157-158)
• Issue: The disconnected landing page links to https://www.npmjs.com/package/opencode-studio (line 157), but the actual npm package name is opencode-studio-server (per server/package.json line 2). The opencode-studio npm package either doesn't exist or is a different package.
• Impact: Users clicking the "npm" link on the landing page will be directed to the wrong (or non-existent) package.
• Fix: Change the URL to https://www.npmjs.com/package/opencode-studio-server.

4. Hardcoded Server Version in Landing Page — Doesn't Match package.json

• File: client-next/src/components/app-shell.tsx (lines 132, 171)
• Issue: The landing page hardcodes opencode-studio-server@2.2.1 in two places, but the actual server version is 2.2.2 (per server/package.json line 3). The MIN_SERVER_VERSION in api.ts (line 46) also requires 2.2.2.
• Impact: Users who follow the landing page instructions will install a version that the client will flag as incompatible.
• Fix: Use a dynamic reference or update the hardcoded version to 2.2.2. Better yet, derive it from package.json at build time.

5. Dropbox OAuth Redirect URI Uses Wrong Port

• File: server/index.js (lines 1786, 1808)
• Issue: The default Dropbox OAuth redirect URI is http://localhost:3000/settings, but the frontend actually runs on port 1080+ (auto-detected). Port 3000 is never used by this application.
• Impact: Dropbox OAuth flow will fail if no explicit redirect_uri is passed from the client, because the redirect will go to port 3000 where nothing is listening.
• Fix: Change the default redirect URI to http://localhost:1080/settings (or better, make it configurable/dynamic).

6. README Missing Multiple UI Routes

• File: README.md (lines 86-96)

• Issue: The "Usage" route table in the README lists only 7 routes (/mcp, /profiles, /skills, /plugins, /commands, /usage, /auth, /settings). However, the actual sidebar navigation (client-next/src/components/sidebar.tsx lines 30-44) has 14 routes including:

  • /agents — Agent management page
  • /logs — Real-time log viewer
  • /rules — Project rules editor (AGENTS.md / CLAUDE.md)
  • /config — Raw JSON config editor
  • /quickstart — Quickstart guide
  • /settings/code — Code settings sub-page

  None of these routes are mentioned in the README's usage table.

• Impact: Users won't know these features exist from reading the documentation.

• Fix: Add the missing routes to the usage table in the README.

7. README Features List Missing Key Features

• File: README.md (lines 51-62)
• Issue: The features list omits several implemented features:
  • Agents: Full agent management with create/edit/delete/toggle, markdown support, permission editor (/agents page, /api/agents endpoints)
  • Logs: Real-time log streaming via SSE (/logs page, /api/logs/stream endpoint)
  • Rules: Project rules editor for AGENTS.md / CLAUDE.md (/rules page)
  • Raw Config: Direct JSON editor for opencode.json (/config page)
  • Cloud Sync: Dropbox push/pull/auto-sync (/api/sync/* endpoints)
  • System Tools Detection: Checks for installed dev tools (/api/system/tools)
  • Presets: Create/apply presets for skills, plugins, and MCPs (/api/presets endpoints)
• Impact: The README significantly undersells the application's capabilities.
• Fix: Add these features to the README features list.

---

P2 — Medium (Stale / Outdated)

8. client-next/README.md Claims "Geist font" — Actually Uses 3 Fonts

• File: client-next/README.md (line 29)
• Issue: The tech stack section says "Geist font" but the actual font setup (from client-next/src/app/layout.tsx lines 2-29 and CHANGELOG.md line 207) uses Rethink Sans for headings, Geist for body text, and Commit Mono for code. The @fontsource/ibm-plex-mono dependency is also installed in package.json (line 13), suggesting a prior font migration that left a stale dependency.
• Impact: Misleading for contributors trying to understand the font setup.
• Fix: Update to "Rethink Sans, Geist, and Commit Mono fonts".

9. server/README.md Lists Only 4 Features — Server Has 30+ API Endpoints

• File: server/README.md (lines 29-35)
• Issue: The server README lists only 4 features (Protocol Handler, Config Management, MCP Management, Auth). The actual server implements:
  • Skills CRUD + toggle
  • Plugins CRUD + toggle
  • Commands management
  • Agents CRUD + toggle (markdown + JSON)
  • Presets management
  • Usage statistics
  • Backup/restore
  • GitHub backup/restore
  • Cloud sync (Dropbox)
  • Log streaming (SSE)
  • System tools detection
  • Project rules (AGENTS.md/CLAUDE.md)
  • Global prompts (OPENCODE.md)
  • Multi-provider auth with account pools
  • Cooldown management
  • Profile management
• Impact: The server README severely under-represents the server's capabilities.
• Fix: Update the server README feature list to match actual functionality.

10. CHANGELOG v0.1.0 Claims Initial Release Date of 2024-01-01

• File: CHANGELOG.md (line 228)
• Issue: The initial release is dated 2024-01-01, but all other releases start from 2026-01-05. This is almost certainly a placeholder/auto-generated date, not the actual release date.
• Impact: Misleading historical record.
• Fix: Correct to the actual initial release date.

11. Hardcoded Placeholder Dropbox Client ID in Production Code

• File: server/index.js (line 1683)
• Issue: const DROPBOX_CLIENT_ID = 'your-dropbox-app-key'; is a literal placeholder string, not a real app key. The .env.example in server/ only mentions Gemini credentials, not Dropbox. The Dropbox sync feature is fully implemented (push/pull/auto endpoints) but will fail at runtime because the client ID is a placeholder.
• Impact: Dropbox sync is documented and implemented but completely non-functional without a real app key. No mechanism is provided for users to configure it.
• Fix: Either (a) remove the Dropbox feature if not intended for production, (b) add DROPBOX_CLIENT_ID to .env.example and load it from environment, or (c) document how to configure it.

12. Auth Provider List Inconsistency — together Included in Server But Not in API Response

• File: server/index.js (lines 2802-2816 vs 2890, 4607)
• Issue: The provider list in GET /api/auth/providers (line 2802) returns 11 providers (no together), but GET /api/auth/profiles (line 2890) and startServer() (line 4607) include together in their provider lists (12 providers). This means together auth profiles can be imported and managed internally, but users can't see or interact with together from the auth providers UI.
• Impact: Silent inconsistency — Together profiles are managed but not visible in the auth UI.
• Fix: Add together to the /api/auth/providers response, or remove it from the other two lists.

13. startServer() Provider List Doesn't Include groq

• File: server/index.js (line 4607)
• Issue: startServer() calls importCurrentAuthToPool(p) for providers including together but not groq. However, groq appears in the auth providers list (line 2812). This means Groq auth is never auto-imported into the pool on startup.
• Impact: Groq authentication profiles won't be automatically detected and pooled on server start.
• Fix: Add 'groq' to the provider array in startServer().

---

P3 — Low (Minor / Cosmetic)

14. client-next/README.md Links to Wrong GitHub Organization

• File: client-next/README.md (line 3)
• Issue: Links to https://github.com/opencode-ai/opencode (opencode-ai org), but this repo is under the Microck org. While this might be intentional (linking to the upstream opencode CLI tool), it could confuse contributors.
• Impact: Minor — potential contributor confusion.
• Fix: Consider adding clarifying text like "for Opencode CLI".

15. README Claims "oh my opencode model preferences" — Feature Name Is Vague

• File: README.md (line 62)
• Issue: The settings feature description says "oh my opencode model preferences" but there's no explanation of what "oh my opencode" is. The code implements this as a model preference system stored in oh-my-opencode.json with agent-level model selection. A user reading this wouldn't understand what it does.
• Impact: Users won't understand this feature from the README alone.
• Fix: Change to "oh my opencode: per-agent model preferences and thinking/reasoning configuration".

16. Project Structure in README Doesn't Mention Key Directories

• File: README.md (lines 165-176)
• Issue: The project structure tree is simplified and omits:
  • client-next/src/app/agents/ — agents page
  • client-next/src/app/logs/ — logs page
  • client-next/src/app/rules/ — rules page
  • client-next/src/app/config/ — raw config page
  • client-next/src/app/quickstart/ — quickstart page
  • client-next/src/app/editor/ — editor page
  • server/profile-manager.js — profile management module
  • server/cli.js — CLI entry point
  • server/register-protocol.js — protocol handler registration
• Impact: Minor — developers exploring the codebase won't see the full structure.
• Fix: Update the tree to include the missing entries or add a note that it's simplified.

17. README Deep Link Port Reference Is Inconsistent

• File: README.md (line 122)
• Issue: The deep link documentation says opencodestudio://launch?open=local opens localhost:1080+, but the + suffix is informal. The code (client-next/dev-with-port.js) starts at port 1080 and auto-detects upward, but the README doesn't explain this clearly. The troubleshooting table (line 190) correctly mentions "frontend 1080+" but the deep link section is less precise.
• Impact: Minor — users may not understand the port auto-detection behavior.
• Fix: Add a note in the deep links section explaining that 1080+ means starting at 1080 with auto-detection.

18. client-next/package.json Has Unused @fontsource/ibm-plex-mono Dependency

• File: client-next/package.json (line 13)
• Issue: The @fontsource/ibm-plex-mono package is listed as a dependency, but the codebase uses local CommitMono fonts (loaded via next/font/local in layout.tsx lines 21-29). The CHANGELOG for v1.0.4 (line 207) confirms the switch from IBM Plex Mono to Commit Mono, but the old dependency was never removed.
• Impact: Unnecessary dependency increases install size.
• Fix: Remove @fontsource/ibm-plex-mono from client-next/package.json.

19. CHANGELOG Version Ordering Is Inconsistent

• File: CHANGELOG.md
• Issue: The changelog is supposed to be in reverse chronological order but has issues:
  • 1.14.5 appears three times (lines 32-36, 37-41, 58-62)
  • 1.14.7 appears twice (lines 42-45, 52-57)
  • The sequence jumps: 1.14.8 → 1.14.7 → 1.14.5 → 1.14.4 (lines 47-66)
• Impact: Confusing to read; suggests the changelog may not be auto-generated.
• Fix: Sort entries in strict reverse chronological order, deduplicate.

20. README "How It Works" Mermaid Diagram Oversimplified

• File: README.md (lines 68-75)
• Issue: The mermaid diagram shows Express API :1920+ reading/writing to ~/.config/opencode/, but the actual config discovery searches multiple paths (~/.config/opencode/, ~/.local/share/opencode/, ~/.opencode/, %APPDATA%/opencode/, WSL paths). The diagram only shows the primary path. Additionally, the server also reads/writes to ~/.config/opencode-studio/ for studio config, which is not shown.
• Impact: Minor — developers may not understand the multi-path discovery system.
• Fix: Add a note below the diagram mentioning multiple search paths and the studio config location.

---

Summary Table

Severity	Count	Description
P0	2	Duplicate CHANGELOG entries; dead code after module.exports
P1	5	Stale npm link; hardcoded wrong version; wrong OAuth redirect port; missing routes in docs; missing features in docs
P2	6	Stale font docs; incomplete server README; wrong initial release date; placeholder Dropbox key; provider list inconsistency; missing groq in startup import
P3	7	Wrong GitHub link; vague feature name; incomplete project tree; port notation; unused dependency; changelog ordering; oversimplified diagram

---

Recommendations

1. Immediate (P0): Remove duplicate CHANGELOG entries and move the /api/prompts/global routes above module.exports.
2. Short-term (P1): Fix the npm link, update the hardcoded version, fix the Dropbox redirect URI, and update the README to document all 14 UI routes and missing features.
3. Medium-term (P2): Update both READMEs to reflect actual capabilities, add groq to the startup provider import, resolve the together provider inconsistency, and fix the Dropbox client ID to use an environment variable.
4. Low-priority (P3): Remove unused @fontsource/ibm-plex-mono dependency, clean up changelog ordering, and improve the project structure diagram.