Docs sidebar drift: 19 synced pages orphaned from navigation (incl. entire MCP section)

[initializ-mk]

Summary

The docs sidebar on useforge.ai (src/data/navigation.ts) has drifted from the docs actually synced from initializ/forge. 19 of 55 synced doc pages are orphaned — they build as live routes at /docs/<section>/<slug> and are indexed by Pagefind search, but they do not appear in the left sidebar, so a user browsing the docs cannot discover them. An entire section (mcp/, 6 pages) has no sidebar group at all.

The root cause is architectural: scripts/sync-docs.ts pulls every docs/**/*.md from the forge repo into src/content/docs/, and src/pages/docs/[...slug].astro generates a route for each via getStaticPaths() — but the sidebar tree in src/data/navigation.ts is hand-maintained and has no automated link to what was synced. New upstream docs silently become hidden pages until someone manually edits navigation.ts.

A secondary staleness: the EXPECTED_PAGES completeness allowlist inside scripts/sync-docs.ts (used to warn on missing pages) is also out of date and contains none of the 19 new pages, so the existing guardrail does not catch this drift.

Evidence

Computed from the current tree:

• Synced doc files (src/content/docs/**/*.md): 55
• Slugs referenced in src/data/navigation.ts: 36
• Orphaned (synced, live route, but absent from sidebar): 19
• Broken sidebar links (in sidebar, no file): 0 ✅

The 19 orphaned pages

Core Concepts (3) — sidebar section exists, these items missing:

• core-concepts/binary-dependencies
• core-concepts/context-compression
• core-concepts/observability-tracing

Getting Started (1):

• getting-started/ship-to-production

Security (6) — sidebar section exists, these items missing:

• security/admission
• security/audit-tamper-evidence
• security/authentication
• security/platform-policy
• security/tenancy
• security/workflow-correlation

Reference (2) — sidebar section exists, these items missing:

• reference/browser-tools
• reference/library-modules

Deployment (1):

• deployment/scheduler-kubernetes

MCP (6) — ⚠️ no mcp/ sidebar group exists at all:

• mcp/index
• mcp/configuration
• mcp/cli-reference
• mcp/audit-events
• mcp/delegated-consent
• mcp/troubleshooting

Impact

• Real, published documentation (MCP configuration, authentication, tenancy, platform policy, tamper-evidence, context compression, the "ship to production" getting-started guide, etc.) is undiscoverable via normal navigation.
• Users can only reach these pages via Pagefind search or a direct/inbound link.
• The gap grows every time forge adds docs, because there is no automated feedback loop.

Proposed fix

Part A — immediate (restore discoverability): Update src/data/navigation.ts:

1. Add a new MCP top-level section with its 6 pages (index, configuration, cli-reference, audit-events, delegated-consent, troubleshooting). Decide placement (suggest after Security or after Reference).
2. Add the 13 missing items into their existing sections (Core Concepts, Getting Started, Security, Reference, Deployment) in a sensible order (respect each doc's frontmatter order where present).
3. Confirm section landing hrefs still resolve.

Part B — prevent recurrence (choose one):

• Option 1 (recommended): derive the sidebar from the synced manifest. scripts/sync-docs.ts already writes src/data/docs-manifest.json (with section, slug, title, order per entry). Generate the sidebar tree from the manifest at build time (or emit a navigation.generated.ts), keeping only section ordering/labels and any curation overrides hand-maintained. This makes "synced ⇒ navigable" automatic.
• Option 2 (lighter): a drift check in CI. Add a script/test that diffs synced slugs against navigation.ts slugs and fails the build (or the sync-docs workflow) when a synced page is not in the sidebar. Also refresh the stale EXPECTED_PAGES list in sync-docs.ts (or generate it from the manifest so it can't drift).

Acceptance criteria

• All 19 orphaned pages are reachable from the docs sidebar (or intentionally excluded via an explicit, reviewed denylist — not by accident).
• A new MCP sidebar section exists with all 6 MCP pages.
• npm run build succeeds; astro check passes.
• Prev/next navigation (flattenNav() in navigation.ts) includes the newly added pages in the correct order.
• A guardrail exists (generated sidebar or CI drift check) so that a future synced page cannot silently become orphaned.
• EXPECTED_PAGES in scripts/sync-docs.ts is refreshed or made self-updating from the manifest.

Notes / references

• Sidebar source: src/data/navigation.ts (docsSidebar, flattenNav())
• Route generation: src/pages/docs/[...slug].astro (getStaticPaths() over the whole docs collection)
• Sync + manifest: scripts/sync-docs.ts → src/content/docs/, src/data/docs-manifest.json
• Layout that consumes the sidebar: src/layouts/Docs.astro via DocsSidebar.astro
• No code changes have been made; this is a backlog item.

[Vetassikc]

Hi Initializ team — I can help with #26 as a bounded documentation-evidence and drift-normalization PR.

At main commit eb4b7a7984785a76450287b7bcc93d2e9f3a00db, I confirmed the navigation source, synced-doc manifest, sync script, sidebar, and docs layout are present. The Vartovii Repository Evidence workflow can pin the commit, produce the manifest-to-navigation ledger, record every included or intentionally excluded page, update the agreed navigation surface, and add the smallest accepted recurrence check. The deliverable would be one reviewable PR and one revision.

For the first three accepted pilots, the price is 250 USDC after PR acceptance. Would paid external contribution be appropriate for this issue, and can you confirm whether Part B should be the generated-navigation path or the lighter CI drift check, together with the acceptance and payment owner? I will not start before scope confirmation.