The feat/learning-nav-p5-prereqs branch added a conditional to the chapter head. Frontmatter declares a prerequisite; the component checks; if one exists, it renders “Read first ↳” and a link. No JavaScript. No hydration. No build step beyond the MDX pipeline already in place.
That landed on 3 July, same day as P6.
P6 was site-wide Pagefind search — the headline feature, the final phase of docs/specs/learning-hub/navigation.md, now marked SHIPPED P0–P6. Index at build time, query at runtime, across the whole property. Two branches, one day, dramatically different implementation surfaces. conventions.md had already named which would deliver more navigability.
The navigation plan
docs/specs/learning-hub/navigation.md ran seven phases, P0 through P6, all now closed. The phases most relevant to the thesis are the four with visible reader-facing output:
- P2: hub track sections and S1 JSON-LD — first visible navigation change, first run through the full UI gate
- P4: “on this page” right rail, IntersectionObserver scroll-spy — the subsystem’s one client island
- P5: “Read first ↳” prerequisite chips at the chapter head —
conventions.md’s N1 item, ranked single highest-value fix - P6: site-wide Pagefind search — the largest implementation in the plan, the final phase
The earlier phases covered other concerns. Out of scope here — the comparison is between the reader-facing navigation mechanisms.
Three mechanisms, three reader positions
Each phase addresses a different point in the reader’s journey.
P2 track sections orient the reader at the hub level. Before clicking into any chapter, the question is: what is here, and which part is for me? The S1 JSON-LD addresses the same question for machines.
P4’s scroll-spy TOC orients the reader within a chapter. You’re already reading. The right rail marks your position and lets you jump to a section. The reader who can skip content they already know spends less time reaching what they need. That value is real.
P6 search addresses retrieval across the site. You know a concept exists — or you know the word you’re looking for — and you want to find where the site covers it. Pagefind handles this cleanly. It’s closer to reference-lookup than learning-hub navigation.
P5 operates earlier than all three: at the chapter entry point, before you’ve read a word. The chip tells you whether you’re ready for this chapter. If you’re not, it redirects you. If you are, it confirms the path. The intervention lands at maximum leverage — before the confusion starts.
Why earlier is higher leverage
A reader who gets lost inside a chapter has two recoveries: go back to the hub and find a different entry point, or push through and accumulate confusion that compounds through every subsequent chapter.
A TOC doesn’t prevent either outcome. It helps if you’re in the right place; it doesn’t tell you whether you should be there.
Search doesn’t prevent either outcome. It helps if you can form a query. A reader who doesn’t know what they don’t know can’t form a query.
Prerequisite chips intercept before the failure mode starts. The chapter with a “Read first ↳ Frontmatter conventions” chip surfaces the dependency gap before the chapter creates confusion. The redirect costs nothing compared to recovering from twenty minutes of compounding confusion.
That’s conventions.md’s argument for ranking N1 above N2. The spec predicted a conditional render on a frontmatter field would outperform a client-island scroll-spy on navigability. The programme has now validated the prediction.
The implementation cost gap
P4 is the subsystem’s one client island. Client island means React hydration on the reader’s machine, JavaScript event listeners persisting across navigation, and a component that doesn’t exist until the runtime runs. Mockup-first, then the real IntersectionObserver with live scroll-spy. Higher code surface, higher maintenance surface.
P6 adds a build-time indexing step: Pagefind walks compiled HTML output and produces a search index. Clean integration, but a new build dependency and a new failure mode if build caching is too aggressive. The runtime query layer is additional complexity beyond the existing MDX pipeline.
P5 is: check if a frontmatter field exists; if yes, render a link with the “Read first ↳” marker; if no, render nothing. Server component. No hydration. No build step. The only ongoing cost is the content-modelling decision — whether this chapter declares a prerequisite — which is a content problem, not an engineering problem.
Navigability per line of code, in concrete terms: P5 is a conditional. P4 is a client island with scroll listeners. P6 is a build-time indexer and a runtime query layer. The reader value from P5, for the primary learning-hub audience, is higher. The implementation cost is lower by a significant margin.
What the closeout confirms
The post-P6 closeout reconciled every tracking surface with what had shipped. conventions.md’s M/E/N/S backlog now carries per-item ✅/⬜ statuses against M1, E2, N1, N2, and the rest. The programme has a living atlas as its navigable document going forward.
The administrative pass produces one clean signal. N1 (prerequisites) was ranked above N2 (TOC) in the original spec. N1 landed in P5, N2 in P4. P5 is lighter to implement. P5 addresses an earlier reader position. Both measures confirm the ranking conventions.md made before either phase existed.
Search wasn’t in the N-series at all. P6 is valuable, but it serves a reader who knows enough to form a query — further down the learning curve than the hub’s primary audience. For the reader who doesn’t yet know what they don’t know, a search bar is inert.
What carries forward
The programme is closed. P0–P6 shipped.
At the current chapter count, the prerequisite model is manageable in frontmatter: a chapter declares one prerequisite, the chip renders it. No graph logic required.
At higher chapter counts, dependency chains emerge. C depends on B depends on A. Single-chip frontmatter doesn’t model that cleanly. That’s a content architecture question, not a current problem. Out of scope until the hub has enough chapters to make the dependency graph non-trivial.
The lesson that carries forward: for a learning hub, orientation at the entry point outperforms retrieval mechanics. conventions.md said so before any code shipped. The phases confirmed it. The highest-leverage navigation fix was a conditional on a frontmatter field.
