fix(docs): repair broken and cross-space docs links sitewide

[ewgenius]

Summary

Fixes broken docs links across Home, Documentation (/docs), API, Help, Changelog, SDKs, and related pages.

GitBook multi-space relatives and stale /broken/pages/... content-refs were resolving to GitHub 404s or dead cards.

Link style: cross-space targets use repo-relative markdown paths (e.g. cloud/monitoring/, ../cloud/portal/apps/api-keys.md) — not absolute https://docs.spice.ai URLs and not leading-slash site paths like /docs/....

Leading-slash paths are treated by GitBook as repository paths, so /docs/monitoring/monitoring became a GitHub fallback to docs/monitoring/monitoring/README.md.

Audit report

Method

• Headed VM browser crawl of Home, /docs, API, Changelog, Help (+ key subpages)
• Full source inventory of /broken/pages/ and cross-space ../ links
• Mapped targets via live llms.txt + HTTP checks of published paths

Confirmed issues (pre-fix)

Home (/)

• Get Started / Monitoring cards → GitHub 404s
• Quick Start steps, API reference, Paid plans, Help Center → GitHub fallbacks

Documentation (/docs)

• Only Get Started + Monitoring cards worked; other feature cards / Use Cases were /broken/pages/... (non-clickable)
• API reference / Help Center → GitHub
• Literal :rocket: shortcodes on cards

Broader

• ~110 /broken/pages/... refs (Changelog + API heavy)
• Help Center cross-space ../portal / ../api/sql-query relatives → GitHub (wrong; portal lives under cloud/)
• API path drift: published runtime paths are under cloud/api/ (site /api/runtime-apis/...)
• Management API index table was entirely /broken/pages/...

Root cause

Multi-space GitBook layout + incorrect link forms:

1. Relative paths that don’t match repo files → GitHub fallback / /broken/pages/...
2. Absolute https://docs.spice.ai/... → breaks preview hosts
3. Leading-slash /docs/... → resolved as repo paths, not site routes

What was fixed

Landing pages

• README.md — Get Started (cloud/getting-started/...), Monitoring (cloud/monitoring/), Quick Start, API (cloud/api/sql-query/), Paid plans (cloud/pricing/plans.md), Help (help/)
• cloud/README.md — feature/use-case cards via ../features/... and ../use-cases/..., API/Help, emoji icons

/broken/pages/ cleanup

• 0 remaining
• Retargeted to current pages where they exist; unlinked removed historical Changelog hrefs (prose kept)

Cross-space links (preview-safe)

• Help → ../cloud/portal/..., ../cloud/pricing/..., ../cloud/api/..., ../features/...
• API / Changelog / SDKs / FAQ similarly use real file paths
• No https://docs.spice.ai/... link targets (OSS docs remain on docs.spiceai.org where intentional)

Test plan

• GitBook preview: Home Monitoring card opens Monitoring page on the preview host (not GitHub)
• Production Home: Get Started, Monitoring, API reference, Paid plans, Help Center work
• /docs landing: all 6 cards + Use Cases navigate correctly
• Help troubleshooting portal/API links stay on docs (not GitHub)
• rg '/broken/pages/' → no matches
• rg 'https://docs\.spice\.ai/' → no matches in link targets
• Changelog historical entries still readable after unlink

[ewgenius]

Follow-up: Replaced all https://docs.spice.ai/... links introduced (and any remaining in touched docs) with root-relative paths (/docs/..., /api/..., /help/..., etc.) so GitBook preview endpoints keep working. No absolute production docs host in link targets.

[ewgenius]

Fix: Root-relative site paths like /docs/monitoring/monitoring were wrong for GitBook — it resolves /… as a repo file path, which produced GitHub fallbacks (…/docs/monitoring/monitoring/README.md).

All of those are now repo-relative markdown paths (e.g. Home Monitoring card → cloud/monitoring/), which keep GitBook previews working and should publish to the correct space page.