Skip to content

DocsNav sidebar is missing 6 published, cross-linked docs pages #8385

Description

@JSONbored

Context

apps/loopover-ui/src/components/site/docs-nav.tsx exports the docsNav array that drives the
persistent left-rail sidebar shown on every /docs/* page (rendered by <DocsNav />, and also used
by <DocsPrevNext /> for the prev/next footer links at the bottom of each doc). It currently lists
50 doc pages across 5 top-level groups.

Separately, apps/loopover-ui/src/routes/docs.index.tsx (the /docs landing page) maintains its own,
independently-curated list of doc cards, and it links to 6 published doc pages that docsNav does
not include:

  • /docs/miner-quickstart ("Quickstart by lane")
  • /docs/self-hosting-unified-ams-orb ("Unified ORB + AMS")
  • /docs/self-hosting-docs-audit ("Self-host docs audit")
  • /docs/loopover-commands ("@Loopover commands")
  • /docs/ai-summaries ("AI summaries policy" / "AI summary boundaries")
  • /docs/owner-checklist ("Onboarding checklist")

All 6 have real, published .mdx content at apps/loopover-ui/content/docs/<slug>.mdx and are
genuinely cross-linked from other doc pages (e.g. miner-coding-agent.mdx links to
miner-quickstart, maintainer-self-hosting.mdx links to self-hosting-docs-audit,
ams-deployment.mdx and federated-fleet-intelligence.mdx link to self-hosting-unified-ams-orb) —
this is not stale/orphaned content, it's just missing from the persistent sidebar.

Net effect: a visitor who reaches one of these 6 pages (via the /docs index, a cross-link, or a
direct URL) sees a left-rail sidebar with no entry highlighted and no way to navigate to any of the
other 44 docs pages' groups without first going back to /docs
— every other published doc page
gets full sidebar navigation; these 6 don't. DocsPrevNext's prev/next footer links are also silently
built from the same docsNav list (via groupItems()), so these 6 pages are skipped in the
site-wide "next doc" reading flow too, and no other page's prev/next ever lands on them.

This is not the frozen docs.*.tsx-route pattern (see this repo's contributor-pipeline-gardening
skill reference on the docs-architecture migration) — docsNav is a plain config array consumed by
the existing, already-shipped docs.$slug.tsx dynamic route. Adding array entries here is the same
kind of change as the ~50 entries already present; no new route file, no docs-pipeline work.

Requirements

  • Add all 6 missing pages to docsNav in apps/loopover-ui/src/components/site/docs-nav.tsx, each
    under the group (or new subgroup, following the existing Maintainers subgroup precedent) that
    best matches its actual topic — do not invent a new top-level group unless none of the 5 existing
    ones fit:
    • /docs/miner-quickstartGet started or Workflows (mirrors the existing /docs/quickstart
      and /docs/miner-workflow entries already in those groups).
    • /docs/loopover-commandsCore concepts or Workflows (it documents the @loopover command
      surface referenced throughout the miner/maintainer workflow docs).
    • /docs/ai-summariesOperating (alongside /docs/privacy-security, the existing entry closest
      in topic).
    • /docs/owner-checklist, /docs/self-hosting-docs-audit, /docs/self-hosting-unified-ams-orb
      under Maintainers, in whichever existing subgroup fits best (self-hosting-docs-audit and
      self-hosting-unified-ams-orb are self-hosting-adjacent; owner-checklist fits the
      GitHub App & managed beta subgroup alongside maintainer-workflow/maintainer-install-trust).
  • Use the label text already established for these pages in docs.index.tsx (or a clear equivalent)
    so the same page isn't described two different ways across the two navs.
  • Do not remove or reorder any of the existing 50 entries — this is additive only.
  • Do not touch docs.index.tsx's own list — the two navs are allowed to exist independently (the
    index page is a curated landing grid, docsNav is the exhaustive sidebar); the bug is specifically
    that docsNav is missing real, published pages, not that the two need to be merged into one source.

Deliverables

  • All 6 pages added to docsNav in apps/loopover-ui/src/components/site/docs-nav.tsx, each in
    an appropriate existing group/subgroup.
  • A regression test (new or added to an existing docs-nav test file) asserting every .mdx file
    under apps/loopover-ui/content/docs/ has a corresponding docsNav entry, so a future new doc
    page that forgets to add itself to the sidebar fails the test instead of silently shipping
    unreachable-from-sidebar (mirror the drift-guard pattern already used elsewhere in this repo,
    e.g. docs:drift-check/manifest:drift-check, adapted to a plain vitest assertion here since
    there's no dedicated CI script for this file).

Test Coverage Requirements

apps/** is outside this repo's Codecov coverage.include (vitest.config.ts / codecov.yml's
ignore: ["apps/**", ...]), so this change owes no Codecov patch-coverage percentage, but the new
drift-guard test is the actual deliverable that prevents this class of bug recurring — it must
genuinely fail on the current state (6 missing pages) before the fix and pass after. Add the test
under apps/loopover-ui/src/components/site/ (co-located with docs-nav.tsx, following this repo's
existing *.test.tsx co-location convention) and run it with
npx vitest run apps/loopover-ui/src/components/site/docs-nav.test.tsx, then npm run ui:test
before opening the PR. Reading the real filesystem (content/docs/*.mdx filenames) from a vitest test
is fine here — mirror how apps/loopover-ui/src/lib/docs-source-server-isolation.test.ts already
reads real repo files in a test.

Expected Outcome

Every published /docs/* page is reachable from the persistent sidebar and participates in the
prev/next footer navigation, matching the other 50 already-listed pages. A future doc page that's
added to content/docs/ but forgotten in docsNav fails a test instead of silently shipping
unreachable.

Links & Resources

  • apps/loopover-ui/src/components/site/docs-nav.tsx (the file to edit)
  • apps/loopover-ui/src/routes/docs.index.tsx (the sibling list with the correct labels/paths for
    these 6 pages)
  • apps/loopover-ui/content/docs/miner-quickstart.mdx, self-hosting-unified-ams-orb.mdx,
    self-hosting-docs-audit.mdx, loopover-commands.mdx, ai-summaries.mdx, owner-checklist.mdx
    (the 6 pages currently missing from the sidebar)
  • apps/loopover-ui/src/lib/docs-source-server-isolation.test.ts (precedent for a vitest test reading
    real repo files)

Metadata

Metadata

Assignees

No one assigned

    Labels

    gittensor:bugGittensor-scored bug fix — scores a 0.05x multiplier.help wantedExtra attention is needed

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions