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

Problem

docs/source/orbit_troubleshooting.md contains:

redirect_to: 'remote/_index.md'

This redirects users looking for troubleshooting help to the Orbit Remote landing page — which has no troubleshooting content. There is currently no troubleshooting page anywhere in docs/source/.

A user hitting an error and searching for "troubleshooting" gets redirected to marketing content.

Proposed solution

Two parts:

Part 1 (required): Fix the redirect in docs/source/orbit_troubleshooting.md.

Option A (recommended): Point it to a new docs/source/troubleshooting.md that you create as part of this issue.

Option B: If a proper troubleshooting page already exists in the GitLab docs site at a known URL, point there.

Part 2 (recommended, same MR): Create a minimal docs/source/troubleshooting.md with the most common errors. Starter content from existing sources in the repo:

Orbit Local errors:

  • "Table 'Definition' does not exist" → repo not indexed yet. Run glab orbit local index <path>.
  • "Could not set lock on file" → another orbit process is running. Wait or kill it.
  • "list_contains source_tags" → known bug with certain filter combinations. Workaround: remove the source_tags filter.
  • "unrecognized subcommand 'mcp'" → orbit mcp serve is not yet implemented.

Orbit Remote errors:

  • Exit code 2 → feature flag knowledge_graph not enabled for your group. Contact your GitLab admin.
  • Exit code 3 → not authenticated. Run glab auth login.
  • "insufficient_scope" on MCP endpoint → token needs mcp_orbit scope, not just read_api.

Affected files

  • docs/source/orbit_troubleshooting.md (update redirect)
  • docs/source/troubleshooting.md (new file — recommended)

Validation

  • Navigating to the troubleshooting redirect leads to actual troubleshooting content
  • mise run lint:docs passes
  • Lychee link check passes on all links in the new file

Hackathon notes

  • Difficulty: L0
  • Estimated effort: 1–2h
  • No server needed: Yes
  • Prerequisites: None — Markdown only
  • How to test: Follow the redirect and confirm the destination has troubleshooting content; verify each error message listed in the new page is accurate