P5 was a component and a frontmatter key. P4 was a client island with a live IntersectionObserver. P6 indexed the entire site. By the time P6 closed, the ratio between implementation size and navigability delivered had inverted every architectural expectation going in.
conventions.md — the backlog document that carried the M/E/N/S items for the learning hub navigation programme — had described N1, the prerequisite chips, as “the single highest-value navigability fix.” I wrote that before any of the phases shipped. It was right. Understanding why took shipping all six.
The programme
The spec ran P0 through P6. P0 was groundwork: hub layout rebuild, breadcrumb, metadata foundation. P2 shipped hub track sections and S1 JSON-LD structured data — the first visible navigation change, and the first time the hub looked like it understood what it contained. P4 built the in-chapter TOC: an “on this page” right rail backed by a live IntersectionObserver scroll-spy, the one client island in the entire navigation subsystem. P5 was the prerequisite chips. P6 was site-wide Pagefind search, the capstone.
P2 and P4 shipped on 2026-07-02. P5 and P6 shipped on 2026-07-03. docs/specs/learning-hub/navigation.md is now marked SHIPPED P0–P6.
What the first phases built
Improving on the earlier navigation coverage — which documented the breadcrumb, the track sections, and the first visible change to the hub — the complete programme reveals where the value actually concentrated.
P2 addressed hub-level orientation. Track sections give a reader arriving at the learning index a structured map of the topic landscape: which track owns a chapter, what sits adjacent, where a subject lives relative to everything else. P2 was the first time the learning hub ran through the full UI gate since the hub v1 rebuild — interactive approval mockup before a line of production code. The S1 JSON-LD was the invisible layer of the same phase: structured data for search engines, same underlying information, different consumer.
P4 addressed page-level orientation. The “on this page” right rail is familiar enough, but the IntersectionObserver scroll-spy is the detail that separates functional from decorative. The mockup at scratchpad/learning-toc-mockup.html ran the live scroll-spy against actual content; the approval gate was meaningful because the approved behaviour was the real thing. The final implementation was a client island — React state, event wiring, real-time DOM observation, active-state management across the TOC items — because real-time scroll tracking requires one.
P6 addressed discovery. Pagefind indexes every page on the property. A reader who remembers a term from weeks ago can surface the relevant chapter in one query rather than traversing the track structure manually. The search mockup came first (scratchpad/learning-search-mockup.html), then the index integration and results surface. It was the final phase because it needed a complete corpus.
What P2, P4, and P6 answer
All three address the same class of question: where am I or where is the content I want?
Track sections: where is this chapter in the topic map? TOC with scroll-spy: where am I in this page right now? Search: where is the thing I half-remember? They are wayfinding tools. Each assumes you have already decided you are in roughly the right place, and helps you move more precisely once that decision is made.
The architecture reflects this. Track sections are a data-modelling and layout problem. The TOC is a component-and-observer problem. Search is an indexing problem. They address different layers of the navigation stack, but the user model is the same: a reader who has arrived, is oriented at some level, and wants to move more efficiently.
What the chips answer instead
The N1 chips answer a different question: am I ready for this?
A chip sits above the chapter title. It reads “Read first ↳” followed by a link to the prerequisite. The prop is in the chapter’s frontmatter. The component renders the badge, links to the dependency, and stops.
The chips operate on the entry condition, not the wayfinding condition. A chapter that presupposes knowledge of an earlier chapter is opaque to a reader who hasn’t read it. No amount of scroll-spy precision or search index coverage addresses that. You are in the wrong place; the other navigation features will help you move efficiently through a chapter you are not equipped to understand.
The chips tell you before you start. That is the gap they close, and it is a different gap from the one P2, P4, and P6 close.
The implementation ratio
P4’s scroll-spy is a client island: React state, event binding, IntersectionObserver lifecycle, active-state synchronisation across TOC items. P2 required designing the hub track structure, running it through the approval gate, and wiring the S1 structured data. P6 required configuring a site-wide indexer and building the full search results surface.
P5 — branch feat/learning-nav-p5-prereqs — required one component and one frontmatter key. No interactivity. No indexer. No observer. The implementation is proportional to what the feature does: read a value, render a chip with a link. The devlog described it as “unlike every other nav” item in the programme, and the distinction is architectural, not just descriptive.
Navigability is not proportional to implementation size. Preparation is the precondition for every other navigation feature to work as intended. A reader who arrives prepared needs nothing more than a good TOC to move efficiently through the content. A reader who arrives unprepared will struggle regardless of how well the right rail tracks their scroll position. The chips address the condition that makes the rest of the system function. The rest of the system does not address what the chips address.
What the ordering implies
P5 shipped fifth in the spec sequence. The sequence was architectural: track sections needed the hub layout, search needed the full corpus. The chips needed neither. They are frontmatter and a component with no dependency on the navigation infrastructure beneath them.
The correct build order, by leverage, would have been chips first. They could have shipped on day one and delivered immediately. The spec was sequenced around architecture, not around impact per line of code. That deferred the highest-value feature to fifth place.
conventions.md had the right annotation before the build started. The evidence to confirm it only existed after the build finished.
What shipped
The programme is complete. Six phases, two days, docs/specs/learning-hub/navigation.md marked SHIPPED P0–P6. The post-ship reconciliation updated every M/E/N/S item in conventions.md with a ✅ or ⬜ status. The living atlas captures the navigable overview of what shipped and what follows.
The chips are what I’d schedule for day one next time. Everything else in the programme assumes readers can arrive at a chapter prepared. The chips are how that assumption becomes valid.
