The Pagefind index built in under three seconds. The first query that went in was a concept from the middle of a chapter, something that lived three pages into a prerequisite chain. Four results came back: the chapter entry itself, the course sidebar heading for that section, a TOC subentry two headings deep, and a reference in a “Read first ↳” chip from two courses back.
That kind of cross-surface retrieval looks like the search is doing clever work. It isn't. It's returning what's in the DOM. The five navigation phases before P6 put it there.
What the spec called for
docs/specs/learning-hub/navigation.md is now marked SHIPPED P0–P6. Seven phases in the spec: P0 the foundation, P6 site-wide search, and five navigability phases between them. Each intermediate phase produced a surface the next could build on, and that P6 would eventually index.
The question the spec was answering was not “how do we add search to the learning hub?” That question has a thirty-minute answer. The question was “how do we make the learning hub navigable enough that search is useful?” That question took a week.
The phases
P2 shipped the hub track sections and the S1 JSON-LD block, on feat/learning-nav-p2-tracks. First visible navigation change on the hub, and the first time the full UI gate had run there since v1. The interactive approval mockup came first, per the gate; the mockup was built against the real content structure, not a placeholder. P2 established the top-level shape: here are the tracks, here is their JSON-LD representation for structured data.
P3 followed on feat/learning-nav-p3-sidebar, adding the persistent course rail to every chapter page. The devlog entry calls it the biggest browsability lift in the spec. That assessment holds. Before P3, a chapter page had no durable reference to the course it was in, so a reader arriving via search or a direct link had no ambient context. After P3, every chapter page carries the full course rail, and that context is in the DOM on every page Pagefind crawls.
P4 added the in-chapter TOC, the “on this page” right rail, on feat/learning-nav-p4-toc. It closed the N2 navigability gap in the spec. The implementation used a live IntersectionObserver scroll-spy built as a client island. It's the only client-side component in the subsystem. The TOC is rendered into the DOM as section headings, which means Pagefind indexes them as distinct findable entries, not just a flat page body.
P5, on feat/learning-nav-p5-prereqs, added the “Read first ↳” prerequisite chips at the top of each chapter. The spec called these the N1 fix: the single highest-value navigability change in the entire plan. The reasoning was that a reader who finds a chapter without knowing what to have read first is likely to bounce or get stuck. The chips surface the prerequisite chain directly in the chapter head. They are text in the DOM. Pagefind indexes them.
What Pagefind actually does
Pagefind is a static-site search library. After the build step outputs HTML, Pagefind crawls it, extracts text from configured selectors, and writes a binary index. Queries run client-side against that index, with no server dependency. The integration is an npx pagefind command wired into the build pipeline and a search component wired to the index endpoint.
The implementation time for P6 was an afternoon. That sentence is not modesty. It reflects what the library is: a crawler and a client-side query engine. The library ships the hard parts.
What the library cannot do is find content that isn't there. Pagefind indexes what the HTML contains. If P3 hasn't run and chapter pages carry no course context, a course-level query returns a chapter title and nothing else. The reader can't orient themselves. If P4 hasn't run and TOC headings aren't in the DOM, a query for a subsection topic returns the chapter page but not the section. If P5 hasn't run and prerequisite chips aren't in the HTML, a query for a foundational concept returns nothing from the prerequisite layer.
The cross-surface retrieval the first query produced covered four surfaces: chapter entry, sidebar heading, TOC subentry, prerequisite chip. All four were possible because four separate phases had put four separate surfaces into the DOM first.
The mockup gate on P6
P6 followed the same approval process as every preceding phase: mockup before implementation. scratchpad/learning-search-mockup.html was built first and reviewed before the implementation started.
The mockup for a search component is not decorative. It forces a concrete decision: what does a useful result snippet look like for this specific hub? A course sidebar heading result should surface the course name and the track. A TOC subentry result should surface the parent chapter. A prerequisite chip result should tell the reader which course's prerequisite chain they've landed in. Those are different snippet shapes.
Working that out in a static HTML mockup took two hours. Working it out during implementation would have taken the same two hours plus a round-trip through the review process. The gate is not overhead. It is the decision process, run at the cheapest possible point.
Why the sequence held
The nav plan was sequenced because each phase consumed what the previous phase produced. P3's course rail depended on P2's course structure. P4's TOC is scoped to a chapter, and P3's sidebar provides the chapter-in-course context that makes the TOC's position meaningful. P5's prerequisite chips reference other chapters; those chapters needed to be navigable items in a course structure before the chips were worth surfacing.
P6 could have been added at P2 without the build pipeline breaking. The search box would have appeared. The results would have been flat: a chapter title, some body text, no course context, no section headings, no prerequisite references. Usable, but not useful. The decision to make P6 the final phase was a decision to make it useful.
Closed
The spec at docs/specs/learning-hub/navigation.md is closed. Track sections, course rails, in-chapter TOCs, prerequisite chips, site-wide search: every navigability surface the plan called for.
Out of scope: cron-driven index rebuilds, personalised ranking by reading history, cross-property search beyond the learning hub. None are spec items. The plan ran P0 through P6. That's the plan.
