fix(docs): add the 6 missing published docs pages to the DocsNav sidebar

[kai392]

Fixes #8385

Root cause

docsNav in apps/loopover-ui/src/components/site/docs-nav.tsx is maintained by hand alongside docs.index.tsx's separately-curated landing grid. Six published pages had real content/docs/*.mdx content and index-page links but no docsNav entry:

miner-quickstart, loopover-commands, ai-summaries, owner-checklist, self-hosting-docs-audit, self-hosting-unified-ams-orb

Because DocsPrevNext builds its footer links from the same array via groupItems(), those pages were both unreachable from the persistent left rail and skipped in the site-wide prev/next reading flow — no other page's "next" ever landed on them.

Fix approach

Additive only — no existing entry removed or reordered. Each page went to the group the issue specified, reusing docs.index.tsx's established label so the same page isn't described two ways:

Page	Group	Label
miner-quickstart	Get started	Quickstart by lane
loopover-commands	Core concepts	@Loopover commands
ai-summaries	Operating	AI summaries policy
self-hosting-unified-ams-orb	Maintainers › Self-hosting: integrations	Unified ORB + AMS
self-hosting-docs-audit	Maintainers › Self-hosting: release & security	Self-host docs audit
owner-checklist	Maintainers › GitHub App & managed beta	Onboarding checklist

self-hosting-docs-audit went to release & security rather than setup because its own frontmatter describes it as a pre-release accuracy checklist, placing it next to the existing "Release checklist" entry.

docs.index.tsx is deliberately untouched, per the issue — the two navs are allowed to differ.

The drift guard

New docs-nav.test.tsx, co-located per this repo's convention and reading real files the way docs-source-server-isolation.test.ts already does. content/docs/ is treated as the source of truth for what's published:

• every .mdx has a sidebar entry (the actual regression)
• no entry points at a page that isn't published (reverse drift)
• no page listed twice, so prev/next can't revisit one
• a guard asserting the directory read is non-empty, so the first three can't pass vacuously if the path ever breaks

It genuinely fails on the pre-fix state. Stashing only the docs-nav.tsx change and re-running reports exactly the 6 missing slugs; restoring it passes 4/4.

Impact / risks

• Sidebar-only; no route, no content, no docs-pipeline change. This is the same kind of edit as the ~50 entries already present, on the already-shipped docs.$slug.tsx dynamic route — not the frozen docs.*.tsx pattern.
• Main risk is a mis-grouped page, which is cosmetic and easily moved.
• The guard now fails CI if a future doc page is added without a sidebar entry. That is the intent, and the fix is a one-line addition.

Validation

• npm --workspace @loopover/ui run test -- src/components/site/docs-nav.test.tsx — 4/4, re-run after rebasing onto current main (9b9924b3), since the guard asserts against the live content/docs/ directory
• npm --workspace @loopover/ui run typecheck — clean
• prettier --check clean on both changed files
• apps/** is outside Codecov's coverage.include, so this carries no patch-coverage percentage; the drift guard is the deliverable that prevents recurrence

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[loopover-orb]

Tip

✅ LoopOver review result - approve/merge recommended

_{Review updated: 2026-07-24 15:03:49 UTC}

2 files · 1 AI reviewer · no blockers · readiness 93/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This is a well-scoped, additive-only fix: it adds exactly the 6 missing docsNav entries the issue (#8385) specifies, each placed in the group/label documented in the PR description, with no existing entries removed or reordered. The new docs-nav.test.tsx reads content/docs/*.mdx as the source of truth and asserts full coverage, no dangling links, and no duplicates, which directly guards against regression of this exact bug. All entries in the diff cross-check cleanly against docs.index.tsx's own links (miner-quickstart, loopover-commands, ai-summaries, self-hosting-unified-ams-orb, self-hosting-docs-audit, owner-checklist all appear there too), so the fix is internally consistent.

Nits — 5 non-blocking

• docs-nav.test.tsx:17 uses a magic threshold (`toBeGreaterThan(40)`) to guard against a vacuous assertion — a comment noting it's intentionally loose (not meant to track the exact count) would save a future maintainer from wondering if it needs bumping.
• The test's reliance on `process.cwd()` resolving to `apps/loopover-ui` (per the comment) is asserted but not independently verified by the test itself; a `readdirSync` failure there would throw before any assertion runs, which is fine but worth being aware of if the workspace root changes.
• docs.index.tsx is intentionally left untouched per the issue, so the two navs (docsNav vs the landing grid) remain a hand-maintained pair with no shared drift guard between them — only docsNav-vs-filesystem is guarded now, not docsNav-vs-index-page consistency, which is an acceptable but worth-noting scope limit.
• Consider a follow-up drift guard between docs.index.tsx's link list and docsNav, since the two are documented as intentionally divergent but could silently diverge further without anyone noticing (a case where docs.index.tsx points to a page that docsNav also has, but with a different label, as already exists for several entries here).
• The self-hosting-docs-audit placement rationale (release & security, not setup) is explained well in the description — consider carrying that one-line justification into a code comment near the entry in docs-nav.tsx for future maintainers who don't read the PR description.

Decision drivers

• ✅ Code review — No blockers (1 reviewer)
• ✅ Gate result — Passing (No configured blocker found.)

Context & advisory signals — never blocks the verdict

Signal	Result	Evidence
Linked issue	✅ Linked	#8385
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 135 registered-repo PR(s), 68 merged, 10 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	kai392; Gittensor profile; 135 PR(s), 10 issue(s).
Improvement	✅ Minor	risk: clean · value: minor · LLM: significant

Linked issue satisfaction

Addressed
The diff adds all 6 specified pages to docsNav under the exact groups/subgroups the issue requested, using labels matching docs.index.tsx, without removing or reordering existing entries, and adds a co-located drift-guard test comparing content/docs/*.mdx files against docsNav entries as required.

Review context

• Author: kai392
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 135 PR(s), 10 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Start here: Triage stale or unlinked PRs.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

🧪 Chat with LoopOver

Ask LoopOver a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @loopover ask <question> answers contribution-quality Q&A with source citations and freshness.
• @loopover chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @loopover mention with a real question is routed to the closest matching read-only command automatically — no exact syntax required.

Full command reference: https://loopover.ai/docs/loopover-commands

🧪 Experimental — new and may change.

Visual preview

Route	Viewport	Before (production)	After (this PR's preview)	Diff
/	desktop	before /	after /	—
/	mobile	before / (mobile)	after / (mobile)	—

Click any thumbnail to open the full-size screenshot. Before = production · After = this PR's preview deploy.

Scroll preview

Route	Before (production)	After (this PR's preview)
/	before / (scroll)	after / (scroll)

A short scroll-through clip (desktop) — click either thumbnail to open the full animation. Evidence for scroll-linked behavior a single screenshot can't show.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by LoopOver, a quiet PR intelligence layer for OSS maintainers.

• Re-run LoopOver review

[loopover-orb]

This pull request changes UI/visual code but its screenshot evidence is incomplete. Every required viewport × theme combination needs its own before/after image pair in a labeled table row (e.g. "Desktop · Light | before | after"). Still missing: Desktop · Dark, Tablet · Dark, Mobile · Dark.

Please resubmit with the remaining rows filled in.

See https://github.com/JSONbored/loopover/blob/main/.claude/skills/contributing-to-loopover/SKILL.md for the exact format and examples. This is an automated maintenance action.