docs: fix orbit_troubleshooting.md redirect and create a real troubleshooting page

What does this MR do and why?

Fixes the redirect in docs/source/orbit_troubleshooting.md: it was sending users to remote/_index.md (the Remote landing page), which has no troubleshooting content. Creates docs/source/troubleshooting.md with the 4 Orbit Local and 3 Orbit Remote errors described in the issue.

Closes #661 (closed)

Testing

lint:docs equivalent (markdownlint-cli2 0.22.1, vale 3.14.2, lychee 0.24.2):

  • markdownlint-cli2: 0 errors
  • vale: 0 errors, 0 warnings, 0 suggestions
  • lychee offline: 6 total, 4 OK, 0 errors, 2 excluded (gitlab.com domain per lychee.toml)
  • Relative links local/_index.md and remote/_index.md confirmed to exist
  • Redirect target troubleshooting.md exists in docs/source/

Performance Analysis

  • This merge request does not introduce any performance regression. If a performance regression is expected, explain why.
Agent context — long-form analysis, file-by-file walkthroughs, profiler output, alternatives considered

Error message verification against orbit 0.74.0 binary and source:

  • no local graph found at ~/.orbit/graph.duckdb — confirmed from binary run and crates/orbit-local/src/main.rs:238. Issue referenced an older message ("Table 'Definition' does not exist"); the new page documents the current message with a backward-compat note covering users on older versions.
  • error: unrecognized subcommand 'mcp' — confirmed exact wording from binary.
  • IO Error: Could not set lock on file — wording from crates/duckdb-client/src/client.rs:19; orbit auto-retries 10× with exponential backoff before surfacing this error.

remove_date: '2026-08-07' in the redirect file is unchanged — the 3-month window was already running from the original redirect creation.

AI-assisted: authored with Claude Code (claude-sonnet-4-6). All content reviewed and verified by human contributor (bcode0127) against the orbit 0.74.0 binary and source before submission.

%{all_commits}

Merge request reports

Loading
Loading