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-quickstart → Get started or Workflows (mirrors the existing /docs/quickstart
and /docs/miner-workflow entries already in those groups).
/docs/loopover-commands → Core concepts or Workflows (it documents the @loopover command
surface referenced throughout the miner/maintainer workflow docs).
/docs/ai-summaries → Operating (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
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)
Context
apps/loopover-ui/src/components/site/docs-nav.tsxexports thedocsNavarray that drives thepersistent left-rail sidebar shown on every
/docs/*page (rendered by<DocsNav />, and also usedby
<DocsPrevNext />for the prev/next footer links at the bottom of each doc). It currently lists50 doc pages across 5 top-level groups.
Separately,
apps/loopover-ui/src/routes/docs.index.tsx(the/docslanding page) maintains its own,independently-curated list of doc cards, and it links to 6 published doc pages that
docsNavdoesnot 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
.mdxcontent atapps/loopover-ui/content/docs/<slug>.mdxand aregenuinely cross-linked from other doc pages (e.g.
miner-coding-agent.mdxlinks tominer-quickstart,maintainer-self-hosting.mdxlinks toself-hosting-docs-audit,ams-deployment.mdxandfederated-fleet-intelligence.mdxlink toself-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
/docsindex, a cross-link, or adirect 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 pagegets full sidebar navigation; these 6 don't.
DocsPrevNext's prev/next footer links are also silentlybuilt from the same
docsNavlist (viagroupItems()), so these 6 pages are skipped in thesite-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'scontributor-pipeline-gardeningskill reference on the docs-architecture migration) —
docsNavis a plain config array consumed bythe existing, already-shipped
docs.$slug.tsxdynamic route. Adding array entries here is the samekind of change as the ~50 entries already present; no new route file, no docs-pipeline work.
Requirements
docsNavinapps/loopover-ui/src/components/site/docs-nav.tsx, eachunder the group (or new subgroup, following the existing
Maintainerssubgroup precedent) thatbest matches its actual topic — do not invent a new top-level group unless none of the 5 existing
ones fit:
/docs/miner-quickstart→Get startedorWorkflows(mirrors the existing/docs/quickstartand
/docs/miner-workflowentries already in those groups)./docs/loopover-commands→Core conceptsorWorkflows(it documents the@loopovercommandsurface referenced throughout the miner/maintainer workflow docs).
/docs/ai-summaries→Operating(alongside/docs/privacy-security, the existing entry closestin 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-auditandself-hosting-unified-ams-orbare self-hosting-adjacent;owner-checklistfits theGitHub App & managed betasubgroup alongsidemaintainer-workflow/maintainer-install-trust).docs.index.tsx(or a clear equivalent)so the same page isn't described two different ways across the two navs.
docs.index.tsx's own list — the two navs are allowed to exist independently (theindex page is a curated landing grid,
docsNavis the exhaustive sidebar); the bug is specificallythat
docsNavis missing real, published pages, not that the two need to be merged into one source.Deliverables
docsNavinapps/loopover-ui/src/components/site/docs-nav.tsx, each inan appropriate existing group/subgroup.
.mdxfileunder
apps/loopover-ui/content/docs/has a correspondingdocsNaventry, so a future new docpage 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 sincethere's no dedicated CI script for this file).
Test Coverage Requirements
apps/**is outside this repo's Codecovcoverage.include(vitest.config.ts/codecov.yml'signore: ["apps/**", ...]), so this change owes no Codecov patch-coverage percentage, but the newdrift-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 withdocs-nav.tsx, following this repo'sexisting
*.test.tsxco-location convention) and run it withnpx vitest run apps/loopover-ui/src/components/site/docs-nav.test.tsx, thennpm run ui:testbefore opening the PR. Reading the real filesystem (
content/docs/*.mdxfilenames) from a vitest testis fine here — mirror how
apps/loopover-ui/src/lib/docs-source-server-isolation.test.tsalreadyreads real repo files in a test.
Expected Outcome
Every published
/docs/*page is reachable from the persistent sidebar and participates in theprev/next footer navigation, matching the other 50 already-listed pages. A future doc page that's
added to
content/docs/but forgotten indocsNavfails a test instead of silently shippingunreachable.
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 forthese 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 readingreal repo files)