earnOS Navigator

Minimum Viable Wiki Spec (Cloudflare)

Owner: Group PMO Reviewed: 2026-02-24 Read: 2 min Repo: earnOS

Summary

Generate an internal executive wiki from markdown and frontmatter metadata with fast search, cross-repo deep links, and mobile-first navigation.

Decision Points

  • Source: markdown files in `earnOS` plus canonical links to entity repositories.
  • Build target: static site deployed on Cloudflare Pages.
  • Runtime: static HTML/CSS with progressive enhancement JS for search, recent docs, and reading progress.
  • Optional worker: Cloudflare Worker for index caching and link validation telemetry.
  • Build quality gate: markdown validation for required frontmatter and relative-link integrity.

Minimum Viable Wiki Spec (Cloudflare)

Goal

Generate an internal executive wiki from markdown and frontmatter metadata with fast search, cross-repo deep links, and mobile-first navigation.

Build and Deployment Model

  • Source: markdown files in earnOS plus canonical links to entity repositories.
  • Build target: static site deployed on Cloudflare Pages.
  • Runtime: static HTML/CSS with progressive enhancement JS for search, recent docs, and reading progress.
  • Optional worker: Cloudflare Worker for index caching and link validation telemetry.
  • Build quality gate: markdown validation for required frontmatter and relative-link integrity.

Search Model

  • Search is primary navigation.
  • Sticky search is always visible on mobile and desktop.
  • Desktop shortcut: Cmd/Ctrl + K.
  • Mobile search opens full-screen search sheet.
  • Build extracts {id, title, summary, domain, entity_badges, headings, body_excerpt, canonical_url, repo, last_reviewed}.
  • Build emits public/search-index.json.
  • Client search uses MiniSearch or Lunr loaded from search-index.json.
  • Ranking order:
    1. title exact match
    2. summary match
    3. heading match
    4. body excerpt match
    5. recency boost from last_reviewed
  • Mobile bottom navigation tabs:
    1. Home
    2. Domains
    3. Search
    4. Entities
    5. Recent
  • Domain switcher uses frontmatter domain.
  • Entity switcher uses entity_badges or related_entities.
  • Sidebar/left-rail ordering:
    1. explicit nav_weight (optional)
    2. alphabetical by title
  • Breadcrumb format: repo > domain > page.
  • Show Repo badge and entity badges on each page header.
  • Entity links always use canonical_url.
  • UI displays Source Repo when repo != earnOS.
  • Canonical path redirects are generated into site/dist/_redirects.

Recently Viewed

  • Client stores last 20 page IDs in localStorage key earnos_recent_pages.
  • Stored object: {id, title, canonical_url, repo, viewed_at}.
  • Deduplicate by id, move latest to top.
  • Show in mobile Recent tab and desktop left rail.

Executive Reading Experience

  • Each document should render:
    1. Summary card
    2. Decision points block
    3. Main sections
    4. Collapsible detail sections
  • Use native <details> for long sections.
  • Reading progress bar appears below sticky search for long pages.

Desktop Layout

  • Left rail: domain/entity/recent navigation.
  • Center column: primary content.
  • Right rail: summary, on-page outline, cross-repo links.

Accessibility Requirements

  • Minimum tap target: 48x48px.
  • WCAG AA contrast minimum.
  • Base text size 17px or higher.
  • Visible focus styles for keyboard navigation.

Non-Functional Requirements

  • Time to interactive under 2 seconds on corporate network.
  • Search response under 150ms after index load.
  • Runtime enhancement scripts under 35KB gzip total.
  • Build fails on missing required frontmatter fields.
  • Broken link checker runs during CI using canonical URL validation.
  • CI workflow runs validate + build on PR, and deploys to Pages on main when Cloudflare secrets are configured.