[Detail Bug] Handbook: hardware detail page “Back to catalog” link routes to non-existent page (404)

Detail Bug Report

https://app.detail.dev/org_62aa40f5-2c23-4914-a665-3bb2068af20e/bugs/bug_75b6d56a-de50-45de-85c2-f1a9476144ba

Introduced in 09f874a80ac72ed9969a9c87f4df9ae748cd7e7c by @kewde on May 24, 2026

Summary

• Context: website/src/app/handbook/catalog/hardware/[id]/page.tsx is the KNX hardware detail page. A user reaches it from the KNX catalog browser (the <CatalogContent /> list) by clicking a hardware row, which navigates to /handbook/catalog/hardware/<id>. The detail page provides a "← Back to catalog" link at the top to return to that catalog browser.
• Bug: That back-link points at a URL that does not exist in the handbook: href="/handbook/catalog/browse-hardware". There is no browse-hardware page anywhere in the handbook — the catalog browser is rendered from content/handbook/catalog/hardware.mdx (front-matter title: Browse Hardware, body <CatalogContent />), so its canonical handbook URL is /handbook/catalog/hardware. Clicking "Back to catalog" therefore hits the handbook catch-all ([[...slug]]/page.tsx), where source.getPage(["catalog","browse-hardware"]) returns null and the page calls notFound() → 404.
• Actual vs. expected: Clicking "← Back to catalog" shows the Next.js 404 page instead of returning to the catalog browser. Expected: navigate to /handbook/catalog/hardware.
• Impact: The in-app "← Back to catalog" link 404s on every detail page on which it is rendered — i.e. every successfully rendered hardware detail page (the link is only mounted after the page's two upstream server fetches, ${API}/hardware/${id} and ${API}/manufacturers/${hardware.manufacturer_id}, both succeed; if the API is unreachable the detail page errors before the link is mounted, see Reproduction prerequisite). In any environment where the catalog HTTP API is reachable and those fetches succeed, the link 404s when clicked.

Code with Bug

website/src/app/handbook/catalog/hardware/[id]/page.tsx

      <Link
        href="/handbook/catalog/browse-hardware"   // <-- BUG 🔴 no such handbook route; resolves to notFound() / 404
        className="text-sm text-fd-muted-foreground hover:text-fd-foreground transition-colors"
      >
        ← Back to catalog
      </Link>

Explanation

• The handbook catalog browser page is website/content/handbook/catalog/hardware.mdx (titled “Browse Hardware”) and is routed by file path to /handbook/catalog/hardware.
• There is no browse-hardware.mdx (and meta.json only lists "hardware"), so /handbook/catalog/browse-hardware cannot resolve.
• Requests to /handbook/catalog/browse-hardware fall through to website/src/app/handbook/[[...slug]]/page.tsx, where source.getPage(params.slug) returns null and notFound() is called, rendering a 404.

Codebase Inconsistency

The inbound navigation into the detail page uses the correct prefix/slug:

router.push(`/handbook/catalog/hardware/${encodeURIComponent(row.original.id)}`)

…but the detail page’s back-link uses /handbook/catalog/browse-hardware, so the round-trip list → detail → list is internally inconsistent.

Recommended Fix

      <Link
        href="/handbook/catalog/hardware"
        className="text-sm text-fd-muted-foreground hover:text-fd-foreground transition-colors"
      >
        ← Back to catalog
      </Link>

History

This bug was introduced in commit 09f874a8. The commit ("feat: split handbook & documentation") relocated the catalog out of /docs into a new /handbook subtree, renaming content/docs/catalog/browse-hardware.mdx to content/handbook/catalog/hardware.mdx (so the page id became hardware, and the new meta.json listed only "hardware"); it copied the detail page to website/src/app/handbook/catalog/hardware/[id]/page.tsx and updated the back-link's path prefix /docs/ → /handbook/, but missed the concurrent filename/slug rename of the destination, leaving the trailing browse-hardware segment dangling — so the link 404s on every successfully rendered detail page and has done so since the split.

Start in website/src/app/handbook/catalog/hardware/[id]/page.tsx and compare its back-link with the catalog page at website/content/handbook/catalog/hardware.mdx and the inbound route in CatalogContent. Verify the canonical catalog URL and confirm that selecting “Back to catalog” returns from a hardware detail page without a 404.