[User Story] docs-13: Refine Core Docs UX With Data-Driven Navigation, Search, Theme, And Audience Paths

[djm81]

Why

The core docs site at docs.specfact.io was restructured by docs-05-core-site-ia-restructure, handoff pages were cleaned up by docs-07-core-handoff-conversion, and validation was added by docs-12-docs-validation-ci. But the overall reading experience is still utilitarian and harder to scan than it needs to be. The site lacks client-side search, expertise-guided navigation, theme toggling, and a clearer visual shell for the header/footer and page layout. Users still need to work too hard to answer basic questions like where to start, which pages are beginner-friendly, and how to jump to the right core CLI reference quickly.

The modules docs now have a richer navigation/search/theme model. The core site should follow with a counterpart change tailored to core-platform content so the two sites feel coherent while preserving the core-vs-modules ownership boundary.

What Changes

• Move core docs sidebar navigation to a data-driven source so navigation structure is easier to evolve without hardcoded layout drift
• Add client-side search for core docs pages using Jekyll-generated search metadata and Lunr.js
• Add expertise and audience-oriented navigation support so users can filter for beginner/intermediate/advanced material and quickly find the right starting path
• Add a light/dark theme toggle with persisted preference and core-doc-friendly styling updates
• Refresh overall page shell with clearer header/footer treatment, cleaner sidebar/content hierarchy, and breadcrumb support where useful
• Update the core landing page so it offers clearer role-based and task-based entry points without reintroducing module-owned content
• Enrich core docs front matter where needed to support search/filter/navigation metadata

Acceptance Criteria

• Core docs navigation is rendered from structured data instead of hardcoded sidebar markup
• Core docs support client-side search, persisted theme toggle, and expertise-aware entry paths
• The landing page and shell are updated without regressing core-vs-modules ownership boundaries

Dependencies

• Depends on: [User Story] docs-05: Restructure Core Docs Site Information Architecture #438 (docs-05-core-site-ia-restructure)
• Depends on: [User Story] docs-07: Convert Core Handoff Pages To Proper Redirects #439 (docs-07-core-handoff-conversion)
• Depends on: [User Story] docs-12: Add CI Validation For Docs Command Examples And Cross-Site Links #440 (docs-12-docs-validation-ci)
• Related modules-repo counterpart: nold-ai/specfact-cli-modules docs-13-nav-search-theme-roles

---

OpenSpec Change Proposal: docs-13-core-nav-search-theme-roles