Milestone D.2.7 — Sidebar, breadcrumbs, on-this-page

Status: Planned
Goal: D.2
Phase: 1.5 — Docs Site
Wave: 2
Estimated effort: 4 hours
ADR required: None

Spec detail: MASTER_BRIEF.md Part D (D.2.7).

Why This Milestone Exists

Introduction-only bootstrap lacks production navigation chrome. Users cannot judge IA depth, scroll-spy, or mobile sidebar behavior until sidebar, breadcrumbs, and on-this-page rail exist.

D.3.1 drops 25+ routes into the sidebar — nav polish must precede bulk stub pages or every content PR becomes a layout fix PR.

Edit-on-GitHub and last-updated footer establish the open-source contribution loop.

Non-Goals

Full IA tree (D.3.1)
Custom 404 page (D.2.8)
Landing site header parity

Branch

feat/d2-7-nav-shell

PR Title

feat(docs): navigation shell (D.2.7)

Prerequisites

D.2.1 merged
D.2.2 merged

Deliverables

Collapsible sidebar; active item bg-panel-raised
Breadcrumbs above H1, mono › separator, max 3 levels
On-this-page rail (≥lg): H2+H3, active border-l border-accent
Edit-on-GitHub + last-updated footer on every page

See MASTER_BRIEF Part D (D.2.7) for full acceptance detail.

Files Affected

File Path	Action	Notes
`docs/app/src/components/layout/docs-sidebar.tsx`	Modify	Sidebar chrome
`docs/app/src/components/layout/breadcrumb.tsx`	Add/Modify	Breadcrumb trail
`docs/app/src/components/layout/toc.tsx`	Modify	On-this-page rail
`docs/app/src/lib/layout.config.tsx`	Modify	Wordmark nav config

Testing Requirements

verifyNav_SidebarCollapsesMobile: Sidebar hidden on <lg, opens via hamburger
verifyNav_ScrollSpy: Long seed page highlights active heading in TOC
verifyNav_EditLink: "Edit this page" points to correct GitHub blob URL

Acceptance Criteria

Sidebar collapses on <lg and opens via hamburger
Scroll-spy works on page with 10+ headings
"Edit this page" links to correct GitHub URL

Risks

Risk	Probability	Impact	Mitigation
Fumadocs layout API changes between versions	Medium	Medium	Pin fumadocs-ui version in D.2.1
TOC overflow on short viewports	Low	Medium	Sticky TOC with max-height scroll
Breadcrumb depth exceeds 3 on nested API pages	Low	Low	Truncate per D.3.4 manual API structure