fix(docs): CLI guide relative links resolve correctly

[bpamiri]

Summary

Resolves #2424. Resolves #2426.

The "Related Commands" / "What's next" CardGrids and inline markdown links across multiple v4-0-0-snapshot/command-line-tools/ pages all resolved to 404. Affected pages:

• command-line-tools/installation.mdx
• command-line-tools/quick-start.mdx
• command-line-tools/configuration.mdx
• command-line-tools/mcp-integration.mdx
• command-line-tools/wheels-commands/app-inspection.mdx
• command-line-tools/wheels-commands/code-generation.mdx
• command-line-tools/wheels-commands/creating-a-project.mdx

Root cause

Links used href="./<sibling>/" and [Text](./<sibling>/). Per RFC 3986, relative refs resolve against the base URL by stripping everything after the last /. For a page served at /v4-0-0-snapshot/command-line-tools/installation/, the base path is /v4-0-0-snapshot/command-line-tools/installation/ — and ./quick-start/ resolves to /v4-0-0-snapshot/command-line-tools/installation/quick-start/, which 404s.

command-line-tools/index.mdx was the one page where ./ worked, because Astro serves it at /command-line-tools/ (URL ends in the section dir itself), so ./quick-start/ lands at /command-line-tools/quick-start/.

Fix

Switched every non-index page in command-line-tools/ and its wheels-commands/ / core-commands/ sub-folders to ../<sibling>/ for both LinkCard href props and inline markdown links. Same transform applied uniformly via sed:

sed -i -E 's|href="\./|href="../|g'
sed -i -E 's|\]\(\./|](../|g'

command-line-tools/index.mdx was deliberately excluded — its ./ links work and don't need to change.

Test plan

• Visit https://guides.wheels.dev/v4-0-0-snapshot/command-line-tools/installation/ and click each "Related Commands" card — all three resolve.
• Same on /quick-start/, /configuration/, /mcp-integration/ — all "What's next" / "Related Commands" cards resolve.
• Visit /wheels-commands/app-inspection/, click "Related Commands" — resolves.
• Inline markdown links (e.g. "see Configuration") — resolve.

---

Generated by Claude Code

[claude]

🔴 The Quick Start LinkCard href="../quick-start/" here resolves to /v4-0-0-snapshot/command-line-tools/wheels-commands/quick-start/, which 404s — quick-start.mdx lives one directory higher, not in wheels-commands/. The PR sed only rewrote ./ → ../, so cards that were already ../ (here and in creating-a-project.mdx:171) were not touched and remain broken. Fix by changing both to ../../quick-start/, matching the pattern already used correctly in wheels-commands/dev-server.mdx:134 and wheels-commands/app-inspection.mdx:267.

Extended reasoning...

What the bug is

In wheels-commands/code-generation.mdx (the <CardGrid> block this PR edits), the Quick Start LinkCard at line 422-425 keeps its pre-PR href="../quick-start/":

  <LinkCard
    title="Quick Start"
    href="../quick-start/"
    description="End-to-end walkthrough from wheels new to a running CRUD resource."
  />

The same defect exists in wheels-commands/creating-a-project.mdx at line 171 — also a Quick Start LinkCard inside a CardGrid this PR edits, also still href="../quick-start/".

Why this 404s — a step-by-step proof

1. The page lives at web/sites/guides/src/content/docs/v4-0-0-snapshot/command-line-tools/wheels-commands/code-generation.mdx.
2. Astro/Starlight serves it at /v4-0-0-snapshot/command-line-tools/wheels-commands/code-generation/.
3. Per RFC 3986 §5.3, the base for relative-ref resolution is everything up to and including the last / of the page path: /v4-0-0-snapshot/command-line-tools/wheels-commands/code-generation/.
4. Resolving ../quick-start/ against that base strips one segment (code-generation/) and appends quick-start/, giving /v4-0-0-snapshot/command-line-tools/wheels-commands/quick-start/.
5. ls web/sites/guides/src/content/docs/v4-0-0-snapshot/command-line-tools/wheels-commands/ — verified — contains no quick-start.mdx. The actual file is at command-line-tools/quick-start.mdx, served at /v4-0-0-snapshot/command-line-tools/quick-start/.
6. Result: 404. The same calculation applies verbatim to creating-a-project.mdx.

Why the PR did not catch it

The PR applied a uniform sed -i -E s|href="\./|href="../|g (per the description). That transform only converts links that started with ./. The two Quick Start cards were already at ../quick-start/ before the PR (the diff itself confirms this — only "Creating a Project", "Database", and "Scaffold Cleanup" cards changed in code-generation.mdx). They were broken before and they are still broken after, even though both files appear in the PRs explicit list of files where Related Commands cards were 404ing.

What "right" looks like

The correct relative ref from a wheels-commands/<page>/ URL up to command-line-tools/quick-start/ requires popping two segments: ../../quick-start/. That is exactly the pattern wheels-commands/dev-server.mdx:134 already uses correctly (verified: grep returns 134: href="../../quick-start/"), and wheels-commands/app-inspection.mdx:267 uses the same ../../configuration/ pattern for its parent-dir cross-link.

Fix

Two single-character edits:

• wheels-commands/code-generation.mdx:424 — href="../quick-start/" → href="../../quick-start/"
• wheels-commands/creating-a-project.mdx:171 — href="../quick-start/" → href="../../quick-start/"

Impact

The PR title is "fix(docs): CLI guide relative links resolve correctly" and the test plan checks that all Related Commands cards resolve. After this PR merges as-is, two cards on two pages explicitly named in the PR description still 404. Catching exactly this is the point of the change.