Draft: docs(orbit): rebuild user docs around one CLI quickstart [skip ci]

Michael Angelo Riverarequested to merge
michaelangeloio/docs-overhaul into main

What does this MR do and why?

The Orbit docs split one product into Local and Remote trees. A new reader had to choose a mode before running a command. This MR rebuilds the docs as one product with one entry point, the CLI. The landing page leads with a value line and a three-step quickstart, in the style of the old Graphify docs. Contributors can now run the real docs.gitlab.com site locally with mise docs:serve, and CI builds the same site.

Related Issues

Relates to gitlab-org/gitlab#604816 (closed) (GA: Orbit UX item 1, docs overhaul). Relates to #1274 (flat CLI, no Local or Remote modes) and follows up #1237.

How it works

1. One flat section instead of two trees

17 pages replace 29. Every old path keeps a redirect stub, so old links still work.

New page Built from
Landing and quickstart old landing, both getting-started pages, Zach Painter's quickstart draft (MR 2471)
Use cases cookbook
CLI three CLI and glab pages
Connect AI agents, Duo, MCP skill page, Duo page, two MCP pages
Queries, query language, REST API moved from remote/
What GitLab Orbit indexes two schema pages, generated tables
How it works, Security, Troubleshooting compare page, two how-it-works and two troubleshooting pages

The local graph and the server graph are now an implementation detail on "How it works".

2. Schema tables come from the ontology

mise docs:generate fills marker regions in schema.md with one node table per domain and one relationship table. The docs-generated-check job fails when the tables drift. The generator replaces the old query-docs task (docs/mod.rs, docs/tables.rs).

Query examples need no new check. The existing corpus_smoke test already runs every orbit-query fence in the docs through the full pipeline.

3. The real docs site, locally and in CI

scripts/docs/site.sh clones docs-gitlab-com into target/docs-site/ and links this checkout where the site expects it.

mise docs:serve   # live preview at http://localhost:1313/orbit/
mise docs:build   # strict production build, index and nav checks

docs_hugo_build calls the same script, so CI now renders Orbit at its production URLs (/orbit/...). Before, CI rendered all of docs/ at / and did not check the nav.

Testing

Check Result
mise docs:build against the real site pass, 99 pages, no nav warnings
Vale, markdownlint, lychee (now with a quoted glob, so all pages are checked) 0 errors
mise docs:check, cargo test -p xtask, clippy pass, 0 warnings
Browser pass with agent-browser over every nav page, light and dark mode, 390 px mobile 0 console errors, 346 links and anchors resolve, 25 redirects land on the right page
Commands and flags checked against the released orbit v0.139.0 help

The lychee glob fix found a broken link on main (_index.md to remote/indexing.md). The new landing page removes it.

Landing page before and after (1440x900)

Before (production today): the first command is below the fold.

36-orbit-docs-current-landing

After: the value line and the install command are in the first screen.

70-landing-fold-desk

Performance Analysis

No runtime code changes. docs_hugo_build now installs the docs site packages and builds its data, which adds about 2 to 4 minutes. To offset this, the job runs only when docs/source, docs-locale, scripts/docs, or .gitlab-ci.yml change.

  • 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

Numbers. Non-stub pages: 29 to 17. Non-stub words: 30,868 to 26,895. Two pages hold most of the rest. The query language reference has 3,565 words and stays almost as is, because the skill mirrors it. The generated schema page has 3,246. Landing page prose: about 345 words.

Facts corrected while rebuilding. Each one was checked in code or with the binary.

  • Turning on indexing: the UI has a Configure button with a Turn on indexing action, not a Configuration tab.
  • The knowledge_graph feature flag no longer exists in Rails; availability comes from the instance setting. The flag advice is gone from troubleshooting, CLI, and README. History blocks are unchanged.
  • status is cluster health; graph-status is indexing progress.
  • Setup agents are claude, codex, duo, opencode, pi. --hostname does not exist. --yes goes before the command. Setup installs the orbit-cli skill.
  • The local graph lives at ~/.gitlab/orbit/graph.duckdb.
  • 20 supported languages, from the code-graph language list.
  • MCP accepts mcp_orbit, mcp, or read_api scopes.
  • Server-only availability blocks now also list GitLab Self-Managed, which matches the landing history line (19.2.2).

Decisions.

  • No query compile check in xtask: corpus_smoke already covers docs fences and runs on every MR.
  • The table renderer writes Markdown by hand instead of tabled, because padded columns would rewrite every row on each regeneration.
  • No CI cache for the docs site: the yarn and Go caches total about 1.5 GB. A changes: rule limits the job instead.
  • Unreleased CLI behavior (the graph-status origin fallback) is not documented.
  • Dropped on purpose: the click-through demo link (it shows the old Local and Remote split), and the source_tags workaround (the column no longer exists).

Follow-ups, not in this MR.

  • docs-gitlab-com nav MR: the new nav is ready on a local branch. It removes the Local and Remote submenus, renames two labels, and fixes stale Orbit redirects, including a loop between /orbit/queries/ and /orbit/remote/queries/. Merge this MR first. Until the nav MR lands, old nav entries resolve through the redirect stubs.
  • Two ontology edge descriptions show internal details in the generated table (MERGED_AT_COMMIT, REOPENED). Changing them needs a schema bump.
  • CLI error text still names the removed knowledge_graph flag and a Configuration tab (crates/orbit-cli/src/remote/error.rs).
  • glab help orbit still calls the feature an experiment.
  • The ja-jp nav still lists the old tree; the localization team owns it.
  • Not tested live: the Self-Managed sign-in line (glab auth login --hostname) and the "Search or go to > Your work" UI step.

Review. Two adversarial passes for content and code and two browser passes. All findings are fixed or listed above.

Merge request reports